@arkade-os/swap 0.0.6 → 0.0.8

package/README.md

@@ -116,13 +116,22 @@ uncached discovery.
 Neither subpath adds a dependency: they take the SDK's structural `SQLExecutor` / `RealmLike`
 handles, so you pass the database you already opened.
 
+All four carry both record types: asset swaps and the monitored RFQ swaps
+(`saveRfqSwap` / `getRfqSwap` / `getAllRfqSwaps` / `removeRfqSwap`). Each keeps them in a store of their own — a
+second object store on IndexedDB, an `…rfq_swaps` table on SQLite, the `ArkadeRfqSwap` class on
+Realm — since the two record types have different keys and no consumer wants them interleaved.
+
 **Records are stored whole.** The SQLite and Realm backends serialize each record to **JSON** in a
-`data` column, with only `status` / `createdAt` mapped out for querying — so a field they do not
-know about survives, which is what the `quote`-shaped extension in `MIGRATION.md` relies on. JSON is
+`data` column, with only `status` / `createdAt` (and an RFQ record's `state` / `updatedAt`) mapped
+out for querying — so a field they do not know about survives, which is what the `quote`-shaped
+extension in `MIGRATION.md` relies on. It is also what keeps an RFQ record's corridor `profile`
+intact: `profile.hashlock` is a nested object holding the payment hash and any preimage material, and
+a field-mapped backend is exactly what would lose it. JSON is
 the boundary, though, and it is narrower than IndexedDB's structured clone: a `Date` in a
 consumer-added field comes back an ISO **string**, a `Set` or `Map` comes back empty, and a `bigint`
-makes `saveSwap` **throw**. `AssetSwap` itself is JSON-safe by design (amounts are strings); keep
-your own added fields that way too.
+makes `saveSwap` **throw**. `AssetSwap` and `RfqSwapRecord` are both JSON-safe by design (amounts are
+strings, binary is hex), and a corridor `profile` is plain JSON by the handler contract; keep your own
+added fields — and any corridor profile you write — that way too.
 
 ### SQLite
 
@@ -169,9 +178,15 @@ const realm = await Realm.open({
 const swaps = new RealmAssetSwapRepository(realm);
 ```
 
-Three classes land in your Realm namespace: `ArkadeAssetSwap`, `ArkadeAssetSwapScannedTxid`,
-`ArkadeAssetSwapMarketsCache`. Unlike SQLite there is no prefix option — a Realm schema name is
-baked into the schema objects you register — so reconcile against your own models by name.
+Four classes land in your Realm namespace: `ArkadeAssetSwap`, `ArkadeRfqSwap`,
+`ArkadeAssetSwapScannedTxid`, `ArkadeAssetSwapMarketsCache`. Unlike SQLite there is no prefix option
+— a Realm schema name is baked into the schema objects you register — so reconcile against your own
+models by name.
+
+`ArkadeRfqSwap` arrived after the other three. **If you already shipped them, add it and bump
+`schemaVersion` again**: Realm creates schemas at open, so a config still listing three fails on the
+first RFQ read rather than at open. SQLite needs nothing — its DDL runs `CREATE TABLE IF NOT EXISTS`
+on every init, so the table appears on the next operation.
 
 ## Creating an offer
 
@@ -290,7 +305,9 @@ message anywhere: **acceptance is funding**.
   offline. The solver observes the funding on-chain, pays the invoice, and claims with the
   preimage — which lands publicly in the claim witness as the receipt. A failed swap refunds by
   covenant to the trader's address, pushable by anyone, no trader keys or state.
-- **Arkade ↔ arkade** (BTC↔asset, asset↔asset): the trader accepts a quote by creating and funding
+- **Arkade ↔ arkade** (BTC↔asset, asset↔asset): an arkade asset leg names the asset id itself —
+  `arkade:<68-hex>`, built with `arkadeAssetLeg` (the deprecated coarse `ARKADE_ASSET` is served by
+  no solver). The trader accepts a quote by creating and funding
   an **offer** (layer 1) bound to the quoted terms before `valid_until`. The offer covenant only
   releases the deposit to a fill that delivers the quoted amount, so the solver fills or nothing
   moves; an unfilled offer is cancelled cooperatively. The quote wire shape ships here; the
@@ -556,6 +573,103 @@ terminal: the lockup stays funded and watched, a solver claim still ends the swa
 `pending`. The manager reports the same state when nothing is wired to act (`enableAutoActions:
 false`, or no callbacks) and the window has passed.
 
+**The two claim callbacks may be omitted.** `setCallbacks` accepts
+`AvailableRfqSwapManagerCallbacks` — the full contract with `claimOnchain` and `claimLockup`
+optional — so a consumer driving only lightning sends installs neither instead of stubbing them to
+throw. Dispatch is already kind-gated, so neither is reachable there. `saveSwap` is optional too
+(see below); `refundArkade` stays required.
+
+`RfqSwapManagerCallbacks` itself is unchanged and still means "fully wired", so a helper taking one
+and calling `claimOnchain` keeps its guarantee; only the parameter widens, which every existing
+caller satisfies. What moves from compile time to runtime is bought back as a **block**: a kind
+whose claim is missing reports `needs_counterparty` naming the gap, non-terminal and re-evaluated
+every pass, lifted the moment `setCallbacks` supplies it. Not `failed` — `setCallbacks` is
+installable late by design, and a terminal state would foreclose the late wiring this exists for.
+A manager with *no* callbacks at all keeps today's manual mode on the L1 half: it reports
+`claimable` and you act by hand.
+
+**Take `arkadeRefunder` rather than assembling `refundArkade` by hand.** It composes the atomic
+push and keeps the three rules the manager relies on structural instead of documented — an empty
+lockup returns `null`, and both `RefundNotLocallyPossibleError` and `LockupNeedsRecoveryError`
+propagate untouched.
+
+```ts
+manager.setCallbacks({
+    // `repository` is how it reaches `profile.signer`: the live swap the manager
+    // passes carries no descriptor, so the refund key is resolved by `rfqId`.
+    refundArkade: arkadeRefunder({ ark, indexer, wallet, repository }),
+    saveSwap,
+});
+```
+
+Keep the covenant on the swap (`request*`'s `script`, as a record's `lockup`): the refund is built
+from it, and a swap carrying only `lockupPkScript` is refused rather than pushed.
+
+### Let the manager own the records
+
+Give `RfqSwapManager` a `repository` and it persists RFQ swaps itself — the restore loop, the
+retention pass and every write, none of which a consumer has to compose:
+
+```ts
+const manager = new RfqSwapManager({
+    indexer,
+    contracts: await wallet.getContractManager(),
+    repository, // any AssetSwapRepository
+});
+manager.setCallbacks({ refundArkade, claimLockup });
+
+// Rebuild what was stored: retention first, then each record's covenant from
+// its own contract row, then `rebuildRfqSwap`. No caller input at all.
+const { restored, failed, pruned } = await manager.restoreFromRepository();
+await manager.start();
+
+// A NEW swap arrives with the request-time half a live record cannot carry.
+await manager.addSwap(swap, {
+    kind: "lightning_send",
+    lockupAddress: request.lockupAddress,
+    profile: rfqSecretsProfile(secrets, paymentHash),
+    fundingArkTxid,
+    amount,
+});
+```
+
+That second argument is the whole point. Composing the write by hand runs into an **origin trap**:
+`updateRfqSwapRecord(record, swap)` needs the record that does not exist yet, and
+`createRfqSwapRecord(origin, swap)` needs request-time facts the live swap never carried — so a
+swap's *first* record cannot be built from the swap alone. `addSwap`'s `origin` is where those
+facts arrive, and the manager keeps them for the swap's life. Omit it and one of two things
+happens: the store already holds a record, which *is* the origin, and it is read back; or it does
+not, and you get `RfqSwapOriginRequired` at the door rather than an unwritable record a pass later.
+An origin whose `kind` or `lockupAddress` is not this swap's is refused at that same door, for the
+same reason: the write that would catch it happens a pass later, with the funding broadcast.
+`start(swaps)` applies the same rule and is otherwise unchanged. Restored swaps carry their own.
+
+`restoreFromRepository` returns three disjoint lists, and every stored record is in exactly one.
+A record that cannot be rebuilt — no contract row (`LockupContractMissing`), covenant params that
+do not derive the funded address, a corridor with no handler — lands in `failed` with its error and
+stays in the store; it never strands the others and it is never silently dropped. `pruned` names
+what retention removed: terminal and more than `RFQ_SWAP_RETENTION_SECONDS` past `updatedAt`, never
+`needs_counterparty`. Retention runs first, so a retired record costs no contract lookup on its way
+out; `pruneRetiredSwaps()` is public for a process that wants it on its own cadence. Pass
+`{ params }` to take covenants from somewhere other than the contract store.
+
+**Two sinks, and both gate.** With a repository wired the canonical `RfqSwapRecord` is written
+first, then `saveSwap` if one is installed, and the pass counts as persisted only when both
+succeeded — which is exactly today's rule for `saveSwap`, applied to whichever sinks exist. A
+rejection from either leaves the record dirty and monitored, so waiters stay unsettled and a
+terminal swap is not finalized until the write it claims lands. A failed canonical write skips
+`saveSwap` entirely: projecting a state the record of record has just refused would put the
+secondary sink ahead of the primary. If your `saveSwap` writes that same repository by hand, delete
+the duplicate when you wire the dep — otherwise every pass writes twice — and keep the callback for
+genuinely secondary sinks. With neither wired, state stays in memory and dies with the process.
+
+**Terminal records name the transaction that ended them.** `RfqSwap.lockupSpendArkTxids` is
+stamped from the chain read that resolved the swap — the solver's claim on a send leg, its reclaim
+on a receive one, the trader's own claim when a receive settles. Nothing local produces those
+transactions, so no other field can name them, and without the stamp the only way to find them is
+another lockup read per terminal swap. Absent when the indexer named the checkpoint but not the ark
+transaction: fewer txids beats a wrong one.
+
 `preimageForSwapRecord` is the read path to wire, not a hand-rolled `contractPreimage` call: it
 knows which of the record's fields are derivation inputs, and it verifies the result against
 `paymentHash`. A caller that forgets to pass the salt gets a _wrong_ preimage from a wallet that can
@@ -640,6 +754,62 @@ through their stored `preimageHex` or their HD descriptor, and `DB_VERSION` is u
 
 Notes from before 0.0.1, kept for consumers who tracked the branch.
 
+- **`RfqSwapManager` can own its own persistence.** New optional
+  `RfqSwapManagerDeps.repository`, new `restoreFromRepository()` and `pruneRetiredSwaps()`, and
+  `addSwap(swap, origin?)` gains an optional second argument. Nothing narrows and nothing is
+  removed, so no existing caller changes: without a repository the manager persists through
+  `saveSwap` exactly as before. Two things to know if you wire it. `saveSwap` becomes a **second**
+  sink rather than the only one — it still gates waiters and finalization, so its semantics are
+  unchanged, but a callback that writes the same repository by hand now double-writes and should
+  drop the duplicate. And `addSwap` for a swap the store has never seen throws
+  `RfqSwapOriginRequired` unless you pass its origin, which is the only way its first record can be
+  written at all.
+- **`saveSwap` is optional at installation**, alongside the two claims — the same
+  `AvailableRfqSwapManagerCallbacks` relaxation extended one field. Omit it with a repository wired
+  and the record store is the only sink; omit both and state is process-local, which is what a
+  manager with no callbacks already did.
+- **`RfqSwap` and `RfqSwapRecord` gained `lockupSpendArkTxids?: string[]`** — the ark transactions
+  that spent the lockup, stamped by the manager from the chain read that ended the swap. Optional
+  and additive: no repository version bump, and a backend storing records whole already carries it.
+- **`RfqSwapState`, `RFQ_SWAP_TERMINAL_STATES` and `isRfqSwapTerminal` moved to
+  `src/rfqSwapState.ts`** so the record layer can read them without importing the manager at
+  runtime. `swapManager.ts` re-exports all three and the package entry point is unchanged, so no
+  import path breaks.
+- **`rfqSwapOriginOf(record)` is new** — a record's immutable half on its own. A record *is* an
+  origin plus manager state, so passing one where an origin is wanted type-checks and quietly
+  carries the old `failure`, `blockedReason` and `refundArkTxid` past `managerState`, which can
+  only set those fields and never clear them. Use this instead of spreading the record.
+- **`arkadeRefunder({ ark, indexer, wallet, repository })` ships the `refundArkade` wiring** that
+  was prose in two places. New export, nothing removed.
+- **`rfqSwapActivityInputs({ repository, indexer })` derives `SwapActivityInput[]` from the record
+  store** — the correlation helper `activity.ts` promised. `SwapActivityInput["kind"]` is now
+  `RfqSwapRecord["kind"]` rather than a literal union repeating it; source-compatible. Corridor
+  handlers gained an optional `activityTxids(profile)` so a leg's own claim txid comes from the
+  handler instead of a kind switch. The `indexer` is optional and consulted only for what a record
+  cannot answer: a record predating `fundingArkTxid`, and the counterparty's spend on a swap no
+  refund of ours ended. An unreachable indexer costs that record its extra txids, never a throw.
+- **`setCallbacks` takes `AvailableRfqSwapManagerCallbacks`** — `RfqSwapManagerCallbacks` with the
+  two kind-gated claims optional. Nothing breaks: the strict interface is untouched and the widened
+  parameter accepts every existing caller. A consumer driving one kind stops stubbing the claims it
+  cannot reach; in exchange, a missing claim blocks at runtime (`needs_counterparty`, non-terminal)
+  instead of being unrepresentable.
+- **The repository interface is at version `4`.** It gained
+  `getRfqSwap(rfqId): Promise<RfqSwapRecord | undefined>` — every backend is already keyed by
+  `rfqId`, so a consumer updating one record no longer scans them all. A miss returns `undefined`;
+  retention prunes terminal records, so absence is ordinary. All four in-tree backends implement it
+  and `DB_VERSION` is unchanged; a custom implementor adds the two-line read and bumps its own
+  `version` to `4`.
+- **`RfqSwapOrigin` gained `fundingArkTxid?`** — the ark transaction that funded the lockup. It is
+  origin, not manager state: the caller broadcasts the funding and knows the txid, while the manager
+  watches the lockup by script and never learns it. Optional and stored whole, so no migration.
+  Consumers stashing it in `profile` should move it: `profile` is merged as
+  `{ ...profile, ...handler.project(swap) }` on every write, so a key a corridor also projects is
+  silently overwritten.
+- **`readLockupFate` names the spends it observed.** `claimed` and `returned` now carry
+  `spends: readonly LockupSpend[]`, one per spent lockup output, with the `checkpointTxid` that
+  `spentBy` names and the `arkTxid` that rode it. History correlation wants `arkTxid`; the
+  checkpoint txid is the wrong value to correlate on alone. `unknown` and `open` claim no spend.
+
 - **Every derived address changed again, in both corridors — the unilateral ladder was re-spaced.**
   `unilateralRefundDelay` now sits **level with** `claimDelay` instead of one 512s step above it,
   and `unilateralRefundWithoutReceiverDelay` sits `SOLO_REFUND_HEADROOM_SECONDS` (4096s, newly
@@ -719,10 +889,100 @@ scanned? })` — the server key is required because a spend is classified by reb
 - **A spend that cannot be classified is no longer restored as `fulfilled`.** It leaves the funding
   txid unanswered so a later scan decides it. Records are never written on a guess.
 - **`AssetSwap` gained `signingDescriptor?`**, and `preimageHex` now means "P that cannot be
-  re-derived" — caller-supplied, or minted for a static descriptor. The repository version stays
-  `1` — the package is unreleased, so there is no stored record to migrate — but a field-mapped
-  backend must persist the record whole: silently dropping `preimageHex` leaves a static swap
-  permanently unclaimable.
+  re-derived" — caller-supplied, or minted for a static descriptor. A field-mapped backend must
+  persist the record whole: silently dropping `preimageHex` leaves a static swap permanently
+  unclaimable.
+- **The repository interface is at version `3`.** It gained `saveRfqSwap` / `getAllRfqSwaps` /
+  `removeRfqSwap` for monitored RFQ swaps, and the IndexedDB backend a matching `rfqSwaps` object
+  store at `DB_VERSION` 2. Version `2` was the shape 0.0.5 released — swaps, scan cursor, markets,
+  with `preimageSaltHex` on the swap record — and `DB_VERSION` was 1 there, so this is the database's
+  first version increase. The bump is deliberate: an implementor must acknowledge the new methods
+  rather than silently satisfy an older shape. Existing databases upgrade in place: the new store is
+  added and the three original ones are untouched. **`DB_VERSION` 2 is a one-way door** — a browser
+  whose database has upgraded cannot be rolled back to 0.0.5, which opens it at version 1 and fails
+  `VersionError` across the whole swap store, not just the RFQ half. Store RFQ records whole for the
+  same reason as above: what is in one is what nothing else can recover — the manager's own state,
+  and, inside the corridor's `profile`, its keys and its gates.
+- **An RFQ record's keys live in its corridor's `profile`, under two keys.** `profile.signer` holds
+  `signingDescriptor` — which wallet key signs this leg, on any corridor. `profile.hashlock` holds
+  `paymentHash` (the covenant binds `hash160` of it, which is one-way) plus, **only on legs we
+  claim**, `preimageHex` or `preimageSaltHex`. The record's own half — `kind`, `lockupAddress`,
+  `amount`, the manager's state — recovers nothing on its own, so a backend that drops either nested
+  object loses the signer or the claim secret exactly as one dropping `preimageHex` used to. Two keys
+  rather than one because a hashlock belongs to a corridor and a signer does not: a corridor that
+  settles without a preimage still has a leg to sign and refund.
+
+    ```ts
+    // In. One call per leg, whatever that leg's provisioning produced — never
+    // hand-mapped: copying `signingDescriptor` and `preimageHex` across by hand
+    // drops the salt a static wallet's P derives from, and the swap is
+    // unclaimable with nothing to say so until claim time.
+    const record = createRfqSwapRecord(
+        {
+            kind: "lightning_receive",
+            lockupAddress: result.address,
+            profile: {
+                ...rfqSecretsProfile(result.secrets, result.treeParams.paymentHash),
+                expectedAmount: result.expectedAmount,
+                payoutAddress: result.payoutAddress,
+            },
+        },
+        swap,
+    );
+
+    // Out, and WHICH reader depends on the leg. The refund signer, on any leg:
+    const sender = await senderIdentityForSwapRecord(wallet, rfqSignerOf(record)!);
+    // P, only where we claim — `lightning_receive`, `onchain_send`:
+    const claim = rfqClaimSecretOf(record);
+    if (claim) await preimageForSwapRecord(wallet, claim); // hash-checked
+    ```
+
+- **`lightning_send` has a payment hash and no preimage**, so `rfqClaimSecretOf` answers `undefined`
+  for it. P belongs to the payee and its descriptor is a *refund* key from `provisionRefundKey`.
+  Wiring the claim helper to all three legs does not degrade gracefully: the salted arm derives
+  *some* P off the refund descriptor and the payment-hash check rejects it, so a correct record reads
+  as corrupt. That leg's reader is `rfqSignerOf`.
+- **Non-hashlock corridors carry no `profile.hashlock` at all** — no `paymentHash`, no preimage
+  material, no placeholder; the key is simply absent, which is why `rfqSecretsProfile` takes the
+  payment hash as an optional second argument. They still write `profile.signer` if their leg is one
+  this wallet signs. The three corridors shipping today all lock to a preimage, but that is a fact
+  about them and not about RFQ. A corridor needing more than one descriptor — a co-signed leg, a
+  second key for an L1 half — extends `profile.signer` rather than fabricating a hashlock.
+- **Both readers answer `undefined` only for "this corridor has no such half", and throw on a half
+  that is there and unusable.** Neither ever hands back a partial projection:
+  `preimageForSwapRecord` verifies only when the projection carries a `paymentHash`, so one missing
+  its hash would claim with an *unverified* preimage instead of failing. A thrown
+  `PreimageNotRecoverableError("malformed-record")` is a storage bug, not a protocol state — treating
+  it as "no preimage available" and falling back to a refund reads the two as the same thing.
+- **An RFQ record stores no covenant.** The tree lives in the lockup's contract row, written before
+  the address could be funded and keyed by the script its params derive — a key `createContract`
+  refuses to write unless they reproduce it. So the rebuild takes the params from the caller:
+
+    ```ts
+    const params = await lockupContractParams(
+        await wallet.getContractManager(),
+        record.lockupAddress,
+    );
+    const swap = rebuildRfqSwap(record, params);
+    ```
+
+    `lockupContractParams` throws `LockupContractMissing` when this wallet has no row for the lockup —
+    a cleared contract store, or a record from elsewhere. A consumer that would rather not depend on
+    the contract store can keep its own copy of
+    `VHTLCV2ContractHandler.serializeParams(script.options)` and pass that instead; either way the
+    params are checked against the record's `lockupAddress` before a swap is handed back, so the wrong
+    row fails at restore rather than at refund time. **Superseded** for a consumer that wires
+    `RfqSwapManagerDeps.repository`: `restoreFromRepository()` is this loop, over every stored
+    record, with retention in front of it.
+
+- **Pruning is the consumer's unless the manager holds the repository.** `shouldRetainRfqSwap(record,
+  now)` answers whether a record is still worth keeping — live swaps and `needs_counterparty`
+  always, terminal ones for `RFQ_SWAP_RETENTION_SECONDS` (30 days) after `updatedAt`. Sweep with it
+  at boot and pass the rejects to `removeRfqSwap`; skip it and a hot wallet's `rfqSwaps` store grows
+  without bound. `now` is **unix seconds**, the unit `RfqSwap.updatedAt` carries — `Date.now()` would
+  retire every terminal record after ~43 minutes. **Superseded** for a consumer that wires
+  `RfqSwapManagerDeps.repository`: `pruneRetiredSwaps()` is that sweep, and
+  `restoreFromRepository()` runs it first.
 - **A write that gates something irreversible throws; one that follows it does not.**
   `addAssetSwap` and `updateAssetSwap` throw on a failed read or write — nothing irreversible may
   happen until the record is durable, which is why `cancelOffer` writes its `cancelling` marker
@@ -752,4 +1012,5 @@ scanned? })` — the server key is required because a spend is classified by reb
   receive swap monitored with nothing wired to claim it expires quietly, and a compile error is the
   right way to learn a corridor was added. A caller with only send swaps can satisfy it with a stub
   that throws. `RfqSwapActionName` gains `"claimLockup"`, so an exhaustive `switch` over it needs a
-  new arm.
+  new arm. **Superseded:** such a caller now installs `AvailableRfqSwapManagerCallbacks` and omits
+  both — see above.

package/dist/{chunk-WGRU2DBF.js → chunk-6ZUS47GA.js}

@@ -1,8 +1,9 @@
 // src/repository.ts
 var marketsCacheKey = (network, registry) => `arkade-intents-markets-${network}-${registry}`;
 var InMemoryAssetSwapRepository = class {
-  version = 2;
+  version = 4;
   swaps = /* @__PURE__ */ new Map();
+  rfqSwaps = /* @__PURE__ */ new Map();
   scanned = /* @__PURE__ */ new Set();
   markets = /* @__PURE__ */ new Map();
   async saveSwap(swap) {
@@ -11,6 +12,18 @@ var InMemoryAssetSwapRepository = class {
   async getAllSwaps() {
     return [...this.swaps.values()];
   }
+  async saveRfqSwap(record) {
+    this.rfqSwaps.set(record.rfqId, record);
+  }
+  async getRfqSwap(rfqId) {
+    return this.rfqSwaps.get(rfqId);
+  }
+  async getAllRfqSwaps() {
+    return [...this.rfqSwaps.values()];
+  }
+  async removeRfqSwap(rfqId) {
+    this.rfqSwaps.delete(rfqId);
+  }
   async getScannedTxids() {
     return new Set(this.scanned);
   }
@@ -25,6 +38,7 @@ var InMemoryAssetSwapRepository = class {
   }
   async clear() {
     this.swaps.clear();
+    this.rfqSwaps.clear();
     this.scanned.clear();
     this.markets.clear();
   }