This section fixes the heights and the set of notes from which a wallet builds a transaction. It states the confirmation policy of ZIP 315; the target height and the anchor height, with the lemma that ties the anchor depth to the trusted confirmation depth; the expiry rule of ZIP 203 and the expiry height a wallet sets; the record a wallet keeps of the transactions it creates and the notes those transactions lock; and the spendability categories of ZIP 315, with the spendable set defined from the wallet’s state.
An output mined in a block of the best chain leaves the chain when a reorganisation replaces that block (Ironwood Guide, §“Anchors”, Definition “Reorganisation”), so a wallet spends an output only once it has a number of confirmations fixed by a policy. The rules of this subsection are those of ZIP 315 and are specified (Definition 1.1); the status of ZIP 315 is that of Table 1.
A confirmation policy is a triple (c tr, c untr, z) of integers
A TXO is an output, transparent coin or shielded note, of a transaction of the best chain or of a mempool visible to the wallet (ZIP 315, “Terminology”). A TXO received by the wallet is trusted if it is an output of a transaction created by the wallet itself, which a wallet SHOULD treat as trusted, or of an external transaction that the user has marked trusted, a marking that a wallet MAY offer; every other received TXO is untrusted (ZIP 315, “Trusted and untrusted TXOs”; ZIP 315, “Prompt accessibility of funds”). A trusted TXO requires c tr confirmations and an untrusted TXO c untr . The output of a shielding transaction is not trusted by virtue of its internal receiver (ZIP 315, “Transparent UTXOs”); its depth rule is stated below.
The rationale of the default depths is ZIP 315’s and is cited, not derived (ZIP 315, “Rationale for the given numbers of confirmations”): the trusted depth is 3 because reorganisations are anecdotally shorter than three blocks, and the two depths differ because the value of a trusted TXO is recoverable after a rollback, the wallet re-creating its transaction, whereas an untrusted TXO may need the sender to pay again. The modelled double-spend risk of a given count is that of the Consensus Guide, §“Waiting for confirmations” and §“Wallet confirmation policy”: three confirmations give an attacker with 10 % of the hash rate a success probability of 1.712 % , and ten about 0.0008 % . A confirmation count bounds the modelled double-spend probability only for a stated attacker share q of the hash rate and a tolerated probability ε (Consensus Guide, §“Wallet confirmation policy”); it is not a guarantee.
Confirmation counts are in blocks, not in time. At the 25 -second target
spacing (ZIP 218, “Block target spacing”; Consensus Guide,
§“Confirmation times at 25-second spacing”), 10 blocks are
Two kinds of transaction enter the rules below; both are constructed in “TEX transfers and shielding transactions” (§11.3). A shielding transaction spends transparent UTXOs of the wallet and pays their value, less the fee, to an internal shielded receiver of the spending account, with no other recipient. An ephemeral UTXO is the transparent output that the first transaction of a transfer to a TEX address creates and its second transaction spends (ZIP 320, “Design considerations for Senders”; ZIP 315, “Trusted and untrusted TXOs”).
The following rules are specified. Floor: wallets SHOULD NOT permit
the spending of TXOs with fewer than 3 confirmations, except (i)
transparent UTXOs spent in shielding transactions and (ii) ephemeral UTXOs
of a ZIP 320 transfer, whose second transaction spends an output that may be
unmined (ZIP 315, “Trusted and untrusted TXOs”). Zero-confirmation
shielding: wallets MAY spend received transparent UTXOs in wallet-internal
shielding transactions with zero confirmations (ZIP 315, “Transparent
UTXOs”); the flag z of Definition 9.1 records whether
the wallet does. Shielding outputs: a shielded output of a
wallet-internal shielding transaction meets its depth requirement if and
only if every transparent UTXO that the transaction spent has at least
ZIP 315 states the rule for shielding outputs twice, and the two statements
differ. The paragraph “Shielded TXOs” requires
| T ≥ h s + max (6, 2 + d), |
and the second at every tip
| T − h s + 1 ≥ 7 | ⇔ T ≥ h s + 6, | ||
| T − h s + 1 ≥ 10 | ⇔ T ≥ h s + 9, | ||
| T − (h s + d) + 1 ≥ 3 | ⇔ T ≥ h s + 2 + d . |
The rule stated above is the first reading, the one inside ZIP 315’s definition of a confirmed-spendable TXO. Which reading the ZIP intends is an open problem (Definition 1.1).
Let T be the height of the tip of the wallet’s view of the chain, the
height returned by Tip () (Definition 5.10).
The target height of a transaction built at that view is
Let (c tr, c untr, z) be a confirmation policy
(Definition 9.1) and
| A := H − c tr, |
a function of H and the policy alone. One anchor height serves every
anchor that the transaction carries, including that of an Orchard-protocol
bundle whose Actions spend no note. For a pool
Let T be the tip,
the note’s commitment is a leaf of the tree rooted by the anchor of its pool at A ;
the note has at least c tr confirmations at T .
The anchor depth thus equals the trusted confirmation depth: a note with
exactly c tr confirmations lies in the block at height A . At
The final treestate of the block at height A holds exactly the
commitments appended in the blocks at heights
The rule for the anchor is specified: a wallet SHOULD choose an anchor a
number of blocks back from the head of the chain equal to the trusted
confirmation depth, the ZIP’s instance being the final treestate of the
block at height
ZIP 315 counts the anchor depth back from the head of the chain, and ZIP
218, “Anchor selection depth”, reads it as the tip, so that a 4 -block
reorganisation is needed to remove the anchor; the Ironwood Guide,
§“Anchors”, Remark “Recommended anchor depth”, follows that reading, which
puts the anchor at
The anchor depth is c tr whatever the trust of the notes spent. The eligibility of each note is decided by its own depth (Definition 9.2), so an untrusted note spent at depth c untr is proved against the anchor at depth c tr , whose tree contains it by Lemma 9.6. ZIP 315 gives three reasons for the rule, specified and cited (ZIP 315, “Rationale for anchor selection”): a rollback past the anchor block invalidates the transaction, whose revealed nullifiers then link it to any later transaction spending the same notes; too deep an anchor keeps recently received notes from being spent; and a fixed depth, rather than one depending on whether the notes spent are trusted, does not reveal their trust. The anchor is published data (Ironwood Guide, §“Anchors”, Remark “Anchor choice as public data”).
Every Orchard-protocol bundle with at least one Action carries an anchor, which must refer to the final treestate of an earlier block in its pool, whether or not any Action spends a note of nonzero value (protocol specification, §“Action Transfers and their Descriptions”; consensus rule). Giving such a bundle the anchor at A makes it indistinguishable by its anchor from a bundle that spends (Ironwood Guide, §“Anchors”, Remark “Anchor choice as public data”).
Every transaction of version at least 3 carries a field
Let t be a non-coinbase transaction with expiry height N , and T the
tip. The expiry rule permits t in the block at the target height
By Definition 9.8, the rule permits t at height H if
and only if
A wallet sets
ZIP 315 specifies (SHOULD) that a wallet create transactions using the
default expiration height of ZIP 203, which it gives as 40 blocks from
the current height (ZIP 315, “Expiration height”). ZIP 218 changes the
default of node implementations that create transactions to
The choice of delta has a privacy consequence, specified. ZIP 315 lists the expiry height, with the anchor position, among the data that reveal to which height the creator was synchronised and some of its policy (ZIP 315, “Kinds of information leakage”), and it specifies a common default (ZIP 315, “Expiration height”). An expiry delta other than the common one therefore distinguishes its creator, as a fee other than the conventional fee does (§10).
The expiry height is fixed by the transaction identifier: nExpiryHeight is effecting data, an input of the header digest (ZIP 244, “T.1: header_digest”), so by Lemma 13.1(ii) a party matches a transaction, and rejects it once expired, by its identifier alone.
When a transaction expires, nodes remove it from their mempools together with every transaction that depends on it (ZIP 203, “Specification”). This is node policy layered on the consensus rule, which constrains only the contents of blocks.
The transaction record of a wallet holds, for each transaction t that the wallet creates:
the identifier txid (t) and the encoding of t , once the wallet holds it;
its fee, its target height H t and its expiry height N t ;
the set of its inputs: the notes it spends in each shielded pool and the transparent outpoints it spends;
its mined height, or ⊥ while it is unmined;
the earliest height h t obs at which it was observed: initially H t for a transaction the wallet builds, and the height of the block in which it was first seen mined for a record entered from compact blocks;
the latest tip at which the server reported it unmined.
A record entered without the encoding of the transaction has N t unknown; such is the record of a transaction learnt from compact blocks, whose compact transaction carries no expiry height (Definition 4.3), and later unmined by a rollback (Definition 7.23). The transitions of the record are those of “Status tracking and terminal states” (§13.2). The record is information that the wallet retains, not a storage layout.
Fix an expiry delta
t is mined, necessarily at a height below H ;
N t is unknown and
A locked note is excluded from selection.
Let t be a recorded transaction with known expiry height N t that
spends a note. At target height
For known N t , condition (d) of Definition 9.12 is void.
By Lemma 9.9, the expiry rule permits t at H if and
only if
Condition (d) of Definition 9.12 assumes that t was
created with the delta δ at a target height at most
h t obs , so that
The watched nullifiers are the set
The mining of any transaction that spends a note of the wallet is therefore
detected by scanning through W , independently of status queries
(Ironwood Guide, §“Nullifier sets”). A rule that removed from W
the nullifiers spent by transactions with
Relative to a chain and a wallet state (ZIP 315, “Categories of TXOs according to spendability”):
a TXO is known-spendable if and only if (1) it is unspent at the wallet’s view of the tip and that view is reasonably up to date, (2) it is not committed to be spent in another unexpired transaction created by the wallet (Proposition 9.13), and (3) the wallet can effect the spend, by holding its spending key or by mediating interaction with a hardware device or another offline signing protocol;
a shielded TXO is confirmed-spendable if and only if it is known-spendable, the wallet can construct its witness (Theorem 7.14), and either it is not an output of a wallet-internal shielding transaction and has c tr confirmations if trusted, c untr if untrusted (Definition 9.2), or it is such an output and meets the rule for shielding outputs of §9.1 (ZIP 315, “Shielded TXOs”);
a known-spendable TXO that is not confirmed-spendable is unconfirmed-spendable;
a TXO is watch-only if and only if the wallet holds its full viewing key, or for a transparent TXO its address, but not its spending key;
a transparent UTXO is confirmed-shieldable if and only if it is known-spendable and the wallet can construct a correct redeem script for it (ZIP 315, “Transparent UTXOs”).
The following rule is specified: a wallet MUST NOT attempt to spend, in a user-initiated transaction, a TXO that is not confirmed-spendable. ZIP 315 notes that the confirmed-spendable balance is 0 until the wallet has synchronised at least the nullifier set to the tip (ZIP 315, “Reporting of balances”).
Let T be the tip,
the note n is in the note state (Definition 6.7),
it is not marked spent, and
it is not locked at H (Definition 9.12);
the wallet holds the spending key of the account of n , or mediates a signer for it;
The spendable set at H is the set of notes spendable at H , each with its value, pool, position and authentication path at A .
Condition (d) implies
A policy that admits a note once the block extent of its own subtree is scanned up to A (Definition 7.16), before every range up to T is scanned, departs from clause (a) of Definition 9.17 and from ZIP 315, whose clause on an up-to-date view carries an open TODO in the ZIP. The departure fails as follows. A note whose spend was mined in a range not yet scanned passes the policy; a transaction that spends it again is rejected by the consensus rule that a nullifier must not repeat (Ironwood Guide, §“Nullifier sets”), and its repeated nullifier links it to the earlier spend for every party that sees it. The departure is designed but unspecified (Definition 1.1).