wikideck/docs/settlement-feasibility.md

# 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.