Marketplace documentation

docs/market-transparency.md

@@ -0,0 +1,143 @@
+# Market payments, buyer protections and seller protections
+
+**Read this before buying or delivering a card.** Trust should come from knowing what a market does, who controls it and where its protections stop—not from a promise that every trade is safe.
+
+## Current status: no real payments
+
+**The running Wikideck market is a testnet sandbox. It does not process real cryptocurrency payments.** XMR amounts, payment confirmations, fees, seller payouts and refunds are simulated. Checkout provides **no payable Monero address**. Do not send cryptocurrency to a host, author-fee address or address someone provides in a message to pay a sandbox order.
+
+**Card delivery is real on the selected blockchain.** When a seller signs delivery, they authorize an actual NFT transfer, even though the buyer only clicked a simulated-payment button. A `paid` or `mock-paid` label here is **not evidence of real money received**. Do not deliver valuable assets in exchange for mock payment.
+
+A separate offline SHKeeper prototype tests a possible future real-payment workflow. It is not connected to public checkout or the current market journal. There is no supported setting that enables live checkout today.
+
+## Who controls what?
+
+| Item | Controller and trust boundary |
+| --- | --- |
+| Your NFT signing key | Your local wallet. New/migrated local storage is password-encrypted; an unlocked tab can sign. Never give the host your password, backup or private key. |
+| A listed card | The seller keeps control until a signed transfer is mined. **Listing is not escrow** and does not lock the card on-chain. |
+| Confirmed card ownership | The selected network's canonical blockchain, subject to reorganizations. The browser trusts the connected node's reported chain; it is not an independent validating wallet. |
+| Listings, auction bids, reservations and orders | The particular hosting peer's local marketplace database. They are not replicated as blockchain consensus records or shared with every other market. |
+| Payment money today | No money is collected, held or sent by this release. Amounts are accounting simulations. |
+| Money in the proposed live design | The market operator's merchant wallet managed through SHKeeper would receive gross buyer payments and send net payouts. **That would be custodial**, not trustless escrow or a non-custodial exchange. It is not active. |
+
+Your NFT wallet address is not an XMR payment address. Sharing the RandomX algorithm with Monero does not merge the two networks, payments or security budgets.
+
+## What happens in today's checkout?
+
+### 1. Seller lists a card
+
+The seller reviews and signs the card, ownership sequence, price, sale format, auction deadline where applicable and hosting-fee rate. Listing/checkout signatures also bind the hardcoded author-fee policy and recipient. The node checks that the seller owns a sufficiently mature card at the current sequence and that no conflicting card transaction is pending. Only one active listing for that card is allowed **on that market host**, not globally across all hosts.
+
+The seller may cancel an available fixed-price listing. An auction cannot be cancelled after its first bid. The seller still controls the card and can transfer it elsewhere; subsequent checks can invalidate the listing. These checks reduce stale sales but cannot prevent a seller from breaking an off-chain promise.
+
+### 2. Buyer reserves the sale or wins an auction
+
+Fixed-price checkout reserves the local listing for **30 minutes from reservation**. An unpaid reservation expires and can reopen if the card is still eligible. A seller cannot cancel the reserved listing through the normal cancellation action.
+
+Auctions last one minute to 30 days. Bids are signed but **unfunded**; each bid must meet the opening price and exceed an existing highest bid by at least $0.01. The seller's own address cannot bid, but alternate-wallet shill bidding is not prevented. There are no funded bid deposits, identity checks or automatic nonpayment penalties.
+
+The auction winner must check out and complete mock payment within **30 minutes after auction close**, not 30 minutes after clicking checkout. Without bids the auction expires at closing. An unpaid winner causes expiry; there is no automatic runner-up sale. The seller can relist later.
+
+### 3. Buyer simulates payment
+
+The buyer sees the USD price, simulated gross XMR, host fee, author fee, seller net and payment deadline. The conversion is a configured test rate—**not a live market quote**. Quote amounts, fee allocations and delivery-confirmation requirements are stored with the order; later configuration changes do not silently reprice it.
+
+Only the order's buyer can sign **Simulate XMR payment**, and eligibility is checked again. This action changes an accounting status; it does not verify a Monero transaction or contact SHKeeper. Other users cannot mark the order paid through the normal participant-authorized API, but the buyer's signature alone never proves real payment.
+
+### 4. Seller reviews and signs delivery
+
+The seller must return to review the exact card, recipient and net proceeds. The market accepts only a valid seller transfer matching that order's card, seller, buyer and ownership sequence. The node validates the transfer under the chain rules. Submission means **pending**, not delivered.
+
+Seller delivery is due **48 hours after mock payment**. The node recognizes the exact agreed transfer if submitted through the marketplace, the normal transfer endpoint or peer gossip. Merely seeing the buyer hold some card is not the settlement criterion. Direct delivery without recorded mock payment is held for review rather than automatically paying the seller.
+
+The market never signs NFT delivery on the seller's behalf. Locking a wallet stops new session signing; it does **not** revoke an already issued signature or undo a mined transfer.
+
+### 5. Canonical delivery unlocks simulated payouts
+
+The market waits for the exact sale transfer to appear in the canonical chain at the order's required depth—**10 confirmations by default**, configurable for new orders. It then records the seller net and author-fee leg as `mock-paid`, with the hosting allocation retained in simulated host accounting. These are not XMR transaction receipts.
+
+No finite depth guarantees proof-of-work finality. If a reorganization removes or reduces the depth of an already settled transfer, the order enters **review** and is not paid a second time automatically. This prevents blind duplicate accounting; it does not recover money or reverse a transfer. An order's `review` state is not automatically cleared just because the chain later changes back.
+
+## Fees: who receives them and how much?
+
+| Allocation | Rate | Recipient / treatment |
+| --- | --- | --- |
+| Hosting fee | Operator-configurable, default **2.5%** | Hosting peer's market operator. Retained from gross proceeds in the intended merchant-wallet design. Currently simulated. |
+| Project author fee | Hardcoded **1%** in the distributed implementation | Fixed author XMR address below. Separate allocation/payout, currently simulated. |
+| Seller net | Gross minus both fees | Seller. Currently simulated; no XMR payout is sent. |
+
+Both fees are calculated independently from gross XMR, not compounded. They are deducted from seller proceeds, not secretly added to the buyer's listed price. At default rates a **0.100000000000 XMR** simulated sale allocates:
+
+- Host: **0.002500000000 XMR**.
+- Author: **0.001000000000 XMR**.
+- Seller: **0.096500000000 XMR**.
+
+The author recipient is:
+
+44xHcCdFhW4b951yBHpkTPdLSJ85qTCnFQ8N7m96TtqqRL3dbhzbEH4fe2SJ3a6ESHcNyzCYH5nYJ9ActR1JtkeA7QYGbQv
+
+**This is a payout recipient, not a checkout address.** Setting hosting fees to zero does not disable the author allocation. Checksum verification does not prove recipient ownership. The author fee is source-level policy, not a guarantee that every independently modified host runs the same release; verify the host and its disclosed terms.
+
+USD values use integer cents. XMR uses 12-decimal atomic units. Simulated gross is rounded up to an atomic unit; each fee is rounded down separately; net is exactly gross minus both fees. A fee below one atomic unit rounds to zero. Existing orders retain their agreed accounting, including legacy orders predating the author fee. Old open listings lacking the current policy must be relisted with fresh authorization.
+
+Fees apply to completed marketplace sales—not listing creation, auction bids, free NFT transfers or card-for-card trades. Failed/expired/refunded orders do not produce successful payout accounting. There is **no finalized live processor/network-fee or refund-cost policy**; one must be disclosed before real payments are enabled. The test numbers are not a promise about future all-in costs.
+
+## What if something goes wrong?
+
+| Situation | Current behavior | What is not guaranteed |
+| --- | --- | --- |
+| Buyer does not pay | Reservation or winner payment window expires; eligible fixed listings reopen; auctions expire. | Funded bid enforcement, penalties or a guaranteed replacement buyer. |
+| Seller transfers the card elsewhere | Ownership/sequence/pending checks can invalidate the listing or put a paid order into `refund-required`. | An on-chain card lock, automatic replacement or compensation. |
+| Seller does not deliver | After the delivery deadline, an order without an exact pending/canonical delivery may become `refund-required`. | A real cash refund or an operator response deadline. |
+| Exact sale transfer is still pending | The deadline alone does not authorize a refund while that transfer remains pending. | A maximum mining time; network congestion/stalls can prolong the wait. |
+| Buyer requests a mock refund | Only the buyer can act, and only in `refund-required`, with no pending card transaction and no exact canonical delivery. The journal records `refunded` and cancels the listing. | A real cryptocurrency refund, cancellation of existing signatures, or future delivery prevention. |
+| Delivery is reorged after settlement | Hold for review; no automatic second payout. | Finality, rollback of payouts or loss insurance. |
+| Host becomes unavailable | Local orders and reconciliation wait until the host recovers. The chain may keep operating elsewhere. | Order portability, replication to another market or a project-run recovery service. |
+| Request times out | Outcome may be unknown; inspect refreshed activity before signing a new action. Replays of the same signed nonce return its stored result where applicable. | That timeout means failure, or that a new nonce cannot create a new action. |
+| Wrong address or compromised key | Valid signatures can transfer cards; verify recipients and protect backups. | Chargebacks, key resets or reversal of confirmed ownership. |
+
+**A refund check cannot revoke a signed NFT transfer.** A delayed transaction can arrive later, including after a reorganization or a proposed refund. No automatic real-money refund mechanism solves that risk here. This is one reason live settlement remains disabled.
+
+There is currently **no built-in arbitration service, buyer insurance, chargeback system, guaranteed reimbursement, operator override/payment-recovery endpoint, or dispute-resolution SLA**. A `review` label means investigation is needed—not that a resolver or repayment fund exists. Do not infer those protections from words such as “market,” “confirmation” or “settlement.”
+
+## What the offline SHKeeper prototype demonstrates—not a live promise
+
+The proposed flow would have the buyer pay gross XMR into the operator's merchant wallet, the host verify it using SHKeeper, the seller sign NFT delivery, and the host pay the seller net plus the separate author allocation after canonical delivery checks. This temporarily entrusts funds to the operator and its processor administration. SHKeeper does not by itself guarantee that a seller delivers or that an operator honors a refund.
+
+The disconnected prototype tests:
+
+- Seller-signed payout destination and buyer-signed exact invoice amount/address/expiry and fee allocations.
+- Authoritative invoice lookup rather than trusting a browser claim or callback `paid` flag; matching currency, amount, destination, unique incoming transactions and confirmed status.
+- Waiting on partial/unconfirmed payment; holding late, overpaid, contradictory or changed evidence for review.
+- Recording payout intent durably **before** sending a payout request. A lost response may mean money was sent; ambiguous requests are not blindly retried.
+- Tracking separate seller/author payout tasks. Seller success followed by fee failure preserves the completed seller leg rather than paying it again. Known task IDs can be polled without creating another payout.
+
+This is fake-processor test evidence, **not** a deployed SHKeeper contract verification, functioning buyer-protection service or live-fund recovery system. No real Monero confirmation threshold, reserve/hold duration, refund rules or dispute policy has been approved. The prototype's journal is separate from production market backups. See [technical prototype and activation holds](shkeeper-settlement.md).
+
+## Privacy, evidence and host accountability
+
+Public listings reveal seller/highest-bidder wallet addresses, card IDs, prices and auction state. Participant activity requires a wallet signature through the application, but **the hosting operator and anyone with its database/backups can read orders, counterparties and amounts**. The host can also observe network requests. An eventual XMR payment would not make this application-level activity anonymous. Never send seed phrases, private keys, passwords or complete wallet backups to a market/support operator.
+
+The market uses signed actions, short request expiry, stored nonce receipts, serialized mutations and SQLite transactions to reduce unauthorized actions, accidental replay and inconsistent updates. These controls do not make the operator's database tamper-proof. Card ownership/transfer records are on-chain; order terms, payment simulation and payout markers are not blockchain-enforced. The browser still relies on its connected host to report them honestly.
+
+Before any future live market can earn trust, its operator must publish:
+
+- Operator identity/contact and which domain, network/chain and software release it runs; any local modifications and responsibility for the merchant wallet.
+- Clear live-versus-test status, supported currency, exact quote/expiry and fee policy, payment-confirmation requirements and disclosure of custodial control.
+- Seller delivery terms, payment/payout holds, network/processor costs, cancellation/late/partial/overpayment treatment, refund eligibility/costs and who bears reorg or processor losses.
+- A workable dispute/reconciliation process with evidence requirements and actual response targets, including ambiguous payouts and partial success. Do not invent a support address or SLA before it exists.
+- Privacy/retention policy, operational monitoring, consistent off-host backup/restore evidence, incident communication and independent security-review evidence.
+
+Those are **requirements for a future offering**, not assurances already fulfilled by this project or every peer. The project author fee does not make the author the guarantor, custodian or arbitrator of independently hosted markets.
+
+## A practical checklist for users
+
+1. Check the host's domain, chain and **mock/live status**. Today's release is mock-only: do not pay real XMR.
+2. Review the exact card ID, counterparty, USD price, displayed XMR, both fees, net proceeds and deadlines before signing.
+3. Keep the order/listing ID, host origin, agreed terms, status and NFT transfer identity for your records. A screenshot or status label is not independently verified proof of payment; never include secret keys/passwords in evidence.
+4. Use **Your activity** on the same market host to inspect progress. Confirmations refer to canonical inclusion, not a money guarantee. Refresh after a timeout; contact the actual host through a verified channel if one is published.
+5. Sellers: never equate a simulated or buyer-supplied receipt with real payment. Buyers: do not assume an off-chain reservation locks the card or guarantees a refund.
+6. Protect and test your [wallet backups](wallet-security.md). If you cannot accept the host/custody/reorg risks, do not transact with valuable assets.
+
+For operational details see [market rules](marketplace.md), [security findings](security-review.md) and [backup/recovery boundaries](operations-recovery.md). These disclosures describe the current implementation; future live features require an updated policy and explicit review before use.

docs/marketplace.md

@@ -1,5 +1,7 @@
 # Peer-hosted markets
 
+**Before buying or delivering:** read [Market payments, buyer protections and seller protections](market-transparency.md) 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](../README.md#peer-ownership-and-customization).

docs/shkeeper-settlement.md

@@ -1,5 +1,7 @@
 # SHKeeper integration prototype — stage 5, disabled
 
+For the participant-facing explanation of what is protected today and what is not, see [Market payment transparency](market-transparency.md). This technical prototype does not create a live buyer-protection, refund or arbitration service.
+
 **This is an offline, fixture-only implementation, not live checkout.** The running marketplace remains mock-only on every profile. `paymentMode` still rejects non-mock settings, `createLiveProcessor()` always throws, and mainnet/production approval gates remain unchanged. No real invoice, callback, payout, refund or credential exchange was performed. The operator-provided SHKeeper instance was **not contacted**. Only the public API documentation was read.
 
 ## What is implemented