@ninsei-labs/sdk 0.48.1 → 0.50.0

package/CHANGELOG.md

@@ -1,3 +1,30 @@
+## 0.50.0 — 2026-10-21
+
+A CLAIM IS SENT BY ITS CLAIMER, AND A SALE IS RANKED AFTER THE TIP.
+
+- `actions.claim` compares the wallet's address with `request.claimer` or `expect.claimer` before it signs. A
+  third-party wallet, a missing claimer or a wallet without an address is a named `bad-input`; `claimSenderVerdict`
+  exposes the same rule. This is a deliberate tightening: a claim reveals the half to its sender.
+- `readQuote` keeps the signed `claimTip`, and `rankOffers` selects a sale by `amount × rate − claimTip`, not by
+  the headline rate. A buy, or a request without an amount, still ranks by rate.
+- `quotes.watch` uses that ranking for the chosen offer, so moving margin from the price into the tip no longer
+  wins a sale.
+
+## 0.49.0 — 2026-10-21
+
+A ONE-KEY RECOVERY CAN WITHDRAW WITHOUT A FULL SCAN, AND A CLAIM TIP IS CHECKED.
+
+- `findSwaps` accepts `xmrNodes` and `moneroNetwork`: it asks the node for `get_info` and
+  `get_block_header_by_height` itself, so a page needs only `evmBlockTime`; the `startHeight` rule stays in the SDK.
+- `sweep.restore({ window })` sets the wallet at the node tip, scans only the blocks from the swap's start to
+  `t1 + 10` through `scanTxs` (batches of 100), checks the wallet's key images at `/is_key_image_spent`, and does
+  not run `rescanBlockchain` after `scanTxs`. An empty window falls back to the full scan; `windowTxHashes` collects
+  the hashes from a node.
+- `quotes.firm` refuses a `claimTip` above twice the SDK's own `claimGasGiftWei` estimate, read from the new
+  `evmBlock` seam. Zero tips (the buy side) do not call it; an unmeasured base fee is named.
+- `claimTipVerdict` is exported for the same arithmetic outside the quote path.
+- No breaking changes: the old recovery-file path, the full restore and zero-tip quotes behave as before.
+
 ## 0.48.1 — 2026-10-21
 
 A SWAP KEEPS ITS MONERO HEIGHT, AND A RECOVERED ORDER KNOWS WHERE TO SCAN.

package/index.d.ts

@@ -108,6 +108,13 @@ export interface NinseiOptions {
    * the order's escrow and the topic is the package's own.
    */
   evmLogs?: EvmLogReader;
+  /**
+   * READING A SETTLEMENT BLOCK FROM OUTSIDE (`(tag) => block`): the claim-tip check needs the chain's current
+   * `baseFeePerGas`. A missing seam is `quote-tip-unchecked` when a quote carries a non-zero tip; zero tips (the
+   * buy side) never call it.
+   */
+  evmBlock?: (tag?: string) => Promise<{ readonly baseFeePerGas?: string | number | bigint | null;
+    readonly baseFeeWei?: string | number | bigint | null }>;
   /**
    * THE INTERFACE'S OWN ADMISSION LIST - policy, not proof. The chain (maker registry, providerOf, taken from the
    * quote) proves whose key signed; this says whom THIS interface trades with at all. An array of provider
@@ -500,6 +507,8 @@ export interface QuoteOffer {
   readonly currency: string | null;
   readonly rate: number;
   readonly rateQuote: number;
+  /** The claim tip in native-token wei; a sale is ranked by the payout AFTER it. */
+  readonly claimTip: string;
   readonly min: number | null;
   readonly max: number | null;
   readonly step: number | null;
@@ -1296,6 +1305,20 @@ export interface SweepRestoreRequest {
   readonly scanBack?: number;
   /** Run the second pass when coins exist but none is spendable. Default true. */
   readonly rescanWhenLocked?: boolean;
+  /**
+   * THE BLOCK WINDOW AROUND THE LOCK. When present, the wallet is set at the node tip and only these blocks are
+   * scanned. An empty window falls back to the full scan unless `fallback` is false. `txHashes` may be supplied by
+   * the caller; otherwise the SDK reads `get_block` from `nodeUrl`.
+   */
+  readonly window?: {
+    readonly nodeUrl?: string;
+    readonly txHashes?: readonly string[];
+    readonly toHeight: number;
+    readonly tipHeight: number;
+    readonly fallback?: boolean;
+  };
+  /** The fetch used for `get_block`; absent - the global fetch. */
+  readonly fetchImpl?: typeof fetch;
 }
 
 /** What `restore` found. Amounts are atomic units as strings; heights are numbers when the driver can read them. */
@@ -1310,6 +1333,18 @@ export interface SweepRestoreResult {
   readonly passes: number;
   /** Whether the second pass RAN - not whether it helped. */
   readonly lockedPass: boolean;
+  /** Present when a window was requested: whether it was used, and why it was skipped. */
+  readonly window?: {
+    readonly used: boolean;
+    readonly skipped: string | null;
+    readonly fromHeight: number;
+    readonly toHeight: number;
+    readonly blocks: number;
+    readonly txs: number;
+    readonly spent?: number | null;
+    readonly keyImages?: number;
+    readonly spentWhy?: string;
+  } | null;
 }
 
 /** What `wallet` needs: the library namespace and the facts the wallet is built from. */
@@ -1564,6 +1599,9 @@ export interface ActionsApi {
 export interface ActionsRequest {
   readonly escrow: string;
   readonly expect: Readonly<Record<string, unknown>>;
+  /** The claimer whose half is revealed by `claim`; absent - `expect.claimer` is used. A claim without one is
+   * refused: the package sends it only from the claimer's own wallet, never from a third-party sender. */
+  readonly claimer?: string;
   readonly onStep?: (stage: string, detail?: string) => void;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninsei-labs/sdk",
-  "version": "0.48.1",
+  "version": "0.50.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/src/actions.mjs

@@ -25,6 +25,18 @@ const walletOrFail = (wallet) => {
   return wallet;
 };
 
+// THE CLAIM'S HALF IS REVEALED BY WHOEVER SENDS IT. The package sends a claim only from the claimer's own wallet:
+// a third-party sender would see the half before the claim is mined, and the only reason to use one is the tip -
+// not a reason to hand the half to another party. A caller with no claimer is refused, not sent blind.
+export function claimSenderVerdict({ sender = null, claimer = null } = {}) {
+  const from = typeof sender === "string" ? sender.trim().toLowerCase() : "";
+  const to = typeof claimer === "string" ? claimer.trim().toLowerCase() : "";
+  if (!to) return { ok: false, code: "bad-input", field: "claimer" };
+  if (!from) return { ok: false, code: "bad-input", field: "wallet.address" };
+  if (from !== to) return { ok: false, code: "bad-input", field: "wallet", why: "not-the-claimer" };
+  return { ok: true };
+}
+
 const requestOrFail = (request, extra) => {
   if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
   const missing = missingFields(request, ["escrow", "expect", ...extra]);
@@ -59,6 +71,9 @@ export function createActions({ call = null } = {}) {
       requestOrFail(request, ["halfClaimer"]);
       walletOrFail(wallet);
       const { escrow, halfClaimer, expect, onStep } = request;
+      const sender = typeof wallet.address === "function" ? await wallet.address() : null;
+      const verdict = claimSenderVerdict({ sender, claimer: request.claimer || (expect && expect.claimer) });
+      if (!verdict.ok) throw new SdkError(verdict.code, { field: verdict.field, why: verdict.why, surface: "actions.claim" });
       return await withCodes("claim", () => flow.claimOrder({ escrow, halfClaimer, expect, onStep, deps: deps(wallet) }));
     },
     /** Refunding: it also reveals a half. The core passes the expectations ALWAYS, though the engine does not require them. */

package/src/index.mjs

@@ -91,6 +91,9 @@ const normalizeOptions = (options) => {
   // same provider the chain read uses. Same rule as evmCall: a READ of the escrow's own event, not a node
   // substitution.
   if (o.evmLogs !== undefined && typeof o.evmLogs !== "function") fail("bad-input", { field: "evmLogs" });
+  // THE BLOCK-READ SEAM: the claim tip is checked against the chain's current base fee, and that is a block read,
+  // not an `eth_call`. Same rule as evmCall - brought from outside, refused when it is not a function.
+  if (o.evmBlock !== undefined && typeof o.evmBlock !== "function") fail("bad-input", { field: "evmBlock" });
   // THE INTERFACE'S ALLOW-LIST (POLICY, NOT PROOF): an array of provider addresses (or providerIds) OR a
   // predicate. It is NOT the check itself - that is `providerOf` on chain, taken from the quote - but the
   // interface's own decision about whom it trades with. A wrong shape is a typo, not a silent no-op.
@@ -156,6 +159,7 @@ const normalizeOptions = (options) => {
     evmCall: o.evmCall || null,
     evmCode: o.evmCode || null,
     evmLogs: o.evmLogs || null,
+    evmBlock: o.evmBlock || null,
     allowedProviders: o.allowedProviders === undefined ? null : o.allowedProviders,
     knownFactoryCodes: o.knownFactoryCodes === undefined ? null : o.knownFactoryCodes,
     knownImplementationCodes: o.knownImplementationCodes === undefined ? null : o.knownImplementationCodes,
@@ -215,7 +219,8 @@ export function createNinsei(options) {
     ? new Set(o.denylist.map((a) => String(a).toLowerCase()))
     : null;
   const quotes = createQuotes({ config, http, now: o.now || (() => Date.now()), evmCall: o.evmCall || null,
-    evmCode: o.evmCode || null, providerAllowed, knownFactoryCodes: o.knownFactoryCodes, knownImplementationCodes: o.knownImplementationCodes,
+    evmCode: o.evmCode || null, evmBlock: o.evmBlock || null,
+    providerAllowed, knownFactoryCodes: o.knownFactoryCodes, knownImplementationCodes: o.knownImplementationCodes,
     denylist });
   // THE SAME CHAIN-READ SEAM AS THE LOCK AND THE CORE: checking the slots and signing must go one way, otherwise
   // part of the check goes past the wallet and part does not.

package/src/public/recovery.d.ts

@@ -385,4 +385,11 @@ export declare function findSwaps(request: {
   moneroTip?: () => Promise<number>;
   /** A Monero block header timestamp, in seconds: (height) -> seconds. */
   moneroBlockTimestamp?: (height: number) => Promise<number>;
+  /** Convenience: the node URLs the caller already probed. When the two Monero readers above are absent, the SDK
+   * asks these for `get_info` and `get_block_header_by_height` itself. */
+  xmrNodes?: readonly (string | { readonly url: string })[];
+  /** The Monero network those nodes must name (mainnet, stagenet, testnet). */
+  moneroNetwork?: string | null;
+  /** The fetch used for those node requests; absent - the global fetch. */
+  fetchImpl?: typeof fetch;
 }): Promise<{ swaps: FoundSwap[]; scanned: number }>;

package/src/quotes.mjs

@@ -18,6 +18,7 @@
 import { fail } from "./errors.mjs";
 import * as engine from "./engine.mjs";
 import { orderQuoteMissingFields, recoverOrderQuoteKey } from "./quoteEip712.mjs";
+import { claimGasGiftWei } from "../engine/evm/claimGas.js";
 // THE CHAIN READ NEEDED TO ASK THE REGISTRY WHO OWNS THE KEY. The selector is COMPUTED from the signature, not
 // remembered: a single wrong hex digit would call another function and return a zero address - and a zero
 // address is exactly the answer "nobody owns this key", which the caller would take as the truth.
@@ -82,6 +83,13 @@ export function readQuote(pair, raw, owner = {}, data = {}) {
     currencyNetwork: q.currencyNetwork ? String(q.currencyNetwork) : null,
     rateQuote,
     rate,
+    // THE CLAIM TIP IS IN THE MAKER'S NATIVE TOKEN (wei). A sale is ranked by what the seller receives AFTER it;
+    // the value is kept as a string, because a wei amount does not fit a float reliably.
+    claimTip: (() => {
+      if (q.claimTip === undefined || q.claimTip === null || q.claimTip === "") return "0";
+      try { const n = BigInt(q.claimTip); return n < 0n ? "0" : n.toString(); }
+      catch { return "0"; }
+    })(),
     min: num(q.min),
     max: num(q.max),
     step: num(q.step),
@@ -103,6 +111,27 @@ export function readQuote(pair, raw, owner = {}, data = {}) {
   };
 }
 
+/**
+ * THE BEST OFFER IS THE ONE THAT PAYS THE MOST, NOT THE ONE WITH THE HIGHEST RATE. On a sale the maker may move
+ * its margin into `claimTip`: the escrow pays that tip out of the seller's payout, so a higher rate with a larger
+ * tip can leave the seller with less. With no amount there is nothing to compare beyond the rate, and a buy has
+ * no tip. Native-token wei are converted at 18 decimals: a sale settles in the chain's native coin.
+ */
+export function rankOffers(offers = [], { direction = "buy", amount = null } = {}) {
+  const list = Array.isArray(offers) ? offers.filter((offer) => offer && Number(offer.rate) > 0) : [];
+  const amountXmr = Number(amount);
+  const score = (offer) => {
+    const rate = Number(offer.rate);
+    if (direction !== "sell" || !(amountXmr > 0)) return rate;
+    let tip = 0;
+    try { tip = Number(BigInt(offer.claimTip || "0")) / 1e18; } catch { tip = 0; }
+    return amountXmr * rate - tip;
+  };
+  const ranked = list.map((offer) => ({ offer, net: score(offer) }))
+    .sort((a, b) => (b.net - a.net) || (Number(b.offer.rate) - Number(a.offer.rate)));
+  return { best: ranked.length ? ranked[0].offer : null, net: ranked.length ? ranked[0].net : null, ranked };
+}
+
 /**
  * Parsing the book in one place. The envelope is accepted in three forms (a map by pairs, a list of rows, a list
  * of providers) and is brought to a single list: the screen must not know which form the answer came in.
@@ -200,7 +229,7 @@ const compactOffer = (o) => ({
   assetNetwork: o.assetNetwork, currencyNetwork: o.currencyNetwork, networkStated: o.networkStated,
   networksDerived: o.networksDerived === true, networksUnnamed: o.networksUnnamed === true,
   // THE REASON (in the provider's words), THE PACKAGE'S SIGNATURE AND KEY, THE AGE BY ITS OWN MARK.
-  why: o.why, signature: o.signature, keyId: o.keyId, ageMs: o.ageMs,
+  claimTip: o.claimTip, why: o.why, signature: o.signature, keyId: o.keyId, ageMs: o.ageMs,
   networks: { asset: o.assetNetwork, currency: o.currencyNetwork, stated: o.networkStated },
 });
 
@@ -208,7 +237,32 @@ const compactOffer = (o) => ({
 // the price of the failed row to tell the person WHY there is no offer (and not just "none").
 const compactRefusal = (r) => ({ ...compactOffer(r), code: r.code, why: r.why });
 
-export function createQuotes({ config, http, now = () => Date.now(), evmCall = null, evmCode = null, providerAllowed = null, knownFactoryCodes = null, knownImplementationCodes = null, denylist = null }) {
+/**
+ * A CLAIM TIP IS SIZED BY THE CLAIM, NOT BY THE MAKER'S MOOD. The node's own estimate uses the chain's current
+ * base fee and the same formula; a quote may carry up to twice that estimate (gas moves between the sizing and
+ * the check). Zero is the buy side and is always allowed. An unmeasured base fee is a refusal, not a free pass.
+ */
+export function claimTipVerdict({ claimTipWei = 0, baseFeeWei = null, priorityFeeWei = 0, factor = 2 } = {}) {
+  let tip = 0n;
+  try { tip = BigInt(claimTipWei === undefined || claimTipWei === null || claimTipWei === "" ? 0 : claimTipWei); }
+  catch { return { ok: false, code: "quote-tip-unreadable" }; }
+  if (tip < 0n) return { ok: false, code: "quote-tip-unreadable" };
+  if (tip === 0n) return { ok: true, tipWei: "0", ceilingWei: null, estimateWei: null };
+  if (baseFeeWei === null || baseFeeWei === undefined || baseFeeWei === "") {
+    return { ok: false, code: "quote-tip-unchecked", tipWei: tip.toString() };
+  }
+  const estimate = claimGasGiftWei({ baseFeeWei, priorityFeeWei });
+  if (estimate === null) return { ok: false, code: "quote-tip-unchecked", tipWei: tip.toString() };
+  const f = BigInt(factor);
+  const ceiling = estimate * f;
+  if (tip > ceiling) {
+    return { ok: false, code: "quote-tip-too-large", tipWei: tip.toString(), estimateWei: estimate.toString(), ceilingWei: ceiling.toString() };
+  }
+  return { ok: true, tipWei: tip.toString(), estimateWei: estimate.toString(), ceilingWei: ceiling.toString() };
+}
+
+export function createQuotes({ config, http, now = () => Date.now(), evmCall = null, evmCode = null, evmBlock = null,
+  providerAllowed = null, knownFactoryCodes = null, knownImplementationCodes = null, denylist = null }) {
   // THE INTERFACE'S FACTORY POLICY (#103): the code hashes of factories it is willing to trade through
   // (extcodehash semantics = keccak256 of the runtime code). An EMPTY list is "no policy" (like
   // allowedProviders); a NON-EMPTY one refuses any factory whose code is not on it. Lower-cased once.
@@ -241,8 +295,11 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
       const asked = explicit ? Number(request.size) : size;
       const data = await http.json("/rate?amount=" + encodeURIComponent(asked) + "&side=" + encodeURIComponent(request.direction));
       const book = readBook(data, now());
-      const offer = book.best;
       const amount = Number.isFinite(Number(request.amount)) ? Number(request.amount) : null;
+      // A SALE IS RANKED BY THE PAYOUT AFTER THE TIP; a buy has no tip. Without an amount the rate is the only
+      // comparable number, and the service's own best remains the fallback.
+      const ranked = rankOffers(book.offers, { direction: request.direction, amount });
+      const offer = ranked.best || book.best;
       // The size derived from the person's amount becomes the size of the NEXT request: the price does not depend
       // on volume, and the volume is needed by the provider to say whether it takes such a size. With a named size
       // there is nothing to derive - it stays what it was asked as.
@@ -507,6 +564,24 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
       if (String(quoted) !== expectedContext) {
         fail("quote-refused", { step: "context", why: quoted ? "other-terms" : "not-reported" });
       }
+      // THE CLAIM TIP: the seller pays it out of the payout, so a quote that asks for more than the claim can
+      // cost is refused before it is signed. The chain's base fee is read through the caller's block seam; a
+      // missing seam or an unreadable base fee is a named refusal, never a silently accepted tip.
+      const tipCheck = (() => {
+        try { return claimTipVerdict({ claimTipWei: quote.claimTip }); }
+        catch { return { ok: true, tipWei: "0" }; }
+      })();
+      if (!tipCheck.ok && tipCheck.code === "quote-tip-unreadable") {
+        fail("quote-field-unbound", { step: "claimTip", field: "claimTip" });
+      }
+      if (tipCheck.tipWei !== "0") {
+        if (typeof evmBlock !== "function") fail("quote-tip-unchecked", { step: "claimTip", why: "no-block-read" });
+        let block = null;
+        try { block = await evmBlock("latest"); } catch { fail("quote-tip-unchecked", { step: "claimTip", why: "block-read-failed" }); }
+        const baseFeeWei = block && (block.baseFeePerGas !== undefined ? block.baseFeePerGas : block.baseFeeWei);
+        const verdict = claimTipVerdict({ claimTipWei: quote.claimTip, baseFeeWei });
+        if (!verdict.ok) fail(verdict.code, { step: "claimTip", ...verdict });
+      }
       return quote;
     },
   };

package/src/recovery-key.mjs

@@ -19,6 +19,7 @@ import { createHalves } from "../engine/atomic/halves.js";
 import { halfCommitmentHex } from "../engine/atomic/orderHalfCommit.js";
 import { ORDER_CREATED_TOPIC } from "../engine/evm/factory.js";
 import { SdkError } from "./errors.mjs";
+import { probeMoneroNode } from "./probes.mjs";
 import { ed25519, keccak256, randomBytes, secp256k1 } from "./primitives.mjs";
 
 const halves = createHalves({ ed25519, secp256k1, keccak256, randomBytes });
@@ -430,6 +431,45 @@ async function heightAtOrBefore(timestamp, { tip, headerTimestamp }) {
   return low;
 }
 
+// THE READERS A CALLER SHOULD NOT HAVE TO BUILD. A page already holds the node URLs it probed; these wrap
+// `get_info` and `get_block_header_by_height` over one of them. The SDK still owns the binary search; only the
+// transport is borrowed.
+async function moneroReadersFromNodes({ nodes = [], network = null, fetchImpl = globalThis.fetch } = {}) {
+  const urls = (Array.isArray(nodes) ? nodes : [])
+    .map((entry) => typeof entry === "string" ? entry : entry && entry.url).filter(Boolean);
+  if (!urls.length) return null;
+  const answers = await Promise.all(urls.map(async (url) => {
+    try { return { ...(await probeMoneroNode({ url, fetchImpl })), url }; }
+    catch { return { ok: false, why: "unreachable", url }; }
+  }));
+  const node = answers.find((answer) => answer.ok === true && (!network || answer.network === network));
+  if (!node) return null;
+  const call = async (method, params) => {
+    let response;
+    try {
+      response = await fetchImpl(node.url + "/json_rpc", {
+        method: "POST", headers: { "content-type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: method, method, params }),
+        signal: typeof AbortSignal !== "undefined" && AbortSignal.timeout ? AbortSignal.timeout(8000) : undefined,
+      });
+    } catch { throw new Error("monero-unreachable"); }
+    if (!response || response.ok !== true) throw new Error("monero-http");
+    let body = null;
+    try { body = await response.json(); } catch { throw new Error("monero-json"); }
+    if (!body || body.error || !body.result) throw new Error("monero-rpc");
+    return body.result;
+  };
+  return {
+    tip: async () => node.height,
+    headerTimestamp: async (height) => {
+      const result = await call("get_block_header_by_height", { height });
+      const ts = Number(result.block_header && result.block_header.timestamp);
+      if (!Number.isFinite(ts) || ts <= 0) throw new Error("monero-header");
+      return ts;
+    },
+  };
+}
+
 async function recoveredStartHeight(order, { evmBlockTime, moneroTip, moneroBlockTimestamp, cache }) {
   if (order.blockNumber === null || order.blockNumber === undefined) {
     return { startHeight: null, startHeightReason: "no-block-number" };
@@ -460,7 +500,8 @@ async function recoveredStartHeight(order, { evmBlockTime, moneroTip, moneroBloc
  */
 export async function findSwaps({ mnemonic, chainId, factory, address = null, evmLogs,
   fromBlock = 0, toBlock = "latest", gap = 5, maxIndex = 1000,
-  evmBlockTime = null, moneroTip = null, moneroBlockTimestamp = null } = {}) {
+  evmBlockTime = null, moneroTip = null, moneroBlockTimestamp = null,
+  xmrNodes = null, moneroNetwork = null, fetchImpl = globalThis.fetch } = {}) {
   if (typeof factory !== "string" || !ADDRESS_RE.test(factory)) throw bad("factory");
   const chain = numberField(chainId, "chainId");
   const max = numberField(maxIndex, "maxIndex") || 1000;
@@ -506,8 +547,14 @@ export async function findSwaps({ mnemonic, chainId, factory, address = null, ev
   // EACH FOUND ORDER CARRIES THE MONERO HEIGHT ITS WITHDRAWAL MAY START FROM. The rule lives here, not in a
   // page: a widget and the recovery page must not derive two different answers from one chain.
   const cache = new Map();
+  let tip = moneroTip;
+  let header = moneroBlockTimestamp;
+  if ((typeof tip !== "function" || typeof header !== "function") && Array.isArray(xmrNodes) && xmrNodes.length) {
+    const readers = await moneroReadersFromNodes({ nodes: xmrNodes, network: moneroNetwork, fetchImpl });
+    if (readers) { tip = tip || readers.tip; header = header || readers.headerTimestamp; }
+  }
   for (const order of found) {
-    Object.assign(order, await recoveredStartHeight(order, { evmBlockTime, moneroTip, moneroBlockTimestamp, cache }));
+    Object.assign(order, await recoveredStartHeight(order, { evmBlockTime, moneroTip: tip, moneroBlockTimestamp: header, cache }));
   }
   return { swaps: found, scanned };
 }

package/src/sweep-restore.mjs

@@ -62,6 +62,45 @@ const heightOf = async (driver, name) => {
   }
 };
 
+// THE BLOCK WINDOW AROUND THE LOCK. A full rescan of mainnet takes hours; the lock can only be in the blocks from
+// the order's start to just after its t1. The caller may pass the hashes, or a node URL and the SDK asks for them.
+export async function windowTxHashes({ nodeUrl, fromHeight, toHeight, fetchImpl = globalThis.fetch } = {}) {
+  let base = typeof nodeUrl === "string" ? nodeUrl.trim() : "";
+  while (base.endsWith("/")) base = base.slice(0, -1);
+  const from = Number(fromHeight);
+  const to = Number(toHeight);
+  if (!base) throw new SdkError("bad-input", { field: "window.nodeUrl" });
+  if (!Number.isSafeInteger(from) || from < 0) throw new SdkError("bad-input", { field: "window.fromHeight" });
+  if (!Number.isSafeInteger(to) || to < from) throw new SdkError("bad-input", { field: "window.toHeight" });
+  if (typeof fetchImpl !== "function") throw new SdkError("bad-input", { field: "fetchImpl" });
+  const hashes = [];
+  for (let height = from; height <= to; height += 1) {
+    let response;
+    try {
+      response = await fetchImpl(base + "/json_rpc", {
+        method: "POST", headers: { "content-type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: "block", method: "get_block", params: { height } }),
+        signal: typeof AbortSignal !== "undefined" && AbortSignal.timeout ? AbortSignal.timeout(8000) : undefined,
+      });
+    } catch { throw new SdkError("wallet-rejected", { surface: "window-blocks", height }); }
+    if (!response || response.ok !== true) throw new SdkError("wallet-rejected", { surface: "window-blocks", height, status: response ? response.status : null });
+    let body = null;
+    try { body = await response.json(); } catch { throw new SdkError("wallet-rejected", { surface: "window-blocks", height, why: "not-json" }); }
+    if (!body || body.error || !body.result) throw new SdkError("wallet-rejected", { surface: "window-blocks", height, why: "rpc" });
+    const result = body.result;
+    let list = Array.isArray(result.tx_hashes) ? result.tx_hashes : null;
+    if (!list && typeof result.json === "string") {
+      try {
+        const json = JSON.parse(result.json);
+        list = Array.isArray(json.tx_hashes) ? json.tx_hashes : null;
+      } catch { list = null; }
+    }
+    if (!list) throw new SdkError("wallet-rejected", { surface: "window-blocks", height, why: "no-tx-hashes" });
+    hashes.push(...list.map(String));
+  }
+  return hashes;
+}
+
 /**
  * Restore the wallet from a height and report what it holds.
  *
@@ -88,6 +127,71 @@ export async function restoreWallet(request = {}) {
   const scanHeight = Math.max(0, Math.floor(fromHeight) - scanBack);
   const driver = driverOf(wallet);
 
+  // THE WINDOW PATH: set the wallet at the node tip, scan the lock's blocks, and only fall back to a full scan
+  // when that window holds nothing. An empty window is "not found", not "no funds".
+  const requestWindow = request.window && typeof request.window === "object" ? request.window : null;
+  let windowReport = null;
+  let windowTotal = 0n;
+  let windowUnlocked = 0n;
+  if (requestWindow) {
+    const tipHeight = Number(requestWindow.tipHeight);
+    if (!Number.isSafeInteger(tipHeight) || tipHeight <= 0) throw new SdkError("bad-input", { field: "window.tipHeight" });
+    let hashes = Array.isArray(requestWindow.txHashes) ? requestWindow.txHashes.map(String) : null;
+    if (hashes === null) {
+      hashes = await windowTxHashes({
+        nodeUrl: requestWindow.nodeUrl, fromHeight, toHeight: requestWindow.toHeight, fetchImpl: request.fetchImpl,
+      });
+    }
+    windowReport = { used: false, skipped: null, fromHeight, toHeight: Number(requestWindow.toHeight),
+      blocks: Math.max(0, Number(requestWindow.toHeight) - fromHeight + 1), txs: hashes.length };
+    if (hashes.length && typeof driver.scanTxs === "function") {
+      await step("setRestoreHeight", () => driver.setRestoreHeight(tipHeight));
+      await step("scanTxs", () => driver.scanTxs(hashes));
+      try { await wallet.sync(); } catch { /* the balance below decides */ }
+      windowTotal = asAmount(await step("getBalance", () => driver.getBalance()), "balance");
+      windowUnlocked = asAmount(await step("unlockedBalance", () => wallet.unlockedBalance()), "unlockedBalance");
+      windowReport.used = true;
+      // THE KEY IMAGES OF THE WALLET, CHECKED AT THE NODE. `scanTxs` finds an output; whether the chain already
+      // spent it is a separate fact, and the caller must not sign on a guess.
+      if (requestWindow.nodeUrl && typeof driver.getKeyImages === "function") {
+        try {
+          const exported = await driver.getKeyImages();
+          const images = Array.isArray(exported) ? exported
+            : (exported && typeof exported.getKeyImages === "function" ? exported.getKeyImages() : []);
+          const hexes = images.map((image) => typeof image === "string" ? image
+            : (image && typeof image.getHex === "function" ? image.getHex() : image && image.hex)).filter(Boolean);
+          if (hexes.length) {
+            let base = String(requestWindow.nodeUrl);
+            while (base.endsWith("/")) base = base.slice(0, -1);
+            const response = await (request.fetchImpl || globalThis.fetch)(base + "/is_key_image_spent", {
+              method: "POST", headers: { "content-type": "application/json" },
+              body: JSON.stringify({ key_images: hexes }),
+              signal: typeof AbortSignal !== "undefined" && AbortSignal.timeout ? AbortSignal.timeout(8000) : undefined,
+            });
+            const body = response && response.ok === true ? await response.json() : null;
+            if (body && Array.isArray(body.spent_status)) {
+              windowReport.spent = body.spent_status.filter((value) => value === true || value === 1).length;
+              windowReport.keyImages = hexes.length;
+            } else windowReport.spent = null;
+          } else { windowReport.spent = null; windowReport.spentWhy = "no-key-images"; }
+        } catch { windowReport.spent = null; windowReport.spentWhy = "check-failed"; }
+      } else if (requestWindow.nodeUrl) {
+        windowReport.spent = null;
+        windowReport.spentWhy = "no-key-images";
+      }
+      // A WINDOW WITH COINS IS THE ANSWER. A window with none falls through to the full scan unless the caller
+      // explicitly turned the fallback off.
+      if (windowTotal > 0n || windowUnlocked > 0n || requestWindow.fallback === false) {
+        return {
+          total: windowTotal.toString(), unlocked: windowUnlocked.toString(), scanHeight, walletHeight: await heightOf(driver, "getHeight"),
+          nodeHeight: await heightOf(driver, "getDaemonHeight"), passes: 1, lockedPass: false, window: windowReport,
+        };
+      }
+    } else if (hashes.length) {
+      windowReport.skipped = "no-scan-txs";
+    }
+  }
+
   await step("setRestoreHeight", () => driver.setRestoreHeight(scanHeight));
   // A RESCAN IS REQUIRED, NOT OPTIONAL: without it the height only applies to a wallet that has not scanned yet,
   // and a wallet restored from a key has. A driver that cannot rescan is the caller's mistake, named here.
@@ -129,5 +233,6 @@ export async function restoreWallet(request = {}) {
     // Whether the second pass RAN - not whether it helped. A reader must be able to tell "nothing was locked" from
     // "it was locked and stayed locked".
     lockedPass,
+    window: windowReport,
   };
 }

package/src/version.mjs

@@ -6,4 +6,4 @@
 // tools/sync-version.mjs. Do not edit it by hand - set the version in package.json and run `npm run sync:version`.
 // The `version` check in tools/check.mjs refuses a mismatch, and refuses a runtime read of package.json here.
 
-export const SDK_VERSION = "0.48.1";
+export const SDK_VERSION = "0.50.0";