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

package/engine/core/chainSource.js

@@ -1,50 +1,38 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/core/chainSource.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.
 
-// Источник данных о Monero-ноге свопа: симулятор демки или настоящий бэкенд (app/).
-//
-// Почему отдельный модуль, а не строчки в core/swap.js: у свопа две ноги, и готовность у них разная.
-//
-//   EVM-нога (escrow, claim, refund) - СИМУЛЯЦИЯ: контракта ещё нет (этап 5). Каждый её ответ
-//   помечен mock: true, и это не косметика, а то, что обязан показать UI.
-//
-//   Monero-нога (пришёл ли XMR на адрес свопа и сколько у него подтверждений) - может быть
-//   НАСТОЯЩЕЙ: бэкенд app/ заводит watch-only кошелёк по адресу и view key и следит за
-//   поступлениями (см. app/README.md). Ключ траты при этом остаётся в браузере.
-//
-// Поэтому источник выбирается именно для Monero-ноги: 'mock' (как в демо: sim-время, без сети)
-// либо 'app' (HTTP к бэкенду). За источником идёт и сеть: у бэкенда на сервере поднят
-// stagenet-кошелёк, а мок-режим демки исторически mainnet (см. XMR_NETWORKS в config.js).
-//
-// ГРАНИЦА, ЗАКРЕПЛЁННАЯ КОДОМ: в бэкенд уходит только адрес и view key, и тело запроса
-// собирается заново по белому списку полей - так в него физически не может уехать ни ключ траты,
-// ни seed, даже если кто-то добавит их в share. Проверяется tools/check-chain-source.mjs.
+// DATA SOURCE FOR THE MONERO LEG OF THE SWAP: the demo simulator or the real backend.
+// TWO LEGS, DIFFERENT READINESS. The EVM leg (escrow, claim, refund) is a SIMULATION (no contract yet): every
+// reply is marked mock: true and the UI must show it. The Monero leg (has XMR arrived, how many confirmations)
+// can be REAL: the backend tracks a watch-only wallet by address and view key, while the spend key stays in the browser.
+// So the source is chosen for the Monero leg: 'mock' (sim-time, no network) or 'app' (HTTP to the backend).
+// A BOUNDARY PINNED BY CODE: only the address and view key go to the backend, and the request body is rebuilt from
+// a field allowlist, so neither the spend key nor the seed can leave.
 
 import { API, XMR_NETWORKS, MONERO } from "./config.js";
 import { confirmations as mockConfirmations } from "../mock/chain.js";
 
-// Статусы бэкенда (app/store.mjs) - те же строки, что отдаёт API.
+// Backend statuses - the same strings the API returns.
 export const XMR_STATUS = {
-  AWAITING: "awaiting_funding", // на адрес ещё ничего не пришло (или пришло меньше ожидаемого)
-  FUNDED: "funded", // пришло, подтверждений меньше цели
-  // ДЕНЬГИ НА АДРЕСЕ ЕСТЬ, НО ЗАПЕРТЫ unlock_time (issue #84): это НЕ приход, и «готово» в этом состоянии не
-  // включается. Отдельный статус, а не молчание и не ноль: бэкенд (app/watcher.mjs) называет его сам.
+  AWAITING: "awaiting_funding", // nothing has arrived at the address yet (or less than expected)
+  FUNDED: "funded", // arrived, confirmations below target
+  // MONEY ON THE ADDRESS BUT LOCKED by unlock_time: NOT an arrival, and 'ready' does not turn on.
+  // A separate status, named by the backend itself.
   LOCKED: "xmr_locked",
-  READY: "ready", // подтверждений достаточно: пользователь может подтверждать
-  SWEPT: "swept", // XMR выведены пользователем
-  CLOSED: "closed", // своп закрыт (отмена или возврат)
+  READY: "ready", // enough confirmations: the user can confirm readiness
+  SWEPT: "swept", // XMR withdrawn by the user
+  CLOSED: "closed", // swap closed (cancelled or refunded)
 };
 
-// Поля, которые вообще разрешено отправлять бэкенду при заведении свопа.
+// The only fields allowed to be sent to the backend when a swap is created.
 export const ALLOWED_SESSION_FIELDS = ["swapId", "network", "address", "viewKey", "expectedAmountXmr", "restoreHeight", "chain"];
 
 export function isLiveSource(source = API.xmrSource) {
   return source === "app";
 }
 
-// Сеть Monero, которую обязан использовать адрес свопа при данном источнике.
+// The Monero network the swap address must use for this source.
 export function xmrNetworkForSource(source = API.xmrSource) {
   return XMR_NETWORKS[isLiveSource(source) ? "app" : "mock"];
 }
@@ -54,18 +42,17 @@ export function xmrSourceLabel(source = API.xmrSource) {
 }
 
 // ---------------------------------------------------------------------------
-// HTTP к бэкенду
+// HTTP to the backend
 //
-// Базу можно переопределить. В браузере это не нужно: "/api" - относительный путь того же
-// origin, и CSP ("connect-src self") его покрывает. Переопределение существует для Node-тестов
-// и для случая, когда фронт отдают не с боевого хоста (в обоих случаях относительный URL не парсится).
+// The base can be overridden. In the browser this is not needed: "/api" is a relative path of the same origin
+// and the CSP (connect-src self) covers it. The override exists for Node tests and for a non-production host.
 let apiBaseOverride = null;
 export function setApiBase(base) {
   apiBaseOverride = base ? String(base).replace(/[/]$/, "") : null;
 }
 
-// Настройки опроса, которые можно переопределить: нужно тестам (там интервал в миллисекундах,
-// а не в секундах) и настройке экрана. Значения по умолчанию - из config.js.
+// Polling settings that can be overridden: needed by tests (interval in milliseconds, not seconds) and by the
+// screen. Defaults come from config.
 let pollMsOverride = null;
 export function setApiOptions({ pollMs } = {}) {
   if (Number.isFinite(Number(pollMs)) && Number(pollMs) > 0) pollMsOverride = Number(pollMs);
@@ -76,12 +63,12 @@ export function pollInterval() {
 }
 // ---------------------------------------------------------------------------
 
-// Один запрос к API. НИКОГДА не бросает: упавшая сеть - это состояние экрана, а не падение демки,
-// и пользователь должен увидеть причину, а не пустую страницу.
+// One API request. It NEVER throws: a failed network is a screen state, not a demo crash, and the user must
+// see the reason, not a blank page.
 async function api(path, { method = "GET", body, base, timeoutMs = API.timeoutMs, fetchImpl } = {}) {
   const target = base || apiBaseOverride || API.base;
   const doFetch = fetchImpl || globalThis.fetch;
-  if (typeof doFetch !== "function") return { ok: false, status: 0, error: "нет fetch: бэкенд недоступен" };
+  if (typeof doFetch !== "function") return { ok: false, status: 0, error: "no fetch: backend unavailable" };
   const ctl = typeof AbortController === "function" ? new AbortController() : null;
   const timer = ctl ? setTimeout(() => ctl.abort(), timeoutMs) : null;
   try {
@@ -101,7 +88,7 @@ async function api(path, { method = "GET", body, base, timeoutMs = API.timeoutMs
     try {
       json = text ? JSON.parse(text) : null;
     } catch {
-      /* не JSON - причину увидим из текста */
+      /* not JSON - the reason will be visible from the text */
     }
     if (!res.ok) {
       const base_ = (json && (json.error || json.detail)) || text.slice(0, 200) || `HTTP ${res.status}`;
@@ -114,14 +101,14 @@ async function api(path, { method = "GET", body, base, timeoutMs = API.timeoutMs
     return {
       ok: false,
       status: 0,
-      error: aborted ? `бэкенд не ответил за ${timeoutMs} мс` : "бэкенд недоступен: " + ((e && e.message) || e),
+      error: aborted ? `backend did not answer within ${timeoutMs} ms` : "backend unavailable: " + ((e && e.message) || e),
     };
   } finally {
     if (timer) clearTimeout(timer);
   }
 }
 
-// Ответ бэкенда -> слепок для экрана и движка состояний.
+// Backend response -> a snapshot for the screen and the state engine.
 export function normalizeSession(json) {
   const j = json || {};
   return {
@@ -132,7 +119,7 @@ export function normalizeSession(json) {
     expectedAmountXmr: j.expectedAmountXmr ?? null,
     receivedXmr: j.receivedXmr ?? "0",
     receivedAtomic: j.receivedAtomic ?? "0",
-    // ЗАПЕРТОЕ unlock_time: сумма и граница ({code,untilHeight,untilTime}) - отдельно от прихода.
+    // LOCKED unlock_time: the sum and the boundary ({code,untilHeight,untilTime}) - separate from the arrival.
     lockedXmr: j.lockedXmr ?? "0",
     lockedAtomic: j.lockedAtomic ?? "0",
     lockedUntil: j.lockedUntil || null,
@@ -145,10 +132,9 @@ export function normalizeSession(json) {
   };
 }
 
-// Заведение свопа на бэкенде. share - то, что возвращает watchOnlyShareFromWallet()
-// (recovery/restore.js): адрес + приватный view key. Ключ траты остаётся в браузере.
-// Одна и та же ли цель у свопа: сумма, валюта и сеть. Нужно, чтобы клик по Swap не заводил новый своп
-// на тот же адрес, если человек ничего не менял. Чистая функция - проверяется тестом без сети.
+// Creating a swap on the backend. share is what watchOnlyShareFromWallet() returns: address + private view key.
+// The spend key stays in the browser. The same intent (sum, currency, network) must not create a new swap on
+// the same address. A pure function - checked without a network.
 export function sameSwapTarget(a, b) {
   if (!a || !b) return false;
   return String(a.payAmount) === String(b.payAmount) &&
@@ -161,17 +147,16 @@ export async function openSession({ swapId, share, expectedAmountXmr, chain, res
   const address = src.address || null;
   const viewKey = src.viewKey || src.privateViewKey || null;
   if (!address || !viewKey) {
-    return { ok: false, status: 0, error: "в watch-only share нет address/viewKey - нечего отправлять бэкенду" };
+    return { ok: false, status: 0, error: "the watch-only share has no address/viewKey - nothing to send to the backend" };
   }
-  // СУММА ОЖИДАНИЯ ОБЯЗАТЕЛЬНА и должна быть числом. Раньше здесь стояло «не число - значит поля не будет»,
-  // и своп заводился БЕЗ суммы: сторож принимал за достаточное любое поступление, то есть недоплата
-  // выглядела как исполненная сделка. Живой своп так и остался с пустым полем. Теперь это отказ с
-  // объяснением: не завести наблюдение лучше, чем завести его без возможности проверить деньги.
+  // THE EXPECTED AMOUNT IS MANDATORY and must be a number. Before, a non-number meant no field, and the swap
+  // was created WITHOUT an amount: any arrival was accepted as enough, so an underpayment looked like a done
+  // deal. Now it is a refusal with an explanation.
   const amountXmr = Number(expectedAmountXmr);
   if (!Number.isFinite(amountXmr) || amountXmr <= 0) {
     const where = (new Error("caller").stack || "").split("\n").slice(1, 4).map((x) => x.trim().split("/").pop()).join(" <- ");
-    console.warn("[chainSource] нет суммы ожидания, вызов из: " + where);
-    return { ok: false, status: 0, error: "сумма ожидания XMR неизвестна (" + String(expectedAmountXmr) + "): без неё наблюдение не заводится" };
+    console.warn("[chainSource] no expected amount, call from: " + where);
+    return { ok: false, status: 0, error: "the expected XMR amount is unknown (" + String(expectedAmountXmr) + "): without it no watch is created" };
   }
   const wanted = {
     swapId: swapId || src.swapId || null,
@@ -182,7 +167,7 @@ export async function openSession({ swapId, share, expectedAmountXmr, chain, res
     restoreHeight: Number.isFinite(Number(restoreHeight)) && Number(restoreHeight) > 0 ? Number(restoreHeight) : Number(src.restoreHeight) || undefined,
     chain: chain || undefined,
   };
-  // Тело собираем заново по белому списку: что не в списке - в запрос не попадёт никогда.
+  // The body is rebuilt from the allowlist: what is not in the list never reaches the request.
   const body = {};
   for (const field of ALLOWED_SESSION_FIELDS) {
     if (wanted[field] !== undefined && wanted[field] !== null) body[field] = wanted[field];
@@ -198,31 +183,31 @@ export async function fetchSession(swapId, opts = {}) {
   return { ok: true, status: res.status, session: normalizeSession(res.json) };
 }
 
-// Сообщить бэкенду, что XMR выведены: хеш настоящего перевода (со страницы sweep).
-// Нужно потому, что watch-only кошелёк исходящие переводы видеть не может в принципе.
+// Tell the backend the XMR was withdrawn (the hash of the real transfer). Needed because a watch-only wallet
+// cannot see outgoing transfers.
 export async function reportSwept(swapId, txid, opts = {}) {
   const res = await api(`/swaps/${encodeURIComponent(swapId)}/swept`, { method: "POST", body: { txid }, ...opts });
   return res.ok ? { ok: true, status: res.status, session: normalizeSession(res.json) } : res;
 }
 
-// Закрыть своп (отмена или возврат на стороне бэкенда): наблюдение прекращается.
+// Close the swap (cancel or refund on the backend): the watch stops.
 export async function closeSession(swapId, reason = "cancelled", opts = {}) {
   const res = await api(`/swaps/${encodeURIComponent(swapId)}/closed`, { method: "POST", body: { reason }, ...opts });
   return res.ok ? { ok: true, status: res.status, session: normalizeSession(res.json) } : res;
 }
 
-// Состояние бэкенда: доступен ли он и видит ли кошелёк. Нужно экрану, чтобы показать «бэкенд
-// недоступен» до того, как пользователь отправит деньги, а не после.
+// Backend state: is it up and does it see the wallet. The screen needs this to show 'backend unavailable'
+// before the user sends money, not after.
 export async function health(opts = {}) {
   const res = await api("/health", opts);
   return res.ok ? { ok: true, ...res.json } : res;
 }
 
 // ---------------------------------------------------------------------------
-// Слепок Monero-ноги для движка состояний
+// The Monero-leg snapshot for the state engine
 // ---------------------------------------------------------------------------
 
-// Мок-режим: подтверждения по sim-времени, ровно как в демке было до сих пор.
+// Mock mode: confirmations by sim-time, as the demo always did.
 export function mockView(swap, simElapsedMs) {
   const confTarget = (swap.timeline && swap.timeline.confTarget) || MONERO.confirmTarget;
   const lockAt = swap.timeline ? swap.timeline.lockAtSim : 0;
@@ -238,7 +223,7 @@ export function mockView(swap, simElapsedMs) {
     live: false,
     status,
     received,
-    // В демо-симуляторе запирания unlock_time нет: приход и разблокированное - одно и то же.
+    // The demo simulator has no unlock_time lock: the arrival and the unlocked are the same.
     unlocked: received,
     locked: 0,
     lockedUntil: null,
@@ -252,8 +237,8 @@ export function mockView(swap, simElapsedMs) {
   };
 }
 
-// Живой режим: берём последний опрос бэкенда. Его кладёт тикер (swap.js), а derive() остаётся
-// чистой функцией - она читает состояние, а не ходит в сеть.
+// Live mode: take the latest backend poll, put there by the ticker; derive() stays a pure function - it reads
+// state, not the network.
 export function liveView(swap) {
   const confTarget = (swap.timeline && swap.timeline.confTarget) || MONERO.confirmTarget;
   const s = swap.xmrSession;
@@ -277,8 +262,8 @@ export function liveView(swap) {
   return {
     live: true,
     status: swap.xmrSessionError ? "error" : s.status,
-    // ПРИХОД И РАЗБЛОКИРОВАННОЕ - РАЗНЫЕ ФАКТЫ. received - то, что можно потратить (receivedXmr),
-    // locked - запертое unlock_time, arrived - всё, что видно на адресе. Состояние называет бэкенд.
+    // ARRIVAL AND UNLOCKED ARE DIFFERENT FACTS. received - what can be spent (receivedXmr); locked - unlock_time-
+    // locked; arrived - everything visible at the address. The backend names the state.
     received: Number(s.receivedXmr) || 0,
     unlocked: Number(s.receivedXmr) || 0,
     locked: Number(s.lockedXmr) || 0,
@@ -297,8 +282,8 @@ export function xmrView(swap, simElapsedMs) {
   return isLiveSource(swap && swap.xmrSource) ? liveView(swap) : mockView(swap, simElapsedMs);
 }
 
-// Ссылка на перевод в обозревателе. В live-режиме это stagenet: подписывать её как настоящие
-// деньги нельзя, поэтому сеть берём из самой сессии, а не из догадки.
+// A link to the transfer in an explorer. In live mode this is stagenet: it must not be signed as real money, so
+// the network comes from the session.
 export function explorerXmrTx(txid, network = "stagenet") {
   if (!txid) return null;
   const prefix = network === "mainnet" ? "" : network + ".";

package/engine/core/clock.js

@@ -1,17 +1,16 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/core/clock.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.
 
-// Sim-часы демки.
+// Demo sim-clock.
 //
-// Идея: реальное время сжимается множителем speed. speed=60 означает, что одна
-// реальная секунда равна одной sim-минуте. Все тайминги сделки живут в sim-времени,
-// поэтому демку можно показывать быстро, а на speed=1 она идёт в реальном темпе
-// (20-40 минут на сделку, как в литпепере).
+// Idea: real time is compressed by the speed multiplier. speed=60 means one
+// real second equals one sim-minute. All swap timings live in sim-time,
+// so the demo can be shown fast, while at speed=1 it runs at real pace
+// (20-40 minutes per swap, as in the litepaper).
 //
-// swap.realStart  - Date.now() в момент создания сделки
-// swap.simStartWall - настенное время демки в этот же момент (для отображения UTC)
+// swap.realStart    - Date.now() at the moment the swap was created
+// swap.simStartWall - the demo's wall time at that same moment (for UTC display)
 // simElapsed(swap) = (Date.now() - realStart) * speed
 
 export function nowReal() {
@@ -22,15 +21,15 @@ export function simElapsed(swap, now = nowReal()) {
   return Math.max(0, (now - swap.realStart) * swap.speed);
 }
 
-// Настенное время демки в момент, когда прошло simMs sim-времени с начала сделки.
+// The demo's wall time at the moment when simMs of sim-time has passed since the swap started.
 export function simWall(swap, simMs) {
   return swap.simStartWall + simMs;
 }
 
 
 
-// Пересчёт базовой точки при смене скорости: sim-прогресс сохраняется,
-// дальше сделка идёт с новой скоростью.
+// Rescale the base point when the speed changes: sim-progress is preserved,
+// after that the swap runs at the new speed.
 export function rescaleStart(swap, newSpeed, now = nowReal()) {
   const elapsed = simElapsed(swap, now);
   swap.speed = newSpeed;