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