wallethd

README

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

Platform	Command
Swift Package Manager	.package(url: "https://github.com/devdasx/wallet-hd-derivation-kit.git", from: "1.0.0")
CocoaPods	pod 'WalletHDDerivationKit', '~> 1.0'
npm	npm install wallet-hd-derivation-kit
GitHub npm	npm install @devdasx/wallet-hd-derivation-kit
JSR	deno add jsr:@devdasx/wallet-hd
Python	python -m pip install wallet-hd-derivation-kit
Rust	cargo add wallet-hd-derivation-kit
Go	go get github.com/devdasx/wallet-hd-derivation-kit@v1.0.0
Dart / Flutter	dart pub add wallet_hd_derivation_kit / flutter pub add wallet_hd_derivation_kit
Kotlin / Android	implementation("io.github.devdasx:wallet-hd-derivation-kit:1.0.0")
Homebrew CLI	brew install devdasx/crypto-kits/wallethd
Cargo CLI	cargo install wallet-hd-derivation-kit --version 1.0.0 --locked
Shell installer	curl -fsSL https://raw.githubusercontent.com/devdasx/wallet-hd-derivation-kit/v1.0.0/install.sh | sh
Container	docker run --rm ghcr.io/devdasx/wallethd:1.0.0 list-chains

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

Family	Chains and behavior
Bitcoin	Mainnet/testnet BIP-44/49/84/86; P2PKH, nested/native SegWit, Taproot; x/y/z/t/u/v pub/prv
Litecoin	BIP-44/49, Ltub/Ltpv and Mtub/Mtpv; native SegWit addresses may be derived from seed without inventing a prefix
UTXO BIP-44	Dogecoin, Dash, DigiByte, Bitcoin Cash CashAddr, Zcash transparent
EVM	Ethereum, Ethereum Classic, Polygon, BNB Smart Chain, Avalanche C-Chain, Arbitrum, Optimism, Base; EIP-55
TRON	BIP-44 coin type 195 and Base58Check T… addresses
Solana	Hardened SLIP-0010 Ed25519 and Base58 public-key addresses

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.

Documentation

Overview

Package wallethd derives standards-compliant HD-wallet keys and addresses.

It is offline-only: no API in this package performs network I/O. Private material is available only through explicitly named private-key functions.

Index

• Constants
• Variables
• func SerializeExtendedKey(parsed ParsedExtendedKey, private bool, formatName string) (string, error)
• type AccountPrivateKey
  • func DeriveAccountPrivateKey(source Source, options Options) (AccountPrivateKey, error)
• type AccountPublicKey
  • func DeriveAccountPublicKey(source Source, options Options) (AccountPublicKey, error)
• type Chain
  • func SupportedChains() []Chain
• type DerivedAddress
  • func DeriveAddress(source Source, options Options) (DerivedAddress, error)
  • func DeriveAddressFromExtendedPublicKey(value, chainID string, change, index uint32, script string) (DerivedAddress, error)
  • func DeriveAddresses(source Source, options Options, start, count uint32) ([]DerivedAddress, error)
• type Format
• type NodeResult
  • func DeriveNode(source Source, curve, path string) (NodeResult, error)
• type Options
• type ParsedExtendedKey
  • func ParseExtendedKey(value string) (ParsedExtendedKey, error)
• type Source
  • func MnemonicSource(words, passphrase string) Source
  • func SeedSource(seed []byte) Source

Constants

const (
	APISchemaVersion = 1
	HardenedOffset   = uint32(0x80000000)
)

Variables

var (
	ErrInvalidMnemonic = errors.New("invalid BIP39 English mnemonic")
	ErrInvalidSeed     = errors.New("seed must be between 16 and 64 bytes")
	ErrHardenedPublic  = errors.New("extended public keys can derive only non-hardened children")
	ErrInvalidKey      = errors.New("invalid BIP32 key material")
	ErrInvalidExtended = errors.New("invalid extended key")
)

Functions

func SerializeExtendedKey

func SerializeExtendedKey(parsed ParsedExtendedKey, private bool, formatName string) (string, error)

Types

type AccountPrivateKey

type AccountPrivateKey struct {
	SchemaVersion      int `json:"schemaVersion"`
	Chain, Curve, Path string
	Format             *string `json:"format"`
	ExtendedPrivateKey *string `json:"extendedPrivateKey"`
	PrivateKeyHex      string  `json:"privateKeyHex"`
	PublicKeyHex       string  `json:"publicKeyHex"`
}

func DeriveAccountPrivateKey

func DeriveAccountPrivateKey(source Source, options Options) (AccountPrivateKey, error)

type AccountPublicKey

type AccountPublicKey struct {
	SchemaVersion              int `json:"schemaVersion"`
	Chain, Curve, Path, Format string
	ExtendedPublicKey          string `json:"extendedPublicKey"`
	PublicKeyHex               string `json:"publicKeyHex"`
}

func DeriveAccountPublicKey

func DeriveAccountPublicKey(source Source, options Options) (AccountPublicKey, error)

type Chain

type Chain struct {
	ID, Name, Symbol, Curve, DefaultFormat, DefaultScriptType string
	CoinType                                                  uint32
	P2PKH, P2SH                                               []byte
	HRP                                                       string
}

func SupportedChains

func SupportedChains() []Chain

type DerivedAddress

type DerivedAddress struct {
	SchemaVersion int    `json:"schemaVersion"`
	Chain         string `json:"chain"`
	Curve         string `json:"curve"`
	Path          string `json:"path"`
	Account       uint32 `json:"account"`
	Change        uint32 `json:"change"`
	Index         uint32 `json:"index"`
	ScriptType    string `json:"scriptType"`
	Address       string `json:"address"`
	PublicKeyHex  string `json:"publicKeyHex"`
}

func DeriveAddress

func DeriveAddress(source Source, options Options) (DerivedAddress, error)

func DeriveAddressFromExtendedPublicKey

func DeriveAddressFromExtendedPublicKey(value, chainID string, change, index uint32, script string) (DerivedAddress, error)

func DeriveAddresses

func DeriveAddresses(source Source, options Options, start, count uint32) ([]DerivedAddress, error)

type Format

type Format struct {
	Name, ScriptType              string
	PublicVersion, PrivateVersion uint32
	Purpose                       uint32
}

type NodeResult

type NodeResult struct {
	SchemaVersion int    `json:"schemaVersion"`
	Curve         string `json:"curve"`
	Path          string `json:"path"`
	PublicKeyHex  string `json:"publicKeyHex"`
	ChainCodeHex  string `json:"chainCodeHex"`
	Depth         byte   `json:"depth"`
	ChildNumber   uint32 `json:"childNumber"`
}

func DeriveNode

func DeriveNode(source Source, curve, path string) (NodeResult, error)

type Options

type Options struct {
	Chain, Format, ScriptType, Path string
	Account, Change, Index          uint32
}

type ParsedExtendedKey

type ParsedExtendedKey struct {
	Value                string `json:"value"`
	VersionHex, Format   string
	IsPrivate            bool   `json:"isPrivate"`
	Depth                byte   `json:"depth"`
	ChildNumber          uint32 `json:"childNumber"`
	ParentFingerprintHex string `json:"parentFingerprintHex"`
	ChainCodeHex         string `json:"chainCodeHex"`
	PublicKeyHex         string `json:"publicKeyHex"`
	// contains filtered or unexported fields
}

func ParseExtendedKey

func ParseExtendedKey(value string) (ParsedExtendedKey, error)

type Source

type Source struct {
	Mnemonic   string
	Passphrase string
	Seed       []byte
}

Source holds exactly one validated BIP39 mnemonic or a 16-64 byte seed.

func MnemonicSource

func MnemonicSource(words, passphrase string) Source

func SeedSource

func SeedSource(seed []byte) Source