@arkade-os/swap 0.1.0-rc.9 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +261 -252
- package/dist/advanced.cjs +6613 -3224
- package/dist/advanced.d.cts +328 -283
- package/dist/advanced.d.ts +328 -283
- package/dist/advanced.js +347 -34
- package/dist/chunk-A3SHHRX4.js +104 -0
- package/dist/chunk-FMRAV77W.js +3065 -0
- package/dist/chunk-T4FHBWZI.js +3459 -0
- package/dist/{chunk-NS3K6BZG.js → chunk-YHESEL4I.js} +1792 -636
- package/dist/index.cjs +6901 -3901
- package/dist/index.d.cts +71 -243
- package/dist/index.d.ts +71 -243
- package/dist/index.js +131 -167
- package/dist/lockupContract-CIXkJPxV.d.ts +148 -0
- package/dist/lockupContract-CkhWMKCo.d.cts +148 -0
- package/dist/node/index.cjs +61 -10
- package/dist/node/index.d.cts +307 -635
- package/dist/node/index.d.ts +307 -635
- package/dist/node/index.js +65 -10
- package/dist/nostr.cjs +427 -49
- package/dist/nostr.d.cts +59 -70
- package/dist/nostr.d.ts +59 -70
- package/dist/nostr.js +268 -36
- package/dist/offer-BPD2ortO.d.ts +269 -0
- package/dist/offer-Diff5Flc.d.cts +269 -0
- package/dist/offerFillPlan-B-5ae_gQ.d.cts +1671 -0
- package/dist/offerFillPlan-CJzneX6F.d.ts +1671 -0
- package/dist/protocol.cjs +5717 -4275
- package/dist/protocol.d.cts +258 -328
- package/dist/protocol.d.ts +258 -328
- package/dist/protocol.js +200 -224
- package/dist/repositories/realm/index.cjs +55 -11
- package/dist/repositories/realm/index.d.cts +18 -30
- package/dist/repositories/realm/index.d.ts +18 -30
- package/dist/repositories/realm/index.js +49 -12
- package/dist/repositories/sqlite/index.cjs +61 -10
- package/dist/repositories/sqlite/index.d.cts +7 -6
- package/dist/repositories/sqlite/index.d.ts +7 -6
- package/dist/repositories/sqlite/index.js +57 -11
- package/dist/repository-BBVRh9ez.d.ts +2357 -0
- package/dist/repository-C4pvymhs.d.cts +2357 -0
- package/dist/{rfq-BO6o7NwS.d.ts → rfq-C0tHOvn6.d.cts} +323 -444
- package/dist/{rfq-BO6o7NwS.d.cts → rfq-C0tHOvn6.d.ts} +323 -444
- package/dist/watch-7BiRa4oB.d.ts +74 -0
- package/dist/watch-Bxq-lx_6.d.cts +74 -0
- package/package.json +10 -10
- package/dist/chunk-JFKGMPMH.js +0 -3456
- package/dist/chunk-LLG7RD2T.js +0 -1499
- package/dist/chunk-U7VWWTL6.js +0 -66
- package/dist/errors-CNISbN0M.d.ts +0 -2218
- package/dist/errors-DwNhIP0N.d.cts +0 -2218
- package/dist/lockupContract-C8-Mcg69.d.ts +0 -664
- package/dist/lockupContract-mIt4syse.d.cts +0 -664
- package/dist/repository-CGPLbjBe.d.ts +0 -3489
- package/dist/repository-DSGGq0ct.d.cts +0 -3489
- package/dist/watch-DWyVqyEN.d.cts +0 -96
- package/dist/watch-DmvHNX6T.d.ts +0 -96
|
@@ -0,0 +1,1671 @@
|
|
|
1
|
+
import { IWallet, NetworkName, Network, SignerSet, OnchainProvider, ArkadeInfo, VHTLC, ProvisionedKey, ProvisionedClaimSecret, Transaction } from '@arkade-os/sdk';
|
|
2
|
+
import { bd as SwapOperator, d as AssetSwapRepository, m as Pubkey, bf as RfqSwapManagerCallbacks, C as Corridor, I as Instrument, bg as RfqSwapActionName, N as NetworkRef, A as AssetId, ao as SnapshotRef, a4 as MarketBackend, X as CardMarketRef, a5 as MarketRef, E as AssetRef, r as AmountOn, ap as Swap, Y as CorridorId, _ as DepositArtifact, l as QuoteInput, a9 as Quote, ae as RankedBid, as as SwapUpdate, au as Unsubscribe, S as SwapRecord, Q as QuoteId, a7 as Outcome, L as LockupSpendIndexer, bc as SwapContractRegistry, j as ResolvedEndpoint, P as PinnedAmount, D as AssetPaymentTerms, B as AssetPaymentInput, O as OfferSwapRecord, G as AssetSwapId, aq as SwapFamily, i as RouteResolution } from './repository-BBVRh9ez.js';
|
|
3
|
+
import { I as InvoiceFacts, C as ChainSource, R as RfqQuote, e as RfqTransport, L as LightningSendContractParams, f as LightningReceiveContractParams, O as OnchainHtlc, g as OnchainHtlcParams, h as OnchainNetwork, S as SwapRefusal } from './rfq-C0tHOvn6.js';
|
|
4
|
+
import { Network as Network$1, LocalCardInput, TransportCardFetcher, DiscoveredMarket, Side, OfferPlan } from '@arkade-os/solver-discovery';
|
|
5
|
+
import { D as DerivedOffer, F as FillFunding, a as FillOutpoint, b as FillInputOwner } from './offer-BPD2ortO.js';
|
|
6
|
+
import * as nostr_tools from 'nostr-tools';
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* What a corridor is given, what a caller may replace, and where "overridden to nothing" is refused.
|
|
10
|
+
*
|
|
11
|
+
* Override fields are `T | null` so "absent, use the default" (`undefined`) differs from "disabled,
|
|
12
|
+
* deliberately" (`null`, which {@link resolveCorridorDeps} refuses with {@link MissingCorridorDep}).
|
|
13
|
+
* Exception: the onchain claim fee rate, whose `null` is manual mode. Resolution runs when a route
|
|
14
|
+
* first touches a corridor, never at construction. The operator seam and co-signer key are trust
|
|
15
|
+
* anchors and deliberately NOT overridable.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* The facts every module reads and no caller replaces. The wallet answers *who and where* (only it
|
|
20
|
+
* can make the live, fail-closed info read — `SwapOperator.getInfo()` takes no options); the
|
|
21
|
+
* operator seam answers *submit and finalize*.
|
|
22
|
+
*/
|
|
23
|
+
interface CorridorBase {
|
|
24
|
+
readonly wallet: IWallet;
|
|
25
|
+
readonly operator: SwapOperator;
|
|
26
|
+
/** The network the live operator info named. */
|
|
27
|
+
readonly networkName: NetworkName;
|
|
28
|
+
/** Address parameters for {@link networkName}. */
|
|
29
|
+
readonly network: Network;
|
|
30
|
+
/** The operator's signer set, for the rotation-aware recipient check. */
|
|
31
|
+
readonly signerSet: SignerSet;
|
|
32
|
+
/** Covenant co-signer override, 33-byte compressed hex. Required on `testnet` and `signet`, which
|
|
33
|
+
* `EMULATOR_PUBKEYS` does not pin. */
|
|
34
|
+
readonly emulatorPubkey?: string;
|
|
35
|
+
/** For hosts without a global `fetch`, and for tests. */
|
|
36
|
+
readonly fetchImpl?: typeof fetch;
|
|
37
|
+
/** The client's storage, here so the arkade override defaults to the same object (records and
|
|
38
|
+
* the markets cache in one store). The override still wins; its `null` still refuses. */
|
|
39
|
+
readonly repository?: AssetSwapRepository;
|
|
40
|
+
}
|
|
41
|
+
/** The override matrix. An override replaces a dependency inside an implemented corridor; it never
|
|
42
|
+
* enables a route, selects a solver or transport, or alters settlement. */
|
|
43
|
+
interface CorridorOverrides {
|
|
44
|
+
arkade?: {
|
|
45
|
+
/** Where persist-first lands. Defaults to the client's own
|
|
46
|
+
* `repository`, so the two seams are one object; `null` refuses. */
|
|
47
|
+
repository?: AssetSwapRepository | null;
|
|
48
|
+
};
|
|
49
|
+
lightning?: {
|
|
50
|
+
/** Default: the package's own {@link decodeBolt11}. */
|
|
51
|
+
decode?: ((bolt11: string) => InvoiceFacts) | null;
|
|
52
|
+
/** Default: none — nothing is sealed and no packet is sent, so the
|
|
53
|
+
* trader must claim its own lockup before `refund_locktime`. Set, only a
|
|
54
|
+
* take-pinned (exact-out) BTC receive is guaranteed one. */
|
|
55
|
+
covclaimd?: {
|
|
56
|
+
pubkey: Pubkey;
|
|
57
|
+
} | null;
|
|
58
|
+
};
|
|
59
|
+
onchain?: {
|
|
60
|
+
/** Default: Esplora at `ESPLORA_URL[network]`. `{ provider }` reads L1 through the caller's
|
|
61
|
+
* own `OnchainProvider` instead, e.g. Electrum: `IWallet` carries none to borrow. */
|
|
62
|
+
chain?: {
|
|
63
|
+
esploraUrl: string;
|
|
64
|
+
} | {
|
|
65
|
+
provider: OnchainProvider;
|
|
66
|
+
} | null;
|
|
67
|
+
/** How the trader's L1 claim is built and broadcast. Default: synthesized from
|
|
68
|
+
* {@link claimFeeRateSatVb} when resolvable (see {@link OnchainCorridorDeps.claim}). */
|
|
69
|
+
claim?: OnchainClaim | null;
|
|
70
|
+
/** How the trader's L1 refund of an `onchain -> arkade` funding is built and broadcast.
|
|
71
|
+
* Default: synthesized from {@link claimFeeRateSatVb} when resolvable (see
|
|
72
|
+
* {@link OnchainCorridorDeps.refund}). */
|
|
73
|
+
refund?: OnchainRefund | null;
|
|
74
|
+
/**
|
|
75
|
+
* Sat/vB the trader's L1 claim (and refund) is built at, and the rate the take leg is grossed up by so the
|
|
76
|
+
* recipient nets the requested amount. Default: {@link ONCHAIN_CLAIM_FEE_RATE_SATVB}.
|
|
77
|
+
*
|
|
78
|
+
* `null` is NOT a refusal here: it is "no default claim" — manual mode. The corridor still
|
|
79
|
+
* quotes (take leg verbatim) and drives the lockup; the L1 claim is the caller's to make.
|
|
80
|
+
*/
|
|
81
|
+
claimFeeRateSatVb?: number | null;
|
|
82
|
+
/** The vsize the recipient-exact gross-up prices the claim at. Default
|
|
83
|
+
* {@link ONCHAIN_CLAIM_VSIZE}; `null` reads as `undefined`. The claim build measures its own. */
|
|
84
|
+
claimVsize?: number | null;
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
/** Build and broadcast the L1 claim of an `arkade -> onchain` fill (the manager's own type). */
|
|
88
|
+
type OnchainClaim = RfqSwapManagerCallbacks["claimOnchain"];
|
|
89
|
+
/** Build and broadcast the L1 refund of an `onchain -> arkade` funding (the manager's own type). */
|
|
90
|
+
type OnchainRefund = RfqSwapManagerCallbacks["refundOnchain"];
|
|
91
|
+
/**
|
|
92
|
+
* Per-network default L1 claim fee rate, sat/vB — deliberately the RELAY FLOOR, since it both builds
|
|
93
|
+
* the claim and prices the gross-up. On mainnet override UPWARD in congestion: the claim has a
|
|
94
|
+
* consensus deadline (`htlc.refundLocktime`). `Partial`: an absent network means manual mode.
|
|
95
|
+
*/
|
|
96
|
+
declare const ONCHAIN_CLAIM_FEE_RATE_SATVB: Partial<Record<NetworkName, number>>;
|
|
97
|
+
/** The arkade corridor's deps. Only the repository is overridable. */
|
|
98
|
+
interface ArkadeCorridorDeps {
|
|
99
|
+
readonly wallet: IWallet;
|
|
100
|
+
readonly operator: SwapOperator;
|
|
101
|
+
readonly networkName: NetworkName;
|
|
102
|
+
readonly network: Network;
|
|
103
|
+
readonly signerSet: SignerSet;
|
|
104
|
+
/** The pinned per-network co-signer, or the caller's override. Resolved from the network NAME,
|
|
105
|
+
* never from the operator's self-report — the key lands in a covenant leaf deciding who moves
|
|
106
|
+
* the funds. */
|
|
107
|
+
readonly emulatorPubkey: string;
|
|
108
|
+
readonly repository: AssetSwapRepository | undefined;
|
|
109
|
+
}
|
|
110
|
+
/** The lightning corridor's deps. */
|
|
111
|
+
interface LightningCorridorDeps {
|
|
112
|
+
readonly networkName: NetworkName;
|
|
113
|
+
readonly decode: (bolt11: string) => InvoiceFacts;
|
|
114
|
+
/** `undefined` means no covclaimd is deployed — nothing is sealed and no
|
|
115
|
+
* packet is sent. Not a missing dep. */
|
|
116
|
+
readonly covclaimd: {
|
|
117
|
+
pubkey: Pubkey;
|
|
118
|
+
} | undefined;
|
|
119
|
+
}
|
|
120
|
+
/** The onchain corridor's deps. */
|
|
121
|
+
interface OnchainCorridorDeps {
|
|
122
|
+
readonly networkName: NetworkName;
|
|
123
|
+
readonly chain: ChainSource;
|
|
124
|
+
/** The caller's L1 claim callback, verbatim. The default claim is built in the drive from
|
|
125
|
+
* {@link claimFeeRateSatVb}; with neither, the L1 half reports blocked while the Arkade lockup is
|
|
126
|
+
* still driven and refunded. */
|
|
127
|
+
readonly claim?: OnchainClaim;
|
|
128
|
+
/** The caller's L1 refund callback, verbatim. The default refund is built in the drive from
|
|
129
|
+
* {@link claimFeeRateSatVb}; with neither, an `onchain -> arkade` swap whose solver never
|
|
130
|
+
* funds reports blocked until one is wired. */
|
|
131
|
+
readonly refund?: OnchainRefund;
|
|
132
|
+
/**
|
|
133
|
+
* The one fee rate both recipient-exact halves share: the quote's gross-up (`claimFeeSats`) and
|
|
134
|
+
* the default claim build. Two numbers would short the recipient. `undefined` = manual mode.
|
|
135
|
+
* The default refund is built at it too.
|
|
136
|
+
*/
|
|
137
|
+
readonly claimFeeRateSatVb?: number;
|
|
138
|
+
/**
|
|
139
|
+
* The vsize the gross-up prices the claim at; the claim build measures its
|
|
140
|
+
* own transaction and never reads this. Default {@link ONCHAIN_CLAIM_VSIZE}.
|
|
141
|
+
*/
|
|
142
|
+
readonly claimVsize?: number;
|
|
143
|
+
}
|
|
144
|
+
/** Which corridor gets which dep record. */
|
|
145
|
+
interface CorridorDepsByCorridor {
|
|
146
|
+
arkade: ArkadeCorridorDeps;
|
|
147
|
+
lightning: LightningCorridorDeps;
|
|
148
|
+
onchain: OnchainCorridorDeps;
|
|
149
|
+
}
|
|
150
|
+
/** Any corridor's deps. */
|
|
151
|
+
type CorridorDeps = CorridorDepsByCorridor[Corridor];
|
|
152
|
+
/**
|
|
153
|
+
* A corridor's deps, with `undefined` taking the default and `null` refused. Per corridor, never all
|
|
154
|
+
* three at once: resolving an untouched corridor would turn its deliberate `null` into an error.
|
|
155
|
+
*/
|
|
156
|
+
declare function resolveCorridorDeps<C extends Corridor>(corridor: C, overrides: CorridorOverrides | undefined, base: CorridorBase): CorridorDepsByCorridor[C];
|
|
157
|
+
/**
|
|
158
|
+
* The operator info read, every failure as one typed {@link OperatorUnreachable}. The whole read is
|
|
159
|
+
* wrapped because `requireLive` re-throws the provider's raw error, whose type varies (and across a
|
|
160
|
+
* service-worker boundary is a bare `Error`). Covenant derivations read live, since a snapshot can
|
|
161
|
+
* bind a signer key the operator no longer co-signs for; `resolve()` takes the offline fallback.
|
|
162
|
+
*/
|
|
163
|
+
declare const liveArkadeInfo: (wallet: IWallet, opts?: {
|
|
164
|
+
requireLive?: boolean;
|
|
165
|
+
}) => Promise<ArkadeInfo>;
|
|
166
|
+
/**
|
|
167
|
+
* The one operator read, made once for all three corridors. `getNetwork` stays fail-closed: an
|
|
168
|
+
* unknown network name is not "unreachable", and resolving it to mainnet params is what it prevents.
|
|
169
|
+
*/
|
|
170
|
+
declare const resolveCorridorBase: (input: {
|
|
171
|
+
wallet: IWallet;
|
|
172
|
+
operator: SwapOperator;
|
|
173
|
+
emulatorPubkey?: string;
|
|
174
|
+
fetchImpl?: typeof fetch;
|
|
175
|
+
/** The client's storage, threaded so the arkade dep can default to it. */
|
|
176
|
+
repository?: AssetSwapRepository;
|
|
177
|
+
/** Defaults to `true` — see {@link liveArkadeInfo}. */
|
|
178
|
+
requireLive?: boolean;
|
|
179
|
+
}) => Promise<CorridorBase>;
|
|
180
|
+
|
|
181
|
+
/**
|
|
182
|
+
* One contract, three implementations: a corridor module owns its destination parse, deps,
|
|
183
|
+
* observation seams, and the lockup-owner axis the drive's outcome table keys on. Keyed by
|
|
184
|
+
* **corridor**, not v1's `RfqSwap["kind"]` route pair. Registration is internal: an externally
|
|
185
|
+
* registered corridor would parse and quote and then sit undriven.
|
|
186
|
+
*/
|
|
187
|
+
|
|
188
|
+
/** A module's answer about one destination — three outcomes: *mine, and wrong* (a `tb1…` on
|
|
189
|
+
* mainnet) must surface as `AmbiguousDestination` with the reason, not collapse into *not mine*. */
|
|
190
|
+
type CorridorClaim = {
|
|
191
|
+
claimed: Instrument;
|
|
192
|
+
refused?: never;
|
|
193
|
+
} | {
|
|
194
|
+
refused: string;
|
|
195
|
+
claimed?: never;
|
|
196
|
+
} | undefined;
|
|
197
|
+
/** What a drive pass reads. Two, and a solver status read is not one of them. */
|
|
198
|
+
type ObservationSeam =
|
|
199
|
+
/** Arkade access — `RfqSwapManagerDeps.indexer`. */
|
|
200
|
+
"indexer"
|
|
201
|
+
/** L1 access — `RfqSwapManagerDeps.chain`. */
|
|
202
|
+
| "chain";
|
|
203
|
+
/** A covenant a pass reads. */
|
|
204
|
+
type CorridorCovenant =
|
|
205
|
+
/** The Arkade-side VHTLC every corridor route has exactly one of. */
|
|
206
|
+
"arkade_lockup"
|
|
207
|
+
/** The L1 HTLC, which the onchain corridor adds in either direction. */
|
|
208
|
+
| "onchain_htlc";
|
|
209
|
+
/** Whose covenant it is. Ownership inverts the deadline: a TRADER lockup's deadline is a moment to
|
|
210
|
+
* act after, a SOLVER lockup's a moment to have acted before. */
|
|
211
|
+
type LockupOwner = "trader" | "solver";
|
|
212
|
+
/** The deadlines the code already fixes. Margins belong to the drive layer. */
|
|
213
|
+
type CorridorDeadline =
|
|
214
|
+
/** `RfqSwapCommon.refundLocktime`, on every kind. */
|
|
215
|
+
"refund_locktime"
|
|
216
|
+
/** The L1 HTLC's `htlc.refundLocktime`, on the onchain corridor alone. */
|
|
217
|
+
| "htlc_refund_locktime";
|
|
218
|
+
/** One covenant a pass reads, with its owner and the deadline it runs against. */
|
|
219
|
+
interface CorridorLockup {
|
|
220
|
+
readonly covenant: CorridorCovenant;
|
|
221
|
+
readonly owner: LockupOwner;
|
|
222
|
+
readonly deadline: CorridorDeadline;
|
|
223
|
+
}
|
|
224
|
+
/** Which side of a route this corridor is on; it inverts every ownership answer. */
|
|
225
|
+
type RouteSide = "give" | "take";
|
|
226
|
+
/** What a drive pass does about a route whose non-arkade leg is this corridor. */
|
|
227
|
+
interface CorridorPass {
|
|
228
|
+
/** Every covenant the pass reads, in the order it reads them. */
|
|
229
|
+
readonly lockups: readonly CorridorLockup[];
|
|
230
|
+
/** The actions the manager may execute; a subset of v1's own union. */
|
|
231
|
+
readonly actions: readonly RfqSwapActionName[];
|
|
232
|
+
/** The seams the pass reads. */
|
|
233
|
+
readonly seams: readonly ObservationSeam[];
|
|
234
|
+
}
|
|
235
|
+
/**
|
|
236
|
+
* A corridor's drive facts, per side. Partial on purpose: `arkade` has neither, since
|
|
237
|
+
* `arkade -> arkade` is an offer covenant with no lockup. The arkade leg's lockup is declared by the counter-corridor's entry.
|
|
238
|
+
*/
|
|
239
|
+
type CorridorDrive = Partial<Record<RouteSide, CorridorPass>>;
|
|
240
|
+
/** One corridor. `deps` are closed over at construction because the parse needs them (network,
|
|
241
|
+
* signer set, decoder) and none is in the destination string. */
|
|
242
|
+
interface CorridorModule<D = unknown> {
|
|
243
|
+
readonly corridor: Corridor;
|
|
244
|
+
/**
|
|
245
|
+
* This corridor's claim over `raw` — a bare destination or a BIP21 URI. **Sync, non-throwing and
|
|
246
|
+
* amount-blind**, matching core's rail contract (`match(req, ctx): boolean`, called bare inside
|
|
247
|
+
* the router's `options()`).
|
|
248
|
+
*/
|
|
249
|
+
matches(raw: string): CorridorClaim;
|
|
250
|
+
readonly deps: D;
|
|
251
|
+
readonly drive: CorridorDrive;
|
|
252
|
+
}
|
|
253
|
+
/** A module's factory, plus `target`: core's dep-free classifier, asked FIRST so a bolt11 never
|
|
254
|
+
* resolves the onchain corridor's deps. */
|
|
255
|
+
interface CorridorFactory<D> {
|
|
256
|
+
(deps: D): CorridorModule<D>;
|
|
257
|
+
/** The destination class this corridor speaks for. Dep-free by
|
|
258
|
+
* construction: core's classifiers read the string and nothing else. */
|
|
259
|
+
readonly target: (raw: string) => string | undefined;
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
/** The shipped corridors. Total over `Corridor`, checked at compile time. */
|
|
263
|
+
declare const CORRIDOR_FACTORIES: {
|
|
264
|
+
readonly arkade: CorridorFactory<ArkadeCorridorDeps>;
|
|
265
|
+
readonly lightning: CorridorFactory<LightningCorridorDeps>;
|
|
266
|
+
readonly onchain: CorridorFactory<OnchainCorridorDeps>;
|
|
267
|
+
};
|
|
268
|
+
/** What a destination resolves to: the corridor that claimed it, and how it
|
|
269
|
+
* settles. No asset — every Arkade asset shares a single address form. */
|
|
270
|
+
interface ClaimedDestination {
|
|
271
|
+
corridor: Corridor;
|
|
272
|
+
instrument: Instrument;
|
|
273
|
+
}
|
|
274
|
+
/**
|
|
275
|
+
* The corridors of one client, with deps resolved lazily on first use, so a dep overridden to
|
|
276
|
+
* `null` on a corridor nobody uses is not an error.
|
|
277
|
+
*/
|
|
278
|
+
interface CorridorSet {
|
|
279
|
+
/** The module for `corridor`, resolving and memoizing its deps on the first
|
|
280
|
+
* call. Throws `MissingCorridorDep` when a dep of THIS corridor was
|
|
281
|
+
* overridden to nothing. */
|
|
282
|
+
get<C extends Corridor>(corridor: C): CorridorModule<CorridorDepsByCorridor[C]>;
|
|
283
|
+
/**
|
|
284
|
+
* Which corridor claims `raw`, if any.
|
|
285
|
+
*
|
|
286
|
+
* @throws {AmbiguousDestination} when more than one corridor claims it,
|
|
287
|
+
* when the corridor that owns its class refuses it, or when nothing
|
|
288
|
+
* classifies it at all.
|
|
289
|
+
* @throws {MissingCorridorDep} when the corridor that owns this destination
|
|
290
|
+
* has a dep disabled via overrides.
|
|
291
|
+
* @returns `undefined` when core classifies the string but no corridor
|
|
292
|
+
* serves it — an LNURL today — which becomes `UnsupportedRoute` at route
|
|
293
|
+
* resolution rather than a parse failure here.
|
|
294
|
+
*/
|
|
295
|
+
claim(raw: string): ClaimedDestination | undefined;
|
|
296
|
+
}
|
|
297
|
+
declare const corridorSet: (base: CorridorBase, overrides?: CorridorOverrides) => CorridorSet;
|
|
298
|
+
|
|
299
|
+
/**
|
|
300
|
+
* The alias layer: public ids down to the vocabulary discovery and RFQ speak.
|
|
301
|
+
*
|
|
302
|
+
* One way only: several CAIP-19 public ids can share one discovery leg, so there is no
|
|
303
|
+
* round trip. The covenant identity is carried verbatim and does round-trip.
|
|
304
|
+
*
|
|
305
|
+
* The RFQ wire's `pair` (`<from-leg>-><to-leg>`, byte-compared and length-capped by the
|
|
306
|
+
* solver) is built by the quote path, not here; a CAIP-19 id would break both.
|
|
307
|
+
*/
|
|
308
|
+
|
|
309
|
+
/** What discovery names a leg by: its corridor, and the asset id on it. */
|
|
310
|
+
interface DiscoveryLeg {
|
|
311
|
+
corridor: Corridor;
|
|
312
|
+
/** `"btc"`, or the 68-hex Arkade asset identity. */
|
|
313
|
+
assetId: string;
|
|
314
|
+
/** Full CAIP-19 id used by solver-discovery's canonical market selector. */
|
|
315
|
+
marketId: AssetId;
|
|
316
|
+
}
|
|
317
|
+
/**
|
|
318
|
+
* A public id down to its discovery leg.
|
|
319
|
+
*
|
|
320
|
+
* @throws {@link UnsupportedRoute} for anything v2 cannot route, e.g. an `eip155:` id, or
|
|
321
|
+
* a non-BTC asset on lightning or L1.
|
|
322
|
+
*/
|
|
323
|
+
declare const toDiscoveryLeg: (id: AssetId) => DiscoveryLeg;
|
|
324
|
+
/** One registry row: what a ticker canonicalizes to. */
|
|
325
|
+
interface RegisteredAsset {
|
|
326
|
+
id: AssetId;
|
|
327
|
+
/** The display ticker. Matched case-insensitively; never an identity. */
|
|
328
|
+
ticker: string;
|
|
329
|
+
}
|
|
330
|
+
/** The table caller input is canonicalized against; the quote path fills it from discovery. */
|
|
331
|
+
interface AssetAliasTable {
|
|
332
|
+
/** The wallet's network. An id on any other network is not a candidate. */
|
|
333
|
+
network: NetworkRef;
|
|
334
|
+
assets: readonly RegisteredAsset[];
|
|
335
|
+
}
|
|
336
|
+
/**
|
|
337
|
+
* The networks discovery publishes a market index for (core's set minus `testnet`). The
|
|
338
|
+
* `satisfies` makes a rename on either side a compile error, not a silent "no index".
|
|
339
|
+
*/
|
|
340
|
+
declare const INDEXED_NETWORKS: readonly ["bitcoin", "signet", "mutinynet", "regtest"];
|
|
341
|
+
/**
|
|
342
|
+
* Whether a market index can be fetched for `network`. `testnet` ids are valid but have
|
|
343
|
+
* no published index; the quote path decides which error that becomes.
|
|
344
|
+
*/
|
|
345
|
+
declare const isIndexedNetwork: (network: NetworkRef) => network is Network$1;
|
|
346
|
+
/**
|
|
347
|
+
* Caller input to a public id: an id passes through validated, a ticker is resolved
|
|
348
|
+
* case-insensitively against the table on the wallet's network.
|
|
349
|
+
*
|
|
350
|
+
* @throws {@link AssetIdError} `ambiguous_alias` when a ticker matches more than one
|
|
351
|
+
* asset: guessing between two `USDT`s sends the money to the wrong one.
|
|
352
|
+
*/
|
|
353
|
+
declare const canonicalAssetId: (input: string, table: AssetAliasTable) => AssetId;
|
|
354
|
+
|
|
355
|
+
/**
|
|
356
|
+
* Discovery, separating the three states `discoverMarkets` collapses into one array:
|
|
357
|
+
*
|
|
358
|
+
* - **No data at all** (no registry, unindexed network, or unreachable with nothing
|
|
359
|
+
* cached) is {@link DiscoverySnapshotUnavailable}.
|
|
360
|
+
* - **A stale cache** resolves and prices, but is `live: false` and cannot supply the
|
|
361
|
+
* key an addressed RFQ's responder is checked against.
|
|
362
|
+
* - **Reachable and empty** is an ordinary snapshot; `quote()` turns an empty eligible
|
|
363
|
+
* set into `UnsupportedRoute`.
|
|
364
|
+
*
|
|
365
|
+
* Wraps `discover()` directly for its per-source outcomes; the cache entry and key are
|
|
366
|
+
* shared with v1's `discoverMarkets`.
|
|
367
|
+
*
|
|
368
|
+
* The cache is a trust boundary: v1's `isMarketShaped` trusts `discovery_pubkey` and
|
|
369
|
+
* `transports`, exactly what an addressed RFQ targets, so cached cards are revalidated
|
|
370
|
+
* here in full and never pin a responder.
|
|
371
|
+
*/
|
|
372
|
+
|
|
373
|
+
/**
|
|
374
|
+
* The default solver registry index per network (the registry's CI publishes one,
|
|
375
|
+
* possibly empty, for each). An explicit `registryUrl` overrides it; `null` opts out.
|
|
376
|
+
*/
|
|
377
|
+
declare const REGISTRY_URL: Record<Network$1, string>;
|
|
378
|
+
/** Where the client's market data comes from. Every field is optional: absent
|
|
379
|
+
* registry config falls back to {@link REGISTRY_URL} for the wallet's network,
|
|
380
|
+
* and an injected snapshot needs no registry at all. */
|
|
381
|
+
interface DiscoveryConfig {
|
|
382
|
+
/**
|
|
383
|
+
* The network's solver registry index URL. Absent means {@link REGISTRY_URL}; `null`
|
|
384
|
+
* opts out, which without an injected snapshot is the unavailable case, not an empty
|
|
385
|
+
* market set.
|
|
386
|
+
*/
|
|
387
|
+
readonly registryUrl?: string | null;
|
|
388
|
+
/** Locally pinned solver cards, merged with the registry's. */
|
|
389
|
+
readonly localCards?: readonly LocalCardInput[];
|
|
390
|
+
/** Reads listed solvers' own cards. Absent means Nostr (optional `nostr-tools` peer); `null` none. */
|
|
391
|
+
readonly transportCards?: TransportCardFetcher | null;
|
|
392
|
+
/**
|
|
393
|
+
* Markets to resolve against without touching the network. Trusted like config: an
|
|
394
|
+
* injected snapshot can pin an RFQ responder, a cached one cannot.
|
|
395
|
+
*/
|
|
396
|
+
readonly snapshot?: readonly DiscoveredMarket[];
|
|
397
|
+
/** Overrides the network the wallet reports. For tests and multi-network hosts. */
|
|
398
|
+
readonly network?: Network$1;
|
|
399
|
+
readonly fetchImpl?: typeof fetch;
|
|
400
|
+
/** Receives discovery warnings (stale index, skipped cards, …). */
|
|
401
|
+
readonly logger?: (...args: unknown[]) => void;
|
|
402
|
+
}
|
|
403
|
+
/** A market set, and where it came from. */
|
|
404
|
+
interface DiscoverySnapshot {
|
|
405
|
+
readonly markets: readonly DiscoveredMarket[];
|
|
406
|
+
readonly ref: SnapshotRef;
|
|
407
|
+
}
|
|
408
|
+
interface DiscoveryIndex {
|
|
409
|
+
/**
|
|
410
|
+
* The snapshot in hand, without touching the network — an injected one, one
|
|
411
|
+
* this client already loaded, the repository's cache, or the pinned cards alone.
|
|
412
|
+
*
|
|
413
|
+
* @throws {DiscoverySnapshotUnavailable} when there is none.
|
|
414
|
+
*/
|
|
415
|
+
peek(): Promise<DiscoverySnapshot>;
|
|
416
|
+
/**
|
|
417
|
+
* A snapshot, fetching when there is none in hand or when asked to refresh.
|
|
418
|
+
*
|
|
419
|
+
* @throws {DiscoverySnapshotUnavailable} when the fetch leaves it with
|
|
420
|
+
* nothing either.
|
|
421
|
+
*/
|
|
422
|
+
load(opts?: {
|
|
423
|
+
refresh?: boolean;
|
|
424
|
+
}): Promise<DiscoverySnapshot>;
|
|
425
|
+
}
|
|
426
|
+
/**
|
|
427
|
+
* Whether a card read back out of the cache is one this client may act on. Stricter
|
|
428
|
+
* than v1's `isMarketShaped` because this path also addresses a solver over the
|
|
429
|
+
* rendezvous the card names, so every field the client depends on is re-checked.
|
|
430
|
+
*/
|
|
431
|
+
declare const isUsableCard: (value: unknown) => value is DiscoveredMarket;
|
|
432
|
+
interface DiscoveryIndexInput {
|
|
433
|
+
/** The network the wallet reported. */
|
|
434
|
+
readonly network: NetworkName;
|
|
435
|
+
readonly config?: DiscoveryConfig;
|
|
436
|
+
/** Backs the shared markets cache. Without one, every load hits the registry. */
|
|
437
|
+
readonly repository?: AssetSwapRepository;
|
|
438
|
+
}
|
|
439
|
+
/**
|
|
440
|
+
* One client's view of the market index.
|
|
441
|
+
*
|
|
442
|
+
* Holds one snapshot until it ages out or a refresh is asked for, so a `resolve()` and
|
|
443
|
+
* the `quote()` after it agree on what the market was.
|
|
444
|
+
*/
|
|
445
|
+
declare const discoveryIndex: (input: DiscoveryIndexInput) => DiscoveryIndex;
|
|
446
|
+
|
|
447
|
+
/**
|
|
448
|
+
* Market resolution: `(give.asset, take.asset, corridors)` to the card that prices the swap, and
|
|
449
|
+
* the provenance that card leaves on the quote.
|
|
450
|
+
*
|
|
451
|
+
* Not `findMarket`: that returns the single best market of one orientation, while
|
|
452
|
+
* `policy.selectMarket` is defined over every eligible card. Both orientations are tried because
|
|
453
|
+
* a registry may publish either leg as base.
|
|
454
|
+
*/
|
|
455
|
+
|
|
456
|
+
/** One card that can price this route, with what the route needs read off it. */
|
|
457
|
+
interface MarketCandidate {
|
|
458
|
+
readonly card: DiscoveredMarket;
|
|
459
|
+
/** Which side of the card the trader gives; the other side is received. */
|
|
460
|
+
readonly give: Side;
|
|
461
|
+
/** Which backend the card selects. The card decides, never the client. */
|
|
462
|
+
readonly backend: MarketBackend;
|
|
463
|
+
/** The canonical market key — see {@link marketKeyOf}. */
|
|
464
|
+
readonly key: string;
|
|
465
|
+
}
|
|
466
|
+
/**
|
|
467
|
+
* The market's canonical key, `<corridor>:<id>/<corridor>:<id>`, under rfq-protocol.md §2's leg
|
|
468
|
+
* order: when exactly one leg is arkade it comes first; otherwise the legs sort lexicographically.
|
|
469
|
+
*
|
|
470
|
+
* Derived here rather than from `marketPairKey` (the card's own order): for a card published
|
|
471
|
+
* outside the registry's reducer they disagree, and both negotiation sides subscribe by this key,
|
|
472
|
+
* so a mismatch is not an error either side sees — it is a request nobody answers.
|
|
473
|
+
*/
|
|
474
|
+
declare const marketKeyOf: (card: DiscoveredMarket) => string;
|
|
475
|
+
/**
|
|
476
|
+
* Whether a corridor card can actually be addressed: it needs its discovery key and relays.
|
|
477
|
+
* Dropping it here keeps "no market serves this pair" one answer instead of a transport error
|
|
478
|
+
* that reads like an outage.
|
|
479
|
+
*/
|
|
480
|
+
declare const isAddressable: (card: DiscoveredMarket) => boolean;
|
|
481
|
+
/**
|
|
482
|
+
* Which backend a card selects — the card decides it, never the client.
|
|
483
|
+
*
|
|
484
|
+
* A card with a leg off arkade has no other option: that route's terms exist
|
|
485
|
+
* only once a solver has quoted them. A card with both legs on arkade is
|
|
486
|
+
* negotiated too **when it names a rendezvous**, which is the one thing that
|
|
487
|
+
* separates the two asset cards in the wild: the solver that publishes relays
|
|
488
|
+
* and a discovery key is asking to be asked, and its quote is the binding
|
|
489
|
+
* artifact — signed, size-aware, and the thing whose `offer_address` the
|
|
490
|
+
* client's own derivation is checked against. A card that names no rendezvous
|
|
491
|
+
* advertises a price and nothing to negotiate with, so its own feed is the only
|
|
492
|
+
* thing that can price it.
|
|
493
|
+
*
|
|
494
|
+
* Not a second execution model and not a client switch: one request-for-quote
|
|
495
|
+
* shape over every route, with the card saying whether the answer comes back
|
|
496
|
+
* over the wire or is computed from the formula the card advertises.
|
|
497
|
+
*/
|
|
498
|
+
declare const marketBackendOf: (card: DiscoveredMarket) => MarketBackend;
|
|
499
|
+
/**
|
|
500
|
+
* The cards on a snapshot this client may act on at all: the policy's registry allowlist, then
|
|
501
|
+
* addressability. Shared with `markets()`; eligibility is not, so `markets()` can list a card
|
|
502
|
+
* `quote()` refuses.
|
|
503
|
+
*/
|
|
504
|
+
declare const usableMarkets: (snapshot: DiscoverySnapshot, policy?: SwapPolicy) => DiscoveredMarket[];
|
|
505
|
+
/**
|
|
506
|
+
* Every card on the snapshot that serves this leg pair, best-ranked first, after policy.
|
|
507
|
+
*
|
|
508
|
+
* The allowlist matches `source`, not `discovery_pubkey`: the latter is carried unvalidated on a
|
|
509
|
+
* cached card, so filtering trust on it would be a check with no effect.
|
|
510
|
+
*
|
|
511
|
+
* @param takeAmount The pin on the TAKE leg only (the side `wantSide` names), which makes a card's
|
|
512
|
+
* `min/max` bounds apply so out-of-range amounts drop the rail at `available()`. Omitting it
|
|
513
|
+
* skips the bounds. A GIVE-side pin is not converted (no price here), so a give-side amount past
|
|
514
|
+
* a card's ceiling still answers eligible and is refused by the solver — a known sharp edge.
|
|
515
|
+
*/
|
|
516
|
+
declare const eligibleMarkets: (snapshot: DiscoverySnapshot, legs: {
|
|
517
|
+
give: DiscoveryLeg;
|
|
518
|
+
take: DiscoveryLeg;
|
|
519
|
+
}, policy?: SwapPolicy, takeAmount?: bigint) => MarketCandidate[];
|
|
520
|
+
/**
|
|
521
|
+
* The card that prices this swap: the best-ranked candidate, or the one the application's policy
|
|
522
|
+
* chose instead. A veto (`undefined` from `selectMarket`) is not an error; it is the same "no
|
|
523
|
+
* market serves this route" as an empty set.
|
|
524
|
+
*/
|
|
525
|
+
declare const chooseMarket: (candidates: readonly MarketCandidate[], policy?: SwapPolicy) => MarketCandidate | undefined;
|
|
526
|
+
/** The provenance a candidate leaves on every quote it prices. */
|
|
527
|
+
declare const marketRefOf: (candidate: MarketCandidate, snapshot: SnapshotRef) => CardMarketRef;
|
|
528
|
+
/** A card's own provenance — the same fields {@link marketRefOf} writes, read
|
|
529
|
+
* off the card rather than off a routed candidate. */
|
|
530
|
+
declare const cardMarketOf: (card: DiscoveredMarket, snapshot: SnapshotRef, key: string, backend: MarketBackend) => CardMarketRef;
|
|
531
|
+
/** Narrow a `MarketRef` to the card arm — the only one `quote()` mints. */
|
|
532
|
+
declare const isCardMarket: (market: MarketRef) => market is CardMarketRef;
|
|
533
|
+
/** One side of a {@link Market}. */
|
|
534
|
+
interface MarketLeg {
|
|
535
|
+
/** Absent when the leg has no public id, e.g. an `eip155:` leg. */
|
|
536
|
+
readonly asset?: AssetId;
|
|
537
|
+
/** For `Amount.format`. */
|
|
538
|
+
readonly decimals: number;
|
|
539
|
+
/**
|
|
540
|
+
* The card's announced bounds, in atomic units. Indicative: the solver can still refuse.
|
|
541
|
+
* `null`: the solver will not pay this leg out; a one-way card still routes it as the give leg.
|
|
542
|
+
* Only an amount pinned with `amountOn: "take"` is checked: a give-pinned amount still resolves,
|
|
543
|
+
* and a feed card still quotes it, even if the resulting take is out of range.
|
|
544
|
+
*/
|
|
545
|
+
readonly limits: {
|
|
546
|
+
readonly min: bigint;
|
|
547
|
+
readonly max: bigint;
|
|
548
|
+
} | null;
|
|
549
|
+
}
|
|
550
|
+
/**
|
|
551
|
+
* A market as the v2 client publishes it: the {@link CardMarketRef} a quote would cite, plus its
|
|
552
|
+
* legs. Find a leg by `asset`, not position: they are in card order. The legs stay off
|
|
553
|
+
* `CardMarketRef` because that is written into durable records, which forbid `bigint`.
|
|
554
|
+
*/
|
|
555
|
+
interface Market extends CardMarketRef {
|
|
556
|
+
readonly legs: readonly [MarketLeg, MarketLeg];
|
|
557
|
+
}
|
|
558
|
+
/** A card as {@link Market}. `network` is the wallet's, as routing uses, so a legacy leg's id
|
|
559
|
+
* matches `resolve()` under a `DiscoveryConfig.network` override. */
|
|
560
|
+
declare const marketOf: (card: DiscoveredMarket, snapshot: SnapshotRef, network: NetworkRef) => Market;
|
|
561
|
+
|
|
562
|
+
/**
|
|
563
|
+
* The three product-facing verbs: `pay`, `receive` and `exchange` each compile a
|
|
564
|
+
* {@link QuoteInput}, `quote`, enforce a fee ceiling, and `accept`.
|
|
565
|
+
*
|
|
566
|
+
* `receive` returns only after `accept()` has persisted, so a caller cannot show a payer
|
|
567
|
+
* an invoice whose claim secret exists only in memory.
|
|
568
|
+
*/
|
|
569
|
+
|
|
570
|
+
/**
|
|
571
|
+
* A fee ceiling: an amount, and the asset it is denominated in.
|
|
572
|
+
*
|
|
573
|
+
* The fee is on the give leg for corridor routes and the take leg for asset swaps, so a
|
|
574
|
+
* bare `bigint` names no asset. A ceiling in another asset than the fee's is refused,
|
|
575
|
+
* never converted: the SDK holds no rate. Same shape as {@link SwapPolicy.maxFee}.
|
|
576
|
+
*/
|
|
577
|
+
interface FeeCeiling {
|
|
578
|
+
readonly amount: bigint;
|
|
579
|
+
readonly asset: AssetId;
|
|
580
|
+
}
|
|
581
|
+
/** What `pay` takes beside the destination. */
|
|
582
|
+
interface PayOptions {
|
|
583
|
+
/** Atomic units delivered to the recipient. Omitted when the destination pins it;
|
|
584
|
+
* passing one beside an amount-bearing invoice is `AmountMismatch`. */
|
|
585
|
+
readonly amount?: bigint;
|
|
586
|
+
readonly maxFee?: FeeCeiling;
|
|
587
|
+
}
|
|
588
|
+
/**
|
|
589
|
+
* What `receive` takes. `via` names the corridor because a receive has no instrument to
|
|
590
|
+
* parse: the instrument is the artifact the solver mints in the quote.
|
|
591
|
+
*/
|
|
592
|
+
interface ReceiveOptions {
|
|
593
|
+
/** Atomic units the trader receives. */
|
|
594
|
+
readonly amount: bigint;
|
|
595
|
+
readonly via: CorridorId;
|
|
596
|
+
/** §9.5, reserved: the asset arriving, where a corridor carries more than one. */
|
|
597
|
+
readonly asset?: AssetRef;
|
|
598
|
+
readonly maxFee?: FeeCeiling;
|
|
599
|
+
}
|
|
600
|
+
/** What `exchange` takes: {@link QuoteInput} minus `to` and `via`, plus the ceiling. */
|
|
601
|
+
interface ExchangeOptions {
|
|
602
|
+
readonly give?: AssetRef;
|
|
603
|
+
readonly take?: AssetRef;
|
|
604
|
+
readonly amount?: bigint;
|
|
605
|
+
readonly amountOn?: AmountOn;
|
|
606
|
+
readonly maxFee?: FeeCeiling;
|
|
607
|
+
}
|
|
608
|
+
/**
|
|
609
|
+
* The artifact a receive over corridor `C` comes back with: an invoice on `lightning`,
|
|
610
|
+
* a deposit otherwise. The conditional lets `receive({ via: "lightning" }).artifact.bolt11`
|
|
611
|
+
* compile without a manual `kind` check; distributed over `C` like {@link DepositArtifact}.
|
|
612
|
+
*/
|
|
613
|
+
type ReceiveArtifact<C extends CorridorId = CorridorId> = C extends CorridorId ? C extends "lightning" ? {
|
|
614
|
+
kind: "invoice";
|
|
615
|
+
bolt11: string;
|
|
616
|
+
} : DepositArtifact<C> : never;
|
|
617
|
+
/** What `receive` answers with: a {@link Swap} whose (otherwise optional) artifact is
|
|
618
|
+
* guaranteed. */
|
|
619
|
+
type ReceiveRequest<C extends CorridorId = CorridorId> = Swap & {
|
|
620
|
+
readonly artifact: ReceiveArtifact<C>;
|
|
621
|
+
};
|
|
622
|
+
/**
|
|
623
|
+
* What `pay` answers with. A bolt11 or `bc1…` crosses a corridor and yields a
|
|
624
|
+
* {@link Swap}; a plain Arkade address is a plain payment and yields only a txid.
|
|
625
|
+
*/
|
|
626
|
+
type PayResult = {
|
|
627
|
+
readonly kind: "swap";
|
|
628
|
+
readonly swap: Swap;
|
|
629
|
+
} | {
|
|
630
|
+
readonly kind: "payment";
|
|
631
|
+
readonly txid: string;
|
|
632
|
+
};
|
|
633
|
+
/** What a verb needs from the client it hangs off. */
|
|
634
|
+
interface VerbDeps {
|
|
635
|
+
readonly wallet: IWallet;
|
|
636
|
+
quote(input: QuoteInput): Promise<Quote>;
|
|
637
|
+
accept(quote: Quote): Promise<Swap>;
|
|
638
|
+
/** {@link SwapPolicy.maxFee}, when the client was configured with one. */
|
|
639
|
+
readonly policyMaxFee?: FeeCeiling;
|
|
640
|
+
}
|
|
641
|
+
/**
|
|
642
|
+
* Enforce the effective ceiling: the **minimum** of the call's and the policy's, so
|
|
643
|
+
* neither can raise the other. Both absent means no ceiling.
|
|
644
|
+
*
|
|
645
|
+
* @throws {Error} when a ceiling is in another asset than the fee (caller input, not a
|
|
646
|
+
* swap condition).
|
|
647
|
+
* @throws {MaxFeeExceeded} when `quote.fee` is over the effective ceiling —
|
|
648
|
+
* between `quote` and `accept`, so nothing was funded.
|
|
649
|
+
*/
|
|
650
|
+
declare const enforceFeeCeiling: (quote: Quote, call: FeeCeiling | undefined, policy: FeeCeiling | undefined) => void;
|
|
651
|
+
/**
|
|
652
|
+
* Pay a destination: a bolt11, a `bc1…`, or a plain Arkade address.
|
|
653
|
+
*
|
|
654
|
+
* The Arkade arm uses core's own parse (so it classifies exactly as the `ark` rail does)
|
|
655
|
+
* and settles through `wallet.send`: fee 0, nothing quoted or persisted.
|
|
656
|
+
*/
|
|
657
|
+
declare const pay: (deps: VerbDeps, destination: string, options?: PayOptions) => Promise<PayResult>;
|
|
658
|
+
/**
|
|
659
|
+
* Ask for an incoming payment over `via`, and get back the artifact to show.
|
|
660
|
+
*
|
|
661
|
+
* @throws {Error} if the accepted swap carries no artifact.
|
|
662
|
+
*/
|
|
663
|
+
declare const receive: <C extends CorridorId = CorridorId>(deps: VerbDeps, options: ReceiveOptions & {
|
|
664
|
+
readonly via: C;
|
|
665
|
+
}) => Promise<ReceiveRequest<C>>;
|
|
666
|
+
/** Swap one Arkade asset for another. */
|
|
667
|
+
declare const exchange: (deps: VerbDeps, options: ExchangeOptions) => Promise<Swap>;
|
|
668
|
+
|
|
669
|
+
/**
|
|
670
|
+
* Application policy: the vetoes and floors a client applies before it discloses anything.
|
|
671
|
+
*
|
|
672
|
+
* Every active member runs BEFORE the RFQ round trip that discloses an invoice or an amount; a
|
|
673
|
+
* policy that could only reject a quote after it arrived would be a preference.
|
|
674
|
+
*/
|
|
675
|
+
|
|
676
|
+
/**
|
|
677
|
+
* A published-RFQ auction's parameters (§10, Q9).
|
|
678
|
+
*
|
|
679
|
+
* Reserved and inert: nothing reads it. Shaped after ts-sdk #777's draft so the name isn't taken
|
|
680
|
+
* by something narrower meanwhile.
|
|
681
|
+
*/
|
|
682
|
+
interface RfqAuctionPolicy {
|
|
683
|
+
/** How long to hold the bid window open, in ms. */
|
|
684
|
+
readonly windowMs: number;
|
|
685
|
+
/** Relays to publish the open request on. Unioned across the pair's cards. */
|
|
686
|
+
readonly relays?: readonly string[];
|
|
687
|
+
/** §4.6's SHOULD: a fresh transport key per open, so bids are unlinkable. */
|
|
688
|
+
readonly freshTransportKey?: boolean;
|
|
689
|
+
}
|
|
690
|
+
/**
|
|
691
|
+
* How much the client drives on its own, so a consumer can inspect its swaps without being made to
|
|
692
|
+
* move money.
|
|
693
|
+
*/
|
|
694
|
+
type DriveMode =
|
|
695
|
+
/**
|
|
696
|
+
* Default. Construction's restore-read arms the drive when it finds live
|
|
697
|
+
* work, and the first `accept()` arms it when it does not.
|
|
698
|
+
*/
|
|
699
|
+
"auto"
|
|
700
|
+
/** Restores, then waits: no timer and no stream until `start()`. */
|
|
701
|
+
| "manual"
|
|
702
|
+
/**
|
|
703
|
+
* Restores and reports, and never actuates: no pass runs, so no claim, refund or recovery
|
|
704
|
+
* round, and nothing new is discovered.
|
|
705
|
+
*/
|
|
706
|
+
| "readonly";
|
|
707
|
+
/** Default {@link SwapPolicy.maxRefundWindowSeconds}: 30 days. */
|
|
708
|
+
declare const DEFAULT_MAX_REFUND_WINDOW_SECONDS: number;
|
|
709
|
+
interface SwapPolicy {
|
|
710
|
+
/** How much the client drives on its own. Default `"auto"`. */
|
|
711
|
+
readonly drive?: DriveMode;
|
|
712
|
+
/**
|
|
713
|
+
* The most a swap may cost, as a standing instruction.
|
|
714
|
+
*
|
|
715
|
+
* The verbs take the **minimum** of this and their own `maxFee`, so a call can only tighten it.
|
|
716
|
+
* Enforced between `quote` and `accept`, before funding. Denominated because the fee sits on
|
|
717
|
+
* the give leg on corridor routes and the take leg on asset swaps; a ceiling in a different
|
|
718
|
+
* asset than the quoted fee is refused, not converted.
|
|
719
|
+
*/
|
|
720
|
+
readonly maxFee?: FeeCeiling;
|
|
721
|
+
/**
|
|
722
|
+
* The last word on which market prices a swap.
|
|
723
|
+
*
|
|
724
|
+
* Called with every eligible candidate, best-ranked first; `undefined` vetoes them all
|
|
725
|
+
* (surfacing as `UnsupportedRoute`). The answer must be one of the candidates: a card from
|
|
726
|
+
* elsewhere has not passed the pair, corridor and addressability checks.
|
|
727
|
+
*/
|
|
728
|
+
readonly selectMarket?: (candidates: readonly MarketCandidate[]) => MarketCandidate | undefined;
|
|
729
|
+
/**
|
|
730
|
+
* The registries whose cards may price a swap, matched exactly against
|
|
731
|
+
* `DiscoveredMarket.source`.
|
|
732
|
+
*
|
|
733
|
+
* On `source`, never `discovery_pubkey`: the cache does not revalidate that field on read, so
|
|
734
|
+
* filtering on it would reopen the hole the allowlist closes. Exact URLs, not hostnames; a
|
|
735
|
+
* locally pinned card carries its discovery label (a path). Absent means every source.
|
|
736
|
+
*/
|
|
737
|
+
readonly allowedRegistries?: readonly string[];
|
|
738
|
+
/**
|
|
739
|
+
* The least validity a quote may arrive with, in seconds. Below it `quote()` throws
|
|
740
|
+
* `QuoteExpired`, rather than handing back terms that would fail at `accept()`.
|
|
741
|
+
*/
|
|
742
|
+
readonly quoteTtlFloorSeconds?: number;
|
|
743
|
+
/**
|
|
744
|
+
* The longest a send's funds may stay locked before the trader can refund, in seconds.
|
|
745
|
+
* Caps `refund_locktime` and the solo-refund delay; above it `quote()` throws
|
|
746
|
+
* `QuoteVerificationFailed("refund_window")`. Default {@link DEFAULT_MAX_REFUND_WINDOW_SECONDS}.
|
|
747
|
+
*/
|
|
748
|
+
readonly maxRefundWindowSeconds?: number;
|
|
749
|
+
/**
|
|
750
|
+
* §10, reserved and inert: the published-RFQ auction's parameters.
|
|
751
|
+
*/
|
|
752
|
+
readonly rfq?: RfqAuctionPolicy;
|
|
753
|
+
/**
|
|
754
|
+
* §10, reserved and inert: which bid to close a published auction with.
|
|
755
|
+
*/
|
|
756
|
+
readonly selectBid?: (bids: readonly RankedBid[]) => RankedBid | undefined;
|
|
757
|
+
}
|
|
758
|
+
|
|
759
|
+
/**
|
|
760
|
+
* The drive: what makes the v2 client self-driving, and the one place the two
|
|
761
|
+
* families' state becomes one {@link Outcome}.
|
|
762
|
+
*
|
|
763
|
+
* Two drivers behind one lifecycle: `RfqSwapManager` (corridor swaps) and `watchOfferSwaps`
|
|
764
|
+
* (offers). The manager survives `stop()`; the watcher is a one-shot unsubscribe rebuilt on the
|
|
765
|
+
* next start.
|
|
766
|
+
*
|
|
767
|
+
* **The poll loop is the correctness mechanism.** Contract events only make a pass run early, and
|
|
768
|
+
* the pass re-reads the lockup, so a missed, duplicated or forged event costs only latency:
|
|
769
|
+
* NO OUTCOME IS EVER WRITTEN FROM AN EVENT PAYLOAD.
|
|
770
|
+
*
|
|
771
|
+
* **No backoff, deliberately**: the poll interval is the retry cadence and
|
|
772
|
+
* `REFUND_MTP_LAG_SECONDS` the deadline, so a backoff could only push a money retry past it.
|
|
773
|
+
*
|
|
774
|
+
* Nothing here trusts the solver's word: there is no `RfqTransport`.
|
|
775
|
+
*/
|
|
776
|
+
|
|
777
|
+
/** Why the drive refused. */
|
|
778
|
+
type DriveRefusal =
|
|
779
|
+
/** `drive: "readonly"` actuates nothing, and this asked it to. */
|
|
780
|
+
"readonly"
|
|
781
|
+
/** No record with this id, here or in the repository. */
|
|
782
|
+
| "unknown-swap"
|
|
783
|
+
/** The lockup's `refundLocktime` has not matured. `recoverVtxos` settles EVERY recoverable
|
|
784
|
+
* output in one batch, so an early attempt could fail unrelated outputs too. */
|
|
785
|
+
| "refund-window-open"
|
|
786
|
+
/** Nothing at this swap has been swept, so there is nothing to recover
|
|
787
|
+
* (includes the `needs_counterparty` sources of `needs_recovery`). */
|
|
788
|
+
| "nothing-swept"
|
|
789
|
+
/** This wallet exposes no VTXO manager, so no recovery round can be run. */
|
|
790
|
+
| "no-recovery-support";
|
|
791
|
+
/**
|
|
792
|
+
* The drive declined, with the reason as a value a caller can branch on. Not a §7 taxonomy
|
|
793
|
+
* member, hence the `Error` suffix.
|
|
794
|
+
*/
|
|
795
|
+
declare class SwapDriveRefusedError extends Error {
|
|
796
|
+
readonly reason: DriveRefusal;
|
|
797
|
+
readonly swapId?: QuoteId | undefined;
|
|
798
|
+
readonly name = "SwapDriveRefusedError";
|
|
799
|
+
constructor(reason: DriveRefusal, detail: string, swapId?: QuoteId | undefined);
|
|
800
|
+
}
|
|
801
|
+
/** What {@link SwapDrive.recover} did. */
|
|
802
|
+
interface RecoveryResult {
|
|
803
|
+
/**
|
|
804
|
+
* Whether THIS swap's outpoints were included in the round, per a re-read afterwards. A
|
|
805
|
+
* settlement txid is not success: `recoverVtxos` takes the whole wallet and caps the round,
|
|
806
|
+
* deferring overflow to the next cycle. An offer re-read the indexer has not caught up on
|
|
807
|
+
* reports `false`; the next client start re-reads it.
|
|
808
|
+
*/
|
|
809
|
+
readonly recovered: boolean;
|
|
810
|
+
/** The settlement the round produced, when one ran. */
|
|
811
|
+
readonly txid?: string;
|
|
812
|
+
/** The swap, after the immediate pass that followed. */
|
|
813
|
+
readonly swap: Swap;
|
|
814
|
+
}
|
|
815
|
+
interface SwapDriveConfig {
|
|
816
|
+
readonly wallet: IWallet;
|
|
817
|
+
readonly operator: SwapOperator;
|
|
818
|
+
/** No repository is legal and shipped: `ready` resolves, nothing arms, and
|
|
819
|
+
* `accept()` keeps its own refusal. */
|
|
820
|
+
readonly repository?: AssetSwapRepository;
|
|
821
|
+
/**
|
|
822
|
+
* The client's corridors, for the L1 chain source and claim/refund callbacks a drive pass
|
|
823
|
+
* needs. Lazy, so a client with `null` onchain deps that never drives an onchain swap never
|
|
824
|
+
* resolves them.
|
|
825
|
+
*/
|
|
826
|
+
readonly corridors: () => Promise<CorridorSet>;
|
|
827
|
+
/** The operator's network, for a rebuilt offer record's asset ids. Lazy like `corridors`. */
|
|
828
|
+
readonly network: () => Promise<NetworkRef>;
|
|
829
|
+
readonly mode?: DriveMode;
|
|
830
|
+
/**
|
|
831
|
+
* How often the fallback poll pass runs. Default 5000 ms (as
|
|
832
|
+
* `RfqSwapManagerConfig.pollIntervalMs`); also the refund push's retry cadence.
|
|
833
|
+
*/
|
|
834
|
+
readonly pollIntervalMs?: number;
|
|
835
|
+
/** Unix seconds. Injected for tests. */
|
|
836
|
+
readonly now?: () => number;
|
|
837
|
+
/** The Arkade observation seam; normally the wallet's own reader. */
|
|
838
|
+
readonly indexer: LockupSpendIndexer;
|
|
839
|
+
/** Defaults to `wallet.getContractManager()`, resolved on first arm. */
|
|
840
|
+
readonly contracts?: SwapContractRegistry;
|
|
841
|
+
}
|
|
842
|
+
interface SwapDrive {
|
|
843
|
+
/**
|
|
844
|
+
* The restore-read, and — when it armed — the first pass after it. Lazy: the first await
|
|
845
|
+
* drives it. Rejects only when the repository itself is unreadable; a corrupt record is
|
|
846
|
+
* filtered and every per-swap problem is an outcome.
|
|
847
|
+
*/
|
|
848
|
+
readonly ready: Promise<void>;
|
|
849
|
+
start(): Promise<void>;
|
|
850
|
+
stop(): Promise<void>;
|
|
851
|
+
dispose(): Promise<void>;
|
|
852
|
+
onUpdate(fn: (update: SwapUpdate) => void): Unsubscribe;
|
|
853
|
+
/**
|
|
854
|
+
* Take a freshly persisted record into the drive and answer with its public form.
|
|
855
|
+
* Synchronous: the registration it schedules runs behind `accept()`'s return.
|
|
856
|
+
*/
|
|
857
|
+
adopt(record: SwapRecord): Swap;
|
|
858
|
+
/** The public form of a record this drive holds. */
|
|
859
|
+
swap(id: QuoteId): Swap | undefined;
|
|
860
|
+
/** The outcome a record would report with no live state behind it. */
|
|
861
|
+
outcomeOf(record: SwapRecord): Outcome;
|
|
862
|
+
/**
|
|
863
|
+
* Take a record written OUTSIDE the drive's own loops (today, cancel) into the registry and
|
|
864
|
+
* emit through `onUpdate`; the `(swapId, outcome)` key absorbs a later pass over it.
|
|
865
|
+
*/
|
|
866
|
+
ingest(record: SwapRecord): void;
|
|
867
|
+
recover(id: QuoteId): Promise<RecoveryResult>;
|
|
868
|
+
/** Everything this drive has in flight — registrations and money pushes.
|
|
869
|
+
* Exposed so a test can be deterministic and so dispose can drain. */
|
|
870
|
+
idle(): Promise<void>;
|
|
871
|
+
}
|
|
872
|
+
/**
|
|
873
|
+
* Whether a stored blob is a record this drive can read at all. A corrupt row is filtered rather
|
|
874
|
+
* than fatal, so it cannot stop every other swap; the checks cover what the drive dereferences.
|
|
875
|
+
*/
|
|
876
|
+
declare const readableRecord: (record: SwapRecord) => boolean;
|
|
877
|
+
declare const createSwapDrive: (config: SwapDriveConfig) => SwapDrive;
|
|
878
|
+
|
|
879
|
+
/**
|
|
880
|
+
* The feed-priced backend: an arkade-to-arkade asset swap, priced from the card's own feed with no
|
|
881
|
+
* round trip. The market picks the backend (an asset card that names no rendezvous → feed, otherwise RFQ).
|
|
882
|
+
*
|
|
883
|
+
* **The margin.** `QUOTE_OPTIONS` (`safetyBps: 0`), not `quoteOffer`'s default 50: price drift
|
|
884
|
+
* between quote and fill is the solver's risk, not the trader's to prepay, and a cushion would
|
|
885
|
+
* inflate the fee that `maxFee` ceilings are compared against.
|
|
886
|
+
*
|
|
887
|
+
* **The expiry.** `expiresAt` is required but `OfferPlan` carries none, so it is minted from the
|
|
888
|
+
* feed cache: the time the value was actually read upstream, plus the TTL — the quote expires when
|
|
889
|
+
* its price does.
|
|
890
|
+
*/
|
|
891
|
+
|
|
892
|
+
/** How long a feed value is reused, and so how long a quote priced from it lives — one number, so a
|
|
893
|
+
* quote cannot outlive the value it quoted. */
|
|
894
|
+
declare const FEED_TTL_MS = 30000;
|
|
895
|
+
/** A fetch that caches feed values, and remembers when each was really read. */
|
|
896
|
+
interface FeedFetch {
|
|
897
|
+
readonly fetch: typeof fetch;
|
|
898
|
+
/** Unix ms the value behind `url` was last read from upstream. */
|
|
899
|
+
fetchedAt(url: string): number | undefined;
|
|
900
|
+
}
|
|
901
|
+
/**
|
|
902
|
+
* The client's feed fetcher. The probe sits INSIDE the cache, so `fetchedAt` is the age of the value
|
|
903
|
+
* served, not the time it was served; the other way round would restamp every hit as fresh.
|
|
904
|
+
*/
|
|
905
|
+
declare const feedFetch: (base?: typeof fetch) => FeedFetch;
|
|
906
|
+
/** What `accept()` needs back from a feed-priced quote. */
|
|
907
|
+
interface OfferPreparation {
|
|
908
|
+
readonly backend: "feed";
|
|
909
|
+
readonly card: DiscoveredMarket;
|
|
910
|
+
/** The plan the offer covenant is built from: both amounts and both assets. */
|
|
911
|
+
readonly plan: OfferPlan;
|
|
912
|
+
readonly give: Side;
|
|
913
|
+
}
|
|
914
|
+
interface FeedQuoteInput {
|
|
915
|
+
readonly quoteId: QuoteId;
|
|
916
|
+
readonly candidate: MarketCandidate;
|
|
917
|
+
readonly market: CardMarketRef;
|
|
918
|
+
readonly legs: {
|
|
919
|
+
readonly give: DiscoveryLeg;
|
|
920
|
+
readonly take: DiscoveryLeg;
|
|
921
|
+
};
|
|
922
|
+
readonly endpoints: {
|
|
923
|
+
readonly give: ResolvedEndpoint;
|
|
924
|
+
readonly take: ResolvedEndpoint;
|
|
925
|
+
};
|
|
926
|
+
readonly amount?: PinnedAmount;
|
|
927
|
+
readonly feed: FeedFetch;
|
|
928
|
+
readonly policy?: SwapPolicy;
|
|
929
|
+
/** Unix seconds. */
|
|
930
|
+
readonly now: number;
|
|
931
|
+
}
|
|
932
|
+
declare const quoteFromFeed: (input: FeedQuoteInput) => Promise<{
|
|
933
|
+
quote: Quote;
|
|
934
|
+
preparation: OfferPreparation;
|
|
935
|
+
}>;
|
|
936
|
+
/**
|
|
937
|
+
* The spread in take-leg units, where it is exact (give units would need a division by price): what
|
|
938
|
+
* the deposit would buy at the feed price with no fee, minus what the trader is actually paid out.
|
|
939
|
+
* `take` is a parameter because the plan is the reference price on both asset backends but the
|
|
940
|
+
* payout is not: a feed quote pays what the plan computed, a negotiated one the solver's `to_amount`.
|
|
941
|
+
*
|
|
942
|
+
* `carrierSats` is what an asset deposit carried to the filler, netted off a BTC payout: a payout
|
|
943
|
+
* that returns it charges nothing for it, and one that does not shows it as fee.
|
|
944
|
+
*/
|
|
945
|
+
declare const feedSpread: (plan: OfferPlan, take: bigint, carrierSats?: bigint) => bigint;
|
|
946
|
+
/**
|
|
947
|
+
* The plan prices the legs that were asked for, in the orientation asked for.
|
|
948
|
+
*
|
|
949
|
+
* Compared through `marketLegKey` rather than the raw `AssetInfo.id`, because a
|
|
950
|
+
* card spells its sides two ways and both reach here: the canonical CAIP-19 id
|
|
951
|
+
* a current registry publishes, and the legacy `"btc"`-or-68-hex form an older
|
|
952
|
+
* card carries beside a `*_corridor` field. That helper normalises the second
|
|
953
|
+
* into `<corridor>:<id>` and leaves the first alone, which is exactly the pair
|
|
954
|
+
* of spellings `eligibleMarkets` already selects by — so this check accepts the
|
|
955
|
+
* cards the routing read accepted, instead of refusing a canonical one as a
|
|
956
|
+
* pair mismatch it never was.
|
|
957
|
+
*/
|
|
958
|
+
declare const verifyPlanLegs: (plan: OfferPlan, legs: {
|
|
959
|
+
give: DiscoveryLeg;
|
|
960
|
+
take: DiscoveryLeg;
|
|
961
|
+
}, give: Side) => void;
|
|
962
|
+
|
|
963
|
+
/**
|
|
964
|
+
* The RFQ wire adapter: the pair string, the amount encoding, and the reply parse.
|
|
965
|
+
*
|
|
966
|
+
* **The pair string is wire, owned here.** Not the registry's display `pair` (`BTC/lightning:BTC`):
|
|
967
|
+
* the wire's is `<from-leg>-><to-leg>` over `<corridor>:<asset>` legs, the asset a registered ticker
|
|
968
|
+
* or, on arkade only, the 68-hex id. Solvers compare it byte for byte and cap it at 158 chars, so a
|
|
969
|
+
* CAIP-19 id cannot go on it; the public alias layer stops one level above.
|
|
970
|
+
*
|
|
971
|
+
* **Amounts go out as canonical decimal strings, unconditionally** — accepted on all four corridor
|
|
972
|
+
* request schemas, and a JSON number past 2^53 would lose the amount. Replies may carry either form
|
|
973
|
+
* (a number only while a non-negative safe integer), so `AmountEncodingUnsupported` fires on receipt.
|
|
974
|
+
*/
|
|
975
|
+
|
|
976
|
+
/**
|
|
977
|
+
* One leg, as the wire spells it. BTC legs use `rfq.ts`'s constants, never rebuilt from name and
|
|
978
|
+
* ticker (a second construction can drift from a byte-compared string). An arkade asset is the id
|
|
979
|
+
* verbatim, already lowercased by the alias layer.
|
|
980
|
+
*/
|
|
981
|
+
declare const rfqLeg: (leg: DiscoveryLeg) => string;
|
|
982
|
+
/** The directional pair, length-checked. Give-to-take, never the card's base/quote order: the card
|
|
983
|
+
* describes a market, the pair this trade. */
|
|
984
|
+
declare const rfqPairFor: (give: DiscoveryLeg, take: DiscoveryLeg) => string;
|
|
985
|
+
/** A request payload (built by `rfq.ts`'s builders, which are the schema) with `amount` in the
|
|
986
|
+
* wire's canonical string encoding. */
|
|
987
|
+
declare const withCanonicalAmount: (payload: Record<string, unknown>, amount: bigint) => Record<string, unknown>;
|
|
988
|
+
/**
|
|
989
|
+
* A solver's quote, with the compared fields decoded once. `RfqQuote` types amounts as `number` but
|
|
990
|
+
* they arrive as either form; decoding at the boundary keeps a string amount from failing a `!==`
|
|
991
|
+
* against a bigint downstream and reading as a solver mismatch.
|
|
992
|
+
*/
|
|
993
|
+
interface ParsedRfqQuote {
|
|
994
|
+
/** The reply verbatim, for the record and for anything not decoded here. */
|
|
995
|
+
readonly raw: RfqQuote;
|
|
996
|
+
readonly rfqId: string;
|
|
997
|
+
readonly pair: string;
|
|
998
|
+
/** `from_amount`: what the trader gives, atomic units of the give leg. */
|
|
999
|
+
readonly give: bigint;
|
|
1000
|
+
/** `to_amount`: what the trader takes. */
|
|
1001
|
+
readonly take: bigint;
|
|
1002
|
+
/** The covenant role key the quote commits to. */
|
|
1003
|
+
readonly solver: Pubkey;
|
|
1004
|
+
readonly validUntil: number;
|
|
1005
|
+
/** Optional on the wire; every corridor route refuses a quote without it. */
|
|
1006
|
+
readonly refundLocktime?: number;
|
|
1007
|
+
readonly profile: Record<string, unknown>;
|
|
1008
|
+
}
|
|
1009
|
+
/** Read a solver's quote, decoding both amounts. */
|
|
1010
|
+
declare const parseRfqQuote: (quote: RfqQuote) => ParsedRfqQuote;
|
|
1011
|
+
|
|
1012
|
+
/** An {@link RfqTransport} that can prove who answered. Absent means "attests nobody". */
|
|
1013
|
+
interface AttestingRfqTransport extends RfqTransport {
|
|
1014
|
+
/**
|
|
1015
|
+
* The x-only key every reply on this transport is proven to come from. Must be a claim the
|
|
1016
|
+
* transport ENFORCES (an author filter plus a conversation key only that author can decrypt
|
|
1017
|
+
* to); setting it otherwise turns a check into a decoration.
|
|
1018
|
+
*/
|
|
1019
|
+
readonly attestedResponder?: Pubkey;
|
|
1020
|
+
}
|
|
1021
|
+
/** What a factory is told about the card it is opening a rendezvous to. */
|
|
1022
|
+
interface RfqRendezvous {
|
|
1023
|
+
readonly card: DiscoveredMarket;
|
|
1024
|
+
/** The card's `discovery_pubkey` — who the request is addressed to. */
|
|
1025
|
+
readonly solverPubkey: Pubkey;
|
|
1026
|
+
/** The card's relays. */
|
|
1027
|
+
readonly relays: readonly string[];
|
|
1028
|
+
}
|
|
1029
|
+
type RfqTransportFactory = (rendezvous: RfqRendezvous) => AttestingRfqTransport | Promise<AttestingRfqTransport>;
|
|
1030
|
+
/** Declare that `transport` proves every reply came from `responder`. */
|
|
1031
|
+
declare const attesting: <T extends RfqTransport>(transport: T, responder: Pubkey) => AttestingRfqTransport;
|
|
1032
|
+
/**
|
|
1033
|
+
* Build the card's Nostr rendezvous bound to one pool, so discovery, quotes, and an
|
|
1034
|
+
* app's own readers share one socket per relay. Pass the process-wide
|
|
1035
|
+
* `sharedNostrPool()` from `@arkade-os/swap/nostr`, or one the caller owns from
|
|
1036
|
+
* `createNostrPool()` (a bare `SimplePool` lets one double close drop the shared socket);
|
|
1037
|
+
* omitting it keeps the shared default.
|
|
1038
|
+
*/
|
|
1039
|
+
declare const createNostrTransportFactory: (pool?: nostr_tools.SimplePool) => RfqTransportFactory;
|
|
1040
|
+
/**
|
|
1041
|
+
* The default: the card's own Nostr rendezvous. It attests the discovery key because
|
|
1042
|
+
* `nostrRfqTransport` subscribes with `authors: [solverPubkey]` and decrypts against that key — any
|
|
1043
|
+
* other reply is filtered by the relay or fails to decrypt.
|
|
1044
|
+
*/
|
|
1045
|
+
declare const nostrTransportFactory: RfqTransportFactory;
|
|
1046
|
+
|
|
1047
|
+
/** What every negotiated quote carries, whatever it settles through. */
|
|
1048
|
+
interface NegotiatedPreparation {
|
|
1049
|
+
readonly backend: "rfq";
|
|
1050
|
+
readonly card: DiscoveredMarket;
|
|
1051
|
+
readonly rfqId: string;
|
|
1052
|
+
/** The solver's reply, decoded once. */
|
|
1053
|
+
readonly wire: ParsedRfqQuote;
|
|
1054
|
+
}
|
|
1055
|
+
/** The covenant and the keys behind one quoted corridor swap. */
|
|
1056
|
+
interface CommonPreparation extends NegotiatedPreparation {
|
|
1057
|
+
/** The trader's OWN derivation of the Arkade lockup. */
|
|
1058
|
+
readonly lockup: {
|
|
1059
|
+
readonly address: string;
|
|
1060
|
+
readonly script: InstanceType<typeof VHTLC.ScriptV2>;
|
|
1061
|
+
readonly pkScript: Uint8Array;
|
|
1062
|
+
};
|
|
1063
|
+
}
|
|
1064
|
+
/**
|
|
1065
|
+
* What `accept()` inherits from a quote, held in memory by quote id and written nowhere. It makes
|
|
1066
|
+
* the covenant the quote was verified against the one that gets funded; re-deriving at accept
|
|
1067
|
+
* would be a second derivation that could disagree.
|
|
1068
|
+
*/
|
|
1069
|
+
type RfqPreparation = CorridorRfqPreparation | AssetRfqPreparation;
|
|
1070
|
+
/**
|
|
1071
|
+
* What `accept()` inherits from a negotiated asset quote.
|
|
1072
|
+
*
|
|
1073
|
+
* No `lockup`: this route settles through an offer covenant rather than a
|
|
1074
|
+
* VHTLC, so what travels is the whole derivation — the encoded offer, the
|
|
1075
|
+
* address the deposit goes to, and the covenant parameters the registration
|
|
1076
|
+
* needs. Derived at quote time because that is what the solver's
|
|
1077
|
+
* `offer_address` was compared against, and registered at accept from THIS
|
|
1078
|
+
* value: rebuilding the tree there would be a second derivation of the same
|
|
1079
|
+
* terms, which is the failure the hand-off exists to delete.
|
|
1080
|
+
*/
|
|
1081
|
+
interface AssetRfqPreparation extends NegotiatedPreparation {
|
|
1082
|
+
readonly assetPayment?: AssetPaymentTerms;
|
|
1083
|
+
readonly assetPaymentRecipient?: Instrument;
|
|
1084
|
+
readonly route: "arkade->arkade";
|
|
1085
|
+
/** The trader's OWN derivation of the offer covenant, registered by nobody. */
|
|
1086
|
+
readonly offer: DerivedOffer;
|
|
1087
|
+
/** The solver's carrier for an asset deposit; the deposit must carry exactly this many sats. */
|
|
1088
|
+
readonly carrierSats?: bigint;
|
|
1089
|
+
}
|
|
1090
|
+
type CorridorRfqPreparation = (CommonPreparation & {
|
|
1091
|
+
readonly route: "arkade->lightning";
|
|
1092
|
+
readonly contractParams: LightningSendContractParams;
|
|
1093
|
+
/** The refund key, and the address the quote named. */
|
|
1094
|
+
readonly secrets: ProvisionedKey;
|
|
1095
|
+
readonly refundAddress: string;
|
|
1096
|
+
/** What the lockup must carry: the quote's give amount. */
|
|
1097
|
+
readonly fundAmount: bigint;
|
|
1098
|
+
}) | (CommonPreparation & {
|
|
1099
|
+
readonly route: "lightning->arkade";
|
|
1100
|
+
readonly contractParams: LightningReceiveContractParams;
|
|
1101
|
+
readonly secrets: ProvisionedClaimSecret;
|
|
1102
|
+
readonly payoutAddress: string;
|
|
1103
|
+
/** What the solver's lockup must carry — the claim refuses less. */
|
|
1104
|
+
readonly expectedAmount: bigint;
|
|
1105
|
+
/** Last moment the hold invoice can be paid, unix seconds. */
|
|
1106
|
+
readonly payDeadline: number;
|
|
1107
|
+
}) | (CommonPreparation & {
|
|
1108
|
+
readonly route: "arkade->onchain";
|
|
1109
|
+
readonly secrets: ProvisionedClaimSecret;
|
|
1110
|
+
readonly refundAddress: string;
|
|
1111
|
+
readonly fundAmount: bigint;
|
|
1112
|
+
/** What the solver's HTLC must carry — the claim refuses less. */
|
|
1113
|
+
readonly expectedAmount: bigint;
|
|
1114
|
+
/** The L1 claim key, provisioned by the wallet like every other key. */
|
|
1115
|
+
readonly payoutKey: ProvisionedKey;
|
|
1116
|
+
/** Where the claim PAYS — the take endpoint's address, encoded. Distinct from
|
|
1117
|
+
* {@link payoutKey}, which only AUTHORISES the claim. */
|
|
1118
|
+
readonly payoutPkScript: Uint8Array;
|
|
1119
|
+
readonly htlc: OnchainHtlc;
|
|
1120
|
+
readonly htlcParams: OnchainHtlcParams;
|
|
1121
|
+
readonly l1Network: OnchainNetwork;
|
|
1122
|
+
readonly minConfirmations: number;
|
|
1123
|
+
}) | (CommonPreparation & {
|
|
1124
|
+
readonly route: "onchain->arkade";
|
|
1125
|
+
/** The Arkade claim: the key the solver's lockup pays, and the P that unlocks it. */
|
|
1126
|
+
readonly secrets: ProvisionedClaimSecret;
|
|
1127
|
+
readonly payoutAddress: string;
|
|
1128
|
+
/** What the solver's lockup must carry — the claim refuses less. */
|
|
1129
|
+
readonly expectedAmount: bigint;
|
|
1130
|
+
/** The HTLC's refund key, provisioned by the wallet like every other key. */
|
|
1131
|
+
readonly refundKey: ProvisionedKey;
|
|
1132
|
+
/** Where the L1 refund PAYS: a boarding address of this wallet. */
|
|
1133
|
+
readonly refundPkScript: Uint8Array;
|
|
1134
|
+
/** The L1 HTLC the trader funds, derived locally. */
|
|
1135
|
+
readonly htlc: OnchainHtlc;
|
|
1136
|
+
readonly htlcParams: OnchainHtlcParams;
|
|
1137
|
+
readonly l1Network: OnchainNetwork;
|
|
1138
|
+
readonly minConfirmations: number;
|
|
1139
|
+
});
|
|
1140
|
+
interface RfqQuoteInput {
|
|
1141
|
+
readonly assetPayment?: AssetPaymentInput;
|
|
1142
|
+
readonly quoteId: QuoteId;
|
|
1143
|
+
readonly route: "arkade->arkade" | "arkade->lightning" | "lightning->arkade" | "arkade->onchain" | "onchain->arkade";
|
|
1144
|
+
readonly candidate: MarketCandidate;
|
|
1145
|
+
readonly market: CardMarketRef;
|
|
1146
|
+
readonly legs: {
|
|
1147
|
+
readonly give: DiscoveryLeg;
|
|
1148
|
+
readonly take: DiscoveryLeg;
|
|
1149
|
+
};
|
|
1150
|
+
readonly endpoints: {
|
|
1151
|
+
readonly give: ResolvedEndpoint;
|
|
1152
|
+
readonly take: ResolvedEndpoint;
|
|
1153
|
+
};
|
|
1154
|
+
readonly amount?: PinnedAmount;
|
|
1155
|
+
readonly wallet: IWallet;
|
|
1156
|
+
/** Live, per section 6: a snapshot binds a covenant to a key that may have rotated. */
|
|
1157
|
+
readonly info: ArkadeInfo;
|
|
1158
|
+
/**
|
|
1159
|
+
* The corridor modules, unresolved: resolution refuses a dep overridden to nothing, so each
|
|
1160
|
+
* route resolves only the corridors it uses.
|
|
1161
|
+
*/
|
|
1162
|
+
readonly corridors: CorridorSet;
|
|
1163
|
+
readonly transport: AttestingRfqTransport;
|
|
1164
|
+
/**
|
|
1165
|
+
* The card's price feed, read by the asset route and by nobody else.
|
|
1166
|
+
*
|
|
1167
|
+
* A cross-asset quote's fee is a concession measured against a price, not a
|
|
1168
|
+
* subtraction of two legs — see {@link feedSpread} — and the card's own
|
|
1169
|
+
* advertised feed is the only price either asset backend has.
|
|
1170
|
+
*/
|
|
1171
|
+
readonly feed: FeedFetch;
|
|
1172
|
+
readonly policy?: SwapPolicy;
|
|
1173
|
+
/** Unix seconds. */
|
|
1174
|
+
readonly now: number;
|
|
1175
|
+
}
|
|
1176
|
+
declare const quoteViaRfq: (input: RfqQuoteInput) => Promise<{
|
|
1177
|
+
quote: Quote;
|
|
1178
|
+
preparation: RfqPreparation;
|
|
1179
|
+
}>;
|
|
1180
|
+
|
|
1181
|
+
/** What a quote derived, kept in memory for the accept that may follow. */
|
|
1182
|
+
type QuotePreparation = RfqPreparation | OfferPreparation;
|
|
1183
|
+
interface AcceptInput {
|
|
1184
|
+
readonly quote: Quote;
|
|
1185
|
+
readonly preparation?: QuotePreparation;
|
|
1186
|
+
readonly wallet: IWallet;
|
|
1187
|
+
readonly repository: AssetSwapRepository | undefined;
|
|
1188
|
+
readonly corridors: CorridorSet;
|
|
1189
|
+
/**
|
|
1190
|
+
* The drive, when the caller has one. It turns a record into the public {@link Swap} (only
|
|
1191
|
+
* the drive knows the live `outcome`) and ARMS the swap with the manager, behind the return.
|
|
1192
|
+
* Without one the answer is the record's projection and nothing is driven.
|
|
1193
|
+
*/
|
|
1194
|
+
readonly drive?: SwapDrive;
|
|
1195
|
+
/** Unix seconds. */
|
|
1196
|
+
readonly now: number;
|
|
1197
|
+
readonly validUntil?: number;
|
|
1198
|
+
}
|
|
1199
|
+
declare const conflictingFields: (record: SwapRecord, quote: Quote) => string[];
|
|
1200
|
+
/**
|
|
1201
|
+
* Accept a quote: make it durable, then move the value.
|
|
1202
|
+
*
|
|
1203
|
+
* Idempotent by quote id and only by quote id. A second call with the same
|
|
1204
|
+
* quote returns the stored swap when the funding txid is already known, resumes
|
|
1205
|
+
* the record when it is not, and refuses as `AcceptConflict` only when the
|
|
1206
|
+
* durable evidence contradicts the quote on a material field.
|
|
1207
|
+
*/
|
|
1208
|
+
declare const acceptQuote: (input: AcceptInput) => Promise<Swap>;
|
|
1209
|
+
/** The stored record for a quote id, for a caller that holds only the id. */
|
|
1210
|
+
declare const swapRecordOf: (repository: AssetSwapRepository | undefined, id: QuoteId) => Promise<SwapRecord | undefined>;
|
|
1211
|
+
|
|
1212
|
+
/** What `cancel()` did to the deposit. An `indeterminate` spend is `needs_recovery`: value moved
|
|
1213
|
+
* and the local rebuild cannot name how. */
|
|
1214
|
+
type CancelOutcome = "cancelled" | "filled" | "needs_recovery";
|
|
1215
|
+
interface CancelInput {
|
|
1216
|
+
readonly wallet: IWallet;
|
|
1217
|
+
readonly repository: AssetSwapRepository;
|
|
1218
|
+
/** The record to cancel, read by the caller after `drive.ready` — the one
|
|
1219
|
+
* read the call makes, and what the gate is written from. */
|
|
1220
|
+
readonly record: OfferSwapRecord;
|
|
1221
|
+
/** The delivery channel both edges emit through, armed or not. */
|
|
1222
|
+
readonly drive: SwapDrive;
|
|
1223
|
+
readonly indexer: LockupSpendIndexer;
|
|
1224
|
+
/** Unix seconds. Injected for tests. */
|
|
1225
|
+
readonly now?: () => number;
|
|
1226
|
+
}
|
|
1227
|
+
/**
|
|
1228
|
+
* Cancel one offer swap, reconciling the fill race and writing the v2 record.
|
|
1229
|
+
*
|
|
1230
|
+
* The caller has already made the strict read (an unreadable repository must not read as "no
|
|
1231
|
+
* record" and send a cancel past its gate) and refused corridor tags and missing records as
|
|
1232
|
+
* `NotCancellable`.
|
|
1233
|
+
*/
|
|
1234
|
+
declare const cancelSwap: (input: CancelInput) => Promise<{
|
|
1235
|
+
outcome: CancelOutcome;
|
|
1236
|
+
}>;
|
|
1237
|
+
|
|
1238
|
+
interface SwapClientConfig {
|
|
1239
|
+
/** The wallet, and through it the operator: server info, chain reads and broadcast all come from
|
|
1240
|
+
* it; no server URL is accepted anywhere. */
|
|
1241
|
+
readonly wallet: IWallet;
|
|
1242
|
+
/**
|
|
1243
|
+
* Storage for accept records, the markets cache and the restore-scan cursor. No implicit default
|
|
1244
|
+
* and never an in-memory fallback: silently losing active swaps is what it must prevent.
|
|
1245
|
+
* Browser: `IndexedDbAssetSwapRepository`; Node: `@arkade-os/swap/node`; tests:
|
|
1246
|
+
* `InMemoryAssetSwapRepository`. Without one, `accept()` throws `MissingCorridorDep`.
|
|
1247
|
+
*/
|
|
1248
|
+
readonly repository?: AssetSwapRepository;
|
|
1249
|
+
readonly discovery?: DiscoveryConfig;
|
|
1250
|
+
/** Dependency overrides only: they never enable a route or pick a solver. */
|
|
1251
|
+
readonly corridors?: CorridorOverrides;
|
|
1252
|
+
readonly policy?: SwapPolicy;
|
|
1253
|
+
/** Covenant co-signer override, 33-byte compressed hex. */
|
|
1254
|
+
readonly emulatorPubkey?: string;
|
|
1255
|
+
/** Overrides the wallet's own connection; for tests and a second operator. */
|
|
1256
|
+
readonly operator?: SwapOperator;
|
|
1257
|
+
readonly fetchImpl?: typeof fetch;
|
|
1258
|
+
/** How a card's rendezvous is opened. Defaults to the card's Nostr transport, the only shipped
|
|
1259
|
+
* one that attests who answered; a transport that attests nobody fails the responder check. */
|
|
1260
|
+
readonly transportFor?: RfqTransportFactory;
|
|
1261
|
+
}
|
|
1262
|
+
interface AcceptOptions {
|
|
1263
|
+
/** Final funding submission deadline, Unix seconds, capped by the quote expiry. */
|
|
1264
|
+
readonly validUntil?: number;
|
|
1265
|
+
}
|
|
1266
|
+
interface SwapClient {
|
|
1267
|
+
/**
|
|
1268
|
+
* The restore-read, and — when it armed — the first pass after it. Under `drive: "auto"` the
|
|
1269
|
+
* read arms the loop on live work; arming runs a pass immediately since a resumed swap may be
|
|
1270
|
+
* past a deadline. **Rejects only when the repository is unreadable**; per-record problems
|
|
1271
|
+
* surface through {@link onUpdate}.
|
|
1272
|
+
*/
|
|
1273
|
+
readonly ready: Promise<void>;
|
|
1274
|
+
/**
|
|
1275
|
+
* Arm the drive. Idempotent (React double-mount safe); required only by `drive: "manual"`.
|
|
1276
|
+
*
|
|
1277
|
+
* @throws {SwapDriveRefusedError} under `drive: "readonly"`, which actuates
|
|
1278
|
+
* nothing — silence would leave two contradictory instructions standing.
|
|
1279
|
+
*/
|
|
1280
|
+
start(): Promise<void>;
|
|
1281
|
+
/**
|
|
1282
|
+
* Release live resources and stay reusable: a pause, not a cancellation. In-flight actions run to
|
|
1283
|
+
* completion; records and the wallet's contract registrations stay, because dropping one
|
|
1284
|
+
* unwatches a funded lockup.
|
|
1285
|
+
*/
|
|
1286
|
+
stop(): Promise<void>;
|
|
1287
|
+
/**
|
|
1288
|
+
* Terminal cleanup: {@link stop}, drain in-flight work (nothing takes an `AbortSignal`), drop
|
|
1289
|
+
* every listener. Durable state survives; an injected repository is never closed. Afterwards
|
|
1290
|
+
* members refuse with {@link ClientDisposed}, except teardown: a second dispose and an issued
|
|
1291
|
+
* {@link Unsubscribe} are no-ops, so React-effect teardown never throws.
|
|
1292
|
+
*/
|
|
1293
|
+
[Symbol.asyncDispose](): Promise<void>;
|
|
1294
|
+
/**
|
|
1295
|
+
* Every outcome transition, both families. Replays every known swap's current outcome, then
|
|
1296
|
+
* streams. Idempotent per derived `(swapId, outcome)`, so the legal `claimed -> claimable`
|
|
1297
|
+
* backslide (`funded` twice) is delivered once.
|
|
1298
|
+
*/
|
|
1299
|
+
onUpdate(fn: (update: SwapUpdate) => void): Unsubscribe;
|
|
1300
|
+
/**
|
|
1301
|
+
* Recover a swap whose value was swept, then run one pass. The wallet's recovery round takes no
|
|
1302
|
+
* outpoints and may defer outputs, so this re-reads the lockup to answer for THIS swap.
|
|
1303
|
+
*
|
|
1304
|
+
* @throws {SwapDriveRefusedError} under `drive: "readonly"`; for a lockup
|
|
1305
|
+
* still inside its refund window, where a round including it can fail the
|
|
1306
|
+
* whole batch; and for a swap with nothing swept — which is what a
|
|
1307
|
+
* `needs_recovery` that came from `needs_counterparty` is.
|
|
1308
|
+
*/
|
|
1309
|
+
recover(swapId: AssetSwapId): Promise<RecoveryResult>;
|
|
1310
|
+
/**
|
|
1311
|
+
* Cancel an asset swap: take back an unfilled offer's deposit (HTLC corridor swaps exit by claim
|
|
1312
|
+
* or refund). Cancel races a fill: an already-spent deposit answers `filled` rather than
|
|
1313
|
+
* throwing; a spend the rebuild cannot classify is `needs_recovery`.
|
|
1314
|
+
*
|
|
1315
|
+
* @throws {NotCancellable} for a corridor-tagged id, or an id no record backs.
|
|
1316
|
+
* @throws {MissingCorridorDep} when the client was given no repository.
|
|
1317
|
+
* @throws {ClientDisposed} after disposal.
|
|
1318
|
+
*/
|
|
1319
|
+
cancel(swapId: AssetSwapId): Promise<{
|
|
1320
|
+
outcome: CancelOutcome;
|
|
1321
|
+
}>;
|
|
1322
|
+
/**
|
|
1323
|
+
* Every swap this client wrote — both families, live and ended — projected through the drive's
|
|
1324
|
+
* derivation, so membership is independent of `start()` and drive mode. Undecodable records are
|
|
1325
|
+
* skipped. **The v2 keyspace is never pruned.** v1-era rows (`swaps`, `rfqSwaps`) are excluded;
|
|
1326
|
+
* they belong to `/protocol`'s readers.
|
|
1327
|
+
*/
|
|
1328
|
+
swaps(filter?: SwapFilter): Promise<Swap[]>;
|
|
1329
|
+
/**
|
|
1330
|
+
* The markets on the active snapshot, in the `Quote.market` shape plus each leg's announced
|
|
1331
|
+
* limits, with no RFQ and no disclosure. Shares `quote()`'s registry allowlist and addressability
|
|
1332
|
+
* filter but not its eligibility, so it can list a card `quote()` refuses. Fetches when no
|
|
1333
|
+
* snapshot is in hand, as `quote()` does, since callers reach for it BEFORE quoting.
|
|
1334
|
+
*
|
|
1335
|
+
* `key` is not unique: correlate with `resolve().market` on `key` + `source` + `discoveryPubkey`,
|
|
1336
|
+
* or `solver` on spot cards, which have no `discoveryPubkey`. These fields identify a solver's
|
|
1337
|
+
* market, not one card. A solver may publish several with different limits: `pair` separates a
|
|
1338
|
+
* flipped card, but nothing public separates fee tiers.
|
|
1339
|
+
*
|
|
1340
|
+
* @throws {DiscoverySnapshotUnavailable} when the fetch leaves it with
|
|
1341
|
+
* nothing either.
|
|
1342
|
+
*/
|
|
1343
|
+
markets(): Promise<Market[]>;
|
|
1344
|
+
/**
|
|
1345
|
+
* The route, the market that would price it, and what the active snapshot serves — disclosing
|
|
1346
|
+
* nothing. Network-free against injected or cached discovery data, so application policy can
|
|
1347
|
+
* veto before an RFQ round trip discloses an invoice or amount.
|
|
1348
|
+
*/
|
|
1349
|
+
resolve(input: QuoteInput): Promise<RouteResolution>;
|
|
1350
|
+
/** Verified, binding terms. Nothing is persisted, funded or watched. */
|
|
1351
|
+
quote(input: QuoteInput): Promise<Quote>;
|
|
1352
|
+
/**
|
|
1353
|
+
* Make the quote durable, then move the value: record and secrets are at rest before anything
|
|
1354
|
+
* irreversible. Idempotent by quote id — never a second invoice or a second funding. Returns
|
|
1355
|
+
* once durable: an invoice shown while its claim secret is only in memory buys an unclaimable
|
|
1356
|
+
* lockup.
|
|
1357
|
+
*
|
|
1358
|
+
* @throws {QuoteExpired} past `quote.expiresAt`; the client never re-quotes.
|
|
1359
|
+
* @throws {InsufficientFunds} before the persist, on funding routes only.
|
|
1360
|
+
* @throws {AcceptConflict} when a record for this quote id contradicts it.
|
|
1361
|
+
* @throws {MissingCorridorDep} when the client was given no repository.
|
|
1362
|
+
*/
|
|
1363
|
+
accept(quote: Quote, options?: AcceptOptions): Promise<Swap>;
|
|
1364
|
+
/**
|
|
1365
|
+
* Pay a bolt11, a `bc1…`, or a plain Arkade address: `quote` → fee ceiling → `accept`, the amount
|
|
1366
|
+
* being what the recipient gets. A plain Arkade address is **not** a swap: it settles through
|
|
1367
|
+
* `wallet.send` and answers `{ kind: "payment", txid }`, hence the union.
|
|
1368
|
+
*
|
|
1369
|
+
* @throws {MaxFeeExceeded} when the quoted fee is over `maxFee` or
|
|
1370
|
+
* `policy.maxFee`, whichever is tighter — before anything is funded.
|
|
1371
|
+
*/
|
|
1372
|
+
pay(destination: string, options?: PayOptions): Promise<PayResult>;
|
|
1373
|
+
/**
|
|
1374
|
+
* Ask for an incoming payment and get back the artifact to show its payer. Returns only after
|
|
1375
|
+
* `accept()` persisted (see {@link accept}). Generic over `via` so the artifact's shape follows
|
|
1376
|
+
* the corridor named; see {@link ReceiveArtifact}.
|
|
1377
|
+
*
|
|
1378
|
+
* @throws {MaxFeeExceeded} as {@link pay} does.
|
|
1379
|
+
*/
|
|
1380
|
+
receive<C extends CorridorId = CorridorId>(options: ReceiveOptions & {
|
|
1381
|
+
readonly via: C;
|
|
1382
|
+
}): Promise<ReceiveRequest<C>>;
|
|
1383
|
+
/**
|
|
1384
|
+
* Swap one Arkade asset for another.
|
|
1385
|
+
*
|
|
1386
|
+
* @throws {MaxFeeExceeded} as {@link pay} does.
|
|
1387
|
+
*/
|
|
1388
|
+
exchange(options: ExchangeOptions): Promise<Swap>;
|
|
1389
|
+
/**
|
|
1390
|
+
* What the quote with this id derived — covenant, keys, wire reply. Process-local, not durable;
|
|
1391
|
+
* it exists so the covenant a quote was verified against is the one funded, not a re-derivation.
|
|
1392
|
+
*/
|
|
1393
|
+
preparationOf(id: QuoteId): QuotePreparation | undefined;
|
|
1394
|
+
}
|
|
1395
|
+
/** The in-memory filter {@link SwapClient.swaps} applies. */
|
|
1396
|
+
interface SwapFilter {
|
|
1397
|
+
readonly family?: SwapFamily;
|
|
1398
|
+
readonly outcome?: Outcome;
|
|
1399
|
+
}
|
|
1400
|
+
declare const createSwapClient: (config: SwapClientConfig) => SwapClient;
|
|
1401
|
+
|
|
1402
|
+
/**
|
|
1403
|
+
* The §7 taxonomy, as typed errors. Every member is thrown before value moves, or not at all;
|
|
1404
|
+
* anything after funding is an outcome of the drive loop, not an exception. Each class names
|
|
1405
|
+
* the boundary it fires at.
|
|
1406
|
+
*
|
|
1407
|
+
* Members are bare condition nouns (`QuoteExpired`), matching `SwapRefusal`. Non-members keep the
|
|
1408
|
+
* `Error` suffix (`AssetIdError`, `AmountFormatError`: codec faults on caller input). v1's
|
|
1409
|
+
* `AddressMismatch` is not a member: it is the `lockup_address` case of
|
|
1410
|
+
* {@link QuoteVerificationFailed}.
|
|
1411
|
+
*/
|
|
1412
|
+
|
|
1413
|
+
/**
|
|
1414
|
+
* The checks §3.1 runs on every quote, before it is returned. `responder` is delivered by the
|
|
1415
|
+
* transport but *run* as a check, so verification cannot be skipped by configuring a dev
|
|
1416
|
+
* transport that authenticates nobody. Published RFQ (§10) attributes bids by signature instead.
|
|
1417
|
+
*/
|
|
1418
|
+
type QuoteCheck = "pair" | "lockup_address" | "invoice" | "refund_window" | "responder";
|
|
1419
|
+
/**
|
|
1420
|
+
* `to` is underdetermined — it parses as nothing, as more than one thing, or as one thing the
|
|
1421
|
+
* corridor that owns it refuses (a `tb1…` on mainnet, another operator's Arkade address, a
|
|
1422
|
+
* bolt11 the decoder rejects). The refusal rides on `detail`.
|
|
1423
|
+
*
|
|
1424
|
+
* A destination core classifies but no module claims (an LNURL today) is NOT this: it becomes
|
|
1425
|
+
* {@link UnsupportedRoute}.
|
|
1426
|
+
*
|
|
1427
|
+
* Boundary: `resolve()`/`quote()`, the single place `to` is parsed.
|
|
1428
|
+
*/
|
|
1429
|
+
declare class AmbiguousDestination extends Error {
|
|
1430
|
+
readonly destination: string;
|
|
1431
|
+
readonly name = "AmbiguousDestination";
|
|
1432
|
+
constructor(destination: string, detail: string);
|
|
1433
|
+
}
|
|
1434
|
+
/**
|
|
1435
|
+
* The corridor pair is not in the implemented route union.
|
|
1436
|
+
*
|
|
1437
|
+
* Boundary: route resolution, before RFQ disclosure, artifact creation, persistence or funding.
|
|
1438
|
+
* Also the alias layer (a rail no corridor serves), and `quote()` when no discovered market
|
|
1439
|
+
* serves the pair on the active snapshot.
|
|
1440
|
+
*/
|
|
1441
|
+
declare class UnsupportedRoute extends Error {
|
|
1442
|
+
readonly name = "UnsupportedRoute";
|
|
1443
|
+
readonly give: CorridorId | undefined;
|
|
1444
|
+
readonly take: CorridorId | undefined;
|
|
1445
|
+
constructor(detail: string, corridors?: {
|
|
1446
|
+
give?: CorridorId;
|
|
1447
|
+
take?: CorridorId;
|
|
1448
|
+
});
|
|
1449
|
+
}
|
|
1450
|
+
/**
|
|
1451
|
+
* No market data: neither an injected nor a cached snapshot. For offline resolution, warm or
|
|
1452
|
+
* inject a snapshot.
|
|
1453
|
+
*
|
|
1454
|
+
* Boundary: `resolve()`, and `quote()` when its permitted fetch also yields nothing (no registry
|
|
1455
|
+
* configured, an unindexed network, or an unreachable registry with no cache).
|
|
1456
|
+
*/
|
|
1457
|
+
declare class DiscoverySnapshotUnavailable extends Error {
|
|
1458
|
+
readonly network: NetworkName;
|
|
1459
|
+
readonly name = "DiscoverySnapshotUnavailable";
|
|
1460
|
+
constructor(network: NetworkName, detail: string);
|
|
1461
|
+
}
|
|
1462
|
+
/**
|
|
1463
|
+
* Two amounts are pinned. Exactly one may be: the caller's `amount` +
|
|
1464
|
+
* `amountOn`, or the invoice's.
|
|
1465
|
+
*
|
|
1466
|
+
* Boundary: `quote()`, before any network round trip.
|
|
1467
|
+
*/
|
|
1468
|
+
declare class AmountMismatch extends Error {
|
|
1469
|
+
readonly sources: readonly [string, string];
|
|
1470
|
+
readonly name = "AmountMismatch";
|
|
1471
|
+
constructor(sources: readonly [string, string]);
|
|
1472
|
+
}
|
|
1473
|
+
/**
|
|
1474
|
+
* The amount cannot cross this encoding without an unsafe narrowing — a quote
|
|
1475
|
+
* field arriving as a JSON number past 2^53, a non-canonical decimal string, or
|
|
1476
|
+
* a `bigint` too large for a foreign `number` amount.
|
|
1477
|
+
*
|
|
1478
|
+
* Boundary: the RFQ adapter, both directions; core's payment rails.
|
|
1479
|
+
*/
|
|
1480
|
+
declare class AmountEncodingUnsupported extends Error {
|
|
1481
|
+
readonly field: string;
|
|
1482
|
+
readonly value: string;
|
|
1483
|
+
readonly name = "AmountEncodingUnsupported";
|
|
1484
|
+
constructor(field: string, value: string, detail: string, options?: ErrorOptions);
|
|
1485
|
+
}
|
|
1486
|
+
/**
|
|
1487
|
+
* A solver response failed a local check (see {@link QuoteCheck}); v1's `AddressMismatch` is the
|
|
1488
|
+
* `lockup_address` case.
|
|
1489
|
+
*
|
|
1490
|
+
* Boundary: `quote()`, before the quote is returned and so before funding.
|
|
1491
|
+
*/
|
|
1492
|
+
declare class QuoteVerificationFailed extends Error {
|
|
1493
|
+
readonly check: QuoteCheck;
|
|
1494
|
+
readonly name = "QuoteVerificationFailed";
|
|
1495
|
+
readonly expected: string | undefined;
|
|
1496
|
+
readonly actual: string | undefined;
|
|
1497
|
+
constructor(check: QuoteCheck, expected?: string, actual?: string,
|
|
1498
|
+
/** The gate or derivation this folds in, kept as the `cause` chain. */
|
|
1499
|
+
options?: ErrorOptions);
|
|
1500
|
+
}
|
|
1501
|
+
/**
|
|
1502
|
+
* A quote past its TTL, or so close to it that acting on it is the same thing. At `accept()` the
|
|
1503
|
+
* client never silently re-quotes, since the price seen is not the price one would get. At
|
|
1504
|
+
* `quote()` a quote arriving with less than `policy.quoteTtlFloorSeconds` left is expired on
|
|
1505
|
+
* arrival.
|
|
1506
|
+
*
|
|
1507
|
+
* Boundary: `quote()`, against the policy floor; `accept()`, before persistence.
|
|
1508
|
+
*/
|
|
1509
|
+
declare class QuoteExpired extends Error {
|
|
1510
|
+
readonly quoteId: string;
|
|
1511
|
+
readonly expiresAt: number;
|
|
1512
|
+
readonly now: number;
|
|
1513
|
+
readonly name = "QuoteExpired";
|
|
1514
|
+
constructor(quoteId: string, expiresAt: number, now: number);
|
|
1515
|
+
}
|
|
1516
|
+
/**
|
|
1517
|
+
* The quote's fee is over the verb's ceiling. Carries the terms rather than the `Quote`; to
|
|
1518
|
+
* re-present them, call `quote()` again.
|
|
1519
|
+
*
|
|
1520
|
+
* Boundary: the verbs layer, between `quote` and `accept` — before funding.
|
|
1521
|
+
*/
|
|
1522
|
+
declare class MaxFeeExceeded extends Error {
|
|
1523
|
+
readonly quoteId: string;
|
|
1524
|
+
readonly asset: AssetId;
|
|
1525
|
+
readonly fee: bigint;
|
|
1526
|
+
readonly maxFee: bigint;
|
|
1527
|
+
readonly name = "MaxFeeExceeded";
|
|
1528
|
+
constructor(quoteId: string, asset: AssetId, fee: bigint, maxFee: bigint);
|
|
1529
|
+
}
|
|
1530
|
+
/**
|
|
1531
|
+
* The wallet cannot fund the give leg.
|
|
1532
|
+
*
|
|
1533
|
+
* Boundary: `accept()`, before persistence and funding.
|
|
1534
|
+
*/
|
|
1535
|
+
declare class InsufficientFunds extends Error {
|
|
1536
|
+
readonly asset: AssetId;
|
|
1537
|
+
readonly required: bigint;
|
|
1538
|
+
readonly name = "InsufficientFunds";
|
|
1539
|
+
readonly available: bigint | undefined;
|
|
1540
|
+
constructor(asset: AssetId, required: bigint, available?: bigint);
|
|
1541
|
+
}
|
|
1542
|
+
/**
|
|
1543
|
+
* A quote id maps to a persisted accept record that contradicts it. Only
|
|
1544
|
+
* incompatible *durable evidence* qualifies — an ordinary duplicate `accept()`
|
|
1545
|
+
* returns or resumes the original swap, and a funding txid appearing where there
|
|
1546
|
+
* was none is a benign resume.
|
|
1547
|
+
*
|
|
1548
|
+
* Boundary: `accept()`, on the persisted record, before any second funding.
|
|
1549
|
+
*/
|
|
1550
|
+
declare class AcceptConflict extends Error {
|
|
1551
|
+
readonly quoteId: string;
|
|
1552
|
+
readonly swapId: string;
|
|
1553
|
+
readonly fields: readonly string[];
|
|
1554
|
+
readonly name = "AcceptConflict";
|
|
1555
|
+
constructor(quoteId: string, swapId: string, fields: readonly string[]);
|
|
1556
|
+
}
|
|
1557
|
+
/**
|
|
1558
|
+
* A method called after async disposal. Disposal is terminal for the instance;
|
|
1559
|
+
* the durable records survive it and a new client resumes them.
|
|
1560
|
+
*
|
|
1561
|
+
* Boundary: every client method, before it does anything.
|
|
1562
|
+
*/
|
|
1563
|
+
declare class ClientDisposed extends Error {
|
|
1564
|
+
readonly method: string;
|
|
1565
|
+
readonly name = "ClientDisposed";
|
|
1566
|
+
constructor(method: string);
|
|
1567
|
+
}
|
|
1568
|
+
/**
|
|
1569
|
+
* `cancel()` on a swap this client cannot cancel. Only an unfilled offer is cancellable (an offer
|
|
1570
|
+
* covenant never expires); an HTLC's exits are a claim or a refund. Also thrown for an `offer:`
|
|
1571
|
+
* or untagged id no record backs — "no such swap" is the same condition.
|
|
1572
|
+
*
|
|
1573
|
+
* Boundary: `cancel()`.
|
|
1574
|
+
*/
|
|
1575
|
+
declare class NotCancellable extends Error {
|
|
1576
|
+
readonly swapId: string;
|
|
1577
|
+
readonly name = "NotCancellable";
|
|
1578
|
+
constructor(swapId: string);
|
|
1579
|
+
}
|
|
1580
|
+
/**
|
|
1581
|
+
* A destination disagrees with its asset's chain. Inert: only §9's deferred EVM corridor could
|
|
1582
|
+
* throw it, so it is the one declared error with no throwing site today.
|
|
1583
|
+
*/
|
|
1584
|
+
declare class InconsistentRoute extends Error {
|
|
1585
|
+
readonly asset: AssetId;
|
|
1586
|
+
readonly destination: string;
|
|
1587
|
+
readonly name = "InconsistentRoute";
|
|
1588
|
+
constructor(asset: AssetId, destination: string);
|
|
1589
|
+
}
|
|
1590
|
+
/**
|
|
1591
|
+
* `getArkadeInfo({ requireLive: true })` failed while deriving a covenant. A
|
|
1592
|
+
* snapshot would bind the covenant to a signer key the operator may no longer
|
|
1593
|
+
* co-sign for, so this fails closed rather than falling back.
|
|
1594
|
+
*
|
|
1595
|
+
* Boundary: `quote()`, at covenant derivation — before funding.
|
|
1596
|
+
*/
|
|
1597
|
+
declare class OperatorUnreachable extends Error {
|
|
1598
|
+
readonly name = "OperatorUnreachable";
|
|
1599
|
+
constructor(detail: string, options?: ErrorOptions);
|
|
1600
|
+
}
|
|
1601
|
+
/**
|
|
1602
|
+
* A corridor's dependency was explicitly overridden to nothing (`null`; `undefined` takes the
|
|
1603
|
+
* default), or is required on this network and absent — e.g. the arkade co-signer key on
|
|
1604
|
+
* `testnet`/`signet`, which `EMULATOR_PUBKEYS` does not pin.
|
|
1605
|
+
*
|
|
1606
|
+
* Boundary: dep resolution, when a route first touches that corridor. Never construction: a
|
|
1607
|
+
* missing dep for a corridor nobody uses is not an error.
|
|
1608
|
+
*/
|
|
1609
|
+
declare class MissingCorridorDep extends Error {
|
|
1610
|
+
readonly corridor: CorridorId;
|
|
1611
|
+
readonly dep: string;
|
|
1612
|
+
readonly name = "MissingCorridorDep";
|
|
1613
|
+
constructor(corridor: CorridorId, dep: string);
|
|
1614
|
+
}
|
|
1615
|
+
/** Every member of the taxonomy. */
|
|
1616
|
+
type SwapError = AmbiguousDestination | UnsupportedRoute | DiscoverySnapshotUnavailable | AmountMismatch | AmountEncodingUnsupported | QuoteVerificationFailed | SwapRefusal | QuoteExpired | MaxFeeExceeded | InsufficientFunds | AcceptConflict | ClientDisposed | NotCancellable | InconsistentRoute | OperatorUnreachable | MissingCorridorDep;
|
|
1617
|
+
/** The sixteen names. Derived, so there is no second list to drift. */
|
|
1618
|
+
type SwapErrorName = SwapError["name"];
|
|
1619
|
+
/** The sixteen, as values — what the coverage pass counts. */
|
|
1620
|
+
declare const SWAP_ERROR_NAMES: readonly SwapErrorName[];
|
|
1621
|
+
/**
|
|
1622
|
+
* Whether `e` belongs to the taxonomy, optionally narrowed to one member. Catalog-driven, and
|
|
1623
|
+
* rejects an impostor: a foreign error merely named `QuoteExpired` fails the constructor check.
|
|
1624
|
+
*/
|
|
1625
|
+
declare function isSwapError(e: unknown): e is SwapError;
|
|
1626
|
+
declare function isSwapError<N extends SwapErrorName>(e: unknown, name: N): e is Extract<SwapError, {
|
|
1627
|
+
name: N;
|
|
1628
|
+
}>;
|
|
1629
|
+
|
|
1630
|
+
interface JointGraph {
|
|
1631
|
+
readonly arkTx: string;
|
|
1632
|
+
readonly checkpoints: readonly string[];
|
|
1633
|
+
readonly graphId: string;
|
|
1634
|
+
readonly inputOwners: readonly (string | null)[];
|
|
1635
|
+
}
|
|
1636
|
+
declare function digestJointGraph(plan: Omit<JointGraph, "graphId">, template: string): string;
|
|
1637
|
+
declare function verifyJointGraph(plan: JointGraph, template: string): boolean;
|
|
1638
|
+
declare function deepFreeze<T>(value: T): T;
|
|
1639
|
+
/** Removes only tapscript signatures, preserving all other PSBT commitments. */
|
|
1640
|
+
declare function unsignedPsbtBytes(tx: Transaction): Uint8Array;
|
|
1641
|
+
|
|
1642
|
+
declare const OFFER_FILL_TEMPLATE = "offer-fill/1";
|
|
1643
|
+
declare const OFFER_FILL_OWNERS: readonly (FillInputOwner | null)[];
|
|
1644
|
+
interface FillSponsorFare {
|
|
1645
|
+
assetId?: string;
|
|
1646
|
+
amount?: bigint | number;
|
|
1647
|
+
script: Uint8Array;
|
|
1648
|
+
/** Defaults to assetCarrierSats; a sats-only fare should set this explicitly. */
|
|
1649
|
+
sats?: bigint | number;
|
|
1650
|
+
}
|
|
1651
|
+
interface FillSponsor {
|
|
1652
|
+
fund: FillFunding[];
|
|
1653
|
+
netContributionSats: bigint | number;
|
|
1654
|
+
fare?: FillSponsorFare;
|
|
1655
|
+
changeScript: Uint8Array;
|
|
1656
|
+
combineSatsFareWithChange?: boolean;
|
|
1657
|
+
}
|
|
1658
|
+
interface BuildOfferFillPlanOpts {
|
|
1659
|
+
fund: FillFunding[];
|
|
1660
|
+
payoutScript?: Uint8Array;
|
|
1661
|
+
fundingTxid?: string;
|
|
1662
|
+
fundingOutpoint?: FillOutpoint;
|
|
1663
|
+
swapAddress?: string;
|
|
1664
|
+
assetCarrierSats?: bigint;
|
|
1665
|
+
sponsor?: FillSponsor;
|
|
1666
|
+
}
|
|
1667
|
+
/** Builds an unsigned offer fill without signing or submitting the spend. */
|
|
1668
|
+
declare function buildOfferFillPlan(wallet: IWallet, arkServerUrl: string, offerHex: string, opts: BuildOfferFillPlanOpts): Promise<JointGraph>;
|
|
1669
|
+
declare function verifyOfferFillPlan(plan: JointGraph): boolean;
|
|
1670
|
+
|
|
1671
|
+
export { type JointGraph as $, type AssetAliasTable as A, type BuildOfferFillPlanOpts as B, type CorridorFactory as C, type DiscoveryIndex as D, type CorridorOverrides as E, type CorridorPass as F, type CorridorRfqPreparation as G, DEFAULT_MAX_REFUND_WINDOW_SECONDS as H, type DiscoveryConfig as I, type DiscoveryIndexInput as J, DiscoverySnapshotUnavailable as K, type LightningCorridorDeps as L, type MarketCandidate as M, type DriveMode as N, type OnchainCorridorDeps as O, type DriveRefusal as P, type ExchangeOptions as Q, FEED_TTL_MS as R, type SwapPolicy as S, type FeeCeiling as T, type FeedFetch as U, type FeedQuoteInput as V, type FillSponsor as W, type FillSponsorFare as X, INDEXED_NETWORKS as Y, InconsistentRoute as Z, InsufficientFunds as _, type ArkadeCorridorDeps as a, feedSpread as a$, type LockupOwner as a0, type Market as a1, type MarketLeg as a2, MaxFeeExceeded as a3, MissingCorridorDep as a4, NotCancellable as a5, OFFER_FILL_OWNERS as a6, OFFER_FILL_TEMPLATE as a7, ONCHAIN_CLAIM_FEE_RATE_SATVB as a8, type ObservationSeam as a9, type SwapDrive as aA, type SwapDriveConfig as aB, SwapDriveRefusedError as aC, type SwapError as aD, type SwapErrorName as aE, type SwapFilter as aF, UnsupportedRoute as aG, type VerbDeps as aH, acceptQuote as aI, attesting as aJ, buildOfferFillPlan as aK, cancelSwap as aL, canonicalAssetId as aM, cardMarketOf as aN, chooseMarket as aO, conflictingFields as aP, corridorSet as aQ, createNostrTransportFactory as aR, createSwapClient as aS, createSwapDrive as aT, deepFreeze as aU, digestJointGraph as aV, discoveryIndex as aW, eligibleMarkets as aX, enforceFeeCeiling as aY, exchange as aZ, feedFetch as a_, type OfferPreparation as aa, type OnchainClaim as ab, type OnchainRefund as ac, OperatorUnreachable as ad, type ParsedRfqQuote as ae, type PayOptions as af, type PayResult as ag, type QuoteCheck as ah, QuoteExpired as ai, type QuotePreparation as aj, QuoteVerificationFailed as ak, REGISTRY_URL as al, type ReceiveArtifact as am, type ReceiveOptions as an, type ReceiveRequest as ao, type RecoveryResult as ap, type RegisteredAsset as aq, type RfqAuctionPolicy as ar, type RfqPreparation as as, type RfqQuoteInput as at, type RfqRendezvous as au, type RfqTransportFactory as av, type RouteSide as aw, SWAP_ERROR_NAMES as ax, type SwapClient as ay, type SwapClientConfig as az, type CorridorSet as b, isAddressable as b0, isCardMarket as b1, isIndexedNetwork as b2, isSwapError as b3, isUsableCard as b4, liveArkadeInfo as b5, marketBackendOf as b6, marketKeyOf as b7, marketOf as b8, marketRefOf as b9, nostrTransportFactory as ba, parseRfqQuote as bb, pay as bc, quoteFromFeed as bd, quoteViaRfq as be, readableRecord as bf, receive as bg, resolveCorridorBase as bh, resolveCorridorDeps as bi, rfqLeg as bj, rfqPairFor as bk, swapRecordOf as bl, toDiscoveryLeg as bm, unsignedPsbtBytes as bn, usableMarkets as bo, verifyJointGraph as bp, verifyOfferFillPlan as bq, verifyPlanLegs as br, withCanonicalAmount as bs, type DiscoveryLeg as c, type DiscoverySnapshot as d, AcceptConflict as e, type AcceptInput as f, type AcceptOptions as g, AmbiguousDestination as h, AmountEncodingUnsupported as i, AmountMismatch as j, type AssetRfqPreparation as k, type AttestingRfqTransport as l, CORRIDOR_FACTORIES as m, type CancelInput as n, type CancelOutcome as o, type ClaimedDestination as p, ClientDisposed as q, type CorridorBase as r, type CorridorClaim as s, type CorridorCovenant as t, type CorridorDeadline as u, type CorridorDeps as v, type CorridorDepsByCorridor as w, type CorridorDrive as x, type CorridorLockup as y, type CorridorModule as z };
|