@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.
- package/README.md +11 -0
- package/dist/advanced.cjs +1028 -1006
- package/dist/advanced.d.cts +145 -279
- package/dist/advanced.d.ts +145 -279
- package/dist/advanced.js +14 -8
- package/dist/{chunk-SC3SAY3X.js → chunk-4WPDXLXH.js} +501 -271
- package/dist/chunk-A3SHHRX4.js +104 -0
- package/dist/{chunk-KRXPQQJ7.js → chunk-BBP25BWH.js} +198 -218
- package/dist/{chunk-ZDFMD4FA.js → chunk-RX3WPV5D.js} +356 -584
- package/dist/errors-BcOgFV-F.d.ts +1559 -0
- package/dist/errors-n6IHTG-Z.d.cts +1559 -0
- package/dist/index.cjs +1406 -1331
- package/dist/index.d.cts +69 -186
- package/dist/index.d.ts +69 -186
- package/dist/index.js +102 -158
- package/dist/lockupContract-B_jNbjrG.d.ts +215 -0
- package/dist/lockupContract-ZsftgqMc.d.cts +215 -0
- package/dist/node/index.cjs +61 -10
- package/dist/node/index.d.cts +227 -600
- package/dist/node/index.d.ts +227 -600
- package/dist/node/index.js +65 -10
- package/dist/nostr.cjs +11 -11
- package/dist/nostr.d.cts +23 -68
- package/dist/nostr.d.ts +23 -68
- package/dist/nostr.js +3 -4
- package/dist/offer--1zVkNsV.d.ts +261 -0
- package/dist/offer-DsP1q6GE.d.cts +261 -0
- package/dist/protocol.cjs +747 -1012
- package/dist/protocol.d.cts +120 -255
- package/dist/protocol.d.ts +120 -255
- package/dist/protocol.js +146 -149
- package/dist/repositories/realm/index.cjs +55 -11
- package/dist/repositories/realm/index.d.cts +18 -30
- package/dist/repositories/realm/index.d.ts +18 -30
- package/dist/repositories/realm/index.js +49 -12
- package/dist/repositories/sqlite/index.cjs +61 -10
- package/dist/repositories/sqlite/index.d.cts +7 -6
- package/dist/repositories/sqlite/index.d.ts +7 -6
- package/dist/repositories/sqlite/index.js +57 -11
- package/dist/repository-BY6GUQiW.d.ts +2233 -0
- package/dist/repository-C32GKpR5.d.cts +2233 -0
- package/dist/{rfq-BWE8qkV2.d.ts → rfq-60PGpQ_x.d.cts} +178 -408
- package/dist/{rfq-BWE8qkV2.d.cts → rfq-60PGpQ_x.d.ts} +178 -408
- package/dist/{watch-D8Z78RAV.d.ts → watch-Cejw5cNQ.d.cts} +12 -30
- package/dist/{watch-C4ReJR5z.d.cts → watch-D8uzWrHc.d.ts} +12 -30
- package/package.json +2 -2
- package/dist/chunk-U7VWWTL6.js +0 -66
- package/dist/errors-LXMcNhNS.d.ts +0 -2222
- package/dist/errors-XUs8r0LT.d.cts +0 -2222
- package/dist/lockupContract-BhMebZCb.d.cts +0 -650
- package/dist/lockupContract-CAiN97fX.d.ts +0 -650
- package/dist/repository-BJLuVFQ0.d.ts +0 -3436
- 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
|
-
*
|
|
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:
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
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.
|
|
65
|
-
* the
|
|
66
|
-
*
|
|
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
|
-
*
|
|
105
|
-
*
|
|
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
|
|
154
|
-
*
|
|
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
|
|
189
|
-
*
|
|
190
|
-
*
|
|
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
|
|
210
|
-
*
|
|
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,
|
|
225
|
-
*
|
|
226
|
-
*
|
|
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
|
|
265
|
-
*
|
|
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
|
-
*
|
|
270
|
-
* `
|
|
271
|
-
*
|
|
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.
|
|
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
|
|
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.
|
|
367
|
-
*
|
|
368
|
-
*
|
|
369
|
-
* (
|
|
370
|
-
*
|
|
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
|
-
*
|
|
387
|
-
*
|
|
388
|
-
*
|
|
389
|
-
*
|
|
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
|
-
*
|
|
429
|
-
*
|
|
430
|
-
*
|
|
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
|
|
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
|
|
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
|
-
*
|
|
502
|
-
* (`
|
|
503
|
-
* `
|
|
504
|
-
*
|
|
505
|
-
*
|
|
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
|
|
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
|
-
*
|
|
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
|
|
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
|
|
539
|
-
*
|
|
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
|
|
544
|
-
*
|
|
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.
|
|
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
|
|
572
|
-
*
|
|
573
|
-
*
|
|
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
|
-
*
|
|
585
|
-
*
|
|
586
|
-
*
|
|
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
|
-
* `
|
|
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
|
|
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
|
-
*
|
|
632
|
-
*
|
|
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
|
-
*
|
|
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.
|
|
661
|
-
*
|
|
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
|
|
672
|
-
*
|
|
673
|
-
*
|
|
674
|
-
*
|
|
675
|
-
*
|
|
676
|
-
*
|
|
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
|
|
679
|
-
*
|
|
680
|
-
*
|
|
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
|
-
*
|
|
684
|
-
*
|
|
685
|
-
*
|
|
686
|
-
* a
|
|
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
|
|
751
|
-
*
|
|
752
|
-
* `
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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
|
|
823
|
-
*
|
|
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
|
|
828
|
-
*
|
|
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
|
|
842
|
-
*
|
|
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
|
|
849
|
-
*
|
|
850
|
-
*
|
|
851
|
-
*
|
|
852
|
-
*
|
|
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
|
|
886
|
-
*
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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
|
-
*
|
|
924
|
-
*
|
|
925
|
-
*
|
|
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
|
-
*
|
|
934
|
-
*
|
|
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).
|
|
954
|
-
*
|
|
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
|
|
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
|
|
997
|
-
*
|
|
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
|
|
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
|
-
*
|
|
1024
|
-
*
|
|
1025
|
-
*
|
|
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
|
|
825
|
+
* Three obligations, all before the invoice is handed to a payer:
|
|
1032
826
|
*
|
|
1033
|
-
* 1. Persist `secrets` and `expectedAmount
|
|
1034
|
-
*
|
|
1035
|
-
*
|
|
1036
|
-
*
|
|
1037
|
-
*
|
|
1038
|
-
*
|
|
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
|
|
1059
|
-
*
|
|
1060
|
-
*
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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)`.
|
|
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
|
|
1135
|
-
* `fundAmount`
|
|
1136
|
-
*
|
|
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
|
|
1141
|
-
*
|
|
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
|
|
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<{
|