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