docs: use a pool of durable nonce accounts for withdrawals

[gregorydemay]

A withdrawal transaction that actually landed can still be reported as missing: getSignatureStatuses without searchTransactionHistory only searches the recent status cache of roughly 300 rooted slots, while both getSignatureStatuses with the flag and getTransaction search the node's local blockstore and an optional archive, whose retention is a provider choice rather than a protocol guarantee. Re-signing such a transaction with a fresh blockhash can pay the withdrawal out twice.

This PR extends the design document so that withdrawal transactions no longer rely on status queries for the resubmission decision. Withdrawals use a pool of durable nonce accounts that are set up offline and passed to the minter via init/upgrade arguments; deposit sweeps and consolidations keep using recent blockhashes. With at most one in-flight transaction per nonce account and at most one message signed per nonce value, reading the nonce account tells the minter definitively whether a withdrawal transaction landed: if the nonce is unchanged, the identical signed transaction is re-broadcast without re-signing; if it advanced, the transaction landed and is never submitted again.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🔵 Needs a closer look

Safety-critical nonce handling and outage recovery need further specification and specialist review.

Review effort: Balanced
Findings: 2

Open (2)

• Enforce slot ordering when reading reused nonce accounts · New
• Define recovery for unresolved outcomes occupying the nonce pool · New

What changed in this PR

Updates the minter design to use durable nonce pools for withdrawals, preventing duplicate payouts when transaction history is unavailable.

Changes:

• Defines nonce pool configuration, withdrawal submission, and recovery behavior.
• Updates monitoring flows, diagrams, cross-references, and RPC cost estimates.

File	Description
docs/​design.md	Documents durable-nonce withdrawals while retaining recent blockhashes for sweeps and consolidations.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The unresolved nonce-account lifecycle and funds-safety guarantees require specialist validation.

Review effort: Balanced
Findings: 3

Open (3)

• Unresolved pruned withdrawals permanently occupy nonce accounts · New
• Define recovery for unresolved outcomes occupying the nonce pool
• Enforce slot ordering when reading reused nonce accounts

[Copilot]

Copilot review overview

🔵 Needs a closer look

The irreversible-payment protocol and nonce-account lifecycle need domain-owner review.

Review effort: Balanced
Findings: 3

Open (3)

• Unresolved pruned withdrawals permanently occupy nonce accounts
• Define recovery for unresolved outcomes occupying the nonce pool
• Enforce slot ordering when reading reused nonce accounts

Previously missed (2)

In code that hasn't changed since last review

Unchanged finalized nonce does not prove a transaction never landed

docs/​design.md:447

An unchanged nonce in a finalized account read does not prove the transaction has never landed: it may already be processed or confirmed on an unfinalized fork. Here and in the “Nonce value unchanged” bullet in Section 3.2.3, say that no finalized nonce advance is visible rather than that the transaction has not landed. Rebroadcasting the identical signed transaction remains safe; the prescribed behavior need not change.

Manual-flow diagram references the wrong finalization section

docs/​design.md:523

Renumbering finalization to Section 3.2.3 leaves the manual-flow sequence diagram at line 334 pointing to Section 3.2.2, which now describes withdrawal submission. Change that note to Note over Minter: ⏱️ Finalization timer (Section 3.2.3).

[Copilot]

Copilot review overview

🔵 Needs a closer look

Safe recovery from failed withdrawal batches remains unresolved and warrants human review of the financial-safety design.

Review effort: Balanced
Findings: 4

Open (4)

• Atomic batch failure can burn unrelated withdrawals · New
• Unresolved pruned withdrawals permanently occupy nonce accounts
• Define recovery for unresolved outcomes occupying the nonce pool
• Enforce slot ordering when reading reused nonce accounts

[Copilot]

Copilot review overview

🟡 Changes recommended

Nonce reservation and retry policies need clarification to prevent concurrent reuse and unbounded recovery costs.

Review effort: Balanced
Findings: 2 · 1

Open (3)

• Reserve nonce accounts before asynchronous reads · New
• Atomic batch failure can burn unrelated withdrawals
• Bound retries for permanently unresolved transaction finalization · New

Resolved since last review (3)

• Unresolved pruned withdrawals permanently occupy nonce accounts
• Define recovery for unresolved outcomes occupying the nonce pool
• Enforce slot ordering when reading reused nonce accounts

[Copilot]

Copilot review overview

🔵 Needs a closer look

Nonce reuse and manual recovery rules need clarification to preserve the withdrawal inclusion guarantees.

Review effort: Balanced
Findings: 2 · 1

Open (3)

• Reserve nonce accounts before asynchronous reads
• Atomic batch failure can burn unrelated withdrawals
• Bound retries for permanently unresolved transaction finalization

Previously missed (2)

In code that hasn't changed since last review

Prevent stale nonce reuse after finalized withdrawal

docs/​design.md:470

The slot floor also needs to include status-based finalization. After reading nonce N at slot 100 and observing its withdrawal finalized at slot 200, a lagging account response at slot 150 still satisfies minContextSlot: 100. Reusing N produces a batch that cannot land; a later fresh read then wrongly classifies it as Landed. Persist the maximum of account-read and finalized-withdrawal slots before releasing the account, and require a nonce different from the last consumed value before signing another batch.

Prevent untracked nonce advances from falsely marking withdrawals landed

docs/​design.md:609

A separate manual nonce advance can consume the nonce without the withdrawal landing, invalidating the documented inclusion check. If that advance wins the race, the minter marks the original withdrawal Landed, but its transaction can never be fetched to resolve the burned request. Explicitly prohibit this recovery action under the current design, or define a tracked cancellation flow that distinguishes which transaction consumed the nonce before allowing it.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The withdrawal protocol has unresolved safety requirements and needs domain-owner review.

Review effort: Balanced
Findings: 1

Open (1)

• Require a non-empty initial account pool before accepting withdrawals · New

Resolved since last review (3)

• Reserve nonce accounts before asynchronous reads
• Atomic batch failure can burn unrelated withdrawals
• Bound retries for permanently unresolved transaction finalization

Previously missed (1)

In code that hasn't changed since last review

Persist finalized slots before releasing accounts to prevent nonce reuse

docs/​design.md:470

The slot floor misses finalization through getSignatureStatuses. If withdrawal A reads nonce N at slot 100 and finalizes at slot 110, a subsequent read at slot 105 still satisfies minContextSlot: 100. After the account is released, batch B can therefore sign the already-consumed nonce. B cannot execute, yet a later read falsely classifies it as Landed, leaving its withdrawals unpaid. Include finalized transaction slots in the persisted floor before releasing the account, and reject the previously consumed nonce when preparing a new batch.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The nonce lifecycle and its financial-safety guarantees require Solana-specific human review.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Require a non-empty initial account pool before accepting withdrawals
• Clarify getSignatureStatuses entry to avoid implying resubmission authorization · New

[Copilot]

Copilot review overview

🔵 Needs a closer look

The nonce recovery design governs irreversible payouts and requires human protocol and security review.

Review effort: Balanced
Findings: None

Resolved since last review (2)

• Require a non-empty initial account pool before accepting withdrawals
• Clarify getSignatureStatuses entry to avoid implying resubmission authorization

Previously missed (1)

In code that hasn't changed since last review

Include withdrawal burn indices in CreatedTransaction

docs/​design.md:518

Include the batch's withdrawal burn indices in CreatedTransaction. The listed Solana message and nonce fields do not identify the ledger requests, especially when multiple requests have identical destinations and amounts. Recovery after an upgrade between creation and submission needs that association to keep those requests reserved and update their statuses. The existing SubmittedTransaction event preserves it through TransactionPurpose::WithdrawSol { burn_indices } in minter/src/state/event.rs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The payout safety model depends on nonce history, Solana finality, and operator setup assumptions that need human validation.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Do not drop sweeps with missing status

[Copilot]

Copilot review overview

🔵 Needs a closer look

The withdrawal safety guarantees and nonce-recovery protocol need final human security review.

Review effort: Balanced
Findings: 1

Open (1)

• Avoid immediate retries when stale reads create no transactions · New

Previously missed (1)

In code that hasn't changed since last review

Treat unchanged nonce as inconclusive, not proof of non-inclusion

docs/​design.md:470

An equal nonce does not prove that the transaction has not landed: a lagging provider can return the pre-advance value even after finalization, and a finalized read also does not rule out inclusion on an unfinalized fork. Describe equality as “no advance observed,” with the outcome still unknown. Rebroadcasting the identical signed transaction remains safe; only a never-seen value proves a finalized advance under the stated invariants, at which point rebroadcasting stops. Apply this distinction consistently here, in the unchanged-nonce bullet at line 580, and in the endpoint summary at line 69.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The design governs irreversible payouts and needs human verification of its nonce, finality, and recovery assumptions.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Avoid immediate retries when stale reads create no transactions