@ninsei-labs/sdk 0.39.3 → 0.40.0

package/engine/atomic/halfenc.js

@@ -1,39 +1,26 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/atomic/halfenc.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.
 
-// Передача половины ключа: зашифрованная половина, пригодная для публикации в цепи.
-// Разбор и обоснование: .hermes/docs/20-key-shares.md, разделы 5, 12.3, 16, 18.
+// Transferring a key half: an encrypted half fit for publishing on chain.
+// WHAT THIS IS. A half x is sent so that: third parties cannot read it (the mask comes from an ECDH shared secret
+// with the recipient); THE RECIPIENT can check that the ciphertext holds the half matching the published point X by
+// the simple equality x*G == X, with no separate ZK proof; and the data fits on chain.
+// THIS IS OUR COMPOSITION, not from the paper: instead of an ECDSA adaptor signature we use ECDH + mask + equality
+// check. The primitives are @noble/curves; the composition is ours.
+// THE ADAPTOR-SIGNATURE DECISION IS MADE: NOT USED. Revealing the half goes by keccak commit/reveal (commitments
+// before money, the contract verifies the half hash), and here the half is sent encrypted.
+// IMPORTANT: the primitives are audited, THIS implementation is not.
+// LOCKED UNTIL EXPLICIT PERMISSION: the encrypted-half envelope is not used in the live flow, and a dead key path
+// nobody tested in a swap is locked. SEALING AND OPENING (seal/open) ARE LOCKED, NOT THE CONSTRUCTOR: the
+// constructor is called by the live flow, so locking it would break the working path.
 //
-// ЧТО ЭТО. Половина x передаётся получателю так, что:
-//   1) третьи лица прочитать её не могут (маска выводится из общего секрета ECDH с получателем);
-//   2) ПОЛУЧАТЕЛЬ может проверить, что в шифртексте лежит именно та половина, которой соответствует
-//      опубликованная точка X - простым равенством (x*G == X), без отдельного ZK-доказательства;
-//   3) данные помещаются в цепь: точка-получателя + эфемерная точка + замаскированный скаляр.
 //
-// ЭТО НАША КОМПОЗИЦИЯ, а не перенос из статьи. В документах протокола половина передаётся адаптерной
-// подписью ECDSA (Binks, раздел про ecdsa adaptor verify/decrypt). Мы делаем проще и проверяемо:
-// ECDH + маска + проверка равенством. Стойкость примитивов - на @noble/curves, но сам состав решения - наш.
 //
-// РЕШЕНИЕ ПО АДАПТЕРНОЙ ПОДПИСИ ПРИНЯТО: ОНА НЕ ПРИМЕНЯЕТСЯ, и это выбор, а не недоделка. Раскрытие половины
-// идёт механизмом keccak commit/reveal (обязательства объявляются ДО денег, контракт сверяет хеш половины),
-// а здесь половина передаётся зашифрованной. Разбор, выгоды, цена и причина - .hermes/docs/28-adaptor-note.md,
-// раздел 8.
 //
-// ВАЖНО: примитивы аудированы, ЭТА реализация - нет.
 
-// ЗАПЕРТО ДО ЯВНОГО РАЗРЕШЕНИЯ (вывод аудитора, review_01 §P3: «удалить или запереть мёртвую ветку, чтобы
-// её не вызвали „на всякий случай“»). Посылка зашифрованной половины в живом потоке не участвует: раскрытие
-// идёт механизмом keccak commit/reveal, а половину вторая сторона получает из цепи. Мёртвая ветка, которую
-// можно позвать случайно, - это путь ключей, который никто не проверял в сделке, поэтому он заперт.
 //
-// ЗАПЕРТО ИМЕННО СОЗДАНИЕ И ВСКРЫТИЕ КОНВЕРТА (seal/open), а НЕ КОНСТРУКТОР. Разница измерена, а не
-// придумана: конструктор зовёт ЖИВОЙ поток (www/js/atomic/order.js:26 создаёт механизм, :43 берёт у него
-// ключ получателя), поэтому замок на конструкторе сломал бы рабочий путь. Мёртвое здесь - сам конверт:
-// запечатать половину и вскрыть её.
-// РАЗРЕШЕНИЕ ДАЁТСЯ ЯВНО: globalThis.ARRAKIS_ALLOW_HALFENC = true (так делает только проверка
-// tools/check-halfenc.mjs, у которой на запертость есть отдельный случай).
+// PERMISSION IS GIVEN EXPLICITLY: globalThis.ARRAKIS_ALLOW_HALFENC = true (only a check sets it, with a separate locked case).
 export const HALFENC_LOCK_REASON =
   "halfenc is locked: the sealed-half envelope is not part of the live flow (keccak commit/reveal replaced it). " +
   "Set globalThis.ARRAKIS_ALLOW_HALFENC = true to work with it in a test or a spike.";
@@ -45,7 +32,7 @@ export function halfencUnlocked() {
 export function createHalfEnc({ secp256k1, ed25519, keccak256, randomBytes }) {
   const ED_ORDER = ed25519.Point.Fn.ORDER;
   const SEC_ORDER = secp256k1.Point.Fn.ORDER;
-  const LIMIT = ED_ORDER < SEC_ORDER ? ED_ORDER : SEC_ORDER;   // маскируем в меньшем порядке
+  const LIMIT = ED_ORDER < SEC_ORDER ? ED_ORDER : SEC_ORDER;   // mask within the smaller order
 
   function bytesToBig(b) { let v = 0n; for (const x of b) v = (v << 8n) | BigInt(x); return v; }
   function randScalar(limit) {
@@ -53,18 +40,18 @@ export function createHalfEnc({ secp256k1, ed25519, keccak256, randomBytes }) {
       const v = bytesToBig(randomBytes(32));
       if (v > 0n && v < limit) return v;
     }
-    throw new Error("randScalar: не удалось за 256 попыток");
+    throw new Error("randScalar: failed in 256 attempts");
   }
   const bigToHex = (v) => v.toString(16).padStart(64, "0");
 
-  // Ключ шифрования получателя: публикуется заранее и не связан с половиной ключа траты.
+  // The encryption recipient key: published in advance and unrelated to the spend half.
   function recipientKeyPair() {
     const priv = randScalar(SEC_ORDER);
     return { priv, pub: secp256k1.Point.BASE.multiply(priv).toHex() };
   }
 
-  // Маска выводится из общего секрета ECDH: у отправителя через свою эфемерную пару и ключ получателя,
-  // у получателя - через свой приватный ключ и эфемерную точку. Формула одна и та же.
+  // The mask comes from the ECDH shared secret: the sender via its ephemeral pair and the recipient key, the
+  // recipient via its private key and the ephemeral point. Same formula.
   function maskFrom(sharedPointHex, context) {
     const h = keccak256(Uint8Array.from(Buffer.concat([
       Buffer.from(sharedPointHex.replace(/^0x/, ""), "hex"),
@@ -73,48 +60,47 @@ export function createHalfEnc({ secp256k1, ed25519, keccak256, randomBytes }) {
     return bytesToBig(h) % LIMIT;
   }
 
-  // ЗАКРЫТИЕ: половина x -> публикуемая посылка для получателя.
+  // SEAL: half x -> a publishable envelope for the recipient.
   function seal(x, recipientPubHex, context) {
-    // ЗАМОК НА САМОМ КОНВЕРТЕ: сюда попадает только мёртвая ветка, и «на всякий случай» позвать её нельзя.
+    // LOCK ON THE ENVELOPE ITSELF: only the dead branch reaches it, so it cannot be called "just in case".
     if (!halfencUnlocked()) throw new Error(HALFENC_LOCK_REASON);
-    if (!(x > 0n && x < LIMIT)) throw new Error("seal: половина вне границ min(l, n)");
+    if (!(x > 0n && x < LIMIT)) throw new Error("seal: half outside min(l, n)");
     const recipient = secp256k1.Point.fromHex(recipientPubHex.replace(/^0x/, ""));
     const ephPriv = randScalar(SEC_ORDER);
     const ephPub = secp256k1.Point.BASE.multiply(ephPriv);
-    const shared = recipient.multiply(ephPriv);                     // ECDH у отправителя
+    const shared = recipient.multiply(ephPriv);                     // ECDH on the sender
     const mask = maskFrom(shared.toHex(), context);
-    // Все hex-поля приводятся к одному виду: с префиксом 0x и в нижнем регистре. Иначе объект-посылка
-    // и результат распаковки различались бы представлением одних и тех же байт (на этом и споткнулась
-    // проверка: seal отдавал точки без префикса, а распаковка добавляла его).
+    // All hex fields are normalised: 0x prefix, lowercase. Else the envelope and the unpacked result would differ
+    // in representation of the same bytes.
     const canon = (h) => "0x" + String(h).replace(/^0x/i, "").toLowerCase();
     return {
-      recipient: canon(recipientPubHex),   // кому адресовано
-      ephemeral: canon(ephPub.toHex()),    // эфемерная точка, нужна получателю
-      masked: "0x" + bigToHex((x + mask) % LIMIT),   // замаскированный скаляр
+      recipient: canon(recipientPubHex),   // to whom it is addressed
+      ephemeral: canon(ephPub.toHex()),    // ephemeral point, needed by the recipient
+      masked: "0x" + bigToHex((x + mask) % LIMIT),   // masked scalar
       context: context || "",
     };
   }
 
-  // ВСКРЫТИЕ: получатель восстанавливает половину и ПРОВЕРЯЕТ её по опубликованной точке.
+  // OPEN: the recipient restores the half and CHECKS it against the published point.
   function open(sealed, recipientPriv, publicPointHex) {
-    // ЗАМОК И НА ВСКРЫТИИ: вторая половина той же мёртвой ветки.
+    // LOCK ON OPEN TOO: the second half of the same dead branch.
     if (!halfencUnlocked()) return { ok: false, reason: HALFENC_LOCK_REASON };
-    if (!sealed || !sealed.ephemeral || !sealed.masked) return { ok: false, reason: "посылка неполная" };
+    if (!sealed || !sealed.ephemeral || !sealed.masked) return { ok: false, reason: "incomplete envelope" };
     const eph = secp256k1.Point.fromHex(sealed.ephemeral.replace(/^0x/, ""));
-    const shared = eph.multiply(recipientPriv);                      // ECDH у получателя
+    const shared = eph.multiply(recipientPriv);                      // ECDH on the recipient
     const mask = maskFrom(shared.toHex(), sealed.context);
     const x = (BigInt(sealed.masked) - mask + LIMIT) % LIMIT;
-    if (x === 0n) return { ok: false, reason: "восстановлен ноль" };
+    if (x === 0n) return { ok: false, reason: "restored zero" };
     if (!publicPointHex) return { ok: true, x };
-    // Проверка связки "в шифртексте именно эта половина": x*G обязан совпасть с опубликованной точкой.
+    // Check the binding "the ciphertext holds exactly this half": x*G must equal the published point.
     const expect = ed25519.Point.BASE.multiply(x).toHex();
     const got = ed25519.Point.fromHex((publicPointHex.startsWith("0x") ? publicPointHex.slice(2) : publicPointHex)).toHex();
-    if (expect !== got) return { ok: false, reason: "в шифртексте не та половина" };
+    if (expect !== got) return { ok: false, reason: "the ciphertext holds a different half" };
     return { ok: true, x };
   }
 
-  // Обязательство для контракта: keccak256 тех самых байтов посылки. Живёт внутри фабрики, потому что
-  // хеш-функция передаётся ей снаружи (как и все зависимости), и снаружи видно только через этот объект.
+  // The commitment for the contract: keccak256 of the envelope bytes. It lives inside the factory, with the hash
+  // passed in from outside.
   function sealedCommitmentOf(hexBytes) {
     const h = keccak256(hexToBytesArr(hexBytes));
     return "0x" + bytesToHexStr(h);
@@ -123,21 +109,21 @@ export function createHalfEnc({ secp256k1, ed25519, keccak256, randomBytes }) {
   return { LIMIT, recipientKeyPair, seal, open, packSealed, unpackSealed, sealedCommitmentOf };
 }
 
-// --- Байтовый формат посылки ---------------------------------------------------------------
+// --- Envelope byte format ---------------------------------------------------------------
 //
-// Контракту нужны БАЙТЫ: их keccak256 идёт в sealedCommitment ордера, и те же байты уходят в
-// calldata при lock(). Формат фиксированный и однозначный, потому что от него зависит обязательство:
-// при любой другой раскладке хеш не совпадёт и блокировка будет отвергнута.
+// The contract needs BYTES: their keccak256 goes into the order's sealedCommitment and the same bytes go into
+// calldata at lock(). The format is fixed, because the commitment depends on it: any other layout changes the
+// hash and the lock is rejected.
 //
-//   0        : версия формата (1)
-//   1..33    : публичный ключ получателя шифрования (33 байта, сжатая точка secp256k1)
-//   34..66   : эфемерная точка отправителя (33 байта, сжатая)
-//   67..98   : замаскированный скаляр (32 байта, big-endian)
-//   99       : длина контекста в байтах (0..255)
-//   100..    : контекст ордера в UTF-8
+//   0        : format version (1)
+//   1..33    : encryption recipient public key (33 bytes, compressed secp256k1)
+//   34..66   : sender ephemeral point (33 bytes, compressed)
+//   67..98   : masked scalar (32 bytes, big-endian)
+//   99       : context length in bytes (0..255)
+//   100..    : order context in UTF-8
 //
-// Итого 100 + длина контекста байт. JSON здесь намеренно не используется: порядок ключей и форматирование
-// чисел дали бы разные байты для одного и того же содержимого - а обязательство требует однозначности.
+// Total 100 + context length bytes. JSON is deliberately not used: key order and number formatting would give
+// different bytes for the same content, and the commitment requires uniqueness.
 const FORMAT_VERSION = 1;
 
 function bytesToHexStr(b) {
@@ -173,28 +159,28 @@ const hexToBytesArr = (h) => {
   return out;
 };
 
-// Посылка -> байты (hex). Именно эти байты хешируются в обязательство и уходят в calldata.
+// Envelope -> bytes (hex). These bytes are hashed into the commitment and go into calldata.
 export function packSealed(sealed) {
-  if (!sealed || !sealed.recipient || !sealed.ephemeral || !sealed.masked) throw new Error("packSealed: посылка неполная");
+  if (!sealed || !sealed.recipient || !sealed.ephemeral || !sealed.masked) throw new Error("packSealed: incomplete envelope");
   const recipient = hexToBytesArr(sealed.recipient);
   const ephemeral = hexToBytesArr(sealed.ephemeral);
-  if (recipient.length !== 33) throw new Error("packSealed: ключ получателя должен быть 33 байта (сжатая точка)");
-  if (ephemeral.length !== 33) throw new Error("packSealed: эфемерная точка должна быть 33 байта (сжатая)");
+  if (recipient.length !== 33) throw new Error("packSealed: recipient key must be 33 bytes (compressed point)");
+  if (ephemeral.length !== 33) throw new Error("packSealed: ephemeral point must be 33 bytes (compressed)");
   const masked = BigInt(sealed.masked).toString(16).padStart(64, "0");
   const ctx = utf8(sealed.context);
-  if (ctx.length > 255) throw new Error("packSealed: контекст длиннее 255 байт");
+  if (ctx.length > 255) throw new Error("packSealed: context longer than 255 bytes");
   return "0x" + bytesToHexStr(Uint8Array.of(FORMAT_VERSION))
     + bytesToHexStr(recipient) + bytesToHexStr(ephemeral) + masked
     + ctx.length.toString(16).padStart(2, "0") + bytesToHexStr(ctx);
 }
 
-// Байты -> посылка. Проверяет версию и длины; повреждённые данные не разбираются молча.
+// Bytes -> envelope. Checks the version and lengths; corrupted data is not parsed silently.
 export function unpackSealed(hexBytes) {
   const b = hexToBytesArr(hexBytes);
-  if (b.length < 100) throw new Error("unpackSealed: посылка короче 100 байт");
-  if (b[0] !== FORMAT_VERSION) throw new Error("unpackSealed: неизвестная версия формата: " + b[0]);
+  if (b.length < 100) throw new Error("unpackSealed: envelope shorter than 100 bytes");
+  if (b[0] !== FORMAT_VERSION) throw new Error("unpackSealed: unknown format version: " + b[0]);
   const ctxLen = b[99];
-  if (b.length !== 100 + ctxLen) throw new Error("unpackSealed: длина не совпадает с указанной в контексте");
+  if (b.length !== 100 + ctxLen) throw new Error("unpackSealed: length does not match the one in the context");
   return {
     recipient: "0x" + bytesToHexStr(b.slice(1, 34)),
     ephemeral: "0x" + bytesToHexStr(b.slice(34, 67)),

package/engine/atomic/halves.js

@@ -1,35 +1,24 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/atomic/halves.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.
 
-// Половина ключа для атомарного свопа XMR <-> EVM.
-// См. .hermes/docs/18-xmr-swap-protocol.md, разделы 2, 3, 12, 13.
-//
-// ЧТО ЭТО. Ключ траты Monero собирается как сумма двух половин: ks = ks_a + ks_b (mod l). Потратить
-// выход можно, только зная обе половины. Одна и та же половина должна работать на двух кривых:
-// edwards25519 (Monero) и secp256k1 (EVM) - поэтому скаляр берётся МЕНЬШЕ меньшего из порядков групп
-// (статья, §4.3, формула 5: ks_i < min(l, n)). Это не деталь: именно из-за этого неравенства
-// доказательство равенства логарифмов сходится в обеих группах.
-//
-// ВАЖНО ПРО БЕЗОПАСНОСТЬ. Аудированы примитивы (@noble/curves), а НЕ этот код. Наш слой поверх них
-// проверки не проходил, и документация это фиксирует (§13). Не использовать для настоящих денег
-// до отдельного разбора.
-//
-// Зависимости передаются снаружи, как в www/js/monero/address.js: в браузере - вендоренный бандл,
-// в проверках - тот же пакет из node_modules. Модуль не тянет ничего сам.
+// Half of a Monero key for the XMR <-> EVM atomic swap.
+// The Monero spend key is the sum of two halves: ks = ks_a + ks_b (mod l); spending needs both.
+// One half must work on edwards25519 (Monero) and secp256k1 (EVM), so the scalar stays below the smaller
+// group order (min(l, n)) - that is what makes the equal-log proof converge on both groups.
+// SECURITY: the audited primitives are @noble/curves, NOT this layer. Do not use with real money before a separate review.
+// Dependencies are passed in from outside (browser: the vendored bundle; checks: node_modules). The module pulls nothing itself.
 
 export function createHalves({ ed25519, secp256k1, keccak256, randomBytes }) {
   for (const [name, v] of [["ed25519", ed25519], ["secp256k1", secp256k1], ["keccak256", keccak256], ["randomBytes", randomBytes]]) {
-    if (!v) throw new Error("createHalves: не передано " + name);
+    if (!v) throw new Error("createHalves: not passed " + name);
   }
   const ED_ORDER = ed25519.Point.Fn.ORDER;
   const SECP_ORDER = secp256k1.Point.Fn.ORDER;
-  // Меньший из порядков: половина обязана помещаться в обе группы (статья §4.3).
+  // The smaller group order: a half must fit into both groups (paper section 4.3).
   const LIMIT = ED_ORDER < SECP_ORDER ? ED_ORDER : SECP_ORDER;
 
-  // Отбор с отбраковкой: даёт равномерное распределение, в отличие от приведения по модулю,
-  // которое перекашивает вероятности в сторону малых значений.
+  // Rejection sampling gives a uniform distribution; a modulo reduction would skew it towards small values.
   function newHalf() {
     for (let i = 0; i < 256; i++) {
       const bytes = randomBytes(32);
@@ -37,34 +26,28 @@ export function createHalves({ ed25519, secp256k1, keccak256, randomBytes }) {
       for (const b of bytes) v = (v << 8n) | BigInt(b);
       if (v > 0n && v < LIMIT) return v;
     }
-    throw new Error("newHalf: не удалось получить скаляр за 256 попыток");
+    throw new Error("newHalf: could not get a scalar in 256 attempts");
   }
 
-  // ВЫВОД ПОЛОВИНЫ ИЗ СЕКРЕТА, А НЕ ИЗ СЛУЧАЙНОСТИ. Нужен ноде провайдера: она не хранит половину под
-  // каждый ордер, а выводит её заново из своего ключа и привязки к ордеру. Один и тот же ордер даёт одну
-  // и ту же половину, разные ордера - разные, посчитать может только владелец секрета.
+  // DERIVE THE HALF FROM A SECRET, NOT RANDOMNESS: the provider node derives it again from its key and the
+  // order binding, so the same order always gives the same half, and only the secret holder can compute it.
   //
-  // ОТБОР С ОТБРАКОВКОЙ, А НЕ ПРИВЕДЕНИЕ ПО МОДУЛЮ - по той же причине, что и в newHalf выше: приведение
-  // перекашивает распределение в сторону малых значений, а половина идёт в адрес Monero, где
-  // распределение обязано быть равномерным. Поэтому берём хеш, и если он не меньше порядка группы -
-  // меняем счётчик и хешируем снова. Счётчик входит в хеш, значит весь путь воспроизводим: тот же ордер
-  // при том же секрете даёт ту же половину и на той же попытке.
+  // Rejection sampling, not modulo, as in newHalf: the half feeds a Monero address and must be uniform.
+  // The attempt counter is part of the hash, so the same order and secret give the same half.
   //
-  // ПОЧЕМУ keccak, А НЕ HMAC. keccak - губка, к удлинению сообщения она невосприимчива, поэтому порядок
-  // «домен, секрет, привязка, счётчик» безопасен и не даёт из одного вывода получить другой. Так модуль
-  // остаётся без зависимости от node:crypto и работает и в браузере.
-  // Домены половин. Отсюда их берут И котирование, И выплата: разойдись строки - и нода выведет половину,
-  // которой не соответствует ни её обязательство, ни собранный адрес, и обнаружит это только отказом.
-  const HALF_DOMAIN = "arrakis-order-half-v1";          // половина ТРАТЫ
-  const VIEW_HALF_DOMAIN = "arrakis-order-view-v1";     // половина ПРОСМОТРА
+  // WHY keccak, NOT HMAC: keccak is a sponge, so the order domain/secret/binding/counter is safe, and the
+  // module needs no node:crypto (it runs in the browser too).
+  // Half domains. Quoting and payout both take them from here: if the strings diverge, the node derives a
+  // half that matches neither its commitment nor the assembled address.
+  const HALF_DOMAIN = "ninsei-order-half-v1";          // spend half
+  const VIEW_HALF_DOMAIN = "ninsei-order-view-v1";     // view half
 
   function halfFromSeed(seedBytes, binding, domain = HALF_DOMAIN) {
-    if (!seedBytes || seedBytes.length < 16) throw new Error("halfFromSeed: секрет короче 16 байт");
-    if (!binding) throw new Error("halfFromSeed: не задана привязка к ордеру");
+    if (!seedBytes || seedBytes.length < 16) throw new Error("halfFromSeed: secret shorter than 16 bytes");
+    if (!binding) throw new Error("halfFromSeed: order binding not set");
     const dom = new TextEncoder().encode(domain + "|" + String(binding) + "|");
     for (let counter = 0; counter < 256; counter++) {
-      // Счётчик попытки лежит ЯВНО и четырьмя байтами, а не подменой соседнего байта: раньше он был
-      // вписан трюком (инкремент последнего байта строки домена), и такой код читается как загадка.
+      // The attempt counter is an explicit 4-byte field, not a byte tweak.
       const input = new Uint8Array(dom.length + seedBytes.length + 4);
       input.set(dom, 0);
       input.set(seedBytes, dom.length);
@@ -77,30 +60,26 @@ export function createHalves({ ed25519, secp256k1, keccak256, randomBytes }) {
       for (const b of bytes) v = (v << 8n) | BigInt(b);
       if (v > 0n && v < LIMIT) return v;
     }
-    throw new Error("halfFromSeed: не удалось получить скаляр за 256 попыток");
+    throw new Error("halfFromSeed: could not get a scalar in 256 attempts");
   }
 
   function pointFromHex(P, hex) { return P.fromHex(hex.startsWith("0x") ? hex.slice(2) : hex); }
 
-  // ПОЛОВИНА МОЖЕТ ПРИЙТИ СТРОКОЙ, И ЭТО НОРМАЛЬНО. Файл восстановления хранит половины hex-строками
-  // (BigInt нельзя положить в JSON - на этом уже один раз молча терялась запись сделки). Значит любой
-  // вызывающий, который читает файл, обязан получить половину строкой, а арифметика кривой требует
-  // bigint. Раньше это место принимало только bigint, и восстановление из НАСТОЯЩЕГО файла падало с
-  // "expected bigint, got string" - а проверка восстановления этого не видела, потому что подавала
-  // свежие половины. Приводим здесь, в одном месте, чтобы покрыть всех вызывающих сразу.
+  // A HALF MAY COME AS A STRING, AND THAT IS NORMAL: the recovery file stores halves as hex (BigInt cannot
+  // go into JSON). Convert here to cover all callers at once.
   function toScalar(v) {
     if (typeof v === "bigint") return v;
     if (typeof v === "string") {
       const t = v.trim().replace(/^0x/, "");
-      if (!/^[0-9a-fA-F]{1,64}$/.test(t)) throw new Error("половина не похожа на число: " + v.slice(0, 12));
+      if (!/^[0-9a-fA-F]{1,64}$/.test(t)) throw new Error("half does not look like a number: " + v.slice(0, 12));
       return BigInt("0x" + t);
     }
     if (typeof v === "number") return BigInt(v);
-    throw new Error("половина неизвестного вида: " + typeof v);
+    throw new Error("half of unknown type: " + typeof v);
   }
   function hex(P) { return P.toHex(); }
 
-  // Публичные половины на обеих кривых: Ks_i = ks_i*G (edwards25519), Bs_i = ks_i*H (secp256k1).
+  // Public halves on both curves: Ks_i = ks_i*G (edwards25519), Bs_i = ks_i*H (secp256k1).
   function publicHalves(half) {
     return {
       ed: hex(ed25519.Point.BASE.multiply(toScalar(half))),
@@ -108,8 +87,7 @@ export function createHalves({ ed25519, secp256k1, keccak256, randomBytes }) {
     };
   }
 
-  // Сумма половин: и приватно (mod l), и публично (сложение точек). Второе равенство - то,
-  // на чём держится сборка общего адреса.
+  // Sum of halves: privately (mod l) and publicly (point addition). The second equality is what the joint address rests on.
   function combineHalves(a, b) { return (toScalar(a) + toScalar(b)) % ED_ORDER; }
   function combinePublic(edHexA, edHexB) {
     return hex(pointFromHex(ed25519.Point, edHexA).add(pointFromHex(ed25519.Point, edHexB)));

package/engine/atomic/order-client.js

@@ -1,14 +1,13 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/atomic/order-client.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.
 
-// Клиент воркера: превращает обмен сообщениями в обычный вызов с колбэком прогресса.
+// Worker client: turns message passing into an ordinary call with a progress callback.
 //
-// Отдельный модуль нужен, чтобы страница не знала ничего про postMessage и идентификаторы запросов:
-// она вызывает buildSide(...) и получает обещание плюс этапы.
+// A separate module is needed so the page knows nothing about postMessage and request ids:
+// it calls buildSide(...) and gets a promise plus the stages.
 export function createOrderWorker() {
-  if (typeof Worker === "undefined") throw new Error("воркеры недоступны в этом окружении");
+  if (typeof Worker === "undefined") throw new Error("workers are unavailable in this environment");
   const worker = new Worker(new URL("./order-worker.js", import.meta.url), { type: "module" });
   const pending = new Map();
   let seq = 0;
@@ -20,10 +19,10 @@ export function createOrderWorker() {
     if (msg.kind === "progress") { entry.onProgress?.(msg.stage, msg.detail); return; }
     pending.delete(msg.id);
     if (msg.kind === "done") entry.resolve(msg.result);
-    else entry.reject(new Error(msg.message || "воркер вернул ошибку"));
+    else entry.reject(new Error(msg.message || "worker returned an error"));
   };
   worker.onerror = (event) => {
-    const err = new Error("воркер упал: " + (event.message || "без сообщения"));
+    const err = new Error("worker crashed: " + (event.message || "no message"));
     for (const [, entry] of pending) entry.reject(err);
     pending.clear();
   };
@@ -40,17 +39,17 @@ export function createOrderWorker() {
     buildSide: (orderContext, onProgress) => call("newSide", { orderContext }, onProgress),
     sealHalf: (orderContext, ownHalf, encPub, onProgress) => call("seal", { orderContext, ownHalf, counterparty: { encPub } }, onProgress),
     verifyCounterparty: (orderContext, counterparty, sealedBytes, onProgress) => call("verify", { orderContext, counterparty, sealedBytes }, onProgress),
-    // Обязательство на половину. Считается в воркере, потому что там же живёт криптография: наружу
-    // уходит только хеш, половина остаётся внутри и в главный поток не попадает.
+    // Commitment to a half. Computed in the worker, because that is where the cryptography lives:
+    // only the hash goes out, the half stays inside and never reaches the main thread.
     halfCommitment: (ownHalf) => call("commit", { ownHalf }),
-    // Точка по половине: половина контрагента приходит из котировки, а для адреса нужна точка.
+    // Point from a half: the counterparty's half comes from the quote, and the address needs a point.
     pointOf: (ownHalf) => call("pointOf", { ownHalf }),
-    // Общий адрес Monero из половин - в воркере, потому что там же криптография.
+    // Joint Monero address from the halves - in the worker, because that is where the cryptography lives.
     jointAddress: (joint) => call("jointAddress", { joint }),
-    // МАТЕРИАЛ МЕЙКЕРА ОБРАТНОЙ ЗАЯВКИ: обе половины, их точки и обязательство. Доказательства здесь нет и
-    // быть не может: в обратном направлении привязку ордера назначает нода, и до билета доказывать нечего
-    // (order-worker.js, newMakerMaterial). Публичная часть уходит ноде в заявке, приватная остаётся у
-    // мейкера - ею забирают выплату и видят приход XMR.
+    // MAKER MATERIAL OF THE REVERSE REQUEST: both halves, their points and the commitment. There is no proof
+    // here and there cannot be: in the reverse direction the node assigns the order binding, and there is
+    // nothing to prove before the ticket (order-worker.js, newMakerMaterial). The public part goes to the node
+    // in the request, the private part stays with the maker - it is used to claim the payout and see XMR arrival.
     makerMaterial: () => call("newMakerMaterial"),
     stop: () => worker.terminate(),
   };