wikideck/docs/production-plan.md

Production delivery plan

Status: active engineering plan; not launch or payment authorization. Updated 2026-10-21. The objective is a production service with explicit guarantees, measurable limits and accountable operations—not relabeling the existing testnet. Existing implementations are reusable groundwork; findings are closed only by reviewed implementation and evidence.

1. Decisions agreed with the operator

Topic	Decision / boundary
Initial MVP hosting	One operator (the project owner) in a US apartment, one x86 host and low initial volume. Assume a single failure domain, no on-call team and no HA. Confirm ISP terms, static/reachable ingress or CGNAT, power/network reliability, DDoS exposure and off-site recovery before choosing this over a small managed host. Do not imply independent-host security or availability.
Settlement architecture	Trustless and arbitrated routes were investigated; the operator has now authorized implementing the custodial pooled-balance market. ADR 002 tracks the first isolated sandbox accounting/UI increment and remaining treasury/consensus work. Implementation authorization is not live deposit, key access, consensus activation or launch authorization.
Host responsibility	Host responsibility, reserves and exposure caps are the selected policy direction. Exact liability, amounts and funding remain undecided. This is not authorization for custody and does not make settlement trustless or guarantee solvency. The author fee does not make the author a guarantor of independent markets.
First live market	Fixed-price sales first. Live auctions remain disabled until their funding, nonpayment and abuse controls pass a separate release gate. Existing sandbox auctions can remain clearly labeled.
Pricing	Native XMR prices, replacing the earlier USD-price decision. No economic listing minimum. Represent nonzero prices as integer atomic units: the smallest representable positive XMR amount is 10^-12 XMR, not an imposed USD/XMR minimum. Zero-price gifts should use free transfers unless separately designed.
Sending/network fees	Earlier model: buyer pays sending fee, seller pays disclosed per-sale disbursement costs. Custodial proposal: no per-purchase Monero transfer; depositor pays external sending, withdrawing beneficiary pays approved actual withdrawal fee, operator pays treasury movements. Author-fee withdrawal costs and overruns require explicit policy approval. No fee change is implemented.
Uneconomic small sales	No economic listing minimum. Custodial proposal allows tiny internal settlements and explicitly disclosed backed balance accumulation; withdrawal economics are separate. This changes the earlier per-sale payout-budget model and requires approval under ADR 002. Never silently discard a tiny liability or subsidize a fee.
Payment before sale finalization	A paid sale must not complete or be included as a completed ownership sale on Wikideck until the agreed XMR payment has satisfied its confirmation/unlock policy. Payment notification/mempool presence is insufficient.
Existing boundaries	No real processor access, credentials, invoices, transfers, genesis change, destructive migration or launch approval is authorized by this plan. Software licensing still requires an operator choice and publication.

Production settlement remains disabled. The public sandbox now prices new v3 listings/orders in native XMR atomic units, with mock-only confirmations, fees, refunds and payouts; legacy v2 USD records retain their original terms. No real XMR invoice, payable address, deposit, credit, withdrawal, or settlement path is enabled. Existing records are not silently reinterpreted as XMR.

Current design deliverable: custodial market design. Read the workstreams below with this update: pooled customer liabilities replace per-order incoming invoices and external sale payouts in the proposed architecture. Earlier trustless-first research gates are historical, not a prerequisite to investigating custody. Exact ledger, withdrawal, fee, custody/legal and host-attested NFT consensus rules still require approval and evidence; the existing mock domain cannot authorize real balance debits.

Monero observation and allocation groundwork: the disabled-by-default observer remains read-only. The separate address RPC capability verifies a mainnet primary address using get_address and validate_address and derives a wallet fingerprint; it does not claim to attest wallet type. Actual testing found get_wallet_info is unavailable as JSON-RPC in v0.18.5.4, and --rpc-login requires legacy HTTP Digest/MD5. The app does not implement Digest or send Basic credentials; the new mTLS gateway/transport is not deployed or wired. Its isolated certificate handshake, method allowlist and denial cases passed the rehearsal below; do not enable Wallet RPC until the intended deployment’s network isolation, certificate lifecycle and firewall controls are also verified. Do not enable Wallet RPC until that end-to-end path passes its certificate and isolation tests. Watch-only wallet provisioning and network isolation must be enforced by deployment. The internal allocator checks the primary-address fingerprint against the durable generation before creating, reserves beneficiary/index first, serializes cooperating allocators, and recovers create-success/lost-response by checking a stable label at the reserved index. It recognizes only the observed “address index is out of bound” error as an unused slot and fails closed on other RPC errors. Actual RPC verification is limited to the offline disposable rehearsal below; no application startup/routes/UI/scans or financial posting are wired, and the registry remains inaccessible to custody API and observer roles. Operational assumptions still include a dedicated wallet RPC, controlled generation enrollment/backups, and wallet/database reconciliation. The registry cannot establish unique output identity. Missing scans remain review evidence, not automatic balance changes. Verification passed: Docker test-target build; 187/187 offline tests; 35/35 disposable PostgreSQL tests, including v1/v2 migrations, allocator concurrency, replay, immutable registration, role isolation, zero journal postings, wallet mismatch rejection, the official -15 index response, and simulated response-loss recovery. New gateway allowlist/config tests pass; no actual mTLS certificate handshake has yet been tested. No live RPC credentials, funds or mainnet wallet were used. Remaining deposit milestone: complete the mTLS gateway interoperability/isolation rehearsal, establish durable wallet-generation enrollment and recovery, pin per-output identity and canonical inclusion/lock/reorg semantics, then implement idempotent credit journals and audited reversal/hold handling before stagenet deposit-credit rehearsal or any real deposits.

Initial actual-wallet rehearsal blocker (2026-10-21, superseded below): no Monero wallet binary or pinned image was present locally, so the RPC contract could not yet be exercised against a real process. This was resolved by obtaining and verifying the official v0.18.5.4 archive and running the disposable offline Stagenet rehearsal recorded below. The recorded evidence does not authorize mainnet access, deposits, credits, or payments.

Actual Wallet RPC + mTLS gateway rehearsal completed (2026-10-21): the test image obtains Monero CLI v0.18.5.4 only from the official downloads host, verifies the binaryFate fingerprint 81AC 591F E9C4 B65C 5806 AFC3 F0AF 4D46 2A0B DF92, verifies the GPG-signed canonical hashes file and checks the Linux x64 archive digest ba2928962c101b609434bf8c1b43ad59ebe96c5525977284ca599d8bf0f02d10 before extraction. Its rehearsal creates ephemeral CA/server/approved-client/untrusted-client certificates, then runs monero-wallet-rpc in Docker --network none, --stagenet --offline, loopback-only, with login disabled behind the tested TLS 1.3 mTLS gateway. The real wallet was verified watch-only by the query_key(spend_key) denial. The configured client cert successfully read the primary address and created one subaddress; the gateway rejected a transfer request (HTTP 400 before upstream), a CA-signed but unapproved client certificate, and a no-certificate request. Wallet files were stopped and deleted with the ephemeral container. No monerod, peer, network, live credential, mainnet or funds were involved. This proves protocol interoperability in that isolated single-container topology; it does not prove Kubernetes/apartment firewall isolation, certificate issuance/rotation, deployment configuration, hard power-loss durability, deposits/credits/withdrawals, or production readiness. The current app still does not start this gateway or observer; HTTP auth with Monero's own --rpc-login remains intentionally unused. Full offline suite after these changes: 187/187 passed; disposable PostgreSQL suite: 35/35 passed; test image build succeeded.

Output failure/reorg test results (2026-10-21): offline coverage now rejects missing outputs, duplicate public keys, subaddress misattribution, and malformed output records. PostgreSQL coverage follows a stable output identity through not-seen, reappeared, and changed-height re-inclusion states; it rejects output-key reuse across transaction IDs and confirms zero journal postings throughout. The image build passed; offline suite 189/189 passed and disposable PostgreSQL suite 35/35 passed. This exercises persistence and review signals only—no customer credit or automatic reversal exists. The actual Stagenet rehearsal against v0.18.5.4 confirms the gateway permits incoming_transfers; for a fresh empty address, the RPC returns an empty result object with the default transfers and status fields omitted. The parser now treats absent transfers as empty; no real owned output was available in the offline, unfunded rehearsal, so nonempty RPC output parsing remains fixture-tested.

Reviewed pending-deposit ledger stage (2026-10-21): schema v5 adds immutable per-output credit records and append-only observation-event holds; schema v6 adds append-only reviewer-signed release and hold-resolution records; v7 permits one signed release to resolve multiple holds while retaining one-time hold identity. A separate, non-HTTP coordinator verifies registered beneficiary allocation, observation freshness/unlock/confirmation/double-spend state, and an allow-listed P-256 reviewer signature. It can first stage an output into a non-spendable deposit-pending liability, then separately release that amount into available under another signed review bound to the current output and every unresolved hold. Reorg/disappearance/re-inclusion events create scoped holds; new purchases and withdrawals for that beneficiary are blocked while any remain unresolved. Holds can be resolved only after the output is again observed, unlocked, sufficiently confirmed, and signed off; journals are never reversed automatically. The dedicated coordinator DB role is explicitly provisioned using grant-monero-credit-runtime and remains separate from observer and custody-runtime roles. This remains isolated sandbox ledger machinery, not proof of treasury backing: no API/startup integration, reviewer key provisioning, continuous scan/hold worker, production deposit activation, withdrawal signer/worker, or live sale settlement exists. Validation: test image build passed; offline suite 190/190 passed; disposable PostgreSQL integration suite 36/36 passed. Tests cover schema upgrades, pending-credit review, concurrent duplicate release/reorg resolution, scoped spending holds, and cleanup of the disposable fixture. No external network or funds used.

Offline deposit-review operator commands (2026-10-21): custody-db now has explicit prepare/stage/release/reorg-hold/review-resolution actions, with exact argument-count checks and idempotent coordinator calls. They consume an owner-protected review-policy file and bounded signed-approval files; reviewer private keys are never loaded by the app. POSIX owner-only permissions and no-follow opens are required; these file operations refuse Windows until ACL verification is implemented. The existing IS_MAINNET guard keeps the CLI sandbox-only. This is an operator rehearsal interface, not a public deposit endpoint or live payment activation. Added argument-parser and protected-file tests; full offline suite passed 194/194 and PostgreSQL integration 36/36.

Separate Monero observation worker (2026-10-21): added a standalone opt-in process, durable bounded catch-up (100,000-block pages, four pages per batch, 1,000-block overlap), PostgreSQL session-lock leadership, restart resumption, and redacted aggregate progress logs. It persists observations only: it has no journal, balance, credit, release, address-allocation, or transfer capability. It is not started by the API and is not included in the sandbox stack as a running service. A separate role grant is available; on mainnet the custody-db CLI now permits only this exact observer-role grant and continues to reject migrations, audits, coordinator grants, and all financial actions. The operator must separately create a non-admin, no-membership database login, provide its protected PostgreSQL URL and the protected mTLS client/observer configuration, and run the worker under a supervised POSIX service. This is not yet a complete deployable Monero topology: no mainnet Wallet RPC/gateway/network-policy service, secret provisioning, monitoring destination, key lifecycle, nonempty owned-output test, or deposit-credit automation is provided. Validation: production test-image build succeeded; offline suite 195/195 and disposable PostgreSQL suite 37/37 passed. Worker evidence is synthetic catch-up/restart/leader fencing and journal exclusion only; it does not authorize mainnet deposits or payments.

Single-host worker deployment increment (2026-10-22): added a hardened systemd unit and protected configuration templates for the stated apartment-host model. Added a distinct mainnet-only, exact-acknowledgement PostgreSQL schema migration action; it runs the existing transactional, digest-checked migrations and grants no runtime permissions. PostgreSQL URL/CA files now require POSIX owner-only permissions. The worker remains non-root, private-network-only by host firewall contract, and separate from the API. This advances deployment preparation, not live service: no external host/DB/gateway was contacted, no credentials were provisioned, and no service was started. The private Monero daemon/Wallet-RPC/gateway, external monitoring and recovery, production database provisioning and independent review remain unprovided. Validation: image build passed, offline suite 196/196, PostgreSQL suite 37/37. See the systemd deployment contract.

Signed deposit-enrollment slice (2026-10-22): added a customer-wallet-signed request contract and server-side enrollment service that verifies mainnet profile, chain, custodian, beneficiary ownership, wallet-generation fingerprint, account index and a five-minute expiry before reserving a never-reused subaddress index and recovering/registering exactly one address. Added a separate allocator DB role, and schema v8 now forbids inserting pre-registered addresses directly; role permissions permit only allocation storage and the guarded reserved→registered fields. Replay returns the existing allocation; wallet mismatch/invalid signature fail before address RPC. PostgreSQL tests cover signed enrollment, replay, beneficiary uniqueness, role isolation, no journal writes and database-trigger bypass attempts. This is not exposed through HTTP/UI and no real wallet was contacted; it does not credit funds or establish a withdrawal path. Validation: build passed, offline suite 175/175, PostgreSQL suite 38/38.

Mainnet enrollment API wiring (2026-10-22): added GET /api/monero/deposit-config and signed POST /api/monero/deposit-address, only mounted when WIKIDECK_MONERO_DEPOSIT_ENROLLMENT=1 on the gated mainnet profile. Startup pins the operator-provided custodian ID, wallet-generation UUID, expected wallet fingerprint, account index, matching mTLS endpoint and separate TLS allocator PostgreSQL role. Enrollment requests are rate-limited and signed by the beneficiary; responses explicitly say address-enrolled-not-credited, with crediting and withdrawals reported disabled. The flag defaults off; this API must not be enabled for customers until deposit crediting, withdrawals and recovery are end-to-end functional. No real wallet or database was contacted. The API has no customer UI yet. Validation: test-image build passed and offline suite 176/176; the preceding complete PostgreSQL suite passed 38/38 after schema-v8 allocator protection.

1A. MVP release boundary — proposed safe first production-hosted release

The apartment/single-operator constraint changes the rollout and availability claims, not the safety evidence required to hold customer funds or valuable assets. Recommended MVP: a public, clearly labeled non-monetary beta on the existing testnet, with real XMR completely disabled, no custodial balances/deposits/withdrawals, and marketplace checkout/delivery disabled for valuable assets. Keep mining, browsing and wallet use only if they are explicitly described as experimental and users accept that data/ownership may be lost. This would be a production-hosted beta, not mainnet production, a custody MVP, or an independently secured chain.

If “MVP” instead means paid fixed-price sales or valuable mainnet NFTs, do not use the reduced beta checklist: P0/P3/P4/P5/P6 and the full NO-GO hold points still apply. Small volume, one host, mock confirmations, or a low exposure cap do not substitute for a reviewed lock/settlement protocol, real deposit/withdrawal reconciliation, funded loss policy, and legal/operational acceptance. In particular, the active v6 consensus still rejects the sale-lock candidate.

For the non-monetary beta, the remaining engineering/operations sequence is:

1. Freeze scope and disclosures: testnet identity, no-value policy, marketplace disabled for valuable cards, experimental wallet/data-loss notice, support contact, abuse/report channel and clear stop conditions.
2. Prove the apartment can safely serve traffic: ISP permission and reachable ingress/CGNAT, DNS/TLS renewal, trusted proxy and no direct backend access, firewall, patched host, restricted SSH/admin, power/network monitoring, and a documented way to stop accepting traffic. If these cannot be demonstrated, use a managed host rather than weakening controls.
3. Repeat load/reorg/restart/restore tests on the exact release candidate. The current one-shot 160-request benchmark is preliminary; define request mix/rate, run repeated trials with concurrent API traffic during reconciliation/mining/peer sync, set explicit latency/error/resource limits, and do a clean isolated restore. Keep assets valueless until consensus and recovery review passes.
4. Freeze artifacts and get independent review appropriate to the exposure. Pin image/base/native/dependency digests, generate SBOM and scans, verify the launch preflight remains NO-GO for mainnet/live payments, and record the operator’s limited beta go/no-go separately from mainnet/payment authorization.
5. Operate conservatively: encrypted off-host backups and restore drill, disk/WAL and peer/tip/reorg/worker alerts delivered somewhere other than the apartment host, patch/incident/rollback procedure, and a person responsible for responding. A single operator cannot promise 24/7 response or HA.

This scope is a proposed release boundary, not an approval to deploy. The operator must explicitly accept the beta’s non-monetary/experimental limits and sign off on apartment-host evidence before a public beta. No real funds, valuable NFT launch, mainnet activation, or consensus identity change is authorized by this proposal.

2. Resolve the cross-chain requirement before selecting architecture

What “confirmed before on-chain completion” requires

RandomX verifies work on Wikideck; it proves nothing about an XMR transfer. Monero privacy also means a Wikideck validator cannot infer recipient/amount/payment validity from a transaction ID alone. A payment service's status is a trusted attestation, not a trustless cross-chain proof. Calling an external service or mutable Monero RPC from block validation would make consensus depend on credentials, service availability and potentially different observations; do not implement that.

The design must specify what every validator can verify deterministically, which Monero chain/confirmation evidence is used, how its recipient/amount/order binding is established, what private information or keys must be disclosed, and how both chains' reorganizations are handled. Any relayer, committee, market operator, oracle or custodian introduces a named trust assumption. “Non-custodial,” “atomic,” and “trustless” are distinct claims and must be justified separately.

Mining one new card per roughly 15 minutes is independent of Monero's block schedule, but today's transfers are included in the same Wikideck blocks. Therefore XMR confirmation, Wikideck inclusion, Wikideck confirmation depth and any final XMR disbursement/unlock are separate timing milestones. Fast end-to-end settlement or a separate transaction-finality layer would need a reviewed consensus design, not just a faster payment poll. The operator has specified ordering, not yet approved changing Wikideck's block schedule.

Pre-payment lock/reservation transactions might be needed to prevent double-selling. They must not transfer completed-sale ownership, and they would appear on-chain before XMR payment. The operator approved preparatory locks/reservations for design research on 2026-10-20. This does not approve an escrow authority, custody model, expiry policy or consensus implementation.

P0 — architecture research and decision record (first critical path)

Deliverables:

1. A threat model: dishonest buyer/seller/host/miner/relayer, compromised keys, eclipse/partition, one-chain stall/reorg, late payment, stale signature, disputed quote and processor partial-send/timeout.
2. A comparison of (a) feasible researched XMR-compatible atomic/adaptor-signature or other non-custodial approaches, (b) deterministic verification/light-client or attestation approaches, and (c) host-custodial settlement with consensus-enforced NFT locks as a fallback. Research compatibility with this chain's P-256 signatures and Monero's transaction model; do not assume a Bitcoin-style HTLC works for Monero or that an existing swap library supports arbitrary NFTs.
3. Exact protocol messages/state transitions, release/refund ordering, timeouts, fee-collection enforcement, replay/domain separation, key-loss recovery and what happens if either party stops cooperating. Identify whether selling can bypass host/author commissions and what can realistically be enforced by a modifiable independent peer.
4. Primary-source/release evidence, maintained dependency/license assessment, feasibility spike using disposable fixtures, attack/failure tests and independent cryptographic review requirements. An unevaluated paper or toy demonstration is not production feasibility.
5. A recommendation with explicit guarantees, trust assumptions, costs, latency and unresolved risks. If trustless settlement is infeasible in scope, present a fallback decision for the operator; keep live sales blocked until approval.

Acceptance: operator approves an architecture decision record (ADR), with external review where required. No live adapter/consensus release is connected merely because the research finishes. Discovery of an impractical design is a valid outcome, not a reason to hide trust assumptions.

3. Workstreams, dependencies and acceptance criteria

P1 — native-XMR domain model and migration

Can begin independently of P0, but must not hardwire a settlement architecture.

• Define canonical decimal input/output backed by integer atomic units, bounded values/precision, exact comparisons and independent commission rounding. No float-based amounts or implicit USD conversion. Optional fiat display, if added, is informational and never settlement authority.
• Replace USD listing/bid/checkout fields and UI with versioned XMR-native terms. Sign currency, gross, commissions, destinations, fee policy/estimate limits, expiry, order/market/network identity and selected settlement protocol version. Update invoice/checkout review and participant disclosures.
• Migration plan: preserve existing USD/mock order history in its original version. Close/relist old open listings with fresh seller authorization; define disposition of bids/reservations before migration. No automated reinterpretation, deletion or mainnet asset migration.
• Use the selected pooled-custody model: direct Monero wallet/daemon observation and durable subaddress allocation for deposits, internal liability transfers for sales, and a separately constrained treasury withdrawal path. No third-party processor is selected or required. Preserve exact native-XMR prices; do not introduce fiat conversion as settlement authority.
• Separate payment-sending fees, hosting/author commissions and payout network fees in quotes/accounting. Define who pays author-leg network costs and fee-overrun caps. Handle sub-atomic commissions without overcharging. Preserve the fixed 1% address/rate in the distributed policy.
• Checkout preflight determines economic viability under the selected architecture before accepting an order. For the custodial proposal, internal sales have no per-sale Monero payout cost; deposit eligibility, available balance and withdrawal economics are separate checks. Accumulated balances are proposed in ADR 002 but not implemented/approved for funds; batching remains deferred. Disclose uneconomic withdrawals before deposit rather than silently forfeiting balances.

Acceptance: exact-amount property/boundary tests, versioned signature tests, zero/tiny/large-price and fee-spike tests; migration dry run/rollback on copied data; all displayed totals reconcile; no USD-authoritative live path; user review of fee semantics. No live payments yet.

P2 — production-scale state and transaction infrastructure

Can run alongside P0/P1. Addresses SEC-01/SEC-06 rather than adding more fixed caps.

Implemented M2 increments, 2026-10-20–21: canonical indexes and durable market observation. Canonical ownership/transaction SQL indexes now serve NFT, deck, custody availability and mock-market queries; per-block undo and anchored connect/disconnect events commit with ledger updates. Market checkpoint/reorg holds persist atomically and bounded catch-up blocks new mutations. Order/listing reconciliation advances in durable, stable-ID keyset batches of at most 32 records per table, resumes after restart, and re-fences when the chain tip/revision changes. The HTTP process now uses a single worker thread to select/evaluate bounded row batches, read canonical facts using its own read-only Ledger connection, and atomically persist changes with cursor progress. The offline suite has 187 passing tests; focused market tests passed 27/27; the disposable PostgreSQL suite passed 31/31 in the previous run. Regressions verify a main-loop timer runs during worker backlog and that a second server process cannot start against the same data directory. A synthetic 10,000 confirmed-delivery run with 160 loopback health/market requests measured worker HTTP p50/p95/max of 285/322/324 ms versus 1,416/2,844/2,971 ms synchronously. This single local run is preliminary (no repeated confidence intervals or realistic request arrivals), not an SLO. Main-thread event-page acquisition/post-batch fencing, realistic concurrent HTTP load, multi-process fencing beyond the existing exclusive directory lock, target hardware/data, production financial storage/recovery, retained-DAG capacity and operator SLO decisions remain open.

Next financial-storage increment: ADR 003 — PostgreSQL selects and integrates the custody SQL backend with existing HTTP callers, exact constrained accounting, explicit migration/runtime roles, source-freezing SQLite import and dump/restore rehearsal. The adapter remains on the fictitious sandbox domain; it is not a production deposit/withdrawal worker. SQLite node-only backup deliberately refuses PostgreSQL-bound financial state. Production hardware/SLO tests, coordinated backup/PITR/failover, real payment schema/worker controls and independent review remain open, so this does not close M2/M4 or authorize funds.

Financial reconciliation increment: business-liability checks now tie each order/withdrawal to its exact reservation, journal lifecycle and pending work, including reverse orphan/duplicate checks. PostgreSQL startup/import/explicit/periodic audits and targeted mutations use these checks; redacted durable incident holds fence new postings, while private reads and original receipt replay remain available. Private operations reports audit freshness/holds, and schema-owner incident acknowledgement requires a successful locked full audit plus evidence reference. No automatic repair, real payment, schema reset or consensus activation is enabled. Production capacity, coordinated recovery and external review remain open.

Deployment increment: persistent local custody stack now starts PostgreSQL and the actual app together, with private TLS/SCRAM networking, separate owner/runtime roles, explicit migrations and scoped persistent credential/data volumes. A signed fictitious credit and custodian identity survived container/network removal and recreation; the server rejected plaintext authentication. Existing deployments and SQLite custody were not switched. Production certificate rotation, coordinated backup/restore and external operating review remain open; all XMR remains simulated.

• Indexed canonical ownership, NFT/transfer lookup and paged wallet/explorer APIs: browser signing must not require loading all history. Tip-pinned queries detect reorgs and preserve complete ownership semantics.
• Incremental market reconciliation from durable canonical/reorg events. Local bounded implementation delivered: rollback-safe canonical event pages, durable 32-row order/listing keyset jobs, tip/revision re-fencing, restart continuation, mutation fencing, and a single worker thread that selects/evaluates batches and reads its own read-only canonical SQLite snapshot before atomically committing results. Regression tests cover snapshot reads, reorg/event append, injected worker commit failures and restart recovery. Still open: move event-page acquisition and post-batch consistency checks off the request event loop, measure concurrent HTTP latency and queue lag, coordinate/fence processes, and establish throughput/overload/recovery limits at declared order/event volumes.
• A versioned production market/settlement schema with append-only financial events and balanced accounting entries for buyer liabilities, host revenue, author liabilities, seller liabilities, paid/refunded amounts and actual network fees. Derived views are rebuildable; financial history and idempotency keys are not discarded to reclaim space.
• Durable inbox/outbox, processor attempts and reconciliation states; no network operation inside a long DB transaction. Store intent before external side effects; unknown POST outcomes stay quarantined until evidenced resolution. Per-market isolation, actor-scoped paged reads, queue/backpressure and tenant/global exposure budgets.
• Database architecture ADR: retain a measured single-writer SQLite deployment if it meets declared limits, or choose a production DB/worker topology and supported migration. Do not claim horizontal safety merely by launching multiple workers against local state. Start with one authoritative writer per market.
• Ledger/DAG storage and startup-replay capacity plan: disk usage budgets, archival/reindex strategy, fork handling, retention rules that do not silently alter consensus or lose recovery evidence.

Acceptance: indexed-vs-full-replay differential tests; adversarial reorg/crash/cursor tests; invariant/property tests for accounting; benchmark populated long-chain/journal fixtures at a declared target dataset and SLO; overload preserves validation/health capacity; explicit supported storage/node/operator envelope. Target numbers must be selected from measurements, not invented here.

P3 — implement the approved exchange protocol

Blocked on P0 ADR; use P1 amount types and P2 durable events. Consensus work is a separately reviewed change.

Candidate increment, 2026-10-20: ADR 004 — sale locks now specifies and implements an offline deterministic signed lock/completion/cancel/expiry model, exact height boundaries, native transfer/trade lock guards, replay-resistant sequences, state commitments and a non-posting financial observation policy. A pure bridge checks terms drafted from actual sandbox reservations. Final build and 162 offline tests passed. Active v6 consensus still rejects the candidate and no host signer or balance-posting integration is enabled. Independent review, policy approval, versioned network activation, actual PoW/peer/index integration and PostgreSQL terminal workflow remain open; M3 is not accepted.

Accounting rehearsal increment, 2026-10-20: signed candidate → PostgreSQL reservation resolution now exercises actual restricted-role SQL terminal postings from bounded synthetic transcripts, behind explicit disposable database/instance guards and without an HTTP route. Exact terms/hosting recipients and reservation commitments are checked; mature completion credits seller/fees once, cancellation/non-admission releases buyer funds, and conflicting post-settlement evidence durably holds mutations rather than repaying. Insert-only first/terminal evidence is audited. Final build, 172 offline tests and 22 PostgreSQL integration tests passed. This supersedes the earlier absence of any balance-posting test integration, not the production/activation boundary: caller-supplied seeds/blocks are not canonical evidence, intermediate unseen disconnects cannot be detected, and no signer, canonical inbox, live deposit/withdrawal or current-chain paid sale is enabled. M3 remains open.

Canonical/per-order reorg rehearsal increment, 2026-10-20: the gated disposable PostgreSQL observer stores bounded pages from an in-process Ledger adapter, checks stream/anchor/hash/tip/ancestor continuity, supports retries, and audits retained history. Tests cover a block mined and independently verified with native RandomX flowing through the local ledger into PostgreSQL, plus a fake-PoW equal-work branch/reorg. A separate synthetic-event test links the deterministic candidate terminal transaction ID to its posted order; disconnecting that ID (even followed by same-page re-inclusion) commits the event history and durable order review hold atomically, without undoing or repeating the payout. Generic incident resolution cannot clear a sale-reorg record. The server now has an opt-in polling lifecycle, restricted to PostgreSQL custody_test, both disposable flags and non-production mode; it drains on shutdown, resumes the persistent cursor after restart and stops on review/failure. Final build, 172 offline regressions and 30 PostgreSQL tests pass. The worker remains disabled in all regular deployments, active v6 cannot emit candidate IDs, and synthetic linkage is not canonical sale evidence. Stream hashes are not tamper-proof against the schema owner; 4,096-event cap/full scan are non-production. M3 remains blocked on reviewed candidate activation, actual candidate IDs from an activated local ledger, production observer/checkpoint design and production readiness.

Coordinated-backup rehearsal increment, 2026-10-20: the stopped-node maintenance utility holds the node startup lock and PostgreSQL custody advisory writer lock, checks local/database custodian identity and frozen cutover digest, performs a full liability audit, snapshots active node SQLite state and writes a custom-format PostgreSQL dump through a dedicated SELECT-only backup login. The strict pair manifest is written last. Its integration mines and independently validates a genuine native-RandomX block, creates the archive, restores the node files into a new directory and reopens them through the reference validator (checking tip and NFT owner); it also restores PostgreSQL into a separate database and compares custodian ID, import digest, balances, audit and receipt state. A post-cutover frozen SQLite source is checked against PostgreSQL import_source and omitted as historical rather than misrepresented as current custody. Lock, identity mismatch, failed dump, incomplete output, overwrite, least-privilege and tamper cases are covered. Final build, 172 offline regressions and 31 PostgreSQL tests pass. The persistent sandbox received only an additive backup-role implementation; it was not restarted or migrated. The package is not encrypted/off-host/signed/scheduled and provides no PITR, retention, measured long-history timing, RPO/RTO or production recovery certification. Coordinated recovery remains open.

• If a reviewed trustless design is selected: implement its actual cross-chain validity/evidence rules, compatible cryptographic primitives, both-party failure/refund paths and commission semantics. Run maintained reference vectors, negative tests, fuzz/property tests and specialist audit before claiming atomicity.
• If a custodial/attested fallback is explicitly approved: define chain-enforced NFT lock, order identity, authorized releaser, cancellation/refund/expiry and stale-signature rules. Separate host control keys from seller wallet and processor payout keys. Reserve/refund procedures must not permit both buyer refund and later seller delivery/release. Describe who can steal, censor or lock assets and how recovery is authorized.
• Completed-sale inclusion must require the approved evidence that payment is sufficiently confirmed. A peer must not insert a completed sale merely because its local database says paid. Define threshold/policy version, proof/attestation authorization and deterministic validation; no external HTTP calls in consensus validation.
• Define lock/release race outcomes, multi-market double-listing, expiry at exact heights/times, unavailability of the host/parties, reorg on either network, network upgrades and replay across canceled/relisted orders.
• If protocol data/rules change, use a reviewed new network/manifest/version and migration strategy. Do not change existing testnet/production rules under the old identity. Existing free transfers/card trades must not accidentally inherit false payment-proof claims.

Acceptance: safety/liveness matrix covers every state transition and adversary; impossibility/trust limitations disclosed; reference-engine multi-host partition/stall/reorg and recovery tests; explicit protocol freeze and independent review. Delayed inclusion is displayed honestly—no “Monero-speed finality” claim.

P4 — production payment integration, reconciliation and controls

Depends on the pooled-custody decision in ADR 002 and the separately reviewed NFT lock/completion/cancellation protocol.

• Deposit enrollment and allocation: authenticate the Wikideck beneficiary, create a durable one-to-one mapping to a Monero subaddress before displaying it, and keep old allocations monitored. The spend-capable wallet must be isolated from the public API.
• Observation and credit: consume wallet-owned output records with stable per-output identity, canonical inclusion, versioned confirmation/unlock policy, exact atomic amounts and idempotent ledger writes. Unknown, late, duplicate, partial and reorged outputs require defined suspense/hold treatment; observations alone never authorize spendable credit.
• Marketplace settlement: reserve available customer liability and order state atomically in PostgreSQL; release seller/author/host liabilities only from the agreed canonical sale outcome. A user-signed mock-payment action is never payment evidence.
• Withdrawals: authorize exact destination, amount and maximum fee; reserve liabilities; fence one treasury worker; durably store prepared-transaction identity before relay; reconcile chain status and actual fee. Ambiguous outcomes must not trigger a second transaction or release of the reservation.
• Recovery and operations: include customer-to-subaddress mapping, wallet generation/high-water marks, journal, pending outputs, signed approvals and prepared transactions in encrypted backups. Restore without spending, reconcile with Monero state, then explicitly re-enable the treasury worker.
• Set measured liability/exposure caps and independent alert/stop controls. Stopping new deposits or orders must not abandon existing liabilities. Separate observation, ledger, operator review and spend-signing privileges.

Acceptance: full end-to-end staging against an isolated Monero daemon and watch-only wallet, unauthorized-action tests, injected outages/timeouts/crashes/reorgs, complete deposit-to-ledger and withdrawal-to-chain reconciliation, and reviewed secret/signing controls. Any real-fund movement requires a separate explicit scope, budget and network authorization. This plan authorizes none.

P5 — buyer/seller policy, disputes and abuse

Policy is a product deliverable, not a footer disclaimer; implementation and legal review must match it.

• Publish host responsibility, contact/support channel, response targets, eligibility/evidence and who decides a dispute. Reserves and caps must be funded and enforceable operationally before they are advertised. No unqualified loss insurance or guaranteed reimbursement without a real funded obligation.
• Define ownership/delivery acceptance, payout hold, cancel/refund/release states and which party bears fees, reorg, key-loss, and late/partial/duplicate deposit outcomes. Prevent double compensation. An expired payment request does not erase a legitimate incoming payment.
• Host and author fees remain separately visible. Decide revenue recognition on settled sales versus refunds and who bears sending costs if seller payout succeeded but author payout failed. The author's fee does not imply author arbitration or host underwriting.
• US operator engages qualified counsel for applicable custody/money-transmission, sanctions, consumer, privacy and tax obligations before accepting real funds. Applicability is not decided by the software author/assistant or by calling the product “decentralized.” Do not assume identity collection is required or unnecessary without that review.
• Anti-abuse for fixed-price launch: short bounded reservations, address/account/request limits, deposit or admission policy only if approved, fee-aware dust handling, suspicious-activity and order-churn controls. Consider Sybil attacks; one wallet is not one person.
• Auctions later: dedicated decision on funded bids/deposits, outbid refunds, nonpayment/shill/bid-sniping policy and privacy, with accounting and dispute tests before enabling live auctions. Avoid forcing a large custodial balance system just to ship auctions.

Acceptance: executable policy-to-state-machine tests, published versioned participant terms, working support/incident routing, operator sign-off on costs/loss allocations, required legal review. No fabricated SLA/support address or unfunded reserve claim.

P6 — release, wallet, deployment and independent review

Run throughout development; final release gates depend on P2–P5.

• Complete wallet review: same-origin threat model, migration/lock/unlock and recovery across supported browsers, signing review/session invalidation and stale handles; decide isolated/hardware signing support. Close old plaintext copies as a user migration/risk procedure, not a secure-erasure claim.
• Real host/edge verification: HTTPS/cert renewal, forwarded-header trust, firewall, admin access, secrets, egress, CPU/RAM/disk/WAL budgets, time sync, on-call alerts and monitoring of actual peer/tip and payment-worker progress.
• Deployment clarification: production target is behind a firewall in Kubernetes. Database certificate issuance/renewal belongs to the database/cluster infrastructure, not a bespoke application service. Verified PostgreSQL TLS remains the default; explicit infrastructure-managed transport is available only with acknowledged externally enforced encryption/peer authentication. A firewall/NetworkPolicy alone is insufficient evidence. Local Docker TLS provisioning remains sandbox-specific; no certificate-rotation feature is being activated.
• Backups/restore with complete financial journals and off-host encrypted copies: measured RPO/RTO and successful cold restore/reconciliation; test losses of host, journal, wallet key and processor reachability. Recovery of customer keys and recovery of merchant funds are different responsibilities.
• Repeat consensus/hashpower studies on intended miner/validator hardware. Quantify production attack and recovery costs; finalize difficulty/retarget/actual genesis after review. One powerful operator server is not multiple independent validators/miners or Monero-level security.
• Pin release artifacts/dependencies/base images, SBOM, secret/dependency/container/native scans, fuzz/sanitizer runs, reproducible/provenance evidence and signed artifacts. Publish the selected project license and respect dependency/Wikipedia licensing.
• External consensus/application/cryptography review against the exact release; close critical/high findings with regression evidence. This coding session is not independent certification. Provide a versioned technical and participant-facing disclosure set describing real guarantees, not stale mock behavior.

Acceptance: signed release evidence packet; recorded unresolved accepted risks with owners, limits and expiry; named operator/reviewer go/no-go. Runtime preflight reflects verified evidence rather than blindly trusting a boolean operator attestation.

4. Delivery order and parallel work

Milestone	Deliverable	Dependency / decision gate
M0	Threat model + trustless feasibility ADR + preparatory-lock decision	First critical-path design work; fallback requires operator approval
M1	Exact XMR types, versioned signed terms, migration dry-run, fee-viability specification	Can start during research; no production processor assumptions
M2	Canonical indexes/paged wallet, incremental workers, production accounting schema	Parallel infrastructure; measured dataset/SLO envelope required
M3	Approved chain exchange protocol and deterministic payment evidence	M0 + M1; reviewed consensus/version/identity decision
M4	Integrated payment/staging workflow, operator reconciliation and full backup coverage	M2 + M3 + verified native-XMR processor capability
M5	Fixed-price policy/abuse/fee/custody acceptance and external review	M4; US legal/risk decisions; funded caps/reserves if applicable
M6	Multi-host rehearsal, release artifact evidence, explicit launch meeting	All required findings/evidence resolved; network and payments separately approved
Later	Live auctions, broader independent-host rollout, higher exposure	Separate scope/capacity/abuse gates; not automatic launch follow-ons

First implementation increment: write the M0 threat model/ADR research questions and P1 XMR domain specification, then build exact amount/property tests. Do not spend the next increment adding another disconnected “live” scaffold. Each milestone must integrate with its actual callers, persistence, recovery, UI and failure tests before being described as delivered.

Current increment status: the operator selected custodial implementation after settlement research. M1 has a signed v3 XMR-native mock path, with historical v2 USD orders preserved. ADR 002 records the implemented isolated custody accounting/UI foundation; production custody is not complete. Canonical indexing and durable reconciliation now includes bounded, restartable, chain-revision-fenced market catch-up and has passed focused, offline, and disposable PostgreSQL regression suites. This closes one incremental-scheduling implementation gap, not M2 acceptance. Next gates include target-scale benchmarks, off-event-loop worker design, production accounting/recovery envelope and the separately reviewed NFT lock/completion/cancellation specification (M3); no live Monero integration or consensus activation is authorized by passing these tests. Migration dry-run, final fee/risk policy, capacity SLOs and independent review remain open.

5. Acceptance evidence and release discipline

For each requirement record: identifier, owner, ADR/policy version, code/schema version, tests and adversarial cases, measured limits, reviewed artifact hash, known residual risk and approving party. A test count alone is insufficient. Historical 122-suite/targeted-doc test results remain useful regression evidence, not proof of current production readiness; rerun against the frozen release.

Release stages:

1. Local deterministic/property/fuzz tests and migration on copied disposable data.
2. Isolated multi-process and multi-host staging, no valuable assets, partitions/stalls/reorgs/crash injection and full recovery.
3. Verified processor integration under separately approved network/credential/fund-testing limits, only where architecture and law allow it.
4. Independent review/remediation, policy/legal/operations sign-off and frozen manifest/release digest.
5. Explicit network authorization and separately explicit payment authorization. Initial exposure caps remain restrictive until a measured soak and reconciliation review succeeds.

Never remove a NO-GO finding to make a dashboard green, reset a journal to clear payout uncertainty, or promise a launch date before dependency decisions and review. An architectural dead end is escalated with evidence and alternatives, not worked around with unannounced custody.

6. Remaining operator questions — ask at the relevant milestone

Not every value is needed to begin engineering; each becomes a blocking decision before its related activation.

Decision	Needed by	Why
Preparatory on-chain NFT lock/reservation without completed ownership transfer	M0 — permission agreed	Approved for design research on 2026-10-20; exact rules and authority remain subject to ADR review.
What exactly is the XMR payment destination and amount condition: seller receives net directly, or gross into approved conditional/custodial structure? How are host/author fees enforced?	M0	Buyer payment confirmation, seller proceeds and disbursement may be different events.
Acceptable trustless protocol liveness/cancellation delay, privacy disclosures and emergency recovery authority?	M0	Cryptography cannot resolve an unstated trust/recovery policy.
Author-leg payout costs: charged to seller; what cap/estimate tolerance and quote lifetime?	M1	Net viability and buyer/seller signatures must agree before money moves.
Tiny sale treatment: block checkout, subsidize under a published budget, or separately approved accumulation/batching?	M1	No listing minimum does not mean every amount can economically settle directly. Default planning assumption is block uneconomic checkout, pending explicit confirmation.
Per-sale, daily and total unsettled exposure caps; initial reserve and funding source; who bears which reorg/processor losses?	M4–M5	Cannot claim buyer/seller loss coverage or fee funding without numbers and funded responsibilities.
CPU model/resources, storage, concurrency/user/order dataset targets, operators expected at each scale milestone and latency SLOs?	M2	“Powerful server”/“large volume” is not a benchmark acceptance criterion. Operator count is independent of per-host capacity.
XMR confirmation/unlock and Wikideck finalization policy; payment/disbursement timing UX?	M3–M4	No universal “fully confirmed” threshold; distinguish ordering, inclusion and risk.
Dispute/support SLA, authenticated operator approvals, backup RPO/RTO and incident on-call?	M5–M6	Procedures must work before promising them to customers.
License, actual US legal operating entity/jurisdiction scope and required legal advice?	Before public distribution/live funds	These cannot be selected or certified by code changes alone.

References

• Current participant payment disclosures — describes existing behavior, not future promises.
• Security findings and operator hold-point register.
• Resource controls, wallet lifecycle, calibration evidence, operations/recovery.

This plan supersedes the earlier USD production-pricing direction. New mock listings already use native XMR; historical USD terms remain intact. Custody and M2 implementation status are explicitly bounded above; no sandbox or infrastructure milestone implies live settlement or launch readiness.