Wallet HD Derivation Kit

Production-oriented, offline HD-wallet derivation for Swift, JavaScript, React Native, Python, Rust, Go, Dart/Flutter, Kotlin/JVM/Android, and the wallethd CLI. Every implementation is native to its language and checked against the same public vectors.

Security: derivation is deterministic, but secret handling is your responsibility. Never paste a real mnemonic into source code, logs, analytics, issue reports, or an online playground. This project has not yet received an independent third-party audit.

30-second start

JavaScript:

npm install wallet-hd-derivation-kit

import { deriveAddress } from "wallet-hd-derivation-kit";

const result = deriveAddress({
  source: { mnemonic: process.env.WALLET_MNEMONIC },
  chain: "bitcoin",
});
console.log(result.address); // private material is not in this result

CLI:

brew install devdasx/crypto-kits/wallethd
wallethd address --chain bitcoin --prompt --pretty

The CLI reads mnemonic/seed material through a hidden prompt, stdin, or a permission-checked file. Mnemonics, seeds, and passphrases are never accepted as command-line values. Private output requires --show-secrets.

Install

Swift Package Manager requires Swift tools 6.2 or newer. CocoaPods consumers compile the same Swift sources with the toolchain selected by their application.

See the verified examples for Swift, JavaScript, React Native, Python, Rust, Go, Dart, Flutter, Kotlin, and CLI.

Supported chains

The machine-readable matrix is spec/chains.json. Cardano, Substrate, Cosmos, Stellar, NEAR, and XRP are intentionally not advertised in v1 because their chain-specific derivation rules require separate work.

Standards boundary

xpub, ypub, and zpub are Bitcoin-style BIP-32/SLIP-0132 serialized keys, not universal chain formats. Generic secp256k1 extended keys require an explicit chain when deriving an address because version bytes do not identify every coin. Solana uses hardened SLIP-0010 Ed25519 and has neither a BIP-32 xpub nor public child derivation.

Public API

Each language provides idiomatic equivalents of:

deriveNode(source, curve, path)
deriveAccountPublicKey(source, chain, scriptType, account)
deriveAccountPrivateKey(...)
deriveAddress(source, chain, account, change, index, scriptType)
deriveAddresses(..., start, count)
deriveAddressFromExtendedPublicKey(...)
parseExtendedKey(...)
serializeExtendedKey(...)
supportedChains()

source is a checksum-validated English BIP-39 mnemonic plus optional passphrase, or a 16–64 byte seed. Paths must be absolute and may use ', h, or H for hardened components. Normal result serialization excludes private data; private key exports are available only from explicitly named private APIs.

CLI

wallethd account       Derive an account xpub; --show-secrets selects private output
wallethd address       Derive one address
wallethd addresses     Derive a bounded batch
wallethd from-xpub     Derive watch-only addresses
wallethd derive-path   Derive an explicit path
wallethd inspect-key   Parse an extended key
wallethd list-chains   Print machine-readable chain support
wallethd vectors verify
wallethd demo          Run only published test vectors
wallethd completion    Generate shell completions
wallethd version

Successful data commands emit JSON schema v1 and exit 0. Any usage, secret-input, verification, or derivation failure exits 2 and writes a concise error to stderr. The CLI makes no telemetry, RPC, balance, update-check, or other network request.

Correctness and trust

• Seven native implementations agree on all 18 default chain vectors in npm run conformance.
• Tests cover watch-only public derivation, public/private child equivalence, BIP-86, SLIP-0132, malformed paths, invalid checksums, batch limits, and serialization round trips.
• Public vectors live in the versioned test-vectors collection, including every official BIP-32 valid/invalid vector and the SLIP-0010 Ed25519 chain.
• Dependency choices and exact pins are documented in DEPENDENCIES.md.
• Threats, non-goals, secret boundaries, fuzzing, and audit status are documented in SECURITY.md and docs/threat-model.md.
• No API performs runtime network I/O. See OFFLINE.md.

Source of truth and releases

GitHub is the only source repository. Registry packages are immutable builds of signed vX.Y.Z tags; registry copies are never edited independently. A merge to main redeploys documentation. Release jobs are separately rerunnable and skip versions that already exist.

Repository: https://github.com/devdasx/wallet-hd-derivation-kit

Documentation: https://devdasx.github.io/wallet-hd-derivation-kit/

Changelog: CHANGELOG.md

Security policy: SECURITY.md

MIT © ROYO STUDIOS.