@ninsei-labs/sdk 0.39.3 → 0.40.0

package/engine/core/finality.js

@@ -1,93 +1,74 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/core/finality.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.
 
-// ЗРЕЛОСТЬ СОСТОЯНИЯ ПО СЕТЯМ: на каком уровне цепь признаёт запись окончательной.
-//
-// ЗАЧЕМ ОТДЕЛЬНАЯ ТАБЛИЦА. Сети отличаются и временем блока, и смыслом тегов. Замер 28.09.2026 по живым
-// узлам (те самые адреса, что в настройках):
-//   arbitrum          0.267 с/блок  safe отстаёт ≈12.6 мин  finalized ≈19.6 мин
-//   arbitrum-sepolia  0.252 с/блок  safe ≈8.6 мин           finalized ≈14.9 мин
-//   mainnet          12.060 с/блок  safe ≈11.8 мин          finalized ≈18.2 мин
-//   base              2.000 с/блок  safe ≈0.4 мин           finalized ≈25.1 мин
-//   bsc               0.450 с/блок  safe и finalized отстают на 0-1 блок
-//   monad             0.302 с/блок  то же
-//   hyperevm          0.984 с/блок  то же
-// Отсюда два вывода, на которых стоит таблица:
-//   1) одно значение на все сети неверно: на base safe стоит 25 секунд, на arbitrum - 13 минут;
-//   2) на bsc, monad и hyperevm теги ФОРМАЛЬНЫ: они отвечают, но отставания нет, то есть "читать по
-//      finalized" там выглядит защитой, а защиты не даёт. Пустышку опаснее отсутствия тега: отсутствие
-//      видно, а пустышка молчит. Поэтому там - числовая глубина с НАЗВАННЫМ риском.
-//
-// ЭТА КОПИЯ - ДЛЯ СТРАНИЦЫ: она обслуживает все сети сразу, поэтому таблица нужна ей целиком.
-// Такая же таблица живёт у служб (rfq/finality.mjs); совпадение копий проверяет страж tools/check-finality.mjs,
-// потому что общего модуля у страницы и у служб быть не может.
-//
-// ОБЛАСТЬ ПРИМЕНЕНИЯ. Таблица отвечает на один вопрос: когда состояние EVM-стороны считается достаточно
-// зрелым, чтобы принять по нему НЕОБРАТИМОЕ решение - отправить XMR. Показ состояния на странице живёт по
-// latest и этой таблицей не ограничен.
+// STATE MATURITY PER NETWORK: at which level the chain treats a record as final.
+// One value for all networks is wrong: on base `safe` is ~25 s, on arbitrum ~13 min (measured on live nodes).
+// On bsc, monad and hyperevm the tags are FORMAL: they answer but lag 0-1 block, so reading by `finalized`
+// looks like protection and gives none. A named numeric depth is used there instead.
+// A twin table lives in the node; the two copies are pinned by a check.
+// SCOPE: the table answers one question - when the EVM side is mature enough for an IRREVERSIBLE decision
+// (send XMR). Displaying state on screen uses `latest` and is not limited by this.
 export const FINALITY = {
-  // ТЕГ ОСМЫСЛЕН: отставание измерено и названо.
-  "arbitrum-sepolia": { mode: "tag", tag: "safe", costSec: 520, reason: "тег осмыслен: отставание ≈8.6 мин (замер)" },
-  "arbitrum": { mode: "tag", tag: "safe", costSec: 760, reason: "тег осмыслен: отставание ≈12.6 мин (замер)" },
-  "mainnet": { mode: "tag", tag: "safe", costSec: 710, reason: "тег осмыслен: отставание ≈11.8 мин (замер)" },
-  "base": { mode: "tag", tag: "safe", costSec: 25, reason: "safe и осмыслен, и быстр: ≈25 с (замер)" },
+  // A MEANINGFUL TAG: the lag is measured and named.
+  "arbitrum-sepolia": { mode: "tag", tag: "safe", costSec: 520, reason: "tag is meaningful: lag ~8.6 min (measured)" },
+  "arbitrum": { mode: "tag", tag: "safe", costSec: 760, reason: "tag is meaningful: lag ~12.6 min (measured)" },
+  "mainnet": { mode: "tag", tag: "safe", costSec: 710, reason: "tag is meaningful: lag ~11.8 min (measured)" },
+  "base": { mode: "tag", tag: "safe", costSec: 25, reason: "safe is both meaningful and fast: ~25 s (measured)" },
 
-  // ТЕГ ПУСТЫШКА: формально отвечает, отставания нет. Числовая глубина - с названной ценой риска.
-  "bsc": { mode: "depth", depth: 15, costSec: 7, reason: "теги формальны (отставание 0-1 блок, замер): глубина ВЫБРАНА, а не измерена - риск назван" },
-  "monad": { mode: "depth", depth: 12, costSec: 4, reason: "теги формальны (отставание 0-1 блок, замер): глубина выбрана" },
-  "hyperevm": { mode: "depth", depth: 12, costSec: 12, reason: "теги формальны (отставание 0-1 блок, замер): глубина выбрана" },
+  // A FORMAL TAG: it answers, but there is no lag. A numeric depth with a named risk cost.
+  "bsc": { mode: "depth", depth: 15, costSec: 7, reason: "tags are formal (lag 0-1 block, measured): the depth is CHOSEN, not measured - risk named" },
+  "monad": { mode: "depth", depth: 12, costSec: 4, reason: "tags are formal (lag 0-1 block, measured): depth chosen" },
+  "hyperevm": { mode: "depth", depth: 12, costSec: 12, reason: "tags are formal (lag 0-1 block, measured): depth chosen" },
 };
 
-// СЕТЬ НЕ ОПИСАНА - ГОВОРИМ ОБ ЭТОМ, А НЕ ПОДСТАВЛЯЕМ МОЛЧА. Глубина 12 - прежнее общее значение, и оно
-// честнее пустого места: решение принимается, но цена риска названа как неизмеренная.
+// NETWORK NOT DESCRIBED - WE SAY SO, NOT PASTE SILENTLY. Depth 12 is the old common value and is more
+// honest than a blank: a decision is made, but the risk cost is named as unmeasured.
 export const DEFAULT_FINALITY = {
   mode: "depth", depth: 12, costSec: 0,
-  reason: "сеть не описана в таблице: берём общую глубину, риск не измерен",
+  reason: "network not described in the table: using the common depth, risk not measured",
 };
 
 export function finalityFor(network) {
   return FINALITY[network] || DEFAULT_FINALITY;
 }
 
-// Сколько эта сеть заставляет ждать перед необратимым решением - в секундах. Складывать с окнами сделки
-// (readyBy, t1) обязан тот, кто эти окна назначает: окно, которое короче ожидания, убивает сделку.
+// How long this network makes us wait before an irreversible decision, in seconds. Whoever sets the swap
+// windows (readyBy, t1) must add it: a window shorter than the wait kills the swap.
 export function finalityWaitSec(network) {
   return Number(finalityFor(network).costSec || 0);
 }
 
-// ЧТО СКАЗАТЬ ЧЕЛОВЕКУ. Строка для экрана: уровень и цена ожидания словами, без чисел-обманок.
+// WHAT TO TELL THE PERSON. A screen line: the level and the wait cost in words.
 export function finalityNote(network) {
   const f = finalityFor(network);
   if (f.mode === "tag") {
     const min = Math.max(1, Math.round(f.costSec / 60));
-    return "ждём уровень " + f.tag + ": это ≈" + min + " мин";
+    return "waiting for level " + f.tag + ": ~" + min + " min";
   }
-  return "ждём " + f.depth + " подтверждений: это ≈" + Math.max(1, Math.round(f.costSec)) + " с";
+  return "waiting for " + f.depth + " confirmations: ~" + Math.max(1, Math.round(f.costSec)) + " s";
 }
 
-// ЗНАЧОК ПРОВАЙДЕРА ДЛЯ СПИСКА. Короткий: человек решает, кого выбрать, и цена ожидания - часть выбора.
-// Свой замер важнее слов провайдера: если его уровень назван тегом, берём измеренную цену из таблицы.
+// PROVIDER BADGE FOR THE LIST. Short: the person chooses whom to pick, and the wait cost is part of it.
+// Our own measurement beats the provider's words: if its level is a tag, we take the measured cost from the table.
 export function finalityBadge(policy) {
   if (!policy) return "finality not stated";
   if (policy.mode === "tag") {
     const known = Object.values(FINALITY).find((f) => f.mode === "tag" && f.tag === policy.tag);
     const cost = Number(policy.costSec || (known && known.costSec) || 0);
-    return cost >= 60 ? policy.tag + " · ≈" + Math.round(cost / 60) + " мин" : policy.tag + " · ≈" + Math.round(cost) + " с";
+    return cost >= 60 ? policy.tag + " · ~" + Math.round(cost / 60) + " min" : policy.tag + " · ~" + Math.round(cost) + " s";
   }
   const d = Number(policy.depth || 0);
   const cost = Number(policy.costSec || d * (FINALITY[Object.keys(FINALITY)[0]] ? 0.3 : 0.3) || 0);
-  return d + " блоков · ≈" + Math.max(1, Math.round(cost)) + " с";
+  return d + " blocks · ~" + Math.max(1, Math.round(cost)) + " s";
 }
 
-// ОКНА ОРДЕРА ПО УРОВНЮ ПРОВАЙДЕРА. Окно короче ожидания убивает сделку: отметка готовности не успевает
-// попасть в контракт, и сделка распадается. Поэтому окна считаются от цены ожидания, а не берутся числом.
-// ЧИСЛА - РЕШЕНИЕ ВЛАДЕЛЬЦА (issue #88): при ПОКУПКЕ окно готовности 4 часа (человек должен успеть увидеть
-// XMR и отметиться), а окно забора ПОСЛЕ readyBy - 1 час; формула ниже держит именно эту разницу: claim на час
-// позже ready. При продаже сроки назначает нода (rfq/reverseOrder.mjs), там окно 1 час.
+// ORDER WINDOWS BY PROVIDER LEVEL. A window shorter than the wait kills the swap: the readiness mark cannot
+// reach the contract in time and the swap falls apart, so the windows are derived from the wait cost.
+// The numbers are the owner's decision: on a BUY the readiness window is 4 hours and the claim window AFTER
+// readyBy is 1 hour - the formula below keeps exactly that: claim one hour after ready. On a sell the node sets the deadlines.
 export function orderWindows(policy, base = { readyWindowSeconds: 14400, claimWindowSeconds: 3600 }) {
   const wait = Number((policy && policy.costSec) || 0);
-  const ready = Math.max(base.readyWindowSeconds, wait + 900);         // запас на внос и на дорогу транзакции
+  const ready = Math.max(base.readyWindowSeconds, wait + 900);         // margin for the deposit and tx travel
   return { readyWindowSeconds: ready, claimWindowSeconds: Math.max(base.claimWindowSeconds, ready + 3600) };
 }

package/engine/core/format.js

@@ -1,9 +1,8 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/core/format.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.
 
-// Форматирование чисел, времени и адресов.
+// Formatting of numbers, time and addresses.
 
 const nf = (min, max) => new Intl.NumberFormat("en-US", { minimumFractionDigits: min, maximumFractionDigits: max });
 
@@ -11,10 +10,10 @@ export function amount(v, dp = 2) {
   const n = Number(v);
   if (!isFinite(n)) return "-";
   const max = Math.min(dp, 6);
-  // ПЫЛЬ НЕ ИСЧЕЗАЕТ. Раньше печать была жёстко «шесть знаков», и сумма меньше 0.000001 показывалась как
-  // 0.000000 - то есть ненулевое значение выглядело нулём. Для денег это худший вид отображения: человек
-  // видит ноль там, где у него что-то есть. Знаки добавляются ровно в том случае, когда печать обнулила
-  // ненулевое, и не больше 18 (предел точности wei).
+  // DUST DOES NOT VANISH. Before, printing was hard-wired to "six digits", and an amount below 0.000001 showed as
+  // 0.000000 - a non-zero value looked like zero. For money this is the worst kind of display: the person
+  // sees zero where they actually have something. Extra digits are added only when the print zeroed a
+  // non-zero value, and never more than 18 (the wei precision limit).
   if (n !== 0 && Math.abs(n) < Math.pow(10, -max)) {
     const need = Math.min(18, Math.max(max + 1, -Math.floor(Math.log10(Math.abs(n)))));
     return nf(need, need).format(n).replace(/(\.\d*?)0+$/, "$1").replace(/\.$/, "");
@@ -49,7 +48,7 @@ export function shortHash(h, head = 6, tail = 4) {
   return s.slice(0, head) + "..." + s.slice(-tail);
 }
 
-// sim-время -> настенные часы демки (UTC, как в макетах литпепера)
+// sim-time -> the demo's wall clock (UTC, as in the litepaper mockups)
 export function clockTime(ms) {
   const d = new Date(ms);
   const hh = String(d.getUTCHours()).padStart(2, "0");
@@ -62,7 +61,7 @@ export function clockTimeShort(ms) {
   return clockTime(ms).slice(0, 5);
 }
 
-// Длительность в секундах -> "12m 30s"
+// Duration in seconds -> "12m 30s"
 export function duration(ms) {
   const total = Math.max(0, Math.round(ms / 1000));
   const m = Math.floor(total / 60);
@@ -92,49 +91,49 @@ export function randomHex(bytes = 16) {
   return toHex(a);
 }
 
-// Байты (Uint8Array/Buffer) -> hex-строка без префикса 0x.
+// Bytes (Uint8Array/Buffer) -> hex string without the 0x prefix.
 export function toHex(bytes) {
   const a = bytes instanceof Uint8Array ? bytes : Uint8Array.from(bytes || []);
   return Array.from(a, (b) => b.toString(16).padStart(2, "0")).join("");
 }
 
-// РАЗБОР СУММЫ, КОТОРУЮ ВВЁЛ ЧЕЛОВЕК.
+// PARSING AN AMOUNT ENTERED BY A PERSON.
 //
-// ПОЧЕМУ ЭТО ОТДЕЛЬНАЯ ФУНКЦИЯ, А НЕ replace ПРЯМО В ПОЛЕ. В полях суммы стояло
-// `e.target.value.replace(/[^0-9.]/g, "")`: всё, кроме цифр и точки, СТИРАЛОСЬ. Европейская запятая
-// ("0,05" - так пишут в половине стран) превращалась в "005", то есть в 5 - ошибка в СТО РАЗ, и заметить её
-// в интерфейсе почти невозможно: поле показывает "005", котировка считается по пяти, человек платит в сто
-// раз больше. Запятая без точки - десятичный разделитель, запятая при наличии точки - разделитель тысяч;
-// так же это делают кошельки Monero.
+// WHY A SEPARATE FUNCTION, NOT A replace RIGHT IN THE FIELD. The amount fields had
+// `e.target.value.replace(/[^0-9.]/g, "")`: everything but digits and a dot was ERASED. The European comma
+// ("0,05" - the way half the world writes) turned into "005", that is 5 - an error by A HUNDREDFOLD, and spotting
+// it in the interface is nearly impossible: the field shows "005", the quote is computed for five, the person pays
+// a hundred times more. A comma without a dot is a decimal separator; a comma when a dot is present is a
+// thousands separator; the Monero wallets do the same.
 //
-// Возвращает КАНОНИЧЕСКУЮ строку (только цифры и максимум одна точка). Именно её видно в поле и именно её
-// парсит остальной код - поэтому «что написано» и «что посчитано» не могут разойтись.
+// Returns a CANONICAL string (digits and at most one dot). It is exactly what is shown in the field and exactly
+// what the rest of the code parses - so "what is written" and "what is computed" cannot diverge.
 export function normalizeAmountInput(raw) {
   let s = String(raw == null ? "" : raw).trim().replace(/[^0-9.,]/g, "");
   if (s.includes(".")) {
-    // Точка есть - запятые разделяют тысячи ("1,234.5" -> "1234.5").
+    // A dot is present - commas separate thousands ("1,234.5" -> "1234.5").
     s = s.replace(/,/g, "");
   } else if (s.includes(",")) {
-    // Одна запятая без точки - десятичный разделитель ("0,05" -> "0.05"). Всё, что стоит ПОСЛЕ второй
-    // запятой, отбрасываем: угадывать, что "1,2,3" значило 123, значит на опечатке увеличить платёж в сто раз.
+    // A single comma without a dot is the decimal separator ("0,05" -> "0.05"). Everything AFTER the second
+    // comma is dropped: guessing that "1,2,3" meant 123 would, on a typo, inflate the payment a hundredfold.
     const i = s.indexOf(",");
     const rest = s.slice(i + 1);
     const cut = rest.indexOf(",");
     s = s.slice(0, i) + "." + (cut < 0 ? rest : rest.slice(0, cut));
   }
-  // Вторая точка - тоже опечатка, и хвост за ней отбрасывается, а не склеивается с числом ("1.2.3" -> "1.2").
+  // A second dot is also a typo, and the tail after it is dropped, not glued to the number ("1.2.3" -> "1.2").
   const dot = s.indexOf(".");
   if (dot >= 0) {
     const rest = s.slice(dot + 1);
     const cut = rest.indexOf(".");
     s = s.slice(0, dot + 1) + (cut < 0 ? rest : rest.slice(0, cut));
   }
-  s = s.replace(/^0+(?=\d)/, "");                     // "005" -> "5", но "0.5" не трогаем
+  s = s.replace(/^0+(?=\d)/, "");                     // "005" -> "5", but "0.5" is left alone
   if (!/[0-9]/.test(s)) return "";
   return s;
 }
 
-/** Число из введённого человеком или null, если числа там нет. Никаких «догадок»: пусто - значит пусто. */
+/** Number from a human-entered value, or null if there is no number. No "guessing": empty means empty. */
 export function parseAmount(raw) {
   const s = normalizeAmountInput(raw);
   if (!s) return null;
@@ -143,22 +142,22 @@ export function parseAmount(raw) {
 }
 
 export function shortId() {
-  // 16 hex-символов (8 байт = 2^64). Раньше было 4 символа (randomHex(2)): при 100 000 сделок совпадение
-  // практически неизбежно - 68.8% на 8 символах и 100% на 4, - а id служит ключом в состоянии и именем файла
-  // восстановления, поэтому совпадение означало бы потерю записи, за которой стоят средства.
-  // ВАЖНО: у уже созданных сделок id остаются короткими. Переименовывать их нельзя: id лежит в файле
-  // восстановления, в ссылках и в состоянии - они бы разъехались.
+  // 16 hex chars (8 bytes = 2^64). Before it was 4 chars (randomHex(2)): with 100 000 swaps a collision is
+  // practically inevitable - 68.8% at 8 chars and 100% at 4 - and the id is a key in the state and the name of
+  // the recovery file, so a collision would mean losing a record that backs funds.
+  // IMPORTANT: already-created swaps keep short ids. They must not be renamed: the id lives in the recovery
+  // file, in links and in the state - they would fall out of sync.
   return randomHex(8);
 }
 
-// БЫСТРАЯ ПРИКИДКА ФОРМЫ Monero-адреса: base58, длина 95 (обычный) / 106 (integrated), префикс сети.
+// QUICK CHECK OF A Monero ADDRESS SHAPE: base58, length 95 (plain) / 106 (integrated), network prefix.
 //
-// ЧЕГО ЭТА ФУНКЦИЯ НЕ ДЕЛАЕТ: НЕ ПРОВЕРЯЕТ КОНТРОЛЬНУЮ СУММУ. Любая опечатка внутри адреса пройдёт здесь
-// незамеченной. Раньше она называлась isValidMoneroAddress - и это имя было ловушкой: функция, которую
-// зовут "проверкой адреса", но которая пропускает опечатку, рано или поздно попадает на путь денег.
+// WHAT THIS FUNCTION DOES NOT DO: IT DOES NOT VERIFY THE CHECKSUM. Any typo inside the address passes here
+// unnoticed. It used to be named isValidMoneroAddress - and that name was a trap: a function called
+// "address check" that lets a typo through ends up on the money path sooner or later.
 //
-// НАСТОЯЩАЯ ПРОВЕРКА - checkAddress() из ../monero/address.js: формат + разбор base58 + keccak256-контрольная
-// сумма + совпадение сети. Именно её зовёт форма. Здесь - только чтобы отсеять явный мусор до тяжёлого разбора.
+// THE REAL CHECK IS checkAddress() from ../monero/address.js: format + base58 decode + keccak256 checksum
+// + network match. The form calls that one. This one only screens out obvious garbage before the heavy decode.
 export function looksLikeMoneroAddress(addr) {
   const a = String(addr || "").trim();
   if (![95, 106].includes(a.length)) return false;