@ninsei-labs/sdk 0.52.0 → 0.54.0

package/CHANGELOG.md

@@ -1,3 +1,176 @@
+## 0.54.0 — 2026-10-29
+
+- `findSwaps` no longer walks the allocator's 100,000 v1 indices in one synchronous call. One call scans at most
+  `RECOVERY_SCAN_DEFAULT` (1000) indices, yields to the event loop between chunks, and returns `nextIndex` with
+  `complete: false` and `incompleteReason: "max-index"` when it stopped. A caller continues from `nextIndex`; a search
+  that matched every order in the logs is complete without scanning the rest. `maxIndex` is the number of indices for
+  this call.
+- `findSwaps` accepts an AbortSignal-like `signal` and an `onProgress` callback. An aborted scan returns
+  `incompleteReason: "aborted"` with the same `nextIndex`; progress is reported after every chunk and after the final
+  index. The SDK creates no worker: a caller can run the same call in one.
+- The relay firm client has its signed-features check and request builder: a `NodeFeatures` digest with the
+  `FirmWindow` array, signature recovery, request binding, a normalised client half, and one HPKE envelope per
+  request. Ask carries one view scalar; bid carries two. Wire revision 13 removed the `capabilities` array: the
+  features now always carry a nonzero HPKE key and at least one firm window.
+- The relay firm client's HTTP hop is `requestFirmQuote`: it posts the exact payload once, keeps a relay refusal
+  code (`compliance`, `no_liquidity`, `size`, `paused`, `unavailable`, `bad_request`, `price_changed`), maps a
+  transport failure to `server-unavailable`, and verifies the outer frame and the inner `OrderQuote` before
+  returning. It also checks the relay/forwarded/answer relay-id equality.
+- `quotes.firmRelay` is the recovery-key adapter: it derives the client half and both view points from one
+  key, fills the provider's role for ask or bid, verifies the node half's DLEQ proof and commitment, sends one
+  relay request, and checks the registry provider and factory against the answer before returning the signed
+  `orderQuote`, the one-time joint XMR address, a `counterparty` object ready for `swaps.start`, and the maker
+  view half. `FirmOffer` now matches the direct `firm` call (`providerId`, `order`, optional `viewHalfClaimer`).
+- `swaps.sellWatch` is the client-side sell wait: it reads the escrow itself and returns `ready`,
+  `claimed` or `refunded` (or `sell-timeout`), with no backend watcher and no signature.
+- `swaps.startSell` records a sell from a verified relay offer: the one-time address, escrow, our half and the
+  order expectations survive a reload; the same offer resumes the same record. `swaps.sellClaim` claims from
+  that record, from the claimer's own wallet.
+
+## 0.53.0 — 2026-10-28
+
+- A failed `rescanBlockchain` is no longer discarded: `sweep.restore` reports `scanComplete: false` with
+  `scanIncompleteReason: "rescan-failed"`, even when the wallet and node heights are equal. A wallet already at the
+  tip cannot turn a failed rescan into a successful no-op sync.
+- A `funding-pending` start keeps the sent transaction hash and the predicted escrow on the swap record. A retry of
+  the same quote reads that receipt and continues to `xmr-incoming` when it is funded, or returns
+  `funding-pending` again; it never builds a second side or sends a second deposit.
+- `scanRange` treats a block without its decoded `json`, a BUSY block, a transaction body count below the wrapper
+  count and an extra transaction as unreadable: the block is named in `missingHeights`, not counted as empty or as
+  money. Transaction results are mapped back by requested hash, so a partial answer cannot pass as complete.
+- The recovery-key store distinguishes "nothing stored" from "could not read": a throwing read is
+  `storage-unavailable { step: "read" }`, corrupt or unknown JSON is `storage-unavailable { step: "parse" }`, and a
+  failed write is `storage-unavailable { step: "write" }`. A corrupt record is no longer silently replaced by the
+  next start.
+- A new `swaps.start` uses a per-order salt by default: the order's own salt is the v2 recovery salt, and a missing
+  salt is drawn before the order context is built. A v1 recovery index is used only when the caller names one
+  explicitly, for restoring an old order.
+- The counterparty's view material is normalised once for the guard and the builder: conflicting `viewHalf` /
+  `viewHalfClaimer` or `viewPoint` / `viewPub` aliases are refused, the point is derived from the half when only the
+  half is present, and a half whose derived point differs from the declared point is refused before funding.
+- `quotes.sale` reads the `{ request: {...} }` envelope as the request, so a claimer named inside it is bound to the
+  signed quote. The requested XMR is compared with the signed `xmrAmount`, and a returned order is compared field by
+  field with the signed terms instead of only with the derived `context`.
+- The order worker now compares the proven secp256k1 point with the quote's `commitHalfClaimer`, not only the DLEQ
+  equation and the ed25519 point. `fundOrder` also refuses a signed quote whose `commitHalfClaimer` or
+  `edPointClaimer` differs from the verified order terms, and `swaps.start` checks the same pair before the lock.
+  A proof for one half can no longer be funded beside a quote that commits to another.
+- The default stagenet node is `https://xmr-stagenet.ninsei.finance`, operated by Ninsei. The old
+  `xmr.arrakisswap.trade` address is retired.
+- `sweep.fromOrder` keeps the order's XMR amount in the recovery file. A found order carries the amount the
+  provider signed in atomic units; the file now records it in whole XMR, so a withdrawal restored from that file
+  checks the arrival against the signed figure instead of a missing or shown amount.
+- `check:monero-live` starts against a real `monerod` in regtest: it refuses a non-regtest nettype, generates a
+  block range to an SDK-built address, runs `scanRange` over the range, and checks the daemon's `get_fee_estimate`
+  shape. It runs in the nightly workflow, not on every PR.
+- `check:types-consumer` compiles a minimal TypeScript consumer with `tsc --noEmit` against the package's own
+  exports map. It imports the root, `./xmr` and `./recovery`, assigns the public interfaces and calls the declared
+  entry points; a declaration that parses but cannot be consumed reddens here.
+- `check-packed-consumer` packs the package, installs that tarball into an empty project and imports every public
+  subpath, then checks the engine's relative assets. It catches a package that reads as complete but fails at the
+  consumer's first import.
+- `check-quote-binding` mutates every signed quote field one at a time: each must change the EIP-712 digest, each
+  must be named when absent, and the signature bytes must stay outside the digest.
+- `check-anvil-fork` now covers the refund and decline paths, a claim by a relayer with a non-zero `claimTip`, a
+  wrong half, `markReady` from a non-locker and a reused salt. The refund must publish the locker half; the decline
+  must publish none.
+- `check-atomic-flow` calls `runAtomicOrder` itself with stand-in worker and funding seams: it proves the sequence
+  reaches funding once, carries the salt, both commitments and the view point, returns the stand-in half and joint
+  address, and refuses a rejected counterparty before funding.
+- Pull-request CI now runs the complete registered check battery, not only the individually named steps. Storage,
+  scan-range, funding receipt, sweep window/order/adapter, claim-tip, claim-sender, quote-rank, provider, compose,
+  entries, version and settlement-profiles were registered in `check.mjs` but ran only in the release workflow.
+- `check-live-contract` asks the configured RPC for the chain id, the factory and cashier code, and the
+  implementation code hash. It is the cheapest check against the deployed contract.
+- `check-anvil-fork` forks Arbitrum Sepolia, registers a provider in the deployed registry, signs a quote locally,
+  runs `createOrderAndFund`, `markReady` and `claim`, and checks the event, escrow roles, revealed half and
+  dump/rewind repeat. Both checks run in the regular CI; Anvil is pinned to the same Foundry version as the
+  contract repository.
+- `check:dex` runs the CoW, Kyber, UniswapX and Uniswap Relay agreement vectors (real order signatures, EIP-712
+  digests, calldata and refusal tables) on every pull request; they used to run only in the release workflow.
+- `check-anvil-uniswap` forks Ethereum mainnet and executes the SDK's UniversalRouter calldata against the real
+  USDC/WETH pool, asserting native ETH reaches the recipient. It caught that Anvil's default account 2 has an
+  EIP-7702 delegation, so the check uses a plain EOA as the recipient.
+- `check-contract-vectors` pins three half commitments, the `OrderCreated` topic and both factory selectors against
+  values produced by Foundry `cast`, not by the SDK's own curve and hash code. A copy that hashes the half number
+  instead of its secp256k1 point reddens the check.
+- `check-order-proof` also exercises `orderStep`: a foreign commitment, a foreign point and a missing commitment are
+  refused before funding, not only by the builder in isolation.
+- Pull-request CI now runs the guards that were previously release-only: sale authentication, backup confirmation,
+  the one-key view half, arrival consensus, the recorded arrival fixture, order proof binding, both recovery-key
+  paths and recovery file opening. `check-ci-scripts` also refuses a `check:*` script that no workflow names, with a
+  breaking run; a guard that no pull request executes no longer counts as coverage.
+- `recovery.open` parses the envelope before handing it to `restoreFromFile`, which takes the object. Every valid
+  file used to fail as `recovery-failed { stage: "restore" }`; a non-JSON file now fails at its own `parse` stage,
+  and a valid file opens from both text and `{ contents }`.
+- The `types` group parses each declaration file with Node's TypeScript parser, not only its text. A missing comment
+  opener in `index.d.ts` is now a named syntax failure; that opener is restored.
+- `spendKeysFromRevealedHalf` reduces the revealed word modulo the secp256k1 order before adding it to our half. The
+  escrow accepts `h + n` in `claim`/`refund`; that alias is the same key on secp256k1 but not on edwards25519, so
+  reducing it makes such a swap withdrawable instead of refused as `revealedHalf`.
+- The per-swap recovery file start path is gone. It was assembled before funding and could not carry the escrow
+  address, so `sweep.plan` on that file reported `revealed-half` missing. Every start now requires the one recovery
+  key; the key is shown and confirmed before the lock. `StartRequest.onRecoveryFile` is removed.
+- `moneroFeeEstimate` reads the daemon's real units: `fee` and `fees` are atomic units per byte, and
+  `quantization_mask` is kept as `quantizationMask`. `feeForBytes` multiplies by the size instead of dividing by
+  1024, so a 1024-byte transaction at 20000/byte is 20,480,000, not 20,000. The old `feePerKB`/`medianFeePerKB`
+  fields were never sent by a daemon and are gone.
+- `scanRange` no longer reports a partial range as complete. A block that failed, a BUSY transaction answer, and a
+  response missing a requested transaction hash now appear in `missingHeights` with `complete: false` and
+  `incompleteReason: "blocks-unreadable"`; the per-address sums are still returned.
+- A height lock is judged at the witnessing node's tip, not at the block that mined the transfer. A transfer mined at
+  100 with `unlock_time` 101 is no longer `xmr-locked` at tip 120; confirmations still use the inclusion height.
+  `matchTransaction` takes `tipHeight` (and `scanRange` passes its top); the duplicate unlock rule in
+  `engine/monero/arrivalRead.js` now re-exports `engine/monero/unlock.js`.
+- A split sweep reports the SUM of every signed transaction's fee, not the first one. Both wallet adapters use one
+  helper; `sweep.sign` subtracts the total from the remainder, and `sweep.relay` already returns every txid. One
+  unreadable fee makes the total unknown (`null`), never a partial figure.
+- A failed settlement block-time read no longer drops every order already matched by `findSwaps`. The order is kept
+  with `blockTime: null` and `startHeightReason: "block-time-read"`; the other orders keep their heights.
+- The retired backend no longer decides a swap. A service watch row is an observation only: `receivedXmr > 0` is
+  returned as `seen: false` with `next: "verify"` and never signs `markReady`, and a service `declined` status is
+  no longer written into the record as a settlement. The escrow's `Declined` event remains the decline source.
+- Storage failures are named, not silent. A failed read, corrupt JSON, a failed write and a failed remove raise
+  `storage-unavailable` with `step` (`read`, `parse`, `write`, `serialize`, `remove`); only a missing value returns
+  the empty state. A second client with a different adapter is refused with `step: "conflict"` instead of taking
+  over the first client's records.
+- The SDK names its own line on every body route it sends to a node: `quotes.firm`, `quotes.sale` and the funding
+  mark carry `sdkVersion` from the package (`src/version.mjs`). A default node no longer refuses a current SDK with
+  `422 sdk-version-absent`; the caller cannot claim a different line.
+- Funding is no longer reported as complete from a sent transaction. `fundOrder` accepts only a status-1 receipt
+  with an `OrderCreated` from the factory that was called, for the predicted escrow; a reverted receipt is
+  `contract-reverted`, and a missing receipt, a missing event or a foreign event returns `pending` with a reason.
+  `swaps.start` refuses with `funding-pending` and does not save an escrow or retire a recovery number.
+- The Monero wallet adapter accepts the standard networks `mainnet`, `stagenet`, `testnet` and `fakechain`, not only
+  the names the demo's engine registry declares. A mainnet withdrawal is no longer refused as `bad-input` before the
+  library is called; the address-shape check still rejects an address from another network.
+- The recovery key has a salt-based v2 derivation: `ninsei-taker-v2|<chain>|<factory>|taker|<salt>`. The client draws
+  a fresh public salt per order; the salt is already in `OrderCreated`, so recovery costs one derivation per order
+  instead of an index scan. No index is reserved, and the same words on a second device or at another factory do not
+  repeat a half. Existing v1 orders still recover through `ninsei-taker-v1|<chain>|<index>`.
+- `swaps.start` accepts the client-owned `recoverySalt` and requires it to equal `order.salt`; without it the v1 index
+  path is unchanged. `newRecoverySalt` and `recoverySaltOf` are exported for the quote client.
+- `sweep.restore` reports `scanComplete: false` with `scanIncompleteReason: "sync-failed"`, `"behind-node"` or
+  `"no-heights"` when the wallet did not reach the node's height. A zero balance after a failed sync is no longer
+  reported as an empty wallet.
+- `findSwaps` no longer stops after five empty numbers. It searches the whole allocator range by default and
+  returns `complete: false` with `searchedUpTo` when a caller supplies a smaller `maxIndex`; `gap` is retained
+  but ignored.
+- `quotes.sale` authenticates the ticket instead of trusting its `signed` flag: the EIP-712 signature, expiry,
+  registry provider, interface allow-list, factory policy and the sale claimer's denylist are checked before the
+  ticket is returned.
+- On the key path, `start` requires the counterparty's view half to be the one derived from the words, chain
+  and index. A foreign or missing half is refused before funding, so the funded address can always be rebuilt.
+- A recovery key in storage is no longer treated as backed up. `backupConfirmed` is recorded only after
+  `onRecoveryKey` returns true; a declined or failed confirmation leaves the key unconfirmed, so the next start
+  asks again and cannot fund the escrow.
+- The XMR arrival check requires witnesses to agree on the whole observation, not only on a block hash, and
+  verifies every decoded amount against its Pedersen commitment (`mask*G + amount*H == outPk`). One altered node
+  can no longer turn a short payment into `arrived`; an unbacked amount is `xmr-nodes-disagree`. The compact
+  RingCT encoding (types 4-6) derives the mask, and a recorded stagenet type-6 transfer is pinned as a fixture.
+- The counterparty DLEQ proof is bound to the signed `commitHalfClaimer`: the proven secp256k1 point must match the
+  commitment the contract compares, and a side without a commitment is refused as input.
+
 ## 0.52.0 — 2026-10-26
 
 THE NEXT CONTRACT VERSION IS WIRED IN.
@@ -415,6 +588,99 @@ THE ENGINE MIRROR IS SYNCED AGAIN AFTER THE DEMO'S BUNDLE REBUILD.
 
 ## Unreleased
 
+- `check:monero-live` starts against a real `monerod` in regtest: it refuses a non-regtest nettype, generates a
+  block range to an SDK-built address, runs `scanRange` over the range, and checks the daemon's `get_fee_estimate`
+  shape. It runs in the nightly workflow, not on every PR.
+- `check:types-consumer` compiles a minimal TypeScript consumer with `tsc --noEmit` against the package's own
+  exports map. It imports the root, `./xmr` and `./recovery`, assigns the public interfaces and calls the declared
+  entry points; a declaration that parses but cannot be consumed reddens here.
+- `check-packed-consumer` packs the package, installs that tarball into an empty project and imports every public
+  subpath, then checks the engine's relative assets. It catches a package that reads as complete but fails at the
+  consumer's first import.
+- `check-quote-binding` mutates every signed quote field one at a time: each must change the EIP-712 digest, each
+  must be named when absent, and the signature bytes must stay outside the digest.
+- `check-anvil-fork` now covers the refund and decline paths, a claim by a relayer with a non-zero `claimTip`, a
+  wrong half, `markReady` from a non-locker and a reused salt. The refund must publish the locker half; the decline
+  must publish none.
+- `check-atomic-flow` calls `runAtomicOrder` itself with stand-in worker and funding seams: it proves the sequence
+  reaches funding once, carries the salt, both commitments and the view point, returns the stand-in half and joint
+  address, and refuses a rejected counterparty before funding.
+- Pull-request CI now runs the complete registered check battery, not only the individually named steps. Storage,
+  scan-range, funding receipt, sweep window/order/adapter, claim-tip, claim-sender, quote-rank, provider, compose,
+  entries, version and settlement-profiles were registered in `check.mjs` but ran only in the release workflow.
+- `check-live-contract` asks the configured RPC for the chain id, the factory and cashier code, and the
+  implementation code hash. It is the cheapest check against the deployed contract.
+- `check-anvil-fork` forks Arbitrum Sepolia, registers a provider in the deployed registry, signs a quote locally,
+  runs `createOrderAndFund`, `markReady` and `claim`, and checks the event, escrow roles, revealed half and
+  dump/rewind repeat. Both checks run in the regular CI; Anvil is pinned to the same Foundry version as the
+  contract repository.
+- `check:dex` runs the CoW, Kyber, UniswapX and Uniswap Relay agreement vectors (real order signatures, EIP-712
+  digests, calldata and refusal tables) on every pull request; they used to run only in the release workflow.
+- `check-anvil-uniswap` forks Ethereum mainnet and executes the SDK's UniversalRouter calldata against the real
+  USDC/WETH pool, asserting native ETH reaches the recipient. It caught that Anvil's default account 2 has an
+  EIP-7702 delegation, so the check uses a plain EOA as the recipient.
+- `check-contract-vectors` pins three half commitments, the `OrderCreated` topic and both factory selectors against
+  values produced by Foundry `cast`, not by the SDK's own curve and hash code. A copy that hashes the half number
+  instead of its secp256k1 point reddens the check.
+- `check-order-proof` also exercises `orderStep`: a foreign commitment, a foreign point and a missing commitment are
+  refused before funding, not only by the builder in isolation.
+- Pull-request CI now runs the guards that were previously release-only: sale authentication, backup confirmation,
+  the one-key view half, arrival consensus, the recorded arrival fixture, order proof binding, both recovery-key
+  paths and recovery file opening. `check-ci-scripts` also refuses a `check:*` script that no workflow names, with a
+  breaking run; a guard that no pull request executes no longer counts as coverage.
+- `recovery.open` parses the envelope before handing it to `restoreFromFile`, which takes the object. Every valid
+  file used to fail as `recovery-failed { stage: "restore" }`; a non-JSON file now fails at its own `parse` stage,
+  and a valid file opens from both text and `{ contents }`.
+- The `types` group parses each declaration file with Node's TypeScript parser, not only its text. A missing comment
+  opener in `index.d.ts` is now a named syntax failure; that opener is restored.
+- `spendKeysFromRevealedHalf` reduces the revealed word modulo the secp256k1 order before adding it to our half. The
+  escrow accepts `h + n` in `claim`/`refund`; that alias is the same key on secp256k1 but not on edwards25519, so
+  reducing it makes such a swap withdrawable instead of refused as `revealedHalf`.
+- The per-swap recovery file start path is gone. It was assembled before funding and could not carry the escrow
+  address, so `sweep.plan` on that file reported `revealed-half` missing. Every start now requires the one recovery
+  key; the key is shown and confirmed before the lock. `StartRequest.onRecoveryFile` is removed.
+- `moneroFeeEstimate` reads the daemon's real units: `fee` and `fees` are atomic units per byte, and
+  `quantization_mask` is kept as `quantizationMask`. `feeForBytes` multiplies by the size instead of dividing by
+  1024, so a 1024-byte transaction at 20000/byte is 20,480,000, not 20,000. The old `feePerKB`/`medianFeePerKB`
+  fields were never sent by a daemon and are gone.
+- `scanRange` no longer reports a partial range as complete. A block that failed, a BUSY transaction answer, and a
+  response missing a requested transaction hash now appear in `missingHeights` with `complete: false` and
+  `incompleteReason: "blocks-unreadable"`; the per-address sums are still returned.
+- A height lock is judged at the witnessing node's tip, not at the block that mined the transfer. A transfer mined at
+  100 with `unlock_time` 101 is no longer `xmr-locked` at tip 120; confirmations still use the inclusion height.
+  `matchTransaction` takes `tipHeight` (and `scanRange` passes its top); the duplicate unlock rule in
+  `engine/monero/arrivalRead.js` now re-exports `engine/monero/unlock.js`.
+- A split sweep reports the SUM of every signed transaction's fee, not the first one. Both wallet adapters use one
+  helper; `sweep.sign` subtracts the total from the remainder, and `sweep.relay` already returns every txid. One
+  unreadable fee makes the total unknown (`null`), never a partial figure.
+- A failed settlement block-time read no longer drops every order already matched by `findSwaps`. The order is kept
+  with `blockTime: null` and `startHeightReason: "block-time-read"`; the other orders keep their heights.
+- The retired backend no longer decides a swap. A service watch row is an observation only: `receivedXmr > 0` is
+  returned as `seen: false` with `next: "verify"` and never signs `markReady`, and a service `declined` status is
+  no longer written into the record as a settlement. The escrow's `Declined` event remains the decline source.
+- Storage failures are named, not silent. A failed read, corrupt JSON, a failed write and a failed remove raise
+  `storage-unavailable` with `step` (`read`, `parse`, `write`, `serialize`, `remove`); only a missing value returns
+  the empty state. A second client with a different adapter is refused with `step: "conflict"` instead of taking
+  over the first client's records.
+- The SDK names its own line on every body route it sends to a node: `quotes.firm`, `quotes.sale` and the funding
+  mark carry `sdkVersion` from the package (`src/version.mjs`). A default node no longer refuses a current SDK with
+  `422 sdk-version-absent`; the caller cannot claim a different line.
+- Funding is no longer reported as complete from a sent transaction. `fundOrder` accepts only a status-1 receipt
+  with an `OrderCreated` from the factory that was called, for the predicted escrow; a reverted receipt is
+  `contract-reverted`, and a missing receipt, a missing event or a foreign event returns `pending` with a reason.
+  `swaps.start` refuses with `funding-pending` and does not save an escrow or retire a recovery number.
+- The recovery key has a salt-based v2 derivation: `ninsei-taker-v2|<chain>|<factory>|taker|<salt>`. The client draws
+  a fresh public salt per order; the salt is already in `OrderCreated`, so recovery costs one derivation per order
+  instead of an index scan. No index is reserved, and the same words on a second device or at another factory do not
+  repeat a half. Existing v1 orders still recover through `ninsei-taker-v1|<chain>|<index>`.
+- `swaps.start` accepts the client-owned `recoverySalt` and requires it to equal `order.salt`; without it the v1 index
+  path is unchanged. `newRecoverySalt` and `recoverySaltOf` are exported for the quote client.
+- `sweep.restore` reports `scanComplete: false` with `scanIncompleteReason: "sync-failed"`, `"behind-node"` or
+  `"no-heights"` when the wallet did not reach the node's height. A zero balance after a failed sync is no longer
+  reported as an empty wallet.
+- `findSwaps` no longer stops after five empty numbers. It searches the whole allocator range by default and
+  returns `complete: false` with `searchedUpTo` when a caller supplies a smaller `maxIndex`; `gap` is retained
+  but ignored.
 THE ENGINE MIRROR (`engine/**`) CROSSES OVER IN ENGLISH, WITHOUT THE OLD BRAND AND WITHOUT A HARDCODED DOMAIN.
 All 45 modules are copied byte-for-byte from the demo repository's `sdk/engine` (`tools/build-sdk-engine.mjs`):
 comments are concise technical English and message strings are translated one to one, `Arrakis` is renamed to

package/README.md

@@ -17,7 +17,8 @@ machine). The wallet arrives as an EIP-1193 provider, storage as an adapter, and
 | `recovery.open` — parsing the recovery file | works |
 | `sim` — sandbox scenarios and time | works (applying to a swap — stage 2) |
 | `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`) |
-| `quotes.firm` | answers `not-implemented` (stage 2: signing with a key and the order protocol) |
+| `quotes.firm` | works: a signed, binding quote with a TTL; a refusal is a named code |
+| `quotes.firmRelay` | works: a firm quote through a relay, built from one recovery key; the node half is DLEQ-checked |
 | `swaps.list` / `swaps.get` | read state from storage (and after a page reload) |
 | `swaps.start` | holds the order: guards → recovery file and the person's confirmation → order → locking funds → **recording with us and watching the Monero address**; returns the named state `step: "xmr-incoming"` |
 | `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 |
@@ -26,6 +27,26 @@ machine). The wallet arrives as an EIP-1193 provider, storage as an adapter, and
 What is not ready names itself with the code `not-implemented` with the fields `surface` and `stage`: an empty
 value that looks like data is more dangerous than a refusal.
 
+## Settlement legs and VM profiles
+
+The settlement side is a driver, not a chain id switch. A VM profile says what that side looks like. The profile is
+metadata: it does not make a network runnable, and it does not carry a finality claim - finality is a chain policy,
+not a VM shape.
+
+| VM | Address form | Settlement | Ref | Driver today |
+|---|---|---|---|---|
+| `evm` | `hex-20` | contract | address | yes |
+| `tron` | `base58check` | contract | address | profile only |
+| `solana` | `base58` | program | PDA | profile only |
+| `bitcoin` | `base58check-or-bech32-or-bech32m` | UTXO script | script | profile only |
+
+The planned order is Tron, Solana, then Bitcoin. Dogecoin is not on that list and has no profile. A profile is not
+a driver: `LEGS` still holds only `evm`, so Tron, Solana and Bitcoin are refused by name until their own work lands.
+
+`chainConfig(...).settlementProfile` returns the profile for the network, or `null` for an unknown VM. The check
+`tools/check.mjs --only=settlement-profiles` guards the table, the absence of Dogecoin and the absence of a finality
+claim. A future driver adds its own settlement methods; the profile alone never authorizes a fund, claim or refund.
+
 ## The contract
 
 `index.d.ts` is the single source of truth about the API shape, and this is checked: `tools/check-sdk.mjs`
@@ -153,11 +174,21 @@ signature, the age (`ageMs`) and the maturity level (`finality`) — display fie
 The price does not depend on volume: the volume is needed by the provider to say whether it takes such a size. So
 the size is computed from the person's amount and is snapped to the node's grid **down**, and a size outside the
 range is not aligned: it is the provider's refusal, and it arrives as a code. Indicative quotes commit to nothing;
-`quotes.firm` commits (stage 2).
+`quotes.firm` and `quotes.firmRelay` commit, and the relay path carries the maker's signed terms and its view half.
 
 ## Found orders and the paying token
 
-`findSwaps` returns the orders whose commitment came from the recovery key. Each found order reports:
+`findSwaps` returns the orders whose commitment came from the recovery key. A salt-based order is found from the
+public `salt` in its own `OrderCreated`: the binding is `ninsei-taker-v2|<chain>|<factory>|taker|<salt>`, so the same
+words on another device or at another factory produce a different half and no number is reserved. The result says
+`derivation: "salt-v2"` and leaves `index` null. Existing v1 orders stay on `ninsei-taker-v1|<chain>|<index>` and are
+still found by the index path; a v2 result needs no range scan. For a v1 fallback, discovery does **not** stop after a
+run of empty numbers. One call scans at most `RECOVERY_SCAN_DEFAULT` (1000) indices; that keeps a shared factory from
+freezing the page. The result names where it stopped: `complete: false`, `searchedUpTo`, `incompleteReason: "max-index"`
+and `nextIndex`. A caller that needs more passes `nextIndex` back as `fromIndex`; the scan yields between chunks so the
+page stays responsive. `maxIndex` is the number of indices for this call, and `gap` is ignored. `onProgress` receives
+`{ scanned, index }` after each chunk and after the final index; `signal` stops between chunks and returns
+`incompleteReason: "aborted"` with the same resumable shape.
 
 - `amount` — the escrow's **native** amount in wei;
 - `settlementToken: "native"` — what the escrow receives;
@@ -173,15 +204,62 @@ When a token is needed, the order can be joined with an off-chain quote record b
 would have to put the token into the signed quote and the clone (and therefore a new order format and factory); only
 then can `findSwaps` return it from the chain and set `payTokenReason` to something other than `not-on-chain`.
 
+`swaps.start` takes the client-owned `recoverySalt` when the signed quote already carries that salt; it must equal
+`order.salt`. `newRecoverySalt()` draws a fresh 32-byte value, and `takerHalvesV2()` derives the halves without
+touching the index allocator.
+
 The found order also carries the Monero start height and the reason it is absent. `no-block-time`,
 `monero-nodes-unreachable` and `monero-network-mismatch` are different answers: a missing settlement timestamp is not
 a dead node, and a node on another network is not an absent reader. A page that starts swaps without the SDK's start
 path can call `recoveryIndexTaken` from `./recovery` before using a number; it checks the factory's `OrderCreated`
 logs from the registry's deployment block.
 
-The withdrawal window retries a `429`, a timeout or a `5xx` before it gives up. If the window still cannot be read,
+A revealed half published as `h + n` (the alias the escrow accepts) is reduced modulo the secp256k1 order before the
+sweep key check, so it rebuilds the same key and remains withdrawable.
+
+`recovery.open` accepts the file as text or `{ contents }`: the envelope is parsed at the boundary, so a valid file
+opens and a non-JSON one fails with its own `parse` stage.
+
+The per-swap recovery file start path is gone: a start requires the one recovery key, shown and confirmed before
+funding, and a file that could not name the escrow is no longer produced.
+
+`moneroFeeEstimate` reports the daemon's per-byte `fee`/`fees` and its `quantization_mask`; `feeForBytes` multiplies
+the price by the transaction size (1024 bytes at 20000/byte is 20,480,000).
+
+A range scan says whether it was complete: `scanRange` returns `complete: false`, `missingHeights` and
+`incompleteReason: "blocks-unreadable"` when a block, a BUSY transaction answer or a missing transaction hash leaves
+the range partial.
+
+A height lock is judged at the witnessing node's tip, not at the block that mined the transfer; confirmations still
+use the inclusion height.
+
+A split sweep reports the sum of every signed transaction's fee, not only the first; one unreadable fee makes the
+total unknown.
+
+A failed settlement block-time read keeps the matched order: `findSwaps` returns `blockTime: null` with
+`startHeightReason: "block-time-read"` instead of throwing away every row.
+
+The retired backend no longer decides a swap: its watch row may observe money, but it cannot declare readiness or
+a decline; the client's two-node check and the escrow's own `Declined` event do.
+
+Storage is a refusal, not a silent empty state: a failed read, corrupt JSON, a failed write or remove is
+`storage-unavailable` with a step, and a second client with another adapter is refused rather than taking over the
+first client's records.
+
+Every body route the SDK sends carries `sdkVersion` from the package (`quotes.firm`, `quotes.sale` and the funding
+mark). The caller cannot override it with a different line.
+
+Funding is reported from the receipt, not from the send. A status-0 receipt is `contract-reverted`; a missing
+receipt, a receipt without `OrderCreated`, or an event from another factory is `funding-pending` with the transaction
+hash, and `swaps.start` does not save an escrow or retire a recovery number in that state.
+
+The wallet adapter accepts the standard Monero network names (`mainnet`, `stagenet`, `testnet`, `fakechain`) and
+still checks the address shape, so a mainnet withdrawal is not refused because the demo registry lists only
+stagenet. The withdrawal window retries a `429`, a timeout or a `5xx` before it gives up. If the window still cannot be read,
 `restoreWallet` falls back to the full scan and reports `window.fallback: true` with `fallbackWhy: "window-read"` and
-the node's status; a withdrawal is not refused because the node was busy.
+the node's status; a withdrawal is not refused because the node was busy. When the wallet cannot reach the node's
+height, the result says `scanComplete: false` with `scanIncompleteReason: "sync-failed"`, `"behind-node"` or
+`"no-heights"`; a zero balance in that state is not an empty wallet.
 
 ## Extending to other networks (Tron, Solana and beyond)
 

package/engine/atomic/order-worker.js

@@ -13,6 +13,20 @@ import {
 
 const builder = createOrderBuilder({ ed25519, secp256k1, keccak256, sha3_512, randomBytes });
 
+// THE COMMITMENT THE CONTRACT WILL COMPARE, DERIVED FROM THE PROVEN POINT. The worker's vendored builder can check
+// the DLEQ equation, but its verifySide did not compare the proven secp256k1 point with the quote's commitment.
+// engine/atomic/order.js carries that comparison; this worker runs the prebuilt bundle, so the same comparison is
+// made here from the bundle's own secp256k1 and keccak256. A proof that is valid for another point must not build a
+// side that funding then signs.
+const commitmentOfPoint = (value) => {
+  try {
+    const point = secp256k1.Point.fromHex(String(value || "").replace(/^0x/i, ""));
+    const xy = point.toBytes(false).slice(1);
+    return "0x" + Array.from(keccak256(xy), (b) => b.toString(16).padStart(2, "0")).join("");
+  } catch { return null; }
+};
+const low160 = (value) => String(value || "").replace(/^0x/i, "").toLowerCase().slice(-40);
+
 // Ключи шифрования построенных сторон: приватный ключ по своему публичному. Наружу приватные не уходят -
 // вскрытие посылки происходит здесь.
 //
@@ -111,14 +125,27 @@ self.onmessage = async (event) => {
       });
     } else if (type === "verify") {
       say("verify", "проверяю доказательство контрагента");
-      const side = { proof: counterparty.proof, pub: { ed: counterparty.edPub } };
+      const side = { proof: counterparty.proof, pub: { ed: counterparty.edPub }, commitHalfClaimer: counterparty.commitHalfClaimer || null };
       // Вскрываем тем ключом, на который посылка была зашифрована в этом контексте.
       const recipient = sealedToPub.get(String(orderContext));
       const openWith = recipient ? encPrivByPub.get(recipient) : null;
       if (sealedBytes && !openWith) {
         throw new Error("нет ключа, которым вскрывать посылку: не было шифрования в этом контексте ордера");
       }
-      const verdict = builder.verifySide(side, orderContext, sealedBytes || null, openWith);
+      let verdict = builder.verifySide(side, orderContext, sealedBytes || null, openWith);
+      // THE PROOF IS ABOUT THE COMMITMENT IN THE QUOTE, not only about two points that stand for one scalar. The
+      // contract pays against commitHalfClaimer; without this comparison a counterparty proves one point and funds
+      // another, and the half revealed at claim time does not open the joint address.
+      if (verdict && verdict.ok === true) {
+        if (!counterparty.commitHalfClaimer) {
+          verdict = { ok: false, reason: "the counterparty side carries no commitHalfClaimer" };
+        } else {
+          const proven = commitmentOfPoint(counterparty.proof && counterparty.proof.XA);
+          if (!proven || low160(proven) !== low160(counterparty.commitHalfClaimer)) {
+            verdict = { ok: false, reason: "the proven secp256k1 point does not match commitHalfClaimer: " + (proven || "unparsed") + " vs " + counterparty.commitHalfClaimer };
+          }
+        }
+      }
       self.postMessage({ id, kind: "done", result: verdict });
     } else {
       self.postMessage({ id, kind: "error", message: "неизвестный запрос воркеру: " + String(type) });

package/engine/atomic/order.js

@@ -60,6 +60,30 @@ export function createOrderBuilder({ ed25519, secp256k1, keccak256, sha3_512, ra
     if (side.pub && side.pub.ed && String(side.proof.XB).toLowerCase() !== String(side.pub.ed).toLowerCase()) {
       return { ok: false, reason: "the proven ed25519 point does not match the declared one: " + side.proof.XB + " vs " + side.pub.ed };
     }
+    // THE COMMITMENT IS PART OF THE PROOF'S MEANING. The contract does not compare halves to a hash of a number:
+    // it compares `half*G` (through ecrecover) with `commitHalfClaimer`. A proof confirms only that XA and XB stand
+    // for one scalar; without this comparison a counterparty could prove XA, put another point in the quote, and
+    // the contract would reject the half at claim time - after the other side has paid.
+    //
+    // `proof.XA` is the compressed secp256k1 point of the half. The commitment is keccak256 of the UNCOMPRESSED
+    // 64-byte coordinates, and the contract compares only its low 160 bits (`uint160`), so the comparison is made
+    // on the same 20 bytes.
+    if (side.commitHalfClaimer) {
+      let provenCommit = null;
+      try {
+        const point = secp256k1.Point.fromHex(String(side.proof.XA).replace(/^0x/, ""));
+        const xy = point.toBytes(false).slice(1);
+        provenCommit = "0x" + Array.from(keccak256(xy), (b) => b.toString(16).padStart(2, "0")).join("");
+      } catch { provenCommit = null; }
+      const low160 = (v) => String(v || "").replace(/^0x/, "").toLowerCase().slice(-40);
+      if (!provenCommit || low160(provenCommit) !== low160(side.commitHalfClaimer)) {
+        return { ok: false, reason: "the proven secp256k1 point does not match commitHalfClaimer: " + (provenCommit || "unparsed") + " vs " + side.commitHalfClaimer };
+      }
+    } else {
+      // A REAL COUNTERPARTY MUST CARRY THE COMMITMENT. Accepting a proof without it leaves the link between the
+      // proven half and the contract unchecked; the stand-in path supplies its own commitment in order.mjs.
+      return { ok: false, reason: "the counterparty side carries no commitHalfClaimer" };
+    }
     if (sealedPayloadBytes && ownEncPriv) {
       const opened = enc.open(enc.unpackSealed(sealedPayloadBytes), ownEncPriv, side.pub.ed);
       if (!opened.ok) return { ok: false, reason: "the counterparty envelope does not confirm the half: " + opened.reason };

package/engine/core/store.js

@@ -46,11 +46,40 @@ const webStorage = (name) => {
 };
 
 let adapter = webStorage("localStorage") || memoryStorage();
+// A SECOND CLIENT WITH ANOTHER STORE USED TO TAKE OVER THE FIRST ONE'S RECORDS: the adapter was module-wide, so
+// A listed B's swaps and A's forget deleted them. The SDK binds one explicit store to the process; a different
+// one is refused instead of silently switching under a live client. `setStorage` remains the test/setup reset.
+let bound = null;
 
-/** Swap the storage. The shape is checked, not the origin: localStorage, memory and the SDK all qualify. */
-export function setStorage(next) {
+const checkAdapter = (next) => {
   const ok = next && typeof next.get === "function" && typeof next.set === "function" && typeof next.remove === "function";
   if (!ok) throw new Error("storage must support get/set/remove");
+};
+
+const storageFailure = (step, cause) => {
+  const error = new Error("storage-unavailable");
+  error.code = "storage-unavailable";
+  error.params = { step };
+  if (cause) error.cause = cause;
+  return error;
+};
+
+/** Swap the storage for setup and tests. It also releases the exclusive binding, so a later client may bind. */
+export function setStorage(next) {
+  checkAdapter(next);
+  adapter = next;
+  bound = null;
+  return adapter;
+}
+
+/**
+ * Bind the store of a client instance. A second, different store is a refusal: records and recovery keys are
+ * addressed through one adapter, and switching it under a live client loses the first client's records.
+ */
+export function bindStorage(next) {
+  checkAdapter(next);
+  if (bound && bound !== next) throw storageFailure("conflict");
+  bound = next;
   adapter = next;
   return adapter;
 }
@@ -59,14 +88,23 @@ export function setStorage(next) {
 export const storage = () => adapter;
 
 export function loadState() {
+  let raw;
+  try {
+    raw = adapter.get(APP.storageKey);
+  } catch (error) {
+    throw storageFailure("read", error);
+  }
+  // NOTHING STORED IS NOT AN UNREADABLE STORE. Only a missing value returns the empty state; a value that does
+  // not parse is a refusal, so the next write cannot silently save over a corrupt record.
+  if (raw === null || raw === undefined || raw === "") return structuredClone(EMPTY);
+  let parsed;
   try {
-    const raw = adapter.get(APP.storageKey);
-    if (!raw) return structuredClone(EMPTY);
-    const parsed = JSON.parse(raw);
-    return { ...structuredClone(EMPTY), ...parsed, settings: { ...EMPTY.settings, ...(parsed.settings || {}) } };
-  } catch {
-    return structuredClone(EMPTY);
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw storageFailure("parse", error);
   }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw storageFailure("parse");
+  return { ...structuredClone(EMPTY), ...parsed, settings: { ...EMPTY.settings, ...(parsed.settings || {}) } };
 }
 
 // BigInt IS NOT SERIALISED IN JSON - and the key halves are BigInt. JSON.stringify FAILS on them
@@ -75,10 +113,16 @@ export function loadState() {
 // We turn BigInt into a hex string: the same meaning, but serialisable, and the secret is not lost.
 const bigintSafe = (key, value) => (typeof value === "bigint" ? "0x" + value.toString(16) : value);
 export function saveState(state) {
+  let text;
   try {
-    adapter.set(APP.storageKey, JSON.stringify(state, bigintSafe));
-  } catch (e) {
-    console.warn("state save failed", e);
+    text = JSON.stringify(state, bigintSafe);
+  } catch (error) {
+    throw storageFailure("serialize", error);
+  }
+  try {
+    adapter.set(APP.storageKey, text);
+  } catch (error) {
+    throw storageFailure("write", error);
   }
   return state;
 }
@@ -91,7 +135,11 @@ export function update(mutator) {
 }
 
 export function reset() {
-  adapter.remove(APP.storageKey);
+  try {
+    adapter.remove(APP.storageKey);
+  } catch (error) {
+    throw storageFailure("remove", error);
+  }
 }
 
 export function exportState() {