@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/README.md CHANGED
@@ -27,7 +27,7 @@ Each is one `quote` → `accept` chain. `quote` returns binding, verified terms
27
27
  durable; `accept` writes the record, then funds.
28
28
 
29
29
  ```ts
30
- const BTC = btcOn("arkade", "bitcoin"); // arkade:bitcoin/slip44:0
30
+ const BTC = btcOn("arkade", "bitcoin"); // arkade:bitcoin/slip44:0 (slip44:1 on test networks)
31
31
  const USDT = "arkade:bitcoin/asset:…";
32
32
 
33
33
  // arkade -> lightning: pay an invoice. The amount is the invoice's.
@@ -54,16 +54,20 @@ artifact is an invoice whose claim secret has to be durable before a payer can a
54
54
  off it would show a payer an invoice this client could not yet claim; the verb removes the
55
55
  ordering from the caller.
56
56
 
57
- `onchain -> arkade` is not in the union. It resolves and quotes to `UnsupportedRoute` until the
58
- client owns the trader's L1 refund path end to end.
57
+ `onchain -> arkade` is a receive too: `client.receive({ via: "onchain", amount })` returns a
58
+ `deposit` artifact naming the L1 HTLC to fund, for exactly its `amount`, from any bitcoin wallet.
59
+ The client claims the solver's Arkade lockup once it is funded. If the solver never funds it, the
60
+ client takes the L1 funding back itself once the HTLC's refund leaf matures, paying a boarding
61
+ address of this wallet fixed at quote time and signing with the wallet key the HTLC was derived
62
+ with. The refund is built at the same `claimFeeRateSatVb` as the `arkade -> onchain` claim; wire
63
+ your own with `corridors: { onchain: { refund } }`.
59
64
 
60
65
  An `arkade -> onchain` withdrawal claims the solver's L1 HTLC itself, and that claim's miner fee
61
66
  comes out of the HTLC output — so the client grosses the take leg up by the claim's cost and the
62
67
  recipient nets exactly the `amount` written, with the estimate folded into the reported `fee`. The
63
68
  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
69
+ wallet's payout key and priced off a per-network fee-rate floor. A routing UI should raise it in
70
+ congestion — the claim has a consensus deadline — via
67
71
  `corridors: { onchain: { claimFeeRateSatVb } }`; set it to `null` to take the claim over manually
68
72
  (the drive then reports the L1 half as your job rather than blocking it). Wire your own builder
69
73
  with `corridors: { onchain: { claim } }` and it wins over the default.
@@ -98,7 +102,7 @@ Asset ids are CAIP-19 with the rail as the CAIP-2 namespace, `<rail>:<network>/<
98
102
  ```ts
99
103
  const asset = canonicalAssetId("BTC", {
100
104
  network: "regtest",
101
- assets: [{ ticker: "BTC", id: "arkade:regtest/slip44:0" }],
105
+ assets: [{ ticker: "BTC", id: "arkade:regtest/slip44:1" }],
102
106
  });
103
107
  ```
104
108
 
@@ -169,7 +173,7 @@ disposal closes a connection, because it is the one that opened it:
169
173
  ```ts
170
174
  import { nodeSwapRepository } from "@arkade-os/swap/node";
171
175
 
172
- await using swaps = nodeSwapRepository({ network: "mainnet" }); // or { path } to choose the file
176
+ await using swaps = nodeSwapRepository({ network: "bitcoin" }); // or { path } to choose the file
173
177
  ```
174
178
 
175
179
  Records are stored whole. The SQLite and Realm backends serialize each record to JSON with only
@@ -179,6 +183,32 @@ though: a `Date` in a field you added comes back an ISO string, a `Set` or `Map`
179
183
  and a `bigint` throws on save. The package's own records are JSON-safe by design; keep yours that
180
184
  way too.
181
185
 
186
+ For bounded reads, all four backends provide `getAssetSwapsPage`,
187
+ `getRfqSwapsPage`, and `getSwapRecordsPage`. Pass `{ limit, after? }` with a
188
+ limit of 1–500, then use each result's `nextCursor` for the following page.
189
+ Asset swaps and swap records sort by ID. RFQ swaps sort by `(updatedAt, rfqId)`
190
+ and accept `{ state?, since? }`; `since` is inclusive Unix seconds. Keep the
191
+ filter fixed while paging. Repository collection reads use pages directly;
192
+ internal recovery and lifecycle paths consume every page before acting.
193
+ SDK transaction-history page `since` values use Unix milliseconds instead.
194
+ SQLite RFQ pages use a row-value comparison, so they need SQLite 3.15.0 or
195
+ newer.
196
+
197
+ ### Restore an imported wallet
198
+
199
+ Run the core wallet's `restore()` first (addresses, contracts, history), **then** create the client:
200
+
201
+ ```ts
202
+ await wallet.restore();
203
+ const client = createSwapClient({ wallet, repository: new IndexedDbAssetSwapRepository() });
204
+ await client.ready;
205
+ ```
206
+
207
+ `client.ready` rebuilds a record for every offer deposit in that history, with
208
+ `market: { kind: "restored" }`. A client created before `restore()` finishes rebuilds only what
209
+ history held at that moment, until its next construction. Corridor swaps a `0.0.x` client stored
210
+ are adopted the same way, with `backend: "rfq"`.
211
+
182
212
  ## Runtime requirements
183
213
 
184
214
  The one global the core requires is `crypto.getRandomValues`. Node and browsers have it; React
@@ -186,8 +216,13 @@ Native does not, so install `react-native-get-random-values` (or `expo-crypto`)
186
216
  before this package. `crypto.subtle` is unused. `EventSource` and `WebSocket` are needed only by
187
217
  the watch and relay transports, each of which takes an injected implementation.
188
218
 
189
- The client takes no server URL anywhere. Server info, chain reads and broadcast are all derived
190
- from the wallet, which is the single place that knows which operator it speaks to.
219
+ The client takes no server URL. Server info, Arkade chain reads and broadcast are all derived
220
+ from the wallet, which is the single place that knows which operator it speaks to. The onchain
221
+ corridor is the exception: `IWallet` carries no L1 provider, so it reads bitcoin from Esplora at
222
+ `ESPLORA_URL[network]`. Point it elsewhere with
223
+ `corridors: { onchain: { chain: { esploraUrl } } }`, or pass `{ provider }` to read through your
224
+ own `OnchainProvider` — an Electrum-backed wallet then watches and claims the HTLC over its own
225
+ backend.
191
226
 
192
227
  ## Subpaths
193
228