How filosottile/zcash-mini works
1. What this repo is
- zcash-mini is a single-purpose, offline command-line wallet generator for Zcash shielded addresses (z-addresses).
- It is intentionally not a full wallet: it does not manage balances, talk to a node, or spend funds.
2. Top-level architecture
- The repo is split into one CLI entrypoint and three internal packages:
- main.go for flag parsing and orchestration
- zcash/ for Zcash key/address derivation
- bip39/ for mnemonic encoding/decoding
- sha256/ for a bundled pure-Go SHA-256 implementation used by the crypto pipeline
- This makes the tool easy to review, portable, and cross-compile.
3. CLI orchestration layer
- main.go is the control plane.
- It supports multiple modes: generate a new wallet, reprocess an existing key, restore from mnemonic, and vanity-search modes (-prefix, -regexp).
- It also has a -simple output mode for scripting, indicating the CLI is the only user-facing interface.
4. Wallet generation pipeline
- The default flow is: entropy generation → secret spending key → shielded address → viewing key → optional mnemonic.
- The program prints all derived artifacts to stdout and explicitly does not persist the secret key anywhere.
- That “print-only” behavior is a key architectural boundary: the repo’s responsibility ends at key material generation and formatting.
5. Zcash-specific core
- zcash/address.go contains the domain logic for turning a secret key into a Zcash shielded address and related keys.
- This package is the main cryptographic boundary for Zcash semantics; the CLI delegates to it rather than embedding derivation logic in main.go.
- The tests in zcash/address_test.go suggest this is where correctness of address/key derivation is enforced.
6. Mnemonic / paper-wallet support
- bip39/ converts the secret key into a 24-word mnemonic and back again.
- This is the paper-wallet subsystem: it allows the private key to be recovered from the written word sequence.
- The README shows the intended use: print the mnemonic, store it offline, and later rebuild the secret key with -mnemonic.
7. Bundled crypto primitive
- sha256/ is a local SHA-256 implementation rather than relying on an external package.
- Architecturally, this reinforces portability and reviewability: the project keeps its crypto dependencies self-contained.
- This package is a low-level helper used by the higher-level wallet/mnemonic logic.
8. Vanity address mode
- Vanity generation is implemented as a search loop in the CLI layer, not as a separate subsystem.
- The program repeatedly generates candidate keys until the derived address matches a requested prefix or regex.
- Because this is CPU-bound and brute-force, it remains strictly local; there is no GPU or distributed search path.
9. Operational boundary with Zcash nodes
- The repo does not integrate with a node directly.
- The intended workflow is external: generate the address offline, receive funds to it, then import the secret key into zcash-cli with z_importkey KEY rescan when spending is needed.
- That means the code stops at key generation; transaction management lives outside the repo.
10. Build and deployment
- Makefile produces the binary, and the README explicitly supports cross-compiling with GOOS/GOARCH.
- The vendor/ directory indicates dependencies are pinned for reproducible builds.
- The overall deployment model is a tiny standalone executable, suitable for air-gapped or low-resource environments.
11. Testing boundaries
- Each core package has tests: bip39_test.go, sha256_test.go, and address_test.go.
- That reflects the architecture: correctness is concentrated in deterministic crypto/encoding functions, while the CLI mostly composes them.
Main entry points: main.go CLI · address.go Address core · bip39.go Mnemonic · README.md Docs
Components 11
Interface
CLI entrypoint and user-facing workflow
- CLI · Parses flags and orchestrates wallet generation, restore, and vanity modes
main.go - Wallet flow · Offline path from entropy to secret key, address, viewing key, and optional mnemonic
- Vanity search · Repeatedly generates candidates until a prefix or regexp matches
- Print-only · Emits derived artifacts to stdout and avoids persistent secret storage
Core
Zcash key and mnemonic logic
- Address core · Derives shielded addresses and related keys from secret material
zcash/address.go - Mnemonic · Encodes and decodes secret keys as 24-word recovery phrases
bip39/bip39.go
Crypto
Bundled hashing implementation
- SHA-256 · Pure-Go SHA-256 implementation used by the wallet pipeline
sha256/sha256.go - Block transform · Low-level compression and block processing for SHA-256
sha256/sha256block.go
Connections 16
- CLI → Wallet flow: drives · Coordinates the default generation and restore pipeline
- CLI → Vanity search: supports · Handles prefix and regexp search modes
- CLI → Address core: delegates · Uses Zcash-specific derivation instead of embedding it in the CLI
- CLI → Mnemonic: encodes/decodes · Turns secret keys into recovery phrases and back
- CLI → Print-only: prints · Writes generated artifacts to stdout
- Wallet flow → Address core: derives · Converts entropy and secret keys into shielded address material
- Wallet flow → Mnemonic: optional · Adds paper-wallet recovery output when requested
- Mnemonic → SHA-256: hashes with · Uses SHA-256 as part of mnemonic/key processing
- SHA-256 → Block transform: implements · Relies on the internal block compressor
- Address core → SHA-256: hashes with · Uses bundled hashing in Zcash derivation logic
- Address core → Print-only: returns to · Supplies key and address artifacts for printing
- CLI → Vendor: builds against · Uses pinned dependencies during compilation
- Build → CLI: builds · Produces the standalone executable
- Docs → CLI: documents · Describes CLI modes and offline workflow
- Docs → Address core: documents · Explains shielded address generation
- Docs → Mnemonic: documents · Explains mnemonic-based recovery