@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
@@ -0,0 +1,983 @@
1
+ import { VHTLC, IWallet, ProvisionedKey, ProvisionedClaimSecret, asset } from '@arkade-os/sdk';
2
+
3
+ /** L1 confirmation-depth and reorg margin between dependent timelocks. */
4
+ declare const ONCHAIN_ORDER_MARGIN_SECONDS: number;
5
+ /** Don't broadcast a claim with less than this before the refund leaf opens:
6
+ * MTP lag plus confirmation time. Past this point the safe move is to let the
7
+ * swap die and take the covenant refund — claiming into the counterparty's
8
+ * live refund window risks losing the race AND publishing P. */
9
+ declare const ONCHAIN_CLAIM_MARGIN_SECONDS: number;
10
+ /** Bounds on the confirmation depth a quote may demand. */
11
+ declare const MAX_MIN_CONFIRMATIONS = 6;
12
+ /**
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).
15
+ */
16
+ declare const LOCKTIME_THRESHOLD = 500000000;
17
+ /** Conservative block interval for converting depths into wall-clock time. */
18
+ declare const ONCHAIN_SECONDS_PER_BLOCK = 600;
19
+ /**
20
+ * Outputs below this are unspendable in practice; builders refuse them.
21
+ *
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.
26
+ */
27
+ declare const ONCHAIN_DUST_SATS: bigint;
28
+ /** 32 random bytes. The user generates P for BOTH onchain directions. */
29
+ declare const newPreimage: () => Uint8Array;
30
+ /** `sha256(P)`, hex — the wire `payment_hash`, same convention as BOLT11. */
31
+ declare const paymentHashOf: (preimage: Uint8Array) => string;
32
+ type OnchainNetwork = "bitcoin" | "testnet" | "regtest";
33
+ /**
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.
37
+ */
38
+ declare const l1ScriptForAddress: (address: string, network: OnchainNetwork) => Uint8Array;
39
+ interface OnchainHtlcParams {
40
+ /** `sha256(P)`, hex; the HASH160 commitment is derived internally. */
41
+ paymentHash: string;
42
+ /** x-only key that claims with the preimage. */
43
+ claimKey: Uint8Array;
44
+ /** x-only key that refunds after the locktime. */
45
+ refundKey: Uint8Array;
46
+ /** Absolute unix seconds (consensus matures it against median-time-past). */
47
+ refundLocktime: number;
48
+ }
49
+ interface OnchainHtlc {
50
+ address: string;
51
+ /** `0x5120…` — the P2TR output script. */
52
+ pkScript: Uint8Array;
53
+ leaves: {
54
+ claim: Uint8Array;
55
+ refund: Uint8Array;
56
+ };
57
+ /** Serialized control blocks per leaf, ready for a script-path witness. */
58
+ controlBlocks: {
59
+ claim: Uint8Array;
60
+ refund: Uint8Array;
61
+ };
62
+ paymentHash: string;
63
+ refundLocktime: number;
64
+ }
65
+ /**
66
+ * Derive the two-leaf taproot HTLC. Internal key is the BIP-341 NUMS point, so
67
+ * there is no key-path spend, ever:
68
+ *
69
+ * claim: `OP_SIZE 32 OP_EQUALVERIFY OP_HASH160 <h160> OP_EQUALVERIFY <claimKey> OP_CHECKSIG`
70
+ * refund: `<locktime> OP_CHECKLOCKTIMEVERIFY OP_DROP <refundKey> OP_CHECKSIG`
71
+ *
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.
74
+ */
75
+ declare function onchainHtlcScript(params: OnchainHtlcParams, network: OnchainNetwork): OnchainHtlc;
76
+ interface HtlcUtxo {
77
+ txid: string;
78
+ vout: number;
79
+ amount: bigint;
80
+ }
81
+ interface SpendResult {
82
+ txHex: string;
83
+ txid: string;
84
+ /** `utxo.amount − fee` — what actually lands at the payout script. */
85
+ payoutAmount: bigint;
86
+ }
87
+ /** Script-path spend of the claim leaf; the witness reveals P — that is how
88
+ * the counterparty learns it, so never build this unless the claim will win
89
+ * (see {@link claimOnchainFill}). `sign` is BIP340 over the claim key. */
90
+ declare const buildHtlcClaim: (input: {
91
+ htlc: OnchainHtlc;
92
+ utxo: HtlcUtxo;
93
+ preimage: Uint8Array;
94
+ payoutPkScript: Uint8Array;
95
+ feeRateSatVb: number;
96
+ sign: (sighash: Uint8Array) => Promise<Uint8Array>;
97
+ }) => Promise<SpendResult>;
98
+ /** Script-path spend of the refund leaf; consensus-valid only once nLockTime
99
+ * has matured against median-time-past — gate on {@link ChainSource.getMtp},
100
+ * not wall clock. `sign` is BIP340 over the refund key. */
101
+ declare const buildHtlcRefund: (input: {
102
+ htlc: OnchainHtlc;
103
+ utxo: HtlcUtxo;
104
+ payoutPkScript: Uint8Array;
105
+ feeRateSatVb: number;
106
+ sign: (sighash: Uint8Array) => Promise<Uint8Array>;
107
+ }) => Promise<SpendResult>;
108
+ interface ChainUtxo extends HtlcUtxo {
109
+ confirmations: number;
110
+ }
111
+ /** `missing`: the chain knows no such transaction. A source that cannot tell says `unconfirmed`. */
112
+ type TxStatus = "confirmed" | "unconfirmed" | "missing";
113
+ /** The package's whole view of Bitcoin L1, injected so the package stays backend-free
114
+ * (`CorridorOverrides.onchain.chain` takes it). */
115
+ interface ChainSource {
116
+ /** Confirmed+mempool outputs paying a script; used to detect the fill. */
117
+ getScriptUtxos(pkScript: Uint8Array): Promise<ChainUtxo[]>;
118
+ /**
119
+ * The spend of an outpoint, if any — where P is extracted from. A provider
120
+ * omitting the spender txid still lists it in `pkScript`'s history.
121
+ *
122
+ * **`txHex` MUST carry the witness**: a legacy serialization parses
123
+ * cleanly without one, so a stripped claim classifies as `swept`. */
124
+ getSpendingTx(txid: string, vout: number, pkScript: Uint8Array): Promise<{
125
+ txHex: string;
126
+ } | null>;
127
+ broadcast(txHex: string): Promise<string>;
128
+ /** Current median-time-past, unix seconds — gates refund broadcasting. */
129
+ getMtp(): Promise<number>;
130
+ /** Where `txid` stands; throws when the chain cannot answer.
131
+ * **Optional, and an `arkade -> onchain` payout turns on it**: without it a mempool
132
+ * claim reads as a mined one, so such a swap still settles on the solver's Arkade
133
+ * claim alone — which its refund, replacing the claim, turns into a loss of both. */
134
+ getTxStatus?(txid: string): Promise<TxStatus>;
135
+ /** Current fee estimate, sat/vB. Optional. */
136
+ getFeeRate?(): Promise<number | undefined>;
137
+ }
138
+ /** Read P out of a claim spend's witness: the 32-byte item whose sha256 is the
139
+ * payment hash. Null when the tx reveals no matching preimage (e.g. a refund
140
+ * spend, or an unrelated tx). */
141
+ declare function extractPreimage(txHex: string, paymentHash: string): Uint8Array | null;
142
+ /** Poll {@link ChainSource} until the HTLC is funded to the required depth.
143
+ * Picks the largest qualifying output when several exist. Throws (reason
144
+ * `fill_timeout`) once `deadline` (unix seconds) passes without one. */
145
+ declare function awaitOnchainFill(chain: ChainSource, htlc: OnchainHtlc, minConfirmations: number, options?: {
146
+ pollMs?: number;
147
+ deadline?: number;
148
+ }): Promise<ChainUtxo>;
149
+ /**
150
+ * Claim the fill: build the claim spend and broadcast it, publishing P (that is how the solver
151
+ * gets paid). Refuses (`claim_window_closed`) with less than {@link ONCHAIN_CLAIM_MARGIN_SECONDS}
152
+ * before the refund leaf opens.
153
+ */
154
+ declare function claimOnchainFill(chain: ChainSource, input: {
155
+ htlc: OnchainHtlc;
156
+ utxo: HtlcUtxo;
157
+ preimage: Uint8Array;
158
+ payoutPkScript: Uint8Array;
159
+ feeRateSatVb: number;
160
+ sign: (sighash: Uint8Array) => Promise<Uint8Array>;
161
+ /** Injected for tests; defaults to wall clock. */
162
+ now?: number;
163
+ /** Re-publish a claim whose `P` is already public: the margin gate protects the
164
+ * preimage, and the refund leaf opening is when a replacement matters most. */
165
+ republish?: boolean;
166
+ }): Promise<{
167
+ txid: string;
168
+ payoutAmount: bigint;
169
+ }>;
170
+ /** Where an onchain HTLC stands, for crash recovery. Persisting the record BEFORE funding is what
171
+ * makes this classification (and the claim) possible after a restart. Each phase names which leaf
172
+ * moved, never whose turn it is: the key roles swap between the legs (module header). */
173
+ type OnchainHtlcPhase = {
174
+ phase: "unfunded";
175
+ } | {
176
+ phase: "awaiting_confirmations";
177
+ utxo: ChainUtxo;
178
+ } | {
179
+ phase: "claimable";
180
+ utxo: ChainUtxo;
181
+ }
182
+ /**
183
+ * The refund leaf has matured. On `arkade->onchain` it is the SOLVER's leaf: the CLAIM WINDOW
184
+ * IS CLOSED and `claimOnchainFill` throws, so do not claim; take the Arkade-side covenant
185
+ * refund instead (on a swap you expected to claim, the claim was missed). On
186
+ * `onchain->arkade` it is the TRADER's own leaf: the act-now signal to refund, and it stays
187
+ * spendable.
188
+ */
189
+ | {
190
+ phase: "refundable";
191
+ utxo: ChainUtxo;
192
+ } | {
193
+ phase: "claimed";
194
+ txid: string;
195
+ preimage: Uint8Array;
196
+ } | {
197
+ phase: "swept";
198
+ txid: string;
199
+ };
200
+ /**
201
+ * Classify an HTLC from chain state alone. `funding` (the known outpoint from
202
+ * the stored record) is what distinguishes "never funded" from "funded and
203
+ * already spent": without it a spent HTLC looks unfunded.
204
+ *
205
+ * `claimed` carries the preimage read from the spend's witness — the receipt;
206
+ * `swept` is a spend that reveals no matching preimage.
207
+ */
208
+ declare function classifyOnchainHtlc(chain: ChainSource, input: {
209
+ htlc: OnchainHtlc;
210
+ minConfirmations: number;
211
+ funding?: {
212
+ txid: string;
213
+ vout: number;
214
+ };
215
+ }): Promise<OnchainHtlcPhase>;
216
+
217
+ /** Legs are `<corridor>:<asset>`; a pair is directional, `from->to`. */
218
+ declare const ARKADE_BTC = "arkade:BTC";
219
+ declare const LIGHTNING_BTC = "lightning:BTC";
220
+ declare const ONCHAIN_BTC = "onchain:BTC";
221
+ /** The arkade leg for an asset: the asset id itself, 68 lowercase hex, in the pair because the
222
+ * pair is what both sides route and subscribe on.
223
+ *
224
+ * Takes an `AssetId`, not a string, to enforce lowercase (`hex.decode` accepts uppercase,
225
+ * `toString()` emits lowercase): solvers compare pair strings byte for byte, so `A1B2…` would be
226
+ * skipped as an unserved pair. */
227
+ declare const arkadeAssetLeg: (id: asset.AssetId) => string;
228
+ /** The implemented pair: pay a BOLT11 invoice out of an Arkade balance. */
229
+ declare const LIGHTNING_SEND_PAIR: string;
230
+ /** On-board via Lightning: pay the solver's hold invoice, land on Arkade. */
231
+ declare const LIGHTNING_RECEIVE_PAIR: string;
232
+ declare const ONCHAIN_SEND_PAIR: string;
233
+ /** On-board: a Bitcoin-L1 HTLC in, Arkade sats out. */
234
+ declare const ONCHAIN_RECEIVE_PAIR: string;
235
+ /** The closed refusal set. Treat any unknown reason as a generic decline. */
236
+ type RfqRefusalReason = "unsupported_pair" | "unsupported_payload" | "amount_out_of_range" | "exposure_cap" | "invoice_expired" | "quote_conflict" | "pricing_unavailable" | "rate_limited";
237
+ 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"];
238
+ type RfqRefusalErrorCode = (typeof RFQ_REFUSAL_ERROR_CODES)[number];
239
+ type RfqRefusalUnit = "blocks" | "characters" | "sats";
240
+ interface RfqRefusalDetail {
241
+ errorCode?: RfqRefusalErrorCode;
242
+ field?: string;
243
+ actual?: number;
244
+ expected?: number;
245
+ limit?: number;
246
+ unit?: RfqRefusalUnit;
247
+ }
248
+ declare const isRfqRefusalErrorCode: (value: unknown) => value is RfqRefusalErrorCode;
249
+ /** A refusal from the solver, carrying its closed-set reason. */
250
+ declare class SwapRefusal extends Error {
251
+ /** Literal-typed so the v2 error taxonomy's union discriminates on `name`
252
+ * — a `string` here collapses the discriminant for every member. */
253
+ readonly name = "SwapRefusal";
254
+ readonly reason: string;
255
+ readonly rfqId: string | undefined;
256
+ readonly errorCode: RfqRefusalErrorCode | undefined;
257
+ readonly field: string | undefined;
258
+ readonly actual: number | undefined;
259
+ readonly expected: number | undefined;
260
+ readonly limit: number | undefined;
261
+ readonly unit: RfqRefusalUnit | undefined;
262
+ constructor(reason: string, rfqId?: string, detail?: RfqRefusalDetail);
263
+ }
264
+ /**
265
+ * The solver's address does not match the local derivation. NEVER fund past
266
+ * this. `derived` is every candidate address tried — more than one when the
267
+ * derivation itself is ambiguous, see {@link verifyLockupAddress}.
268
+ */
269
+ declare class AddressMismatch extends Error {
270
+ readonly derived: string | string[];
271
+ readonly quoted: string | undefined;
272
+ constructor(derived: string | string[], quoted?: string);
273
+ }
274
+ interface RfqQuote {
275
+ v: 1;
276
+ type: "rfq_quote";
277
+ rfq_id: string;
278
+ pair: string;
279
+ /** Sats on HTLC-class corridors (number); canonical decimal string on
280
+ * arkade↔arkade asset legs (bigint range, see WIRE_ASSET_AMOUNT on the
281
+ * solver). */
282
+ from_amount: number | string;
283
+ to_amount: number | string;
284
+ /** Dust an asset deposit rides on, kept by the filler. Expected back in `to_amount`; the
285
+ * client counts any shortfall as fee. */
286
+ carrier_sats?: number | string;
287
+ solver_pubkey: string;
288
+ valid_until: number;
289
+ /** HTLC-class quotes only; absent for arkade↔arkade. */
290
+ refund_locktime?: number;
291
+ profile: {
292
+ [key: string]: unknown;
293
+ payment_hash?: string;
294
+ lockup_address?: string;
295
+ refund_without_receiver_delay?: number;
296
+ offer_address?: string;
297
+ offer_pk_script?: string;
298
+ };
299
+ [key: string]: unknown;
300
+ }
301
+ interface RfqStatus {
302
+ v: 1;
303
+ type: "rfq_status";
304
+ rfq_id: string;
305
+ state: string;
306
+ updated_at: number;
307
+ profile: Record<string, unknown>;
308
+ [key: string]: unknown;
309
+ }
310
+ /** The rfq_request for the lightning send profile. BOLT11 is exact-out: the invoice fixes the
311
+ * amount. `senderPubkey` is the trader's key for the VHTLC's sender-side leaves (see
312
+ * {@link lightningSendContract}), sent as `client_refund_pubkey`; the solver's schema
313
+ * (https://docs.arkadeos.com/intents/reference/rfq) is `.strict()`, so a wrong or missing name
314
+ * refuses every request.
315
+ */
316
+ declare const lightningSendRequest: (input: {
317
+ rfqId: string;
318
+ invoice: string;
319
+ refundAddress: string;
320
+ senderPubkey: Uint8Array;
321
+ }) => Record<string, unknown>;
322
+ /** The rfq_request for an arkade↔arkade swap. At least one side names an asset
323
+ * id (BTC has none), and the id is the leg itself — see
324
+ * {@link arkadeAssetLeg}.
325
+ *
326
+ * Matches the reference solver's strict `AssetRfqRequest`: `amount` is a canonical decimal string
327
+ * of atomic units (never a JSON number: an asset's precision is unknowable client-side), and
328
+ * `amount_side` is `"from"` or `"to"`, and `profile` carries the trader's covenant position — the fill pays `maker_pk_script`, and `cancel`
329
+ * is signed by `maker_public_key`. */
330
+ declare const arkadeSwapRequest: (input: {
331
+ rfqId: string;
332
+ /** Asset the trader deposits; omit when depositing BTC. */
333
+ offerAsset?: asset.AssetId;
334
+ /** Asset the trader wants; omit when wanting BTC. */
335
+ wantAsset?: asset.AssetId;
336
+ amountSide?: "from" | "to";
337
+ /** Atomic units of the deposit (`from`) leg. bigint-safe: encoded as a
338
+ * canonical decimal string on the wire. */
339
+ amount: bigint | number | string;
340
+ /** Trader's own taproot scriptPubKey (34 bytes, `OP_1 <32-byte program>`),
341
+ * as bytes or lowercase hex. The covenant's `makerWP` minus its prefix. */
342
+ makerPkScript: Uint8Array | string;
343
+ /** Trader's own x-only key (32 bytes), as bytes or lowercase hex. The
344
+ * `cancel` path's `user` signer. */
345
+ makerPublicKey: Uint8Array | string;
346
+ }) => Record<string, unknown>;
347
+ /** Canonical decimal string of atomic units: ASCII digits, no sign, point,
348
+ * exponent, or leading zero (unless the value is exactly "0"). bigint passes
349
+ * through; number must be a safe integer; string must already be canonical.
350
+ *
351
+ * @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`. */
352
+ declare const canonicalAssetAmount: (amount: bigint | number | string) => string;
353
+ /** 34-byte taproot scriptPubKey (`OP_1 <32-byte program>`), lowercase hex.
354
+ *
355
+ * @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`. */
356
+ declare const normalizeMakerPkScript: (value: Uint8Array | string) => string;
357
+ /** 32-byte x-only key, lowercase hex. Never a 33-byte compressed key.
358
+ *
359
+ * @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`. */
360
+ declare const normalizeMakerPublicKey: (value: Uint8Array | string) => string;
361
+ /**
362
+ * Compare-only check of the solver's address against YOUR OWN derivation(s)
363
+ * — never extends trust, only narrows it.
364
+ *
365
+ * Pass an array when your derivation is ambiguous, as for covenant lockups while solvers roll out
366
+ * the timelocked non-interactive refund leaf (nothing on the wire says which shape a quote uses).
367
+ * No security is lost: every candidate pins the refund to the trader's own destination.
368
+ *
369
+ * @returns the address that matched.
370
+ * @throws {AddressMismatch} only when NONE of the candidates match.
371
+ */
372
+ declare const verifyLockupAddress: (quote: RfqQuote, derivedAddress: string | string[]) => string;
373
+ interface RfqTransport {
374
+ requestQuote(payload: Record<string, unknown>): Promise<RfqQuote>;
375
+ status(rfqId: string): Promise<RfqStatus | null>;
376
+ close(): Promise<void>;
377
+ }
378
+ /** HTTP: POST /v1/swap for quotes, GET /v1/rfq/<rfq_id> for status.
379
+ * `fetchImpl` is injectable for tests and non-global-fetch runtimes. */
380
+ declare const httpTransport: (baseUrl: string, options?: {
381
+ fetchImpl?: typeof fetch;
382
+ }) => RfqTransport;
383
+ /** Minimal WebSocket surface the relay transport needs — satisfied by the DOM
384
+ * WebSocket and by `ws` alike, so neither becomes a dependency. */
385
+ interface RelaySocket {
386
+ send(data: string): void;
387
+ close(): void;
388
+ addEventListener(type: "open" | "message" | "error", listener: (event: any) => void): void;
389
+ }
390
+ /** Relay: both parties outbound, addressed by x-only pubkey, speaking the dev
391
+ * broker framing. Nostr (directed kind + NIP-44) replaces only this function.
392
+ * One socket; replies correlated by rfq_id. */
393
+ declare const relayTransport: (relayUrl: string, options: {
394
+ solverPubkey: string;
395
+ clientPubkey: string;
396
+ WebSocketCtor?: new (url: string) => RelaySocket;
397
+ timeoutMs?: number;
398
+ }) => RfqTransport;
399
+ /** The solver's unilateral-claim delay, derived from the Arkade operator's reported
400
+ * exit delay exactly as the reference solver derives it — both sides read the
401
+ * SAME server, so the derivation (not a quote field) is what keeps the two
402
+ * scripts identical. */
403
+ declare const unilateralClaimDelay: (operatorExitDelaySeconds: number) => number;
404
+ /** VHTLC's `unilateralRefund` tier: sender + receiver, no server — LEVEL with
405
+ * `claimDelay`, not above it. Neither party can spend a two-signature leaf
406
+ * alone, so separating it buys no safety and would only eat into the headroom that matters. */
407
+ declare const unilateralRefundDelay: (claimDelay: number) => number;
408
+ /** VHTLC's `unilateralRefundWithoutReceiver` tier: sender alone, needing
409
+ * nobody. The only leaf whose timing can steal — a funder able to refund
410
+ * before the claimant can claim takes money from someone holding the preimage
411
+ * — so it opens last, by {@link SOLO_REFUND_HEADROOM_SECONDS}. */
412
+ declare const unilateralRefundWithoutReceiverDelay: (claimDelay: number) => number;
413
+ /** Compile the lightning-send VHTLC from the quote's binding fields plus the
414
+ * trader's own data. `paymentHash` is the BOLT11 payment hash (`sha256(P)`,
415
+ * hex); the script's HASH160 commitment is derived from it here, which is why
416
+ * the trader never needs to see `P`.
417
+ *
418
+ * Nine leaves unless `legacy`: VHTLC's six plus the emulator-covenant suite —
419
+ * `nonInteractiveClaim` (server + emulator, pays the solver's `receiverPkScript`),
420
+ * `nonInteractiveRefund` (server + solver + emulator, pays the trader's `refundPkScript`, no
421
+ * timelock or trader signature; see {@link VHTLC.Options.nonInteractiveParameters}), and
422
+ * `nonInteractiveRefundWithoutReceiver` (server + emulator after `refundLocktime`).
423
+ */
424
+ declare function lightningSendContract(params: {
425
+ /** Binding field #1: the solver's x-only key, from the quote. */
426
+ solverPubkey: Uint8Array;
427
+ /** Binding field #2: when the trader's refund path opens, from the quote. */
428
+ refundLocktime: number;
429
+ /** The Arkade operator's x-only key — the trader's OWN connection. */
430
+ operatorPubkey: Uint8Array;
431
+ /** BOLT11 payment hash, hex — from the trader's OWN invoice decode. */
432
+ paymentHash: string;
433
+ /** From {@link unilateralClaimDelay} over the trader's OWN server info; all three unilateral
434
+ * tiers derive from it. */
435
+ claimDelay: number;
436
+ /** Binding quote field. Optional only for rebuilding pre-upgrade scripts. */
437
+ refundWithoutReceiverDelay?: number;
438
+ /** Emulator x-only key (32 bytes). */
439
+ emulatorPubkey: Uint8Array;
440
+ /** Where a refund must pay: the trader's P2TR pkScript (34 bytes). Also
441
+ * the refund covenants' destination. */
442
+ refundPkScript: Uint8Array;
443
+ /** The trader's own key — VHTLC's `sender` role, on every interactive refund-side leaf. */
444
+ senderPubkey: Uint8Array;
445
+ /** The solver's claim destination (`profile.receiver_pk_script`, P2TR), used only to derive
446
+ * `nonInteractiveClaim`'s covenant key; not otherwise trusted. */
447
+ receiverPkScript: Uint8Array;
448
+ /** LEGACY REBUILD ONLY: re-derive a lockup funded before the timelocked refund leaf shipped
449
+ * (see {@link VHTLC.Options.nonInteractiveParameters}); set by {@link matchQuotedLockup}. */
450
+ legacy?: "preTimelockedRefund";
451
+ }): InstanceType<typeof VHTLC.ScriptV2>;
452
+ /** Every input {@link lightningSendContract} builds from. */
453
+ type LightningSendContractParams = Parameters<typeof lightningSendContract>[0];
454
+ /** The BOLT11 facts the trader read from its OWN decode — this module takes
455
+ * the facts, not the decoder, so any wallet's existing decoder serves
456
+ * (`CorridorOverrides.lightning.decode` returns it). */
457
+ interface InvoiceFacts {
458
+ /** The raw BOLT11 — what travels in the request profile. */
459
+ raw: string;
460
+ /** `sha256(P)`, LOWERCASE hex (64 chars) — {@link verifyReceiveInvoice}
461
+ * compares it byte-for-byte against `paymentHashOf`, which emits lowercase. */
462
+ paymentHash: string;
463
+ amountSats: number;
464
+ /** Absolute expiry, unix seconds. */
465
+ expiresAt: number;
466
+ }
467
+ /**
468
+ * The lightning-send user flow: quote → derive locally → verify → gate. Funds nothing: the caller
469
+ * funds `address` with `fundAmount` before `quote.valid_until`, then may go OFFLINE. Success
470
+ * reveals the preimage in the solver's claim witness; failure refunds to `refundAddress`.
471
+ *
472
+ * @throws {SwapRefusal} (closed reason), {@link AddressMismatch} (never fund), a gate error with a
473
+ * stable `reason`, or {@link LockupRegistrationFailed} — only the last leaves the quote good for a
474
+ * retry once local storage is.
475
+ *
476
+ * @remarks Registers the lockup with the contract manager before returning the address, so it is
477
+ * watched (and out of coin selection) from the moment it lands, and a persistence failure throws
478
+ * while nothing is funded. Persist `secrets` (a public descriptor) with the record: it is how the
479
+ * refund signer is found again; without it `nonInteractiveRefund` still works but needs the
480
+ * SOLVER's active cooperation.
481
+ */
482
+ declare function requestLightningSend(wallet: IWallet, transport: RfqTransport, params: {
483
+ invoice: InvoiceFacts;
484
+ rfqId?: string;
485
+ /** Co-signer key override (33-byte compressed hex); see
486
+ * {@link resolveEmulatorPubkey}. */
487
+ emulatorPubkey?: string;
488
+ }): Promise<{
489
+ rfqId: string;
490
+ quote: RfqQuote;
491
+ /** The trader's OWN derivation — the only address to fund. */
492
+ address: string;
493
+ /** What the lockup must carry: the quote's `from_amount` (the invoice
494
+ * amount plus the corridor's fee), in sats. */
495
+ fundAmount: number;
496
+ /** The covenant's scriptPubKey, for watching the lockup and its spend. */
497
+ swapPkScript: Uint8Array;
498
+ /** The covenant itself. Hand it to `RfqSwapManager` as the record's `lockup` (with
499
+ * `address`); without it the manager can only poll and cannot retire the row. */
500
+ script: InstanceType<typeof VHTLC.ScriptV2>;
501
+ /** Where a failed swap refunds; the address `secrets.pkScript` was decoded from. */
502
+ refundAddress: string;
503
+ /** The VHTLC `sender` x-only key, bound into the covenant. Public. */
504
+ senderPubkey: Uint8Array;
505
+ /** How the `sender` key is recovered later. Persist it with the record;
506
+ * it holds nothing secret. */
507
+ secrets: ProvisionedKey;
508
+ /**
509
+ * Every input the covenant was built from, as it was AT REQUEST TIME (half are not on the
510
+ * quote). All public, and optional to persist: `rebuildRfqSwap` reads the registered contract
511
+ * row. To rebuild without that store, keep
512
+ * `VHTLCV2ContractHandler.serializeParams(script.options)` instead.
513
+ */
514
+ contractParams: LightningSendContractParams;
515
+ }>;
516
+ /** Compare-only check of the solver's offer address AND script against YOUR OWN derivation.
517
+ * Throws {@link AddressMismatch} unless both match exactly.
518
+ *
519
+ * @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`. */
520
+ declare const verifyOfferAddress: (quote: RfqQuote, derived: {
521
+ address: string;
522
+ swapPkScript: Uint8Array;
523
+ }) => {
524
+ address: string;
525
+ swapPkScript: Uint8Array;
526
+ };
527
+ /** Gate an arkade↔arkade quote immediately before funding. The only clock is `valid_until`:
528
+ * funding after it leaves a deposit the solver won't fill, reclaimable only via `cancelOffer`.
529
+ *
530
+ * @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`. */
531
+ declare const assertArkadeFundable: (input: {
532
+ quote: RfqQuote;
533
+ now?: number;
534
+ }) => void;
535
+ /**
536
+ * The arkade↔arkade user flow: quote → derive locally → verify → gate. Funds nothing; the caller
537
+ * funds before `quote.valid_until`, then may go offline. No timelock refund: an unfilled offer is
538
+ * cancelled cooperatively (`cancelOffer`).
539
+ *
540
+ * With `amountSide: "to"` the deposit is the solver's to name: set `maxFromAmount`, or fund
541
+ * whatever it quotes.
542
+ *
543
+ * Maker keys are read once here so the request profile and the local `createOffer` derivation
544
+ * cannot diverge. Throws {@link SwapRefusal}, {@link AddressMismatch} (never fund), or a gate error
545
+ * with a stable `reason`.
546
+ *
547
+ * `client.exchange()` now covers this route end to end — it opens the card's
548
+ * Nostr rendezvous, sends this same request, runs the full verification set,
549
+ * and registers, persists and funds in one step — so there is nothing left here
550
+ * that it does not do. What it additionally refuses is a transport that cannot
551
+ * say who answered, which this function, taking one from its caller, cannot.
552
+ *
553
+ * Funding (caller's job, immediately after, before `valid_until`):
554
+ * - BTC->asset (`wantAsset`): `wallet.send({ address, amount: Number(fundAmount), extensions: [extension] })`
555
+ * - asset->BTC or asset->asset (`offerAsset`): `wallet.send({ address, amount: Number(carrierSats), assets: [{ assetId: offerAsset, amount: fundAmount }], extensions: [extension] })`
556
+ *
557
+ * @deprecated Use `client.exchange()`. Moved off the package root to `@arkade-os/swap/protocol`.
558
+ */
559
+ declare function requestArkadeSwap(wallet: IWallet, transport: RfqTransport, params: {
560
+ /** Asset the trader deposits; omit when depositing BTC. */
561
+ offerAsset?: asset.AssetId;
562
+ /** Asset the trader wants; omit when wanting BTC. */
563
+ wantAsset?: asset.AssetId;
564
+ /** Atomic units of whichever leg `amountSide` names. */
565
+ amount: bigint | number | string;
566
+ amountSide?: "from" | "to";
567
+ /** Bounds the side the SOLVER chose — the named side is echoed back verbatim,
568
+ * so asserting it proves nothing and an unbounded caller funds what it is asked. */
569
+ maxFromAmount?: bigint | number | string;
570
+ minToAmount?: bigint | number | string;
571
+ rfqId?: string;
572
+ /** Co-signer key override (33-byte compressed hex); see `createOffer`. */
573
+ emulatorPubkey?: string;
574
+ /** Canonical Arkade payout destination; the maker signing key stays this wallet's. */
575
+ receiveAddress?: string;
576
+ now?: number;
577
+ }): Promise<{
578
+ rfqId: string;
579
+ quote: RfqQuote;
580
+ pair: string;
581
+ /** The trader's OWN derivation — the only address to fund. */
582
+ address: string;
583
+ /** What the deposit must carry: the quote's `from_amount`. Sats for a BTC
584
+ * deposit, asset units for an asset deposit (plus a dust carrier). */
585
+ fundAmount: bigint;
586
+ /** Dust sats to attach to an asset deposit; 0n for a BTC deposit. */
587
+ carrierSats: bigint;
588
+ /** The covenant's scriptPubKey, for watching the deposit and its spend. */
589
+ swapPkScript: Uint8Array;
590
+ /** The encoded offer. Persist this — it is the only input `cancelOffer`
591
+ * needs, and the restore scan reads it back off the funding tx. */
592
+ offerHex: string;
593
+ /** Ready for `wallet.send`'s `extensions`. */
594
+ extension: {
595
+ type: number;
596
+ payload: Uint8Array;
597
+ };
598
+ }>;
599
+ /** The rfq_request for `arkade:BTC->onchain:BTC`. Exact-out means "this much
600
+ * lands in the L1 HTLC". `senderPubkey` is the user's own key for the
601
+ * VHTLC's sender-side leaves — same role as in {@link lightningSendRequest}.
602
+ * On the wire it's `client_refund_pubkey`, same as there. */
603
+ declare const onchainSendRequest: (input: {
604
+ rfqId: string;
605
+ /** `sha256(P)`, hex — user-chosen; see {@link paymentHashOf}. */
606
+ paymentHash: string;
607
+ /** User's x-only L1 key for the HTLC's claim leaf. */
608
+ payoutPubkey: Uint8Array;
609
+ /** User's arkade address — where the covenant refund must pay. */
610
+ refundAddress: string;
611
+ senderPubkey: Uint8Array;
612
+ amount: number;
613
+ amountSide: "from" | "to";
614
+ }) => Record<string, unknown>;
615
+ /** The rfq_request for `lightning:BTC->arkade:BTC`. The trader sends only `H` plus `P` sealed to
616
+ * covclaimd, so the solver never sees `P` before a claim witness. `payoutPubkey` is the covenant's
617
+ * `receiver`, so the trader can claim without covclaimd. */
618
+ declare const lightningReceiveRequest: (input: {
619
+ rfqId: string;
620
+ /** `H = sha256(P)`, hex — trader-chosen; see {@link paymentHashOf}. */
621
+ paymentHash: string;
622
+ /** Trader's arkade address — where the swapped sats land. */
623
+ payoutAddress: string;
624
+ /** Trader's x-only arkade key — the covenant's `receiver` role. */
625
+ payoutPubkey: Uint8Array;
626
+ /** `P` sealed to covclaimd, base64 — `sealClaimPacket(...).ciphertext`. Omitted from the wire
627
+ * when there is no covclaimd: the solver refuses an empty packet. */
628
+ claimPacket?: string;
629
+ amount: number;
630
+ amountSide: "from" | "to";
631
+ }) => Record<string, unknown>;
632
+ /** The rfq_request for `onchain:BTC->arkade:BTC`. The user funds the L1 HTLC (holding its refund
633
+ * role); when P travels sealed to covclaimd, the user can go offline. Only an exact-out request
634
+ * is guaranteed to seal it. */
635
+ declare const onchainReceiveRequest: (input: {
636
+ rfqId: string;
637
+ paymentHash: string;
638
+ /** Trader's arkade address — where the swapped sats land. */
639
+ payoutAddress: string;
640
+ /** Trader's x-only arkade key — the covenant's `receiver` role. */
641
+ payoutPubkey: Uint8Array;
642
+ /** Trader's x-only L1 key for the HTLC's refund leaf. */
643
+ refundPubkey: Uint8Array;
644
+ /** `P` sealed to covclaimd, base64. Omitted when there is none to seal to —
645
+ * see {@link lightningReceiveRequest}. */
646
+ claimPacket?: string;
647
+ amount: number;
648
+ amountSide: "from" | "to";
649
+ }) => Record<string, unknown>;
650
+ /**
651
+ * The pure core of {@link requestOnchainSend}: derive BOTH contracts locally
652
+ * from the quote's binding fields plus the user's own data, and refuse on any
653
+ * mismatch. Binding: `solver_pubkey`, `refund_locktime`, `htlc_pubkey`,
654
+ * `htlc_locktime`, `min_confirmations`, `refund_without_receiver_delay` when
655
+ * present; `lockup_address` and `htlc_address` are compare-only.
656
+ */
657
+ declare function deriveOnchainSend(input: {
658
+ quote: RfqQuote;
659
+ paymentHash: string;
660
+ payoutPubkey: Uint8Array;
661
+ operatorPubkey: Uint8Array;
662
+ emulatorPubkey: Uint8Array;
663
+ claimDelay: number;
664
+ hrp: string;
665
+ l1Network: OnchainNetwork;
666
+ refundAddress: string;
667
+ /** The user's own key for the VHTLC's sender-side leaves — same role as
668
+ * in {@link requestLightningSend}. */
669
+ senderPubkey: Uint8Array;
670
+ }): {
671
+ address: string;
672
+ swapPkScript: Uint8Array;
673
+ /** The lockup covenant itself — what the contract row is registered from,
674
+ * so the row can never key on a script other than the derived one. */
675
+ script: InstanceType<typeof VHTLC.ScriptV2>;
676
+ htlc: OnchainHtlc;
677
+ /** The inputs {@link htlc} was built from; nothing else gives them back (L1 has no contract
678
+ * row, and `OnchainHtlc` exposes only derived values). */
679
+ htlcParams: OnchainHtlcParams;
680
+ /** Echoed from the input so the result fully describes the L1 half
681
+ * ({@link onchainSendProfile} reads it). */
682
+ l1Network: OnchainNetwork;
683
+ refundLocktime: number;
684
+ /** The quote's solo-refund delay; undefined when the lockup uses the base ladder. */
685
+ refundWithoutReceiverDelay: number | undefined;
686
+ htlcLocktime: number;
687
+ minConfirmations: number;
688
+ expectedAmount: number;
689
+ };
690
+ /**
691
+ * The `arkade:BTC->onchain:BTC` user flow, mirroring `requestLightningSend`:
692
+ * quote → derive BOTH contracts locally → verify → gate. Pure of funding —
693
+ * the caller funds `address` with its own wallet before `quote.valid_until`.
694
+ *
695
+ * Registers the arkade lockup before returning, as {@link requestLightningSend} does (the L1 HTLC
696
+ * has no contract row).
697
+ *
698
+ * Two obligations, both LOUD:
699
+ * - **Persist `secrets` (with the record) BEFORE funding.** On a non-HD wallet it carries raw
700
+ * secrets; losing them forfeits the L1 claim and every interactive refund path.
701
+ * - **Stay claim-capable.** The user must claim the L1 HTLC (`awaitOnchainFill` →
702
+ * `claimOnchainFill`) before `htlc.refundLocktime`, or the fill is forfeit and the swap falls
703
+ * back to the Arkade covenant refund.
704
+ */
705
+ declare function requestOnchainSend(wallet: IWallet, transport: RfqTransport, params: {
706
+ amount: number;
707
+ amountSide: "from" | "to";
708
+ /** User's x-only L1 key that will claim the HTLC. */
709
+ payoutPubkey: Uint8Array;
710
+ /** Optional caller-owned P. Persist it with the returned secrets before funding. */
711
+ preimage?: Uint8Array;
712
+ rfqId?: string;
713
+ /** Co-signer key override (33-byte compressed hex); see
714
+ * {@link resolveEmulatorPubkey}. */
715
+ emulatorPubkey?: string;
716
+ }): Promise<{
717
+ rfqId: string;
718
+ quote: RfqQuote;
719
+ /** The user's OWN arkade lockup derivation — the only address to fund. */
720
+ address: string;
721
+ fundAmount: number;
722
+ /** What the solver's L1 fill must carry — persist it with the record. */
723
+ expectedAmount: number;
724
+ swapPkScript: Uint8Array;
725
+ /** The arkade covenant itself — the record's `lockup` for
726
+ * `RfqSwapManager`, same role as {@link requestLightningSend}'s. */
727
+ script: InstanceType<typeof VHTLC.ScriptV2>;
728
+ refundAddress: string;
729
+ /** The EXPECTED L1 fill, derived locally — watch and claim against this. */
730
+ htlc: OnchainHtlc;
731
+ /** The inputs {@link htlc} was built from — persist these (with `htlc.address`) to rebuild it
732
+ * after a restart; nothing else gives them back. Prefer `onchainSendProfile(result)` to
733
+ * mapping them by hand. */
734
+ htlcParams: OnchainHtlcParams;
735
+ /** Which bitcoin network the L1 HTLC was derived for. NOT the ark network name: signet,
736
+ * mutinynet and testnet4 all become `"testnet"`. */
737
+ l1Network: OnchainNetwork;
738
+ /** `profile.min_confirmations`; gates when the L1 fill becomes claimable,
739
+ * and part of what a restored swap needs to drive its own claim. */
740
+ minConfirmations: number;
741
+ /** The arkade lockup's refund deadline, as the covenant was built with it. Read this, not
742
+ * `quote.refund_locktime`: a solver may carry the value in `profile` instead. */
743
+ refundLocktime: number;
744
+ /** The VHTLC `sender` x-only key, bound into the covenant. Public. */
745
+ senderPubkey: Uint8Array;
746
+ /** How the preimage and the `sender` key are recovered later — map it
747
+ * through `swapSecretsToRecord` and persist BEFORE funding. Public unless
748
+ * `mustPersistPreimage` says the wallet could not derive P. */
749
+ secrets: ProvisionedClaimSecret;
750
+ }>;
751
+ /**
752
+ * Default floor for the window between the last moment the hold invoice can
753
+ * be paid and the solver's refund leaf opening.
754
+ */
755
+ declare const MIN_CLAIM_WINDOW_SECONDS: number;
756
+ /**
757
+ * Bind the SOLVER's hold invoice to the quote and to the trader's own `H`.
758
+ *
759
+ * The only attack on this corridor with no on-chain trace: an invoice on another payment hash is
760
+ * paid to the solver in full and no lockup on `H` is ever funded. NEVER publish an invoice that
761
+ * has not passed this.
762
+ *
763
+ * The decoder is injected (no BOLT11 dependency), but the comparison lives here: a caller-supplied
764
+ * summary of an adversary's invoice checks nothing. A hold invoice is indistinguishable on the
765
+ * wire, so that is not checked.
766
+ *
767
+ * Reasons: `invoice_undecodable` | `invoice_hash_mismatch` |
768
+ * `invoice_amount_mismatch` | `quote_malformed`.
769
+ *
770
+ * @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
771
+ */
772
+ declare const verifyReceiveInvoice: (input: {
773
+ invoice: string;
774
+ decode: (bolt11: string) => InvoiceFacts;
775
+ /** `sha256(P)`, hex — the trader's OWN. */
776
+ paymentHash: string;
777
+ quote: RfqQuote;
778
+ }) => {
779
+ payDeadline: number;
780
+ };
781
+ /** Compile the RECEIVE-direction VHTLC: the same suite-carrying tree as {@link
782
+ * lightningSendContract} with the roles inverted — the trader is the
783
+ * `receiver` (it generated `P` and claims the lockup with it), the solver is
784
+ * the `sender` (it funds the lockup and holds the refund recourse). Shared by both receive
785
+ * corridors.
786
+ *
787
+ * @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
788
+ */
789
+ declare function lightningReceiveContract(params: {
790
+ /** Binding field #1: the solver's x-only key, from the quote — VHTLC's
791
+ * `sender` role on the receive corridors. */
792
+ solverPubkey: Uint8Array;
793
+ /** Binding field #2: the SOLVER's own refund deadline on these legs, from
794
+ * the quote — after it the solver may reclaim an unclaimed lockup. */
795
+ refundLocktime: number;
796
+ /** The Arkade operator's x-only key — the trader's OWN connection. */
797
+ operatorPubkey: Uint8Array;
798
+ /** `sha256(P)`, hex — the trader's OWN preimage hash. */
799
+ paymentHash: string;
800
+ /** From {@link unilateralClaimDelay} over the trader's OWN server info. */
801
+ claimDelay: number;
802
+ /** Emulator x-only key — see {@link requestLightningSend}'s parameter. */
803
+ emulatorPubkey: Uint8Array;
804
+ /** The solver's covenant refund destination, from the quote
805
+ * (`profile.solver_refund_pk_script`) — the one tree parameter nothing
806
+ * else on the wire determines. */
807
+ solverRefundPkScript: Uint8Array;
808
+ /** The trader's own x-only Arkade key — VHTLC's `receiver` role on these
809
+ * legs, so the trader can claim without covclaimd. */
810
+ payoutPubkey: Uint8Array;
811
+ /** The trader's own Arkade payout pkScript (decoded from its payout
812
+ * address) — `nonInteractiveClaim`'s pinned destination. */
813
+ payoutPkScript: Uint8Array;
814
+ /** LEGACY REBUILD ONLY — see {@link lightningSendVtxoScript}'s `legacy`. */
815
+ legacy?: "preTimelockedRefund";
816
+ }): InstanceType<typeof VHTLC.ScriptV2>;
817
+ /** Every input {@link lightningReceiveContract} builds from; see
818
+ * {@link LightningSendContractParams}.
819
+ *
820
+ * @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
821
+ */
822
+ type LightningReceiveContractParams = Parameters<typeof lightningReceiveContract>[0];
823
+ /**
824
+ * The pure core of {@link requestLightningReceive}: derive the solver-funded
825
+ * covenant locally from the quote's binding fields plus the trader's own data
826
+ * and refuse on any address mismatch. The trader funds nothing on Arkade here, but this is what
827
+ * makes paying the hold invoice safe: the lockup must be a tree whose claim paths pay the trader.
828
+ */
829
+ declare function deriveLightningReceive(input: {
830
+ quote: RfqQuote;
831
+ paymentHash: string;
832
+ payoutPubkey: Uint8Array;
833
+ payoutAddress: string;
834
+ operatorPubkey: Uint8Array;
835
+ emulatorPubkey: Uint8Array;
836
+ claimDelay: number;
837
+ hrp: string;
838
+ }): {
839
+ address: string;
840
+ swapPkScript: Uint8Array;
841
+ script: InstanceType<typeof VHTLC.ScriptV2>;
842
+ /** The solver's hold invoice on `H` — what the trader pays to arm the swap. */
843
+ invoice: string;
844
+ refundLocktime: number;
845
+ /** Every input the covenant was built from; see `requestLightningSend`'s result. */
846
+ contractParams: LightningReceiveContractParams;
847
+ };
848
+ /**
849
+ * The `lightning:BTC->arkade:BTC` user flow: quote → derive the covenant locally → verify → gate.
850
+ * Returns the solver's hold invoice (already checked by {@link verifyReceiveInvoice}) for the
851
+ * trader's own Lightning wallet to PAY before `invoiceExpiresAt`. Once the HTLC is held the solver
852
+ * funds the lockup and the trader claims it with its own `P` (`pushClaim`).
853
+ *
854
+ * Three obligations, all before the invoice is handed to a payer:
855
+ *
856
+ * 1. Persist `secrets` and `expectedAmount`; without the latter the claim cannot check the funded
857
+ * value.
858
+ * 2. Stay online. covclaimd cannot claim this covenant today, so an unclaimed lockup is reclaimed
859
+ * by the solver at `refund_locktime` and the payer refunded.
860
+ * 3. On {@link LockupRegistrationFailed}, call this again once the store works. The failed attempt
861
+ * is inert (no invoice was returned); re-registering `error.script` does NOT resume it.
862
+ */
863
+ declare function requestLightningReceive(wallet: IWallet, transport: RfqTransport, params: {
864
+ amount: number;
865
+ amountSide: "from" | "to";
866
+ /** Co-signer key override (33-byte compressed hex); see
867
+ * {@link resolveEmulatorPubkey}. */
868
+ emulatorPubkey?: string;
869
+ /** covclaimd's 33-byte compressed pubkey; the claim packet seals `P` to it. Only an
870
+ * exact-out request (`amountSide: "to"`) is guaranteed one, bound to `amount`; an exact-in
871
+ * one may carry none, and then claiming before `refund_locktime` is the caller's job.
872
+ * Never substitute a throwaway key — nobody could open it. */
873
+ covclaimdPubkey?: Uint8Array;
874
+ /** The caller's own BOLT11 decoder, applied to the SOLVER's invoice. Required: skipping
875
+ * this check can lose the whole payment. */
876
+ decodeInvoice: (bolt11: string) => InvoiceFacts;
877
+ /** Opt-in ceiling, in sats, on what the payer will be asked for. */
878
+ maxPayAmount?: number;
879
+ rfqId?: string;
880
+ }): Promise<{
881
+ rfqId: string;
882
+ quote: RfqQuote;
883
+ /** The solver's hold invoice — what the trader pays, for `payAmount`.
884
+ * Verified against this swap's `H` and the quote's `from_amount`. */
885
+ invoice: string;
886
+ /** What the trader pays: the quote's `from_amount`. */
887
+ payAmount: number;
888
+ /** What the solver's lockup must carry: the quote's `to_amount`. Persist it with the record:
889
+ * `pushClaim` refuses to publish `P` for less. */
890
+ expectedAmount: number;
891
+ /** Last moment the invoice can be paid, unix seconds: `min(invoice
892
+ * expiry, valid_until)`. */
893
+ invoiceExpiresAt: number;
894
+ /** The trader's OWN derivation of the lockup the solver must fund. */
895
+ address: string;
896
+ swapPkScript: Uint8Array;
897
+ script: InstanceType<typeof VHTLC.ScriptV2>;
898
+ payoutAddress: string;
899
+ /** The trader's covenant `receiver` key, bound into the tree. Public. */
900
+ payoutPubkey: Uint8Array;
901
+ /** How the preimage and the payout key are recovered later — map it
902
+ * through `swapSecretsToRecord` and persist BEFORE paying the invoice.
903
+ * Public unless `mustPersistPreimage` says the wallet could not derive P. */
904
+ secrets: ProvisionedClaimSecret;
905
+ /** Every input the covenant was built from; see the same field on
906
+ * `requestLightningSend`'s result. */
907
+ contractParams: LightningReceiveContractParams;
908
+ }>;
909
+ /**
910
+ * The pure core of {@link requestOnchainReceive}: derive BOTH contracts
911
+ * locally — the solver-funded Arkade covenant and the L1 HTLC the trader
912
+ * funds — and refuse on any mismatch. Binding: `solver_pubkey`,
913
+ * `refund_locktime`, `claim_pubkey`, `htlc_locktime`, `min_confirmations`;
914
+ * `lockup_address` and `htlc_address` are compare-only.
915
+ */
916
+ declare function deriveOnchainReceive(input: {
917
+ quote: RfqQuote;
918
+ paymentHash: string;
919
+ payoutPubkey: Uint8Array;
920
+ payoutAddress: string;
921
+ /** The trader's own x-only L1 key — the HTLC's refund role. */
922
+ refundPubkey: Uint8Array;
923
+ operatorPubkey: Uint8Array;
924
+ emulatorPubkey: Uint8Array;
925
+ claimDelay: number;
926
+ hrp: string;
927
+ l1Network: OnchainNetwork;
928
+ }): {
929
+ address: string;
930
+ swapPkScript: Uint8Array;
931
+ script: InstanceType<typeof VHTLC.ScriptV2>;
932
+ /** The L1 HTLC the trader funds, derived locally — fund only this. */
933
+ htlc: OnchainHtlc;
934
+ /** The inputs {@link htlc} was derived from; a restore rebuilds it from these. */
935
+ htlcParams: OnchainHtlcParams;
936
+ refundLocktime: number;
937
+ htlcLocktime: number;
938
+ minConfirmations: number;
939
+ };
940
+ /**
941
+ * The `onchain:BTC->arkade:BTC` user flow: quote → derive BOTH contracts
942
+ * locally → verify → gate. Returns the L1 HTLC for the trader's own L1 wallet to fund with
943
+ * `fundAmount`. After `min_confirmations` the solver funds the Arkade lockup; the trader claims it
944
+ * with `P`.
945
+ *
946
+ * Persist `secrets` BEFORE funding. If the swap never settles, the L1 refund leaf opens at
947
+ * `htlc.refundLocktime` (see `buildHtlcRefund`).
948
+ */
949
+ declare function requestOnchainReceive(wallet: IWallet, transport: RfqTransport, params: {
950
+ amount: number;
951
+ amountSide: "from" | "to";
952
+ /** Co-signer key override (33-byte compressed hex); see
953
+ * {@link resolveEmulatorPubkey}. */
954
+ emulatorPubkey?: string;
955
+ /** Trader's x-only L1 key for the HTLC's refund leaf. */
956
+ refundPubkey: Uint8Array;
957
+ /** covclaimd's 33-byte compressed pubkey. Only an exact-out request (`amountSide: "to"`)
958
+ * is guaranteed a claim packet; see {@link requestLightningReceive}. */
959
+ covclaimdPubkey?: Uint8Array;
960
+ rfqId?: string;
961
+ }): Promise<{
962
+ rfqId: string;
963
+ quote: RfqQuote;
964
+ /** The trader's OWN derivation of the lockup the solver must fund. */
965
+ address: string;
966
+ /** What the trader's L1 funding must carry: the quote's `from_amount`. */
967
+ fundAmount: number;
968
+ /** What the solver's lockup must carry: the quote's `to_amount`. Persist
969
+ * it with the record — see {@link requestLightningReceive}. */
970
+ expectedAmount: number;
971
+ swapPkScript: Uint8Array;
972
+ script: InstanceType<typeof VHTLC.ScriptV2>;
973
+ /** The EXPECTED L1 contract, derived locally — fund only this address. */
974
+ htlc: OnchainHtlc;
975
+ payoutAddress: string;
976
+ payoutPubkey: Uint8Array;
977
+ /** How the preimage and the payout key are recovered later — map it
978
+ * through `swapSecretsToRecord` and persist BEFORE funding. Public unless
979
+ * `mustPersistPreimage` says the wallet could not derive P. */
980
+ secrets: ProvisionedClaimSecret;
981
+ }>;
982
+
983
+ export { l1ScriptForAddress as $, ARKADE_BTC as A, type RelaySocket as B, type ChainSource as C, type RfqRefusalReason as D, type RfqStatus as E, arkadeAssetLeg as F, arkadeSwapRequest as G, type HtlcUtxo as H, type InvoiceFacts as I, assertArkadeFundable as J, awaitOnchainFill as K, type LightningSendContractParams as L, MAX_MIN_CONFIRMATIONS as M, buildHtlcClaim as N, type OnchainHtlc as O, buildHtlcRefund as P, canonicalAssetAmount as Q, type RfqQuote as R, SwapRefusal as S, type TxStatus as T, claimOnchainFill as U, classifyOnchainHtlc as V, deriveLightningReceive as W, deriveOnchainReceive as X, deriveOnchainSend as Y, extractPreimage as Z, httpTransport as _, RFQ_REFUSAL_ERROR_CODES as a, lightningReceiveContract as a0, lightningReceiveRequest as a1, lightningSendContract as a2, lightningSendRequest as a3, newPreimage as a4, normalizeMakerPkScript as a5, normalizeMakerPublicKey as a6, onchainHtlcScript as a7, onchainReceiveRequest as a8, onchainSendRequest as a9, paymentHashOf as aa, relayTransport as ab, requestArkadeSwap as ac, requestLightningReceive as ad, requestOnchainReceive as ae, unilateralClaimDelay as af, unilateralRefundDelay as ag, unilateralRefundWithoutReceiverDelay as ah, verifyLockupAddress as ai, verifyOfferAddress as aj, verifyReceiveInvoice as ak, type RfqRefusalDetail as b, type RfqRefusalErrorCode as c, type RfqRefusalUnit as d, type RfqTransport as e, type LightningReceiveContractParams as f, type OnchainHtlcParams as g, type OnchainNetwork as h, isRfqRefusalErrorCode as i, requestOnchainSend as j, AddressMismatch as k, type ChainUtxo as l, LIGHTNING_BTC as m, LIGHTNING_RECEIVE_PAIR as n, LIGHTNING_SEND_PAIR as o, LOCKTIME_THRESHOLD as p, MIN_CLAIM_WINDOW_SECONDS as q, requestLightningSend as r, ONCHAIN_BTC as s, ONCHAIN_CLAIM_MARGIN_SECONDS as t, ONCHAIN_DUST_SATS as u, ONCHAIN_ORDER_MARGIN_SECONDS as v, ONCHAIN_RECEIVE_PAIR as w, ONCHAIN_SECONDS_PER_BLOCK as x, ONCHAIN_SEND_PAIR as y, type OnchainHtlcPhase as z };