Ledger-side credit and withdrawal-intent paths

docs/mainnet-launch.md

@@ -1,6 +1,6 @@
 # Gated mainnet candidate
 
-This repository now has a **separate mainnet candidate profile**, not an audited or launched production network. Shipping code does not establish independent miners, economic security, an operational public network, or a safe real-money market. **Payments remain mocked on every profile.**
+This repository now has a **separate mainnet candidate profile**, not an audited or launched production network. Shipping code does not establish independent miners, economic security, an operational public network, or a safe real-money market. **Marketplace payments remain mocked on every profile.** There is opt-in mainnet code for operator-reviewed pending deposit credits and signed withdrawal reservations, but it does not expose customer deposits by default or construct/relay Monero transactions; it is not a live payment service.
 
 **Current production decision: NO-GO.** See the [2026-10-20 security review](security-review.md) and [operator evidence register and launch procedure](operator-launch.md). The read-only `launch:preflight` package script (or node entry-point `--launch-preflight`) reports local gates and unresolved blockers without starting a node or setting approvals. It deliberately exits nonzero while production readiness is blocked.
 

docs/market-transparency.md

@@ -103,7 +103,7 @@ There is currently **no built-in arbitration service, buyer insurance, chargebac
 
 ## Future live custody is not active
 
-The intended direction is direct wallet/daemon observation into a pooled liability ledger; it does not depend on a third-party invoice processor. That future flow is not implemented end-to-end. There is no customer-facing deposit route, automatic customer credit, treasury withdrawal service, or real sale settlement. No confirmation threshold, funded reserve, loss allocation, refund policy or dispute process has been approved. This document describes current behavior and does not promise future buyer protection.
+The intended direction is direct wallet/daemon observation into a pooled liability ledger; it does not depend on a third-party invoice processor. An opt-in mainnet operator workflow can stage observed outputs as pending and release them to a customer's available ledger balance after signed review. A separate opt-in API accepts signed withdrawal requests and reserves funds, but does not create or relay Monero transactions. Neither flow has a customer UI, and the address-enrollment API does not itself credit funds. No customer-facing deposit address should be issued until withdrawals, outgoing reconciliation, backup recovery, and custody policy are complete. No confirmation threshold, funded reserve, loss allocation, refund policy or dispute process has been approved. This document describes current behavior and does not promise buyer protection.
 
 ## Privacy, evidence and host accountability
 

docs/marketplace.md

@@ -89,5 +89,6 @@ For **review**, preserve backups and inspect canonical blocks, pending transfers
 ## Future live XMR custody
 
 The selected direction is a pooled custodial ledger, not per-sale processor invoices. Real deposits would be assigned to durable Monero subaddresses and reconciled against wallet-owned outputs; purchases would transfer liabilities internally. Withdrawals would require a separate, policy-constrained treasury signer and durable reconciliation. A mainnet-only address-enrollment API now exists behind `WIKIDECK_MONERO_DEPOSIT_ENROLLMENT=1`, but it is off by default and has no customer UI; its response explicitly says the address is not credited. There is still no customer credit worker, withdrawal signer, or paid-sale settlement path. **Do not enable the enrollment API or publish its addresses until customers can be credited, withdraw, and recover funds end-to-end.**
+The selected direction is a pooled custodial ledger, not per-sale processor invoices. Deposits are associated with durable Monero subaddresses and an operator-reviewed observation can now be staged as a pending liability, then separately released to a customer's available balance. A separate mainnet-only API can accept signed withdrawal requests, reserve the exact amount plus maximum fee from that balance, and let the customer cancel before signer handoff. Both mainnet paths require dedicated PostgreSQL roles and explicit startup/operator configuration. **They are not a complete payment system:** the current withdrawal endpoint only reserves liabilities; there is no transaction construction, signer, relay, outgoing-chain confirmation or recovery process, and no customer UI. Deposits and withdrawals remain off by default. Do not publish addresses or solicit funds until the XMR send and recovery lifecycle is proven.
 
 Do not send real XMR to this sandbox. Live activation requires an end-to-end reviewed implementation, funded-liability and custody policies, production wallet/daemon isolation, withdrawal/reorg recovery, backups and operations evidence. No payment-mode setting is an activation path.

docs/operator-launch.md

@@ -27,7 +27,7 @@ The runtime image can execute the entry point with `--launch-preflight` as well;
 
 For the proposed **non-monetary testnet beta only**, use a separate scoped decision: the chain/network is explicitly testnet, no valuable cards are offered, real payment/custody settings remain off, mock market delivery is disabled or the deployment is demonstrably valueless, and experimental wallet/data-loss limitations are disclosed. This does not close any mainnet/live-payment hold point below. Apartment-hosting evidence must include ISP/CGNAT/reachability, TLS/proxy/backend isolation, firewall/admin/patch controls, off-host encrypted backup and restore, and external alert delivery. If these cannot be verified, do not expose the apartment host publicly; choose a managed host.
 
-The real-money custody path is not implemented end-to-end. Production deposit/credit/withdrawal services, custody and refund policy, journal/backup/monitor integration, operator reconciliation and independent review remain missing.
+The real-money path is still not end-to-end. Mainnet can now be configured for operator-reviewed deposit staging/release and signed customer withdrawal reservations, but those paths remain opt-in and there is no external treasury signer, relay, outgoing transaction confirmation/reorg reconciliation, customer UI or complete recovery procedure. Do not provide addresses or accept funds until a customer can actually withdraw and that send is reconciled against the chain.
 
 [Stage-4 deployment and recovery tooling](operations-recovery.md) adds explicit proxy trust, private loopback diagnostics/checks and stopped-node pair backup/verification/non-overwriting restore. A local native proof-replay restore drill is automated, but actual-host TLS/proxy verification, off-host recovery, alert delivery and operational ownership still require external evidence.
 
@@ -41,7 +41,7 @@ For each item record **owner, artifact/release ID, date, evidence location, revi
 | Consensus launch design | Final genesis and manifest; measured starting target/hashpower; reviewed timestamp/retarget/partition/reorg attack analysis | Missing |
 | Node availability | Bounded public APIs/client; global resource/admission controls; realistic long-chain and hostile traffic capacity report | Missing |
 | Production wallet | At-rest/unlock/signing policy, same-origin compromise analysis, user confirmation and offline recovery drill | Missing |
-| Real-money market, if offered | Direct wallet deposit observation and exact liability crediting, customer-authorized withdrawals, isolated treasury signing, durable reconciliation, custody policy, refund/reorg dispute controls | Not implemented; real payment must stay blocked |
+| Real-money market, if offered | Direct wallet deposit observation and exact liability crediting, customer-authorized withdrawals, isolated treasury signing/relay, outgoing-chain reconciliation, custody policy, refund/reorg dispute controls | Partial reservation and reviewed-credit code only; no XMR send; keep real payments blocked |
 | Mock-market policy | Ensure public users cannot mistake buyer-triggered mock payment for money; disable sandbox selling/delivery for valuable mainnet cards unless explicitly confined to a valueless trial | Unresolved |
 | Peer/miner topology | Multiple independently administered hosts/operators/failure domains; actual online matching manifests and sufficient independent hashpower, not just two URL strings | Unverified |
 | Edge and host security | TLS/certificate renewal, firewall, loopback backend, reviewed proxy IP trust, connection/global limits, restricted administration, patched hosts, time synchronization | Unverified |

docs/production-plan.md

@@ -40,6 +40,9 @@ Status: active engineering plan; **not launch or payment authorization**. Update
 
 **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.
 
+**Mainnet reviewed credit and withdrawal-reservation path (2026-10-22):** added one-time `initialize-mainnet-custody-identity CUSTODIAN_UUID`, guarded by exact identity and `reviewed-credit-only` acknowledgements. It binds a migrated v9 custody database to the selected mainnet chain/custodian and refuses rebinding or existing financial/allocation records. The existing signed review workflow can stage an observed output as pending, then release it into the customer's available balance; it is restricted to registered beneficiary allocations, current observations, allow-listed reviewer signatures, and reorg holds. Added signed customer-only balance reads, withdrawal requests that atomically reserve recipient amount plus max-fee against that beneficiary's available balance, and customer cancellation before signer handoff. New withdrawal reservations cannot exceed that customer's cumulative reviewed, released deposits. A separate no-membership withdrawal database role has ledger-intent privileges only; no Monero signing or relay capability is exposed. **This is not a completed withdrawal/payment system:** reserved requests are not signed, broadcast, or confirmed on Monero, there is no customer UI, and no funded-treasury reconciliation or recovery process. Do not solicit deposits until the isolated treasury signer and end-to-end send/confirmation/reorg/recovery path exists. Validation: image build passed; offline suite **177/177** and disposable PostgreSQL suite **40/40** passed. No mainnet database, wallet, or funds were contacted.
+The API-side switches are `WIKIDECK_MONERO_DEPOSIT_ENROLLMENT=1` for address allocation and `WIKIDECK_MONERO_WITHDRAWAL_REQUESTS=1` for signed balance/withdrawal intents; both require `WIKIDECK_NETWORK=mainnet`, protected wallet/DB config, and a separately initialized custody identity. Both default to off. Withdrawal endpoints never call Wallet RPC. There is intentionally no environment switch for transfer signing, transaction relay, or live sale settlement.
+
 ## 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.