@arkade-os/swap 0.1.0-rc.9 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +261 -252
- package/dist/advanced.cjs +6613 -3224
- package/dist/advanced.d.cts +328 -283
- package/dist/advanced.d.ts +328 -283
- package/dist/advanced.js +347 -34
- package/dist/chunk-A3SHHRX4.js +104 -0
- package/dist/chunk-FMRAV77W.js +3065 -0
- package/dist/chunk-T4FHBWZI.js +3459 -0
- package/dist/{chunk-NS3K6BZG.js → chunk-YHESEL4I.js} +1792 -636
- package/dist/index.cjs +6901 -3901
- package/dist/index.d.cts +71 -243
- package/dist/index.d.ts +71 -243
- package/dist/index.js +131 -167
- package/dist/lockupContract-CIXkJPxV.d.ts +148 -0
- package/dist/lockupContract-CkhWMKCo.d.cts +148 -0
- package/dist/node/index.cjs +61 -10
- package/dist/node/index.d.cts +307 -635
- package/dist/node/index.d.ts +307 -635
- package/dist/node/index.js +65 -10
- package/dist/nostr.cjs +427 -49
- package/dist/nostr.d.cts +59 -70
- package/dist/nostr.d.ts +59 -70
- package/dist/nostr.js +268 -36
- package/dist/offer-BPD2ortO.d.ts +269 -0
- package/dist/offer-Diff5Flc.d.cts +269 -0
- package/dist/offerFillPlan-B-5ae_gQ.d.cts +1671 -0
- package/dist/offerFillPlan-CJzneX6F.d.ts +1671 -0
- package/dist/protocol.cjs +5717 -4275
- package/dist/protocol.d.cts +258 -328
- package/dist/protocol.d.ts +258 -328
- package/dist/protocol.js +200 -224
- 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-BBVRh9ez.d.ts +2357 -0
- package/dist/repository-C4pvymhs.d.cts +2357 -0
- package/dist/{rfq-BO6o7NwS.d.ts → rfq-C0tHOvn6.d.cts} +323 -444
- package/dist/{rfq-BO6o7NwS.d.cts → rfq-C0tHOvn6.d.ts} +323 -444
- package/dist/watch-7BiRa4oB.d.ts +74 -0
- package/dist/watch-Bxq-lx_6.d.cts +74 -0
- package/package.json +10 -10
- package/dist/chunk-JFKGMPMH.js +0 -3456
- package/dist/chunk-LLG7RD2T.js +0 -1499
- package/dist/chunk-U7VWWTL6.js +0 -66
- package/dist/errors-CNISbN0M.d.ts +0 -2218
- package/dist/errors-DwNhIP0N.d.cts +0 -2218
- package/dist/lockupContract-C8-Mcg69.d.ts +0 -664
- package/dist/lockupContract-mIt4syse.d.cts +0 -664
- package/dist/repository-CGPLbjBe.d.ts +0 -3489
- package/dist/repository-DSGGq0ct.d.cts +0 -3489
- package/dist/watch-DWyVqyEN.d.cts +0 -96
- package/dist/watch-DmvHNX6T.d.ts +0 -96
|
@@ -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,48 +108,48 @@ declare const buildHtlcRefund: (input: {
|
|
|
150
108
|
interface ChainUtxo extends HtlcUtxo {
|
|
151
109
|
confirmations: number;
|
|
152
110
|
}
|
|
153
|
-
/**
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
*
|
|
157
|
-
* A root export because `CorridorOverrides.onchain.chain` takes it: a caller
|
|
158
|
-
* wiring that override names this type.
|
|
159
|
-
*/
|
|
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). */
|
|
160
115
|
interface ChainSource {
|
|
161
116
|
/** Confirmed+mempool outputs paying a script; used to detect the fill. */
|
|
162
117
|
getScriptUtxos(pkScript: Uint8Array): Promise<ChainUtxo[]>;
|
|
163
|
-
/**
|
|
164
|
-
*
|
|
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`. */
|
|
165
124
|
getSpendingTx(txid: string, vout: number, pkScript: Uint8Array): Promise<{
|
|
166
125
|
txHex: string;
|
|
167
126
|
} | null>;
|
|
168
127
|
broadcast(txHex: string): Promise<string>;
|
|
169
128
|
/** Current median-time-past, unix seconds — gates refund broadcasting. */
|
|
170
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>;
|
|
171
137
|
}
|
|
172
138
|
/** Read P out of a claim spend's witness: the 32-byte item whose sha256 is the
|
|
173
139
|
* payment hash. Null when the tx reveals no matching preimage (e.g. a refund
|
|
174
|
-
* spend, or an unrelated tx).
|
|
175
|
-
*
|
|
176
|
-
*/
|
|
140
|
+
* spend, or an unrelated tx). */
|
|
177
141
|
declare function extractPreimage(txHex: string, paymentHash: string): Uint8Array | null;
|
|
178
142
|
/** Poll {@link ChainSource} until the HTLC is funded to the required depth.
|
|
179
143
|
* Picks the largest qualifying output when several exist. Throws (reason
|
|
180
|
-
* `fill_timeout`) once `deadline` (unix seconds) passes without one.
|
|
181
|
-
*
|
|
182
|
-
*/
|
|
144
|
+
* `fill_timeout`) once `deadline` (unix seconds) passes without one. */
|
|
183
145
|
declare function awaitOnchainFill(chain: ChainSource, htlc: OnchainHtlc, minConfirmations: number, options?: {
|
|
184
146
|
pollMs?: number;
|
|
185
147
|
deadline?: number;
|
|
186
148
|
}): Promise<ChainUtxo>;
|
|
187
149
|
/**
|
|
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
|
-
*
|
|
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.
|
|
195
153
|
*/
|
|
196
154
|
declare function claimOnchainFill(chain: ChainSource, input: {
|
|
197
155
|
htlc: OnchainHtlc;
|
|
@@ -202,15 +160,16 @@ declare function claimOnchainFill(chain: ChainSource, input: {
|
|
|
202
160
|
sign: (sighash: Uint8Array) => Promise<Uint8Array>;
|
|
203
161
|
/** Injected for tests; defaults to wall clock. */
|
|
204
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;
|
|
205
166
|
}): Promise<{
|
|
206
167
|
txid: string;
|
|
207
168
|
payoutAmount: bigint;
|
|
208
169
|
}>;
|
|
209
|
-
/** Where an onchain HTLC stands, for crash recovery
|
|
210
|
-
*
|
|
211
|
-
*
|
|
212
|
-
*
|
|
213
|
-
*/
|
|
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). */
|
|
214
173
|
type OnchainHtlcPhase = {
|
|
215
174
|
phase: "unfunded";
|
|
216
175
|
} | {
|
|
@@ -221,12 +180,11 @@ type OnchainHtlcPhase = {
|
|
|
221
180
|
utxo: ChainUtxo;
|
|
222
181
|
}
|
|
223
182
|
/**
|
|
224
|
-
* The refund leaf has matured
|
|
225
|
-
* `claimOnchainFill` throws
|
|
226
|
-
*
|
|
227
|
-
*
|
|
228
|
-
*
|
|
229
|
-
* to claim means the claim was missed, not that it is still available.
|
|
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.
|
|
230
188
|
*/
|
|
231
189
|
| {
|
|
232
190
|
phase: "refundable";
|
|
@@ -245,8 +203,7 @@ type OnchainHtlcPhase = {
|
|
|
245
203
|
* already spent": without it a spent HTLC looks unfunded.
|
|
246
204
|
*
|
|
247
205
|
* `claimed` carries the preimage read from the spend's witness — the receipt;
|
|
248
|
-
* `swept` is a spend that reveals no preimage
|
|
249
|
-
*
|
|
206
|
+
* `swept` is a spend that reveals no matching preimage.
|
|
250
207
|
*/
|
|
251
208
|
declare function classifyOnchainHtlc(chain: ChainSource, input: {
|
|
252
209
|
htlc: OnchainHtlc;
|
|
@@ -257,53 +214,25 @@ declare function classifyOnchainHtlc(chain: ChainSource, input: {
|
|
|
257
214
|
};
|
|
258
215
|
}): Promise<OnchainHtlcPhase>;
|
|
259
216
|
|
|
260
|
-
/** Legs are `<corridor>:<asset>`; a pair is directional, `from->to`.
|
|
261
|
-
*
|
|
262
|
-
* @deprecated An RFQ pair leg, not an asset id — the client builds the pair from the route. The v2 asset id is `btcOn("arkade", network)`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
263
|
-
*/
|
|
217
|
+
/** Legs are `<corridor>:<asset>`; a pair is directional, `from->to`. */
|
|
264
218
|
declare const ARKADE_BTC = "arkade:BTC";
|
|
265
|
-
/** @deprecated An RFQ pair leg, not an asset id — the client builds the pair from the route. The v2 asset id is `btcOn("bolt11", network)`. Moved off the package root to `@arkade-os/swap/protocol`. */
|
|
266
219
|
declare const LIGHTNING_BTC = "lightning:BTC";
|
|
267
|
-
/** @deprecated An RFQ pair leg, not an asset id — the client builds the pair from the route. The v2 asset id is `btcOn("bitcoin", network)`. Moved off the package root to `@arkade-os/swap/protocol`. */
|
|
268
220
|
declare const ONCHAIN_BTC = "onchain:BTC";
|
|
269
|
-
/** The arkade leg for an asset: the asset id itself, 68 lowercase hex
|
|
270
|
-
*
|
|
271
|
-
* sides route and subscribe on, and a coarse leg cannot say which asset a
|
|
272
|
-
* market key is for.
|
|
273
|
-
*
|
|
274
|
-
* Taking an `AssetId` rather than a string is what enforces the case rule:
|
|
275
|
-
* `hex.decode` accepts uppercase while `hex.encode` only emits lowercase, so a
|
|
276
|
-
* value that reached us as `A1B2…` leaves here as `a1b2…`. Solvers compare pair
|
|
277
|
-
* strings byte for byte — a sender that normalised only in its key derivation
|
|
278
|
-
* would reach the right subscription and then be skipped as an unserved pair.
|
|
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.
|
|
279
223
|
*
|
|
280
|
-
*
|
|
281
|
-
|
|
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. */
|
|
282
227
|
declare const arkadeAssetLeg: (id: asset.AssetId) => string;
|
|
283
|
-
/** The implemented pair: pay a BOLT11 invoice out of an Arkade balance.
|
|
284
|
-
*
|
|
285
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
286
|
-
*/
|
|
228
|
+
/** The implemented pair: pay a BOLT11 invoice out of an Arkade balance. */
|
|
287
229
|
declare const LIGHTNING_SEND_PAIR: string;
|
|
288
|
-
/** On-board via Lightning: pay the solver's hold invoice, land on Arkade.
|
|
289
|
-
*
|
|
290
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
291
|
-
*/
|
|
230
|
+
/** On-board via Lightning: pay the solver's hold invoice, land on Arkade. */
|
|
292
231
|
declare const LIGHTNING_RECEIVE_PAIR: string;
|
|
293
|
-
/** Off-board: Arkade sats out to a Bitcoin-L1 HTLC.
|
|
294
|
-
*
|
|
295
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
296
|
-
*/
|
|
297
232
|
declare const ONCHAIN_SEND_PAIR: string;
|
|
298
|
-
/** On-board: a Bitcoin-L1 HTLC in, Arkade sats out.
|
|
299
|
-
*
|
|
300
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
301
|
-
*/
|
|
233
|
+
/** On-board: a Bitcoin-L1 HTLC in, Arkade sats out. */
|
|
302
234
|
declare const ONCHAIN_RECEIVE_PAIR: string;
|
|
303
|
-
/** The closed refusal set. Treat any unknown reason as a generic decline.
|
|
304
|
-
*
|
|
305
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
306
|
-
*/
|
|
235
|
+
/** The closed refusal set. Treat any unknown reason as a generic decline. */
|
|
307
236
|
type RfqRefusalReason = "unsupported_pair" | "unsupported_payload" | "amount_out_of_range" | "exposure_cap" | "invoice_expired" | "quote_conflict" | "pricing_unavailable" | "rate_limited";
|
|
308
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"];
|
|
309
238
|
type RfqRefusalErrorCode = (typeof RFQ_REFUSAL_ERROR_CODES)[number];
|
|
@@ -320,8 +249,7 @@ declare const isRfqRefusalErrorCode: (value: unknown) => value is RfqRefusalErro
|
|
|
320
249
|
/** A refusal from the solver, carrying its closed-set reason. */
|
|
321
250
|
declare class SwapRefusal extends Error {
|
|
322
251
|
/** Literal-typed so the v2 error taxonomy's union discriminates on `name`
|
|
323
|
-
* — a `string` here collapses the discriminant for every member.
|
|
324
|
-
* the constructor has always set, moved to a field initializer. */
|
|
252
|
+
* — a `string` here collapses the discriminant for every member. */
|
|
325
253
|
readonly name = "SwapRefusal";
|
|
326
254
|
readonly reason: string;
|
|
327
255
|
readonly rfqId: string | undefined;
|
|
@@ -337,22 +265,25 @@ declare class SwapRefusal extends Error {
|
|
|
337
265
|
* The solver's address does not match the local derivation. NEVER fund past
|
|
338
266
|
* this. `derived` is every candidate address tried — more than one when the
|
|
339
267
|
* derivation itself is ambiguous, see {@link verifyLockupAddress}.
|
|
340
|
-
*
|
|
341
|
-
* @deprecated Folded into `QuoteVerificationFailed`, which `client.quote()` throws. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
342
268
|
*/
|
|
343
269
|
declare class AddressMismatch extends Error {
|
|
344
270
|
readonly derived: string | string[];
|
|
345
271
|
readonly quoted: string | undefined;
|
|
346
272
|
constructor(derived: string | string[], quoted?: string);
|
|
347
273
|
}
|
|
348
|
-
/** @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`. */
|
|
349
274
|
interface RfqQuote {
|
|
350
275
|
v: 1;
|
|
351
276
|
type: "rfq_quote";
|
|
352
277
|
rfq_id: string;
|
|
353
278
|
pair: string;
|
|
354
|
-
|
|
355
|
-
|
|
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;
|
|
356
287
|
solver_pubkey: string;
|
|
357
288
|
valid_until: number;
|
|
358
289
|
/** HTLC-class quotes only; absent for arkade↔arkade. */
|
|
@@ -361,10 +292,12 @@ interface RfqQuote {
|
|
|
361
292
|
[key: string]: unknown;
|
|
362
293
|
payment_hash?: string;
|
|
363
294
|
lockup_address?: string;
|
|
295
|
+
refund_without_receiver_delay?: number;
|
|
296
|
+
offer_address?: string;
|
|
297
|
+
offer_pk_script?: string;
|
|
364
298
|
};
|
|
365
299
|
[key: string]: unknown;
|
|
366
300
|
}
|
|
367
|
-
/** @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`. */
|
|
368
301
|
interface RfqStatus {
|
|
369
302
|
v: 1;
|
|
370
303
|
type: "rfq_status";
|
|
@@ -374,17 +307,11 @@ interface RfqStatus {
|
|
|
374
307
|
profile: Record<string, unknown>;
|
|
375
308
|
[key: string]: unknown;
|
|
376
309
|
}
|
|
377
|
-
/** The rfq_request for the lightning send profile.
|
|
378
|
-
*
|
|
379
|
-
*
|
|
380
|
-
* (
|
|
381
|
-
*
|
|
382
|
-
* script. On the wire it's `client_refund_pubkey` (the payload schemas are
|
|
383
|
-
* public at https://docs.arkadeos.com/intents/reference/rfq — the solver's schema
|
|
384
|
-
* is `.strict()`, so both the wrong name AND the missing required field would
|
|
385
|
-
* refuse every request).
|
|
386
|
-
*
|
|
387
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
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.
|
|
388
315
|
*/
|
|
389
316
|
declare const lightningSendRequest: (input: {
|
|
390
317
|
rfqId: string;
|
|
@@ -392,62 +319,69 @@ declare const lightningSendRequest: (input: {
|
|
|
392
319
|
refundAddress: string;
|
|
393
320
|
senderPubkey: Uint8Array;
|
|
394
321
|
}) => Record<string, unknown>;
|
|
395
|
-
/** The rfq_request for an arkade↔arkade swap.
|
|
396
|
-
*
|
|
397
|
-
* {@link arkadeAssetLeg}.
|
|
398
|
-
*
|
|
399
|
-
*
|
|
400
|
-
*
|
|
401
|
-
|
|
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`. */
|
|
402
330
|
declare const arkadeSwapRequest: (input: {
|
|
403
331
|
rfqId: string;
|
|
404
332
|
/** Asset the trader deposits; omit when depositing BTC. */
|
|
405
333
|
offerAsset?: asset.AssetId;
|
|
406
334
|
/** Asset the trader wants; omit when wanting BTC. */
|
|
407
335
|
wantAsset?: asset.AssetId;
|
|
408
|
-
amountSide
|
|
409
|
-
/**
|
|
410
|
-
|
|
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;
|
|
411
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;
|
|
412
361
|
/**
|
|
413
362
|
* Compare-only check of the solver's address against YOUR OWN derivation(s)
|
|
414
363
|
* — never extends trust, only narrows it.
|
|
415
364
|
*
|
|
416
|
-
*
|
|
417
|
-
*
|
|
418
|
-
*
|
|
419
|
-
* nothing on the wire says whether a given quote's covenant carries it (the
|
|
420
|
-
* shape is fixed by the solver's own build, not negotiated per quote), so the
|
|
421
|
-
* only safe move is to derive BOTH shapes and accept whichever one the quote's
|
|
422
|
-
* own `lockup_address` matches. This loses no security: every candidate shape
|
|
423
|
-
* pins the refund to the trader's own refund destination, so a solver gains
|
|
424
|
-
* nothing by choosing which one to quote.
|
|
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.
|
|
425
368
|
*
|
|
426
|
-
*
|
|
427
|
-
*
|
|
428
|
-
*
|
|
429
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
369
|
+
* @returns the address that matched.
|
|
370
|
+
* @throws {AddressMismatch} only when NONE of the candidates match.
|
|
430
371
|
*/
|
|
431
372
|
declare const verifyLockupAddress: (quote: RfqQuote, derivedAddress: string | string[]) => string;
|
|
432
|
-
/** @deprecated Transport is an inference; `@arkade-os/swap/nostr` stays the hand-built floor. Moved off the package root to `@arkade-os/swap/protocol`. */
|
|
433
373
|
interface RfqTransport {
|
|
434
374
|
requestQuote(payload: Record<string, unknown>): Promise<RfqQuote>;
|
|
435
375
|
status(rfqId: string): Promise<RfqStatus | null>;
|
|
436
376
|
close(): Promise<void>;
|
|
437
377
|
}
|
|
438
378
|
/** HTTP: POST /v1/swap for quotes, GET /v1/rfq/<rfq_id> for status.
|
|
439
|
-
* `fetchImpl` is injectable for tests and non-global-fetch runtimes.
|
|
440
|
-
*
|
|
441
|
-
* @deprecated A dev transport; `client.quote()` opens the card's rendezvous itself. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
442
|
-
*/
|
|
379
|
+
* `fetchImpl` is injectable for tests and non-global-fetch runtimes. */
|
|
443
380
|
declare const httpTransport: (baseUrl: string, options?: {
|
|
444
381
|
fetchImpl?: typeof fetch;
|
|
445
382
|
}) => RfqTransport;
|
|
446
383
|
/** Minimal WebSocket surface the relay transport needs — satisfied by the DOM
|
|
447
|
-
* WebSocket and by `ws` alike, so neither becomes a dependency.
|
|
448
|
-
*
|
|
449
|
-
* @deprecated A dev transport; `client.quote()` opens the card's rendezvous itself. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
450
|
-
*/
|
|
384
|
+
* WebSocket and by `ws` alike, so neither becomes a dependency. */
|
|
451
385
|
interface RelaySocket {
|
|
452
386
|
send(data: string): void;
|
|
453
387
|
close(): void;
|
|
@@ -455,104 +389,71 @@ interface RelaySocket {
|
|
|
455
389
|
}
|
|
456
390
|
/** Relay: both parties outbound, addressed by x-only pubkey, speaking the dev
|
|
457
391
|
* broker framing. Nostr (directed kind + NIP-44) replaces only this function.
|
|
458
|
-
* One socket; replies correlated by rfq_id.
|
|
459
|
-
*
|
|
460
|
-
* @deprecated A dev transport; `client.quote()` opens the card's rendezvous itself. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
461
|
-
*/
|
|
392
|
+
* One socket; replies correlated by rfq_id. */
|
|
462
393
|
declare const relayTransport: (relayUrl: string, options: {
|
|
463
394
|
solverPubkey: string;
|
|
464
395
|
clientPubkey: string;
|
|
465
396
|
WebSocketCtor?: new (url: string) => RelaySocket;
|
|
466
397
|
timeoutMs?: number;
|
|
467
398
|
}) => RfqTransport;
|
|
468
|
-
/** The solver's unilateral-claim delay, derived from the
|
|
399
|
+
/** The solver's unilateral-claim delay, derived from the Arkade operator's reported
|
|
469
400
|
* exit delay exactly as the reference solver derives it — both sides read the
|
|
470
401
|
* SAME server, so the derivation (not a quote field) is what keeps the two
|
|
471
|
-
* scripts identical.
|
|
472
|
-
*
|
|
473
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
474
|
-
*/
|
|
402
|
+
* scripts identical. */
|
|
475
403
|
declare const unilateralClaimDelay: (operatorExitDelaySeconds: number) => number;
|
|
476
404
|
/** VHTLC's `unilateralRefund` tier: sender + receiver, no server — LEVEL with
|
|
477
405
|
* `claimDelay`, not above it. Neither party can spend a two-signature leaf
|
|
478
|
-
* alone, so separating it buys no safety
|
|
479
|
-
* is a second taken off the headroom that does matter.
|
|
480
|
-
*
|
|
481
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
482
|
-
*/
|
|
406
|
+
* alone, so separating it buys no safety and would only eat into the headroom that matters. */
|
|
483
407
|
declare const unilateralRefundDelay: (claimDelay: number) => number;
|
|
484
408
|
/** VHTLC's `unilateralRefundWithoutReceiver` tier: sender alone, needing
|
|
485
409
|
* nobody. The only leaf whose timing can steal — a funder able to refund
|
|
486
410
|
* before the claimant can claim takes money from someone holding the preimage
|
|
487
|
-
* — so it opens last, by {@link SOLO_REFUND_HEADROOM_SECONDS}.
|
|
488
|
-
*
|
|
489
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
490
|
-
*/
|
|
411
|
+
* — so it opens last, by {@link SOLO_REFUND_HEADROOM_SECONDS}. */
|
|
491
412
|
declare const unilateralRefundWithoutReceiverDelay: (claimDelay: number) => number;
|
|
492
413
|
/** Compile the lightning-send VHTLC from the quote's binding fields plus the
|
|
493
414
|
* trader's own data. `paymentHash` is the BOLT11 payment hash (`sha256(P)`,
|
|
494
415
|
* hex); the script's HASH160 commitment is derived from it here, which is why
|
|
495
416
|
* the trader never needs to see `P`.
|
|
496
417
|
*
|
|
497
|
-
*
|
|
498
|
-
* (`
|
|
499
|
-
* `
|
|
500
|
-
*
|
|
501
|
-
*
|
|
502
|
-
* the trader's own `refundPkScript`, no timelock and no trader signature
|
|
503
|
-
* needed — see {@link VHTLC.Options.nonInteractiveParameters}'s doc comment for why
|
|
504
|
-
* that matters), and its timelocked twin `nonInteractiveRefundWithoutReceiver`
|
|
505
|
-
* (server + emulator alone, after `refundLocktime` — the only refund tier
|
|
506
|
-
* needing no participant at all). Nine leaves in all, unless `legacy` says
|
|
507
|
-
* otherwise.
|
|
508
|
-
*
|
|
509
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
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`).
|
|
510
423
|
*/
|
|
511
424
|
declare function lightningSendContract(params: {
|
|
512
425
|
/** Binding field #1: the solver's x-only key, from the quote. */
|
|
513
426
|
solverPubkey: Uint8Array;
|
|
514
427
|
/** Binding field #2: when the trader's refund path opens, from the quote. */
|
|
515
428
|
refundLocktime: number;
|
|
516
|
-
/** The
|
|
429
|
+
/** The Arkade operator's x-only key — the trader's OWN connection. */
|
|
517
430
|
operatorPubkey: Uint8Array;
|
|
518
431
|
/** BOLT11 payment hash, hex — from the trader's OWN invoice decode. */
|
|
519
432
|
paymentHash: string;
|
|
520
|
-
/** From {@link unilateralClaimDelay} over the trader's OWN server info
|
|
521
|
-
*
|
|
522
|
-
* derive from this same value — one rounding, shared across all three tiers. */
|
|
433
|
+
/** From {@link unilateralClaimDelay} over the trader's OWN server info; all three unilateral
|
|
434
|
+
* tiers derive from it. */
|
|
523
435
|
claimDelay: number;
|
|
436
|
+
/** Binding quote field. Optional only for rebuilding pre-upgrade scripts. */
|
|
437
|
+
refundWithoutReceiverDelay?: number;
|
|
524
438
|
/** Emulator x-only key (32 bytes). */
|
|
525
439
|
emulatorPubkey: Uint8Array;
|
|
526
440
|
/** Where a refund must pay: the trader's P2TR pkScript (34 bytes). Also
|
|
527
441
|
* the refund covenants' destination. */
|
|
528
442
|
refundPkScript: Uint8Array;
|
|
529
|
-
/** The trader's own key — VHTLC's `sender` role
|
|
530
|
-
* interactive refund-side leaf; the trader generates and persists it
|
|
531
|
-
* (see {@link requestLightningSend}'s own obligations). */
|
|
443
|
+
/** The trader's own key — VHTLC's `sender` role, on every interactive refund-side leaf. */
|
|
532
444
|
senderPubkey: Uint8Array;
|
|
533
|
-
/** The solver's
|
|
534
|
-
*
|
|
535
|
-
* covenant key can be derived; the trader does not otherwise use or trust
|
|
536
|
-
* this value. P2TR pkScript, 34 bytes. */
|
|
445
|
+
/** The solver's claim destination (`profile.receiver_pk_script`, P2TR), used only to derive
|
|
446
|
+
* `nonInteractiveClaim`'s covenant key; not otherwise trusted. */
|
|
537
447
|
receiverPkScript: Uint8Array;
|
|
538
|
-
/** LEGACY REBUILD ONLY
|
|
539
|
-
*
|
|
540
|
-
* timelocked refund leaf shipped; {@link matchQuotedLockup} passes it when
|
|
541
|
-
* the quote's own address says the solver quoted that shape. */
|
|
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}. */
|
|
542
450
|
legacy?: "preTimelockedRefund";
|
|
543
451
|
}): InstanceType<typeof VHTLC.ScriptV2>;
|
|
544
|
-
/** Every input {@link lightningSendContract} builds from.
|
|
545
|
-
* builder rather than restated, so the two cannot drift.
|
|
546
|
-
*
|
|
547
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
548
|
-
*/
|
|
452
|
+
/** Every input {@link lightningSendContract} builds from. */
|
|
549
453
|
type LightningSendContractParams = Parameters<typeof lightningSendContract>[0];
|
|
550
454
|
/** The BOLT11 facts the trader read from its OWN decode — this module takes
|
|
551
|
-
* the facts, not the decoder, so any wallet's existing decoder serves
|
|
552
|
-
*
|
|
553
|
-
* A root export because `CorridorOverrides.lightning.decode` returns it: a
|
|
554
|
-
* caller wiring that override names this type.
|
|
555
|
-
*/
|
|
455
|
+
* the facts, not the decoder, so any wallet's existing decoder serves
|
|
456
|
+
* (`CorridorOverrides.lightning.decode` returns it). */
|
|
556
457
|
interface InvoiceFacts {
|
|
557
458
|
/** The raw BOLT11 — what travels in the request profile. */
|
|
558
459
|
raw: string;
|
|
@@ -564,35 +465,19 @@ interface InvoiceFacts {
|
|
|
564
465
|
expiresAt: number;
|
|
565
466
|
}
|
|
566
467
|
/**
|
|
567
|
-
* The lightning-send user flow
|
|
568
|
-
*
|
|
569
|
-
*
|
|
570
|
-
* (`wallet.send({ address, amount })`) before `quote.valid_until`, after
|
|
571
|
-
* which the user may go OFFLINE: filling is non-interactive. Success reveals
|
|
572
|
-
* the preimage in the solver's claim witness (also served via status as
|
|
573
|
-
* `settled`); failure refunds to `refundAddress`.
|
|
574
|
-
*
|
|
575
|
-
* Throws {@link SwapRefusal} (closed reason), {@link AddressMismatch} (never
|
|
576
|
-
* fund), a gate error with a stable `reason`, or
|
|
577
|
-
* {@link LockupRegistrationFailed} — the last one alone means the quote is
|
|
578
|
-
* still good and the same call can be retried once local storage is.
|
|
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`.
|
|
579
471
|
*
|
|
580
|
-
*
|
|
581
|
-
*
|
|
582
|
-
*
|
|
583
|
-
* moment it lands and out of generic coin selection, and a persistence failure
|
|
584
|
-
* throws while nothing is funded. `RfqSwapManager` re-registers as a backstop
|
|
585
|
-
* for older records; a repeat write is a no-op.
|
|
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.
|
|
586
475
|
*
|
|
587
|
-
*
|
|
588
|
-
*
|
|
589
|
-
*
|
|
590
|
-
* is
|
|
591
|
-
*
|
|
592
|
-
* without it — but it needs the SOLVER's active cooperation, not just
|
|
593
|
-
* infrastructure uptime.
|
|
594
|
-
*
|
|
595
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
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.
|
|
596
481
|
*/
|
|
597
482
|
declare function requestLightningSend(wallet: IWallet, transport: RfqTransport, params: {
|
|
598
483
|
invoice: InvoiceFacts;
|
|
@@ -610,12 +495,10 @@ declare function requestLightningSend(wallet: IWallet, transport: RfqTransport,
|
|
|
610
495
|
fundAmount: number;
|
|
611
496
|
/** The covenant's scriptPubKey, for watching the lockup and its spend. */
|
|
612
497
|
swapPkScript: Uint8Array;
|
|
613
|
-
/** The covenant itself. Hand it to `RfqSwapManager` as the record's
|
|
614
|
-
* `
|
|
615
|
-
* cannot retire the row this call just wrote. */
|
|
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. */
|
|
616
500
|
script: InstanceType<typeof VHTLC.ScriptV2>;
|
|
617
|
-
/** Where a failed swap refunds
|
|
618
|
-
* decoded from, so the quote and the covenant always name one script. */
|
|
501
|
+
/** Where a failed swap refunds; the address `secrets.pkScript` was decoded from. */
|
|
619
502
|
refundAddress: string;
|
|
620
503
|
/** The VHTLC `sender` x-only key, bound into the covenant. Public. */
|
|
621
504
|
senderPubkey: Uint8Array;
|
|
@@ -623,31 +506,100 @@ declare function requestLightningSend(wallet: IWallet, transport: RfqTransport,
|
|
|
623
506
|
* it holds nothing secret. */
|
|
624
507
|
secrets: ProvisionedKey;
|
|
625
508
|
/**
|
|
626
|
-
* Every input the covenant was built from, as it was AT REQUEST TIME
|
|
627
|
-
*
|
|
628
|
-
*
|
|
629
|
-
*
|
|
630
|
-
* come from this wallet's own `getArkadeInfo()`, `emulatorPubkey` from a
|
|
631
|
-
* per-network pin, `refundPkScript` from `secrets` — decoded from the
|
|
632
|
-
* refund address at provisioning time, the same address this call returns
|
|
633
|
-
* as `refundAddress`.
|
|
634
|
-
*
|
|
635
|
-
* All public. Persisting them is optional: this call also registers the
|
|
636
|
-
* lockup as a contract, and that row is where `rebuildRfqSwap` takes its
|
|
637
|
-
* covenant from — see `rfqRecord.ts`. Keep a copy only to hold a record
|
|
638
|
-
* that rebuilds without the wallet's contract store, and keep it as
|
|
639
|
-
* `VHTLCV2ContractHandler.serializeParams(script.options)`, the shape the
|
|
640
|
-
* rebuild accepts.
|
|
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.
|
|
641
513
|
*/
|
|
642
514
|
contractParams: LightningSendContractParams;
|
|
643
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
|
+
}>;
|
|
644
599
|
/** The rfq_request for `arkade:BTC->onchain:BTC`. Exact-out means "this much
|
|
645
600
|
* lands in the L1 HTLC". `senderPubkey` is the user's own key for the
|
|
646
601
|
* VHTLC's sender-side leaves — same role as in {@link lightningSendRequest}.
|
|
647
|
-
* On the wire it's `client_refund_pubkey`, same as there.
|
|
648
|
-
*
|
|
649
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
650
|
-
*/
|
|
602
|
+
* On the wire it's `client_refund_pubkey`, same as there. */
|
|
651
603
|
declare const onchainSendRequest: (input: {
|
|
652
604
|
rfqId: string;
|
|
653
605
|
/** `sha256(P)`, hex — user-chosen; see {@link paymentHashOf}. */
|
|
@@ -660,15 +612,9 @@ declare const onchainSendRequest: (input: {
|
|
|
660
612
|
amount: number;
|
|
661
613
|
amountSide: "from" | "to";
|
|
662
614
|
}) => Record<string, unknown>;
|
|
663
|
-
/** The rfq_request for `lightning:BTC->arkade:BTC
|
|
664
|
-
*
|
|
665
|
-
* `
|
|
666
|
-
* appears in a claim witness. `payoutPubkey` is the trader's own x-only
|
|
667
|
-
* Arkade key — the covenant's `receiver` role on this leg, so the trader can
|
|
668
|
-
* claim the lockup itself without covclaimd.
|
|
669
|
-
*
|
|
670
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
671
|
-
*/
|
|
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. */
|
|
672
618
|
declare const lightningReceiveRequest: (input: {
|
|
673
619
|
rfqId: string;
|
|
674
620
|
/** `H = sha256(P)`, hex — trader-chosen; see {@link paymentHashOf}. */
|
|
@@ -677,21 +623,15 @@ declare const lightningReceiveRequest: (input: {
|
|
|
677
623
|
payoutAddress: string;
|
|
678
624
|
/** Trader's x-only arkade key — the covenant's `receiver` role. */
|
|
679
625
|
payoutPubkey: Uint8Array;
|
|
680
|
-
/** `P` sealed to covclaimd, base64 — `sealClaimPacket(...).ciphertext`.
|
|
681
|
-
*
|
|
682
|
-
* the wire entirely, since the solver refuses an empty packet. */
|
|
626
|
+
/** `P` sealed to covclaimd, base64 — `sealClaimPacket(...).ciphertext`. Omitted from the wire
|
|
627
|
+
* when there is no covclaimd: the solver refuses an empty packet. */
|
|
683
628
|
claimPacket?: string;
|
|
684
629
|
amount: number;
|
|
685
630
|
amountSide: "from" | "to";
|
|
686
631
|
}) => Record<string, unknown>;
|
|
687
|
-
/** The rfq_request for `onchain:BTC->arkade:BTC`. The user funds the L1 HTLC
|
|
688
|
-
*
|
|
689
|
-
*
|
|
690
|
-
* funding. `payoutPubkey` is the trader's own x-only Arkade key — the
|
|
691
|
-
* covenant's `receiver` role, same as the Lightning receive leg's.
|
|
692
|
-
*
|
|
693
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
694
|
-
*/
|
|
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. */
|
|
695
635
|
declare const onchainReceiveRequest: (input: {
|
|
696
636
|
rfqId: string;
|
|
697
637
|
paymentHash: string;
|
|
@@ -711,10 +651,8 @@ declare const onchainReceiveRequest: (input: {
|
|
|
711
651
|
* The pure core of {@link requestOnchainSend}: derive BOTH contracts locally
|
|
712
652
|
* from the quote's binding fields plus the user's own data, and refuse on any
|
|
713
653
|
* mismatch. Binding: `solver_pubkey`, `refund_locktime`, `htlc_pubkey`,
|
|
714
|
-
* `htlc_locktime`, `min_confirmations
|
|
715
|
-
* are compare-only.
|
|
716
|
-
*
|
|
717
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
654
|
+
* `htlc_locktime`, `min_confirmations`, `refund_without_receiver_delay` when
|
|
655
|
+
* present; `lockup_address` and `htlc_address` are compare-only.
|
|
718
656
|
*/
|
|
719
657
|
declare function deriveOnchainSend(input: {
|
|
720
658
|
quote: RfqQuote;
|
|
@@ -736,42 +674,33 @@ declare function deriveOnchainSend(input: {
|
|
|
736
674
|
* so the row can never key on a script other than the derived one. */
|
|
737
675
|
script: InstanceType<typeof VHTLC.ScriptV2>;
|
|
738
676
|
htlc: OnchainHtlc;
|
|
739
|
-
/** The inputs {@link htlc} was built from
|
|
740
|
-
*
|
|
741
|
-
* contract is Bitcoin L1 — there is no Arkade contract row for it, so a
|
|
742
|
-
* consumer persisting the swap has no other route to rebuilding it. */
|
|
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). */
|
|
743
679
|
htlcParams: OnchainHtlcParams;
|
|
744
|
-
/** Echoed from the input
|
|
745
|
-
*
|
|
746
|
-
* {@link onchainSendProfile} reads it from here. */
|
|
680
|
+
/** Echoed from the input so the result fully describes the L1 half
|
|
681
|
+
* ({@link onchainSendProfile} reads it). */
|
|
747
682
|
l1Network: OnchainNetwork;
|
|
748
683
|
refundLocktime: number;
|
|
684
|
+
/** The quote's solo-refund delay; undefined when the lockup uses the base ladder. */
|
|
685
|
+
refundWithoutReceiverDelay: number | undefined;
|
|
749
686
|
htlcLocktime: number;
|
|
750
687
|
minConfirmations: number;
|
|
688
|
+
expectedAmount: number;
|
|
751
689
|
};
|
|
752
690
|
/**
|
|
753
691
|
* The `arkade:BTC->onchain:BTC` user flow, mirroring `requestLightningSend`:
|
|
754
692
|
* quote → derive BOTH contracts locally → verify → gate. Pure of funding —
|
|
755
693
|
* the caller funds `address` with its own wallet before `quote.valid_until`.
|
|
756
694
|
*
|
|
757
|
-
* Registers the arkade lockup before returning
|
|
758
|
-
*
|
|
759
|
-
* the one throw here that does not mean "walk away from this quote". The L1
|
|
760
|
-
* HTLC is not a contract row: it lives on bitcoin, not on Ark, and the wallet's
|
|
761
|
-
* contract manager knows nothing of it.
|
|
695
|
+
* Registers the arkade lockup before returning, as {@link requestLightningSend} does (the L1 HTLC
|
|
696
|
+
* has no contract row).
|
|
762
697
|
*
|
|
763
698
|
* Two obligations, both LOUD:
|
|
764
|
-
* - **Persist `secrets` (with the record) BEFORE funding.** On
|
|
765
|
-
*
|
|
766
|
-
*
|
|
767
|
-
*
|
|
768
|
-
*
|
|
769
|
-
* - **Stay claim-capable.** Unlike lightning-send the user cannot go fully
|
|
770
|
-
* offline: it must claim the L1 HTLC (`awaitOnchainFill` →
|
|
771
|
-
* `claimOnchainFill`) before `htlc.refundLocktime`. Missing that window
|
|
772
|
-
* forfeits the fill and falls back to the Arkade covenant refund.
|
|
773
|
-
*
|
|
774
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
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.
|
|
775
704
|
*/
|
|
776
705
|
declare function requestOnchainSend(wallet: IWallet, transport: RfqTransport, params: {
|
|
777
706
|
amount: number;
|
|
@@ -790,6 +719,8 @@ declare function requestOnchainSend(wallet: IWallet, transport: RfqTransport, pa
|
|
|
790
719
|
/** The user's OWN arkade lockup derivation — the only address to fund. */
|
|
791
720
|
address: string;
|
|
792
721
|
fundAmount: number;
|
|
722
|
+
/** What the solver's L1 fill must carry — persist it with the record. */
|
|
723
|
+
expectedAmount: number;
|
|
793
724
|
swapPkScript: Uint8Array;
|
|
794
725
|
/** The arkade covenant itself — the record's `lockup` for
|
|
795
726
|
* `RfqSwapManager`, same role as {@link requestLightningSend}'s. */
|
|
@@ -797,34 +728,18 @@ declare function requestOnchainSend(wallet: IWallet, transport: RfqTransport, pa
|
|
|
797
728
|
refundAddress: string;
|
|
798
729
|
/** The EXPECTED L1 fill, derived locally — watch and claim against this. */
|
|
799
730
|
htlc: OnchainHtlc;
|
|
800
|
-
/** The inputs {@link htlc} was built from — persist these to rebuild it
|
|
801
|
-
* after a restart
|
|
802
|
-
*
|
|
803
|
-
* lockup there is no contract row holding its parameters. Persist
|
|
804
|
-
* `htlc.address` alongside them (`OnchainSendProfile.htlcAddress`): the
|
|
805
|
-
* rebuild checks the two against each other, which is the only check
|
|
806
|
-
* available on a leg with no second copy of its covenant.
|
|
807
|
-
*
|
|
808
|
-
* `onchainSendProfile(result)` does all of that mapping for you; prefer it
|
|
809
|
-
* to reading these fields across by hand. */
|
|
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. */
|
|
810
734
|
htlcParams: OnchainHtlcParams;
|
|
811
|
-
/**
|
|
812
|
-
*
|
|
813
|
-
*
|
|
814
|
-
* Returned because it is NOT the ark network name and cannot be recovered
|
|
815
|
-
* from one by inspection: this call maps `info.network` through a private
|
|
816
|
-
* narrowing where signet, mutinynet and testnet4 all become `"testnet"`.
|
|
817
|
-
* A caller reconstructing it from context would be re-deriving a mapping
|
|
818
|
-
* it cannot see, and a value the profile needs verbatim.
|
|
819
|
-
*/
|
|
735
|
+
/** Which bitcoin network the L1 HTLC was derived for. NOT the ark network name: signet,
|
|
736
|
+
* mutinynet and testnet4 all become `"testnet"`. */
|
|
820
737
|
l1Network: OnchainNetwork;
|
|
821
738
|
/** `profile.min_confirmations`; gates when the L1 fill becomes claimable,
|
|
822
739
|
* and part of what a restored swap needs to drive its own claim. */
|
|
823
740
|
minConfirmations: number;
|
|
824
|
-
/** The arkade lockup's refund deadline, as the covenant was built with it.
|
|
825
|
-
*
|
|
826
|
-
* the wire, a solver may carry the value in `profile` instead, and
|
|
827
|
-
* `deriveOnchainSend` is what settles which one this contract used. */
|
|
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. */
|
|
828
743
|
refundLocktime: number;
|
|
829
744
|
/** The VHTLC `sender` x-only key, bound into the covenant. Public. */
|
|
830
745
|
senderPubkey: Uint8Array;
|
|
@@ -833,21 +748,21 @@ declare function requestOnchainSend(wallet: IWallet, transport: RfqTransport, pa
|
|
|
833
748
|
* `mustPersistPreimage` says the wallet could not derive P. */
|
|
834
749
|
secrets: ProvisionedClaimSecret;
|
|
835
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;
|
|
836
756
|
/**
|
|
837
757
|
* Bind the SOLVER's hold invoice to the quote and to the trader's own `H`.
|
|
838
758
|
*
|
|
839
|
-
*
|
|
840
|
-
*
|
|
841
|
-
*
|
|
842
|
-
* funded. NEVER publish an invoice that has not passed this.
|
|
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.
|
|
843
762
|
*
|
|
844
|
-
* The decoder is injected
|
|
845
|
-
*
|
|
846
|
-
*
|
|
847
|
-
* summary of an adversary's invoice checks nothing.
|
|
848
|
-
*
|
|
849
|
-
* There is no check for "is this actually a hold invoice": on the wire it is
|
|
850
|
-
* indistinguishable from an ordinary one.
|
|
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.
|
|
851
766
|
*
|
|
852
767
|
* Reasons: `invoice_undecodable` | `invoice_hash_mismatch` |
|
|
853
768
|
* `invoice_amount_mismatch` | `quote_malformed`.
|
|
@@ -866,9 +781,8 @@ declare const verifyReceiveInvoice: (input: {
|
|
|
866
781
|
/** Compile the RECEIVE-direction VHTLC: the same suite-carrying tree as {@link
|
|
867
782
|
* lightningSendContract} with the roles inverted — the trader is the
|
|
868
783
|
* `receiver` (it generated `P` and claims the lockup with it), the solver is
|
|
869
|
-
* the `sender` (it funds the lockup and holds the refund recourse).
|
|
870
|
-
*
|
|
871
|
-
* of `lightningSendContract`.
|
|
784
|
+
* the `sender` (it funds the lockup and holds the refund recourse). Shared by both receive
|
|
785
|
+
* corridors.
|
|
872
786
|
*
|
|
873
787
|
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
874
788
|
*/
|
|
@@ -879,7 +793,7 @@ declare function lightningReceiveContract(params: {
|
|
|
879
793
|
/** Binding field #2: the SOLVER's own refund deadline on these legs, from
|
|
880
794
|
* the quote — after it the solver may reclaim an unclaimed lockup. */
|
|
881
795
|
refundLocktime: number;
|
|
882
|
-
/** The
|
|
796
|
+
/** The Arkade operator's x-only key — the trader's OWN connection. */
|
|
883
797
|
operatorPubkey: Uint8Array;
|
|
884
798
|
/** `sha256(P)`, hex — the trader's OWN preimage hash. */
|
|
885
799
|
paymentHash: string;
|
|
@@ -909,12 +823,8 @@ type LightningReceiveContractParams = Parameters<typeof lightningReceiveContract
|
|
|
909
823
|
/**
|
|
910
824
|
* The pure core of {@link requestLightningReceive}: derive the solver-funded
|
|
911
825
|
* covenant locally from the quote's binding fields plus the trader's own data
|
|
912
|
-
* and refuse on any address mismatch. The trader funds nothing on Arkade
|
|
913
|
-
*
|
|
914
|
-
* the lockup the solver will fund must be the tree whose claim paths pay the
|
|
915
|
-
* trader.
|
|
916
|
-
*
|
|
917
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
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.
|
|
918
828
|
*/
|
|
919
829
|
declare function deriveLightningReceive(input: {
|
|
920
830
|
quote: RfqQuote;
|
|
@@ -932,42 +842,23 @@ declare function deriveLightningReceive(input: {
|
|
|
932
842
|
/** The solver's hold invoice on `H` — what the trader pays to arm the swap. */
|
|
933
843
|
invoice: string;
|
|
934
844
|
refundLocktime: number;
|
|
935
|
-
/** Every input the covenant was built from
|
|
936
|
-
* `requestLightningSend`'s result for why a consumer needs them. */
|
|
845
|
+
/** Every input the covenant was built from; see `requestLightningSend`'s result. */
|
|
937
846
|
contractParams: LightningReceiveContractParams;
|
|
938
847
|
};
|
|
939
848
|
/**
|
|
940
|
-
* The `lightning:BTC->arkade:BTC` user flow: quote → derive the covenant
|
|
941
|
-
*
|
|
942
|
-
*
|
|
943
|
-
*
|
|
944
|
-
* held, the solver funds the lockup; the trader claims it with `P` (its own,
|
|
945
|
-
* generated here) — itself via the collaborative claim leaf
|
|
946
|
-
* ({@link claimReceiveLockup} in `claim.ts`), or via covclaimd if it is
|
|
947
|
-
* offline.
|
|
948
|
-
*
|
|
949
|
-
* Three obligations, all of them before the invoice is handed to a payer:
|
|
950
|
-
*
|
|
951
|
-
* 1. Persist `secrets` and `expectedAmount`. The preimage and the payout key
|
|
952
|
-
* re-derive from `secrets` (or, on a non-HD wallet, are carried by it), and
|
|
953
|
-
* without `expectedAmount` the claim has nothing to compare the funded
|
|
954
|
-
* value against.
|
|
955
|
-
* 2. Stay online. covclaimd cannot claim this covenant today, so the offline
|
|
956
|
-
* path the claim packet exists for does not run yet: an unclaimed lockup is
|
|
957
|
-
* reclaimed by the solver at `refund_locktime` and the payer refunded.
|
|
958
|
-
* 3. On {@link LockupRegistrationFailed}, call this function again once the
|
|
959
|
-
* store is working. The failed attempt is inert — it returned no invoice,
|
|
960
|
-
* so nothing can be paid into the lockup nobody is watching — and the new
|
|
961
|
-
* call derives its own preimage and `rfq_id`. Re-registering `error.script`
|
|
962
|
-
* does NOT resume it: the invoice and `secrets` were never handed back.
|
|
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`).
|
|
963
853
|
*
|
|
964
|
-
*
|
|
965
|
-
* `H` and the quote ({@link verifyReceiveInvoice}) before it is returned —
|
|
966
|
-
* nothing publishable comes back from a failed check, registration included.
|
|
967
|
-
* Pay before `invoiceExpiresAt`: the hold-invoice window is minutes, not the
|
|
968
|
-
* quote's `valid_until`.
|
|
854
|
+
* Three obligations, all before the invoice is handed to a payer:
|
|
969
855
|
*
|
|
970
|
-
*
|
|
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.
|
|
971
862
|
*/
|
|
972
863
|
declare function requestLightningReceive(wallet: IWallet, transport: RfqTransport, params: {
|
|
973
864
|
amount: number;
|
|
@@ -975,16 +866,13 @@ declare function requestLightningReceive(wallet: IWallet, transport: RfqTranspor
|
|
|
975
866
|
/** Co-signer key override (33-byte compressed hex); see
|
|
976
867
|
* {@link resolveEmulatorPubkey}. */
|
|
977
868
|
emulatorPubkey?: string;
|
|
978
|
-
/** covclaimd's 33-byte compressed pubkey
|
|
979
|
-
*
|
|
980
|
-
*
|
|
981
|
-
* sent, and claiming the lockup before the quote's `refund_locktime` is
|
|
982
|
-
* then the caller's own job — miss that window and the fill is lost.
|
|
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.
|
|
983
872
|
* Never substitute a throwaway key — nobody could open it. */
|
|
984
873
|
covclaimdPubkey?: Uint8Array;
|
|
985
|
-
/** The caller's own BOLT11 decoder, applied to the SOLVER's invoice.
|
|
986
|
-
*
|
|
987
|
-
* the check whose absence loses the whole payment. */
|
|
874
|
+
/** The caller's own BOLT11 decoder, applied to the SOLVER's invoice. Required: skipping
|
|
875
|
+
* this check can lose the whole payment. */
|
|
988
876
|
decodeInvoice: (bolt11: string) => InvoiceFacts;
|
|
989
877
|
/** Opt-in ceiling, in sats, on what the payer will be asked for. */
|
|
990
878
|
maxPayAmount?: number;
|
|
@@ -997,13 +885,11 @@ declare function requestLightningReceive(wallet: IWallet, transport: RfqTranspor
|
|
|
997
885
|
invoice: string;
|
|
998
886
|
/** What the trader pays: the quote's `from_amount`. */
|
|
999
887
|
payAmount: number;
|
|
1000
|
-
/** What the solver's lockup must carry: the quote's `to_amount`. Persist
|
|
1001
|
-
*
|
|
1002
|
-
* captured at claim time instead it would be whatever the solver funded. */
|
|
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. */
|
|
1003
890
|
expectedAmount: number;
|
|
1004
891
|
/** Last moment the invoice can be paid, unix seconds: `min(invoice
|
|
1005
|
-
* expiry, valid_until)`.
|
|
1006
|
-
* here is stale before the caller reads it; derive one at display time. */
|
|
892
|
+
* expiry, valid_until)`. */
|
|
1007
893
|
invoiceExpiresAt: number;
|
|
1008
894
|
/** The trader's OWN derivation of the lockup the solver must fund. */
|
|
1009
895
|
address: string;
|
|
@@ -1026,8 +912,6 @@ declare function requestLightningReceive(wallet: IWallet, transport: RfqTranspor
|
|
|
1026
912
|
* funds — and refuse on any mismatch. Binding: `solver_pubkey`,
|
|
1027
913
|
* `refund_locktime`, `claim_pubkey`, `htlc_locktime`, `min_confirmations`;
|
|
1028
914
|
* `lockup_address` and `htlc_address` are compare-only.
|
|
1029
|
-
*
|
|
1030
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1031
915
|
*/
|
|
1032
916
|
declare function deriveOnchainReceive(input: {
|
|
1033
917
|
quote: RfqQuote;
|
|
@@ -1047,24 +931,20 @@ declare function deriveOnchainReceive(input: {
|
|
|
1047
931
|
script: InstanceType<typeof VHTLC.ScriptV2>;
|
|
1048
932
|
/** The L1 HTLC the trader funds, derived locally — fund only this. */
|
|
1049
933
|
htlc: OnchainHtlc;
|
|
934
|
+
/** The inputs {@link htlc} was derived from; a restore rebuilds it from these. */
|
|
935
|
+
htlcParams: OnchainHtlcParams;
|
|
1050
936
|
refundLocktime: number;
|
|
1051
937
|
htlcLocktime: number;
|
|
1052
938
|
minConfirmations: number;
|
|
1053
939
|
};
|
|
1054
940
|
/**
|
|
1055
941
|
* The `onchain:BTC->arkade:BTC` user flow: quote → derive BOTH contracts
|
|
1056
|
-
* locally → verify → gate. Returns the L1 HTLC to fund
|
|
1057
|
-
* `fundAmount`
|
|
1058
|
-
*
|
|
1059
|
-
* the solver funds the Arkade lockup; the trader claims it with `P` (its
|
|
1060
|
-
* own), itself or via covclaimd.
|
|
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`.
|
|
1061
945
|
*
|
|
1062
|
-
* Persist `secrets` BEFORE funding
|
|
1063
|
-
*
|
|
1064
|
-
* `refundPubkey`) opens at `htlc.refundLocktime` — `buildHtlcRefund` takes it
|
|
1065
|
-
* back from there.
|
|
1066
|
-
*
|
|
1067
|
-
* @deprecated Internal to `client.quote()` and `client.accept()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
946
|
+
* Persist `secrets` BEFORE funding. If the swap never settles, the L1 refund leaf opens at
|
|
947
|
+
* `htlc.refundLocktime` (see `buildHtlcRefund`).
|
|
1068
948
|
*/
|
|
1069
949
|
declare function requestOnchainReceive(wallet: IWallet, transport: RfqTransport, params: {
|
|
1070
950
|
amount: number;
|
|
@@ -1074,9 +954,8 @@ declare function requestOnchainReceive(wallet: IWallet, transport: RfqTransport,
|
|
|
1074
954
|
emulatorPubkey?: string;
|
|
1075
955
|
/** Trader's x-only L1 key for the HTLC's refund leaf. */
|
|
1076
956
|
refundPubkey: Uint8Array;
|
|
1077
|
-
/** covclaimd's 33-byte compressed pubkey
|
|
1078
|
-
*
|
|
1079
|
-
* caller's own; see {@link requestLightningReceive}. */
|
|
957
|
+
/** covclaimd's 33-byte compressed pubkey. Only an exact-out request (`amountSide: "to"`)
|
|
958
|
+
* is guaranteed a claim packet; see {@link requestLightningReceive}. */
|
|
1080
959
|
covclaimdPubkey?: Uint8Array;
|
|
1081
960
|
rfqId?: string;
|
|
1082
961
|
}): Promise<{
|
|
@@ -1101,4 +980,4 @@ declare function requestOnchainReceive(wallet: IWallet, transport: RfqTransport,
|
|
|
1101
980
|
secrets: ProvisionedClaimSecret;
|
|
1102
981
|
}>;
|
|
1103
982
|
|
|
1104
|
-
export {
|
|
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 };
|