@ninsei-labs/sdk 0.50.0 → 0.51.1

package/CHANGELOG.md

@@ -1,3 +1,36 @@
+## 0.51.1 — 2026-10-22
+
+A BUSY NODE NO LONGER ENDS A WITHDRAWAL, AND MISSING HEIGHT DATA HAS A NAME.
+
+- `windowTxHashes` retries a `429`, a timeout and a `5xx` with `Retry-After` or exponential backoff; only a read that
+  still fails reaches the fallback.
+- `restoreWallet` runs the full scan when the window cannot be read and reports `window.fallback: true`,
+  `fallbackWhy: "window-read"` and the node's status. A malformed window is still a caller error, not a fallback.
+- A null settlement block time is `no-block-time`, not timestamp 0. An unreachable Monero node
+  (`monero-nodes-unreachable`) and a reachable node on another network (`monero-network-mismatch`) no longer share
+  `no-height-readers`.
+- `recoveryIndexTaken` is exported from `@ninsei-labs/sdk/recovery`.
+- The on-chain recovery-number check starts at the registry's escrow deployment block, not block 0; an explicit
+  `fromBlock` still wins.
+
+## 0.51.0 — 2026-10-22
+
+THE WITHDRAWAL AND THE ON-CHAIN SEARCH NOW CARRY EVERYTHING THE KEY CAN KNOW.
+
+- `sweep` keeps all 32 bytes of the revealed half; the old slice to 20 bytes made every real withdrawal fail.
+- The Monero node readers return the top block (`height - 1`) and accept the genesis timestamp, so `findSwaps` can
+  derive a start height instead of asking for a block that does not exist.
+- `quotes.firm` sends the taker's maker view half and requires the quote to echo it; without it a buy from the one
+  key could not be restored from the twelve words.
+- `quotes.sale` checks the signed claim tip with base plus priority fee, and `rankOffers` ranks a sale by
+  `amount × rate − claimTip`.
+- `sweep.restore` reports `window.fallback`; `findSwaps` returns `blockTime`, reads `xmrAmount` from the clone with
+  an `evmCode` reader, uses the factory's `deploymentBlock`, and names the native settlement while leaving the
+  paying token off-chain (`payToken: null`, `payTokenReason: "not-on-chain"`).
+- `sweep.fromOrder({ mnemonic, order })` builds the payload without a recovery file, and one wallet adapter now
+  serves both `sweep.restore` and `sweep.sign`.
+- The npm package ships the assets and `order-worker.js` its own code imports; Node floor is `>=24.22.1`.
+
 ## 0.50.0 — 2026-10-21
 
 A CLAIM IS SENT BY ITS CLAIMER, AND A SALE IS RANKED AFTER THE TIP.

package/README.md

@@ -155,6 +155,34 @@ the size is computed from the person's amount and is snapped to the node's grid
 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).
 
+## Found orders and the paying token
+
+`findSwaps` returns the orders whose commitment came from the recovery key. Each found order reports:
+
+- `amount` — the escrow's **native** amount in wei;
+- `settlementToken: "native"` — what the escrow receives;
+- `xmrAmount` — the XMR side, read from the clone's condition word 18 when an `evmCode` reader is passed;
+- `payToken: null` and `payTokenReason: "not-on-chain"` — the asset the person actually paid before the DEX leg.
+
+The reason is structural, not an omission. `OrderCreated` and the clone carry no token field, and the current escrow is
+native-only. A user may have paid USDC, USDT or DAI, but that happened in the DEX leg and lives in the quote/order
+record, not in the settlement contract. Inventing a token from the pair or the UI would be a claim the chain cannot
+support.
+
+When a token is needed, the order can be joined with an off-chain quote record by the caller. A future ERC-20 escrow
+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`.
+
+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,
+`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.
+
 ## Extending to other networks (Tron, Solana and beyond)
 
 The package name is deliberately common: the shared part — the quote client, the Monero leg, the state machine,