@ninsei-labs/sdk 0.39.3 → 0.40.0-develop.1

package/engine/evm/permit.js

@@ -1,35 +1,39 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/evm/permit.js for the SDK package.
-// Edit the source under www/js, then run: node tools/build-sdk-engine.mjs
-// tools/check-sdk-engine.mjs reddens on any drift, so a stale copy cannot ship silently.
+// Edit the source under www/js and regenerate the mirror; a drift guard reddens on any difference.
 // Everything below this header is identical to the source.
 
-// РАЗРЕШЕНИЕ НА ТОКЕН ДЛЯ ПОКУПКИ БЕЗ СВОЕГО ETH (issue #97, часть C): что именно умеет токен и чего не хватает.
+// TOKEN ALLOWANCE FOR BUYING WITHOUT OWN ETH: what the token supports and what is missing.
 //
-// ЧТО ЗДЕСЬ И ЧЕГО НЕТ. Здесь ТОЛЬКО селекторы, сборка calldata и ЧЕСТНЫЙ вердикт о том, хватает ли протоколу
-// разрешения по подписи. Ни одного вывода «у USDC permit есть» из памяти тут не записано: такой вывод -
-// догадка, а догадка об учётной функции токена стоит денег. Возможность ПРОВЕРЯЕТСЯ чтением цепи (есть ли у
-// адреса код, отвечает ли DOMAIN_SEPARATOR словом, отвечает ли nonces(owner)), и вердикт умеет говорить
-// «неизвестно» - третьим значением, а не одним из двух.
+// WHAT IS HERE AND WHAT IS NOT. Only selectors, calldata assembly and an HONEST verdict on whether a signature
+// allowance suffices. No conclusion like "USDC has permit" is written from memory: that is a guess, and a guess
+// about a token's accounting function costs money. The capability is PROBED by reading the chain, and the verdict
+// can say "unknown" as a third value.
 //
-// ЧТО УЖЕ ПРОВЕРЕНО ПРО НАШУ НОГУ ОБМЕНА (docs/48, www/js/evm/dexExec.js): разрешение нужно РОУТЕРУ обычным
-// approve. Роутер этой сборки Permit2 НЕ ЗНАЕТ (`permit2()` у него откатывает, перенос оплачивает
-// TransferHelper.safeTransferFrom от msg.sender). Значит Permit2 в реестре лежит для БУДУЩЕГО пути
-// финансирования, а не потому, что этот своп его вызывает.
+// WHAT IS ALREADY CHECKED FOR OUR SWAP LEG: the allowance is needed by the ROUTER as a normal approve. The
+// router of this build does NOT know Permit2 (permit2() reverts; the transfer is paid by TransferHelper.safeTransferFrom
+// from msg.sender). So Permit2 sits in the registry for a FUTURE funding path.
 //
-// ПОЧЕМУ ОДНОЙ ТРАНЗАКЦИИ ЗДЕСЬ НЕТ, И ЭТО НЕ ЗАБЫВЧИВОСТЬ. Своп платит ТОТ, КОГО роутер видит `msg.sender`.
-// Пользователь без ETH не может отправить ни approve, ни своп, ни внесение. Внести за него и списать USDC по
-// его подписи может только КОНТРАКТ-исполнитель (EOA чужую подпись на списание предъявить не может). Такого
-// контракта в репозитории нет и план 61 его не называет, поэтому `usdcWithoutEthVerdict` ОТКАЗЫВАЕТСЯ назвать
-// путь исполняемым и говорит, чего не хватает. Собирать calldata «на всякий случай» - значит выдать догадку
-// за согласие (ровно то, что док 48 называет ловушкой подставленного получателя).
+// WHY THERE IS NO SINGLE-TRANSACTION PATH HERE, AND IT IS NOT AN OVERSIGHT. The router sees msg.sender as the payer.
+// A user without ETH cannot send approve, swap or deposit. Only an EXECUTOR CONTRACT could deposit for them and
+// pull USDC by their signature (an EOA cannot present someone else's signature). No such contract exists here, so
+// the SINGLE-TRANSACTION path stays refused and says what is missing (kind "no-orchestrator"). BUT A PERSON WITH
+// NO OWN NATIVE COIN IS NO LONGER SENT AWAY BY THAT ALONE: the wallet's balance decides the path first, and an
+// ASYNCHRONOUS provider (an intent auction, whose settlement arrives later) carries the purchase when the wallet
+// cannot cover the gas - the swap settles first and the escrow is funded after it. See usdcWithoutEthVerdict below
+// and www/js/evm/asyncRoute.js - and it is a NAMED refusal only when no provider serves the network.
 //
-// ПОДПИСЬ ВНОСЯЩЕГО (www/js/evm/depositor.js) - ДРУГОЕ РАЗРЕШЕНИЕ. Оно даёт релейщику право ОТПРАВИТЬ
-// транзакцию создания ордера, но не право списать токен. Одно другое не заменяет: списание USDC требует
-// отдельного разрешения ПО ТОКЕНУ (approve или permit), и оно адресуется тому, кто тянет токен.
+// THE DEPOSITOR SIGNATURE IS A DIFFERENT ALLOWANCE. It lets a relayer SEND the order-creation transaction, but
+// not pull the token. Pulling USDC needs a separate TOKEN allowance (approve or permit) addressed to the puller.
 
-// Селекторы ERC-20 и EIP-2612. Рядом с каждым - строка подписи, из которой он посчитан: проверка
-// (tools/check-usdc-without-eth.mjs) пересчитывает keccak256 от этих строк, поэтому селектор не может
-// разойтись с подписью молча.
+// THE BALANCE-DRIVEN PATH CHOICE. Whether a provider serves a network ASYNCHRONOUSLY (an intent auction whose
+// settlement arrives later - see www/js/evm/asyncRoute.js) is what decides the path for a person with no own
+// native coin: covered gas -> the ordinary route; short native + a served network -> the asynchronous route;
+// short native + an unserved network -> a NAMED refusal. That answer comes from the same table the package's
+// provider layer pins (sdk/src/legs/cow.mjs).
+import { asyncRouteVerdict } from "./asyncRoute.js";
+
+// ERC-20 and EIP-2612 selectors. Next to each is the signature string it was computed from, and a check
+// recomputes keccak256 of those strings, so a selector cannot diverge from its signature silently.
 export const ERC20_METHOD = {
   approve: { hex: "0x095ea7b3", signature: "approve(address,uint256)" },
   allowance: { hex: "0xdd62ed3e", signature: "allowance(address,address)" },
@@ -47,20 +51,26 @@ const addrWord = (a) => hexBody(a).toLowerCase().padStart(64, "0");
 const uintWord = (v) => BigInt(v).toString(16).padStart(64, "0");
 const wordBytes = (hex) => {
   const b = hexBody(hex);
-  // ПУСТОЙ ОТВЕТ - ЭТО «НЕ ПРОЧИТАЛИ», А НЕ «НОЛЬ БАЙТ». Так eth_call отвечает по адресу без кода:
-  // показать это как «нет домена» значило бы принять незнание за отказ токена.
+  // AN EMPTY ANSWER IS "NOT READ", NOT "ZERO BYTES". This is how eth_call answers for an address without code.
   if (b.length === 0) return null;
   return b.length % 2 ? null : b.length / 2;
 };
 
-// calldata для разрешения по подписи (EIP-2612). Подпись - r || s || v (65 байт); v - в {27,28}.
+// A quantity as BigInt, or null. An empty/unreadable value is null ("not known"), never zero: a zero balance
+// and an unread balance are different states, and the path choice must not confuse them.
+const toBig = (v) => {
+  if (v === null || v === undefined || v === "") return null;
+  try { return BigInt(typeof v === "bigint" ? v : String(v)); } catch { return null; }
+};
+
+// calldata for a signature allowance (EIP-2612). Signature is r || s || v (65 bytes); v in {27,28}.
 export function encodePermit({ owner, spender, value, deadline, signature }) {
-  if (!isAddr(owner) || !isAddr(spender)) throw new Error("permit: owner и spender обязаны быть адресами");
+  if (!isAddr(owner) || !isAddr(spender)) throw new Error("permit: owner and spender must be addresses");
   const hex = hexBody(signature);
-  if (hex.length !== 130) throw new Error("permit: подпись обязана быть 65 байт, а пришло " + hex.length / 2);
+  if (hex.length !== 130) throw new Error("permit: the signature must be 65 bytes, got " + hex.length / 2);
   let v = parseInt(hex.slice(128, 130), 16);
   if (v < 27) v += 27;
-  if (v !== 27 && v !== 28) throw new Error("permit: v вне {27,28}: " + v);
+  if (v !== 27 && v !== 28) throw new Error("permit: v outside {27,28}: " + v);
   return EIP2612_METHOD.permit.hex +
     addrWord(owner) + addrWord(spender) + uintWord(value) + uintWord(deadline) +
     uintWord(v) + hex.slice(0, 64) + hex.slice(64, 128);
@@ -71,55 +81,118 @@ export const encodeDomainSeparator = () => EIP2612_METHOD.DOMAIN_SEPARATOR.hex;
 export const encodeApprove = ({ spender, amountWei }) => ERC20_METHOD.approve.hex + addrWord(spender) + uintWord(amountWei);
 
 /**
- * Умеет ли ЭТОТ адрес разрешение по подписи (EIP-2612). Ответ - ТРИ состояния, и это не педантизм:
- * «не проверено» обязано отличаться от «нет».
- *   supported === true  - код есть, DOMAIN_SEPARATOR отвечает словом, nonces(owner) отвечает словом,
- *                         и в байткоде присутствует селектор permit;
- *   supported === false - код есть, но одного из признаков НЕТ (тогда разрешение по подписи недоступно);
- *   supported === null  - прочитать не удалось (нет кода/пустой ответ): это НЕ «нет permit», это «не знаем».
+ * Whether THIS address supports a signature allowance (EIP-2612). The answer has THREE states: "not checked"
+ * must differ from "no".
+ *   supported === true  - code exists, DOMAIN_SEPARATOR answers 32 bytes, nonces(owner) answers 32 bytes, and the bytecode has the permit selector;
+ *   supported === false - code exists, but a signal is MISSING (then a signature allowance is unavailable);
+ *   supported === null  - could not read (no code / empty answer): this is NOT "no permit", it is "unknown".
  */
 export function permitSupportVerdict({ code = null, domainSeparator = null, nonces = null, owner = null } = {}) {
   const codeHex = hexBody(code);
-  if (codeHex.length === 0) return { supported: null, kind: "no-code", reason: "по адресу токена нет кода - это не токен, и разрешение читать не у чего" };
-  if (!isAddr(owner)) return { supported: null, kind: "no-owner", reason: "владелец не назван - nonces(owner) прочитать нечем" };
+  if (codeHex.length === 0) return { supported: null, kind: "no-code", reason: "no code at the token address - not a token, the allowance cannot be read" };
+  if (!isAddr(owner)) return { supported: null, kind: "no-owner", reason: "no owner given - cannot read nonces(owner)" };
   const dsBytes = wordBytes(domainSeparator);
-  if (dsBytes === null) return { supported: null, kind: "domain-unread", reason: "DOMAIN_SEPARATOR не отвечает 32 байтами: читать не удалось" };
-  if (dsBytes !== 32) return { supported: false, kind: "domain-empty", reason: "DOMAIN_SEPARATOR вернул " + dsBytes + " байт вместо 32: EIP-712-домен не заявлен" };
+  if (dsBytes === null) return { supported: null, kind: "domain-unread", reason: "DOMAIN_SEPARATOR did not answer 32 bytes: could not read" };
+  if (dsBytes !== 32) return { supported: false, kind: "domain-empty", reason: "DOMAIN_SEPARATOR returned " + dsBytes + " bytes instead of 32: no EIP-712 domain declared" };
   const nonceBytes = wordBytes(nonces);
-  if (nonceBytes === null) return { supported: null, kind: "nonces-unread", reason: "nonces(owner) не отвечает: читать не удалось" };
-  if (nonceBytes !== 32) return { supported: false, kind: "nonces-empty", reason: "nonces(owner) вернул " + nonceBytes + " байт вместо 32: EIP-2612-счётчика нет" };
+  if (nonceBytes === null) return { supported: null, kind: "nonces-unread", reason: "nonces(owner) did not answer: could not read" };
+  if (nonceBytes !== 32) return { supported: false, kind: "nonces-empty", reason: "nonces(owner) returned " + nonceBytes + " bytes instead of 32: no EIP-2612 counter" };
   if (!codeHex.toLowerCase().includes(EIP2612_METHOD.permit.hex.slice(2))) {
-    return { supported: false, kind: "permit-selector-absent", reason: "в байткоде токена нет селектора permit: разрешения по подписи токен не предоставляет" };
+    return { supported: false, kind: "permit-selector-absent", reason: "the token bytecode has no permit selector: no signature allowance" };
   }
-  return { supported: true, kind: "eip2612", reason: "токен заявляет EIP-712-домен, счётчик nonces и селектор permit" };
+  return { supported: true, kind: "eip2612", reason: "the token declares an EIP-712 domain, a nonces counter and the permit selector" };
 }
 
 /**
- * Можно ли провести покупку за токен БЕЗ своего ETH ОДНОЙ транзакцией. Вердикт говорит ИМЕННО то, чего не
- * хватает, и НЕ выдаёт calldata, пока путь не исполним полностью.
- * @param {{ orchestrator?: string|null, permitSupported?: boolean|null, token?: string|null }} args
+ * WHICH WAY A "BUY WITHOUT OWN NATIVE COIN" GOES - DECIDED BY THE WALLET'S BALANCE, NOT BY A FIXED REFUSAL.
+ *
+ * The wallet's own native coin decides the path BEFORE any token question:
+ *   * the wallet covers the gas the deal needs (`gasNeedWei`) - the ordinary, synchronous path is taken: the
+ *     person pays with their own gas and nothing has to be asked of anyone (`kind: "own-gas"`, `path: "sync"`);
+ *   * the wallet does NOT cover it - the ASYNCHRONOUS path is taken (`kind: "async-route"`, `path: "async"`):
+ *     the swap settles FIRST and the escrow is funded AFTER it, so the deposit and its gas come later. This is
+ *     NOT a refusal as long as a provider serves the network - the "stop being a refusal" rule;
+ *   * no provider serves the network - a NAMED refusal (`kind: "no-async-provider"`, blocked): "the wallet cannot
+ *     cover the gas and there is no asynchronous path here" - never silence and never a silent "yes".
+ *
+ * An unread balance or an unmeasured gas need is its OWN state: "not known" must not look like "covered", but it
+ * is not a refusal either - the caller reads `blocked`.
+ *
+ * The single-transaction executor branch lives BELOW and stays reachable when the balance question cannot be
+ * answered at all (no gas need given): an executor contract could still carry the whole purchase in one
+ * transaction. That branch is the older verdict and is kept so existing callers see the same kinds.
+ *
+ * @param {{ orchestrator?: string|null, permitSupported?: boolean|null, token?: string|null,
+ *           nativeBalanceWei?: *, gasNeedWei?: *, asyncProvider?: object|null, chainId?: * }} args
  */
-export function usdcWithoutEthVerdict({ orchestrator = null, permitSupported = null, token = null } = {}) {
-  // ПЕРВЫЙ И ГЛАВНЫЙ ОТКАЗ, и он не про токен. Своп платит msg.sender (роутер), а чужую подпись на списание
-  // может предъявить только КОНТРАКТ. Без исполнителя однотранзакционный путь не существует ВООБЩЕ - и это
-  // не зависит от того, есть ли у токена permit.
+export function usdcWithoutEthVerdict({
+  orchestrator = null, permitSupported = null, token = null,
+  nativeBalanceWei = null, gasNeedWei = null, asyncProvider = null, chainId = null,
+} = {}) {
+  const need = toBig(gasNeedWei);
+  // THE ASYNC ANSWER - from the caller's explicit verdict (the package layer's own answer) or from the engine's
+  // table by chainId. Either way it is a VALUE with a named reason, never silence.
+  const async = asyncProvider && typeof asyncProvider === "object"
+    ? asyncProvider
+    : (chainId === null || chainId === undefined ? null : asyncRouteVerdict({ chainId }));
+  const asyncOk = Boolean(async && async.ok === true);
+  const asyncReason = async && async.ok === false && async.reason ? String(async.reason) : "no-async-provider";
+
+  if (need !== null && need > 0n) {
+    const have = toBig(nativeBalanceWei);
+    if (have === null) {
+      return {
+        ok: false, blocked: false, checked: false, kind: "balance-unread", path: null,
+        gasNeedWei: need.toString(),
+        reason: "the wallet's native balance was not read, so it is unknown which path fits - read the balance before choosing",
+      };
+    }
+    if (have >= need) {
+      return {
+        ok: true, blocked: false, checked: true, kind: "own-gas", path: "sync",
+        nativeBalanceWei: have.toString(), gasNeedWei: need.toString(),
+        reason: "the wallet's own native covers the gas this deal needs, so the ordinary synchronous path is taken",
+      };
+    }
+    const base = {
+      checked: true, nativeBalanceWei: have.toString(), gasNeedWei: need.toString(),
+      shortfallWei: (need - have).toString(),
+    };
+    if (asyncOk) {
+      return {
+        ok: true, blocked: false, ...base, kind: "async-route", path: "async",
+        provider: async.provider ?? null, venue: async.venue ?? null,
+        reason: "the wallet's own native does not cover the gas this deal needs, but an asynchronous provider serves this network: the swap settles first and the escrow is funded after it, so the deposit's gas is paid later",
+      };
+    }
+    return {
+      ok: false, blocked: true, ...base, kind: "no-async-provider", path: null,
+      reason: "the wallet's own native does not cover the gas this deal needs and no asynchronous provider serves this network (" + asyncReason + "): there is no path for a purchase without own native coin here",
+    };
+  }
+
+  // GAS NOT MEASURED: the balance cannot decide anything - fall through to the single-transaction executor
+  // verdict (unchanged behaviour for callers that pass no gas need).
+  // THE REFUSAL WITHOUT AN EXECUTOR, and it is not about the token. The swap pays msg.sender (the router), and
+  // only a CONTRACT can present someone else's pull signature. Without an executor the one-transaction path
+  // does not exist AT ALL, regardless of the token.
   if (!isAddr(orchestrator)) {
     return {
-      ok: false, blocked: true, kind: "no-orchestrator",
-      reason: "нет контракта-исполнителя: списать токен по подписи пользователя и внести натив в эскроу одной транзакцией может только контракт, а в этой сборке его нет. Подпись вносящего без него даёт релейщику право ОТПРАВИТЬ создание ордера, но не право списать токен",
+      ok: false, blocked: true, kind: "no-orchestrator", path: null,
+      reason: "no executor contract: only a contract could pull a token by the user signature and deposit native into the escrow in one transaction, and this build has none. The depositor signature without it lets a relayer SEND the order creation, but not pull the token",
     };
   }
   if (permitSupported === false) {
     return {
       ok: false, blocked: true, kind: "token-no-permit",
-      reason: "у токена нет разрешения по подписи (EIP-2612): разрешение придётся выдавать отдельным approve, то есть отдельной транзакцией - одной транзакцией путь не собирается",
+      reason: "the token has no signature allowance (EIP-2612): the allowance must be a separate approve, i.e. a separate transaction - the path does not assemble into one transaction",
     };
   }
   if (permitSupported !== true) {
     return {
       ok: false, blocked: true, kind: "permit-unproven",
-      reason: "неизвестно, умеет ли токен разрешение по подписи: «не проверено» - это не «можно». Возможность обязана быть прочитана у цепи до сборки пути",
+      reason: "unknown whether the token supports a signature allowance: \"not checked\" is not \"possible\". The capability must be read from the chain before assembling the path",
     };
   }
-  return { ok: true, blocked: false, kind: "one-tx-possible", reason: "исполнитель назван, токен заявляет EIP-2612: путь одной транзакцией собирается" };
+  return { ok: true, blocked: false, kind: "one-tx-possible", path: "sync", reason: "an executor is present and the token declares EIP-2612: the one-transaction path assembles" };
 }

package/engine/evm/prices.js

@@ -1,32 +1,23 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/evm/prices.js for the SDK package.
-// Edit the source under www/js, then run: node tools/build-sdk-engine.mjs
-// tools/check-sdk-engine.mjs reddens on any drift, so a stale copy cannot ship silently.
+// Edit the source under www/js and regenerate the mirror; a drift guard reddens on any difference.
 // Everything below this header is identical to the source.
 
-// Живые рыночные числа для EVM-ноги: цена нейтива (Chainlink on-chain) и стоимость газа (RPC).
-//
-// ПОЧЕМУ ON-CHAIN, А НЕ API. Цена берётся вызовом контракта через тот же RPC, что уже разрешён
-// в CSP (`connect-src`), поэтому:
-//   - не появляется ни одного нового внешнего домена (и ни одного нового доверенного сервиса);
-//   - нет ключей, лимитов и «мы упали, потому что у CoinGecko 429»;
-//   - значение нельзя перепутать с ценой другой сети: адрес фида свой у каждой цепи.
-// Адреса фидов НЕ выдуманы: каждый подтверждён вызовом в сети - описание `description()` должно
-// совпасть с ожидаемой парой, а ответ - попасть в разумный коридор и быть свежим. Проверка живёт
-// в tools/check-prices.mjs (работает на заглушке RPC, без сети).
-//
-// ЧЕГО ЗДЕСЬ НЕТ: если фида для сети нет или он молчит - возвращаем null, и вызывающий код обязан
-// показать, что число демонстрационное, а не подставить вчерашнюю константу молча.
+// LIVE MARKET NUMBERS FOR THE EVM LEG: the native price (Chainlink on-chain) and the gas cost (RPC).
+// WHY ON-CHAIN, NOT AN API: the price is a contract call over the same RPC already allowed by the CSP
+// (connect-src), so no new external domain appears, there are no keys or rate limits, and the feed address is
+// per chain. The feed addresses are NOT invented: each is confirmed by a call on chain (description() must match).
+// WHAT IS NOT HERE: if a network has no feed or it is silent, return null and let the caller mark the number as demo.
 
 const SELECTOR = {
   description: "0x7284e416", // description()
   latestRoundData: "0xfeaf968c", // latestRoundData() -> (roundId, answer, startedAt, updatedAt, answeredInRound)
 };
 
-const CACHE_MS = 60_000; // цена: минута - компромисс между свежестью и числом запросов
-const GAS_CACHE_MS = 30_000; // газ меняется чаще, но и он не обязан бегать на каждый ввод символа
-const MAX_AGE_MS = 24 * 60 * 60 * 1000; // старше суток фид считаем несвежим и не показываем как живой
+const CACHE_MS = 60_000; // price: a minute balances freshness and request count
+const GAS_CACHE_MS = 30_000; // gas changes more often, but it need not run on every keystroke
+const MAX_AGE_MS = 24 * 60 * 60 * 1000; // older than a day, the feed is stale and not shown as live
 
-const cache = new Map(); // ключ: chainId + вид запроса
+const cache = new Map(); // key: chainId + request kind
 
 function cached(key, ttlMs) {
   const hit = cache.get(key);
@@ -47,14 +38,14 @@ async function rpc(chain, method, params = []) {
   });
   if (!res.ok) throw new Error(method + ": HTTP " + res.status);
   const j = await res.json();
-  if (j.error) throw new Error(method + ": " + (j.error.message || "ошибка RPC"));
+  if (j.error) throw new Error(method + ": " + (j.error.message || "RPC error"));
   return j.result;
 }
 
 const word = (data, i) => BigInt("0x" + String(data).slice(2).slice(i * 64, (i + 1) * 64));
 
-// Декодирование строки ABI: [offset][length][bytes]. Нужно, чтобы отличить фид ETH/USD от любого
-// другого, который кто-то подставил в конфиг. TextDecoder, а не Buffer: этот код живёт в браузере.
+// ABI string decode: [offset][length][bytes]. Needed to tell the ETH/USD feed from another one. TextDecoder,
+// not Buffer: this code runs in the browser.
 function decodeString(data) {
   const s = String(data || "");
   if (s.length < 2 + 128) return "";
@@ -65,7 +56,7 @@ function decodeString(data) {
   return new TextDecoder().decode(bytes);
 }
 
-// Цена нейтива в USD. null - если фида нет, он молчит или значения не проходят проверку.
+// Native price in USD. null if the feed is missing, silent, or fails validation.
 export async function nativeUsd(chain, { force = false } = {}) {
   const feed = chain && chain.priceFeed;
   if (!feed || !feed.address) return null;
@@ -87,7 +78,7 @@ export async function nativeUsd(chain, { force = false } = {}) {
     const fresh = updatedAt > 0 && Date.now() - updatedAt < MAX_AGE_MS;
     const sane = value >= (feed.min || 0.01) && value <= (feed.max || 1e7);
     if (desc !== feed.pair || !fresh || !sane) {
-      return put(key, null); // null, а не «примерно столько»: молчание честнее выдумки
+      return put(key, null); // null, not "roughly this": silence is more honest than a guess
     }
     return put(key, { usd: value, updatedAt, source: "chainlink", pair: desc });
   } catch {
@@ -95,9 +86,8 @@ export async function nativeUsd(chain, { force = false } = {}) {
   }
 }
 
-// Стоимость газа в USD: оценка лимита × цена газа × цена нейтива.
-// На Arbitrum в цену газа уже входит L1-составляющая (так устроен их gas price), поэтому
-// отдельный вызов NodeInterface не нужен - обычная оценка даёт сопоставимую с кошельками цифру.
+// Gas cost in USD: limit estimate x gas price x native price. On Arbitrum the L1 part is already in the gas
+// price, so no separate NodeInterface call is needed.
 export async function gasUsd(chain, { from = null, payToken = null, amountWei = null } = {}) {
   const key = chain.id + ":gas";
   const hit = cached(key, GAS_CACHE_MS);
@@ -108,15 +98,12 @@ export async function gasUsd(chain, { from = null, payToken = null, amountWei =
     const gasPrice = BigInt(await rpc(chain, "eth_gasPrice"));
     let gasLimit = null;
     let measured = false;
-    // Оцениваем ту транзакцию, которую человек и подпишет: перевод оплачиваемого токена.
-    // Эскроу ещё не задеплоен, поэтому это честная нижняя оценка, а не «газ свопа».
+    // We estimate the transaction the person will actually sign: a transfer of the paying token.
+    // The escrow is not deployed yet, so this is an honest lower bound, not the swap gas.
     try {
-      // Без аккаунта eth_estimateGas подставляет НУЛЕВОЙ адрес, и перевод токена справедливо
-      // падает с "ERC20: transfer from the zero address". Поэтому без from не оцениваем вовсе:
-      // берём типовой лимит и честно помечаем, что он не измерен (в интерфейсе это видно).
-      // ВАЖНО: признак "перевод токена" и признак "есть аккаунт" - РАЗНЫЕ условия. Раньше они
-      // были слиты в одну ветку, и без аккаунта перевод токена получал лимит нативного перевода
-      // (21000 вместо 65000) - поймал tools/check-prices.mjs.
+      // Without an account eth_estimateGas uses the ZERO address and a token transfer fails with
+      // "ERC20: transfer from the zero address". So without `from` we do not estimate: we take a typical
+      // limit and mark it as unmeasured. NOTE: "token transfer" and "has account" are DIFFERENT conditions.
       const tokenTransfer = Boolean(payToken && !payToken.native);
       if (tokenTransfer && from) {
         // transfer(address,uint256) = 0xa9059cbb
@@ -128,7 +115,7 @@ export async function gasUsd(chain, { from = null, payToken = null, amountWei =
         gasLimit = BigInt(await rpc(chain, "eth_estimateGas", [{ from, to: from, value: "0x1" }]));
         measured = true;
       } else {
-        // Ни аккаунта, ни измерения: типовой лимит и честный признак «не измерено».
+        // No account and no measurement: a typical limit and an honest 'not measured' flag.
         gasLimit = BigInt(chain.gasLimitFallback || (tokenTransfer ? 65000 : 21000));
       }
     } catch {
@@ -142,21 +129,19 @@ export async function gasUsd(chain, { from = null, payToken = null, amountWei =
   }
 }
 
-// Одна точка обновления: подтянуть цену и газ для сети и вернуть то, чем можно подписать интерфейс.
+// One refresh point: fetch price and gas for the network and return what the interface can sign with.
 export async function refreshChainPrices(chain, opts = {}) {
   if (!chain || !chain.rpcUrl) return { nativeUsd: null, gasUsd: null, source: "none" };
   const [price, gas] = await Promise.all([nativeUsd(chain), gasUsd(chain, opts)]);
-  // Цена нейтива - общая для всех расчётов сети (балансы, «≈ $», оценка газа), поэтому пишем её
-  // в конфиг сети: иначе одна и та же цифра жила бы в двух местах и разъезжалась.
+  // The native price is shared by all network maths (balances, '~ $', gas), so it is written into the
+  // network config, else the same number would live in two places and drift.
   if (price && Number.isFinite(price.usd)) chain.native.usd = price.usd;
   return {
     nativeUsd: price ? price.usd : null,
     nativeUpdatedAt: price ? price.updatedAt : null,
     gasUsd: gas ? gas.usd : null,
-    // ЦЕНА ГАЗА В ВЕЙ - НАРУЖУ, А НЕ ТОЛЬКО СТОИМОСТЬ ОЦЕНКИ. Из неё считается запас газа на действия ордера
-    // (www/js/evm/gasReserve.js): отметка готовности и возврат - другие транзакции, у них свои пределы, и
-    // «стоимость одной оценки» их не заменяет. Нет газа у цепи - null, и вызывающий обязан сказать, что запас
-    // не измерен, а не подставить ноль.
+    // GAS PRICE IN WEI GOES OUT, not just the estimate cost. The order-action gas reserve is derived from it
+    // (gasReserve.js): the mark and refund are different transactions with their own limits. No gas - null.
     gasPriceWei: gas ? gas.gasPrice : null,
     gasSource: gas ? gas.source : null,
     gasMeasured: gas ? Boolean(gas.measured) : false,
@@ -164,8 +149,8 @@ export async function refreshChainPrices(chain, opts = {}) {
   };
 }
 
-// Коротко и в одну строку, но про ОБЕ половины: строка называется «Gas & price», значит и газ,
-// и цена должны быть в значении. Живая цена видна по самому тексту (Chainlink), демо - по «demo values».
+// Short and one line, but covering BOTH halves: the string is "Gas & price", so both gas and price must be
+// in the value. A live price shows as Chainlink, a demo one as 'demo values'.
 export function priceLabel(info) {
   if (!info || !info.source || info.source === "none") return "demo values";
   if (info.source !== "chainlink") return "demo values";