Wallet Guide The Zcash wallet layer: keys, transactions, and light-client synchronisation 10 Fees (ZIP 317)12 Partially created transactions (PCZT)

11 Transaction construction

This section states how a wallet turns payments into transactions. It defines the transaction plan and its balance equation; the pool in which each payment and each change output lies; transfers to TEX addresses and shielding transactions; input selection as a fixed point of the fee; change; the outgoing viewing key of every output; the assembly of Orchard-protocol bundles with dummy Actions in uniform order; and the authorisation of a built transaction, with the theorem that the result pays what the plan states. The input state is the spendable set of Definition 9.17; the fee is the conventional fee of §10.

11.1 The transaction plan

Definition 11.1 (Payment and payment request).

A payment is a transfer of funds implemented by a single output of a transaction: a triple $(a,v,m)$ of a recipient address $a$ (Definition 3.20), a value $v\in\mathbb{N}$ in zatoshi and an optional memo $m$ , a memo being admitted only when $a$ is memo-capable. A payment request is a finite map $R$ from indices to payments; it asks for one transaction that pays every payment in its range (ZIP 321, “Terminology”). ZIP 321 encodes payment requests as URIs (§14.1); the label and message parameters of that encoding are display data and enter no transaction.

Construction has two phases. Planning maps a payment request and the wallet state, its spendable notes (Definition 9.17) and its tip, to a plan exact to the zatoshi, and uses no spending key. Execution builds, proves and authorises the transactions of the plan and records them (§13); submission is a separate act. Every choice of inputs, fee and change is fixed in the plan before a spending key is used. No ZIP defines plans: the two-phase structure is designed but unspecified (Definition 1.1).

Definition 11.2 (Transaction plan).

A transaction plan is a non-empty sequence $P=(S_{1},\dots,S_{\ell})$ of steps. Each step describes one transaction by:

(i)

its target height $H$ (Definition 9.4), anchor height $A$ (Definition 9.5) and expiry height $N$ (Definition 9.8);
(ii)

its spending account, the account of the wallet to which every input of the step belongs;
(iii)

its inputs, partitioned by pool (transparent, Sapling, Orchard, Ironwood), each either a note of the spending account spendable at $H$ (Definition 9.17), a transparent UTXO of that account that meets its depth (§9.1), or a reference $(j,i)$ to output $i$ of an earlier step $S_{j}$ ;
(iv)

its payment outputs, each a payment of the request together with the pool assigned to it (§11.2);
(v)

its change outputs, each a value and a pool;
(vi)

its fee $f\in\mathbb{N}$ , computed under the conventional fee rule (Definition 10.2).

A transparent output of a step may be marked ephemeral: it pays a fresh transparent address of the wallet and exists only to be spent by a later step (§11.3). Each step satisfies the balance equation

\textstyle\sum_{\text{inputs}}v=\sum_{\text{payments}}v+\sum_{\text{change}}v+f,

the sums taken over all pools, ephemeral outputs counted among the payments of their step. In the built transaction $f$ is the value remaining in the transparent transaction value pool: the sum of the transparent inputs, minus the transparent outputs, plus every shielded balancing value (Ironwood Guide, §“The balancing value”, Definitions “Transparent transaction value pool” and “Balancing value”).

Clause (ii) restricts this section to steps funded by one account; ZIP 316 also admits transfers whose sending account is undetermined, a case that enters only the choice of outgoing viewing key (§11.6).

Definition 11.3 (Well-formed plan).

A plan $(S_{1},\dots,S_{\ell})$ is well formed if and only if

(i)

every reference $(j,i)$ among the inputs of step $S_{k}$ has $j<k$ ;
(ii)

every output of an earlier step that a step spends is ephemeral; no step spends a change output of an earlier step;
(iii)

no output, of the wallet or of a step, is spent twice within the plan;
(iv)

every ephemeral output of a step is spent by exactly one later step.

Proposition 11.4 (Chaining through transparent outputs).

Let step $S_{k}$ of a plan spend output $i$ of an earlier step $S_{j}$ , and let $t_{j}$ be the transaction built for $S_{j}$ .

(a)

If the output is transparent, every field of the transaction of $S_{k}$ is computable once $t_{j}$ is built, before $t_{j}$ is mined.
(b)

If the output is a shielded note of non-zero value, the proof that covers its spend (its Sapling spend proof, or the proof of its Orchard-protocol bundle) is not computable before $t_{j}$ is mined.
(c)

If the output is an Orchard-protocol note and the transaction of $S_{k}$ has version $6$ , its signature digest, and hence every spend-authorisation and binding signature of it, is computable once $t_{j}$ is built; only proving waits for the mining of $t_{j}$ .
(d)

If the output is a Sapling note, the signature digest of the transaction of $S_{k}$ is not computable before $t_{j}$ is mined.

A plan whose steps are all completed before any of them is submitted therefore passes value between steps only through transparent outputs, which Definition 11.3 (ii) and the ephemeral outputs of Definition 11.2 realise.

Proof.

(a) A transparent input names the outpoint $(\mathsf{txid}(t_{j}),i)$ and is signed over a digest that commits to the value and script of the spent coin (ZIP 244, “S.2: transparent_sig_digest”). The identifier is a function of the effecting data of $t_{j}$ (Ironwood Guide, §“Transaction digests and signatures”, Definition “Transaction identifier”), and value and script are fixed by $S_{j}$ ; none depends on the mining of $t_{j}$ .

(b) A proof for a spend of a note of non-zero value needs the note’s authentication path to the anchor (Ironwood Guide, §“Authentication paths”; condition A3 of the Action statement, which exempts only a consumed note of value $0$ ). The path is a function of the note’s position in its tree, which is fixed only when $t_{j}$ is mined (Definition 4.11).

(c) The version- $6$ signature digest commits to no anchor and to no proof (ZIP 229, “Anchor commitment (version 6)”; Ironwood Guide, §“Transaction digests and signatures”, Definition “Authorising-data digest; effecting and authorising data” and Definition “Signature digest”). The effecting data of an Orchard-protocol spend are computable before mining: its nullifier is $\mathsf{DeriveNullifier}_{\mathsf{nk}}(\rho,\psi,\mathsf{cm})$ , a function of note data and not of the position (Ironwood Guide, §“The nullifier”), and $\rho$ of the note is fixed by the Action of $t_{j}$ that creates it; the key $\mathsf{rk}$ and the commitment $\mathsf{cv}^{\mathsf{net}}$ depend on keys, values and fresh randomness. ZIP 374, “Anchors and pre-authorization”, states this workflow, and ZIP 318, “Note preparation transactions”, uses it.

(d) A Sapling nullifier is computed from $\rho=\mathsf{MixingPedersenHash}(\mathsf{cm},\mathsf{pos})$ , where $\mathsf{pos}$ is the note’s position (protocol specification, §“Computing $\rho$ values and Nullifiers”), and it is effecting data, committed by the signature digest (ZIP 244, “Signature Digest”).

For the final claim: by (b) and (d), a step that spends a shielded note of non-zero value of an earlier step cannot be completed before that step’s transaction is mined, so a plan completed as a unit passes value only through transparent outputs, which (a) admits; a zero-valued Orchard-protocol note carries no value. □

The partially created form of (c) is that of §12.5. Fee and change are fixed jointly: the change outputs enter the padded counts of Definition 10.6 and hence the conventional fee, and the fee determines the change value; §11.5 resolves the dependence.

Execution is not deterministic. The note seeds $\mathsf{rseed}$ , hence $\mathsf{esk}$ , $\psi$ and $\mathsf{rcm}$ , the value-commitment trapdoors $\mathsf{rcv}$ , the randomisers $\alpha$ , the proofs and the permutations of §11.7 are drawn fresh (Ironwood Guide, §“Construction of a transaction”), so one plan executed twice yields transactions with different effecting data and different transaction identifiers. A plan fixes values and shape, not the transaction identifier.

11.2 Payments to pools

Construction 11.5 (Output pool of a payment).

The output of a payment $(a,v,m)$ is determined by $a$ :

(i)

a transparent address yields a transparent output to it;
(ii)

a TEX address yields a transparent P2PKH output of the second transaction of a ZIP 320 transfer (§11.3);
(iii)

a Sapling address yields a Sapling output;
(iv)

a unified address yields an output to its receiver of the most preferred type in the Priority List of §3.3 that the sender supports, which ZIP 316 makes a MUST (ZIP 316, “Encoding of Unified Addresses”); an Orchard receiver is paid by an Ironwood-pool output;
(v)

an address with no receiver that the sender supports is refused, and so is a payment with a memo whose output is transparent.

Case (iv) is sound because both pools of the Orchard protocol share keys, addresses and receivers (Ironwood Guide, §“The Orchard protocol and its two pools”; ZIP 326, “Scanning for Ironwood-pool and Orchard-pool notes” and “Receiving funds into the Ironwood pool”).

Orchard-pool rules. Consensus admits no value into the Orchard pool: for every transaction, $\mathsf{valueBalanceOrchard}\geq 0$ ; and every Orchard-pool Action has cross-address transfers disabled, so the note it creates lies at the expanded receiver of the note it consumes (ZIP 258, “Consensus rules from NU6.3 activation”; Ironwood Guide, §“Chain state and pool rules”, rules (i) and (ii), and §“Bundle flags”). A wallet MUST NOT send funds to any external receiver, its own included, in the Orchard pool (ZIP 326, “Wallet key-generation restrictions”), and MUST NOT use its knowledge of the internal addresses of all its accounts to send funds from one account to an internal address of another (ZIP 326, “Scanning for Ironwood-pool and Orchard-pool notes”). A wallet that generates $\mathsf{use\_qsk}=\mathsf{true}$ keys MUST NOT send Orchard-pool funds to them at any point (ZIP 326, “Wallet key-generation restrictions”). This volume reads “external receiver” as every receiver that is not an internal-scope receiver (Construction 2.14) of an account of the wallet.

Change. A change output lies at an internal-scope address of the spending account (§11.5) in the Ironwood pool, in the Sapling pool, or, only as Proposition 11.6 allows, in the Orchard pool. The choice among these is wallet policy, designed but unspecified (Definition 1.1); a change output in a pool other than that of the inputs moves value between pools, and the moved amount is published in the balancing values.

Proposition 11.6 (Orchard-pool change).

In a transaction built by a wallet that follows Construction 11.5, every Orchard-pool output of non-zero value lies at the expanded receiver of the note consumed by its own Action, a real note or a fabricated zero-valued note, and that receiver is an internal-scope receiver of the spending account. Hence no payment output lies in the Orchard pool; non-zero change remains in the Orchard pool only at internal-scope receivers of the spending account, with total at most the value of the Orchard-pool notes spent; any other change lies in the Ironwood or the Sapling pool.

Proof.

Condition A10 of the Action statement with $\mathsf{enableCrossAddress}=0$ (Ironwood Guide, §“Bundle flags” and §“Chain state and pool rules”, rule (i)) places each Orchard-pool output at the expanded receiver of the note consumed in its Action. By the first rule of ZIP 326 under the reading of Construction 11.5, an output of non-zero value lies at an internal-scope receiver of an account of the wallet, and by the second that account is the spending account. A payment output is routed by cases (i) to (iv) of Construction 11.5, none of which yields an Orchard-pool output. Let $V_{\mathrm{in}}$ and $V_{\mathrm{out}}$ be the totals of the consumed and created Orchard-pool notes; the balancing value of the Orchard pool is $V_{\mathrm{in}}-V_{\mathrm{out}}\geq 0$ (rule (ii)), so the Orchard-pool change, a part of $V_{\mathrm{out}}$ , is at most $V_{\mathrm{in}}$ . Every other change output lies, by Construction 11.5, in the Ironwood or the Sapling pool. □

The following consequences are cited later rather than restated. Orchard-pool bundles are priced by Definition 10.6 with the requested count $s+o$ ; Orchard-pool fabricated outputs and spends are assembled in §11.7; and the canonical migration and note-preparation transactions of ZIP 318 are the exceptions to the padding floor stated in §10.2.

One Orchard-protocol spending key authorises spends in both Orchard-protocol pools. Ironwood-pool and Orchard-pool spends use the same full viewing key and the same spend authorising key $\mathsf{ask}$ , each pool’s bundle with its own note commitment tree, anchor and nullifier set (Ironwood Guide, §“Key capabilities and scope”, §“The Orchard protocol and its two pools” and §“Chain state and pool rules”); the two bundles of one transaction are built, proved and signed side by side.

Migration is specified. ZIP 2005 states that wallets SHOULD move all funds they control, transparent, Sprout and Sapling funds included, into recoverable Ironwood-pool notes as soon as practically possible, and that other wallets are REQUIRED to be able to receive them (ZIP 2005, “Proactive movement of funds to recoverable notes”). ZIP 318 specifies a scheduled migration from the Orchard pool to the Ironwood pool; its scheduling rules and privacy analysis are cited, not restated (ZIP 318, “Specification” and “Privacy Implications”). Its block-count constants are stated for a $75$ -second block spacing; their treatment under the $25$ -second spacing of ZIP 218, which NU7 deploys (ZIP 259, “NU7 consensus changes”), is an open problem (Definition 1.1). The privacy of the choice of source pool is stated in §11.4.

11.3 TEX transfers and shielding transactions

Construction 11.7 (Transfer to a TEX address).

A sender paying one or more TEX addresses from shielded funds MUST create two transactions (ZIP 320, “Design considerations for Senders”), realised as two steps of one plan.

(1)

The first transaction $\mathit{tr}_{0}$ spends shielded notes only and pays, in place of the $n$ TEX payments of values $v_{1},\dots,v_{n}$ , one ephemeral transparent output of value

$v_{\mathsf{eph}}:=\textstyle\sum_{i=1}^{n}v_{i}+\mathit{fee}(\mathit{tr}_{1})$

to a fresh ephemeral transparent address of the wallet.
(2)

The second transaction $\mathit{tr}_{1}$ spends exactly that output and pays the $n$ TEX payments as P2PKH outputs (Crypto Guide, §“The transparent layer’s hashes”), with no memo and no change, so that its input equals its outputs plus its fee.

Here $\mathit{fee}(\mathit{tr}_{1})$ is the conventional fee of one P2PKH input priced at $150$ bytes (Proposition 10.5 (i), the ephemeral key being a compressed key of the wallet) and $n$ P2PKH outputs of $34$ bytes each:

\mathit{fee}(\mathit{tr}_{1})=5000\cdot\max\bigl{(}2,\,\max(\lceil 150/150% \rceil,\,\lceil 34n/34\rceil)\bigr{)}=5000\cdot\max(2,n)\text{ zatoshi},

which is $10{,}000$ zatoshi for $n=1$ and $n=2$ and $15{,}000$ zatoshi for $n=3$ . A single transaction that pays a TEX address and spends shielded inputs is refused: a sender to a TEX address MUST spend only transparent (P2SH or P2PKH) UTXOs in that transaction, and SHOULD pay only transparent outputs in it (ZIP 320, “Specification”). ZIP 320 does not require that those UTXOs come from a single transparent address.

The plan of Construction 11.7 is well formed (Definition 11.3): its one reference points from $\mathit{tr}_{1}$ to the ephemeral output of $\mathit{tr}_{0}$ , which is spent exactly once. By Proposition 11.4 (a) both transactions are completed before either is mined, and ZIP 315 exempts the ephemeral UTXO from the confirmation floor (§9.1).

Ephemeral addresses are specified. A wallet based on ZIP 32 SHOULD choose ephemeral addresses so that their private keys are recoverable from the seed, SHOULD NOT choose them so that they can be linked between transactions without the seed or the relevant transparent viewing keys, and so SHOULD avoid collisions with the addresses of earlier outputs, change outputs included; a wallet MUST recognise, and be able to spend, funds that a recipient returns to an ephemeral address (ZIP 320, “Design considerations for Senders”). An ephemeral address reserved for a construction that fails is not reused, since reuse would link the two transactions; this rule is designed but unspecified (Definition 1.1).

Construction 11.8 (Shielding transaction).

A shielding transaction is the transaction of a one-step plan with an empty payment request. It spends transparent UTXOs of the spending account and pays their total, less the conventional fee, to change outputs at an internal-scope shielded receiver of that account (Construction 2.14), with no other recipient and no transparent output. Its outputs lie in the Ironwood pool, since no value enters the Orchard pool (Construction 11.5) and ZIP 2005 asks for recoverable Ironwood-pool notes (ZIP 2005, “Proactive movement of funds to recoverable notes”); its balancing value in that pool is negative. Its UTXOs may be spent with zero confirmations (§9.1). The value threshold at which a wallet shields is wallet policy, designed but unspecified (Definition 1.1).

Shielding rules are specified. A wallet that receives transparent funds SHOULD auto-shield them by default; it SHOULD NOT auto-shield from several transparent addresses in one transaction, and SHOULD NOT use opportunistic shielding, the shielding of received transparent funds within a user-initiated transaction, which would show its recipients the link between the transparent addresses and the payment (ZIP 315, “Long-term storage of funds”). Users MUST be able to disable auto-shielding (ZIP 315, “Auto-shielding”). Spent transparent UTXOs SHOULD be sent only to an internal shielded receiver of the wallet, except the ephemeral outputs of a ZIP 320 transfer (ZIP 315, “Linkability of transactions or addresses”).

Transparent inputs are public, so a transaction that spends UTXOs of different transparent receivers links those receivers. ZIP 315 states that UTXOs received on different transparent receivers SHOULD NOT be shielded in one transaction, and that shielding several UTXOs of one address together leaks nothing further (ZIP 315, “Linkability of transactions or addresses”). The same holds for ephemeral addresses, so a transaction spends the ephemeral output of at most one ZIP 320 transfer.

11.4 Input selection

Definition 11.9 (Covering selection).

Fix a step with payments of total $\mathit{out}$ , target height $H$ , anchor height $A$ and a number $k$ of change outputs (§11.5 fixes $k$ ). Let $U$ be the finite set of inputs of the spending account that Definition 11.2 (iii) admits at $(H,A)$ , each $u\in U$ with value $v(u)$ , and let $\mathcal{S}\subseteq 2^{U}$ be the family of admissible selections, those that meet the pool rules stated at the end of this subsection. For $I\in\mathcal{S}$ let $\mathit{shape}(I)$ be the public counts of Definition 10.1 of the step funded by $I$ , with its payments and $k$ change outputs, after padding (Definition 10.6), and let $\mathit{fee}(I):=\mathit{conventional\_fee}(\mathit{shape}(I))$ (Definition 10.2). A selection $I\in\mathcal{S}$ is covering if and only if

\textstyle\sum_{u\in I}v(u)\geq\mathit{out}+\mathit{fee}(I).

Adding an input never lowers a count of Definition 10.1, so $\mathit{fee}$ is non-decreasing under inclusion, and a covering selection is a fixed point of the fee: its total must cover a fee that depends on it. A plan requires a covering selection for each step; any procedure that returns one conforms. The following construction is one such procedure.

Construction 11.10 (Fee escalation).

Set $I_{0}:=\emptyset$ and $t_{0}:=0$ . At round $k\geq 0$ :

(1)

compute the balance of the step on $I_{k}$ (§11.5 gives its exact form);
(2)

if $I_{k}$ is covering, return $I_{k}$ ;
(3)

otherwise let $r_{k}:=\mathit{out}+\mathit{fee}(I_{k})-t_{k}>0$ be the shortfall, and choose $I_{k+1}\in\mathcal{S}$ with total $t_{k+1}:=\sum_{u\in I_{k+1}}v(u)\geq t_{k}+r_{k}$ ; if no such $I_{k+1}$ exists, fail with insufficient funds.

The choice of $I_{k+1}$ among the admissible sets that step (3) allows is the wallet’s.

Proposition 11.11 (Termination of fee escalation).

Fee escalation terminates after finitely many rounds. On success the returned selection is covering, and the fee of the step is the conventional fee of its final padded shape. On failure at round $k$ , no admissible selection has total at least $\mathit{out}+\mathit{fee}(I_{k})$ . No bound on the number of rounds is claimed beyond this finiteness.

Proof.

A round that does not stop has $t_{k+1}\geq t_{k}+r_{k}>t_{k}$ , so the totals increase strictly. Every $t_{k}$ lies in the finite set $\{\sum_{u\in I}v(u):I\in\mathcal{S}\}\cup\{0\}$ , which admits no infinite strictly increasing sequence. On success the returned $I_{k}$ is covering by step (2), and its fee is $\mathit{fee}(I_{k})$ , the conventional fee of $\mathit{shape}(I_{k})$ by Definition 11.9. On failure, step (3) found no admissible set of total at least $t_{k}+r_{k}=\mathit{out}+\mathit{fee}(I_{k})$ . □

A failure does not show that no covering selection exists: an admissible set $J$ with $\mathit{fee}(J)<\mathit{fee}(I_{k})$ and total in $[\mathit{out}+\mathit{fee}(J),\mathit{out}+\mathit{fee}(I_{k}))$ covers. Fee escalation is therefore sound, returning only covering selections, and complete only for choice rules that exclude this case.

Definition 11.12 (Uneconomic input).

An input $u$ is uneconomic if and only if $v(u)<\mathit{marginal\_fee}$ , where $\mathit{marginal\_fee}=5000$ zatoshi (Definition 10.2). The strict inequality is ZIP 317’s wording, “below the marginal fee” (ZIP 317, “Requirements” and “Rationale for the chosen parameters”).

Lemma 11.13 (Cost of an additional input).

Let $L$ be the number of logical actions of a step (Definition 10.1) and $L^{\prime}$ that after adding one input.

(i)

A P2PKH input priced at $150$ bytes gives $L^{\prime}-L\in\{0,1\}$ .
(ii)

A shielded spend added to a non-empty bundle with $s$ real spends and $o$ real outputs, $s+o\geq 1$ , gives $L^{\prime}-L\in\{0,1\}$ , and leaves the bundle’s padded count unchanged if and only if $s+1\leq\max(o,2)$ in an Orchard-protocol bundle with cross-address transfers enabled, $s+o=1$ in an Orchard-pool bundle, and $s+1\leq\max(o,2)$ in a Sapling bundle.
(iii)

A shielded spend that opens an empty bundle gives $L^{\prime}-L=2$ , the padded count going from $0$ to $2$ for every kind of bundle.
(iv)

The fee rises by $\mathit{marginal\_fee}\cdot(\max(2,L^{\prime})-\max(2,L))\leq\mathit{marginal% \_fee}\cdot(L^{\prime}-L)$ , and not at all while $L^{\prime}\leq\mathit{grace\_actions}=2$ .

Hence an uneconomic input of positive value adds positive net value to the step if and only if $\max(2,L^{\prime})=\max(2,L)$ : when padding absorbs its spend, or while the step stays within the grace window.

Proof.

(i) For every $x\in\mathbb{N}$ , $\lceil(x+150)/150\rceil=\lceil x/150\rceil+1$ ; the transparent contribution is the maximum of this term and the unchanged output term, so it rises by $0$ or $1$ .

(ii) and (iii). By Definition 10.6 the contribution of a non-empty bundle is $\max(\max(s,o),2)$ with cross-address transfers enabled, $\max(s+o,2)$ in an Orchard-pool bundle, and $\max(s,\max(o,2))$ for Sapling, whose outputs are padded to $\max(o,2)$ ; an empty bundle contributes $0$ . Each non-empty form is $\max(x,c)$ with $c\geq 2$ and a count $x$ that rises by exactly one, so it rises by $0$ or $1$ , and by $0$ if and only if $x+1\leq c$ : that is $s+1\leq\max(o,2)$ in the first and third forms, and $s+o+1\leq 2$ , which with $s+o\geq 1$ is $s+o=1$ , in the second. A single spend in an empty bundle gives $\max(1,2)=2$ with cross-address transfers enabled, $\max(1+0,2)=2$ in the Orchard pool and $\max(1,\max(0,2))=2$ for Sapling. No other contribution changes.

(iv) From Definition 10.2, since $n\mapsto\max(2,n)$ is non-decreasing and rises by at most the rise of $n$ . For the final claim: if $\max(2,L^{\prime})=\max(2,L)$ the fee is unchanged and the input adds $v(u)>0$ ; otherwise the fee rises by at least $\mathit{marginal\_fee}>v(u)$ .

The instances $(s,o,\text{rise of the padded count})$ are, with cross-address transfers enabled and for Sapling, $(0,1,0)$ , $(1,1,0)$ , $(1,2,0)$ and $(2,2,1)$ ; in an Orchard-pool bundle $(0,1,0)$ , $(1,1,1)$ , $(1,2,1)$ and $(2,2,1)$ ; and $(0,0,2)$ for the empty bundle of every kind. □

ZIP 315 states that automatic shielding and automatic or opportunistic migration SHOULD NOT be applied to inputs whose cost of shielding or migrating exceeds their economic value (ZIP 315, “Auto-shielding”); under the conventional fee, Lemma 11.13 decides which inputs these are.

The choice of source pool is constrained by privacy. Value that crosses pools is published in the balancing values (Ironwood Guide, §“The balancing value”, Remark “Disclosure by the balancing value”), so selecting inputs in the pool of the payment outputs keeps the amount private, and ZIP 315 states the aim of minimising pool crossing (ZIP 315, “Linkability of transactions or addresses”). Wallets MUST NOT automatically combine funds across pools to satisfy a transfer, since that could reveal the total the user holds in a pool (ZIP 315, “Information leakage for transfers between pools”). One policy serving these rules is designed but unspecified (Definition 1.1): order the shielded pools with the pool of the outputs first, then the other Orchard-protocol pool, then Sapling, or, for Sapling outputs, Sapling, then Ironwood, then Orchard; remove the pools that the user’s policy forbids; and spend from the first pool whose notes alone cover the payment.

Transparent sources and recipients are specified. A wallet MUST NOT send funds to a transparent address unless all of the source funds come from shielded pools, and this SHOULD be a single shielded pool (ZIP 315, “Linkability of transactions or addresses”); the ZIP 320 transfer of Construction 11.7 meets this rule, its first transaction spending only shielded notes. A wallet SHOULD NOT spend funds from a transparent address in a transaction with an external recipient unless the user gives explicit consent for that transaction, and MAY restrict transfers further (ZIP 315, “Allowed transfers”). The admissible family $\mathcal{S}$ of Definition 11.9 consists of the selections that meet the rules of this and the preceding paragraph, those of §11.3, and the wallet’s policy.

11.5 Change

Construction 11.14 (Balance and change).

Change is the excess of a step’s inputs over its payments and fee, returned to the wallet in $k\geq 0$ outputs whose pool follows Construction 11.5. Let $\mathit{in}$ be the total of the inputs, over all pools and ephemeral inputs included, $\mathit{out}$ the total of the payment outputs, and $f_{k}$ the conventional fee of the padded shape with $k$ change outputs, which is non-decreasing in $k$ .

(1)

If $\mathit{in}<\mathit{out}+f_{0}$ , fail with shortfall $\mathit{out}+f_{0}-\mathit{in}$ , the requirement fed back to selection (Construction 11.10).
(2)

If $\mathit{in}=\mathit{out}+f_{0}$ , the step has no shielded input or output and no change memo is requested, set $k:=0$ and fee $f_{0}$ .
(3)

Otherwise let $k$ be the least number of change outputs, $1$ , or a larger number chosen by the wallet to split change across notes, a choice designed but unspecified (Definition 1.1), subject to $\mathit{in}\geq\mathit{out}+f_{k}$ . The change is $c:=\mathit{in}-\mathit{out}-f_{k}\geq 0$ , divided among the $k$ outputs, each carrying the change memo if one is requested. If $\mathit{out}+f_{0}\leq\mathit{in}<\mathit{out}+f_{1}$ , no $k\geq 1$ qualifies: the step fails with requirement $\mathit{out}+f_{1}-\mathit{in}$ , or, if $\mathit{in}>\mathit{out}+f_{0}$ , may instead set $k:=0$ and fold the positive remainder $\mathit{in}-\mathit{out}-f_{0}$ into the fee; the plan records which.

Balance invariant. Before building, the transparent, Sapling, Orchard and Ironwood balances of the step, each the value of the step’s inputs in that pool minus the value of its outputs in that pool, sum to the planned fee. A sum above the fee means that change was omitted; a sum below it, insufficient funds.

Change goes to an internal-scope address of the spending account (ZIP 32, “Orchard internal key derivation”; Construction 2.14; ZIP 316, “Deriving Internal Keys”), its diversifier index a wallet policy; non-zero change remains in the Orchard pool only at an internal-scope receiver of the spending account, the receiver of the note consumed in its Action (Proposition 11.6). A zero-valued fabricated output at the receiver of a spent note is not change.

The balance invariant is the balance equation of Definition 11.2 with every term moved to one side, summed pool by pool.

Proposition 11.15 (Zero-valued change).

Let a step have a shielded input or output, and let Construction 11.14 complete it with $k\geq 1$ change outputs, of total $0$ when $\mathit{in}=\mathit{out}+f_{k}$ .

(i)

The public counts of the step are the same function of its inputs, payments and $k$ whether the change is $0$ or positive.
(ii)

If change were instead omitted at exact balance, the counts at exact balance would differ from those with change exactly when one more output of the change pool raises that pool’s padded count or opens a bundle (Definition 10.6). An observer who knows the payment outputs, such as a party that receives every payment, and sees the counts would then infer that the inputs sum exactly to the payments plus the fee.
(iii)

In the Ironwood pool, bundles with equal public leakage that differ only in whether the change is $0$ or positive are computationally indistinguishable.

The zero-valued output also carries a requested change memo. Where padding already absorbs the change output, as in the two-Action Orchard-pool bundle of ZIP 318, the omission of (ii) reveals nothing (ZIP 318, “Canonical migration transaction structure”).

Proof.

(i) and (ii) follow from Construction 11.14 and Definition 10.6: the counts depend on $k$ , which is at least $1$ whatever the value of $c$ , and omission replaces $k$ by $0$ at exact balance only. (iii) is Ironwood Guide, §“Privacy”, Theorem “Privacy of an Action”, under its preconditions (P1) to (P4) and its assumptions: Actions whose private inputs have equal public leakage are indistinguishable, and a created note’s value is a private input, not public leakage. No claim is made for Sapling outputs beyond (i). □

A zero-valued note needs no witness. Condition A3 of the Action statement, $v^{\mathsf{old}}\cdot(\mathit{root}-\mathit{rt})=0$ , checks the authentication path only of a consumed note of non-zero value (Ironwood Guide, §“The Action statement”), so a zero-valued change note can later be spent without tracking its path.

Only a step with no shielded input or output and no change memo omits change at exact balance. The second transaction $\mathit{tr}_{1}$ of Construction 11.7 is the instance, and a change memo is not carried there. A change note of value $v<\mathit{marginal\_fee}$ is an uneconomic input when it is later spent (Definition 11.12), and adds positive net value only where Lemma 11.13 gives no rise of the fee. The wallet’s policy for such change is designed but unspecified (Definition 1.1), constrained by the following proposition.

Proposition 11.16 (Fee uniformity).

The fee of a transaction is public, the value remaining in its transparent transaction value pool, and its conventional fee is a function of public fields (Definitions 10.1 and 10.2), so every observer computes both. A transaction whose fee differs from the conventional fee of its shape is distinguished from every transaction of that shape that pays the conventional fee. Folding a remainder into the fee (Construction 11.14, case (3)) produces exactly such a fee whenever the remainder is positive. The folding threshold is the wallet’s policy, designed but unspecified (Definition 1.1).

Proof.

The fee is the sum of the transparent input values and the balancing values, minus the transparent output values, each a public field (Ironwood Guide, §“The balancing value”); the transparent sizes and the shielded counts of Definition 10.1 are public fields. The predicate “the fee differs from the conventional fee of the shape” is therefore a function of the public data; it holds for a transaction with a folded remainder $\mathit{in}-\mathit{out}-f_{0}>0$ , whose fee exceeds $f_{0}$ , and fails for every transaction of the same shape that pays the conventional fee. ZIP 317 states that non-standard fees may reveal specific users or wallets (ZIP 317, “Security and Privacy considerations”). □

11.6 Outgoing viewing keys

Definition 11.17 (Outgoing viewing key of an output).

For a transfer, the sender determines:

(a)

the sending account: the account that the transfer names, if it names one; otherwise, if every fund used comes from addresses of one account, that account, a rule that ZIP 316 makes a SHOULD; otherwise the sending account is undetermined;
(b)

the preferred sending protocol, the most preferred receiver type (the Priority List of §3.3) among the funds used: Orchard if any Orchard-protocol note, of either pool, is spent, else Sapling, else transparent.

The outgoing viewing key of an output is, with the sending account determined, that account’s external or internal $\mathsf{ovk}$ of the preferred protocol at the account level, external for a payment and internal for a wallet-internal output such as change or a shielding output (SHOULD); with the sending account undetermined, the external or internal $\mathsf{ovk}$ of the full viewing key of one address of the preferred protocol from which funds are sent, for example the first (SHOULD) (ZIP 316, “Usage of Outgoing Viewing Keys”). The Orchard external $\mathsf{ovk}$ is that of the Ironwood Guide, Construction “Diversifier key and outgoing viewing key” in §“Viewing keys”, and the internal one that of Construction 2.14; the transparent pair is that of Construction 2.18, the two halves of $I_{\mathsf{ovk}}=\mathsf{PRFexpand}_{\mathsf{c}}([\mathtt{0xD0}]\,\|\,\mathsf{% ser}_{P}(\mathsf{pk}))$ ; the Sapling keys are those of ZIP 32, “Sapling internal key derivation”. The choice governs the outgoing ciphertext $C_{\mathsf{out}}$ of every payment and change output. Its construction, which also admits $\mathsf{ovk}=\bot$ with a uniformly random $\mathsf{ock}$ , is cited (Ironwood Guide, §“The outgoing ciphertext”, Construction “Outgoing ciphertext”; protocol specification, §“Sending Notes (Sapling)” and §“Sending Notes (Orchard)”).

For change the rule gives the internal $\mathsf{ovk}$ . The specification also permits no $\mathsf{ovk}$ : with $\mathsf{ovk}=\bot$ the sender draws $\mathsf{ock}$ and the outgoing plaintext uniformly, no viewing key recovers the outgoing plaintext of the change, and the wallet finds its change by trial decryption under the internal $\mathsf{ivk}$ (Ironwood Guide, §“Trial decryption and note acceptance”; protocol specification, §“Sending Notes (Orchard)”). Encrypting change with no $\mathsf{ovk}$ departs from the SHOULD of ZIP 316.

The holder of an account’s external $\mathsf{ovk}$ therefore recovers the recipient, value and memo of the account’s Ironwood-pool payment outputs (Ironwood Guide, §“The outgoing ciphertext”, Construction “Recovery with $\mathsf{ovk}$ ”), and those of its change only with the internal $\mathsf{ovk}$ .

11.7 Padding, dummies, and shuffling

Construction 11.18 (Assembly of an Orchard-protocol bundle).

Fix an Orchard-protocol bundle with $s$ real spends and $o$ real outputs, and let $n$ be its padded Action count (Definition 10.6), or $n=1$ for the Ironwood-pool bundle of a canonical migration transaction, or $n=16$ for the Orchard-pool bundle of a note-preparation transaction (§10.2). The wallet sets $\mathsf{enableSpends}=\mathsf{enableOutputs}=1$ , the flags that ZIP 315 notes depend under normal circumstances only on whether a transaction is a coinbase transaction (ZIP 315, “Kinds of information leakage”).

(A)

Cross-address transfers enabled, an Ironwood-pool bundle with $\mathsf{enableCrossAddress}=1$ , the normal case of ZIP 229 (ZIP 229, “enableCrossAddress polarity”), which the wallet uses for every Ironwood-pool bundle. Pad the list of real spends with $n-s$ dummy consumed notes and the list of real outputs with $n-o$ dummy created notes (Ironwood Guide, §“Actions, bundles, and dummy notes”, Definition “Dummy notes”), each at an independent fresh random address; draw independent uniform permutations $\sigma$ and $\tau$ of $\{1,\dots,n\}$ ; place spend $j$ in Action $\sigma(j)$ and output $j$ in Action $\tau(j)$ .
(B)
Orchard pool, cross-address transfers disabled (Construction 11.5). Form
1. (i)
  
  for each real spend, one Action whose output is a fabricated zero-valued note at the spent note’s address, with its $C_{\mathsf{enc}}$ filled with random bytes (MUST), since a real encryption would let a holder of that receiver’s $\mathsf{ivk}$ link the spend’s nullifier to the address (ZIP 326, “Fabricated same-address outputs and randomized note ciphertexts”);
2. (ii)
  
  for each real output, one Action whose spend is a fabricated zero-valued note at that output’s address, a real spend signed with the account’s $\mathsf{ask}$ for that receiver, carrying no dummy spending key (ZIP 374, “Fabricated same-address outputs (NU6.3)”);
3. (iii)
  
  $n-s-o$ fully dummy Actions, whose dummy spend and dummy output share one common fresh random address, the only Actions that carry a dummy spending key;
then draw a uniform permutation $\pi$ of $\{1,\dots,n\}$ and place the $j$ -th Action so formed at position $\pi(j)$ .

The second Action of the canonical Orchard-pool bundle of ZIP 318 is of kind (B)(iii) when that bundle carries no change, and of kind (B)(ii) when it does (ZIP 318, “Canonical migration transaction structure”). A dummy output at an address independent of its Action’s consumed note exists only in bundles with cross-address transfers enabled; in kind (B)(iii) the dummy output shares the fresh random address of its dummy spend. A dummy spend coexists with any anchor, since condition A3 of the Action statement checks no path for a zero-valued consumed note. Per Action, $\mathsf{rcv}$ , $\alpha$ and the created note’s $\mathsf{rseed}$ are drawn fresh, and $\rho$ of the created note is the Action’s $\mathsf{nf}^{\mathsf{old}}$ (Ironwood Guide, §“Construction of a transaction”). A Sapling bundle samples $\mathsf{rcv}$ and $\alpha$ per spend and $\mathsf{rcv}$ per output, pads its outputs as in Definition 10.6, and its binding signing key is the sum of the spends’ $\mathsf{rcv}$ minus the sum of the outputs’ (protocol specification, §“Balance and Binding Signature (Sapling)”). The builder keeps the permutations, which are not part of the transaction, so that later roles (§12) attach per-output data to the right Action.

Refer to caption — Figure 4: Assembly of Orchard-protocol bundles with $n=2$ Actions (Construction 11.18). (A) An Ironwood-pool bundle with one real spend and two real outputs: the padded spend list and the output list are permuted independently by $\sigma$ and $\tau$ , so any spend may pair with any output. (B) An Orchard-pool bundle with one real spend at receiver $X$ and one change output at an internal receiver $Y$ of the spending account: each real side is paired with a fabricated zero-valued side at its own receiver, the one beside the real spend with a random $C_{\mathsf{enc}}$ , and only the order of the Actions is permuted, by $\pi$ . Red marks real spends, green real outputs, blue fabricated sides and grey dummies.

Proposition 11.19 (Uniform order and pairing of Actions).

In a bundle with cross-address transfers enabled built by Construction 11.18, the position of each spend and the pairing of spends with outputs are uniform and independent of the order of the plan: the map from spend index to Action position is a uniform permutation, and the spend-to-output pairing is a uniform permutation independent of it. In an Orchard-pool bundle the order of the Actions is a uniform permutation independent of the order of the plan. Positions therefore carry no information about the plan beyond the Action count; for an Ironwood-pool bundle, the public data of the Actions reveal no more than their public leakage.

Proof.

With $\sigma$ and $\tau$ independent uniform permutations of $\{1,\dots,n\}$ applied to the padded spend and output lists, Action $i$ pairs spend $\sigma^{-1}(i)$ with output $\tau^{-1}(i)$ , so spend $j$ is paired with output $\pi(j)$ for $\pi:=\tau^{-1}\circ\sigma$ . The map $(\sigma,\tau)\mapsto(\sigma,\pi)$ is a bijection of pairs of permutations, since $\tau=\sigma\circ\pi^{-1}$ ; it maps the uniform distribution to the uniform distribution, so $\pi$ is uniform and independent of $\sigma$ . The plan’s order enters only as the indexing of the lists, which both permutations randomise. The Orchard-pool case is the single uniform permutation $\pi$ . The last clause is Ironwood Guide, §“Privacy”, Theorem “Privacy of an Action”, under its preconditions (P1) to (P4) and its assumptions, applied to the bundle as a whole. No indistinguishability is claimed between the kinds (B)(i), (B)(ii) and (B)(iii) of Orchard-pool Actions, whose bundles that theorem does not cover. □

11.8 Authorisation of a transaction

The transaction carries the consensus branch identifier in force at its target height $H$ (Ironwood Guide, §“The transaction format”). Transaction versions $5$ and $6$ are valid and version $4$ is not (ZIP 2003, “Specification”; ZIP 259, “Abstract”); a transaction with an Ironwood-pool component is of version $6$ . The lock time is specified: the field $\mathsf{nLockTime}$ is public and may distinguish a transaction if used, and SHOULD be zero (ZIP 315, “Kinds of information leakage”); the wallet sets it to $0$ , and ZIP 318 lists $\mathsf{lock\_time}=0$ among the SHOULDs of its canonical migration transaction structure (ZIP 318, “Canonical migration transaction structure”). The reason is the one proved for the fee in Proposition 11.16: a public field set otherwise than by every other wallet distinguishes the transaction. The expiry height is that of §9.3.

Construction 11.20 (Authorising a built transaction).

Let a transaction be built from one step by Construction 11.18, every field of its effecting data fixed.

(1)

Compute its signature digest $\mathsf{SigHash}$ over the effecting data (ZIP 244, “Signature Digest”, as amended by ZIP 229, “Anchor commitment (version 6)”, which omits the anchors from the version- $6$ digest; Ironwood Guide, §“Transaction digests and signatures”). Every spend-authorisation signature and every binding signature signs $\mathsf{SigHash}$ .
(2)

For each Orchard-protocol Action of either pool, with the Action’s randomiser $\alpha$ , set $\mathsf{rsk}:=\mathsf{ask}+\alpha$ and $\mathsf{spendAuthSig}:=\mathsf{Sign}_{\mathsf{rsk}}(\mathsf{SigHash})$ (Ironwood Guide, §“Randomised validating keys”). Every Action carries one: a fully dummy Action’s spend is signed with its own random key, and a fabricated zero-valued spend beside a real Orchard-pool output with the account’s $\mathsf{ask}$ , not with a dummy key. Each Sapling spend likewise signs $\mathsf{SigHash}$ under its randomised key (protocol specification, §“Spend Authorization Signature (Sapling and Orchard)”).
(3)

For each bundle, set $\mathsf{bsk}:=\sum\mathsf{rcv}\bmod p_{\mathsf{Vesta}}$ over its Actions, check it against $\mathsf{bvk}$ , and sign $\mathsf{SigHash}$ under $\mathsf{bsk}$ (Ironwood Guide, §“The binding signature”); the Sapling $\mathsf{bsk}$ is that of Construction 11.18.
(4)

Sign each transparent input under the key of its address, by the scheme of the Crypto Guide, §“The transparent layer’s schemes: ECDSA and BIP-340 over secp256k1”, over the signature digest of that input (ZIP 244, “S.2: transparent_sig_digest”).

Keys. One Orchard-protocol $\mathsf{ask}$ serves both scopes and both pools (Construction 2.14; ZIP 32, “Orchard internal key derivation”). One Sapling $\mathsf{ask}$ serves both scopes, the internal scope differing in $\mathsf{nsk}$ , which enters the proof and the nullifier, not the signature (ZIP 32, “Deriving a Sapling internal spending key”), so a Sapling spend is added under the scope of its note. Each transparent input needs the key of its own address.

Lemma 11.21 (Scope of the signature digest).

The signature digests of version- $5$ and version- $6$ transactions commit to the effecting data and, for transparent inputs, to the values and scripts of the coins spent (ZIP 244, “S.2: transparent_sig_digest”), excluding proofs and signatures, and the version- $6$ digest also excludes the anchors. Hence steps (2) to (4) of Construction 11.20 need no proof; proofs and signatures can be computed in either order; in version $6$ , signing can precede the choice of anchor; and the transaction identifier is unchanged by proofs, by signatures and, in version $6$ , by anchors.

Proof.

By the Ironwood Guide, §“Transaction digests and signatures”, Definition “Signature digest”, $\mathsf{SigHash}$ has the header and shielded children of $\mathsf{txid}$ and the transparent signature digest as its children, all computed over effecting data and, for the transparent signature digest, the values and scripts of the coins spent; proofs, signatures and transparent scripts are authorising data, under the authorising-data digest (Definition “Authorising-data digest; effecting and authorising data”). ZIP 229, “Anchor commitment (version 6)”, moves the anchors to the authorising data in version $6$ ; in version $5$ they are effecting data (ZIP 244, “Signature Digest”). A step of Construction 11.20 computes a signature over $\mathsf{SigHash}$ from keys and randomisers, and the binding key from the $\mathsf{rcv}$ values, none of which is a proof, so the order of proving and signing is free. The transaction identifier is a function of the effecting data alone (Definition “Transaction identifier”). The multi-party form of the lemma is that of §12.9. □

Theorem 11.22 (Payment integrity).

Let a well-formed plan (Definition 11.3) be executed by Construction 11.18 and Construction 11.20, with Orchard-protocol keys generated with $\mathsf{use\_qsk}=\mathsf{false}$ . In each resulting transaction:

(i)

each payment is paid by exactly one output, in the pool that Construction 11.5 assigns, to the routed receiver, of the payment’s value and with its memo, none for a transparent output;
(ii)

every other output is a change output of Construction 11.14, an ephemeral output of the step, or a zero-valued dummy or fabricated output;
(iii)

the fee equals the planned fee: the conventional fee of the final shape, or, where Construction 11.14 folds a remainder into it, that fee plus the remainder.

Moreover, for a version- $6$ transaction whose signing keys meet hypotheses (H) and (S) of Ironwood Guide, §“Transaction digests and signatures”, Proposition “Bundle binding”, and under the assumptions of that proposition and of its Theorem “Spend authority” (§“Authorisation of spends”), no other party produces, except with negligible probability, an accepted transaction that carries any of the transaction’s Orchard-protocol randomised validating keys $\mathsf{rk}$ with different effecting data. The theorem claims content, not inclusion: inclusion further requires that no spent nullifier be revealed first, that the anchor block remain on the best chain and that inclusion occur by the expiry height, none of which the wallet controls (§13).

Proof.

(i) and (ii). By Definition 11.2 each payment is one output of its step, placed by Construction 11.5, and the only other outputs of a step are its change and ephemeral outputs. Construction 11.18 adds only notes of value $0$ : dummy created notes, fabricated outputs and the outputs of fully dummy Actions. The padding therefore creates no output of non-zero value, and each real output keeps the receiver, value and memo that the plan gives it.

(iii) In the built transaction the fee is the value remaining in the transparent transaction value pool, the transparent inputs minus the transparent outputs plus the balancing value of each shielded pool, and each balancing value is the value consumed minus the value created in its pool. Since dummy and fabricated notes have value $0$ , the remaining value is the total of the step’s inputs minus the total of its payment, ephemeral and change outputs, which is the planned fee by the balance equation of Definition 11.2 and the balance invariant of Construction 11.14; the planned fee is $f_{k}$ , or $f_{0}$ plus the folded remainder.

Binding. Every signature of the transaction signs $\mathsf{SigHash}$ (Construction 11.20), which covers the effecting data (Lemma 11.21). By Ironwood Guide, §“Transaction digests and signatures”, Proposition “Bundle binding”, an accepted transaction that carries some $\mathsf{rk}_{i}$ of the transaction carries the same effecting data, except with negligible probability; Theorem “Spend authority” excludes a valid signature under a key of the wallet on a digest that the wallet did not sign. For transparent and Sapling signatures the commitment to the effecting data is that of ZIP 244; no lower volume proves the unforgeability of those schemes, and none is claimed here. □

The wallet records each of its shielded outputs from the data it built the output with: the address, the value, $\mathsf{rseed}$ and the memo, and, for an Orchard-protocol output, $\rho$ , the nullifier of the spend of its Action. For such an output,

\mathsf{esk}=\mathrm{ToScalar}\bigl{(}\mathsf{PRFexpand}_{\mathsf{rseed}}([% \mathtt{0x04}]\,\|\,\mathsf{I2LEOSP}_{256}(\rho))\bigr{)},

and the note plaintext follow without any viewing key (Ironwood Guide, §“Encryption to the recipient”, and §“The outgoing ciphertext”, Construction “Recovery with $\mathsf{ovk}$ ”). A fabricated zero-valued Orchard-pool output at a spent note’s receiver carries a random $C_{\mathsf{enc}}$ , which trial decryption under any $\mathsf{ivk}$ rejects except with negligible probability (Ironwood Guide, §“Encryption to the recipient”, Assumption “Confidentiality and integrity of ChaCha20-Poly1305”; ZIP 326, “Fabricated same-address outputs and randomized note ciphertexts”). Non-zero Orchard-pool change lies only at internal-scope receivers (Proposition 11.6), so scanning finds it under the internal $\mathsf{ivk}$ (Definition 6.4), and no external $\mathsf{ivk}$ is needed for it (ZIP 326, “Wallet key-generation restrictions”).