@arkade-os/swap 0.1.0-rc.9 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/README.md +261 -252
  2. package/dist/advanced.cjs +6613 -3224
  3. package/dist/advanced.d.cts +328 -283
  4. package/dist/advanced.d.ts +328 -283
  5. package/dist/advanced.js +347 -34
  6. package/dist/chunk-A3SHHRX4.js +104 -0
  7. package/dist/chunk-FMRAV77W.js +3065 -0
  8. package/dist/chunk-T4FHBWZI.js +3459 -0
  9. package/dist/{chunk-NS3K6BZG.js → chunk-YHESEL4I.js} +1792 -636
  10. package/dist/index.cjs +6901 -3901
  11. package/dist/index.d.cts +71 -243
  12. package/dist/index.d.ts +71 -243
  13. package/dist/index.js +131 -167
  14. package/dist/lockupContract-CIXkJPxV.d.ts +148 -0
  15. package/dist/lockupContract-CkhWMKCo.d.cts +148 -0
  16. package/dist/node/index.cjs +61 -10
  17. package/dist/node/index.d.cts +307 -635
  18. package/dist/node/index.d.ts +307 -635
  19. package/dist/node/index.js +65 -10
  20. package/dist/nostr.cjs +427 -49
  21. package/dist/nostr.d.cts +59 -70
  22. package/dist/nostr.d.ts +59 -70
  23. package/dist/nostr.js +268 -36
  24. package/dist/offer-BPD2ortO.d.ts +269 -0
  25. package/dist/offer-Diff5Flc.d.cts +269 -0
  26. package/dist/offerFillPlan-B-5ae_gQ.d.cts +1671 -0
  27. package/dist/offerFillPlan-CJzneX6F.d.ts +1671 -0
  28. package/dist/protocol.cjs +5717 -4275
  29. package/dist/protocol.d.cts +258 -328
  30. package/dist/protocol.d.ts +258 -328
  31. package/dist/protocol.js +200 -224
  32. package/dist/repositories/realm/index.cjs +55 -11
  33. package/dist/repositories/realm/index.d.cts +18 -30
  34. package/dist/repositories/realm/index.d.ts +18 -30
  35. package/dist/repositories/realm/index.js +49 -12
  36. package/dist/repositories/sqlite/index.cjs +61 -10
  37. package/dist/repositories/sqlite/index.d.cts +7 -6
  38. package/dist/repositories/sqlite/index.d.ts +7 -6
  39. package/dist/repositories/sqlite/index.js +57 -11
  40. package/dist/repository-BBVRh9ez.d.ts +2357 -0
  41. package/dist/repository-C4pvymhs.d.cts +2357 -0
  42. package/dist/{rfq-BO6o7NwS.d.ts → rfq-C0tHOvn6.d.cts} +323 -444
  43. package/dist/{rfq-BO6o7NwS.d.cts → rfq-C0tHOvn6.d.ts} +323 -444
  44. package/dist/watch-7BiRa4oB.d.ts +74 -0
  45. package/dist/watch-Bxq-lx_6.d.cts +74 -0
  46. package/package.json +10 -10
  47. package/dist/chunk-JFKGMPMH.js +0 -3456
  48. package/dist/chunk-LLG7RD2T.js +0 -1499
  49. package/dist/chunk-U7VWWTL6.js +0 -66
  50. package/dist/errors-CNISbN0M.d.ts +0 -2218
  51. package/dist/errors-DwNhIP0N.d.cts +0 -2218
  52. package/dist/lockupContract-C8-Mcg69.d.ts +0 -664
  53. package/dist/lockupContract-mIt4syse.d.cts +0 -664
  54. package/dist/repository-CGPLbjBe.d.ts +0 -3489
  55. package/dist/repository-DSGGq0ct.d.cts +0 -3489
  56. package/dist/watch-DWyVqyEN.d.cts +0 -96
  57. package/dist/watch-DmvHNX6T.d.ts +0 -96
@@ -1,71 +1,40 @@
1
1
  import { SQLExecutor } from '@arkade-os/sdk/repositories/sqlite';
2
2
  import { DiscoveredMarket } from '@arkade-os/solver-discovery';
3
- import { VHTLC, NetworkName } from '@arkade-os/sdk';
3
+ import { VHTLC, InputExpiryFloor, NetworkName, PageRequest, PageResult } from '@arkade-os/sdk';
4
4
 
5
5
  /**
6
- * The platform's per-user configuration directory.
7
- *
8
- * The three conventions, in the order each platform expects:
9
- *
10
- * - Linux and the BSDs follow the XDG Base Directory spec — `$XDG_CONFIG_HOME`
11
- * when set to an absolute path, else `~/.config`. A relative value is
12
- * ignored, which the spec requires rather than suggests.
13
- * - macOS uses `~/Library/Application Support`.
14
- * - Windows uses `%APPDATA%`, falling back to the roaming path under the home
15
- * directory when the variable is missing — as it is in some service contexts.
6
+ * The platform's per-user configuration directory: `%APPDATA%` on Windows (falling back to the
7
+ * roaming path, as the variable is missing in some service contexts), `~/Library/Application
8
+ * Support` on macOS, else XDG (`$XDG_CONFIG_HOME` if absolute, else `~/.config`).
16
9
  */
17
10
  declare const configDir: (env?: NodeJS.ProcessEnv) => string;
18
11
  /**
19
- * The default database path for one network.
20
- *
21
- * Returned rather than created: opening it is what creates the directory, and a
22
- * caller that only wants to know where the file would be — to report it, to
23
- * back it up, to delete it — should not have to make one as a side effect.
12
+ * The default database path for one network. Returned, not created, so callers that only report,
13
+ * back up or delete it don't make a directory as a side effect.
24
14
  */
25
15
  declare const swapDatabasePath: (network: string, env?: NodeJS.ProcessEnv) => string;
26
16
 
27
17
  /** @deprecated Use `Outcome`. Moved off the package root to `@arkade-os/swap/protocol`. */
28
18
  type AssetSwapStatus = "pending" | "cancelling" | "fulfilled" | "cancelled" | "recoverable" | "awaiting_fill" | "claimable" | "claimed" | "refunded_l1";
29
19
  /**
30
- * The record fields a wallet-provisioned secret becomes — what
31
- * {@link swapSecretsToRecord} emits, and what every record type carrying swap
32
- * secrets embeds.
33
- *
34
- * A named type rather than four fields restated per record: the mapper and the
35
- * records it feeds must agree exactly, and a record that silently omits one of
36
- * these round-trips a swap whose preimage cannot be re-derived. Embedding makes
37
- * the omission a compile error instead.
38
- *
39
- * **Only `preimageHex` is secret.** `signingDescriptor` and `preimageSaltHex`
40
- * are public derivation inputs — they must survive a field-mapped backend, but
41
- * they leak nothing without the seed.
42
- *
43
- * @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
20
+ * The record fields a wallet-provisioned secret becomes; every secret-carrying record embeds it, so
21
+ * omitting one (an unrecoverable preimage) is a compile error. **Only `preimageHex` is secret**; the
22
+ * descriptor and salt are public derivation inputs that leak nothing without the seed.
44
23
  */
45
24
  interface SwapSecretsProjection {
46
- /**
47
- * The wallet descriptor this swap's sender key comes from — a fresh HD
48
- * child, or a static wallet's `tr(pubkey)`. Public — the signer
49
- * re-derives from the wallet, so the record carries no key material.
50
- */
25
+ /** The wallet descriptor this swap's sender key comes from (a fresh HD child, or a static
26
+ * wallet's `tr(pubkey)`). Public; the record carries no key material. */
51
27
  signingDescriptor?: string;
52
28
  /** P, hex, when it cannot be re-derived from the seed at all: the user
53
29
  * supplied it, or the signer cannot sign deterministically. The swap's only
54
30
  * claim secret when present. */
55
31
  preimageHex?: string;
56
- /**
57
- * The salt P derives from, hex, on the salted arm — what a static wallet
58
- * gets instead of storing P. **Public**, and unlike every other field here
59
- * it is minted per swap: it is what stops one repeating key from handing
60
- * every swap the same preimage.
61
- */
32
+ /** The salt P derives from, hex — what a static wallet stores instead of P. **Public**, and minted
33
+ * per swap: it stops one repeating key from giving every swap the same preimage. */
62
34
  preimageSaltHex?: string;
63
35
  }
64
- /** The row {@link AssetSwapRepository} stores. A custom storage backend is
65
- * written against this, which is why it is a root export rather than a
66
- * `/protocol` one — the interface it appears in is part of the v2 surface.
67
- * What it is NOT is the v2 client's own record: that is `SwapRecord`, and
68
- * `client.swaps()` projects it as `Swap`. */
36
+ /** The row {@link AssetSwapRepository} stores. A root export because custom storage backends are
37
+ * written against it. Not the v2 client's record (that is `SwapRecord`, projected as `Swap`). */
69
38
  interface AssetSwap extends SwapSecretsProjection {
70
39
  /** Funding txid — the swap's identity. */
71
40
  id: string;
@@ -116,26 +85,17 @@ interface OnchainHtlc {
116
85
  }
117
86
 
118
87
  /**
119
- * Where a monitored RFQ swap stands, and which of those states end it.
120
- *
121
- * Its own module rather than a corner of `swapManager.ts` because the
122
- * dependency runs the other way: the record layer decides retention from
123
- * {@link isRfqSwapTerminal}, and the manager persists through the record
124
- * layer. With the vocabulary here, neither has to import the other at runtime.
125
- * `swapManager.ts` re-exports all three names, so nothing about the public
126
- * surface moved.
88
+ * Where a monitored RFQ swap stands, and which of those states end it. Its own module so the
89
+ * record layer (retention via {@link isRfqSwapTerminal}) and the manager need not import each
90
+ * other at runtime; `swapManager.ts` re-exports all three names.
127
91
  */
128
92
  /**
129
- * Where a monitored swap stands.
93
+ * Where a monitored swap stands; the vocabulary of `CorridorSwapRecord.state`. `Outcome`, from
94
+ * `client.onUpdate()`, is the client-level projection over it.
130
95
  *
131
- * `claimable` and `claimed` are the states of a swap the TRADER has something
132
- * to claim on: the L1 fill on an onchain send, and the solver-funded lockup on
133
- * a receive. Only `lightning_send` has neither — there the solver claims the
134
- * lockup, and the trader's only move is the refund.
135
- *
136
- * A root export because `CorridorSwapRecord.state` is this vocabulary: a
137
- * caller reading a record off `client.swaps()` names it. `Outcome`, delivered
138
- * by `client.onUpdate()`, is the client-level projection over it.
96
+ * `claimable`/`claimed` apply when the TRADER has something to claim: the L1 fill on an onchain
97
+ * send, the solver-funded lockup on a receive. `lightning_send` has neither; the trader's only
98
+ * move there is the refund.
139
99
  */
140
100
  type RfqSwapState =
141
101
  /** Live; nothing actionable yet. On a receive leg this covers the whole
@@ -146,71 +106,45 @@ type RfqSwapState =
146
106
  * least `expectedAmount` on a receive. */
147
107
  | "claimable"
148
108
  /**
149
- * The trader's claim has been made — its L1 broadcast on an onchain send,
150
- * its Arkade submission on a receive.
151
- *
152
- * **On a receive this is a local belief and not a chain fact**, which is
153
- * why it is not terminal: `settled` is the chain's answer, and `refunded`
154
- * is still reachable from here if the claim never lands and the solver
155
- * takes the lockup back.
109
+ * The trader's claim has been made (L1 broadcast on an onchain send, Arkade submission on a
110
+ * receive). **On a receive this is a local belief, not a chain fact**, hence not terminal:
111
+ * `refunded` is still reachable if the claim never lands.
156
112
  */
157
113
  | "claimed"
158
114
  /**
159
- * This wallet will not act, and only the counterparty can change that.
115
+ * This wallet will not act, and only the counterparty can change that
116
+ * (`RfqSwapCommon.blockedReason` says why).
160
117
  *
161
- * On a send leg: the Arkade refund cannot be pushed from here — no secrets
162
- * on the record, a descriptor from another seed, or nothing wired to act —
163
- * so the lockup comes back only if the counterparty claims it or the wallet
164
- * that can sign it is restored. On a receive leg: the trader holds no
165
- * refund at all, so this is a lockup that cannot be claimed — funded for
166
- * less than the swap agreed (publishing `P` for it is the whole attack
167
- * `LockupAmountMismatchError` exists to refuse), or one whose claim window
168
- * shut unclaimed. `RfqSwapCommon.blockedReason` says which.
118
+ * Send leg: the Arkade refund cannot be pushed from here (no secrets, foreign descriptor, or
119
+ * nothing wired). Receive leg: the lockup cannot be claimed — underfunded (publishing `P`
120
+ * for it is the attack `LockupAmountMismatchError` refuses) or its claim window shut.
169
121
  *
170
- * **Not terminal, and not a dead end.** The money is still at the lockup,
171
- * so the counterparty's move is still observable and still ends the swap;
172
- * and the refusal is re-checked every pass, so restoring the right wallet,
173
- * wiring the callbacks, or the solver topping the lockup up returns the
174
- * swap to `pending` and resumes the normal drive. For an onchain-send swap
175
- * it says nothing about the L1 half, which keeps being driven and claimed.
122
+ * **Not terminal.** The money is still at the lockup and the refusal is re-checked every
123
+ * pass, so fixing the cause returns the swap to `pending`. On an onchain send the L1 half
124
+ * keeps being driven regardless.
176
125
  */
177
126
  | "needs_counterparty"
178
127
  /**
179
- * Terminal: the lockup was spent by a hash-verified claim. Read off chain,
180
- * never reported.
181
- *
182
- * On a send leg that claim is the counterparty's, and it is proof the
183
- * counterparty completed its side. On a receive leg it is the TRADER's own
184
- * — matched by the hash and not by our txid, so a claim that lands without
185
- * us still counts (see `RfqSwapManager`).
128
+ * Terminal: the lockup was spent by a hash-verified claim, read off chain, never reported.
129
+ * On a send leg it is the counterparty's claim; on a receive leg the TRADER's own, matched by
130
+ * hash rather than our txid so a claim that lands without us still counts.
186
131
  */
187
132
  | "settled"
188
133
  /**
189
- * Terminal: the lockup was spent by something other than a claim.
190
- *
191
- * On a send leg that is the money coming back, by the solver's hand or the
192
- * trader's. **On a receive leg it is a LOSS**: the lockup was the solver's
193
- * money, every non-claim leaf is the solver's, and a swap that ends here
194
- * ended with the trader's incoming payment never arriving. It is also where
195
- * a receive swap ends when its window closes with nothing left to observe —
196
- * see `RfqSwapManager`.
134
+ * Terminal: the lockup was spent by something other than a claim. On a send leg that is the
135
+ * money coming back. **On a receive leg it is a LOSS**: every non-claim leaf is the
136
+ * solver's. Also where a receive swap ends when its window closes with nothing to observe.
197
137
  */
198
138
  | "refunded"
199
139
  /** Terminal: an action failed and its window closed. */
200
140
  | "failed";
201
141
 
202
142
  /**
203
- * What the manager needs to register a swap's lockup with the wallet, so the
204
- * indexer pushes its funding and its spend instead of being asked every few
205
- * seconds.
143
+ * What the manager needs to register a swap's lockup with the wallet, so the indexer
144
+ * pushes its funding and spend.
206
145
  *
207
- * Both fields are things the caller already holds. `script` is the very object
208
- * `pushRefundWithoutReceiver` and `pushClaim` take, so a caller wired to act has
209
- * it in hand; `address` is the request entrypoint's own return value. The
210
- * address is taken rather than re-derived on purpose — the row's address must be
211
- * the one that was actually funded, and a local re-derivation would silently use
212
- * the SDK's default network, which is the exact bug `registerOfferContract`
213
- * guards against.
146
+ * `address` is taken, not re-derived: it must be the one actually funded, and a local
147
+ * re-derivation would silently use the SDK's default network.
214
148
  *
215
149
  * @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
216
150
  */
@@ -224,108 +158,60 @@ interface RfqSwapCommon {
224
158
  /** The negotiation id — this record's identity. */
225
159
  rfqId: string;
226
160
  state: RfqSwapState;
227
- /** The Arkade lockup's scriptPubKey — `swapPkScript` from any of the four
228
- * request entrypoints. This is what the manager watches to decide the swap:
229
- * it is the only handle on the covenant whose spend witness says whether
230
- * the swap settled or came back. */
161
+ /** The Arkade lockup's scriptPubKey (`swapPkScript` from the request entrypoint): the
162
+ * only handle on the covenant whose spend witness decides the swap. */
231
163
  lockupPkScript: Uint8Array;
232
- /** The covenant behind {@link lockupPkScript}, when the caller wants the
233
- * lockup registered with a contract manager. Optional: without it the
234
- * manager still watches the swap on its timer, it just cannot subscribe.
235
- * See {@link RfqSwapManagerDeps.contracts}. */
164
+ /** The covenant behind {@link lockupPkScript}. Without it the manager still polls the
165
+ * swap, it just cannot subscribe; see {@link RfqSwapManagerDeps.contracts}. */
236
166
  lockup?: RfqSwapLockup;
237
167
  /**
238
- * `sha256(P)`, hex — the quote's `payment_hash`. The claim leaf can only
239
- * be spent by revealing a value that hashes to this, which is what makes a
240
- * settlement provable rather than reported. For an onchain send this is
241
- * the SAME hash the L1 `htlc` carries: one `P` unlocks both legs.
242
- *
243
- * True of the three corridors that exist today and only of them: a hashlock
244
- * belongs to a CORRIDOR, and a banco-style one settles without any. The
245
- * stored record already says so — the hash lives in `profile.hashlock`, not
246
- * on `RfqSwapRecord` — and this field follows onto the per-corridor swap
247
- * types when the first such corridor lands. Do not read the current shape as
248
- * final.
168
+ * `sha256(P)`, hex — the quote's `payment_hash`. The claim leaf is spendable only by
169
+ * revealing its preimage, which makes settlement provable. For an onchain send the L1
170
+ * `htlc` carries the SAME hash. Not final: a hashlock belongs to a corridor (the stored
171
+ * record keeps it in `profile.hashlock`), and hashlock-free corridors may follow.
249
172
  */
250
173
  paymentHash: string;
251
174
  /**
252
- * `refund_locktime` from the quote, unix seconds.
253
- *
254
- * Whose deadline it is inverts with the direction, and so does what to do
255
- * about it. On a send leg it is the TRADER's: the lockup is the trader's
256
- * money and this gates the refund that takes it back, so it is a moment to
257
- * act AFTER. On a receive leg it is the SOLVER's: the trader has no refund
258
- * leaf at all, and this is the moment to have claimed BEFORE.
175
+ * `refund_locktime` from the quote, unix seconds. On a send leg it is the TRADER's:
176
+ * refund AFTER it. On a receive leg it is the SOLVER's: the trader must have claimed
177
+ * BEFORE it.
259
178
  */
260
179
  refundLocktime: number;
261
180
  createdAt: number;
262
181
  updatedAt: number;
263
- /** Set once the trader's own `refundWithoutReceiver` push landed. */
182
+ /** The trader's own refund: the `refundWithoutReceiver` push that landed, or on
183
+ * `onchain_receive` the L1 HTLC refund. */
264
184
  refundTxid?: string;
265
185
  /**
266
- * The ark transactions that SPENT the lockup, stamped from the chain read
267
- * that ended the swap — `LockupFate.spends`, whichever verdict it reached.
268
- *
269
- * The counterparty's move, on every leg but one: a solver claim on a send,
270
- * a solver reclaim on a receive, and — the exception — the trader's own
271
- * claim when a receive settles. What they have in common is that no local
272
- * action produced them, so nothing else on this record can name them:
273
- * {@link refundTxid} names only a push this wallet made, and
274
- * `claimTxid` only a submission it made.
275
- *
276
- * Stamped so a terminal record answers "which transaction ended this" from
277
- * storage. Without it the only source is another read of the lockup — a
278
- * network round trip per terminal swap, which is what activity correlation
279
- * has to pay on the offline-first path where it is least affordable.
280
- *
281
- * Absent when the swap ended without a chain verdict, or when the indexer
282
- * named the checkpoint but not the ark transaction — the same `txid`
283
- * `LockupSpend` declares optional, for the same reason.
186
+ * The ark transactions that SPENT the lockup, from the chain read that ended the swap
187
+ * (`LockupFate.spends`) — moves no local action produced, so a terminal record can
188
+ * name them without another network read. Absent without a chain verdict, or when the
189
+ * indexer named only the checkpoint.
284
190
  */
285
191
  lockupSpendTxids?: string[];
286
192
  /**
287
- * `P`, hex — the preimage the solver revealed to claim the lockup,
288
- * stamped from the chain read that ended the swap.
289
- *
290
- * Lightning sends only, and the one leg where the wallet cannot produce
291
- * `P` itself: the payee mints it, so the quote carries only
292
- * {@link paymentHash}. The claiming legs keep their own secret in
293
- * `profile`, where `preimageForSwapRecord` recovers it — so this is a
294
- * settlement receipt, not a second home for a claim secret, and not a
295
- * secret at all: it is already public in the witness it came from.
296
- * `readLockupFate` hashes it against {@link paymentHash} before returning
297
- * it, so what is stamped here is verified by construction.
298
- *
299
- * Absent on the other legs, and on a send that did not settle.
193
+ * `P`, hex — the preimage the solver revealed to claim the lockup. Lightning sends
194
+ * only (the payee mints `P`). A public settlement receipt, not a claim secret;
195
+ * `readLockupFate` verifies it against {@link paymentHash} before it is stamped.
300
196
  */
301
197
  settlementPreimageHex?: string;
302
198
  /** Why `state` is `failed`. */
303
199
  failure?: string;
304
200
  /**
305
- * Last local claim error while the receive swap is still retryable.
306
- *
307
- * Distinct from terminal `failure`: this records a claim attempt that failed
308
- * before the window closed. If the window later closes without a submitted
309
- * claim, it becomes the terminal failure reason.
201
+ * Last local claim error while the receive swap is still retryable. Becomes the
202
+ * terminal `failure` if the window closes without a submitted claim.
310
203
  */
311
204
  claimFailure?: string;
312
205
  /** Why `state` is `needs_counterparty`. Distinct from {@link failure},
313
206
  * which means an action was attempted and did not work. */
314
207
  blockedReason?: string;
315
208
  }
316
- /** `arkade:BTC->lightning:BTC`. Nothing for the trader to claim: the solver
317
- * claims the lockup with the preimage it learns by paying the invoice — which
318
- * is exactly why that spend's witness is proof the payment landed.
319
- *
320
- * @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
321
- */
209
+ /** `arkade:BTC->lightning:BTC`. The solver claims the lockup with the preimage it learns
210
+ * by paying, so that spend's witness proves the payment landed. */
322
211
  interface LightningSendSwap extends RfqSwapCommon {
323
212
  kind: "lightning_send";
324
213
  }
325
- /** `arkade:BTC->onchain:BTC`. Carries the L1 half the trader must claim.
326
- *
327
- * @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
328
- */
214
+ /** `arkade:BTC->onchain:BTC`. Carries the L1 half the trader must claim. */
329
215
  interface OnchainSendSwap extends RfqSwapCommon {
330
216
  kind: "onchain_send";
331
217
  /** The locally derived HTLC from `requestOnchainSend` — the manager reads
@@ -333,142 +219,124 @@ interface OnchainSendSwap extends RfqSwapCommon {
333
219
  htlc: OnchainHtlc;
334
220
  /** `profile.min_confirmations` from the quote. */
335
221
  minConfirmations: number;
222
+ /** The quote's `to_amount`, captured at REQUEST time: read at claim time it
223
+ * would be whatever the solver funded. */
224
+ expectedAmount: number;
336
225
  /** Where {@link RfqSwapManagerCallbacks.claimOnchain} pays; optional only
337
226
  * so records predating its profile slot still restore. */
338
227
  payoutPkScript?: Uint8Array;
339
- /** The fill's outpoint, learned on first sighting. Without it a SPENT
340
- * HTLC reads as never funded — see {@link classifyOnchainHtlc}. */
228
+ /** The fill's outpoint and value, learned on first sighting. Without it a SPENT HTLC
229
+ * reads as never funded, and no replacement claim can be signed ({@link classifyOnchainHtlc}). */
341
230
  funding?: {
342
231
  txid: string;
343
232
  vout: number;
233
+ amount?: number;
344
234
  };
345
- /** Our L1 claim's txid. */
235
+ /** Our L1 claim's txid, the sat/vB it went out at, and when (unix seconds). */
346
236
  claimTxid?: string;
237
+ claimFeeRateSatVb?: number;
238
+ claimBroadcastAt?: number;
239
+ /** Whether the chain reports {@link claimTxid} confirmed; `undefined` when it cannot
240
+ * say. Read fresh each pass, never persisted: a stale `true` is what loses money. */
241
+ claimConfirmed?: boolean;
347
242
  }
348
243
  /**
349
- * `lightning:BTC->arkade:BTC`. The inverted leg: the SOLVER funds the lockup
350
- * and the TRADER claims it, and that claim is what publishes `P` and lets the
351
- * solver settle the payer's held Lightning HTLC.
352
- *
353
- * Two consequences shape how this record is driven, both of them absent from
354
- * the send legs:
244
+ * `lightning:BTC->arkade:BTC`. The SOLVER funds the lockup and the TRADER claims it,
245
+ * publishing `P` so the solver can settle the payer's held Lightning HTLC.
355
246
  *
356
- * - **There is no trader-side refund.** Every non-claim leaf of this covenant
357
- * is the solver's, so the manager never calls
358
- * {@link RfqSwapManagerCallbacks.refundArkade} for one of these. A swap that
359
- * is not claimed is simply lost — the solver reclaims at
360
- * {@link RfqSwapCommon.refundLocktime} and the payer is refunded when the
361
- * held HTLC lapses.
362
- * - **The claim is the whole swap, and it is on a deadline.** The trader must
363
- * be online for it: covclaimd cannot claim this covenant today, so the claim
364
- * packet's offline path does not run.
365
- *
366
- * @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
247
+ * - **No trader-side refund.** Every non-claim leaf is the solver's; an unclaimed swap is
248
+ * lost when the solver reclaims at {@link RfqSwapCommon.refundLocktime}.
249
+ * - **The claim is the whole swap, on a deadline**, and the trader must be online:
250
+ * covclaimd cannot claim this covenant today.
367
251
  */
368
252
  interface LightningReceiveSwap extends RfqSwapCommon {
369
253
  kind: "lightning_receive";
370
254
  /**
371
- * What the lockup must carry — the quote's `to_amount`, captured at REQUEST
372
- * time and persisted with the record.
255
+ * What the lockup must carry — the quote's `to_amount`, captured at REQUEST time.
373
256
  *
374
- * **Not re-derivable, and not optional.** Captured at claim time it would
375
- * be whatever the solver funded, which is the dust-funding attack rather
376
- * than a check on it. A record that reaches the manager without a finite
377
- * value here is reported `needs_counterparty` and never claimed: a
378
- * comparison against `undefined` or `NaN` is false, so an unusable
379
- * comparand does not fail the value gate, it deletes it.
257
+ * **Not re-derivable, not optional.** Read at claim time it would be whatever the
258
+ * solver funded (the dust-funding attack). A non-finite value is reported
259
+ * `needs_counterparty` and never claimed: comparing against `undefined`/`NaN` is
260
+ * false, which would delete the value gate rather than fail it.
380
261
  */
381
262
  expectedAmount: number;
382
263
  /** Our Arkade claim's txid, once submitted. Set from the callback's return
383
264
  * and never from a chain read — the chain's answer is `settled`. */
384
265
  claimTxid?: string;
385
266
  }
267
+ /**
268
+ * `onchain:BTC->arkade:BTC`. A {@link LightningReceiveSwap}'s lockup plus an L1
269
+ * HTLC the trader funds and must take back itself. That refund leaf does not
270
+ * expire, so the failure to drive against is the manager finishing the swap
271
+ * while the output still holds the trader's money.
272
+ */
273
+ interface OnchainReceiveSwap extends RfqSwapCommon {
274
+ kind: "onchain_receive";
275
+ expectedAmount: number;
276
+ /** Its `refundLocktime` is the trader's own, NOT {@link RfqSwapCommon}'s. */
277
+ htlc: OnchainHtlc;
278
+ minConfirmations: number;
279
+ /** Required, unlike the send leg's optional `payoutPkScript`: without it
280
+ * the refund cannot be built at all. */
281
+ refundPkScript: Uint8Array;
282
+ funding?: {
283
+ txid: string;
284
+ vout: number;
285
+ };
286
+ claimTxid?: string;
287
+ }
386
288
 
387
289
  /**
388
- * The swap kinds this projection covers — all three the manager monitors.
389
- *
390
- * `onchain_send` carries an L1 half nothing else can rebuild. Its Arkade lockup
391
- * has a contract row like the others, but the HTLC is Bitcoin L1, not an Arkade
392
- * contract, so no row exists for it; and `OnchainHtlc` exposes only derived
393
- * values — `address`, `pkScript`, `leaves`, `controlBlocks` — never the
394
- * `claimKey`/`refundKey` `onchainHtlcScript` takes as inputs. So they ride in
395
- * that corridor's {@link RfqSwapOrigin.profile}, and without them a restored
396
- * swap would let its L1 refund window pass unwatched.
397
- *
398
- * @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
290
+ * The swap kinds this projection covers — all four the manager monitors. The onchain legs' L1 keys
291
+ * ride in their profiles, since no contract row or `OnchainHtlc` field can give them back.
399
292
  */
400
- type PersistableRfqSwap = LightningSendSwap | LightningReceiveSwap | OnchainSendSwap;
293
+ type PersistableRfqSwap = LightningSendSwap | LightningReceiveSwap | OnchainSendSwap | OnchainReceiveSwap;
401
294
  /** The immutable request-time half, and only what EVERY corridor has. Hex for
402
295
  * everything binary, so the record is plain JSON and survives any
403
- * structured-clone backend unchanged.
404
- *
405
- * @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
406
- */
296
+ * structured-clone backend unchanged. */
407
297
  interface RfqSwapOrigin {
408
298
  /**
409
299
  * Which corridor this is. Resolves the handler that owns {@link profile};
410
300
  * see `rfqCorridor.ts`.
411
301
  *
412
- * The manager's own union, not an open string: `RfqSwapManager` branches on
413
- * `kind` to decide what to drive, so a corridor it does not know could be
414
- * persisted and rebuilt here and then never driven — which is the failure
415
- * this whole file is arranged to make impossible.
302
+ * The manager's own union, not an open string: a kind it does not branch on would persist and
303
+ * rebuild here and then never be driven.
416
304
  */
417
305
  kind: PersistableRfqSwap["kind"];
418
306
  /**
419
- * The Arkade address that was funded.
420
- *
421
- * Both the swap's handle on its covenant — {@link lockupContractParams}
422
- * looks the contract row up by the script it decodes to — and, being taken
423
- * from the entry point rather than re-derived, the check that the
424
- * parameters a caller supplies belong to THIS swap.
307
+ * The Arkade address that was funded: the handle {@link lockupContractParams} looks the row up
308
+ * by, and, being taken from the entry point, the check that supplied params are THIS swap's.
425
309
  */
426
310
  lockupAddress: string;
427
311
  /**
428
312
  * The corridor's own half, as plain JSON — written by the caller from the
429
313
  * request result, kept current by the handler's `project`.
430
314
  *
431
- * Opaque here on purpose. Nothing in this file, the repository or the
432
- * IndexedDB store interprets it, which is what lets a new corridor ship
433
- * without touching any of them. It carries the corridor's keys as well as
434
- * its state: `signer` (which wallet key signs this leg) and, on a corridor
435
- * locked to a preimage, `hashlock` — see `rfqProfileParts.ts`, and write
436
- * both with `rfqSecretsProfile` rather than by hand.
437
- *
438
- * Not a consumer scratchpad: every write merges it as `{ ...profile,
439
- * ...handler.project(swap) }`, so a consumer key colliding with one the
440
- * handler projects is silently overwritten on every pass.
315
+ * Opaque here, so a new corridor ships without touching this file or the stores. Carries the
316
+ * corridor's keys (`signer`, and `hashlock` with the `sha256(P)` the covenant cannot give
317
+ * back); write them with `rfqSecretsProfile`. Not a consumer scratchpad: every write merges
318
+ * `handler.project(swap)` over it.
441
319
  */
442
320
  profile: Record<string, unknown>;
443
321
  /** Consumer display metadata. The rebuild ignores it — `RfqSwapCommon`
444
322
  * carries no amount of its own. */
445
323
  amount?: number;
446
324
  /**
447
- * The ark transaction that funded {@link lockupAddress}.
448
- *
449
- * Origin, not manager state: the caller broadcasts the funding and knows
450
- * its txid, while the manager watches the lockup by script and never
451
- * learns it. So it is written once at record creation, like {@link amount},
452
- * and no corridor `project` emits it.
325
+ * The ark transaction that funded {@link lockupAddress}. Origin, not manager state: only the
326
+ * caller that broadcast it knows it, so it is written once and no `project` emits it.
453
327
  */
454
328
  fundingTxid?: string;
455
329
  }
456
- /** The stored record: the origin plus the manager's mutable state.
457
- *
458
- * @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
459
- */
330
+ /** The stored record: the origin plus the manager's mutable state. */
460
331
  interface RfqSwapRecord extends RfqSwapOrigin {
461
332
  rfqId: string;
462
333
  state: RfqSwapState;
463
334
  createdAt: number;
464
335
  updatedAt: number;
465
336
  refundTxid?: string;
466
- /** The ark transactions that spent the lockup, stamped by the manager from
467
- * the chain read that ended the swap. See
468
- * `RfqSwapCommon.lockupSpendTxids`. */
337
+ /** See `RfqSwapCommon.lockupSpendTxids`. */
469
338
  lockupSpendTxids?: string[];
470
- /** The preimage that settled a Lightning send, stamped by the manager from
471
- * the same chain read. See `RfqSwapCommon.settlementPreimageHex`. */
339
+ /** See `RfqSwapCommon.settlementPreimageHex`. */
472
340
  settlementPreimageHex?: string;
473
341
  failure?: string;
474
342
  /** Last local receive-claim error while the swap is still retryable. */
@@ -476,6 +344,38 @@ interface RfqSwapRecord extends RfqSwapOrigin {
476
344
  blockedReason?: string;
477
345
  }
478
346
 
347
+ interface VerifiedCarrierTerms {
348
+ mode: "purchase" | "recycle_receiver";
349
+ physicalSats: bigint;
350
+ loanSats: bigint;
351
+ receiptSats: bigint;
352
+ serviceFareSats: bigint;
353
+ pricedSats: bigint;
354
+ expiresAt: number;
355
+ quoteId?: string;
356
+ taxiUrl?: string;
357
+ taxiKey?: string;
358
+ }
359
+ interface AssetPaymentTerms {
360
+ readonly receiveAddress: string;
361
+ readonly carrier?: VerifiedCarrierTerms;
362
+ readonly inputExpiryFloor?: InputExpiryFloor;
363
+ readonly validUntil: number;
364
+ }
365
+ type RecordedAssetPayment = Omit<AssetPaymentTerms, "carrier" | "inputExpiryFloor"> & {
366
+ readonly carrier?: Omit<VerifiedCarrierTerms, "physicalSats" | "loanSats" | "receiptSats" | "serviceFareSats" | "pricedSats"> & {
367
+ readonly physicalSats: string;
368
+ readonly loanSats: string;
369
+ readonly receiptSats: string;
370
+ readonly serviceFareSats: string;
371
+ readonly pricedSats: string;
372
+ };
373
+ readonly inputExpiryFloor?: {
374
+ readonly kind: "time" | "height";
375
+ readonly value: string;
376
+ };
377
+ };
378
+
479
379
  declare const ATOMIC_DECIMAL: unique symbol;
480
380
  /** Atomic units written out: the form records and the wire hold. */
481
381
  type AtomicDecimal = string & {
@@ -486,33 +386,18 @@ type AtomicDecimal = string & {
486
386
  * Asset identity for the v2 client: CAIP-19 with the rail as the CAIP-2
487
387
  * namespace — `<rail>:<network>/<asset-ns>:<reference>`.
488
388
  *
489
- * The rail is the namespace rather than the settlement chain because sameness
490
- * across rails is then a comparison on the asset part instead of a shared
491
- * string: `arkade:bitcoin/slip44:0` and `bitcoin:bitcoin/slip44:0` are one BTC
492
- * on two rails, and nothing has to agree on a single id for them. Arkade has no
493
- * CAIP-2 namespace and no bitcoin-chain identity to nest under, so
494
- * `bip122:…/arkade:…` would assert a relationship it does not have.
495
- *
496
- * These ids parse under CAIP-19 and resolve under no published namespace spec:
497
- * `arkade`, `bitcoin` and `bolt11` are registered in no CASA registry. That is
498
- * the price of naming rails instead of chains, and it costs nothing here — this
499
- * module is the grammar, and what an id *means* is the alias layer's job.
389
+ * Rail, not settlement chain, as namespace: cross-rail sameness becomes a comparison on the asset
390
+ * part (`arkade:bitcoin/slip44:0` vs `bitcoin:bitcoin/slip44:0`), and `bip122:…/arkade:…` would
391
+ * assert a relationship Arkade does not have. These ids parse under CAIP-19 but `arkade`,
392
+ * `bitcoin` and `bolt11` are in no CASA registry; meaning is the alias layer's job.
500
393
  */
501
394
 
502
395
  /**
503
- * A CAIP-2 namespace this client can spell. Closed rather than open to the
504
- * CAIP-2 character class, so a rail nobody implements is a parse failure here
505
- * rather than a lookup miss three layers down.
396
+ * A CAIP-2 namespace this client can spell. Closed, so an unimplemented rail fails at parse.
506
397
  *
507
- * `bolt11` is lightning: CAIP-2 caps a namespace at eight characters, which
508
- * `lightning` overruns, and floors it at three, which `ln` misses. It names the
509
- * instrument the rail carries today; BOLT12 is a separate corridor when it
510
- * ships.
511
- *
512
- * `eip155` is grammar and nothing else. §9's EVM corridor is deferred, and §9
513
- * exists to prove the seams hold, so its own examples have to parse; the
514
- * refusal belongs where a route is chosen, not where a string is read, and the
515
- * alias layer is where it happens.
398
+ * `bolt11` is lightning: CAIP-2 namespaces are 3-8 chars, which `lightning` and `ln` miss. BOLT12
399
+ * will be a separate corridor. `eip155` is grammar only: the EVM corridor is deferred, and refusal
400
+ * belongs where a route is chosen (the alias layer), not where a string is read.
516
401
  */
517
402
  declare const RAILS: readonly ["arkade", "bitcoin", "bolt11", "eip155"];
518
403
  type Rail = (typeof RAILS)[number];
@@ -520,77 +405,46 @@ type Rail = (typeof RAILS)[number];
520
405
  declare const BITCOIN_RAILS: readonly ["arkade", "bitcoin", "bolt11"];
521
406
  type BitcoinRail = (typeof BITCOIN_RAILS)[number];
522
407
  /**
523
- * The network half of a bitcoin-family chain part: core's own
524
- * {@link NetworkName}, because the wallet is the only source of the network —
525
- * v2 accepts no server URL anywhere — and this is the vocabulary a wallet
526
- * resolves to.
408
+ * The network half of a bitcoin-family chain part: core's own {@link NetworkName}, since the
409
+ * wallet is the only source of the network.
527
410
  *
528
- * It is one wider than discovery's `NETWORKS`, which omits `testnet`. That
529
- * difference belongs to the alias layer and not to the grammar: an asset on
530
- * testnet exists whether or not anyone publishes a market index for it, so
531
- * amputating the identity to match the index would make a network the SDK fully
532
- * supports unnameable.
411
+ * Wider than discovery's `NETWORKS` (which omits `testnet`): an asset on testnet exists whether or
412
+ * not a market index covers it.
533
413
  */
534
414
  type NetworkRef = NetworkName;
535
415
  type BitcoinAssetId<R extends BitcoinRail> = `${R}:${NetworkRef}/${string}:${string}`;
536
416
  /**
537
417
  * A public asset id.
538
418
  *
539
- * A template literal type and not `string`, which is what makes the other three
540
- * asset spellings in this package — core's 68-hex `asset.AssetId#toString()`,
541
- * discovery's `AssetInfo.id`, the RFQ leg's `arkade:BTC` — a compile error in a
542
- * slot that wants a public id, rather than a wrong pair string three layers
543
- * down. The rail parameter carries that further: `AssetId<"arkade">` accepts no
544
- * `bitcoin:` string, which is what makes an endpoint whose corridor and asset
545
- * disagree a compile error (see `route.ts`).
419
+ * A template literal type, so the package's other asset spellings (core's 68-hex id, discovery's
420
+ * `AssetInfo.id`, the RFQ leg's `arkade:BTC`) are compile errors here, and `AssetId<"arkade">`
421
+ * accepts no `bitcoin:` string (see `route.ts`).
546
422
  *
547
- * Deliberately not branded — `client.quote({ give: "arkade:bitcoin/slip44:0" })`
548
- * must stay writable, and the spec's own examples are written that way — so the
549
- * shape is what the type checks and {@link parseAssetId} is the gate for
550
- * everything else. A value out of a record or off the wire is a `string`: parse
551
- * it, never cast it.
423
+ * Deliberately not branded, so `client.quote({ give: "arkade:bitcoin/slip44:0" })` stays writable.
424
+ * A value from a record or the wire is a `string`: parse it with {@link parseAssetId}, never cast.
552
425
  */
553
426
  type AssetId<R extends Rail = Rail> = R extends BitcoinRail ? BitcoinAssetId<R> : `eip155:${number}/${string}:${string}`;
554
427
 
555
428
  /**
556
429
  * The corridor axis, and its bijection with the rail namespaces.
557
430
  *
558
- * One axis, two vocabularies: client routes speak `arkade | lightning |
559
- * onchain` and an asset id's CAIP-2 namespace is `arkade | bolt11 | bitcoin`.
560
- * They agree on one member of three. Collapsing them was the alternative and
561
- * it loses either way — take the rail names and the public route vocabulary
562
- * becomes protocol-shaped; take the route names and `lightning:` overruns
563
- * CAIP-2's eight-character namespace cap.
564
- *
565
- * So both stay, and the disagreement is spent once, here:
566
- * {@link railOfCorridor} is total, and `route.ts` ties an endpoint's corridor
567
- * to its asset's rail in the type system so the two cannot disagree in a value.
431
+ * Routes speak `arkade | lightning | onchain`; CAIP-2 asset namespaces are `arkade | bolt11 |
432
+ * bitcoin`. Both stay: rail names would make the public route vocabulary protocol-shaped, and
433
+ * `lightning:` overruns CAIP-2's eight-character namespace cap. {@link railOfCorridor} is total, and
434
+ * `route.ts` ties an endpoint's corridor to its asset's rail in the type system.
568
435
  */
569
436
 
570
- /**
571
- * The corridor a leg settles on.
572
- *
573
- * This is deliberately independent from discovery's CAIP chain-namespace
574
- * vocabulary. Discovery changed its public corridor names to `bolt11` and
575
- * `bitcoin`; those are rail identifiers here, not caller-facing route names.
576
- */
437
+ /** The corridor a leg settles on — caller-facing route names, independent of discovery's CAIP rail
438
+ * identifiers. */
577
439
  declare const CORRIDORS: readonly ["arkade", "lightning", "onchain"];
578
440
  type Corridor = (typeof CORRIDORS)[number];
579
- /**
580
- * A corridor id: the three implemented corridors plus §9's EVM chains.
581
- *
582
- * The template arm stays open against the registry's closed enum on purpose —
583
- * which chains a registry lists is a listing decision, not an id-grammar one.
584
- */
441
+ /** A corridor id: the three implemented corridors plus EVM chains. The template arm stays open on
442
+ * purpose — which chains a registry lists is a listing decision, not an id-grammar one. */
585
443
  type CorridorId = Corridor | `eip155:${number}`;
586
444
 
587
445
  /**
588
- * The two string aliases the v2 surface is written in.
589
- *
590
- * Aliases rather than branded types: they document what a field carries at the
591
- * places §3.1's `Quote` reads (`lock.hash`, `solver`) without making every
592
- * literal go through a constructor. Core exports neither, so nothing here is a
593
- * duplicate.
446
+ * The two string aliases the v2 surface is written in. Aliases rather than branded types, so
447
+ * literals need no constructor.
594
448
  */
595
449
  /** Lowercase hex, no `0x` prefix — the encoding `@scure/base`'s `hex` emits. */
596
450
  type Hex = string;
@@ -598,30 +452,8 @@ type Hex = string;
598
452
  type Pubkey = Hex;
599
453
 
600
454
  /**
601
- * What a quote is: the order, fully resolved, plus the provenance that says who
602
- * priced it and where that card came from.
603
- *
604
- * M1 named these shapes and left them to whichever milestone decided their
605
- * semantics; this is that milestone, so `QuoteId`, `QuoteInput`, `Quote`,
606
- * `MarketRef` and `AuctionProvenance` are declared here rather than beside the
607
- * types they are built out of. Nothing in this module has behaviour — the quote
608
- * path assembles these, `accept()` (M4) consumes them.
609
- *
610
- * The one rule worth restating at the top: a `Quote` is binding terms plus the
611
- * evidence for them. Every field is either something the caller must act on
612
- * (the two obligations, the artifact, the deadline) or something they must be
613
- * able to audit afterwards (the market, the solver, the checks that passed).
614
- * Nothing internal rides along — no covenant, no secret, no transport.
615
- */
616
-
617
- /**
618
- * A quote's identity, minted by the client at quote time.
619
- *
620
- * Client-minted everywhere, not just where the wire offers no id: a feed-priced
621
- * offer quote has no solver-minted id at all, and `accept()` is idempotent by
622
- * quote id *and only* by quote id (§3.2), so an identity that exists on one
623
- * backend and not the other could not carry that rule. An alias rather than a
624
- * brand, matching `Hex` and `Pubkey` beside it.
455
+ * A quote's identity, minted by the client at quote time on every backend: feed-priced quotes
456
+ * have no solver id, and `accept()` is idempotent by quote id *only* (§3.2).
625
457
  */
626
458
  type QuoteId = string;
627
459
  /** Which backend priced a quote. The card decides it; no client switch does. */
@@ -631,40 +463,33 @@ interface SnapshotRef {
631
463
  /** Unix ms the markets were read from their sources. */
632
464
  readonly fetchedAt: number;
633
465
  /**
634
- * The registry answered in this read, so the cards are registry-served
635
- * rather than replayed out of local storage.
466
+ * The cards came from this read or from config, never replayed from local storage, so they
467
+ * may supply the key an addressed RFQ's responder is checked against.
636
468
  *
637
- * `false` is not an error: a stale snapshot still resolves and still prices
638
- * a feed-priced quote — it is marked, not refused. What it cannot do is
639
- * supply the key an addressed RFQ's responder is checked against, because
640
- * that field is unvalidated cache content (`isMarketShaped` revalidates
641
- * four fields and trusts the rest).
469
+ * `false` is marked, not refused: a stale snapshot still prices a feed-priced quote. It cannot
470
+ * pin a responder, because cached cards are only partly revalidated (`isMarketShaped`).
642
471
  */
643
472
  readonly live: boolean;
644
- /** How the markets were obtained. */
645
- readonly source: "live" | "cache" | "injected";
646
- /** The registry URL behind it, or `undefined` for an injected snapshot. */
473
+ /**
474
+ * How the markets were obtained: `live` from the registry, `cache` from local storage,
475
+ * `injected` from `DiscoveryConfig.snapshot`, `local` from pinned cards alone while the
476
+ * registry was unreachable and nothing was cached.
477
+ */
478
+ readonly source: "live" | "cache" | "injected" | "local";
479
+ /** The registry URL behind it; `undefined` for an injected or local snapshot. */
647
480
  readonly registry?: string;
648
481
  }
649
482
  /**
650
- * Which card priced a quote, and from which registry.
651
- *
652
- * A union rather than a bag of optionals, because §10's published RFQ is the
653
- * one place the sentence "the market picks the backend" stops: a quote closed
654
- * out of an open auction has a market *key* and no card behind it, so every
655
- * card-derived field is absent at once rather than one at a time. Sizing that
656
- * arm now costs a discriminant and keeps the addressed arm total.
483
+ * Which card priced a quote, and from which registry. A union because an auction-closed quote
484
+ * (§10) has a market key and no card, and a restored record has neither.
657
485
  */
658
- type MarketRef = CardMarketRef | AuctionMarketRef;
486
+ type MarketRef = CardMarketRef | AuctionMarketRef | RestoredMarketRef;
659
487
  interface CardMarketRef {
660
488
  readonly kind: "card";
661
489
  /**
662
- * The canonical market key, `<corridor>:<id>/<corridor>:<id>`, derived under
663
- * rfq-protocol.md §2's leg order — arkade first when exactly one leg is
664
- * arkade, lexicographic otherwise — and never read off the card's own
665
- * base/quote order. The two agree for every card the registry's reducer
666
- * validated, and a card published outside it is exactly where the silent
667
- * miss lives.
490
+ * The canonical market key, `<corridor>:<id>/<corridor>:<id>`, under rfq-protocol.md §2's leg
491
+ * order — arkade first when exactly one leg is arkade, lexicographic otherwise — never the
492
+ * card's own base/quote order (see `marketKeyOf`).
668
493
  */
669
494
  readonly key: string;
670
495
  readonly backend: MarketBackend;
@@ -685,44 +510,14 @@ interface AuctionMarketRef {
685
510
  readonly key: string;
686
511
  readonly backend: "rfq";
687
512
  }
513
+ /** A record rebuilt after a restore (from the funding tx, or a v1 corridor row): no card stands
514
+ * behind it. */
515
+ interface RestoredMarketRef {
516
+ readonly kind: "restored";
517
+ readonly backend: "feed" | "rfq";
518
+ }
688
519
 
689
- /**
690
- * What survives a crash, and the public shape `accept()` hands back.
691
- *
692
- * Two types, one key. {@link SwapRecord} is the storage form — JSON-safe by
693
- * declaration, every amount a canonical decimal string — and {@link Swap} is the
694
- * answer a caller reads, with `bigint` amounts and the resolved `Route`. The
695
- * conversion between them is §D's record-boundary codec, and it is not a third
696
- * law: `toAtomicDecimal`/`fromAtomicDecimal` already ship in `./amount`, minted
697
- * by M1 and used by M3's wire adapter, so both sites emit the same canonical
698
- * form — atomic units, unsigned, no leading zeros, never a scaled display
699
- * decimal.
700
- *
701
- * **The key is the quote id, on every route.** That is what makes persist-first
702
- * representable at all: v1's `AssetSwap.id` *is* the funding txid
703
- * (`store.ts:70-71`), so a record could not exist before the money did, and
704
- * `coverage.ts` carries a process-local issuance mark precisely to paper over
705
- * the gap. Here the record precedes the funding and `fundingTxid` is a later,
706
- * best-effort write.
707
- *
708
- * **JSON-safe means no `bigint` anywhere, at any depth.** The SQLite and Realm
709
- * backends `JSON.stringify` the record whole, so a `bigint` throws on two
710
- * backends and round-trips on the third — the asymmetry
711
- * `test/repository.test.ts` refuses to paper over. Every amount here is an
712
- * {@link AtomicDecimal}; `test/client/record.types.ts` proves the absence
713
- * structurally rather than by review.
714
- */
715
-
716
- /**
717
- * Which family a record belongs to, and the discriminant M5's `RawState` keys
718
- * on.
719
- *
720
- * Not a cosmetic tag. v1's two families occupied one `string` id space by
721
- * accident — an offer record's id a funding txid, a corridor record's an
722
- * `rfqId` — and keying both on `QuoteId` closes that collision (§B). The tag is
723
- * what M6's public id carries, and what lets M5 branch its outcome table
724
- * without a repository read.
725
- */
520
+ /** Which family a record belongs to — what the drive's outcome table branches on without a read. */
726
521
  type SwapFamily = "offer" | "rfq";
727
522
  /** One leg's obligation, in the form a record holds it. */
728
523
  interface RecordedLeg {
@@ -730,14 +525,8 @@ interface RecordedLeg {
730
525
  /** Atomic units as a canonical decimal string — never a `bigint`. */
731
526
  readonly amount: AtomicDecimal;
732
527
  }
733
- /**
734
- * An endpoint as the record holds it: the corridor, the asset, the instrument.
735
- *
736
- * `Instrument`'s invoice arm carries a `bigint` amount, so it cannot be stored
737
- * as declared — {@link RecordedInstrument} is the same union with that one field
738
- * in decimal form. The rest is field for field identical, which is what keeps the
739
- * comparison in `acceptConflict` honest.
740
- */
528
+ /** An endpoint as the record holds it; field for field `Instrument`'s shape, so `acceptConflict`
529
+ * compares like with like. */
741
530
  interface RecordedEndpoint {
742
531
  readonly corridor: CorridorId;
743
532
  readonly asset: AssetId;
@@ -768,26 +557,14 @@ type RecordedArtifact = {
768
557
  readonly amount: AtomicDecimal;
769
558
  readonly expiresAt?: number;
770
559
  };
771
- /**
772
- * The half both families carry.
773
- *
774
- * Every field is either something `AcceptConflict` compares (§3.2's list), or
775
- * something M5 named as a cross-milestone ask, or the two timestamps. Nothing
776
- * is here for display: a record carries what no covenant and no chain read can
777
- * give back, which is the same rule `RfqSwapRecord` is arranged by.
778
- */
560
+ /** The half both families carry: what `AcceptConflict` compares and no chain read can give back. */
779
561
  interface SwapRecordCommon {
780
- /** The client-minted quote id — the primary key, per C1 and §B. */
562
+ readonly assetPayment?: RecordedAssetPayment;
563
+ /** The client-minted quote id — the primary key. */
781
564
  readonly id: QuoteId;
782
565
  readonly family: SwapFamily;
783
- /**
784
- * Both endpoints, instruments included — `AcceptConflict` items 1 and 3.
785
- *
786
- * Nested under `route` so the record's field names are `Quote`'s field
787
- * names: the conflict check walks the two shapes together, and a record
788
- * that spelled the same fact differently would make every comparison a
789
- * translation.
790
- */
566
+ /** Both endpoints, instruments included. Nested under `route` so field names match `Quote`'s and
567
+ * the conflict check walks both shapes without translation. */
791
568
  readonly route: {
792
569
  readonly give: RecordedEndpoint;
793
570
  readonly take: RecordedEndpoint;
@@ -797,53 +574,27 @@ interface SwapRecordCommon {
797
574
  readonly take: RecordedLeg;
798
575
  /** The spread, as the quote precomputed it. */
799
576
  readonly fee: RecordedLeg;
800
- /**
801
- * Which card priced this, from which registry, how fresh — stored WHOLE.
802
- *
803
- * A trimmed projection could not rebuild the type {@link Swap.market}
804
- * promises: `CardMarketRef` requires `kind`, `pair` and `snapshot` beside
805
- * the fields a summary would keep. Every member is a string, number or
806
- * boolean, so the union round-trips through JSON untouched, and `snapshot`
807
- * is restated as read at accept rather than restamped — a past `fetchedAt`
808
- * beside the recorded `live` is the honest answer about how fresh the card
809
- * was when this swap was accepted.
810
- */
577
+ /** Which card priced this, from which registry, how fresh — stored WHOLE (a projection could not
578
+ * rebuild `CardMarketRef`); `snapshot` is as read at accept, not restamped. */
811
579
  readonly market: MarketRef;
812
- /**
813
- * The committed counterparty, from the quote's covenant role.
814
- *
815
- * NOT `CardMarketRef.solver`, which is the card's display name. Two
816
- * different facts that v1 spelled with one word: this one is a key that
817
- * ends up in a covenant leaf, the other is a label. `AcceptConflict`
818
- * compares this one.
819
- */
580
+ /** The committed counterparty key from the quote's covenant role — NOT `CardMarketRef.solver`,
581
+ * which is a display name. `AcceptConflict` compares this one. */
820
582
  readonly solver?: Pubkey;
821
583
  /** The quote's own deadline, unix seconds — what makes a stalled accept a
822
584
  * benign abandon rather than a live obligation. */
823
585
  readonly expiresAt: number;
824
- /**
825
- * The one thing a counterparty must see, when this route has one.
826
- *
827
- * Durable because a duplicate accept must return the SAME invoice, and the
828
- * invoice lives on the quote object — nowhere in the corridor profile. A
829
- * caller that re-accepts after a restart has no quote object left, so
830
- * without this field the only honest answer would be a second invoice,
831
- * which §3.2 forbids by name.
832
- */
586
+ /** The one thing a counterparty must see, when the route has one. Durable because a duplicate
587
+ * accept after a restart must return the SAME invoice, and the quote object is gone by then. */
833
588
  readonly artifact?: RecordedArtifact;
834
- /**
835
- * The transaction that funded this swap, once known.
836
- *
837
- * A later, best-effort write, and the field that separates M5's `accepted`
838
- * from `funding`. Set-where-absent is a benign resume and never an
839
- * `AcceptConflict` — §3.2 says so by name.
840
- */
589
+ /** The funding transaction, once known. A later best-effort write; set-where-absent is a benign
590
+ * resume, never an `AcceptConflict`. */
841
591
  readonly fundingTxid?: string;
842
- /**
843
- * Last local receive-claim error while the swap is still retryable. If the
844
- * claim window later closes without a submitted claim, this becomes the
845
- * terminal failure reason after restore.
846
- */
592
+ /** SDK proof that this wallet never submitted the funding transaction. */
593
+ readonly fundingNotSubmitted?: {
594
+ readonly reason: "send_deadline";
595
+ readonly validUntil: number;
596
+ };
597
+ /** Last retryable receive-claim error; becomes the terminal failure if the claim window closes. */
847
598
  readonly claimFailure?: string;
848
599
  /** Terminal failure reason. */
849
600
  readonly failure?: string;
@@ -854,53 +605,42 @@ interface SwapRecordCommon {
854
605
  readonly createdAt: number;
855
606
  readonly updatedAt: number;
856
607
  }
857
- /**
858
- * `arkade <-> arkade`: the offer covenant, and what cancels it.
859
- *
860
- * `offerHex` is the whole covenant — `cancelOffer` needs nothing else to
861
- * rebuild it — so this arm stores no tree parameters of its own.
862
- */
608
+ /** `arkade <-> arkade`: the offer covenant. `offerHex` is the whole covenant, so no tree params. */
863
609
  interface OfferSwapRecord extends SwapRecordCommon {
864
610
  readonly family: "offer";
865
- /** v1's raw status vocabulary, which M5's `RawState` reads verbatim. */
611
+ /** v1's raw status vocabulary, read verbatim by the drive's `RawState`. */
866
612
  readonly status: AssetSwapStatus;
867
613
  /** The TLV offer, hex. The only input `cancelOffer` needs. */
868
614
  readonly offerHex: string;
869
615
  readonly swapAddress: string;
870
- /** The covenant's scriptPubKey, hex — the indexer's monitoring key, and
871
- * what §F's reconcile matches a discovered deposit against. */
616
+ /** The covenant's scriptPubKey, hex — the indexer's monitoring key and the reconcile's match key. */
872
617
  readonly swapPkScript: string;
618
+ /** Sats riding an asset deposit, decimal: the solver's published carrier, which the fill is
619
+ * priced against. Absent for a BTC deposit and for feed-priced swaps (the SDK default). */
620
+ readonly carrierSats?: string;
873
621
  readonly spentTxid?: string;
874
622
  readonly completedAt?: number;
875
623
  }
876
624
  /**
877
625
  * The three corridor routes: a VHTLC lockup, its clocks and its secrets.
878
626
  *
879
- * **No covenant tree here.** Every lockup registers a contract row before its
880
- * address can be funded, and that row already holds the parameters, keyed by
881
- * the script they derive — a key `createContract` refuses to write unless the
882
- * params reproduce it. Storing the tree a second time would be two sources for
883
- * one covenant. `accept()` is what writes that row (see `./accept.ts`), which
884
- * is why a persisted record always has one.
627
+ * **No covenant tree here.** `accept()` registers a contract row before the lockup can be funded,
628
+ * keyed by the script its params derive (`createContract` refuses params that don't reproduce it);
629
+ * storing the tree again would be two sources for one covenant.
885
630
  */
886
631
  interface CorridorSwapRecord extends SwapRecordCommon {
887
632
  readonly family: "rfq";
888
- /** v1's raw state vocabulary, read verbatim by M5's `RawState`. */
633
+ /** v1's raw state vocabulary, read verbatim by the drive's `RawState`. */
889
634
  readonly state: RfqSwapState;
890
- /**
891
- * Which corridor, in the manager's own vocabulary.
892
- *
893
- * `PersistableRfqSwap["kind"]` rather than a `Corridor`: it is a route pair
894
- * — `lightning_send` and `lightning_receive` are one corridor from opposite
895
- * ends — and it is what resolves the handler that owns {@link profile}.
896
- */
635
+ /** The route pair in the manager's vocabulary (`lightning_send`/`lightning_receive` are one
636
+ * corridor from opposite ends); resolves the handler that owns {@link profile}. */
897
637
  readonly kind: PersistableRfqSwap["kind"];
898
638
  /** The solver's own id for the negotiation, echoed back on the wire. */
899
639
  readonly rfqId: string;
900
640
  /** The Arkade address that was funded, and the swap's handle on its
901
641
  * covenant row. */
902
642
  readonly lockupAddress: string;
903
- /** Its pkScript, hex — the row's key, and §F's matching key. */
643
+ /** Its pkScript, hex — the row's key and the reconcile's match key. */
904
644
  readonly lockupPkScript: string;
905
645
  /** The hash both covenants commit to. `sha256(P)`, hex. */
906
646
  readonly lock: {
@@ -909,174 +649,116 @@ interface CorridorSwapRecord extends SwapRecordCommon {
909
649
  /** When the trader's value comes back if the swap does not complete. */
910
650
  readonly refundLocktime: number;
911
651
  /**
912
- * The corridor's own half, as plain JSON.
913
- *
914
- * v1's opaque bag (`rfqRecord.ts:108-123`), written with `rfqSecretsProfile`
915
- * and read by `rfqCorridorHandlers.hydrate` — reused rather than
916
- * reinvented, so M5 rebuilds through machinery that already exists and a new
917
- * corridor still ships without touching this file. It is also what carries
918
- * `expectedAmount`, the claim value gate's request-time input.
652
+ * The corridor's own half, as plain JSON (written by `rfqSecretsProfile`, read by
653
+ * `rfqCorridorHandlers.hydrate`), so a new corridor ships without touching this file. Its
654
+ * `expectedAmount` is a `number`; the decimal-string rule covers only this record's own fields.
919
655
  *
920
- * Amounts inside it follow v1's shapes (`expectedAmount` is a `number`),
921
- * which is JSON-safe and therefore fine: the decimal-string law governs
922
- * this record's OWN amount fields, not the bag it carries forward.
923
- *
924
- * **This is also where the swap's secrets live** — `profile.signer` and,
925
- * on a leg locked to a preimage, `profile.hashlock`. Deliberately not a
926
- * second copy at the record's top level: `rfqClaimSecretOf` and
927
- * `preimageForSwapRecord` already read them from here, and two homes for
928
- * one claim secret is two things to keep in step with one of them always
929
- * empty. At most one of `preimageHex`/`preimageSaltHex` is ever written,
930
- * and which arm exists is decided by the wallet's provisioning result, not
931
- * here.
656
+ * **The swap's secrets live here** (`profile.signer`, and `profile.hashlock` on a preimage-locked
657
+ * leg), deliberately not duplicated at top level.
932
658
  */
933
659
  readonly profile: Record<string, unknown>;
934
660
  readonly refundTxid?: string;
935
661
  readonly lockupSpendTxids?: readonly string[];
936
662
  /**
937
- * `P`, hex — the preimage the solver revealed to settle a Lightning send.
938
- *
939
- * The exception the doctrine above allows for, and only on that leg: the
940
- * payee mints `P`, so {@link profile}'s hashlock carries the payment hash
941
- * and no claim-secret material. This is the counterparty's revealed
942
- * settlement proof, not a second copy of the wallet's own claim secret —
943
- * and public by the time it is written, being read out of the witness that
944
- * spent the lockup.
663
+ * `P`, hex — the preimage the solver revealed to settle a Lightning send. Not a copy of our claim
664
+ * secret (the payee mints `P` on that leg), and already public: read from the spending witness.
945
665
  */
946
666
  readonly settlementPreimageHex?: string;
947
667
  }
948
668
  /** Everything `accept()` persists, both families in one key space. */
949
669
  type SwapRecord = OfferSwapRecord | CorridorSwapRecord;
950
670
 
951
- /** A registry discovery result held for reuse. Refetchable — unlike a swap
952
- * record, losing it costs one network round trip — but it must survive a cold
953
- * boot: serving it stale is what keeps quoting alive while a registry is down. */
671
+ /** A cached registry discovery result. Refetchable, but must survive a cold boot:
672
+ * serving it stale keeps quoting alive while a registry is down. */
954
673
  interface MarketsCacheEntry {
955
674
  markets: DiscoveredMarket[];
956
675
  fetchedAt: number;
957
676
  }
677
+ interface RfqSwapPageFilter {
678
+ state?: RfqSwapState;
679
+ /** Inclusive Unix seconds. */
680
+ since?: number;
681
+ }
682
+ interface RfqSwapPageCursor {
683
+ updatedAt: number;
684
+ rfqId: string;
685
+ }
958
686
  /**
959
- * Everything the package persists, following the monorepo repository
960
- * convention: versioned interface, AsyncDisposable, one backend per platform.
961
- * Consumers construct exactly one of these; there is no second storage seam.
687
+ * Everything the package persists: versioned interface, AsyncDisposable, one backend
688
+ * per platform. Durable records and rebuildable state (scan cursor, markets cache) share
689
+ * one store because they share a lifetime: one wallet on one device.
962
690
  *
963
- * Durable records (swaps) and rebuildable state (the restore scan's txid
964
- * cursor, the markets cache) live side by side because they share a
965
- * lifetime: all three belong to one wallet on one device, and a consumer
966
- * that wipes one wants all three gone.
967
- *
968
- * ponytail: no query filters — every consumer reads all swaps and filters
969
- * in memory; add a filter type when a consumer needs subset queries.
691
+ * Collection reads are paged. RFQ reads may filter by state and date.
970
692
  */
971
693
  interface AssetSwapRepository extends AsyncDisposable {
972
- /** 5 adds the v2 swap-record store — one row per accepted swap, keyed by
973
- * the client-minted quote id. 4 added `getRfqSwap`; 3 added the other RFQ
974
- * methods below; 2 was the released shape — swaps, scan cursor, markets,
975
- * with `preimageSaltHex` on the swap record — so an implementor built
976
- * against any of them cannot satisfy this one silently. */
694
+ /** Bumped on every shape change (5: v2 swap-record store) so an implementor built
695
+ * against an older shape cannot satisfy this one silently. */
977
696
  readonly version: 5;
978
- /** Insert or replace a swap by id. Store the record whole: `preimageHex`
979
- * and `preimageSaltHex` both leave the swap unclaimable if a field-mapped
980
- * backend drops them — the first is the only claim secret of a swap whose
981
- * signer cannot derive, the second the public input every other static
982
- * wallet's preimage derives from.
697
+ /** Insert or replace a swap by id. Store the record whole: a field-mapped backend
698
+ * dropping `preimageHex` or `preimageSaltHex` leaves the swap unclaimable.
983
699
  *
984
- * Records must be **JSON-safe**: the SQLite and Realm backends serialize
985
- * the record to JSON, so a `Date` in a consumer-added field comes back a
986
- * string, a `Set`/`Map` comes back empty, and a `bigint` throws here —
987
- * none of which happens on IndexedDB's structured clone. `AssetSwap` as
988
- * declared is JSON-safe; keep added fields that way. */
700
+ * Records must be **JSON-safe**: SQLite and Realm serialize to JSON, so a `Date`
701
+ * comes back a string, a `Set`/`Map` empty, and a `bigint` throws — unlike
702
+ * IndexedDB's structured clone. Keep consumer-added fields JSON-safe. */
989
703
  saveSwap(swap: AssetSwap): Promise<void>;
990
- /** All stored swaps, in no particular order — `getAssetSwaps` is the
991
- * canonical newest-first read. */
992
- getAllSwaps(): Promise<AssetSwap[]>;
704
+ getAssetSwapsPage(page: PageRequest): Promise<PageResult<AssetSwap>>;
993
705
  /**
994
706
  * Insert or replace a monitored RFQ swap by `rfqId`.
995
707
  *
996
- * Store the record WHOLE. Every field is a covenant tree parameter or the
997
- * manager's own state, and a field-mapped backend that drops one round-trips
998
- * a record whose covenant `rebuildRfqSwap` cannot reproduce — which surfaces
999
- * as a refund that cannot be signed, long after the write.
708
+ * Store the record WHOLE: every field is a covenant parameter or manager state, and a
709
+ * dropped one surfaces much later as a refund that cannot be signed.
1000
710
  */
1001
711
  saveRfqSwap(record: RfqSwapRecord): Promise<void>;
1002
- /** One record by key. `undefined` on a miss — retention prunes terminal
1003
- * records, so absence is ordinary and not an error. */
712
+ /** One record by key. */
1004
713
  getRfqSwap(rfqId: string): Promise<RfqSwapRecord | undefined>;
1005
- /** Every stored RFQ swap record, in no particular order. */
1006
- getAllRfqSwaps(): Promise<RfqSwapRecord[]>;
1007
- /** Drop one, once it is past retention — see `shouldRetainRfqSwap`. */
714
+ getRfqSwapsPage(filter: RfqSwapPageFilter, page: PageRequest<RfqSwapPageCursor>): Promise<PageResult<RfqSwapRecord, RfqSwapPageCursor>>;
715
+ /** Drop one record. Only explicit pruning calls this; restore keeps history. */
1008
716
  removeRfqSwap(rfqId: string): Promise<void>;
1009
717
  /**
1010
- * Insert or replace a v2 swap record by its quote id.
718
+ * Insert or replace a v2 swap record (what `accept()` writes) by its quote id.
1011
719
  *
1012
- * The store the v2 client's `accept()` writes, and the reason this
1013
- * interface is at 5. Separate from `swaps` rather than sharing it: the v1
1014
- * read path drops any row carrying neither `offerHex` nor `paymentHash`
1015
- * (`getAssetSwapsOrThrow`), silently and as corrupt, so a v2 record in that
1016
- * store would be pinned by a v1 predicate — and the two histories are meant
1017
- * to be disjoint for the deprecation window anyway. A v1 reader not seeing
1018
- * v2 rows is the design, asserted in the conformance suite rather than
1019
- * tolerated.
720
+ * Separate from `swaps`: the v1 read path silently drops rows with neither `offerHex`
721
+ * nor `paymentHash` as corrupt. v1 readers not seeing v2 rows is by design.
1020
722
  *
1021
- * Store the record WHOLE, and note that it is **JSON-safe by declaration**:
1022
- * every amount on it is a canonical decimal string, precisely so the SQLite
1023
- * and Realm backends' `JSON.stringify` and IndexedDB's structured clone
1024
- * agree. A `bigint` reaching here would throw on two backends and
1025
- * round-trip on the third.
723
+ * Store the record WHOLE. Amounts are canonical decimal strings so every backend
724
+ * agrees; a `bigint` would throw on SQLite/Realm and round-trip on IndexedDB.
1026
725
  */
1027
726
  saveSwapRecord(record: SwapRecord): Promise<void>;
1028
- /** One record by quote id. `undefined` on a miss — which is the ordinary
1029
- * answer for a first `accept()`, and what makes it idempotent. */
727
+ /** `undefined` on a miss — the ordinary answer for a first `accept()`, and what
728
+ * makes it idempotent. */
1030
729
  getSwapRecord(id: string): Promise<SwapRecord | undefined>;
1031
- /** Every stored v2 record, in no particular order. */
1032
- getAllSwapRecords(): Promise<SwapRecord[]>;
730
+ getSwapRecordsPage(page: PageRequest): Promise<PageResult<SwapRecord>>;
1033
731
  /** Drop one, once it is past retention. */
1034
732
  removeSwapRecord(id: string): Promise<void>;
1035
733
  /**
1036
- * Sent txids already checked for offer packets (see restore.ts).
1037
- *
1038
- * **Shared across both record families, deliberately.** This is not
1039
- * record-family data — it marks txids of transactions a scan has answered,
1040
- * whatever family a later record belongs to — and both families walk the
1041
- * same sent-txid set during the deprecation window. Two cursors would have
1042
- * each side re-walking deposits the other already answered.
734
+ * Sent txids already checked for offer packets (see restore.ts). Deliberately shared
735
+ * by both record families: they walk the same sent-txid set, and two cursors would
736
+ * each re-walk what the other already answered.
1043
737
  */
1044
738
  getScannedTxids(): Promise<Set<string>>;
1045
739
  markTxidsScanned(txids: Iterable<string>): Promise<void>;
1046
- /** Cached registry markets, or undefined on a miss. Shared across both
1047
- * record families for the reason the cursor is: the key is network-and-
1048
- * registry, not a store, and two caches would serve two staleness clocks
1049
- * for one registry. */
740
+ /** Cached registry markets, or undefined on a miss. Shared by both record families,
741
+ * like the cursor, so one registry has one staleness clock. */
1050
742
  getCachedMarkets(network: string, registry: string): Promise<MarketsCacheEntry | undefined>;
1051
743
  saveCachedMarkets(network: string, registry: string, entry: MarketsCacheEntry): Promise<void>;
1052
744
  clear(): Promise<void>;
1053
745
  }
1054
746
 
1055
747
  /**
1056
- * An executor that owns its connection.
1057
- *
1058
- * `SQLExecutor` declares no lifecycle — the interface is three query methods,
1059
- * because every other implementation wraps a connection the consumer already
1060
- * opened. This one opens the file itself, so it is the one that has something
1061
- * to close.
748
+ * An executor that owns its connection. `SQLExecutor` declares no lifecycle because other
749
+ * implementations wrap a consumer-opened connection; this one opens the file itself.
1062
750
  */
1063
751
  interface NodeSqlExecutor extends SQLExecutor {
1064
752
  /** Close the underlying database handle. Idempotent. */
1065
753
  close(): Promise<void>;
1066
754
  }
1067
755
  /**
1068
- * Open (creating if absent) a SQLite database at `path`.
756
+ * Open (creating the file and its parent directory if absent) a SQLite database at `path`.
1069
757
  *
1070
- * **One instance per file, held for the process's life.** `runInTransaction`
1071
- * keys its write chain on the executor *object* through a `WeakMap`, so a
1072
- * second executor over the same file forks the chain and two "transactions" can
1073
- * interleave on one connection. Every repository on a database must be handed
1074
- * the same instance — which is what {@link nodeSwapRepository} does for the
758
+ * **One instance per file, held for the process's life.** `runInTransaction` keys its write chain
759
+ * on the executor *object* via a `WeakMap`, so a second executor over the same file forks the
760
+ * chain and two "transactions" can interleave. {@link nodeSwapRepository} handles this for the
1075
761
  * common case.
1076
- *
1077
- * The parent directory is created on open: the config dir exists on any real
1078
- * machine but `arkade/swaps` under it does not, and failing on a first run for
1079
- * a directory the caller never chose would be a poor default.
1080
762
  */
1081
763
  declare const createNodeSqlExecutor: (path: string) => NodeSqlExecutor;
1082
764
  interface NodeSwapRepositoryOptions {
@@ -1091,22 +773,12 @@ interface NodeSwapRepositoryOptions {
1091
773
  readonly prefix?: string;
1092
774
  }
1093
775
  /**
1094
- * The Node storage default, connection included.
1095
- *
1096
- * This is where D1/D2's ownership rule lands: the returned repository's
1097
- * `[Symbol.asyncDispose]` closes the connection **it** opened, and an injected
1098
- * repository is disposed by whoever built it — which is already true of every
1099
- * other backend, whose disposal is a no-op precisely because the consumer owns
1100
- * the handle.
1101
- *
1102
- * Hanging ownership on the repository rather than on a client lifecycle method
1103
- * is deliberate: the v2 client has no `stop()` or `dispose()` yet — the
1104
- * lifecycle is the next milestone's — and a connection that could only be
1105
- * closed through a method that does not exist would leak until the process
1106
- * ended.
776
+ * The Node storage default, connection included. Its `[Symbol.asyncDispose]` closes the
777
+ * connection **it** opened; an injected repository is disposed by whoever built it. Ownership
778
+ * sits on the repository because the v2 client has no `dispose()` yet.
1107
779
  *
1108
780
  * ```ts
1109
- * await using repository = nodeSwapRepository({ network: "mainnet" });
781
+ * await using repository = nodeSwapRepository({ network: "bitcoin" });
1110
782
  * const client = createSwapClient({ wallet, repository });
1111
783
  * ```
1112
784
  */