@ninsei-labs/sdk 0.60.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 (96) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/README.md +81 -18
  3. package/assets/vendors/MANIFEST.json +1 -1
  4. package/assets/vendors/sdk/sdk-browser.js +4 -4
  5. package/engine/atomic/dleq2.js +0 -4
  6. package/engine/atomic/halfenc.js +6 -10
  7. package/engine/atomic/halves.js +0 -4
  8. package/engine/atomic/order.js +0 -4
  9. package/engine/atomic/orderContext.js +0 -4
  10. package/engine/atomic/orderHalfCommit.js +0 -4
  11. package/engine/core/chainSource.js +0 -4
  12. package/engine/core/clock.js +0 -4
  13. package/engine/core/config.js +17 -42
  14. package/engine/core/finality.js +0 -4
  15. package/engine/core/format.js +1 -5
  16. package/engine/core/preSignGuards.js +0 -4
  17. package/engine/core/rfqSource.js +0 -3
  18. package/engine/core/sellWindow.js +1 -5
  19. package/engine/core/store.js +11 -7
  20. package/engine/core/swap.js +3 -7
  21. package/engine/evm/amounts.js +2 -6
  22. package/engine/evm/asyncRoute.js +3 -7
  23. package/engine/evm/auth.js +0 -4
  24. package/engine/evm/claimGas.js +2 -6
  25. package/engine/evm/dex.js +1 -5
  26. package/engine/evm/escrow.js +0 -4
  27. package/engine/evm/factory.js +1 -5
  28. package/engine/evm/fees.js +62 -4
  29. package/engine/evm/funding.js +73 -71
  30. package/engine/evm/gasReserve.js +10 -4
  31. package/engine/evm/index.js +7 -11
  32. package/engine/evm/injected.js +0 -4
  33. package/engine/evm/permit.js +0 -4
  34. package/engine/evm/prices.js +3 -4
  35. package/engine/evm/session.js +1 -5
  36. package/engine/mock/chain.js +0 -4
  37. package/engine/monero/address.js +4 -5
  38. package/engine/monero/arrivalRead.js +15 -2
  39. package/engine/monero/halvesSweep.js +0 -4
  40. package/engine/monero/keyImage.js +146 -0
  41. package/engine/monero/keys.js +1 -0
  42. package/engine/monero/mnemonic.js +2 -1
  43. package/engine/monero/node.js +1 -4
  44. package/engine/monero/scan.js +12 -2
  45. package/engine/monero/swapKeys.js +0 -4
  46. package/engine/monero/unlock.js +2 -6
  47. package/engine/monero/wallet.js +0 -3
  48. package/engine/recovery/recoveryFile.js +31 -89
  49. package/engine/recovery/restore.js +0 -4
  50. package/engine/sdk/bridge.js +24 -58
  51. package/engine/ui/dom.js +0 -4
  52. package/engine/ui/walletModal.js +0 -4
  53. package/index.d.ts +436 -42
  54. package/package.json +22 -3
  55. package/src/actions.mjs +72 -6
  56. package/src/addressGuard.mjs +16 -0
  57. package/src/codes.mjs +26 -9
  58. package/src/config.mjs +56 -3
  59. package/src/decline.mjs +23 -74
  60. package/src/engine.mjs +17 -26
  61. package/src/firmRequest.mjs +80 -0
  62. package/src/index.mjs +17 -28
  63. package/src/legs/cow.mjs +2 -2
  64. package/src/legs/evm.mjs +20 -12
  65. package/src/legs/kyber-spec.mjs +2 -2
  66. package/src/legs/kyber.mjs +1 -1
  67. package/src/legs/shape.mjs +1 -1
  68. package/src/legs/uniswaprelay.mjs +16 -4
  69. package/src/legs/uniswapx.mjs +29 -7
  70. package/src/levelsWalkSpec.mjs +1 -1
  71. package/src/lock.mjs +18 -37
  72. package/src/provider/envFile.mjs +3 -3
  73. package/src/provider/sign.mjs +3 -3
  74. package/src/public/evm.d.ts +84 -0
  75. package/src/public/evm.mjs +20 -0
  76. package/src/public/order.mjs +1 -1
  77. package/src/public/provider.mjs +1 -1
  78. package/src/public/recovery.d.ts +4 -3
  79. package/src/public/recovery.mjs +1 -1
  80. package/src/public/xmr.d.ts +2 -2
  81. package/src/quoteEip712Spec.mjs +4 -4
  82. package/src/quotes.mjs +52 -11
  83. package/src/recovery-key.mjs +7 -3
  84. package/src/relayClaim.mjs +17 -3
  85. package/src/relayFirmClient.mjs +4 -0
  86. package/src/relayQuote.mjs +1 -0
  87. package/src/sim.mjs +1 -1
  88. package/src/swap-flow.mjs +28 -41
  89. package/src/swaps.mjs +217 -123
  90. package/src/sweep-inputs.mjs +61 -0
  91. package/src/sweep-reconcile.mjs +71 -0
  92. package/src/sweep-restore.mjs +38 -9
  93. package/src/sweep.mjs +164 -10
  94. package/src/version.mjs +1 -1
  95. package/src/wallet.mjs +1 -1
  96. package/src/xmr-arrival.mjs +1053 -57
package/CHANGELOG.md CHANGED
@@ -1,3 +1,60 @@
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
+
36
+ ## 0.61.0 — 2026-11-14
37
+
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.
39
+ - A claim window is read from the escrow one last time before it is reported closed: a claim, refund or defund that landed after the last sender slot wins over the closing state. An unreadable final read still returns the named window state.
40
+ - `swaps.watch` refuses `request.escrow` and `verify.address` that redirect the stored record (`bad-input` / `record-mismatch`) before any chain read.
41
+ - A first unread escrow is `claim-window` / `unreadable` when nothing has been sent; after an earlier attempt it remains `claim-unknown` with `escrow-unread`.
42
+ - Relay-level answers `rate_limited`, `bad_request`, `unsupported_version` and `no_quote` are `claim-unknown` (`relay-<code>`), not a sender refusal; the sender keeps its slot.
43
+ - Funding compares `commitHalfLocker`, `edPointLocker` and `edViewPointLocker` with the signed quote before sending, so a locker-half mismatch is refused before the factory.
44
+ - `engine/**` is now the SDK's own source; the generated-mirror headers and the `www/js` source-of-truth comments are gone.
45
+ - The claim guards have a mutation suite in `tools/check-claim-teeth.mjs`, run in CI after `check:guard-teeth`.
46
+ - CI uses Rust 1.100.0 and pnpm 12.21.0; Cargo resolves registry dependencies with a three-day cooldown.
47
+ - The supported version line is `0.61.x`; `package.json` and the baked-in `SDK_VERSION` move to 0.61.0.
48
+
49
+ ## 0.60.1 — 2026-11-13
50
+
51
+ - `claimViaRelay` treats `claimAttempts` as a diagnostic journal, not as a list of senders to skip. A repeated call starts from the first sender again; a previous `sending` or `unknown` entry is waited out for its slot and retried. A legacy future timestamp is capped at one slot, so an old device clock cannot stall recovery. A temporary relay refusal, a process restart or a closed tab no longer removes the seller's no-wallet path.
52
+ - The claim window and `secondsLeft` use the escrow chain's block timestamp (`evmBlock` or the wallet's block provider). A device clock skew can no longer post the half after `t1`, and a missing chain clock returns `claim-window` / `unreadable` instead of falling back to `Date.now()`.
53
+ - `sellWatch` does not report `ready` after `t1`; a ready mark that arrives too late is named as `claim-window-closed`.
54
+ - The witness shadow walks every fixed slice to the common target even after finding a perfect candidate, and `witnessQuorum.ok` requires completed operators with no witness-to-witness disagreement.
55
+ - `sweep.restore` keeps the facade's fetch transport through `createNinsei({ fetch })`, while a per-call `fetchImpl` still wins.
56
+ - The supported version line remains `0.60.x`; `package.json` and the baked-in `SDK_VERSION` move to `0.60.1`.
57
+
1
58
  ## 0.60.0 — 2026-11-13
2
59
 
3
60
  - `swaps.watch` keeps the joint Monero address apart from the EVM escrow: the result carries the address the client checked, and the automatic ready mark always signs against the escrow. A typed watch no longer returns the escrow as its `address`; the legacy untyped `request.address` is not read. `verify` remains mandatory, so a watch without the client's own check is refused by name instead of falling back to a retired service answer.
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.60.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,
@@ -225,19 +249,22 @@ if (claimed.state === "claimed") {
225
249
  ```
226
250
 
227
251
  `claimSenders` is the client's ordered list: the relay's own sender first, then other listed makers. `startSell`
228
- accepts the same list (or the relay answer's published `claimSender`) and stores it, so a later
229
- `claimViaRelay({ id })` can use the record without repeating the list. The SDK tries
230
- one sender at a time for a 15-30 s slot. A refusal moves on at once; a txid is not success - the SDK reads the
231
- escrow until it says `claimed` or the slot ends. The deal's maker and its quote-key owner are refused before the
232
- half leaves the client. When the list is exhausted the result is `state: "claim-yourself"` with `t1` and
233
- `secondsLeft`. The old scalar `claimSender` remains a one-element fallback for callers written before the list.
252
+ stores a list only when the caller passes `claimSenders`; otherwise the offer's published `claimSender` becomes a
253
+ one-element list. An explicit list replaces that published sender; it is never prepended. `claimViaRelay({ id })`
254
+ uses the stored list, while a request `claimSenders` replaces it. The old scalar `claimSender` is retired and
255
+ refused by name; the claim result names the sender that landed it as `provider`. The SDK tries one sender at a
256
+ time for a 15-30 s slot. A refusal moves on at once; a txid is not success - the SDK reads the escrow until it
257
+ says `claimed` or the slot ends. The deal's maker and its quote-key owner are refused before the half leaves the
258
+ client. When the list is exhausted the result is `state: "claim-yourself"` with `t1` and `secondsLeft`.
234
259
 
235
260
  The claim window is the escrow's, not the relay's. Before every sender the SDK reads `ready`, `readyBy` and `t1`
236
261
  from the chain. Without the ready mark before `readyBy`, at or after `t1`, or inside the 120 s settlement margin
237
262
  (plus the sender's slot and time for the seller's own claim), it returns `state: "claim-window"` with a named
238
- `reason` and posts nothing. An unread escrow is `claim-unknown` with `why: "escrow-unread"`; it is never reported as
263
+ `reason` and posts nothing. An escrow read that fails before any send is `claim-window` / `unreadable`; if an earlier
264
+ attempt may already have sent the half, it is `claim-unknown` with `why: "escrow-unread"`. It is never reported as
239
265
  `claim-yourself`. A relay answer such as `claim-not-ready` or `claim-window-closed` stops the list instead of
240
- passing the half to the next sender.
266
+ passing the half to the next sender. Relay-level answers (`rate_limited`, `bad_request`, `unsupported_version`,
267
+ `no_quote`) are `claim-unknown`, not a sender refusal; the sender keeps its slot and the list continues.
241
268
 
242
269
  `claimViaRelay` reads the sell record made by `startSell` and requires a positive `claimTip`, the escrow and the
243
270
  half. It posts to the relay origin stored with the record; an optional `relayUrl` may repeat that origin but a
@@ -245,13 +272,22 @@ different one is refused. A node refusal keeps its code under `quote-refused.par
245
272
  without a real transaction hash is `claim-unknown`: the claim may have been sent, so the SDK reads the escrow and
246
273
  moves on only after the slot. Only an escrow that reads `claimed` is success.
247
274
 
248
- Each sender is written to the record before its POST. A reload skips senders that were already tried; a refused
249
- sender allows the next, while an attempt left `sending` or `unknown` stops with `claim-unknown` and
250
- `why: "previous-sender-unknown"` instead of resending the half. An `unconfirmed` sender is skipped as well. A
251
- sender's slot starts when it is entered, not when its POST returns; `pollMs` has a 250 ms floor and `timeoutMs` a
252
- 120 s ceiling. The relay gate also reserves the settlement margin, so `sellWatch` can still report its own-wallet
253
- `claim-open` while `claimViaRelay` has already stopped. A refunded escrow is `claim-window` with
254
- `reason: "escrow-refunded"`, not a request to claim; recovery is the next step.
275
+ Each sender is written to the record before its POST. The log is diagnostic, not a skip list: a later call starts
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
278
+ a closed tab recoverable. A sender's slot starts when it is entered, not when its POST returns; `pollMs` has a
279
+ 250 ms floor and `timeoutMs` a 120 s ceiling. The relay gate also reserves the settlement margin, so `sellWatch` can
280
+ still report its own-wallet `claim-open` while `claimViaRelay` has already stopped. A refunded escrow is
281
+ `claim-window` with `reason: "escrow-refunded"`, not a request to claim; recovery is the next step.
282
+
283
+ `claimAttempts` is append-only and the SDK does not prune it: a long-lived record can grow with every retry. The
284
+ journal is diagnostic, not a spendable state. A host may trim older entries, but it must keep the latest
285
+ `sending` or `unknown` entry: that slot is waited out before the sender is tried again. Do not use the journal as
286
+ proof that a sender is finished.
287
+
288
+ The claim window uses the escrow's chain time, read with `evmBlock` (or the wallet's block provider), not the
289
+ device clock. If neither clock is available, the client refuses with `claim-window` / `unreadable` before the half
290
+ leaves; it does not fall back to `Date.now()`. `secondsLeft` is derived from that same chain time.
255
291
 
256
292
  `actions.claim` is unchanged: it still sends only from the claimer's own wallet, because the half is revealed by
257
293
  whoever sends the claim.
@@ -267,6 +303,33 @@ read once, and an unreadable log request is a refusal, not a partial answer.
267
303
  `readEscrowEventsByTopic` reads the same three settlement events (`HalfRevealed`, `Ready` and `Declined`) without
268
304
  an address filter: the caller receives every event in the block range and filters by `escrow`. This is the
269
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"`.
270
333
 
271
334
  - `amount` — the escrow's **native** amount in wei;
272
335
  - `settlementToken: "native"` — what the escrow receives;
@@ -344,8 +407,8 @@ still checks the address shape, so a mainnet withdrawal is not refused because t
344
407
  stagenet. The withdrawal window retries a `429`, a timeout or a `5xx` before it gives up. If the window still cannot be read,
345
408
  `restoreWallet` falls back to the full scan and reports `window.fallback: true` with `fallbackWhy: "window-read"` and
346
409
  the node's status; a withdrawal is not refused because the node was busy. When the wallet cannot reach the node's
347
- height, the result says `scanComplete: false` with `scanIncompleteReason: "sync-failed"`, `"behind-node"` or
348
- `"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.
349
412
 
350
413
  ## Extending to other networks (Tron, Solana and beyond)
351
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": "e9c934b0d5e6a164ea959e780e447485361913f91e7e5bcb475147b6cc657d8f",
6
+ "sha256": "82ff9f8b799c587b53ff9051de63185f030b352f6541cad698e2669ab42ccc86",
7
7
  "source": "sdk/src (facade, adapters, recovery)"
8
8
  }
9
9
  }