wikideck/docs/xmr-domain.md

Native-XMR domain and migration specification — first increment

Status: exact-amount primitives and version-3 native-XMR mock marketplace pricing are implemented. No live settlement architecture/payment, production accounting migration or approved network-cost policy is delivered. See production plan and settlement investigation.

Implemented amount contract

Shared amount primitives use bigint internally and strings at JSON/signature/storage boundaries. One XMR is 1,000,000,000,000 atomic units. No float parsing, rounding, exponent notation, signs, whitespace, leading-zero whole numbers, coercion or more than twelve decimal places is accepted. Zero is valid for fee/observation amounts; sale allocation requires a positive gross, including a one-atomic-unit price. Gifts remain ordinary free transfers.

• Decimal input: e.g. 1, 1.2, 0.000000000001. Display/processor output has exactly twelve fractional places, e.g. 1.200000000000.
• Canonical atomic wire value: integer string, e.g. "1200000000000"; zero is "0". Never a JSON number or serialized bigint. Alternative spellings are rejected rather than silently normalized inside signed records.
• Encoding bound: 9,999,999,999.999999999999 XMR (22 atomic digits), retaining the former processor parser's bound. This is a bounded application representation, not Monero's supply limit, a spendable amount, an exposure cap or approval of a large checkout.
• Wallet-RPC individual amounts have a separate unsigned-64-bit bound; assertXmrRpcAmount checks it. An eventual adapter must also enforce operational/available-funds limits and lossless JSON encoding/decoding. JavaScript JSON.parse of large numeric RPC amounts loses precision; converting a rounded Number to bigint does not recover it. No wallet-RPC transport is added here.

Existing atomicXmr and xmrString callers now reuse the shared parser/formatter. The mock quote and offline settlement lab reuse the same independent commission allocation. Valid existing amounts, USD semantics, message domains, database records and displayed mock totals remain unchanged. Trailing newline acceptance from JavaScript's $ regex anchor is deliberately removed; amounts require absolute end-of-input.

Commission and budget arithmetic

Given atomic gross G, hosting basis points H (0..5000), and fixed author basis points A=100:

• hosting = floor(G × H / 10000)
• author = floor(G × A / 10000)
• seller before network costs = G − hosting − author

Each commission rounds independently down; every residual atomic unit remains in seller proceeds. Do not round a sub-atomic 1% fee up to one atomic unit. A zero author allocation is not a deferred balance. The existing fixed public author destination remains unchanged in market policy.

assessXmrSaleBudget evaluates a supplied total seller-funded maximum network-cost budget B. It reports viable only when seller proceeds before network costs exceed B, leaving at least one atomic unit. A blocked result contains zero minimum net and a funding shortfall, not a negative payable amount. Shortfall is additional funding at the current allocation, not a recommended price increase (changing gross can also change commissions).

This pure result is not a payable quote, does not estimate real network fees, and does not silently approve fee policy. Caller must include every applicable seller-funded leg exactly once. Buyer wallet sending fees are outside G and B. The budget is not a host fee or revenue; approved accounting must record actual costs and disposition of unused budget. Fee spikes cannot authorize spending beyond signed limits.

Pending operator decisions: author-leg cost allocation/caps, estimator/quote expiry, overrun handling and explicit tiny-checkout policy. The planning assumption is to block uneconomic checkout before accepting payment, with no subsidy, pooling or accumulated customer balances. No live checkout currently calls the budget helper.

Versioned terms

New commands use market-command-v3 and strictly bind network/chain, market, actor/public key, nonce, expiry, action, currency XMR, and canonical atomic gross for listing/bid/buy. List and buy terms bind the fixed author rate/address; listing terms bind hosting basis points. New public sale prices no longer use USD or a conversion rate. The current signed model is intentionally a mock-market terms schema, not yet the full production economic settlement commitment. The eventual production terms need a reviewed new protocol/domain version (not a silent reinterpretation of v3) binding at least:

• network and chain identity, market and order/listing identity, nonce and expiry;
• card hash/ownership sequence, seller and buyer authorization identities;
• currency XMR, canonical gross atomic string, hosting basis points/allocation and destination;
• fixed author basis points/address and exact independent allocation;
• seller destination, seller minimum net, total/leg-specific network-cost caps and cost policy version;
• payment destination/conditional-output commitment, payment-evidence/confirmation/unlock policy and selected exchange protocol version;
• lock identity, release/refund/cancel conditions and relevant deadlines.

The buyer must review immutable exact terms and addresses; the seller must authorize network-cost exposure. Validate supplied allocations by recomputation, not trust them because they are signed. A changed quote needs fresh authorization; callback status cannot amend it. The mock v3 checkout currently derives the quote only from the exact gross and hosting rate; it does not set live addresses or use an exchange rate.

Non-destructive migration specification

1. Inventory copied, stopped-node market data by schema/order state; record counts, original terms/receipts and hashes. Keep existing recovery contract until a reviewed new schema includes all financial journals. The v3 runtime reads mixed old/new JSON rows without rewriting old USD rows. No destructive database migration is run here.
2. Keep historical USD/mock listings/orders and market-command-v2 authorization material in their original version. Never convert priceCents into XMR, infer an old seller XMR address, synthesize a signature or issue a real invoice from old orders.
3. New v2 USD listing creation, bids and checkout are rejected. Existing v2 reserved orders can still complete their old mock pay/refund/delivery route with v2 signatures. This is compatibility, not an external payment obligation. Do not relist their cards while an order is reserved/in flight.
4. Old open USD listings are displayed as legacy/read-only; where eligible (seller-owned and no bid), the seller can close the listing with a fresh v3 authorization. Auctions with bids cannot be retired through this action and expire under the original sandbox rule. Sellers create a new XMR listing with a new v3 signature. Old records and receipts remain; no price conversion or automatic bid transfer.
5. Fixed-price and sandbox-auction v3 terms are native-XMR mock routes. No real payment processor can use them. Before live fixed-price delivery, selected settlement evidence, index/accounting/recovery controls, policy and disclosures still require integrated implementation and review; live auctions remain a separate later gate.
6. Full stopped-copy migration dry-run, complete mixed-record upgrade/restart tests, rollback rehearsal and journal hash/count evidence remain outstanding. No external effects occur in this mock path. Before any future real external effect, a local DB rollback alone is unsafe: reconcile external history first and retain authoritative intents/events.

Versioned XMR signature tests, direct HTTP v3 integration, one-atomic-unit no-minimum fee tests, and legacy-order/listing compatibility tests cover this increment. A full stop-copy data migration dry-run, interrupted-upgrade/rollback evidence, approved network-cost policy, live processor integration and settlement are not covered. Amount tests cover boundary/coercion/newline/precision cases, RPC range, independent rounding, fee-budget exhaustion/spikes, 4,000 deterministic generated conservation/round-trip cases and original mock caller behavior. They are not settlement feasibility or launch evidence.

Validation for this increment (2026-10-20): Docker test-target build passed TypeScript and Vite compilation; the full suite ran with external networking disabled and passed 133 tests, 0 failures, 0 skips. Includes API v3 signing, one-atomic minimum, legacy read-only listing retirement, and in-flight USD order restart compatibility. This evidence does not close the remaining M0 settlement, fee-policy, data-copy dry-run or launch gates.