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

package/engine/evm/factory.js

@@ -1,51 +1,48 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/evm/factory.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.
 
-// Вызовы контракта-фабрики эскроу ArrakisSwap.
+// Calls to the NinseiSwap escrow factory contract.
 //
-// Библиотек для EVM в проекте нет и не добавляем. ОБЕ ФУНКЦИИ ФАБРИКИ ТЕПЕРЬ ПРИНИМАЮТ ПОДПИСАННУЮ КОТИРОВКУ
-// (OrderQuote.Quote), подпись тремя словами (r, s, v) и три поля вносившего. Комиссия и адрес реестра - ЧАСТЬ
-// КОТИРОВКИ, а не настройка контракта: функций feeBps()/feeFor() у фабрики больше нет (роутер удалён,
-// решение #76), и спрашивать их не у чего. Все аргументы статические, поэтому calldata - селектор плюс слова
-// по 32 байта; собирается здесь, в одном месте, и проверяется tools/check-evm-abi.mjs.
+// There are no EVM libraries in the project and we are not adding any. BOTH FACTORY FUNCTIONS NOW TAKE THE
+// SIGNED QUOTE (OrderQuote.Quote), the signature as three words (r, s, v) and three depositor fields. The fee
+// and the registry address are PART of the quote, not a contract setting: the factory no longer has feeBps()/
+// feeFor() (the router was removed), so there is nothing to ask. All arguments are static, so calldata is a
+// selector plus 32-byte words, built here in one place and checked mechanically.
 //
 //   cast sig "predict((address,address,address,address,address,address,uint256,uint64,uint64,bytes32,bytes32,bytes32,uint256,uint256,uint256,address,uint64,uint256,uint256),bytes32,bytes32,uint8,bytes32,bytes32,bytes32)" -> 0x0824d205
-//   cast sig "createOrderAndFund(<тот же tuple>,...)"                                                                                                                -> 0x4703a9d3
+//   cast sig "createOrderAndFund(<same tuple>,...)"                                                                                                                -> 0x4703a9d3
 
 export const FACTORY_METHODS = {
-  // СОСТАВ КОТИРОВКИ ВЫРОС ПОЛЕМ xmrAmount (#110 шаг 3): XMR-сторона сделки входит в подписанный набор, поэтому
-  // селекторы обеих прежних функций сменились вторично (прежде - от поля cashier, #103).
+  // THE QUOTE GREW THE xmrAmount FIELD: the XMR side of the deal is part of the signed set, so both selectors
+  // changed a second time (earlier for the cashier field).
   predict: "0x0824d205",
-  // создать эскроу И внести деньги ОДНОЙ транзакцией (перевод value вместе с вызовом).
+  // create the escrow AND deposit funds in ONE transaction (a value transfer with the call).
   createOrderAndFund: "0x4703a9d3",
-  // создать эскроу и внести деньги, когда ВНОСЯЩИЙ восстановлен ИЗ ПОДПИСИ над дайджестом котировки
-  // (issue #97, часть A): транзакцию шлёт кто угодно, а `locker` записан подписавшим.
+  // create the escrow and deposit when the DEPOSITOR is recovered FROM THE SIGNATURE over the quote digest:
+  // anyone may send the transaction, and `locker` is set to the signer.
   createOrderAndFundByDepositor: "0x2acd187b",
 };
 
-// ТЕМА СОБЫТИЯ OrderCreated. Она выросла адресом реестра, провайдером и ключом подписи:
+// The OrderCreated event topic. It grew the registry address, the provider and the signing key:
 //   cast keccak "OrderCreated(address,address,address,bytes32,bytes32,bytes32,bytes32,bytes32,uint256,uint64,uint64,bytes32,address,address,address)"
-// Тема живёт в ДВУХ местах - здесь и в watchtower/scan.mjs, - и обе обязаны совпадать: разойтись молча они
-// не могут, сверку держит проверка ABI.
+// The topic lives in TWO places and both must match; a check pins them.
 export const ORDER_CREATED_TOPIC =
   "0xa22cdabaed3cce4f51dde71626a108ffe9c7bc4216fd14d5e719f892e2fd8ab0";
 
-// ПОЛЯ КОТИРОВКИ В ПОРЯДКЕ КОНТРАКТА. Порядок - часть ABI: перестановка даёт другой вызов (чужую функцию
-// или ордер с чужими условиями). Список ОДИН на обе функции: разойтись им нечем.
+// QUOTE FIELDS IN CONTRACT ORDER. The order is part of the ABI: a swap gives another call. One list for both
+// functions, so they cannot diverge.
 export const QUOTE_FIELDS = [
   "provider", "quoteKey", "registry", "cashier", "locker", "claimer", "amount", "readyBy", "t1", "salt",
   "commitHalfClaimer", "edPointClaimer", "chainId", "feeBps", "fee", "feeRecipient", "validUntil", "nonce", "xmrAmount",
 ];
-// Поля вносившего котировка НЕ несёт: они уходят отдельными аргументами (входят в init-код эскроу).
+// The depositor fields are NOT in the quote: they go as separate arguments (into the escrow init code).
 const LOCKER_HALF_FIELDS = ["commitHalfLocker", "edPointLocker", "edViewPointLocker"];
 const ADDR_FIELDS = ["provider", "quoteKey", "registry", "cashier", "locker", "claimer", "feeRecipient"];
 const B32_FIELDS = ["salt", "commitHalfClaimer", "edPointClaimer", "commitHalfLocker", "edPointLocker", "edViewPointLocker"];
 
-// Слово calldata: значение, выровненное вправо до 32 байт. Числа приходят десятичными (wei, сроки), а в
-// calldata обязаны быть шестнадцатеричными: дополнение нулями десятичных цифр кодировало бы их как hex и
-// уводило сумму в другое число. Поймано сверкой с эталоном Foundry.
+// A calldata word: a value right-aligned to 32 bytes. Numbers arrive decimal (wei, deadlines) but must be hex in
+// calldata: padding decimal digits as hex would change the number. Caught by comparison with a Foundry reference.
 export function word(value, bytes = 32) {
   const raw = String(value).trim();
   let hex;
@@ -55,34 +52,34 @@ export function word(value, bytes = 32) {
   } else if (/^[0-9]+$/.test(raw)) {
     hex = BigInt(raw).toString(16);
   } else {
-    throw new Error("не число и не hex: " + value);
+    throw new Error("not a number and not hex: " + value);
   }
-  if (!/^[0-9a-f]*$/.test(hex)) throw new Error("не hex: " + value);
-  if (hex.length > bytes * 2) throw new Error(`значение не влезает в ${bytes} байт: ${value}`);
+  if (!/^[0-9a-f]*$/.test(hex)) throw new Error("not hex: " + value);
+  if (hex.length > bytes * 2) throw new Error(`value does not fit in ${bytes} bytes: ${value}`);
   return hex.padStart(bytes * 2, "0");
 }
 
-// ФОРМА ПРИВОДИТСЯ, А НЕ ТРЕБУЕТСЯ: точки и обязательства в записи движка лежат БЕЗ префикса 0x, а word()
-// требует префикс. Байты одни и те же, поэтому оба вида кодируются одинаково.
+// FORM IS NORMALISED, NOT DEMANDED: points and commitments in the engine record sit WITHOUT the 0x prefix, while
+// word() requires it. Same bytes, so both forms encode identically.
 const asHex32 = (v) => {
   const x = String(v === undefined || v === null ? "" : v).trim();
   return /^[0-9a-fA-F]{64}$/.test(x) ? "0x" + x.toLowerCase() : x;
 };
 
-// СЛОВА ПОДПИСАННОГО НАБОРА. Подпись - 65 байт r || s || v; v приводится к 27/28 (контракт принимает оба
-// соглашения). r и s - ПОЛНЫЕ 32 байта, v - тоже ПОЛНОЕ слово из 32 байт (ABI uint8 не бывает короче слова:
-// неполное слово сдвинуло бы хвост calldata и вызов ушёл бы на несуществующий селектор).
+// WORDS OF THE SIGNED SET. The signature is 65 bytes r || s || v; v is normalised to 27/28 (the contract takes
+// both). r and s are FULL 32 bytes, v is a FULL 32-byte word (ABI uint8 is never shorter: a short word would shift
+// the calldata tail and the call would go to a non-existent selector).
 function quoteWords(quote) {
   for (const name of QUOTE_FIELDS) {
-    if (quote[name] === undefined || quote[name] === null || quote[name] === "") throw new Error("в котировке нет поля: " + name);
+    if (quote[name] === undefined || quote[name] === null || quote[name] === "") throw new Error("the quote has no field: " + name);
   }
-  // ФОРМА ПРОВЕРЯЕТСЯ, А НЕ ДОСТРАИВАЕТСЯ: короткий адрес или усечённый bytes32 молча выровнялся бы
-  // нулями и ушёл в контракт ДРУГИМ значением.
+  // FORM IS CHECKED, NOT PADDED: a short address or a truncated bytes32 would be silently zero-padded and reach
+  // the contract as a DIFFERENT value.
   for (const name of ADDR_FIELDS) {
-    if (!/^(0x)?[0-9a-fA-F]{40}$/.test(String(quote[name]).trim())) throw new Error("поле котировки " + name + " - не адрес");
+    if (!/^(0x)?[0-9a-fA-F]{40}$/.test(String(quote[name]).trim())) throw new Error("quote field " + name + " is not an address");
   }
   for (const name of B32_FIELDS) {
-    if (!/^(0x)?[0-9a-fA-F]{64}$/.test(String(quote[name]).trim())) throw new Error("поле котировки " + name + " - не bytes32");
+    if (!/^(0x)?[0-9a-fA-F]{64}$/.test(String(quote[name]).trim())) throw new Error("quote field " + name + " is not bytes32");
   }
   const map = {
     provider: word(quote.provider, 32), quoteKey: word(quote.quoteKey, 32), registry: word(quote.registry, 32),
@@ -101,17 +98,17 @@ function quoteWords(quote) {
 
 function signatureWords(signature) {
   const hex = String(signature || "").replace(/^0x/, "");
-  if (!/^[0-9a-fA-F]{130}$/.test(hex)) throw new Error("подпись котировки должна быть 65 байт: " + String(signature).slice(0, 20));
+  if (!/^[0-9a-fA-F]{130}$/.test(hex)) throw new Error("the quote signature must be 65 bytes: " + String(signature).slice(0, 20));
   const r = hex.slice(0, 64), s = hex.slice(64, 128);
   let v = parseInt(hex.slice(128, 130), 16);
   if (v < 27) v += 27;
   return word("0x" + r, 32) + word("0x" + s, 32) + word(v, 32);
 }
 
-// ОБЩАЯ ЧАСТЬ predict и createOrderAndFund.
+// The common part of predict and createOrderAndFund.
 function lockerHalfWords(quote) {
   return LOCKER_HALF_FIELDS.map((name) => {
-    if (quote[name] === undefined || quote[name] === null || quote[name] === "") throw new Error("в котировке нет поля вносившего: " + name);
+    if (quote[name] === undefined || quote[name] === null || quote[name] === "") throw new Error("the quote has no depositor field: " + name);
     return word(asHex32(quote[name]), 32);
   }).join("");
 }
@@ -120,45 +117,44 @@ function quoteCallArgs(quote) {
   return quoteWords(quote) + signatureWords(quote.signature) + lockerHalfWords(quote);
 }
 
-// ПРЕДСКАЗАТЬ АДРЕС. Состав аргументов совпадает с createOrderAndFund БАЙТ В БАЙТ (адрес - хеш кода
-// создания, и подпись в него входит).
+// PREDICT THE ADDRESS. The argument set matches createOrderAndFund BYTE FOR BYTE (the address is the code hash of
+// creation, and the signature is part of it).
 export function encodePredict(quote) {
   return FACTORY_METHODS.predict + quoteCallArgs(quote);
 }
 
-// СОЗДАТЬ И ВНЕСТИ. Вносившим становится msg.sender; его адрес уже внутри котировки, а фабрика сверяет его
-// с отправителем.
+// CREATE AND DEPOSIT. The depositor becomes msg.sender; its address is already inside the quote and the factory
+// checks it against the sender.
 export function encodeCreateOrderAndFund(quote) {
   return FACTORY_METHODS.createOrderAndFund + quoteCallArgs(quote);
 }
 
-// СОЗДАТЬ И ВНЕСТИ, когда вносящий восстановлен ИЗ ЕГО ПОДПИСИ над ДАЙДЖЕСТОМ КОТИРОВКИ (#97, часть A).
-// Транзакцию шлёт кто угодно, поэтому подписантов ДВОЕ: `quote.signature` - подпись провайдера (её
-// проверяет эскроу), `depositorSignature` - подпись ВНОСЯЩЕГО (её проверяет фабрика и требует, чтобы
-// восстановленный адрес совпал с `quote.locker`). Обе - над ОДНИМ дайджестом котировки.
+// CREATE AND DEPOSIT when the depositor is recovered FROM ITS SIGNATURE over the quote digest. Anyone may send
+// the transaction, so there are TWO signers: quote.signature (the provider, checked by the escrow) and
+// depositorSignature (the depositor, checked by the factory, which requires the recovered address to equal
+// quote.locker). Both over ONE digest.
 export function encodeCreateOrderAndFundByDepositor(quote, depositorSignature) {
   return FACTORY_METHODS.createOrderAndFundByDepositor + quoteWords(quote) +
     signatureWords(quote.signature) + signatureWords(depositorSignature) + lockerHalfWords(quote);
 }
 
-// Ответ predict() - один адрес в 32-байтовом слове.
+// predict() answer - one address in a 32-byte word.
 export function decodeAddress(returnedHex) {
   const hex = String(returnedHex || "").replace(/^0x/, "");
-  if (hex.length < 64) throw new Error("короткий ответ: " + returnedHex);
+  if (hex.length < 64) throw new Error("short answer: " + returnedHex);
   return "0x" + hex.slice(24, 64);
 }
 
 
 // ============================================================================================
-// РЕАЛИЗАЦИЯ ЭСКРОУ: ЕЁ АДРЕС И ХЕШ ЕЁ КОДА (issue #114, поправка 2).
-// С #114 эскроу каждого ордера - КЛОН EIP-1167 одной общей реализации, а адрес реализации и хеш её кода
-// лежат у фабрики (implementation() / implementationCodeHash()). ФАБРИКА при создании ордера проверяет эту
-// пару; КЛИЕНТ обязан проверить ТУ ЖЕ пару, иначе клон исполнит чужой код, а денежные пути "пройдут" впустую
-// (delegatecall на адрес без кода УСПЕШЕН). Здесь - только чтение полей и вердикт; вызовы к цепи делает
-// носитель (session.js: readContract/readCode), поэтому функция чистая и проверяется без сети.
+// ESCROW IMPLEMENTATION: ITS ADDRESS AND CODE HASH. Every order escrow is an EIP-1167 CLONE of one shared
+// implementation, and the implementation address and code hash live at the factory. The FACTORY checks the pair
+// at order creation; the CLIENT must check the SAME pair, else the clone runs foreign code and the money paths
+// "pass" for nothing (a delegatecall to an address without code SUCCEEDS). Here we only read fields and give a
+// verdict; the chain calls are made by the carrier, so the function is pure.
 // ============================================================================================
 
-// Селекторы посчитаны инструментом, не вручную:
+// Selectors are computed by a tool, not by hand:
 //   cast sig "implementation()"         -> 0x5c60da1b
 //   cast sig "implementationCodeHash()" -> 0xbc0a3981
 export const FACTORY_READS = {
@@ -166,32 +162,32 @@ export const FACTORY_READS = {
   implementationCodeHash: "0xbc0a3981",
 };
 
-// Чтение поля фабрики без аргументов: calldata равен селектору.
+// Reading a factory field with no arguments: calldata is the selector.
 export function encodeFactoryRead(name) {
   const sel = FACTORY_READS[name];
-  if (typeof sel !== "string" || !/^0x[0-9a-f]{8}$/.test(sel)) throw new Error("нет такого чтения фабрики: " + name);
+  if (typeof sel !== "string" || !/^0x[0-9a-f]{8}$/.test(sel)) throw new Error("no such factory read: " + name);
   return sel;
 }
 
-// implementation() - один адрес в 32-байтовом слове.
+// implementation() - one address in a 32-byte word.
 export function decodeImplementation(returnedHex) {
   return decodeAddress(returnedHex);
 }
 
-// implementationCodeHash() - одно слово bytes32.
+// implementationCodeHash() - one bytes32 word.
 export function decodeImplementationCodeHash(returnedHex) {
   const hex = String(returnedHex || "").replace(/^0x/, "");
-  if (hex.length < 64) throw new Error("короткий ответ implementationCodeHash(): " + returnedHex);
+  if (hex.length < 64) throw new Error("short answer from implementationCodeHash(): " + returnedHex);
   return "0x" + hex.slice(0, 64).toLowerCase();
 }
 
-// ВЕРДИКТ ПО РЕАЛИЗАЦИИ - те же три условия, что проверяет фабрика (и что закрывает поправки #114):
-//   1) адрес реализации назван и её КОД на цепи непуст: delegatecall на адрес без кода успешен, поэтому
-//      клон без реализации принял бы ETH, а markReady/claim/refund "прошли" бы, ничего не сделав;
-//   2) хеш кода реализации равен recorded-хешу фабрики (сравнение делает сама фабрика через codehash);
-//   3) recorded-хеш входит в политику интерфейса (список известных сборок) - если она задана.
-// Если передан hashCode (keccak256 байтов кода), сверяется и живой код: тогда вердикт не доверяет одному
-// лишь ответу фабрики, а пересчитывает хеш из eth_getCode.
+// VERDICT ON THE IMPLEMENTATION - the same three conditions the factory checks:
+//   1) the implementation address is named and its CODE on chain is non-empty: a delegatecall to an address without
+//      code succeeds, so a clone without an implementation would take ETH and markReady/claim/refund would "pass";
+//   2) the implementation code hash equals the factory recorded hash (compared by the factory via codehash);
+//   3) the recorded hash is in the interface policy (a list of known builds), if set.
+// If hashCode is given (keccak256 of the code bytes), the live code is compared too: the verdict then recomputes
+// the hash from eth_getCode.
 export function verifyFactoryImplementation({ implementation, implementationCodeHash, code, hashCode, policy } = {}) {
   if (!implementation || !/^0x[0-9a-fA-F]{40}$/.test(String(implementation))) {
     return { ok: false, why: "implementation-missing" };
@@ -215,13 +211,11 @@ export function verifyFactoryImplementation({ implementation, implementationCode
   return { ok: true, codeHash: pinned };
 }
 
-// ЧТЕНИЕ ПАРЫ У ФАБРИКИ + ВЕРДИКТ - ОДНО МЕСТО НА ВСЕ НОСИТЕЛИ (SDK, узел, сторож). Читает пару полей
-// фабрики (implementation() / implementationCodeHash()) и КОД по адресу реализации, затем применяет тот же
-// вердикт, что и фабрика при создании ордера (verifyFactoryImplementation выше). Цепь инжектится: read -
-// это eth_call ({to,data}) -> hex, code - это eth_getCode (address) -> hex. Модуль остаётся чистым: ни
-// одного импорта, ни одного сетевого вызова, поэтому проверяется без сети. Носители подставляют СВОИ
-// чтения (SDK - evmCall/evmCode кошелька страницы, узел и сторож - свой RPC). hashCode, если передан,
-// пересчитывает живой код: тогда вердикт не доверяет одному лишь ответу фабрики.
+// READING THE PAIR AT THE FACTORY + VERDICT - ONE PLACE FOR ALL CARRIERS (SDK, node, watchtower). It reads the
+// factory fields (implementation()/implementationCodeHash()) and the CODE at the implementation address, then
+// applies the same verdict the factory applies at order creation (verifyFactoryImplementation above). The chain
+// is injected: read - eth_call({to,data}) -> hex, code - eth_getCode(address) -> hex. The module stays pure: no
+// import, no network call. Carriers pass their OWN reads. hashCode, if given, recomputes the live code.
 export async function verifyFactoryImplementationOnChain({ factory, read, code, policy = null, hashCode = null } = {}) {
   if (!factory || !/^0x[0-9a-fA-F]{40}$/.test(String(factory))) {
     return { ok: false, why: "factory-missing" };
@@ -233,8 +227,8 @@ export async function verifyFactoryImplementationOnChain({ factory, read, code,
     implRaw = await read({ to: factory, data: FACTORY_READS.implementation });
     hashRaw = await read({ to: factory, data: FACTORY_READS.implementationCodeHash });
   } catch {
-    // ЧТЕНИЕ ПАРЫ НЕ УДАЛОСЬ - ЭТО НАЗВАННЫЙ ОТКАЗ, А НЕ МОЛЧАНИЕ. Старая фабрика (без этих геттеров)
-    // отвечает revert'ом: пара не прочитана, вердикта нет, и носитель обязан отказать.
+    // READING THE PAIR FAILED - A NAMED REFUSAL, NOT SILENCE. An old factory (without these getters) reverts:
+    // the pair is unread, there is no verdict, and the carrier must refuse.
     return { ok: false, why: "implementation-unreadable", factory: String(factory).toLowerCase() };
   }
   let implementation, implementationCodeHash;

package/engine/evm/fees.js

@@ -1,90 +1,89 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/evm/fees.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.
 
-// Комиссия ArrakisSwap: ЧАСТЬ ПОДПИСАННОЙ КОТИРОВКИ (OrderQuote v7), а не настройка контракта.
+// The NinseiSwap fee: PART OF THE SIGNED QUOTE (OrderQuote v7), not a contract setting.
 //
-// ГДЕ ЖИВЁТ СТАВКА. Раньше её и получателя назначала ФАБРИКА (или роутер) в неизменяемых полях, и клиент
-// спрашивал их у цепи (feeBps()/feeRecipient()/feeFor()). Теперь этих функций у контракта НЕТ: роутер удалён
-// (решение #76), а ставка, величина и получатель комиссии входят в ПОДПИСАННЫЙ набор условий ордера. Значит
-// источник правды ОДИН - котировка, и второго места быть не должно:
-//   * в настройках страницы ставки НЕТ; копия разошлась бы с подписанным набором;
-//   * у фабрики спрашивать нечего - она ничего о комиссии не знает;
-//   * величина в wei посчитана по формуле `amount * feeBps / 10000` (округление ВНИЗ) и здесь сверяется с
-//     этой же формулой ЗЕРКАЛОМ: расхождение обязано остановить подпись, а не превратиться в отказ эскроу
-//     (WrongAmount/BadFee) уже после неё.
+// WHERE THE RATE LIVES. Before, it and the recipient were set by the FACTORY (or router) in immutable fields, and
+// the client asked the chain for them (feeBps()/feeRecipient()/feeFor()). Now the contract has NO such functions:
+// the router was removed, and the rate, amount and recipient of the fee are part of the SIGNED set
+// of order terms. So the source of truth is ONE - the quote - and there must be no second place:
+//   * the page settings hold NO rate; a copy would diverge from the signed set;
+//   * there is nothing to ask the factory - it knows nothing about the fee;
+//   * the amount in wei is computed by the formula `amount * feeBps / 10000` (rounding DOWN) and here it is verified
+//     against that same formula by the MIRROR: a divergence must stop the signature, not turn into an escrow
+//     refusal (WrongAmount/BadFee) after it.
 //
-// КТО ПЛАТИТ. Комиссию платит ПОЛЬЗОВАТЕЛЬ ИНТЕРФЕЙСА. Направление видно из ролей котировки: провайдер
-// забирает ETH - покупка (комиссия СВЕРХУ взноса), провайдер вносит ETH - продажа (комиссия ВЫЧЕТОМ из
-// выплаты, `amount - fee`). Провайдер не назван ни там, ни там - понять нечего, отказ.
+// WHO PAYS. The fee is paid by the USER OF THE INTERFACE. The direction is visible from the quote roles: the
+// provider takes ETH - a buy (fee ON TOP of the deposit), the provider deposits ETH - a sell (fee DEDUCTED from
+// the payout, `amount - fee`). The provider is named in neither - nothing to tell, refusal.
 //
-// ОДНА ЕДИНИЦА ВРЕМЕНИ. Время в проекте - СЕКУНДЫ (сроки ордера, срок годности котировки, block.timestamp):
-// пересчёт между шкалами и был единственным местом, где ошибка на тысячу проходит молча.
+// ONE UNIT OF TIME. Time in the project is SECONDS (order deadlines, quote validity, block.timestamp):
+// converting between scales was the only place where an error by a thousand passes silently.
 
-// Потолок ставки, зашитый в контракте (NinseiEscrow.MAX_FEE_BPS = 200 = 2%). Нужен здесь, чтобы отличить
-// осмысленную ставку от испорченной: читать мусор как ставку и считать по нему комиссию нельзя.
+// The rate ceiling hard-wired in the contract (NinseiEscrow.MAX_FEE_BPS = 200 = 2%). Needed here to tell a
+// meaningful rate from a corrupted one: reading garbage as a rate and computing a fee from it is not allowed.
 export const MAX_FEE_BPS = 200;
 
-// ЗЕРКАЛО ФОРМУЛЫ КОНТРАКТА. Одно место на всю страницу: вторая копия разошлась бы с первой ровно там,
-// где это дороже всего - на величине, которую требует эскроу.
+// THE MIRROR OF THE CONTRACT FORMULA. One place for the whole page: a second copy would diverge from the first
+// exactly where it is most expensive - on the amount the escrow requires.
 export function feeWeiFor(amountWei, feeBps) {
   const amount = BigInt(amountWei === null || amountWei === undefined || amountWei === "" ? 0 : amountWei);
   const bps = BigInt(Number(feeBps) || 0);
-  if (amount < 0n || bps < 0n) throw new Error("комиссия: отрицательная сумма или ставка");
-  return (amount * bps) / 10000n;   // ВНИЗ, как в Solidity: amount * feeBps / 10000
+  if (amount < 0n || bps < 0n) throw new Error("fee: negative amount or rate");
+  return (amount * bps) / 10000n;   // DOWN, as in Solidity: amount * feeBps / 10000
 }
 
 const sameAddr = (a, b) => String(a || "").toLowerCase() === String(b || "").toLowerCase();
 const zeroAddr = (a) => !a || /^0x0{40}$/i.test(String(a));
 
-// ПАМЯТЬ О ПОСЛЕДНЕЙ ПОДПИСАННОЙ КОТИРОВКЕ. Ставка становится известна ТОЛЬКО с котировкой; до неё её нет,
-// и показывать вместо неё ноль или число из конфига значило бы врать. Проверки подставляют свои значения
-// через resetFeeCache + feeTermsFromQuote.
+// MEMORY OF THE LAST SIGNED QUOTE. The rate becomes known ONLY with the quote; before it there is none,
+// and showing zero or a config value instead would be lying. The checks insert their own values
+// via resetFeeCache + feeTermsFromQuote.
 let lastTerms = null;
 
-// СБРОС ПАМЯТИ. Нужен проверкам и любому повтору после смены котировки.
+// RESET THE MEMORY. Needed by the checks and by any retry after the quote changes.
 export function resetFeeCache() {
   lastTerms = null;
 }
 
-// КОМИССИЯ ИЗ КОТИРОВКИ. Возвращает ставку, величину (сверенную зеркалом), получателя и направление; при
-// ненулевой ставке без получателя - отказ (комиссия сгорела бы). Результат кладётся в память для экрана.
+// FEE FROM THE QUOTE. Returns the rate, the amount (verified by the mirror), the recipient and the direction;
+// with a non-zero rate and no recipient - a refusal (the fee would burn). The result is kept in memory for the screen.
 export function feeTermsFromQuote(quote) {
-  if (!quote || typeof quote !== "object") throw new Error("нет подписанной котировки: комиссию и адрес реестра взять неоткуда");
+  if (!quote || typeof quote !== "object") throw new Error("no signed quote: there is nowhere to take the fee and the registry address");
   const amount = BigInt(String(quote.amount));
   const bps = Number(quote.feeBps === undefined || quote.feeBps === null ? 0 : quote.feeBps);
-  if (!Number.isFinite(bps) || bps < 0 || bps > MAX_FEE_BPS) throw new Error("ставка комиссии вне потолка: " + quote.feeBps);
+  if (!Number.isFinite(bps) || bps < 0 || bps > MAX_FEE_BPS) throw new Error("fee rate outside the ceiling: " + quote.feeBps);
   const fee = feeWeiFor(amount, bps);
   if (BigInt(String(quote.fee === undefined || quote.fee === null ? 0 : quote.fee)) !== fee) {
-    throw new Error("подписанная комиссия " + quote.fee + " расходится с формулой amount * rate (" + fee + ") - подпись не начата");
+    throw new Error("signed fee " + quote.fee + " diverges from the formula amount * rate (" + fee + ") - signature not started");
   }
-  if (bps !== 0 && zeroAddr(quote.feeRecipient)) throw new Error("при ненулевой ставке получатель комиссии обязан быть назван");
+  if (bps !== 0 && zeroAddr(quote.feeRecipient)) throw new Error("with a non-zero rate the fee recipient must be named");
   const providerIsLocker = sameAddr(quote.locker, quote.provider);
   const providerIsClaimer = sameAddr(quote.claimer, quote.provider);
-  if (providerIsLocker === providerIsClaimer) throw new Error("не понять, кто платит комиссию: провайдер не назван ни вносившим, ни забирающим");
-  const feeOnTop = providerIsClaimer;   // провайдер забирает ETH -> покупка -> комиссия сверху взноса
+  if (providerIsLocker === providerIsClaimer) throw new Error("cannot tell who pays the fee: the provider is named neither as depositor nor as claimer");
+  const feeOnTop = providerIsClaimer;   // the provider takes ETH -> a buy -> fee on top of the deposit
   const terms = { bps, feeWei: fee, totalWei: feeOnTop ? amount + fee : amount, recipient: quote.feeRecipient || null, feeOnTop, legacy: false };
   lastTerms = terms;
   return terms;
 }
 
-// СИНХРОННЫЙ ДОСТУП К ПРОЧИТАННОМУ. Пусто - значит "ещё не читали либо не смогли": это НЕ ноль, и
-// вызывающий обязан закрыть подпись, а не посчитать комиссию нулевой.
+// SYNCHRONOUS ACCESS TO WHAT WAS READ. Empty means "not read yet or could not": this is NOT zero, and
+// the caller must close the signature, not count the fee as zero.
 export function cachedFeeTerms() {
   return lastTerms;
 }
 
-// СТАВКА ДЛЯ ПОКАЗА. Единственное место, откуда страница берёт число для строки разбивки цены. Ответа нет -
-// null, и экран говорит, что ставка ещё неизвестна.
+// RATE FOR DISPLAY. The only place the page takes the number for the price-breakdown line from. No answer -
+// null, and the screen says the rate is not known yet.
 export function cachedFeeRate() {
   if (!lastTerms || !Number.isFinite(Number(lastTerms.bps))) return null;
   return Number(lastTerms.bps) / 10000;
 }
 
-// РАНЬШЕ ЭТА ФУНКЦИЯ ЧИТАЛА СТАВКУ У ЦЕПИ. Теперь читать не у чего: ставка - в подписанной котировке, и
-// приходит она вместе с нею (feeTermsFromQuote). Функция оставлена ради вызывающих экранов: до котировки она
-// честно возвращает то, что уже известно (обычно null - "ставка неизвестна"), и ничего не выдумывает.
+// THIS FUNCTION USED TO READ THE RATE FROM THE CHAIN. Now there is nothing to read: the rate is in the signed
+// quote and arrives with it (feeTermsFromQuote). The function is kept for the screens that call it: before the
+// quote it honestly returns what is already known (usually null - "rate unknown"), and invents nothing.
 export async function ensureFeeTerms() {
   return lastTerms;
 }