@arkade-os/swap 0.1.0-rc.8 → 0.1.0

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