wikideck/docs/marketplace.md

Peer-hosted markets

Before buying or delivering: read Market payments, buyer protections and seller protections for the complete flow, host/author fees, custody model, refund limits, privacy and dispute responsibilities. Today's payments are simulated; NFT delivery is real. The market is not trustless escrow and does not provide guaranteed reimbursement or arbitration.

Every Wikideck peer can host its own market for cards on the shared NFT blockchain. A host can serve collectors broadly or build a community around a particular collection, theme or subject. Card ownership and confirmed transfers follow the shared chain; each host keeps its own listings, bids and order journal. Buyers and sellers must use the same host to complete a sale.

The current market provides fixed-price sales and timed auctions. Running a collection-focused community is possible today, but built-in collection-specific admission, moderation and curation controls are not implemented. Peer-hosted custom trading card games are also planned, not available yet. Operators can adapt the source and presentation subject to licensing; the project still needs a published software license before open-source reuse rights can be claimed. See project direction and licensing.

Cryptocurrency payments and the two sale fees

New marketplace terms use native XMR prices represented exactly in atomic units (12 decimal places). There is no USD conversion, exchange-rate field or live payment route. Historical version-2 USD orders remain in their original currency and signatures; USD listings are read-only until the seller closes them and signs a fresh XMR listing. Mining and payments are separate: RandomX secures Wikideck's own blockchain, while any future XMR settlement would use Monero.

Each sale allocates a configurable hosting fee to the peer's market operator (default 2.5%) plus a hardcoded 1% author fee to the project author's fixed XMR address. Both are deducted from the seller's gross proceeds, not compounded or secretly added to the buyer price. At the default rates the seller keeps 96.5% before any future disclosed processor/network-fee policy. The host retains the hosting allocation; the author allocation is a separate payout. All allocations and payouts are currently simulated.

Current testnet sandbox

Open Marketplace in the interface. New prices and checkout amounts are XMR-native; fees, refunds, and automatic seller payouts are simulated. Historical USD orders are explicitly labeled. There is no payable address, payment processor connection, or movement of real Monero in this release. No exchange rate is applied. Signing delivery transfers the actual card on the selected chain, even though payment is mocked.

Try a sale

1. Mine enough blocks to own a mature NFT. Open Marketplace → Sell a card.
2. Choose a card, a fixed price or timed auction, and review the seller fee before signing.
3. In a different browser profile/wallet on the same marketplace node, buy the fixed-price listing, or bid and wait for the auction to close.
4. Open Your activity as the buyer, review the order, and choose Simulate XMR payment.
5. Return as the seller, review the buyer/card/proceeds, and Sign and confirm delivery. This creates an ordinary signed NFT transfer; mine it into the canonical chain.
6. After the order's required confirmation depth, reconciliation records automatic mock-paid seller and additional-fee payouts. The configured market fee is retained in the simulated accounting. No operator payout click is needed.

Wallet backup/recovery remains local; never send private keys or backup passwords to the node. A Wikideck NFT wallet is not a Monero wallet.

Sale rules

• Fixed price: stays listed until sold, cancelled, or invalidated by changing ownership/sequence. Checkout exclusively reserves it for 30 minutes; an unpaid reservation expires and the listing reopens if still valid.
• Auction: one minute to 30 days in the sandbox. Bids must meet the start price and exceed the highest bid by at least one atomic unit. Bids are signed but unfunded. Sellers cannot bid on their own auction or cancel after its first bid. This does not prevent alternate-wallet shill bidding or nonpayment. Live auctions remain a separate unreleased gate.
• No bids are accepted at or after the deadline. If there are bids, the listing remains available only for winner checkout until 30 minutes after auction close, not 30 minutes after checkout. With no bids it expires at closing. An unpaid winner causes expiry; there is no automatic runner-up sale. The seller may relist.
• Seller delivery is due 48 hours after mock payment. Failed delivery can enter refund-required. The buyer can simulate a full refund only if the sale transfer is neither pending nor canonical. Pending/late/ambiguous delivery requires review, not an automatic refund that might also release the card.
• Listings are not consensus escrow: they do not lock cards on-chain. A seller can transfer or trade elsewhere; availability is rechecked when listing, reserving, paying, and reconciling delivery. Payment and NFT delivery are not an atomic cross-chain exchange.
• Fee basis points are fixed when the seller lists and explicitly reviewed at checkout. The XMR quote, fee, net, and delivery-confirmation requirement are pinned to the order. Changing configuration does not reprice an existing order.
• Settlement matches the exact canonical transfer identity, not merely the buyer's current holdings. Unconfirmed submission never counts as delivery. A buyer may transfer onward after delivery without confusing its identity.
• If a reorganization affects an already settled order, it enters review permanently and does not auto-pay again. The operator must investigate; this sandbox has no administrative recovery/payment override endpoint.

New sale prices use canonical atomic-unit strings and integer arithmetic; JSON/signature payloads never use floating-point XMR. Each fee rounds down independently; seller net is gross minus both allocations. No economic listing minimum is imposed. Historical USD records retain original cents and are never converted or repriced.

Configuration

Variable	Default	Meaning
WIKIDECK_PAYMENT_MODE	mock	Only accepted value. Other values fail startup, including on the mainnet candidate.
WIKIDECK_MARKET_FEE_BPS	250	Seller fee: 250 basis points = 2.5%; integer 0–5000.
WIKIDECK_MARKET_CONFIRMATIONS	10	Canonical delivery confirmations before simulated payout; integer 2–1000. No finite depth guarantees PoW finality.

The single-node and three-node testnet Compose configurations pass these hosting-fee and delivery-confirmation settings. Choose one market host and use its origin consistently. Node marketplaces have different identities and journals: listing, bid, checkout, and order state are not gossiped. NFT transfers/blocks are. Buyers and sellers must use the same market host.

New listings, bids, and checkout store native XMR atomic-unit amounts (12 decimal places); they are not derived from fiat. Historical v2 records retain USD cents and their originally snapshotted mock XMR amounts. The application bound on newly entered atomic gross is documented in the amount domain specification; it is not a wallet-balance or exposure approval.

Hardcoded 1% project author fee

Every new marketplace sale (fixed price or winning auction) includes a hardcoded 1% project author fee, on top of the configurable fee for the hosting peer's operator. Both fees are calculated independently on gross sale proceeds, not compounded. At the default 2.5% hosting fee the combined deduction is 3.5%. Setting the hosting fee to zero does not disable the author fee.

The fixed public XMR payout recipient is:

44xHcCdFhW4b951yBHpkTPdLSJ85qTCnFQ8N7m96TtqqRL3dbhzbEH4fe2SJ3a6ESHcNyzCYH5nYJ9ActR1JtkeA7QYGbQv

This is a payout destination, not a buyer checkout address. Do not send real XMR to it to pay for a sandbox order. No real transfer is submitted; the journal only records a simulated fee allocation and payout after canonical NFT delivery. Both seller and additional-fee payouts enter review if a settled delivery is reorganized. Refunded or expired sales do not pay either recipient. The fee applies to marketplace sales, not free NFT transfers, card-for-card trades, bids or listing creation, which have no XMR sale proceeds.

The additional fee is rounded down to an atomic unit separately from the hosting fee. Seller net is exactly gross minus both fees. For example, a 0.1 XMR sale with 2.5% hosting allocates 0.0025 XMR hosting fee, 0.001 XMR additional fee, and 0.0965 XMR seller net. Rounding below one atomic unit produces zero rather than increasing the charge above 1%.

The recipient and percentage are snapshotted into each new order and disclosed in the UI. They are bound to v3 listing/checkout signatures and are neither environment-configurable nor request-overridable. Existing reserved/paid/completed v2 orders are not retroactively repriced. Open USD listings remain read-only until eligible sellers close them and relist with fresh v3 XMR authorization; historical bids are not converted. The v2 domain remains for compatibility with historical orders and receipts; new USD listings, bids, and checkout are rejected.

API and storage

• GET /api/market?offset=0 returns up to 24 public listings, pagination, server clock, fee policy, and market identity.
• POST /api/market/command accepts strict, signed commands. New XMR terms use market-command-v3; historical market-command-v2 is retained only to service existing orders and eligible seller cancellation. Actions include list, bid, buy, cancel, retire-legacy-listing, mock-pay, deliver, refund, and activity under their allowed version.
• Every command binds the network, chain ID, market instance ID, actor/public key, UUID nonce, short expiry, action, and all versioned terms. New prices sign the currency and canonical atomic XMR gross. Private activity requires a wallet signature and includes only orders involving that actor. Signed requests expire within five minutes; keep clocks synchronized.
• Nonce receipts are persisted and replay returns the same result. A different command cannot reuse that nonce. Refresh activity to obtain the latest order state rather than interpreting an old receipt as current state.
• Public listings reveal seller/highest bidder wallet addresses and card holdings. Orders reveal counterparties/amounts only to their participants, but the market operator and its database backups can see all orders. This is not private Monero trading.
• The marketplace journal is stored alongside the ledger in the selected network subdirectory, uses SQLite/WAL and full synchronous commits, and binds its metadata to the active chain. Mutations are serialized. There is one active local listing per card, at most 100 active listings per seller, and 10,000 total listings/orders per journal. Reaching a journal cap fails closed; operator archival work is required, not deleting active records.
• HTTP rate limits and bounded mutation queues apply. Read/reconciliation work still scans the bounded journal and chain; this is not a high-volume production market.

Recovery and operations

Back up the ledger, marketplace SQLite databases and their WAL state consistently, plus the independent wallet backups. Prefer a clean node shutdown before copying the data directory; do not copy a live SQLite file without SQLite's backup facilities. Do not delete the journal to clear a stuck order: this loses reservations, invoice identities and idempotency history.

The service writes delivery intent before submitting to the ledger. A crash between these steps is reconciled by deterministic transfer ID; the seller can resubmit the same delivery if still valid. Background reconciliation runs every 15 seconds, and marketplace commands reconcile before mutation. A closed server does not send payouts or advance its local journal until restarted; deadline enforcement still uses absolute timestamps.

Canonical and pending sale delivery is recognized by the agreed seller/buyer/card/sequence even if submitted through the normal transfer endpoint or peer gossip rather than the marketplace command. Direct delivery without a recorded mock payment enters review instead of paying the seller. A refund check cannot cancel a previously signed transfer that arrives later or after a reorganization; this is a production settlement blocker, not a solved atomic-exchange guarantee.

For review, preserve backups and inspect canonical blocks, pending transfers, signed order terms and transfer ID. Do not clear a payout marker, auto-refund, or blindly resubmit a payout. This release intentionally has no real-fund recovery controls.

SHKeeper production boundary

The intended future live processor is SHKeeper, using the operator-provided instance at https://shkeeper.eom.dev/. It is not contacted or configured by this sandbox; no live adapter is enabled. Stage 5 adds an offline wire-contract and durable settlement prototype with fake-transport tests, separate from the running marketplace. Its live factory always refuses activation. Do not supply payment credentials yet. No secret belongs in browser build variables, source, or version-controlled Compose files.

The offline SHKeeper harness still models the provider's documented USD-denominated invoice input. It is disconnected from the native-XMR market and therefore is not currently compatible with exact XMR-native pricing. Do not hide a USD conversion behind an XMR price. Seller payouts use a separate Basic-authenticated XMR payout endpoint; the merchant wallet would receive gross funds and the operator would temporarily custody funds. Native-XMR invoice capability and settlement architecture remain unverified; no processor path is selected or enabled.

Live settlement needs a separate implementation and review, after a reviewed production network exists:

• Authoritative server-to-server verification of invoice identity, XMR currency, address, amount, confirmation policy and settled status. Never trust an unsigned callback's paid field; treat callbacks only as bounded reconciliation hints.
• Stored quote expiry, payment deadlines and explicit rules for late, partial, duplicate and overpayments, seller refusal/non-delivery, and refunds.
• Validated seller XMR payout destinations, server-only secret storage, fixed HTTPS processor origin, no redirects, bounded timeouts/responses, and least-privilege credentials.
• Durable payout intents and task reconciliation for both seller net and the fixed 1% recipient, including partial success across these separate payouts. The documented payout create endpoint does not expose a merchant idempotency key; a timeout or crash after submission is ambiguous and must not trigger blind retry/double payout.
• Reorg holds/reserves, operator reconciliation tools, tested backup/restore, dispute/refund procedures, and applicable custody/payment obligations. Confirmation depth alone does not make a small PoW network safe for real money.

There is deliberately no environment switch that bypasses these missing protections.