docs(specs): fixed-lot credit trading with HTLC recovery

[maxie-agent]

Documentation-only refresh of #1041

Refresh requested by Bob in #cashu-token-marketplace, 2026-10-07 19:37 UTC. Rebased the existing maxie-agent:docs/credit-trading draft onto current main. Only docs/specs/credit-trading.md differs from main; the probe is throwaway/uncommitted. No merge, runtime implementation, production relay writes or real-money operations.

Single anchor: 8c3bf74f87ca4e5d0f7b0bff64c41a7073ac849e.

What changed since 9f17266

• Replaced the unmerged seller-credit stack framing with merged docs(specs): seller credits — nostr:// mint transport + opt-in mint sidecar #1084–test(mint): seller credits stage 3 end to end (stacked on stage 2) #1087 and follow-ups fix(buyer): reserve awards against the funding mint, not only the default (#1076) #1077/test(mint): fix two clippy lints in the total_issued helper #1088/fix(wallet): hint sellers to configure accepted mints #1091/fix(private): accept nostr:// mints in private jobs #1092/fix: credits-first buyer mint choice and private settlement parity #1100, released in v0.6.1-rc7.
• Re-derived all 39 unique repository citations by grep at the single anchor, including moved payment/recovery paths, current wallet melt refusal, private mint validation and credits-first selection. Checked dependency claims against pinned CDK/Cashu 0.17.2 source.
• Explained fix: credits-first buyer mint choice and private settlement parity #1100: covering configured credits get selected before sats for issuer/accepting-seller jobs; credits cannot be hop targets or melt sources. A sats-only buyer must acquire accepted credits before awarding a credits-only seller; buying credits is the proposed paid route, never an automatic job-payment conversion.
• Recovery must persist each request's event id/exp before publication and fence on exp + skew, then reconcile state/restore. Main's updated_at + 300s estimate is not sufficient for the proposed trade contract. nostr:// recovery: fence on a persisted request exp instead of updated_at + 300s #1035 remains open; Flaky test: maxplayer-mint killed_mid_swap_is_compensated_on_restart_then_executes (no reply after restart) #1090's sidecar flake and Enforce sealed delivery_mint at pay; journalled supersession for re-planned binds #1101's sealed delivery-mint issue remain explicit integration boundaries.
• Re-ran the HTLC probe against copied merged main sidecar backend/dispatch/wire and shared private-protocol source. NUT-04/05 disabled does not remove NUT-07/14.

Bob's decisions

Settled in §0, attributed to Bob, #cashu-token-marketplace, 2026-10-07:

• Q1: taker generates secret and locks first; maker locks second.
• Q4: no tested-only mint allowlist. Buyer may pay from any seller-accepted mint whose reachable quote-time info advertises NUT-14 and NUT-07. Missing/false advertisement or unreachable info refuses. Advertising is not proof of behavior; a canary checks its selected mint/configuration, not all eligible mints forever.
• Q5: 24 h listings, then republish with backing checks; 30-day trade-request dedup, unresolved funds retained until reconciliation.
• Q6: deploy persistent 3410/3411 in buzz required_scope_for_kind under Scope::MessagesWrite before clients use the feature; 23412 ephemeral. Anchor search confirms no product allocation (3410 only in an unknown-kind negative test); global registry/rollout review remains.
• Q7: ≤100 sats principal + ≤10 sats mint fees, one canary trade in flight. Bob's separate go is still required.

Settled — Q2/Q3 (Bob, #cashu-token-marketplace, 2026-10-07 19:40 UTC)

• Q2: taker lock 60 min, maker lock 15 min, from the same signed quote timestamp; 45 min nominal gap.
• Taker refuses claim initiation below 3 min remaining on maker lock. Persisted claim expiry must be ≤ short − 2 min and within the actual caller wait. No deadline renewal on retry; maker starts its lock inside the original quote window.
• Plain-language tradeoff: happy path takes seconds; deadlines limit failed-trade lock-up versus the seller/relay/payment-mint outage the maker can survive.
• Each mint's clock must be bounded within 60 s of the reference (up to 120 s relative skew). The 45-minute margin depends on that bound and bounded execution before the fence. CDK allows receiver claims after expiry, so “always 45 minutes” is not unconditional against malicious/late claims. §3.2 explains this and requires two-mint fault validation.
• Q3: 60 s quote hold from issuance, one open quote per taker, four per maker. Acceptance/retries never restart the hold.

Probe results — 2026-10-07

CDK/Cashu/CDK-common/CDK-sqlite/CDK-fake-wallet all =0.17.2; real local SQLite sidecar and native wallets, direct in-process connector. Copied source byte-compared against anchor (dispatch import only adapted). The first build exposed the wire module's new shared-crate dependency; copied that exact crate into tmp and reran successfully.

sidecar_htlc_probe: 1 passed, 0 failed; 5 helper tests filtered out; 5.04 s runtime. Cargo 1.98.1 + Nix protoc. One harmless standalone gateway cfg warning.

Requested item	Observed result
1. Info NUT-14/07 after NUT-04/05 change	PASS: both supported; NUT-04/05 both disabled through actual copied info dispatch
2. HTLC needs preimage + signature	PASS: missing both, preimage-only and signature-only rejected; native claim returns 64 local test sats
3. Refund only after locktime	PASS at mint API: same refund-key-signed token refused before, accepted after; unsigned refund after expiry rejected; explicit HTLC witness with empty preimage required
4. NUT-07 witness after claim	PASS: all claim-input Ys accounted for, SPENT, exact preimage in each witness via CHECKSTATE dispatch
5. Wallet-native create/claim and refund gap	PASS create/claim; FAIL native refund capability: receive with refund key but no preimage returns Preimage not provided. Lower-level signed swap works; durable refund adapter still required
6. Seconds-scale locktimes	PASS: +10 s claim completes before expiry; +4 s refund refuses early and succeeds after strict expiry. No hours-scale minimum in pinned CDK

SWAP and CHECKSTATE dispatch forwarding exercised. Local artifacts: ~/.openclaw/workspace/.openclaw/tmp/credit-htlc-probe/ (refresh-20261007.log, citation-audit.json, exact copied source and test).

Not verified: full two-mint atomic swap; encrypted/production relay delivery; killed-process recovery; persisted-exp integration or durable refund-output storage; positive fees; cross-mint clock skew/processing bounds; production-length outage behavior; key rotation; live Minibits/other mint claim/refund/witness behavior. Historical 24 Sep Minibits info remains labeled historical, not refreshed certification. Repository runtime suites not run for this docs-only change. Mermaid source reviewed; rendered GitHub visualization unverified.

Self-review: flaws fixed vs risks accepted

Fixed in the spec: stale anchors/unmerged framing; missing credits-first consequences; tested-only gate contrary to Q4; stale Q2/Q3 pending markers (approved by Bob at 19:40 UTC); stale 2h cutoff/five-minute hold; automatic-refund assumptions; recovery reuse without persisted-exp fences; stale sidecar info evidence. Existing asset-qualified caps, exact proof conditions, fee-inclusive quotes, wallet-wide reservations, single-fill CAS, idempotent journal and unchanged job platform fees remain intact.

Accepted/remaining risks: advertised-but-broken mint behavior; issuer fraud; late-claim/refund races and outages beyond the bounded gap; maker's witness dependency; funded free options/Sybil holds; single-relay censorship and metadata exposure; cloned-wallet spends/key loss; fee increases blocking capped recovery. The canary narrows exposure, not universal mint trust.

git diff --check and anchored citation/copy audits pass. Stages stay default-off. Keep draft; no canary runs without Bob's separate go. Still open: who deploys the 3410/3411 relay change.

[vercel]

@maxie-agent is attempting to deploy a commit to the MakePrisms Team on Vercel.

A member of the Team first needs to authorize it.

[maxie-agent]

Replaced by #1106 (same commit, now on a MakePrisms branch so Vercel previews run).