1 Introduction

This volume states the protocols by which a wallet, in the sense of “Parties, pools, and classifications” (§1.2), performs three tasks. It derives and holds keys and addresses: hierarchical key derivation (ZIP 32), and unified addresses and unified viewing keys (ZIP 316). It discovers and tracks its notes: the compact-block format (ZIP 307) as an abstract message format, trial decryption, nullifier tracking, the retention of the note commitment tree information that its witnesses need, and what an untrusted light-client server learns. It pays: anchors and confirmation depths (ZIP 315), expiry (ZIP 203), the conventional fee (ZIP 317), transaction construction (note selection, change, dummy Actions), partially created transactions (ZIP 374), the transaction lifecycle from submission to a terminal state, and payment requests (ZIP 321).

The subject is the wallet of a user of the Orchard protocol who holds funds in the Ironwood pool, the sealed Orchard pool, the Sapling pool and the transparent pool. Sapling constructions and transparent scripts are cited to the protocol specification and to the BIPs where a wallet protocol needs them, and are never constructed; constructions of the shielded protocol are cited to the Ironwood Guide by section title, and are never re-derived. The light-client service is an abstract query and response interface, and tree storage is the information that a wallet retains; no implementation is described. The volume is non-normative: the protocol specification and the ZIPs are authoritative.

The volume describes the protocols as specified for NU7, whose deployment ZIP, ZIP 259, has status Draft.

ZIP 307 specifies the compact format for the Sapling pool only: a compact block of height, block hash and transactions, and a compact transaction of index, transaction identifier, and compact Sapling spends and outputs. The parent hash, the tree sizes, the compact Actions of both Orchard-protocol pools, the transparent part and pool selection are designed but unspecified in the sense of the Ironwood Guide, Definition “Epistemic classes” (“Scope and status”), and the volume states them abstractly in “Compact blocks (ZIP 307)” (§4).

Rules of the Ironwood pool and of NU6.3 are cited to the NU6.3 edition of the protocol specification, labelled “NU6.3 proposal”, whose section numbers equal those of the default edition; the text on $\mathrm{𝗎𝗌𝖾}\mathrm{\_}\mathrm{𝗊𝗌𝗄}$ for protocol specification, §“Orchard Key Components”, is in no edition and is cited to ZIP 2005, “Changes to the Protocol Specification”, directly.

Table 1 gives the status, and only the status, of each ZIP that the volume cites. Every later citation of these ZIPs relies on the table for status. ZIP 258 activates ZIP 2005 with NU6.3 (ZIP 258, “ZIP 2005 activation”).

A wallet is a party that holds a seed and the keys derived from it, and no copy of the chain. A light-client server is a party that answers the queries of a wallet from its own view of the best chain, the best valid block chain of the Consensus Guide, “Work, and the best chain” (Definition “Best valid block chain”). The network is the set of the nodes that relay transactions and blocks and of the miners that produce blocks. The trust placed in the server is not fixed here; it is an assumption of “Architecture and authority” (§5.1).

A wallet handles funds in four value pools. The first is the transparent pool. The second is the Sapling pool (protocol specification, §“Chain Value Pool Balances”), whose constructions are cited, never constructed. The third and fourth are the Ironwood pool and the sealed Orchard pool, the two value pools of the Orchard protocol (Ironwood Guide, “The Orchard protocol and its two pools”, Definitions “Orchard protocol” and “Orchard pool, Ironwood pool”; ZIP 229, Terminology); each has its own note commitment tree, its own nullifier set and its own chain value pool balance. The rules that seal the Orchard pool are cited there (ZIP 258, “Consensus rules from NU6.3 activation”), and are stated for wallets in “Payments to pools” (§11.2).

Heights are counted as in the Ironwood Guide, “Scope and status” (Definition “Block chain, transaction, consensus rules”), the genesis block having height $0$. The tip $T$ is the height of the last block of the wallet’s view of the best chain. Every other height (the target height, the anchor height, the expiry height) is defined where it is first used.

Every design-stage statement of the volume carries one class of Definition 1.1, and every deployed rule is cited at its use to the section of the protocol specification or of the ZIP that fixes it. A specified rule keeps the normative level of its source (MUST, SHOULD, MAY).