wikideck/docs/custody-sale-rehearsal.md

Signed sale → PostgreSQL accounting rehearsal

Status: disposable, synthetic evidence only; no live settlement or consensus activation. Evidence: 2026-10-20. Related: sale-lock candidate, financial reconciliation, production plan.

What is integrated

The replay bridge validates trader-signed candidate terms against an actual sandbox purchase reservation. The PostgreSQL custody implementation can consume this evidence and atomically resolve its reserved balance. This exercises the real restricted runtime role, financial writer lock, journals, balance projection, listing/order/outbox updates and business audit—not an in-memory imitation of SQL accounting.

observeSaleRehearsal() is callable only on an instance explicitly opened with disposableSaleRehearsal: true, with WIKIDECK_PG_DISPOSABLE_TEST=1, a configured database named custody_test, and a matching actual connected database name. There is no HTTP route, production environment enable switch, host signer, Monero adapter or public checkout integration. These guards prevent accidental use; a database name/environment flag does not independently prove infrastructure isolation. The supplied test Compose deployment is disposable/internal/tmpfs, and must never contain funds or valuable assets.

The evidence supplies one synthetic seller-owned NFT seed and up to 128 candidate blocks, each containing at most 64 sale transactions. Replay uses the existing candidate state machine, signatures and depth rules. JSON traversal has collection/depth/node limits and a 256 KiB evidence ceiling. Seed, policy, host identity, signed windows and exact economics are bound on the first successful observation. Changing that binding is rejected; a different block history under the same binding can be observed to test reorg handling.

This seed is caller-supplied, not discovered in the live node. Blocks have no RandomX proof, parent hashes, fork choice, issuance verification, peer validation or canonical event provenance. Signed terms authorize the simulated transitions; signatures do not prove the chain is canonical or that real Monero backs the reservation.

Exact authorization and financial behavior

• Both seller and buyer sign exact order/custodian/card/sequence, trading identities, host authority, candidate policy/domain, gross XMR amount, fee policy, recipient and admission/expiry heights. Existing sandbox reservation signatures alone are not candidate sale authorization.
• The signed hosting rate must equal the stored listing rate, even where two rates round to identical commissions on a tiny sale. The allocation and host recipient must match the reserved order/listing. All amounts remain canonical atomic-unit strings and bigint; there is no float or USD conversion.
• Optional hosting recipient terms use a tagged signature extension. Omission retains the earlier candidate message bytes. New drafts preserve the order's snapshotted recipient; changing current host policy does not redirect revenue. The candidate only checks address shape; actual custody policy/business audits additionally check Monero network and checksum.
• The reservation commitment binds the order's exact buyer/seller, card/sequence, gross and split amounts, author and hosting recipient, custodian and rehearsal binding. Completion must contain that commitment and the bound host's valid signature. There is no private key or automatic signature generation in the accounting implementation.
• Before maturity, gross remains in the buyer's reserved account. Once authorization has been bound, ordinary buyer cancel-reservation is denied, including through another ordinary custody instance. Synthetic mature terminal/non-admission evidence is required instead.
• Mature completion debits reserved gross and credits the seller's available balance, fixed author liability and snapshotted hosting revenue in one balanced transaction. Zero commission legs are omitted, not rounded up; a one-atomic sale still credits one atomic unit to the seller.
• Mature cancellation/expiry or the safe never-admitted boundary debits the reservation and returns gross to the buyer. There is no seller/fee credit or Monero transfer on this branch.
• Deterministic journal IDs plus the shared database writer lock prevent duplicate terminal postings across pools, replay and restart. An identical outcome returns none rather than posting again. Failure while storing terminal evidence rolls the entire financial mutation back.

Evidence, audit and review

Three namespaced metadata records per observed order retain its binding, first signed observation, and terminal observation when resolved. Runtime has INSERT/SELECT but no UPDATE/DELETE privilege on these metadata records. Repeated observations do not create an unbounded transcript archive. Business audits replay signed retained evidence, check the exact listing rate and binding/state commitment, and compare terminal outcome with the stored order and financial lifecycle.

The existing sandbox mock-sale-settlement journal and fixture-complete/fixture:<state-root> outbox format are reused deliberately. They remain fixture evidence, not a new assertion of canonical delivery. No schema migration or production evidence format is implied. Existing imported SQLite fixture settlements remain supported without being relabeled as signed rehearsals.

A submitted history that conflicts with, removes or makes immature an already posted outcome triggers sale-rehearsal-outcome-reorg. Business changes roll back, and a redacted durable integrity incident commits while retaining the shared writer lock. All custody instances then reject new mutations; private reads and original signed receipts remain available. The original seller credit/refund stays recorded: no automatic compensation, reversal or second payout. Re-submitting the old mature history cannot clear the incident. Existing schema-owner incident review procedures are not a substitute for resolving chain risk; production resolution requires retained canonical evidence and approved loss policy.

This rehearsal is not a durable connect/disconnect observer. It retains first/terminal evidence and the redacted incident reason, not every submitted fork transcript. It cannot detect an intermediate disconnect that is never submitted, even if an outcome later reappears. The caller must retain conflicting evidence for investigation. Production must integrate a replay-safe canonical event inbox/cursor, history anchors, disconnect-before-reconnect handling and persistent per-order review. No monotonic canonical-height guarantee is claimed for this caller-driven seam.

Validation and remaining gates

TypeScript/Vite Docker build passed; 172 offline regressions and 22 PostgreSQL integration tests passed, zero failures/skips. Candidate tests cover signature compatibility/recipient tampering and candidate transition rules. PostgreSQL tests add:

• explicit instance/database consent and exact signed reservation matching;
• seed-binding changes, malformed/cyclic/oversized collections, and denial of ordinary cancellation after binding;
• immature completion hold, concurrent exactly-once seller/author/host credit, replay and reconnect;
• mature cancellation and never-admitted-lock refund boundaries;
• identical-rounded-allocation but different fee-rate rejection;
• one-atomic settlement and signed custom-recipient revenue across current-policy changes;
• conflicting outcome → durable cross-instance/restart hold without a second credit;
• injected terminal-evidence failure → complete rollback and safe retry; corrupted evidence → audit hold.

A first bounded-checkpoint implementation attempted metadata UPDATE and was rejected by the real runtime grants. It was corrected to retain insert-only first/terminal evidence; no privilege was widened. Test evidence is for this implementation boundary, not production approval.

M3 remains open. Next work is independently reviewed protocol/policy and explicit new-network activation design, then actual PoW/peer/index/undo integration and durable canonical observation tied to financially fenced host-signing intent. Monero deposit confirmation/unlock observation, treasury/signer separation, real withdrawal controls, coordinated recovery, capacity and legal/operational release gates remain separate. The active v6 chain still rejects every candidate sale transaction. Persistent local custody deployments were not switched or restarted by this rehearsal.