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

package/engine/evm/dex.js

@@ -1,84 +1,83 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/evm/dex.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.
 
-// DEX-нога: КОТИРОВКА Uniswap v3, полученная из цепи. ТОЛЬКО ЧТЕНИЕ: eth_call, ни одной транзакции.
+// THE DEX LEG: a Uniswap v3 quote read from the chain. READ ONLY: eth_call, not one transaction.
 //
-// ЧТО ЗДЕСЬ ЗАМЕНЕНО. Раньше в разбивке цены стоял мок: "Uniswap v3 USDC/WETH 0.05%" и спред 0.0004
-// брались из констант конфига (www/js/mock/market.js:76-77), то есть комиссия пула и выход были
-// ВЫДУМАНЫ. Теперь и то и другое читается у самой цепи через QuoterV2 - тот же путь, которым страница
-// уже читает цену и газ (evm/prices.js): POST к chain.rpcUrl, никаких новых доменов, никаких новых
-// параметров в URL и никаких новых внешних адресов. Хост уже разрешён в CSP - он берётся из реестра сетей.
+// WHAT IS REPLACED HERE. The price breakdown used to hold a mock: "Uniswap v3 USDC/WETH 0.05%" and the spread
+// 0.0004 came from config constants, i.e. the pool fee and the output were INVENTED. Now both are read from the
+// chain itself via QuoterV2 - the same path the page already uses to read price and gas (evm/prices.js): a POST
+// to chain.rpcUrl, no new domains, no new URL parameters and no new external addresses. The host is already
+// allowed in CSP - it comes from the network registry.
 //
-// СЕЛЕКТОРЫ И СТРУКТУРА АРГУМЕНТОВ ВЗЯТЫ ИЗ ВЫЗОВА, А НЕ ИЗ ПАМЯТИ (проверено 2026-09-23):
-//   * selector = keccak256(подпись)[0..4]. Считается в тесте (tools/check-uniswap-quote.mjs) из строки
-//     подписи, лежащей здесь рядом с селектором, и наличие селектора сверяется в КОДЕ контракта.
-//   * АРГУМЕНТЫ ИДУТ ПЯТЬЮ СЛОВАМИ ПОДРЯД, БЕЗ СЛОВА-СМЕЩЕНИЯ. Подпись формально принимает структуру
-//     (address,address,uint256,uint24,uint160), и по спецификации ABI первым словом должно идти
-//     смещение 0x20. НА РАЗВЁРНУТОМ QuoterV2 ЭТО ЛОЖЬ: вариант со смещением ОТКАТЫВАЕТ (execution
-//     reverted), а пять слов подряд отвечают четырьмя словами (amountOut, sqrtPriceX96After,
-//     initializedTicksCrossed, gasEstimate). Поэтому кодируем подряд - и это записано здесь, чтобы
-//     никто не "починил" код по спецификации и не сломал котировку молча.
+// SELECTORS AND ARGUMENT SHAPE ARE TAKEN FROM A CALL, NOT FROM MEMORY (checked 2026-09-23):
+//   * selector = keccak256(signature)[0..4]. Computed by a check from the signature string lying here next to
+//     the selector, and the selector's presence is cross-checked in the contract CODE.
+//   * THE ARGUMENTS GO AS FIVE CONSECUTIVE WORDS, WITHOUT AN OFFSET WORD. The signature formally takes a struct
+//     (address,address,uint256,uint24,uint160) and by the ABI spec the first word should be the offset 0x20. ON
+//     THE DEPLOYED QuoterV2 THAT IS FALSE: the offset variant REVERTS (execution reverted), while five consecutive
+//     words answer with four (amountOut, sqrtPriceX96After, initializedTicksCrossed, gasEstimate). So we encode
+//     consecutively - and this is written here so nobody "fixes" the code to the spec and silently breaks the quote.
 //
-// ЧЕГО МОДУЛЬ НЕ ДЕЛАЕТ: не отправляет транзакции, не делает approve, не свопает и НЕ трогает путь
-// фондирования. Оценка газа здесь - это gasEstimate, который вернул сам QuoterV2 (число из цепи), а не
-// eth_estimateGas по чужой транзакции.
 //
-// ЧЕСТНОЕ "НЕТ КОТИРОВКИ" ВМЕСТО ВЫДУМАННОГО ЧИСЛА. Пустой пул, отсутствие пула, откат котировки и
-// цена, разошедшаяся с эталоном, - ЧЕТЫРЕ РАЗНЫХ ответа, и каждый назван словами (why). Число
-// возвращается только тогда, когда его действительно назвала цепь и оно прошло сверку с эталоном.
+// WHAT THE MODULE DOES NOT DO: it sends no transactions, makes no approve, swaps nothing and does NOT touch the
+// funding path. The gas figure here is the gasEstimate QuoterV2 itself returned (a number from the chain), not
+// eth_estimateGas over someone else's transaction.
 //
-// МАРШРУТ ЗДЕСЬ ОБЪЯВЛЕН, А НЕ ВЫБРАН. Перебора "прямой путь или через хаб" в рантайме нет и быть не
-// должно: человек объявил маршрут в реестре (DEX_ROUTES), а модуль только переводит его в путь и
-// спрашивает цепь ОДНИМ вызовом. Если объявленного маршрута нет (или в нём пусто) - это честное
-// "маршрута нет", причина лежит в данных (route.why), и такая нога блокирует подпись, а не ищет обход.
+// AN HONEST "NO QUOTE" INSTEAD OF AN INVENTED NUMBER. An empty pool, no pool, a reverted quote and a price that
+// diverged from the reference - FOUR DIFFERENT answers, each named in words (why). A number is returned only
+// when the chain really named it and it passed the reference check.
+//
+// THE ROUTE IS DECLARED HERE, NOT CHOSEN. There is no runtime search for "a direct path or via a hub" and there
+// must not be: a person declared the route in the registry (DEX_ROUTES), and the module only turns it into a path
+// and asks the chain IN ONE CALL. If there is no declared route (or it is empty) - that is an honest "no route",
+// the cause lies in the data (route.why), and such a leg blocks signing rather than looking for a detour.
+//
+// THE PRICE CHECK (priceGateVerdict) - A SECOND GUARD OF THE SAME FAMILY as coverage: a wrong price means the
+// deal will not settle and signing does not start. It is computed two ways, neither needing a feed per token: the
+// implied native price from the quote against the reference (Chainlink) and a "near 1:1" band on steps between
+// stables (with no oracle at all). The thresholds are in the registry (DEX_PRICE_GATE), and the testnet exception
+// is data too (a network's dexPriceGate): there the price is wrong by nature, and a wrong price is marked in
+// words rather than stopping the flow. There is still no liquidity scoring here: pool depth is a person's call.
+//
+
+// Selectors. Next to each is the signature string it was computed from: the check recomputes keccak256 over these
+// strings and fails if even one selector diverged from its signature.
+// WHAT IS VERIFIED BY A CALL HERE (2026-09-23, Arbitrum One and Ethereum):
+//   * quoteExactInputSingle 0xc6a5026a - a ONE-step quote, five consecutive words with no offset;
+//   * quoteExactInput 0xcdca1753 - a WHOLE-PATH quote in one call. Signature quoteExactInput(bytes,uint256), the
+//     selector found in the QuoterV2 code on both networks, and a single-step path checked against the single
+//     quote gave EXACTLY the same number (36685744820778786 for 100 USDC), so the path encoding (20-byte address
+//     + 3-byte fee, consecutively) is confirmed by a number, not from memory. There is no reference value - there
+//     is a match of two DIFFERENT calls.
 //
-// ПРОВЕРКА ЦЕНЫ (priceGateVerdict) - ВТОРАЯ ЗАЩИТА ТОЙ ЖЕ СЕМЬИ, что покрытие суммы: неверная цена
-// означает, что сделка не сойдётся, и подпись не начинается. Считается двумя способами, ни один из
-// которых не требует фида на каждый токен: неявная цена натива из котировки против эталона (Chainlink)
-// и полоса "около 1:1" на шагах между стейблами (без оракула вовсе). Пороги - в реестре
-// (DEX_PRICE_GATE), исключение для тестнета - тоже данные (dexPriceGate у сети): там цена негодная по
-// природе, и негодная цена помечается словами, а не останавливает поток. Оценок ликвидности здесь
-// по-прежнему нет: глубину пула решает человек.
-
-// Селекторы. Рядом с каждым - строка подписи, из которой он посчитан: проверка
-// (tools/check-uniswap-quote.mjs) пересчитывает keccak256 от этих строк и падает, если хоть один
-// селектор разошёлся с подписью.
-// ЧТО ЗДЕСЬ ПРОВЕРЕНО ВЫЗОВОМ (2026-09-23, Arbitrum One и Ethereum, tools/check-uniswap-quote.mjs):
-//   * quoteExactInputSingle 0xc6a5026a - котировка ОДНОЙ ступени, пять слов подряд без смещения;
-//   * quoteExactInput 0xcdca1753 - котировка ВСЕГО ПУТИ ОДНИМ ВЫЗОВОМ. Подпись
-//     quoteExactInput(bytes,uint256), селектор найден в коде QuoterV2 в обеих сетях, а сверка
-//     одноступенчатого пути против одиночной котировки дала РОВНО то же число (36685744820778786 на
-//     100 USDC), то есть кодирование пути (20 байт адрес + 3 байта комиссия, подряд) подтверждено числом,
-//     а не по памяти. Эталонного значения нет - есть совпадение двух РАЗНЫХ вызовов.
 export const DEX_METHOD = {
-  // ФОРМА С ТОЧНЫМ ВЫХОДОМ. Это НЕ "сколько выйдет", а "получить ровно столько, потратив не больше
-  // такого-то": при ней вопроса о разнице сумм не существует вовсе (док 45 §"Что добавит DEX-нога").
-  // ОБЕ формы подтверждены вызовом на Arbitrum One и основной сети (tools/check-uniswap-quote.mjs):
-  //   - одиночная даёт amountIn на ровно 0.035 WETH;
-  //   - многошаговая по пути из двух ног тоже отвечает, но ПУТЬ У НЕЁ ЗАДАЁТСЯ В ОБРАТНУЮ СТОРОНУ - от
-  //     получаемого токена к оплачиваемому (прямой путь отказывает: "Unexpected error"). Это измерено, а
-  //     не выведено: перепутать направление здесь стоит отказа вызова.
+  // THE EXACT-OUT SHAPE. This is NOT "how much comes out" but "receive exactly this much, spending no more than
+  // that": with it the question of a difference in amounts does not exist at all.
+  // BOTH shapes are confirmed by a call on Arbitrum One and mainnet:
+  //   - the single one gives amountIn for exactly 0.035 WETH;
+  //   - the multi-step on a two-leg path also answers, but ITS PATH IS SET IN REVERSE - from the received token
+  //     to the paid one (a forward path fails: "Unexpected error"). This is measured, not deduced: getting the
+  //     direction wrong here costs a call refusal.
   quoteExactOutputSingle: { hex: "0xbd21704a", signature: "quoteExactOutputSingle((address,address,uint256,uint24,uint160))" },
   quoteExactOutput: { hex: "0x2f80bb1d", signature: "quoteExactOutput(bytes,uint256)" },
   quoteExactInputSingle: { hex: "0xc6a5026a", signature: "quoteExactInputSingle((address,address,uint256,uint24,uint160))" },
-  // Многошаговая форма: путь передаётся УПАКОВАННЫМ (token|fee|token|fee|token), аргумент динамический,
-  // поэтому здесь смещение 0x40 (см. encodeQuoteExactInput), в отличие от одиночной формы.
+  // The multi-step shape: the path is passed PACKED (token|fee|token|fee|token), the argument is dynamic, so the
+  // offset is 0x40 here (see encodeQuoteExactInput), unlike the single shape.
   quoteExactInput: { hex: "0xcdca1753", signature: "quoteExactInput(bytes,uint256)" },
   getPool: { hex: "0x1698ee82", signature: "getPool(address,address,uint24)" },
   liquidity: { hex: "0x1a686502", signature: "liquidity()" },
   balanceOf: { hex: "0x70a08231", signature: "balanceOf(address)" },
-  // withdraw у WETH9: НЕ для отправки, только для оценки газа unwrap (и только если у нас есть
-  // измеренный держатель WETH - см. tools/check-uniswap-quote.mjs).
+  // withdraw on WETH9: NOT for sending, only for estimating the unwrap gas (and only if we have a measured WETH
+  // holder - see the DEX quote check).
   withdraw: { hex: "0x2e1a7d4d", signature: "withdraw(uint256)" },
 };
 
-// ПУТЬ ИЗ ОБЪЯВЛЕННОГО МАРШРУТА (DEX_ROUTES в реестре). Здесь НЕТ никакого выбора: человек объявил шаги
-// со ступенями, а мы только переводим символы в адреса. Обёрнутый нативный токен берётся из данных сети
-// (u.wrapped), а не пишется строкой "WETH": у сети на BNB обёрнутый натив - WBNB.
-// Возвращает null и причину, если объявленный маршрут собрать нельзя (шаг назван токеном, которого в
-// этой сети нет) - это НЕ "маршрута нет", а ошибка в данных, и называть её надо иначе.
+// THE PATH FROM THE DECLARED ROUTE (DEX_ROUTES in the registry). There is NO choice here: a person declared the
+// steps with their fees, and we only map symbols to addresses. The wrapped native comes from the network data
+// (u.wrapped), not written as the string "WETH": a BNB network's wrapped native is WBNB.
+// Returns null and a cause if the declared route cannot be assembled (a step names a token this network does not
+// have) - that is NOT "no route" but a data error, and it must be named differently.
 export function declaredRoutePath({ token, tokens = [], wrapped, route }) {
   if (!token || !route || !Array.isArray(route.steps) || !route.steps.length) return null;
   const bySym = new Map((tokens || []).map((t) => [String(t.symbol).toUpperCase(), t]));
@@ -103,8 +102,8 @@ export function declaredRoutePath({ token, tokens = [], wrapped, route }) {
   return { tokens: addresses, symbols, fees, pools };
 }
 
-// Путь одной строкой с комиссиями ступеней: "USDe → USDC 0.01% → WETH 0.05%". Одна и та же запись в
-// интерфейсе и в отчёте - разойдясь, они начнут объяснять человеку одно, а оператору другое.
+// The path as one string with step fees: "USDe → USDC 0.01% → WETH 0.05%". The same record in the interface and
+// in the report - once they diverge they explain one thing to the person and another to the operator.
 export function routeLabel(route) {
   if (!route || !route.symbols) return "";
   let s = route.symbols[0];
@@ -112,13 +111,13 @@ export function routeLabel(route) {
   return s;
 }
 
-// Разбор пути на шаги: [{from, to, fee, feeLabel}] - для пошаговой строки в интерфейсе и в отчёте.
+// Split the path into steps: [{from, to, fee, feeLabel}] - for the step-by-step line in the interface and report.
 export function routeSteps(route) {
   if (!route || !route.symbols) return [];
   return route.fees.map((fee, i) => ({ from: route.symbols[i], to: route.symbols[i + 1], fee, feeLabel: feeTierLabel(fee) }));
 }
 
-const CACHE_MS = 20_000; // котировка живёт 20 с: дольше держать её нельзя (цена в пуле движется), чаще спрашивать незачем
+const CACHE_MS = 20_000; // a quote lives 20 s: holding it longer is unsafe (the pool price moves), asking more often is needless
 
 const cache = new Map();
 
@@ -135,8 +134,8 @@ export function resetDexCache() {
   cache.clear();
 }
 
-// Один eth_call в сеть сети из реестра. Никогда не бросает: молчание узла - это состояние интерфейса,
-// а не падение экрана (так же сделано в evm/prices.js).
+// One eth_call to the network's node from the registry. Never throws: node silence is a UI state, not a screen
+// crash (the same as in evm/prices.js).
 async function rpc(chain, method, params = [], { timeoutMs = 15_000 } = {}) {
   if (!chain || !chain.rpcUrl) return { ok: false, why: "network has no RPC endpoint" };
   const ctl = typeof AbortController === "function" ? new AbortController() : null;
@@ -160,14 +159,14 @@ async function rpc(chain, method, params = [], { timeoutMs = 15_000 } = {}) {
   }
 }
 
-// --- кодирование/декодирование ABI без библиотек (в проекте ноль зависимостей в app/) ---------------
+// --- ABI encode/decode without libraries (the project has zero dependencies in app/) ----------------------
 const hexBody = (s) => String(s || "").replace(/^0x/, "");
 const word = (v) => hexBody(v).toLowerCase().padStart(64, "0");
-// АДРЕС - ЭТО ЦЕЛОЕ СЛОВО ABI (24 нуля и 20 байт адреса), а не только 20 байт. Здесь была ошибка ровно
-// наоборот от той, что кажется очевидной: сначала адрес дополнялся нулями до слова, а потом у слова
-// срезались первые 24 знака - то есть дополнение выбрасывалось, и в calldata уходили аргументы,
-// сдвинутые на 12 байт. Вызов на этом откатывался ("execution reverted"), и выглядело это как "в пуле
-// нет ликвидности", хотя пул отвечал - врал наш кодировщик (поймано сверкой с рабочим вызовом).
+// AN ADDRESS IS A WHOLE ABI WORD (24 zeros and 20 address bytes), not just 20 bytes. The bug here was exactly the
+// opposite of the obvious one: the address was first padded with zeros to a word, and then the first 24 characters
+// of the word were cut - i.e. the padding was thrown away and calldata carried arguments shifted by 12 bytes. The
+// call reverted ("execution reverted") and it looked like "no liquidity in the pool" although the pool answered -
+// our encoder lied (caught by comparing against a working call).
 const addrWord = (a) => word(a);
 const uintWord = (v) => {
   let h = "";
@@ -198,16 +197,16 @@ export function encodeGetPool({ tokenA, tokenB, fee }) {
   return DEX_METHOD.getPool.hex + addrWord(tokenA) + addrWord(tokenB) + uintWord(fee);
 }
 
-// ОБРАТНАЯ ЗАДАЧА ПО ОДНОМУ ПУЛУ: сколько надо отдать, чтобы получить РОВНО amountOutWei. Раскладка та же,
-// что у одиночной формы на вход (статическая структура идёт ВНУТРИ, без слова смещения): адрес, адрес,
-// сумма, комиссия, предел цены. Подтверждено вызовом, см. DEX_METHOD.quoteExactOutputSingle.
+// THE INVERSE FOR ONE POOL: how much you must give to get EXACTLY amountOutWei. The layout is the same as the
+// single input shape (the static struct goes INSIDE, with no offset word): address, address, amount, fee, price
+// limit. Confirmed by a call, see DEX_METHOD.quoteExactOutputSingle.
 export function encodeQuoteExactOutputSingle({ tokenIn, tokenOut, amountOutWei, fee, sqrtPriceLimitX96 = 0 }) {
   return DEX_METHOD.quoteExactOutputSingle.hex +
     addrWord(tokenIn) + addrWord(tokenOut) + uintWord(amountOutWei) + uintWord(fee) + uintWord(sqrtPriceLimitX96);
 }
 
-// ЛИБО СКОЛЬКО ВЫЙДЕТ, ЛИБО ПОЧЕМУ НЕТ - так же, как у формы на вход. Здесь ЭТО НЕ ПРОГНОЗ, а ответ на
-// вопрос "хватает ли пула, чтобы получить ровно столько": отказ и есть "не хватает".
+// EITHER HOW MUCH COMES OUT, OR WHY NOT - same as the input shape. Here this is NOT a forecast but the answer to
+// "does the pool have enough to give exactly this much": the refusal IS "not enough".
 export async function quoteExactOutSingle(chain, { tokenIn, tokenOut, amountOutWei, fee }, opts = {}) {
   const u = chain && chain.uniswap;
   if (!u || !u.quoter) return { ok: false, why: "no verified QuoterV2 for this network" };
@@ -224,12 +223,12 @@ export async function quoteExactOutSingle(chain, { tokenIn, tokenOut, amountOutW
   };
 }
 
-// ОБРАТНАЯ ЗАДАЧА ПО ВСЕМУ ПУТИ: сколько надо отдать, чтобы получить РОВНО amountOutWei.
-// ПУТЬ ЗДЕСЬ ИДЁТ В ОБРАТНУЮ СТОРОНУ - от получаемого токена к оплачиваемому, и комиссии в том же
-// обратном порядке. Это не наше соглашение, а требование контракта: на прямом пути вызов отказывает
-// ("Unexpected error"), на обратном отвечает числом. Измерено на обеих сетях, см. DEX_METHOD.
-// ПРЕДПОЧТЕНИЕ ЭТОЙ ФОРМЫ: при ней минимум на выходе не "примерно равен" требуемой сумме, а равен ей
-// точно, и вопроса "а что делать с разницей" не возникает вовсе (док 45).
+// THE INVERSE OVER THE WHOLE PATH: how much you must give to get EXACTLY amountOutWei.
+// THE PATH GOES IN REVERSE HERE - from the received token to the paid one, with fees in the same reverse order.
+// This is not our convention but the contract's requirement: a forward path fails ("Unexpected error"), a reverse
+// one answers with a number. Measured on both networks, see DEX_METHOD.
+// THE PREFERENCE FOR THIS SHAPE: with it the output minimum is not "roughly equal" to the required amount but
+// exactly it, and the question "what to do with the difference" does not arise at all.
 export async function quoteExactOutPath(chain, { route, amountOutWei }, opts = {}) {
   const u = chain && chain.uniswap;
   if (!u || !u.quoter) return { ok: false, why: "no verified QuoterV2 for this network" };
@@ -237,12 +236,12 @@ export async function quoteExactOutPath(chain, { route, amountOutWei }, opts = {
   const tokens = route.tokens.slice().reverse();
   const fees = (route.fees || []).slice().reverse();
   const path = encodePath({ tokens, fees });
-  // Динамический аргумент (bytes) идёт со словом смещения: 0x40, затем сумма точного выхода, затем сам путь.
+  // A dynamic argument (bytes) goes with an offset word: 0x40, then the exact output amount, then the path itself.
   const data = DEX_METHOD.quoteExactOutput.hex + uintWord(0x40) + uintWord(amountOutWei) + uintWord(path.bytes) +
     path.packed.padEnd(Math.ceil(path.packed.length / 64) * 64, "0");
   const res = await rpc(chain, "eth_call", [{ to: u.quoter, data }, "latest"], opts);
   if (!res.ok) return { ok: false, why: res.why };
-  const out = decodeQuoteExactInput(res.result); // форма ответа та же: сумма, массивы, газ
+  const out = decodeQuoteExactInput(res.result); // the answer shape is the same: amount, arrays, gas
   if (!out || out.amountOutWei <= 0n) return { ok: false, why: "pool cannot serve exactly this output" };
   return {
     ok: true,
@@ -253,10 +252,10 @@ export async function quoteExactOutPath(chain, { route, amountOutWei }, opts = {
   };
 }
 
-// ПУТЬ ДЛЯ МНОГОШАГОВОЙ КОТИРОВКИ. Путь в Uniswap v3 - это УПАКОВАННАЯ последовательность
-// "адрес(20) + комиссия(3)" с завершающим адресом: token0|fee0|token1|fee1|token2. Никаких слов ABI
-// внутри пути нет: 43 байта на одну ногу, 66 на две. Проверено числом: одноступенчатый путь через
-// quoteExactInput вернул ровно тот же amountOut, что и quoteExactInputSingle по той же ступени.
+// THE PATH FOR A MULTI-STEP QUOTE. A Uniswap v3 path is a PACKED sequence "address(20) + fee(3)" with a trailing
+// address: token0|fee0|token1|fee1|token2. There are no ABI words inside the path: 43 bytes per leg, 66 for two.
+// Confirmed by a number: a single-step path through quoteExactInput returned exactly the same amountOut as
+// quoteExactInputSingle on the same step.
 export function encodePath({ tokens, fees }) {
   const parts = [];
   for (let i = 0; i < tokens.length; i++) {
@@ -267,10 +266,10 @@ export function encodePath({ tokens, fees }) {
   return { packed, bytes: packed.length / 2 };
 }
 
-// ВЫЗОВ quoteExactInput(bytes path, uint256 amountIn) - ОДИН eth_call на ВЕСЬ маршрут. Собран по
-// спецификации ABI, потому что здесь аргумент динамический: слово смещения (0x40), затем amountIn,
-// затем длина пути и сам путь, добитый до границы слова. ЗДЕСЬ, В ОТЛИЧИЕ ОТ ОДИНОЧНОЙ ФОРМЫ, СМЕЩЕНИЕ
-// ДЕЙСТВИТЕЛЬНО НУЖНО - одиночная форма принимает статичную структуру и идёт словами подряд.
+// THE CALL quoteExactInput(bytes path, uint256 amountIn) - ONE eth_call for the WHOLE route. Built to the ABI
+// spec because the argument is dynamic here: an offset word (0x40), then amountIn, then the path length and the
+// path itself, padded to a word boundary. HERE, UNLIKE THE SINGLE SHAPE, THE OFFSET IS REALLY NEEDED - the single
+// shape takes a static struct and goes as consecutive words.
 export function encodeQuoteExactInput({ tokens, fees, amountInWei }) {
   const { packed, bytes } = encodePath({ tokens, fees });
   const padded = packed.padEnd(Math.ceil(bytes / 32) * 64, "0");
@@ -279,11 +278,11 @@ export function encodeQuoteExactInput({ tokens, fees, amountInWei }) {
 const wordToAddress = (w) => (w === undefined || w === null ? null : "0x" + w.toString(16).padStart(40, "0"));
 const ZERO_ADDR = "0x" + "0".repeat(40);
 
-// Ступень комиссии в процентах: 500 -> "0.05%". Это ЕДИНСТВЕННАЯ величина, которая раньше бралась из
-// мока, и теперь она считается из самой ступени, а не берётся константой.
-// Арифметика: fee измеряется в сотых долях базисной точки, 1 000 000 = 100%. Значит проценты = fee/10 000,
-// то есть 500 -> 0.05%. Здесь сначала стояло ЕЩЁ деление на 100, и ступень 500 подписывалась как
-// "0.0005%" - то есть комиссия занижалась в сто раз (поймано прогоном, а не на глаз).
+// The step fee in percent: 500 -> "0.05%". This is the ONLY value that used to come from the mock, and now it is
+// computed from the step itself rather than taken as a constant.
+// Arithmetic: fee is measured in hundredths of a basis point, 1,000,000 = 100%. So percent = fee/10,000, i.e.
+// 500 -> 0.05%. It first had ANOTHER division by 100 here, and step 500 was labelled "0.0005%" - the fee was
+// understated a hundredfold (caught by a run, not by eye).
 export function feeTierPct(fee) {
   const n = Number(fee);
   if (!Number.isFinite(n)) return null;
@@ -296,10 +295,10 @@ export function feeTierLabel(fee) {
 }
 
 // ---------------------------------------------------------------------------
-// Чтения
+// Reads
 // ---------------------------------------------------------------------------
 
-// Адрес пула у фабрики. null - пула нет (это ОТВЕТ, а не ошибка: значит менять не на что).
+// The pool address at the factory. null - no pool (that is an ANSWER, not an error: nothing to change it into).
 export async function poolAddress(chain, { tokenIn, tokenOut, fee }, opts = {}) {
   const u = chain && chain.uniswap;
   if (!u || !u.factory) return { ok: false, why: "no verified Uniswap factory for this network" };
@@ -311,9 +310,9 @@ export async function poolAddress(chain, { tokenIn, tokenOut, fee }, opts = {})
   return { ok: true, pool };
 }
 
-// Состояние пула: активная ликвидность и запасы обеих сторон. Нужно для ЧЕСТНОГО ответа "ликвидности
-// нет": котировка пустого пула отвечает нулём, и без этого чтения мы не отличим "пула нет" от "пул есть,
-// но пустой". Читается только в диагностическом пути (когда котировки нет или она неправдоподобна).
+// Pool state: active liquidity and both-side reserves. Needed for an HONEST "no liquidity" answer: an empty
+// pool quotes zero, and without this read we cannot tell "no pool" from "a pool exists but is empty". Read only
+// on the diagnostic path (when there is no quote or it is implausible).
 export async function poolState(chain, pool, { tokenIn, tokenOut }, opts = {}) {
   if (!pool) return null;
   const [liq, balIn, balOut] = await Promise.all([
@@ -329,7 +328,7 @@ export async function poolState(chain, pool, { tokenIn, tokenOut }, opts = {}) {
   };
 }
 
-// ОДНА КОТИРОВКА ОДНОЙ СТУПЕНИ. Откат котировки - это НАЗВАННЫЙ отказ, а не исключение.
+// ONE QUOTE OF ONE STEP. A reverted quote is a NAMED refusal, not an exception.
 export async function quoteTier(chain, { tokenIn, tokenOut, amountInWei, fee }, opts = {}) {
   const u = chain && chain.uniswap;
   if (!u || !u.quoter) return { fee, ok: false, why: "no verified QuoterV2 for this network" };
@@ -350,10 +349,10 @@ export async function quoteTier(chain, { tokenIn, tokenOut, amountInWei, fee },
   };
 }
 
-// Разбор ответа quoteExactInput. Ответ ДРУГОЙ, чем у одиночной формы: (uint256 amountOut,
-// uint160[] sqrtPriceX96AfterList, uint32[] initializedTicksCrossedList, uint256 gasEstimate) - то есть
-// на каждый шаг пути по элементу в двух массивах. Смещения читаются из самого ответа, а не
-// предполагаются: длина массивов равна числу ног пути, и это можно СВЕРИТЬ, а не поверить.
+// Parsing the quoteExactInput answer. The answer DIFFERS from the single shape: (uint256 amountOut,
+// uint160[] sqrtPriceX96AfterList, uint32[] initializedTicksCrossedList, uint256 gasEstimate) - i.e. one element
+// per path step in two of the arrays. Offsets are read from the answer itself, not assumed: the array lengths
+// equal the number of path legs, and that can be CHECKED, not trusted.
 export function decodeQuoteExactInput(hex) {
   const words = decodeWords(hex);
   if (words.length < 4) return null;
@@ -373,8 +372,8 @@ export function decodeQuoteExactInput(hex) {
   };
 }
 
-// КОТИРОВКА ВСЕГО ПУТИ ОДНИМ ВЫЗОВОМ. Здесь НЕТ цепочки "котировка шага 1, потом шаг 2 от её выхода":
-// такая цепочка считает оба шага по одному и тому же состоянию пулов и даёт оптимистично неверное число.
+// A WHOLE-PATH QUOTE IN ONE CALL. There is NO chain of "step 1 quote, then step 2 from its output": such a chain
+// prices both steps against the same pool state and gives a optimistically wrong number.
 export async function quotePath(chain, { route, amountInWei }, opts = {}) {
   const u = chain && chain.uniswap;
   if (!u || !u.quoter) return { ...route, ok: false, why: "no verified QuoterV2 for this network" };
@@ -392,42 +391,42 @@ export async function quotePath(chain, { route, amountInWei }, opts = {}) {
     sqrtPriceX96After: out.sqrtPriceX96After,
     initializedTicksCrossed: out.initializedTicksCrossed,
     hops: route.fees.length,
-    // ЧИСЛО ШАГОВ ОТВЕТА СВЕРЯЕТСЯ С ЧИСЛОМ НОГ ПУТИ: если контракт вернул не по элементу на шаг, то это
-    // не тот ответ, который мы умеем читать, и лучше сказать это словами, чем показать число наугад.
+    // THE ANSWER STEP COUNT IS CHECKED AGAINST THE PATH LEG COUNT: if the contract returned not one element per
+    // step, this is not an answer we can read, and it is better to say so in words than to show a number at random.
     shapeOk: out.sqrtPriceX96After.length === route.fees.length,
   };
 }
 
-// ПОДПИСЬ ОБЪЯВЛЕННОГО МАРШРУТА: одна строка, по которой видно, ИЗ ЧЕГО он собран. Нужна для ключа
-// кеша: если объявление поменяли (другая ступень, другой хаб), старый ответ на новый вопрос не годится.
+// THE DECLARED-ROUTE SIGNATURE: one string showing WHAT it is assembled from. Needed for the cache key: if the
+// declaration changed (another fee, another hub), the old answer does not fit the new question.
 export function routeSignature(route) {
   if (!route || !Array.isArray(route.steps) || !route.steps.length) return route && route.unwrap ? "unwrap" : "none";
   return route.steps.map((s) => String(s.to).toUpperCase() + ":" + Number(s.fee) + (s.pool ? ":" + String(s.pool).toLowerCase() : "")).join("+");
 }
 
 // ---------------------------------------------------------------------------
-// ПРОВЕРКА ЦЕНЫ: СДЕЛКА НЕВЕРНАЯ ИЛИ НЕТ.
+// THE PRICE CHECK: IS THE DEAL WRONG OR NOT.
 //
-// Это НЕ оценка ликвидности - её, как и раньше, делает человек, и приговоров о глубине пулов здесь нет.
-// Это проверка того же рода, что покрытие суммы: если цена не та, сделка не сойдётся, и она не должна
-// начинаться. Признак неверной цены берётся ДВУМЯ способами, и ни одному из них не нужен фид на каждый
-// токен (иначе USDe/USDS/PyUSD без своего фида сломали бы проверку вовсе):
+// This is NOT liquidity scoring - that is still a person's job, and there are no verdicts about pool depth here.
+// It is a check of the same kind as amount coverage: if the price is wrong the deal will not settle and must not
+// start. A sign of a wrong price is taken TWO ways, and neither needs a feed per token (else USDe/USDS/PyUSD
+// without their own feed would break the check entirely):
 //
-//   1) ПОСЛЕДНИЙ ШАГ В НАТИВ. Из котировки выводится НЕЯВНАЯ цена натива в долларах (сколько входит в
-//      долларах / сколько натива выходит) и сравнивается с эталоном цены натива - тем самым Chainlink,
-//      который страница уже читает (evm/prices.js). Это работает для любого входа: у стейбла цена в
-//      долларах известна из реестра, у остальных маршрут всё равно заканчивается нативом;
-//   2) ШАГ МЕЖДУ ДВУМЯ СТЕЙБЛАМИ (USDe→USDC, USDS→USDC, PyUSD→USDC): цена обязана быть около 1:1, и это
-//      проверяется САМОЙ КОТИРОВКОЙ, без оракула вообще. Абсурд вида "100 USDe дают 0.5 USDC" ловится
-//      именно здесь.
+//   1) THE LAST STEP INTO NATIVE. The implied dollar price of native is derived from the quote (dollars in /
+//      native out) and compared against the native price reference - the same Chainlink the page already reads
+//      (evm/prices.js). This works for any input: a stable's dollar price is known from the registry, and the
+//      rest end at native anyway;
+//   2) A STEP BETWEEN TWO STABLES (USDe→USDC, USDS→USDC, PyUSD→USDC): the price must be near 1:1, and that is
+//      checked BY THE QUOTE ITSELF, with no oracle at all. An absurdity like "100 USDe give 0.5 USDC" is caught
+//      exactly here.
 //
-// ПОРОГИ ПРИХОДЯТ ДАННЫМИ (реестр: DEX_PRICE_GATE), а не лежат здесь числами: менять их - правка данных.
-// ПРИЗНАК СЕТИ tolerated (реестр: dexPriceGate === "tolerated") ОТМЕНЯЕТ БЛОКИРОВКУ, НО НЕ ФАКТ: цена
-// остаётся негодной и названа таковой (bad), а интерфейс обязан её показать. Так тестнет не встаёт на
-// цене, которую мы не выбирали, и при этом не притворяется, что цена рыночная.
+// THE THRESHOLDS COME IN AS DATA (the registry: DEX_PRICE_GATE), not as numbers here: changing them is a data edit.
+// A NETWORK MARK tolerated (registry: dexPriceGate === "tolerated") CANCELS THE BLOCK BUT NOT THE FACT: the price
+// stays wrong and is named so (bad), and the interface must show it. Thus a testnet does not stall on a price we
+// did not choose, and does not pretend the price is market.
 //
-// Функция ЧИСТАЯ: ни одного вызова в сеть, только числа ноги и эталон. Поэтому её можно прогнать на
-// любых числах без сети - чем и доказывается, что защита краснеет (tools/check-dex-gate.mjs).
+// The function is PURE: not one network call, only the leg numbers and the reference. So it can be run on any
+// numbers without a network - which is how the guard is proven to go red (the DEX gate check).
 // ---------------------------------------------------------------------------
 export function priceGateVerdict({
   amountInWei = null, amountOutWei = null, inDecimals = null, outDecimals = null,
@@ -437,7 +436,7 @@ export function priceGateVerdict({
   const band = gates && Number.isFinite(Number(gates.stableBandPct)) && Number(gates.stableBandPct) >= 0 ? Number(gates.stableBandPct) : null;
   const why = [];
 
-  // (1) ШАГИ МЕЖДУ СТЕЙБЛАМИ: около 1:1, без оракула.
+  // (1) STEPS BETWEEN STABLES: near 1:1, no oracle.
   const stable = (Array.isArray(stableSteps) ? stableSteps : []).map((s) => {
     const row = {
       from: s.from, to: s.to, fee: s.fee, feeLabel: feeTierLabel(s.fee),
@@ -445,8 +444,8 @@ export function priceGateVerdict({
       quoted: Boolean(s.ok), ok: false, ratio: null, deviationPct: null, why: null,
     };
     if (!s.ok) {
-      // ШАГ СТЕЙБЛ-СТЕЙБЛ НЕ ОТВЕТИЛ - И ЭТО НАЗВАНО, А НЕ ПРОПУЩЕНО: неизмеренная цена не проходит
-      // проверку, иначе "не проверили" выглядело бы как "цена в порядке".
+      // A STABLE-STABLE STEP DID NOT ANSWER - AND THAT IS NAMED, NOT SKIPPED: an unmeasured price does not pass
+      // the check, else "we did not check" would look like "the price is fine".
       row.why = "the 1:1 step could not be quoted (" + (s.why || "no answer") + ")";
       why.push(row.why);
       return row;
@@ -470,7 +469,7 @@ export function priceGateVerdict({
     return row;
   });
 
-  // (2) НЕЯВНАЯ ЦЕНА НАТИВА ПРОТИВ ЭТАЛОНА.
+  // (2) THE IMPLIED NATIVE PRICE AGAINST THE REFERENCE.
   const inUnits = Number.isFinite(Number(inDecimals)) && Number(amountInWei) > 0 ? Number(amountInWei) / 10 ** Number(inDecimals) : null;
   const outUnits = Number.isFinite(Number(outDecimals)) && Number(amountOutWei) > 0 ? Number(amountOutWei) / 10 ** Number(outDecimals) : null;
   const valueUsd = inUnits !== null && Number(tokenUsd) > 0 ? inUnits * Number(tokenUsd) : null;
@@ -481,7 +480,7 @@ export function priceGateVerdict({
   if (nativeBad) {
     why.push(`the route implies the native coin at $${impliedUsd.toFixed(2)} while the reference price is $${ref.toFixed(2)} - ${deviationPct.toFixed(1)}% apart, and the limit is ${maxDev}%: this is not the market price`);
   } else if (deviationPct === null) {
-    // НЕ ПРОВЕРЯЛИ - ЭТО НЕ "ВСЁ ХОРОШО". Причину называем ту, по которой проверить не вышло.
+    // NOT CHECKED IS NOT "ALL GOOD". We name the cause that made the check impossible.
     why.push(ref === null
       ? "the reference price of the native coin is not known, so the price cannot be checked"
       : "the price of the token being paid is not known, so the price cannot be checked");
@@ -489,14 +488,14 @@ export function priceGateVerdict({
     why.push("the price limit is not declared for this route, so the price cannot be checked");
   }
 
-  // ПРОВЕРКА СОСТОЯЛАСЬ - значит НАТИВНАЯ ЧАСТЬ состоялась (эталон есть, лимит объявлен). Шаги
-  // стейбл-стейбл не входят сюда намеренно: неизмеренный или вышедший из полосы шаг - это уже bad
-  // (см. выше), а не "не проверено".
+  // THE CHECK TOOK PLACE - so the NATIVE PART did (a reference exists, a limit is declared). Stable-stable steps
+  // do not enter here on purpose: an unmeasured or out-of-band step is already bad (see above), not "unchecked".
+  //
   const checked = deviationPct !== null && maxDev !== null;
   const bad = nativeBad || stable.some((r) => !r.ok);
-  // БЛОКИРУЕТ ЛИ: негодная цена - да (кроме сети с признаком tolerated); непроверенная цена - тоже да,
-  // и по той же логике, по которой блокирует неизвестная требуемая сумма: "не проверили" нельзя
-  // показывать как "проверили и всё хорошо". На тестнете не блокирует ни то, ни другое.
+  // DOES IT BLOCK: a wrong price - yes (except a network marked tolerated); an unchecked price - also yes, by the
+  // same logic that blocks an unknown required amount: "we did not check" must not be shown as "checked and fine".
+  // On a testnet neither blocks.
   const blocks = tolerated ? false : (bad || !checked);
   return {
     checked, bad, tolerated: Boolean(tolerated), blocks,
@@ -509,68 +508,68 @@ export function priceGateVerdict({
 }
 
 // ---------------------------------------------------------------------------
-// ПОЧЕМУ МАРШРУТА НЕТ - СЛОВАМИ, И ЭТИ СЛОВА - ИЗ ДАННЫХ. Причина лежит в самом объявлении (route.why):
-// её писал человек, объявляя маршрут, и она подтверждена замером (tools/check-uniswap-quote.mjs - раздел
-// "объявленные маршруты"). Одна и та же формулировка в интерфейсе и в отчёте: разойдясь, они начнут
-// объяснять человеку одно, а оператору другое.
-// Маршрута в реестре НЕТ ВОВСЕ (токен есть, объявления нет) - это ТОЖЕ честный ответ, а не "не нашли":
-// значит, обход не объявляли, и подпись по нему не начинается.
+// WHY THERE IS NO ROUTE - IN WORDS, AND THOSE WORDS COME FROM THE DATA. The cause lies in the declaration itself
+// (route.why): it was written by the person declaring the route, and it is confirmed by measurement. The same
+// wording in the interface and in the report: once they diverge they explain one thing to the person and another
+// to the operator.
+// A route is NOT in the registry at all (the token is there, no declaration) - that is ALSO an honest answer, not
+// "not found": the detour was not declared, and signing on it does not start.
 export function noRouteWords({ paySymbol, wrappedSymbol, chainName, route = null }) {
-  // ТЕМПЛЕЙТ, А НЕ СКЛЕЙКА СТРОК: текст тот же, но подстроки `from "` в исходнике больше нет (склейка
-  // случайно читалась проверкой голых импортов пакета SDK как спецификатор). Правило то же, слова те же.
+  // A TEMPLATE, NOT STRING GLUING: the text is the same, but the substring `from "` no longer appears in the source
+  // (the gluing was accidentally read by the SDK bare-import check as a specifier). Same rule, same words.
   const head = `no route from ${paySymbol} to ${wrappedSymbol} on ${chainName}`;
   const why = route && route.why ? String(route.why) : null;
-  // В ВИДИМОМ ТЕКСТЕ НЕТ НИ "registry", НИ "DEX_ROUTES": это имена НАШЕГО устройства, а не то, что
-  // человеку нужно понять. Смысл тот же: маршрут не ищут перебором, его объявляет человек.
+  // THE VISIBLE TEXT HAS NEITHER "registry" NOR "DEX_ROUTES": those are names of OUR machinery, not what a person
+  // needs to understand. The meaning is the same: a route is not found by brute force, it is declared by a person.
   return why ? head + ": " + why : head + ": no route for " + paySymbol + " is declared - routes are declared by hand, not searched";
 }
 
 
 // ---------------------------------------------------------------------------
-// ВЕРДИКТ НОГИ: МОЖНО ЛИ ПО НЕЙ ПОДПИСЫВАТЬ (док 45). Две защиты ОДНОЙ СЕМЬИ, и обе БЛОКИРУЮТ подпись:
-//   * ПОКРЫТИЕ СУММЫ - маршрут обязан дать не меньше, чем требует ордер (сумма эскроу);
-//   * ЦЕНА - цена маршрута обязана быть рыночной (priceGateVerdict): неверная цена означает то же самое,
-//     что и недостача, - сделка не сойдётся.
-// Отличается от наблюдений именно этим: "не покрывает" и "цена не та" - такие же ФАКТЫ, как "пула нет",
-// и они обязаны останавливать человека ДО подписи, а не показываться строкой в разбивке цены. Отсюда
-// правило: функция возвращает либо { blocked: false }, либо { blocked: true, kind, reason } - и
-// вызывающий ОБЯЗАН считаться с blocked.
-// Приговоров о ликвидности здесь нет: "не покрывает на 0.4%" - это число, а не оценка качества пула.
+// THE LEG VERDICT: MAY ONE SIGN ON IT. Two guards OF ONE FAMILY, both BLOCKING signing:
+//   * AMOUNT COVERAGE - the route must give at least what the order requires (the escrow amount);
+//   * PRICE - the route price must be market (priceGateVerdict): a wrong price means the same as a shortfall -
+//     the deal will not settle.
+// It differs from observations exactly in this: "does not cover" and "the price is wrong" are FACTS just like "no
+// pool", and they must stop the person BEFORE signing, not be shown as a line in the price breakdown. Hence the
+// rule: the function returns either { blocked: false } or { blocked: true, kind, reason } - and the caller MUST
+// honour blocked.
+// There are no liquidity verdicts here: "covers 0.4% short" is a number, not a judgement of pool quality.
+//
+//   kind: "unquoted"            - there is no quote yet (nothing to ask, no waiting allowed: block)
+//         "no-route"            - no route: causes lie in leg.why (the registry declaration + the chain refusal)
+//         "price-unchecked"     - the price cannot be checked (no native price reference): block - "we did not
+//                                 check" must not be shown as "checked and fine"
+//         "bad-price"           - the price is not market: numbers in verdict.price (blocks on a live network)
+//         "unchecked"           - the required amount is unknown (no XMR/native rate to compute it)
+//         "short"               - a route exists but the output is LESS than required: here is by how much
+//         "bad-price-tolerated" - the price is wrong but the network is marked dexPriceGate: signing is NOT
+//                                 blocked, and the wrongness is NAMED (a testnet: testing the flow, not the market)
+//         "covers"              - all agrees: signing allowed (the page's other guards stay in force)
 //
-//   kind: "unquoted"            - котировки ещё нет вовсе (спрашивать нечего, ждать нельзя: блокируем)
-//         "no-route"            - маршрута нет: причины лежат в leg.why (объявление реестра + отказ цепи)
-//         "price-unchecked"     - цену проверить НЕЧЕМ (нет эталона цены натива): блокируем - "не
-//                                 проверили" нельзя показывать как "проверили и всё хорошо"
-//         "bad-price"           - цена не рыночная: числа в verdict.price (блокирует на боевой сети)
-//         "unchecked"           - требуемая сумма неизвестна (нет курса XMR/<натив>, чтобы её посчитать)
-//         "short"               - маршрут есть, но выход МЕНЬШЕ требуемой суммы: вот насколько
-//         "bad-price-tolerated" - цена негодная, но у сети признак dexPriceGate: подпись НЕ блокируется,
-//                                 а негодность НАЗВАНА (тестнет: проверяем поток, а не рынок)
-//         "covers"              - всё сходится: подпись разрешена (прочие защиты страницы в силе)
+// COVERAGE NUMBERS ARE RETURNED WHENEVER THEY ARE KNOWN (needWei/getsWei/shortfallWei/covers) - even when signing
+// is locked by price: the person must see WHAT the verdict came from, not only the word "blocked".
 //
-// ЧИСЛА ПОКРЫТИЯ ВОЗВРАЩАЮТСЯ ВСЕГДА, КОГДА ОНИ ИЗВЕСТНЫ (needWei/getsWei/shortfallWei/covers) - даже
-// когда подпись заперта ценой: человеку должно быть видно, ИЗ ЧЕГО взялся вердикт, а не только слово
-// "заблокировано".
 //
-// МИНИМУМ НА ВЫХОДЕ БУДУЩЕГО СВОПА БЕРЁТСЯ ОТСЮДА ЖЕ - из требуемой суммы эскроу, а не "на глазок"
-// (docs 45). Поэтому недостача невозможна по построению, а излишек остаётся пользователю: НИКАКОЙ
-// автоматической конвертации остатка в коде нет и не должно появиться - фондирование вносит ровно сумму
-// ордера, всё прочее остаётся у человека.
+// THE OUTPUT MINIMUM OF THE FUTURE SWAP COMES FROM HERE TOO - from the required escrow amount, not "by eye". So a
+// shortfall is impossible by construction and any surplus stays with the user: there is NO automatic conversion of
+// the remainder in the code and there must not be - funding deposits exactly the order amount, everything else
+// stays with the person.
 export function dexLegVerdict(leg, requiredOutWei = null) {
   if (leg && leg.unwrap) return { blocked: false, kind: "unwrap", reason: null, price: null };
   if (!leg) return { blocked: true, kind: "unquoted", reason: "the swap leg has not been quoted yet", price: null };
   if (!leg.ok) return { blocked: true, kind: "no-route", reason: leg.why || "no route", price: null };
-  // ЦЕНА ПРИХОДИТ ИЗ САМОЙ НОГИ: её считает quoteDexOut тем же ответом цепи, что и выход. Нога без
-  // проверки цены (её собрал кто-то руками) эту защиту не подтверждает - проверить её здесь нечем,
-  // поэтому и вердикта о цене у такой ноги нет.
+  // THE PRICE COMES FROM THE LEG ITSELF: quoteDexOut computes it from the same chain answer as the output. A leg
+  // without a price check (someone assembled it by hand) does not confirm this guard - there is nothing here to
+  // check it with, so such a leg has no price verdict either.
   const price = leg.price || null;
   const priceBad = Boolean(price && price.bad);
   const priceUnchecked = Boolean(price && price.checked === false);
   const priceBlocks = Boolean(price && price.blocks && (priceBad || priceUnchecked));
-  // ТРЕБУЕМАЯ СУММА ПРИХОДИТ СЮДА АРГУМЕНТОМ, А НЕ БЕРЁТСЯ ИЗ САМОЙ НОГИ: котировка живёт в кеше 20 с, а
-  // размер ордера человек может поменять в любой момент. Возьми мы требуемую сумму из кешированного
-  // ответа - вердикт отставал бы от того, что человек видит в форме, и это ровно тот случай, когда
-  // защита "есть, но не срабатывает".
+  // THE REQUIRED AMOUNT COMES IN AS AN ARGUMENT, NOT TAKEN FROM THE LEG ITSELF: the quote lives in a 20 s cache,
+  // while the person can change the order size at any moment. If we took the required amount from the cached
+  // answer, the verdict would lag behind what the person sees in the form - exactly the case where a guard "exists
+  // but does not fire".
   const need = requiredOutWei !== null && requiredOutWei !== undefined && Number(requiredOutWei) > 0 ? BigInt(requiredOutWei) : null;
   const gets = BigInt(leg.amountOutWei);
   const coverage = need === null ? null : {
@@ -584,9 +583,9 @@ export function dexLegVerdict(leg, requiredOutWei = null) {
     decimals: leg.wrapped ? leg.wrapped.decimals : null,
     wrappedSymbol: leg.wrapped ? leg.wrapped.symbol : null,
   };
-  // ПОРЯДОК ПРИЧИН: сначала "подписывать нельзя вообще" (маршрута нет - выше; цена непроверена; цена не
-  // та), потом "суммы не хватает", потом "всё сошлось". Он важен: при неверной цене вопрос о покрытии
-  // числам уже не верится.
+  // ORDER OF CAUSES: first "signing is impossible at all" (no route - above; price unchecked; price wrong), then
+  // "the amount is short", then "all agrees". It matters: with a wrong price, the coverage numbers can no longer
+  // be believed.
   if (priceBlocks) return { blocked: true, ...base, kind: priceBad ? "bad-price" : "price-unchecked", reason: price.why };
   if (coverage === null) {
     return { blocked: true, ...base, kind: "unchecked", reason: "the required escrow amount is not known yet, so coverage cannot be checked" };
@@ -597,27 +596,27 @@ export function dexLegVerdict(leg, requiredOutWei = null) {
 }
 
 // ---------------------------------------------------------------------------
-// Главный вход для страницы: сколько натива даст оплата этим токеном ПО ОБЪЯВЛЕННОМУ МАРШРУТУ.
+// The main entry for the page: how much native the payment with this token gives ALONG THE DECLARED ROUTE.
 //
-//   token              - токен оплаты из реестра (адрес, decimals и цена)
-//   amountWei          - сумма оплаты в его минимальных единицах
-//   requiredOutWei     - СКОЛЬКО НАТИВА ТРЕБУЕТ ОРДЕР (сумма эскроу на этот размер входа). Это НЕ
-//                        наблюдение, а условие выполнимости: по нему считается вердикт "покрывает /
-//                        не покрывает", и "не покрывает" блокирует подпись (см. dexLegVerdict).
-//   route              - ОБЪЯВЛЕННЫЙ маршрут из реестра (DEX_ROUTES[chainId][symbol]). Выбора здесь нет
-//                        и быть не должно: что объявлено - то и котируется, ОДНИМ вызовом. Объявления
-//                        нет или в нём пусто - это честное "маршрута нет" (слова - из route.why), и
-//                        подпись по нему не начинается.
-//   tokens             - токены этой сети: по символу из шага берутся адрес и decimals
-//   referenceNativeUsd - ЭТАЛОН цены натива в долларах (Chainlink у страницы). Без него проверка цены
-//                        не состоится, и это не повод её пропустить (см. priceGateVerdict).
-//   gates              - пороги проверки цены из реестра (DEX_PRICE_GATE)
+//   token              - the payment token from the registry (address, decimals and price)
+//   amountWei          - the payment amount in its smallest units
+//   requiredOutWei     - HOW MUCH NATIVE THE ORDER REQUIRES (the escrow amount for this input size). This is NOT
+//                        an observation but a feasibility condition: from it the "covers / does not cover" verdict
+//                        is computed, and "does not cover" blocks signing (see dexLegVerdict).
+//   route              - the DECLARED route from the registry (DEX_ROUTES[chainId][symbol]). There is no choice
+//                        here and there must not be: what is declared is what is quoted, in ONE call. No
+//                        declaration, or an empty one - an honest "no route" (the words come from route.why), and
+//                        signing on it does not start.
+//   tokens             - this network's tokens: the address and decimals are taken by the symbol from the step
+//   referenceNativeUsd - the REFERENCE native price in dollars (the page's Chainlink). Without it the price check
+//                        cannot take place, and that is no reason to skip it (see priceGateVerdict).
+//   gates              - the price-check thresholds from the registry (DEX_PRICE_GATE)
 //
-// ХАБОВ ЗДЕСЬ БОЛЬШЕ НЕТ: обход через USDC/USDT - это тоже объявленный маршрут, а не поиск в рантайме.
+// THERE ARE NO HUBS HERE ANY MORE: a detour via USDC/USDT is also a declared route, not a runtime search.
 //
-// Возвращает ЛИБО { ok: true, ... } с числами из цепи, ЛИБО { ok: false, why } словами. Числа и
-// "почему нет" вместе не возвращаются: показать человеку и то и другое - значит предложить ему
-// догадаться, какому из двух ответов верить.
+// Returns EITHER { ok: true, ... } with numbers from the chain, OR { ok: false, why } in words. Numbers and "why
+// not" are not returned together: showing a person both means asking him to guess which of the two answers to
+// believe.
 // ---------------------------------------------------------------------------
 export async function quoteDexOut(chain, { token, amountWei, requiredOutWei = null, route = null, tokens = [], referenceNativeUsd = null, gates = null } = {}, opts = {}) {
   const u = chain && chain.uniswap;
@@ -628,29 +627,29 @@ export async function quoteDexOut(chain, { token, amountWei, requiredOutWei = nu
   const wrapped = u.wrapped;
   const chainName = (chain && chain.name) || (chain && chain.id) || "this network";
   if (String(token.address).toLowerCase() === String(wrapped.address).toLowerCase()) {
-    // Обёрнутый нативный токен меняется на натив НЕ в пуле: это withdraw у WETH9, один к одному.
+    // The wrapped native is changed to native NOT in a pool: this is a WETH9 withdraw, one to one.
     return { ok: false, why: "this is the wrapped native coin: no pool needed, it unwraps 1:1", unwrap: true };
   }
   const declared = route || null;
-  // ПРИЗНАК СЕТИ: негодная цена на тестнете не блокирует (реестр: dexPriceGate у сети). Отсутствие
-  // признака - блокирует, и это умолчание: молчаливое "сойдёт" на боевой сети недопустимо.
+  // THE NETWORK MARK: a wrong price on a testnet does not block (registry: the network's dexPriceGate). A missing
+  // mark blocks, and that is the default: a silent "it will do" on a live network is unacceptable.
   const tolerated = String((chain && chain.dexPriceGate) || "") === "tolerated";
-  // ОБЪЯВЛЕНИЕ, КОТОРЫМ ПОЛЬЗУЕМСЯ, ВОЗВРАЩАЕТСЯ В ОТВЕТЕ ЦЕЛИКОМ (со ступенями, пулами и датой замера):
-  // интерфейс и отчёт обязаны называть не только ЧТО получилось, но и ПО ЧЕМУ это объявлено.
+  // THE DECLARATION WE USE IS RETURNED WHOLE (with steps, pools and a measurement date): the interface and the
+  // report must name not only WHAT came out but WHAT it was declared from.
   const declaration = declared
     ? {
         steps: (Array.isArray(declared.steps) ? declared.steps : []).map((s) => ({ to: s.to, fee: s.fee, pool: s.pool || null, verified: s.verified || null })),
         why: declared.why || null, unwrap: Boolean(declared.unwrap),
       }
     : null;
-  // (1) МАРШРУТА НЕТ - ЭТО ОТВЕТ ИЗ ДАННЫХ, А НЕ ОШИБКА. Пустой steps значит "объявленного маршрута нет":
-  // почему его нет - в route.why, и эти слова уходят и в интерфейс, и в отчёт (одни и те же).
+  // (1) NO ROUTE IS AN ANSWER FROM THE DATA, NOT AN ERROR. Empty steps means "no declared route": why there is
+  // none is in route.why, and those words go to both the interface and the report (the same ones).
   if (!declared || !Array.isArray(declared.steps) || !declared.steps.length) {
     if (declared && declared.unwrap) return { ok: false, why: "this is the wrapped native coin: no pool needed, it unwraps 1:1", unwrap: true };
     return { ok: false, why: noRouteWords({ paySymbol: token.symbol, wrappedSymbol: wrapped.symbol, chainName, route: declared }), declared: true, declaration, steps: [] };
   }
-  // (2) ПУТЬ ИЗ ОБЪЯВЛЕННЫХ ШАГОВ. Не собрать объявленное (шаг называет токен, которого в этой сети нет) -
-  // это ошибка В ДАННЫХ, и называть её надо иначе, чем "маршрута нет": по ней видно, что правки ждёт реестр.
+  // (2) A PATH FROM THE DECLARED STEPS. Failing to assemble the declaration (a step names a token this network
+  // lacks) is a DATA error and must be named differently from "no route": it shows the registry needs an edit.
   const path = declaredRoutePath({ token, tokens, wrapped, route: declared });
   if (!path || path.error) {
     return {
@@ -665,14 +664,14 @@ export async function quoteDexOut(chain, { token, amountWei, requiredOutWei = nu
     const h = byAddr.get(String(addr).toLowerCase());
     return h && Number.isFinite(Number(h.decimals)) ? Number(h.decimals) : null;
   };
-  // (3) КЕШ НА 20 С ПО СЕТИ, ТОКЕНУ, СУММЕ И ПОДПИСИ ОБЪЯВЛЕНИЯ. Сменив объявление, мы спрашиваем ДРУГОЙ
-  // маршрут, и старый ответ на новый вопрос не годится. Требуемая сумма в ключ НЕ входит: она меняется от
-  // размера ордера, а покрытие и цена считаются ниже - каждый раз, из свежих чисел.
+  // (3) A 20 s CACHE BY NETWORK, TOKEN, AMOUNT AND DECLARATION SIGNATURE. Changing the declaration asks a
+  // DIFFERENT route, and the old answer does not fit the new question. The required amount does NOT enter the
+  // key: it changes with the order size, while coverage and price are computed below - every time, from fresh numbers.
   const key = [chain.id, token.symbol, amount.toString(), routeSignature(declared)].join("|");
   let base = cached(key);
   if (base === undefined) {
-    // ОДИН ВЫЗОВ НА ВЕСЬ ПУТЬ. Цепочки "котировка шага 1, потом шаг 2 от её выхода" здесь нет и быть не
-    // должно: такая цепочка считает оба шага по одному состоянию пулов и даёт оптимистично неверное число.
+    // ONE CALL FOR THE WHOLE PATH. There is no chain of "step 1 quote, then step 2 from its output" here and
+    // there must not be: such a chain prices both steps against one pool state and gives an optimistically wrong number.
     const quote = await quotePath(chain, { route: { tokens: path.tokens, fees: path.fees, symbols: path.symbols, via: null }, amountInWei: amount }, opts);
     if (!quote.ok) return put(key, { ok: false, why: quote.why, declared: true });
     base = { ok: true, quote };
@@ -680,10 +679,10 @@ export async function quoteDexOut(chain, { token, amountWei, requiredOutWei = nu
   }
   if (!base.ok) return { ...base, declaration };
   const q = base.quote;
-  // ПУЛЫ МАРШРУТА ЧИТАЮТСЯ ВСЕГДА, КОГДА КОТИРОВКА ЕСТЬ - по одной записи на КАЖДУЮ ногу. Это ФАКТ,
-  // который человеку нужен рядом с числом: "маршрут ответил столько-то" само по себе не говорит, много
-  // ли лежит в пулах на его пути. Запасы в wei БЕЗ decimals человеку не читаются, поэтому decimals
-  // едут рядом - подставлять 18 "по похожести" значило бы однажды показать 6-значный токен как 18-значный.
+  // ROUTE POOLS ARE READ WHENEVER A QUOTE EXISTS - one record per leg. This is a FACT the person needs next to
+  // the number: "the route answered so much" by itself does not say how much lies in the pools on his path.
+  // Reserves in wei WITHOUT decimals are unreadable to a person, so decimals ride alongside - substituting 18
+  // "by similarity" would mean one day showing a 6-decimal token as 18-decimal.
   if (base.hops === undefined) {
     const hops = [];
     for (let i = 0; i < path.fees.length; i++) {
@@ -697,24 +696,24 @@ export async function quoteDexOut(chain, { token, amountWei, requiredOutWei = nu
         step: i + 1, from: path.symbols[i], to: path.symbols[i + 1], fee, feeLabel: feeTierLabel(fee),
         decimals: [dec(from), dec(to)],
         pool,
-        // СВЕРКА ОБЪЯВЛЕННОГО АДРЕСА ПУЛА С ЦЕПЬЮ. Если фабрика отвечает другим пулом, объявление
-        // устарело: в отчёте инструмента это провал, здесь - факт рядом с числом (решает человек).
+        // CHECKING THE DECLARED POOL ADDRESS AGAINST THE CHAIN. If the factory answers another pool, the
+        // declaration is stale: in the tool's report that is a failure, here a fact next to the number (a person decides).
         declaredPool,
         poolMatchesDeclared: pool && declaredPool ? String(pool).toLowerCase() === String(declaredPool).toLowerCase() : null,
         verified: declaredStep.verified || null,
-        // СОСТОЯНИЕ ПУЛА ЗДЕСЬ БОЛЬШЕ НЕ ЧИТАЕТСЯ. Три вызова eth_call на каждую ногу (liquidity(),
-        // balanceOf(tokenIn), balanceOf(tokenOut)) собирались ради одной строки в интерфейсе - liquidity,
-        // резервы пула, - и та убрана: после ссылки на пул человек смотрит глубину и состояние в обозревателе.
-        // Сама функция poolState остаётся: её зовёт отчёт инструмента (tools/check-uniswap-quote.mjs), и там
-        // эти числа нужны оператору. Здесь же они не нужны никому, а страница спрашивает их на каждом обновлении.
+        // POOL STATE IS NO LONGER READ HERE. Three eth_call calls per leg (liquidity(), balanceOf(tokenIn),
+        // balanceOf(tokenOut)) were gathered for one line in the interface - liquidity, pool reserves - and that
+        // line is removed: after a link to the pool a person checks depth and state in the explorer. The poolState
+        // function itself stays: the tool's report calls it, and the operator needs those numbers there. Here they
+        // are needed by nobody, while the page asks for them on every refresh.
       });
     }
     base.hops = hops;
   }
   const hops = base.hops;
-  // ШАГИ МЕЖДУ ДВУМЯ СТЕЙБЛАМИ ПРОВЕРЯЮТСЯ САМОЙ КОТИРОВКОЙ (около 1:1, без оракула вовсе). Сумма шага -
-  // сумма маршрута: у объявленных маршрутов такой шаг идёт ПЕРВЫМ, поэтому для него это ровно его сумма
-  // (и это отмечено полем exact у каждой строки).
+  // STEPS BETWEEN TWO STABLES ARE CHECKED BY THE QUOTE ITSELF (near 1:1, with no oracle at all). The step amount
+  // is the route amount: in declared routes such a step comes FIRST, so for it this is exactly its amount (and
+  // that is marked by the exact field on every row).
   if (base.stableSteps === undefined) {
     const stables = (gates && Array.isArray(gates.stables) ? gates.stables : []).map((s) => String(s).toUpperCase());
     const steps = [];
@@ -731,9 +730,9 @@ export async function quoteDexOut(chain, { token, amountWei, requiredOutWei = nu
     }
     base.stableSteps = steps;
   }
-  // ПРОВЕРКА ЦЕНЫ. Считается КАЖДЫЙ РАЗ, а не кешируется вместе с котировкой: эталон цены натива
-  // подгружается отдельно и может появиться позже, чем ответ пула - ровно та же причина, по которой
-  // здесь не кешируется и вердикт покрытия.
+  // THE PRICE CHECK. Computed EVERY TIME, not cached with the quote: the native price reference is loaded
+  // separately and may appear later than the pool answer - exactly the same reason the coverage verdict is not
+  // cached here either.
   const price = priceGateVerdict({
     amountInWei: amount, amountOutWei: q.amountOutWei,
     inDecimals: token.decimals, outDecimals: wrapped.decimals,
@@ -741,19 +740,19 @@ export async function quoteDexOut(chain, { token, amountWei, requiredOutWei = nu
     referenceUsd: referenceNativeUsd,
     stableSteps: base.stableSteps, tolerated, gates,
   });
-  // ПРЕДПОЧТИТЕЛЬНАЯ ФОРМА: "получить РОВНО требуемую сумму, потратив не больше введённого" (док 45).
-  // Спрашивается тем же путём-победителем, но В ОБРАТНУЮ СТОРОНУ - контракт требует именно так. Ответ
-  // важен не только числом: он снимает вопрос о разнице сумм, потому что минимум на выходе становится
-  // равен требуемой сумме по построению. Отказ здесь - тоже ответ: значит ровно столько пул не отдаёт,
-  // и тогда остаётся обычная форма на вход с минимумом от требуемой суммы.
+  // THE PREFERRED SHAPE: "receive EXACTLY the required amount, spending no more than entered". It is asked on the
+  // same winning path but IN REVERSE - the contract requires exactly that. The answer matters not only as a
+  // number: it removes the question of a difference in amounts, because the output minimum becomes equal to the
+  // required amount by construction. A refusal here is also an answer: the pool does not give exactly that much,
+  // and then the usual input shape remains, with a minimum from the required amount.
   let exactOut = null;
   if (requiredOutWei !== null && requiredOutWei !== undefined && Number(requiredOutWei) > 0) {
     const eo = await quoteExactOutPath(chain, { route: q, amountOutWei: BigInt(requiredOutWei) }, opts);
     exactOut = eo.ok
       ? {
           ok: true, amountInWei: eo.amountInWei, gasEstimate: eo.gasEstimate,
-          // ХВАТИТ ЛИ ВВЕДЁННОГО: сравнивается сумма на входе, потому что у этой формы ответ - именно
-          // "сколько надо отдать". Излишек остаётся пользователю: никакой конвертации остатка в коде нет.
+          // IS THE ENTERED AMOUNT ENOUGH: the input amount is compared, because with this shape the answer is
+          // exactly "how much to give". Any surplus stays with the user: no conversion of the remainder in the code.
           enough: BigInt(eo.amountInWei) <= amount,
           enteredWei: amount.toString(),
           spareInWei: (BigInt(eo.amountInWei) <= amount ? amount - BigInt(eo.amountInWei) : 0n).toString(),
@@ -761,9 +760,9 @@ export async function quoteDexOut(chain, { token, amountWei, requiredOutWei = nu
         }
       : { ok: false, why: eo.why };
   }
-  // ПОКРЫТИЕ СЧИТАЕТСЯ ЗДЕСЬ, А НЕ БЕРЁТСЯ ИЗ КЕША: пул и сумма входа кешируются на 20 с, а требуемая
-  // сумма приходит из ордера и может смениться (человек поправил размер XMR) - и тогда покрытие обязано
-  // пересчитаться, а не остаться прежним. Считается в целых wei.
+  // COVERAGE IS COMPUTED HERE, NOT TAKEN FROM THE CACHE: the pool and input amount are cached for 20 s, but the
+  // required amount comes from the order and may change (the person adjusted the XMR size) - and then coverage
+  // must be recomputed, not left stale. Computed in whole wei.
   const required = requiredOutWei !== null && requiredOutWei !== undefined && Number(requiredOutWei) > 0
     ? (() => {
         const need = BigInt(requiredOutWei);
@@ -782,10 +781,10 @@ export async function quoteDexOut(chain, { token, amountWei, requiredOutWei = nu
     venue: "Uniswap v3",
     payToken: token.symbol,
     wrapped,
-    // ОБЪЯВЛЕННЫЙ МАРШРУТ, КОТОРЫМ СПРОШЕНА ЦЕНА: ступени, их пулы и дата замера - целиком, как в реестре.
-    // Интерфейс обязан показывать не только ЧТО получилось, но и ПО ЧЕМУ это объявлено.
+    // THE DECLARED ROUTE THE PRICE WAS ASKED ON: the steps, their pools and the measurement date - whole, as in the registry.
+    // The interface must show not only WHAT came out but WHAT it was declared from.
     declaredRoute: declaration,
-    // ПУТЬ - ЭТО ШАГИ С КОМИССИЯМИ, а не одна ступень: у объявленного обхода через стейбл их две.
+    // THE PATH IS THE STEPS WITH FEES, not one step: a declared detour via a stable has two.
     route: { symbols: q.symbols.slice(), fees: q.fees.slice(), pools: path.pools.slice(), via: null, hops: q.fees.length },
     routeLabel: routeLabel(q),
     steps: routeSteps(q),
@@ -794,31 +793,31 @@ export async function quoteDexOut(chain, { token, amountWei, requiredOutWei = nu
     amountInWei: amount.toString(),
     amountOutWei: q.amountOutWei,
     gasEstimate: q.gasEstimate,
-    // ВЕРДИКТ ВЫПОЛНИМОСТИ: покрывает ли маршрут требуемую сумму ордера. null означает "требуемая сумма
-    // не передана" - и тогда подпись блокируется как непроверенная (см. dexLegVerdict), а не разрешается.
+    // THE FEASIBILITY VERDICT: whether the route covers the required order amount. null means "the required amount
+    // was not passed" - and then signing is blocked as unverified (see dexLegVerdict), not allowed.
     required,
-    // ПРОВЕРКА ЦЕНЫ: проверили ли, похожа ли цена на рыночную, и блокирует ли это подпись на этой сети.
+    // THE PRICE CHECK: whether it was done, whether the price looks market, and whether it blocks signing on this network.
     price,
-    // ПРЕДПОЧТИТЕЛЬНАЯ ФОРМА (точный выход): сколько надо отдать, чтобы получить ровно требуемую сумму.
-    // Вопрос о разнице сумм при ней не встаёт - минимум на выходе равен требуемому по построению.
+    // THE PREFERRED SHAPE (exact output): how much to give to receive exactly the required amount.
+    // The question of a difference in amounts does not arise with it - the output minimum equals the required by construction.
     exactOut,
     hopsDetail: hops,
-    // Одиночная ступень (прежняя форма ответа) - из первой ноги пути. Читать их как "пул всего маршрута"
-    // нельзя, и это сказано тут: у обхода через хаб ног две.
+    // The single step (the former answer shape) - from the first leg of the path. They must not be read as "the
+    // whole route's pool", and that is said here: a detour via a hub has two legs.
     pool: hops.length ? hops[0].pool : null,
     at: Date.now(),
   };
 }
 
 // ---------------------------------------------------------------------------
-// WETH -> ETH: unwrap у самого WETH9, один к одному, БЕЗ пула.
+// WETH -> ETH: an unwrap at WETH9 itself, one to one, WITHOUT a pool.
 //
-// Отсюда берётся описание строки "unwrap, 1:1". Оценка газа СЮДА НЕ ВХОДИТ: чтобы назвать газ unwrap,
-// нужен счёт, который держит WETH и может платить за газ, а у страницы такого счёта нет (и отправлять
-// ничего нельзя на этом шаге). Измеренный газ unwrap лежит в отчёте инструмента
-// (tools/check-uniswap-quote.mjs: газ измеряется eth_estimateGas на настоящем держателе WETH, которого
-// инструмент находит по журналам Transfer). Подставлять это число в интерфейс как "газ этой сделки"
-// было бы подменой: оно измерено на чужом счёте и на другой сумме. Поэтому честно: gasEstimate === null.
+// This is where the "unwrap, 1:1" line description comes from. The gas estimate does NOT enter here: to name the
+// unwrap gas one needs an account that holds WETH and can pay for gas, and the page has no such account (and
+// nothing may be sent at this step). The measured unwrap gas lies in the tool's report (the gas is measured via
+// eth_estimateGas on a real WETH holder, which the tool finds from Transfer logs). Substituting that number into
+// the interface as "this deal's gas" would be a fake: it is measured on someone else's account and another
+// amount. So, honestly: gasEstimate === null.
 // ---------------------------------------------------------------------------
 export function unwrapLeg(chain) {
   const u = chain && chain.uniswap;
@@ -829,7 +828,7 @@ export function unwrapLeg(chain) {
     leg: "unwrap",
     venue: w.name || w.symbol,
     wrapped: w,
-    rate: 1, // один к одному по определению WETH9: withdraw(wad) отдаёт ровно wad нативного
+    rate: 1, // one to one by WETH9's definition: withdraw(wad) returns exactly wad of native
     gasEstimate: null,
     why: null,
   };