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

package/engine/core/swap.js

@@ -1,35 +1,34 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/core/swap.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.
 
-// Ядро демки: состояние сделки во времени.
+// The demo core: the deal state over time.
 //
-// Принцип: состояние НЕ хранится как «текущий шаг». Хранятся таймстемпы и события,
-// а фаза выводится функцией derive() из sim-времени. Поэтому демо переживает
-// перезагрузку страницы, а «закрыть вкладку и вернуться» работает по-настоящему.
+// PRINCIPLE: the state is NOT kept as a "current step". Timestamps and events are kept, and the phase is derived
+// by derive() from the sim time. So the demo survives a page reload, and "close the tab and come back" truly works.
 //
-// Модель соответствует litepaper §4.2 и §5.3:
-//  - T0: дедлайн лока XMR мейкером. Не залочил - пользователь возвращает ETH (permissionless).
-//  - ready: пользователь подтверждает, что увидел лок своим view-ключом.
-//  - T1: дедлайн claim мейкера. Не сделал claim - пользователь возвращает ETH.
-//  - Если пользователь не сделал ready - мейкер забирает XMR назад, пользователь возвращает ETH.
-//  - Watchtower может вернуть деньги пользователю без его участия.
-
-// DEMO НУЖЕН ЗДЕСЬ, И ЭТО НЕ МЕЛОЧЬ: ниже из него берётся умолчание режима цепи. Имя не было импортировано,
-// поэтому ЛЮБАЯ сделка, заведённая без явного chainMode, падала с "DEMO is not defined" - а страница живой
-// сделки передаёт режим явно, и поломка не была видна до первой проверки, которая заводит сделку без него.
+//
+// The model follows litepaper §4.2 and §5.3:
+//  - T0: the maker's XMR lock deadline. Did not lock - the user refunds the ETH (permissionless).
+//  - ready: the user confirms he saw the lock with his view key.
+//  - T1: the maker's claim deadline. Did not claim - the user refunds the ETH.
+//  - If the user did not mark ready - the maker takes the XMR back and the user refunds the ETH.
+//  - A watchtower can refund the user's money without his involvement.
+
+// DEMO IS NEEDED HERE, AND IT IS NOT A TRIFLE: the default chain mode is taken from it below. The name was not
+// imported, so ANY deal created without an explicit chainMode failed with "DEMO is not defined" - while the live
+// deal page passes the mode explicitly, so the break stayed invisible until the first check that creates a deal without it.
 import { TIMING, MONERO, SCENARIO_LABELS, DEFAULT_CHAIN, API, DEMO, chainById, SIGNING_GUARDS } from "./config.js";
-// ОКНО ПРОДАЖИ XMR (issue #111) - ОДНО правило на ноду и страницу. Здесь оно только читается для отсчёта.
+// THE XMR SELL WINDOW - ONE rule for the node and the page. Here it is only read for the countdown.
 import { sellWindowSec, SELL_WINDOW } from "./sellWindow.js";
 import { simElapsed, simWall, nowReal, rescaleStart } from "./clock.js";
 import { loadState, saveState } from "./store.js";
 import { shortId, randomHex } from "./format.js";
 import * as chain from "../mock/chain.js";
 import * as node from "../monero/node.js";
-// Источник Monero-ноги: в режиме "app" подтверждения и поступления приходят от бэкенда,
-// в режиме "mock" - от симулятора демки. Что именно уходит наружу (только адрес и view key),
-// проверяется в tools/check-chain-source.mjs.
+// The Monero-leg source: in "app" mode confirmations and arrivals come from the backend,
+// in "mock" mode - from the demo simulator. Exactly what goes outward (only the address and view key)
+// is checked mechanically.
 import { XMR_STATUS, explorerXmrTx, fetchSession, isLiveSource, openSession, pollInterval, xmrView } from "./chainSource.js";
 import { watchOnlyShareFromWallet } from "../recovery/restore.js";
 
@@ -56,8 +55,8 @@ export function createSwap(input) {
     side: input.side || "buy",
     scenario: input.scenario || "happy",
     speed: input.speed || 60,
-    // ВИДА КОТИРОВКИ В ЗАПИСИ НЕТ. Прежнее поле mode ("floating"/"fixed") было выбором вида цены, а в
-    // версии 4 второго вида не существует (док 41, §7): твёрдая котировка ровно одна - ордерная.
+    // THERE IS NO QUOTE KIND IN THE RECORD. The former field mode ("floating"/"fixed") was a choice of price
+    // kind, and in version 4 there is no second kind: a firm quote is exactly one - the order quote.
     network: input.network || DEFAULT_CHAIN,
     moneroNetwork: MONERO.networkType,
     realStart: now,
@@ -73,7 +72,7 @@ export function createSwap(input) {
     gasUsd: input.gasUsd,
     receiveAddress: input.receiveAddress,
     quoteSignature: input.quoteSignature,
-    swapWallet: input.swapWallet || null, // ключи одноразового Monero-кошелька
+    swapWallet: input.swapWallet || null, // the one-shot Monero wallet's keys
     timeline: {
       fundAtSim: 0,
       lockAtSim: input.scenario === "maker_no_lock" ? null : TIMING.makerLock,
@@ -81,13 +80,13 @@ export function createSwap(input) {
       confTarget: MONERO.confirmTarget,
       t0Sim: TIMING.t0Refund,
     },
-    // ТО ЖЕ УМОЛЧАНИЕ, ЧТО И В НАСТРОЙКАХ: "live" - настоящая высота цепи, "mock" - таймер песочницы.
-  // Второй умолчал здесь значил бы, что сделка без явного режима считается по таймеру.
-  chainMode: input.chainMode || DEMO.defaultChainMode, // mock | live (реальная высота Monero mainnet)
-    // Источник Monero-ноги: "app" - настоящий бэкенд (см. core/chainSource.js), "mock" - симулятор.
+    // THE SAME DEFAULT AS IN THE SETTINGS: "live" - the real chain height, "mock" - a sandbox timer.
+  // A second default here would mean a deal without an explicit mode is timed.
+  chainMode: input.chainMode || DEMO.defaultChainMode, // mock | live (the real Monero mainnet height)
+    // The Monero-leg source: "app" - the real backend (see core/chainSource.js), "mock" - the simulator.
     xmrSource: input.xmrSource || API.xmrSource,
-    xmrSession: null, // последний опрос бэкенда: статус, сумма, подтверждения, txid
-    xmrSessionError: null, // причина отказа бэкенда: показываем как состояние, а не как падение
+    xmrSession: null, // the last backend poll: status, amount, confirmations, txid
+    xmrSessionError: null, // the backend refusal cause: shown as a state, not a crash
     events: [],
     escrow: null,
     xmr: null,
@@ -95,11 +94,11 @@ export function createSwap(input) {
     log: [],
   };
 
-  // ДЕМОНСТРАЦИОННОЕ ФОНДИРОВАНИЕ ТОЛЬКО В ДЕМОНСТРАЦИИ. Здесь стоял безусловный вызов моковой ветки
-  // (chain.fundEscrow), и он выполнялся В ТОМ ЧИСЛЕ на живом пути: запись получала ВЫДУМАННЫЙ адрес эскроу
-  // и ВЫДУМАННЫЙ хеш транзакции, а живой поток потом с ними боролся. Снаружи это выглядело так: настоящий
-  // ордер создан и оплачен, а экран прогресса, ссылка на обозреватель, файл восстановления и плательщик
-  // смотрят на адрес, которого на цепи нет. На живом пути адрес и хеш обязан дать ТОЛЬКО живой поток.
+  // DEMO FUNDING ONLY IN THE DEMO. An unconditional call to the mock branch (chain.fundEscrow) used to stand
+  // here and ran INCLUDING on the live path: the record got an INVENTED escrow address and an INVENTED
+  // transaction hash, and the live flow then fought them. From outside it looked like this: a real order was
+  // created and paid, while the progress screen, the explorer link, the recovery file and the payer looked at
+  // an address not on chain. On the live path only the live flow may give the address and hash.
   if (swap.chainMode !== "live") {
     const fund = chain.fundEscrow({ swapId: swap.id, ethAmountUsd: swap.payAmount, ethUsd: 3212.4 });
     swap.escrow = {
@@ -111,9 +110,9 @@ export function createSwap(input) {
     };
     pushLog(swap, 0, "Escrow funded", `eth escrow ${fund.escrow}`);
   } else {
-    // ЗАГОТОВКА ПОД ЖИВОЙ ОРДЕР - И БЕЗ ЕДИНОГО ВЫДУМАННОГО ЗНАЧЕНИЯ. Адрес и хеш появятся из живого
-    // потока фондирования (confirm.js записывает их из ответа потока). Пустые поля здесь нужны не для
-    // красоты: без объекта запись оставалась без места, куда живому пути писать, и адрес терялся молча.
+    // A PLACEHOLDER FOR A LIVE ORDER - WITH NOT ONE INVENTED VALUE. The address and hash will come from the live
+    // funding flow (confirm.js writes them from the flow's answer). The empty fields are here not for beauty:
+    // without the object the record had nowhere for the live path to write, and the address was lost silently.
     swap.escrow = { address: null, fundTx: null, method: null, fundedAtSim: 0, gasUsd: input.gasUsd ?? null };
   }
 
@@ -123,7 +122,7 @@ export function createSwap(input) {
   return swap;
 }
 
-// REVERSE-FLOW DEAL RECORD (issue #118, second half). The sell screen used to stop at the request, and there was
+// REVERSE-FLOW DEAL RECORD . The sell screen used to stop at the request, and there was
 // nowhere to show a refund: a reverse deal had no record. It is created here - from exactly what the screen
 // already has (the node ticket plus the computed halves) - and lands in the same store as the buy flow, so the
 // deal card, the recovery file and the XMR sweep all work off it.
@@ -197,21 +196,21 @@ export function createReverseSwap(input = {}) {
 
 function pushLog(swap, atSim, title, detail) {
   swap.log.push({ atSim, wall: simWall(swap, atSim), title, detail: detail || "" });
-  // Дублируем в КОНСОЛЬ и это основной канал для разбора. Раньше журнал показывался только на странице,
-  // где жил в состоянии экрана и исчезал при перерисовке - то есть ровно тогда, когда он нужнее всего.
-  // В консоли история сохраняется, и её можно скопировать целиком.
+  // We duplicate to the CONSOLE too, and it is the main channel for diagnosis. The journal used to be shown only
+  // on the page, where it lived in the screen state and vanished on a redraw - exactly when it was needed most.
+  // In the console the history is kept and can be copied whole.
   console.log(`[swap ${swap.id}] ${title}${detail ? " - " + detail : ""}`);
 }
 
-// Убрать сделку из состояния браузера. Только локально: на сервере запись остаётся, и файлы кошелька,
-// которые им управляет бэкенд, тоже. Массово удалять их по маске нельзя - там кошельки настоящих свопов,
-// поэтому серверная уборка делается отдельным скриптом осознанно (tools/cleanup-swaps.mjs).
-// КОШЕЛОК ИЗ ПОЛОВИН ЗАПИСИ - ДЛЯ ФАЙЛА ВОССТАНОВЛЕНИЯ. Половины сохраняются в записи сделки в момент
-// фондирования (escrow.half и соседние поля), и это единственный их дом: полного ключа траты не существует
-// ни у одной стороны, а своя половина случайна - мнемоникой её не восстановить. Раньше выгрузка брала
-// swapWallet (кошелёк прежней схемы), и файл получался версией 2 - по такому файлу свои XMR не забрать.
-// Собираем ровно те поля, которых ждёт recoveryFile.js версии 3, и в одном месте, чтобы выгрузка и
-// проверки не расходились.
+// Drop a deal from the browser state. Locally only: the server keeps the record, and so do the wallet files the
+// backend manages. They must not be mass-deleted by a pattern - those are real swaps' wallets - so server cleanup
+// is a separate script on purpose.
+// THE HALVES WALLET FROM THE RECORD - FOR THE RECOVERY FILE. The halves are saved in the deal record at funding
+// time (escrow.half and neighbouring fields), and that is their only home: no full spend key exists for either
+// side, and one's own half is random - a mnemonic cannot restore it. The export used to take swapWallet (the
+// former scheme's wallet), and the file came out version 2 - from which one's XMR cannot be claimed. We assemble
+// exactly the fields recoveryFile.js version 3 expects, in one place, so the export and the checks do not diverge.
+//
 export function halvesWalletOf(swap) {
   const e = (swap && swap.escrow) || {};
   if (!e.half || !e.viewHalf || !e.counterViewHalf || !e.moneroAddress) return null;
@@ -250,20 +249,20 @@ export function allSwaps() {
   return Object.values(s.swaps).sort((a, b) => (a.realStart < b.realStart ? 1 : -1));
 }
 
-// ---- СЛИЯНИЕ С СПИСКОМ СЕРВЕРА --------------------------------------------------------------------
+// ---- MERGING WITH THE SERVER LIST -----------------------------------------------------------------
+//
+// Why. While records live only in localStorage the list is tied to the browser: cleared site data or another
+// device - no deals visible, although the money is in the escrow. The server list removes that.
 //
-// Зачем. Пока записи живут только в localStorage, список привязан к браузеру: очистили данные сайта или
-// открыли с другого устройства - сделок не видно, хотя деньги в эскроу на месте. Серверный список это
-// снимает.
 //
-// ПРАВИЛА СЛИЯНИЯ, и они намеренно осторожные:
-//   1) локальная запись ВСЕГДА главнее: она знает больше (секрет, кошелёк, стадии). Серверная строка только
-//      ДОБАВЛЯЕТ то, чего в этом браузере нет, и никогда не перезаписывает найденное;
-//   2) запись, пришедшая с сервера, помечается source: "server" - чтобы человек и код видели, откуда она,
-//      и чтобы на экране можно было честно сказать об этом;
-//   3) из серверной строки берём только публичные поля. Секрета там нет и быть не может - значит, такая
-//      сделка будет видна, но подписать забор средств из неё нельзя: секрет лежит в файле восстановления.
-//      Это не недоделка, а следствие того, что секрет на сервер не уходит.
+// MERGE RULES, deliberately cautious:
+//   1) a local record ALWAYS wins: it knows more (secret, wallet, stages). A server row only ADDS what this
+//      browser lacks and never overwrites what was found;
+//   2) a record that came from the server is marked source: "server" - so a person and the code see where it
+//      came from, and the screen can say so honestly;
+//   3) from a server row we take only public fields. There is no secret there and there cannot be - so such a
+//      deal will be visible but claiming funds from it cannot be signed: the secret lies in the recovery file.
+//      That is not an omission but a consequence of the secret never leaving for the server.
 export function serverRowToSwap(row) {
   const escrow = String((row && row.escrow) || "").toLowerCase();
   return {
@@ -285,15 +284,15 @@ export function serverRowToSwap(row) {
   };
 }
 
-// Добавить записи с сервера, которых нет локально. Возвращает число добавленных: вызывающий по нему решает,
-// перерисовывать ли список, а не догадывается.
+// Add server records the browser lacks. Returns the number added: the caller decides from it whether to redraw
+// the list, rather than guessing.
 export function addServerSwaps(rows) {
   if (!Array.isArray(rows) || rows.length === 0) return 0;
   const s = loadState();
   let added = 0;
   for (const row of rows) {
     if (!row || !row.id || !row.escrow) continue;
-    if (s.swaps[row.id]) continue;                       // локальная запись главнее - не трогаем
+    if (s.swaps[row.id]) continue;                       // a local record wins - do not touch
     s.swaps[row.id] = serverRowToSwap(row);
     added += 1;
   }
@@ -301,16 +300,16 @@ export function addServerSwaps(rows) {
   return added;
 }
 
-// Найти сделку по адресу эскроу: нужно, чтобы связать запись из списка сервера с настоящим ордером.
+// Find a deal by escrow address: needed to tie a server-list record to a real order.
 
 export function activeSwaps() {
   return allSwaps().filter((sw) => !sw.settlement);
 }
 
-// СОХРАНИТЬ СДЕЛКУ ПОСЛЕ ПРАВОК ИЗВНЕ. persist() был внутренним, и вызывающие модули (например
-// confirm.js) правили поля записи - адрес эскроу, соль, сроки, секрет - и НЕ сохраняли её: правки жили в
-// памяти и исчезали вместе с вкладкой, а экран прогресса читал из хранилища СТАРУЮ запись. Именно
-// поэтому интерфейс показывал адрес, которого на цепи нет, даже когда фондирование прошло успешно.
+// SAVE A DEAL AFTER OUTSIDE EDITS. persist() was internal, and calling modules (e.g. confirm.js) edited record
+// fields - escrow address, salt, deadlines, secret - and did NOT save it: the edits lived in memory and vanished
+// with the tab, while the progress screen read the OLD record from storage. That is exactly why the interface
+// showed an address not on chain even when funding had succeeded.
 export function saveSwap(swap) {
   return persist(swap);
 }
@@ -332,14 +331,14 @@ function findEvent(swap, type) {
 }
 
 // ---------------------------------------------------------------------------
-// Действия пользователя
+// User actions
 // ---------------------------------------------------------------------------
 
 export function confirmReady(id) {
   const swap = getSwap(id);
   if (!swap || swap.settlement) return swap;
   const view = derive(swap);
-  if (!view.can.ready) throw new Error("ready() недоступен в этой фазе");
+  if (!view.can.ready) throw new Error("ready() is not available in this phase");
   const atSim = simElapsed(swap);
   event(swap, "ready", atSim);
   pushLog(swap, atSim, "ready() called by you", "maker may now claim the ETH escrow");
@@ -350,14 +349,14 @@ export function confirmReady(id) {
 // THE COUNTERPARTY'S SPEND HALF - THE ONE PLACE THAT SHOWS WHETHER THERE IS ANYTHING TO ASSEMBLE. The Monero
 // spend key is the sum of two halves, and the user holds their own; sweeping XMR back after a refund is possible
 // exactly when the second half is ALREADY revealed. In the record it is stored as counterHalf (the engine sets it
-// while the counterparty is a stand-in) or as revealedHalf (read from the chain after claim/refund, docs/36).
+// while the counterparty is a stand-in) or as revealedHalf (read from the chain after claim/refund).
 export function refundHalfRevealed(swap) {
   const e = (swap && swap.escrow) || {};
   return e.revealedHalf || e.counterHalf || null;
 }
 
 // XMR SWEEP. In the ordinary phase this happens after the other side reveals its half through settlement. A
-// REVERSE-FLOW REFUND (issue #118, second half) is the SECOND case: the order was refunded, the user's coins
+// REVERSE-FLOW REFUND  is the SECOND case: the order was refunded, the user's coins
 // stayed on the swap's one-time address, and the contract revealed the DEPOSITOR's half on refund. Then the same
 // sweep takes our coins back, and the settlement is marked recovered: the money returned to the user rather
 // than leaving through the swap.
@@ -368,7 +367,7 @@ export function sweepNow(id) {
   // back.
   if (swap.settlement && !(swap.settlement.kind === "refund_eth" && swap.side === "reverse")) return swap;
   const view = derive(swap);
-  if (!view.can.sweep) throw new Error("sweep недоступен в этой фазе");
+  if (!view.can.sweep) throw new Error("sweep is not available in this phase");
   const atSim = simElapsed(swap);
   const tx = chain.sweepXmr({ swapId: swap.id });
   swap.xmr = swap.xmr || {};
@@ -384,7 +383,7 @@ export function refundEth(id, by = "you") {
   const swap = getSwap(id);
   if (!swap || swap.settlement) return swap;
   const view = derive(swap);
-  if (!view.can.refund) throw new Error("refund недоступен в этой фазе");
+  if (!view.can.refund) throw new Error("refund is not available in this phase");
   const atSim = simElapsed(swap);
   const tx = chain.refundEscrow({ swapId: swap.id, by });
   swap.settlement = { kind: "refund_eth", phase: TERMINAL.refunded_eth.phase, atSim, txHash: tx.txHash, by };
@@ -393,26 +392,26 @@ export function refundEth(id, by = "you") {
 }
 
 // ---------------------------------------------------------------------------
-// Вывод состояния
+// State output
 // ---------------------------------------------------------------------------
 
-// Живая ли сеть сделки: escrow.mode = live в конфиге сети. Настройка сети - факт, одинаковый для старых и
-// новых сделок, в отличие от поля chainMode внутри записи.
+// Whether the deal's network is live: escrow.mode = live in the network config. The network setting is a fact,
+// the same for old and new deals, unlike the chainMode field inside a record.
 function isLiveNetwork(swap) {
   const conf = (chainById((swap && swap.network) || DEFAULT_CHAIN) || {}).escrow || {};
   return conf.mode === "live";
 }
 
-// СУММА НА АДРЕСЕ ПРОТИВ ОБЕЩАННОЙ КОТИРОВКОЙ. Отметка ready разрешает забирающему расчёт по своей половине -
-// то есть отдаёт ему ETH - поэтому она делается не на "что-то пришло", а на ДОСТАТОЧНУЮ сумму. Допуск 1e-6 XMR
-// покрывает округление показа, а не скидку. Неизвестная сумма - тоже отказ: незнание не разрешение.
+// THE AMOUNT AT THE ADDRESS AGAINST THE QUOTE'S PROMISE. The ready mark lets the claimer settle by his half -
+// i.e. gives him the ETH - so it is made not on "something arrived" but on a SUFFICIENT amount. The 1e-6 XMR
+// tolerance covers display rounding, not a discount. An unknown amount is also a refusal: not knowing is not permission.
 const XMR_AMOUNT_EPS = 1e-6;
 export function xmrAmountCheck(swap, xmr) {
   const expected = Number(swap && swap.xmrAmount);
   const hasExpected = Number.isFinite(expected) && expected > 0;
-  // «УВИДЕННАЯ СУММА» - ЭТО ВСЁ, ЧТО ЛЕЖИТ НА АДРЕСЕ: и разблокированное, и запертое unlock_time. Иначе у
-  // запертого поступления сумма показывалась бы «не увидена», хотя деньги на адресе есть. Что из неё можно
-  // потратить - отдельный вопрос, и его решает статус (ready не включается, пока деньги заперты).
+  // "THE SEEN AMOUNT" IS EVERYTHING AT THE ADDRESS: both unlocked and locked by unlock_time. Otherwise a locked
+  // arrival would show its amount as "not seen", although the money is at the address. What of it can be spent
+  // is a separate question, decided by the status (ready does not enable while the money is locked).
   const seenSource = xmr && xmr.arrived !== null && xmr.arrived !== undefined ? xmr.arrived : (xmr ? xmr.received : null);
   const seen = seenSource !== null && seenSource !== undefined && Number.isFinite(Number(seenSource))
     ? Number(seenSource) : null;
@@ -424,11 +423,11 @@ export function xmrAmountCheck(swap, xmr) {
     return { ok: false, checked: true, expected, seen: null,
       why: "the amount of XMR on the address is not known (" + expected + " XMR was quoted): ready stays closed until the sum is seen" };
   }
-  // СВЕРКА ДВУСТОРОННЯЯ, И ЭТО ИСПРАВЛЕНИЕ issue #116. Прежде проверка была односторонней («пришло не
-  // меньше») и оттого СЛЕПОЙ к переплате ноды: нода считала долг по сырому эталону без спреда и отдавала
-  // 5,000 XMR там, где обещала 4,950 - приход был БОЛЬШЕ обещанного, и проверка молчала. Число, с которым
-  // сверяем, - то же, что нода кладёт долгом в журнал (amount_xmr): оно идёт от той же ленты цен, что и
-  // показанное человеку. Расхождение в ЛЮБУЮ сторону значит, что записанное и показанное - разные числа.
+  // THE COMPARISON IS TWO-SIDED, AND THIS IS A FIX. It used to be one-sided ("arrived no less") and therefore
+  // BLIND to a node overpayment: the node counted the debt by a raw reference without spread and gave 5,000 XMR
+  // where it promised 4,950 - the arrival was MORE than promised and the check stayed silent. The number we
+  // compare against is the one the node writes into the journal as the debt (amount_xmr): it comes from the same
+  // price feed as the one shown to the person. A divergence in EITHER direction means the recorded and shown numbers differ.
   if (seen + XMR_AMOUNT_EPS < expected) {
     return { ok: false, checked: true, expected, seen,
       why: "only " + seen + " XMR arrived, the quote promised " + expected + " XMR: ready is blocked - the escrow would pay out for less than agreed" };
@@ -446,35 +445,35 @@ export function derive(swap, now = nowReal()) {
   const ev = (type) => findEvent(swap, type);
   const readyEv = ev("ready");
 
-  // Слепок Monero-ноги: в мок-режиме считается по sim-времени, в live - читается из последнего
-  // опроса бэкенда. Дальше движок работает одинаково и не знает, откуда данные.
+  // The Monero-leg snapshot: in mock mode computed from sim time, in live read from the last backend poll.
+  // Beyond this the engine works the same and does not know where the data came from.
   const live = isLiveSource(swap.xmrSource);
   const xmr = xmrView(swap, sim);
-  // ПРИХОД - ЭТО ВСЁ, ЧТО ВИДНО НА АДРЕСЕ (arrived), а не только разблокированное: запертое unlock_time
-  // пришло, но потратить его нельзя - это отдельное состояние, которое называется ниже и не пускает «готово».
+  // ARRIVAL IS EVERYTHING VISIBLE AT THE ADDRESS (arrived), not just the unlocked: money locked by unlock_time
+  // has arrived but cannot be spent - a separate state, named below, that does not let "done" through.
   const arrived = Number(xmr.arrived !== undefined && xmr.arrived !== null ? xmr.arrived : (xmr.received || 0));
-  const lockAt = live ? (arrived > 0 ? 0 : null) : t.lockAtSim; // null => мейкер не лочит (сценарий maker_no_lock)
+  const lockAt = live ? (arrived > 0 ? 0 : null) : t.lockAtSim; // null => the maker does not lock (the maker_no_lock scenario)
   const conf = xmr.confirmations;
   const lockDone = live ? arrived > 0 : lockAt !== null && sim >= lockAt;
 
   const readyAt = readyEv ? readyEv.atSim : null;
-  // СРОКИ ИЗ ЦЕПИ - В НАСТОЯЩЕМ ВРЕМЕНИ: readyBy и t1 проставляет контракт, и они не имеют отношения ни к
-  // ускоренному времени демонстрации, ни к симулятору.
+  // DEADLINES FROM CHAIN - IN REAL TIME: readyBy and t1 are set by the contract and have nothing to do with the
+  // accelerated demo time or the simulator.
   const chainReadyByMs = swap.escrow && swap.escrow.readyBy ? Number(swap.escrow.readyBy) * 1000 : null;
   const chainT1Ms = swap.escrow && swap.escrow.t1 ? Number(swap.escrow.t1) * 1000 : null;
-  // ОКНО ПРОДАЖИ XMR (issue #111). Отсчёт идёт ОТ КОНТРАКТНОГО readyBy (это проставляют не мы и не симулятор),
-  // а не от TIMING.readyWindow: тот живёт в ускоренном времени демонстрации и на живой сделке показал бы
-  // демо-время. Мягкое обещание (600 с) продлевается до контрактного (1200 с), пока в пуле нет ПОЛНОЙ суммы, -
-  // тем же правилом, что у ноды (sellWindowSec). Право на действие это НЕ меняет: отметку контракт принимает
-  // до readyBy, а окно здесь - обещание на экране.
+  // THE XMR SELL WINDOW. The countdown runs FROM the contract readyBy (set by neither us nor the simulator),
+  // not from TIMING.readyWindow: that lives in the accelerated demo time and on a live deal would show demo
+  // time. The soft promise (600 s) is extended to the contract one (1200 s) while the pool lacks the FULL amount
+  // - by the same rule as the node (sellWindowSec). This does NOT change the right to act: the contract takes
+  // the mark up to readyBy, and the window here is an on-screen promise.
   const sellSeen = Number(xmr.arrived !== undefined && xmr.arrived !== null ? xmr.arrived : (xmr.received || 0)) > 0;
   const sellWindow = (() => {
     if (swap.side !== "reverse" || chainReadyByMs === null) return null;
-    const startMs = chainReadyByMs - SELL_WINDOW.hardSec * 1000;      // начало окна = readyBy минус контрактный максимум
+    const startMs = chainReadyByMs - SELL_WINDOW.hardSec * 1000;      // window start = readyBy minus the contract maximum
     const softAtMs = startMs + SELL_WINDOW.softSec * 1000;
     const windowSec = sellWindowSec({ poolSeen: sellSeen, soft: SELL_WINDOW.softSec, hard: SELL_WINDOW.hardSec });
-    const extended = !sellSeen && nowReal() >= softAtMs;             // обещание продлено до контрактного окна
-    const atMs = extended ? startMs + windowSec * 1000 : softAtMs;   // до продления счёт идёт до мягкого обещания
+    const extended = !sellSeen && nowReal() >= softAtMs;             // the promise extended to the contract window
+    const atMs = extended ? startMs + windowSec * 1000 : softAtMs;   // before the extension the count goes to the soft promise
     return { startMs, atMs, leftMs: atMs - nowReal(), seen: sellSeen, extended,
       softSec: SELL_WINDOW.softSec, hardSec: SELL_WINDOW.hardSec, windowSec };
   })();
@@ -485,10 +484,10 @@ export function derive(swap, now = nowReal()) {
   const makerReclaimAt = readyDeadline !== null ? readyDeadline + TIMING.makerReclaim : null;
   const t1At = readyAt !== null ? readyAt + TIMING.t1Refund : null;
 
-  // Сценарий «пользователь не подтвердил»: мейкер забирает XMR назад.
+  // The "user did not confirm" scenario: the maker takes the XMR back.
   const xmrReclaimed = readyAt === null && makerReclaimAt !== null && sim >= makerReclaimAt;
 
-  // Доступные действия/дедлайны
+  // Available actions/deadlines
   const can = { ready: false, sweep: false, refund: false };
   let phase = "xmr_locked";
   let phaseLabel = "Waiting";
@@ -498,7 +497,7 @@ export function derive(swap, now = nowReal()) {
   if (swap.settlement) {
     phase = swap.settlement.phase;
     phaseLabel = Object.values(TERMINAL).find((x) => x.phase === swap.settlement.phase)?.label || "Settled";
-    // SWEEPING OUR OWN XMR AFTER A REFUND (issue #118, second half). On the reverse flow a refund leaves the
+    // SWEEPING OUR OWN XMR AFTER A REFUND . On the reverse flow a refund leaves the
     // user's coins on the swap's one-time address: the claimer's ETH came back, and nobody moved the XMR. They can
     // only be taken by assembling the spend key from OUR half and the OTHER half that the chain revealed on
     // settlement. While the revealed half is missing we do NOT grant the right - can.sweep stays false precisely
@@ -517,11 +516,11 @@ export function derive(swap, now = nowReal()) {
     }
   } else if (live && readyAt === null && chainReadyByMs !== null && nowReal() >= chainReadyByMs
              && (chainT1Ms === null || nowReal() < chainT1Ms)) {
-    // БЫЛА МЁРТВАЯ ЗОНА - СТАЛА ОТКРЫТАЯ ДВЕРЬ (решение 30.09.2026). Отметку внёсший уже не поставит, забор
-    // без неё контракт запрещает, значит окно забора НЕ ОТКРЫЛОСЬ ВООБЩЕ - и возврат разрешён сразу после
-    // readyBy (условие контракта: `block.timestamp < readyBy || (block.timestamp < t1 && ready)`). Он же
-    // публикует половину внёсшего, поэтому мейкер забирает свои XMR, не дожидаясь t1. Это и есть ответ на
-    // мёртвую зону: раньше деньги и половина ждали t1, а Monero-нога была недоступна обеим сторонам.
+    // THERE WAS A DEAD ZONE - NOW AN OPEN DOOR. The depositor will not mark anymore, and the contract forbids a
+    // claim without it, so the claim window NEVER OPENED - and a refund is allowed right after readyBy (the
+    // contract condition: block.timestamp < readyBy || (block.timestamp < t1 && ready)). It also publishes the
+    // depositor's half, so the maker takes his XMR back without waiting for t1. That is the answer to the dead
+    // zone: before, the money and the half waited for t1, and the Monero leg was unavailable to both sides.
     phase = "dead_zone";
     phaseLabel = "Ready deadline passed - the refund is open";
     can.ready = false;
@@ -532,13 +531,13 @@ export function derive(swap, now = nowReal()) {
       "the XMR from Monero right away. " +
       (chainT1Ms !== null ? "T1 closes the order for good: " + new Date(chainT1Ms).toISOString() + "." : "");
   } else if (live && readyAt === null) {
-    // Live-режим: состояния Monero-ноги приходят от бэкенда. Симулированные таймауты EVM-ноги
-    // (T0/T1, watchtower) здесь намеренно НЕ показываем: контракта ещё нет, и кнопка «вернуть ETH»
-    // была бы обманом. Пометка «EVM-нога - симуляция» висит в UI отдельно (derive().simulated).
+    // Live mode: Monero-leg states come from the backend. The simulated EVM-leg timeouts (T0/T1, watchtower)
+    // are deliberately NOT shown here: the contract does not exist yet, and a "refund ETH" button would be a
+    // lie. The "EVM leg - simulation" mark hangs in the UI separately (derive().simulated).
     if (xmr.status === XMR_STATUS.LOCKED) {
-      // ДЕНЬГИ НА АДРЕСЕ ЕСТЬ, НО ЗАПЕРТЫ unlock_time. Это НАЗВАННОЕ состояние, а не «ждём приход»: иначе
-      // экран молчал бы, а сумма выглядела бы нулевой. Отметка готовности здесь невозможна - забор ETH под
-      // запертые XMR отдал бы мейкеру ETH за деньги, которыми нельзя заплатить (issue #84).
+      // THE MONEY IS AT THE ADDRESS BUT LOCKED BY unlock_time. This is a NAMED state, not "waiting for arrival":
+      // otherwise the screen would be silent and the amount would look zero. A readiness mark is impossible here
+      // - claiming ETH against locked XMR would give the maker ETH for money that cannot be paid with.
       phase = "xmr_unlock_pending";
       phaseLabel = "XMR is on your address but locked on-chain";
       can.ready = false;
@@ -560,8 +559,8 @@ export function derive(swap, now = nowReal()) {
     } else if (xmr.status === XMR_STATUS.READY) {
       phase = "xmr_locked";
       phaseLabel = "XMR received and confirmed (" + conf + "/" + t.confTarget + ")";
-      // СУММА ПРОВЕРЯЕТСЯ ВМЕСТЕ С ГОТОВНОСТЬЮ. Бэкенд видит XMR по ключу просмотра и называет сумму, а
-      // котировка обещала своё число: расхождение означает, что отметка отдала бы ETH дешевле договора.
+      // THE AMOUNT IS CHECKED TOGETHER WITH READINESS. The backend sees the XMR by the view key and names the
+      // amount, while the quote promised its own number: a divergence means the mark would give ETH cheaper than the agreement.
       const paid = xmrAmountCheck(swap, xmr);
       can.ready = paid.ok;
       can.readyAmount = paid;
@@ -577,7 +576,7 @@ export function derive(swap, now = nowReal()) {
       note = "About " + Math.max(1, Math.round(((t.confTarget - conf) * t.blockSim) / 60000)) + " min left of confirmations.";
     }
   } else if (lockAt === null) {
-    // Мейкер не залочил XMR. После T0 пользователь может вернуть ETH сам.
+    // The maker did not lock the XMR. After T0 the user can refund the ETH himself.
     if (sim >= t.t0Sim) {
       phase = "refund_available";
       phaseLabel = "Maker did not lock XMR";
@@ -619,43 +618,43 @@ export function derive(swap, now = nowReal()) {
     phaseLabel = "Secret revealed - sweeping XMR";
     can.sweep = true;
   } else {
-    // maker_stall: ready сделано, но claim не происходит
+    // maker_stall: ready is done, but no claim happens
     phase = "refund_available";
     phaseLabel = "Maker did not claim in time";
     refundAfterSim = t1At;
-    // ПРАВО НА ВОЗВРАТ ОПРЕДЕЛЯЕТ КОНТРАКТ, И ПРАВИЛО ЗАВИСИТ ОТ ВОЗРАСТА ОРДЕРА - так и надо, это не
-    // ветвление ради ветвления. Новые ордера создаются с ОДНОЙ границей t1: до неё возврата нет ни у кого,
-    // с неё - у кого угодно (решение 2026-09-16, док 26). У ордеров, созданных раньше, в записи лежит t0,
-    // и у них правило прежнее: с t0 вернуть вправе только locker, с t1 - кто угодно. Роли и сроки в старых
-    // ордерах неизменяемы, поэтому никакой миграции нет - они доживают свой срок по прежним правилам.
-    // Сравнивать надо с настоящим временем и по срокам из записи, а не по времени симулятора (оно ускорено).
-    const escrowT0 = swap.escrow && swap.escrow.t0 ? swap.escrow.t0 * 1000 : null;   // есть только у старых
+    // THE RIGHT TO REFUND IS DETERMINED BY THE CONTRACT, AND THE RULE DEPENDS ON THE ORDER'S AGE - and rightly
+    // so, this is not branching for branching's sake. New orders are created with ONE boundary t1: before it
+    // nobody may refund, from it anyone may. Orders created earlier carry t0 in their record and keep the old
+    // rule: from t0 only the locker may refund, from t1 anyone. Roles and deadlines in old orders are immutable,
+    // so there is no migration - they live out their term under the old rules. Compare against real time and by
+    // the record's deadlines, not by simulator time (which is accelerated).
+    const escrowT0 = swap.escrow && swap.escrow.t0 ? swap.escrow.t0 * 1000 : null;   // only in old orders
     const chainT1 = swap.escrow && swap.escrow.t1 ? swap.escrow.t1 * 1000 : null;
     const realNow = nowReal();
     if (chainT1 !== null) {
       if (escrowT0 !== null) {
-        can.refund = realNow >= escrowT0;                   // старый ордер: с t0, и только сам locker
-        can.refundByAnyone = realNow >= chainT1;            // с t1 - кто угодно
+        can.refund = realNow >= escrowT0;                   // an old order: from t0, and only the locker
+        can.refundByAnyone = realNow >= chainT1;            // from t1 - anyone
       } else {
-        // НОВЫЙ ОРДЕР: ГРАНИЦ ДВЕ, И ЭТО РЕШЕНИЕ 30.09.2026. С t1 - как было, возврат открыт всем. Но если
-        // отметки `ready` нет, окно забора не открылось вовсе, и возврат открыт сразу после readyBy: иначе
-        // мёртвая зона держала бы деньги и половину до t1. Отметку берём из ЗАПИСИ (`readyAt`) - её ставит сам
-        // пользователь, и в этой ветке она пуста. Если запись потеряна, а на цепи отметка есть, контракт
-        // откажет: честный отказ вместо обещания, которого мы не исполнили бы.
+        // A NEW ORDER: TWO BOUNDARIES. From t1 - as before, a refund is open to all. But if the ready mark is
+        // absent, the claim window never opened, and a refund is open right after readyBy: otherwise the dead
+        // zone would hold the money and the half until t1. The mark is taken from the RECORD (readyAt) - the
+        // user sets it himself, and in this branch it is empty. If the record is lost while the chain has the
+        // mark, the contract refuses: an honest refusal instead of a promise we would not keep.
         const chainReadyBy = swap.escrow && swap.escrow.readyBy ? Number(swap.escrow.readyBy) * 1000 : null;
         const earlyRefund = chainReadyBy !== null && realNow >= chainReadyBy && readyAt === null;
         can.refund = realNow >= chainT1 || earlyRefund;
-        can.refundByAnyone = can.refund;                    // и с t1 возврат открыт всем одновременно
-        if (earlyRefund && realNow < chainT1) refundAfterSim = null;   // возврат уже открыт: отсчёта нет
+        can.refundByAnyone = can.refund;                    // and from t1 a refund is open to all at once
+        if (earlyRefund && realNow < chainT1) refundAfterSim = null;   // the refund is already open: no countdown
       }
     } else if (!isLiveNetwork(swap)) {
-      can.refund = sim >= t1At;                             // демо-сделка: как раньше, по симулятору
+      can.refund = sim >= t1At;                             // a demo deal: as before, from the simulator
     } else {
-      can.refund = false;                                   // живая сделка без прочитанных сроков: не обещаем
+      can.refund = false;                                   // a live deal with unread deadlines: we do not promise
     }
-    // ЧТО МОЖНО СДЕЛАТЬ СЕЙЧАС - БЕЗ ОБЕЩАНИЙ, КОТОРЫХ МЫ НЕ ИСПОЛНИМ. Сторож сейчас ручной вызов, а не
-    // служба: он НЕ вернёт средства сам по себе. Поэтому говорим не "will be refunded automatically", а что
-    // право появилось у кого угодно, включая сторожа, и кнопка по-прежнему работает.
+    // WHAT CAN BE DONE NOW - WITHOUT PROMISES WE WILL NOT KEEP. The watchtower is a manual call right now, not a
+    // service: it does NOT refund by itself. So we say not "will be refunded automatically" but that the right
+    // has appeared for anyone, the watchtower included, and the button still works.
     note = can.refund
       ? (can.refundByAnyone
         ? "The claim deadline passed: the refund is open to anyone who can present the half of the depositor - " +
@@ -667,7 +666,7 @@ export function derive(swap, now = nowReal()) {
         : "Waiting for T1: before it the ETH can only be claimed with the secret. From T1 the claim closes and the refund opens - and it always pays you, never the caller.");
   }
 
-  // Шаги для степпера
+  // Steps for the stepper
   const confDone = conf >= t.confTarget;
   const claimed = claimAt !== null && sim >= claimAt;
   const steps = [
@@ -689,18 +688,18 @@ export function derive(swap, now = nowReal()) {
     conf,
     confTarget: t.confTarget,
     confProgress: t.confTarget ? conf / t.confTarget : 0,
-    // СРОКИ ДЛЯ ПОКАЗА БЕРУТСЯ ИЗ ТОГО ЖЕ ИСТОЧНИКА, ЧТО И ПРАВО НА ВОЗВРАТ - ИЗ ЗАПИСИ О СДЕЛКЕ.
-    // Здесь стояло simWall(swap, t.t0Sim): это время ДЕМО-СИМУЛЯТОРА (ускоренного в 60 раз), к живой сделке
-    // отношения не имеющее. Из-за этого получалось противоречие на одном экране: can.refund считался по
-    // НАСТОЯЩЕМУ сроку из escrow (и говорил "ещё нельзя"), а таймер кнопки и строка "T0 (refund if no XMR
-    // lock)" показывали симулированный (и говорили "available now" и "in 00:00").
-    // Два показателя одного и того же события обязаны считаться из одной величины: иначе экран противоречит
-    // сам себе, и человек не знает, какому сроку верить.
-    // Для ЖИВОЙ сделки сроки контрактные (те же, что у can.refund выше), для демонстрационной - из симулятора.
+    // THE DEADLINES FOR DISPLAY ARE TAKEN FROM THE SAME SOURCE AS THE RIGHT TO REFUND - FROM THE DEAL RECORD.
+    // Here stood simWall(swap, t.t0Sim): the DEMO SIMULATOR time (accelerated 60x), unrelated to a live deal.
+    // That produced a contradiction on one screen: can.refund was computed by the REAL deadline from escrow
+    // (saying "not yet"), while the button timer and the "T0 (refund if no XMR lock)" row showed the simulated
+    // one (saying "available now" and "in 00:00").
+    // Two indicators of the same event must be computed from one quantity: otherwise the screen contradicts
+    // itself and the person does not know which deadline to believe.
+    // For a LIVE deal the deadlines are contractual (the same as can.refund above), for a demo one - from the simulator.
     deadlines: {
-      // t0 ЕСТЬ ТОЛЬКО У СТАРЫХ ОРДЕРОВ. У новых граница одна, и для живой сделки без t0 честнее показать
-      // ничего (null), чем выдуманное число: строка T0 на экране по этому признаку и не рисуется.
-      // В демонстрационном режиме срок берётся из симулятора - там своё время, и оно осознанно ускорено.
+      // t0 EXISTS ONLY IN OLD ORDERS. New ones have one boundary, and for a live deal without t0 it is more
+      // honest to show nothing (null) than an invented number: the T0 row is not drawn on screen by this mark.
+      // In demo mode the deadline comes from the simulator - it has its own time, deliberately accelerated.
       t0: swap.escrow && swap.escrow.t0 ? swap.escrow.t0 * 1000 : (swap.escrow ? null : simWall(swap, t.t0Sim)),
       t0Sim: t.t0Sim,
       lockAtSim: lockAt,
@@ -712,13 +711,13 @@ export function derive(swap, now = nowReal()) {
       refundAfterWall: refundAfterSim !== null ? simWall(swap, refundAfterSim) : null,
     },
     refundLeftSim: refundAfterSim !== null ? refundAfterSim - sim : null,
-    // Данные Monero-ноги для экрана: статус, адрес, txid и ссылка в обозревателе.
+    // Monero-leg data for the screen: status, address, txid and an explorer link.
     xmr: {
       live: xmr.live,
       source: swap.xmrSource,
       status: xmr.status,
       received: xmr.received,
-      // Запертое unlock_time и всё, что видно на адресе: экран показывает причину и границу.
+      // Locks by unlock_time and everything visible at the address: the screen shows the cause and the boundary.
       locked: xmr.locked || 0,
       lockedUntil: xmr.lockedUntil || null,
       arrived: Number(xmr.arrived !== undefined && xmr.arrived !== null ? xmr.arrived : (xmr.received || 0)),
@@ -730,15 +729,15 @@ export function derive(swap, now = nowReal()) {
       error: xmr.error,
       sweepTxid: xmr.sweepTxid,
     },
-    // Что сейчас настоящее, а что симуляция. UI обязан показывать это, а не угадывать.
-    // EVM-нога симулирована тогда и только тогда, когда сеть сделки не переведена в live. Раньше здесь стояло
-    // жёсткое true, и на ЖИВОЙ сделке с настоящим эскроу экран писал "EVM leg ... is still simulated" - то есть
-    // врал, хотя ордер существовал в контракте. Признак берём из настроек сети, а не из поля в сделке: поле
-    // проставляется при создании, и у сделок, заведённых раньше, там осталось "mock".
+    // What is real now and what is a simulation. The UI must show this, not guess.
+    // The EVM leg is simulated if and only if the deal's network is not switched to live. It used to stand as a
+    // hard true, and on a LIVE deal with a real escrow the screen wrote "EVM leg ... is still simulated" - i.e.
+    // lied, although the order existed in the contract. The mark comes from the network settings, not from a
+    // field in the deal: the field is set at creation, and deals created earlier still have "mock" there.
     simulated: { evm: !isLiveNetwork(swap), xmr: !xmr.live },
     can,
-    // СКОЛЬКО ЖДАТЬ ДО ГРАНИЦЫ ОТМЕТКИ и не подошла ли она: граница есть, отметки нет. Предупреждение за
-    // SIGNING_GUARDS.minReadyLeadSec секунд до неё - потому что после границы не работает НИ ОДНА кнопка.
+    // HOW LONG TO THE MARK BOUNDARY and whether it has passed: the boundary exists, the mark does not. A warning
+    // SIGNING_GUARDS.minReadyLeadSec seconds before it - because after the boundary NOT ONE button works.
     readyDeadline: {
       atMs: chainReadyByMs,
       soonMs: chainReadyByMs !== null && readyAt === null ? chainReadyByMs - nowReal() : null,
@@ -746,11 +745,11 @@ export function derive(swap, now = nowReal()) {
         && chainReadyByMs - nowReal() > 0
         && chainReadyByMs - nowReal() <= Number(SIGNING_GUARDS.readyLeadWarnSec || 0) * 1000,
     },
-    // ОБЕ СУММЫ НАРУЖУ: обещанная котировкой и увиденная на адресе. Экран обязан показать обе, а не одну.
+    // BOTH AMOUNTS OUTWARD: the one promised by the quote and the one seen at the address. The screen must show both, not one.
     xmrAmount: { expected: (() => { const e = Number(swap.xmrAmount); return Number.isFinite(e) && e > 0 ? e : null; })(),
                  seen: xmr.received !== null && xmr.received !== undefined ? Number(xmr.received) : null },
     steps,
-    // ОКНО ПРОДАЖИ: адрес уже в xmr.address, здесь - отсчёт и его границы (issue #111). null у прямого потока.
+    // THE SELL WINDOW: the address is already in xmr.address, here is the countdown and its bounds. null on the direct flow.
     sellWindow,
     terminal: swap.settlement,
     xmrReclaimed,
@@ -762,8 +761,8 @@ function swappedAtOrNull(swap) {
 }
 
 // ---------------------------------------------------------------------------
-// Тикер: завершает сделки, которые должны завершиться без пользователя
-// (авто-sweep и watchtower), и рассылает подписчикам изменения.
+// The ticker: finishes deals that must finish without the user
+// (auto-sweep and watchtower) and sends changes to subscribers.
 // ---------------------------------------------------------------------------
 
 let timer = null;
@@ -781,11 +780,11 @@ function emit() {
   }
 }
 
-// --- live-режим: сессия свопа на бэкенде -----------------------------------------------
+// --- live mode: the swap session on the backend -----------------------------------------------
 //
-// Опрос идёт без ожидания: тикер экрана не должен ждать сеть, иначе при недоступном бэкенде демка
-// начнёт тормозить. Результат кладём в сам своп (xmrSession / xmrSessionError), а derive() читает
-// его как обычное состояние - она остаётся чистой функцией.
+// The poll runs without waiting: the screen ticker must not wait for the network, else with an unavailable backend
+// the demo starts to lag. The result is put into the swap itself (xmrSession / xmrSessionError), and derive()
+// reads it as ordinary state - it stays a pure function.
 const liveInFlight = new Set();
 
 function applyLive(id, patch) {
@@ -795,21 +794,21 @@ function applyLive(id, patch) {
   saveState(s);
 }
 
-// Время последней ПОПЫТКИ обращения к бэкенду по каждому свопу. Именно попытки, а не успеха: ограничение
-// частоты должно работать и когда запрос падает.
+// The time of the last ATTEMPT to reach the backend per swap. Attempts, not successes: rate limiting must work
+// even when the request fails.
 const liveLastTry = new Map();
 
 
-// КЛЮЧ СДЕЛКИ: СТРАНИЦА И ПРИЛОЖЕНИЕ НАЗЫВАЮТ ЕЁ ПО-РАЗНОМУ. У страницы свой id (живёт в браузере), у
-// приложения - свой (localtest-...): id задаёт приложение, когда заводит запись наблюдения. Состояние XMR
-// страница спрашивала по СВОЕМУ id, приложение такого не знает и отвечает отказом. Снаружи это выглядит
-// так: XMR пришли, подтверждений десяток, а экран сделки показывает прежнее состояние, кнопка отметки
-// готовности не открывается - и окно сделки закрывается впустую (проверено живым прогоном).
-// СВЯЗЫВАЕМ ПО АДРЕСУ MONERO: страница и так сообщает его приложению при заведении наблюдения, значит по
-// нему и находит свою запись, а дальше спрашивает состояние по её id. Правок в приложении не требуется.
-// ВСЕ ЗАПИСИ ОДНОЙ СДЕЛКИ В БРАУЗЕРЕ. Их две (обмен и эскроу), и следить нужно за сделкой, а не за той записью,
-// на которую случайно попал экран: у записи эскроу нет суммы ожидания XMR, поэтому её сессия не заводится, и
-// состояние до экрана не доходит. Связь - общий адрес Monero, он один на сделку.
+// THE DEAL KEY: THE PAGE AND THE APP NAME IT DIFFERENTLY. The page has its own id (lives in the browser), the
+// app its own (localtest-...): the id is set by the app when it creates the watch record. The page asked for the
+// XMR state by ITS OWN id, which the app does not know and answers with a refusal. From outside it looks like
+// this: the XMR arrived, a dozen confirmations, while the deal screen shows the previous state and the readiness
+// button does not open - and the deal window closes in vain (verified by a live run).
+// WE TIE BY THE MONERO ADDRESS: the page already reports it to the app when creating the watch, so by it the page
+// finds its record and then asks the state by its id. No change in the app is needed.
+// ALL RECORDS OF ONE DEAL IN THE BROWSER. There are two (swap and escrow), and one must follow the deal, not
+// whichever record the screen happened to land on: the escrow record has no expected XMR amount, so its session
+// is not created and the state never reaches the screen. The link is the shared Monero address, one per deal.
 export function dealSwapIds(swap) {
   const ids = new Set([String((swap && swap.id) || "")].filter(Boolean));
   const w0 = (() => { try { return halvesWalletOf(swap) || {}; } catch { return {}; } })();
@@ -825,37 +824,37 @@ export function dealSwapIds(swap) {
 
 const serverIdByAddress = new Map();
 
-// ФАКТЫ СДЕЛКИ ИЩЕМ ПО ВСЕМ ЕЁ ЗАПИСЯМ В БРАУЗЕРЕ. Об одной сделке страница держит ДВЕ записи: одну завёл
-// обмен (адрес Monero, сумма ожидания XMR), другую - эскроу (половины, адрес эскроу). Экран, открытый по
-// записи эскроу, не знал суммы ожидания, сессия не заводилась вовсе, и кнопка готовности не включалась -
-// при том что приложение готовность уже отдавало. Записи связаны ОБЩИМ адресом Monero: он один на сделку.
+// WE LOOK FOR THE DEAL'S FACTS ACROSS ALL ITS RECORDS IN THE BROWSER. The page keeps TWO records per deal: one
+// created by the swap (Monero address, expected XMR amount), another by the escrow (halves, escrow address). A
+// screen opened on the escrow record did not know the expected amount, the session was not created at all and the
+// readiness button did not turn on - although the app was already reporting readiness. The records are tied by the SHARED Monero address: one per deal.
 function dealFactsFor(swap) {
   const w0 = (() => { try { return halvesWalletOf(swap) || {}; } catch { return {}; } })();
   let address = w0.address || (swap && swap.escrow && swap.escrow.moneroAddress) || (swap && swap.xmrSession && swap.xmrSession.address) || null;
   let amountXmr = Number(swap && swap.xmrAmount) > 0 ? Number(swap.xmrAmount) : null;
-  let source = "своя запись";
+  let source = "own record";
   if (address && amountXmr === null) {
     for (const other of Object.values((loadState() || {}).swaps || {})) {
       if (!other || other === swap) continue;
       const w = (() => { try { return halvesWalletOf(other) || {}; } catch { return {}; } })();
       if (!w.address || w.address !== address) continue;
-      if (Number(other.xmrAmount) > 0) { amountXmr = Number(other.xmrAmount); source = "другая запись той же сделки (" + String(other.id || "?") + ")"; break; }
+      if (Number(other.xmrAmount) > 0) { amountXmr = Number(other.xmrAmount); source = "another record of the same deal (" + String(other.id || "?") + ")"; break; }
     }
   }
   if (!address) {
     for (const other of Object.values((loadState() || {}).swaps || {})) {
       const w = (() => { try { return halvesWalletOf(other) || {}; } catch { return {}; } })();
-      if (w.address && Number(other.xmrAmount) > 0) { address = w.address; amountXmr = amountXmr || Number(other.xmrAmount); source = "другая запись той же сделки"; break; }
+      if (w.address && Number(other.xmrAmount) > 0) { address = w.address; amountXmr = amountXmr || Number(other.xmrAmount); source = "another record of the same deal"; break; }
     }
   }
   return { address, amountXmr, source };
 }
 
-// АДРЕС СДЕЛКИ БЕРЁМ ОТОВСЮДУ, ГДЕ ОН МОЖЕТ ЛЕЖАТЬ. Сделка в браузере и запись наблюдения в приложении - это
-// РАЗНЫЕ записи об одной сделке (страница заводит свою на эскроу, приложение - на наблюдение за адресом),
-// поэтому у записи страницы адрес есть не всегда: у записи эскроу он лежит в половинах, а не в поле
-// escrow.moneroAddress. Живой прогон из-за этого опрашивал мёртвый id, получал 404 и оставлял кнопку
-// готовности выключенной. Вынесено отдельно, чтобы этим же адресом пользовался поиск высоты у сервера.
+// WE TAKE THE DEAL ADDRESS FROM EVERYWHERE IT MAY LIE. A browser deal and the app's watch record are DIFFERENT
+// records about one deal (the page creates its own for the escrow, the app one for watching the address), so the
+// page's record does not always have the address: on the escrow record it lies in the halves, not in the
+// escrow.moneroAddress field. A live run therefore polled a dead id, got 404 and left the readiness button off.
+// Extracted separately so the same address is used by the server height lookup too.
 function dealMoneroAddress(swap) {
   const fromHalves = (() => { try { return (halvesWalletOf(swap) || {}).address || null; } catch { return null; } })();
   return (swap && swap.escrow && swap.escrow.moneroAddress)
@@ -865,17 +864,17 @@ function dealMoneroAddress(swap) {
     || null;
 }
 
-// ВЫСОТА СКАНА, КОТОРУЮ ЗНАЕТ ПРИЛОЖЕНИЕ. Нужна файлам СТАРЫХ сделок: в их записи нет birthHeight (поле
-// появилось позже), а высоту при регистрации наблюдения приложение разрешило само и хранит. Источник наш,
-// поэтому от чужой ноды Monero не зависит. Сервер молчит - возвращаем null, и вызывающий остаётся на
-// прежнем поведении: высота берётся из других источников или файл честно предупреждает о её отсутствии.
+// THE SCAN HEIGHT THE APP KNOWS. Needed by OLD deals' files: their record has no birthHeight (the field appeared
+// later), while the app resolved and stored the height when registering the watch. The source is ours, so it does
+// not depend on someone else's Monero node. The server is silent - we return null and the caller keeps the
+// previous behaviour: the height comes from other sources or the file honestly warns of its absence.
 export async function serverRestoreHeightFor(swap, { attempts = 3, pauseMs = 1200 } = {}) {
   const addr = dealMoneroAddress(swap);
   if (!addr) return null;
-  // НЕ ОДНА ПОПЫТКА. Строка наблюдения появляется у приложения в тот же миг, что и эскроу, и файл может
-  // быть выпущен на волосок раньше: тогда запасной источник молчит, а в файл ложится null - и высоту взять
-  // больше негде, файл уже у владельца. Несколько коротких попыток закрывают этот зазор, а не превращают
-  // его в пустое поле; цена - доли секунды в редком случае, когда строки нет вовсе.
+  // NOT ONE ATTEMPT. The app's watch row appears the same instant as the escrow, and the file may be issued a
+  // hair earlier: then the fallback source is silent and null goes into the file - and there is nowhere else to
+  // get the height, the file is already with the owner. A few short attempts close this gap instead of turning
+  // it into an empty field; the price is fractions of a second in the rare case when there is no row at all.
   for (let i = 0; i < attempts; i++) {
     try {
       const r = await fetch("/api/swaps", { headers: { accept: "application/json" } });
@@ -887,7 +886,7 @@ export async function serverRestoreHeightFor(swap, { attempts = 3, pauseMs = 120
         if (Number.isFinite(h) && h > 0) return h;
       }
     } catch {
-      /* попробуем ещё раз: сервис мог быть занят первым обращением */
+      /* try again: the service may have been busy with the first request */
     }
     if (i < attempts - 1) await new Promise((r) => setTimeout(r, pauseMs));
   }
@@ -908,16 +907,16 @@ async function resolveServerSwapId(swap) {
     serverIdByAddress.set(addr, String(row.id));
     return String(row.id);
   } catch {
-    return null;   // сервер молчит - остаёмся на прежнем поведении, экран не ждёт сеть
+    return null;   // the server is silent - we keep the previous behaviour, the screen does not wait for the network
   }
 }
 
 function refreshLiveSession(id) {
   if (liveInFlight.has(id)) return;
-  // Не чаще одного раза в pollMs на своп, НЕЗАВИСИМО от того, сохранилась ли сессия. Раньше ограничение
-  // стояло только в ветке "сессия уже есть": если запрос падал (429 от прокси, 502 от таймаута), сессия
-  // не сохранялась, ограничение не применялось - и тик повторял запрос каждые 5 секунд по КАЖДОМУ свопу.
-  // При накопившихся восьми свопах это давало поток 429: приложение боролось само с собой.
+  // No more than once per pollMs per swap, REGARDLESS of whether the session survived. The limit used to stand
+  // only in the "session exists" branch: if the request failed (429 from the proxy, 502 from a timeout), the
+  // session was not saved, the limit did not apply - and the tick repeated the request every 5 seconds for EACH
+  // swap. With eight accumulated swaps that produced a stream of 429s: the app fought itself.
   const now = Date.now();
   const lastTry = liveLastTry.get(id) || 0;
   if (now - lastTry < pollInterval()) return;
@@ -928,18 +927,18 @@ function refreshLiveSession(id) {
       const fresh = loadState().swaps[id];
       if (!fresh || fresh.settlement) return;
       if (!fresh.xmrSession) {
-        // Кошелёк свопа создан в браузере; наружу уходят только адрес и view key (см. chainSource).
-        // СУММА ОЖИДАНИЯ ОБЯЗАТЕЛЬНА. Без неё сессию не заводим вовсе: кошелёк тот же, что у экрана
-        // подтверждения, поэтому адрес уже под наблюдением. Иначе на тот же адрес появлялась бы вторая
-        // правда об одной сделке, а запись без суммы пропускала бы недоплату. Как только сумма появится,
-        // следующий тик заведёт сессию сам.
+        // The swap wallet is created in the browser; only the address and view key go outward (see chainSource).
+        // THE EXPECTED AMOUNT IS MANDATORY. Without it we do not create a session at all: the wallet is the same
+        // as on the confirmation screen, so the address is already watched. Otherwise a second truth about one
+        // deal would appear at the same address, and a record without an amount would let an underpayment through.
+        // As soon as the amount appears, the next tick creates the session itself.
         const facts = dealFactsFor(fresh);
         const amountXmr = facts.amountXmr;
         if (!Number.isFinite(amountXmr) || amountXmr <= 0) {
-          pushLog(fresh, simElapsed(fresh), "Backend session not opened yet: amount of XMR is unknown", String((fresh && fresh.xmrAmount) ?? "нет"));
+          pushLog(fresh, simElapsed(fresh), "Backend session not opened yet: amount of XMR is unknown", String((fresh && fresh.xmrAmount) ?? "no"));
           return;
         }
-        if (facts.source !== "своя запись") {
+        if (facts.source !== "own record") {
           pushLog(fresh, simElapsed(fresh), "Amount of XMR taken from the deal's other record", facts.source + ", " + String(amountXmr));
         }
         const share = watchOnlyShareFromWallet({ swapId: fresh.id, wallet: fresh.swapWallet });
@@ -960,10 +959,10 @@ function refreshLiveSession(id) {
           applyLive(id, { xmrSessionError: opened.error });
         }
       } else if (Date.now() - (fresh.xmrSession.at || 0) >= pollInterval()) {
-        // СПРАШИВАЕМ ПО ID ПРИЛОЖЕНИЯ, а не по своему: см. resolveServerSwapId. Если запись не нашлась, НЕ
-        // спрашиваем по своему id - приложение ответит 404, и экран будет молча ждать вечно. Вместо этого
-        // заводим наблюдение заново: приложение само связывает его по адресу с уже существующей записью и
-        // возвращает её же, а не вторую правду об одной сделке.
+        // WE ASK BY THE APP'S ID, not our own: see resolveServerSwapId. If the record was not found, we do NOT
+        // ask by our own id - the app will answer 404 and the screen will silently wait forever. Instead we
+        // create the watch afresh: the app itself ties it by address to the existing record and returns the same
+        // one, not a second truth about one deal.
         const serverId = await resolveServerSwapId(fresh);
         const polled = await fetchSession(serverId || id);
         if (polled.ok) {
@@ -985,21 +984,21 @@ function refreshLiveSession(id) {
         }
       }
     } catch (e) {
-      applyLive(id, { xmrSessionError: "сессия не открылась: " + e.message });
+      applyLive(id, { xmrSessionError: "session did not open: " + e.message });
     } finally {
       liveInFlight.delete(id);
     }
   })();
 }
 
-// Сделки, которые сейчас открыты на экране. Ядро опрашивает бэкенд ТОЛЬКО по ним.
+// The deals currently open on screen. The core polls the backend ONLY for them.
 //
-// Зачем: раньше tick опрашивал все незавершённые сделки без разбора. После нескольких нажатий кнопки
-// подписи их накопилось восемь, и приложение само заваливало прокси запросами - приходил 429. При этом
-// на главной странице нечего отслеживать вообще: там ещё нет сделки.
+// Why: the tick used to poll all unfinished deals indiscriminately. After a few presses of the sign button they
+// accumulated to eight, and the app itself flooded the proxy with requests - a 429 came back. And on the main
+// page there is nothing to watch at all: there is no deal yet.
 //
-// Пустой набор (по умолчанию) означает "не опрашивать ничего". Экраны, которым слежение нужно, сообщают
-// свой набор сами: список сделок - все незавершённые, экран сделки - одну.
+// An empty set (the default) means "poll nothing". Screens that need watching report their set themselves: the
+// deal list - all unfinished, the deal screen - one.
 let liveFocusIds = new Set();
 
 export function setLiveFocus(ids) {
@@ -1014,20 +1013,20 @@ export function tick() {
   for (const swap of Object.values(s.swaps)) {
     if (swap.settlement) continue;
 
-    // Live-режим: сессия на бэкенде. Заводим при первом тике после создания свопа и дальше
-    // опрашиваем не чаще API.pollMs. Не await: экран не должен ждать сеть.
-    // Опрашиваем только то, что открыто на экране.
+    // Live mode: a session on the backend. We create it on the first tick after the swap is created and then
+    // poll no more often than API.pollMs. Not awaited: the screen must not wait for the network.
+    // We poll only what is open on screen.
     if (isLiveSource(swap.xmrSource) && liveFocusIds.has(String(swap.id))) refreshLiveSession(swap.id);
 
     const view = derive(swap);
 
-    // мейкер лочит XMR на совместном одноразовом адресе (кроме сценария maker_no_lock)
+    // the maker locks the XMR at the joint one-shot address (except the maker_no_lock scenario)
     if (!isLiveSource(swap.xmrSource) && !swap.xmr && view.deadlines.lockAtSim !== null && view.sim >= view.deadlines.lockAtSim) {
       const lock = chain.lockXmr({ swapId: swap.id, xmrAmount: swap.xmrAmount });
       swap.xmr = { ...lock, reclaimed: false, sweepTxid: null };
 
-      // В режиме live фиксируем реальную высоту нода на момент лока: по ней считаются
-      // подтверждения (блок Monero ~2 минуты, поэтому сделка идёт по-настоящему ~20 минут).
+      // In live mode we fix the node's real height at the lock moment: confirmations are counted from it
+      // (a Monero block is ~2 minutes, so the deal really takes ~20 minutes).
       if (swap.chainMode === "live") {
         const snap = node.snapshot();
         swap.xmr.lockHeight = snap ? snap.height : null;
@@ -1050,8 +1049,8 @@ export function tick() {
       changed = true;
     }
 
-    // Live-режим: первый замеченный приход XMR превращаем в запись swap.xmr с НАСТОЯЩИМ txid,
-    // чтобы остальной код (логи, шаги, экраны) работал с ним так же, как с моковым локом.
+    // Live mode: the first seen XMR arrival is turned into a swap.xmr record with the REAL txid, so the rest of
+    // the code (logs, steps, screens) works with it the same as with a mock lock.
     if (isLiveSource(swap.xmrSource) && !swap.xmr && view.xmr && view.xmr.received > 0) {
       swap.xmr = {
         mock: false,
@@ -1073,8 +1072,8 @@ export function tick() {
       changed = true;
     }
 
-    // Live-режим: факт вывода подтверждает страница sweep (watch-only кошелёк исходящие переводы
-    // видеть не может), поэтому финальное состояние берём из статуса сессии, а хеш - не выдумываем.
+    // Live mode: the withdrawal is confirmed by the sweep page (a watch-only wallet cannot see outgoing
+    // transfers), so the final state is taken from the session status, and the hash is not invented.
     if (isLiveSource(swap.xmrSource) && swap.xmrSession && swap.xmrSession.status === XMR_STATUS.SWEPT && !swap.settlement) {
       const atSim = view.sim;
       swap.settlement = {
@@ -1094,7 +1093,7 @@ export function tick() {
       continue;
     }
 
-    // happy path: после claim пользовательский кошелёк сам сметает XMR (litepaper §4.2)
+    // happy path: after claim the user's wallet sweeps the XMR itself (litepaper §4.2)
     if (!isLiveSource(swap.xmrSource) && view.can.sweep && view.phase === "success") {
       const atSim = view.sim;
       swap.xmr.sweepTxid = chain.sweepXmr({ swapId: swap.id }).txid;
@@ -1106,7 +1105,7 @@ export function tick() {
       continue;
     }
 
-    // watchtower: если пользователь ушёл, а деньги можно вернуть - возвращает он
+    // watchtower: if the user left and the money can be refunded - the watchtower does it
     if (!isLiveSource(swap.xmrSource) && view.can.refund && view.refundLeftSim !== null && view.refundLeftSim <= -TIMING.watchtowerGrace) {
       const atSim = view.sim;
       const tx = chain.refundEscrow({ swapId: swap.id, by: "watchtower" });
@@ -1118,7 +1117,7 @@ export function tick() {
       continue;
     }
 
-    // сценарий «пользователь не подтвердил»: мейкер забирает XMR
+    // the "user did not confirm" scenario: the maker takes the XMR back
     if (!isLiveSource(swap.xmrSource) && swap.xmr && view.xmrReclaimed && !swap.xmr.reclaimed) {
       swap.xmr.reclaimed = true;
       pushLog(swap, view.sim, "Maker reclaimed the XMR", swap.xmr.txid);
@@ -1145,7 +1144,7 @@ export function startTicker(intervalMs = 400) {
   if (timer) clearInterval(timer);
   timer = setInterval(() => {
     try { tick(); } catch (e) { console.error(e); }
-    emit(); // экран перерисовывается каждый тик: подтверждения и таймеры идут живьём
+    emit(); // the screen redraws every tick: confirmations and timers run live
   }, intervalMs);
 }