fix(server): prepare-then-commit mint to prevent state desync

[TaprootFreak]

Closes #89.

Problem

mint_handler advanced minting_meta.num_pubkeys, mutated the in-memory minting account, and persisted recipient state before attempting the on-chain inscription broadcast. When the broadcast failed (publisher empty, Esplora 5xx, WS timeout, etc.) the server's bookkeeping had already moved on, but the SMT/MMR never received the commitment — every subsequent mint and send for the same minting-account-pubkey-N then returned 422 with either:

• Unable to get merkle proofs for provided public key, or
• Unable to get mmr inclusion proof for the previous root

Once tripped, the only known recovery was a full DEV-state wipe.

Fix — prepare → broadcast → commit

1. Snapshot phase: under the minting_account guard, read N = num_pubkeys and derive (pubkey_N, pubkey_{N+1}, pubkey_{N-1}). Release.
2. Proof phase: clone the minting account and run prepare_mint (a new clone-based wrapper around the existing send_coins logic) against the clone — no mutation of self.accounts.
3. Broadcast phase: create_and_broadcast_inscription. On Err → 503, NO state advanced anywhere.
4. Commit phase (broadcast OK only): single sqlx::Transaction with an optimistic UPDATE: UPDATE minting_meta SET num_pubkeys = N+1 WHERE id = 1 AND num_pubkeys = N. On rows_affected() == 0 → 503 "Concurrent mint detected". After tx commit: re-acquire the lock, atomically swap the mutated minting snapshot into account_server via commit_mint(...), and apply receive_coin (additive) on each recipient — no import_account that would overwrite concurrent updates. Persist each recipient with an independent db::upsert_account (mirrors the broadcast_commit_and_deliver shape for /api/send). Return 200.

Startup invariant check

In server_runtime::start_rest_server, before binding the listener:

For i in 0..num_pubkeys, assert state.get_commitment_proof(derive_public_key(i)) is Ok. Refuse to start on first miss with a CRITICAL log line naming the recovery procedure (reset_state workflow).

To avoid a false-positive when a recent mint hasn't yet been ingested by the scanner, the check awaits a bounded scanner-settle window: up to SCANNER_INITIAL_SETTLE_TIMEOUT_MS (default 90 s, env-overridable) for the scanner to make at least one successful state.update call. The signal is an Arc<AtomicU64> incremented on every successful state.update from the scanner callback (main.rs). On timeout, the SMT check runs against the current state anyway — better a loud false-positive than a silent zombie.

On bootstrap failure, main.rs now calls std::process::exit(1) so the orchestrator crash-loops cleanly (matches the existing panic-hook semantics).

What's not changed

• commit_handler and broadcast_commit_and_deliver already do broadcast-first-then-receive_coin. Audited and confirmed. Documented as an invariant in code comments.
• send_handler has no on-chain broadcast — it returns a CoinProof that clients submit via /api/commit. Nothing to refactor.

Tests

• mint_broadcast_failure_does_not_advance_num_pubkeys — failed broadcast → num_pubkeys stays at Some(0).
• mint_broadcast_failure_does_not_mutate_minting_account — in-memory state unchanged after failed broadcast.
• mint_retry_after_broadcast_failure_succeeds — first call: dead Esplora → 503; second call: working Esplora → 200, num_pubkeys == 1, single inscription on mock.
• concurrent_mints_only_one_commits — deterministic: pre-seeded stale minting_meta row triggers the loser branch with 503 "Concurrent mint detected".
• startup_invariant_rejects_when_num_pubkeys_exceeds_smt — bootstraps with num_pubkeys = 5 + empty SMT, asserts start_rest_server errors with the CRITICAL message.
• Existing mint_broadcast_failure_returns_503 was updated with state-unchanged assertions it was previously missing.
• Existing mint_upsert_account_failure_logs_and_returns_ok was renamed/rewritten to mint_commit_tx_failure_returns_503 to reflect the new hard-fail semantics on commit-tx errors.

Companion change

DFXServer/server@6b0506c removes the orphan DEV_SKIP_BROADCAST_FAILURE=true env var from infrastructure/dfxdev/zkcoins/docker-compose.yaml and adds a reset_state runbook entry to the README. The env var was no longer read by the binary (since PR #73); this PR closes the desync class underneath, so the orphan line can finally go.

Test plan

• CI green (lint + heavy tests + coverage gate).
• After merge: DEV deploy → mint_roundtrip + send_commit_roundtrip against DEV pass cleanly. No retries on Unable to get merkle proofs or Unable to get mmr inclusion proof because the underlying desync can no longer happen.
• Trigger a deliberate broadcast failure (e.g. drain publisher wallet) → /api/mint returns 503 → subsequent /api/mint after refunding the publisher succeeds with num_pubkeys advanced by exactly one.