@ninsei-labs/sdk 0.39.1 → 0.39.2

package/CHANGELOG.md

@@ -1,3 +1,103 @@
+## Unreleased — 2026-10-08
+
+EVERY ORDER'S ESCROW IS A CLONE, AND THE CLIENT NOW CHECKS THE IMPLEMENTATION IT WILL EXECUTE (issue #114).
+Since the contract change an order's escrow is an EIP-1167 minimal proxy of ONE shared implementation, and the
+factory carries the pair (`implementation()`, `implementationCodeHash()`). The factory checks that pair before every
+creation; the client now checks the SAME pair on chain, armed by the interface's own policy - `knownImplementationCodes`,
+an array of known implementation build hashes, sitting next to `knownFactoryCodes`. The verdict reads the pair off the
+factory, reads the CODE at the implementation's address and applies the same check the factory does - and re-hashes the
+live code, so it does not trust the factory's own answer alone. A `delegatecall` to an address without code SUCCEEDS,
+so a clone without an implementation would take the ETH and its `markReady`/`claim`/`refund` would appear to go through
+while doing nothing: that case is refused by name (`implementation-has-no-code`).
+
+- **`knownImplementationCodes`** (`src/quotes.mjs`, `src/index.mjs`, `index.d.ts`) - the interface's
+  escrow-implementation policy, next to `knownFactoryCodes`. An empty/absent list means "no policy": the pair is not
+  read and behaviour is as before (needed while a network still runs a factory of the OLDER build, which has no such
+  getters and answers a revert - the deployed one does). A non-empty list refuses an implementation whose recorded
+  hash is not a known build with `quote-factory-code-unknown`; a pair that cannot be read at all is refused with
+  `quote-factory-unchecked`. Proven by four cases beside the existing factory-code ones: a known build is accepted,
+  and a foreign one, a code whose hash does not match the recorded one, and an implementation without code are each
+  refused by a named reason.
+- **`verifyFactoryImplementationOnChain`** (`engine/evm/factory.js`) - one place that reads the pair and applies
+  `verifyFactoryImplementation`, with the chain injected (`read` = `eth_call`, `code` = `eth_getCode`). The module
+  stays pure (no imports, no network) and is the same helper the demo's node and watchtower call with their own reads.
+- **The package source is re-synced from the source-of-truth tree**: `src/**`, `engine/**` and `index.d.ts` are
+  byte-for-byte the demo repository's `sdk/`. The demo's interface config pins the known implementation hash - a
+  protocol constant, because the implementation has no immutable fields, so its runtime code (and its hash) is the
+  same on every network.
+- **Claim and order-creation gas limits are the MEASURED ones** (`engine/evm/claimGas.js`, `engine/evm/funding.js`).
+  `CLAIM_GAS_LIMIT` is raised from 120 000 to 200 000: an honest `claim` whose fee is the FIRST credit to the
+  recipient's cashier costs 120 721 gas on a live chain (124 072 in `forge --gas-report`), so the former limit cut a
+  valid claim. `GAS_CREATE_ORDER_AND_FUND` is lowered from 1 500 000 to 700 000, because an order's escrow is now an
+  EIP-1167 clone - the measured full call is 315 530 gas (1 190 683 for the former full contract). The dead
+  `GAS_CREATE_ORDER` constant (there is no separate creation path) is removed. The node's own claim in the
+  source-of-truth tree signs with the SAME shared limit instead of its own literal.
+- Checks: `node tools/check.mjs` - all green.
+
+## 0.39.2 — 2026-10-08
+
+`fakechain` IS A KNOWN MONERO NETWORK. The withdrawal page takes the Monero network FROM THE NODE, and monerod in
+regtest mode reports its network as `fakechain` - the official name of that mode. On the CI contour (a regtest node)
+the core therefore refused its OWN recovery file (`bad-input`, field `xmrNetwork`) and the withdrawal never started.
+The name is now accepted by every check of the network value, and everything else is still refused by name.
+
+- **`fakechain` joins the accepted networks** (`src/config.mjs`, `index.d.ts`): beside the engine registry's own
+  names and the standard mainnet/stagenet/testnet it is a KNOWN name of the regtest mode. Anything else is still a
+  `bad-input` refusal that names the known list - the value is checked, not "any word accepted".
+- **The recovery-file reader accepts it as well** (`engine/recovery/recoveryFile.js`): a file whose wallet network is
+  `fakechain` reads back; an unknown name is still rejected. Proven by a writer -> reader round trip, with the
+  unknown-name case beside it.
+- **The engine's network registry declares it** (`engine/core/config.js`): the Monero wallet adapter builds its list
+  of known networks from `XMR_NETWORKS`, so `/adapters` knows the name too.
+- **The package source is re-synced from the source-of-truth tree**: `src/**`, `engine/**` and `index.d.ts` are now
+  byte-for-byte the demo repository's `sdk/`. Besides the change above this also carries two changes that were
+  already in that tree: the escrow-implementation address/codehash read and verdict (`engine/evm/factory.js`,
+  `verifyFactoryImplementation`) and the smallest-trade rule that reads the maker's SENT minimum rather than the
+  effective set's first level (`src/levelsWalkSpec.mjs`, the `minAtomic` argument).
+- **A withdrawal no longer loses its refusal code on a chain the wallet library cannot scan** (`src/sweep.mjs`):
+  the FREE REMAINDER is read and judged BEFORE any input selection, and a failed `sync()` no longer pre-empts that
+  verdict. On the CI contour (a regtest node) monero-ts `sync()` throws a bare `failed to get hashes`; that error
+  used to escape ahead of the funds check, so an EMPTY wallet was refused with `code: null` + raw text instead of
+  the named `insufficient-funds` - and the page had no phrase to translate, because the core had named nothing.
+- **Every refusal keeps a code from the package's dictionary** (`src/sweep.mjs`, `walletStep`): a wallet step that
+  fails with anything other than an `SdkError` is re-thrown as one, on `wallet-rejected`, with the library's own
+  message kept as `params.why`. `code: null` + raw text is not a refusal an interface can show or a check assert.
+- Proven by a unit run WITHOUT a browser or a contour (the source-of-truth tree's `tools/check-sweep-empty-wallet.mjs`,
+  part of the fast gates): a zero remainder refuses with `insufficient-funds` and human words while input selection
+  is never touched; a non-zero remainder reaches signing; a low-level library failure comes out WITH a code. Two
+  breaking runs redden - cutting the remainder check (the refusal stops being named) and cutting the wrapper (the
+  run then reproduces the exact CI symptom: `code: null` + `failed to get hashes`).
+- Checks: `node tools/check.mjs` - all green.
+
+ HEAD
+## Unreleased — 2026-10-07
+
+PRERELEASES GET THEIR OWN npm TAGS, AND `latest` STOPS MOVING BY ACCIDENT. The release workflow published whatever
+version `package.json` carried under whatever tag npm chose on its own; now the tag is DERIVED from the version and
+handed to `npm publish` by name. This entry rides the next version - nothing in `src/`, `engine/` or `index.d.ts`
+changes here.
+
+- **The tag comes from the version** (`tools/npm-tag.mjs`): `X.Y.Z` -> `latest`, `X.Y.Z-develop.N` -> `develop`,
+  `X.Y.Z-preview.N` -> `preview`, read from the FIRST identifier of the prerelease part. Anything else is a named
+  refusal, not a guess: a version that is not `X.Y.Z[...]`, a prerelease channel that is not declared, a tag that
+  reads as a version.
+- **A prerelease can never move `latest`.** The publish step works the tag out before it sends anything, and the
+  derivation refuses, naming the case, when a prerelease would take `latest` - even under a manual override. The
+  reverse is refused too: a plain version does not publish into a channel tag with no decision behind it.
+- **The tag is passed explicitly.** "Publishing a package sets the `latest` tag to the published version unless
+  the `--tag` option is used" (https://docs.npmjs.com/cli/v11/commands/npm-dist-tag), and the `tag` config defaults
+  to `latest` (https://docs.npmjs.com/cli/v11/using-npm/config#tag) - so the step now ends in
+  `npm publish --access public --provenance --tag <tag>` and never leans on that default.
+- **A manual run may override the tag** with the new `tag` input; the step echoes the override and the tag the
+  derivation would have produced into the log before the publish, so the decision is readable, not silent.
+- **The cycle is written down** (README, "Releases and prereleases"): a build for ourselves is a prerelease under
+  `develop`/`preview`, the demo pins the EXACT version, and a release is a separate decision - a plain version, the
+  only shape that moves `latest`.
+- **Proven locally:** `node tools/npm-tag.test.mjs` walks the table - plain, both channels, build metadata, an
+  undeclared channel, garbage, every override - 28 cases, all green. A breaking run that cuts the guard reddens 5
+  of those 28, exactly the tooth's own cases, and `tools/npm-tag.mjs` was restored byte for byte. `node
+  tools/check.mjs` stays green, and CI gained the same case table as its own named step.
+
 ## 0.39.1 — 2026-10-07
 
 THE FIRST RELEASE CUT BY THE TAG-TRIGGERED WORKFLOW. The package's contents did not change: this entry and the

package/README.md

@@ -185,3 +185,24 @@ trigger where those exist; on another VM they simply do not appear, rather than
    touch them: `atomic/order-worker.js`, the Monero bundles.
 6. **Strict CSP.** The package is designed for a policy without `eval` and inline.
 7. **Zero dependencies.**
+
+## Releases and prereleases
+
+Every published version rides on an npm dist-tag, and the tag is **derived from the version** - never left to
+npm's default:
+
+| Version | npm dist-tag | What it is |
+|---|---|---|
+| `X.Y.Z` | `latest` | a release - a separate decision, and the only thing that moves `latest` |
+| `X.Y.Z-develop.N` | `develop` | a build for ourselves |
+| `X.Y.Z-preview.N` | `preview` | a build to show |
+
+The loop this serves: build a version for yourself (`0.40.0-develop.1`), publish it under `develop`, and have the
+demo pin the **exact** version (`"@ninsei-labs/sdk": "0.40.0-develop.1"`) rather than a tag. `latest` does not
+move, so `npm install @ninsei-labs/sdk` keeps serving the last real release. Shipping a release is then its own
+decision: a plain `X.Y.Z`, the only shape that publishes under `latest`.
+
+The tag is passed to `npm publish` explicitly (`--tag <tag>`), and `tools/npm-tag.mjs` refuses the two ways this
+can go wrong **by name** - a prerelease that would take `latest`, and a plain version that would slide into a
+channel someone else owns. A manual run of the release workflow may override the tag with an input; when it does,
+the log says so. The derivation and its refusals are covered by `node tools/npm-tag.test.mjs`.

package/engine/core/config.js

@@ -365,7 +365,16 @@ export const CHAINS = [
     // селектор predict 0x3d81fc01) и касса 0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512 (573 байта, но ДРУГОЙ
     // сборки - keccak 0x5c32bb9c…): её код не совпадал с канонической кассой, и эскроу отверг бы такой ордер
     // по #122 - поэтому касса развёрнута заново тем же заходом.
-    escrow: { address: "0xcbEAF3BDe82155F56486Fb5a1072cb8baAf547cc", mode: "live", cashier: "0x1429859428C0aBc9C2C47C8Ee9FBaf82cFA0F20f" },
+    // ХЕШ КОДА РЕАЛИЗАЦИИ ЭСКРОУ (#114): то, что исполняет клон каждого ордера и что интерфейс обязан
+    // сверить сам, а не только довериться фабрике. Значение - keccak256 runtime-кода NinseiEscrow, взято
+    // из СВОЕЙ сборки: forge inspect NinseiEscrow deployedBytecode --root mvp/contracts и keccak (совпало
+    // с keccak256(type(NinseiEscrow).runtimeCode), которое записывает фабрика, и с артефактом out/).
+    // У реализации НЕТ immutables, поэтому это КОНСТАНТА ПРОТОКОЛА - один и тот же хеш в любой сети со
+    // сборкой #114. Лежит при сети, а не одним общим числом, потому что политика может отсутствовать: сеть
+    // со СТАРОЙ фабрикой (без implementation()) обязана остаться БЕЗ политики, иначе чтение пары откажет и
+    // живые котировки этой сети встанут. Так и есть у arbitrum-sepolia: развёрнутая там фабрика сборки #114
+    // не знает (оба геттера revert-ят), поэтому у неё поля НЕТ; включается тем же заходом, что и новый деплой.
+    escrow: { address: "0xcbEAF3BDe82155F56486Fb5a1072cb8baAf547cc", mode: "live", cashier: "0x1429859428C0aBc9C2C47C8Ee9FBaf82cFA0F20f", implementationCodeHash: "0xfd1ef12c1d96d3ee7060bd5901e06108723783403fad00c9630dcdeb6193674b" },
     // Токенов в песочнице нет: расплата идёт нейтивом. Пустой список - это факт о песочнице, а не забывчивость.
     tokens: [],
     // Uniswap в песочнице не развёрнут и не нужен: тут своя цепочка для сквозных прогонов, а DEX-нога
@@ -692,6 +701,18 @@ export function knownFactoryCodesFor(chainOrId) {
   return list.map((h) => String(h).toLowerCase());
 }
 
+// СПИСОК ИЗВЕСТНЫХ СБОРОК РЕАЛИЗАЦИИ ЭСКРОУ - ПОЛИТИКА ИНТЕРФЕЙСА (#114), при самой сети, где живёт адрес
+// фабрики (escrow.address). Хеш её кода - КОНСТАНТА ПРОТОКОЛА (у реализации нет immutables), но политика
+// может быть не задана: у сети без поля implementationCodeHash её НЕТ (старая фабрика пары не отдаёт).
+// Пусто = политики нет; непусто = интерфейс торгует только через фабрики, ведущие на эту сборку.
+export function knownImplementationCodesFor(chainOrId) {
+  const id = typeof chainOrId === "string" ? chainOrId : chainOrId && chainOrId.id;
+  const chain = CHAINS.find((c) => c.id === id) || chainById(id);
+  const pinned = chain && chain.escrow ? chain.escrow.implementationCodeHash : null;
+  if (typeof pinned !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(pinned)) return null;
+  return [pinned.toLowerCase()];
+}
+
 export function chainById(id) {
   return CHAINS.find((c) => c.id === id) || CHAINS.find((c) => c.id === DEFAULT_CHAIN) || CHAINS[0];
 }
@@ -795,7 +816,13 @@ export const API = {
 // но это только вредило: адреса в мок-режиме выглядели как mainnet (префикс 4), а живая нода -
 // stagenet (префикс 5), и в одном UI соседствовали две цепи. Смешение цепей в свопе означает
 // потерянные деньги (см. monero/address.js), поэтому теперь и мок, и живой режим - stagenet.
-export const XMR_NETWORKS = { app: "stagenet", mock: "stagenet" };
+//
+// ПЛЮС ЗНАКОМОЕ ИМЯ REGTEST. Ключи app/mock отвечают на вопрос «в какой сети кошелёк этого источника».
+// Третья запись источника не имеет: fakechain - официальное имя regtest-режима monerod, которым нода
+// называет себя на контуре CI. Она нужна, чтобы имя сети ПРИНИМАЛОСЬ: ядро сверяет xmrNetwork со списком
+// сетей движка (sdk/src/config.mjs, STANDARD_XMR_NETWORKS), а адаптер кошелька ядра берёт список сетей
+// из ЭТОГО реестра (sdk/src/adapters/monero-wallet.mjs). Кошелёк демки при этом остаётся stagenet.
+export const XMR_NETWORKS = { app: "stagenet", mock: "stagenet", fakechain: "fakechain" };
 
 // Страница sweep: отдельный домен со своей (более строгой) политикой и WASM-кошельком.
 // Вывод XMR делает сам пользователь там, по своему recovery-файлу - демка за него не подписывает

package/engine/evm/claimGas.js

@@ -22,10 +22,11 @@
 // стоимость claim плюс ЯВНЫЙ ЗАПАС на рост базовой цены между выдачей билета и забором. Второго расчёта
 // размера подарка нет ни у ноды, ни у прогонов: они зовут claimGasGiftWei отсюда.
 
-// ПРЕДЕЛ ГАЗА CLAIM - ОДНО ЧИСЛО НА ОБЕИХ СТОРОНАХ. Это тот же предел, с которым нода подписывает свой
-// claim в rfq/payout.mjs, и тот же, что отправляет страница/SDK (sdk/src/swap-flow.mjs). Число не
-// выдумано: живой прогон меряет фактический gasUsed забора сверху (tools/live-gas-run.mjs).
-export const CLAIM_GAS_LIMIT = 120_000n;
+// ПРЕДЕЛ ГАЗА CLAIM - ОДНО ЧИСЛО НА ОБЕИХ СТОРОНАХ: его берут и страница/SDK (sdk/src/swap-flow.mjs), и
+// нода (rfq/payout.mjs). ИЗМЕРЕНО: честный claim, когда получателю комиссии ещё НЕ начислено (первая запись
+// в кассе = SSTORE нуля), стоит 120 721 газа на живой цепи (124 072 в gas-report канонических контрактов) -
+// больше прежних 120 000, чем законный забор и резался. Лимит задан с запасом: 200 000.
+export const CLAIM_GAS_LIMIT = 200_000n;
 
 // ПОЛ ЧАЕВЫХ - ПОЛИТИКА СЕТИ, А НЕ КОНСТАНТА В КОДЕ ОТПРАВКИ. Раньше session.js ставил минимум 1 gwei
 // ВСЕГДА. На сети с дешёвым газом (Arbitrum One: baseFee ~0.02 gwei) это раздувало maxFeePerGas примерно

package/engine/evm/factory.js

@@ -147,3 +147,109 @@ export function decodeAddress(returnedHex) {
   if (hex.length < 64) throw new Error("короткий ответ: " + returnedHex);
   return "0x" + hex.slice(24, 64);
 }
+
+
+// ============================================================================================
+// РЕАЛИЗАЦИЯ ЭСКРОУ: ЕЁ АДРЕС И ХЕШ ЕЁ КОДА (issue #114, поправка 2).
+// С #114 эскроу каждого ордера - КЛОН EIP-1167 одной общей реализации, а адрес реализации и хеш её кода
+// лежат у фабрики (implementation() / implementationCodeHash()). ФАБРИКА при создании ордера проверяет эту
+// пару; КЛИЕНТ обязан проверить ТУ ЖЕ пару, иначе клон исполнит чужой код, а денежные пути "пройдут" впустую
+// (delegatecall на адрес без кода УСПЕШЕН). Здесь - только чтение полей и вердикт; вызовы к цепи делает
+// носитель (session.js: readContract/readCode), поэтому функция чистая и проверяется без сети.
+// ============================================================================================
+
+// Селекторы посчитаны инструментом, не вручную:
+//   cast sig "implementation()"         -> 0x5c60da1b
+//   cast sig "implementationCodeHash()" -> 0xbc0a3981
+export const FACTORY_READS = {
+  implementation: "0x5c60da1b",
+  implementationCodeHash: "0xbc0a3981",
+};
+
+// Чтение поля фабрики без аргументов: calldata равен селектору.
+export function encodeFactoryRead(name) {
+  const sel = FACTORY_READS[name];
+  if (typeof sel !== "string" || !/^0x[0-9a-f]{8}$/.test(sel)) throw new Error("нет такого чтения фабрики: " + name);
+  return sel;
+}
+
+// implementation() - один адрес в 32-байтовом слове.
+export function decodeImplementation(returnedHex) {
+  return decodeAddress(returnedHex);
+}
+
+// implementationCodeHash() - одно слово bytes32.
+export function decodeImplementationCodeHash(returnedHex) {
+  const hex = String(returnedHex || "").replace(/^0x/, "");
+  if (hex.length < 64) throw new Error("короткий ответ implementationCodeHash(): " + returnedHex);
+  return "0x" + hex.slice(0, 64).toLowerCase();
+}
+
+// ВЕРДИКТ ПО РЕАЛИЗАЦИИ - те же три условия, что проверяет фабрика (и что закрывает поправки #114):
+//   1) адрес реализации назван и её КОД на цепи непуст: delegatecall на адрес без кода успешен, поэтому
+//      клон без реализации принял бы ETH, а markReady/claim/refund "прошли" бы, ничего не сделав;
+//   2) хеш кода реализации равен recorded-хешу фабрики (сравнение делает сама фабрика через codehash);
+//   3) recorded-хеш входит в политику интерфейса (список известных сборок) - если она задана.
+// Если передан hashCode (keccak256 байтов кода), сверяется и живой код: тогда вердикт не доверяет одному
+// лишь ответу фабрики, а пересчитывает хеш из eth_getCode.
+export function verifyFactoryImplementation({ implementation, implementationCodeHash, code, hashCode, policy } = {}) {
+  if (!implementation || !/^0x[0-9a-fA-F]{40}$/.test(String(implementation))) {
+    return { ok: false, why: "implementation-missing" };
+  }
+  if (!implementationCodeHash || !/^0x[0-9a-fA-F]{64}$/.test(String(implementationCodeHash))) {
+    return { ok: false, why: "code-hash-missing" };
+  }
+  if (code === undefined || code === null || code === "0x" || code === "0x0") {
+    return { ok: false, why: "implementation-has-no-code" };
+  }
+  const pinned = String(implementationCodeHash).toLowerCase();
+  if (Array.isArray(policy) && policy.length) {
+    if (!policy.map((h) => String(h).toLowerCase()).includes(pinned)) {
+      return { ok: false, why: "implementation-code-unknown", codeHash: pinned };
+    }
+  }
+  if (typeof hashCode === "function") {
+    const live = String(hashCode(code)).toLowerCase();
+    if (live !== pinned) return { ok: false, why: "implementation-code-mismatch", got: live, want: pinned };
+  }
+  return { ok: true, codeHash: pinned };
+}
+
+// ЧТЕНИЕ ПАРЫ У ФАБРИКИ + ВЕРДИКТ - ОДНО МЕСТО НА ВСЕ НОСИТЕЛИ (SDK, узел, сторож). Читает пару полей
+// фабрики (implementation() / implementationCodeHash()) и КОД по адресу реализации, затем применяет тот же
+// вердикт, что и фабрика при создании ордера (verifyFactoryImplementation выше). Цепь инжектится: read -
+// это eth_call ({to,data}) -> hex, code - это eth_getCode (address) -> hex. Модуль остаётся чистым: ни
+// одного импорта, ни одного сетевого вызова, поэтому проверяется без сети. Носители подставляют СВОИ
+// чтения (SDK - evmCall/evmCode кошелька страницы, узел и сторож - свой RPC). hashCode, если передан,
+// пересчитывает живой код: тогда вердикт не доверяет одному лишь ответу фабрики.
+export async function verifyFactoryImplementationOnChain({ factory, read, code, policy = null, hashCode = null } = {}) {
+  if (!factory || !/^0x[0-9a-fA-F]{40}$/.test(String(factory))) {
+    return { ok: false, why: "factory-missing" };
+  }
+  if (typeof read !== "function") return { ok: false, why: "no-chain-read" };
+  if (typeof code !== "function") return { ok: false, why: "no-code-read" };
+  let implRaw, hashRaw;
+  try {
+    implRaw = await read({ to: factory, data: FACTORY_READS.implementation });
+    hashRaw = await read({ to: factory, data: FACTORY_READS.implementationCodeHash });
+  } catch {
+    // ЧТЕНИЕ ПАРЫ НЕ УДАЛОСЬ - ЭТО НАЗВАННЫЙ ОТКАЗ, А НЕ МОЛЧАНИЕ. Старая фабрика (без этих геттеров)
+    // отвечает revert'ом: пара не прочитана, вердикта нет, и носитель обязан отказать.
+    return { ok: false, why: "implementation-unreadable", factory: String(factory).toLowerCase() };
+  }
+  let implementation, implementationCodeHash;
+  try {
+    implementation = decodeImplementation(implRaw);
+    implementationCodeHash = decodeImplementationCodeHash(hashRaw);
+  } catch {
+    return { ok: false, why: "implementation-unreadable", factory: String(factory).toLowerCase() };
+  }
+  let liveCode;
+  try {
+    liveCode = await code(implementation);
+  } catch {
+    return { ok: false, why: "implementation-code-unreadable", implementation };
+  }
+  const verdict = verifyFactoryImplementation({ implementation, implementationCodeHash, code: liveCode, hashCode, policy });
+  return { ...verdict, implementation, implementationCodeHash };
+}

package/engine/evm/funding.js

@@ -104,17 +104,17 @@ export function toWei(human, decimals = 18) {
   return BigInt(intPart || "0") * 10n ** BigInt(decimals) + BigInt(frac || "0");
 }
 
-// ГАЗ ВЫСТАВЛЯЕМ САМИ И С ЗАПАСОМ - ЭТО НЕ ПЕРЕСТРАХОВКА, А ЛЕЧЕНИЕ КОНКРЕТНОЙ ОШИБКИ.
-// createOrder и lock уходят двумя транзакциями подряд. Кошелёк оценивает вторую в момент подписи, когда
-// эскроу ещё НЕ создан, поэтому считает по пустому адресу обычный перевод: 21000 + стоимость данных. На
-// живом контракте это дало лимит 24167 при реальной надобности 50294 - и lock упал по газу, хотя вызов
-// был полностью верный (та же сумма, тот же отправитель, тот же адрес). Оценку кошелька здесь доверять
-// нельзя, поэтому лимиты задаём явно, с запасом от измеренных значений.
-const GAS_CREATE_ORDER = 1_200_000n;   // измерено 612567 - запас ~2x: создаётся целый контракт
-// Создание И взнос в одной транзакции: создание контракта плюс запись взноса, запас намеренно большой -
-// недобор лимита стоит человеку подписи, а лишний газ в лимите на Arbitrum почти ничего не стоит.
-const GAS_CREATE_ORDER_AND_FUND = 1_500_000n;
-// GAS_LOCK УБРАН вместе с вызовом lock(bytes): взнос идёт в той же транзакции, что и создание ордера.
+// ГАЗ ВЫСТАВЛЯЕМ САМИ И С ЗАПАСОМ - ЭТО ЛЕЧЕНИЕ КОНКРЕТНОЙ ОШИБКИ, А НЕ ПЕРЕСТРАХОВКА.
+// createOrderAndFund уходит ОДНОЙ транзакцией, но кошелёк оценивает её по адресу, где эскроу ещё НЕ создан:
+// вместо создания клона и записи взноса он считает обычный перевод (21000 плюс данные). Оценку кошелька
+// здесь доверять нельзя, поэтому лимит задаём явно, с запасом от ИЗМЕРЕННОГО значения.
+// ИЗМЕРЕНО: полный createOrderAndFund после перехода на клоны EIP-1167 - 315 530 газа (у прежнего целого
+// контракта было 1 190 683); замер и методика - в описании PR в репозитории контрактов. Лимит примерно
+// вдвое выше измеренного: недобор стоит человеку подписи, а лишний газ в лимите почти ничего не стоит.
+const GAS_CREATE_ORDER_AND_FUND = 700_000n;
+// ОТДЕЛЬНОЙ КОНСТАНТЫ «СОЗДАНИЕ БЕЗ ВЗНОСА» НЕТ: целого контракта больше не создаётся - эскроу каждого
+// ордера есть клон EIP-1167 одной общей реализации, условия лежат в коде клона, а фабрика умеет только
+// createOrderAndFund. GAS_LOCK УБРАН вместе с вызовом lock(bytes): взнос идёт в той же транзакции.
 
 // СОБЫТИЕ OrderCreated: topic0 посчитан по фактической подписи (и сверяется проверкой watchtower),
 // topics = [topic0, escrow, locker, claimer]; в data - оба обязательства, обе точки, сумма, readyBy, t1, соль.

package/engine/recovery/recoveryFile.js

@@ -88,7 +88,10 @@ export const PAYLOAD_VERSION = 3;
 // источник, v3 - ПОЛОВИНЫ. Читать обязаны все три: у людей на руках есть файлы всех версий, и файл
 // восстановления - единственный способ забрать свои XMR. Выбрасывать старые версии нельзя.
 const SUPPORTED_PAYLOAD_VERSIONS = [1, 2, 3];
-const NETWORKS = ["mainnet", "stagenet", "testnet"];
+// СЕТИ, КОТОРЫЕ ЧИТАТЕЛЬ ФАЙЛА ЗНАЕТ. Три стандартные плюс fakechain - официальное имя regtest-режима
+// monerod: нода контура CI называет себя именно так, и файл, выпущенный на такой сети, обязан читаться.
+// Список поимённый: сеть вне него отвергается как неизвестная, и это остаётся в силе.
+const NETWORKS = ["mainnet", "stagenet", "testnet", "fakechain"];
 
 function b64(bytes) {
   return btoa(String.fromCharCode(...new Uint8Array(bytes)));

package/engine/sdk/bridge.js

@@ -37,7 +37,7 @@
 // загрузился (нет файла, старый кеш, сеть) - это НАЗВАННЫЙ отказ с причиной в консоли (sdkBundle ниже), а не
 // молчание и не подмена.
 
-import { chainById, DEFAULT_CHAIN, MONERO, allowedProvidersFor, knownFactoryCodesFor } from "../core/config.js";
+import { chainById, DEFAULT_CHAIN, MONERO, allowedProvidersFor, knownFactoryCodesFor, knownImplementationCodesFor } from "../core/config.js";
 import { storage as pageStorage } from "../core/store.js";
 import { token as authToken, signIn } from "../evm/auth.js";
 import * as evm from "../evm/index.js";
@@ -69,7 +69,7 @@ import { height as nodeHeightValue } from "../monero/node.js";
 
 // АДРЕС ЯДРА СТРОКОЙ - СОБРАННЫЙ БАНДЛ ПОД www/ (tools/build-sdk.mjs): страница получает ядро ОДНИМ
 // модулем, а не пачкой исходников sdk/. ?v=<хеш> проставляет tools/stamp-assets.mjs.
-const SDK_BUNDLE = "/assets/vendors/sdk/sdk-browser.js?v=bdb79a39";
+const SDK_BUNDLE = "/assets/vendors/sdk/sdk-browser.js?v=31e62de5";
 
 // ОДНА ЗАГРУЗКА НА СТРАНИЦУ. Отказ - это состояние, а не поломка: он назван в консоли, и вызывающий решает.
 let loading = null;
@@ -140,6 +140,11 @@ function optionsFor(chain) {
     // берёт из записи реестра провайдера, а её КОД сверяет с этим списком (extcodehash). Пусто = политики
     // нет; тогда фабрика всё равно обязана совпасть с подписанной котировкой.
     knownFactoryCodes: knownFactoryCodesFor(chain),
+    // ХЕШ ИЗВЕСТНОЙ СБОРКИ РЕАЛИЗАЦИИ ЭСКРОУ (#114) - РЯДОМ С knownFactoryCodes. Фабрика сверяет пару
+    // (implementation, implementationCodeHash) при создании ордера; ядро сверяет ТУ ЖЕ пару на цепи, и этот
+    // список - политика интерфейса: какие сборки реализации он принимает. Пусто = политики нет (сеть со
+    // старой фабрикой), и тогда пара всё равно читается, а код по адресу реализации обязан быть непустым.
+    knownImplementationCodes: knownImplementationCodesFor(chain),
   };
 }
 

package/index.d.ts

@@ -24,8 +24,12 @@ export interface NinseiOptions {
    * without a driver answers with the code `not-implemented`, rather than being assumed EVM by default.
    */
   settlement: { chain: string; vm?: string };
-  /** The Monero network. A value from `sdk.config.xmrNetworks`. */
-  xmrNetwork: "mainnet" | "stagenet" | "testnet";
+  /**
+   * The Monero network. A value from `sdk.config.xmrNetworks`. Besides mainnet/stagenet/testnet it names
+   * `fakechain` - the official network name monerod reports in regtest mode, which the withdrawal page picks up
+   * from the node on the CI contour.
+   */
+  xmrNetwork: "mainnet" | "stagenet" | "testnet" | "fakechain";
   /** Where to load workers and WASM from (order-worker, the Monero bundles). Default "/". */
   assetsBase?: string;
   /** Storage for unfinished swaps and sessions. Default - a localStorage adapter, if present. */
@@ -89,6 +93,18 @@ export interface NinseiOptions {
    * policy": the record's factory must still be named and agree with the quote.
    */
   knownFactoryCodes?: readonly string[];
+  /**
+   * THE INTERFACE'S ESCROW-IMPLEMENTATION POLICY (issue #114) - policy, not proof, next to knownFactoryCodes and
+   * allowedProviders. Since #114 every order's escrow is an EIP-1167 clone of ONE shared implementation, and the
+   * factory carries the pair (`implementation()`, `implementationCodeHash()`). The factory checks that pair at
+   * creation; the core checks the SAME pair on chain - it reads the pair off the factory, reads the code at the
+   * implementation's address, re-hashes it and matches it against this list of known build hashes (`keccak256` of
+   * the implementation's runtime code, a protocol constant: the implementation has no immutables). An implementation
+   * whose code is not a known build (or has no code at all) is refused with `quote-factory-code-unknown`; a pair
+   * that cannot be read at all (an older factory without those getters) is refused with `quote-factory-unchecked`.
+   * An empty/absent list means "no policy": the pair is still read and the implementation's code must be non-empty.
+   */
+  knownImplementationCodes?: readonly string[];
   /**
    * A PASS TO OUR SERVICE for the "server" step (recording the swap with us). Only a wallet can sign the sign-in
    * message, and the wallet's role in the SDK is an adapter: windows and message signatures remain the interface's,

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ninsei-labs/sdk",
-  "version": "0.39.1",
+  "version": "0.39.2",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "packageManager": "pnpm@9.15.9",
+  "packageManager": "pnpm@12.10.1",
   "description": "XMR <-> EVM swap engine: quotes, guards, order steps, recovery (no DOM, no user-facing strings)",
   "license": "MIT",
   "type": "module",
@@ -16,9 +16,9 @@
     "check:import": "node tools/check.mjs --only=import",
     "check:surface": "node tools/check.mjs --only=surface",
     "check:mirror": "node tools/check.mjs --only=mirror",
-    "check:language": "node tools/check.mjs --only=language",
     "check:pack": "node tools/check.mjs --only=pack",
-    "check:secrets": "node tools/check.mjs --only=secrets"
+    "check:secrets": "node tools/check.mjs --only=secrets",
+    "check:sweep": "node tools/sweep-refusal.test.mjs"
   },
   "types": "./index.d.ts",
   "exports": {

package/src/config.mjs

@@ -218,12 +218,15 @@ export function buildConfig(options) {
     if (!known.includes(id)) fail("bad-input", { field: "routing.prefer", unknown: id, known });
   }
 
-  // MONERO NETWORKS THE CORE KNOWS. The engine's registry declares only the one the demo is configured for
-  // (XMR_NETWORKS: stagenet). But the SDK contract (index.d.ts, xmrNetwork) names THREE standard names -
-  // mainnet/stagenet/testnet - and that is not about the demo: the withdrawal page takes the network FROM THE
-  // NODE, and on a production network its network is mainnet, not a typo. So three standard ones are added to
-  // the declared ones; anything else is still a refusal with the known list.
-  const STANDARD_XMR_NETWORKS = ["mainnet", "stagenet", "testnet"];
+  // MONERO NETWORKS THE CORE KNOWS. The engine's registry declares only the ones the demo is configured for
+  // (XMR_NETWORKS). But the SDK contract (index.d.ts, xmrNetwork) names the STANDARD ones - mainnet/stagenet/
+  // testnet - and that is not about the demo: the withdrawal page takes the network FROM THE NODE, and on a
+  // production network its network is mainnet, not a typo.
+  // REGTEST JOINS THEM BY ITS OFFICIAL NAME. monerod in regtest mode reports its network as `fakechain`, and the
+  // withdrawal page builds the facade from the network the node hands it - so the CI contour (a regtest node)
+  // hands out `fakechain`. Without that name the core refuses its OWN recovery file and the withdrawal never
+  // starts. This is a KNOWN name, not a wildcard: anything else is still a refusal with the known list below.
+  const STANDARD_XMR_NETWORKS = ["mainnet", "stagenet", "testnet", "fakechain"];
   const xmrNetworks = [...new Set([...Object.values(engine.config.XMR_NETWORKS || {}), ...STANDARD_XMR_NETWORKS])];
   if (!xmrNetworks.includes(options.xmrNetwork)) {
     fail("bad-input", { field: "xmrNetwork", known: xmrNetworks });

package/src/index.mjs

@@ -97,6 +97,14 @@ const normalizeOptions = (options) => {
   if (o.knownFactoryCodes !== undefined && o.knownFactoryCodes !== null && !Array.isArray(o.knownFactoryCodes)) {
     fail("bad-input", { field: "knownFactoryCodes" });
   }
+  // THE INTERFACE'S ESCROW-IMPLEMENTATION POLICY (issue #114): an array of code hashes of known implementations
+  // of the escrow - the code every order's clone delegatecalls. The client checks the pair (implementation,
+  // implementationCodeHash) the factory carries, exactly as the factory does at creation; this list pins WHICH
+  // builds the interface accepts. Same rule as knownFactoryCodes: a POLICY list, empty/absent means "no policy"
+  // (then the pair is still read and the code at the implementation's address must be non-empty).
+  if (o.knownImplementationCodes !== undefined && o.knownImplementationCodes !== null && !Array.isArray(o.knownImplementationCodes)) {
+    fail("bad-input", { field: "knownImplementationCodes" });
+  }
   // A PASS TO OUR SERVICE - A SEAM FROM OUTSIDE, like the wallet: only a wallet can sign the sign-in message
   // (www/js/evm/auth.js, signIn), and requiring it of the core would mean opening windows and signing messages
   // inside the SDK. The core receives a ready pass and presents it. A missing pass is NOT an option error: the
@@ -137,6 +145,7 @@ const normalizeOptions = (options) => {
     evmCode: o.evmCode || null,
     allowedProviders: o.allowedProviders === undefined ? null : o.allowedProviders,
     knownFactoryCodes: o.knownFactoryCodes === undefined ? null : o.knownFactoryCodes,
+    knownImplementationCodes: o.knownImplementationCodes === undefined ? null : o.knownImplementationCodes,
     serverAuth: o.serverAuth || null,
     watch: o.watch || null,
     createRecord: o.createRecord || null,
@@ -186,7 +195,7 @@ export function createNinsei(options) {
     return (provider) => set.has(String(provider).toLowerCase());
   })();
   const quotes = createQuotes({ config, http, now: o.now || (() => Date.now()), evmCall: o.evmCall || null,
-    evmCode: o.evmCode || null, providerAllowed, knownFactoryCodes: o.knownFactoryCodes });
+    evmCode: o.evmCode || null, providerAllowed, knownFactoryCodes: o.knownFactoryCodes, knownImplementationCodes: o.knownImplementationCodes });
   // 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.
   const actions = createActions({ call: o.evmCall });

package/src/levelsWalkSpec.mjs

@@ -141,11 +141,22 @@ function walkCostForXmr(levels, xmrAtomic) {
   return costWei;
 }
 
+// THE SMALLEST TRADE (rule 3). It is the size of the FIRST level the maker SENT, and the node's own
+// deductions (outstanding quotes, a balance cut) never change it: they take depth off the TOP, and a trade
+// that was allowed when the set arrived must stay allowed after the top was eaten. If the minimum were read
+// off the EFFECTIVE set, eating the first level whole would RAISE it to the next, larger level, and eating it
+// in part would LOWER it below what the maker sent - both wrong. Callers pass the sent minimum as minAtomic;
+// absent, the set's own first level is the minimum (the historical behaviour and what the vectors pin).
+function minOf(levels, minAtomic) {
+  if (minAtomic === null || minAtomic === undefined) return toBigInt(levels[0].amount);
+  return toBigInt(minAtomic);
+}
+
 // DIRECTION 1: "I give/take ASSET - how much XMR".
 //   buy:  assetWei - the asset the taker PAYS; the walk budget = assetWei - fee;
 //   sell: assetWei - the asset the taker RECEIVES; the walk budget = assetWei + fee (the set must yield that
 //         much so that AFTER the fee is taken out exactly assetWei is left in hand).
-export function xmrForAsset({ levels, role, feeWei = 0n, assetWei, orientation = "ask" }) {
+export function xmrForAsset({ levels, role, feeWei = 0n, assetWei, orientation = "ask", minAtomic = null }) {
   const verdict = checkLevels(levels, orientation);
   if (!verdict.ok) return { ok: false, reason: verdict.reason, role, index: verdict.index };
   if (!verdict.enabled) return { ok: false, reason: "side-off", role };
@@ -157,7 +168,12 @@ export function xmrForAsset({ levels, role, feeWei = 0n, assetWei, orientation =
   if (budget <= 0n) return { ok: false, reason: "levels-fee-beyond-budget", role };
   const { fullCostWei } = sideSummary(levels);
   if (budget > fullCostWei) return { ok: false, reason: "levels-exceed-side", role };
-  const minCost = levelCostWei(toBigInt(levels[0].amount), toBigInt(levels[0].price));
+  // THE SMALLEST TRADE, from the set AS THE MAKER SENT IT (rule 3): callers pass it in minAtomic and the
+  // node's deductions never change it. Absent, the set's own first level is used, as it always was.
+  const min = minOf(levels, minAtomic);
+  // Its cost ON THE EFFECTIVE SET: after deductions the smallest trade may reach into a later level, so the
+  // cost is walked, not read off one price.
+  const minCost = walkCostForXmr(levels, min);
   if (budget < minCost) return { ok: false, reason: "levels-below-minimum", role };
   const xmrAtomic = walkXmrForBudget(levels, budget);
   return { ok: true, role, xmrAtomic, assetWei: asset };
@@ -166,7 +182,7 @@ export function xmrForAsset({ levels, role, feeWei = 0n, assetWei, orientation =
 // DIRECTION 2: "I give/want XMR - how much ASSET".
 //   buy:  xmrAtomic - how much XMR the taker WANTS; the asset to pay = the walk + fee;
 //   sell: xmrAtomic - how much XMR the taker GIVES;  the asset to receive = the walk - fee.
-export function assetForXmr({ levels, role, feeWei = 0n, xmrAtomic, orientation = "ask" }) {
+export function assetForXmr({ levels, role, feeWei = 0n, xmrAtomic, orientation = "ask", minAtomic = null }) {
   const verdict = checkLevels(levels, orientation);
   if (!verdict.ok) return { ok: false, reason: verdict.reason, role, index: verdict.index };
   if (!verdict.enabled) return { ok: false, reason: "side-off", role };
@@ -175,7 +191,8 @@ export function assetForXmr({ levels, role, feeWei = 0n, xmrAtomic, orientation
   const fee = toBigInt(feeWei === undefined || feeWei === null ? 0n : feeWei);
   if (want === null || fee === null || fee < 0n) return { ok: false, reason: "levels-not-integer", role };
   if (want > verdict.totalAtomic) return { ok: false, reason: "levels-exceed-side", role };
-  if (want < verdict.minAtomic) return { ok: false, reason: "levels-below-minimum", role };
+  // THE SMALLEST TRADE AS THE MAKER SENT IT, never the effective set's first level (rule 3): see minOf.
+  if (want < minOf(levels, minAtomic)) return { ok: false, reason: "levels-below-minimum", role };
   const walkWei = walkCostForXmr(levels, want);
   const assetWei = role === "buy" ? walkWei + fee : walkWei - fee;
   if (assetWei <= 0n) return { ok: false, reason: "levels-fee-beyond-budget", role };

package/src/quotes.mjs

@@ -208,13 +208,19 @@ 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 }) {
+export function createQuotes({ config, http, now = () => Date.now(), evmCall = null, evmCode = null, providerAllowed = null, knownFactoryCodes = null, knownImplementationCodes = 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.
   const factoryPolicy = Array.isArray(knownFactoryCodes) && knownFactoryCodes.length
     ? knownFactoryCodes.map((h) => String(h).toLowerCase()).filter(Boolean)
     : null;
+  // THE INTERFACE'S ESCROW-IMPLEMENTATION POLICY (#114): the code hashes of the escrow IMPLEMENTATION the
+  // factory must lead to - the code every order's clone delegatecalls. Same rule as the factory policy: an
+  // EMPTY list is "no policy" (then the pair is still read and the implementation's code must be non-empty).
+  const implementationPolicy = Array.isArray(knownImplementationCodes) && knownImplementationCodes.length
+    ? knownImplementationCodes.map((h) => String(h).toLowerCase()).filter(Boolean)
+    : null;
   const listeners = new Set();
   let timer = null;
   let size = 1;              // the request size in units of the pair's ASSET; we start from one, as the engine does
@@ -428,6 +434,30 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
           fail("quote-factory-code-unknown", { step: "factory", factory: declaredFactory, codeHash });
         }
       }
+      // THE IMPLEMENTATION THE CLONES WILL EXECUTE (#114). A pinned factory CODE is not enough on its own: the
+      // implementation ADDRESS lives in the factory's STORAGE, so the client re-reads the pair the factory itself
+      // checks (implementation() / implementationCodeHash()) and the CODE at that address, then applies the same
+      // verdict (verifyFactoryImplementationOnChain). A delegatecall to an address WITHOUT code SUCCEEDS, so a
+      // clone without an implementation would take the ETH and its markReady/claim/refund would appear to go
+      // through while doing nothing - that is exactly the case this refuses. The live code is re-hashed here, so
+      // the verdict does not trust the factory's own answer alone.
+      if (implementationPolicy) {
+        if (typeof evmCall !== "function") fail("quote-factory-unchecked", { step: "factory", why: "no-chain-read" });
+        if (typeof evmCode !== "function") fail("quote-factory-unchecked", { step: "factory", why: "no-code-read" });
+        const verdict = await engine.evm.verifyFactoryImplementationOnChain({
+          factory: declaredFactory,
+          read: evmCall,
+          code: (address) => evmCode(address),
+          policy: implementationPolicy,
+          hashCode: (codeHex) => bytesToHexQ(keccak256(hexToBytesQ(codeHex) || new Uint8Array(0))),
+        });
+        if (!verdict.ok) {
+          const unknown = verdict.why === "implementation-code-unknown" ||
+            verdict.why === "implementation-code-mismatch" || verdict.why === "implementation-has-no-code";
+          fail(unknown ? "quote-factory-code-unknown" : "quote-factory-unchecked",
+            { step: "factory", why: verdict.why, factory: declaredFactory, implementation: verdict.implementation || null });
+        }
+      }
       // BINDING THE QUOTE TO OUR TERMS. The signature confirms the provider signed THIS quote, but not that it is
       // about our swap: we are responsible for the binding. The context string is computed by OUR engine module
       // (format arrakis-order-v3; the field order is part of the protocol and must not be rearranged). There is

package/src/sweep.mjs

@@ -14,6 +14,22 @@ const STEPS = ["unlock", "sync", "sweep", "relay"];
 
 const contentsOf = (file) => (typeof file === "string" ? file : file && typeof file.contents === "string" ? file.contents : null);
 
+// A LOW-LEVEL WALLET ERROR IS STILL A REFUSAL, AND EVERY REFUSAL CARRIES A CODE.
+//
+// The library brings its own exceptions with no code at all - monero-ts answers "failed to get hashes" while
+// scanning, and lets it out as a bare `Error`. Releasing one turns a named refusal into `code: null` + raw
+// text: the interface cannot translate it (it has no phrase to look up) and a check cannot assert it. So a
+// wallet step that fails with anything but an SdkError is re-thrown as one, on a code from the package's own
+// dictionary, with the library's message kept as a detail.
+const walletStep = async (surface, step) => {
+  try {
+    return await step();
+  } catch (error) {
+    if (error instanceof SdkError) throw error;
+    throw new SdkError("wallet-rejected", { surface, why: String((error && error.message) || error) });
+  }
+};
+
 export function createSweep({ http, config }) {
   // THE NAME IS NEEDED BY THE OBJECT ITSELF: `run` calls `api.plan(...)` - the step order is held by the plan and
   // the withdrawal living in one object, not in two copies. During a manual merge of branches the object was left
@@ -157,9 +173,16 @@ export function createSweep({ http, config }) {
 
     // SIGNING WITHOUT SENDING - AS A SEPARATE STEP. The core HOLDS the signed transaction until the person's
     // decision: otherwise the interface could not show what exactly will leave, and would tell about it only after
-    // sending. Here is the whole order UP TO AND INCLUDING SIGNING: plan -> wallet -> open -> sync -> free remainder
+    // sending. Here is the whole order UP TO AND INCLUDING SIGNING: plan -> wallet -> open -> free remainder
     // (an empty one STOPS the withdrawal with a code) -> sign (relay: false). The wallet stays open until `relay`,
     // and the session token is the only handle to it.
+    //
+    // THE FREE REMAINDER IS READ AND JUDGED BEFORE ANY INPUT SELECTION, AND A SYNC PASS IS NOT THE VERDICT.
+    // The wallet library fails low-level while scanning a chain it cannot read (measured: monero-ts `sync()` against
+    // a regtest node answering "failed to get hashes"), and that bare error used to escape BEFORE the remainder was
+    // read - an empty wallet was refused by a raw exception (`code: null`) instead of `insufficient-funds`. A failed
+    // pass is not fatal by itself: the remainder below decides, and anything still blocking the signature is refused
+    // WITH A CODE from the dictionary (see `walletStep`).
     async sign(request) {
       const plan = await api.plan(request);
       if (!request || typeof request.to !== "string" || !request.to) throw new SdkError("bad-input", { field: "to" });
@@ -171,12 +194,14 @@ export function createSweep({ http, config }) {
 
       await wallet.open(plan);
       try {
-        await wallet.sync();
-        const unlocked = BigInt(await wallet.unlockedBalance());
+        // A SYNC PASS - BEST-EFFORT, NOT THE VERDICT. A node whose chain the wallet cannot scan makes the library
+        // throw; that must not pre-empt the funds verdict below, and it must not leave as raw text.
+        try { await wallet.sync(); } catch { /* the remainder below decides; a real blocker is refused by a code */ }
+        const unlocked = BigInt(await walletStep("unlockedBalance", () => wallet.unlockedBalance()));
         // AN EMPTY REMAINDER STOPS THE WITHDRAWAL BEFORE SIGNING: otherwise the wallet would sign a transaction for
         // zero, and the refusal would look like success.
         if (unlocked <= 0n) throw new SdkError("insufficient-funds", { unlocked: unlocked.toString() });
-        const signed = await wallet.sweepUnlocked({ address: request.to, relay: false });
+        const signed = await walletStep("sweepUnlocked", () => wallet.sweepUnlocked({ address: request.to, relay: false }));
         const token = "sweep-" + (++sessionSeq);
         sessions.set(token, { wallet, plan, signed });
         return { token, amount: unlocked.toString(), to: request.to, swept: plan.address };