latest

pkg/bip85/README.md

@@ -0,0 +1,152 @@
+# BIP85 - Deterministic Entropy From BIP32 Keychains
+
+This package implements [BIP85](https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki), which allows for deterministic derivation of entropy from a BIP32 master key. This enables a single seed to generate multiple wallet keys, mnemonics, and random values in a fully deterministic way.
+
+## Overview
+
+BIP85 enables a variety of use cases:
+- Generate multiple BIP39 mnemonic seeds from a single master key
+- Derive Bitcoin HD wallet seeds (WIF format)
+- Create extended private keys (XPRV)
+- Generate deterministic random values for hex values and passwords
+
+## Usage Examples
+
+### Initialization
+
+```go
+import (
+    "fmt"
+    "git.eeqj.de/sneak/secret/pkg/bip85"
+    "github.com/btcsuite/btcd/btcutil/hdkeychain"
+)
+
+// Parse an existing master key
+masterKeyStr := "xprv9s21ZrQH143K2LBWUUQRFXhucrQqBpKdRRxNVq2zBqsx8HVqFk2uYo8kmbaLLHRdqtQpUm98uKfu3vca1LqdGhUtyoFnCNkfmXRyPXLjbKb"
+masterKey, err := bip85.ParseMasterKey(masterKeyStr)
+if err != nil {
+    panic(err)
+}
+```
+
+### Derive BIP39 Mnemonic
+
+```go
+// Parameters:
+// - language (0 = English, 1 = Japanese, 2 = Korean, 3 = Spanish, etc.)
+// - number of words (12, 15, 18, 21, or 24)
+// - index (allows multiple seeds of the same type)
+entropy, err := bip85.DeriveBIP39Entropy(masterKey, 0, 12, 0)
+if err != nil {
+    panic(err)
+}
+
+// Use the entropy with github.com/tyler-smith/go-bip39
+// to generate a mnemonic
+mnemonic, err := bip39.NewMnemonic(entropy)
+if err != nil {
+    panic(err)
+}
+fmt.Println("12-word BIP39 mnemonic:", mnemonic)
+```
+
+### Derive HD-WIF Key
+
+```go
+// Create a WIF format key for Bitcoin Core's hdseed
+wif, err := bip85.DeriveWIFKey(masterKey, 0)
+if err != nil {
+    panic(err)
+}
+fmt.Println("WIF Key:", wif)
+```
+
+### Derive XPRV
+
+```go
+// Create an extended private key (XPRV)
+xprv, err := bip85.DeriveXPRV(masterKey, 0)
+if err != nil {
+    panic(err)
+}
+fmt.Println("XPRV:", xprv.String())
+```
+
+### Generate Hex Data
+
+```go
+// Generate arbitrary hex data (16-64 bytes)
+hex, err := bip85.DeriveHex(masterKey, 32, 0)
+if err != nil {
+    panic(err)
+}
+fmt.Println("32 bytes of hex:", hex)
+```
+
+### DRNG (Deterministic Random Number Generator)
+
+```go
+// First derive entropy
+path := "m/83696968'/0'/0'"
+entropy, err := bip85.DeriveBIP85Entropy(masterKey, path)
+if err != nil {
+    panic(err)
+}
+
+// Create a deterministic random number generator
+drng := bip85.NewBIP85DRNG(entropy)
+
+// Read arbitrary amount of random bytes
+buffer := make([]byte, 32)
+_, err = drng.Read(buffer)
+if err != nil {
+    panic(err)
+}
+fmt.Printf("Random bytes: %x\n", buffer)
+```
+
+## BIP85 Paths
+
+The derivation paths follow the format:
+
+```
+m/83696968'/{app}'/{parameters}
+```
+
+Where:
+- `83696968'` is the BIP85 root path (BIP in ASCII)
+- `{app}'` is the application number:
+  - `39'` for BIP39 mnemonics
+  - `2'` for HD-WIF keys
+  - `32'` for XPRV
+  - `128169'` for HEX data
+  - `707764'` for Base64 passwords
+  - `707785'` for Base85 passwords
+  - `828365'` for RSA keys
+- `{parameters}` are application-specific parameters
+
+## Test Vectors
+
+This implementation passes all the test vectors from the BIP85 specification:
+
+- Basic test cases
+- BIP39 12, 18, and 24 word mnemonics
+- HD-WIF keys
+- XPRV
+- SHAKE256 DRNG output
+
+The implementation is also compatible with the Python reference implementation's test vectors for the DRNG functionality.
+
+Run the tests with verbose output to see the test vectors and results:
+
+```
+go test -v git.eeqj.de/sneak/secret/pkg/bip85
+```
+
+## References
+
+- [BIP85 Specification](https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki)
+- [Python Reference Implementation](https://github.com/ethankosakovsky/bip85)
+- [Bitcoin Core](https://github.com/bitcoin/bitcoin)
+- [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki)
+- [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki)