docs: functions

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<Shake256ReaderCore>,
 }

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<C: secp256k1::Signing>(
     secp: &Secp256k1<C>,
     root: &Xpriv,

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<C: secp256k1::Signing>(
     secp: &Secp256k1<C>,
     root: &Xpriv,
@@ -66,6 +74,18 @@ pub fn to_mnemonic_in<C: secp256k1::Signing>(
 /// 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<C: secp256k1::Signing>(
     secp: &Secp256k1<C>,

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<C: secp256k1::Signing>(
     secp: &Secp256k1<C>,
     root: &Xpriv,

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<C: secp256k1::Signing>(
     secp: &Secp256k1<C>,
     root: &Xpriv,

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<C: secp256k1::Signing>(
     secp: &Secp256k1<C>,
     root: &Xpriv,

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<C: secp256k1::Signing>(
     secp: &Secp256k1<C>,
     root: &Xpriv,

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 =