@ninsei-labs/sdk 0.61.0 → 0.62.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 (71) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/README.md +56 -5
  3. package/assets/vendors/MANIFEST.json +1 -1
  4. package/assets/vendors/sdk/sdk-browser.js +4 -4
  5. package/engine/atomic/halfenc.js +6 -6
  6. package/engine/core/config.js +17 -38
  7. package/engine/core/format.js +1 -1
  8. package/engine/core/sellWindow.js +1 -1
  9. package/engine/core/store.js +11 -3
  10. package/engine/core/swap.js +3 -3
  11. package/engine/evm/amounts.js +2 -2
  12. package/engine/evm/asyncRoute.js +3 -3
  13. package/engine/evm/dex.js +1 -1
  14. package/engine/evm/factory.js +1 -1
  15. package/engine/evm/fees.js +62 -0
  16. package/engine/evm/funding.js +71 -66
  17. package/engine/evm/gasReserve.js +10 -0
  18. package/engine/evm/index.js +2 -2
  19. package/engine/evm/prices.js +3 -0
  20. package/engine/evm/session.js +1 -1
  21. package/engine/monero/address.js +4 -2
  22. package/engine/monero/arrivalRead.js +15 -2
  23. package/engine/monero/keyImage.js +146 -0
  24. package/engine/monero/keys.js +1 -0
  25. package/engine/monero/mnemonic.js +2 -1
  26. package/engine/monero/node.js +1 -0
  27. package/engine/monero/scan.js +12 -2
  28. package/engine/recovery/recoveryFile.js +31 -85
  29. package/engine/sdk/bridge.js +21 -51
  30. package/index.d.ts +412 -19
  31. package/package.json +20 -2
  32. package/src/actions.mjs +72 -6
  33. package/src/addressGuard.mjs +16 -0
  34. package/src/codes.mjs +26 -9
  35. package/src/config.mjs +56 -3
  36. package/src/decline.mjs +23 -74
  37. package/src/firmRequest.mjs +80 -0
  38. package/src/index.mjs +17 -28
  39. package/src/legs/cow.mjs +2 -2
  40. package/src/legs/evm.mjs +20 -12
  41. package/src/legs/kyber-spec.mjs +2 -2
  42. package/src/legs/kyber.mjs +1 -1
  43. package/src/legs/shape.mjs +1 -1
  44. package/src/legs/uniswaprelay.mjs +16 -4
  45. package/src/legs/uniswapx.mjs +29 -7
  46. package/src/levelsWalkSpec.mjs +1 -1
  47. package/src/lock.mjs +18 -37
  48. package/src/provider/envFile.mjs +3 -3
  49. package/src/provider/sign.mjs +3 -3
  50. package/src/public/evm.d.ts +84 -0
  51. package/src/public/evm.mjs +20 -0
  52. package/src/public/order.mjs +1 -1
  53. package/src/public/provider.mjs +1 -1
  54. package/src/public/recovery.d.ts +3 -2
  55. package/src/public/recovery.mjs +1 -1
  56. package/src/public/xmr.d.ts +2 -2
  57. package/src/quoteEip712Spec.mjs +4 -4
  58. package/src/quotes.mjs +52 -11
  59. package/src/recovery-key.mjs +7 -3
  60. package/src/relayFirmClient.mjs +4 -0
  61. package/src/relayQuote.mjs +1 -0
  62. package/src/sim.mjs +1 -1
  63. package/src/swap-flow.mjs +22 -32
  64. package/src/swaps.mjs +63 -56
  65. package/src/sweep-inputs.mjs +61 -0
  66. package/src/sweep-reconcile.mjs +71 -0
  67. package/src/sweep-restore.mjs +38 -9
  68. package/src/sweep.mjs +164 -10
  69. package/src/version.mjs +1 -1
  70. package/src/wallet.mjs +1 -1
  71. package/src/xmr-arrival.mjs +1041 -43
package/CHANGELOG.md CHANGED
@@ -1,3 +1,38 @@
1
+ ## 0.62.0 — 2026-11-21
2
+
3
+ - **BREAKING:** `quotes.firmRequest` places `readyBy` and `t1` inside the signed window for one market, side and Monero network on the chain's clock; `firmRelay` now selects that window by the Monero network too. `@ninsei-labs/sdk/evm` exports `feeWeiFor`, `principalForTotal`, `salePayoutBeforeClaim` (guaranteed minimum and seller-sent figure), `salePayoutAfterClaim` (actual payout judged by `msg.sender`), `GAS_CREATE_ORDER_AND_FUND` and `fundingGasReserveWei` for the Max reserve. Balance reads accept only an ETH JSON-RPC quantity or one 32-byte ABI word; an empty, malformed or boolean answer is `null`, never zero.
4
+ - `sweep.reconcile` handles a saved signed withdrawal after the session token is gone. It uses one `readRecovery` walk with the signed hash and verified `keyImages` and returns `present` (hash in a block or pool), `inputs-spent` (hash absent, an input moved), `unknown` (incomplete read) or `absent` with `resend: true` (hash absent, every input unspent). It never signs or relays; only the `absent` answer permits the same bytes, with the same hash, to be sent once. `readRecovery` now reports the requested `txid` as `target` when its walk meets it.
5
+ - **BREAKING:** `sweep.sign` requires a completed `sweep.restore` on the same wallet adapter. A behind-node or failed scan is `sweep-scan-incomplete`; a sweep that needs more than one transaction is `sweep-split`. Both `sweep.sign` and `swaps.start` validate the destination with `checkAddress`, refusing a bad checksum or another Monero network before a wallet or a funding send.
6
+ - **BREAKING:** `sweep.sign` requires the verified unspent `keyImages` and refuses `sweep-inputs-changed` unless the signed transaction's inputs are exactly that set; an opaque signed transaction is `sweep-inputs-unknown`. `sweep.relay` requires a fresh `keyImages` list and checks it again before sending.
7
+ - A public node refusing the optional `rescanSpent` pass no longer fails the full restore: the balances are kept and the result names `spent-status-unavailable`.
8
+ - `sweep.keyImages` derives the key images of an arrival's verified funding outputs without a monero-ts wallet. It uses Monero's `ge_fromfe_frombytes_vartime` map and the per-output derivation, refuses an unverified or malformed output as a whole, and returns the same order as the verified outputs. Monero's own `hash_to_point`, `biased_hash_to_ec` and `generate_key_image` vectors are pinned; a local monerod stand compares the buy, refunded-sale and additional-key outputs across monero-ts, the SDK and a separate Rust `monero-ed25519` oracle.
9
+ - `verifyArrival` and `verifyRecovery` expose each verified output's `derivation`; `XmrArrivalVerdict` carries the agreed `outputs` so a caller can derive key images from the same evidence.
10
+ - `swaps.readRecovery` reads one chosen node from the order's start height to its head with a caller-owned checkpoint, progress events, resume and an idle stall bound. A moved anchor, a bad digest, a short block or a broken parent link is `complete: false`, never an empty range; a missing confirmation count is derived from the block, not read as zero. A throwing progress or checkpoint callback rejects the read as a caller error (`bad-input`) instead of appearing as a node failure. The independent two-operator decision remains separate.
11
+ - `swaps.readRecovery` and `readRecoveryWitness` accept `keyImages` from `sweep.keyImages`: inputs are matched locally, a spend is carried in the checkpoint and the available remainder excludes it. A fresh pool read runs on every synced primary, including a pool withdrawal, and a failed pool read is incomplete. The available remainder counts only confirmed, unlocked, verified outputs; it is a primary-sourced figure and is null when a key image has no output key. `verifyRecovery` is now the agreement layer over a primary read plus plain-daemon witness reads: transfers keep the two-operator rule, while available is a primary-sourced figure over confirmed, unlocked outputs and is withheld when a witness sees a spend the primary did not.
12
+ - `tools/check-recovery-acceptance.mjs` records the live primary/witness request sequence against a plain monerod: the exact primary start, the witness grid boundary, every height, no slice route, no exact-start parameter and identical cold/resume requests. The recorded browser exchange with a third-party operator remains the manual acceptance step.
13
+ - `swaps.verifyArrivalFromRead` applies the owner's amount rule over the one recovery read: `at-least` sums distinct verified outputs across confirmed, unlocked transfers (buy), `exact` sums confirmed, unlocked transfers (sale). Arrival no longer needs the private spend key: the public spend key is taken from the address and a supplied one is checked. Incomplete reads and one-node observations do not arrive; an empty range from two completed operators is `absent: true`, which keeps the refund path open.
14
+ - `swaps.readRecoveryWitness` reads a plain monerod by whole zero-aligned grid windows: every height and every transaction hash of a window, no exact start or payout txid, and no early stop at a match. A witness behind the primary top is incomplete; a resumed read re-reads the whole window that contains its checkpoint. The residual leak is the grid bucket containing the start.
15
+
16
+ ## Unreleased — 2026-11-19
17
+
18
+ - `createNinsei` accepts the deployment a local anvil just created (`settlement.escrow`), and the `testnet` and `fakechain` node maps are present but empty until the caller names nodes.
19
+ - `swaps.verifyRecovery` reads every transfer to the order address without a quoted amount, including short, overpaid, split and still-pool payments. `verifyArrival` keeps its amount rule.
20
+ - A previous claim attempt owns its sender slot even after a refusal: a later call waits out the remaining slot and starts the sender list from the beginning, so a temporary refusal or restart never removes the seller's no-wallet path.
21
+ - `verifyArrival` reports `state: "pool"` with the matching txid while the transfer is still in a node's mempool; it never counts as seen or arrived.
22
+ - The funding send uses the same wallet-error classifier as `markReady`, `claim` and `refund`, so a numeric provider refusal is no longer reported as `server-unavailable`.
23
+ - The Node.js floor is `24.22.3` across `engines`, CI, the Docker build and the support docs.
24
+
25
+ ## Unreleased — 2026-11-18
26
+
27
+ - The security inventory covers lock/funding, sweep/recovery, DEX legs and amount/fee modules; the map labels itself as inventory lint and no longer claims executable evidence.
28
+ - `quotes.firmRelay`, `swaps.start` and the atomic flow are driven with an injected chunk clock, and a ready record is proven to reuse the known halves without a second proof.
29
+ - The deployment-pins check ignores CRLF-only differences, so a Windows checkout is current; a real content change still fails.
30
+ - Relay quote verification uses the caller's clock seam instead of `Date.now()`, so an injected clock controls the expiry check.
31
+ - `order.escrowNativeWei` accepts only a canonical decimal string, or a safe number. It refuses a significant digit beyond `nativeDecimals`, exponent form, and a number above `Number.MAX_SAFE_INTEGER`; it never truncates the signed amount. The guard is in the full battery and has a breaking-run suite.
32
+ - `sweep.relay` keeps the signed set and session token when the wallet throws or returns no transaction id. The answer is `sweep-relay-unknown`; the same token never relays that set twice.
33
+ - `readEscrowEvents` keeps only the requested escrows, and both recovery event readers drop `removed` logs.
34
+ - A window spent check counts pool status `2` as spent. A short, long or non-integer `spent_status` list is unknown: `spent` is null and the scan is incomplete.
35
+
1
36
  ## 0.61.0 — 2026-11-14
2
37
 
3
38
  - **BREAKING:** the scalar `claimSender` is retired from `SellStartRequest`, `RelayClaimRequest` and `RelayClaimed`. `claimSenders` is the only sender source; an explicit list replaces the relay-published sender and is never prepended. Pre-list records are migrated on their first claim.
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.61.0)
25
+ ## State (0.62.0)
26
26
 
27
27
  | Surface | State |
28
28
  |---|---|
@@ -93,6 +93,19 @@ const verdict = await sdk.preflight(quote, { payBalanceWei, payAmountWei });
93
93
  if (!verdict.ok) render(verdict.blockedBy); // codes, not phrases
94
94
  ```
95
95
 
96
+ A local anvil deployment is supplied by the caller, because a fresh `Deploy.s.sol` changes the factory and cashier
97
+ addresses:
98
+
99
+ ```js
100
+ const sdk = createNinsei({
101
+ settlement: { chain: "local-anvil", escrow: { address: factory, cashier, implementationCodeHash } },
102
+ xmrNetwork: "fakechain",
103
+ });
104
+ ```
105
+
106
+ The override is refused for a public network. `testnet` and `fakechain` have an empty node map by default; pass
107
+ `nodes: { testnet: [...] }` or `addNodes: [...]` to name the nodes that witness the arrival.
108
+
96
109
  ## Code tables
97
110
 
98
111
  It is the interface that must show the person anything based on these codes: the SDK has not a single
@@ -188,6 +201,17 @@ verified. `quotes.firmRelay` refuses a shorter one with `quote-too-short` before
188
201
  for its own expiry: the node has already funded the escrow and the client opens no wallet. The lock step then checks only
189
202
  the 30 s margin: the preparation was already spent between the answer and the send.
190
203
 
204
+ `quotes.firmRequest({ features, side, market, xmrNetwork, chainNow })` selects the one signed window for that market,
205
+ side and Monero network and places `readyBy` and `t1` inside it on the chain's clock. `firmRelay` uses the same
206
+ selection; two windows for one market on different networks are refused unless `xmrNetwork` names the one to use.
207
+
208
+ The money arithmetic is exported from `@ninsei-labs/sdk/evm`: `feeWeiFor` and `principalForTotal` for a buy,
209
+ `salePayoutBeforeClaim` for the guaranteed minimum and the seller-sent figure, and `salePayoutAfterClaim` for the
210
+ amount actually paid (judged by the contract's `msg.sender`, not `tx.from`). `fundingGasReserveWei` is the Max
211
+ reserve: `GAS_CREATE_ORDER_AND_FUND × maxFeePerGas`; `orderGasReserveWei` remains the mark/refund reserve. Balance
212
+ answers are accepted only as an ETH JSON-RPC quantity or one 32-byte ABI word; anything else is `null` (unknown) and
213
+ never zero. The sale's `monero:` URI amount comes from `formatXmr` in `@ninsei-labs/sdk/core`, not a second formatter.
214
+
191
215
  ## Selling and claiming
192
216
 
193
217
  A bid is a sale of XMR. `quotes.firmRelay({ side: "bid", claimTip, ... })` returns the signed quote, the escrow,
@@ -249,8 +273,8 @@ without a real transaction hash is `claim-unknown`: the claim may have been sent
249
273
  moves on only after the slot. Only an escrow that reads `claimed` is success.
250
274
 
251
275
  Each sender is written to the record before its POST. The log is diagnostic, not a skip list: a later call starts
252
- at the first sender again. A previous `sending` or `unknown` entry is waited out for its slot and then retried; a
253
- `refused` or `unconfirmed` entry is retried immediately. This is what makes a temporary relay failure, a restart or
276
+ at the first sender again. The latest attempt is waited out for its slot and then retried, whatever its outcome;
277
+ a `refused` or `unconfirmed` entry is retried after that slot, not before it. This is what makes a temporary relay failure, a restart or
254
278
  a closed tab recoverable. A sender's slot starts when it is entered, not when its POST returns; `pollMs` has a
255
279
  250 ms floor and `timeoutMs` a 120 s ceiling. The relay gate also reserves the settlement margin, so `sellWatch` can
256
280
  still report its own-wallet `claim-open` while `claimViaRelay` has already stopped. A refunded escrow is
@@ -279,6 +303,33 @@ read once, and an unreadable log request is a refusal, not a partial answer.
279
303
  `readEscrowEventsByTopic` reads the same three settlement events (`HalfRevealed`, `Ready` and `Declined`) without
280
304
  an address filter: the caller receives every event in the block range and filters by `escrow`. This is the
281
305
  privacy-preserving path for a recovery page, because the RPC does not learn which escrows belong to the visitor.
306
+ `readEscrowEvents` keeps only the escrows named in its request, and both readers drop logs marked `removed`.
307
+
308
+ `sweep.relay` returns `outcome: "sent"` with the transaction ids. If the wallet throws or returns no transaction id,
309
+ the answer is `sweep-relay-unknown`: the session token, the signed set and any known txids stay in the open session.
310
+ The same token never relays that set again. Check the chain before signing a new withdrawal.
311
+
312
+ `sweep.reconcile` is the later answer when the token is gone and only the signed bytes remain. It reads the swap
313
+ address through `swaps.readRecovery`, with the signed hash and the verified `keyImages`, and never signs or relays:
314
+ `present` means the hash is in a block or in the pool; `inputs-spent` means the hash is absent but an input moved;
315
+ `unknown` means the read could not decide and the bytes stay; only `absent` with `resend: true` permits the same
316
+ bytes, with the same hash, to be sent once.
317
+
318
+ `sweep.sign` refuses with `sweep-scan-incomplete` unless `sweep.restore` first completed a full scan on that same
319
+ wallet adapter; a behind-node, failed rescan or missing spent status is not a zero balance. A public node that refuses
320
+ the optional `rescanSpent` pass no longer fails the restore: the full scan is kept and the result names
321
+ `spent-status-unavailable`. A sweep that needs more than one transaction is refused with `sweep-split`; it is never
322
+ split silently. Both `sweep.sign` and `swaps.start` check the destination with `checkAddress`, so a bad checksum or an
323
+ address for another Monero network is refused before a wallet or a funding send.
324
+
325
+ `sweep.sign` also requires the verified unspent `keyImages` (strings or records from `sweep.keyImages`). It reads the
326
+ signed transaction's inputs from the wallet library and refuses `sweep-inputs-changed` unless that set is exactly the
327
+ verified one; an opaque signed transaction that cannot expose its inputs is `sweep-inputs-unknown`. `sweep.relay`
328
+ requires a fresh `keyImages` list and checks it again before sending; a changed set leaves the session open and sends
329
+ nothing. `sweep.run` passes the same list it used for signing, so a fresh post-sign read is a `sign` → `relay` pair.
330
+
331
+ A window spent check counts status `2` as spent in the pool. A short, long or non-integer `spent_status` list is not a
332
+ spent count: `spent` is null and `scanComplete` is false with `scanIncompleteReason: "spent-status-unavailable"`.
282
333
 
283
334
  - `amount` — the escrow's **native** amount in wei;
284
335
  - `settlementToken: "native"` — what the escrow receives;
@@ -356,8 +407,8 @@ still checks the address shape, so a mainnet withdrawal is not refused because t
356
407
  stagenet. The withdrawal window retries a `429`, a timeout or a `5xx` before it gives up. If the window still cannot be read,
357
408
  `restoreWallet` falls back to the full scan and reports `window.fallback: true` with `fallbackWhy: "window-read"` and
358
409
  the node's status; a withdrawal is not refused because the node was busy. When the wallet cannot reach the node's
359
- height, the result says `scanComplete: false` with `scanIncompleteReason: "sync-failed"`, `"behind-node"` or
360
- `"no-heights"`; a zero balance in that state is not an empty wallet.
410
+ height, the result says `scanComplete: false` with `scanIncompleteReason: "sync-failed"`, `"rescan-failed"`, `"behind-node"`,
411
+ `"no-heights"` or `"spent-status-unavailable"`; a zero balance in that state is not an empty wallet.
361
412
 
362
413
  ## Extending to other networks (Tron, Solana and beyond)
363
414
 
@@ -3,7 +3,7 @@
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
5
  "sdk/sdk-browser.js": {
6
- "sha256": "b48b18f7a9fe6d3ea28008cba34f28f815697e302279c3274cea96af5696d75c",
6
+ "sha256": "82ff9f8b799c587b53ff9051de63185f030b352f6541cad698e2669ab42ccc86",
7
7
  "source": "sdk/src (facade, adapters, recovery)"
8
8
  }
9
9
  }