@arkade-os/swap 0.1.0-rc.2 → 0.1.0-rc.21

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 (54) hide show
  1. package/README.md +52 -2
  2. package/dist/advanced.cjs +8376 -0
  3. package/dist/advanced.d.cts +550 -0
  4. package/dist/advanced.d.ts +550 -0
  5. package/dist/advanced.js +451 -0
  6. package/dist/chunk-A3SHHRX4.js +104 -0
  7. package/dist/chunk-HUQQVBC4.js +4262 -0
  8. package/dist/{chunk-EOYGUCDM.js → chunk-ITFCQWPG.js} +755 -1382
  9. package/dist/chunk-PVB7EBAM.js +2517 -0
  10. package/dist/errors-C3h8ANmE.d.ts +1560 -0
  11. package/dist/errors-hm7aqnRM.d.cts +1560 -0
  12. package/dist/index.cjs +4861 -3988
  13. package/dist/index.d.cts +69 -2812
  14. package/dist/index.d.ts +69 -2812
  15. package/dist/index.js +179 -3719
  16. package/dist/lockupContract-5r5RlgOJ.d.cts +137 -0
  17. package/dist/lockupContract-5r5RlgOJ.d.ts +137 -0
  18. package/dist/node/index.cjs +61 -10
  19. package/dist/node/index.d.cts +249 -591
  20. package/dist/node/index.d.ts +249 -591
  21. package/dist/node/index.js +65 -10
  22. package/dist/nostr.cjs +191 -11
  23. package/dist/nostr.d.cts +23 -68
  24. package/dist/nostr.d.ts +23 -68
  25. package/dist/nostr.js +3 -4
  26. package/dist/offer-Bd9Yvd8Z.d.ts +261 -0
  27. package/dist/offer-F88rtL_I.d.cts +261 -0
  28. package/dist/protocol.cjs +4086 -3706
  29. package/dist/protocol.d.cts +163 -768
  30. package/dist/protocol.d.ts +163 -768
  31. package/dist/protocol.js +190 -173
  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-BuYWGAKz.d.cts +2261 -0
  41. package/dist/repository-DYnRLPt-.d.ts +2261 -0
  42. package/dist/rfq-60PGpQ_x.d.cts +950 -0
  43. package/dist/rfq-60PGpQ_x.d.ts +950 -0
  44. package/dist/watch-BTyiBLSd.d.ts +74 -0
  45. package/dist/watch-M_KY-5ho.d.cts +74 -0
  46. package/package.json +20 -10
  47. package/dist/chunk-LYCMM3VB.js +0 -1357
  48. package/dist/chunk-U7VWWTL6.js +0 -66
  49. package/dist/repository-_zU9_pM3.d.cts +0 -3426
  50. package/dist/repository-kO95noyv.d.ts +0 -3426
  51. package/dist/rfq-DdBV4JO5.d.cts +0 -1097
  52. package/dist/rfq-DdBV4JO5.d.ts +0 -1097
  53. package/dist/watch-CQqvwgwY.d.cts +0 -96
  54. package/dist/watch-wMbmfN4p.d.ts +0 -96
package/README.md CHANGED
@@ -15,13 +15,19 @@ const client = createSwapClient({ wallet, repository: new IndexedDbAssetSwapRepo
15
15
  Construction is synchronous and inert: no network, no wallet read, no repository open. The first
16
16
  call that needs one does it.
17
17
 
18
+ Market discovery needs no configuration either: the client defaults to the reference solver
19
+ registry's index for the wallet's network (`REGISTRY_URL[network]`, exported). Follow your own
20
+ registry instead with `discovery: { registryUrl }`, or opt out of registries entirely with
21
+ `discovery: { registryUrl: null }` — `discovery: { snapshot }` resolves against a fixed market
22
+ list without touching the network.
23
+
18
24
  ## The four routes
19
25
 
20
26
  Each is one `quote` → `accept` chain. `quote` returns binding, verified terms and touches nothing
21
27
  durable; `accept` writes the record, then funds.
22
28
 
23
29
  ```ts
24
- const BTC = btcOn("arkade", "bitcoin"); // arkade:bitcoin/slip44:0
30
+ const BTC = btcOn("arkade", "bitcoin"); // arkade:bitcoin/slip44:0 (slip44:1 on test networks)
25
31
  const USDT = "arkade:bitcoin/asset:…";
26
32
 
27
33
  // arkade -> lightning: pay an invoice. The amount is the invoice's.
@@ -51,6 +57,17 @@ ordering from the caller.
51
57
  `onchain -> arkade` is not in the union. It resolves and quotes to `UnsupportedRoute` until the
52
58
  client owns the trader's L1 refund path end to end.
53
59
 
60
+ An `arkade -> onchain` withdrawal claims the solver's L1 HTLC itself, and that claim's miner fee
61
+ comes out of the HTLC output — so the client grosses the take leg up by the claim's cost and the
62
+ recipient nets exactly the `amount` written, with the estimate folded into the reported `fee`. The
63
+ claim is built and broadcast by the client itself once the fill is claimable, signed by the
64
+ wallet's payout key and priced off a per-network fee-rate floor
65
+ (`discovery`/corridor overrides aside, that floor is the only environment-specific input). A
66
+ routing UI should raise it in congestion — the claim has a consensus deadline — via
67
+ `corridors: { onchain: { claimFeeRateSatVb } }`; set it to `null` to take the claim over manually
68
+ (the drive then reports the L1 half as your job rather than blocking it). Wire your own builder
69
+ with `corridors: { onchain: { claim } }` and it wins over the default.
70
+
54
71
  ### One call instead of two
55
72
 
56
73
  `pay`, `receive` and `exchange` are `quote` → fee ceiling → `accept`, and add no capability the
@@ -81,7 +98,7 @@ Asset ids are CAIP-19 with the rail as the CAIP-2 namespace, `<rail>:<network>/<
81
98
  ```ts
82
99
  const asset = canonicalAssetId("BTC", {
83
100
  network: "regtest",
84
- assets: [{ ticker: "BTC", id: "arkade:regtest/slip44:0" }],
101
+ assets: [{ ticker: "BTC", id: "arkade:regtest/slip44:1" }],
85
102
  });
86
103
  ```
87
104
 
@@ -162,6 +179,32 @@ though: a `Date` in a field you added comes back an ISO string, a `Set` or `Map`
162
179
  and a `bigint` throws on save. The package's own records are JSON-safe by design; keep yours that
163
180
  way too.
164
181
 
182
+ For bounded reads, all four backends provide `getAssetSwapsPage`,
183
+ `getRfqSwapsPage`, and `getSwapRecordsPage`. Pass `{ limit, after? }` with a
184
+ limit of 1–500, then use each result's `nextCursor` for the following page.
185
+ Asset swaps and swap records sort by ID. RFQ swaps sort by `(updatedAt, rfqId)`
186
+ and accept `{ state?, since? }`; `since` is inclusive Unix seconds. Keep the
187
+ filter fixed while paging. Repository collection reads use pages directly;
188
+ internal recovery and lifecycle paths consume every page before acting.
189
+ SDK transaction-history page `since` values use Unix milliseconds instead.
190
+ SQLite RFQ pages use a row-value comparison, so they need SQLite 3.15.0 or
191
+ newer.
192
+
193
+ ### Restore an imported wallet
194
+
195
+ Run the core wallet's `restore()` first (addresses, contracts, history), **then** create the client:
196
+
197
+ ```ts
198
+ await wallet.restore();
199
+ const client = createSwapClient({ wallet, repository: new IndexedDbAssetSwapRepository() });
200
+ await client.ready;
201
+ ```
202
+
203
+ `client.ready` rebuilds a record for every offer deposit in that history, with
204
+ `market: { kind: "restored" }`. A client created before `restore()` finishes rebuilds only what
205
+ history held at that moment, until its next construction. Corridor swaps a `0.0.x` client stored
206
+ are adopted the same way, with `backend: "rfq"`.
207
+
165
208
  ## Runtime requirements
166
209
 
167
210
  The one global the core requires is `crypto.getRandomValues`. Node and browsers have it; React
@@ -177,11 +220,18 @@ from the wallet, which is the single place that knows which operator it speaks t
177
220
  | Subpath | What it is |
178
221
  | ---------------------------------- | ----------------------------------------------------------------- |
179
222
  | `@arkade-os/swap` | the client, the verbs, the vocabulary, the error taxonomy |
223
+ | `@arkade-os/swap/advanced` | the orchestration below the verbs: the drive, corridors, RFQ wire |
180
224
  | `@arkade-os/swap/node` | the Node storage default |
181
225
  | `@arkade-os/swap/repositories/*` | the React Native backends |
182
226
  | `@arkade-os/swap/nostr` | the Nostr RFQ transport, for hand-building one |
183
227
  | `@arkade-os/swap/protocol` | the v1 building blocks, deprecated |
184
228
 
229
+ The root is a curated surface — if a name the client's modules define is not on it, it is on
230
+ `./advanced` (manual driving with `createSwapDrive`, destination claiming with `corridorSet`,
231
+ custom quote flows with `acceptQuote`/`quoteViaRfq`, record reading with `recordLeg`/`swapOf`).
232
+ "Advanced" is a deliberate deep subpath, not a second compatibility promise: those names move
233
+ with the client's internals across minor versions; the root is what stays put.
234
+
185
235
  `./nostr` is a floor and not a deprecation: the client opens the card's rendezvous itself, and the
186
236
  subpath is what keeps that an escape hatch rather than a wall. It is a separate entry point
187
237
  because `nostr-tools` is an optional peer dependency, so a consumer who never hand-builds a