@ninsei-labs/sdk 0.57.2 → 0.58.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 (46) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +64 -27
  3. package/THIRD_PARTY_NOTICES.md +2 -2
  4. package/assets/vendors/MANIFEST.json +1 -9
  5. package/assets/vendors/sdk/sdk-browser.js +4 -4
  6. package/engine/core/config.js +3 -22
  7. package/engine/core/rfqSource.js +6 -133
  8. package/engine/core/swap.js +1 -1
  9. package/engine/evm/index.js +3 -2
  10. package/engine/evm/session.js +46 -277
  11. package/engine/monero/address.js +15 -33
  12. package/engine/monero/keys.js +124 -0
  13. package/engine/monero/mnemonic.js +104 -0
  14. package/engine/monero/scan.js +23 -9
  15. package/engine/monero/wallet.js +31 -68
  16. package/engine/monero/wordlist.en.js +210 -0
  17. package/engine/recovery/restore.js +1 -1
  18. package/engine/sdk/bridge.js +7 -182
  19. package/engine/ui/walletModal.js +7 -27
  20. package/index.d.ts +187 -252
  21. package/package.json +4 -5
  22. package/src/codes.mjs +12 -0
  23. package/src/config.mjs +16 -54
  24. package/src/engine.mjs +3 -0
  25. package/src/index.mjs +24 -45
  26. package/src/order.mjs +2 -2
  27. package/src/public/recovery.d.ts +17 -1
  28. package/src/public/recovery.mjs +1 -0
  29. package/src/quotePolicy.mjs +25 -0
  30. package/src/quotes.mjs +21 -751
  31. package/src/readyWindow.mjs +76 -0
  32. package/src/recovery-key.mjs +39 -2
  33. package/src/recovery.mjs +11 -28
  34. package/src/relayClaim.mjs +132 -0
  35. package/src/relayFirmClient.mjs +3 -0
  36. package/src/relayQuote.mjs +5 -1
  37. package/src/swap-flow.mjs +49 -5
  38. package/src/swaps.mjs +301 -307
  39. package/src/sweep-action.mjs +73 -0
  40. package/src/sweep.mjs +7 -1
  41. package/src/version.mjs +1 -1
  42. package/src/xmr-arrival.mjs +275 -7
  43. package/src/xmrAmountPolicy.mjs +35 -0
  44. package/assets/vendors/monero/monero-js-browser.js +0 -58
  45. package/assets/vendors/monero-js/LICENSE +0 -9
  46. package/assets/vendors/walletconnect/wc-browser.js +0 -6202
package/CHANGELOG.md CHANGED
@@ -1,5 +1,21 @@
1
+ ## 0.58.0 — 2026-11-10
2
+
3
+ - `swaps.verifyArrivalShadow` runs the exact arrival walk and the fixed-slice witness-v1 walk side by side. The witness request carries only `{version, network, grid, slice}` (20 blocks aligned to multiples of 20), never the start height, payout block, txid or order id; a node without `protocol: "witness-v1"` is refused rather than guessed. The exact verdict still decides, so this is the staging path before an independent operator serves the protocol.
4
+ - A quote is refused as `quote-too-short` when it arrives with less than the start margin left, instead of showing a confirmation that the lock would reject seconds later.
5
+ - Arrival refuses a view key or spend key that does not belong to the watched address, refuses a subaddress by name, skips a malformed transaction extra key instead of losing the whole walk, and treats an unsynchronized witness as unknown, not as absence.
6
+ - A pending funding is resumed only for the same quote nonce and salt; a reused nonce with different terms is a new order, and an id-only retry is refused instead of funding a second escrow.
7
+ - The release publish job receives the npm dist-tag as an environment value and validates it, so the build output cannot become shell code in the OIDC job.
8
+ - The quote defaults are public: `DEFAULT_ORDER_QUOTE_TTL_SEC` (60 s) is the firm quote lifetime a node signs when it has no override, and `LOCK_START_MARGIN_SEC` (30 s) is the margin `swaps.start` requires before opening a wallet. A node imports the lifetime instead of keeping its own copy.
9
+ - The node's signed ready window now drives a sale: `quotes.firmRelay` returns `readyWindow`, `startSell` stores it, and `sellWatch`, the late-arrival boundary and `refundIfXmrMissing` use `readyMinSeconds`/`readyMaxSeconds` instead of the retired local 1200 s and 20-minute constants. A record without the window is refused by name.
10
+ - `swaps.claimViaRelay` claims a sell through the relay that answered the quote without creating or using a wallet: the signed `claimTip` pays the sender, and the sender is a listed maker OTHER than the deal's maker, chosen by the client and stored by `startSell` (a request may supply it for an older record). A request or record naming the deal's maker is refused before the half leaves the client. Only a validated txid is a success; a lost answer is `claim-unknown`; `sellClaim` remains the own-wallet path.
11
+ - The retired direct-node paths are gone: `quotes.watch`, `quotes.snapshot`, `quotes.firm`, `quotes.sale`, `swaps.sync`, `DEFAULT_ROUTES`, `config.route`/`routes`, `apiBase` and `serverAuth`. `quotes.firmRelay` is the only quote path; `swaps.start` ends at the joint address, and `swaps.watch` requires the client-side `verify` inputs. The page bridge lost the matching quote-book, direct-quote and server-sync helpers.
12
+ - The engine's `rfqSource` mirror keeps only the executor's order quote and its shape check; the indicative quote book and its `sdkBook`/`sdkBookSnapshot` calls are gone.
13
+ - The SDK no longer ships or loads a WalletConnect browser bundle. `evmWallet(provider)` remains the only wallet seam, so a host page can keep using injected wallets or load `@walletconnect/ethereum-provider` itself and pass the resulting EIP-1193 provider. The SDK's browser engine now offers only the injected connector; the WalletConnect build package, manifest entry, CI workflow and checks are gone.
14
+ - `recovery.readEscrowEventsByTopic` reads `HalfRevealed`, `Ready` and `Declined` without an address filter, so a recovery page can scan by topic and filter by `escrow` locally. The existing `readEscrowEvents({ escrows, ... })` is unchanged.
15
+
1
16
  ## 0.57.2 — 2026-11-06
2
17
 
18
+ - Monero mnemonic, key and subaddress derivation now comes from the package's own `engine/monero/mnemonic.js` and `engine/monero/keys.js` over `@noble/curves`; the vendored `monero-js` browser bundle and its licence copy are gone. Address building and checksum checks no longer load a vendor at runtime. The pinned mnemonic, spend/view key, subaddress and address vectors are unchanged.
3
19
  - Re-release of 0.57.0 after the publish job rejected the local tarball path. `0.57.1` was tagged but not published; there are no API changes from 0.57.0, and the package content and generated deployment pins are unchanged.
4
20
 
5
21
  ## 0.57.0 — 2026-11-06
package/README.md CHANGED
@@ -22,7 +22,7 @@ Report suspected vulnerabilities through GitHub's private **Report a vulnerabili
22
22
  The supported versions, scope, response targets, safe-harbor rules and disclosure process are in
23
23
  [`SECURITY.md`](SECURITY.md).
24
24
 
25
- ## State (0.57.2)
25
+ ## State (0.58.0)
26
26
 
27
27
  | Surface | State |
28
28
  |---|---|
@@ -31,12 +31,12 @@ The supported versions, scope, response targets, safe-harbor rules and disclosur
31
31
  | `preflight` — the engine's guards, answering with codes | works |
32
32
  | `recovery.open` — parsing the recovery file | works |
33
33
  | `sim` — sandbox scenarios and time | works (applying to a swap — stage 2) |
34
- | `quotes.watch` | works: live indicative quotes, its own client; a snapshot carries the display fields (sides, networks, `why`, signature, age, maturity), and the size can be NAMED (`size`) |
35
- | `quotes.firm` | works: a signed, binding quote with a TTL; a refusal is a named code |
36
34
  | `quotes.firmRelay` | works: a firm quote through a relay, built from one recovery key; the node half is DLEQ-checked |
37
35
  | `swaps.list` / `swaps.get` | read state from storage (and after a page reload) |
38
36
  | `swaps.start` | holds the order: guards → recovery file and the person's confirmation → order → locking funds → **watching the Monero address**; no backend is required; returns the named state `step: "xmr-incoming"` |
39
- | `swaps.watch` | waits for XMR to arrive at the joint address with the same request as the page (`GET /swaps/{id}`): arrived — returns the fact (amount, confirmations, txid); did not wait — a refusal with the code `xmr-timeout`; already on the address but barred by `unlock_time` — a refusal with the code `xmr-locked` (the boundary is in `params.until`), and NO ready mark; the maker DECLINED the order — returns `SwapDeclinedWatch` (`declined: true`, `terminal: "declined"`, the node's own `code`), with every action off; with expectations and a wallet, places the ready mark after the arrival |
37
+ | `swaps.watch` | waits for XMR at the joint address with the CLIENT's own check: `verify` carries the joint address, view secret, spend public key and witness nodes. Arrived — returns the fact (amount, confirmations, txid); did not wait — a refusal with `xmr-timeout`; funds barred by `unlock_time` — `xmr-locked`; the maker DECLINED — `SwapDeclinedWatch` (`declined: true`, `terminal: "declined"`), every action off; with expectations and a wallet, places the ready mark after the arrival |
38
+ | `swaps.verifyArrivalShadow` | the staging path for witness-v1: runs the exact walk and the fixed-slice walk side by side, without changing ready or refund. The slice request carries only the grid and slice; a node must name `protocol: "witness-v1"` |
39
+ | `swaps.startSell` / `swaps.sellClaim` / `swaps.claimViaRelay` | a sell is recorded from the verified relay offer; `sellClaim` claims from the claimer's own wallet, `claimViaRelay` claims with no wallet through the sender the client chose, paid by the signed `claimTip` |
40
40
  | `wallet.balances` | works: the native coin and tokens, in minimal units |
41
41
 
42
42
  What is not ready names itself with the code `not-implemented` with the fields `surface` and `stage`: an empty
@@ -81,7 +81,6 @@ import { createNinsei } from "@ninsei-labs/sdk";
81
81
  const sdk = createNinsei({
82
82
  settlement: { chain: "arbitrum-sepolia" }, // from sdk.config.chains; vm is taken from the registry
83
83
  xmrNetwork: "stagenet",
84
- // apiBase: "https://your-service", // only when you bring a backend; there is no default
85
84
  assetsBase: "/sdk/",
86
85
  mode: "live", // or "sim"
87
86
  });
@@ -157,7 +156,8 @@ interface's: this package holds no user-facing string.
157
156
 
158
157
  `not-implemented`, `bad-input`, `wallet-not-connected`, `wallet-rejected`, `wrong-chain`, `quote-unavailable`,
159
158
  `quote-refused`, `address-denied`, `quote-stale`, `recovery-declined`, `recovery-failed`, `storage-unavailable`,
160
- `server-unavailable`, `server-refused`, `xmr-timeout`, `xmr-locked`, `contract-reverted`, `insufficient-funds`, `unknown`.
159
+ `server-unavailable`, `server-refused`, `claim-unknown`, `xmr-timeout`, `xmr-locked`, `contract-reverted`,
160
+ `insufficient-funds`, `unknown`.
161
161
 
162
162
  Three refusals that are easy to merge into one are named DIFFERENTLY, because the advice differs:
163
163
  `server-unavailable` — the service did not answer (retry); `server-refused` — it answered and did not accept (its
@@ -171,26 +171,58 @@ interface shows its own neutral message.
171
171
 
172
172
  ## Quotes
173
173
 
174
+ The SDK has one quote path: a relay. `quotes.firmRelay` derives the client half and both view points from one
175
+ recovery key, sends one request, verifies the relay answer and the on-chain registry/factory binding, and returns
176
+ the signed `orderQuote` with its `startRequest`. There is no direct node client, no quote book and no route table
177
+ in the package; a host that needs an indicative book keeps it in the host.
178
+
174
179
  ```js
175
- const stop = sdk.quotes.watch({ direction: "buy", token: "eth", amount: 1 }, (s) => render(s));
176
- s.rate; // the best offer's price: non-XMR coins per 1 XMR; null - there is no offer (this is not zero)
177
- s.xmr; // how much XMR for the entered amount (buy) or how much the person gives (sell)
178
- s.sizeOk; // does the size fall within the node's grid and range
179
- s.sizeCode; // why it does not: below-min | above-max | bad-size | no-offer
180
- s.offers; // all offers for the size; s.refused - rows that did not become offers
181
- s.best; // the best for the requested volume and side, AS THE SERVICE NAMED IT (pair and node)
182
- stop(); // the last one to unsubscribe stops the polling
180
+ const offer = await sdk.quotes.firmRelay({ relayUrl, features, order, side: "ask", recoveryKey, xmrAmount });
181
+ offer.orderQuote; // the signed quote the factory takes
182
+ offer.startRequest; // quote, order, orderQuote, counterparty and recovery salt for swaps.start
183
183
  ```
184
184
 
185
- The size can be NAMED rather than derived: `watch({ direction, token, size }, cb)` — if the caller has already
186
- aligned the volume to the provider's grid, the core asks for EXACTLY that size. An offer row and a refusal row
187
- carry the pair's sides, both networks and the "named" marker, the provider's reason (`why`), the package's
188
- signature, the age (`ageMs`) and the maturity level (`finality`) — display fields, not a second computation.
185
+ ## Selling and claiming
186
+
187
+ A bid is a sale of XMR. `quotes.firmRelay({ side: "bid", claimTip, ... })` returns the signed quote, the escrow,
188
+ the one-time address, the `relayUrl` that answered and the node's `readyWindow`. `swaps.startSell` stores all of
189
+ them, including the relay origin and the window, and sends nothing. The window's `readyMinSeconds` and
190
+ `readyMaxSeconds` drive the sale watch, the late-arrival boundary and the refund lead; a record without it is
191
+ refused by name when the watch or the refund needs it. The send-xmr gate still uses its confirmation lead
192
+ (`xmrConfirmations * xmrBlockTimeSec`, or `limits.sellReadyLeadSec` when set).
193
+
194
+ A seller who has their own EVM wallet uses the own-wallet path. It signs the claim from that wallet and therefore
195
+ needs ETH for gas:
196
+
197
+ ```js
198
+ await sdk.swaps.sellClaim({ id }, wallet);
199
+ ```
189
200
 
190
- The price does not depend on volume: the volume is needed by the provider to say whether it takes such a size. So
191
- the size is computed from the person's amount and is snapped to the node's grid **down**, and a size outside the
192
- range is not aligned: it is the provider's refusal, and it arrives as a code. Indicative quotes commit to nothing;
193
- `quotes.firm` and `quotes.firmRelay` commit, and the relay path carries the maker's signed terms and its view half.
201
+ A seller who has XMR but no ETH uses the relay path. The escrow pays the signed `claimTip` to the sender, so the
202
+ relay submits the half and is paid from the claim itself. No wallet is created or used, and no chain transaction is
203
+ signed by the client:
204
+
205
+ ```js
206
+ const sell = await sdk.swaps.startSell({ offer, claimSender }); // another listed maker
207
+ const claimed = await sdk.swaps.claimViaRelay({ id: sell.id });
208
+ claimed.txid; // the claim transaction
209
+ claimed.from; // the sender node's claim sender
210
+ claimed.tipWei; // the signed tip paid out of the claim
211
+ ```
212
+
213
+ `claimSender` is chosen by the client from the relay's price answer: a listed maker OTHER than the deal's maker and
214
+ other than its quote key owner. `startSell` stores it with the record, so a reload claims through the same node; a
215
+ record made before the sender was stored may pass `claimSender` to `claimViaRelay` once; it is stored on the record
216
+ then. A sender naming the deal's maker or its quote key is refused before the half leaves the client.
217
+
218
+ `claimViaRelay` reads the sell record made by `startSell` and requires a positive `claimTip`, the sender, the
219
+ escrow and the half. It posts to the relay origin stored with the record; an optional `relayUrl` may repeat that
220
+ origin but a different one is refused. A node refusal is `quote-refused` with the sender's own code in
221
+ `params.code`. A timeout or a body without a real transaction hash is `claim-unknown`: the claim may have been
222
+ sent, so read the escrow before trying anything else. Only a validated txid is returned as a claim.
223
+
224
+ `actions.claim` is unchanged: it still sends only from the claimer's own wallet, because the half is revealed by
225
+ whoever sends the claim.
194
226
 
195
227
  ## Found orders and the paying token
196
228
 
@@ -200,6 +232,10 @@ another device or at another factory produce a different half and no number is r
200
232
  `derivation: "salt-v2"` and has no index. There is no range scan and no `max-index` result: every order in the logs is
201
233
  read once, and an unreadable log request is a refusal, not a partial answer.
202
234
 
235
+ `readEscrowEventsByTopic` reads the same three settlement events (`HalfRevealed`, `Ready` and `Declined`) without
236
+ an address filter: the caller receives every event in the block range and filters by `escrow`. This is the
237
+ privacy-preserving path for a recovery page, because the RPC does not learn which escrows belong to the visitor.
238
+
203
239
  - `amount` — the escrow's **native** amount in wei;
204
240
  - `settlementToken: "native"` — what the escrow receives;
205
241
  - `xmrAmount` — the XMR side, read from the clone's condition word 18 when an `evmCode` reader is passed;
@@ -248,6 +284,11 @@ total unknown.
248
284
  A failed settlement block-time read keeps the matched order: `findSwaps` returns `blockTime: null` with
249
285
  `startHeightReason: "block-time-read"` instead of throwing away every row.
250
286
 
287
+ Pass `evmBlockTimes` to read the timestamps for every distinct matched block in one request. It receives the block
288
+ numbers in first-seen order and returns a map; a `null` or missing entry is `no-block-time`, while an `Error` entry
289
+ is `block-time-read`. When the batch seam is supplied it is the only timestamp reader: `evmBlockTime` is not called,
290
+ even after a failed batch. Without the seam, the older `evmBlockTime` path stays in use.
291
+
251
292
  The retired backend no longer decides a swap: its watch row may observe money, but it cannot declare readiness or
252
293
  a decline; the client's two-node check and the escrow's own `Declined` event do.
253
294
 
@@ -255,9 +296,6 @@ Storage is a refusal, not a silent empty state: a failed read, corrupt JSON, a f
255
296
  `storage-unavailable` with a step. Every SDK instance gets its own store over the adapter it was given, so two
256
297
  clients with different adapters keep separate records and neither takes over the other's.
257
298
 
258
- Every body route the SDK sends carries `sdkVersion` from the package (`quotes.firm`, `quotes.sale` and the funding
259
- mark). The caller cannot override it with a different line.
260
-
261
299
  Funding is reported from the receipt, not from the send. A status-0 receipt is `contract-reverted`; a missing
262
300
  receipt, a receipt without `OrderCreated`, or an event from another factory is `funding-pending` with the transaction
263
301
  hash, and `swaps.start` does not save an escrow or retire a recovery number in that state.
@@ -336,8 +374,7 @@ after that runs it again, so keep the work in draft until the last commit.
336
374
  3. **The wallet is outside.** The SDK opens no windows and does not look for injected providers itself.
337
375
  4. **The step order and the guards are inside `swaps.start`** (stage 2): funds are not locked until the interface
338
376
  has confirmed the recovery file is saved; retrying after an error or a reload is safe.
339
- 5. **WASM and the Monero bundles are separate files** from `assetsBase`, so the interface's bundler (Astro/Vite)
340
- does not touch them.
377
+ 5. **WalletConnect is the host's connector.** The SDK ships no vendor bundle and loads no connector at runtime; a page that wants mobile wallets loads `@walletconnect/ethereum-provider` itself (from its own lock or a pinned CDN asset), draws the QR, and passes the resulting EIP-1193 provider to `evmWallet(provider)`. A page without it works with injected wallets only. Monero mnemonic, key and address code is part of the package core: it needs no separate file and no vendored browser bundle.
341
378
  6. **Strict CSP.** The package is designed for a policy without `eval` and inline.
342
379
  7. **Few dependencies, all permissive.** Every production dependency is checked in CI against an allowlist: MIT, MIT-0,
343
380
  ISC, Apache-2.0, BSD-2-Clause, BSD-3-Clause, Unlicense, 0BSD, CC0-1.0 and BlueOak-1.0.0. Copyleft,
@@ -37,7 +37,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
37
37
  SOFTWARE.
38
38
  ```
39
39
 
40
- ## @hpke/common 1.10.1
40
+ ## @hpke/common 1.10.1, 1.11.0
41
41
 
42
42
  License: MIT
43
43
  Source: git+https://github.com/dajiaji/hpke-js.git
@@ -68,7 +68,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
68
68
  SOFTWARE.
69
69
  ```
70
70
 
71
- ## @hpke/core 1.9.0
71
+ ## @hpke/core 1.10.0
72
72
 
73
73
  License: MIT
74
74
  Source: git+https://github.com/dajiaji/hpke-js.git
@@ -2,17 +2,9 @@
2
2
  "version": 1,
3
3
  "note": "Pinned browser bundles. A change to one of these files must be accompanied by a matching SHA-256 here and a rebuild of the page's asset registry.",
4
4
  "bundles": {
5
- "monero/monero-js-browser.js": {
6
- "sha256": "05c682ea514db089b3f872e4e8eee3d526e7131079bdb3871dad57d201db7e89",
7
- "source": "monero-js"
8
- },
9
5
  "sdk/sdk-browser.js": {
10
- "sha256": "5ea90250943fca3e98a542ee2b2b7f16c22b7c59416ed358d73aa3868137b1df",
6
+ "sha256": "61b3a75c36457b4485144be3c328c00938d1c164b9f2bd3a1c28207d9af7d681",
11
7
  "source": "sdk/src (facade, adapters, recovery)"
12
- },
13
- "walletconnect/wc-browser.js": {
14
- "sha256": "fb64f27c1ec026811fe72bfff06da1f997bbf720569ea73be87818e2c5847eec",
15
- "source": "@walletconnect"
16
8
  }
17
9
  }
18
10
  }