# filosottile/zcash-mini architecture

> Architecture diagram of the GitHub repository filosottile/zcash-mini, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/filosottile/zcash-mini
- Repository: https://github.com/filosottile/zcash-mini

## Overview

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`](https://github.com/filosottile/zcash-mini/blob/master/main.go) (CLI), [`zcash/address.go`](https://github.com/filosottile/zcash-mini/blob/master/zcash/address.go) (Address core), [`bip39/bip39.go`](https://github.com/filosottile/zcash-mini/blob/master/bip39/bip39.go) (Mnemonic), [`README.md`](https://github.com/filosottile/zcash-mini/blob/master/README.md) (Docs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Interface"]
  node_main["CLI<br/>entrypoint<br/>[main.go]"]
  node_wallet_flow(("Wallet flow<br/>pipeline"))
  node_vanity_search(("Vanity search<br/>loop"))
  node_output_boundary(("Print-only<br/>boundary"))
end

subgraph group_core["Core"]
  node_zcash_addr["Address core<br/>zcash-domain<br/>[address.go]"]
  node_mnemonic["Mnemonic<br/>bip39-encoding<br/>[bip39.go]"]
end

subgraph group_crypto["Crypto"]
  node_sha256_core["SHA-256<br/>crypto-primitive<br/>[sha256.go]"]
  node_sha256_block["Block transform<br/>hash-internal<br/>[sha256block.go]"]
end

subgraph group_packaging["Packaging"]
  node_vendor_deps[("Vendor<br/>deps")]
  node_makefile["Build"]
  node_readme["Docs<br/>usage<br/>[README.md]"]
end

node_main -->|"drives"| node_wallet_flow
node_main -->|"supports"| node_vanity_search
node_main -->|"delegates"| node_zcash_addr
node_main -->|"encodes/decodes"| node_mnemonic
node_main -->|"prints"| node_output_boundary
node_wallet_flow -->|"derives"| node_zcash_addr
node_wallet_flow -->|"optional"| node_mnemonic
node_mnemonic -->|"hashes with"| node_sha256_core
node_sha256_core -->|"implements"| node_sha256_block
node_zcash_addr -->|"hashes with"| node_sha256_core
node_zcash_addr -->|"returns to"| node_output_boundary
node_main -->|"builds against"| node_vendor_deps
node_makefile -->|"builds"| node_main
node_readme -->|"documents"| node_main
node_readme -->|"documents"| node_zcash_addr
node_readme -->|"documents"| node_mnemonic

click node_main "https://github.com/filosottile/zcash-mini/blob/master/main.go"
click node_zcash_addr "https://github.com/filosottile/zcash-mini/blob/master/zcash/address.go"
click node_mnemonic "https://github.com/filosottile/zcash-mini/blob/master/bip39/bip39.go"
click node_sha256_core "https://github.com/filosottile/zcash-mini/blob/master/sha256/sha256.go"
click node_sha256_block "https://github.com/filosottile/zcash-mini/blob/master/sha256/sha256block.go"
click node_vendor_deps "https://github.com/filosottile/zcash-mini/tree/master/vendor"
click node_makefile "https://github.com/filosottile/zcash-mini/tree/master/Makefile"
click node_readme "https://github.com/filosottile/zcash-mini/blob/master/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_wallet_flow,node_vanity_search,node_output_boundary toneBlue
class node_zcash_addr,node_mnemonic toneAmber
class node_sha256_core,node_sha256_block toneMint
class node_vendor_deps,node_makefile,node_readme toneRose
```

## Components

### Interface

CLI entrypoint and user-facing workflow

- [CLI](https://github.com/filosottile/zcash-mini/blob/master/main.go): entrypoint · Parses flags and orchestrates wallet generation, restore, and vanity modes · `main.go`
- **Wallet flow**: pipeline · Offline path from entropy to secret key, address, viewing key, and optional mnemonic
- **Vanity search**: loop · Repeatedly generates candidates until a prefix or regexp matches
- **Print-only**: boundary · Emits derived artifacts to stdout and avoids persistent secret storage

### Core

Zcash key and mnemonic logic

- [Address core](https://github.com/filosottile/zcash-mini/blob/master/zcash/address.go): zcash-domain · Derives shielded addresses and related keys from secret material · `zcash/address.go`
- [Mnemonic](https://github.com/filosottile/zcash-mini/blob/master/bip39/bip39.go): bip39-encoding · Encodes and decodes secret keys as 24-word recovery phrases · `bip39/bip39.go`

### Crypto

Bundled hashing implementation

- [SHA-256](https://github.com/filosottile/zcash-mini/blob/master/sha256/sha256.go): crypto-primitive · Pure-Go SHA-256 implementation used by the wallet pipeline · `sha256/sha256.go`
- [Block transform](https://github.com/filosottile/zcash-mini/blob/master/sha256/sha256block.go): hash-internal · Low-level compression and block processing for SHA-256 · `sha256/sha256block.go`

### Packaging

Build and dependency packaging

- [Vendor](https://github.com/filosottile/zcash-mini/tree/master/vendor): deps · Pinned third-party dependencies for reproducible builds · `vendor`
- [Build](https://github.com/filosottile/zcash-mini/tree/master/Makefile): build · Builds the standalone binary and supports cross-compilation · `Makefile`
- [Docs](https://github.com/filosottile/zcash-mini/blob/master/README.md): usage · Explains offline generation, restore flow, and external import into zcash-cli · `README.md`

## Connections

- 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