Architecture Details

Crate Details

zns-types -- Core types and validation

Component	Details
Name validation	3-63 chars, a-z, 0-9, hyphens. No leading/trailing/consecutive hyphens.
Fee calculation	3-4 chars = 1 ZEC, 5-7 chars = 0.1 ZEC, 8+ chars = 0.01 ZEC
Memo parsing	REGISTER (7 fields, pubkey + signature), BUY (7 fields, escrow format). UPDATE/TRANSFER/LIST/DELIST rejected on-chain.
Ed25519 signature	verify_ed25519_signature(), validate_pubkey_hex(), validate_signature_hex() in signature.rs
Transaction types	Txid, ZnsTransaction, ChainBlock, TransactionTarget (Registrar/Escrow)

zns-chain -- Blockchain data sources

Component	Details
ChainSource trait	get_latest_height(), get_blocks(from, to)
MockChainSource	In-memory simulator with tx injection, block mining, escrow tx injection
LightwalletChainSource	gRPC to lightwalletd, dual-UFVK scanning (registrar + escrow)
Trial decryption	Sapling and Orchard output decryption
Registrar keys	Deterministic from SHA-256("ZNS Registrar v1 - Zcash Naming Service")
Escrow keys	From ZNS_ESCROW_SEED, retains spending key for payouts

zns-scanner -- Transaction processing engine

Component	Details
SQLite DB	Tables: scanner_state, registrations, operations_log, listings, escrow_payouts, escrow_refunds
REGISTER handler	Validates name, checks not taken, verifies Ed25519 signature, checks fee
Escrow BUY handler	Validates listing, price match, payment amount. Queues payout/refund.
Scanner loop	Async polling (5s), persistent state across restarts
Transaction routing	Routes by (operation, target): REGISTER->Registrar, BUY->Escrow
Deterministic ordering	Same-block transactions sorted by txid

zns-api -- REST API server

Endpoint	Method	Response
/v1/resolve/{name}	GET	{name, address}
/v1/names/{name}	GET	Full details (owner, txids, listing, nonce)
/v1/owner/pubkey/{pubkey}	GET	All names owned by pubkey
/v1/status	GET	{scanner_height, chain_height, total_registrations}
/v1/marketplace/listings	GET	All active listings
/v1/marketplace/listing/{name}	GET	Single listing details
/v1/escrow/payouts	GET	Pending seller payouts
/v1/escrow/refunds	GET	Pending buyer refunds
/v1/names/{name}/update	POST	Signed address update
/v1/names/{name}/transfer	POST	Signed ownership transfer
/v1/names/{name}/list	POST	Signed marketplace listing
/v1/names/{name}/delist	POST	Signed delisting
/v1/names/{name}/confirm-sale	POST	Signed atomic sale
/debug/submit_memo	POST	Inject tx (mock only)
/debug/mine_blocks	POST	Advance chain (mock only)
/debug/inject_escrow_tx	POST	Inject escrow tx (mock only)

zns-wallet -- CLI wallet tool (identity, signing, escrow commands)

Test Coverage

112 tests pass:

Crate	Tests	Coverage
zns-types	46	Name validation (14), memo parsing (22), transaction types (4), Ed25519 (6)
zns-scanner	24	DB CRUD (12), processor logic (12)
zns-chain	8	Mock chain (3), registrar keys (2), escrow keys (3)
zns-api	20	Marketplace flow (10), signed ops (10)

Run: cd zns && cargo test --workspace

Dependencies

Dependency	Version	Purpose
zcash_client_backend	0.21	lightwalletd gRPC, block scanning
zcash_primitives	0.26	Transaction parsing
zcash_keys	0.12	Key derivation, unified addresses
zcash_protocol	0.7	Consensus parameters, memo types
zcash_note_encryption	0.4	Sapling memo decryption
sapling-crypto	0.5	Sapling trial decryption
orchard	0.11	Orchard trial decryption
axum	0.8	HTTP API framework
rusqlite	0.32	SQLite database (bundled)
tonic	0.14	gRPC client for lightwalletd
ed25519-dalek	2	Ed25519 signatures