Wallet Guide The Zcash wallet layer: keys, transactions, and light-client synchronisation 12 Partially created transactions (PCZT)14 Payment requests (ZIP 321)

13 The transaction lifecycle

This section states what a wallet does with a transaction between its creation and a terminal state: the encoding it submits and the identifier by which it tracks the transaction; the rule that a transaction is recorded before it is released, with the completeness of the record that follows; submission and rebroadcast; the status observations that update the record; and the terminal states, re-sending and the consensus branch. A transaction is created when it is built, proved and authorised from one step of a plan (Definition 11.2; Constructions 11.18 and 11.20). The record is that of Definition 9.11.

13.1 Submission and the transaction identifier

The wallet serialises a created transaction in the encoding of its version: version $5$ (ZIP 225, “Transaction Format”) or version $6$ (ZIP 229, “Transaction Format”), the only versions in force; a transaction with Ironwood-pool Actions has version $6$ (Ironwood Guide, §“The transaction format”, Construction “Version-6 transaction”; protocol specification, §“Transaction Encoding and Consensus”). The argument of $\mathsf{Submit}$ (Definition 5.10) is this byte string. The encoding is cited, not restated.

The wallet tracks a transaction $t$ by its transaction identifier $\mathsf{txid}(t)$ : the root of the BLAKE2b-256 digest tree of ZIP 244 over the effecting data of $t$ ,

\mathsf{txid}(t)=\mathsf{h}\bigl{(}\texttt{ZcashTxHash\_}\,\|\,\beta,\ d_{% \mathsf{hdr}}\,\|\,d_{\mathsf{tr}}\,\|\,d_{\mathsf{Sap}}\,\|\,d_{\mathsf{Orc}}% \,\|\,d_{\mathsf{Irw}}\bigr{)},

where $\mathsf{h}(P,x)$ is BLAKE2b-256 of $x$ under the $16$ -byte personalisation $P$ , $\beta$ is the $4$ -byte little-endian consensus branch identifier, and the child $d_{\mathsf{Irw}}$ is absent in version $5$ (Ironwood Guide, §“Transaction digests and signatures”, Definition “Transaction identifier”, for version $6$ , and Remark “Version 5”; ZIP 244, “txid_digest”; ZIP 229, “Transaction Identifiers, Auth Digests, and Signature Digests”; protocol specification, §“Transaction Identifiers”). The header digest $d_{\mathsf{hdr}}$ hashes, under ZTxIdHeadersHash, the $4$ -byte little-endian encodings of $\mathsf{header}$ , $\mathsf{nVersionGroupId}$ , $\mathsf{nConsensusBranchId}$ , $\mathsf{lock\_time}$ and $\mathsf{nExpiryHeight}$ (ZIP 244, “T.1: header_digest”), so the expiry height $N$ of Definition 9.8 is effecting data. The wallet computes $\mathsf{txid}(t)$ from $t$ and needs no response of the server to know it.

Lemma 13.1 (Non-malleability of the identifier).

Let $t$ be a transaction of version $5$ or $6$ .

(i)

Replacing the authorising data of $t$ , namely its proofs, signatures and transparent scripts and, in version $6$ , its anchors ( $\mathsf{anchorSapling}$ , $\mathsf{anchorOrchard}$ and $\mathsf{anchorIronwood}$ , ZIP 229, “Anchor commitment (version 6)”; Ironwood Guide, §“Transaction digests and signatures”, Definition “Authorising-data digest; effecting and authorising data”), leaves $\mathsf{txid}(t)$ unchanged.
(ii)

Under the Ironwood Guide’s Assumption “Collision resistance of BLAKE2b” (§“Transaction digests and signatures”), no efficient algorithm outputs, except with negligible probability, two transactions with different effecting data and equal identifiers.
(iii)

Under the same assumption, a transaction built for one consensus branch and the same payment built for another have different identifiers, except with negligible probability.

Proof.

(i) Authorising data lie under the authorising-data digest and under no node of the tree whose root is $\mathsf{txid}$ (Ironwood Guide, §“Transaction digests and signatures”, Definition “Authorising-data digest; effecting and authorising data”). (ii) Each node of the tree hashes an injective encoding (fixed-size fields and length-prefixed scripts, concatenated in order) of effecting data or of the digests of its children (ZIP 244, “txid_digest”). If the effecting data differ, the inputs of some node differ. A node whose inputs differ either has equal digests, which is a collision, or passes different digests to its parent, whose inputs then differ; at the root, equal identifiers from different inputs are a collision. (iii) The branch identifier enters both the root personalisation $\texttt{ZcashTxHash\_}\,\|\,\beta$ and the header digest through $\mathsf{nConsensusBranchId}$ , so the two root pairs differ, and equal identifiers are a collision (Ironwood Guide, §“Transaction digests and signatures”, Remark “Consensus-branch binding”). □

By (i) and (ii), the identifier tracks a pending transaction from its creation on, before and after any re-signing or re-proving. The identifier of versions up to $4$ , the double SHA-256 of the encoding (protocol specification, §“Transaction Identifiers”), is malleable; it belongs to no version in force and is not used.

Construction 13.2 (Recording and submission).

The following rules are designed but unspecified (Definition 1.1).

(L1)

Recording before release. The wallet enters each transaction $t$ it creates into its transaction record (Definition 9.11), which locks the notes $t$ spends (Definition 9.12), in storage that survives restarts and rollbacks (Definition 7.23, item (v)), before it submits $t$ or releases its bytes to any other party. It never removes an entry of the record.
(L2)

Multi-step plans. For a plan of $\ell>1$ steps (Definitions 11.2 and 11.3), the wallet creates every step before it records any, records all $\ell$ transactions in one update of the record, and submits them after that update, in step order. A construction that fails at some step leaves no recorded, hence by (L1) no transmittable, prefix. Every step can be created before any is mined, since a well-formed plan chains steps only through transparent outputs (Proposition 11.4); the transfer to a TEX address of Construction 11.7 is the instance (ZIP 320, “Design considerations for Senders”).
(L3)

Submission. The wallet submits $t$ by $\mathsf{Submit}(\mathit{bytes})$ , whose response is $\mathsf{accepted}(\mathsf{txid})$ or $\mathsf{rejected}$ (Definition 5.10). Neither response changes the record. It submits at a tip $T$ that leaves a margin of blocks, a wallet parameter, before the last includable height $N$ (Definition 9.8), rather than at $T=N-1$ .
(L4)

Rebroadcast. While $t$ is pending and unmined (Definition 13.8), the wallet resubmits it at intervals whenever, at its tip $T$ , $N=0$ or $T<N$ (Lemma 9.9) and no transaction included in its view of the chain spends an input of $t$ . For $N=0$ this continues until $t$ is mined or an input of $t$ is spent by a mined transaction. The rule is motivated by ZIP 203, “Specification”, under which nodes drop a transaction from their mempools at its expiry.

The semantics of the two responses of $\mathsf{Submit}$ are those of the server’s node and are fixed by no ZIP: $\mathsf{accepted}$ means that the node admitted $t$ to its mempool, $\mathsf{rejected}$ that it refused it. Under clause (a) of Assumption 5.2, acceptance implies neither propagation to other nodes nor inclusion in a block, since relay policy is local to each node and may refuse a transaction that consensus still admits in the next block (Lemma 9.9); and rejection does not imply that $t$ is invalid. Rule (L3) keeps a margin for this reason. Each submission is an observation of the server (Proposition 8.21).

Proposition 13.3 (Completeness of the transaction record).

Let the wallet follow rule (L1), and let no party other than the wallet hold the bytes of a created transaction $t$ before the wallet submits them. Then, if a block of any chain includes a transaction with the effecting data of $t$ , the record contains $t$ , and the included transaction has identifier $\mathsf{txid}(t)$ , except with negligible probability. The converse fails: a recorded transaction that the network never received is stale, not lost, and, for $N\neq 0$ , reaches the terminal state expired unmined of Definition 13.8; for $N=0$ it stays pending by item (c) until the end of its consensus branch is known, and then reaches expired unmined with the bound $N^{*}$ (“Consensus-branch bound” below).

Proof.

A block includes a transaction only if the party that assembled the block held its bytes. The first party other than the wallet to hold bytes of $t$ received them by the wallet’s submission, by hypothesis; by (L1) the wallet recorded $t$ before that event, and the entry survives restarts and rollbacks and is never removed. A valid transaction with the effecting data of $t$ carries, for each spend of $t$ other than a dummy, a signature under a key of the wallet on the signature digest those data fix; except with negligible probability no party obtains such a signature except from bytes the wallet released (Ironwood Guide, §“RedPallas unforgeability”, Proposition “Unforgeability under re-randomisation”, for Orchard-protocol spends; for transparent and Sapling spends the unforgeability of those schemes is assumed, as in §11.8, where no lower volume proves it). Bytes derived from those of $t$ by another party with the effecting data of $t$ differ from $t$ at most in authorising data, so the included transaction has identifier $\mathsf{txid}(t)$ by part (i) of the lemma above. The converse fails because recording does not imply delivery. □

Where a partially created transaction is extracted by another party (“Spend finalisation and extraction”, §12.10), that party holds the bytes of $t$ before any submission, and the hypothesis is arranged differently: the wallet records $\mathsf{txid}(t)$ , $N$ and the inputs of $t$ , locking them, before it releases the partially created transaction to any party that may extract it, and at a point where the effecting data of $t$ are final. After IO finalisation (Construction 12.14) of a partially created transaction with shielded spends or outputs, or, for one that is transparent-only, once signatures without $\mathsf{SIGHASH\_ANYONECANPAY}$ and without $\mathsf{SIGHASH\_NONE}$ have cleared bits $0$ and $1$ of $\mathsf{tx\_modifiable}$ (ZIP 374, “Global”), the inputs and outputs are final, the lock time is determined by Definition 12.24, and the proofs and signatures still to be added are authorising data; by part (i) of the lemma the extracted transaction then has the recorded identifier, and the proof above applies with release in place of submission. The entry acquires the encoding of $t$ when the wallet obtains it.

Remark 13.4 (Retained data).

From creation until it is mined, $t$ exists only in the wallet’s record, in remote mempools and, for an extracted partially created transaction, at the extracting party. Once the wallet holds the encoding of $t$ (Definition 9.11, item (i)) the record keeps it, and rule (L4) needs it; before that the wallet does not rebroadcast $t$ . It may hold data that the chain never will: a transaction that ends expired and unmined lies on no chain that agrees with the server’s up to $N$ (Lemma 13.7), and its entry may be the only trace of it.

13.2 Status tracking and terminal states

Remark 13.5 (Scope of scanning).

Scanning detects a transaction only through a nullifier of the watched set $W$ (Definition 9.15) or an output accepted under the wallet’s scanning keys (Construction 6.8). A recorded transaction that spends no note of $W$ and has no such output, every fully transparent transaction among them, is invisible to scanning. Its fate is learnt only by queries $\mathsf{Status}(\mathsf{txid})$ (Definition 5.9), each of which puts its identifier into the view of the server (Proposition 8.18).

For a recorded transaction $t$ write $N$ for its expiry height, $h_{t}$ for its mined height ( $\bot$ while unmined), $h^{\mathrm{obs}}_{t}$ for its earliest observation height, and $u_{t}$ for the latest tip at which the server reported it unmined ( $\bot$ initially): items (ii), (iv), (v) and (vi) of Definition 9.11. A status observation $(s,T)$ is a response $s$ of $\mathsf{Status}(\mathsf{txid}(t))$ received while the wallet’s view of the chain has tip $T$ .

Construction 13.6 (Status transitions).

The record entry of $t$ changes only as follows.

(i)

On an observation $(s,T)$ with $s\in\{\mathsf{unknown},\mathsf{unmined}\}$ : $u_{t}:=T$ .
(ii)

On an observation $(\mathsf{mined}(h^{\prime}),T)$ : $h_{t}:=h^{\prime}$ , $h^{\mathrm{obs}}_{t}:=\min(h^{\mathrm{obs}}_{t},h^{\prime})$ and $u_{t}:=\bot$ .
(iii)

Scanning a block of height $h^{\prime}$ in which $t$ is wallet-relevant (Construction 6.8) has the effect of (ii).
(iv)

A rollback to $r$ (Definition 7.23) sets $h_{t}:=\bot$ if $h_{t}>r$ , and $u_{t}:=\min(u_{t},r)$ if $u_{t}\neq\bot$ , since a report at a tip above $r$ concerned blocks that the rollback discards.

Query termination. The wallet issues $\mathsf{Status}(\mathsf{txid}(t))$ for a pending transaction $t$ with $h_{t}=\bot$ : if $N\neq 0$ , until $u_{t}\geq N$ , that is, until $t$ is reported unmined at a tip of at least $N$ ; if $N=0$ , for as long as $t$ is pending and unmined. No rule stops at a first report of $\mathsf{unmined}$ or at a fixed depth after first observation. A rollback that lowers $u_{t}$ below $N$ , or sets $h_{t}:=\bot$ , resumes the queries. The transitions and the termination rule are designed but unspecified (Definition 1.1); the termination rule rests on the consensus rule of Definition 9.8 (ZIP 203, “Specification”). For an entry with $N_{t}$ unknown (Definition 9.11), the wallet obtains the encoding by $\mathsf{Tx}(\mathsf{txid})$ (Definition 5.10); until then it queries as for $N=0$ , does not rebroadcast, and its inputs are locked by condition (d) of Definition 9.12.

Lemma 13.7 (Expired unmined is final on its chain).

Assume clause (a) of Assumption 5.2. Let $t$ be a transaction created by the wallet, with expiry height $N\neq 0$ , and let $(s,T)$ be an observation with $s\in\{\mathsf{unknown},\mathsf{unmined}\}$ and $T\geq N$ , answered from a best chain $C$ of the server (Consensus Guide, §“Work, and the best chain”) whose blocks at heights at most $N$ are those of the wallet’s view. Then no chain whose blocks at heights at most $N$ are those of $C$ includes $t$ .

Proof.

The wallet’s view has tip $T\geq N$ , so $C$ has blocks at every height up to $N$ . By clause (a), $s$ is the status of $\mathsf{txid}(t)$ on $C$ (Definition 5.9): no block of $C$ contains $t$ , so no block of height at most $N$ of a chain that agrees with $C$ up to $N$ does. The transaction $t$ is not a coinbase transaction, and by Lemma 9.9 the expiry rule permits it in no block of height greater than $N$ (protocol specification, §“Transaction Consensus Rules”; ZIP 203, “Specification”). □

A reorganisation with fork point below $N$ reopens the question, since the new chain need not agree with $C$ up to $N$ . The wallet meets it as a continuity error (Definition 6.10), and the rollback of Construction 7.24 to some $r<N$ sets $u_{t}\leq r<N$ by transition (iv), which resumes the queries.

Let $B$ be the birthday of the wallet (Definition 6.2) and $\mathcal{H}$ its retained block boundaries (Definition 7.12). Write $r_{\min}$ for the least element of $\mathcal{H}\setminus\{B-1\}$ , the lowest rollback point of the rollback window, and $r_{\min}:=B-1$ when that set is empty.

Definition 13.8 (Terminal states).

A recorded transaction $t$ is pending from its recording until it reaches one of the following states.

(a)

Mined: $h_{t}\neq\bot$ and $h_{t}\leq r_{\min}$ , so that no rollback to a point of the window unmines $t$ . The state is terminal relative to the rollback window only, since consensus bounds no reorganisation depth (Remark 7.28); a deeper rollback, to $B-1$ or to a fetched chain state in steps (1) and (3) of Construction 7.24, returns $t$ to pending by transition (iv).
(b)

Expired unmined: $N\neq 0$ , $h_{t}=\bot$ and $u_{t}\geq N$ , which gives the conclusion of Lemma 13.7 when the server’s chain agrees with the wallet’s view up to $N$ ; a disagreement surfaces as a continuity error (Definition 6.10), whose rollback to $r<N$ returns $t$ to pending by transition (iv). Its inputs are released (Proposition 9.13, every later target height exceeding $N$ ), its entry is kept, and the user is notified.
(c)

For $N=0$ , a value chosen explicitly: $t$ remains pending until it is mined, rebroadcast by rule (L4), or, once the end of its consensus branch is known, until it reaches state (b) with the bound $N^{*}$ of that branch (“Consensus-branch bound” below). Its mining is detected by scanning through $W$ , from which a spend, $N=0$ included, removes a nullifier only once mined (Definition 9.15), or by continued status queries.

The states and their transitions are designed but unspecified (Definition 1.1). The notification is specified: the wallet should notify the user of expired transactions that must be re-sent, and user interfaces and services must never rely on zero-confirmation transactions (ZIP 203, “Wallet behavior and UI”).

Refer to caption — Figure 6: The states of a recorded transaction $t$ (Definition 13.8). Solid edges are transitions of the record: recording by rule (L1), which locks the inputs of $t$ ; submission, rebroadcast and reports $\mathsf{unmined}$ or $\mathsf{unknown}$ at a tip below $N$ , which leave $t$ pending; a report $\mathsf{mined}(h^{\prime})$ or the scan of a block containing $t$ , transitions (ii) and (iii); burial below the lowest rollback point $r_{\min}$ of the window; and, for $N\neq 0$ , a report of an unmined $t$ at a tip $T\geq N$ , after which Lemma 13.7 excludes $t$ from every chain that agrees with the server’s up to $N$ . Dashed red edges are rollbacks, transition (iv): below $h_{t}$ from either mined state, from the terminal one only by a rollback deeper than the window, and below $N$ from expired unmined. The green and amber states are terminal; a transaction with $N=0$ stays pending until mined, unless its consensus branch ends.

Remark 13.9 (Re-sending).

Re-sending an expired payment usually spends the same TXOs, and ZIP 315 lists which spends of given TXOs are repeated across transactions among the kinds of information leakage, the case arising when a previous transaction expired (ZIP 315, “Kinds of information leakage”): the repeated spends link the expired transaction to its replacement. Selecting other notes avoids that link, but the nullifiers that the expired transaction revealed still link it to any later transaction that spends those notes (ZIP 315, “Rationale for anchor selection”). A wallet that re-sends accepts one of the two links. ZIP 315, “Note selection”, records as a TODO, not as a rule, that such revealed nullifiers be spent in a note-management transaction; how to avoid both links is an open problem (Definition 1.1).

Consensus-branch bound. The consensus branch bounds a pending transaction as well as its expiry height does. An authorisation binds the consensus branch identifier through $\beta$ and $\mathsf{nConsensusBranchId}$ , which must equal the identifier of the branch under which $t$ is validated, so a transaction authorised for one branch is invalid under another whatever its expiry height (Ironwood Guide, §“Transaction digests and signatures”, Remark “Consensus-branch binding”, under its Assumption “Collision resistance of BLAKE2b”; ZIP 244, “txid_digest” and “T.1: header_digest”; ZIP 259, “Backward compatibility”; protocol specification, §“Transaction Consensus Rules”). A pending transaction built for a branch that ends at a height $X$ , with $N=0$ or $X\leq N$ , can be mined only below $X$ . Once $X$ is known, write $N^{*}:=X-1$ if $N=0$ or $N\geq X$ , and $N^{*}:=N$ otherwise. Rule (L4), the query termination of Construction “Status transitions”, state (b) of Definition 13.8 and conditions (b) and (c) of Definition 9.12 apply with $N^{*}$ in place of $N$ , and Lemma 13.7 holds with $N^{*}$ , by the branch binding in place of the expiry rule. Thus $t$ becomes expired unmined from a report at a tip of at least $N^{*}$ , and its inputs are released for the rebuild at every target height $H\geq X$ . This rule is designed but unspecified (Definition 1.1). To pay across the activation of the next branch, the wallet rebuilds and re-authorises the payment for the branch in force at its target height (Definition 9.4): a new transaction, with a new identifier by part (iii) of the lemma of §13.1 and a new entry of the record.