@arkade-os/swap 0.1.0-rc.8 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/README.md +45 -10
  2. package/dist/advanced.cjs +6429 -3083
  3. package/dist/advanced.d.cts +325 -282
  4. package/dist/advanced.d.ts +325 -282
  5. package/dist/advanced.js +343 -34
  6. package/dist/chunk-A3SHHRX4.js +104 -0
  7. package/dist/chunk-FMRAV77W.js +3065 -0
  8. package/dist/{chunk-HV7EIUE2.js → chunk-HRMWBULL.js} +1773 -634
  9. package/dist/chunk-WKJFXXSR.js +3382 -0
  10. package/dist/index.cjs +6868 -3837
  11. package/dist/index.d.cts +71 -243
  12. package/dist/index.d.ts +71 -243
  13. package/dist/index.js +139 -167
  14. package/dist/lockupContract-D7BNjksX.d.ts +148 -0
  15. package/dist/lockupContract-G-9CNRMq.d.cts +148 -0
  16. package/dist/node/index.cjs +61 -10
  17. package/dist/node/index.d.cts +310 -639
  18. package/dist/node/index.d.ts +310 -639
  19. package/dist/node/index.js +65 -10
  20. package/dist/nostr.cjs +428 -49
  21. package/dist/nostr.d.cts +59 -70
  22. package/dist/nostr.d.ts +59 -70
  23. package/dist/nostr.js +268 -36
  24. package/dist/offer-CcJfx5Fj.d.cts +269 -0
  25. package/dist/offer-DdB1M6FZ.d.ts +269 -0
  26. package/dist/offerFillPlan-BII0PW92.d.cts +1642 -0
  27. package/dist/offerFillPlan-CNTLVD7j.d.ts +1642 -0
  28. package/dist/protocol.cjs +5591 -4064
  29. package/dist/protocol.d.cts +258 -355
  30. package/dist/protocol.d.ts +258 -355
  31. package/dist/protocol.js +209 -228
  32. package/dist/repositories/realm/index.cjs +55 -11
  33. package/dist/repositories/realm/index.d.cts +18 -30
  34. package/dist/repositories/realm/index.d.ts +18 -30
  35. package/dist/repositories/realm/index.js +49 -12
  36. package/dist/repositories/sqlite/index.cjs +61 -10
  37. package/dist/repositories/sqlite/index.d.cts +7 -6
  38. package/dist/repositories/sqlite/index.d.ts +7 -6
  39. package/dist/repositories/sqlite/index.js +57 -11
  40. package/dist/repository-DmPzpbd7.d.ts +2342 -0
  41. package/dist/repository-DqdLVrVv.d.cts +2342 -0
  42. package/dist/rfq-C0tHOvn6.d.cts +983 -0
  43. package/dist/rfq-C0tHOvn6.d.ts +983 -0
  44. package/dist/watch-BonYT9af.d.cts +74 -0
  45. package/dist/watch-CmJQDtsy.d.ts +74 -0
  46. package/package.json +12 -12
  47. package/dist/chunk-4PATNGYQ.js +0 -3297
  48. package/dist/chunk-ARYFNDJY.js +0 -1432
  49. package/dist/chunk-U7VWWTL6.js +0 -66
  50. package/dist/errors-CSpOUdCN.d.ts +0 -2216
  51. package/dist/errors-DVn92LQd.d.cts +0 -2216
  52. package/dist/lockupContract-6TYZOBbn.d.ts +0 -490
  53. package/dist/lockupContract-aLCQQiSu.d.cts +0 -490
  54. package/dist/repository-D0gFF_GA.d.cts +0 -3491
  55. package/dist/repository-tDT8p-Nx.d.ts +0 -3491
  56. package/dist/rfq-DhkgiwQ7.d.cts +0 -1126
  57. package/dist/rfq-DhkgiwQ7.d.ts +0 -1126
  58. package/dist/watch-C4cMEeZT.d.cts +0 -96
  59. package/dist/watch-DbWXdpzm.d.ts +0 -96
package/dist/index.d.ts CHANGED
@@ -1,11 +1,12 @@
1
- export { e as AcceptConflict, g as AmbiguousDestination, h as AmountEncodingUnsupported, i as AmountMismatch, A as AssetAliasTable, m as CancelOutcome, o as ClientDisposed, y as CorridorOverrides, B as DiscoveryConfig, d as DiscoverySnapshot, F as DiscoverySnapshotUnavailable, G as DriveMode, I as ExchangeOptions, K as FeeCeiling, R as InconsistentRoute, T as InsufficientFunds, V as Market, W as MaxFeeExceeded, X as MissingCorridorDep, Y as NotCancellable, a1 as OperatorUnreachable, a3 as PayOptions, a4 as PayResult, a5 as QuoteCheck, a6 as QuoteExpired, a8 as QuoteVerificationFailed, a9 as REGISTRY_URL, aa as ReceiveArtifact, ab as ReceiveOptions, ac as ReceiveRequest, ad as RecoveryResult, ae as RegisteredAsset, af as RfqAuctionPolicy, aj as RfqTransportFactory, al as SWAP_ERROR_NAMES, am as SwapClient, an as SwapClientConfig, aq as SwapDriveRefusedError, ar as SwapError, as as SwapErrorName, at as SwapFilter, S as SwapPolicy, au as UnsupportedRoute, av as VerbDeps, az as canonicalAssetId, aE as createSwapClient, aJ as exchange, aO as isSwapError, aW as pay, a_ as receive } from './errors-CSpOUdCN.js';
2
- import { c as AssetSwapRepository, aW as AssetSwap, d as RfqSwapRecord, S as SwapRecord, aX as MarketsCacheEntry, a1 as Outcome, ag as Swap, i as QuoteInput, f as RouteResolution, a3 as Quote, aj as SwapUpdate, ak as Unsubscribe } from './repository-tDT8p-Nx.js';
3
- export { l as ARKADE_ASSET_NAMESPACE, m as Amount, n as AmountFormatError, p as AmountRefusal, q as Artifact, A as AssetId, r as AssetIdError, s as AssetIdRefusal, t as AssetNamespace, u as AssetOn, v as AssetPart, w as AssetRef, x as AssetScale, y as AssetSwapId, z as AtomicDecimal, B as AuctionMarketRef, D as AuctionProvenance, E as BITCOIN_RAILS, F as BTC_ASSET_PART, G as BitcoinRail, K as CardMarketRef, M as CorridorId, T as CorridorKind, b as CorridorSwapRecord, U as DepositArtifact, V as DisplayDecimal, W as Endpoint, X as Ep, aY as InMemoryAssetSwapRepository, I as Instrument, L as LockupSpendIndexer, _ as MarketBackend, $ as MarketRef, N as NetworkRef, O as OfferSwapRecord, a2 as ParsedAssetId, P as PinnedAmount, Q as QuoteId, a4 as QuoteLeg, a5 as RAILS, R as Rail, a8 as RankedBid, a9 as RawState, aa as RecordedArtifact, ab as RecordedEndpoint, ac as RecordedInstrument, ad as RecordedLeg, g as ResolvedEndpoint, aZ as RfqSwapState, h as Route, af as SnapshotRef, a_ as SwapContractRegistry, ah as SwapFamily, a$ as SwapOperator, ai as SwapRecordCommon, al as arkadeAsset, an as assetPartOf, ao as assetSwapIdOf, ap as bitcoinNetworkOf, aq as btcOn, av as familyOfSwapId, aw as formatAssetId, ax as fromAtomicDecimal, aB as isAssetId, aC as isAtomicDecimal, aD as isNetworkRef, b0 as isRfqSwapTerminal, aE as issuanceOf, aH as parseAssetId, aI as quoteIdOfSwapId, aJ as railOf, aR as sameAsset, aT as toAtomicDecimal } from './repository-tDT8p-Nx.js';
4
- export { C as ChainSource, I as InvoiceFacts, a as RFQ_REFUSAL_ERROR_CODES, b as RfqRefusalDetail, c as RfqRefusalErrorCode, d as RfqRefusalUnit, S as SwapRefusal, i as isRfqRefusalErrorCode } from './rfq-DhkgiwQ7.js';
5
- import { IWallet, PaymentHandle, PaymentRail, RouterPreferences, Wallet, PaymentRouter, PaymentStatus } from '@arkade-os/sdk';
6
- import { R as RestoreIndexer, T as Tx } from './lockupContract-6TYZOBbn.js';
7
- export { L as LockupRegistrationFailed } from './lockupContract-6TYZOBbn.js';
1
+ export { e as AcceptConflict, g as AcceptOptions, h as AmbiguousDestination, i as AmountEncodingUnsupported, j as AmountMismatch, A as AssetAliasTable, B as BuildOfferFillPlanOpts, o as CancelOutcome, q as ClientDisposed, E as CorridorOverrides, H as DEFAULT_MAX_REFUND_WINDOW_SECONDS, I as DiscoveryConfig, d as DiscoverySnapshot, K as DiscoverySnapshotUnavailable, N as DriveMode, Q as ExchangeOptions, T as FeeCeiling, W as FillSponsor, X as FillSponsorFare, Z as InconsistentRoute, _ as InsufficientFunds, $ as JointGraph, a1 as Market, a2 as MaxFeeExceeded, a3 as MissingCorridorDep, a4 as NotCancellable, a5 as OFFER_FILL_OWNERS, a6 as OFFER_FILL_TEMPLATE, ac as OperatorUnreachable, ae as PayOptions, af as PayResult, ag as QuoteCheck, ah as QuoteExpired, aj as QuoteVerificationFailed, ak as REGISTRY_URL, al as ReceiveArtifact, am as ReceiveOptions, an as ReceiveRequest, ao as RecoveryResult, ap as RegisteredAsset, aq as RfqAuctionPolicy, au as RfqTransportFactory, aw as SWAP_ERROR_NAMES, ax as SwapClient, ay as SwapClientConfig, aB as SwapDriveRefusedError, aC as SwapError, aD as SwapErrorName, aE as SwapFilter, S as SwapPolicy, aF as UnsupportedRoute, aG as VerbDeps, aJ as buildOfferFillPlan, aL as canonicalAssetId, aR as createSwapClient, aT as deepFreeze, aU as digestJointGraph, aY as exchange, b2 as isSwapError, ba as pay, be as receive, bl as unsignedPsbtBytes, bn as verifyJointGraph, bo as verifyOfferFillPlan } from './offerFillPlan-CNTLVD7j.js';
2
+ import { d as AssetSwapRepository, h as AssetSwap, e as RfqSwapRecord, f as RfqSwapPageFilter, g as RfqSwapPageCursor, S as SwapRecord, b9 as MarketsCacheEntry, a7 as Outcome, ap as Swap, l as QuoteInput, i as RouteResolution, a9 as Quote, as as SwapUpdate, au as Unsubscribe } from './repository-DmPzpbd7.js';
3
+ export { o as ARKADE_ASSET_NAMESPACE, p as Amount, q as AmountFormatError, s as AmountRefusal, t as ArkadeCarrierChoice, u as Artifact, A as AssetId, v as AssetIdError, w as AssetIdRefusal, x as AssetNamespace, y as AssetOn, z as AssetPart, B as AssetPaymentInput, D as AssetPaymentTerms, E as AssetRef, F as AssetScale, G as AssetSwapId, H as AtomicDecimal, J as AuctionMarketRef, K as AuctionProvenance, M as BITCOIN_RAILS, T as BTC_ASSET_PART, U as BitcoinRail, X as CardMarketRef, Y as CorridorId, Z as CorridorKind, b as CorridorSwapRecord, _ as DepositArtifact, $ as DisplayDecimal, a0 as Endpoint, a1 as Ep, ba as InMemoryAssetSwapRepository, I as Instrument, L as LockupSpendIndexer, a4 as MarketBackend, a5 as MarketRef, N as NetworkRef, O as OfferSwapRecord, a8 as ParsedAssetId, P as PinnedAmount, Q as QuoteId, aa as QuoteLeg, ab as RAILS, R as Rail, ae as RankedBid, af as RawState, ag as ReceiverPaidCarrierQuote, ah as RecordedArtifact, ai as RecordedAssetPayment, aj as RecordedEndpoint, ak as RecordedInstrument, al as RecordedLeg, j as ResolvedEndpoint, am as RestoredMarketRef, bb as RfqSwapState, k as Route, ao as SnapshotRef, bc as SwapContractRegistry, aq as SwapFamily, bd as SwapOperator, ar as SwapRecordCommon, at as TaxiIdentity, av as VerifiedCarrierTerms, aw as arkadeAsset, ay as assetPartOf, az as assetSwapIdOf, aA as bitcoinNetworkOf, aB as btcAssetPart, aC as btcOn, aH as familyOfSwapId, aI as formatAssetId, aJ as fromAtomicDecimal, aO as isAssetId, aP as isAtomicDecimal, aQ as isBtcAsset, aR as isBtcAssetLenient, aS as isNetworkRef, be as isRfqSwapTerminal, aT as issuanceOf, aW as parseAssetId, aX as quoteIdOfSwapId, aY as railOf, b4 as sameAsset, b6 as toAtomicDecimal } from './repository-DmPzpbd7.js';
4
+ export { C as ChainSource, I as InvoiceFacts, a as RFQ_REFUSAL_ERROR_CODES, b as RfqRefusalDetail, c as RfqRefusalErrorCode, d as RfqRefusalUnit, S as SwapRefusal, T as TxStatus, i as isRfqRefusalErrorCode } from './rfq-C0tHOvn6.js';
5
+ import { PageRequest, PageResult, PaymentHandle, PaymentRail, RouterPreferences, Wallet, PaymentRouter, PaymentStatus } from '@arkade-os/sdk';
6
+ export { C as CLAIM_PACKET_TYPE, a as ClaimPacketShape, L as LockupRegistrationFailed, S as SEALED_CIPHERTEXT_LENGTH, b as appendArkadeScript, c as claimPacketShape } from './lockupContract-D7BNjksX.js';
8
7
  import '@arkade-os/solver-discovery';
8
+ import './offer-DdB1M6FZ.js';
9
+ import 'nostr-tools';
9
10
 
10
11
  /** Browser backend over the SDK's shared IndexedDB manager. */
11
12
  declare class IndexedDbAssetSwapRepository implements AssetSwapRepository {
@@ -19,14 +20,16 @@ declare class IndexedDbAssetSwapRepository implements AssetSwapRepository {
19
20
  * transaction, which `awaitTransaction` reports. */
20
21
  private write;
21
22
  saveSwap(swap: AssetSwap): Promise<void>;
22
- getAllSwaps(): Promise<AssetSwap[]>;
23
+ getAssetSwapsPage(page: PageRequest): Promise<PageResult<AssetSwap>>;
23
24
  saveRfqSwap(record: RfqSwapRecord): Promise<void>;
24
25
  getRfqSwap(rfqId: string): Promise<RfqSwapRecord | undefined>;
25
- getAllRfqSwaps(): Promise<RfqSwapRecord[]>;
26
+ getRfqSwapsPage(filter: RfqSwapPageFilter, page: PageRequest<RfqSwapPageCursor>): Promise<PageResult<RfqSwapRecord, RfqSwapPageCursor>>;
26
27
  removeRfqSwap(rfqId: string): Promise<void>;
27
28
  saveSwapRecord(record: SwapRecord): Promise<void>;
28
29
  getSwapRecord(id: string): Promise<SwapRecord | undefined>;
29
- getAllSwapRecords(): Promise<SwapRecord[]>;
30
+ getSwapRecordsPage(page: PageRequest): Promise<PageResult<SwapRecord>>;
31
+ private pageStore;
32
+ private resultOfPage;
30
33
  removeSwapRecord(id: string): Promise<void>;
31
34
  getScannedTxids(): Promise<Set<string>>;
32
35
  markTxidsScanned(txids: Iterable<string>): Promise<void>;
@@ -39,94 +42,19 @@ declare class IndexedDbAssetSwapRepository implements AssetSwapRepository {
39
42
  [Symbol.asyncDispose](): Promise<void>;
40
43
  }
41
44
 
42
- interface AssetSwapRestoreChange {
43
- /** The stored record before this restore; absent for a rebuilt record. */
44
- previous?: AssetSwap;
45
- /** The record persisted by this restore. */
46
- current: AssetSwap;
47
- }
48
- interface RestoreAssetSwapRepositoryOptions {
49
- wallet: IWallet;
50
- indexer: RestoreIndexer;
51
- repository: AssetSwapRepository;
52
- txs: Tx[];
53
- /** The operator key the restored covenants were funded against, x-only. */
54
- operatorPubkey: Uint8Array;
55
- /** Add consumer-owned metadata to a newly rebuilt record before it is saved. */
56
- prepareNew?: (swap: AssetSwap) => AssetSwap | Promise<AssetSwap>;
57
- /** Stops repository writes and coverage work after an in-flight scan returns. */
58
- signal?: AbortSignal;
59
- }
60
- interface RestoreAssetSwapRepositoryResult {
61
- /** The repository's newest-first state after this operation. */
62
- swaps: AssetSwap[];
63
- /** Every record this operation inserted or updated. */
64
- changes: AssetSwapRestoreChange[];
65
- /** Funding txids newly added to the durable scan cursor. */
66
- scannedTxids: string[];
67
- /** Set when the caller cancelled before the operation could commit. */
68
- aborted: boolean;
69
- /** Coverage setup failed after records were safely persisted. Retry is safe. */
70
- coverageError?: unknown;
71
- }
72
- /**
73
- * Restore the durable asset-swap state for one wallet.
74
- *
75
- * This is the consumer entry point above the two lower-level recovery
76
- * primitives: it reads the repository, reopens every live record, persists
77
- * rebuilt records and outcomes before advancing the scan cursor, then restores
78
- * the wallet-contract coverage needed by the live watcher. Consumers keep only
79
- * presentation work (for example decorating a new record or announcing a
80
- * returned change).
81
- *
82
- * Scan and persistence failures reject. Coverage setup is different: records
83
- * are already safe by then, so its error is returned as `coverageError` and a
84
- * later call can retry without losing or duplicating anything.
85
- */
86
- declare function restoreAssetSwapRepository(opts: RestoreAssetSwapRepositoryOptions): Promise<RestoreAssetSwapRepositoryResult>;
87
-
88
- interface RegisterAssetSwapRestoreOptions {
89
- repository: AssetSwapRepository;
90
- indexer?: RestoreIndexer;
91
- operatorPubkey?: Uint8Array;
92
- prepareNew?: RestoreAssetSwapRepositoryOptions["prepareNew"];
93
- onResult?: (result: RestoreAssetSwapRepositoryResult) => void | Promise<void>;
94
- }
95
- declare function registerAssetSwapRestore(wallet: IWallet, options: RegisterAssetSwapRestoreOptions): () => void;
96
-
97
45
  /**
98
- * What the two v2 swap rails share: the client seam, the quote arithmetic, and
99
- * the handle that observes a swap through core's four-state stream.
100
- *
101
- * A rail here is a thin adapter and deliberately nothing more. Persistence,
102
- * refunds, recovery and the outcome vocabulary all live behind the v2 client;
103
- * the rail's whole job is to turn a `PaymentRequest` into a `QuoteInput`, a
104
- * `Quote` into a receiver-exact `RouteQuote`, and a swap's outcome stream into
105
- * a `PaymentHandle`.
106
- *
107
- * Two boundaries are crossed here and both are named. Amounts narrow from P3's
108
- * `bigint` to core's `number` (see `client/sats.ts`). And a ranking estimate
109
- * meets a binding quote: `RouteQuote.fee` is documented as "a display and
110
- * ranking figure, not a guarantee" while a v2 `Quote` is verified before return
111
- * and expires. `PaymentOption.quote()` is lazy and `options()` never calls it,
112
- * so ranking is free — but a swap rail's `quote()` is an RFQ round trip that
113
- * discloses an invoice and an amount, and an app that ranks then quotes several
114
- * options would disclose to every solver. `available()` therefore **never
115
- * quotes**: it resolves, which is network-free against the cached snapshot.
116
- *
117
- * A held `RouteQuote` can outlive its `Quote` — core's shape carries no
118
- * `expiresAt` — and then `send()` throws `QuoteExpired` inside `makeHandle`'s
119
- * run, which core turns into a terminal `failed`. That stays: re-quoting inside
120
- * `send()` is the silent re-quote §3.2 forbids.
46
+ * What the two v2 swap rails share: the client seam, the quote arithmetic, and the handle that
47
+ * observes a swap through core's four-state stream. A rail is a thin adapter; persistence, refunds,
48
+ * recovery and outcomes live behind the v2 client.
49
+ *
50
+ * Amounts narrow from `bigint` to core's `number` here (see `client/sats.ts`). `available()`
51
+ * **never quotes**: a swap rail's `quote()` is an RFQ round trip disclosing an invoice and amount, so
52
+ * ranking must not call it — it resolves, network-free against the cached snapshot. A held
53
+ * `RouteQuote` can outlive its `Quote` (core's shape has no `expiresAt`); `send()` then fails with
54
+ * `QuoteExpired` rather than silently re-quoting.
121
55
  */
122
56
 
123
- /**
124
- * The slice of `SwapClient` a rail uses.
125
- *
126
- * Structural and minimal, so what a rail can reach is visible in one place and
127
- * a test can stand in for it without a wallet, a repository or a solver behind
128
- * it. A full `SwapClient` satisfies it.
129
- */
57
+ /** The minimal structural slice of `SwapClient` a rail uses, so a test can stand in for it. */
130
58
  interface SwapRailClient {
131
59
  resolve(input: QuoteInput): Promise<RouteResolution>;
132
60
  quote(input: QuoteInput): Promise<Quote>;
@@ -134,13 +62,9 @@ interface SwapRailClient {
134
62
  onUpdate(fn: (update: SwapUpdate) => void): Unsubscribe;
135
63
  }
136
64
  /**
137
- * A payment that ended in something other than success.
138
- *
139
- * Not a member of §7's taxonomy and suffixed to say so: that taxonomy is thrown
140
- * *before* value moves, and this is an outcome reported after it did. It exists
141
- * to carry the {@link Outcome} onto the handle's terminal `error`, which is
142
- * where `refunded` and `lapsed` stay distinguishable after the four-state
143
- * projection has mapped both to `failed`.
65
+ * A payment that ended in something other than success. Not part of the error taxonomy (thrown
66
+ * *before* value moves): this is an outcome reported after, carrying the {@link Outcome} so
67
+ * `refunded` and `lapsed` stay distinguishable once both project to `failed`.
144
68
  */
145
69
  declare class SwapPaymentFailedError extends Error {
146
70
  readonly railId: string;
@@ -152,15 +76,9 @@ declare class SwapPaymentFailedError extends Error {
152
76
  /** `eligible > 0` for this input, or false for anything that will not route. */
153
77
  declare const railAvailable: (client: SwapRailClient, input: QuoteInput) => Promise<boolean>;
154
78
  /**
155
- * The three receiver-exact numbers, checked against each other.
156
- *
157
- * `total === amount + fee` is core's contract and this is where a rail proves
158
- * it rather than asserting it in a comment: `amount` is what the recipient
159
- * gets, `fee` is what the rail and its counterparty charge on top, and `total`
160
- * is what leaves the wallet. A `Quote` whose give leg does not equal the take
161
- * leg plus the spread has broken an invariant M3 owns, and surfacing it here
162
- * beats quoting a number that would rank this rail against the collaborative
163
- * exit on a fee it does not charge.
79
+ * The three receiver-exact numbers, checked: `total === amount + fee` is core's contract (`amount`
80
+ * delivered, `fee` on top, `total` leaving the wallet). A violation is surfaced rather than ranked
81
+ * against the collaborative exit on a fee this rail does not charge.
164
82
  */
165
83
  declare const receiverExact: (railId: string, parts: {
166
84
  amount: bigint;
@@ -172,85 +90,43 @@ declare const receiverExact: (railId: string, parts: {
172
90
  total: number;
173
91
  };
174
92
  /**
175
- * Accept the quote, then observe it to its first terminal outcome.
176
- *
177
- * The handle's contract, stated once: it observes the payment up to and
178
- * including the first terminal outcome, and every recovery past that point is
179
- * observed on `client.onUpdate` — keyed by the tagged `RouteResult.swapId`, so
180
- * the two views join. `client.onUpdate` replays synchronously on subscribe, so
181
- * a swap that was already terminal by the time we subscribed still resolves.
93
+ * Accept the quote, then observe it up to its first terminal outcome; recovery past that is observed
94
+ * on `client.onUpdate`, keyed by the same `RouteResult.swapId`. `onUpdate` replays synchronously, so
95
+ * an already-terminal swap still resolves.
182
96
  */
183
97
  declare const swapHandle: (railId: string, client: SwapRailClient, quote: Quote) => Promise<PaymentHandle>;
184
98
 
185
99
  /**
186
- * `lightning` — pay a BOLT11 invoice out of an Arkade balance, through the v2
187
- * swap client.
188
- *
189
- * The rail id is a registry key with published history: the factory deleted
190
- * with `packages/boltz-swap` registered `"lightning"`, and a key is what an
191
- * app's `priority` array and `disabled` list name. It therefore stays
192
- * `lightning` even though Q12 renamed the lightning *asset* namespace to
193
- * `bolt11` — the divergence between a registry key and an asset vocabulary is
194
- * recorded here, not resolved by a rename that would break every consumer's
195
- * preferences.
100
+ * `lightning` — pay a BOLT11 invoice out of an Arkade balance, through the v2 swap client.
196
101
  *
197
- * The whole rail is an adapter. The invoice fixes the amount, the client
198
- * verifies and prices the route, `accept()` persists before it funds, and the
199
- * drive owns everything after — so there is no `persist`, no `awaitSettlement`
200
- * and no solver selection to configure here.
102
+ * The rail id stays `lightning` although the asset namespace is `bolt11`: it is a published registry
103
+ * key that apps' `priority` and `disabled` lists name, so renaming would break their preferences.
104
+ * The rail is only an adapter; persistence, settlement and solver selection live in the client.
201
105
  */
202
106
 
203
107
  declare const LIGHTNING_RAIL = "lightning";
204
- /**
205
- * Register alongside core's rails. The deleted factory's ranking was
206
- * `["ark", "lightning", "onchain-swap", "onchain"]`; see
207
- * {@link createSwapPaymentRouter}.
208
- */
108
+ /** Register alongside core's rails; see {@link createSwapPaymentRouter} for the ranking. */
209
109
  declare function lightningRail(client: SwapRailClient): PaymentRail;
210
110
 
211
111
  /**
212
- * `onchain-swap` — pay an L1 address out of an Arkade balance through a solver,
213
- * via the v2 swap client.
214
- *
215
- * Registered alongside core's `onchain` rail (the collaborative exit) and
216
- * ranked ahead of it, with both left registered: the default is a *preference*,
217
- * not a restriction. The preference self-heals by amount — an out-of-range
218
- * request drops this rail at `available()` and `onchain` wins with no error.
219
- *
220
- * The id is the deleted factory's published registry key, `"onchain-swap"`,
221
- * kept for the reason the `lightning` rail keeps its own: a rail id is what an
222
- * app's `priority` array names.
223
- *
224
- * **The claim fee is this rail's whole subtlety.** On `arkade -> onchain` the
225
- * trader claims the solver's L1 HTLC itself, and that claim's fee comes out of
226
- * the HTLC output — `payout = utxo.amount - fee`. So the sats the recipient
227
- * actually receives are less than the sats the solver locks, by an amount the
228
- * swap quote knows nothing about. A rail that quoted the solver's spread alone
229
- * would be reporting a fee it does not charge, and would win a ranking against
230
- * the collaborative exit that it should lose.
231
- *
232
- * This rail therefore takes a claim fee-rate policy at construction and grosses
233
- * the swap up by the estimate: it asks the solver for `amount + claimFee` on the
234
- * take leg, so what lands after the claim is the `amount` the caller asked for,
235
- * and it reports the estimate inside `fee` where a ranking can see it. A fee
236
- * rate is environment-specific and is nobody's to default — the same reason
237
- * `CorridorOverrides.onchain.claim` has no default.
238
- *
239
- * The same arithmetic gives the rail its floor: a payout under
240
- * {@link ONCHAIN_DUST_SATS} is one `buildHtlcClaim` refuses to build, so an
241
- * amount that small drops the rail at `available()` and is refused outright at
242
- * `quote()` — before a lockup exists, rather than after one is funded.
112
+ * `onchain-swap` — pay an L1 address out of an Arkade balance through a solver, via the v2 swap
113
+ * client. Ranked ahead of core's `onchain` rail with both registered: an out-of-range request
114
+ * drops this rail at `available()` and `onchain` wins with no error. The id is what an app's
115
+ * `priority` array names, so it must stay `"onchain-swap"`.
116
+ *
117
+ * **The claim fee.** The trader claims the solver's L1 HTLC itself and the fee comes out of the
118
+ * output (`payout = utxo.amount - fee`), which the swap quote knows nothing about. So the rail
119
+ * grosses the take leg up by the estimated claim fee and reports it inside `fee`; quoting the
120
+ * spread alone would understate the cost and win rankings it should lose. A payout under
121
+ * {@link ONCHAIN_DUST_SATS} is refused before a lockup exists, not after one is funded.
243
122
  */
244
123
 
245
124
  declare const ONCHAIN_SWAP_RAIL = "onchain-swap";
246
125
  interface OnchainSwapRailDeps {
247
126
  /**
248
- * Sat/vB the trader's L1 claim will be built at — the rate the corridor's
249
- * own `claim` dep will use.
250
- *
251
- * No default, and the rail refuses to exist without it: the fee comes out
252
- * of the recipient's payout, so a rail with no rate either quotes a fee it
253
- * does not charge or short-pays the recipient. Neither is a default.
127
+ * Sat/vB the trader's L1 claim will be built at — the rate the corridor's own `claim` dep
128
+ * uses. Required: without it the rail either quotes a fee it does not charge or short-pays
129
+ * the recipient.
254
130
  */
255
131
  readonly claimFeeRateSatVb: number;
256
132
  /** vsize the claim is priced at. Defaults to {@link ONCHAIN_CLAIM_VSIZE}. */
@@ -266,96 +142,48 @@ declare const claimFeeSats: (deps: OnchainSwapRailDeps) => bigint;
266
142
  declare function onchainSwapRail(client: SwapRailClient, deps: OnchainSwapRailDeps): PaymentRail;
267
143
 
268
144
  /**
269
- * The router that puts lightning and `arkade -> onchain` back into a payment
270
- * app's reach.
271
- *
272
- * Core's `createDefaultPaymentRouter(wallet)` registers `ark` and `onchain` and
273
- * nothing else. The two swap rails never lived there — they were in
274
- * `packages/boltz-swap`, behind a second overload with the priority
275
- * `["ark", "lightning", "onchain-swap", "onchain"]`, and ts-sdk #811 removed
276
- * them along with the package. This is that overload's shape, rebuilt on the v2
277
- * client.
145
+ * A payment router with the lightning and `arkade -> onchain` swap rails on top of core's
146
+ * `ark` and `onchain`. The rails close over their own deps rather than widening core's
147
+ * published `RouterContext` (whose legacy `swaps` slot is ignored).
278
148
  *
279
- * **The rails close over their own dependencies, and `RouterContext` is not
280
- * re-opened.** Widening core's context further was the alternative and it is
281
- * the wrong half: it edits a published payment type and asks core to name
282
- * things it cannot — a repository, a transport, a discovery index. (Core's
283
- * context carries an optional `swaps` slot for the legacy boltz-swap rails;
284
- * these rails ignore it.) A rail factory over an already-constructed
285
- * `SwapClient` names none of that in core.
286
- *
287
- * This factory stays out of core's own, which is pinned at exactly
288
- * `["ark", "onchain"]`. Registering the swap rails is the app's decision, and
289
- * the ranking it gets is a *preference*: both `onchain-swap` and `onchain` stay
290
- * registered, so an amount outside the solver's range drops the swap rail at
291
- * `available()` and the collaborative exit wins with no error.
149
+ * Both `onchain-swap` and `onchain` stay registered, so an amount outside the solver's
150
+ * range drops the swap rail at `available()` and the collaborative exit wins, no error.
292
151
  */
293
152
 
294
- /** The deleted factory's ranking, and the one this factory ships. */
153
+ /** The ranking this factory ships (the removed boltz-swap overload's). */
295
154
  declare const SWAP_ROUTER_PRIORITY: readonly string[];
296
155
  interface SwapPaymentRouterConfig extends OnchainSwapRailDeps {
297
156
  /** Overrides the shipped ranking; `disabled`, `caps` and `tieBreak` pass through. */
298
157
  readonly prefs?: RouterPreferences;
299
158
  }
300
159
  /**
301
- * Core's four rails plus the two this package supplies, ranked as the deleted
302
- * factory ranked them.
160
+ * Core's rails plus the two this package supplies, ranked by {@link SWAP_ROUTER_PRIORITY}.
303
161
  *
304
- * Takes the concrete `Wallet` — it fits core's `IWallet`-typed
305
- * `RouterContext`, and only the concrete class reaches `arkProvider`, which
306
- * the `onchain` rail's fee source needs — and the already-constructed client,
307
- * because building one here would put storage, discovery and corridor policy
308
- * behind a payment-router call that has no business deciding any of them.
162
+ * Takes the concrete `Wallet` because only it reaches `arkProvider`, which the `onchain`
163
+ * rail's fee source needs; and an already-constructed client so storage, discovery and
164
+ * corridor policy are not decided behind a router call.
309
165
  */
310
166
  declare function createSwapPaymentRouter(wallet: Wallet, client: SwapRailClient, config: SwapPaymentRouterConfig): PaymentRouter;
311
167
 
312
168
  /**
313
- * Fourteen outcomes onto four payment statuses — the only artefact M7 mints.
314
- *
315
- * Declared **total** even though a send rail cannot reach every member, because
316
- * a partial map is where the collapse hides: an outcome with no row does not
317
- * fail loudly, it renders as whatever the lookup happens to return.
169
+ * Fourteen outcomes onto four payment statuses.
318
170
  *
319
- * The projection is lossy by construction and the loss is recoverable, which is
320
- * the whole design. `refunded` and `lapsed` both land on `failed` — P6 exists so
321
- * those two never become one word, and the difference survives on the update's
322
- * `error`, which core's `PaymentHandle` docblock already reserves for it. No
323
- * fifth `PaymentStatus` is proposed: a status is what a payment UI branches on,
324
- * and "the trader's value came back" versus "the incoming payment never arrived"
325
- * is a sentence, not a branch.
171
+ * Total even where a send rail cannot reach a member: a partial map fails silently, rendering a
172
+ * missing outcome as whatever the lookup returns. `refunded` and `lapsed` both become `failed`;
173
+ * the difference survives on the update's `error`, not a fifth status.
326
174
  *
327
- * **Where the rail goes terminal is a decision, not a rounding.** It goes
328
- * terminal at `refunding`, not at `refunded`: `makeHandle` clears its subscriber
329
- * set on a terminal update and replays-without-registering afterwards, so the
330
- * `refunded` that follows could not reach that handle anyway — and holding
331
- * terminality back until the refund resolves would hang every
332
- * `settled({ timeoutMs })` caller for a whole refund window. The refund is
333
- * observed through `client.onUpdate` and `swaps()`, keyed by the tagged
334
- * `RouteResult.swapId`.
335
- *
336
- * The same rule answers the `unblock` backslide. `needs_recovery -> funded` is
337
- * a legal re-entry that crosses the terminality boundary the rail just drew; it
338
- * is emitted rather than swallowed, because the drive's idempotence key is the
339
- * DERIVED outcome and the second `funded` is a new key — delivered on
340
- * `client.onUpdate`, never through the handle, which stays terminal. A handle
341
- * observes a payment up to and including its first terminal outcome; every
342
- * recovery past that point is observed on the client's update stream.
175
+ * The rail goes terminal at `refunding`, not `refunded`: `makeHandle` drops subscribers on a
176
+ * terminal update, so `refunded` could not reach the handle anyway, and waiting would hang
177
+ * `settled({ timeoutMs })` for a whole refund window. Later updates (the refund, or an `unblock`
178
+ * `needs_recovery -> funded` re-entry) arrive on `client.onUpdate`, keyed by `RouteResult.swapId`.
343
179
  */
344
180
 
345
- /**
346
- * The projection, total over {@link Outcome}.
347
- *
348
- * The `on the rail` column of M7's table is not encoded here: a send rail
349
- * cannot reach `open`, `filled`, `cancelling`, `cancelled` or `lapsed`, but a
350
- * map that refused them would be a map with holes, and the point of totality is
351
- * that there are none.
352
- */
181
+ /** The projection, total over {@link Outcome}. */
353
182
  declare const PAYMENT_STATUS: {
354
183
  /** Persisted, funding not broadcast. */
355
184
  readonly accepted: "pending";
356
185
  readonly funding: "pending";
357
- /** The lockup is funded. Nothing has emitted `"sent"` in core since the
358
- * `onchain-swap` rail left with `packages/boltz-swap`. */
186
+ /** The lockup is funded. */
359
187
  readonly funded: "sent";
360
188
  /** Asset swaps only: an unfilled offer. */
361
189
  readonly open: "pending";
@@ -384,4 +212,4 @@ declare const paymentStatusOf: (outcome: Outcome) => PaymentStatus;
384
212
  /** Whether this status ends the handle's observation. Core's own rule. */
385
213
  declare const isTerminalStatus: (status: PaymentStatus) => boolean;
386
214
 
387
- export { AssetSwap, AssetSwapRepository, type AssetSwapRestoreChange, IndexedDbAssetSwapRepository, LIGHTNING_RAIL, MarketsCacheEntry, ONCHAIN_SWAP_RAIL, type OnchainSwapRailDeps, Outcome, PAYMENT_STATUS, Quote, QuoteInput, type RegisterAssetSwapRestoreOptions, type RestoreAssetSwapRepositoryOptions, type RestoreAssetSwapRepositoryResult, RouteResolution, SWAP_ROUTER_PRIORITY, Swap, SwapPaymentFailedError, type SwapPaymentRouterConfig, type SwapRailClient, SwapRecord, SwapUpdate, Unsubscribe, claimFeeSats, createSwapPaymentRouter, isTerminalStatus, lightningRail, onchainSwapRail, paymentStatusOf, railAvailable, receiverExact, registerAssetSwapRestore, restoreAssetSwapRepository, swapHandle };
215
+ export { AssetSwap, AssetSwapRepository, IndexedDbAssetSwapRepository, LIGHTNING_RAIL, MarketsCacheEntry, ONCHAIN_SWAP_RAIL, type OnchainSwapRailDeps, Outcome, PAYMENT_STATUS, Quote, QuoteInput, RfqSwapPageCursor, RfqSwapPageFilter, RouteResolution, SWAP_ROUTER_PRIORITY, Swap, SwapPaymentFailedError, type SwapPaymentRouterConfig, type SwapRailClient, SwapRecord, SwapUpdate, Unsubscribe, claimFeeSats, createSwapPaymentRouter, isTerminalStatus, lightningRail, onchainSwapRail, paymentStatusOf, railAvailable, receiverExact, swapHandle };