@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
|
@@ -1,3489 +0,0 @@
|
|
|
1
|
-
import { DiscoveredMarket } from '@arkade-os/solver-discovery';
|
|
2
|
-
import { IWallet, ProvisionedKey, ProvisionedClaimSecret, ArkProvider, RestIndexerProvider, VHTLC, Identity, IContractManager, NetworkName, asset } from '@arkade-os/sdk';
|
|
3
|
-
import { D as RfqStatus, e as RfqTransport, O as OnchainHtlc, l as ChainUtxo, C as ChainSource, y as OnchainHtlcPhase } from './rfq-BO6o7NwS.cjs';
|
|
4
|
-
|
|
5
|
-
/** @deprecated Use `Outcome`. Moved off the package root to `@arkade-os/swap/protocol`. */
|
|
6
|
-
type AssetSwapStatus = "pending" | "cancelling" | "fulfilled" | "cancelled" | "recoverable" | "awaiting_fill" | "claimable" | "claimed" | "refunded_l1";
|
|
7
|
-
/** The sentinel asset id for BTC itself, as opposed to a 68-hex asset id.
|
|
8
|
-
* Lives here with the {@link AssetSwap} fields it describes so the market and
|
|
9
|
-
* restore layers share one spelling instead of re-typing the literal.
|
|
10
|
-
*
|
|
11
|
-
* @deprecated A record-local sentinel, not a public id. The v2 asset id is `btcOn(rail, network)`, and `client.swaps()` projects records that carry it. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
12
|
-
*/
|
|
13
|
-
declare const BTC_ASSET_ID = "btc";
|
|
14
|
-
/**
|
|
15
|
-
* The record fields a wallet-provisioned secret becomes — what
|
|
16
|
-
* {@link swapSecretsToRecord} emits, and what every record type carrying swap
|
|
17
|
-
* secrets embeds.
|
|
18
|
-
*
|
|
19
|
-
* A named type rather than four fields restated per record: the mapper and the
|
|
20
|
-
* records it feeds must agree exactly, and a record that silently omits one of
|
|
21
|
-
* these round-trips a swap whose preimage cannot be re-derived. Embedding makes
|
|
22
|
-
* the omission a compile error instead.
|
|
23
|
-
*
|
|
24
|
-
* **Only `preimageHex` is secret.** `signingDescriptor` and `preimageSaltHex`
|
|
25
|
-
* are public derivation inputs — they must survive a field-mapped backend, but
|
|
26
|
-
* they leak nothing without the seed.
|
|
27
|
-
*
|
|
28
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
29
|
-
*/
|
|
30
|
-
interface SwapSecretsProjection {
|
|
31
|
-
/**
|
|
32
|
-
* The wallet descriptor this swap's sender key comes from — a fresh HD
|
|
33
|
-
* child, or a static wallet's `tr(pubkey)`. Public — the signer
|
|
34
|
-
* re-derives from the wallet, so the record carries no key material.
|
|
35
|
-
*/
|
|
36
|
-
signingDescriptor?: string;
|
|
37
|
-
/** P, hex, when it cannot be re-derived from the seed at all: the user
|
|
38
|
-
* supplied it, or the signer cannot sign deterministically. The swap's only
|
|
39
|
-
* claim secret when present. */
|
|
40
|
-
preimageHex?: string;
|
|
41
|
-
/**
|
|
42
|
-
* The salt P derives from, hex, on the salted arm — what a static wallet
|
|
43
|
-
* gets instead of storing P. **Public**, and unlike every other field here
|
|
44
|
-
* it is minted per swap: it is what stops one repeating key from handing
|
|
45
|
-
* every swap the same preimage.
|
|
46
|
-
*/
|
|
47
|
-
preimageSaltHex?: string;
|
|
48
|
-
}
|
|
49
|
-
/** The row {@link AssetSwapRepository} stores. A custom storage backend is
|
|
50
|
-
* written against this, which is why it is a root export rather than a
|
|
51
|
-
* `/protocol` one — the interface it appears in is part of the v2 surface.
|
|
52
|
-
* What it is NOT is the v2 client's own record: that is `SwapRecord`, and
|
|
53
|
-
* `client.swaps()` projects it as `Swap`. */
|
|
54
|
-
interface AssetSwap extends SwapSecretsProjection {
|
|
55
|
-
/** Funding txid — the swap's identity. */
|
|
56
|
-
id: string;
|
|
57
|
-
/** 'btc' or a 68-hex asset id. */
|
|
58
|
-
fromAsset: string;
|
|
59
|
-
toAsset: string;
|
|
60
|
-
/** Atomic amounts as strings (bigint is not JSON-safe). */
|
|
61
|
-
fromAmount: string;
|
|
62
|
-
/** The covenant wantAmount — a floor, the fill pays >= this. */
|
|
63
|
-
toAmount: string;
|
|
64
|
-
swapAddress: string;
|
|
65
|
-
/** Hex pkScript of the swap contract — the indexer monitoring key. */
|
|
66
|
-
swapPkScript: string;
|
|
67
|
-
/** TLV offer — needed to rebuild the contract for cancel. */
|
|
68
|
-
offerHex: string;
|
|
69
|
-
fundingTxid: string;
|
|
70
|
-
spentTxid?: string;
|
|
71
|
-
status: AssetSwapStatus;
|
|
72
|
-
createdAt: number;
|
|
73
|
-
completedAt?: number;
|
|
74
|
-
/** RFQ pair string, e.g. `arkade:BTC->onchain:BTC`. */
|
|
75
|
-
pair?: string;
|
|
76
|
-
/** `sha256(P)`, hex. Public, and how a restore confirms a candidate
|
|
77
|
-
* derivation is the right one. */
|
|
78
|
-
paymentHash?: string;
|
|
79
|
-
/** The L1 HTLC's pkScript, hex — the chain-watch key. */
|
|
80
|
-
htlcPkScriptHex?: string;
|
|
81
|
-
htlcLocktime?: number;
|
|
82
|
-
/** The L1 funding txid, once observed. */
|
|
83
|
-
l1Txid?: string;
|
|
84
|
-
}
|
|
85
|
-
/** The consumer read: a broken backend reads as no swaps rather than crashing
|
|
86
|
-
* a history view. Mutations must use {@link getAssetSwapsOrThrow} instead —
|
|
87
|
-
* swallowing the read there would let "the backend is gone" masquerade as "no
|
|
88
|
-
* such swap" and skip the write silently.
|
|
89
|
-
*
|
|
90
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
91
|
-
*/
|
|
92
|
-
declare const getAssetSwaps: (repository: AssetSwapRepository) => Promise<AssetSwap[]>;
|
|
93
|
-
/** Add a swap; no-op if the id is already stored. Returns the updated list.
|
|
94
|
-
* THROWS on a failed write — nothing irreversible may happen until this record
|
|
95
|
-
* is durable, so the caller must not fund on a failure.
|
|
96
|
-
*
|
|
97
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
98
|
-
*/
|
|
99
|
-
declare const addAssetSwap: (repository: AssetSwapRepository, swap: AssetSwap) => Promise<AssetSwap[]>;
|
|
100
|
-
/** Merge changes into a swap by id. Returns the updated list.
|
|
101
|
-
* THROWS on a failed read or write, like {@link addAssetSwap} — use this for a
|
|
102
|
-
* write that gates something irreversible. Transitions written *after* the
|
|
103
|
-
* irreversible act belong on {@link updateAssetSwapBestEffort}.
|
|
104
|
-
*
|
|
105
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
106
|
-
*/
|
|
107
|
-
declare const updateAssetSwap: (repository: AssetSwapRepository, id: string, changes: Partial<Omit<AssetSwap, "id">>) => Promise<AssetSwap[]>;
|
|
108
|
-
/**
|
|
109
|
-
* The record fields a wallet-provisioned secret becomes.
|
|
110
|
-
*
|
|
111
|
-
* `signingDescriptor` is public and always stored — it is what recovers the
|
|
112
|
-
* signer. Then at most one of: `preimageHex`, when the wallet says it cannot
|
|
113
|
-
* re-derive P and it becomes the swap's only claim secret; or
|
|
114
|
-
* `preimageSaltHex`, the public input a derivable-but-repeating key needs.
|
|
115
|
-
*
|
|
116
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
117
|
-
*/
|
|
118
|
-
declare const swapSecretsToRecord: (secrets: ProvisionedKey | ProvisionedClaimSecret) => SwapSecretsProjection & {
|
|
119
|
-
signingDescriptor: string;
|
|
120
|
-
};
|
|
121
|
-
/** Why a wallet cannot produce a swap's preimage.
|
|
122
|
-
*
|
|
123
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
124
|
-
*/
|
|
125
|
-
type PreimageBlockedReason =
|
|
126
|
-
/** The record carries no `signingDescriptor`. */
|
|
127
|
-
"no-secrets"
|
|
128
|
-
/** `preimageHex` or `preimageSaltHex` is present but not 32 bytes of hex. */
|
|
129
|
-
| "malformed-record"
|
|
130
|
-
/**
|
|
131
|
-
* Nothing to derive from: a descriptor that repeats across swaps, with
|
|
132
|
-
* neither a stored preimage nor a salt — or one this wallet holds no key
|
|
133
|
-
* for. Merged deliberately: `contractSigner` reports a key it does not
|
|
134
|
-
* hold as a plain `Error` for static wallets and a `ForeignDescriptorError`
|
|
135
|
-
* for HD ones, so splitting the two here would mean matching on message
|
|
136
|
-
* text, which is the thing this type exists to avoid. The `cause` carries
|
|
137
|
-
* whichever it was.
|
|
138
|
-
*/
|
|
139
|
-
| "not-derivable"
|
|
140
|
-
/** Derived, but it does not hash to the record's `paymentHash`. */
|
|
141
|
-
| "hash-mismatch";
|
|
142
|
-
/**
|
|
143
|
-
* The wallet cannot produce this swap's preimage, and which of the four ways
|
|
144
|
-
* is `reason`.
|
|
145
|
-
*
|
|
146
|
-
* Deliberately **not** {@link RefundNotLocallyPossibleError}: that one means
|
|
147
|
-
* "no local refund is possible", and `RfqSwapManager` acts on it by reporting
|
|
148
|
-
* `needs_counterparty`. A claim-path read failure is a different verdict, and
|
|
149
|
-
* borrowing the refund error would have the manager announce one for the
|
|
150
|
-
* other.
|
|
151
|
-
*
|
|
152
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
153
|
-
*/
|
|
154
|
-
declare class PreimageNotRecoverableError extends Error {
|
|
155
|
-
readonly reason: PreimageBlockedReason;
|
|
156
|
-
readonly name = "PreimageNotRecoverableError";
|
|
157
|
-
constructor(reason: PreimageBlockedReason, message: string, options?: {
|
|
158
|
-
cause?: unknown;
|
|
159
|
-
});
|
|
160
|
-
}
|
|
161
|
-
/**
|
|
162
|
-
* The preimage a swap record claims with — stored, or re-derived from the
|
|
163
|
-
* wallet.
|
|
164
|
-
*
|
|
165
|
-
* The record-shaped inverse of {@link swapSecretsToRecord}, and the one place
|
|
166
|
-
* that knows which of a record's fields `contractPreimage` needs. Wire claim
|
|
167
|
-
* paths here rather than composing it by hand: a caller that forgets to pass
|
|
168
|
-
* `preimageSaltHex` gets a *wrong* preimage from a wallet that can derive,
|
|
169
|
-
* not an error.
|
|
170
|
-
*
|
|
171
|
-
* Verifies the result against `paymentHash` when the record carries one. The
|
|
172
|
-
* salted arm has two inputs that can be wrong — the key and the salt — where
|
|
173
|
-
* the HD arm had one, and a wrong P otherwise surfaces as an opaque script
|
|
174
|
-
* failure at claim time, long after the mistake.
|
|
175
|
-
*
|
|
176
|
-
* Every refusal is a {@link PreimageNotRecoverableError} carrying a `reason`,
|
|
177
|
-
* so a caller can tell "this record predates the descriptor" from "the salt is
|
|
178
|
-
* corrupt" without reading message text.
|
|
179
|
-
*
|
|
180
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
181
|
-
*/
|
|
182
|
-
declare const preimageForSwapRecord: (wallet: IWallet, record: SwapSecretsProjection & {
|
|
183
|
-
paymentHash?: string;
|
|
184
|
-
}) => Promise<Uint8Array>;
|
|
185
|
-
|
|
186
|
-
/** True for the states after which the solver will report nothing further.
|
|
187
|
-
*
|
|
188
|
-
* @deprecated Recovery is internal to the drive; use `client.recover()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
189
|
-
*/
|
|
190
|
-
declare const isRfqTerminal: (state: string) => boolean;
|
|
191
|
-
/**
|
|
192
|
-
* Poll a swap's status until it reaches a terminal state.
|
|
193
|
-
*
|
|
194
|
-
* Same shape and conventions as {@link awaitOnchainFill}: a `pollMs` interval,
|
|
195
|
-
* an optional unix-seconds `deadline`, and a thrown error carrying a stable
|
|
196
|
-
* `reason` when that deadline passes.
|
|
197
|
-
*
|
|
198
|
-
* A `null` status (the solver has no record of this `rfq_id`) is treated as
|
|
199
|
-
* "not yet", not as an answer — a status route can legitimately 404 for a
|
|
200
|
-
* moment after a quote is issued. The deadline is what bounds that wait.
|
|
201
|
-
*
|
|
202
|
-
* Transport errors are NOT swallowed; a failing `status()` call rejects this
|
|
203
|
-
* function. Callers polling across a long refund window should expect to
|
|
204
|
-
* restart it after a network blip — nothing is lost by doing so, since the
|
|
205
|
-
* refund path this feeds is gated on an absolute timelock that does not
|
|
206
|
-
* expire.
|
|
207
|
-
*
|
|
208
|
-
* @deprecated Recovery is internal to the drive; use `client.recover()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
209
|
-
*/
|
|
210
|
-
declare function awaitRfqResolution(transport: RfqTransport, rfqId: string, options?: {
|
|
211
|
-
pollMs?: number;
|
|
212
|
-
deadline?: number;
|
|
213
|
-
}): Promise<RfqStatus>;
|
|
214
|
-
/** The indexer surface the lockup lookup needs. */
|
|
215
|
-
/**
|
|
216
|
-
* What a push needs from the operator: the broadcast pair, plus the info read
|
|
217
|
-
* that supplies `checkpointTapscript`.
|
|
218
|
-
*
|
|
219
|
-
* Narrow on purpose. A wallet's own connection satisfies it —
|
|
220
|
-
* `getArkadeBroadcaster()` for the pair and `getArkadeInfo()` for the read — so
|
|
221
|
-
* a plugin composes one from the wallet it already has and never opens a second
|
|
222
|
-
* connection of its own (#734). A full `ArkProvider` still fits, structurally.
|
|
223
|
-
*/
|
|
224
|
-
type SwapOperator = Pick<ArkProvider, "getInfo" | "submitTx" | "finalizeTx">;
|
|
225
|
-
/** @deprecated Recovery is internal to the drive; use `client.recover()`. Moved off the package root to `@arkade-os/swap/protocol`. */
|
|
226
|
-
type RefundIndexer = Pick<RestIndexerProvider, "getVtxos">;
|
|
227
|
-
/** A still-refundable virtual output sitting at the swap lockup.
|
|
228
|
-
*
|
|
229
|
-
* @deprecated Recovery is internal to the drive; use `client.recover()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
230
|
-
*/
|
|
231
|
-
interface LockupVtxo {
|
|
232
|
-
txid: string;
|
|
233
|
-
vout: number;
|
|
234
|
-
value: number;
|
|
235
|
-
/**
|
|
236
|
-
* The batch this output lived in expired and the operator swept it, so it
|
|
237
|
-
* is no longer a live leaf — it can be RECOVERED, but not spent offchain.
|
|
238
|
-
*
|
|
239
|
-
* It is still the trader's money and it is still visible, which is why
|
|
240
|
-
* {@link findLockupVtxos} returns it. What it is not is refundable by
|
|
241
|
-
* {@link pushRefundWithoutReceiver}: that builds an offchain Ark
|
|
242
|
-
* transaction, and the SDK's own predicates put the two states on opposite
|
|
243
|
-
* sides — `canSpendOffchain` is false whenever `canRecoverOnchain` is true
|
|
244
|
-
* (`wallet/vtxo.ts`), and the latter is documented as "must be recovered
|
|
245
|
-
* into a fresh batch rather than spent offchain". Holding the trader's
|
|
246
|
-
* `sender` key does not change that; a sweep removes the leaf from the live
|
|
247
|
-
* tree, not the signature from the trader.
|
|
248
|
-
*
|
|
249
|
-
* Opposite, but not exhaustive: an unrolled output satisfies neither, and
|
|
250
|
-
* {@link findLockupVtxos} drops those before they reach this type at all.
|
|
251
|
-
*
|
|
252
|
-
* So the remedy is recovery (renewing the output into a fresh batch),
|
|
253
|
-
* after which the ordinary CLTV refund works again. This package does not
|
|
254
|
-
* build that round — see {@link pushRefundWithoutReceiver}, which refuses
|
|
255
|
-
* rather than submitting a spend that cannot succeed.
|
|
256
|
-
*/
|
|
257
|
-
recoverable: boolean;
|
|
258
|
-
}
|
|
259
|
-
/**
|
|
260
|
-
* Thrown when a refund was asked for over outputs that have been swept.
|
|
261
|
-
*
|
|
262
|
-
* Carries the outpoints so a caller can act — recover exactly those, then
|
|
263
|
-
* retry — instead of reading a server rejection and guessing. `reason` follows
|
|
264
|
-
* the same convention as `awaitOnchainFill`'s `fill_timeout` and
|
|
265
|
-
* `claimOnchainFill`'s `claim_window_closed`.
|
|
266
|
-
*
|
|
267
|
-
* **The remedy already exists; this package does not reimplement it.** The SDK
|
|
268
|
-
* recovers swept outputs by re-registering them into a fresh batch, through
|
|
269
|
-
* `IVtxoManager.recoverVtxos()`. It reads the wallet's registered-contract
|
|
270
|
-
* snapshot (`recoverVtxos` → `wallet.getVtxos({ withRecoverable: true })` →
|
|
271
|
-
* `contractSnapshot()` → `contractManager.getContractsWithVtxos()`), so it
|
|
272
|
-
* covers a swap lockup as soon as that lockup is registered as a contract —
|
|
273
|
-
* which is what {@link RfqSwapManagerDeps.contracts} does. Registration is
|
|
274
|
-
* therefore not only a latency optimization; it is what turns a swept lockup
|
|
275
|
-
* from a dead end into something the ordinary wallet path can recover.
|
|
276
|
-
*
|
|
277
|
-
* Two caveats a caller must hold, neither enforceable from here:
|
|
278
|
-
*
|
|
279
|
-
* - **The wallet must hold the lockup's `sender` key**, because recovery
|
|
280
|
-
* settles through `refundWithoutReceiver` — the leaf `vhtlc-v2` annotates
|
|
281
|
-
* these VTXOs with.
|
|
282
|
-
* - **`refundLocktime` must have matured.** That leaf carries a CLTV, so a
|
|
283
|
-
* recovery round including this VTXO earlier is rejected. `recoverVtxos`
|
|
284
|
-
* sweeps every recoverable output in ONE settlement and has no CLTV
|
|
285
|
-
* awareness, so recovering early can fail the whole batch rather than just
|
|
286
|
-
* this output.
|
|
287
|
-
*
|
|
288
|
-
* @deprecated Recovery is internal to the drive; use `client.recover()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
289
|
-
*/
|
|
290
|
-
declare class LockupNeedsRecoveryError extends Error {
|
|
291
|
-
readonly name = "LockupNeedsRecoveryError";
|
|
292
|
-
readonly reason = "needs_recovery";
|
|
293
|
-
/** `txid:vout` for each output that must be recovered first. */
|
|
294
|
-
readonly outpoints: string[];
|
|
295
|
-
/**
|
|
296
|
-
* The contract's `refundLocktime`. Recovering before this matures is the
|
|
297
|
-
* hazard described above: `recoverVtxos()` sweeps EVERY recoverable output
|
|
298
|
-
* into one settlement with no CLTV awareness, so an early attempt can fail
|
|
299
|
-
* the whole batch — including unrelated outputs that were otherwise fine.
|
|
300
|
-
*
|
|
301
|
-
* Exposed as a value, not only inside the message, so a caller can skip
|
|
302
|
-
* pre-CLTV recoverable outputs without parsing prose. Seconds-based
|
|
303
|
-
* locktimes mature against the chain tip's timestamp rather than wall
|
|
304
|
-
* clock, so treat this as a floor to wait past, not an exact alarm.
|
|
305
|
-
*/
|
|
306
|
-
readonly recoverableAfter: bigint;
|
|
307
|
-
constructor(outpoints: string[], recoverableAfter: bigint);
|
|
308
|
-
}
|
|
309
|
-
/**
|
|
310
|
-
* Every output still sitting at the lockup script — spendable AND
|
|
311
|
-
* swept-but-recoverable, each tagged with which it is.
|
|
312
|
-
*
|
|
313
|
-
* All of them, not the first: a trader may fund a lockup in more than one
|
|
314
|
-
* send, and refunding only `vtxos[0]` returns part of the money and strands
|
|
315
|
-
* the rest at a script whose other refund paths are all longer.
|
|
316
|
-
*
|
|
317
|
-
* BOTH queries, because they are disjoint sets and `spendableOnly` alone goes
|
|
318
|
-
* blind at exactly the wrong moment. A lockup whose batch expiry passed is
|
|
319
|
-
* swept into the recoverable set, and this function exists to serve swaps that
|
|
320
|
-
* sat unresolved — which are precisely the ones most likely to have got there.
|
|
321
|
-
* Reading only the spendable set would report `nothing_to_refund` over money
|
|
322
|
-
* that is still sitting at the script, which is worse than an error: it looks
|
|
323
|
-
* like a resolved swap.
|
|
324
|
-
*
|
|
325
|
-
* **Visible is not the same as refundable.** A `recoverable` output cannot be
|
|
326
|
-
* spent offchain at all — see {@link LockupVtxo.recoverable} — so this set is
|
|
327
|
-
* "what is there", not "what {@link pushRefundWithoutReceiver} can take back".
|
|
328
|
-
* That function refuses the recoverable ones by name rather than submitting a
|
|
329
|
-
* spend the server must reject.
|
|
330
|
-
*
|
|
331
|
-
* **Unrolled outputs are the one exception, and are dropped.** A unilaterally
|
|
332
|
-
* exited output lives onchain behind its CSV; no offchain spend of any leaf can
|
|
333
|
-
* reach it, and `LockupVtxo` carries no field to say so, so a caller could not
|
|
334
|
-
* tell it apart from a live one. Whether arkd returns such an output under
|
|
335
|
-
* `spendableOnly` is not determinable from here, so the exclusion is made
|
|
336
|
-
* defensively rather than assumed. It costs the two waiting callers nothing
|
|
337
|
-
* they wanted: `awaitLockupFunding` keeps waiting for a claimable lockup
|
|
338
|
-
* instead of publishing `P` into a spend that cannot land, and
|
|
339
|
-
* `refundIfUnresolved` reports rather than grinding a doomed push to its
|
|
340
|
-
* deadline. Both that function and `RfqSwapManager` name the exit through
|
|
341
|
-
* {@link readLockupFate}, which queries unfiltered and reports it as `exited`;
|
|
342
|
-
* this drop is the second line, and what still refuses the push on a pass where
|
|
343
|
-
* the fate read learned nothing.
|
|
344
|
-
*
|
|
345
|
-
* This read — not the RFQ's reported state — is the authority on whether
|
|
346
|
-
* there is anything left at the lockup.
|
|
347
|
-
*
|
|
348
|
-
* **Not replaced by the contract manager's VTXO state, deliberately.** Once a
|
|
349
|
-
* lockup is registered (see `RfqSwapManagerDeps.contracts`) the wallet tracks
|
|
350
|
-
* these same outputs, and `getContractsWithVtxos` plus `canSpendOffchain` /
|
|
351
|
-
* `canRecoverOnchain` would classify them. That is a WEAKER answer here on two
|
|
352
|
-
* counts: it serves the wallet REPOSITORY, which a degraded sync will happily
|
|
353
|
-
* hand back stale (`getSyncState()` reports `degraded` and returns cached rows
|
|
354
|
-
* rather than failing), and its height-based expiry test needs a chain tip this
|
|
355
|
-
* module does not have. The two queries below ask the indexer itself and need
|
|
356
|
-
* neither. Ask-the-indexer, don't-trust-local-state — the same posture
|
|
357
|
-
* {@link readLockupFate} takes, and for the same reason: this decides money.
|
|
358
|
-
*
|
|
359
|
-
* @deprecated Recovery is internal to the drive; use `client.recover()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
360
|
-
*/
|
|
361
|
-
declare function findLockupVtxos(indexer: RefundIndexer, swapPkScript: Uint8Array): Promise<LockupVtxo[]>;
|
|
362
|
-
/**
|
|
363
|
-
* The indexer surface the lockup-spend read needs: the vtxo lookup, plus the
|
|
364
|
-
* raw transactions those vtxos were spent by. Same narrow-seam style as
|
|
365
|
-
* {@link RefundIndexer} and `restore.ts`'s `RestoreIndexer`, and satisfied by
|
|
366
|
-
* {@link RestIndexerProvider}.
|
|
367
|
-
*
|
|
368
|
-
* A root export because `SwapDriveConfig.indexer` takes it — and because
|
|
369
|
-
* `walletLockupIndexer()` returns it.
|
|
370
|
-
*/
|
|
371
|
-
type LockupSpendIndexer = Pick<RestIndexerProvider, "getVtxos" | "getVirtualTxs">;
|
|
372
|
-
/**
|
|
373
|
-
* What chain data says became of a swap lockup — the whole answer, with no
|
|
374
|
-
* solver involvement and nothing taken on the solver's word.
|
|
375
|
-
*
|
|
376
|
-
* @deprecated Recovery is internal to the drive; use `client.recover()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
377
|
-
*/
|
|
378
|
-
interface LockupSpend {
|
|
379
|
-
/** What the vtxo's `spentBy` names — the checkpoint, never the ark
|
|
380
|
-
* transaction. */
|
|
381
|
-
checkpointTxid: string;
|
|
382
|
-
/** The ark transaction that spent the above checkpoint output. What
|
|
383
|
-
* history correlation matches on; absent when the indexer omitted it. */
|
|
384
|
-
txid?: string;
|
|
385
|
-
}
|
|
386
|
-
/** @deprecated Recovery is internal to the drive; use `client.recover()`. Moved off the package root to `@arkade-os/swap/protocol`. */
|
|
387
|
-
type LockupFate =
|
|
388
|
-
/** At least one output at the lockup is still unspent. Not over. */
|
|
389
|
-
{
|
|
390
|
-
fate: "open";
|
|
391
|
-
}
|
|
392
|
-
/** Spent by a witness carrying a preimage that HASHES to the quote's
|
|
393
|
-
* `payment_hash`. Only the claim leaf can reveal one, and the only
|
|
394
|
-
* legitimate way the solver obtains it is by completing its side. */
|
|
395
|
-
| {
|
|
396
|
-
fate: "claimed";
|
|
397
|
-
preimage: Uint8Array;
|
|
398
|
-
spends: readonly LockupSpend[];
|
|
399
|
-
}
|
|
400
|
-
/** Fully spent, and nothing that spent it revealed a matching preimage —
|
|
401
|
-
* so the money went back to the trader. See {@link readLockupFate}. */
|
|
402
|
-
| {
|
|
403
|
-
fate: "returned";
|
|
404
|
-
spends: readonly LockupSpend[];
|
|
405
|
-
}
|
|
406
|
-
/**
|
|
407
|
-
* At least one output was unilaterally exited: it sits onchain under the
|
|
408
|
-
* VHTLC script, where no offchain claim or refund can reach it.
|
|
409
|
-
*
|
|
410
|
-
* Not terminal, and not a loss. The money is still under the same script
|
|
411
|
-
* with the same leaves, so `completeUnroll` plus an onchain spend can still
|
|
412
|
-
* end the swap either way — which is why this outranks `open`: an output
|
|
413
|
-
* that is "still unspent" but unreachable is not a swap that is merely
|
|
414
|
-
* running.
|
|
415
|
-
*
|
|
416
|
-
* It outranks a verdict too, on a lockup where a sibling output was claimed
|
|
417
|
-
* or returned. That is the rule `open` already sets, not a new one: the
|
|
418
|
-
* unspent test short-circuits before any witness is read, so a partially
|
|
419
|
-
* resolved lockup has never reported `claimed`/`returned`. What changes is
|
|
420
|
-
* only that such a lockup now says why it is unresolved.
|
|
421
|
-
*/
|
|
422
|
-
| {
|
|
423
|
-
fate: "exited";
|
|
424
|
-
outpoints: readonly {
|
|
425
|
-
txid: string;
|
|
426
|
-
vout: number;
|
|
427
|
-
}[];
|
|
428
|
-
}
|
|
429
|
-
/** Nothing was learned: no outputs visible, an output spent by nothing the
|
|
430
|
-
* indexer names, a spend it could not produce, or a blob that would not
|
|
431
|
-
* decode. Never an answer. */
|
|
432
|
-
| {
|
|
433
|
-
fate: "unknown";
|
|
434
|
-
};
|
|
435
|
-
/**
|
|
436
|
-
* Decide from chain data alone whether a swap lockup settled, came back, or is
|
|
437
|
-
* still live.
|
|
438
|
-
*
|
|
439
|
-
* **Why this is decidable without asking anyone.** The lockup's claim leaf can
|
|
440
|
-
* only be spent by revealing `P`, so a spend witness carrying a value that
|
|
441
|
-
* hashes to the quote's `payment_hash` is proof the claim leaf was used — and
|
|
442
|
-
* the only legitimate way the counterparty obtains `P` is by completing its
|
|
443
|
-
* side of the swap. Every OTHER leaf is a refund: `nonInteractiveRefund` is
|
|
444
|
-
* covenant-pinned to the trader's own address (`enforcePayTo(senderPkScript)`),
|
|
445
|
-
* and `refund`, `refundWithoutReceiver`, `unilateralRefund` and
|
|
446
|
-
* `unilateralRefundWithoutReceiver` all require the trader's own signature. So
|
|
447
|
-
* "spent, but not by a hash-verified claim" means the money went back to the
|
|
448
|
-
* trader, and nothing here has to trust a counterparty to say so.
|
|
449
|
-
*
|
|
450
|
-
* **A matching witness SHAPE is not proof.** Only a candidate that hashes to
|
|
451
|
-
* `paymentHash` may be read as a claim; a 32-byte item that hashes to anything
|
|
452
|
-
* else is just bytes, and is treated as a refund. Getting this wrong in the
|
|
453
|
-
* permissive direction would report "settled" for a swap that actually
|
|
454
|
-
* refunded, which is precisely the fact a trader is relying on.
|
|
455
|
-
*
|
|
456
|
-
* **`unknown` is not `returned`.** An empty vtxo set (indexer lag, or a lockup
|
|
457
|
-
* not visible yet), a `spentBy` the indexer cannot produce a transaction for,
|
|
458
|
-
* or a blob that will not decode all come back as `unknown`. `getVirtualTxs`
|
|
459
|
-
* may legitimately return fewer transactions than were asked for, so the
|
|
460
|
-
* observed set is counted rather than assumed complete. The caller's correct
|
|
461
|
-
* response to `unknown` is the same as to `open`: keep watching, and let the
|
|
462
|
-
* refund timelock — which no outage can move — be what ends the wait.
|
|
463
|
-
*
|
|
464
|
-
* **An exit is read before anything else, and over the whole set.** It is the
|
|
465
|
-
* one fact that makes an unspent output unreachable, so it outranks `open`; and
|
|
466
|
-
* it is scanned across every output rather than in outpoint order, so which
|
|
467
|
-
* output happens to come first cannot change the answer.
|
|
468
|
-
*
|
|
469
|
-
* Ask-the-indexer, don't-trust-local-state: read fresh on every poll, never
|
|
470
|
-
* cached, the same posture {@link findLockupVtxos} already establishes.
|
|
471
|
-
*
|
|
472
|
-
* @deprecated Recovery is internal to the drive; use `client.recover()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
473
|
-
*/
|
|
474
|
-
declare function readLockupFate(indexer: LockupSpendIndexer, input: {
|
|
475
|
-
swapPkScript: Uint8Array;
|
|
476
|
-
/** `sha256(P)`, hex — the quote's `payment_hash`. */
|
|
477
|
-
paymentHash: string;
|
|
478
|
-
}): Promise<LockupFate>;
|
|
479
|
-
/**
|
|
480
|
-
* Build, sign, and push the `refundWithoutReceiver` spend: return every funded
|
|
481
|
-
* output at the lockup to the trader's refund address.
|
|
482
|
-
*
|
|
483
|
-
* The leaf is `CLTV(refundLocktime) + <sender> + <server>` — the trader's own
|
|
484
|
-
* VHTLC `sender` key and the Arkade server, and NOBODY else. In particular the
|
|
485
|
-
* emulator is not involved: it co-signs only the two covenant leaves
|
|
486
|
-
* (`nonInteractiveClaim` / `nonInteractiveRefund`), which is why the solver's
|
|
487
|
-
* own escape hatch has to go through it and this one does not. So unlike that
|
|
488
|
-
* push, this transaction is submitted SIGNED, and the only counterparty is the
|
|
489
|
-
* Arkade server doing what it does for any collaborative spend.
|
|
490
|
-
*
|
|
491
|
-
* One aggregate output, not one per input — again unlike the solver's covenant
|
|
492
|
-
* refund, which needs index-aligned outputs because its ArkadeScript inspects
|
|
493
|
-
* the output at the current input's index. This leaf carries no covenant, so a
|
|
494
|
-
* single output paying the whole balance is both valid and cheaper.
|
|
495
|
-
*
|
|
496
|
-
* `refundPkScript` defaults to the destination the contract itself commits to
|
|
497
|
-
* (`nonInteractiveRefund`'s `senderPkScript`, i.e. the address the trader gave
|
|
498
|
-
* at quote time), so the ordinary call cannot send the refund somewhere the
|
|
499
|
-
* trader did not intend. It is overridable because this leaf, having no
|
|
500
|
-
* covenant, genuinely does permit any destination.
|
|
501
|
-
*
|
|
502
|
-
* **Consensus, not wall clock, decides when this is spendable.** A seconds
|
|
503
|
-
* locktime matures against median-time-past, which trails real time by roughly
|
|
504
|
-
* an hour, so a push issued the moment `refundLocktime` passes can be rejected
|
|
505
|
-
* until enough blocks land. That is expected, not a failure — see
|
|
506
|
-
* {@link refundIfUnresolved}, which retries.
|
|
507
|
-
*
|
|
508
|
-
* **Swept outputs are refused, not attempted.** This is an OFFCHAIN spend, and
|
|
509
|
-
* a swept output is no longer a live leaf: `canSpendOffchain` is false wherever
|
|
510
|
-
* `canRecoverOnchain` is true, so a recoverable input cannot be spent this way
|
|
511
|
-
* whatever key signs it (see
|
|
512
|
-
* {@link LockupVtxo.recoverable}). Because every input lands in ONE aggregate
|
|
513
|
-
* transaction, a single swept output would take the live ones down with it —
|
|
514
|
-
* so the whole push is refused with {@link LockupNeedsRecoveryError} naming the
|
|
515
|
-
* outpoints, rather than submitted and rejected. Filtering them out silently
|
|
516
|
-
* would be worse still: it would report success over money that never moved.
|
|
517
|
-
*
|
|
518
|
-
* @deprecated Recovery is internal to the drive; use `client.recover()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
519
|
-
*/
|
|
520
|
-
declare function pushRefundWithoutReceiver(operator: SwapOperator, input: {
|
|
521
|
-
contract: InstanceType<typeof VHTLC.ScriptV2>;
|
|
522
|
-
/** The `sender` signer. Build it from the swap record with
|
|
523
|
-
* {@link senderIdentityForSwapRecord} — on an HD wallet that resolves
|
|
524
|
-
* from the seed, with no stored key bytes anywhere, and every way the
|
|
525
|
-
* wallet can fail to produce it arrives as one typed
|
|
526
|
-
* {@link RefundNotLocallyPossibleError} the manager reads as permanent
|
|
527
|
-
* rather than retrying for the rest of the refund window. */
|
|
528
|
-
sender: Identity;
|
|
529
|
-
vtxos: readonly LockupVtxo[];
|
|
530
|
-
/** Defaults to the contract's own committed refund destination. */
|
|
531
|
-
refundPkScript?: Uint8Array;
|
|
532
|
-
}): Promise<{
|
|
533
|
-
txid: string;
|
|
534
|
-
amount: number;
|
|
535
|
-
}>;
|
|
536
|
-
/** @deprecated Recovery is internal to the drive; use `client.recover()`. Moved off the package root to `@arkade-os/swap/protocol`. */
|
|
537
|
-
type RefundOutcome =
|
|
538
|
-
/** The solver resolved it — claimed (`settled`) or returned it (`refunded`). */
|
|
539
|
-
{
|
|
540
|
-
outcome: "resolved";
|
|
541
|
-
status: RfqStatus;
|
|
542
|
-
}
|
|
543
|
-
/** The trader took it back via `refundWithoutReceiver`. */
|
|
544
|
-
| {
|
|
545
|
-
outcome: "refunded";
|
|
546
|
-
txid: string;
|
|
547
|
-
amount: number;
|
|
548
|
-
status: RfqStatus | null;
|
|
549
|
-
}
|
|
550
|
-
/** The refund window opened but the lockup holds nothing to return. */
|
|
551
|
-
| {
|
|
552
|
-
outcome: "nothing_to_refund";
|
|
553
|
-
status: RfqStatus | null;
|
|
554
|
-
}
|
|
555
|
-
/**
|
|
556
|
-
* The money is still at the lockup, but its batch was swept, so no offchain
|
|
557
|
-
* spend can take it back until it is recovered into a fresh batch. Returned
|
|
558
|
-
* rather than retried: unlike a median-time-past refusal, no amount of
|
|
559
|
-
* waiting fixes this — see {@link LockupNeedsRecoveryError}. Recover the
|
|
560
|
-
* named outpoints, then call this again.
|
|
561
|
-
*/
|
|
562
|
-
| {
|
|
563
|
-
outcome: "needs_recovery";
|
|
564
|
-
outpoints: string[];
|
|
565
|
-
vtxos: LockupVtxo[];
|
|
566
|
-
status: RfqStatus | null;
|
|
567
|
-
}
|
|
568
|
-
/**
|
|
569
|
-
* The lockup was unilaterally exited: its outputs sit onchain under the VHTLC
|
|
570
|
-
* script, where no offchain refund can reach them. Returned rather than
|
|
571
|
-
* retried: no amount of waiting changes where the money lives. Complete the
|
|
572
|
-
* unroll and spend the named outputs onchain.
|
|
573
|
-
*
|
|
574
|
-
* **`outpoints` is not necessarily the whole lockup, and `exited` does not
|
|
575
|
-
* mean "nothing left to refund".** A lockup funded by more than one UTXO
|
|
576
|
-
* reports `exited` as soon as ANY of them has been exited, and `outpoints`
|
|
577
|
-
* names only those; a still-live sibling is left unrefunded, and this call
|
|
578
|
-
* will not come back for it — the outcome is terminal, so the caller's retry
|
|
579
|
-
* loop ends here. That is deliberate rather than an oversight: `RfqSwapManager`
|
|
580
|
-
* reports the same lockup `exited` on the same any-output rule, and the two
|
|
581
|
-
* must not disagree. It does make the surviving outputs the caller's to
|
|
582
|
-
* pursue, through an independent onchain or offchain recovery path that this
|
|
583
|
-
* function will not reach.
|
|
584
|
-
*
|
|
585
|
-
* Distinct from {@link RefundOutcome} `needs_recovery` on purpose: that
|
|
586
|
-
* variant's remedy is recovery into a fresh batch, which is a spend no batch
|
|
587
|
-
* can make for an output that is already onchain.
|
|
588
|
-
*/
|
|
589
|
-
| {
|
|
590
|
-
outcome: "exited";
|
|
591
|
-
outpoints: string[];
|
|
592
|
-
status: RfqStatus | null;
|
|
593
|
-
};
|
|
594
|
-
/**
|
|
595
|
-
* Ask first, then fall back: watch the swap for the solver to resolve it, and
|
|
596
|
-
* if `refundLocktime` matures without that happening, take the lockup back
|
|
597
|
-
* with `refundWithoutReceiver`.
|
|
598
|
-
*
|
|
599
|
-
* This is the whole trader-side failure story in one call. It polls `status()`
|
|
600
|
-
* — the only "asking" this protocol has (see the module doc) — and returns as
|
|
601
|
-
* soon as the solver reports `settled` or `refunded`. Otherwise, once the
|
|
602
|
-
* quote's `refund_locktime` passes, it looks up what is actually at the lockup
|
|
603
|
-
* and pushes the refund.
|
|
604
|
-
*
|
|
605
|
-
* Two behaviours worth knowing:
|
|
606
|
-
*
|
|
607
|
-
* - **A dead negotiation is not a reason to stop.** `refused`, `expired` and
|
|
608
|
-
* `stuck` are terminal states, but a trader can be holding a funded lockup in
|
|
609
|
-
* every one of them, so they do not end the wait — only `settled`/`refunded`
|
|
610
|
-
* do (see {@link RFQ_RESOLVED_STATES}). What ends it otherwise is the
|
|
611
|
-
* timelock.
|
|
612
|
-
* - **The first push after the deadline may legitimately fail.** Median-time-
|
|
613
|
-
* past trails wall clock, so the server can still consider the leaf locked
|
|
614
|
-
* for a while after `refundLocktime` passes in real time. Failures are
|
|
615
|
-
* retried at the poll interval until `attemptDeadline`, after which the last
|
|
616
|
-
* error is rethrown rather than swallowed.
|
|
617
|
-
* - **A swept lockup ends the wait instead of consuming it.** Once the batch
|
|
618
|
-
* is gone the CLTV refund is not "not yet" but "not this way", so it returns
|
|
619
|
-
* `needs_recovery` naming the outpoints rather than retrying until the
|
|
620
|
-
* deadline. Recover them and call again.
|
|
621
|
-
* - **An exited lockup ends it the same way, and is checked first.** Each pass
|
|
622
|
-
* past the deadline asks {@link readLockupFate} before reading what is
|
|
623
|
-
* refundable, so an output that has been unilaterally exited returns `exited`
|
|
624
|
-
* instead of feeding a push that cannot land. It costs one extra `getVtxos`
|
|
625
|
-
* per such pass (three where there were two), plus a `getVirtualTxs` on a
|
|
626
|
-
* fully-spent lockup; only the pass that returns `exited` saves the other two.
|
|
627
|
-
* Paid to prevent a push that would otherwise be retried to the deadline and
|
|
628
|
-
* then rethrown. A failing fate read is swallowed, not raised: it is a
|
|
629
|
-
* shortcut, and losing it must not end a wait the ordinary path could answer.
|
|
630
|
-
*
|
|
631
|
-
* A lockup funded in two sends of which only one exited reports `exited` for
|
|
632
|
-
* the whole thing and leaves the live half unrefunded. That is deliberate:
|
|
633
|
-
* `RfqSwapManager` reports the same lockup `exited` on the same any-output
|
|
634
|
-
* rule, and the two must not disagree.
|
|
635
|
-
*
|
|
636
|
-
* Safe to call late, and safe to call again: a caller recovering from a crash
|
|
637
|
-
* well past the deadline skips straight to the push, and a lockup that is
|
|
638
|
-
* already empty comes back as `nothing_to_refund` instead of an error.
|
|
639
|
-
*
|
|
640
|
-
* @deprecated Use `client.recover()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
641
|
-
*/
|
|
642
|
-
declare function refundIfUnresolved(transport: RfqTransport, operator: SwapOperator, indexer: LockupSpendIndexer, input: {
|
|
643
|
-
rfqId: string;
|
|
644
|
-
contract: InstanceType<typeof VHTLC.ScriptV2>;
|
|
645
|
-
/** @see pushRefundWithoutReceiver */
|
|
646
|
-
sender: Identity;
|
|
647
|
-
/**
|
|
648
|
-
* `sha256(P)`, hex — the quote's `payment_hash`, as {@link readLockupFate}
|
|
649
|
-
* takes it. Not derivable from `script`, whose `preimageHash` is a
|
|
650
|
-
* `hash160` of the same secret.
|
|
651
|
-
*/
|
|
652
|
-
paymentHash: string;
|
|
653
|
-
/** `refund_locktime` from the quote, unix seconds. */
|
|
654
|
-
refundLocktime: number;
|
|
655
|
-
/** Defaults to the contract's own committed refund destination. */
|
|
656
|
-
refundPkScript?: Uint8Array;
|
|
657
|
-
pollMs?: number;
|
|
658
|
-
/** Stop retrying the push at this unix time, rethrowing the last
|
|
659
|
-
* error. Defaults to `refundLocktime + REFUND_MTP_LAG_SECONDS`. */
|
|
660
|
-
attemptDeadline?: number;
|
|
661
|
-
/** Injected for tests; defaults to wall clock, in unix seconds. */
|
|
662
|
-
now?: () => number;
|
|
663
|
-
}): Promise<RefundOutcome>;
|
|
664
|
-
|
|
665
|
-
/**
|
|
666
|
-
* Where a monitored RFQ swap stands, and which of those states end it.
|
|
667
|
-
*
|
|
668
|
-
* Its own module rather than a corner of `swapManager.ts` because the
|
|
669
|
-
* dependency runs the other way: the record layer decides retention from
|
|
670
|
-
* {@link isRfqSwapTerminal}, and the manager persists through the record
|
|
671
|
-
* layer. With the vocabulary here, neither has to import the other at runtime.
|
|
672
|
-
* `swapManager.ts` re-exports all three names, so nothing about the public
|
|
673
|
-
* surface moved.
|
|
674
|
-
*/
|
|
675
|
-
/**
|
|
676
|
-
* Where a monitored swap stands.
|
|
677
|
-
*
|
|
678
|
-
* `claimable` and `claimed` are the states of a swap the TRADER has something
|
|
679
|
-
* to claim on: the L1 fill on an onchain send, and the solver-funded lockup on
|
|
680
|
-
* a receive. Only `lightning_send` has neither — there the solver claims the
|
|
681
|
-
* lockup, and the trader's only move is the refund.
|
|
682
|
-
*
|
|
683
|
-
* A root export because `CorridorSwapRecord.state` is this vocabulary: a
|
|
684
|
-
* caller reading a record off `client.swaps()` names it. `Outcome`, delivered
|
|
685
|
-
* by `client.onUpdate()`, is the client-level projection over it.
|
|
686
|
-
*/
|
|
687
|
-
type RfqSwapState =
|
|
688
|
-
/** Live; nothing actionable yet. On a receive leg this covers the whole
|
|
689
|
-
* stretch before the solver funds anything. */
|
|
690
|
-
"pending"
|
|
691
|
-
/** There is something for the trader to take, and the window to take it is
|
|
692
|
-
* open: the confirmed L1 fill on an onchain send, or a lockup funded for at
|
|
693
|
-
* least `expectedAmount` on a receive. */
|
|
694
|
-
| "claimable"
|
|
695
|
-
/**
|
|
696
|
-
* The trader's claim has been made — its L1 broadcast on an onchain send,
|
|
697
|
-
* its Arkade submission on a receive.
|
|
698
|
-
*
|
|
699
|
-
* **On a receive this is a local belief and not a chain fact**, which is
|
|
700
|
-
* why it is not terminal: `settled` is the chain's answer, and `refunded`
|
|
701
|
-
* is still reachable from here if the claim never lands and the solver
|
|
702
|
-
* takes the lockup back.
|
|
703
|
-
*/
|
|
704
|
-
| "claimed"
|
|
705
|
-
/**
|
|
706
|
-
* This wallet will not act, and only the counterparty can change that.
|
|
707
|
-
*
|
|
708
|
-
* On a send leg: the Arkade refund cannot be pushed from here — no secrets
|
|
709
|
-
* on the record, a descriptor from another seed, or nothing wired to act —
|
|
710
|
-
* so the lockup comes back only if the counterparty claims it or the wallet
|
|
711
|
-
* that can sign it is restored. On a receive leg: the trader holds no
|
|
712
|
-
* refund at all, so this is a lockup that cannot be claimed — funded for
|
|
713
|
-
* less than the swap agreed (publishing `P` for it is the whole attack
|
|
714
|
-
* `LockupAmountMismatchError` exists to refuse), or one whose claim window
|
|
715
|
-
* shut unclaimed. `RfqSwapCommon.blockedReason` says which.
|
|
716
|
-
*
|
|
717
|
-
* **Not terminal, and not a dead end.** The money is still at the lockup,
|
|
718
|
-
* so the counterparty's move is still observable and still ends the swap;
|
|
719
|
-
* and the refusal is re-checked every pass, so restoring the right wallet,
|
|
720
|
-
* wiring the callbacks, or the solver topping the lockup up returns the
|
|
721
|
-
* swap to `pending` and resumes the normal drive. For an onchain-send swap
|
|
722
|
-
* it says nothing about the L1 half, which keeps being driven and claimed.
|
|
723
|
-
*/
|
|
724
|
-
| "needs_counterparty"
|
|
725
|
-
/**
|
|
726
|
-
* Terminal: the lockup was spent by a hash-verified claim. Read off chain,
|
|
727
|
-
* never reported.
|
|
728
|
-
*
|
|
729
|
-
* On a send leg that claim is the counterparty's, and it is proof the
|
|
730
|
-
* counterparty completed its side. On a receive leg it is the TRADER's own
|
|
731
|
-
* — matched by the hash and not by our txid, so a claim that lands without
|
|
732
|
-
* us still counts (see `RfqSwapManager`).
|
|
733
|
-
*/
|
|
734
|
-
| "settled"
|
|
735
|
-
/**
|
|
736
|
-
* Terminal: the lockup was spent by something other than a claim.
|
|
737
|
-
*
|
|
738
|
-
* On a send leg that is the money coming back, by the solver's hand or the
|
|
739
|
-
* trader's. **On a receive leg it is a LOSS**: the lockup was the solver's
|
|
740
|
-
* money, every non-claim leaf is the solver's, and a swap that ends here
|
|
741
|
-
* ended with the trader's incoming payment never arriving. It is also where
|
|
742
|
-
* a receive swap ends when its window closes with nothing left to observe —
|
|
743
|
-
* see `RfqSwapManager`.
|
|
744
|
-
*/
|
|
745
|
-
| "refunded"
|
|
746
|
-
/** Terminal: an action failed and its window closed. */
|
|
747
|
-
| "failed";
|
|
748
|
-
/** Whether `CorridorSwapRecord.state` ends the swap — the record reader's
|
|
749
|
-
* terminal check, beside the `Outcome` projection `client.onUpdate()`
|
|
750
|
-
* delivers. */
|
|
751
|
-
declare const isRfqSwapTerminal: (state: RfqSwapState) => boolean;
|
|
752
|
-
|
|
753
|
-
/**
|
|
754
|
-
* What the manager needs to register a swap's lockup with the wallet, so the
|
|
755
|
-
* indexer pushes its funding and its spend instead of being asked every few
|
|
756
|
-
* seconds.
|
|
757
|
-
*
|
|
758
|
-
* Both fields are things the caller already holds. `script` is the very object
|
|
759
|
-
* `pushRefundWithoutReceiver` and `pushClaim` take, so a caller wired to act has
|
|
760
|
-
* it in hand; `address` is the request entrypoint's own return value. The
|
|
761
|
-
* address is taken rather than re-derived on purpose — the row's address must be
|
|
762
|
-
* the one that was actually funded, and a local re-derivation would silently use
|
|
763
|
-
* the SDK's default network, which is the exact bug `registerOfferContract`
|
|
764
|
-
* guards against.
|
|
765
|
-
*
|
|
766
|
-
* @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
767
|
-
*/
|
|
768
|
-
interface RfqSwapLockup {
|
|
769
|
-
/** The covenant. Its `pkScript` MUST equal the record's `lockupPkScript`. */
|
|
770
|
-
script: InstanceType<typeof VHTLC.ScriptV2>;
|
|
771
|
-
/** The Arkade address that was funded. */
|
|
772
|
-
address: string;
|
|
773
|
-
}
|
|
774
|
-
interface RfqSwapCommon {
|
|
775
|
-
/** The negotiation id — this record's identity. */
|
|
776
|
-
rfqId: string;
|
|
777
|
-
state: RfqSwapState;
|
|
778
|
-
/** The Arkade lockup's scriptPubKey — `swapPkScript` from any of the four
|
|
779
|
-
* request entrypoints. This is what the manager watches to decide the swap:
|
|
780
|
-
* it is the only handle on the covenant whose spend witness says whether
|
|
781
|
-
* the swap settled or came back. */
|
|
782
|
-
lockupPkScript: Uint8Array;
|
|
783
|
-
/** The covenant behind {@link lockupPkScript}, when the caller wants the
|
|
784
|
-
* lockup registered with a contract manager. Optional: without it the
|
|
785
|
-
* manager still watches the swap on its timer, it just cannot subscribe.
|
|
786
|
-
* See {@link RfqSwapManagerDeps.contracts}. */
|
|
787
|
-
lockup?: RfqSwapLockup;
|
|
788
|
-
/**
|
|
789
|
-
* `sha256(P)`, hex — the quote's `payment_hash`. The claim leaf can only
|
|
790
|
-
* be spent by revealing a value that hashes to this, which is what makes a
|
|
791
|
-
* settlement provable rather than reported. For an onchain send this is
|
|
792
|
-
* the SAME hash the L1 `htlc` carries: one `P` unlocks both legs.
|
|
793
|
-
*
|
|
794
|
-
* True of the three corridors that exist today and only of them: a hashlock
|
|
795
|
-
* belongs to a CORRIDOR, and a banco-style one settles without any. The
|
|
796
|
-
* stored record already says so — the hash lives in `profile.hashlock`, not
|
|
797
|
-
* on `RfqSwapRecord` — and this field follows onto the per-corridor swap
|
|
798
|
-
* types when the first such corridor lands. Do not read the current shape as
|
|
799
|
-
* final.
|
|
800
|
-
*/
|
|
801
|
-
paymentHash: string;
|
|
802
|
-
/**
|
|
803
|
-
* `refund_locktime` from the quote, unix seconds.
|
|
804
|
-
*
|
|
805
|
-
* Whose deadline it is inverts with the direction, and so does what to do
|
|
806
|
-
* about it. On a send leg it is the TRADER's: the lockup is the trader's
|
|
807
|
-
* money and this gates the refund that takes it back, so it is a moment to
|
|
808
|
-
* act AFTER. On a receive leg it is the SOLVER's: the trader has no refund
|
|
809
|
-
* leaf at all, and this is the moment to have claimed BEFORE.
|
|
810
|
-
*/
|
|
811
|
-
refundLocktime: number;
|
|
812
|
-
createdAt: number;
|
|
813
|
-
updatedAt: number;
|
|
814
|
-
/** Set once the trader's own `refundWithoutReceiver` push landed. */
|
|
815
|
-
refundTxid?: string;
|
|
816
|
-
/**
|
|
817
|
-
* The ark transactions that SPENT the lockup, stamped from the chain read
|
|
818
|
-
* that ended the swap — `LockupFate.spends`, whichever verdict it reached.
|
|
819
|
-
*
|
|
820
|
-
* The counterparty's move, on every leg but one: a solver claim on a send,
|
|
821
|
-
* a solver reclaim on a receive, and — the exception — the trader's own
|
|
822
|
-
* claim when a receive settles. What they have in common is that no local
|
|
823
|
-
* action produced them, so nothing else on this record can name them:
|
|
824
|
-
* {@link refundTxid} names only a push this wallet made, and
|
|
825
|
-
* `claimTxid` only a submission it made.
|
|
826
|
-
*
|
|
827
|
-
* Stamped so a terminal record answers "which transaction ended this" from
|
|
828
|
-
* storage. Without it the only source is another read of the lockup — a
|
|
829
|
-
* network round trip per terminal swap, which is what activity correlation
|
|
830
|
-
* has to pay on the offline-first path where it is least affordable.
|
|
831
|
-
*
|
|
832
|
-
* Absent when the swap ended without a chain verdict, or when the indexer
|
|
833
|
-
* named the checkpoint but not the ark transaction — the same `txid`
|
|
834
|
-
* `LockupSpend` declares optional, for the same reason.
|
|
835
|
-
*/
|
|
836
|
-
lockupSpendTxids?: string[];
|
|
837
|
-
/**
|
|
838
|
-
* `P`, hex — the preimage the solver revealed to claim the lockup,
|
|
839
|
-
* stamped from the chain read that ended the swap.
|
|
840
|
-
*
|
|
841
|
-
* Lightning sends only, and the one leg where the wallet cannot produce
|
|
842
|
-
* `P` itself: the payee mints it, so the quote carries only
|
|
843
|
-
* {@link paymentHash}. The claiming legs keep their own secret in
|
|
844
|
-
* `profile`, where `preimageForSwapRecord` recovers it — so this is a
|
|
845
|
-
* settlement receipt, not a second home for a claim secret, and not a
|
|
846
|
-
* secret at all: it is already public in the witness it came from.
|
|
847
|
-
* `readLockupFate` hashes it against {@link paymentHash} before returning
|
|
848
|
-
* it, so what is stamped here is verified by construction.
|
|
849
|
-
*
|
|
850
|
-
* Absent on the other legs, and on a send that did not settle.
|
|
851
|
-
*/
|
|
852
|
-
settlementPreimageHex?: string;
|
|
853
|
-
/** Why `state` is `failed`. */
|
|
854
|
-
failure?: string;
|
|
855
|
-
/**
|
|
856
|
-
* Last local claim error while the receive swap is still retryable.
|
|
857
|
-
*
|
|
858
|
-
* Distinct from terminal `failure`: this records a claim attempt that failed
|
|
859
|
-
* before the window closed. If the window later closes without a submitted
|
|
860
|
-
* claim, it becomes the terminal failure reason.
|
|
861
|
-
*/
|
|
862
|
-
claimFailure?: string;
|
|
863
|
-
/** Why `state` is `needs_counterparty`. Distinct from {@link failure},
|
|
864
|
-
* which means an action was attempted and did not work. */
|
|
865
|
-
blockedReason?: string;
|
|
866
|
-
}
|
|
867
|
-
/** `arkade:BTC->lightning:BTC`. Nothing for the trader to claim: the solver
|
|
868
|
-
* claims the lockup with the preimage it learns by paying the invoice — which
|
|
869
|
-
* is exactly why that spend's witness is proof the payment landed.
|
|
870
|
-
*
|
|
871
|
-
* @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
872
|
-
*/
|
|
873
|
-
interface LightningSendSwap extends RfqSwapCommon {
|
|
874
|
-
kind: "lightning_send";
|
|
875
|
-
}
|
|
876
|
-
/** `arkade:BTC->onchain:BTC`. Carries the L1 half the trader must claim.
|
|
877
|
-
*
|
|
878
|
-
* @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
879
|
-
*/
|
|
880
|
-
interface OnchainSendSwap extends RfqSwapCommon {
|
|
881
|
-
kind: "onchain_send";
|
|
882
|
-
/** The locally derived HTLC from `requestOnchainSend` — the manager reads
|
|
883
|
-
* `pkScript`, `paymentHash` and `refundLocktime` off it to classify. */
|
|
884
|
-
htlc: OnchainHtlc;
|
|
885
|
-
/** `profile.min_confirmations` from the quote. */
|
|
886
|
-
minConfirmations: number;
|
|
887
|
-
/** Where {@link RfqSwapManagerCallbacks.claimOnchain} pays; optional only
|
|
888
|
-
* so records predating its profile slot still restore. */
|
|
889
|
-
payoutPkScript?: Uint8Array;
|
|
890
|
-
/** The fill's outpoint, learned on first sighting. Without it a SPENT
|
|
891
|
-
* HTLC reads as never funded — see {@link classifyOnchainHtlc}. */
|
|
892
|
-
funding?: {
|
|
893
|
-
txid: string;
|
|
894
|
-
vout: number;
|
|
895
|
-
};
|
|
896
|
-
/** Our L1 claim's txid. */
|
|
897
|
-
claimTxid?: string;
|
|
898
|
-
}
|
|
899
|
-
/**
|
|
900
|
-
* `lightning:BTC->arkade:BTC`. The inverted leg: the SOLVER funds the lockup
|
|
901
|
-
* and the TRADER claims it, and that claim is what publishes `P` and lets the
|
|
902
|
-
* solver settle the payer's held Lightning HTLC.
|
|
903
|
-
*
|
|
904
|
-
* Two consequences shape how this record is driven, both of them absent from
|
|
905
|
-
* the send legs:
|
|
906
|
-
*
|
|
907
|
-
* - **There is no trader-side refund.** Every non-claim leaf of this covenant
|
|
908
|
-
* is the solver's, so the manager never calls
|
|
909
|
-
* {@link RfqSwapManagerCallbacks.refundArkade} for one of these. A swap that
|
|
910
|
-
* is not claimed is simply lost — the solver reclaims at
|
|
911
|
-
* {@link RfqSwapCommon.refundLocktime} and the payer is refunded when the
|
|
912
|
-
* held HTLC lapses.
|
|
913
|
-
* - **The claim is the whole swap, and it is on a deadline.** The trader must
|
|
914
|
-
* be online for it: covclaimd cannot claim this covenant today, so the claim
|
|
915
|
-
* packet's offline path does not run.
|
|
916
|
-
*
|
|
917
|
-
* @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
918
|
-
*/
|
|
919
|
-
interface LightningReceiveSwap extends RfqSwapCommon {
|
|
920
|
-
kind: "lightning_receive";
|
|
921
|
-
/**
|
|
922
|
-
* What the lockup must carry — the quote's `to_amount`, captured at REQUEST
|
|
923
|
-
* time and persisted with the record.
|
|
924
|
-
*
|
|
925
|
-
* **Not re-derivable, and not optional.** Captured at claim time it would
|
|
926
|
-
* be whatever the solver funded, which is the dust-funding attack rather
|
|
927
|
-
* than a check on it. A record that reaches the manager without a finite
|
|
928
|
-
* value here is reported `needs_counterparty` and never claimed: a
|
|
929
|
-
* comparison against `undefined` or `NaN` is false, so an unusable
|
|
930
|
-
* comparand does not fail the value gate, it deletes it.
|
|
931
|
-
*/
|
|
932
|
-
expectedAmount: number;
|
|
933
|
-
/** Our Arkade claim's txid, once submitted. Set from the callback's return
|
|
934
|
-
* and never from a chain read — the chain's answer is `settled`. */
|
|
935
|
-
claimTxid?: string;
|
|
936
|
-
}
|
|
937
|
-
/**
|
|
938
|
-
* A monitored swap.
|
|
939
|
-
*
|
|
940
|
-
* This is a live record, not a serialization format: `lockupPkScript` and
|
|
941
|
-
* `htlc` hold derived `Uint8Array`s, and `RfqSwapRecord` is its storable
|
|
942
|
-
* projection. Give the manager a {@link RfqSwapManagerDeps.repository} and it
|
|
943
|
-
* writes and rebuilds these itself, through
|
|
944
|
-
* {@link RfqSwapManager.restoreFromRepository}. A caller keeping its own store
|
|
945
|
-
* projects it in {@link RfqSwapManagerCallbacks.saveSwap} instead, rebuilds it
|
|
946
|
-
* on restart the way it was made — `lightningSendContract` /
|
|
947
|
-
* `lightningReceiveContract` / `onchainHtlcScript` over the quote's binding fields —
|
|
948
|
-
* and hands the result to {@link RfqSwapManager.start}.
|
|
949
|
-
*
|
|
950
|
-
* **`onchain:BTC->arkade:BTC` is deliberately not a member yet.** Its Arkade
|
|
951
|
-
* half is the same solver-funded lockup as {@link LightningReceiveSwap}'s, but
|
|
952
|
-
* it also has an L1 half the trader funds and must take back itself
|
|
953
|
-
* (`buildHtlcRefund` at the HTLC's own `htlc_locktime`), which is a second
|
|
954
|
-
* deadline, a second observation seam and a second action callback. Adding the
|
|
955
|
-
* lockup half alone would produce a manager that silently lets that L1 refund
|
|
956
|
-
* window pass — the one failure mode {@link RfqSwapManager} refuses elsewhere
|
|
957
|
-
* by name (see `driveOnchain`'s missing-`ChainSource` check). Until the L1
|
|
958
|
-
* refund is driven too, that corridor is better served by the request and claim
|
|
959
|
-
* functions directly than by a monitor that covers half of it.
|
|
960
|
-
*
|
|
961
|
-
* @deprecated Use `Swap`, projected by `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
962
|
-
*/
|
|
963
|
-
type RfqSwap = LightningSendSwap | OnchainSendSwap | LightningReceiveSwap;
|
|
964
|
-
/** What the manager should do next about an onchain-send swap's L1 half.
|
|
965
|
-
*
|
|
966
|
-
* @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
967
|
-
*/
|
|
968
|
-
type OnchainSendAction =
|
|
969
|
-
/** Not funded yet, or not confirmed deep enough. */
|
|
970
|
-
"wait"
|
|
971
|
-
/** Funded, confirmed, and far enough from the refund leaf to claim safely. */
|
|
972
|
-
| "claim"
|
|
973
|
-
/** The claim is off the table for good; the money comes back through the
|
|
974
|
-
* Arkade lockup instead. */
|
|
975
|
-
| "claim_window_closed"
|
|
976
|
-
/** Our claim already landed (only the trader holds P). */
|
|
977
|
-
| "claimed"
|
|
978
|
-
/** The solver took its L1 refund — the fill is gone. */
|
|
979
|
-
| "swept";
|
|
980
|
-
/**
|
|
981
|
-
* The decision a "poll status, refund on timeout" loop gets wrong.
|
|
982
|
-
*
|
|
983
|
-
* {@link OnchainHtlcPhase} runs `unfunded -> awaiting_confirmations ->
|
|
984
|
-
* claimable -> (refundable | claimed | swept)`, and `refundable` does NOT mean
|
|
985
|
-
* "time to refund the L1 HTLC" — the trader has no key on that leaf; it is the
|
|
986
|
-
* SOLVER's refund, and reaching it means the trader's claim was missed. So the
|
|
987
|
-
* L1 claim has to be driven before it, and from it the only remaining move is
|
|
988
|
-
* the Arkade-side refund.
|
|
989
|
-
*
|
|
990
|
-
* There is a second, quieter trap between those two functions:
|
|
991
|
-
* `classifyOnchainHtlc` reports `claimable` right up until median-time-past
|
|
992
|
-
* reaches `refundLocktime`, while `claimOnchainFill` refuses from
|
|
993
|
-
* {@link ONCHAIN_CLAIM_MARGIN_SECONDS} before it — because broadcasting
|
|
994
|
-
* publishes P, and doing that into the counterparty's live refund window risks
|
|
995
|
-
* losing the race AND giving away the preimage. Driving straight off the phase
|
|
996
|
-
* would therefore spend that whole margin throwing `claim_window_closed` at
|
|
997
|
-
* every poll and never fall back. This function applies the margin, so
|
|
998
|
-
* "claimable" here means claimable by `claimOnchainFill` too.
|
|
999
|
-
*
|
|
1000
|
-
* @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1001
|
-
*/
|
|
1002
|
-
declare function nextOnchainAction(input: {
|
|
1003
|
-
phase: OnchainHtlcPhase;
|
|
1004
|
-
/** `htlc.refundLocktime` — when the solver's L1 refund leaf opens. */
|
|
1005
|
-
htlcLocktime: number;
|
|
1006
|
-
/** Unix seconds. */
|
|
1007
|
-
now: number;
|
|
1008
|
-
}): OnchainSendAction;
|
|
1009
|
-
/** What the trader's own `refundWithoutReceiver` push returned, or `null` when
|
|
1010
|
-
* the lockup held nothing to return.
|
|
1011
|
-
*
|
|
1012
|
-
* @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1013
|
-
*/
|
|
1014
|
-
type ArkadeRefundResult = {
|
|
1015
|
-
txid: string;
|
|
1016
|
-
amount: number;
|
|
1017
|
-
} | null;
|
|
1018
|
-
/**
|
|
1019
|
-
* The money-moving half, injected. The manager decides when; these do it.
|
|
1020
|
-
*
|
|
1021
|
-
* Neither action gets a retry loop of its own here — see the module doc. Take
|
|
1022
|
-
* `arkadeRefunder` for `refundArkade` rather than assembling it: it composes
|
|
1023
|
-
* the atomic push (`findLockupVtxos` + `senderIdentityForSwapRecord` +
|
|
1024
|
-
* `pushRefundWithoutReceiver`) and keeps the three rules below structural.
|
|
1025
|
-
*
|
|
1026
|
-
* Do NOT wire `refundArkade` to `refundIfUnresolved`: that function is the
|
|
1027
|
-
* single-swap version of this whole class and brings its own status polling
|
|
1028
|
-
* and its own MTP retry loop, which would nest inside the manager's.
|
|
1029
|
-
*
|
|
1030
|
-
* Resolve the sender key through `senderIdentityForSwapRecord`: it is
|
|
1031
|
-
* what turns "this wallet cannot sign this swap" into
|
|
1032
|
-
* {@link RefundNotLocallyPossibleError}, which the manager reports as
|
|
1033
|
-
* `needs_counterparty` instead of retrying for the whole refund window.
|
|
1034
|
-
*
|
|
1035
|
-
* @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1036
|
-
*/
|
|
1037
|
-
interface RfqSwapManagerCallbacks {
|
|
1038
|
-
/** Build and broadcast the L1 claim. See `claimOnchainFill`. */
|
|
1039
|
-
claimOnchain: (swap: OnchainSendSwap, utxo: ChainUtxo) => Promise<{
|
|
1040
|
-
txid: string;
|
|
1041
|
-
}>;
|
|
1042
|
-
/**
|
|
1043
|
-
* Claim the solver-funded lockup on a receive leg, revealing `P`. Wire it
|
|
1044
|
-
* to `pushClaim` — the outputs are supplied, so `findLockupVtxos` has
|
|
1045
|
-
* already been called and `claimReceiveLockup`'s wait would only sit on a
|
|
1046
|
-
* lockup the manager has just seen.
|
|
1047
|
-
*
|
|
1048
|
-
* **Pass `expectedAmount` and `partiallyClaimed` straight through.** The
|
|
1049
|
-
* manager checks the funded value before calling this, but that check
|
|
1050
|
-
* decides WHEN to act; `pushClaim`'s decides whether `P` is published, and
|
|
1051
|
-
* it is the one that runs with nothing between it and the signature. Two
|
|
1052
|
-
* checks, one of which is load-bearing — do not drop the inner one because
|
|
1053
|
-
* the outer one exists.
|
|
1054
|
-
*
|
|
1055
|
-
* Required here, like {@link claimOnchain}: a receive swap monitored with
|
|
1056
|
-
* nothing wired to claim it is a swap that quietly expires, and a compile
|
|
1057
|
-
* error is the right way to learn that. A consumer that drives only the
|
|
1058
|
-
* kinds needing neither installs
|
|
1059
|
-
* {@link AvailableRfqSwapManagerCallbacks} instead and takes the runtime
|
|
1060
|
-
* refusal in its place.
|
|
1061
|
-
*/
|
|
1062
|
-
claimLockup: (swap: LightningReceiveSwap, vtxos: readonly LockupVtxo[], options: {
|
|
1063
|
-
/** A claim of ours is already out, so `P` is public and the value
|
|
1064
|
-
* gate has nothing left to protect — pass this to `pushClaim` so a
|
|
1065
|
-
* funding that arrived piecemeal can still be swept. */
|
|
1066
|
-
partiallyClaimed: boolean;
|
|
1067
|
-
}) => Promise<{
|
|
1068
|
-
txid: string;
|
|
1069
|
-
amount: number;
|
|
1070
|
-
}>;
|
|
1071
|
-
/**
|
|
1072
|
-
* Push `refundWithoutReceiver` for every output at the lockup. See
|
|
1073
|
-
* `pushRefundWithoutReceiver`; return `null` for an empty lockup. Never
|
|
1074
|
-
* called for a {@link LightningReceiveSwap} — that leg's refund leaf is the
|
|
1075
|
-
* solver's.
|
|
1076
|
-
*
|
|
1077
|
-
* Only {@link RefundNotLocallyPossibleError} is read as permanent. Every
|
|
1078
|
-
* other throw is treated as transient and RETRIED once a poll: each attempt
|
|
1079
|
-
* reports through `onSwapFailed` unwrapped, and the swap ends `failed` only
|
|
1080
|
-
* past `refundLocktime + REFUND_MTP_LAG_SECONDS`. That is deliberate for a
|
|
1081
|
-
* genuinely transient failure — `LockupNeedsRecoveryError` is the
|
|
1082
|
-
* case it is built for, since recovery is something the caller can perform
|
|
1083
|
-
* while the window is still open — but it means a wiring mistake that
|
|
1084
|
-
* throws unconditionally does not read as `needs_counterparty`. It reports
|
|
1085
|
-
* once a poll for the rest of the refund window and then ends `failed`.
|
|
1086
|
-
* Throw {@link RefundNotLocallyPossibleError} for anything this wallet will
|
|
1087
|
-
* never be able to do.
|
|
1088
|
-
*/
|
|
1089
|
-
refundArkade: (swap: RfqSwap) => Promise<ArkadeRefundResult>;
|
|
1090
|
-
/**
|
|
1091
|
-
* Whether a local refund is possible at all — the record's secrets, against
|
|
1092
|
-
* this wallet. Called every pass, including *before* the refund window
|
|
1093
|
-
* opens, so a swap nobody can refund says so while the solver can still
|
|
1094
|
-
* act, instead of at the deadline; and so restoring the right wallet lifts
|
|
1095
|
-
* the state again. Never called for a receive swap: there is no local
|
|
1096
|
-
* refund there to probe for.
|
|
1097
|
-
*
|
|
1098
|
-
* Optional: omit to answer "yes" and learn at push time, from
|
|
1099
|
-
* {@link RefundNotLocallyPossibleError}. Local by contract — no network
|
|
1100
|
-
* call belongs here.
|
|
1101
|
-
*/
|
|
1102
|
-
canRefundArkade?: (swap: RfqSwap) => Promise<{
|
|
1103
|
-
ok: true;
|
|
1104
|
-
} | {
|
|
1105
|
-
ok: false;
|
|
1106
|
-
reason: string;
|
|
1107
|
-
}>;
|
|
1108
|
-
/**
|
|
1109
|
-
* Persist the record. Called after any pass that changed it.
|
|
1110
|
-
*
|
|
1111
|
-
* With {@link RfqSwapManagerDeps.repository} wired this is the SECOND
|
|
1112
|
-
* write of the pass, not the only one: the manager writes the canonical
|
|
1113
|
-
* `RfqSwapRecord` itself and then calls this. Both must succeed for the
|
|
1114
|
-
* pass to count as persisted, so a rejection here still holds waiters and
|
|
1115
|
-
* finalization back exactly as it does without a repository. A consumer
|
|
1116
|
-
* whose `saveSwap` writes that same repository by hand should
|
|
1117
|
-
* drop the duplicate when it wires the dep, and keep this for genuinely
|
|
1118
|
-
* secondary sinks: metrics, a cache, a second store.
|
|
1119
|
-
*/
|
|
1120
|
-
saveSwap: (swap: RfqSwap) => Promise<void>;
|
|
1121
|
-
}
|
|
1122
|
-
/**
|
|
1123
|
-
* What {@link RfqSwapManager.setCallbacks} accepts: the full contract, minus
|
|
1124
|
-
* the two claims that are already kind-gated at dispatch, and minus
|
|
1125
|
-
* `saveSwap`. A consumer driving only lightning sends reaches neither claim,
|
|
1126
|
-
* and stubbing them to throw is not a contract — it is a lie the compiler
|
|
1127
|
-
* waves through.
|
|
1128
|
-
*
|
|
1129
|
-
* `saveSwap` is optional for the same reason one step removed: with
|
|
1130
|
-
* {@link RfqSwapManagerDeps.repository} wired the manager writes the record
|
|
1131
|
-
* itself, so a consumer with no second sink has nothing to put here, and a
|
|
1132
|
-
* no-op stub would be that same lie. Omitting BOTH is the documented
|
|
1133
|
-
* process-local mode: state is kept in memory and dies with the process,
|
|
1134
|
-
* which is what a manager with no callbacks at all already does today.
|
|
1135
|
-
*
|
|
1136
|
-
* The strict {@link RfqSwapManagerCallbacks} is untouched and still means
|
|
1137
|
-
* "fully wired", so a helper that takes one and calls `claimOnchain` keeps its
|
|
1138
|
-
* guarantee. Only the parameter widens, which every existing caller satisfies.
|
|
1139
|
-
*
|
|
1140
|
-
* The compile-time guarantee this trades away is bought back at runtime: a
|
|
1141
|
-
* kind whose claim is missing blocks — non-terminal, re-evaluated every pass,
|
|
1142
|
-
* and lifted the moment `setCallbacks` supplies it.
|
|
1143
|
-
*
|
|
1144
|
-
* @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1145
|
-
*/
|
|
1146
|
-
type AvailableRfqSwapManagerCallbacks = Omit<RfqSwapManagerCallbacks, "claimOnchain" | "claimLockup" | "saveSwap"> & Partial<Pick<RfqSwapManagerCallbacks, "claimOnchain" | "claimLockup" | "saveSwap">>;
|
|
1147
|
-
/** The actions the manager executes on a caller's behalf.
|
|
1148
|
-
*
|
|
1149
|
-
* @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1150
|
-
*/
|
|
1151
|
-
type RfqSwapActionName = "claimOnchain" | "claimLockup" | "refundArkade";
|
|
1152
|
-
/** @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`. */
|
|
1153
|
-
interface RfqSwapManagerEvents {
|
|
1154
|
-
/** Every state change, including ones that read as going backwards.
|
|
1155
|
-
* `claimed -> claimable` is legal and expected on a receive swap the solver
|
|
1156
|
-
* funds piecemeal: a lockup topped up after a claim is a new claimable
|
|
1157
|
-
* event, and the label says so before the sweep goes out. Treat these
|
|
1158
|
-
* states as a description of what to do next, not as a progress bar. */
|
|
1159
|
-
onSwapUpdate?: (swap: RfqSwap, previous: RfqSwapState) => void;
|
|
1160
|
-
/** Fired once, when a swap leaves monitoring `settled` or `refunded`.
|
|
1161
|
-
* A swap that ends `failed` reports through `onSwapFailed` instead — the
|
|
1162
|
-
* two are mutually exclusive. */
|
|
1163
|
-
onSwapCompleted?: (swap: RfqSwap) => void;
|
|
1164
|
-
/** Fired for any action that threw — including ones the manager will retry
|
|
1165
|
-
* on the next pass — and once more when the swap finally ends `failed`. */
|
|
1166
|
-
onSwapFailed?: (swap: RfqSwap, error: Error) => void;
|
|
1167
|
-
onActionExecuted?: (swap: RfqSwap, action: RfqSwapActionName) => void;
|
|
1168
|
-
}
|
|
1169
|
-
type SwapUpdateListener = NonNullable<RfqSwapManagerEvents["onSwapUpdate"]>;
|
|
1170
|
-
type SwapCompletedListener = NonNullable<RfqSwapManagerEvents["onSwapCompleted"]>;
|
|
1171
|
-
type SwapFailedListener = NonNullable<RfqSwapManagerEvents["onSwapFailed"]>;
|
|
1172
|
-
type ActionExecutedListener = NonNullable<RfqSwapManagerEvents["onActionExecuted"]>;
|
|
1173
|
-
/** @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`. */
|
|
1174
|
-
interface RfqSwapManagerConfig {
|
|
1175
|
-
/** Drive claims and refunds automatically (default: true). With this off
|
|
1176
|
-
* the manager still watches and reports, so a caller can act by hand off
|
|
1177
|
-
* `claimable`. */
|
|
1178
|
-
enableAutoActions?: boolean;
|
|
1179
|
-
/** How often to run a pass, ms. Default 5000 — the same interval
|
|
1180
|
-
* `awaitOnchainFill` and `refundIfUnresolved` poll at. */
|
|
1181
|
-
pollIntervalMs?: number;
|
|
1182
|
-
/** Injected for tests; defaults to wall clock, in unix seconds — the same
|
|
1183
|
-
* convention `refundIfUnresolved` uses. */
|
|
1184
|
-
now?: () => number;
|
|
1185
|
-
events?: RfqSwapManagerEvents;
|
|
1186
|
-
}
|
|
1187
|
-
/** The contract-manager surface this needs, narrowed for injection — the same
|
|
1188
|
-
* seam style as {@link LockupSpendIndexer} and `refund.ts`'s
|
|
1189
|
-
* `RefundIndexer`, and satisfied structurally by a real
|
|
1190
|
-
* `ContractManager` (`await wallet.getContractManager()`).
|
|
1191
|
-
*
|
|
1192
|
-
* A root export because `SwapDriveConfig.contracts` takes it.
|
|
1193
|
-
*/
|
|
1194
|
-
type SwapContractRegistry = Pick<IContractManager, "createContract" | "getContracts" | "onContractEvent" | "setContractWatchState">;
|
|
1195
|
-
/**
|
|
1196
|
-
* The record store the manager writes to, narrowed to the four RFQ methods —
|
|
1197
|
-
* the same seam style as {@link LockupSpendIndexer} and
|
|
1198
|
-
* {@link SwapContractRegistry}, and satisfied structurally by a real
|
|
1199
|
-
* `AssetSwapRepository`.
|
|
1200
|
-
*
|
|
1201
|
-
* Narrowed rather than imported whole so this module keeps no runtime edge to
|
|
1202
|
-
* `repository.ts`, and so a caller with a different backing store — a server
|
|
1203
|
-
* process holding many wallets' records in one table — can satisfy it without
|
|
1204
|
-
* implementing the offer-swap and markets halves it has no use for.
|
|
1205
|
-
*
|
|
1206
|
-
* Expect TWO calls per dirty swap per poll: `getRfqSwap` then `saveRfqSwap`.
|
|
1207
|
-
* The read is deliberate — the store is the system of record, so a consumer's
|
|
1208
|
-
* own edit to a record's origin half must not be overwritten by a copy the
|
|
1209
|
-
* manager took at boot — but a backend where a keyed read is expensive should
|
|
1210
|
-
* know it is on the write path, not just the restore path.
|
|
1211
|
-
*
|
|
1212
|
-
* @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1213
|
-
*/
|
|
1214
|
-
interface RfqSwapRecordStore {
|
|
1215
|
-
saveRfqSwap(record: RfqSwapRecord): Promise<void>;
|
|
1216
|
-
getRfqSwap(rfqId: string): Promise<RfqSwapRecord | undefined>;
|
|
1217
|
-
getAllRfqSwaps(): Promise<RfqSwapRecord[]>;
|
|
1218
|
-
removeRfqSwap(rfqId: string): Promise<void>;
|
|
1219
|
-
}
|
|
1220
|
-
/**
|
|
1221
|
-
* A swap was handed to the manager with a repository wired, no origin, and no
|
|
1222
|
-
* record already in the store.
|
|
1223
|
-
*
|
|
1224
|
-
* Thrown at the door rather than at the first write, because the write happens
|
|
1225
|
-
* a pass later and by then the funding is broadcast: a swap admitted here and
|
|
1226
|
-
* refused at `save` would be monitored, acted on, and unwritable — the record
|
|
1227
|
-
* would exist only in memory while its lockup held money, and a restart would
|
|
1228
|
-
* lose it. The remedy is to pass the origin, which the caller has: it is what
|
|
1229
|
-
* the request entrypoint returned.
|
|
1230
|
-
*
|
|
1231
|
-
* @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1232
|
-
*/
|
|
1233
|
-
declare class RfqSwapOriginRequired extends Error {
|
|
1234
|
-
/** The swap that could not be admitted. */
|
|
1235
|
-
readonly rfqId: string;
|
|
1236
|
-
constructor(rfqId: string);
|
|
1237
|
-
}
|
|
1238
|
-
/** One stored record that could not be turned back into a live swap.
|
|
1239
|
-
*
|
|
1240
|
-
* @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1241
|
-
*/
|
|
1242
|
-
interface RfqRestoreFailure {
|
|
1243
|
-
rfqId: string;
|
|
1244
|
-
/** Why — a covenant that does not derive the funded address, a lockup with
|
|
1245
|
-
* no contract row, a corridor with no handler registered. */
|
|
1246
|
-
error: Error;
|
|
1247
|
-
}
|
|
1248
|
-
/** @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`. */
|
|
1249
|
-
interface RfqRestoreOptions {
|
|
1250
|
-
/**
|
|
1251
|
-
* Where each record's covenant parameters come from. Defaults to the
|
|
1252
|
-
* lockup's own contract row, read through
|
|
1253
|
-
* {@link RfqSwapManagerDeps.contracts}.
|
|
1254
|
-
*
|
|
1255
|
-
* Override it when the covenant lives somewhere else — a consumer keeping
|
|
1256
|
-
* its own copy of `VHTLCV2ContractHandler.serializeParams(...)`, or a
|
|
1257
|
-
* process with no contract manager at all. Whatever it returns is still
|
|
1258
|
-
* checked against the record's funded address by `rebuildRfqSwap`, so an
|
|
1259
|
-
* override cannot produce a swap watching the wrong covenant.
|
|
1260
|
-
*/
|
|
1261
|
-
params?: (record: RfqSwapRecord) => Promise<LockupParams>;
|
|
1262
|
-
}
|
|
1263
|
-
/** What {@link RfqSwapManager.restoreFromRepository} did. Every stored record
|
|
1264
|
-
* is in exactly one of the three lists.
|
|
1265
|
-
*
|
|
1266
|
-
* @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1267
|
-
*/
|
|
1268
|
-
interface RfqRestoreResult {
|
|
1269
|
-
/** Rebuilt: monitored, or kept as finished when already terminal. */
|
|
1270
|
-
restored: RfqSwap[];
|
|
1271
|
-
/** Kept in the store, but not rebuildable right now. */
|
|
1272
|
-
failed: RfqRestoreFailure[];
|
|
1273
|
-
/** Removed: terminal and past `RFQ_SWAP_RETENTION_SECONDS`. */
|
|
1274
|
-
pruned: string[];
|
|
1275
|
-
}
|
|
1276
|
-
/** The observation seams. None is owned by the manager, and none holds keys —
|
|
1277
|
-
* same philosophy as `onchainHtlc.ts`'s `ChainSource`. There is no
|
|
1278
|
-
* `RfqTransport` here on purpose: nothing this manager decides depends on the
|
|
1279
|
-
* solver answering (see the module doc).
|
|
1280
|
-
*
|
|
1281
|
-
* @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1282
|
-
*/
|
|
1283
|
-
interface RfqSwapManagerDeps {
|
|
1284
|
-
/** Arkade access. Required: this is how a swap's resolution is determined,
|
|
1285
|
-
* for both legs. */
|
|
1286
|
-
indexer: LockupSpendIndexer;
|
|
1287
|
-
/** L1 access. Required to monitor onchain-send swaps; a lightning-only
|
|
1288
|
-
* caller can leave it out. */
|
|
1289
|
-
chain?: ChainSource;
|
|
1290
|
-
/**
|
|
1291
|
-
* Where the manager persists RFQ swap records, when a caller wants it to.
|
|
1292
|
-
*
|
|
1293
|
-
* Wiring it makes the repository the CANONICAL sink: every pass that
|
|
1294
|
-
* changed a swap is written here as an {@link RfqSwapRecord}, and
|
|
1295
|
-
* {@link RfqSwapManager.restoreFromRepository} reads it back. That removes
|
|
1296
|
-
* the origin trap a caller otherwise hits assembling the write by hand —
|
|
1297
|
-
* `updateRfqSwapRecord` needs the existing record and
|
|
1298
|
-
* `createRfqSwapRecord` needs request-time facts the live swap does not
|
|
1299
|
-
* carry, so the first write of a swap cannot be composed from the swap
|
|
1300
|
-
* alone. The manager resolves that itself, which is what
|
|
1301
|
-
* {@link RfqSwapManager.addSwap}'s `origin` parameter is for.
|
|
1302
|
-
*
|
|
1303
|
-
* Optional, like every other dep here: without it the manager persists
|
|
1304
|
-
* through {@link RfqSwapManagerCallbacks.saveSwap} exactly as before, and
|
|
1305
|
-
* without either it keeps its state in memory.
|
|
1306
|
-
*/
|
|
1307
|
-
repository?: RfqSwapRecordStore;
|
|
1308
|
-
/**
|
|
1309
|
-
* The wallet's contract manager, when there is one. Optional in the same
|
|
1310
|
-
* way {@link chain} is: a caller with no wallet, or one that only wants the
|
|
1311
|
-
* timer, still gets a fully working manager — the subscription is a
|
|
1312
|
-
* LATENCY optimization and nothing depends on it.
|
|
1313
|
-
*
|
|
1314
|
-
* Supplying it buys two things. The lockup gets REGISTERED, which is what
|
|
1315
|
-
* puts it in the wallet's own contract set at all — a prerequisite for
|
|
1316
|
-
* anything that has to act on the lockup before its batch expires, since an
|
|
1317
|
-
* expired lockup is swept and loses every cooperative path. And the indexer
|
|
1318
|
-
* PUSHES its funding and its spend, so a settlement is noticed when it
|
|
1319
|
-
* happens rather than up to `pollIntervalMs` later.
|
|
1320
|
-
*
|
|
1321
|
-
* Prefer `await wallet.getContractManager()` over constructing one, the way
|
|
1322
|
-
* `createOffer` does.
|
|
1323
|
-
*/
|
|
1324
|
-
contracts?: SwapContractRegistry;
|
|
1325
|
-
}
|
|
1326
|
-
/**
|
|
1327
|
-
* Watches a set of live RFQ swaps and drives each to its end.
|
|
1328
|
-
*
|
|
1329
|
-
* One pass per swap, in this order, every
|
|
1330
|
-
* {@link RfqSwapManagerConfig.pollIntervalMs} — and additionally the moment a
|
|
1331
|
-
* contract event names that swap's lockup, which changes only WHEN a pass runs,
|
|
1332
|
-
* never what it concludes (see {@link subscribe}):
|
|
1333
|
-
*
|
|
1334
|
-
* 0. **Register the lockup**, if a contract manager was supplied and it is not
|
|
1335
|
-
* registered yet. Best-effort; never blocks the steps below.
|
|
1336
|
-
* 1. **Ask the chain what became of the lockup** — {@link readLockupFate}. A
|
|
1337
|
-
* spend whose witness HASHES to the quote's `payment_hash` ends the swap
|
|
1338
|
-
* `settled`; a lockup fully spent by anything else ends it `refunded`.
|
|
1339
|
-
* Anything the indexer could not answer is `unknown`, which is NOT an
|
|
1340
|
-
* answer: the pass carries on to the steps below, whose deadlines an indexer
|
|
1341
|
-
* outage has no bearing on. `exited` — an output unilaterally taken onchain
|
|
1342
|
-
* — ends neither the swap nor the pass: it blocks the Arkade half below,
|
|
1343
|
-
* with the L1 half left running.
|
|
1344
|
-
* 2. **Drive the trader's claim.** On an onchain send that is the L1 fill — see
|
|
1345
|
-
* {@link nextOnchainAction}. On a receive it is the lockup itself, and it
|
|
1346
|
-
* ends the pass: that leg has no step 3.
|
|
1347
|
-
* 3. **Take the lockup back**, send legs only, once `refundLocktime` has passed
|
|
1348
|
-
* and step 1 has not ended the swap. This runs for onchain-send too,
|
|
1349
|
-
* including after a successful claim: the trader's lockup is still funded and
|
|
1350
|
-
* still theirs to recover if the solver never comes for it. When no local
|
|
1351
|
-
* refund is possible at all — no secrets, another wallet's descriptor,
|
|
1352
|
-
* nothing wired — the swap reports `needs_counterparty` instead of retrying
|
|
1353
|
-
* a push that cannot work.
|
|
1354
|
-
*
|
|
1355
|
-
* **What step 1 proves depends on the direction.** On a send leg every non-claim
|
|
1356
|
-
* leaf pays the trader's own committed address or needs the trader's own
|
|
1357
|
-
* signature, so "spent, but not by a hash-verified claim" means the money came
|
|
1358
|
-
* back. On a receive leg those leaves are the SOLVER's and the claim leaf is the
|
|
1359
|
-
* trader's, so the same two readings mean the opposite things — `settled` is the
|
|
1360
|
-
* trader's own claim landing, `refunded` is the solver taking back a lockup the
|
|
1361
|
-
* trader failed to claim. The read is identical; only the state docs differ.
|
|
1362
|
-
*
|
|
1363
|
-
* Two things about the receive arm that are easy to get wrong, and are asserted
|
|
1364
|
-
* in the tests rather than left to be inferred:
|
|
1365
|
-
*
|
|
1366
|
-
* - **A claim is matched by its preimage, never by our txid.** The covenant's
|
|
1367
|
-
* `nonInteractiveClaim` leaf is pinned to the trader's own payout script, so a
|
|
1368
|
-
* claim that lands without us — covclaimd, the day it works — still pays the
|
|
1369
|
-
* trader and is still `settled`. Matching on the txid we submitted would turn
|
|
1370
|
-
* that success into an anomaly.
|
|
1371
|
-
* - **`LockupFate.fate === "claimed"` maps to the state `settled`, never to the
|
|
1372
|
-
* state `claimed`.** The two words live one layer apart: the fate is the
|
|
1373
|
-
* chain's, the state is ours, and the state `claimed` means only that we
|
|
1374
|
-
* submitted something.
|
|
1375
|
-
*
|
|
1376
|
-
* @deprecated Use `createSwapClient`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1377
|
-
*/
|
|
1378
|
-
declare class RfqSwapManager {
|
|
1379
|
-
private readonly deps;
|
|
1380
|
-
private readonly config;
|
|
1381
|
-
private callbacks;
|
|
1382
|
-
private readonly swapUpdateListeners;
|
|
1383
|
-
private readonly swapCompletedListeners;
|
|
1384
|
-
private readonly swapFailedListeners;
|
|
1385
|
-
private readonly actionExecutedListeners;
|
|
1386
|
-
private readonly monitored;
|
|
1387
|
-
/** Monitored swaps by lockup script hex, so a contract event — which names
|
|
1388
|
-
* a script and nothing else — can find the swap it belongs to. */
|
|
1389
|
-
private readonly byLockupScript;
|
|
1390
|
-
/**
|
|
1391
|
-
* Swaps whose lockup registration has been SETTLED one way or another,
|
|
1392
|
-
* mapped to whether a contract row actually resulted. Membership is what
|
|
1393
|
-
* stops a per-pass retry from becoming a per-pass round trip; the value is
|
|
1394
|
-
* what keeps a swap that could never be registered from later trying to
|
|
1395
|
-
* retire a row that does not exist, which would report a spurious failure
|
|
1396
|
-
* on a swap that in fact succeeded.
|
|
1397
|
-
*/
|
|
1398
|
-
private readonly registered;
|
|
1399
|
-
/**
|
|
1400
|
-
* Swaps whose `refundArkade` answered {@link RefundNotLocallyPossibleError}
|
|
1401
|
-
* in this process. Membership stops the push from being re-issued every
|
|
1402
|
-
* pass — it cannot start working on its own, and re-issuing it is the
|
|
1403
|
-
* grind `needs_counterparty` exists to remove. Only
|
|
1404
|
-
* {@link RfqSwapManagerCallbacks.canRefundArkade} clears it, so a caller
|
|
1405
|
-
* with no probe learns again on the next start, when the wallet that can
|
|
1406
|
-
* sign may well have been restored.
|
|
1407
|
-
*/
|
|
1408
|
-
private readonly refundRefused;
|
|
1409
|
-
/**
|
|
1410
|
-
* The lockup outpoints a receive swap's claim callback has already been
|
|
1411
|
-
* handed, by rfqId.
|
|
1412
|
-
*
|
|
1413
|
-
* What this exists to prevent: a claim SUCCEEDS, and for the next few
|
|
1414
|
-
* passes the indexer still lists those outputs as unspent. Without a
|
|
1415
|
-
* record of what was already claimed, every one of those passes would
|
|
1416
|
-
* re-submit the same spend, fail against the server, and report a swap
|
|
1417
|
-
* that in fact worked as failing. With one, a re-claim happens only when
|
|
1418
|
-
* an outpoint appears that was never claimed — a lockup funded piecemeal,
|
|
1419
|
-
* which is legitimate and which `partiallyClaimed` exists for.
|
|
1420
|
-
*
|
|
1421
|
-
* Process-local: after a restart a swap with a live claim tries once more.
|
|
1422
|
-
* That is the recovery case rather than the spam one — a claim that never
|
|
1423
|
-
* landed leaves its outputs unspent, and one that did leaves a single
|
|
1424
|
-
* rejection.
|
|
1425
|
-
*/
|
|
1426
|
-
private readonly claimedOutpoints;
|
|
1427
|
-
/** Live `onContractEvent` subscription, held so `stop()` can drop it. */
|
|
1428
|
-
private unsubscribeContracts;
|
|
1429
|
-
/** Terminal records, kept so a late {@link waitForSwapCompletion} still
|
|
1430
|
-
* answers instead of throwing "not found". Cleared by {@link removeSwap}. */
|
|
1431
|
-
private readonly finished;
|
|
1432
|
-
private readonly waiters;
|
|
1433
|
-
/**
|
|
1434
|
-
* The request-time origin of each swap the manager may have to CREATE a
|
|
1435
|
-
* record for, by rfqId.
|
|
1436
|
-
*
|
|
1437
|
-
* Needed only for a swap the store has never seen: once a record exists,
|
|
1438
|
-
* `updateRfqSwapRecord` carries the origin half through and the map is
|
|
1439
|
-
* redundant. It is kept anyway for the swap's whole life, so a record the
|
|
1440
|
-
* store loses between passes is rewritten rather than lost — and dropped
|
|
1441
|
-
* by {@link removeSwap} and by retention, which are the two places a swap
|
|
1442
|
-
* stops being this manager's business.
|
|
1443
|
-
*/
|
|
1444
|
-
private readonly origins;
|
|
1445
|
-
/** Records changed during the current pass, flushed to the repository and
|
|
1446
|
-
* through `saveSwap`. */
|
|
1447
|
-
private readonly dirty;
|
|
1448
|
-
/** Race guard: one action at a time per swap. */
|
|
1449
|
-
private readonly inProgress;
|
|
1450
|
-
private timer;
|
|
1451
|
-
private running;
|
|
1452
|
-
constructor(deps: RfqSwapManagerDeps, config?: RfqSwapManagerConfig);
|
|
1453
|
-
/** Wire the money-moving half. Without it the manager only watches. The
|
|
1454
|
-
* two claims may be omitted for a consumer that drives no kind reaching
|
|
1455
|
-
* them — see {@link AvailableRfqSwapManagerCallbacks}. */
|
|
1456
|
-
setCallbacks(callbacks: AvailableRfqSwapManagerCallbacks): void;
|
|
1457
|
-
onSwapUpdate(listener: SwapUpdateListener): () => void;
|
|
1458
|
-
onSwapCompleted(listener: SwapCompletedListener): () => void;
|
|
1459
|
-
onSwapFailed(listener: SwapFailedListener): () => void;
|
|
1460
|
-
onActionExecuted(listener: ActionExecutedListener): () => void;
|
|
1461
|
-
/**
|
|
1462
|
-
* Rebuild every stored swap and take over monitoring them.
|
|
1463
|
-
*
|
|
1464
|
-
* The composition a consumer otherwise writes by hand, and the one place
|
|
1465
|
-
* all four pieces meet: retention decides what to keep
|
|
1466
|
-
* (`shouldRetainRfqSwap`), the lockup's contract row supplies the covenant
|
|
1467
|
-
* (`lockupContractParams`), `rebuildRfqSwap` turns a record back into a
|
|
1468
|
-
* live swap, and each rebuilt swap arrives with its own origin, so nothing
|
|
1469
|
-
* is asked of the caller.
|
|
1470
|
-
*
|
|
1471
|
-
* **Deliberately not part of {@link start}.** A consumer that wants to
|
|
1472
|
-
* look at its records — count them, show them, prune and stop — is not
|
|
1473
|
-
* forced to start driving money to do it. Call this first and `start()`
|
|
1474
|
-
* after; a manager already running polls the restored swaps at once.
|
|
1475
|
-
*
|
|
1476
|
-
* Retention runs BEFORE the rebuild, so a record past
|
|
1477
|
-
* `RFQ_SWAP_RETENTION_SECONDS` costs no contract lookup on its way to being
|
|
1478
|
-
* dropped.
|
|
1479
|
-
*
|
|
1480
|
-
* **A record that cannot be rebuilt is reported, never swallowed and never
|
|
1481
|
-
* fatal.** `rebuildRfqSwap` throws by design when the covenant params do
|
|
1482
|
-
* not derive the funded address, and `lockupContractParams` throws
|
|
1483
|
-
* `LockupContractMissing` when the wallet has no row for the lockup — both
|
|
1484
|
-
* say something true about that one record, and neither is a reason to
|
|
1485
|
-
* strand the others. They come back in {@link RfqRestoreResult.failed}.
|
|
1486
|
-
*/
|
|
1487
|
-
restoreFromRepository(options?: RfqRestoreOptions): Promise<RfqRestoreResult>;
|
|
1488
|
-
/**
|
|
1489
|
-
* Drop stored records that are terminal and past
|
|
1490
|
-
* `RFQ_SWAP_RETENTION_SECONDS`, and return their ids.
|
|
1491
|
-
*
|
|
1492
|
-
* `needs_counterparty` is never dropped, however old: the money is still at
|
|
1493
|
-
* the lockup and the counterparty's move still ends the swap. That rule
|
|
1494
|
-
* lives in `shouldRetainRfqSwap`, which this defers to rather than
|
|
1495
|
-
* restating.
|
|
1496
|
-
*
|
|
1497
|
-
* Public because retention is a caller's cadence, not the manager's: a
|
|
1498
|
-
* long-lived process wants it on a timer of its own, a mobile app wants it
|
|
1499
|
-
* at boot. {@link restoreFromRepository} runs it first, so the boot path
|
|
1500
|
-
* needs no separate call.
|
|
1501
|
-
*/
|
|
1502
|
-
pruneRetiredSwaps(): Promise<string[]>;
|
|
1503
|
-
private dropRetired;
|
|
1504
|
-
private requireRepository;
|
|
1505
|
-
/** The default covenant source: the wallet's own contract row for each
|
|
1506
|
-
* lockup, which is where registration put it before the address could be
|
|
1507
|
-
* funded. */
|
|
1508
|
-
private paramsFromContracts;
|
|
1509
|
-
/**
|
|
1510
|
-
* Load records and begin monitoring. Runs one pass immediately — a caller
|
|
1511
|
-
* resuming after a restart may be well past a deadline already — then
|
|
1512
|
-
* every `pollIntervalMs`. Records that are already terminal are kept only
|
|
1513
|
-
* so {@link waitForSwapCompletion} can answer for them.
|
|
1514
|
-
*
|
|
1515
|
-
* Calling it again while running loads the records and returns rather than
|
|
1516
|
-
* re-arming — dropping them silently would strand a funded swap on a
|
|
1517
|
-
* caller's harmless double-start.
|
|
1518
|
-
*
|
|
1519
|
-
* The signature is unchanged with a {@link RfqSwapManagerDeps.repository}
|
|
1520
|
-
* wired; the origins are resolved from the store instead, by the same rule
|
|
1521
|
-
* {@link addSwap} applies. A swap the store has never seen throws
|
|
1522
|
-
* {@link RfqSwapOriginRequired} — hand that one to `addSwap` with its
|
|
1523
|
-
* origin, or restore the whole set with {@link restoreFromRepository},
|
|
1524
|
-
* which needs no caller input at all. Every swap is checked before any is
|
|
1525
|
-
* tracked, so a bad one in the list does not leave a half-loaded manager.
|
|
1526
|
-
*/
|
|
1527
|
-
start(swaps?: readonly RfqSwap[]): Promise<void>;
|
|
1528
|
-
/**
|
|
1529
|
-
* Stop monitoring and clear the timer. In-flight actions are not
|
|
1530
|
-
* cancellable and run to completion; outstanding
|
|
1531
|
-
* {@link waitForSwapCompletion} promises are left pending, since
|
|
1532
|
-
* stop/start is a pause rather than a cancellation.
|
|
1533
|
-
*
|
|
1534
|
-
* The contract subscription is dropped too — an open stream with nothing
|
|
1535
|
-
* reacting to it is a leak, and {@link start} puts it back. What is NOT
|
|
1536
|
-
* undone is the contract registration: those rows are the wallet's, they
|
|
1537
|
-
* outlive this manager's lifecycle, and dropping them would unwatch a
|
|
1538
|
-
* lockup that is still funded.
|
|
1539
|
-
*/
|
|
1540
|
-
stop(): Promise<void>;
|
|
1541
|
-
/**
|
|
1542
|
-
* Begin monitoring a swap. Polled immediately when the manager is running,
|
|
1543
|
-
* so a just-funded swap does not wait out a whole interval.
|
|
1544
|
-
*
|
|
1545
|
-
* `origin` is the request-time half a live swap cannot carry — the corridor,
|
|
1546
|
-
* the funded address, the corridor's profile, the funding txid — and it is
|
|
1547
|
-
* what lets the manager write this swap's FIRST record. Supply it whenever
|
|
1548
|
-
* a {@link RfqSwapManagerDeps.repository} is wired and the swap is new. It
|
|
1549
|
-
* may be omitted for a swap the store already holds a record for, which is
|
|
1550
|
-
* then read to confirm it; omitting it for one the store has never seen
|
|
1551
|
-
* throws {@link RfqSwapOriginRequired} rather than admitting a swap whose
|
|
1552
|
-
* record could never be written. With no repository wired the parameter is
|
|
1553
|
-
* inert.
|
|
1554
|
-
*/
|
|
1555
|
-
addSwap(swap: RfqSwap, origin?: RfqSwapOrigin): Promise<void>;
|
|
1556
|
-
/**
|
|
1557
|
-
* Settle where this swap's record will come from, before it is monitored.
|
|
1558
|
-
*
|
|
1559
|
-
* Three ways it can be answered, in order: the caller passed an origin, one
|
|
1560
|
-
* is already remembered from an earlier `addSwap`, or the store holds a
|
|
1561
|
-
* record — which is the origin, already written. Only the last costs a read,
|
|
1562
|
-
* and only when the first two are absent.
|
|
1563
|
-
*/
|
|
1564
|
-
private admit;
|
|
1565
|
-
/** Forget a swap entirely, monitored or finished.
|
|
1566
|
-
*
|
|
1567
|
-
* Its contract row is left alone: registration is a wallet-level fact about
|
|
1568
|
-
* a script that may still hold money, and this call says only that THIS
|
|
1569
|
-
* manager stops driving the swap. Retiring the row is reserved for a swap
|
|
1570
|
-
* that reached a terminal state, where the lockup is provably done. */
|
|
1571
|
-
removeSwap(rfqId: string): Promise<void>;
|
|
1572
|
-
/** Every swap still being monitored. */
|
|
1573
|
-
getPendingSwaps(): Promise<RfqSwap[]>;
|
|
1574
|
-
/**
|
|
1575
|
-
* Every swap this manager holds — {@link getPendingSwaps} plus the ones
|
|
1576
|
-
* that already ended. The two sets are disjoint: a swap leaves `monitored`
|
|
1577
|
-
* as it enters `finished`.
|
|
1578
|
-
*
|
|
1579
|
-
* The finished half is what this process has seen, which after
|
|
1580
|
-
* {@link restoreFromRepository} is the stored history minus what retention
|
|
1581
|
-
* pruned. A manager that has restored nothing answers with the live swaps
|
|
1582
|
-
* alone.
|
|
1583
|
-
*/
|
|
1584
|
-
getAllSwaps(): Promise<RfqSwap[]>;
|
|
1585
|
-
hasSwap(rfqId: string): Promise<boolean>;
|
|
1586
|
-
/** True while an action for this swap holds the per-swap lock. */
|
|
1587
|
-
isProcessing(rfqId: string): Promise<boolean>;
|
|
1588
|
-
getStats(): Promise<{
|
|
1589
|
-
isRunning: boolean;
|
|
1590
|
-
monitoredSwaps: number;
|
|
1591
|
-
finishedSwaps: number;
|
|
1592
|
-
inProgress: number;
|
|
1593
|
-
pollIntervalMs: number;
|
|
1594
|
-
}>;
|
|
1595
|
-
/**
|
|
1596
|
-
* Run one monitoring pass over every swap now.
|
|
1597
|
-
*
|
|
1598
|
-
* {@link start} calls this on an interval, but it is public on purpose: a
|
|
1599
|
-
* caller that sleeps its process (a mobile app resuming, a service worker
|
|
1600
|
-
* waking) wants a pass on that event rather than at the next tick. Passes
|
|
1601
|
-
* do not overlap per swap — the in-progress lock makes a concurrent call a
|
|
1602
|
-
* no-op for any swap already being worked on.
|
|
1603
|
-
*/
|
|
1604
|
-
poll(): Promise<void>;
|
|
1605
|
-
/**
|
|
1606
|
-
* Resolve once this swap's PAYOUT is decided — which for onchain-send is
|
|
1607
|
-
* the L1 claim, not the end of the record's life: once `claimTxid` is set
|
|
1608
|
-
* the trader has the coins it swapped for, and what remains is the manager
|
|
1609
|
-
* watching the Arkade lockup close. That holds however the record is
|
|
1610
|
-
* labelled afterwards, `needs_counterparty` included. Lightning-send has no
|
|
1611
|
-
* such split and resolves at `settled`/`refunded`, and so does lightning
|
|
1612
|
-
* receive — see {@link isPayoutDecided} for why its own claim txid does not
|
|
1613
|
-
* decide it.
|
|
1614
|
-
*
|
|
1615
|
-
* Rejects only on `failed`. `refunded` resolves: on a send leg a refund is
|
|
1616
|
-
* an outcome the caller asked this manager to drive, not an exception. On a
|
|
1617
|
-
* receive leg it is the swap being lost, which is still an answer and not
|
|
1618
|
-
* an error — read `state`, do not infer success from resolution.
|
|
1619
|
-
*/
|
|
1620
|
-
waitForSwapCompletion(rfqId: string): Promise<RfqSwapOutcome>;
|
|
1621
|
-
private track;
|
|
1622
|
-
/** Drops the swap from BOTH indexes. The event index is the one that stops
|
|
1623
|
-
* a late event finding a swap that is gone; `pollSwap`'s own
|
|
1624
|
-
* `monitored` check would also catch it, and deliberately still does —
|
|
1625
|
-
* either alone is sufficient, which is what keeps a future change to one of
|
|
1626
|
-
* them from silently re-driving a cancelled swap. */
|
|
1627
|
-
private untrack;
|
|
1628
|
-
/**
|
|
1629
|
-
* Turn the indexer's push into an extra reason to run a pass — and nothing
|
|
1630
|
-
* more.
|
|
1631
|
-
*
|
|
1632
|
-
* **This is deliberately not a source of truth.** An event names a script;
|
|
1633
|
-
* the reaction is to run the ordinary pass for the swap at that script, and
|
|
1634
|
-
* that pass re-reads the lockup through {@link readLockupFate} exactly as
|
|
1635
|
-
* the timer's pass does. So an event that is missed, duplicated, reordered
|
|
1636
|
-
* or outright FORGED can only cost or save latency — it can never change
|
|
1637
|
-
* what this manager believes about a swap, and it can never on its own
|
|
1638
|
-
* cause a claim or a refund. That property is what makes it safe to bolt a
|
|
1639
|
-
* best-effort stream onto a money path, and it must survive any future
|
|
1640
|
-
* change here: the moment an event is BELIEVED rather than merely acted on,
|
|
1641
|
-
* a relay outage becomes a correctness problem instead of a latency one.
|
|
1642
|
-
*
|
|
1643
|
-
* The timer stays armed regardless, and is the failsafe. Every deadline
|
|
1644
|
-
* that moves money — `refundLocktime`, the L1 claim window — is an absolute
|
|
1645
|
-
* timelock that passes whether or not a single event ever arrives.
|
|
1646
|
-
*/
|
|
1647
|
-
private subscribe;
|
|
1648
|
-
/**
|
|
1649
|
-
* Register this swap's lockup with the wallet's contract manager, once.
|
|
1650
|
-
*
|
|
1651
|
-
* The backstop, not the primary site: `requestLightningSend` /
|
|
1652
|
-
* `requestOnchainSend` register before the caller can fund, so this covers
|
|
1653
|
-
* swaps whose records predate that — and costs nothing when it does not,
|
|
1654
|
-
* since `createContract` is first-writer-wins.
|
|
1655
|
-
*
|
|
1656
|
-
* Best-effort by design: a failure here is reported and retried on the next
|
|
1657
|
-
* pass, and never aborts the pass it is part of. Registration buys latency
|
|
1658
|
-
* and puts the lockup in the wallet's contract set; it decides nothing. The
|
|
1659
|
-
* money path below it reads the indexer directly and is gated on timelocks
|
|
1660
|
-
* that a missing contract row has no bearing on, so failing the pass over
|
|
1661
|
-
* this would trade a real deadline for a bookkeeping one.
|
|
1662
|
-
*/
|
|
1663
|
-
private ensureRegistered;
|
|
1664
|
-
/** Stop watching a finished swap's lockup. Retained, not deleted: the row
|
|
1665
|
-
* is what keeps the lockup's own VTXOs annotatable and its history
|
|
1666
|
-
* readable, while `retained` is what drops it from the subscription and
|
|
1667
|
-
* the poll — a settled swap that stayed watched would cost the wallet a
|
|
1668
|
-
* script for its whole life. Best-effort — the swap is over either way. */
|
|
1669
|
-
private retireContract;
|
|
1670
|
-
private arm;
|
|
1671
|
-
private pollSwap;
|
|
1672
|
-
private runPass;
|
|
1673
|
-
/**
|
|
1674
|
-
* The lockup was unilaterally exited: its outputs sit onchain under the
|
|
1675
|
-
* VHTLC script, where no offchain claim or refund can reach them.
|
|
1676
|
-
*
|
|
1677
|
-
* `needs_counterparty` rather than a terminal state, because the money still
|
|
1678
|
-
* needs action and the swap can still end either way — an onchain claim can
|
|
1679
|
-
* reveal the preimage, an onchain refund can return it — and that state is
|
|
1680
|
-
* documented as re-checked every pass. It must be set from HERE and not from
|
|
1681
|
-
* inside `driveArkadeRefund`, whose two `unblock` calls would lift it again
|
|
1682
|
-
* on the very next pass.
|
|
1683
|
-
*/
|
|
1684
|
-
private blockExitedLockup;
|
|
1685
|
-
/**
|
|
1686
|
-
* The receive leg's whole state machine: claim the solver-funded lockup
|
|
1687
|
-
* while the window is open, and recognise the shapes in which it can be
|
|
1688
|
-
* lost.
|
|
1689
|
-
*
|
|
1690
|
-
* **The window closes at `refundLocktime`, on wall clock, with no margin.**
|
|
1691
|
-
* Both halves of that are deliberate. It closes there because publishing
|
|
1692
|
-
* `P` into the solver's live refund window risks losing the race and
|
|
1693
|
-
* handing over the preimage anyway — the hazard `ONCHAIN_CLAIM_MARGIN_SECONDS`
|
|
1694
|
-
* guards on the L1 side. It takes no margin because the two situations are
|
|
1695
|
-
* not alike: that one budgets for confirmation depth, while this claim is an
|
|
1696
|
-
* offchain spend that lands in seconds. Wall clock is already the
|
|
1697
|
-
* conservative reading — the solver's leaf is a CLTV, which matures against
|
|
1698
|
-
* median-time-past, and MTP trails wall clock — so the real window extends
|
|
1699
|
-
* PAST this deadline rather than ending before it. Every second of margin
|
|
1700
|
-
* subtracted here is a second of live claim window given away for nothing.
|
|
1701
|
-
*
|
|
1702
|
-
* **The trader has no move after it.** Nothing here can take the lockup
|
|
1703
|
-
* back, so once the window shuts the swap is the solver's to resolve and
|
|
1704
|
-
* this manager's job is to watch it happen and then stop.
|
|
1705
|
-
*/
|
|
1706
|
-
private driveReceiveClaim;
|
|
1707
|
-
/**
|
|
1708
|
-
* Claim what the solver funded, once it is enough.
|
|
1709
|
-
*
|
|
1710
|
-
* The value gate here decides WHEN to act. `pushClaim`'s decides whether
|
|
1711
|
-
* `P` is published, and runs with nothing between it and the signature —
|
|
1712
|
-
* the check that matters is the inner one, and this is not a reason to
|
|
1713
|
-
* relax it.
|
|
1714
|
-
*/
|
|
1715
|
-
private claimIfFunded;
|
|
1716
|
-
/** `handled` ends the pass; `continue` falls through to the refund gate. */
|
|
1717
|
-
private driveOnchain;
|
|
1718
|
-
private driveArkadeRefund;
|
|
1719
|
-
/** Whether any of these outputs has never been handed to the claim
|
|
1720
|
-
* callback — the only reason to claim a lockup a second time. */
|
|
1721
|
-
private hasUnclaimedOutpoint;
|
|
1722
|
-
private rememberClaimed;
|
|
1723
|
-
/**
|
|
1724
|
-
* L1 progress, which past the refund window must not overwrite a refusal.
|
|
1725
|
-
* The two halves are independent — a claimed fill says nothing about
|
|
1726
|
-
* whether this wallet can take the Arkade lockup back — and `claimed` is
|
|
1727
|
-
* re-asserted from chain on every pass, so without this a blocked swap
|
|
1728
|
-
* would flip between the two states forever. The claim itself always runs;
|
|
1729
|
-
* only the label defers, and only once the refund is the live half.
|
|
1730
|
-
*/
|
|
1731
|
-
private setOnchainState;
|
|
1732
|
-
/** The probe's refusal reason, or `undefined` when a local refund is
|
|
1733
|
-
* possible as far as anyone here can tell. A probe that throws is treated
|
|
1734
|
-
* as a refusal: a capability check that cannot answer is not a yes. */
|
|
1735
|
-
private probeRefusal;
|
|
1736
|
-
/** Report that no local refund will happen, without ending the swap. */
|
|
1737
|
-
private block;
|
|
1738
|
-
/** The way back out, taken as soon as the swap becomes actionable again.
|
|
1739
|
-
* Back to what the record can prove, not to `pending` unconditionally: a
|
|
1740
|
-
* swap that already made its claim has a txid for it, and reporting that
|
|
1741
|
-
* swap as `pending` would un-say something true. */
|
|
1742
|
-
private unblock;
|
|
1743
|
-
/**
|
|
1744
|
-
* Record which ark transactions ended the lockup.
|
|
1745
|
-
*
|
|
1746
|
-
* Only the ones the indexer actually named: `LockupSpend.txid` is
|
|
1747
|
-
* optional, and a checkpoint txid is not what history correlates on — a
|
|
1748
|
-
* record carrying one would name a transaction the wallet's own activity
|
|
1749
|
-
* never shows. Fewer txids is the right failure here.
|
|
1750
|
-
*
|
|
1751
|
-
* Assigned rather than merged: the fate is one read of the whole lockup,
|
|
1752
|
-
* so it is the complete answer for this swap, and a swap only reaches a
|
|
1753
|
-
* verdict once.
|
|
1754
|
-
*/
|
|
1755
|
-
private stampLockupSpends;
|
|
1756
|
-
/**
|
|
1757
|
-
* Keep the preimage that settled a Lightning send.
|
|
1758
|
-
*
|
|
1759
|
-
* Only that leg. A receive's `claimed` verdict reveals the wallet's own
|
|
1760
|
-
* claim secret and an onchain send's reveals the one it minted — both
|
|
1761
|
-
* already recoverable from `profile`, so stamping either would be a second
|
|
1762
|
-
* home for a secret that has one.
|
|
1763
|
-
*/
|
|
1764
|
-
private stampSettlementPreimage;
|
|
1765
|
-
private touch;
|
|
1766
|
-
private setState;
|
|
1767
|
-
/** Terminal failure. The `onSwapFailed` emission is left to
|
|
1768
|
-
* {@link finalize}, so this does not double-report. */
|
|
1769
|
-
private fail;
|
|
1770
|
-
private emitFailed;
|
|
1771
|
-
private emitAction;
|
|
1772
|
-
/**
|
|
1773
|
-
* Flush a changed record to every sink that is wired, and say whether all
|
|
1774
|
-
* of them took it.
|
|
1775
|
-
*
|
|
1776
|
-
* Up to two writes, in this order: the canonical `RfqSwapRecord` to
|
|
1777
|
-
* {@link RfqSwapManagerDeps.repository}, then
|
|
1778
|
-
* {@link RfqSwapManagerCallbacks.saveSwap}. Both gate — a rejection from
|
|
1779
|
-
* either leaves the record dirty and monitored, so waiters stay unsettled
|
|
1780
|
-
* and a terminal swap is not finalized until the write it claims lands.
|
|
1781
|
-
* That is exactly today's rule for `saveSwap`, applied to whichever sinks
|
|
1782
|
-
* exist; wiring the repository does not weaken it.
|
|
1783
|
-
*
|
|
1784
|
-
* The canonical write goes FIRST and a failure there skips the second.
|
|
1785
|
-
* `saveSwap` is a projection of the record, and projecting a state the
|
|
1786
|
-
* record of record has just refused would leave the secondary sink ahead
|
|
1787
|
-
* of the primary — the one ordering that survives no restart.
|
|
1788
|
-
*
|
|
1789
|
-
* With neither wired the state is process-local, which is what a manager
|
|
1790
|
-
* with no callbacks has always done.
|
|
1791
|
-
*/
|
|
1792
|
-
private save;
|
|
1793
|
-
/** The canonical write. True when there is no repository to write to. */
|
|
1794
|
-
private saveRecord;
|
|
1795
|
-
private originOrThrow;
|
|
1796
|
-
/**
|
|
1797
|
-
* Drop a terminal swap from monitoring and report it exactly once.
|
|
1798
|
-
*
|
|
1799
|
-
* `onSwapCompleted` and `onSwapFailed` are mutually exclusive here: a
|
|
1800
|
-
* listener named "completed" that also fires on failure is a trap, so a
|
|
1801
|
-
* swap that leaves monitoring reports through exactly one of them.
|
|
1802
|
-
*/
|
|
1803
|
-
private finalize;
|
|
1804
|
-
private settleWaiters;
|
|
1805
|
-
}
|
|
1806
|
-
/** What {@link RfqSwapManager.waitForSwapCompletion} reports. `txid` is the
|
|
1807
|
-
* trader's own claim — L1 for a claimed onchain send, Arkade for a claimed
|
|
1808
|
-
* receive — or the ark txid for a refund the trader pushed; a solver-side
|
|
1809
|
-
* settlement or refund carries none, and a receive swap that ended `refunded`
|
|
1810
|
-
* carries none either, however far its claim got (see {@link outcomeOf}). So
|
|
1811
|
-
* a `txid` here always names something that happened, and `state` remains the
|
|
1812
|
-
* only thing to read for whether the swap paid out.
|
|
1813
|
-
*
|
|
1814
|
-
* @deprecated Use `createSwapClient` and `client.onUpdate()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1815
|
-
*/
|
|
1816
|
-
interface RfqSwapOutcome {
|
|
1817
|
-
state: RfqSwapState;
|
|
1818
|
-
txid?: string;
|
|
1819
|
-
}
|
|
1820
|
-
|
|
1821
|
-
/**
|
|
1822
|
-
* The swap kinds this projection covers — all three the manager monitors.
|
|
1823
|
-
*
|
|
1824
|
-
* `onchain_send` carries an L1 half nothing else can rebuild. Its Arkade lockup
|
|
1825
|
-
* has a contract row like the others, but the HTLC is Bitcoin L1, not an Arkade
|
|
1826
|
-
* contract, so no row exists for it; and `OnchainHtlc` exposes only derived
|
|
1827
|
-
* values — `address`, `pkScript`, `leaves`, `controlBlocks` — never the
|
|
1828
|
-
* `claimKey`/`refundKey` `onchainHtlcScript` takes as inputs. So they ride in
|
|
1829
|
-
* that corridor's {@link RfqSwapOrigin.profile}, and without them a restored
|
|
1830
|
-
* swap would let its L1 refund window pass unwatched.
|
|
1831
|
-
*
|
|
1832
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1833
|
-
*/
|
|
1834
|
-
type PersistableRfqSwap = LightningSendSwap | LightningReceiveSwap | OnchainSendSwap;
|
|
1835
|
-
/**
|
|
1836
|
-
* The serialized covenant parameters a rebuild is given.
|
|
1837
|
-
*
|
|
1838
|
-
* `VHTLCV2ContractHandler`'s own wire shape — what `serializeParams` writes and
|
|
1839
|
-
* `createScript` reads — which is exactly what a lockup's contract row stores
|
|
1840
|
-
* under `params`.
|
|
1841
|
-
*
|
|
1842
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1843
|
-
*/
|
|
1844
|
-
type LockupParams = Record<string, string>;
|
|
1845
|
-
/**
|
|
1846
|
-
* How long a retired swap's record is kept, in SECONDS.
|
|
1847
|
-
*
|
|
1848
|
-
* Terminal records are history, not garbage: the covenant's spender is a
|
|
1849
|
-
* transaction the wallet never signed, so its own history cannot reconstruct
|
|
1850
|
-
* them. Kept for a month, then dropped so a hot wallet's store stays bounded.
|
|
1851
|
-
*
|
|
1852
|
-
* Seconds, not milliseconds, because that is the unit `RfqSwap.updatedAt`
|
|
1853
|
-
* carries; the manager stamps it from `RfqSwapManagerConfig.now`, which is
|
|
1854
|
-
* "wall clock, in unix seconds". Comparing it against `Date.now()` would drop
|
|
1855
|
-
* every terminal record after ~43 minutes.
|
|
1856
|
-
*
|
|
1857
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1858
|
-
*/
|
|
1859
|
-
declare const RFQ_SWAP_RETENTION_SECONDS: number;
|
|
1860
|
-
/** The immutable request-time half, and only what EVERY corridor has. Hex for
|
|
1861
|
-
* everything binary, so the record is plain JSON and survives any
|
|
1862
|
-
* structured-clone backend unchanged.
|
|
1863
|
-
*
|
|
1864
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1865
|
-
*/
|
|
1866
|
-
interface RfqSwapOrigin {
|
|
1867
|
-
/**
|
|
1868
|
-
* Which corridor this is. Resolves the handler that owns {@link profile};
|
|
1869
|
-
* see `rfqCorridor.ts`.
|
|
1870
|
-
*
|
|
1871
|
-
* The manager's own union, not an open string: `RfqSwapManager` branches on
|
|
1872
|
-
* `kind` to decide what to drive, so a corridor it does not know could be
|
|
1873
|
-
* persisted and rebuilt here and then never driven — which is the failure
|
|
1874
|
-
* this whole file is arranged to make impossible.
|
|
1875
|
-
*/
|
|
1876
|
-
kind: PersistableRfqSwap["kind"];
|
|
1877
|
-
/**
|
|
1878
|
-
* The Arkade address that was funded.
|
|
1879
|
-
*
|
|
1880
|
-
* Both the swap's handle on its covenant — {@link lockupContractParams}
|
|
1881
|
-
* looks the contract row up by the script it decodes to — and, being taken
|
|
1882
|
-
* from the entry point rather than re-derived, the check that the
|
|
1883
|
-
* parameters a caller supplies belong to THIS swap.
|
|
1884
|
-
*/
|
|
1885
|
-
lockupAddress: string;
|
|
1886
|
-
/**
|
|
1887
|
-
* The corridor's own half, as plain JSON — written by the caller from the
|
|
1888
|
-
* request result, kept current by the handler's `project`.
|
|
1889
|
-
*
|
|
1890
|
-
* Opaque here on purpose. Nothing in this file, the repository or the
|
|
1891
|
-
* IndexedDB store interprets it, which is what lets a new corridor ship
|
|
1892
|
-
* without touching any of them. It carries the corridor's keys as well as
|
|
1893
|
-
* its state: `signer` (which wallet key signs this leg) and, on a corridor
|
|
1894
|
-
* locked to a preimage, `hashlock` — see `rfqProfileParts.ts`, and write
|
|
1895
|
-
* both with `rfqSecretsProfile` rather than by hand.
|
|
1896
|
-
*
|
|
1897
|
-
* Not a consumer scratchpad: every write merges it as `{ ...profile,
|
|
1898
|
-
* ...handler.project(swap) }`, so a consumer key colliding with one the
|
|
1899
|
-
* handler projects is silently overwritten on every pass.
|
|
1900
|
-
*/
|
|
1901
|
-
profile: Record<string, unknown>;
|
|
1902
|
-
/** Consumer display metadata. The rebuild ignores it — `RfqSwapCommon`
|
|
1903
|
-
* carries no amount of its own. */
|
|
1904
|
-
amount?: number;
|
|
1905
|
-
/**
|
|
1906
|
-
* The ark transaction that funded {@link lockupAddress}.
|
|
1907
|
-
*
|
|
1908
|
-
* Origin, not manager state: the caller broadcasts the funding and knows
|
|
1909
|
-
* its txid, while the manager watches the lockup by script and never
|
|
1910
|
-
* learns it. So it is written once at record creation, like {@link amount},
|
|
1911
|
-
* and no corridor `project` emits it.
|
|
1912
|
-
*/
|
|
1913
|
-
fundingTxid?: string;
|
|
1914
|
-
}
|
|
1915
|
-
/** The stored record: the origin plus the manager's mutable state.
|
|
1916
|
-
*
|
|
1917
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1918
|
-
*/
|
|
1919
|
-
interface RfqSwapRecord extends RfqSwapOrigin {
|
|
1920
|
-
rfqId: string;
|
|
1921
|
-
state: RfqSwapState;
|
|
1922
|
-
createdAt: number;
|
|
1923
|
-
updatedAt: number;
|
|
1924
|
-
refundTxid?: string;
|
|
1925
|
-
/** The ark transactions that spent the lockup, stamped by the manager from
|
|
1926
|
-
* the chain read that ended the swap. See
|
|
1927
|
-
* `RfqSwapCommon.lockupSpendTxids`. */
|
|
1928
|
-
lockupSpendTxids?: string[];
|
|
1929
|
-
/** The preimage that settled a Lightning send, stamped by the manager from
|
|
1930
|
-
* the same chain read. See `RfqSwapCommon.settlementPreimageHex`. */
|
|
1931
|
-
settlementPreimageHex?: string;
|
|
1932
|
-
failure?: string;
|
|
1933
|
-
/** Last local receive-claim error while the swap is still retryable. */
|
|
1934
|
-
claimFailure?: string;
|
|
1935
|
-
blockedReason?: string;
|
|
1936
|
-
}
|
|
1937
|
-
/**
|
|
1938
|
-
* A stored record read under the current field names.
|
|
1939
|
-
*
|
|
1940
|
-
* Four fields were renamed after `0.0.9`: `fundingArkTxid`, `refundArkTxid`,
|
|
1941
|
-
* `lockupSpendArkTxids`, and the receive corridor's `profile.claimArkTxid`. All
|
|
1942
|
-
* four arrived together with record persistence itself in `0.0.8`, so `0.0.8`
|
|
1943
|
-
* and `0.0.9` are the only versions that ever wrote them. Backends store the
|
|
1944
|
-
* record WHOLE, so such a store still holds the old names on disk and the
|
|
1945
|
-
* current code reads every one of them as `undefined`.
|
|
1946
|
-
*
|
|
1947
|
-
* Called by every function here that takes a record, so a consumer needs no
|
|
1948
|
-
* boot-time migration of its own; and because the old keys never reach the
|
|
1949
|
-
* object handed back, the next write persists the record without them.
|
|
1950
|
-
*
|
|
1951
|
-
* What it buys, in descending order of sharpness: a receive leg with a partial
|
|
1952
|
-
* claim already out keeps its `claimTxid`, so the value gate stays disarmed
|
|
1953
|
-
* rather than re-blocking the rest of a lockup whose preimage is public;
|
|
1954
|
-
* `refunded` swaps report an outcome txid again; and activity answers from the
|
|
1955
|
-
* record instead of falling back to a lockup read per query. It is NOT a
|
|
1956
|
-
* re-refund fix — `refunded` is terminal, and `restoreFromRepository` puts a
|
|
1957
|
-
* terminal record straight into `finished` without ever driving it.
|
|
1958
|
-
*
|
|
1959
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1960
|
-
*/
|
|
1961
|
-
declare function normalizeRfqSwapRecord(record: RfqSwapRecord): RfqSwapRecord;
|
|
1962
|
-
/** First write, at the moment the caller hands the swap to the manager.
|
|
1963
|
-
*
|
|
1964
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1965
|
-
*/
|
|
1966
|
-
declare function createRfqSwapRecord(origin: RfqSwapOrigin, swap: PersistableRfqSwap): RfqSwapRecord;
|
|
1967
|
-
/**
|
|
1968
|
-
* Every later write. The origin half is carried through untouched.
|
|
1969
|
-
*
|
|
1970
|
-
* The mutable half is REPLACED, not merged. `managerState` omits a key the live
|
|
1971
|
-
* swap no longer carries, so spreading it over the old record could only ever
|
|
1972
|
-
* set these fields, never clear them. The manager clears them on purpose: it
|
|
1973
|
-
* deletes `blockedReason` when a swap leaves `needs_counterparty` and
|
|
1974
|
-
* `claimFailure` when a swap becomes terminal, precisely because stale mutable
|
|
1975
|
-
* reasons read as live refusal or retry state.
|
|
1976
|
-
*
|
|
1977
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1978
|
-
*/
|
|
1979
|
-
declare function updateRfqSwapRecord(record: RfqSwapRecord, swap: PersistableRfqSwap): RfqSwapRecord;
|
|
1980
|
-
/**
|
|
1981
|
-
* The immutable half of a stored record, on its own.
|
|
1982
|
-
*
|
|
1983
|
-
* A record IS an origin plus manager state, so `record` where an
|
|
1984
|
-
* {@link RfqSwapOrigin} is wanted type-checks — and is a bug. Spread into
|
|
1985
|
-
* {@link createRfqSwapRecord} it carries the OLD state's `failure`,
|
|
1986
|
-
* `blockedReason`, `claimFailure` and `refundTxid` past `managerState`, which omits
|
|
1987
|
-
* fields the live swap no longer has and therefore cannot clear them. That is the same
|
|
1988
|
-
* trap {@link updateRfqSwapRecord} strips those mutable fields to avoid; this is
|
|
1989
|
-
* how a caller holding only a record gets an origin that is safe to keep.
|
|
1990
|
-
*
|
|
1991
|
-
* What `RfqSwapManager.restoreFromRepository` remembers for each record it
|
|
1992
|
-
* rebuilds, so a later write can create the record again if the store lost it.
|
|
1993
|
-
*
|
|
1994
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
1995
|
-
*/
|
|
1996
|
-
declare function rfqSwapOriginOf(record: RfqSwapRecord): RfqSwapOrigin;
|
|
1997
|
-
/**
|
|
1998
|
-
* Rebuild the live record. Pure, and synchronous, given the covenant's
|
|
1999
|
-
* parameters.
|
|
2000
|
-
*
|
|
2001
|
-
* Hand the result to {@link RfqSwapManager.start}. Take `params` from the
|
|
2002
|
-
* lockup's contract row — {@link lockupContractParams} is the one-liner — or
|
|
2003
|
-
* from a copy of `VHTLCV2ContractHandler.serializeParams(script.options)` a
|
|
2004
|
-
* consumer keeps itself; either way they are checked against the address that
|
|
2005
|
-
* was actually funded, so the `lockupPkScript` this produces is the one the
|
|
2006
|
-
* funded lockup is keyed by.
|
|
2007
|
-
*
|
|
2008
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
2009
|
-
*/
|
|
2010
|
-
declare function rebuildRfqSwap(record: RfqSwapRecord, params: LockupParams): PersistableRfqSwap;
|
|
2011
|
-
/**
|
|
2012
|
-
* Whether a retired swap's record should be kept.
|
|
2013
|
-
*
|
|
2014
|
-
* `needs_counterparty` is deliberately not terminal and is never dropped: the
|
|
2015
|
-
* money is still at the lockup, the counterparty's move is still what ends the
|
|
2016
|
-
* swap, and the refusal is re-checked every pass; restoring the right wallet
|
|
2017
|
-
* returns it to `pending`.
|
|
2018
|
-
*
|
|
2019
|
-
* @param now Current time in **unix seconds**; the same unit as
|
|
2020
|
-
* `RfqSwap.updatedAt`, which the manager stamps from
|
|
2021
|
-
* `RfqSwapManagerConfig.now`. Pass `Math.floor(Date.now() / 1000)`, never
|
|
2022
|
-
* `Date.now()`: milliseconds against a seconds window would retire every
|
|
2023
|
-
* terminal record after ~43 minutes.
|
|
2024
|
-
*
|
|
2025
|
-
* @deprecated `accept()` writes the record; read it with `client.swaps()`. Moved off the package root to `@arkade-os/swap/protocol`.
|
|
2026
|
-
*/
|
|
2027
|
-
declare function shouldRetainRfqSwap(record: RfqSwapRecord, now: number): boolean;
|
|
2028
|
-
|
|
2029
|
-
/**
|
|
2030
|
-
* What the codec needs from an asset, and nothing else. Structural, so
|
|
2031
|
-
* discovery's `AssetInfo` satisfies it directly and this module reaches for no
|
|
2032
|
-
* network layer. There is no id-to-decimals lookup at M1: that needs the
|
|
2033
|
-
* registry M3 builds, and M3 adds an id-taking convenience on top of this rather
|
|
2034
|
-
* than replacing it.
|
|
2035
|
-
*/
|
|
2036
|
-
interface AssetScale {
|
|
2037
|
-
decimals: number;
|
|
2038
|
-
}
|
|
2039
|
-
declare const ATOMIC_DECIMAL: unique symbol;
|
|
2040
|
-
/** Atomic units written out: the form records and the wire hold. */
|
|
2041
|
-
type AtomicDecimal = string & {
|
|
2042
|
-
readonly [ATOMIC_DECIMAL]: true;
|
|
2043
|
-
};
|
|
2044
|
-
/** A string that is provably not an {@link AtomicDecimal}; plain strings qualify. */
|
|
2045
|
-
type DisplayDecimal = string & {
|
|
2046
|
-
readonly [ATOMIC_DECIMAL]?: never;
|
|
2047
|
-
};
|
|
2048
|
-
/** Why an amount was refused. */
|
|
2049
|
-
type AmountRefusal = "not_decimal" | "negative" | "too_precise" | "too_large" | "invalid_decimals" | "not_canonical";
|
|
2050
|
-
/**
|
|
2051
|
-
* An amount that cannot be represented in the form asked for.
|
|
2052
|
-
*
|
|
2053
|
-
* Not a member of the §7 `SwapError` taxonomy: that taxonomy is the client
|
|
2054
|
-
* surface's, thrown by a verb before value moves, and this is a codec refusing
|
|
2055
|
-
* its input before a swap exists. The wire's compatibility failure is different
|
|
2056
|
-
* and does have a member — `AmountEncodingUnsupported`, in `rfqAmount.ts`.
|
|
2057
|
-
*/
|
|
2058
|
-
declare class AmountFormatError extends Error {
|
|
2059
|
-
readonly reason: AmountRefusal;
|
|
2060
|
-
readonly name = "AmountFormatError";
|
|
2061
|
-
constructor(reason: AmountRefusal, message: string);
|
|
2062
|
-
}
|
|
2063
|
-
declare const Amount: {
|
|
2064
|
-
/**
|
|
2065
|
-
* A human decimal into atomic units.
|
|
2066
|
-
*
|
|
2067
|
-
* `string` only, and no exponent. Accepting a `number` is the whole v1
|
|
2068
|
-
* footgun: it makes `100000` ambiguous between sats and whole BTC, and by
|
|
2069
|
-
* the time the ambiguity resolves the offer is funded. Exponent form goes
|
|
2070
|
-
* for the same reason — a UI never produces `1e-4`, so accepting it only
|
|
2071
|
-
* widens what a mistake can look like.
|
|
2072
|
-
*
|
|
2073
|
-
* Refuses rather than rounds when the input is finer than the asset: a
|
|
2074
|
-
* silently truncated amount is a swap for the wrong size, and nothing
|
|
2075
|
-
* downstream can tell it was ever a different number. Refuses too when the
|
|
2076
|
-
* result would not survive the record boundary, so one law holds in both
|
|
2077
|
-
* directions.
|
|
2078
|
-
*/
|
|
2079
|
-
parse(display: DisplayDecimal, asset: AssetScale): bigint;
|
|
2080
|
-
/**
|
|
2081
|
-
* Atomic units into a human decimal, trailing zeros trimmed.
|
|
2082
|
-
*
|
|
2083
|
-
* Refuses a negative: every amount on this surface is an obligation, and a
|
|
2084
|
-
* negative one is a defect upstream rather than a number to render.
|
|
2085
|
-
*/
|
|
2086
|
-
format(value: bigint, asset: AssetScale): string;
|
|
2087
|
-
};
|
|
2088
|
-
/**
|
|
2089
|
-
* Atomic units into the canonical decimal string records and the wire hold:
|
|
2090
|
-
* discovery's `AMOUNT_PATTERN` — unsigned, no leading zeros, at most 30 digits.
|
|
2091
|
-
*/
|
|
2092
|
-
declare const toAtomicDecimal: (value: bigint) => AtomicDecimal;
|
|
2093
|
-
/**
|
|
2094
|
-
* The canonical decimal string back into atomic units.
|
|
2095
|
-
*
|
|
2096
|
-
* Takes a plain `string` on purpose: it is what a record read and a `JSON.parse`
|
|
2097
|
-
* hand back, and demanding a cast would put one on the safe direction.
|
|
2098
|
-
*/
|
|
2099
|
-
declare const fromAtomicDecimal: (text: string) => bigint;
|
|
2100
|
-
/** Whether `value` is already in the canonical atomic form. */
|
|
2101
|
-
declare const isAtomicDecimal: (value: unknown) => value is AtomicDecimal;
|
|
2102
|
-
|
|
2103
|
-
/**
|
|
2104
|
-
* Asset identity for the v2 client: CAIP-19 with the rail as the CAIP-2
|
|
2105
|
-
* namespace — `<rail>:<network>/<asset-ns>:<reference>`.
|
|
2106
|
-
*
|
|
2107
|
-
* The rail is the namespace rather than the settlement chain because sameness
|
|
2108
|
-
* across rails is then a comparison on the asset part instead of a shared
|
|
2109
|
-
* string: `arkade:bitcoin/slip44:0` and `bitcoin:bitcoin/slip44:0` are one BTC
|
|
2110
|
-
* on two rails, and nothing has to agree on a single id for them. Arkade has no
|
|
2111
|
-
* CAIP-2 namespace and no bitcoin-chain identity to nest under, so
|
|
2112
|
-
* `bip122:…/arkade:…` would assert a relationship it does not have.
|
|
2113
|
-
*
|
|
2114
|
-
* These ids parse under CAIP-19 and resolve under no published namespace spec:
|
|
2115
|
-
* `arkade`, `bitcoin` and `bolt11` are registered in no CASA registry. That is
|
|
2116
|
-
* the price of naming rails instead of chains, and it costs nothing here — this
|
|
2117
|
-
* module is the grammar, and what an id *means* is the alias layer's job.
|
|
2118
|
-
*/
|
|
2119
|
-
|
|
2120
|
-
/**
|
|
2121
|
-
* A CAIP-2 namespace this client can spell. Closed rather than open to the
|
|
2122
|
-
* CAIP-2 character class, so a rail nobody implements is a parse failure here
|
|
2123
|
-
* rather than a lookup miss three layers down.
|
|
2124
|
-
*
|
|
2125
|
-
* `bolt11` is lightning: CAIP-2 caps a namespace at eight characters, which
|
|
2126
|
-
* `lightning` overruns, and floors it at three, which `ln` misses. It names the
|
|
2127
|
-
* instrument the rail carries today; BOLT12 is a separate corridor when it
|
|
2128
|
-
* ships.
|
|
2129
|
-
*
|
|
2130
|
-
* `eip155` is grammar and nothing else. §9's EVM corridor is deferred, and §9
|
|
2131
|
-
* exists to prove the seams hold, so its own examples have to parse; the
|
|
2132
|
-
* refusal belongs where a route is chosen, not where a string is read, and the
|
|
2133
|
-
* alias layer is where it happens.
|
|
2134
|
-
*/
|
|
2135
|
-
declare const RAILS: readonly ["arkade", "bitcoin", "bolt11", "eip155"];
|
|
2136
|
-
type Rail = (typeof RAILS)[number];
|
|
2137
|
-
/** The rails whose CAIP-2 reference is a bitcoin network rather than a chain id. */
|
|
2138
|
-
declare const BITCOIN_RAILS: readonly ["arkade", "bitcoin", "bolt11"];
|
|
2139
|
-
type BitcoinRail = (typeof BITCOIN_RAILS)[number];
|
|
2140
|
-
/**
|
|
2141
|
-
* The network half of a bitcoin-family chain part: core's own
|
|
2142
|
-
* {@link NetworkName}, because the wallet is the only source of the network —
|
|
2143
|
-
* v2 accepts no server URL anywhere — and this is the vocabulary a wallet
|
|
2144
|
-
* resolves to.
|
|
2145
|
-
*
|
|
2146
|
-
* It is one wider than discovery's `NETWORKS`, which omits `testnet`. That
|
|
2147
|
-
* difference belongs to the alias layer and not to the grammar: an asset on
|
|
2148
|
-
* testnet exists whether or not anyone publishes a market index for it, so
|
|
2149
|
-
* amputating the identity to match the index would make a network the SDK fully
|
|
2150
|
-
* supports unnameable.
|
|
2151
|
-
*/
|
|
2152
|
-
type NetworkRef = NetworkName;
|
|
2153
|
-
type BitcoinAssetId<R extends BitcoinRail> = `${R}:${NetworkRef}/${string}:${string}`;
|
|
2154
|
-
/**
|
|
2155
|
-
* A public asset id.
|
|
2156
|
-
*
|
|
2157
|
-
* A template literal type and not `string`, which is what makes the other three
|
|
2158
|
-
* asset spellings in this package — core's 68-hex `asset.AssetId#toString()`,
|
|
2159
|
-
* discovery's `AssetInfo.id`, the RFQ leg's `arkade:BTC` — a compile error in a
|
|
2160
|
-
* slot that wants a public id, rather than a wrong pair string three layers
|
|
2161
|
-
* down. The rail parameter carries that further: `AssetId<"arkade">` accepts no
|
|
2162
|
-
* `bitcoin:` string, which is what makes an endpoint whose corridor and asset
|
|
2163
|
-
* disagree a compile error (see `route.ts`).
|
|
2164
|
-
*
|
|
2165
|
-
* Deliberately not branded — `client.quote({ give: "arkade:bitcoin/slip44:0" })`
|
|
2166
|
-
* must stay writable, and the spec's own examples are written that way — so the
|
|
2167
|
-
* shape is what the type checks and {@link parseAssetId} is the gate for
|
|
2168
|
-
* everything else. A value out of a record or off the wire is a `string`: parse
|
|
2169
|
-
* it, never cast it.
|
|
2170
|
-
*/
|
|
2171
|
-
type AssetId<R extends Rail = Rail> = R extends BitcoinRail ? BitcoinAssetId<R> : `eip155:${number}/${string}:${string}`;
|
|
2172
|
-
/** The `<asset-ns>:<reference>` half of an id — what sameness compares. */
|
|
2173
|
-
type AssetPart = `${string}:${string}`;
|
|
2174
|
-
/** BTC's asset part on every rail that carries it (SLIP-44 coin type 0). */
|
|
2175
|
-
declare const BTC_ASSET_PART = "slip44:0";
|
|
2176
|
-
/** The asset namespace an Arkade-issued asset takes. */
|
|
2177
|
-
declare const ARKADE_ASSET_NAMESPACE = "asset";
|
|
2178
|
-
interface ParsedAssetId {
|
|
2179
|
-
/** CAIP-2 namespace. */
|
|
2180
|
-
readonly rail: Rail;
|
|
2181
|
-
/**
|
|
2182
|
-
* CAIP-2 reference: the bitcoin network on a bitcoin-family rail, the
|
|
2183
|
-
* decimal chain id on `eip155`.
|
|
2184
|
-
*/
|
|
2185
|
-
readonly reference: string;
|
|
2186
|
-
/** CAIP-19 asset namespace — `slip44`, `asset`, `erc20`. */
|
|
2187
|
-
readonly assetNamespace: AssetNamespace;
|
|
2188
|
-
/** CAIP-19 asset reference. */
|
|
2189
|
-
readonly assetReference: string;
|
|
2190
|
-
}
|
|
2191
|
-
/** Why an id was refused. Stable strings; callers switch on them. */
|
|
2192
|
-
type AssetIdRefusal = "malformed" | "uppercase" | "unknown_rail" | "unknown_network" | "invalid_chain_id" | "unknown_asset_namespace" | "invalid_asset_reference" | "token_id_unsupported" | "unknown_alias" | "ambiguous_alias";
|
|
2193
|
-
/**
|
|
2194
|
-
* A string that is not a public asset id.
|
|
2195
|
-
*
|
|
2196
|
-
* Not a member of the §7 `SwapError` taxonomy, and deliberately so: that
|
|
2197
|
-
* taxonomy is the client surface's, thrown by a verb before value moves, and
|
|
2198
|
-
* this is a codec refusing its input before a swap exists at all. Core's own
|
|
2199
|
-
* `AssetId.fromBytes` sets the same precedent.
|
|
2200
|
-
*/
|
|
2201
|
-
declare class AssetIdError extends Error {
|
|
2202
|
-
readonly reason: AssetIdRefusal;
|
|
2203
|
-
readonly value: string;
|
|
2204
|
-
constructor(reason: AssetIdRefusal, value: string, detail: string, options?: ErrorOptions);
|
|
2205
|
-
}
|
|
2206
|
-
/**
|
|
2207
|
-
* The asset namespaces this client spells, and the reference form each takes.
|
|
2208
|
-
*
|
|
2209
|
-
* Closed for the same reason the rail set is: the parser *is* the vocabulary,
|
|
2210
|
-
* and an id nothing downstream can map is a lookup miss dressed as an id. The
|
|
2211
|
-
* per-namespace form is what makes `arkade:bitcoin/asset:notahex` a parse
|
|
2212
|
-
* failure rather than an unserved RFQ pair.
|
|
2213
|
-
*/
|
|
2214
|
-
declare const REFERENCE_RULE: {
|
|
2215
|
-
readonly slip44: RegExp;
|
|
2216
|
-
/** The 68-lowercase-hex identity form; `asset.AssetId` then re-validates it. */
|
|
2217
|
-
readonly asset: RegExp;
|
|
2218
|
-
/**
|
|
2219
|
-
* Reserved for §9. Lowercase, never EIP-55: a checksum belongs on an
|
|
2220
|
-
* address a human types, and an id here comes out of the alias table or a
|
|
2221
|
-
* market card. Mixed case would be two spellings of one asset comparing
|
|
2222
|
-
* unequal in a pair string, a record and a cache key.
|
|
2223
|
-
*/
|
|
2224
|
-
readonly erc20: RegExp;
|
|
2225
|
-
};
|
|
2226
|
-
type AssetNamespace = keyof typeof REFERENCE_RULE;
|
|
2227
|
-
/** Whether `value` is a network core can resolve. Read off core's own table, so
|
|
2228
|
-
* a network added there needs no edit here. */
|
|
2229
|
-
declare const isNetworkRef: (value: string) => value is NetworkRef;
|
|
2230
|
-
/**
|
|
2231
|
-
* Parse an id, or refuse it.
|
|
2232
|
-
*
|
|
2233
|
-
* Total over strings and throwing rather than returning a result, because every
|
|
2234
|
-
* caller in the client either has an id or has nothing to do: an unparsed id
|
|
2235
|
-
* has no route, no market and no leg.
|
|
2236
|
-
*/
|
|
2237
|
-
declare const parseAssetId: (value: string) => ParsedAssetId;
|
|
2238
|
-
/** Whether `value` parses as a public asset id. */
|
|
2239
|
-
declare const isAssetId: (value: string) => value is AssetId;
|
|
2240
|
-
/** Build an id from its parts, validating the result. */
|
|
2241
|
-
declare const formatAssetId: <R extends Rail>(parts: ParsedAssetId & {
|
|
2242
|
-
rail: R;
|
|
2243
|
-
}) => AssetId<R>;
|
|
2244
|
-
/** The rail an id names. */
|
|
2245
|
-
declare const railOf: (id: AssetId) => Rail;
|
|
2246
|
-
/**
|
|
2247
|
-
* The bitcoin network an id settles on, or `undefined` on a rail whose CAIP-2
|
|
2248
|
-
* reference is a chain id rather than a network.
|
|
2249
|
-
*/
|
|
2250
|
-
declare const bitcoinNetworkOf: (id: AssetId) => NetworkRef | undefined;
|
|
2251
|
-
/** The `<asset-ns>:<reference>` half. */
|
|
2252
|
-
declare const assetPartOf: (id: AssetId) => AssetPart;
|
|
2253
|
-
/**
|
|
2254
|
-
* Whether two ids name the same asset on (possibly) different rails.
|
|
2255
|
-
*
|
|
2256
|
-
* This is the whole reason the rail is the namespace: BTC's sameness is the
|
|
2257
|
-
* shared `slip44:0`, a comparison, where a single cross-rail id would have made
|
|
2258
|
-
* it a string both sides had to already agree on.
|
|
2259
|
-
*
|
|
2260
|
-
* The rail is the *only* half sameness drops. The CAIP-2 reference still has to
|
|
2261
|
-
* agree: `arkade:regtest/slip44:0` and `bitcoin:bitcoin/slip44:0` share a coin
|
|
2262
|
-
* type and nothing else — regtest BTC settles nothing on mainnet — and an ERC-20
|
|
2263
|
-
* contract address repeats verbatim across every chain that copied the token, so
|
|
2264
|
-
* the asset part alone would make USDT-on-mainnet the same asset as its address
|
|
2265
|
-
* twin on another chain. Comparing references across rail families is safe on a
|
|
2266
|
-
* plain string: a bitcoin network name is never a decimal chain id.
|
|
2267
|
-
*/
|
|
2268
|
-
declare const sameAsset: (a: AssetId, b: AssetId) => boolean;
|
|
2269
|
-
/** BTC on a bitcoin-family rail: the same coin, named once per rail. */
|
|
2270
|
-
declare const btcOn: <R extends BitcoinRail>(rail: R, network: NetworkRef) => AssetId<R>;
|
|
2271
|
-
/**
|
|
2272
|
-
* An Arkade-issued asset.
|
|
2273
|
-
*
|
|
2274
|
-
* Takes `asset.AssetId` rather than a hex string for the reason `arkadeAssetLeg`
|
|
2275
|
-
* does (`rfq.ts:111`): `hex.decode` accepts uppercase where `hex.encode` emits
|
|
2276
|
-
* only lowercase, so the parameter type is what enforces the case rule, and a
|
|
2277
|
-
* value that reached us as `A1B2…` leaves here as `a1b2…`.
|
|
2278
|
-
*
|
|
2279
|
-
* The reference is that identity verbatim — 68 lowercase hex, `toString()`'s
|
|
2280
|
-
* own output. The spec's prose spells it `<genesis_txid>.<idx>`, which is what
|
|
2281
|
-
* those bytes mean, not a second encoding: the identity is implemented in seven
|
|
2282
|
-
* places across three repos and pinned by `asset.ASSET_ID_VECTORS` precisely
|
|
2283
|
-
* because every disagreement between sites fails silently, so this layer adds
|
|
2284
|
-
* no eighth spelling.
|
|
2285
|
-
*/
|
|
2286
|
-
declare const arkadeAsset: (network: NetworkRef, id: asset.AssetId) => AssetId<"arkade">;
|
|
2287
|
-
/**
|
|
2288
|
-
* The issuance identity nested inside an arkade id; `undefined` for BTC.
|
|
2289
|
-
*
|
|
2290
|
-
* The inverse of {@link arkadeAsset}, and the round trip the shared vectors
|
|
2291
|
-
* pin: the 34 bytes in equal the 34 bytes out.
|
|
2292
|
-
*/
|
|
2293
|
-
declare const issuanceOf: (id: AssetId<"arkade">) => asset.AssetId | undefined;
|
|
2294
|
-
|
|
2295
|
-
/**
|
|
2296
|
-
* The corridor axis, and its bijection with the rail namespaces.
|
|
2297
|
-
*
|
|
2298
|
-
* One axis, two vocabularies: client routes speak `arkade | lightning |
|
|
2299
|
-
* onchain` and an asset id's CAIP-2 namespace is `arkade | bolt11 | bitcoin`.
|
|
2300
|
-
* They agree on one member of three. Collapsing them was the alternative and
|
|
2301
|
-
* it loses either way — take the rail names and the public route vocabulary
|
|
2302
|
-
* becomes protocol-shaped; take the route names and `lightning:` overruns
|
|
2303
|
-
* CAIP-2's eight-character namespace cap.
|
|
2304
|
-
*
|
|
2305
|
-
* So both stay, and the disagreement is spent once, here:
|
|
2306
|
-
* {@link railOfCorridor} is total, and `route.ts` ties an endpoint's corridor
|
|
2307
|
-
* to its asset's rail in the type system so the two cannot disagree in a value.
|
|
2308
|
-
*/
|
|
2309
|
-
|
|
2310
|
-
/**
|
|
2311
|
-
* The corridor a leg settles on.
|
|
2312
|
-
*
|
|
2313
|
-
* This is deliberately independent from discovery's CAIP chain-namespace
|
|
2314
|
-
* vocabulary. Discovery changed its public corridor names to `bolt11` and
|
|
2315
|
-
* `bitcoin`; those are rail identifiers here, not caller-facing route names.
|
|
2316
|
-
*/
|
|
2317
|
-
declare const CORRIDORS: readonly ["arkade", "lightning", "onchain"];
|
|
2318
|
-
type Corridor = (typeof CORRIDORS)[number];
|
|
2319
|
-
/**
|
|
2320
|
-
* A corridor id: the three implemented corridors plus §9's EVM chains.
|
|
2321
|
-
*
|
|
2322
|
-
* The template arm stays open against the registry's closed enum on purpose —
|
|
2323
|
-
* which chains a registry lists is a listing decision, not an id-grammar one.
|
|
2324
|
-
*/
|
|
2325
|
-
type CorridorId = Corridor | `eip155:${number}`;
|
|
2326
|
-
/** The rail namespace a corridor's assets are spelled on. */
|
|
2327
|
-
type RailOf<C extends CorridorId> = C extends "arkade" ? "arkade" : C extends "lightning" ? "bolt11" : C extends "onchain" ? "bitcoin" : "eip155";
|
|
2328
|
-
/** The rail a corridor's assets are spelled on. Total, and the type agrees. */
|
|
2329
|
-
declare const railOfCorridor: <C extends CorridorId>(corridor: C) => RailOf<C>;
|
|
2330
|
-
/**
|
|
2331
|
-
* The corridor a rail belongs to, or `undefined` for `eip155` — whose corridor
|
|
2332
|
-
* id carries a chain reference this side has no way to invent.
|
|
2333
|
-
*/
|
|
2334
|
-
declare const corridorOfRail: (rail: Rail) => Corridor | undefined;
|
|
2335
|
-
|
|
2336
|
-
/**
|
|
2337
|
-
* The two string aliases the v2 surface is written in.
|
|
2338
|
-
*
|
|
2339
|
-
* Aliases rather than branded types: they document what a field carries at the
|
|
2340
|
-
* places §3.1's `Quote` reads (`lock.hash`, `solver`) without making every
|
|
2341
|
-
* literal go through a constructor. Core exports neither, so nothing here is a
|
|
2342
|
-
* duplicate.
|
|
2343
|
-
*/
|
|
2344
|
-
/** Lowercase hex, no `0x` prefix — the encoding `@scure/base`'s `hex` emits. */
|
|
2345
|
-
type Hex = string;
|
|
2346
|
-
/** A secp256k1 public key as {@link Hex}: x-only (32 bytes) or compressed (33). */
|
|
2347
|
-
type Pubkey = Hex;
|
|
2348
|
-
|
|
2349
|
-
/**
|
|
2350
|
-
* One outcome vocabulary, and the translation that produces it.
|
|
2351
|
-
*
|
|
2352
|
-
* The protocol keeps two state machines — `RfqSwapState` for the corridors and
|
|
2353
|
-
* `AssetSwapStatus` for offers — and v1 handed both to every consumer, who then
|
|
2354
|
-
* wrote `family === "offer" ? swap.status : swap.state` and decided what each
|
|
2355
|
-
* word meant. {@link Outcome} is that decision, made once.
|
|
2356
|
-
*
|
|
2357
|
-
* **The axis is not send-versus-receive: it is whose lockup the pass reads.**
|
|
2358
|
-
* On `arkade -> lightning` and `arkade -> onchain` the arkade lockup is the
|
|
2359
|
-
* trader's, so a non-claim spend of it returns the trader's money. On
|
|
2360
|
-
* `lightning -> arkade` it is the solver's, so the identical chain read means
|
|
2361
|
-
* the trader's incoming payment never arrived. `refunded` and `lapsed` are that
|
|
2362
|
-
* one difference, and the reason this enum refuses to inherit the protocol's
|
|
2363
|
-
* word: on the receive leg the state the wire calls `refunded` is a LOSS.
|
|
2364
|
-
*
|
|
2365
|
-
* The ownership is not restated here. {@link LIGHTNING_DRIVE} and
|
|
2366
|
-
* {@link ONCHAIN_DRIVE} already declare it per route side — that is what M2
|
|
2367
|
-
* minted `CorridorPass` for — so this module reads it off them and a corridor
|
|
2368
|
-
* that changes its mind is a compile error rather than a second table to keep
|
|
2369
|
-
* in step.
|
|
2370
|
-
*
|
|
2371
|
-
* Three outcomes come from neither machine, and they are the record's and the
|
|
2372
|
-
* clock's: `accepted` and `funding` describe a record the drive holds no live
|
|
2373
|
-
* state for, and `refunding` a send leg past its deadline with a push in
|
|
2374
|
-
* flight. All three still carry the raw word their machine holds, because
|
|
2375
|
-
* {@link SwapUpdate.detail} is `RawState` and `RawState` is the raw word.
|
|
2376
|
-
*/
|
|
2377
|
-
|
|
2378
|
-
/**
|
|
2379
|
-
* What happened to a swap, in one vocabulary for both families.
|
|
2380
|
-
*
|
|
2381
|
-
* Trader-centric by definition. Fourteen members, §3.5's, and the two that
|
|
2382
|
-
* carry the whole point are `refunded` — the trader's value came back — and
|
|
2383
|
-
* `lapsed`, the solver reclaiming a lockup the trader failed to claim.
|
|
2384
|
-
*/
|
|
2385
|
-
type Outcome =
|
|
2386
|
-
/** Persisted, and its funding has not been broadcast. */
|
|
2387
|
-
"accepted"
|
|
2388
|
-
/** The funding is broadcast and the drive has not adopted the swap yet. */
|
|
2389
|
-
| "funding"
|
|
2390
|
-
/** The trader's lockup is funded and the swap is live. */
|
|
2391
|
-
| "funded"
|
|
2392
|
-
/** Waiting on the counterparty: an unpaid invoice, an unfilled offer. */
|
|
2393
|
-
| "open"
|
|
2394
|
-
/** An offer covenant was filled. */
|
|
2395
|
-
| "filled"
|
|
2396
|
-
/** The trader's own claim is confirmed on chain. */
|
|
2397
|
-
| "claimed"
|
|
2398
|
-
/** A lightning send settled: the solver's hash-verified spend IS the
|
|
2399
|
-
* invoice being paid. */
|
|
2400
|
-
| "paid" | "cancelling" | "cancelled"
|
|
2401
|
-
/** A send leg past `refundLocktime` with a refund push in flight. */
|
|
2402
|
-
| "refunding"
|
|
2403
|
-
/** The trader's value came back. Send legs only, ever. */
|
|
2404
|
-
| "refunded"
|
|
2405
|
-
/** A receive leg the trader never claimed: the solver took the lockup back
|
|
2406
|
-
* and the incoming payment never arrived. */
|
|
2407
|
-
| "lapsed"
|
|
2408
|
-
/** Surfaced, never silently retried, and never terminal. */
|
|
2409
|
-
| "needs_recovery"
|
|
2410
|
-
/** An action failed and its window closed. */
|
|
2411
|
-
| "failed";
|
|
2412
|
-
/**
|
|
2413
|
-
* The untranslated protocol word, for support and audit.
|
|
2414
|
-
*
|
|
2415
|
-
* A tagged union over the two families rather than a bare string, so M6's
|
|
2416
|
-
* cancel path reads the family split off the update one lookup earlier than a
|
|
2417
|
-
* repository read. The reason strings are deliberately NOT here: `failure` and
|
|
2418
|
-
* `blockedReason` arrive on the record as fields, not as vocabulary, and
|
|
2419
|
-
* {@link Swap} is where a consumer reads them.
|
|
2420
|
-
*
|
|
2421
|
-
* `wire`, `htlc` and `fate` are the supporting vocabularies a pass consults.
|
|
2422
|
-
* They are declared because the shape is fixed here rather than left to the
|
|
2423
|
-
* first consumer that wants one, and populated by nothing today: the manager
|
|
2424
|
-
* surfaces neither the L1 phase nor the lockup fate on its update callback, and
|
|
2425
|
-
* the solver's own `RfqStatus` is a self-report no drive pass reads at all.
|
|
2426
|
-
*/
|
|
2427
|
-
type RawState = {
|
|
2428
|
-
readonly family: "rfq";
|
|
2429
|
-
readonly state: RfqSwapState;
|
|
2430
|
-
readonly wire?: RfqStatus["state"];
|
|
2431
|
-
readonly htlc?: OnchainHtlcPhase;
|
|
2432
|
-
readonly fate?: LockupFate;
|
|
2433
|
-
} | {
|
|
2434
|
-
readonly family: "offer";
|
|
2435
|
-
readonly status: AssetSwapStatus;
|
|
2436
|
-
};
|
|
2437
|
-
/** What `onUpdate` delivers. */
|
|
2438
|
-
interface SwapUpdate {
|
|
2439
|
-
readonly swap: Swap;
|
|
2440
|
-
readonly outcome: Outcome;
|
|
2441
|
-
readonly detail: RawState;
|
|
2442
|
-
}
|
|
2443
|
-
/** What every listener registration hands back. */
|
|
2444
|
-
type Unsubscribe = () => void;
|
|
2445
|
-
/** The manager's route-pair vocabulary — a route pair, not a corridor. */
|
|
2446
|
-
type CorridorKind = PersistableRfqSwap["kind"];
|
|
2447
|
-
/**
|
|
2448
|
-
* Which route side each corridor kind is, and so which {@link CorridorPass}
|
|
2449
|
-
* describes its drive.
|
|
2450
|
-
*
|
|
2451
|
-
* `lightning_send` is `arkade -> lightning`: the trader TAKES on lightning.
|
|
2452
|
-
* `lightning_receive` is `lightning -> arkade`: the trader GIVES on it.
|
|
2453
|
-
*/
|
|
2454
|
-
declare const CORRIDOR_PASS: {
|
|
2455
|
-
readonly lightning_send: {
|
|
2456
|
-
readonly lockups: readonly [{
|
|
2457
|
-
readonly covenant: "arkade_lockup";
|
|
2458
|
-
readonly owner: "trader";
|
|
2459
|
-
readonly deadline: "refund_locktime";
|
|
2460
|
-
}];
|
|
2461
|
-
readonly actions: readonly ["refundArkade"];
|
|
2462
|
-
readonly seams: readonly ["indexer"];
|
|
2463
|
-
};
|
|
2464
|
-
readonly lightning_receive: {
|
|
2465
|
-
readonly lockups: readonly [{
|
|
2466
|
-
readonly covenant: "arkade_lockup";
|
|
2467
|
-
readonly owner: "solver";
|
|
2468
|
-
readonly deadline: "refund_locktime";
|
|
2469
|
-
}];
|
|
2470
|
-
readonly actions: readonly ["claimLockup"];
|
|
2471
|
-
readonly seams: readonly ["indexer"];
|
|
2472
|
-
};
|
|
2473
|
-
readonly onchain_send: {
|
|
2474
|
-
readonly lockups: readonly [{
|
|
2475
|
-
readonly covenant: "arkade_lockup";
|
|
2476
|
-
readonly owner: "trader";
|
|
2477
|
-
readonly deadline: "refund_locktime";
|
|
2478
|
-
}, {
|
|
2479
|
-
readonly covenant: "onchain_htlc";
|
|
2480
|
-
readonly owner: "solver";
|
|
2481
|
-
readonly deadline: "htlc_refund_locktime";
|
|
2482
|
-
}];
|
|
2483
|
-
readonly actions: readonly ["claimOnchain", "refundArkade"];
|
|
2484
|
-
readonly seams: readonly ["indexer", "chain"];
|
|
2485
|
-
};
|
|
2486
|
-
};
|
|
2487
|
-
/**
|
|
2488
|
-
* Whose the arkade lockup is, per corridor kind — read off the corridor
|
|
2489
|
-
* modules' own declarations rather than restated.
|
|
2490
|
-
*
|
|
2491
|
-
* The arkade lockup is `lockups[0]` on all three, which is the order
|
|
2492
|
-
* `CorridorPass.lockups` documents: "every covenant the pass reads, in the
|
|
2493
|
-
* order it reads them", and step 1 of every pass is the arkade lockup.
|
|
2494
|
-
*/
|
|
2495
|
-
declare const LOCKUP_OWNER: {
|
|
2496
|
-
readonly lightning_send: "trader";
|
|
2497
|
-
readonly lightning_receive: "solver";
|
|
2498
|
-
readonly onchain_send: "trader";
|
|
2499
|
-
};
|
|
2500
|
-
/** Whether this kind's drive pass reads L1 — the seam that decides whether the
|
|
2501
|
-
* onchain corridor's deps have to be resolved at all. */
|
|
2502
|
-
declare const readsChain: (kind: CorridorKind) => boolean;
|
|
2503
|
-
/** The corridor family's translation. */
|
|
2504
|
-
declare const corridorOutcome: (kind: CorridorKind, state: RfqSwapState) => Outcome;
|
|
2505
|
-
declare const offerOutcome: (status: AssetSwapStatus) => Outcome;
|
|
2506
|
-
/**
|
|
2507
|
-
* What a record reports when nothing live stands behind it.
|
|
2508
|
-
*
|
|
2509
|
-
* Two of the three record-and-clock projections, and the reason they are a
|
|
2510
|
-
* projection at all: nothing is written when a swap is handed to the manager,
|
|
2511
|
-
* so the first write is the first pass, and until then the record and the
|
|
2512
|
-
* funding txid are the whole answer. A corridor record therefore reads
|
|
2513
|
-
* `accepted` until its funding is broadcast and `funding` until the drive
|
|
2514
|
-
* adopts it — including the receive leg, whose `accepted -> open` arrow is
|
|
2515
|
-
* exactly the durable invoice becoming a watched one.
|
|
2516
|
-
*
|
|
2517
|
-
* The offer family has no live object of its own — its watcher is event-driven
|
|
2518
|
-
* over the store — so past the funding the record IS the state.
|
|
2519
|
-
*/
|
|
2520
|
-
declare const recordOutcome: (record: {
|
|
2521
|
-
family: "offer" | "rfq";
|
|
2522
|
-
fundingTxid?: string;
|
|
2523
|
-
status?: AssetSwapStatus;
|
|
2524
|
-
}) => Outcome;
|
|
2525
|
-
/**
|
|
2526
|
-
* `Outcome`, as `activity.ts`'s opaque grouping token.
|
|
2527
|
-
*
|
|
2528
|
-
* The resolver's vocabulary is deliberately coarser than this one — it labels a
|
|
2529
|
-
* history row, not a swap's state — so this is a projection and not a rename.
|
|
2530
|
-
* `lost` is what `lapsed` projects to, which is the token that file already
|
|
2531
|
-
* emitted by hand for a receive leg's `refunded`.
|
|
2532
|
-
*/
|
|
2533
|
-
declare const ACTIVITY_TOKEN: Record<Outcome, string>;
|
|
2534
|
-
|
|
2535
|
-
/**
|
|
2536
|
-
* A route is two endpoints, each an asset on a corridor, plus the instrument
|
|
2537
|
-
* that settles it.
|
|
2538
|
-
*
|
|
2539
|
-
* Two invariants live in the types rather than in a check. An endpoint's
|
|
2540
|
-
* corridor and its asset cannot disagree, because {@link Endpoint} is a union
|
|
2541
|
-
* with one member per corridor and each member types its asset as
|
|
2542
|
-
* {@link AssetOn} of that one corridor. And `onchain -> arkade` is not in
|
|
2543
|
-
* {@link Route} at all, so once a route has been resolved the misroute is a
|
|
2544
|
-
* compile error; before resolution it is `UnsupportedRoute`, thrown ahead of
|
|
2545
|
-
* RFQ disclosure, artifact creation, persistence and funding.
|
|
2546
|
-
*/
|
|
2547
|
-
|
|
2548
|
-
/**
|
|
2549
|
-
* A leg's concrete settlement locus. Direction comes from give versus take,
|
|
2550
|
-
* never from the instrument.
|
|
2551
|
-
*
|
|
2552
|
-
* `{ kind: "wallet" }` is the only instrument the SDK holds signing authority
|
|
2553
|
-
* over, which is why it is the only one nobody passes: `accept()` spends the
|
|
2554
|
-
* balance and lands the claim on wallet legs and merely watches the others. The
|
|
2555
|
-
* supply law is that the caller provides non-wallet take instruments (that is
|
|
2556
|
-
* what `to` is), the quote provides non-wallet give instruments (that is
|
|
2557
|
-
* exactly what the artifact is), and every remaining slot resolves to `wallet`.
|
|
2558
|
-
*
|
|
2559
|
-
* `wallet` is an explicit variant rather than an absent field because absence
|
|
2560
|
-
* would mean two unrelated things — wallet-by-default and not-yet-resolved —
|
|
2561
|
-
* and a receive leg lives in the second state until the quote returns.
|
|
2562
|
-
*/
|
|
2563
|
-
type Instrument = {
|
|
2564
|
-
kind: "wallet";
|
|
2565
|
-
} | {
|
|
2566
|
-
kind: "address";
|
|
2567
|
-
address: string;
|
|
2568
|
-
/**
|
|
2569
|
-
* The amount a BIP21 URI pinned beside the address, when one did.
|
|
2570
|
-
*
|
|
2571
|
-
* An address on its own pins no amount, but `bitcoin:…?amount=` does —
|
|
2572
|
-
* and that number is the destination's own statement of what the
|
|
2573
|
-
* recipient expects, the same way an amount-bearing bolt11 is. It is
|
|
2574
|
-
* carried here rather than folded into the route resolution so a
|
|
2575
|
-
* caller passing `amount` beside it trips `AmountMismatch` on the
|
|
2576
|
-
* destination's pin, exactly as it would on an invoice's.
|
|
2577
|
-
*/
|
|
2578
|
-
amount?: bigint;
|
|
2579
|
-
} | {
|
|
2580
|
-
kind: "invoice";
|
|
2581
|
-
bolt11: string;
|
|
2582
|
-
paymentHash: Hex;
|
|
2583
|
-
amount?: bigint;
|
|
2584
|
-
expiresAt: number;
|
|
2585
|
-
};
|
|
2586
|
-
/**
|
|
2587
|
-
* The asset ids corridor `C` can carry.
|
|
2588
|
-
*
|
|
2589
|
-
* On the three bitcoin-family corridors the corridor names no network, so the
|
|
2590
|
-
* tie is the rail alone. On an EVM corridor it is more than that: `eip155:8453`
|
|
2591
|
-
* *is* the CAIP-2 chain part its assets are spelled with, so the asset id has to
|
|
2592
|
-
* start with the corridor id verbatim. Enforcing only the rail there would admit
|
|
2593
|
-
* `eip155:1/erc20:…` on a Base corridor — the same near-miss `sameAsset` refuses
|
|
2594
|
-
* one layer up, an address being a chain's fact and not a token's.
|
|
2595
|
-
*/
|
|
2596
|
-
type AssetOn<C extends CorridorId> = C extends Corridor ? AssetId<RailOf<C>> : `${C}/${AssetPart}`;
|
|
2597
|
-
/**
|
|
2598
|
-
* An asset on a corridor, with the instrument that settles it.
|
|
2599
|
-
*
|
|
2600
|
-
* `corridor` is a cross-check rather than an input: every id already carries
|
|
2601
|
-
* its rail. Typing `asset` against that rail is what makes the cross-check free
|
|
2602
|
-
* — there is no value in which the two disagree.
|
|
2603
|
-
*
|
|
2604
|
-
* Distributed over `C` rather than written as one object whose two fields both
|
|
2605
|
-
* mention it: `{ corridor: C; asset: AssetOn<C> }` at `C = CorridorId` widens
|
|
2606
|
-
* *each field independently* to its own union, and correlates nothing —
|
|
2607
|
-
* `{ corridor: "arkade", asset: "bitcoin:…" }` satisfies it. The conditional
|
|
2608
|
-
* makes `Endpoint` the union of the four single-corridor shapes instead, so the
|
|
2609
|
-
* pairing survives the default type argument, which is the case every unwitnessed
|
|
2610
|
-
* `Endpoint` in a signature lands on.
|
|
2611
|
-
*/
|
|
2612
|
-
type Endpoint<C extends CorridorId = CorridorId> = C extends CorridorId ? {
|
|
2613
|
-
corridor: C;
|
|
2614
|
-
asset: AssetOn<C>;
|
|
2615
|
-
/** Resolved by the client, never constructed by callers. */
|
|
2616
|
-
instrument: Instrument;
|
|
2617
|
-
} : never;
|
|
2618
|
-
/** Shorthand for one corridor's endpoint, as the route union spells it. */
|
|
2619
|
-
type Ep<C extends CorridorId> = Endpoint<C>;
|
|
2620
|
-
/**
|
|
2621
|
-
* The implemented routes, as a closed union.
|
|
2622
|
-
*
|
|
2623
|
-
* `onchain -> arkade` is deliberately absent until the manager owns the
|
|
2624
|
-
* trader's L1 refund path end to end.
|
|
2625
|
-
*/
|
|
2626
|
-
type Route = {
|
|
2627
|
-
give: Ep<"arkade">;
|
|
2628
|
-
take: Ep<"arkade">;
|
|
2629
|
-
} | {
|
|
2630
|
-
give: Ep<"arkade">;
|
|
2631
|
-
take: Ep<"lightning">;
|
|
2632
|
-
} | {
|
|
2633
|
-
give: Ep<"lightning">;
|
|
2634
|
-
take: Ep<"arkade">;
|
|
2635
|
-
} | {
|
|
2636
|
-
give: Ep<"arkade">;
|
|
2637
|
-
take: Ep<"onchain">;
|
|
2638
|
-
};
|
|
2639
|
-
/**
|
|
2640
|
-
* The one thing a counterparty must see, when a route has one.
|
|
2641
|
-
*
|
|
2642
|
-
* The deposit variant carries no `chain` field. §3.4 reserved one and Q12 made
|
|
2643
|
-
* it redundant: the chain part lives inside `asset`, and a second, untyped
|
|
2644
|
-
* spelling of it is a fact two fields can disagree about with nothing checking.
|
|
2645
|
-
* `corridor` stays because it is the typed axis `route.ts` already ties to the
|
|
2646
|
-
* asset's rail — a cross-check, where `chain?: string | number` was a copy.
|
|
2647
|
-
*/
|
|
2648
|
-
type Artifact = {
|
|
2649
|
-
kind: "invoice";
|
|
2650
|
-
bolt11: string;
|
|
2651
|
-
} | DepositArtifact;
|
|
2652
|
-
/**
|
|
2653
|
-
* The deposit half of {@link Artifact}, distributed over the corridor for the
|
|
2654
|
-
* reason {@link Endpoint} is: `corridor` is only a cross-check if a value cannot
|
|
2655
|
-
* spell it against an asset from another corridor.
|
|
2656
|
-
*/
|
|
2657
|
-
type DepositArtifact<C extends CorridorId = CorridorId> = C extends CorridorId ? {
|
|
2658
|
-
kind: "deposit";
|
|
2659
|
-
corridor: C;
|
|
2660
|
-
address: string;
|
|
2661
|
-
asset: AssetOn<C>;
|
|
2662
|
-
amount: bigint;
|
|
2663
|
-
expiresAt?: number;
|
|
2664
|
-
} : never;
|
|
2665
|
-
|
|
2666
|
-
/** Which side of the trade an amount pins, in v2's vocabulary. */
|
|
2667
|
-
type AmountOn = "give" | "take";
|
|
2668
|
-
/** The same axis on the wire, where the key is `amount_side`. */
|
|
2669
|
-
type RfqAmountSide = "from" | "to";
|
|
2670
|
-
/** v2 to the wire. One translation point, so the rename cannot spread. */
|
|
2671
|
-
declare const toRfqAmountSide: (on: AmountOn) => RfqAmountSide;
|
|
2672
|
-
/** The wire back to v2. */
|
|
2673
|
-
declare const fromRfqAmountSide: (side: RfqAmountSide) => AmountOn;
|
|
2674
|
-
/**
|
|
2675
|
-
* An amount out to the wire, as the canonical decimal string.
|
|
2676
|
-
*
|
|
2677
|
-
* `field` has no default: every throw on a quote would otherwise say `"amount"`,
|
|
2678
|
-
* and telling `from_amount` from `to_amount` is the only thing it is for.
|
|
2679
|
-
*/
|
|
2680
|
-
declare const encodeRfqAmount: (value: bigint, field: string) => AtomicDecimal;
|
|
2681
|
-
/**
|
|
2682
|
-
* An amount in from the wire.
|
|
2683
|
-
*
|
|
2684
|
-
* Accepts the canonical string, or a JSON number inside the safe-integer window
|
|
2685
|
-
* — the migration's compatibility arm, and the only place a number is tolerated
|
|
2686
|
-
* anywhere in v2. A non-canonical string is this error too, not a verification
|
|
2687
|
-
* failure: verification is the four semantic checks over a well-formed quote,
|
|
2688
|
-
* and this fires before them.
|
|
2689
|
-
*/
|
|
2690
|
-
declare const decodeRfqAmount: (raw: unknown, field: string) => bigint;
|
|
2691
|
-
/**
|
|
2692
|
-
* A `bigint` amount into a foreign `number` one, checked.
|
|
2693
|
-
*
|
|
2694
|
-
* Core's payment router types its amounts as `number` sats and M7's swap-backed
|
|
2695
|
-
* rail narrows at that boundary rather than changing a published core type. The
|
|
2696
|
-
* narrowing is sound because both sides are sats and a sat count past 2^53 is
|
|
2697
|
-
* not a payment — but it has to be checked, which is why it lives here beside
|
|
2698
|
-
* the error rather than as a bare `Number()` at the call site.
|
|
2699
|
-
*/
|
|
2700
|
-
declare const toSafeNumber: (value: bigint, field: string) => number;
|
|
2701
|
-
|
|
2702
|
-
/**
|
|
2703
|
-
* What a quote is: the order, fully resolved, plus the provenance that says who
|
|
2704
|
-
* priced it and where that card came from.
|
|
2705
|
-
*
|
|
2706
|
-
* M1 named these shapes and left them to whichever milestone decided their
|
|
2707
|
-
* semantics; this is that milestone, so `QuoteId`, `QuoteInput`, `Quote`,
|
|
2708
|
-
* `MarketRef` and `AuctionProvenance` are declared here rather than beside the
|
|
2709
|
-
* types they are built out of. Nothing in this module has behaviour — the quote
|
|
2710
|
-
* path assembles these, `accept()` (M4) consumes them.
|
|
2711
|
-
*
|
|
2712
|
-
* The one rule worth restating at the top: a `Quote` is binding terms plus the
|
|
2713
|
-
* evidence for them. Every field is either something the caller must act on
|
|
2714
|
-
* (the two obligations, the artifact, the deadline) or something they must be
|
|
2715
|
-
* able to audit afterwards (the market, the solver, the checks that passed).
|
|
2716
|
-
* Nothing internal rides along — no covenant, no secret, no transport.
|
|
2717
|
-
*/
|
|
2718
|
-
|
|
2719
|
-
/**
|
|
2720
|
-
* A quote's identity, minted by the client at quote time.
|
|
2721
|
-
*
|
|
2722
|
-
* Client-minted everywhere, not just where the wire offers no id: a feed-priced
|
|
2723
|
-
* offer quote has no solver-minted id at all, and `accept()` is idempotent by
|
|
2724
|
-
* quote id *and only* by quote id (§3.2), so an identity that exists on one
|
|
2725
|
-
* backend and not the other could not carry that rule. An alias rather than a
|
|
2726
|
-
* brand, matching `Hex` and `Pubkey` beside it.
|
|
2727
|
-
*/
|
|
2728
|
-
type QuoteId = string;
|
|
2729
|
-
/**
|
|
2730
|
-
* A caller's spelling of an asset: a public id, or a ticker the alias layer
|
|
2731
|
-
* canonicalizes against the registry.
|
|
2732
|
-
*
|
|
2733
|
-
* `AssetId | (string & {})` rather than `string`, so an editor still completes
|
|
2734
|
-
* the id form and a mistyped id still shows up as one — `AssetId | string`
|
|
2735
|
-
* collapses to `string` and takes both with it.
|
|
2736
|
-
*/
|
|
2737
|
-
type AssetRef = AssetId | (string & {});
|
|
2738
|
-
/**
|
|
2739
|
-
* Everything a caller supplies. §4's bottom line: two asset ids or one
|
|
2740
|
-
* destination string, one amount, which side it pins, and — on receives, where
|
|
2741
|
-
* no instrument exists yet — a corridor.
|
|
2742
|
-
*/
|
|
2743
|
-
interface QuoteInput {
|
|
2744
|
-
/** Omitted when the route determines it: the give leg is the wallet's. */
|
|
2745
|
-
give?: AssetRef;
|
|
2746
|
-
/** Omitted when `to` determines it — a corridor that carries BTC only does. */
|
|
2747
|
-
take?: AssetRef;
|
|
2748
|
-
/** A self-describing instrument: bolt11, an Arkade address, or `bc1…`. */
|
|
2749
|
-
to?: string;
|
|
2750
|
-
/** Receive flows only: names the corridor when no instrument can exist yet. */
|
|
2751
|
-
via?: CorridorId;
|
|
2752
|
-
/** Atomic units. Exactly one amount may be pinned — see `amountOn`. */
|
|
2753
|
-
amount?: bigint;
|
|
2754
|
-
/** Which leg `amount` pins. Required with `amount`, and refused with an
|
|
2755
|
-
* invoice, which pins one already. */
|
|
2756
|
-
amountOn?: AmountOn;
|
|
2757
|
-
}
|
|
2758
|
-
/** Which backend priced a quote. The card decides it; no client switch does. */
|
|
2759
|
-
type MarketBackend = "rfq" | "feed";
|
|
2760
|
-
/** Where a snapshot came from, and how fresh it is. */
|
|
2761
|
-
interface SnapshotRef {
|
|
2762
|
-
/** Unix ms the markets were read from their sources. */
|
|
2763
|
-
readonly fetchedAt: number;
|
|
2764
|
-
/**
|
|
2765
|
-
* The registry answered in this read, so the cards are registry-served
|
|
2766
|
-
* rather than replayed out of local storage.
|
|
2767
|
-
*
|
|
2768
|
-
* `false` is not an error: a stale snapshot still resolves and still prices
|
|
2769
|
-
* a feed-priced quote — it is marked, not refused. What it cannot do is
|
|
2770
|
-
* supply the key an addressed RFQ's responder is checked against, because
|
|
2771
|
-
* that field is unvalidated cache content (`isMarketShaped` revalidates
|
|
2772
|
-
* four fields and trusts the rest).
|
|
2773
|
-
*/
|
|
2774
|
-
readonly live: boolean;
|
|
2775
|
-
/** How the markets were obtained. */
|
|
2776
|
-
readonly source: "live" | "cache" | "injected";
|
|
2777
|
-
/** The registry URL behind it, or `undefined` for an injected snapshot. */
|
|
2778
|
-
readonly registry?: string;
|
|
2779
|
-
}
|
|
2780
|
-
/**
|
|
2781
|
-
* Which card priced a quote, and from which registry.
|
|
2782
|
-
*
|
|
2783
|
-
* A union rather than a bag of optionals, because §10's published RFQ is the
|
|
2784
|
-
* one place the sentence "the market picks the backend" stops: a quote closed
|
|
2785
|
-
* out of an open auction has a market *key* and no card behind it, so every
|
|
2786
|
-
* card-derived field is absent at once rather than one at a time. Sizing that
|
|
2787
|
-
* arm now costs a discriminant and keeps the addressed arm total.
|
|
2788
|
-
*/
|
|
2789
|
-
type MarketRef = CardMarketRef | AuctionMarketRef;
|
|
2790
|
-
interface CardMarketRef {
|
|
2791
|
-
readonly kind: "card";
|
|
2792
|
-
/**
|
|
2793
|
-
* The canonical market key, `<corridor>:<id>/<corridor>:<id>`, derived under
|
|
2794
|
-
* rfq-protocol.md §2's leg order — arkade first when exactly one leg is
|
|
2795
|
-
* arkade, lexicographic otherwise — and never read off the card's own
|
|
2796
|
-
* base/quote order. The two agree for every card the registry's reducer
|
|
2797
|
-
* validated, and a card published outside it is exactly where the silent
|
|
2798
|
-
* miss lives.
|
|
2799
|
-
*/
|
|
2800
|
-
readonly key: string;
|
|
2801
|
-
readonly backend: MarketBackend;
|
|
2802
|
-
/** The registry URL, or the label a locally pinned card was loaded under. */
|
|
2803
|
-
readonly source: string;
|
|
2804
|
-
readonly sourceType: "registry" | "local";
|
|
2805
|
-
/** The solver's name, as the card publishes it. Display, never identity. */
|
|
2806
|
-
readonly solver: string;
|
|
2807
|
-
/** The card's signing key. Absent on spot cards, which need no rendezvous. */
|
|
2808
|
-
readonly discoveryPubkey?: Pubkey;
|
|
2809
|
-
/** The card's display label, e.g. `BTC/lightning:BTC`. Display only. */
|
|
2810
|
-
readonly pair: string;
|
|
2811
|
-
readonly snapshot: SnapshotRef;
|
|
2812
|
-
}
|
|
2813
|
-
/** §10, reserved: a quote closed out of a published auction has no card. */
|
|
2814
|
-
interface AuctionMarketRef {
|
|
2815
|
-
readonly kind: "auction";
|
|
2816
|
-
readonly key: string;
|
|
2817
|
-
readonly backend: "rfq";
|
|
2818
|
-
}
|
|
2819
|
-
/**
|
|
2820
|
-
* One bid seen in a published auction (§10, Q9).
|
|
2821
|
-
*
|
|
2822
|
-
* Typed against ts-sdk #777's shipped draft rather than invented: a bid is a
|
|
2823
|
-
* counter-amount on the leg the client did not fix, attributed to the event key
|
|
2824
|
-
* that signed it — which is NOT the covenant's `solver_pubkey`, a role key the
|
|
2825
|
-
* quote fills from a different field.
|
|
2826
|
-
*/
|
|
2827
|
-
interface RankedBid {
|
|
2828
|
-
/** The event key that signed the bid. Attribution, not a covenant role. */
|
|
2829
|
-
readonly bidder: Pubkey;
|
|
2830
|
-
/** The counter-amount, on the leg the client left free. */
|
|
2831
|
-
readonly amount: bigint;
|
|
2832
|
-
readonly amountOn: AmountOn;
|
|
2833
|
-
readonly expiresAt: number;
|
|
2834
|
-
}
|
|
2835
|
-
/**
|
|
2836
|
-
* The auction a published-RFQ quote was closed out of (§10, Q9).
|
|
2837
|
-
*
|
|
2838
|
-
* Reserved and inert: `quote()` never populates it, and Q9 froze the name so
|
|
2839
|
-
* the shape it will take cannot be occupied by something else in the meantime.
|
|
2840
|
-
*/
|
|
2841
|
-
interface AuctionProvenance {
|
|
2842
|
-
/** The market key the open request was tagged with. */
|
|
2843
|
-
readonly marketKey: string;
|
|
2844
|
-
/** The bid that was closed with. */
|
|
2845
|
-
readonly winner: RankedBid;
|
|
2846
|
-
/** Every other bid seen before the window closed. */
|
|
2847
|
-
readonly losers: readonly RankedBid[];
|
|
2848
|
-
/** Unix seconds the bid window closed. */
|
|
2849
|
-
readonly closedAt: number;
|
|
2850
|
-
}
|
|
2851
|
-
/** One leg's obligation: an asset, and exactly how much of it. */
|
|
2852
|
-
interface QuoteLeg {
|
|
2853
|
-
readonly asset: AssetId;
|
|
2854
|
-
readonly amount: bigint;
|
|
2855
|
-
}
|
|
2856
|
-
/**
|
|
2857
|
-
* The order, fully resolved.
|
|
2858
|
-
*
|
|
2859
|
-
* Both amounts are exact obligations with the fee already inside them, which is
|
|
2860
|
-
* what `fee` restates rather than adds: it is the spread, precomputed, so a
|
|
2861
|
-
* verb (M7) can compare it to a ceiling without re-deriving it from a price.
|
|
2862
|
-
*/
|
|
2863
|
-
interface Quote {
|
|
2864
|
-
readonly id: QuoteId;
|
|
2865
|
-
/** Both endpoints resolved, instruments included. */
|
|
2866
|
-
readonly route: Route;
|
|
2867
|
-
/** What the trader gives, fee included. */
|
|
2868
|
-
readonly give: QuoteLeg;
|
|
2869
|
-
/** What the trader takes. */
|
|
2870
|
-
readonly take: QuoteLeg;
|
|
2871
|
-
/** Corridor routes: the hash both covenants commit to. */
|
|
2872
|
-
readonly lock?: {
|
|
2873
|
-
readonly hash: Hex;
|
|
2874
|
-
};
|
|
2875
|
-
/** Which card priced this, from which registry, how fresh. */
|
|
2876
|
-
readonly market: MarketRef;
|
|
2877
|
-
/** RFQ routes: the committed counterparty, from the quote's covenant role. */
|
|
2878
|
-
readonly solver?: Pubkey;
|
|
2879
|
-
/** §10 only, and never populated today. */
|
|
2880
|
-
readonly auction?: AuctionProvenance;
|
|
2881
|
-
/** Unix seconds. Non-optional on both backends — a feed-priced quote has no
|
|
2882
|
-
* wire expiry to inherit, so the client mints one from the feed's freshness. */
|
|
2883
|
-
readonly expiresAt: number;
|
|
2884
|
-
/**
|
|
2885
|
-
* Corridor routes: when the trader's value comes back if the swap does not
|
|
2886
|
-
* complete.
|
|
2887
|
-
*
|
|
2888
|
-
* Optional on the type because an asset swap has no refund clock at all —
|
|
2889
|
-
* an offer covenant never expires — and non-optional in practice on every
|
|
2890
|
-
* corridor route, where the wire's own field is optional and the client
|
|
2891
|
-
* refuses a quote without it.
|
|
2892
|
-
*/
|
|
2893
|
-
readonly refundLocktime?: number;
|
|
2894
|
-
/** The one thing a counterparty must see, when this route has one. */
|
|
2895
|
-
readonly artifact?: Artifact;
|
|
2896
|
-
/** The spread, denominated on the leg where it is exact. */
|
|
2897
|
-
readonly fee: {
|
|
2898
|
-
readonly amount: bigint;
|
|
2899
|
-
readonly asset: AssetId;
|
|
2900
|
-
};
|
|
2901
|
-
}
|
|
2902
|
-
/**
|
|
2903
|
-
* An endpoint as `resolve()` can answer for it, before any disclosure.
|
|
2904
|
-
*
|
|
2905
|
-
* Not an `Endpoint`: that type's instrument is non-optional, deliberately, and a
|
|
2906
|
-
* receive leg has none until the quote returns — the instrument IS the artifact
|
|
2907
|
-
* the solver mints. Absence here means exactly that one thing, because the
|
|
2908
|
-
* wallet case is spelled `{ kind: "wallet" }` rather than left out.
|
|
2909
|
-
*/
|
|
2910
|
-
interface ResolvedEndpoint {
|
|
2911
|
-
readonly corridor: Corridor;
|
|
2912
|
-
readonly asset: AssetId;
|
|
2913
|
-
/** Absent only while the leg's instrument does not exist yet. */
|
|
2914
|
-
readonly instrument?: Instrument;
|
|
2915
|
-
}
|
|
2916
|
-
/** The amount a caller or a destination pinned, and which leg it pins. */
|
|
2917
|
-
interface PinnedAmount {
|
|
2918
|
-
readonly value: bigint;
|
|
2919
|
-
readonly on: AmountOn;
|
|
2920
|
-
/**
|
|
2921
|
-
* What pinned it, for the diagnostic an `AmountMismatch` carries.
|
|
2922
|
-
*
|
|
2923
|
-
* `"destination"` covers the two shapes a destination pins an amount in —
|
|
2924
|
-
* an amount-bearing bolt11 and a BIP21 `amount=` — so the message names the
|
|
2925
|
-
* destination's pin rather than pretending the caller supplied it.
|
|
2926
|
-
*/
|
|
2927
|
-
readonly source: "caller" | "destination";
|
|
2928
|
-
}
|
|
2929
|
-
/**
|
|
2930
|
-
* What `resolve()` answers: the route's shape, the market that would price it,
|
|
2931
|
-
* and what the active snapshot actually serves.
|
|
2932
|
-
*
|
|
2933
|
-
* `eligible` is reported alongside rather than folded into an error because
|
|
2934
|
-
* zero is not a failure of resolution: the destination parsed, the corridor pair
|
|
2935
|
-
* is implemented, and nothing about the route is wrong — there is simply no
|
|
2936
|
-
* market for it on this snapshot. `quote()` is where that becomes
|
|
2937
|
-
* `UnsupportedRoute`, since a quote cannot proceed past market selection.
|
|
2938
|
-
*/
|
|
2939
|
-
interface RouteResolution {
|
|
2940
|
-
readonly give: ResolvedEndpoint;
|
|
2941
|
-
readonly take: ResolvedEndpoint;
|
|
2942
|
-
/** The card that would price it: the first eligible one after policy. */
|
|
2943
|
-
readonly market?: MarketRef;
|
|
2944
|
-
/** How many markets serve this pair on the active snapshot, after policy. */
|
|
2945
|
-
readonly eligible: number;
|
|
2946
|
-
/** Where the market data came from, and how fresh it is. */
|
|
2947
|
-
readonly snapshot: SnapshotRef;
|
|
2948
|
-
/** The amount pinned so far, when the input pinned one. */
|
|
2949
|
-
readonly amount?: PinnedAmount;
|
|
2950
|
-
}
|
|
2951
|
-
|
|
2952
|
-
/**
|
|
2953
|
-
* What survives a crash, and the public shape `accept()` hands back.
|
|
2954
|
-
*
|
|
2955
|
-
* Two types, one key. {@link SwapRecord} is the storage form — JSON-safe by
|
|
2956
|
-
* declaration, every amount a canonical decimal string — and {@link Swap} is the
|
|
2957
|
-
* answer a caller reads, with `bigint` amounts and the resolved `Route`. The
|
|
2958
|
-
* conversion between them is §D's record-boundary codec, and it is not a third
|
|
2959
|
-
* law: `toAtomicDecimal`/`fromAtomicDecimal` already ship in `./amount`, minted
|
|
2960
|
-
* by M1 and used by M3's wire adapter, so both sites emit the same canonical
|
|
2961
|
-
* form — atomic units, unsigned, no leading zeros, never a scaled display
|
|
2962
|
-
* decimal.
|
|
2963
|
-
*
|
|
2964
|
-
* **The key is the quote id, on every route.** That is what makes persist-first
|
|
2965
|
-
* representable at all: v1's `AssetSwap.id` *is* the funding txid
|
|
2966
|
-
* (`store.ts:70-71`), so a record could not exist before the money did, and
|
|
2967
|
-
* `coverage.ts` carries a process-local issuance mark precisely to paper over
|
|
2968
|
-
* the gap. Here the record precedes the funding and `fundingTxid` is a later,
|
|
2969
|
-
* best-effort write.
|
|
2970
|
-
*
|
|
2971
|
-
* **JSON-safe means no `bigint` anywhere, at any depth.** The SQLite and Realm
|
|
2972
|
-
* backends `JSON.stringify` the record whole, so a `bigint` throws on two
|
|
2973
|
-
* backends and round-trips on the third — the asymmetry
|
|
2974
|
-
* `test/repository.test.ts` refuses to paper over. Every amount here is an
|
|
2975
|
-
* {@link AtomicDecimal}; `test/client/record.types.ts` proves the absence
|
|
2976
|
-
* structurally rather than by review.
|
|
2977
|
-
*/
|
|
2978
|
-
|
|
2979
|
-
/**
|
|
2980
|
-
* Which family a record belongs to, and the discriminant M5's `RawState` keys
|
|
2981
|
-
* on.
|
|
2982
|
-
*
|
|
2983
|
-
* Not a cosmetic tag. v1's two families occupied one `string` id space by
|
|
2984
|
-
* accident — an offer record's id a funding txid, a corridor record's an
|
|
2985
|
-
* `rfqId` — and keying both on `QuoteId` closes that collision (§B). The tag is
|
|
2986
|
-
* what M6's public id carries, and what lets M5 branch its outcome table
|
|
2987
|
-
* without a repository read.
|
|
2988
|
-
*/
|
|
2989
|
-
type SwapFamily = "offer" | "rfq";
|
|
2990
|
-
/**
|
|
2991
|
-
* The public swap id: the family tag over the client-minted quote id,
|
|
2992
|
-
* `offer:<QuoteId>` / `rfq:<QuoteId>`, as {@link Swap.id} carries it.
|
|
2993
|
-
*
|
|
2994
|
-
* The tag is presentation, not a second identity — storage, the drive and
|
|
2995
|
-
* `accept()`'s idempotency stay keyed on the bare quote id. But a branded
|
|
2996
|
-
* string erases at runtime, so the tag is not cosmetic either: it makes
|
|
2997
|
-
* `NotCancellable` a parse of the prefix — a corridor id refused with no
|
|
2998
|
-
* repository read, an offer id distinguished from a corridor id the way the v1
|
|
2999
|
-
* read could not be — and it retypes the id a caller hands around, so
|
|
3000
|
-
* `cancel(swap.id)` and `recover(swap.id)` stop being two spellings of one
|
|
3001
|
-
* thing. An id arriving untagged from `/protocol`'s re-exported readers takes
|
|
3002
|
-
* the same one read the tagged form takes.
|
|
3003
|
-
*/
|
|
3004
|
-
type AssetSwapId = `${SwapFamily}:${QuoteId}`;
|
|
3005
|
-
/** The public id a record answers with — the tag, minted off its family. */
|
|
3006
|
-
declare const assetSwapIdOf: (family: SwapFamily, quoteId: QuoteId) => AssetSwapId;
|
|
3007
|
-
declare const OFFER_SWAP_ID_PREFIX: "offer:";
|
|
3008
|
-
declare const RFQ_SWAP_ID_PREFIX: "rfq:";
|
|
3009
|
-
/**
|
|
3010
|
-
* The family an id names, or `undefined` for an id no prefix tags — the form
|
|
3011
|
-
* `/protocol`'s re-exported readers still hand back, which takes the
|
|
3012
|
-
* repository read rather than the parse.
|
|
3013
|
-
*/
|
|
3014
|
-
declare const familyOfSwapId: (swapId: string) => SwapFamily | undefined;
|
|
3015
|
-
/**
|
|
3016
|
-
* The bare quote id under the tag — what storage, the drive and `accept()`'s
|
|
3017
|
-
* idempotency key on. Strips a family prefix when one is present and passes an
|
|
3018
|
-
* untagged id through unchanged, so a reader-era id still reaches its record.
|
|
3019
|
-
*/
|
|
3020
|
-
declare const quoteIdOfSwapId: (swapId: string) => QuoteId;
|
|
3021
|
-
/** One leg's obligation, in the form a record holds it. */
|
|
3022
|
-
interface RecordedLeg {
|
|
3023
|
-
readonly asset: AssetId;
|
|
3024
|
-
/** Atomic units as a canonical decimal string — never a `bigint`. */
|
|
3025
|
-
readonly amount: AtomicDecimal;
|
|
3026
|
-
}
|
|
3027
|
-
/**
|
|
3028
|
-
* An endpoint as the record holds it: the corridor, the asset, the instrument.
|
|
3029
|
-
*
|
|
3030
|
-
* `Instrument`'s invoice arm carries a `bigint` amount, so it cannot be stored
|
|
3031
|
-
* as declared — {@link RecordedInstrument} is the same union with that one field
|
|
3032
|
-
* in decimal form. The rest is field for field identical, which is what keeps the
|
|
3033
|
-
* comparison in `acceptConflict` honest.
|
|
3034
|
-
*/
|
|
3035
|
-
interface RecordedEndpoint {
|
|
3036
|
-
readonly corridor: CorridorId;
|
|
3037
|
-
readonly asset: AssetId;
|
|
3038
|
-
readonly instrument: RecordedInstrument;
|
|
3039
|
-
}
|
|
3040
|
-
/** {@link Instrument}, with the invoice arm's amount in decimal form. */
|
|
3041
|
-
type RecordedInstrument = {
|
|
3042
|
-
readonly kind: "wallet";
|
|
3043
|
-
} | {
|
|
3044
|
-
readonly kind: "address";
|
|
3045
|
-
readonly address: string;
|
|
3046
|
-
} | {
|
|
3047
|
-
readonly kind: "invoice";
|
|
3048
|
-
readonly bolt11: string;
|
|
3049
|
-
readonly paymentHash: Hex;
|
|
3050
|
-
readonly amount?: AtomicDecimal;
|
|
3051
|
-
readonly expiresAt: number;
|
|
3052
|
-
};
|
|
3053
|
-
/** {@link Artifact}, with the deposit arm's amount in decimal form. */
|
|
3054
|
-
type RecordedArtifact = {
|
|
3055
|
-
readonly kind: "invoice";
|
|
3056
|
-
readonly bolt11: string;
|
|
3057
|
-
} | {
|
|
3058
|
-
readonly kind: "deposit";
|
|
3059
|
-
readonly corridor: CorridorId;
|
|
3060
|
-
readonly address: string;
|
|
3061
|
-
readonly asset: AssetId;
|
|
3062
|
-
readonly amount: AtomicDecimal;
|
|
3063
|
-
readonly expiresAt?: number;
|
|
3064
|
-
};
|
|
3065
|
-
/**
|
|
3066
|
-
* The half both families carry.
|
|
3067
|
-
*
|
|
3068
|
-
* Every field is either something `AcceptConflict` compares (§3.2's list), or
|
|
3069
|
-
* something M5 named as a cross-milestone ask, or the two timestamps. Nothing
|
|
3070
|
-
* is here for display: a record carries what no covenant and no chain read can
|
|
3071
|
-
* give back, which is the same rule `RfqSwapRecord` is arranged by.
|
|
3072
|
-
*/
|
|
3073
|
-
interface SwapRecordCommon {
|
|
3074
|
-
/** The client-minted quote id — the primary key, per C1 and §B. */
|
|
3075
|
-
readonly id: QuoteId;
|
|
3076
|
-
readonly family: SwapFamily;
|
|
3077
|
-
/**
|
|
3078
|
-
* Both endpoints, instruments included — `AcceptConflict` items 1 and 3.
|
|
3079
|
-
*
|
|
3080
|
-
* Nested under `route` so the record's field names are `Quote`'s field
|
|
3081
|
-
* names: the conflict check walks the two shapes together, and a record
|
|
3082
|
-
* that spelled the same fact differently would make every comparison a
|
|
3083
|
-
* translation.
|
|
3084
|
-
*/
|
|
3085
|
-
readonly route: {
|
|
3086
|
-
readonly give: RecordedEndpoint;
|
|
3087
|
-
readonly take: RecordedEndpoint;
|
|
3088
|
-
};
|
|
3089
|
-
/** The two obligations — `AcceptConflict` item 2. */
|
|
3090
|
-
readonly give: RecordedLeg;
|
|
3091
|
-
readonly take: RecordedLeg;
|
|
3092
|
-
/** The spread, as the quote precomputed it. */
|
|
3093
|
-
readonly fee: RecordedLeg;
|
|
3094
|
-
/**
|
|
3095
|
-
* Which card priced this, from which registry, how fresh — stored WHOLE.
|
|
3096
|
-
*
|
|
3097
|
-
* A trimmed projection could not rebuild the type {@link Swap.market}
|
|
3098
|
-
* promises: `CardMarketRef` requires `kind`, `pair` and `snapshot` beside
|
|
3099
|
-
* the fields a summary would keep. Every member is a string, number or
|
|
3100
|
-
* boolean, so the union round-trips through JSON untouched, and `snapshot`
|
|
3101
|
-
* is restated as read at accept rather than restamped — a past `fetchedAt`
|
|
3102
|
-
* beside the recorded `live` is the honest answer about how fresh the card
|
|
3103
|
-
* was when this swap was accepted.
|
|
3104
|
-
*/
|
|
3105
|
-
readonly market: MarketRef;
|
|
3106
|
-
/**
|
|
3107
|
-
* The committed counterparty, from the quote's covenant role.
|
|
3108
|
-
*
|
|
3109
|
-
* NOT `CardMarketRef.solver`, which is the card's display name. Two
|
|
3110
|
-
* different facts that v1 spelled with one word: this one is a key that
|
|
3111
|
-
* ends up in a covenant leaf, the other is a label. `AcceptConflict`
|
|
3112
|
-
* compares this one.
|
|
3113
|
-
*/
|
|
3114
|
-
readonly solver?: Pubkey;
|
|
3115
|
-
/** The quote's own deadline, unix seconds — what makes a stalled accept a
|
|
3116
|
-
* benign abandon rather than a live obligation. */
|
|
3117
|
-
readonly expiresAt: number;
|
|
3118
|
-
/**
|
|
3119
|
-
* The one thing a counterparty must see, when this route has one.
|
|
3120
|
-
*
|
|
3121
|
-
* Durable because a duplicate accept must return the SAME invoice, and the
|
|
3122
|
-
* invoice lives on the quote object — nowhere in the corridor profile. A
|
|
3123
|
-
* caller that re-accepts after a restart has no quote object left, so
|
|
3124
|
-
* without this field the only honest answer would be a second invoice,
|
|
3125
|
-
* which §3.2 forbids by name.
|
|
3126
|
-
*/
|
|
3127
|
-
readonly artifact?: RecordedArtifact;
|
|
3128
|
-
/**
|
|
3129
|
-
* The transaction that funded this swap, once known.
|
|
3130
|
-
*
|
|
3131
|
-
* A later, best-effort write, and the field that separates M5's `accepted`
|
|
3132
|
-
* from `funding`. Set-where-absent is a benign resume and never an
|
|
3133
|
-
* `AcceptConflict` — §3.2 says so by name.
|
|
3134
|
-
*/
|
|
3135
|
-
readonly fundingTxid?: string;
|
|
3136
|
-
/**
|
|
3137
|
-
* Last local receive-claim error while the swap is still retryable. If the
|
|
3138
|
-
* claim window later closes without a submitted claim, this becomes the
|
|
3139
|
-
* terminal failure reason after restore.
|
|
3140
|
-
*/
|
|
3141
|
-
readonly claimFailure?: string;
|
|
3142
|
-
/** Terminal failure reason. */
|
|
3143
|
-
readonly failure?: string;
|
|
3144
|
-
/** Refusal reason while `state` is `needs_counterparty`. */
|
|
3145
|
-
readonly blockedReason?: string;
|
|
3146
|
-
/** Unix **seconds**, both — the unit `RfqSwapRecord` carries and
|
|
3147
|
-
* `shouldRetainRfqSwap` compares against, not `AssetSwap`'s milliseconds. */
|
|
3148
|
-
readonly createdAt: number;
|
|
3149
|
-
readonly updatedAt: number;
|
|
3150
|
-
}
|
|
3151
|
-
/**
|
|
3152
|
-
* `arkade <-> arkade`: the offer covenant, and what cancels it.
|
|
3153
|
-
*
|
|
3154
|
-
* `offerHex` is the whole covenant — `cancelOffer` needs nothing else to
|
|
3155
|
-
* rebuild it — so this arm stores no tree parameters of its own.
|
|
3156
|
-
*/
|
|
3157
|
-
interface OfferSwapRecord extends SwapRecordCommon {
|
|
3158
|
-
readonly family: "offer";
|
|
3159
|
-
/** v1's raw status vocabulary, which M5's `RawState` reads verbatim. */
|
|
3160
|
-
readonly status: AssetSwapStatus;
|
|
3161
|
-
/** The TLV offer, hex. The only input `cancelOffer` needs. */
|
|
3162
|
-
readonly offerHex: string;
|
|
3163
|
-
readonly swapAddress: string;
|
|
3164
|
-
/** The covenant's scriptPubKey, hex — the indexer's monitoring key, and
|
|
3165
|
-
* what §F's reconcile matches a discovered deposit against. */
|
|
3166
|
-
readonly swapPkScript: string;
|
|
3167
|
-
readonly spentTxid?: string;
|
|
3168
|
-
readonly completedAt?: number;
|
|
3169
|
-
}
|
|
3170
|
-
/**
|
|
3171
|
-
* The three corridor routes: a VHTLC lockup, its clocks and its secrets.
|
|
3172
|
-
*
|
|
3173
|
-
* **No covenant tree here.** Every lockup registers a contract row before its
|
|
3174
|
-
* address can be funded, and that row already holds the parameters, keyed by
|
|
3175
|
-
* the script they derive — a key `createContract` refuses to write unless the
|
|
3176
|
-
* params reproduce it. Storing the tree a second time would be two sources for
|
|
3177
|
-
* one covenant. `accept()` is what writes that row (see `./accept.ts`), which
|
|
3178
|
-
* is why a persisted record always has one.
|
|
3179
|
-
*/
|
|
3180
|
-
interface CorridorSwapRecord extends SwapRecordCommon {
|
|
3181
|
-
readonly family: "rfq";
|
|
3182
|
-
/** v1's raw state vocabulary, read verbatim by M5's `RawState`. */
|
|
3183
|
-
readonly state: RfqSwapState;
|
|
3184
|
-
/**
|
|
3185
|
-
* Which corridor, in the manager's own vocabulary.
|
|
3186
|
-
*
|
|
3187
|
-
* `PersistableRfqSwap["kind"]` rather than a `Corridor`: it is a route pair
|
|
3188
|
-
* — `lightning_send` and `lightning_receive` are one corridor from opposite
|
|
3189
|
-
* ends — and it is what resolves the handler that owns {@link profile}.
|
|
3190
|
-
*/
|
|
3191
|
-
readonly kind: PersistableRfqSwap["kind"];
|
|
3192
|
-
/** The solver's own id for the negotiation, echoed back on the wire. */
|
|
3193
|
-
readonly rfqId: string;
|
|
3194
|
-
/** The Arkade address that was funded, and the swap's handle on its
|
|
3195
|
-
* covenant row. */
|
|
3196
|
-
readonly lockupAddress: string;
|
|
3197
|
-
/** Its pkScript, hex — the row's key, and §F's matching key. */
|
|
3198
|
-
readonly lockupPkScript: string;
|
|
3199
|
-
/** The hash both covenants commit to. `sha256(P)`, hex. */
|
|
3200
|
-
readonly lock: {
|
|
3201
|
-
readonly hash: Hex;
|
|
3202
|
-
};
|
|
3203
|
-
/** When the trader's value comes back if the swap does not complete. */
|
|
3204
|
-
readonly refundLocktime: number;
|
|
3205
|
-
/**
|
|
3206
|
-
* The corridor's own half, as plain JSON.
|
|
3207
|
-
*
|
|
3208
|
-
* v1's opaque bag (`rfqRecord.ts:108-123`), written with `rfqSecretsProfile`
|
|
3209
|
-
* and read by `rfqCorridorHandlers.hydrate` — reused rather than
|
|
3210
|
-
* reinvented, so M5 rebuilds through machinery that already exists and a new
|
|
3211
|
-
* corridor still ships without touching this file. It is also what carries
|
|
3212
|
-
* `expectedAmount`, the claim value gate's request-time input.
|
|
3213
|
-
*
|
|
3214
|
-
* Amounts inside it follow v1's shapes (`expectedAmount` is a `number`),
|
|
3215
|
-
* which is JSON-safe and therefore fine: the decimal-string law governs
|
|
3216
|
-
* this record's OWN amount fields, not the bag it carries forward.
|
|
3217
|
-
*
|
|
3218
|
-
* **This is also where the swap's secrets live** — `profile.signer` and,
|
|
3219
|
-
* on a leg locked to a preimage, `profile.hashlock`. Deliberately not a
|
|
3220
|
-
* second copy at the record's top level: `rfqClaimSecretOf` and
|
|
3221
|
-
* `preimageForSwapRecord` already read them from here, and two homes for
|
|
3222
|
-
* one claim secret is two things to keep in step with one of them always
|
|
3223
|
-
* empty. At most one of `preimageHex`/`preimageSaltHex` is ever written,
|
|
3224
|
-
* and which arm exists is decided by the wallet's provisioning result, not
|
|
3225
|
-
* here.
|
|
3226
|
-
*/
|
|
3227
|
-
readonly profile: Record<string, unknown>;
|
|
3228
|
-
readonly refundTxid?: string;
|
|
3229
|
-
readonly lockupSpendTxids?: readonly string[];
|
|
3230
|
-
/**
|
|
3231
|
-
* `P`, hex — the preimage the solver revealed to settle a Lightning send.
|
|
3232
|
-
*
|
|
3233
|
-
* The exception the doctrine above allows for, and only on that leg: the
|
|
3234
|
-
* payee mints `P`, so {@link profile}'s hashlock carries the payment hash
|
|
3235
|
-
* and no claim-secret material. This is the counterparty's revealed
|
|
3236
|
-
* settlement proof, not a second copy of the wallet's own claim secret —
|
|
3237
|
-
* and public by the time it is written, being read out of the witness that
|
|
3238
|
-
* spent the lockup.
|
|
3239
|
-
*/
|
|
3240
|
-
readonly settlementPreimageHex?: string;
|
|
3241
|
-
}
|
|
3242
|
-
/** Everything `accept()` persists, both families in one key space. */
|
|
3243
|
-
type SwapRecord = OfferSwapRecord | CorridorSwapRecord;
|
|
3244
|
-
/**
|
|
3245
|
-
* A swap, as a caller reads it.
|
|
3246
|
-
*
|
|
3247
|
-
* The quote's terms plus what has happened to them. `bigint` amounts and the
|
|
3248
|
-
* resolved `Route`, because this is the public answer and the record is the
|
|
3249
|
-
* storage form — §D's codec is the boundary between the two.
|
|
3250
|
-
*
|
|
3251
|
-
* `artifact` stays optional: M7's `ReceiveRequest` is `Swap & { artifact:
|
|
3252
|
-
* Artifact }`, and an intersection cannot narrow a field that is already
|
|
3253
|
-
* required. `id` is the tagged public form {@link AssetSwapId} — minted from
|
|
3254
|
-
* `record.family` by {@link swapOf} — while storage, the drive and `accept()`'s
|
|
3255
|
-
* idempotency stay keyed on the bare quote id.
|
|
3256
|
-
*
|
|
3257
|
-
* {@link outcome} and the two reason strings are M5's, and they are here rather
|
|
3258
|
-
* than on `SwapUpdate.detail` because `detail` is typed `RawState` — the raw
|
|
3259
|
-
* machine word and nothing else. The reasons live on `SwapRecordCommon`, the
|
|
3260
|
-
* internal record, so without this a consumer told a swap `needs_recovery` had
|
|
3261
|
-
* nowhere to read WHY.
|
|
3262
|
-
*/
|
|
3263
|
-
interface Swap {
|
|
3264
|
-
readonly id: AssetSwapId;
|
|
3265
|
-
readonly family: SwapFamily;
|
|
3266
|
-
/** Where this swap stands, in the one vocabulary both families share. */
|
|
3267
|
-
readonly outcome: Outcome;
|
|
3268
|
-
/** Both endpoints resolved, instruments included. */
|
|
3269
|
-
readonly route: Route;
|
|
3270
|
-
/** What the trader gives, fee included. */
|
|
3271
|
-
readonly give: QuoteLeg;
|
|
3272
|
-
/** What the trader takes. */
|
|
3273
|
-
readonly take: QuoteLeg;
|
|
3274
|
-
/** The spread, denominated on the leg where it is exact. */
|
|
3275
|
-
readonly fee: QuoteLeg;
|
|
3276
|
-
readonly market: MarketRef;
|
|
3277
|
-
readonly solver?: Pubkey;
|
|
3278
|
-
/** Corridor routes: the hash both covenants commit to. */
|
|
3279
|
-
readonly lock?: {
|
|
3280
|
-
readonly hash: Hex;
|
|
3281
|
-
};
|
|
3282
|
-
/** Corridor routes: when the trader's value comes back. */
|
|
3283
|
-
readonly refundLocktime?: number;
|
|
3284
|
-
readonly artifact?: Artifact;
|
|
3285
|
-
readonly expiresAt: number;
|
|
3286
|
-
/** Absent until the funding is broadcast and its txid written. */
|
|
3287
|
-
readonly fundingTxid?: string;
|
|
3288
|
-
/**
|
|
3289
|
-
* Why the swap `failed`, when it did.
|
|
3290
|
-
*
|
|
3291
|
-
* Carried across from the record rather than derived: the outcome says
|
|
3292
|
-
* WHICH terminal state, and only the record says why.
|
|
3293
|
-
*/
|
|
3294
|
-
readonly failure?: string;
|
|
3295
|
-
/**
|
|
3296
|
-
* Why this wallet will not act, while the outcome is `needs_recovery`.
|
|
3297
|
-
*
|
|
3298
|
-
* Also what makes a suppressed configuration block legible: under
|
|
3299
|
-
* `drive: "manual"` or `"readonly"` the three configuration refusals are
|
|
3300
|
-
* not translated to `needs_recovery`, and this is where the reason is
|
|
3301
|
-
* still read.
|
|
3302
|
-
*/
|
|
3303
|
-
readonly blockedReason?: string;
|
|
3304
|
-
readonly createdAt: number;
|
|
3305
|
-
readonly updatedAt: number;
|
|
3306
|
-
}
|
|
3307
|
-
/** An endpoint into its stored form. */
|
|
3308
|
-
declare const recordEndpoint: (endpoint: {
|
|
3309
|
-
corridor: CorridorId;
|
|
3310
|
-
asset: string;
|
|
3311
|
-
instrument: Instrument;
|
|
3312
|
-
}) => RecordedEndpoint;
|
|
3313
|
-
/** An instrument into its stored form: only the invoice arm's amount moves. */
|
|
3314
|
-
declare const recordInstrument: (instrument: Instrument) => RecordedInstrument;
|
|
3315
|
-
/** A stored instrument back into the live union. */
|
|
3316
|
-
declare const instrumentOf: (instrument: RecordedInstrument) => Instrument;
|
|
3317
|
-
/** An artifact into its stored form. */
|
|
3318
|
-
declare const recordArtifact: (artifact: Artifact) => RecordedArtifact;
|
|
3319
|
-
/** A stored artifact back into the live union. */
|
|
3320
|
-
declare const artifactOf: (artifact: RecordedArtifact) => Artifact;
|
|
3321
|
-
/** A leg into its stored form. */
|
|
3322
|
-
declare const recordLeg: (leg: QuoteLeg) => RecordedLeg;
|
|
3323
|
-
/** A stored leg back into `bigint` units. */
|
|
3324
|
-
declare const legOf: (leg: RecordedLeg) => QuoteLeg;
|
|
3325
|
-
/**
|
|
3326
|
-
* The public {@link Swap} a stored record answers with.
|
|
3327
|
-
*
|
|
3328
|
-
* The one read path, so a duplicate `accept()` answers from the record rather
|
|
3329
|
-
* than from the in-memory preparation cache — which is bounded, evicted in
|
|
3330
|
-
* insertion order, and therefore not a durable answer to anything.
|
|
3331
|
-
*
|
|
3332
|
-
* The outcome is a parameter rather than a field read off the record: it is
|
|
3333
|
-
* derived from the record, the clock AND whether the drive holds live state for
|
|
3334
|
-
* this swap, and only the drive knows the third. Passing it keeps `Swap.outcome`
|
|
3335
|
-
* non-optional, which is what stops a caller from having to test for it.
|
|
3336
|
-
*
|
|
3337
|
-
* The `Route` is reassembled from the two stored endpoints. The cast is the
|
|
3338
|
-
* seam: `Route` is a closed union of four corridor pairs and a record read off
|
|
3339
|
-
* disk carries two independently-typed endpoints, so nothing in the type system
|
|
3340
|
-
* can re-correlate them. What guarantees the pairing is that `accept()` only
|
|
3341
|
-
* ever writes a record from a `Quote` whose route was already resolved through
|
|
3342
|
-
* that union.
|
|
3343
|
-
*/
|
|
3344
|
-
declare const swapOf: (record: SwapRecord, outcome: Outcome) => Swap;
|
|
3345
|
-
/**
|
|
3346
|
-
* Whether this swap's give leg is funded from the wallet.
|
|
3347
|
-
*
|
|
3348
|
-
* The discriminant for every funding-route decision in `accept()` — the balance
|
|
3349
|
-
* pre-flight, the `wallet.send`, the funding-txid write. It is the
|
|
3350
|
-
* **instrument** and not the asset: a `lightning -> arkade` receive gives BTC
|
|
3351
|
-
* too, but the give instrument is the hold invoice a third party pays, so an
|
|
3352
|
-
* asset-branched test would send every receive down the wallet-balance path and
|
|
3353
|
-
* refuse the canonical empty-wallet receive.
|
|
3354
|
-
*/
|
|
3355
|
-
declare const fundsFromWallet: (route: {
|
|
3356
|
-
give: {
|
|
3357
|
-
instrument: Instrument | RecordedInstrument;
|
|
3358
|
-
};
|
|
3359
|
-
}) => boolean;
|
|
3360
|
-
|
|
3361
|
-
/** A registry discovery result held for reuse. Refetchable — unlike a swap
|
|
3362
|
-
* record, losing it costs one network round trip — but it must survive a cold
|
|
3363
|
-
* boot: serving it stale is what keeps quoting alive while a registry is down. */
|
|
3364
|
-
interface MarketsCacheEntry {
|
|
3365
|
-
markets: DiscoveredMarket[];
|
|
3366
|
-
fetchedAt: number;
|
|
3367
|
-
}
|
|
3368
|
-
/**
|
|
3369
|
-
* Everything the package persists, following the monorepo repository
|
|
3370
|
-
* convention: versioned interface, AsyncDisposable, one backend per platform.
|
|
3371
|
-
* Consumers construct exactly one of these; there is no second storage seam.
|
|
3372
|
-
*
|
|
3373
|
-
* Durable records (swaps) and rebuildable state (the restore scan's txid
|
|
3374
|
-
* cursor, the markets cache) live side by side because they share a
|
|
3375
|
-
* lifetime: all three belong to one wallet on one device, and a consumer
|
|
3376
|
-
* that wipes one wants all three gone.
|
|
3377
|
-
*
|
|
3378
|
-
* ponytail: no query filters — every consumer reads all swaps and filters
|
|
3379
|
-
* in memory; add a filter type when a consumer needs subset queries.
|
|
3380
|
-
*/
|
|
3381
|
-
interface AssetSwapRepository extends AsyncDisposable {
|
|
3382
|
-
/** 5 adds the v2 swap-record store — one row per accepted swap, keyed by
|
|
3383
|
-
* the client-minted quote id. 4 added `getRfqSwap`; 3 added the other RFQ
|
|
3384
|
-
* methods below; 2 was the released shape — swaps, scan cursor, markets,
|
|
3385
|
-
* with `preimageSaltHex` on the swap record — so an implementor built
|
|
3386
|
-
* against any of them cannot satisfy this one silently. */
|
|
3387
|
-
readonly version: 5;
|
|
3388
|
-
/** Insert or replace a swap by id. Store the record whole: `preimageHex`
|
|
3389
|
-
* and `preimageSaltHex` both leave the swap unclaimable if a field-mapped
|
|
3390
|
-
* backend drops them — the first is the only claim secret of a swap whose
|
|
3391
|
-
* signer cannot derive, the second the public input every other static
|
|
3392
|
-
* wallet's preimage derives from.
|
|
3393
|
-
*
|
|
3394
|
-
* Records must be **JSON-safe**: the SQLite and Realm backends serialize
|
|
3395
|
-
* the record to JSON, so a `Date` in a consumer-added field comes back a
|
|
3396
|
-
* string, a `Set`/`Map` comes back empty, and a `bigint` throws here —
|
|
3397
|
-
* none of which happens on IndexedDB's structured clone. `AssetSwap` as
|
|
3398
|
-
* declared is JSON-safe; keep added fields that way. */
|
|
3399
|
-
saveSwap(swap: AssetSwap): Promise<void>;
|
|
3400
|
-
/** All stored swaps, in no particular order — `getAssetSwaps` is the
|
|
3401
|
-
* canonical newest-first read. */
|
|
3402
|
-
getAllSwaps(): Promise<AssetSwap[]>;
|
|
3403
|
-
/**
|
|
3404
|
-
* Insert or replace a monitored RFQ swap by `rfqId`.
|
|
3405
|
-
*
|
|
3406
|
-
* Store the record WHOLE. Every field is a covenant tree parameter or the
|
|
3407
|
-
* manager's own state, and a field-mapped backend that drops one round-trips
|
|
3408
|
-
* a record whose covenant `rebuildRfqSwap` cannot reproduce — which surfaces
|
|
3409
|
-
* as a refund that cannot be signed, long after the write.
|
|
3410
|
-
*/
|
|
3411
|
-
saveRfqSwap(record: RfqSwapRecord): Promise<void>;
|
|
3412
|
-
/** One record by key. `undefined` on a miss — retention prunes terminal
|
|
3413
|
-
* records, so absence is ordinary and not an error. */
|
|
3414
|
-
getRfqSwap(rfqId: string): Promise<RfqSwapRecord | undefined>;
|
|
3415
|
-
/** Every stored RFQ swap record, in no particular order. */
|
|
3416
|
-
getAllRfqSwaps(): Promise<RfqSwapRecord[]>;
|
|
3417
|
-
/** Drop one, once it is past retention — see `shouldRetainRfqSwap`. */
|
|
3418
|
-
removeRfqSwap(rfqId: string): Promise<void>;
|
|
3419
|
-
/**
|
|
3420
|
-
* Insert or replace a v2 swap record by its quote id.
|
|
3421
|
-
*
|
|
3422
|
-
* The store the v2 client's `accept()` writes, and the reason this
|
|
3423
|
-
* interface is at 5. Separate from `swaps` rather than sharing it: the v1
|
|
3424
|
-
* read path drops any row carrying neither `offerHex` nor `paymentHash`
|
|
3425
|
-
* (`getAssetSwapsOrThrow`), silently and as corrupt, so a v2 record in that
|
|
3426
|
-
* store would be pinned by a v1 predicate — and the two histories are meant
|
|
3427
|
-
* to be disjoint for the deprecation window anyway. A v1 reader not seeing
|
|
3428
|
-
* v2 rows is the design, asserted in the conformance suite rather than
|
|
3429
|
-
* tolerated.
|
|
3430
|
-
*
|
|
3431
|
-
* Store the record WHOLE, and note that it is **JSON-safe by declaration**:
|
|
3432
|
-
* every amount on it is a canonical decimal string, precisely so the SQLite
|
|
3433
|
-
* and Realm backends' `JSON.stringify` and IndexedDB's structured clone
|
|
3434
|
-
* agree. A `bigint` reaching here would throw on two backends and
|
|
3435
|
-
* round-trip on the third.
|
|
3436
|
-
*/
|
|
3437
|
-
saveSwapRecord(record: SwapRecord): Promise<void>;
|
|
3438
|
-
/** One record by quote id. `undefined` on a miss — which is the ordinary
|
|
3439
|
-
* answer for a first `accept()`, and what makes it idempotent. */
|
|
3440
|
-
getSwapRecord(id: string): Promise<SwapRecord | undefined>;
|
|
3441
|
-
/** Every stored v2 record, in no particular order. */
|
|
3442
|
-
getAllSwapRecords(): Promise<SwapRecord[]>;
|
|
3443
|
-
/** Drop one, once it is past retention. */
|
|
3444
|
-
removeSwapRecord(id: string): Promise<void>;
|
|
3445
|
-
/**
|
|
3446
|
-
* Sent txids already checked for offer packets (see restore.ts).
|
|
3447
|
-
*
|
|
3448
|
-
* **Shared across both record families, deliberately.** This is not
|
|
3449
|
-
* record-family data — it marks txids of transactions a scan has answered,
|
|
3450
|
-
* whatever family a later record belongs to — and both families walk the
|
|
3451
|
-
* same sent-txid set during the deprecation window. Two cursors would have
|
|
3452
|
-
* each side re-walking deposits the other already answered.
|
|
3453
|
-
*/
|
|
3454
|
-
getScannedTxids(): Promise<Set<string>>;
|
|
3455
|
-
markTxidsScanned(txids: Iterable<string>): Promise<void>;
|
|
3456
|
-
/** Cached registry markets, or undefined on a miss. Shared across both
|
|
3457
|
-
* record families for the reason the cursor is: the key is network-and-
|
|
3458
|
-
* registry, not a store, and two caches would serve two staleness clocks
|
|
3459
|
-
* for one registry. */
|
|
3460
|
-
getCachedMarkets(network: string, registry: string): Promise<MarketsCacheEntry | undefined>;
|
|
3461
|
-
saveCachedMarkets(network: string, registry: string, entry: MarketsCacheEntry): Promise<void>;
|
|
3462
|
-
clear(): Promise<void>;
|
|
3463
|
-
}
|
|
3464
|
-
declare class InMemoryAssetSwapRepository implements AssetSwapRepository {
|
|
3465
|
-
readonly version: 5;
|
|
3466
|
-
private readonly swaps;
|
|
3467
|
-
private readonly records;
|
|
3468
|
-
private readonly rfqSwaps;
|
|
3469
|
-
private readonly scanned;
|
|
3470
|
-
private readonly markets;
|
|
3471
|
-
saveSwap(swap: AssetSwap): Promise<void>;
|
|
3472
|
-
getAllSwaps(): Promise<AssetSwap[]>;
|
|
3473
|
-
saveRfqSwap(record: RfqSwapRecord): Promise<void>;
|
|
3474
|
-
getRfqSwap(rfqId: string): Promise<RfqSwapRecord | undefined>;
|
|
3475
|
-
getAllRfqSwaps(): Promise<RfqSwapRecord[]>;
|
|
3476
|
-
removeRfqSwap(rfqId: string): Promise<void>;
|
|
3477
|
-
saveSwapRecord(record: SwapRecord): Promise<void>;
|
|
3478
|
-
getSwapRecord(id: string): Promise<SwapRecord | undefined>;
|
|
3479
|
-
getAllSwapRecords(): Promise<SwapRecord[]>;
|
|
3480
|
-
removeSwapRecord(id: string): Promise<void>;
|
|
3481
|
-
getScannedTxids(): Promise<Set<string>>;
|
|
3482
|
-
markTxidsScanned(txids: Iterable<string>): Promise<void>;
|
|
3483
|
-
getCachedMarkets(network: string, registry: string): Promise<MarketsCacheEntry | undefined>;
|
|
3484
|
-
saveCachedMarkets(network: string, registry: string, entry: MarketsCacheEntry): Promise<void>;
|
|
3485
|
-
clear(): Promise<void>;
|
|
3486
|
-
[Symbol.asyncDispose](): Promise<void>;
|
|
3487
|
-
}
|
|
3488
|
-
|
|
3489
|
-
export { type MarketRef as $, type AssetId as A, type AuctionMarketRef as B, type Corridor as C, type AuctionProvenance as D, BITCOIN_RAILS as E, BTC_ASSET_PART as F, type BitcoinRail as G, CORRIDORS as H, type Instrument as I, CORRIDOR_PASS as J, type CardMarketRef as K, type LockupSpendIndexer as L, type CorridorId as M, type NetworkRef as N, type OfferSwapRecord as O, type PinnedAmount as P, type QuoteId as Q, type Rail as R, type SwapRecord as S, type CorridorKind as T, type DepositArtifact as U, type DisplayDecimal as V, type Endpoint as W, type Ep as X, type Hex as Y, LOCKUP_OWNER as Z, type MarketBackend as _, type RfqSwapRecordStore as a, type SwapOperator as a$, OFFER_SWAP_ID_PREFIX as a0, type Outcome as a1, type ParsedAssetId as a2, type Quote as a3, type QuoteLeg as a4, RAILS as a5, RFQ_SWAP_ID_PREFIX as a6, type RailOf as a7, type RankedBid as a8, type RawState as a9, instrumentOf as aA, isAssetId as aB, isAtomicDecimal as aC, isNetworkRef as aD, issuanceOf as aE, legOf as aF, offerOutcome as aG, parseAssetId as aH, quoteIdOfSwapId as aI, railOf as aJ, railOfCorridor as aK, readsChain as aL, recordArtifact as aM, recordEndpoint as aN, recordInstrument as aO, recordLeg as aP, recordOutcome as aQ, sameAsset as aR, swapOf as aS, toAtomicDecimal as aT, toRfqAmountSide as aU, toSafeNumber as aV, type AssetSwap as aW, type MarketsCacheEntry as aX, InMemoryAssetSwapRepository as aY, type RfqSwapState as aZ, type SwapContractRegistry as a_, type RecordedArtifact as aa, type RecordedEndpoint as ab, type RecordedInstrument as ac, type RecordedLeg as ad, type RfqAmountSide as ae, type SnapshotRef as af, type Swap as ag, type SwapFamily as ah, type SwapRecordCommon as ai, type SwapUpdate as aj, type Unsubscribe as ak, arkadeAsset as al, artifactOf as am, assetPartOf as an, assetSwapIdOf as ao, bitcoinNetworkOf as ap, btcOn as aq, corridorOfRail as ar, corridorOutcome as as, decodeRfqAmount as at, encodeRfqAmount as au, familyOfSwapId as av, formatAssetId as aw, fromAtomicDecimal as ax, fromRfqAmountSide as ay, fundsFromWallet as az, type CorridorSwapRecord as b, isRfqSwapTerminal as b0, type RfqSwapManagerCallbacks as b1, type RfqSwapActionName as b2, type SwapSecretsProjection as b3, type RefundIndexer as b4, type RfqSwap as b5, type ArkadeRefundResult as b6, type LockupVtxo as b7, type AvailableRfqSwapManagerCallbacks as b8, BTC_ASSET_ID as b9, createRfqSwapRecord as bA, findLockupVtxos as bB, getAssetSwaps as bC, isRfqTerminal as bD, nextOnchainAction as bE, normalizeRfqSwapRecord as bF, preimageForSwapRecord as bG, pushRefundWithoutReceiver as bH, readLockupFate as bI, rebuildRfqSwap as bJ, refundIfUnresolved as bK, rfqSwapOriginOf as bL, shouldRetainRfqSwap as bM, swapSecretsToRecord as bN, updateAssetSwap as bO, updateRfqSwapRecord as bP, type LightningReceiveSwap as ba, type LightningSendSwap as bb, type LockupFate as bc, LockupNeedsRecoveryError as bd, type LockupParams as be, type LockupSpend as bf, type OnchainSendAction as bg, type OnchainSendSwap as bh, type PersistableRfqSwap as bi, type PreimageBlockedReason as bj, PreimageNotRecoverableError as bk, RFQ_SWAP_RETENTION_SECONDS as bl, type RefundOutcome as bm, type RfqRestoreFailure as bn, type RfqRestoreOptions as bo, type RfqRestoreResult as bp, type RfqSwapLockup as bq, RfqSwapManager as br, type RfqSwapManagerConfig as bs, type RfqSwapManagerDeps as bt, type RfqSwapManagerEvents as bu, type RfqSwapOrigin as bv, RfqSwapOriginRequired as bw, type RfqSwapOutcome as bx, addAssetSwap as by, awaitRfqResolution as bz, type AssetSwapRepository as c, type RfqSwapRecord as d, type AssetSwapStatus as e, type RouteResolution as f, type ResolvedEndpoint as g, type Route as h, type QuoteInput as i, type Pubkey as j, ACTIVITY_TOKEN as k, ARKADE_ASSET_NAMESPACE as l, Amount as m, AmountFormatError as n, type AmountOn as o, type AmountRefusal as p, type Artifact as q, AssetIdError as r, type AssetIdRefusal as s, type AssetNamespace as t, type AssetOn as u, type AssetPart as v, type AssetRef as w, type AssetScale as x, type AssetSwapId as y, type AtomicDecimal as z };
|