wikideck/docs/xmr-domain.md

Native-XMR domain and migration specification — first increment

Status: exact-amount primitives implemented; native-XMR marketplace migration and fee policy not delivered/approved. 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 native-XMR terms — integration target, not an active schema

The eventual signed terms must use a new domain/schema version, not reinterpret market-command-v2. Select exact serialization after M0, 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 the supplied allocations by recomputation, not trust them because they are signed. A changed quote needs fresh authorization; callback status or later exchange-rate changes cannot amend it. No native-XMR signatures are generated by this increment.

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. No 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. Disable new old-version checkouts during the eventual cutover. Reserved/in-flight mock orders require an explicit drain/cancel policy before migration; do not relist their cards while an old obligation remains active. Auctions/bids require disposition; do not silently convert them to funded live bids.
4. Close old open listings through an audited versioned process. Sellers relist with fresh native-XMR terms and authorization. Preserve old records and references; do not delete receipt/idempotency history.
5. Keep live auctions disabled. New fixed-price routes/UI/storage must integrate exact amounts, selected settlement evidence, index/accounting/recovery controls and disclosures together. Public UI remains explicitly USD/mock until this delivery is tested.
6. Dry-run on disposable copies; compare immutable old records and signatures, assert no legacy record reaches a real processor, test every in-flight state, interruption/restart and rollback. Before external effects, rollback may restore the stopped-node copy. After any real external effect, a local DB rollback alone is unsafe: reconcile external history first and retain authoritative intents/events.

Acceptance remains open: actual versioned schema/signature tests, copied-data migration executable/dry run, UI review, recovery/invariant tests and approved fee/settlement semantics. 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 130 tests, 0 failures, 0 skips. Includes adjacent USD processor final-newline hardening. This evidence does not close the remaining M0/M1 integration and policy gates.