XMR native

docs/production-plan.md

@@ -28,7 +28,7 @@ The design must specify what every validator can verify deterministically, which
 
 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. **Whether such preparatory transactions are acceptable needs explicit confirmation** before implementing escrow. If no preparatory transaction is permitted, research must assess how seller availability and duplicate-sale prevention can work within that constraint.
+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)
 
@@ -136,6 +136,8 @@ Acceptance: signed release evidence packet; recorded unresolved accepted risks w
 
 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.
 
+First increment status: [M0 source-grounded investigation/threat model](settlement-feasibility.md) and [M1 amount/migration specification](xmr-domain.md) recorded. Shared exact amount and commission primitives are reused by existing mock/processor-lab callers; no native-XMR public marketplace migration, approved exchange protocol or live payment integration is claimed. Both milestones remain open against their full acceptance criteria.
+
 ## 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.
@@ -156,7 +158,7 @@ Not every value is needed to begin engineering; each becomes a blocking decision
 
 | Decision | Needed by | Why |
 | --- | --- | --- |
-| Allow on-chain pre-payment NFT lock/reservation records without completed ownership transfer? | M0 | Determines viable anti-double-sale/escrow designs and interpretation of payment-first ordering. |
+| 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. |

docs/settlement-feasibility.md

@@ -0,0 +1,71 @@
+# ADR 001 — XMR/NFT settlement feasibility investigation
+
+Status: **proposed; research checkpoint, not an approved exchange protocol**. Source review: 2026-10-20. Related: [production plan](production-plan.md). No processor instance, credentials, wallet or funds were accessed. No swap implementation was installed or run.
+
+## Decisions and recommendation
+
+- Operator approved preparatory on-chain NFT locks/reservations for design research. They must not transfer completed-sale ownership before the agreed XMR condition. This does **not** approve a custodian, lock authority, timeout or new consensus rule.
+- Continue research into an NFT-first, XMR-compatible conditional exchange. Do not port Bitcoin swap code as though Wikideck were Bitcoin. Current transfers cannot implement the researched protocol.
+- No practical reviewed Wikideck-compatible trustless design has yet been demonstrated. This is an evidence gap, **not a proof of impossibility**. M0 remains open pending protocol specification, disposable-fixture spike, failure tests, specialist review and operator approval.
+- Do not connect SHKeeper or replace trustless exchange with host attestation/custody by default. If the researched route fails its gates, return for explicit fallback approval.
+
+## Evidence and compatibility boundaries
+
+| Source | Obtained evidence | Implication / unresolved work |
+| --- | --- | --- |
+| [Hoenisch / Soriano del Pino, 2021, v2, sections 3–4](https://arxiv.org/html/2101.12332v2) | Section 3 describes Bitcoin lock/redeem/cancel/refund/punish transactions, adaptor signatures and cross-curve discrete-log equality proofs. Monero is funded into a shared-key output after Bitcoin is locked. Timely chain observation and reaction matter. Section 4 explicitly describes further work, not a completed proof/implementation of its alternative. | Potential structure for NFT-first research, not a ready-made NFT exchange. Cross-curve proof and adaptor implementations must match the chosen curves. Never infer current Monero capabilities solely from a 2021 proposal. |
+| [COMIT upstream](https://github.com/comit-network/xmr-btc-swap) | Archived/unmaintained; README points to eigenwallet and warns of incompatible peer changes. README states its cryptography was not formally audited. GPL-3.0. | Do not adopt archived upstream as a production dependency. Its historical direction/limitations are not proof of current feasibility or impossibility. |
+| [eigenwallet core](https://github.com/eigenwallet/core) | Public successor has ongoing development and a visible 4.16.1 release; describes a Monero–Bitcoin DEX. Repository displayed commit e77e2ecb1ffe43891c06ab2cdb2100a72d2f7aa0 during this review; GPL-3.0. | Maintenance/release evidence only. Not an audit, arbitrary-NFT support or P-256 compatibility evidence. Any reuse needs a pinned version, dependency/license review and review of the actual selected protocol implementation. No audit artifact was evaluated here. |
+| [Monero wallet RPC: check_tx_proof / check_tx_key](https://docs.getmonero.org/rpc-library/wallet-rpc/#check_tx_proof) | Reports proof validity, recipient amount, in-pool status and confirmations; explicitly warns that proofs do not guarantee spendability (locked, already spent or duplicated/burnt one-time outputs). | A valid proof/txid is not by itself a release condition. Define exact output validity, order binding, chain evidence, confirmation and unlock semantics. Merely requiring that funds remain unspent after a seller legitimately spends them would also be incorrect. |
+| [Monero wallet RPC: transfer](https://docs.getmonero.org/rpc-library/wallet-rpc/#transfer) | Supports multiple recipients and atomic-unit amounts; warns against subtracting fees from outputs when exact recipient amounts are required. | Native wallet multi-recipient capability is not the same as SHKeeper multi-payout support and does not make NFT exchange atomic. Amounts need lossless JSON encoding, not conversion to JavaScript Number. |
+| [SHKeeper API 2.1.47](https://shkeeper.io/api/) | Documented invoice creation accepts USD fiat amounts; returns converted crypto amounts. XMR multipayout unsupported. Payout fee input is priority, not an atomic cost cap. | Exact native-XMR invoice and bounded-fee guarantees remain unverified. No hidden USD conversion. Processor status is trusted external observation, not deterministic consensus evidence. |
+
+The initial Monero atomic-swaps glossary URL returned 404 and is not relied upon. Sources above are primary project/paper documentation, not independent certification. Their live pages can change; a release decision needs archived/pinned evidence against actual dependencies.
+
+### What Wikideck lacks today
+
+[Current transaction types](../shared/testnet.ts) implement ordinary P-256 ECDSA transfers and signed two-party card trades. There is no sale lock, expiry/revocation, conditional witness, payment evidence or cancel/refund branch. An ordinary signed transfer can be submitted later; an off-chain database reservation cannot stop a valid conflicting chain transfer.
+
+Bitcoin's secp256k1 transaction graph, witness rules and timelocks cannot be assumed from the fact that Wikideck also uses ECDSA. P-256 is a different curve. Adding another per-sale cryptographic key scheme might be an alternative to changing wallet identity, but neither is selected. The NFT's uniqueness and absence of a fungible settlement asset also change the economic meaning of the paper's punishment paths.
+
+Most importantly, the paper's participants observe Monero before cooperating; that is not a light client inside every validator. A signature may establish one party's authorization or reveal a secret without proving the full XMR payment condition to consensus. The operator's requirement that completed-sale inclusion require confirmed payment needs a separate explicit guarantee: is this validator-enforced Monero evidence, or participant-verified conditional authorization? Do not conflate them.
+
+Mining remains roughly one card per 15-minute Wikideck block. Preparatory-lock inclusion, Monero funding confirmation/unlock, completed-sale inclusion, Wikideck depth, and any Monero withdrawal are separate milestones. Either chain may stall; no numerical threshold or recovery latency is approved here.
+
+## Options under investigation
+
+| Route | Possible guarantee | Named assumptions and release blockers |
+| --- | --- | --- |
+| Conditional NFT-first adaptor/shared-key exchange | Potential atomic control exchange without host custody under stated protocol assumptions | Requires new NFT lock/redeem/cancel rules, compatible reviewed cryptography and keys, both-chain reorg/timing analysis, recoverable secrets and funded fee handling. Payment-to-conditional-output versus seller-net-direct semantics unresolved. Participant observations alone are not global payment-proof validation. |
+| Deterministic Monero evidence/light client | Validators could evaluate a precisely specified payment condition | Need canonical Monero chain selection/work/difficulty/upgrade verification, recipient/amount/output evidence, privacy disclosures, reorg handling and resource bounds. A header/txid or successful wallet-RPC response alone is insufficient. Not implemented or established feasible in scope. |
+| Host/committee attestation | Deterministic verification of an authorized signature | Verifies what an attestor asserted, not Monero truth. Theft/censorship/key compromise and cross-host trust remain. Not trustless; explicit approval required. |
+| Host custody plus chain-enforced lock | Coordinated payment/disbursement and refunds under an accountable host | Host can lose/steal/freeze XMR; lock releaser can censor or misrelease depending on rules. Requires explicit fallback approval, legal/policy/reserve controls and full journal/recovery design. Not selected. |
+
+## Threat model and required failure evidence
+
+Assets: NFT ownership/availability, buyer gross payment, seller proceeds, host/author allocations, refund liabilities, wallet/conditional secrets, order privacy and durable recovery evidence. Independent hosts, miners, relayers, processors and user wallets are separate trust boundaries. An author commission does not underwrite hosts.
+
+| Adversary / failure | Required invariant and test before acceptance |
+| --- | --- |
+| Dishonest seller, duplicate listings across hosts, stale signatures | A canonical lock excludes conflicting spends under the selected rules. Exact card sequence/order/network/market binding; cancelled or expired authorizations cannot revive. Race tests at every boundary. |
+| Dishonest buyer, late/partial/duplicate/overpayment | No NFT release for inadequate or misbound evidence; no reuse of one funded output across sales. Define legitimate incoming liabilities instead of discarding late funds. No refund plus later successful delivery. |
+| Buyer aborts after seller locks; Sybil reservation spam | Explicit bounded liveness/cost exposure without assuming a wallet is a person. Quantify locking/griefing costs; no unapproved deposit requirement. |
+| Dishonest host/relayer/processor or compromised authorization key | Forged observations do not bypass selected validity rules. Document which roles can steal, censor or lock funds/assets. Sender identity and authenticated transport are not economic truth. |
+| Miner censorship, eclipse, partition, stalled chain | Deadline safety margins must cover publication/confirmation and observation assumptions. Secret publication in a losing transaction or mempool can be irreversible even when NFT inclusion fails. Test cancel/redeem races. |
+| Reorg of either chain, including after payout/release | Explicit finality and residual-loss model. Never silently repay after an ambiguous send or infer that a local restore reverses XMR. Reorg tests before/after each critical action. |
+| Fee spikes, dust and separately paid author leg | No rounding up sub-atomic commissions; no unapproved subsidy/balance accumulation. Pre-payment viability plus approved fee cap and overrun behavior; partial-success accounting. |
+| Key loss, crash or malicious recovery operator | Required refund/redeem data survives authorized restore. Unknown external effects stay quarantined. No manual journal reset creates duplicate sends; public-chain replay alone cannot recover all wallet metadata. |
+| Disputed or replayed terms | Versioned canonical terms bind price/currency, all destinations, commissions, cost caps, expiry, parties, card sequence and selected protocol. Negative signature/replay tests across market/network/order versions. |
+
+### Fee enforcement limit
+
+Fixed host and 1% author allocations can be signed and validated for the selected sale protocol, but ordinary free transfers already exist. Parties can exchange XMR off-platform and submit a nominal gift unless new protocol policy prevents it; modifiable peers can also fork policy. Do not claim universal royalty enforcement or infer the value of off-chain consideration. The commission rule for recognized sales and treatment of alternate transfers must be reviewed explicitly.
+
+## Next decision gates
+
+1. Specify whether the confirmed payment is gross funding of a conditional structure or seller net directly, and whether every validator must verify Monero evidence rather than only selected participants doing so. Present concrete choices and privacy/liveness costs before seeking approval.
+2. Map each required NFT-first transition and secret exposure to current maintained protocol/reference behavior; identify compatible crypto libraries, audit artifacts and licenses. No hand-written cryptographic substitute.
+3. Build only a disposable, offline protocol/state-model spike after selecting its exact assumptions. Include abort, timeout, mempool leak, double-lock, reorg and recovery counterexamples; a happy-path demo cannot close M0.
+4. Obtain specialist cryptographic/consensus review and operator ADR approval before any versioned consensus implementation. If no practical reviewed route meets requirements, request custodial/attested fallback approval with its explicit guarantees and liabilities.
+
+No lock code, consensus version change, production migration or payment activation is authorized by this research checkpoint.

docs/xmr-domain.md

@@ -0,0 +1,57 @@
+# 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](production-plan.md) and [settlement investigation](settlement-feasibility.md).
+
+## Implemented amount contract
+
+[Shared amount primitives](../shared/xmr-amount.ts) 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](../shared/xmr-pricing.ts) 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](../shared/market.ts).
+
+`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](../tests/xmr-amount.test.ts) 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.