BitVMX Key Manager is a comprehensive Rust library designed for managing cryptographic keys used in BitVMX protocol transactions. It offers robust methods for generating, importing, and deriving keys, as well as signing messages using ECDSA, Schnorr, Winternitz, and MuSig2 algorithms. The library ensures secure storage of keys, making it a reliable choice for blockchain and cryptographic applications.
This library is currently under development and may not be fully stable. It is not production-ready, has not been audited, and future updates may introduce breaking changes without preserving backward compatibility.
A random mnemonic will be auto generated and stored, is no one is provided by configuration, and if it's not already found at the keystore. Make sure to back it up securely!
- 🔑 Key Generation and Storage: Generate new keys and store them securely.
- 📥 Key Importing: Import existing private keys into the keystore.
- 🌐 Key Derivation: Derive keys using BIP39, BIP44 hierarchical deterministic wallets.
- ✍️ Message Signing: Sign messages using ECDSA, Schnorr, Winternitz, and MuSig2 algorithms.
- ✅ Signature Verification: Verify signatures for ECDSA, Schnorr, Winternitz, and MuSig2.
The BitVMX Key Manager implements different strategies for key derivation and storage based on the cryptographic algorithm and practical considerations:
- HD Derivation: Bitcoin keys are derived using hierarchical deterministic (HD) derivation following BIP39/BIP44 standards from a master seed/mnemonic
- Storage: Both private and public keys are stored in the encrypted keystore for persistent access
- Rationale: Standard Bitcoin practice enabling deterministic key generation and wallet recovery
- HD Derivation: Winternitz keys are HD derived from the same master seed for consistency
- Storage: Keys are not stored in the keystore - they are regenerated on-demand each time they're needed
- Rationale: Storage scalability - Winternitz signatures require large key sets that would significantly bloat storage requirements. Since they can be deterministically regenerated from the HD seed, we prioritize storage efficiency
- Fresh Entropy: RSA keys are generated using fresh entropy provided by the user, with no correlation to the HD mnemonic
- Storage: Private and public keys are stored in the encrypted keystore
- Rationale: While HD derivation of RSA keys is theoretically possible (as explored in research), we deliberately choose fresh entropy generation to:
- Align with RSA industry standards and best practices
- Provide stronger security guarantees independent of the HD seed
- Acknowledge that users must backup the keystore anyway due to key importing features
- No HD Correlation: Imported keys have no relationship to the master HD mnemonic by design
- Storage: Stored in the encrypted keystore alongside generated keys
- Rationale: Preserves the original entropy and properties of externally generated keys
Important: Since the key manager supports importing external keys and uses fresh entropy for RSA keys, users must backup the entire encrypted keystore in addition to the HD mnemonic. The mnemonic alone is insufficient for complete wallet recovery.
Internally the key manager generates a key pair, stores the private key and the corresponding public key in the encrypted keystore. The public key is later used to select the corresponding private key for signing.
next_keypair is always the preferred way to get a new keypair, as it manages the derivation index automatically.
The KeyManager supports both Taproot script path spends and key path spends (with or without tweaking). These methods use Schnorr signatures and are compatible with BIP-340/341 Taproot usage in Bitcoin.
The key manager supports Winternitz one-time keys. Winternitz keys can be generated using SHA-256 or RIPEMD-160 hash functions. As with the ECDSA keys, a key pair is generated and only the public key is returned. The public key can later be used to select the corresponding private key for signing.
The KeyManager supports MuSig2 multi-signature schemes, allowing multiple parties to jointly produce a single Schnorr signature. See more details on MuSig2 for Rust.
- Clone the repository
- Install dependencies:
cargo build - Run tests:
cargo test -- --test-threads=1
- create:
run with
cargo run --example create - key_gen:
run with
cargo run --example key_gen - key_import:
run with
cargo run --example key_import - deriving_winternitz:
run with
cargo run --example deriving_winternitz - sign_verify_ecdsa:
run with
cargo run --example sign_verify_ecdsa - sign_verify_schnorr_taproot:
run with
cargo run --example sign_verify_schnorr_taproot - sign_verify_winternitz:
run with
cargo run --example sign_verify_winternitz - rsa:
run with
cargo run --example rsa
Contributions are welcome! Please open an issue or submit a pull request on GitHub.
This project is licensed under the MIT License - see LICENSE file for details.
This repository is a component of the BitVMX Ecosystem, an open platform for disputable computation secured by Bitcoin. You can find the index of all BitVMX open-source components at FairgateLabs/BitVMX.