From 1b9a2a79f2c83152842a31432dc49eb96652b20d Mon Sep 17 00:00:00 2001 From: ethicnology Date: Thu, 14 Nov 2024 13:56:21 -0500 Subject: [PATCH] docs: functions --- src/drng.rs | 20 ++++++++++++++++++++ src/hex.rs | 9 +++++++++ src/mnemonic.rs | 22 +++++++++++++++++++++- src/pwd_base64.rs | 8 ++++++++ src/pwd_base85.rs | 8 ++++++++ src/wif.rs | 9 ++++++++- src/xprv.rs | 9 ++++++++- tests/bip85_tests.rs | 6 +----- 8 files changed, 83 insertions(+), 8 deletions(-) diff --git a/src/drng.rs b/src/drng.rs index 4461219..a035b58 100644 --- a/src/drng.rs +++ b/src/drng.rs @@ -3,6 +3,26 @@ use sha3::{ Shake256, Shake256ReaderCore, }; +/// BIP85-DRNG-SHAKE256 is a deterministic random number generator for cryptographic functions that require deterministic outputs, but where the input to that function requires more than the 64 bytes provided by BIP85's HMAC output. +/// BIP85-DRNG-SHAKE256 uses BIP85 to seed a SHAKE256 stream (from the SHA-3 standard). +/// +/// The input must be exactly 64 bytes long. +/// +/// See [specs](https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki#bip85-drng) for more info. +/// +/// ### Example +/// ```rust +/// let xprv = Xpriv::from_str("xprv9s21ZrQH143K2LBWUUQRFXhucrQqBpKdRRxNVq2zBqsx8HVqFk2uYo8kmbaLLHRdqtQpUm98uKfu3vca1LqdGhUtyoFnCNkfmXRyPXLjbKb").unwrap(); +/// let path = DerivationPath::from_str("m/0'/0'").unwrap(); +/// let derived = derive(&Secp256k1::new(), &xprv, &path).unwrap(); +/// let entropy: [u8; 64] = derived.try_into().unwrap(); +/// println!("Entropy: {}", entropy.clone().to_lower_hex_string()); +/// +/// let mut drng_reader = DRNG::new(entropy); +/// let mut drng_80_bytes = [0u8; 80]; +/// drng_reader.read(&mut drng_80_bytes); +/// println!("DRNG: {}", drng_80_bytes.to_lower_hex_string()); +/// ``` pub struct DRNG { reader: XofReaderCoreWrapper, } diff --git a/src/hex.rs b/src/hex.rs index 026859f..c9cf905 100644 --- a/src/hex.rs +++ b/src/hex.rs @@ -3,9 +3,18 @@ use bitcoin::bip32::{ChildNumber, DerivationPath}; use bitcoin::hex::DisplayHex; use bitcoin::{bip32::Xpriv, key::Secp256k1, secp256k1}; +/// Derive entropy into hexadecimal +/// /// The `length` can be from 16 to 64 and defines number of bytes derived. /// /// See [specs](https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki#hex) for more info. +/// +/// ### Example +/// ```rust +/// let root = Xpriv::from_str("xprv9s21ZrQH143K2LBWUUQRFXhucrQqBpKdRRxNVq2zBqsx8HVqFk2uYo8kmbaLLHRdqtQpUm98uKfu3vca1LqdGhUtyoFnCNkfmXRyPXLjbKb").unwrap(); +/// let secp = Secp256k1::new(); +/// let derived = to_hex(&secp, &root, 64, 0).unwrap(); +/// ``` pub fn to_hex( secp: &Secp256k1, root: &Xpriv, diff --git a/src/mnemonic.rs b/src/mnemonic.rs index 369a9f9..bb68991 100644 --- a/src/mnemonic.rs +++ b/src/mnemonic.rs @@ -8,12 +8,20 @@ use bitcoin::bip32::{ChildNumber, DerivationPath}; use bitcoin::{bip32::Xpriv, key::Secp256k1, secp256k1}; #[cfg(feature = "mnemonic")] -/// Derive mnemonic in given language +/// Derive entropy into a mnemonic for the in given language /// /// See [specs](https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki#bip39) /// for more info. /// /// `word_count` can be 12, 18 or 24, `index` - anything lower than `0x80000000` +/// +/// ### Example +/// ```rust +/// let root = Xpriv::from_str("xprv9s21ZrQH143K2LBWUUQRFXhucrQqBpKdRRxNVq2zBqsx8HVqFk2uYo8kmbaLLHRdqtQpUm98uKfu3vca1LqdGhUtyoFnCNkfmXRyPXLjbKb").unwrap(); +/// let secp = Secp256k1::new(); +/// let mnemonic = bip85_fork::to_mnemonic_in(&secp, &root, Language::Japanese, 18, 0).unwrap(); +/// println!("18-word mnemonic in Japanese:\n{}", mnemonic); +/// ``` pub fn to_mnemonic_in( secp: &Secp256k1, root: &Xpriv, @@ -66,6 +74,18 @@ pub fn to_mnemonic_in( /// Same as `to_mnemonic_in` using English language as default. /// /// `word_count` can be 12, 18 or 24, `index` - anything lower than `0x80000000` +/// +/// ### Example +/// ```rust +/// let root = Xpriv::from_str("xprv9s21ZrQH143K2LBWUUQRFXhucrQqBpKdRRxNVq2zBqsx8HVqFk2uYo8kmbaLLHRdqtQpUm98uKfu3vca1LqdGhUtyoFnCNkfmXRyPXLjbKb").unwrap(); +/// let secp = Secp256k1::new(); +/// +/// let mnemonic = to_mnemonic(&secp, &root, 12, 0).unwrap(); +/// println!("12-word english mnemonic:\n{}", mnemonic); +/// +/// let mnemonic = to_mnemonic(&secp, &root, 24, 0).unwrap(); +/// println!("24-word english mnemonic:\n{}", mnemonic); +/// ``` #[cfg(feature = "mnemonic")] pub fn to_mnemonic( secp: &Secp256k1, diff --git a/src/pwd_base64.rs b/src/pwd_base64.rs index b961d50..48fd087 100644 --- a/src/pwd_base64.rs +++ b/src/pwd_base64.rs @@ -4,9 +4,17 @@ use base64::Engine; use bitcoin::bip32::{ChildNumber, DerivationPath}; use bitcoin::{bip32::Xpriv, key::Secp256k1, secp256k1}; +/// Derive entropy into base64 +/// /// The `length` can be from 20 to 86 and defines number of bytes derived. /// /// See [specs](https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki#pwd-base64) for more info. +/// +/// ### Example +/// ```rust +/// let root = Xpriv::from_str("xprv9s21ZrQH143K2LBWUUQRFXhucrQqBpKdRRxNVq2zBqsx8HVqFk2uYo8kmbaLLHRdqtQpUm98uKfu3vca1LqdGhUtyoFnCNkfmXRyPXLjbKb").unwrap(); +/// let pwd_base64 = to_pwd_base64(&Secp256k1::new(), &root, 21, 0).unwrap(); +/// ``` pub fn to_pwd_base64( secp: &Secp256k1, root: &Xpriv, diff --git a/src/pwd_base85.rs b/src/pwd_base85.rs index 8fdf1c4..87425cc 100644 --- a/src/pwd_base85.rs +++ b/src/pwd_base85.rs @@ -2,9 +2,17 @@ use super::Error; use bitcoin::bip32::{ChildNumber, DerivationPath}; use bitcoin::{bip32::Xpriv, key::Secp256k1, secp256k1}; +/// Derive entropy into base85 +/// /// The `length` can be from 10 to 80 and defines number of bytes derived. /// /// See [specs](https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki#pwd-base85) for more info. +/// +/// ### Example +/// ```rust +/// let root = Xpriv::from_str("xprv9s21ZrQH143K2LBWUUQRFXhucrQqBpKdRRxNVq2zBqsx8HVqFk2uYo8kmbaLLHRdqtQpUm98uKfu3vca1LqdGhUtyoFnCNkfmXRyPXLjbKb").unwrap(); +/// let pwd_base64 = to_pwd_base85(&Secp256k1::new(), &root, 21, 0).unwrap(); +/// ``` pub fn to_pwd_base85( secp: &Secp256k1, root: &Xpriv, diff --git a/src/wif.rs b/src/wif.rs index 5b93b4c..be8868a 100644 --- a/src/wif.rs +++ b/src/wif.rs @@ -4,12 +4,19 @@ use bitcoin::secp256k1::SecretKey; use bitcoin::PrivateKey; use bitcoin::{bip32::Xpriv, key::Secp256k1, secp256k1}; -/// Derive Bitcoin Private Key from the root inner +/// Derive entropy into a Bitcoin Private Key HD-Seed WIF /// /// See [specs](https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki#hd-seed-wif) /// for more info. /// /// `index` can be any number lower than `0x80000000` +/// +/// ### Example +/// ```rust +/// let root = Xpriv::from_str("xprv9s21ZrQH143K2LBWUUQRFXhucrQqBpKdRRxNVq2zBqsx8HVqFk2uYo8kmbaLLHRdqtQpUm98uKfu3vca1LqdGhUtyoFnCNkfmXRyPXLjbKb").unwrap(); +/// let secp = Secp256k1::new(); +/// let derived = to_wif(&secp, &root, 0).unwrap(); +/// ``` pub fn to_wif( secp: &Secp256k1, root: &Xpriv, diff --git a/src/xprv.rs b/src/xprv.rs index 4b27520..6e591bc 100644 --- a/src/xprv.rs +++ b/src/xprv.rs @@ -4,11 +4,18 @@ use bitcoin::{bip32::Xpriv, key::Secp256k1, secp256k1}; use super::Error; -/// Derive bip32 extended private inner from root xprv +/// Derive bip32 extended private key /// /// See [specs](https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki#xprv) for more info. /// /// `index` can be any number lower than `0x80000000` +/// +/// ### Example +/// ```rust +/// let root = Xpriv::from_str("xprv9s21ZrQH143K2LBWUUQRFXhucrQqBpKdRRxNVq2zBqsx8HVqFk2uYo8kmbaLLHRdqtQpUm98uKfu3vca1LqdGhUtyoFnCNkfmXRyPXLjbKb").unwrap(); +/// let secp = Secp256k1::new(); +/// let derived = to_xprv(&secp, &root, 0).unwrap(); +/// ``` pub fn to_xprv( secp: &Secp256k1, root: &Xpriv, diff --git a/tests/bip85_tests.rs b/tests/bip85_tests.rs index d38f128..2502899 100644 --- a/tests/bip85_tests.rs +++ b/tests/bip85_tests.rs @@ -44,11 +44,7 @@ fn test_raw() { #[test] fn test_priv() { - let root = Xpriv::from_str( - "xprv9s21ZrQH143K2LBWUUQRFXhucrQqBpKdRRxNVq2zBqsx8HVqFk2uYo8kmbaL\ - LHRdqtQpUm98uKfu3vca1LqdGhUtyoFnCNkfmXRyPXLjbKb", - ) - .unwrap(); + let root = Xpriv::from_str("xprv9s21ZrQH143K2LBWUUQRFXhucrQqBpKdRRxNVq2zBqsx8HVqFk2uYo8kmbaLLHRdqtQpUm98uKfu3vca1LqdGhUtyoFnCNkfmXRyPXLjbKb").unwrap(); let secp = Secp256k1::new(); let derived = to_wif(&secp, &root, 0).unwrap(); let expected =