Removed SHKeeper
This commit is contained in:
@@ -132,7 +132,7 @@ No hidden withdrawal minimum or flat fee. Baseline: exact recipient amount plus
|
||||
|
||||
## 10. Integration and staged acceptance
|
||||
|
||||
Reuse [exact XMR amounts](../shared/xmr-amount.ts), [pricing splits](../shared/xmr-pricing.ts), [v3 mock domain](../shared/market-v3.ts) and receipt concepts in [market store](../server/market/store.ts). The [settlement lab](../server/market/settlement-lab.ts) provides failure-journal ideas only: its USD invoice and per-order external payout assumptions are not this balance model. Prefer direct pinned Monero wallet/daemon infrastructure for the first custody adapter; SHKeeper is not the customer-liability ledger and its documented USD invoicing is not needed for account deposits. No adapter is connected by this proposal.
|
||||
Reuse [exact XMR amounts](../shared/xmr-amount.ts), [pricing splits](../shared/xmr-pricing.ts), [v3 mock domain](../shared/market-v3.ts) and receipt concepts in [market store](../server/market/store.ts). There is no connected live payment adapter. The selected implementation path is direct pinned Monero wallet/daemon observation for deposits, a pooled PostgreSQL liability ledger, and an isolated, policy-constrained treasury signer for withdrawals; each component requires production integration and review before funds are accepted.
|
||||
|
||||
1. **Approve scope and economics:** custodian identity, custody disclosure, account recovery, beneficiary enrollment, withdrawal/author fee policy, balance accumulation, loss/reserve obligations and numerical risk/confirmation/hold policies. These remain open; no fabricated thresholds or support SLA.
|
||||
2. **Offline financial model:** property-test conservation, nonnegative available balances, concurrency, replay, output deduplication, tiny amounts, duplicate workers, crash at every journal/outbox boundary and repeat restoration. Keep mocks isolated; no mock balances become real opening liabilities.
|
||||
|
||||
@@ -54,4 +54,4 @@ Unknown profile names fail closed. A direct import of the HTTP entry point is al
|
||||
|
||||
This remains experimental software. Nodes retain the DAG and overlays in memory, rebuild state roots over the full NFT set, and revalidate proofs at startup. The HTTP UI trusts its connected node rather than independently validating the chain. There is no automatic peer discovery, established bootstrap infrastructure, formal finality, independent audit, built-in anti-shill mechanism or production abuse system. The marketplace is node-local, not consensus escrow. Mainnet selection does not remove any of these limitations.
|
||||
|
||||
See [marketplace sandbox and future SHKeeper boundary](marketplace.md) for the mock settlement model and the additional work required before any real XMR can be accepted or paid out.
|
||||
See [marketplace sandbox and future live-custody boundary](marketplace.md) for the mock settlement model and the additional work required before any real XMR can be accepted or paid out.
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
|
||||
**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.
|
||||
There is no live payment integration or supported setting that enables live checkout today.
|
||||
|
||||
## Who controls what?
|
||||
|
||||
@@ -19,7 +19,7 @@ A separate offline SHKeeper prototype tests a possible future real-payment workf
|
||||
| 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. |
|
||||
| Money in the proposed live design | The selected direction is a pooled Monero treasury and internal liability ledger controlled by the market operator. **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.
|
||||
|
||||
@@ -43,7 +43,7 @@ The auction winner must check out and complete mock payment within **30 minutes
|
||||
|
||||
For a new version-3 order, the buyer sees the exact signed XMR gross, host fee, author fee, seller net and payment deadline. No USD conversion or exchange rate is applied. Legacy version-2 USD orders retain their previously signed USD price and snapshotted mock-XMR quote; they are not reinterpreted as XMR. Quote amounts, fee allocations and delivery-confirmation requirements remain stored with each order.
|
||||
|
||||
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.
|
||||
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. 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
|
||||
|
||||
@@ -101,19 +101,9 @@ Fees apply to completed marketplace sales—not listing creation, auction bids,
|
||||
|
||||
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
|
||||
## Future live custody is not active
|
||||
|
||||
The earlier disconnected prototype modeled a USD-denominated SHKeeper invoice, gross XMR into an operator merchant wallet, seller-signed NFT delivery, then operator payout of seller net and the separate author allocation. This would temporarily entrust 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. This USD invoice prototype is **not connected to the new native-XMR marketplace** and must not be silently used to convert its prices; any future processor path requires verified exact-XMR capability or a separately approved architecture.
|
||||
|
||||
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).
|
||||
The intended direction is direct wallet/daemon observation into a pooled liability ledger; it does not depend on a third-party invoice processor. That future flow is not implemented end-to-end. There is no customer-facing deposit route, automatic customer credit, treasury withdrawal service, or real sale settlement. No confirmation threshold, funded reserve, loss allocation, refund policy or dispute process has been approved. This document describes current behavior and does not promise future buyer protection.
|
||||
|
||||
## Privacy, evidence and host accountability
|
||||
|
||||
|
||||
+3
-13
@@ -86,18 +86,8 @@ Canonical and pending sale delivery is recognized by the agreed seller/buyer/car
|
||||
|
||||
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
|
||||
## Future live XMR custody
|
||||
|
||||
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](shkeeper-settlement.md) 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 selected direction is a pooled custodial ledger, not per-sale processor invoices. Real deposits would be assigned to durable Monero subaddresses and reconciled against wallet-owned outputs; purchases would transfer liabilities internally. Withdrawals would require a separate, policy-constrained treasury signer and durable reconciliation. **None of this is connected to the public marketplace or enabled:** there is no live deposit-address route, customer credit worker, withdrawal signer, or paid-sale settlement path.
|
||||
|
||||
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**.
|
||||
Do not send real XMR to this sandbox. Live activation requires an end-to-end reviewed implementation, funded-liability and custody policies, production wallet/daemon isolation, withdrawal/reorg recovery, backups and operations evidence. No payment-mode setting is an activation path.
|
||||
|
||||
@@ -15,7 +15,7 @@ Use Node.js 24 and a clean reviewed checkout. For mainnet assessment on a host,
|
||||
The preflight:
|
||||
|
||||
- Selects the pinned profile and reports network, chain/genesis, fixed fee policy and local gate status.
|
||||
- Does **not** open/create a ledger or wallet, start a RandomX engine/listener, contact peers or SHKeeper, or write approval settings.
|
||||
- Does **not** open/create a ledger or wallet, start a RandomX engine/listener, contact peers or external payment services, or write approval settings.
|
||||
- Does not print environment values or payment credentials. Reports are still operational information; review them before publishing.
|
||||
- Lists code blockers and missing external evidence. `productionReady` remains false even if startup approval variables are supplied. Fixes and independently reviewed evidence must be reflected in a future reviewed release; do not turn the report green by deleting findings.
|
||||
|
||||
@@ -27,7 +27,7 @@ The runtime image can execute the entry point with `--launch-preflight` as well;
|
||||
|
||||
For the proposed **non-monetary testnet beta only**, use a separate scoped decision: the chain/network is explicitly testnet, no valuable cards are offered, real payment/custody settings remain off, mock market delivery is disabled or the deployment is demonstrably valueless, and experimental wallet/data-loss limitations are disclosed. This does not close any mainnet/live-payment hold point below. Apartment-hosting evidence must include ISP/CGNAT/reachability, TLS/proxy/backend isolation, firewall/admin/patch controls, off-host encrypted backup and restore, and external alert delivery. If these cannot be verified, do not expose the apartment host publicly; choose a managed host.
|
||||
|
||||
[Stage-5 SHKeeper prototype](shkeeper-settlement.md) is fixture-only and disconnected from the public market. Production payment activation, real processor verification, custody/refund policy, journal/backup/monitor integration and operator reconciliation remain missing. It cannot justify closing the real-money hold point.
|
||||
The real-money custody path is not implemented end-to-end. Production deposit/credit/withdrawal services, custody and refund policy, journal/backup/monitor integration, operator reconciliation and independent review remain missing.
|
||||
|
||||
[Stage-4 deployment and recovery tooling](operations-recovery.md) adds explicit proxy trust, private loopback diagnostics/checks and stopped-node pair backup/verification/non-overwriting restore. A local native proof-replay restore drill is automated, but actual-host TLS/proxy verification, off-host recovery, alert delivery and operational ownership still require external evidence.
|
||||
|
||||
@@ -41,7 +41,7 @@ For each item record **owner, artifact/release ID, date, evidence location, revi
|
||||
| Consensus launch design | Final genesis and manifest; measured starting target/hashpower; reviewed timestamp/retarget/partition/reorg attack analysis | Missing |
|
||||
| Node availability | Bounded public APIs/client; global resource/admission controls; realistic long-chain and hostile traffic capacity report | Missing |
|
||||
| Production wallet | At-rest/unlock/signing policy, same-origin compromise analysis, user confirmation and offline recovery drill | Missing |
|
||||
| Real-money market, if offered | Reviewed SHKeeper invoice/payment checks, invoice quote authorization, seller destination registration, fee-recipient allocation, custody policy, durable payout intents, timeout/partial-success reconciliation, refund/reorg dispute controls | Not implemented; real payment must stay blocked |
|
||||
| Real-money market, if offered | Direct wallet deposit observation and exact liability crediting, customer-authorized withdrawals, isolated treasury signing, durable reconciliation, custody policy, refund/reorg dispute controls | Not implemented; real payment must stay blocked |
|
||||
| Mock-market policy | Ensure public users cannot mistake buyer-triggered mock payment for money; disable sandbox selling/delivery for valuable mainnet cards unless explicitly confined to a valueless trial | Unresolved |
|
||||
| Peer/miner topology | Multiple independently administered hosts/operators/failure domains; actual online matching manifests and sufficient independent hashpower, not just two URL strings | Unverified |
|
||||
| Edge and host security | TLS/certificate renewal, firewall, loopback backend, reviewed proxy IP trust, connection/global limits, restricted administration, patched hosts, time synchronization | Unverified |
|
||||
|
||||
+10
-11
@@ -16,7 +16,7 @@ Status: active engineering plan; **not launch or payment authorization**. Update
|
||||
| Payment before sale finalization | A paid sale must not complete or be included as a completed ownership sale on Wikideck until the agreed XMR payment has satisfied its confirmation/unlock policy. Payment notification/mempool presence is insufficient. |
|
||||
| Existing boundaries | No real processor access, credentials, invoices, transfers, genesis change, destructive migration or launch approval is authorized by this plan. Software licensing still requires an operator choice and publication. |
|
||||
|
||||
**Production settlement remains disabled.** The public sandbox now prices new v3 listings/orders in native XMR atomic units, with mock-only confirmations, fees, refunds and payouts; legacy v2 USD records retain their original terms. The disconnected SHKeeper harness still models USD invoice requests and is not wired to v3. No real XMR invoice, payable address, conversion, transfer or settlement was enabled. Existing records are not silently reinterpreted as XMR.
|
||||
**Production settlement remains disabled.** The public sandbox now prices new v3 listings/orders in native XMR atomic units, with mock-only confirmations, fees, refunds and payouts; legacy v2 USD records retain their original terms. No real XMR invoice, payable address, deposit, credit, withdrawal, or settlement path is enabled. Existing records are not silently reinterpreted as XMR.
|
||||
|
||||
**Current design deliverable:** [custodial market design](custodial-market-design.md). Read the workstreams below with this update: pooled customer liabilities replace per-order incoming invoices and external sale payouts in the proposed architecture. Earlier trustless-first research gates are historical, not a prerequisite to investigating custody. Exact ledger, withdrawal, fee, custody/legal and host-attested NFT consensus rules still require approval and evidence; the existing mock domain cannot authorize real balance debits.
|
||||
|
||||
@@ -56,7 +56,7 @@ This scope is a proposed release boundary, not an approval to deploy. The operat
|
||||
|
||||
### What “confirmed before on-chain completion” requires
|
||||
|
||||
RandomX verifies work on Wikideck; it proves nothing about an XMR transfer. Monero privacy also means a Wikideck validator cannot infer recipient/amount/payment validity from a transaction ID alone. A processor's status is a trusted attestation, not a trustless cross-chain proof. Naively calling SHKeeper or a mutable Monero RPC from block validation would make consensus depend on credentials, service availability and potentially different observations; **do not implement that**.
|
||||
RandomX verifies work on Wikideck; it proves nothing about an XMR transfer. Monero privacy also means a Wikideck validator cannot infer recipient/amount/payment validity from a transaction ID alone. A payment service's status is a trusted attestation, not a trustless cross-chain proof. Calling an external service or mutable Monero RPC from block validation would make consensus depend on credentials, service availability and potentially different observations; **do not implement that**.
|
||||
|
||||
The design must specify what every validator can verify deterministically, which Monero chain/confirmation evidence is used, how its recipient/amount/order binding is established, what private information or keys must be disclosed, and how both chains' reorganizations are handled. Any relayer, committee, market operator, oracle or custodian introduces a named trust assumption. “Non-custodial,” “atomic,” and “trustless” are distinct claims and must be justified separately.
|
||||
|
||||
@@ -85,7 +85,7 @@ Can begin independently of P0, but must not hardwire a settlement architecture.
|
||||
- Define canonical decimal input/output backed by integer atomic units, bounded values/precision, exact comparisons and independent commission rounding. No float-based amounts or implicit USD conversion. Optional fiat display, if added, is informational and never settlement authority.
|
||||
- Replace USD listing/bid/checkout fields and UI with versioned XMR-native terms. Sign currency, gross, commissions, destinations, fee policy/estimate limits, expiry, order/market/network identity and selected settlement protocol version. Update invoice/checkout review and participant disclosures.
|
||||
- Migration plan: preserve existing USD/mock order history in its original version. Close/relist old open listings with fresh seller authorization; define disposition of bids/reservations before migration. No automated reinterpretation, deletion or mainnet asset migration.
|
||||
- Resolve SHKeeper's documented USD-denominated invoice input. Verify whether a supported deployed version offers exact native-XMR invoices and stable amounts; otherwise research direct Monero wallet-RPC/payment infrastructure or a reviewed adapter. **Do not reintroduce an approximate USD conversion behind XMR-native pricing.** SHKeeper is the preferred processor where compatible, not a justification to violate exact-price requirements.
|
||||
- Use the selected pooled-custody model: direct Monero wallet/daemon observation and durable subaddress allocation for deposits, internal liability transfers for sales, and a separately constrained treasury withdrawal path. No third-party processor is selected or required. Preserve exact native-XMR prices; do not introduce fiat conversion as settlement authority.
|
||||
- Separate payment-sending fees, hosting/author commissions and payout network fees in quotes/accounting. Define who pays author-leg network costs and fee-overrun caps. Handle sub-atomic commissions without overcharging. Preserve the fixed 1% address/rate in the distributed policy.
|
||||
- Checkout preflight determines economic viability under the selected architecture before accepting an order. For the custodial proposal, internal sales have no per-sale Monero payout cost; deposit eligibility, available balance and withdrawal economics are separate checks. Accumulated balances are proposed in ADR 002 but not implemented/approved for funds; batching remains deferred. Disclose uneconomic withdrawals before deposit rather than silently forfeiting balances.
|
||||
|
||||
@@ -134,14 +134,14 @@ Acceptance: safety/liveness matrix covers every state transition and adversary;
|
||||
|
||||
### P4 — production payment integration, reconciliation and controls
|
||||
|
||||
Depends on selected P0 model; may not require SHKeeper if incompatible with the approved native-XMR/trustless design.
|
||||
Depends on the pooled-custody decision in ADR 002 and the separately reviewed NFT lock/completion/cancellation protocol.
|
||||
|
||||
- Approved exact-XMR processor contract and private infrastructure: credential scoping/rotation, secrets-file/manager loading, restricted fixed-origin TLS/DNS/egress transport, bounded responses/deadlines, no redirects and no sensitive logs. API keys never enter browser/build variables.
|
||||
- Actual Monero payment confirmation policy: canonical transaction identity, amount/destination/order binding, incoming/outgoing and locked/unlocked/spendable states. Determine whether processor status is adequate or wallet/daemon evidence is required. “Fully confirmed” must have a defined numerical/policy meaning; no finite count eliminates reorg risk.
|
||||
- Invoice requests are immutable by version and replay-safe. Late, partial, duplicate, overpaid, expired and unattributed incoming payments get defined liabilities/reconciliation outcomes, not disappearance or unconditional refunds. Callbacks, if supported, are bounded hints; re-read authoritative state.
|
||||
- Outbound seller/author/refund attempts use unique durable allocations and task IDs. Reconcile exact amounts/destinations/transaction IDs; preserve successful legs during partial failure. No blind resubmission after timeout/crash and no manual DB editing to reset an attempt. Use independent approvals and audited reason/evidence for resolution; exact rules depend on protocol/custody decision.
|
||||
- Embed all authoritative payment state into the production backup/restore schema, monitoring and retention policy. Test processor external history against restored journals before resuming work; local restore cannot undo an XMR transfer.
|
||||
- Per-order/daily/total unsettled and hot-wallet exposure caps, immediate disable-new-checkout controls and bounded existing-obligation handling. Stopping new orders is not permission to abandon customer funds. Credentials and signing capabilities have separated roles where possible.
|
||||
- Deposit enrollment and allocation: authenticate the Wikideck beneficiary, create a durable one-to-one mapping to a Monero subaddress before displaying it, and keep old allocations monitored. The spend-capable wallet must be isolated from the public API.
|
||||
- Observation and credit: consume wallet-owned output records with stable per-output identity, canonical inclusion, versioned confirmation/unlock policy, exact atomic amounts and idempotent ledger writes. Unknown, late, duplicate, partial and reorged outputs require defined suspense/hold treatment; observations alone never authorize spendable credit.
|
||||
- Marketplace settlement: reserve available customer liability and order state atomically in PostgreSQL; release seller/author/host liabilities only from the agreed canonical sale outcome. A user-signed mock-payment action is never payment evidence.
|
||||
- Withdrawals: authorize exact destination, amount and maximum fee; reserve liabilities; fence one treasury worker; durably store prepared-transaction identity before relay; reconcile chain status and actual fee. Ambiguous outcomes must not trigger a second transaction or release of the reservation.
|
||||
- Recovery and operations: include customer-to-subaddress mapping, wallet generation/high-water marks, journal, pending outputs, signed approvals and prepared transactions in encrypted backups. Restore without spending, reconcile with Monero state, then explicitly re-enable the treasury worker.
|
||||
- Set measured liability/exposure caps and independent alert/stop controls. Stopping new deposits or orders must not abandon existing liabilities. Separate observation, ledger, operator review and spend-signing privileges.
|
||||
|
||||
Acceptance: full end-to-end staging against the verified supported processor/network, unauthorized-action tests, injected partial sends/outages/timeout/crash/reorg tests, actual-fund reconciliation procedure and reviewed secret-access controls. Any processor access, credentials or fund movement requires a separate explicit authorized test scope, budgets and network selection. This plan authorizes none.
|
||||
|
||||
@@ -225,6 +225,5 @@ Not every value is needed to begin engineering; each becomes a blocking decision
|
||||
- [Current participant payment disclosures](market-transparency.md) — describes existing behavior, not future promises.
|
||||
- [Security findings](security-review.md) and [operator hold-point register](operator-launch.md).
|
||||
- [Resource controls](node-resources.md), [wallet lifecycle](wallet-security.md), [calibration evidence](consensus-calibration.md), [operations/recovery](operations-recovery.md).
|
||||
- [Offline SHKeeper contract/state-machine work](shkeeper-settlement.md) — reusable tests/ideas, not the selected production architecture.
|
||||
|
||||
This plan supersedes the earlier USD production-pricing direction. New mock listings already use native XMR; historical USD terms remain intact. Custody and M2 implementation status are explicitly bounded above; no sandbox or infrastructure milestone implies live settlement or launch readiness.
|
||||
|
||||
@@ -8,11 +8,11 @@
|
||||
|
||||
This is an internal, source-assisted review with automated regression and dependency checks, **not an independent security audit, penetration test, formal consensus proof, or production certification**. The candidate has not been launched and no approval/attestation was set. Do not interpret passing tests, the existence of a mainnet profile, or the arrival of its candidate genesis date as permission to launch.
|
||||
|
||||
Scope: current consensus/ledger/P2P/RandomX integration, HTTP entry point, browser wallet/backups, marketplace authorization/accounting/reconciliation, Docker configuration and candidate startup gates. The operating hosts, real reverse proxy, public peers, SHKeeper instance, wallets and funds were **not** accessed or assessed. No active Internet-facing adversarial load test or independent native-code audit was performed.
|
||||
Scope: current consensus/ledger/P2P/RandomX integration, HTTP entry point, browser wallet/backups, marketplace authorization/accounting/reconciliation, Docker configuration and candidate startup gates. The operating hosts, real reverse proxy, public peers, wallets and funds were **not** accessed or assessed. No active Internet-facing adversarial load test or independent native-code audit was performed.
|
||||
|
||||
## Findings that block production
|
||||
|
||||
**Stage-5 follow-up:** [Offline SHKeeper/settlement prototype](shkeeper-settlement.md) adds wire-contract validation and durable signed-quote/payout failure-path tests, without connecting a real processor or changing mock-only runtime behavior. SEC-04/SEC-05 remain open; the prototype is not production accounting/backup/UI integration or an atomic/refund solution.
|
||||
Real-money settlement is not implemented end-to-end. The selected direction is direct Monero custody with a pooled liability ledger; no production deposit, credit, withdrawal, or customer-facing live settlement path exists. SEC-04/SEC-05 remain open.
|
||||
|
||||
**Stage-4 follow-up:** [Operations/recovery tooling](operations-recovery.md) provides explicit trusted proxy IP/CIDRs, opt-in separate loopback diagnostics and aggregate monitoring checks, a proxy example (not installed), stopped-node SQLite pair snapshots/verification and new-directory restore. Native integration replays restored reference proofs and preserves marketplace identity/orders/receipts. SEC-07 and SEC-09 remain open pending intended-host deployment, off-host recovery and real alert/on-call evidence.
|
||||
|
||||
@@ -23,7 +23,7 @@ Scope: current consensus/ledger/P2P/RandomX integration, HTTP entry point, brows
|
||||
| SEC-01 | High · public node availability | [HTTP full-state routes](../server/testnet/http.ts#L63) return [full cloned canonical snapshots](../server/testnet/ledger.ts#L223). The ledger retains [all DAG nodes in memory](../server/testnet/ledger.ts#L29); state-root calculation rebuilds the NFT set. Read cost and startup replay grow with chain/fork history. Per-IP request limits do not impose a global CPU, response-byte, memory or disk budget. | Bounded/paged public RPC and a compatible paged client; tested caching/indexing; validation admission budgets; disk/fork retention or a reviewed archival strategy. Demonstrate the intended workload and malicious traffic do not starve consensus or trigger OOM/disk exhaustion. Do not add an arbitrary consensus height cap. |
|
||||
| SEC-02 | High · chain security | [Initial target](../server/testnet/consensus.ts#L12) succeeds with probability approximately 1/16 per hash, and [retarget](../server/testnet/consensus.ts#L172) uses ten-block windows. This is inherited testnet calibration, not evidence of a secure 15-minute production launch. Timestamp/retarget manipulation, hashpower concentration and private-chain rewrites require quantified analysis. | Independent consensus/economic review; measured launch hashpower; adversarial retarget/clock/partition simulations; choose and freeze final launch parameters and genesis before approval. Changing these changes chain identity. RandomX's shared algorithm does **not** inherit Monero's hashpower or security. |
|
||||
| SEC-03 | High · valuable NFT keys | [Browser wallet creation/storage](../src/wallet.ts#L76) persists an extractable P-256 private key without password encryption in IndexedDB. Encrypted portable backups do not encrypt that stored key. Same-origin script compromise, profile access or a sufficiently privileged extension can sign/export it. | A reviewed production wallet model with encrypted-at-rest storage/unlock lifecycle or isolated/hardware signing, explicit XSS threat model and tested recovery. Non-extractable keys alone do not stop malicious same-origin signing; storage encryption does not protect an already unlocked page. |
|
||||
| SEC-04 | High · real-money marketplace | [Payment adapter](../server/market/payments.ts) is deliberately mock-only. Buyer-controlled mock payment can lead a seller to sign a **real** card transfer. Listing reservations are not consensus locks. There is no reviewed live invoice verification, seller XMR destination registration, payout reconciliation, fee-recipient payout, refund/dispute system or custody controls. | Keep real money blocked. For valuable cards, disable mock-sale delivery/listings or keep the entire deployment explicitly valueless. Build/review the real SHKeeper settlement path separately; do not replace the mock adapter with a simple HTTP call. |
|
||||
| SEC-04 | High · real-money marketplace | [Payment adapter](../server/market/payments.ts) is deliberately mock-only. Buyer-controlled mock payment can lead a seller to sign a **real** card transfer. Listing reservations are not consensus locks. There is no reviewed live deposit/credit flow, seller XMR destination registration, treasury withdrawal reconciliation, fee-recipient payout, refund/dispute system or custody controls. | Keep real money blocked. For valuable cards, disable mock-sale delivery/listings or keep the entire deployment explicitly valueless. Implement and review the complete direct-custody ledger and treasury path; do not replace the mock adapter with a simple HTTP call. |
|
||||
| SEC-05 | High · future live refunds/finality | [NFT transfer signatures](../shared/testnet.ts#L54) have no expiry/revocation and payment state is not a consensus commitment. A transfer absent during refund review may be rebroadcast or reappear after a reorg. An off-chain refund cannot cancel a previously signed NFT transfer. Recognizing current canonical delivery (fixed below) does not solve this general issue. | Explicit escrow/atomic-settlement design or a reviewed reserve/dispute/manual risk policy, late-payment/delivery rules, and recovery tools. Never promise trustless exchange or unconditional automatic real refunds. No finite confirmation count guarantees finality on a small PoW network. |
|
||||
| SEC-06 | Medium · market availability | [Reconciliation](../server/market/store.ts#L115) synchronously scans journal rows/chain and writes journal state. Public browsing invokes it. Lifetime [10,000-listing/order caps](../server/market/store.ts) stop new business without a built-in archival workflow; signed unfunded bids and reservations have little economic cost. Nonces/receipts are not an economic spam defense. | Separate/cached read paths and indexed incremental reconciliation; measured event-loop/IO budgets; account/global anti-abuse policy; bounded receipt/storage management and a tested archive process that preserves payout/idempotency history. |
|
||||
| SEC-07 | Medium · deployment availability | The app leaves Express proxy trust at its default. Behind a reverse proxy, IP-based limits may group clients under the proxy IP, allowing one client to throttle everyone. Conversely, blindly enabling proxy trust would permit spoofed forwarded IPs. [Health](../server/testnet/http.ts#L50) reports process liveness, not peer synchronization, native-engine readiness or market reconciliation health. | Configure trusted proxy hops/CIDRs against the real topology; reject direct backend access and untrusted forwarded headers; apply edge/global limits and connection/time/body budgets. Add private monitoring for peer freshness, tip lag, reorgs, queues, RandomX failures, disk/WAL usage and market review states. Test actual TLS/HSTS/certificate renewal. |
|
||||
@@ -68,4 +68,4 @@ USD authorization followed by a separately displayed XMR quote is not itself a c
|
||||
- Fixed fee address decoded independently as **95-character Monero Base58, 69 decoded bytes, prefix 18 (mainnet standard address)**; Keccak-256 checksum matched (`c752185b`). This proves formatting/checksum only, **not** ownership or intended recipient. Verify control out of band before any future live transfer; never share seed/private keys.
|
||||
- Mainnet preflight exercised with approvals absent: reports `NO-GO`, `productionReady: false`, `paymentMode: mock`; no node/ledger/network startup. Mainnet manifest/configuration remains candidate-only.
|
||||
|
||||
Not performed: independent audit, production-host penetration test, adversarial sustained load/fuzz campaign, private-key/hardware review, actual XMR invoice/payment/payout, SHKeeper instance verification, real peer/miner independence validation, or a production backup/restore exercise. See [operator launch procedure](operator-launch.md) for evidence required before explicit approval.
|
||||
Not performed: independent audit, production-host penetration test, adversarial sustained load/fuzz campaign, private-key/hardware review, actual XMR deposit/credit/withdrawal, real peer/miner independence validation, or a production backup/restore exercise. See [operator launch procedure](operator-launch.md) for evidence required before explicit approval.
|
||||
|
||||
@@ -9,7 +9,7 @@ Status: **proposed; research checkpoint, not an approved exchange protocol**. So
|
||||
- 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.
|
||||
- The later approved direction is pooled custodial XMR balances under ADR 002; the trustless/arbitrated analysis below remains historical research, not the active implementation plan.
|
||||
|
||||
**Earlier recommendation (superseded as the preferred investigation):** build proof-backed order evidence and fair, host-scoped reputation as a non-settlement safety layer; evaluate per-order 2-of-3 Monero multisig escrow with independent dispute arbitration as a live-sale candidate. Keep permissionless conditional XMR↔NFT research separate. A payment proof and delivery record cannot return direct-to-seller XMR. The escrow candidate is **arbitrated, not trustless**: the arbitrator and wallet/recovery procedures become material trust and availability dependencies. No live funds, key custody, or new consensus rules were authorized by that recommendation.
|
||||
|
||||
@@ -21,9 +21,8 @@ Status: **proposed; research checkpoint, not an approved exchange protocol**. So
|
||||
| [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), [protocol explanation](https://docs.eigenwallet.org/advanced/refund_punish), [4.16.1 release](https://github.com/eigenwallet/core/releases/tag/4.16.1) | Maintained project with 4.16.1 release. Its current docs explicitly define taker as Bitcoin seller and maker as Monero seller; its lock/cancel/refund/punish flow is Bitcoin-timelock centric. The docs and site describe Bitcoin→Monero only. GPL-3.0; historical COMIT README says formal crypto audit absent, but that is not evidence about every current successor version. | Useful comparative protocol and operational lessons, but not the requested XMR-for-NFT direction or an arbitrary-NFT/P-256 integration. No audit artifact for a proposed Wikideck adaptation was found/evaluated. Review exact current source before considering any reuse. |
|
||||
| [Monero payment-proof guide](https://www.getmonero.org/resources/user-guides/prove-payment.html), [wallet RPC `check_tx_proof`](https://docs.getmonero.org/rpc-library/wallet-rpc/#check_tx_proof) | The payer can give a payee a transaction ID, destination address and transaction proof/key. The payee checks the proof against an up-to-date Monero blockchain view; RPC reports validity, received amount, in-pool status and confirmations. The RPC explicitly warns proof does not guarantee spendability (locked, already spent or duplicated/burnt one-time outputs). | Buyers can prove payment to a seller/market verifier for accountability. This does not identify a real-world person, reverse payment, or give every Wikideck validator an independently verifiable canonical-chain proof. Bind each order to a unique destination and exact amount; treat proof verification/depth as sensitive evidence. |
|
||||
| [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. |
|
||||
| [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 does not make NFT exchange atomic. Amounts need lossless JSON encoding, not conversion to JavaScript Number. |
|
||||
| [Haveno trade protocol](https://docs.haveno.exchange/overview/trade-protocol/), [dispute resolution](https://docs.haveno.exchange/overview/dispute-resolution/), [project status](https://github.com/haveno-dex/haveno) | A maintained XMR P2P exchange documents per-trade 2-of-3 Monero multisig: one key for each trader and one for an arbitrator. Two keys are needed to spend. Parties normally co-release funds; when they disagree, an arbitrator investigates and co-signs with one party. Security deposits are locked to discourage protocol abuse. Its current project README says the upstream project does not support real trades directly; real networks use third-party builds/networks it does not endorse. | Strong prior art for an **arbitrated escrow**, not a trustless/automatic refund and not an NFT cross-chain protocol. The arbitrator is a real trust and availability dependency in disputes; deposits, key ceremony, wallet recovery, multisig fees, network governance and third-party network integrity matter. Its second asset/payment is fiat/other cryptocurrency and does not answer Wikideck card lock or consensus validation. Treat as a design pattern to adapt only after specialist review, not as a drop-in integration or endorsement. |
|
||||
| [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.
|
||||
|
||||
@@ -146,7 +145,7 @@ This layer improves detection, customer support and deterrence. If direct paymen
|
||||
- Run separate multi-process/multi-host adversarial tests for false proof, wrong recipient/amount, duplicate/replayed proof, stale/out-of-date node, payment reorg, buyer false dispute, delayed NFT transfer/reorg, arbitrator unavailable/colluding, key loss, and partial payout. Require an external Monero multisig/security review before staging.
|
||||
- If the operator's eventual priority is permissionless no-arbitrator exchange, keep pursuing the custom conditional XMR↔NFT protocol separately; no practical current implementation is established. Do not downgrade to direct payment while describing buyer protection.
|
||||
|
||||
**Decision request remains open:** no live settlement flow or Monero verifier has been selected. Direct seller payment plus proof and reputation (A) may deter abuse but is not buyer-protecting; B is a custodial fallback; C is the researched direction intended to target two-sided atomic control, but remains unproven and may be impractical. The public marketplace now displays native-XMR prices under a mock-only v3 domain; actual XMR payments remain disabled and the separate SHKeeper prototype still takes USD.
|
||||
**Historical research status:** this ADR records earlier trustless/arbitrated options. The operator subsequently selected pooled custodial XMR balances in [ADR 002](custodial-market-design.md). The public marketplace displays native-XMR prices under a mock-only v3 domain; actual XMR payments remain disabled. No payment processor is part of the selected path.
|
||||
|
||||
## Threat model and required failure evidence
|
||||
|
||||
|
||||
@@ -1,75 +0,0 @@
|
||||
# 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
|
||||
|
||||
- [XMR validation](../server/market/xmr.ts): Monero block-Base58 decoding, mainnet standard/subaddress prefix and Keccak-256 checksum checking, integer atomic-unit amount parsing (12 decimal places), bounded USD decimal parsing. Integrated/payment-ID and testnet addresses are rejected. A valid address/checksum is not proof of curve-key correctness, ownership or recipient control. Monero has tail emission; no invented fixed-supply cap is used as a validator.
|
||||
- [SHKeeper wire-contract harness](../server/market/shkeeper.ts): explicit injected transport only, fixed HTTPS-shaped processor origin, correct API-key versus Basic authentication, no redirects, five-second deadline, 256 KiB streamed response limit, bounded schemas/arrays and secret-safe request failures. There is no global/default `fetch`, production network transport, credential loader, environment bypass or usable callback route. Tests supply ephemeral fixture credentials and fake `Response` objects. The factory name deliberately says **Harness**.
|
||||
- [Durable settlement lab](../server/market/settlement-lab.ts): a separate SQLite/WAL journal, serialized operations, strict network identity and exclusive single-process lock; seller authorization of payout address/sale terms; buyer authorization of the exact invoice/address/amount/expiry and both fee allocations; authoritative invoice polling; exact confirmed payment verification; trusted canonical-delivery-reader boundary; durable payout intents; separate seller and hardcoded 1% payout legs; task/transaction allocation uniqueness; partial-success and ambiguous-outcome holds; restart reconciliation.
|
||||
- No web UI/action, callback handler, background worker or production `Market` path constructs the harness/lab. The prototype must not be connected to real money by simply injecting global `fetch` or changing an environment variable.
|
||||
|
||||
## API contract evidence
|
||||
|
||||
Read from [public SHKeeper API docs](https://shkeeper.io/api/) version **2.1.47** on 2026-10-20, including the embedded OpenAPI definitions for `Invoice`, `Transaction` and `PayoutResultObj`:
|
||||
|
||||
| Operation | Contract used |
|
||||
| --- | --- |
|
||||
| Create invoice | `POST /api/v1/XMR/payment_request`, `X-Shkeeper-Api-Key`, USD `amount`, unique `external_id`, required `callback_url`. Response has `id`, XMR `amount`, `wallet`, `exchange_rate`, `recalculate_after`. |
|
||||
| Invoice lookup | `GET /api/v1/invoices/{external_id}`, API key, `status: success`, `invoices` array. Invoice fields: `external_id`, `fiat`, `amount_fiat`, `balance_fiat`, `status` in UNPAID/PARTIAL/PAID/OVERPAID, `txs`. |
|
||||
| Invoice transaction | `addr`, `amount`, `crypto`, `status` CONFIRMED/UNCONFIRMED, `txid`. No numeric confirmation count is documented in this schema. |
|
||||
| XMR payout | `POST /api/v1/XMR/payout`, Basic authentication, `amount`, `destination`, `fee` priority 1–4. Prototype chooses 2. XMR does not support the multipayout endpoint. |
|
||||
| Payout status | `GET /api/v1/XMR/task/{task_id}`, Basic authentication, PENDING/FAILURE/SUCCESS; result entries contain `amount`, `dest`, success/error, optional message and `txids`. |
|
||||
|
||||
The harness accepts numeric/string invoice IDs as documented examples differ, but requires UUID payout task IDs. It accepts quote `recalculate_after` only 0 or "0"; a floating/recalculating quote is refused rather than silently repriced. The required callback URL uses the reserved **market.invalid** domain and has no receiving route; it is a deliberate fixture placeholder that makes the create operation unsuitable for live use.
|
||||
|
||||
Documentation alone cannot prove the deployed processor returns identical shapes/semantics. The actual instance/version, XMR enablement, precision, quote locking, fees, confirmation policy, task success meaning and failure/partial-send behavior require an explicitly authorized future integration review. A processor's `CONFIRMED` flag is not proof of an agreed XMR confirmation depth until its configured policy is independently established. Callback signing was not established by these schemas; **callback payloads never authorize payment** in this prototype.
|
||||
|
||||
## Authorization and accounting
|
||||
|
||||
Seller signs the lab's domain-separated network/chain/order/card/sequence/buyer terms, USD price, hosting basis points, expiry, NFT delivery depth, payout public key/address, and fixed **1% recipient/rate**. This proof links their NFT identity to the requested XMR destination; it does not prove that they control its private spend key. Invalid checksum/network destinations fail before quote creation.
|
||||
|
||||
After invoice creation, buyer signs the exact invoice ID, currency, address, XMR amount, exchange rate, USD terms, expiry, hosting retention, seller net/destination and fixed-fee amount/destination. Wrong buyer, modified quote and wrong signature are refused. This second authorization is distinct from the existing mock market's USD reservation command; the public marketplace has not been migrated to this protocol.
|
||||
|
||||
Both fees are computed independently from gross XMR in integer atomic units, rounded down. Seller net = gross − hosting retention − 1% allocation. **Hosting stays in the merchant wallet**, as designed; it is not a missing third payout or burned funds. Seller net and 1% recipient require separate XMR payouts because XMR multipayout is unsupported. For 0.1 XMR and 2.5% hosting: 0.0025 retained, 0.0965 seller, 0.001 fixed recipient. A sub-atomic fixed fee rounds to zero and its leg is skipped, not inflated.
|
||||
|
||||
Processor fees included in an invoice can alter actual gross/fiat semantics. The prototype requires exact expected fiat and crypto totals and will hold inconsistent fee-bearing cases rather than assuming compatibility. Network fees, overpayment handling, processor-fee policy and reserves must be designed/disclosed before connecting live. This is a custodial gross-receipt/net-payout design, **not** a trustless XMR/NFT exchange.
|
||||
|
||||
## State machine and failure rules
|
||||
|
||||
1. **Draft → invoice intent:** persist `invoice-submitting` before calling the fixture create endpoint. A response loss, invalid response or restart with unresolved intent enters review. The POST is not automatically repeated, even though invoice external IDs exist, because create/update behavior and outcome reconciliation must be reviewed.
|
||||
2. **Quote → awaiting payment:** buyer explicitly authorizes the exact quote before payment can be recognized. Expired signatures/quotes fail. No public payable address is exposed by the running app.
|
||||
3. **Payment polling:** only server-to-server-shaped lookup data is used; exactly one external-ID invoice is required. It must have the expected fiat amount, currency and transaction addresses/currency; no duplicate tx IDs; exact confirmed gross and fiat balance. Partial/unconfirmed payments wait. Overpaid, contradictory, unknown, changed or late observations enter review; there is no blind refund or automatic invoice reuse.
|
||||
4. **Paid identity:** save the exact incoming tx-ID set and enforce global incoming allocation uniqueness in the lab journal. Later changes to the paid set or amounts suspend settlement. The same observed deposit cannot fund two lab orders.
|
||||
5. **NFT delivery:** the reader is a trusted consensus-library boundary, never a buyer-supplied HTTP boolean. It must return the exact transfer identity (chain/card/from/to/sequence), required canonical depth and a well-formed tip. Before any payout, missing depth waits; after payout begins, changed delivery enters permanent review. Recheck invoice and delivery before each separate payout. These reads cannot make off-chain money and on-chain delivery atomic; a reorg can occur after any check.
|
||||
6. **Durable payout intent:** mark a leg `submitting` and commit **before** its create POST. Save its task ID under a unique constraint. Transport timeout, malformed result, task-ID collision, interrupted persistence or restart with no acknowledged task ID becomes `ambiguous`/review. Never retry that payout automatically.
|
||||
7. **Known tasks:** repeat status GETs only. PENDING waits. SUCCESS must contain exactly one successful result matching amount/destination, at least one well-formed distinct transaction ID and no transaction ID already allocated to another leg/order. FAILURE, malformed success, amount/address mismatch or duplicate evidence enters review. A known task query failure does not create another POST.
|
||||
8. **Partial success:** seller completion is durably recorded before the fee leg. If fee fails, preserve the seller's success and hold the remainder. There is no rollback, re-payment of the seller or assumption that the entire sale was unpaid. Reorg after completion holds without paying again.
|
||||
|
||||
`expiresAt` is an invoice/payment-authorization deadline, not a deadline that cancels a correctly paid sale while NFT delivery is being mined. Refusing payout solely because a legitimate invoice later expires would not be a safe general settlement policy. Delivery timeouts/disputes and reserves remain unimplemented live-policy requirements.
|
||||
|
||||
## Journal, recovery and activation holds
|
||||
|
||||
The lab uses a **separate settlement-lab.sqlite** and lock under a caller-supplied disposable directory. It is **not** inside the production two-database backup contract, not exposed by current operations diagnostics and not an authoritative production accounting system. Current node backups do not protect it. Test fixtures reopen the lab to verify intent/task persistence; this is not a production processor reconciliation tool. Do not delete a stale lab lock unless its owning process is verified stopped.
|
||||
|
||||
There is no operator override/retry/refund endpoint. `review` is intentionally not auto-recovered. The lab retains privacy-sensitive participant/payout/transaction data and signatures but **not processor credentials**. Trusted local filesystem ownership and external encryption remain necessary. Schema inspection validates identity, but this is not tamper-resistant accounting against an operator who controls the DB.
|
||||
|
||||
Before live integration can be reviewed/activated, the following remain required:
|
||||
|
||||
- Production network readiness and independent custody/consensus/application review; explicit operator payment activation, separate from network startup. **No live approval variable is implemented in this release.**
|
||||
- A production adapter with restricted server-only secret loading, approved fixed origin/DNS/egress controls, no redirects, TLS review, least-privilege credentials and a verified deployed API contract. Never put credentials in Vite/browser variables or code.
|
||||
- Real-market journal/schema, backup/restore/monitoring integration and migrations; typed authenticity validation of persisted authorization/amount records; trusted canonical delivery lookup; exposure only through participant-authorized APIs, not direct lab methods.
|
||||
- Actual quote presentation/authorization UX, seller payout-address registration/change authorization, minimum order/payout policy, exact fees and network-cost/reserve treatment.
|
||||
- Verified XMR confirmation policy and task success/failure semantics; bounded callback hints only; late/partial/overpayment/refund and non-delivery rules. Previously signed NFT transfers may arrive after a proposed refund—no auto-refund atomicity claim is made.
|
||||
- Durable operator reconciliation tooling for ambiguous create/payout requests, partial sends, known task failures, reorgs and external wallet/task history. Timeout is **not** failure/no-send evidence. Never erase an intent or re-submit to make tests/operations appear healthy.
|
||||
- Controlled end-to-end processor tests only after specific approval; this work did not request secrets, create invoices, transfer XMR or access the configured instance. No fund movement is authorized by this document.
|
||||
|
||||
## Tests
|
||||
|
||||
Final Node 24 TypeScript/Vite build passed. The full suite ran in a Docker container with **external networking disabled**: **119 tests passed, 0 failed, 0 skipped**, including existing native RandomX loopback integration. No real SHKeeper endpoint or credential was used; only public documentation retrieval occurred outside those offline tests.
|
||||
|
||||
Offline fake transports cover endpoint auth separation, bounded bytes/redirect/type failures, five-second abort, fixed quote policy, XMR checksum/network/decimal rejection, seller/buyer quote binding, confirmed exact payment/depth, duplicate inbound allocation, duplicate payout tasks/tx IDs, concurrent advancement, response-loss ambiguity, restart quarantine, known-task polling, seller-success/fee-failure, mismatched payouts, changed paid evidence and post-payout reorg hold. Existing mock marketplace/backup/lock/launch and native RandomX tests remain in the full suite.
|
||||
|
||||
This is partial engineering groundwork for SEC-04/SEC-05, not closure of those production findings. Live payments remain hard-disabled.
|
||||
Reference in New Issue
Block a user