[ZIP 318] Orchard to Ironwood migration

[pacu]

Summary

This PR rewrites zips/draft-schell-ironwood-migration.md in place into a
single unified draft that integrates two earlier Orchard-to-Ironwood migration
drafts: the stateful, background-scheduled wallet flow from issue
#1315 ("Path A") and this branch's
stateless, canonical-quantization proposal. Editing the same file keeps the
review diff clean as an update/counter-proposal to the existing draft.

How the two designs were reconciled

• Normative mechanism = Path A. A two-phase flow: (1) mandatory
  note-splitting (wallet-internal send-to-self), then (2) scheduled, pre-signed,
  background-broadcast migration transactions de-correlated from app opens.
  Best-effort background scheduling (iOS BGTaskScheduler / Android WorkManager)
  with an on-launch fallback; synchronization decoupled in time from broadcast;
  Tor opt-in network-privacy step; detailed progress, notification, platform,
  and error-handling requirements.
• Canonical quantization folded in as the RECOMMENDED amount-selection
  heuristic inside Phase 2's split/scheduling algorithm. The split now produces
  canonical power-of-ten denominations rather than high-entropy random sizes,
  with the collision-privacy argument as rationale; "random arbitrary/partitioned
  amounts" are listed among rejected alternatives.
• Unified timing concept. Path A's ~6h anchor-height buckets and this branch's
  height ≡ 0 mod M boundaries/cohorts (~5.3h) are merged into a single
  network-wide bucket/boundary scheme forming cohorts that mix wallets. The
  shared previous-boundary anchor and the auth-data forward-looking
  recommendation are retained.
• State conflict resolved explicitly. The mechanism is stateful (persisted
  schedule + pre-signed transactions); statelessness and multi-device recovery are
  non-requirements (per [ZIP 318] Orchard to Ironwood Migration #1315). The stateless, chain-recoverable approach is
  preserved as a discussed rejected alternative with its tradeoff rationale,
  not silently dropped.

Where schell's analysis was preserved (non-normative)

The following are kept and clearly marked non-normative: Consensus context, Why
amounts leak, Threat model, Why value collision provides privacy, On multiplicity
and cohorts, On subset-sum, Accepted residual leaks, Whale handling, cohort size
vs. per-wallet multiplicity, Rationale for anchor selection, and the
Rejected-alternatives table (extended with Path A's rejected on-open / "Path B"
approach and the stateless alternative).

Path A's user-path and error-case material is included as non-normative
appendices in <details> blocks.

Preamble / conventions

Dual owners (Schell Carl Scivally, Pacu Gindre), Kris Nuttycombe credited,
Status: Draft, Category: Wallet, Discussions-To → issue #1315. BCP 14
boilerplate lists only the keywords actually used. Validated with multimarkdown:
definition lists render (10 <dt>), no unresolved footnote refs, every internal
(#anchor) link resolves to a generated id, and all headings are unique.

Refs #1315. This integrates that issue's "Path A" specification; it intentionally does not use a closing keyword, since the issue should remain open as the discussion thread and this PR targets a feature branch rather than the default branch.

AI disclosure

Claude Opus 4.8 was used to integrate and draft this unified document under
maintainer direction; the human contributor is the responsible author. The commit
carries the corresponding Co-Authored-By: trailer.

🤖 Generated with Claude Code

[linear]

COR-1376

[nuttycom]

nit: requirements don't use conformance language; these are bounds that we evaluate against to determine whether the specification below satisfies the requirements.

[pacu]

Good point — updated in 4d46580. The Requirements section no longer uses BCP 14 conformance keywords; the goals are now stated as plain declarative bounds ("The user can migrate…", "All Orchard-pool funds… are eventually transferred…", etc.), and the intro clarifies that these are the bounds the Specification is evaluated against, with conformance language reserved for the Specification section.

[dorianvp]

Should we include note consolidation here too? Is that a viable alternative?

If I have two Orchard notes of 4, 6 + N ZEC, where N is the amount I would need to pay as fee for a consolidation transaction, wouldn't it make more sense to just consolidate instead of splitting my notes into ten 1 ZEC notes?

[pacu]

The ideal is that you split your balance into transactions that are fee inclusive in a way that the balances can't be easily be deduces as belonging to the same wallet.

[nuttycom]

This can be renamed to zip-0318.md since the ZIP number has now been assigned.

[zookoatshieldedlabs]

Shielded Labs has written a threat model doc, visible to anyone who has this link: https://docs.google.com/document/d/1z4Aj7tO34RKk0SXZYkNXtswxdBXKbR_IJ_Xw5EJljkc . It includes a slightly different algorithm for selecting amounts and timings and anchors (Appendix A), but don't get hung up on that! The point of the document is that Appendix A is much less important for practical protection of real users than the other parts. :-) And, as described in that document, we currently think that it is not necessary for all or many wallet implementations and users to use compatible (indistinguishable on the blockchain) migration transactions, so that's another reason that Appendix A is less important than the rest of it.

Please review! If there are any major errors in this doc, please let us know ASAP. The main recommendation is to use Tor/Nym in specific ways, and we don't yet know how feasible this will be, and Zodl in particular is at the head of the class on that particular area, so please teach us.

[dannywillems]

Human review/implementation note (will be edited) - don't review:

Let's define $N$ the total balance to migrate. $N$ is decomposed into $l$ quantas, $n_l$, plus $l$ fees. $N = \sum_{i = 1}^l n_i + l * fees$.
The value $N$ is not necessarily the total balance of the wallet user. The total balance of the user can be higher for very large whales, and therefore the denomination/note splitting process will happen multiple times.

The user wallet has $M$ notes, note $M_i$, each of a balance $b_i$.
We want at the end to have a set $M'$ of notes containing, at least, the notes for the quanta $n_l$. The total balance of the notes in M' will be strictly smaller than the balance of the notes in $M$, as transactions incur fees. If we note $B(M)$ the sum of the values of each note in the set $M$, $Q$ the set of notes for the quanta, we have:

$B(M) = B(Q) + B(M' \setminus Q) + l * \text{fees}$

The problem of note preparation is actually a note consolidation problem, which is actually a system of multilinear equations, where variables are existing notes, quanta and changes, with "selectors" between rows to pick or not the previously created changes.
The problem is to create $l$ transactions (we have the constraints below that one note per quanta for the output), at least, from the notes $M_i$.
For each quantum $n_l$, the implementation must select $k$ notes from the set $M$ such that

$$\sum_{i = 1}^{k} b_{i, l} = n_l + \text{fee} + \text{change}_{l}$$

with $k$ depending on $l$.

The change will go back to a change address authorized by the Orchard pool after NU6.3. This change will become part of a set $M'$.
The consolidation problem will happen in layers, which we can see as a finite sequence of intermediary set $M_k$ which converges to the wanted set $M'$. Why a finite sequence and not directly a set $M'$? Because the change might be needed to create the next quanta.

If we develop the set of $l$ equations, we have the following:

$$\begin{align} \sum_{i = 1}^{k_{1}} b_{i, 1} & & = n_{1} + \text{fee} + c_{1} \\\ \sum_{i = 1}^{k_{2}} b_{i, 2} & + p_{1,1} c_{1} & = n_{2} + \text{fee} + c_{2} \\\ \sum_{i = 1}^{k_{3}} b_{i, 3} & + p_{1,2} c_{1} + p_{2, 1} c_{2} & = n_{3} + \text{fee} + c_{3} \\\ ... \\\ \sum_{i = 1}^{k_{l}} b_{i, l} & + \sum_{j = 1}^{l - 1} p_{j, t} c_{j} & = n_{l} + \text{fee} + c_{l} \\\ \end{align}$$

with $p_{i, t} = 0$ or $p_{i, t} = 1$ depending on using or not the change, and they must be only used once.
We can relax the system by having a set of system of equations (or layers) where all $p_{i, t}$ are equal $0$ within the same system, and $c_{i}$ are reported to the next system. In other words, in each layer, the equations are independent, and we want to minimize the set of layers as more layers mean we need to wait for more transaction confirmations/blocks.

[dannywillems]

Note: we're getting a DAG of notes.