@arkade-os/swap 0.1.0-rc.13 → 0.1.0-rc.15

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 (53) hide show
  1. package/README.md +11 -0
  2. package/dist/advanced.cjs +1028 -1006
  3. package/dist/advanced.d.cts +145 -279
  4. package/dist/advanced.d.ts +145 -279
  5. package/dist/advanced.js +14 -8
  6. package/dist/{chunk-SC3SAY3X.js → chunk-4WPDXLXH.js} +501 -271
  7. package/dist/chunk-A3SHHRX4.js +104 -0
  8. package/dist/{chunk-KRXPQQJ7.js → chunk-BBP25BWH.js} +198 -218
  9. package/dist/{chunk-ZDFMD4FA.js → chunk-RX3WPV5D.js} +356 -584
  10. package/dist/errors-BcOgFV-F.d.ts +1559 -0
  11. package/dist/errors-n6IHTG-Z.d.cts +1559 -0
  12. package/dist/index.cjs +1406 -1331
  13. package/dist/index.d.cts +69 -186
  14. package/dist/index.d.ts +69 -186
  15. package/dist/index.js +102 -158
  16. package/dist/lockupContract-B_jNbjrG.d.ts +215 -0
  17. package/dist/lockupContract-ZsftgqMc.d.cts +215 -0
  18. package/dist/node/index.cjs +61 -10
  19. package/dist/node/index.d.cts +227 -600
  20. package/dist/node/index.d.ts +227 -600
  21. package/dist/node/index.js +65 -10
  22. package/dist/nostr.cjs +11 -11
  23. package/dist/nostr.d.cts +23 -68
  24. package/dist/nostr.d.ts +23 -68
  25. package/dist/nostr.js +3 -4
  26. package/dist/offer--1zVkNsV.d.ts +261 -0
  27. package/dist/offer-DsP1q6GE.d.cts +261 -0
  28. package/dist/protocol.cjs +747 -1012
  29. package/dist/protocol.d.cts +120 -255
  30. package/dist/protocol.d.ts +120 -255
  31. package/dist/protocol.js +146 -149
  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-BY6GUQiW.d.ts +2233 -0
  41. package/dist/repository-C32GKpR5.d.cts +2233 -0
  42. package/dist/{rfq-BWE8qkV2.d.ts → rfq-60PGpQ_x.d.cts} +178 -408
  43. package/dist/{rfq-BWE8qkV2.d.cts → rfq-60PGpQ_x.d.ts} +178 -408
  44. package/dist/{watch-D8Z78RAV.d.ts → watch-Cejw5cNQ.d.cts} +12 -30
  45. package/dist/{watch-C4ReJR5z.d.cts → watch-D8uzWrHc.d.ts} +12 -30
  46. package/package.json +2 -2
  47. package/dist/chunk-U7VWWTL6.js +0 -66
  48. package/dist/errors-LXMcNhNS.d.ts +0 -2222
  49. package/dist/errors-XUs8r0LT.d.cts +0 -2222
  50. package/dist/lockupContract-BhMebZCb.d.cts +0 -650
  51. package/dist/lockupContract-CAiN97fX.d.ts +0 -650
  52. package/dist/repository-BJLuVFQ0.d.ts +0 -3436
  53. package/dist/repository-DsR3b0JJ.d.cts +0 -3436
@@ -1,71 +1,39 @@
1
1
  import { VHTLC, IWallet, ProvisionedKey, ProvisionedClaimSecret, asset } from '@arkade-os/sdk';
2
2
 
3
- /** L1 confirmation-depth and reorg margin between dependent timelocks.
4
- *
5
- */
3
+ /** L1 confirmation-depth and reorg margin between dependent timelocks. */
6
4
  declare const ONCHAIN_ORDER_MARGIN_SECONDS: number;
7
5
  /** Don't broadcast a claim with less than this before the refund leaf opens:
8
6
  * MTP lag plus confirmation time. Past this point the safe move is to let the
9
7
  * swap die and take the covenant refund — claiming into the counterparty's
10
- * live refund window risks losing the race AND publishing P.
11
- *
12
- */
8
+ * live refund window risks losing the race AND publishing P. */
13
9
  declare const ONCHAIN_CLAIM_MARGIN_SECONDS: number;
14
- /** Bounds on the confirmation depth a quote may demand.
15
- *
16
- */
10
+ /** Bounds on the confirmation depth a quote may demand. */
17
11
  declare const MAX_MIN_CONFIRMATIONS = 6;
18
12
  /**
19
- * BIP65's boundary between the two things an absolute locktime can mean.
20
- * Below it consensus reads the value as a block height; at or above it, as a
21
- * unix timestamp. 500,000,000 itself is 1985-07-05 and is a timestamp, so the
22
- * comparison against it is strict.
23
- *
13
+ * BIP65's boundary between the two things an absolute locktime can mean: below it a block height,
14
+ * at or above it a unix timestamp (so the comparison is strict).
24
15
  */
25
16
  declare const LOCKTIME_THRESHOLD = 500000000;
26
- /** Conservative block interval for converting depths into wall-clock time.
27
- *
28
- */
17
+ /** Conservative block interval for converting depths into wall-clock time. */
29
18
  declare const ONCHAIN_SECONDS_PER_BLOCK = 600;
30
19
  /**
31
20
  * Outputs below this are unspendable in practice; builders refuse them.
32
21
  *
33
- * 330, not 546: Bitcoin Core's dust threshold is a function of the OUTPUT
34
- * type, and 546 is the P2PKH figure. Both payout scripts on this corridor are
35
- * taproot — the claim pays the user's Arkade-side L1 address and the refund
36
- * pays the trader's — for which the threshold is 330 (the same number
37
- * `FALLBACK_WALLET_DUST_AMOUNT` already uses in the core SDK). Holding the
38
- * P2PKH number here rejects payouts between 330 and 546 that the network
39
- * would relay perfectly well, which on a refund path means refusing to return
40
- * funds that could have been returned.
41
- *
42
- * Should a caller ever pass a legacy `payoutPkScript`, this floor is too low
43
- * for that output and the spend would be non-standard; the threshold would
44
- * then have to be derived from the script rather than fixed.
45
- *
46
- * `BigInt(330)` rather than a `330n` literal, matching the rest of the
47
- * package: a bigint literal needs an ES2020 target, and this source is read
48
- * directly by consumers that target lower — forcing every one of them to
49
- * raise their own target for a single constant. The compiled output is
50
- * identical.
51
- *
22
+ * 330, not 546: dust depends on output type, and both payouts here are taproot (546 is P2PKH).
23
+ * The higher figure would refuse relayable refunds. A legacy `payoutPkScript` would need a
24
+ * script-derived threshold. `BigInt(330)`, not `330n`: consumers read this source directly and
25
+ * may target below ES2020.
52
26
  */
53
27
  declare const ONCHAIN_DUST_SATS: bigint;
54
- /** 32 random bytes. The user generates P for BOTH onchain directions.
55
- *
56
- */
28
+ /** 32 random bytes. The user generates P for BOTH onchain directions. */
57
29
  declare const newPreimage: () => Uint8Array;
58
- /** `sha256(P)`, hex — the wire `payment_hash`, same convention as BOLT11.
59
- *
60
- */
30
+ /** `sha256(P)`, hex — the wire `payment_hash`, same convention as BOLT11. */
61
31
  declare const paymentHashOf: (preimage: Uint8Array) => string;
62
32
  type OnchainNetwork = "bitcoin" | "testnet" | "regtest";
63
33
  /**
64
- * The `payoutPkScript` {@link buildHtlcClaim} pays the fill to. Resolved EARLY:
65
- * the claim's output is the spender's own choice, so nothing that survives a
66
- * send screen names it, and a destination that cannot be encoded must be
67
- * refused before the swap is negotiated rather than at claim time.
68
- *
34
+ * The `payoutPkScript` {@link buildHtlcClaim} pays the fill to. Resolve it EARLY: nothing else
35
+ * names the spender's destination, and one that cannot be encoded must be refused before the swap
36
+ * is negotiated, not at claim time.
69
37
  */
70
38
  declare const l1ScriptForAddress: (address: string, network: OnchainNetwork) => Uint8Array;
71
39
  interface OnchainHtlcParams {
@@ -101,14 +69,8 @@ interface OnchainHtlc {
101
69
  * claim: `OP_SIZE 32 OP_EQUALVERIFY OP_HASH160 <h160> OP_EQUALVERIFY <claimKey> OP_CHECKSIG`
102
70
  * refund: `<locktime> OP_CHECKLOCKTIMEVERIFY OP_DROP <refundKey> OP_CHECKSIG`
103
71
  *
104
- * The claim leaf's `OP_SIZE 32 OP_EQUALVERIFY` prefix pins the witness
105
- * preimage to exactly 32 bytes before it's hashed — the same shape real HTLC
106
- * scripts (e.g. BOLT3's) carry, and this contract's preimage is always
107
- * exactly 32 bytes by construction.
108
- *
109
- * Pure derivation — pinned byte-for-byte by the golden test; any drift here
110
- * changes addresses on BOTH sides of a swap.
111
- *
72
+ * `OP_SIZE 32` pins the preimage to 32 bytes before hashing, as BOLT3 HTLCs do. Pinned
73
+ * byte-for-byte by the golden test; any drift changes addresses on BOTH sides of a swap.
112
74
  */
113
75
  declare function onchainHtlcScript(params: OnchainHtlcParams, network: OnchainNetwork): OnchainHtlc;
114
76
  interface HtlcUtxo {
@@ -124,9 +86,7 @@ interface SpendResult {
124
86
  }
125
87
  /** Script-path spend of the claim leaf; the witness reveals P — that is how
126
88
  * the counterparty learns it, so never build this unless the claim will win
127
- * (see {@link claimOnchainFill}). `sign` is BIP340 over the claim key.
128
- *
129
- */
89
+ * (see {@link claimOnchainFill}). `sign` is BIP340 over the claim key. */
130
90
  declare const buildHtlcClaim: (input: {
131
91
  htlc: OnchainHtlc;
132
92
  utxo: HtlcUtxo;
@@ -137,9 +97,7 @@ declare const buildHtlcClaim: (input: {
137
97
  }) => Promise<SpendResult>;
138
98
  /** Script-path spend of the refund leaf; consensus-valid only once nLockTime
139
99
  * has matured against median-time-past — gate on {@link ChainSource.getMtp},
140
- * not wall clock. `sign` is BIP340 over the refund key.
141
- *
142
- */
100
+ * not wall clock. `sign` is BIP340 over the refund key. */
143
101
  declare const buildHtlcRefund: (input: {
144
102
  htlc: OnchainHtlc;
145
103
  utxo: HtlcUtxo;
@@ -150,13 +108,8 @@ declare const buildHtlcRefund: (input: {
150
108
  interface ChainUtxo extends HtlcUtxo {
151
109
  confirmations: number;
152
110
  }
153
- /** The package's whole view of Bitcoin L1. An esplora-backed implementation
154
- * belongs to the caller (a reference one lives in the test suite); the package
155
- * itself stays backend-free.
156
- *
157
- * A root export because `CorridorOverrides.onchain.chain` takes it: a caller
158
- * wiring that override names this type.
159
- */
111
+ /** The package's whole view of Bitcoin L1, injected so the package stays backend-free
112
+ * (`CorridorOverrides.onchain.chain` takes it). */
160
113
  interface ChainSource {
161
114
  /** Confirmed+mempool outputs paying a script; used to detect the fill. */
162
115
  getScriptUtxos(pkScript: Uint8Array): Promise<ChainUtxo[]>;
@@ -171,27 +124,19 @@ interface ChainSource {
171
124
  }
172
125
  /** Read P out of a claim spend's witness: the 32-byte item whose sha256 is the
173
126
  * payment hash. Null when the tx reveals no matching preimage (e.g. a refund
174
- * spend, or an unrelated tx).
175
- *
176
- */
127
+ * spend, or an unrelated tx). */
177
128
  declare function extractPreimage(txHex: string, paymentHash: string): Uint8Array | null;
178
129
  /** Poll {@link ChainSource} until the HTLC is funded to the required depth.
179
130
  * Picks the largest qualifying output when several exist. Throws (reason
180
- * `fill_timeout`) once `deadline` (unix seconds) passes without one.
181
- *
182
- */
131
+ * `fill_timeout`) once `deadline` (unix seconds) passes without one. */
183
132
  declare function awaitOnchainFill(chain: ChainSource, htlc: OnchainHtlc, minConfirmations: number, options?: {
184
133
  pollMs?: number;
185
134
  deadline?: number;
186
135
  }): Promise<ChainUtxo>;
187
136
  /**
188
- * Claim the fill: build the claim spend and broadcast it. Broadcasting
189
- * publishes P (mempool) — by design, it is how the solver gets paid — so this
190
- * refuses (reason `claim_window_closed`) when less than
191
- * {@link ONCHAIN_CLAIM_MARGIN_SECONDS} remains before the refund leaf opens:
192
- * past that point, let the swap die and take the covenant refund instead of
193
- * racing the counterparty's refund with P exposed.
194
- *
137
+ * Claim the fill: build the claim spend and broadcast it, publishing P (that is how the solver
138
+ * gets paid). Refuses (`claim_window_closed`) with less than {@link ONCHAIN_CLAIM_MARGIN_SECONDS}
139
+ * before the refund leaf opens.
195
140
  */
196
141
  declare function claimOnchainFill(chain: ChainSource, input: {
197
142
  htlc: OnchainHtlc;
@@ -206,11 +151,8 @@ declare function claimOnchainFill(chain: ChainSource, input: {
206
151
  txid: string;
207
152
  payoutAmount: bigint;
208
153
  }>;
209
- /** Where an onchain HTLC stands, for crash recovery (see the store docs:
210
- * persisting the record BEFORE funding is what makes this classification —
211
- * and the claim — possible after a restart).
212
- *
213
- */
154
+ /** Where an onchain HTLC stands, for crash recovery. Persisting the record BEFORE funding is what
155
+ * makes this classification (and the claim) possible after a restart. */
214
156
  type OnchainHtlcPhase = {
215
157
  phase: "unfunded";
216
158
  } | {
@@ -221,12 +163,9 @@ type OnchainHtlcPhase = {
221
163
  utxo: ChainUtxo;
222
164
  }
223
165
  /**
224
- * The refund leaf has matured, which means the CLAIM WINDOW IS CLOSED —
225
- * `claimOnchainFill` throws `claim_window_closed` from here, by design.
226
- * A recovery caller reading this phase must not try to claim: the correct
227
- * action is to let the counterparty's L1 refund settle and take the
228
- * Arkade-side covenant refund. Reaching this phase on a swap you expected
229
- * to claim means the claim was missed, not that it is still available.
166
+ * The refund leaf has matured, so the CLAIM WINDOW IS CLOSED and `claimOnchainFill` throws.
167
+ * Do not claim: let the counterparty's L1 refund settle and take the Arkade-side covenant
168
+ * refund. On a swap you expected to claim, this means the claim was missed.
230
169
  */
231
170
  | {
232
171
  phase: "refundable";
@@ -246,7 +185,6 @@ type OnchainHtlcPhase = {
246
185
  *
247
186
  * `claimed` carries the preimage read from the spend's witness — the receipt;
248
187
  * `swept` is a spend that reveals no preimage (the counterparty's refund).
249
- *
250
188
  */
251
189
  declare function classifyOnchainHtlc(chain: ChainSource, input: {
252
190
  htlc: OnchainHtlc;
@@ -261,33 +199,21 @@ declare function classifyOnchainHtlc(chain: ChainSource, input: {
261
199
  declare const ARKADE_BTC = "arkade:BTC";
262
200
  declare const LIGHTNING_BTC = "lightning:BTC";
263
201
  declare const ONCHAIN_BTC = "onchain:BTC";
264
- /** The arkade leg for an asset: the asset id itself, 68 lowercase hex. The id
265
- * lives in the pair rather than the profile because the pair is the field both
266
- * sides route and subscribe on, and a coarse leg cannot say which asset a
267
- * market key is for.
202
+ /** The arkade leg for an asset: the asset id itself, 68 lowercase hex, in the pair because the
203
+ * pair is what both sides route and subscribe on.
268
204
  *
269
- * Taking an `AssetId` rather than a string is what enforces the case rule:
270
- * `hex.decode` accepts uppercase while `hex.encode` only emits lowercase, so a
271
- * value that reached us as `A1B2…` leaves here as `a1b2…`. Solvers compare pair
272
- * strings byte for byte — a sender that normalised only in its key derivation
273
- * would reach the right subscription and then be skipped as an unserved pair.
274
- *
275
- */
205
+ * Takes an `AssetId`, not a string, to enforce lowercase (`hex.decode` accepts uppercase,
206
+ * `toString()` emits lowercase): solvers compare pair strings byte for byte, so `A1B2…` would be
207
+ * skipped as an unserved pair. */
276
208
  declare const arkadeAssetLeg: (id: asset.AssetId) => string;
277
209
  /** The implemented pair: pay a BOLT11 invoice out of an Arkade balance. */
278
210
  declare const LIGHTNING_SEND_PAIR: string;
279
- /** On-board via Lightning: pay the solver's hold invoice, land on Arkade.
280
- *
281
- */
211
+ /** On-board via Lightning: pay the solver's hold invoice, land on Arkade. */
282
212
  declare const LIGHTNING_RECEIVE_PAIR: string;
283
213
  declare const ONCHAIN_SEND_PAIR: string;
284
- /** On-board: a Bitcoin-L1 HTLC in, Arkade sats out.
285
- *
286
- */
214
+ /** On-board: a Bitcoin-L1 HTLC in, Arkade sats out. */
287
215
  declare const ONCHAIN_RECEIVE_PAIR: string;
288
- /** The closed refusal set. Treat any unknown reason as a generic decline.
289
- *
290
- */
216
+ /** The closed refusal set. Treat any unknown reason as a generic decline. */
291
217
  type RfqRefusalReason = "unsupported_pair" | "unsupported_payload" | "amount_out_of_range" | "exposure_cap" | "invoice_expired" | "quote_conflict" | "pricing_unavailable" | "rate_limited";
292
218
  declare const RFQ_REFUSAL_ERROR_CODES: readonly ["amount_side_unsupported", "exact_out_unsupported", "invalid_amount", "invalid_payout_address", "invalid_refund_address", "invoice_amount_mismatch", "invoice_cltv_too_large", "invoice_malformed", "invoice_missing_amount", "invoice_missing_network", "invoice_missing_payment_hash", "invoice_missing_timestamp", "invoice_mixed_case", "invoice_sub_satoshi_amount", "invoice_too_long", "invoice_wrong_network"];
293
219
  type RfqRefusalErrorCode = (typeof RFQ_REFUSAL_ERROR_CODES)[number];
@@ -304,8 +230,7 @@ declare const isRfqRefusalErrorCode: (value: unknown) => value is RfqRefusalErro
304
230
  /** A refusal from the solver, carrying its closed-set reason. */
305
231
  declare class SwapRefusal extends Error {
306
232
  /** Literal-typed so the v2 error taxonomy's union discriminates on `name`
307
- * — a `string` here collapses the discriminant for every member. Same value
308
- * the constructor has always set, moved to a field initializer. */
233
+ * — a `string` here collapses the discriminant for every member. */
309
234
  readonly name = "SwapRefusal";
310
235
  readonly reason: string;
311
236
  readonly rfqId: string | undefined;
@@ -321,7 +246,6 @@ declare class SwapRefusal extends Error {
321
246
  * The solver's address does not match the local derivation. NEVER fund past
322
247
  * this. `derived` is every candidate address tried — more than one when the
323
248
  * derivation itself is ambiguous, see {@link verifyLockupAddress}.
324
- *
325
249
  */
326
250
  declare class AddressMismatch extends Error {
327
251
  readonly derived: string | string[];
@@ -338,7 +262,8 @@ interface RfqQuote {
338
262
  * solver). */
339
263
  from_amount: number | string;
340
264
  to_amount: number | string;
341
- /** Dust an asset rides on. NOT a fee — already netted into the amounts above. */
265
+ /** Dust an asset deposit rides on, kept by the filler. Expected back in `to_amount`; the
266
+ * client counts any shortfall as fee. */
342
267
  carrier_sats?: number | string;
343
268
  solver_pubkey: string;
344
269
  valid_until: number;
@@ -363,15 +288,11 @@ interface RfqStatus {
363
288
  profile: Record<string, unknown>;
364
289
  [key: string]: unknown;
365
290
  }
366
- /** The rfq_request for the lightning send profile. A BOLT11 profile is always
367
- * exact-out: the invoice fixes the amount, so none is restated here.
368
- * `senderPubkey` is the trader's own key for the VHTLC's sender-side leaves
369
- * (see {@link lightningSendContract}) — required, never sent anywhere else,
370
- * never trusted by the solver as anything but a pubkey to bind into the
371
- * script. On the wire it's `client_refund_pubkey` (the payload schemas are
372
- * public at https://docs.arkadeos.com/intents/reference/rfq — the solver's schema
373
- * is `.strict()`, so both the wrong name AND the missing required field would
374
- * refuse every request).
291
+ /** The rfq_request for the lightning send profile. BOLT11 is exact-out: the invoice fixes the
292
+ * amount. `senderPubkey` is the trader's key for the VHTLC's sender-side leaves (see
293
+ * {@link lightningSendContract}), sent as `client_refund_pubkey`; the solver's schema
294
+ * (https://docs.arkadeos.com/intents/reference/rfq) is `.strict()`, so a wrong or missing name
295
+ * refuses every request.
375
296
  */
376
297
  declare const lightningSendRequest: (input: {
377
298
  rfqId: string;
@@ -383,13 +304,10 @@ declare const lightningSendRequest: (input: {
383
304
  * id (BTC has none), and the id is the leg itself — see
384
305
  * {@link arkadeAssetLeg}.
385
306
  *
386
- * Wire-compatible with the reference solver (`AssetRfqRequest`, strict):
387
- * `amount` is a canonical decimal string of atomic units (never a JSON
388
- * number — an Arkade asset's precision is not knowable client-side, so the
389
- * losslessness carve-out cannot be checked), `amount_side` is `"from"` or
390
- * `"to"`, and `profile` carries the trader's own covenant position
391
- * (`maker_pk_script`, `maker_public_key`) — the fill pays that script, and
392
- * `cancel` is signed by that key. */
307
+ * Matches the reference solver's strict `AssetRfqRequest`: `amount` is a canonical decimal string
308
+ * of atomic units (never a JSON number: an asset's precision is unknowable client-side), and
309
+ * `amount_side` is `"from"` or `"to"`, and `profile` carries the trader's covenant position — the fill pays `maker_pk_script`, and `cancel`
310
+ * is signed by `maker_public_key`. */
393
311
  declare const arkadeSwapRequest: (input: {
394
312
  rfqId: string;
395
313
  /** Asset the trader deposits; omit when depositing BTC. */
@@ -425,19 +343,12 @@ declare const normalizeMakerPublicKey: (value: Uint8Array | string) => string;
425
343
  * Compare-only check of the solver's address against YOUR OWN derivation(s)
426
344
  * — never extends trust, only narrows it.
427
345
  *
428
- * `derivedAddress` may be a single address or an array of candidates. Pass an
429
- * array when your own derivation is ambiguous — as it is for the covenant
430
- * lockups while solvers roll out the timelocked non-interactive refund leaf:
431
- * nothing on the wire says whether a given quote's covenant carries it (the
432
- * shape is fixed by the solver's own build, not negotiated per quote), so the
433
- * only safe move is to derive BOTH shapes and accept whichever one the quote's
434
- * own `lockup_address` matches. This loses no security: every candidate shape
435
- * pins the refund to the trader's own refund destination, so a solver gains
436
- * nothing by choosing which one to quote.
437
- *
438
- * Throws {@link AddressMismatch} only when NONE of the candidates match.
439
- * Returns the address that matched, so calls chain exactly as before.
346
+ * Pass an array when your derivation is ambiguous, as for covenant lockups while solvers roll out
347
+ * the timelocked non-interactive refund leaf (nothing on the wire says which shape a quote uses).
348
+ * No security is lost: every candidate pins the refund to the trader's own destination.
440
349
  *
350
+ * @returns the address that matched.
351
+ * @throws {AddressMismatch} only when NONE of the candidates match.
441
352
  */
442
353
  declare const verifyLockupAddress: (quote: RfqQuote, derivedAddress: string | string[]) => string;
443
354
  interface RfqTransport {
@@ -446,16 +357,12 @@ interface RfqTransport {
446
357
  close(): Promise<void>;
447
358
  }
448
359
  /** HTTP: POST /v1/swap for quotes, GET /v1/rfq/<rfq_id> for status.
449
- * `fetchImpl` is injectable for tests and non-global-fetch runtimes.
450
- *
451
- */
360
+ * `fetchImpl` is injectable for tests and non-global-fetch runtimes. */
452
361
  declare const httpTransport: (baseUrl: string, options?: {
453
362
  fetchImpl?: typeof fetch;
454
363
  }) => RfqTransport;
455
364
  /** Minimal WebSocket surface the relay transport needs — satisfied by the DOM
456
- * WebSocket and by `ws` alike, so neither becomes a dependency.
457
- *
458
- */
365
+ * WebSocket and by `ws` alike, so neither becomes a dependency. */
459
366
  interface RelaySocket {
460
367
  send(data: string): void;
461
368
  close(): void;
@@ -463,66 +370,49 @@ interface RelaySocket {
463
370
  }
464
371
  /** Relay: both parties outbound, addressed by x-only pubkey, speaking the dev
465
372
  * broker framing. Nostr (directed kind + NIP-44) replaces only this function.
466
- * One socket; replies correlated by rfq_id.
467
- *
468
- */
373
+ * One socket; replies correlated by rfq_id. */
469
374
  declare const relayTransport: (relayUrl: string, options: {
470
375
  solverPubkey: string;
471
376
  clientPubkey: string;
472
377
  WebSocketCtor?: new (url: string) => RelaySocket;
473
378
  timeoutMs?: number;
474
379
  }) => RfqTransport;
475
- /** The solver's unilateral-claim delay, derived from the Ark server's reported
380
+ /** The solver's unilateral-claim delay, derived from the Arkade operator's reported
476
381
  * exit delay exactly as the reference solver derives it — both sides read the
477
382
  * SAME server, so the derivation (not a quote field) is what keeps the two
478
- * scripts identical.
479
- *
480
- */
383
+ * scripts identical. */
481
384
  declare const unilateralClaimDelay: (operatorExitDelaySeconds: number) => number;
482
385
  /** VHTLC's `unilateralRefund` tier: sender + receiver, no server — LEVEL with
483
386
  * `claimDelay`, not above it. Neither party can spend a two-signature leaf
484
- * alone, so separating it buys no safety, and every second spent separating it
485
- * is a second taken off the headroom that does matter.
486
- *
487
- */
387
+ * alone, so separating it buys no safety and would only eat into the headroom that matters. */
488
388
  declare const unilateralRefundDelay: (claimDelay: number) => number;
489
389
  /** VHTLC's `unilateralRefundWithoutReceiver` tier: sender alone, needing
490
390
  * nobody. The only leaf whose timing can steal — a funder able to refund
491
391
  * before the claimant can claim takes money from someone holding the preimage
492
- * — so it opens last, by {@link SOLO_REFUND_HEADROOM_SECONDS}.
493
- *
494
- */
392
+ * — so it opens last, by {@link SOLO_REFUND_HEADROOM_SECONDS}. */
495
393
  declare const unilateralRefundWithoutReceiverDelay: (claimDelay: number) => number;
496
394
  /** Compile the lightning-send VHTLC from the quote's binding fields plus the
497
395
  * trader's own data. `paymentHash` is the BOLT11 payment hash (`sha256(P)`,
498
396
  * hex); the script's HASH160 commitment is derived from it here, which is why
499
397
  * the trader never needs to see `P`.
500
398
  *
501
- * Every quote gets the full emulator-covenant suite on top of VHTLC's own six
502
- * (`claim`/`refund`/`refundWithoutReceiver`/`unilateralClaim`/
503
- * `unilateralRefund`/`unilateralRefundWithoutReceiver`): `nonInteractiveClaim`
504
- * (server + emulator, pays the solver's own `receiverPkScript`, no solver
505
- * signature needed), `nonInteractiveRefund` (server + solver + emulator, pays
506
- * the trader's own `refundPkScript`, no timelock and no trader signature
507
- * needed — see {@link VHTLC.Options.nonInteractiveParameters}'s doc comment for why
508
- * that matters), and its timelocked twin `nonInteractiveRefundWithoutReceiver`
509
- * (server + emulator alone, after `refundLocktime` — the only refund tier
510
- * needing no participant at all). Nine leaves in all, unless `legacy` says
511
- * otherwise.
512
- *
399
+ * Nine leaves unless `legacy`: VHTLC's six plus the emulator-covenant suite —
400
+ * `nonInteractiveClaim` (server + emulator, pays the solver's `receiverPkScript`),
401
+ * `nonInteractiveRefund` (server + solver + emulator, pays the trader's `refundPkScript`, no
402
+ * timelock or trader signature; see {@link VHTLC.Options.nonInteractiveParameters}), and
403
+ * `nonInteractiveRefundWithoutReceiver` (server + emulator after `refundLocktime`).
513
404
  */
514
405
  declare function lightningSendContract(params: {
515
406
  /** Binding field #1: the solver's x-only key, from the quote. */
516
407
  solverPubkey: Uint8Array;
517
408
  /** Binding field #2: when the trader's refund path opens, from the quote. */
518
409
  refundLocktime: number;
519
- /** The Ark server's x-only key — the trader's OWN connection. */
410
+ /** The Arkade operator's x-only key — the trader's OWN connection. */
520
411
  operatorPubkey: Uint8Array;
521
412
  /** BOLT11 payment hash, hex — from the trader's OWN invoice decode. */
522
413
  paymentHash: string;
523
- /** From {@link unilateralClaimDelay} over the trader's OWN server info.
524
- * {@link unilateralRefundDelay} and {@link unilateralRefundWithoutReceiverDelay}
525
- * derive from this same value — one rounding, shared across all three tiers. */
414
+ /** From {@link unilateralClaimDelay} over the trader's OWN server info; all three unilateral
415
+ * tiers derive from it. */
526
416
  claimDelay: number;
527
417
  /** Binding quote field. Optional only for rebuilding pre-upgrade scripts. */
528
418
  refundWithoutReceiverDelay?: number;
@@ -531,32 +421,20 @@ declare function lightningSendContract(params: {
531
421
  /** Where a refund must pay: the trader's P2TR pkScript (34 bytes). Also
532
422
  * the refund covenants' destination. */
533
423
  refundPkScript: Uint8Array;
534
- /** The trader's own key — VHTLC's `sender` role. Required on every
535
- * interactive refund-side leaf; the trader generates and persists it
536
- * (see {@link requestLightningSend}'s own obligations). */
424
+ /** The trader's own key — VHTLC's `sender` role, on every interactive refund-side leaf. */
537
425
  senderPubkey: Uint8Array;
538
- /** The solver's own claim destination, from the quote
539
- * (`profile.receiver_pk_script`) — needed only so `nonInteractiveClaim`'s
540
- * covenant key can be derived; the trader does not otherwise use or trust
541
- * this value. P2TR pkScript, 34 bytes. */
426
+ /** The solver's claim destination (`profile.receiver_pk_script`, P2TR), used only to derive
427
+ * `nonInteractiveClaim`'s covenant key; not otherwise trusted. */
542
428
  receiverPkScript: Uint8Array;
543
- /** LEGACY REBUILD ONLY — see {@link VHTLC.Options.nonInteractiveParameters}'s
544
- * `legacy` field. Set only to re-derive a lockup funded before the
545
- * timelocked refund leaf shipped; {@link matchQuotedLockup} passes it when
546
- * the quote's own address says the solver quoted that shape. */
429
+ /** LEGACY REBUILD ONLY: re-derive a lockup funded before the timelocked refund leaf shipped
430
+ * (see {@link VHTLC.Options.nonInteractiveParameters}); set by {@link matchQuotedLockup}. */
547
431
  legacy?: "preTimelockedRefund";
548
432
  }): InstanceType<typeof VHTLC.ScriptV2>;
549
- /** Every input {@link lightningSendContract} builds from. Derived from the
550
- * builder rather than restated, so the two cannot drift.
551
- *
552
- */
433
+ /** Every input {@link lightningSendContract} builds from. */
553
434
  type LightningSendContractParams = Parameters<typeof lightningSendContract>[0];
554
435
  /** The BOLT11 facts the trader read from its OWN decode — this module takes
555
- * the facts, not the decoder, so any wallet's existing decoder serves.
556
- *
557
- * A root export because `CorridorOverrides.lightning.decode` returns it: a
558
- * caller wiring that override names this type.
559
- */
436
+ * the facts, not the decoder, so any wallet's existing decoder serves
437
+ * (`CorridorOverrides.lightning.decode` returns it). */
560
438
  interface InvoiceFacts {
561
439
  /** The raw BOLT11 — what travels in the request profile. */
562
440
  raw: string;
@@ -568,34 +446,19 @@ interface InvoiceFacts {
568
446
  expiresAt: number;
569
447
  }
570
448
  /**
571
- * The lightning-send user flow, mirroring `createOffer`'s shape: quote →
572
- * derive locally → verify → gate. Pure of funding on purpose — it returns the
573
- * address and amount, and the caller funds with its own wallet
574
- * (`wallet.send({ address, amount })`) before `quote.valid_until`, after
575
- * which the user may go OFFLINE: filling is non-interactive. Success reveals
576
- * the preimage in the solver's claim witness (also served via status as
577
- * `settled`); failure refunds to `refundAddress`.
578
- *
579
- * Throws {@link SwapRefusal} (closed reason), {@link AddressMismatch} (never
580
- * fund), a gate error with a stable `reason`, or
581
- * {@link LockupRegistrationFailed} — the last one alone means the quote is
582
- * still good and the same call can be retried once local storage is.
449
+ * The lightning-send user flow: quote → derive locally → verify → gate. Funds nothing: the caller
450
+ * funds `address` with `fundAmount` before `quote.valid_until`, then may go OFFLINE. Success
451
+ * reveals the preimage in the solver's claim witness; failure refunds to `refundAddress`.
583
452
  *
584
- * Broadcasts nothing, but does write locally: the lockup is registered with the
585
- * wallet's contract manager before the address is returned, exactly as
586
- * `createOffer` registers its covenant — so the lockup is watched from the
587
- * moment it lands and out of generic coin selection, and a persistence failure
588
- * throws while nothing is funded. `RfqSwapManager` re-registers as a backstop
589
- * for older records; a repeat write is a no-op.
590
- *
591
- * The `sender` key is the wallet's identity key, as {@link provisionRefundKey}
592
- * pins it — returned as `senderPubkey` plus `secrets`. `secrets` holds only a
593
- * public descriptor; the signer re-derives from the wallet, so nothing secret
594
- * is at rest. Persist `secrets` with the record anyway: it is how the refund
595
- * signer is found again. `nonInteractiveRefund` recovers the funds even
596
- * without it — but it needs the SOLVER's active cooperation, not just
597
- * infrastructure uptime.
453
+ * @throws {SwapRefusal} (closed reason), {@link AddressMismatch} (never fund), a gate error with a
454
+ * stable `reason`, or {@link LockupRegistrationFailed} — only the last leaves the quote good for a
455
+ * retry once local storage is.
598
456
  *
457
+ * @remarks Registers the lockup with the contract manager before returning the address, so it is
458
+ * watched (and out of coin selection) from the moment it lands, and a persistence failure throws
459
+ * while nothing is funded. Persist `secrets` (a public descriptor) with the record: it is how the
460
+ * refund signer is found again; without it `nonInteractiveRefund` still works but needs the
461
+ * SOLVER's active cooperation.
599
462
  */
600
463
  declare function requestLightningSend(wallet: IWallet, transport: RfqTransport, params: {
601
464
  invoice: InvoiceFacts;
@@ -613,12 +476,10 @@ declare function requestLightningSend(wallet: IWallet, transport: RfqTransport,
613
476
  fundAmount: number;
614
477
  /** The covenant's scriptPubKey, for watching the lockup and its spend. */
615
478
  swapPkScript: Uint8Array;
616
- /** The covenant itself. Hand it to `RfqSwapManager` as the record's
617
- * `lockup` (with `address`): without it the manager can only poll, and
618
- * cannot retire the row this call just wrote. */
479
+ /** The covenant itself. Hand it to `RfqSwapManager` as the record's `lockup` (with
480
+ * `address`); without it the manager can only poll and cannot retire the row. */
619
481
  script: InstanceType<typeof VHTLC.ScriptV2>;
620
- /** Where a failed swap refunds — the same address `secrets.pkScript` was
621
- * decoded from, so the quote and the covenant always name one script. */
482
+ /** Where a failed swap refunds; the address `secrets.pkScript` was decoded from. */
622
483
  refundAddress: string;
623
484
  /** The VHTLC `sender` x-only key, bound into the covenant. Public. */
624
485
  senderPubkey: Uint8Array;
@@ -626,28 +487,15 @@ declare function requestLightningSend(wallet: IWallet, transport: RfqTransport,
626
487
  * it holds nothing secret. */
627
488
  secrets: ProvisionedKey;
628
489
  /**
629
- * Every input the covenant was built from, as it was AT REQUEST TIME.
630
- *
631
- * Returned so a consumer can persist the swap without re-deriving any of
632
- * it. Half of these are not on the quote: `serverPubkey` and `claimDelay`
633
- * come from this wallet's own `getArkadeInfo()`, `emulatorPubkey` from a
634
- * per-network pin, `refundPkScript` from `secrets` — decoded from the
635
- * refund address at provisioning time, the same address this call returns
636
- * as `refundAddress`.
637
- *
638
- * All public. Persisting them is optional: this call also registers the
639
- * lockup as a contract, and that row is where `rebuildRfqSwap` takes its
640
- * covenant from — see `rfqRecord.ts`. Keep a copy only to hold a record
641
- * that rebuilds without the wallet's contract store, and keep it as
642
- * `VHTLCV2ContractHandler.serializeParams(script.options)`, the shape the
643
- * rebuild accepts.
490
+ * Every input the covenant was built from, as it was AT REQUEST TIME (half are not on the
491
+ * quote). All public, and optional to persist: `rebuildRfqSwap` reads the registered contract
492
+ * row. To rebuild without that store, keep
493
+ * `VHTLCV2ContractHandler.serializeParams(script.options)` instead.
644
494
  */
645
495
  contractParams: LightningSendContractParams;
646
496
  }>;
647
- /** Compare-only check of the solver's offer address against YOUR OWN
648
- * derivation — never extends trust, only narrows it. Funds only on an exact
649
- * match of both the address (what the wallet sends to) and the script (what
650
- * `offerVtxoScript` compiles to). Throws {@link AddressMismatch} otherwise.
497
+ /** Compare-only check of the solver's offer address AND script against YOUR OWN derivation.
498
+ * Throws {@link AddressMismatch} unless both match exactly.
651
499
  *
652
500
  * @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`. */
653
501
  declare const verifyOfferAddress: (quote: RfqQuote, derived: {
@@ -657,10 +505,8 @@ declare const verifyOfferAddress: (quote: RfqQuote, derived: {
657
505
  address: string;
658
506
  swapPkScript: Uint8Array;
659
507
  };
660
- /** Gate an arkade↔arkade quote immediately before funding. No timelock exists
661
- * on this class (neither `fulfill` nor `cancel` carries one), so the only
662
- * clock is `valid_until`: funding after it is a deposit the solver will
663
- * refuse to fill, reclaimable only via cooperative `cancelOffer`.
508
+ /** Gate an arkade↔arkade quote immediately before funding. The only clock is `valid_until`:
509
+ * funding after it leaves a deposit the solver won't fill, reclaimable only via `cancelOffer`.
664
510
  *
665
511
  * @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`. */
666
512
  declare const assertArkadeFundable: (input: {
@@ -668,22 +514,22 @@ declare const assertArkadeFundable: (input: {
668
514
  now?: number;
669
515
  }) => void;
670
516
  /**
671
- * The arkade↔arkade user flow, mirroring `requestLightningSend`'s shape:
672
- * quote → derive locally → verify → gate. Pure of funding on purpose — it
673
- * returns the offer and the deposit it must carry, and the caller funds with
674
- * its own wallet before `quote.valid_until`, after which the user may go
675
- * offline: filling is non-interactive. An unfilled offer is cancelled
676
- * cooperatively (`cancelOffer`); there is no timelock refund.
517
+ * The arkade↔arkade user flow: quote → derive locally → verify → gate. Funds nothing; the caller
518
+ * funds before `quote.valid_until`, then may go offline. No timelock refund: an unfilled offer is
519
+ * cancelled cooperatively (`cancelOffer`).
520
+ *
521
+ * With `amountSide: "to"` the deposit is the solver's to name: set `maxFromAmount`, or fund
522
+ * whatever it quotes.
677
523
  *
678
- * Maker keys are the wallet's own (address script + identity x-only key), read
679
- * here so the request profile and the local `createOffer` derivation cannot
680
- * diverge. The quote's `offer_address`/`offer_pk_script` are compare-only:
681
- * a mismatch throws {@link AddressMismatch} and must never be funded.
524
+ * Maker keys are read once here so the request profile and the local `createOffer` derivation
525
+ * cannot diverge. Throws {@link SwapRefusal}, {@link AddressMismatch} (never fund), or a gate error
526
+ * with a stable `reason`.
682
527
  *
683
- * Works over any {@link RfqTransport} — HTTP, dev relay, or Nostr — since the
684
- * negotiation is one `rfq_request` round trip. Throws {@link SwapRefusal}
685
- * (closed reason), {@link AddressMismatch} (never fund), or a gate error with
686
- * a stable `reason`.
528
+ * `client.exchange()` now covers this route end to end — it opens the card's
529
+ * Nostr rendezvous, sends this same request, runs the full verification set,
530
+ * and registers, persists and funds in one step — so there is nothing left here
531
+ * that it does not do. What it additionally refuses is a transport that cannot
532
+ * say who answered, which this function, taking one from its caller, cannot.
687
533
  *
688
534
  * Funding (caller's job, immediately after, before `valid_until`):
689
535
  * - BTC->asset (`wantAsset`): `wallet.send({ address, amount: Number(fundAmount), extensions: [extension] })`
@@ -732,9 +578,7 @@ declare function requestArkadeSwap(wallet: IWallet, transport: RfqTransport, par
732
578
  /** The rfq_request for `arkade:BTC->onchain:BTC`. Exact-out means "this much
733
579
  * lands in the L1 HTLC". `senderPubkey` is the user's own key for the
734
580
  * VHTLC's sender-side leaves — same role as in {@link lightningSendRequest}.
735
- * On the wire it's `client_refund_pubkey`, same as there.
736
- *
737
- */
581
+ * On the wire it's `client_refund_pubkey`, same as there. */
738
582
  declare const onchainSendRequest: (input: {
739
583
  rfqId: string;
740
584
  /** `sha256(P)`, hex — user-chosen; see {@link paymentHashOf}. */
@@ -747,14 +591,9 @@ declare const onchainSendRequest: (input: {
747
591
  amount: number;
748
592
  amountSide: "from" | "to";
749
593
  }) => Record<string, unknown>;
750
- /** The rfq_request for `lightning:BTC->arkade:BTC`: pay the solver's hold
751
- * invoice, land on Arkade. The trader generates `P`, keeps it, and sends only
752
- * `H` plus `P` sealed to covclaimd — the solver never sees `P` until it
753
- * appears in a claim witness. `payoutPubkey` is the trader's own x-only
754
- * Arkade key — the covenant's `receiver` role on this leg, so the trader can
755
- * claim the lockup itself without covclaimd.
756
- *
757
- */
594
+ /** The rfq_request for `lightning:BTC->arkade:BTC`. The trader sends only `H` plus `P` sealed to
595
+ * covclaimd, so the solver never sees `P` before a claim witness. `payoutPubkey` is the covenant's
596
+ * `receiver`, so the trader can claim without covclaimd. */
758
597
  declare const lightningReceiveRequest: (input: {
759
598
  rfqId: string;
760
599
  /** `H = sha256(P)`, hex — trader-chosen; see {@link paymentHashOf}. */
@@ -763,20 +602,14 @@ declare const lightningReceiveRequest: (input: {
763
602
  payoutAddress: string;
764
603
  /** Trader's x-only arkade key — the covenant's `receiver` role. */
765
604
  payoutPubkey: Uint8Array;
766
- /** `P` sealed to covclaimd, base64 — `sealClaimPacket(...).ciphertext`.
767
- * Omitted when there is no covclaimd to seal to; the field is then left off
768
- * the wire entirely, since the solver refuses an empty packet. */
605
+ /** `P` sealed to covclaimd, base64 — `sealClaimPacket(...).ciphertext`. Omitted from the wire
606
+ * when there is no covclaimd: the solver refuses an empty packet. */
769
607
  claimPacket?: string;
770
608
  amount: number;
771
609
  amountSide: "from" | "to";
772
610
  }) => Record<string, unknown>;
773
- /** The rfq_request for `onchain:BTC->arkade:BTC`. The user funds the L1 HTLC
774
- * (holding its refund role) and receives Arkade; P travels sealed to
775
- * covclaimd (see `sealClaimPacket`) so the user can go offline after
776
- * funding. `payoutPubkey` is the trader's own x-only Arkade key — the
777
- * covenant's `receiver` role, same as the Lightning receive leg's.
778
- *
779
- */
611
+ /** The rfq_request for `onchain:BTC->arkade:BTC`. The user funds the L1 HTLC (holding its refund
612
+ * role); P travels sealed to covclaimd so the user can go offline after funding. */
780
613
  declare const onchainReceiveRequest: (input: {
781
614
  rfqId: string;
782
615
  paymentHash: string;
@@ -819,14 +652,11 @@ declare function deriveOnchainSend(input: {
819
652
  * so the row can never key on a script other than the derived one. */
820
653
  script: InstanceType<typeof VHTLC.ScriptV2>;
821
654
  htlc: OnchainHtlc;
822
- /** The inputs {@link htlc} was built from. Returned because nothing else
823
- * can give them back: `OnchainHtlc` exposes only derived values, and this
824
- * contract is Bitcoin L1 — there is no Arkade contract row for it, so a
825
- * consumer persisting the swap has no other route to rebuilding it. */
655
+ /** The inputs {@link htlc} was built from; nothing else gives them back (L1 has no contract
656
+ * row, and `OnchainHtlc` exposes only derived values). */
826
657
  htlcParams: OnchainHtlcParams;
827
- /** Echoed from the input, so a result is a complete description of the L1
828
- * half rather than one a caller has to re-assemble from what it passed in.
829
- * {@link onchainSendProfile} reads it from here. */
658
+ /** Echoed from the input so the result fully describes the L1 half
659
+ * ({@link onchainSendProfile} reads it). */
830
660
  l1Network: OnchainNetwork;
831
661
  refundLocktime: number;
832
662
  htlcLocktime: number;
@@ -838,22 +668,15 @@ declare function deriveOnchainSend(input: {
838
668
  * quote → derive BOTH contracts locally → verify → gate. Pure of funding —
839
669
  * the caller funds `address` with its own wallet before `quote.valid_until`.
840
670
  *
841
- * Registers the arkade lockup before returning the address, on the same terms
842
- * as {@link requestLightningSend} — including {@link LockupRegistrationFailed},
843
- * the one throw here that does not mean "walk away from this quote". The L1
844
- * HTLC is not a contract row: it lives on bitcoin, not on Ark, and the wallet's
845
- * contract manager knows nothing of it.
671
+ * Registers the arkade lockup before returning, as {@link requestLightningSend} does (the L1 HTLC
672
+ * has no contract row).
846
673
  *
847
674
  * Two obligations, both LOUD:
848
- * - **Persist `secrets` (with the record) BEFORE funding.** On an HD wallet it
849
- * is a public descriptor and both the preimage and the `sender` key
850
- * re-derive from the seed; otherwise it carries the raw secrets, and losing
851
- * them forfeits the L1 claim and every interactive refund path — leaving
852
- * recovery dependent on the solver via `nonInteractiveRefund`.
853
- * - **Stay claim-capable.** Unlike lightning-send the user cannot go fully
854
- * offline: it must claim the L1 HTLC (`awaitOnchainFill` →
855
- * `claimOnchainFill`) before `htlc.refundLocktime`. Missing that window
856
- * forfeits the fill and falls back to the Arkade covenant refund.
675
+ * - **Persist `secrets` (with the record) BEFORE funding.** On a non-HD wallet it carries raw
676
+ * secrets; losing them forfeits the L1 claim and every interactive refund path.
677
+ * - **Stay claim-capable.** The user must claim the L1 HTLC (`awaitOnchainFill` →
678
+ * `claimOnchainFill`) before `htlc.refundLocktime`, or the fill is forfeit and the swap falls
679
+ * back to the Arkade covenant refund.
857
680
  */
858
681
  declare function requestOnchainSend(wallet: IWallet, transport: RfqTransport, params: {
859
682
  amount: number;
@@ -881,34 +704,18 @@ declare function requestOnchainSend(wallet: IWallet, transport: RfqTransport, pa
881
704
  refundAddress: string;
882
705
  /** The EXPECTED L1 fill, derived locally — watch and claim against this. */
883
706
  htlc: OnchainHtlc;
884
- /** The inputs {@link htlc} was built from — persist these to rebuild it
885
- * after a restart. Nothing else gives them back: `OnchainHtlc` exposes only
886
- * derived values, and this contract is Bitcoin L1, so unlike the arkade
887
- * lockup there is no contract row holding its parameters. Persist
888
- * `htlc.address` alongside them (`OnchainSendProfile.htlcAddress`): the
889
- * rebuild checks the two against each other, which is the only check
890
- * available on a leg with no second copy of its covenant.
891
- *
892
- * `onchainSendProfile(result)` does all of that mapping for you; prefer it
893
- * to reading these fields across by hand. */
707
+ /** The inputs {@link htlc} was built from — persist these (with `htlc.address`) to rebuild it
708
+ * after a restart; nothing else gives them back. Prefer `onchainSendProfile(result)` to
709
+ * mapping them by hand. */
894
710
  htlcParams: OnchainHtlcParams;
895
- /**
896
- * Which bitcoin network the L1 HTLC was derived for.
897
- *
898
- * Returned because it is NOT the ark network name and cannot be recovered
899
- * from one by inspection: this call maps `info.network` through a private
900
- * narrowing where signet, mutinynet and testnet4 all become `"testnet"`.
901
- * A caller reconstructing it from context would be re-deriving a mapping
902
- * it cannot see, and a value the profile needs verbatim.
903
- */
711
+ /** Which bitcoin network the L1 HTLC was derived for. NOT the ark network name: signet,
712
+ * mutinynet and testnet4 all become `"testnet"`. */
904
713
  l1Network: OnchainNetwork;
905
714
  /** `profile.min_confirmations`; gates when the L1 fill becomes claimable,
906
715
  * and part of what a restored swap needs to drive its own claim. */
907
716
  minConfirmations: number;
908
- /** The arkade lockup's refund deadline, as the covenant was built with it.
909
- * Read this rather than `quote.refund_locktime`: that field is optional on
910
- * the wire, a solver may carry the value in `profile` instead, and
911
- * `deriveOnchainSend` is what settles which one this contract used. */
717
+ /** The arkade lockup's refund deadline, as the covenant was built with it. Read this, not
718
+ * `quote.refund_locktime`: a solver may carry the value in `profile` instead. */
912
719
  refundLocktime: number;
913
720
  /** The VHTLC `sender` x-only key, bound into the covenant. Public. */
914
721
  senderPubkey: Uint8Array;
@@ -920,18 +727,13 @@ declare function requestOnchainSend(wallet: IWallet, transport: RfqTransport, pa
920
727
  /**
921
728
  * Bind the SOLVER's hold invoice to the quote and to the trader's own `H`.
922
729
  *
923
- * This is the only field the trader hands to a third party, and the only
924
- * attack on this corridor with no on-chain trace: an invoice on some other
925
- * payment hash is paid to the solver in full and no lockup on `H` is ever
926
- * funded. NEVER publish an invoice that has not passed this.
927
- *
928
- * The decoder is injected — `@arkade-os/swap` takes no BOLT11 dependency — but
929
- * unlike {@link requestLightningSend}, which takes the caller's facts about
930
- * the caller's OWN invoice, the comparison lives here: a caller-supplied
931
- * summary of an adversary's invoice checks nothing.
730
+ * The only attack on this corridor with no on-chain trace: an invoice on another payment hash is
731
+ * paid to the solver in full and no lockup on `H` is ever funded. NEVER publish an invoice that
732
+ * has not passed this.
932
733
  *
933
- * There is no check for "is this actually a hold invoice": on the wire it is
934
- * indistinguishable from an ordinary one.
734
+ * The decoder is injected (no BOLT11 dependency), but the comparison lives here: a caller-supplied
735
+ * summary of an adversary's invoice checks nothing. A hold invoice is indistinguishable on the
736
+ * wire, so that is not checked.
935
737
  *
936
738
  * Reasons: `invoice_undecodable` | `invoice_hash_mismatch` |
937
739
  * `invoice_amount_mismatch` | `quote_malformed`.
@@ -950,9 +752,8 @@ declare const verifyReceiveInvoice: (input: {
950
752
  /** Compile the RECEIVE-direction VHTLC: the same suite-carrying tree as {@link
951
753
  * lightningSendContract} with the roles inverted — the trader is the
952
754
  * `receiver` (it generated `P` and claims the lockup with it), the solver is
953
- * the `sender` (it funds the lockup and holds the refund recourse). One
954
- * function shared by both receive corridors, mirroring the send legs' sharing
955
- * of `lightningSendContract`.
755
+ * the `sender` (it funds the lockup and holds the refund recourse). Shared by both receive
756
+ * corridors.
956
757
  *
957
758
  * @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
958
759
  */
@@ -963,7 +764,7 @@ declare function lightningReceiveContract(params: {
963
764
  /** Binding field #2: the SOLVER's own refund deadline on these legs, from
964
765
  * the quote — after it the solver may reclaim an unclaimed lockup. */
965
766
  refundLocktime: number;
966
- /** The Ark server's x-only key — the trader's OWN connection. */
767
+ /** The Arkade operator's x-only key — the trader's OWN connection. */
967
768
  operatorPubkey: Uint8Array;
968
769
  /** `sha256(P)`, hex — the trader's OWN preimage hash. */
969
770
  paymentHash: string;
@@ -993,10 +794,8 @@ type LightningReceiveContractParams = Parameters<typeof lightningReceiveContract
993
794
  /**
994
795
  * The pure core of {@link requestLightningReceive}: derive the solver-funded
995
796
  * covenant locally from the quote's binding fields plus the trader's own data
996
- * and refuse on any address mismatch. The trader funds nothing on Arkade on
997
- * this leg — verification is still what makes paying the hold invoice safe:
998
- * the lockup the solver will fund must be the tree whose claim paths pay the
999
- * trader.
797
+ * and refuse on any address mismatch. The trader funds nothing on Arkade here, but this is what
798
+ * makes paying the hold invoice safe: the lockup must be a tree whose claim paths pay the trader.
1000
799
  */
1001
800
  declare function deriveLightningReceive(input: {
1002
801
  quote: RfqQuote;
@@ -1014,40 +813,23 @@ declare function deriveLightningReceive(input: {
1014
813
  /** The solver's hold invoice on `H` — what the trader pays to arm the swap. */
1015
814
  invoice: string;
1016
815
  refundLocktime: number;
1017
- /** Every input the covenant was built from — see the same field on
1018
- * `requestLightningSend`'s result for why a consumer needs them. */
816
+ /** Every input the covenant was built from; see `requestLightningSend`'s result. */
1019
817
  contractParams: LightningReceiveContractParams;
1020
818
  };
1021
819
  /**
1022
- * The `lightning:BTC->arkade:BTC` user flow: quote → derive the covenant
1023
- * locally → verify → gate. Returns the solver's hold invoice to PAY — the
1024
- * payment itself is the trader's own Lightning wallet's job, exactly as
1025
- * funding is the caller's job on the send corridors. Once the paid HTLC is
1026
- * held, the solver funds the lockup; the trader claims it with `P` (its own,
1027
- * generated here) — itself via the collaborative claim leaf
1028
- * ({@link claimReceiveLockup} in `claim.ts`), or via covclaimd if it is
1029
- * offline.
820
+ * The `lightning:BTC->arkade:BTC` user flow: quote → derive the covenant locally → verify → gate.
821
+ * Returns the solver's hold invoice (already checked by {@link verifyReceiveInvoice}) for the
822
+ * trader's own Lightning wallet to PAY before `invoiceExpiresAt`. Once the HTLC is held the solver
823
+ * funds the lockup and the trader claims it with its own `P` ({@link claimReceiveLockup}).
1030
824
  *
1031
- * Three obligations, all of them before the invoice is handed to a payer:
825
+ * Three obligations, all before the invoice is handed to a payer:
1032
826
  *
1033
- * 1. Persist `secrets` and `expectedAmount`. The preimage and the payout key
1034
- * re-derive from `secrets` (or, on a non-HD wallet, are carried by it), and
1035
- * without `expectedAmount` the claim has nothing to compare the funded
1036
- * value against.
1037
- * 2. Stay online. covclaimd cannot claim this covenant today, so the offline
1038
- * path the claim packet exists for does not run yet: an unclaimed lockup is
1039
- * reclaimed by the solver at `refund_locktime` and the payer refunded.
1040
- * 3. On {@link LockupRegistrationFailed}, call this function again once the
1041
- * store is working. The failed attempt is inert — it returned no invoice,
1042
- * so nothing can be paid into the lockup nobody is watching — and the new
1043
- * call derives its own preimage and `rfq_id`. Re-registering `error.script`
1044
- * does NOT resume it: the invoice and `secrets` were never handed back.
1045
- *
1046
- * The invoice is the solver's, so it is verified here against the trader's own
1047
- * `H` and the quote ({@link verifyReceiveInvoice}) before it is returned —
1048
- * nothing publishable comes back from a failed check, registration included.
1049
- * Pay before `invoiceExpiresAt`: the hold-invoice window is minutes, not the
1050
- * quote's `valid_until`.
827
+ * 1. Persist `secrets` and `expectedAmount`; without the latter the claim cannot check the funded
828
+ * value.
829
+ * 2. Stay online. covclaimd cannot claim this covenant today, so an unclaimed lockup is reclaimed
830
+ * by the solver at `refund_locktime` and the payer refunded.
831
+ * 3. On {@link LockupRegistrationFailed}, call this again once the store works. The failed attempt
832
+ * is inert (no invoice was returned); re-registering `error.script` does NOT resume it.
1051
833
  */
1052
834
  declare function requestLightningReceive(wallet: IWallet, transport: RfqTransport, params: {
1053
835
  amount: number;
@@ -1055,16 +837,12 @@ declare function requestLightningReceive(wallet: IWallet, transport: RfqTranspor
1055
837
  /** Co-signer key override (33-byte compressed hex); see
1056
838
  * {@link resolveEmulatorPubkey}. */
1057
839
  emulatorPubkey?: string;
1058
- /** covclaimd's 33-byte compressed pubkey (from its own info endpoint)
1059
- * — the claim packet seals to it and only it can ever read `P` early.
1060
- * Unset where no covclaimd is deployed: nothing is sealed, no packet is
1061
- * sent, and claiming the lockup before the quote's `refund_locktime` is
1062
- * then the caller's own job — miss that window and the fill is lost.
1063
- * Never substitute a throwaway key — nobody could open it. */
840
+ /** covclaimd's 33-byte compressed pubkey; the claim packet seals `P` to it. Unset where
841
+ * none is deployed: nothing is sent, and claiming before `refund_locktime` is the caller's
842
+ * job. Never substitute a throwaway key — nobody could open it. */
1064
843
  covclaimdPubkey?: Uint8Array;
1065
- /** The caller's own BOLT11 decoder, applied to the SOLVER's invoice.
1066
- * Required: an optional verifier is one integrators skip, and this is
1067
- * the check whose absence loses the whole payment. */
844
+ /** The caller's own BOLT11 decoder, applied to the SOLVER's invoice. Required: skipping
845
+ * this check can lose the whole payment. */
1068
846
  decodeInvoice: (bolt11: string) => InvoiceFacts;
1069
847
  /** Opt-in ceiling, in sats, on what the payer will be asked for. */
1070
848
  maxPayAmount?: number;
@@ -1077,13 +855,11 @@ declare function requestLightningReceive(wallet: IWallet, transport: RfqTranspor
1077
855
  invoice: string;
1078
856
  /** What the trader pays: the quote's `from_amount`. */
1079
857
  payAmount: number;
1080
- /** What the solver's lockup must carry: the quote's `to_amount`. Persist
1081
- * it with the record — `pushClaim` refuses to publish `P` for less, and
1082
- * captured at claim time instead it would be whatever the solver funded. */
858
+ /** What the solver's lockup must carry: the quote's `to_amount`. Persist it with the record:
859
+ * `pushClaim` refuses to publish `P` for less. */
1083
860
  expectedAmount: number;
1084
861
  /** Last moment the invoice can be paid, unix seconds: `min(invoice
1085
- * expiry, valid_until)`. Absolute on purpose — a countdown returned from
1086
- * here is stale before the caller reads it; derive one at display time. */
862
+ * expiry, valid_until)`. */
1087
863
  invoiceExpiresAt: number;
1088
864
  /** The trader's OWN derivation of the lockup the solver must fund. */
1089
865
  address: string;
@@ -1131,16 +907,12 @@ declare function deriveOnchainReceive(input: {
1131
907
  };
1132
908
  /**
1133
909
  * The `onchain:BTC->arkade:BTC` user flow: quote → derive BOTH contracts
1134
- * locally → verify → gate. Returns the L1 HTLC to fund (`htlc.address`, for
1135
- * `fundAmount`) — the funding transaction itself is the trader's own L1
1136
- * wallet's job, exactly as on the send corridors. After `min_confirmations`
1137
- * the solver funds the Arkade lockup; the trader claims it with `P` (its
1138
- * own), itself or via covclaimd.
910
+ * locally → verify → gate. Returns the L1 HTLC for the trader's own L1 wallet to fund with
911
+ * `fundAmount`. After `min_confirmations` the solver funds the Arkade lockup; the trader claims it
912
+ * with `P`.
1139
913
  *
1140
- * Persist `secrets` BEFORE funding, and note the direction's own deadline:
1141
- * if the swap never settles, the L1 HTLC's refund leaf (the trader's
1142
- * `refundPubkey`) opens at `htlc.refundLocktime` — `buildHtlcRefund` takes it
1143
- * back from there.
914
+ * Persist `secrets` BEFORE funding. If the swap never settles, the L1 refund leaf opens at
915
+ * `htlc.refundLocktime` (see `buildHtlcRefund`).
1144
916
  */
1145
917
  declare function requestOnchainReceive(wallet: IWallet, transport: RfqTransport, params: {
1146
918
  amount: number;
@@ -1150,9 +922,7 @@ declare function requestOnchainReceive(wallet: IWallet, transport: RfqTransport,
1150
922
  emulatorPubkey?: string;
1151
923
  /** Trader's x-only L1 key for the HTLC's refund leaf. */
1152
924
  refundPubkey: Uint8Array;
1153
- /** covclaimd's 33-byte compressed pubkey, unset where none is deployed
1154
- * — nothing is sealed and the claim before `refund_locktime` is the
1155
- * caller's own; see {@link requestLightningReceive}. */
925
+ /** covclaimd's 33-byte compressed pubkey; see {@link requestLightningReceive}. */
1156
926
  covclaimdPubkey?: Uint8Array;
1157
927
  rfqId?: string;
1158
928
  }): Promise<{