wikideck/docs/market-transparency.md

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.

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. If you cannot accept the host/custody/reorg risks, do not transact with valuable assets.

For operational details see market rules, security findings and backup/recovery boundaries. These disclosures describe the current implementation; future live features require an updated policy and explicit review before use.