The Zcash ArboretumWallet Guide PDF

9 Anchors, confirmations, and expiry

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.

9.1 The confirmation policy

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.

Definition 9.1 (Confirmation policy).

A confirmation policy is a triple (ctr,cuntr,z) of integers 1≤ctr≤cuntr, the trusted and the untrusted confirmation depth, and a flag z∈{𝗍𝗋𝗎𝖾,𝖿𝖺𝗅𝗌𝖾} that permits zero-confirmation shielding. Confirmations are those of the Consensus Guide, §“Work, and the best chain”, Definition “Confirmations”: at a tip of height T, an output mined in the block of height m≤T of the best chain has T−m+1 confirmations, its own block being the first; an output of a transaction that no block of the best chain contains has 0. ZIP 315 RECOMMENDS the depths ctr=3 and cuntr=10 (“Trusted and untrusted TXOs”) and permits, without recommending, z=𝗍𝗋𝗎𝖾 (“Transparent UTXOs”, MAY); a wallet SHOULD have a policy that it communicates to the user in a clear form (“Trusted and untrusted TXOs”).

Definition 9.2 (Trusted and untrusted outputs).

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 ctr confirmations and an untrusted TXO cuntr. 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, §“Zcash time: 25-second blocks”), 10 blocks are 10×25=250 s and 3 blocks are 3×25=75 s. ZIP 218 does not argue for reducing confirmation counts (ZIP 218, “Motivation”) and keeps the anchor depth at 3 blocks (ZIP 218, “Anchor selection depth”). Neither an equal count nor an equal elapsed time establishes an equal risk, whose model is that of the Consensus Guide.

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 cuntr−ctr confirmations and the shielding transaction has at least ctr (ZIP 315, “Shielded TXOs”). With hs the greatest mining height of the spent UTXOs and T the tip, the first condition is T−hs+1≥cuntr−ctr.

Remark 9.3 (Two readings of the shielding rule).

ZIP 315 states the rule for shielding outputs twice, and the two statements differ. The paragraph “Shielded TXOs” requires cuntr−ctr confirmations of the source UTXOs; the paragraph “Transparent UTXOs” requires cuntr confirmations of the transaction that produced them. Both require ctr confirmations of the shielding transaction. Let the sources be mined at greatest height hs and the shielding transaction at hs+d with d≥0. At the policy (3,10,𝗍𝗋𝗎𝖾), the first reading is met at every tip

T≥hs+max⁡(6, 2+d),

and the second at every tip T≥hs+max⁡(9, 2+d); the two agree for d≥7. Indeed, a block at height m has T−m+1 confirmations at tip T (Definition 9.1), and

T−hs+1≥7 ⇔T≥hs+6,
T−hs+1≥10 ⇔T≥hs+9,
T−(hs+d)+1≥3 ⇔T≥hs+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).

9.2 Target and anchor heights

Definition 9.4 (Target height).

Let T be the height of the tip of the wallet’s view of the chain, the height returned by 𝖳𝗂𝗉⁢() (Definition 5.10). The target height of a transaction built at that view is H:=T+1, the height of the first block that could include it. Every height-dependent rule of construction is fixed by H: the consensus branch, the fee rule and the expiry height are those of a block of height H, and confirmation counts are taken at the tip T=H−1.

Definition 9.5 (Anchor height).

Let (ctr,cuntr,z) be a confirmation policy (Definition 9.1) and H≥ctr a target height. The anchor height of a transaction with target height H is

A:=H−ctr,

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 P∈{Sapling,Orchard,Ironwood}, the anchor of the transaction’s bundle of P is the root of P’s note commitment tree in the final treestate of the block at height A (Ironwood Guide, §“Anchors”, Definition “Treestate and anchor”), and the authentication path of every note that the transaction spends from P is computed to that root (Ironwood Guide, §“Authentication paths”). Since ctr≥1, the block at height A precedes the block at height H, as the consensus anchor rules require (Ironwood Guide, §“Anchors”; protocol specification, §“Action Transfers and their Descriptions” and §“Spend Transfers, Output Transfers, and their Descriptions”). A transaction therefore carries, for each pool it touches, its own anchor and authentication paths, the Orchard pool and the Ironwood pool of the Orchard protocol separately.

Lemma 9.6 (Anchor height and confirmations).

Let T be the tip, H=T+1 and A=H−ctr. For a note mined at height m≤T of the best chain, the following are equivalent:

  1. (i)

    the note’s commitment is a leaf of the tree rooted by the anchor of its pool at A;

  2. (ii)

    m≤A;

  3. (iii)

    the note has at least ctr confirmations at T.

The anchor depth thus equals the trusted confirmation depth: a note with exactly ctr confirmations lies in the block at height A. At ctr=3 the anchor height is A=T−2, and a note with at least cuntr=10 confirmations is mined at a height at most T−9<A.

Proof.

The final treestate of the block at height A holds exactly the commitments appended in the blocks at heights 0,…,A (Ironwood Guide, §“Anchors”, Definition “Treestate and anchor” and Remark “Old anchors”), so (i) and (ii) are equivalent. By Definition 9.1 the note has T−m+1 confirmations, and T−m+1≥ctr if and only if m≤T+1−ctr=A, so (ii) and (iii) are equivalent. The instances follow with ctr=3, A=T+1−3, and T−m+1≥10 if and only if m≤T−9. □

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 H315−3 when the current block is at height H315 (ZIP 315, “Anchor selection”). ZIP 218 recommends that the depth stay 3 blocks at the 25-second spacing, 3×25=75 s (ZIP 218, “Anchor selection depth”). The rule is a recommendation to the builder, not a consensus rule: the anchor rules admit the final treestate of any earlier block.

Remark 9.7 (The anchor convention).

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 T−3 with ctr+1 confirmations. This volume’s convention counts from the block being built, H=T+1, one block shallower, which gives Lemma 9.6: the anchor block has exactly ctr confirmations. Both satisfy the consensus anchor rules.

The anchor depth is ctr 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 cuntr is proved against the anchor at depth ctr, 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”).

9.3 Expiry (ZIP 203)

Definition 9.8 (Transaction expiry).

Every transaction of version at least 3 carries a field 𝗇𝖤𝗑𝗉𝗂𝗋𝗒𝖧𝖾𝗂𝗀𝗁𝗍∈{0,…,232−1}, a block height and never a timestamp; for a non-coinbase transaction, 𝗇𝖤𝗑𝗉𝗂𝗋𝗒𝖧𝖾𝗂𝗀𝗁𝗍≤499,999,999 (consensus rule). A non-coinbase transaction with N:=𝗇𝖤𝗑𝗉𝗂𝗋𝗒𝖧𝖾𝗂𝗀𝗁𝗍≠0 is expired at height h if and only if h>N, and it MUST NOT be mined at a height greater than N (consensus rule), so the block at height N is the last that may include it; the value N=0 disables expiry (protocol specification, §“Transaction Encoding and Consensus”; ZIP 203, “Specification”). Coinbase transactions, which a wallet does not create, are outside the definition.

Lemma 9.9 (Includability at the next block).

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 H=T+1 if and only if N=0 or T<N; when N≠0, it permits t in no block of height greater than N. Inclusion requires the other consensus rules as well; the lemma concerns expiry only.

Proof.

By Definition 9.8, the rule permits t at height H if and only if N=0 or H≤N, and H=T+1≤N if and only if T<N. The second claim is the rule itself. □

Construction 9.10 (Expiry height of a wallet transaction).

A wallet sets 𝗇𝖤𝗑𝗉𝗂𝗋𝗒𝖧𝖾𝗂𝗀𝗁𝗍:=H+δ, where H is the target height (Definition 9.4) and δ≥1 is an expiry delta chosen by the wallet. Reading ZIP 203’s “current height” as the target height is designed but unspecified (Definition 1.1). Every later rule that depends on the delta, the locking of notes (§9.4) and the polling and re-sending of transactions (§13), uses the δ actually chosen.

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 𝖭𝖴𝟩𝖯𝗈𝖶𝖳𝖺𝗋𝗀𝖾𝗍𝖲𝗉𝖺𝖼𝗂𝗇𝗀𝖱𝖺𝗍𝗂𝗈×40=120 blocks (SHOULD), to keep an expiry of about 50 minutes, and keeps an explicitly configured delta (ZIP 218, “Default expiry delta”); ZIP 315 is not updated for the 25-second spacing. At that spacing, ZIP 315’s SHOULD therefore has two readings: the literal 40 blocks, about 40×25=1000 s, and the ZIP 203 default as ZIP 218 changes it, 120 blocks, about 120×25=3000 s. Which one a wallet uses is an open problem (Definition 1.1). Either time is an estimate, since block intervals vary, and not a guaranteed period of validity.

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: 𝗇𝖤𝗑𝗉𝗂𝗋𝗒𝖧𝖾𝗂𝗀𝗁𝗍 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.

9.4 The transaction record and locked notes

Definition 9.11 (Transaction record).

The transaction record of a wallet holds, for each transaction t that the wallet creates:

  1. (i)

    the identifier 𝗍𝗑𝗂𝖽⁢(t) and the encoding of t, once the wallet holds it;

  2. (ii)

    its fee, its target height Ht and its expiry height Nt;

  3. (iii)

    the set of its inputs: the notes it spends in each shielded pool and the transparent outpoints it spends;

  4. (iv)

    its mined height, or ⊥ while it is unmined;

  5. (v)

    the earliest height htobs at which it was observed: initially Ht 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;

  6. (vi)

    the latest tip at which the server reported it unmined.

A record entered without the encoding of the transaction has Nt 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.

Definition 9.12 (Locked note).

Fix an expiry delta δ≥1, a parameter of the definition, whose default at the 25-second spacing is the open problem of §9.3. At target height H, a note is locked if and only if some recorded transaction t that spends it satisfies one of:

  1. (a)

    t is mined, necessarily at a height below H;

  2. (b)

    Nt=0;

  3. (c)

    Nt≥H;

  4. (d)

    Nt is unknown and htobs+δ≥H.

A locked note is excluded from selection.

Proposition 9.13 (Locks follow includability).

Let t be a recorded transaction with known expiry height Nt that spends a note. At target height H=T+1, the conditions of Definition 9.12 hold for t if and only if t is mined or the expiry rule permits t at H (Lemma 9.9). Hence, for a note that no mined recorded transaction spends and whose recorded spending transactions all have known expiry heights, being unlocked is the clause of ZIP 315 that the TXO is not committed to be spent in another unexpired transaction created by the wallet (ZIP 315, “Categories of TXOs according to spendability”); a mined spend, which condition (a) locks, makes the note spent, and ZIP 315’s clause that the TXO is unspent excludes it; and an unmined t with Nt>0 releases its inputs, as far as t is concerned, at every target height H>Nt.

Proof.

For known Nt, condition (d) of Definition 9.12 is void. By Lemma 9.9, the expiry rule permits t at H if and only if Nt=0 or H≤Nt, which are conditions (b) and (c); with condition (a) this gives the first claim. By Definition 9.8, t is unexpired at H if and only if Nt=0 or H≤Nt, so for an unmined t the conditions hold exactly when t is an unexpired transaction of the wallet that spends the note, and a note is unlocked exactly when no such transaction exists, which is ZIP 315’s clause (ZIP 203, “Specification”). For H>Nt>0 and t unmined, each of (a) to (d) fails. □

Remark 9.14 (Unknown expiry).

Condition (d) of Definition 9.12 assumes that t was created with the delta δ at a target height at most htobs, so that Nt≤htobs+δ. If Nt=0, or its creator used a larger delta with Nt>htobs+δ, the note is released from H=htobs+δ+1 while t can still be mined (for H≤Nt, or at every H if Nt=0), and a re-spend conflicts with the late mining of t. If its creator used a smaller delta, the note stays locked longer than necessary. Either misjudgement lasts until the wallet sees t mined, or obtains its encoding and hence Nt by the query 𝖳𝗑 (Definition 5.10).

Definition 9.15 (Watched nullifiers).

The watched nullifiers are the set W:=⋃PWP of the tracked sets of Definition 6.7: the nullifiers of the wallet’s detected notes not marked spent. A lock (Definition 9.12) removes a note from selection and never removes its nullifier from W. A nullifier leaves W only when Construction 6.8 marks its note spent, that is, when a transaction revealing it is mined, whatever that transaction’s expiry height, N=0 included; or when a rollback unmines the creating transaction of a Sapling note, whose nullifier is then discarded until a later scan derives it again (Definition 7.23(iii)). A rollback that clears the spent mark returns the nullifier to W.

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 N=0, combined with status polling that ends at the first report of an unmined transaction, would leave such a transaction, when it has no output to the wallet, mined and never observed as mined: no block would reveal a watched nullifier, and no note of the wallet would be created by it.

9.5 Spendable notes

Definition 9.16 (Spendability categories).

Relative to a chain and a wallet state (ZIP 315, “Categories of TXOs according to spendability”):

  1. (i)

    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;

  2. (ii)

    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 ctr confirmations if trusted, cuntr 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”);

  3. (iii)

    a known-spendable TXO that is not confirmed-spendable is unconfirmed-spendable;

  4. (iv)

    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;

  5. (v)

    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”).

Definition 9.17 (Spendable note at a target height).

Let T be the tip, H=T+1, A=H−ctr (Definition 9.5), and f the fully scanned height (Definition 6.11). A shielded note n of pool P, mined at height m, is spendable at H if and only if:

  1. (a)

    the note n is in the note state (Definition 6.7), it is not marked spent, and f≥T;

  2. (b)

    it is not locked at H (Definition 9.12);

  3. (c)

    the wallet holds the spending key of the account of n, or mediates a signer for it;

  4. (d)

    it meets its depth: T−m+1≥ctr or T−m+1≥cuntr according to its trust (Definition 9.2), or, if n is an output of a wallet-internal shielding transaction, the rule for shielding outputs of §9.1;

  5. (e)

    the authentication path of the position of n to the anchor of P at A is computable from retained information (Theorem 7.14, Proposition 7.17).

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 m≤A in each case, since cuntr≥ctr and the shielding transaction has at least ctr confirmations, so n lies in the tree of the anchor by Lemma 9.6. The spendable set at H is the set of confirmed-spendable shielded notes of Definition 9.16, with ZIP 315’s “reasonably up-to-date” instantiated as f≥T; the instantiation is designed but unspecified (Definition 1.1). Clause (a) is clause (1) of known-spendability: with f≥T, every block up to the tip has been scanned, and a note is marked spent exactly when its nullifier is revealed on the best chain at or below T (Theorem 6.14, item (ii)). Clause (b) is clause (2) by Proposition 9.13, with condition (d) of Definition 9.12 in place of the expiry height where that is unknown; clause (c) is clause (3); clauses (e) and (d) are the witness and depth clauses of confirmed-spendability. The spendable set is the input state of construction (“Transaction construction”, §11): it is reconstructed by synchronisation (§6, Theorem 6.14) and taken as given by fee computation and note selection.

Remark 9.18 (Spending before the nullifier set is complete).

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).