From 7817c3514e180e3b56fe1718ca43dc9e9b3075e5 Mon Sep 17 00:00:00 2001
From: ryan <ryan@distrust.co>
Date: Sat, 10 Feb 2024 23:58:25 -0500
Subject: [PATCH] keyfork-derive-util: add README / lib.rs docs

---
 crates/derive/keyfork-derive-util/README.md   | 52 +++++++++++++++++++
 crates/derive/keyfork-derive-util/src/lib.rs  |  2 +-
 .../derive/keyfork-derive-util/src/request.rs |  6 +--
 3 files changed, 56 insertions(+), 4 deletions(-)
 create mode 100644 crates/derive/keyfork-derive-util/README.md

diff --git a/crates/derive/keyfork-derive-util/README.md b/crates/derive/keyfork-derive-util/README.md
new file mode 100644
index 0000000..04cc48a
--- /dev/null
+++ b/crates/derive/keyfork-derive-util/README.md
@@ -0,0 +1,52 @@
+# Keyfork Derive: BIP-0032 Key Derivation
+
+Keyfork offers a [BIP-0032] based hierarchial key derivation system enabling
+the ability to create keys based on a [BIP-0032] seed, a value between 128 to
+512 bits. The keys can be made using any algorithm supported by Keyfork Derive.
+Newtypes can be added to wrap around foreign key types that aren't supported by
+Keyfork.
+
+Keys derived with the same parameters, from the same seed, will _always_ return
+the same value. This makes Keyfork a reliable backend for generating encryption
+or signature keys, as every key can be recovered using the previously used
+derivation algorithm. However, this may be seen as a concern, as all an
+attacker may need to recreate all previously-used seeds would be the original
+derivation seed. For this reason, it is recommended to use the Keyfork server
+for derivation from the root seed. The Keyfork server will ensure the root seed
+and any highest-level keys (such as BIP-44, BIP-85, etc.) keys are not leaked.
+
+The primary use case of Keyfork Derive will be the creation of Derivation
+Requests, to be used by Keyforkd Client. In the included example, derivation is
+performed directly on a master seed. This is how Keyforkd works internally.
+
+## Example
+
+```rust
+use std::str::FromStr;
+use keyfork_mnemonic_util::Mnemonic;
+use keyfork_derive_util::{*, request::*};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+
+    let mnemonic = Mnemonic::from_str(
+        "enter settle kiwi high shift absorb protect sword talent museum lazy okay"
+    )?;
+    let path = DerivationPath::from_str("m/44'/0'/0'/0/0")?;
+
+    let request = DerivationRequest::new(
+        DerivationAlgorithm::Secp256k1,
+        &path
+    );
+
+    let key1 = request.derive_with_mnemonic(&mnemonic)?;
+
+    let seed = mnemonic.seed(None)?;
+    let key2 = request.derive_with_master_seed(seed)?;
+
+    assert_eq!(key1, key2);
+
+    Ok(())
+}
+```
+
+[BIP-0032]: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki
diff --git a/crates/derive/keyfork-derive-util/src/lib.rs b/crates/derive/keyfork-derive-util/src/lib.rs
index 402c918..eaf53d3 100644
--- a/crates/derive/keyfork-derive-util/src/lib.rs
+++ b/crates/derive/keyfork-derive-util/src/lib.rs
@@ -1,6 +1,6 @@
 #![allow(clippy::module_name_repetitions, clippy::must_use_candidate)]
 
-//! BIP-0032 derivation utilities.
+#![doc = include_str!("../README.md")]
 
 ///
 pub mod extended_key;
diff --git a/crates/derive/keyfork-derive-util/src/request.rs b/crates/derive/keyfork-derive-util/src/request.rs
index 231fba5..e01bbfa 100644
--- a/crates/derive/keyfork-derive-util/src/request.rs
+++ b/crates/derive/keyfork-derive-util/src/request.rs
@@ -31,7 +31,7 @@ pub type Result<T, E = DerivationError> = std::result::Result<T, E>;
 
 /// The algorithm to derive a key for. The choice of algorithm will result in a different resulting
 /// derivation.
-#[derive(Serialize, Deserialize, Clone, Debug)]
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 #[non_exhaustive]
 pub enum DerivationAlgorithm {
     #[allow(missing_docs)]
@@ -94,7 +94,7 @@ impl std::str::FromStr for DerivationAlgorithm {
 }
 
 /// A derivation request.
-#[derive(Serialize, Deserialize, Clone, Debug)]
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct DerivationRequest {
     algorithm: DerivationAlgorithm,
     path: DerivationPath,
@@ -211,7 +211,7 @@ impl DerivationRequest {
 }
 
 /// A response to a [`DerivationRequest`]
-#[derive(Serialize, Deserialize, Clone, Debug)]
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct DerivationResponse {
     /// The algorithm used to derive the data.
     pub algorithm: DerivationAlgorithm,