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

package/CHANGELOG.md

@@ -1,3 +1,66 @@
+## 0.40.0-develop.1 — 2026-10-10
+
+A build of the asynchronous route-provider work, published for the demo and for our own testing. This build does NOT
+move `latest`: install it as `@ninsei-labs/sdk@develop`, or pin this exact version.
+
+- Four asynchronous route providers: CoWSwap (settles native), KyberSwap Limit Order (settles wrapped), UniswapX
+  (settles native; publishing needs a Uniswap Trading API key and a submitter URL of your own), and the relayed
+  Uniswap route through the UniversalRouter.
+- `submitUniswapxOrder` publishes through a submitter you name; the package never carries an API key.
+- A route can be composed of two legs - liquidity to the wrapped token, then a native leg - and a provider that
+  cannot carry the route to what the person needs can never be chosen alone.
+- The engine mirror is regenerated from the source of truth, and the vendored browser bundle is rebuilt.
+
+Nothing that already existed changed behaviour: the synchronous swap path is untouched.
+
+## Unreleased — 2026-10-09
+
+THE ENGINE MIRROR IS SYNCED AGAIN AFTER THE DEMO'S BUNDLE REBUILD.
+
+- All 45 `engine/**` modules are byte-for-byte copies of the demo repository's `sdk/engine` (regenerated by
+  the demo's `tools/build-sdk-engine.mjs`). Two files changed since the previous sync, and only in the asset
+  version stamp: `engine/recovery/restore.js` (`atomic-browser.js?v=77cc4725`) and `engine/sdk/bridge.js`
+  (`sdk-browser.js?v=fbc82629`) — the demo's bundles were rebuilt after the repository-wide brand rename
+  (`Arrakis` -> `Ninsei`, English comments), so their content hashes moved.
+- No API, code table or message changed: this entry records a mirror refresh, not a behaviour change.
+
+## Unreleased
+
+THE ENGINE MIRROR (`engine/**`) CROSSES OVER IN ENGLISH, WITHOUT THE OLD BRAND AND WITHOUT A HARDCODED DOMAIN.
+All 45 modules are copied byte-for-byte from the demo repository's `sdk/engine` (`tools/build-sdk-engine.mjs`):
+comments are concise technical English and message strings are translated one to one, `Arrakis` is renamed to
+`Ninsei` (including environment constants and paths), the hardcoded domain is gone from the code - the page's own
+address comes from `location.origin` and node addresses from one named place set at deploy - and the EIP-712
+signing-domain name/version are read from the config, not from a literal in the signer.
+
+## 0.39.3 — 2026-10-09
+
+A NODE'S ADDRESS DENYLIST REFUSAL REACHES THE APP AS ITS OWN CODE, AND THE INTERFACE CAN CHECK ADDRESSES ITSELF (issue #16).
+A maker's node refuses a firm quote to an address on the maker's denylist (`PUT /v1/denylist`) and answers
+`{ok:false, code:"denied-address", why:"..."}`. Until now `quotes.firm` read the answer with `http.json`, which throws
+`server-unavailable` and LOSES the body on any non-2xx: the app was told the node was unavailable when the node had
+answered and refused, and it could not tell "did not answer" from "answered and refused".
+
+- **`quotes.firm` reads the answer as a VALUE** (`http.tryJson`, `src/quotes.mjs`): a failed CONNECTION is still
+  `server-unavailable`, while an answer that refused is its own refusal code (`quote-refused`), not "unavailable".
+- **The node's `denied-address` refusal reaches the app under the SDK code `address-denied`** (`src/codes.mjs`,
+  `index.d.ts`), WITHOUT the node's `why` text and WITHOUT the address: the node names both, and the interface shows
+  its own neutral message. A backend relaying the quote passes the node's `code` through (the demo's
+  `app/server.mjs` `/api/order-quote` relay now forwards it).
+- **A new optional address check: `createNinsei({ ..., denylist: [addresses] })`** (`src/index.mjs`, `src/quotes.mjs`,
+  `src/swaps.mjs`, `index.d.ts`). Compared WITHOUT CASE; an empty/absent list means "no check"; the SDK fetches
+  nothing - the interface brings the list in. Before `quotes.firm` the order's `locker` is checked (on a purchase the
+  claimer is the node's own address, so it is deliberately not checked); before `swaps.start` the ACTUAL sender is
+  checked - the address the funding transaction will really be sent from, read from the wallet adapter's `address()`
+  (`eth_accounts[0]`) at the moment of sending, because the person may have switched accounts. A barred address is
+  refused with `address-denied` BEFORE any request; an adapter that cannot hand out the current account is refused
+  with `bad-input` rather than skipping the policy silently.
+- Checks (`tools/check-sdk.mjs`): the node's `denied-address` answer yields `address-denied` with neither the address
+  nor the `why` in `params`; a plain refusal yields `quote-refused` while a failed connection yields
+  `server-unavailable`; a denylisted `order.locker` is refused before any request (zero calls seen); a denylisted
+  actual sender stops the lock before it signs (no transaction); the comparison is case-insensitive; an empty list
+  changes nothing. The breaking run removes the `denied-address` mapping and the pre-send check and must redden.
+
 ## Unreleased — 2026-10-08
 
 EVERY ORDER'S ESCROW IS A CLONE, AND THE CLIENT NOW CHECKS THE IMPLEMENTATION IT WILL EXECUTE (issue #114).

package/README.md

@@ -96,7 +96,7 @@ Terminal states (`state.terminal`): `success`, `refunded_eth`, `xmr_returned`, `
 ### Errors (`error.code`, `SdkError.code`)
 
 `not-implemented`, `bad-input`, `wallet-not-connected`, `wallet-rejected`, `wrong-chain`, `quote-unavailable`,
-`quote-refused`, `quote-stale`, `recovery-declined`, `recovery-failed`, `storage-unavailable`,
+`quote-refused`, `address-denied`, `quote-stale`, `recovery-declined`, `recovery-failed`, `storage-unavailable`,
 `server-unavailable`, `server-refused`, `xmr-timeout`, `xmr-locked`, `contract-reverted`, `insufficient-funds`, `unknown`.
 
 Three refusals that are easy to merge into one are named DIFFERENTLY, because the advice differs:
@@ -105,6 +105,9 @@ reason and status are in `params`; investigate); `xmr-timeout` — the wait for
 state of the money, not a breakdown); `xmr-locked` — XMR is on the address but the transaction's `unlock_time`
 barred it until a height or a date (`params.until`), so the funds are not an arrival and the ready mark is not
 signed (issue #84).
+`address-denied` (issue #16) - the address is on the interface's `denylist` (refused before any
+request) or the node's own `denied-address` refusal, WITHOUT the node's `why` text and WITHOUT the address: the
+interface shows its own neutral message.
 
 ## Quotes
 

package/engine/atomic/dleq2.js

@@ -1,32 +1,27 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/atomic/dleq2.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.
 
-// DLEQ между кривыми: доказательство, что за точками на secp256k1 и ed25519 стоит ОДИН скаляр.
-// Перенос конструкции из github.com/athanorlabs/go-dleq (prove.go, verify.go) на @noble/curves.
-// Разбор алгоритма: .hermes/docs/20-key-shares.md, разделы 14-16.
+// DLEQ ACROSS CURVES: a proof that one scalar stands behind points on secp256k1 and ed25519.
+// Ported from go-dleq (prove.go, verify.go) to @noble/curves.
+// THE CHALLENGE IS COMPUTED AS IN THE ORIGINAL: SHA3-512 and WIDE REDUCTION. The old edition used keccak256
+// (32 bytes) reduced mod the order, which was BIASED (~2^-128) and differed from the reference; named by the
+// audit and closed here. Now: a 64-byte hash, read LEAST-SIGNIFICANT first and reduced mod the order, exactly
+// what ed25519 HashToScalar does. CONSEQUENCE: old proofs do not verify, so the context version was raised
+// (ninsei-order-v3), else a live quote with an old proof would break silently.
+// STRICT SUBGROUP CHECK. ed25519 has cofactor 8, so a point may carry a small-order component; the check
+// "multiply by 8 is non-zero" lets it through and makes the equalities degenerate. We check strictly: [l]*P = 0.
+// IMPORTANT: the primitives are audited (@noble/curves), THIS implementation is not.
 //
-// ВЫЗОВ СЧИТАЕТСЯ ТАК ЖЕ, КАК В ОРИГИНАЛЕ: SHA3-512 И ШИРОКОЕ ПРИВЕДЕНИЕ. Прежняя редакция считала вызов
-// keccak256, то есть 32 байта, и приводила их по модулю порядка - приведение было СМЕЩЕНО (около 2^-128) и
-// отличалось от эталона; это названо аудитом (reports/audit-02/review_02-dleq2.md §5.1) и закрыто здесь.
-// Теперь: хеш 64 байта, читается МЛАДШИМ БАЙТОМ ВПЕРЁД и приводится по модулю порядка - ровно то, что
-// делает edwards25519 Scalar.SetUniformBytes в go-dleq (ed25519_curve.go, HashToScalar).
-// СЛЕДСТВИЕ НАЗВАНО ПРЯМО: доказательства прежнего варианта не проходят, поэтому поднята версия контекста
-// (arrakis-order-v3) - иначе живая котировка со старым доказательством молча ломалась бы.
 //
-// СТРОГАЯ ПРОВЕРКА ПОДГРУППЫ. У ed25519 кофактор 8, и точка может нести составляющую малого порядка:
-// проверка «умножение на 8 не даёт ноль» её пропускает, а именно она делает равенства вырожденными.
-// Проверяем строго: [l]*P = 0, то есть точка лежит в подгруппе простого порядка.
 //
-// ВАЖНО: примитивы аудированы (@noble/curves), ЭТА реализация - нет.
 
 export function createDleq2({ ed25519, secp256k1, keccak256, sha3_512, randomBytes }) {
-  // SHA3-512 ОБЯЗАТЕЛЕН: без него считать вызов нечем, а молчаливая подмена на keccak256 была бы ровно
-  // той ошибкой, которую здесь закрывают. Отказ громкий и сразу.
-  if (typeof sha3_512 !== "function") throw new Error("createDleq2: нужна функция sha3_512 (SHA3-512 из @noble/hashes)");
+  // SHA3-512 IS MANDATORY: without it the challenge cannot be computed, and a silent fallback to keccak256 would
+  // be exactly the bug closed here. The refusal is loud and immediate.
+  if (typeof sha3_512 !== "function") throw new Error("createDleq2: sha3_512 is required (SHA3-512 from @noble/hashes)");
   const ED_ORDER = ed25519.Point.Fn.ORDER, SEC_ORDER = secp256k1.Point.Fn.ORDER;
-  // Секрет живёт числом бит МЕНЬШЕГО порядка: так снимается ограничение ks < min(l, n).
+  // The secret lives in the bit length of the SMALLER order: this lifts the ks < min(l, n) limit.
   const BITS = Math.min(ED_ORDER.toString(2).length, SEC_ORDER.toString(2).length);
 
   const curves = {
@@ -42,28 +37,23 @@ export function createDleq2({ ed25519, secp256k1, keccak256, sha3_512, randomByt
     },
   };
 
-  // ПРЕДВЫЧИСЛЕНИЯ ДЛЯ ВТОРОЙ БАЗОВОЙ ТОЧКИ. Она умножается в каждом бите четыре раза, плюс раз на
-  // бит в обязательствах, то есть около тысячи раз на доказательство - и всё это время умножение шло
-  // БЕЗ таблицы. Измерено (tools/measure-proof-components.mjs, отдельный замер предвычислений):
-  //   без таблицы: 2,84 мс (secp256k1) и 2,86 мс (ed25519)
-  //   W=8:         0,905 мс (3,1x) и 0,422 мс (6,8x); построение таблицы 226 мс, один раз на процесс
-  // W=10 даёт ещё 13%, но построение втрое дороже (732 мс), а W=12 уже 2,4 с - на старте это заметно.
-  // true означает ленивость: здесь только запоминается размер окна, таблица построится при первом
-  // умножении. Поэтому импорт модуля не дорожает, а платит первый расчёт - и платит один раз.
+  // PRECOMPUTATION FOR THE SECOND BASE POINT. It is multiplied four times per bit, plus once in the commitments -
+  // about a thousand times per proof, all of it WITHOUT a table. Measured: without a table 2.84 ms (secp256k1) and
+  // 2.86 ms (ed25519); W=8 gives 0.905 ms and 0.422 ms with a table built once (226 ms). W=10 adds 13% but builds
+  // 3x slower; W=12 is 2.4 s. true means lazy: the table is built at the first multiplication, so importing the
+  // module is cheap and the first computation pays once.
   curves.A.Galt.precompute(8);
   curves.B.Galt.precompute(8);
 
-  // КОНТЕКСТ ИДЁТ СЫРЫМИ БАЙТАМИ UTF-8. Прежний ctxHex собирал hex из charCodeAt и отдавал его в hexBytes:
-  // для ASCII это ровно те же байты, но для любого символа выше 0x7F hex выходил длиннее двух цифр, hexBytes
-  // резал его по чётности, и доказывающий с проверяющим могли посчитать РАЗНЫЕ вызовы. Канонический контекст
-  // ордера - ASCII, поэтому живые котировки не меняются: это проверено сравнением байт (tools/check-dleq2.mjs).
-  // Кодировщик свой, а не TextEncoder: он не требует глобального объекта в среде воркера страницы.
+  // THE CONTEXT GOES IN AS RAW UTF-8 BYTES. The old ctxHex built hex from charCodeAt, which broke for any char
+  // above 0x7F (the prover and verifier could compute DIFFERENT challenges). The canonical order context is ASCII,
+  // so live quotes do not change. The encoder is our own, not TextEncoder, to avoid a global in the worker.
   const ctxUtf8 = (context) => {
     const t = String(context == null ? "" : context);
     const out = [];
     for (let i = 0; i < t.length; i++) {
       let c = t.codePointAt(i);
-      if (c > 0xffff) i++;                                  // суррогатная пара: codePointAt уже вернул её целиком
+      if (c > 0xffff) i++;                                  // surrogate pair: codePointAt already returned it whole
       if (c < 0x80) out.push(c);
       else if (c < 0x800) out.push(0xc0 | (c >> 6), 0x80 | (c & 63));
       else if (c < 0x10000) out.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 63), 0x80 | (c & 63));
@@ -80,59 +70,50 @@ export function createDleq2({ ed25519, secp256k1, keccak256, sha3_512, randomByt
   }
   const bigToHex = (v) => v.toString(16).padStart(64, "0");
   function bytesToBig(b) { let v = 0n; for (const x of b) v = (v << 8n) | BigInt(x); return v; }
-  // ЧТЕНИЕ МЛАДШИМ БАЙТОМ ВПЕРЁД - как у edwards25519 в эталоне. Это не стилистика: с обратным порядком
-  // байт вызов получился бы другим, и доказательство не сошлось бы с реализацией на другой стороне.
+  // READ LEAST-SIGNIFICANT FIRST, as ed25519 in the reference. Not style: the reverse order gives a different
+  // challenge and the proof would not match the other side.
   function bytesToBigLE(b) { let v = 0n; for (let i = b.length - 1; i >= 0; i--) v = (v << 8n) | BigInt(b[i]); return v; }
   function concat(parts) {
     const t = parts.reduce((s, p) => s + p.length, 0), out = new Uint8Array(t);
     let o = 0; for (const p of parts) { out.set(p, o); o += p.length; } return out;
   }
-  // Вызов: один и тот же preimage, но приведение к скаляру - по правилам СВОЕЙ кривой.
-  // ПРИВЯЗКА К ОРДЕРУ. Контекст (например, адрес эскроу и hashlock) входит в preimage вызова.
-  // Без него доказательство можно было бы переиспользовать в другом ордере с той же половиной:
-  // в вызове участвовали только точки и обязательства. Найдено при сверке документов, раздел 21.2.
-  // Контекст ордера НЕ здесь: он уже входит в parts через сборку preimage (см. ctxUtf8). Одна механика
-  // на обе стороны - иначе доказывающий и проверяющий считали бы вызов по-разному (так и вышло в первом
-  // варианте правки: параметр был добавлен в сигнатуру, а подставлен в один вызов из двенадцати).
+  // Challenge: the same preimage, but reduced to a scalar by each curve's own rules. The ORDER CONTEXT is not
+  // here - it enters parts via the preimage assembly. One mechanic for both sides, else the prover and verifier
+  // would compute different challenges.
   function challenge(curve, parts) {
     const h = sha3_512(concat(parts.map((p) => (typeof p === "string" ? hexBytes(p) : p))));
-    if (h.length !== 64) throw new Error("challenge: sha3_512 вернул " + h.length + " байт вместо 64");
+    if (h.length !== 64) throw new Error("challenge: sha3_512 returned " + h.length + " bytes instead of 64");
     return bytesToBigLE(h) % curve.order;
   }
-  // СЛУЧАЙНЫЙ СКАЛЯР - ТОЖЕ ШИРОКОЕ ПРИВЕДЕНИЕ: 64 случайных байта по модулю порядка, как NewRandomScalar
-  // в эталоне. Прежний цикл брал 32 байта и отбраковывал всё, что не легло в порядок: смещение около
-  // 2^-128 и лишние повторы. Ноль теоретически возможен (порядка 2^-252) и здесь заменяется единицей:
-  // для обязательств это значит лишь ненулевую случайность, а не отказ.
+  // A RANDOM SCALAR IS ALSO WIDE-REDUCED: 64 random bytes mod the order. The old loop took 32 bytes and rejected
+  // anything out of range: biased (~2^-128). Zero is theoretically possible (about 2^-252) and is replaced by one
+  // - for commitments that is just non-zero randomness, not a refusal.
   function randScalar(curve) {
     const v = bytesToBigLE(randomBytes(64)) % curve.order;
     return v === 0n ? 1n : v;
   }
   function bit(x, i) { return (x >> BigInt(i)) & 1n; }
-  // Умножение на ПУБЛИЧНЫЙ скаляр. В доказательстве DLEQ все скаляры и так входят в само доказательство,
-  // которое уходит контрагенту, поэтому постоянное время здесь не защищает ничего, а стоит дорого:
-  // измерено multiply 3.1 мс против multiplyUnsafe 0.62 мс на ed25519 (3.5 против 0.78 на secp256k1).
-  // На бит приходится около десятка умножений, и разница составляла основную часть тех 20 секунд.
+  // Multiplication by a PUBLIC scalar. In DLEQ all scalars are part of the proof the counterparty receives, so
+  // constant time protects nothing and costs a lot: multiply 3.1 ms vs multiplyUnsafe 0.62 ms on ed25519. About
+  // ten multiplications per bit, and the difference was most of those 20 seconds.
   //
-  // НОЛЬ ЗДЕСЬ ЗАКОНЕН. Это первое, что нужно знать об этой функции: нулевой бит даёт b*G при b=0, и
-  // приведённый к нулю вызов тоже встречается. Прежний код возвращал в этом случае нейтральный элемент,
-  // и это правильное поведение. Я однажды заменил его проверкой, которая бросала исключение, - и получил
-  // падение на ровном месте, потому что комментарий прежнего кода не прочитал, а только переписал.
-  // Ноль возвращает нейтральный элемент кривой, multiplyUnsafe(0) не вызывается вовсе: он бросает.
+  // ZERO IS LEGAL HERE. A zero bit gives b*G at b=0, and a zero-reduced challenge also occurs. The old code
+  // returned the neutral element, which is correct. Zero returns the curve neutral element; multiplyUnsafe(0) is
+  // not called at all - it throws.
   function mPublic(curve, point, scalar) {
-    // Скаляр приходит и числом, и hex-строкой: в доказательстве скаляры хранятся hex, чтобы переживать
-    // JSON. Обе формы приводятся здесь, в одном месте.
+    // The scalar arrives as a number or a hex string: scalars are stored as hex to survive JSON, and both forms
+    // are normalised here.
     const raw = typeof scalar === "bigint" ? scalar : BigInt(scalar);
     const s = ((raw % curve.order) + curve.order) % curve.order;
     if (s === 0n) return curve.P.ZERO;
-    // ТОЧКА С ТАБЛИЦЕЙ УМНОЖАЕТСЯ ЧЕРЕЗ multiply, остальные - через multiplyUnsafe. Это не взаимозаменяемо:
-    // multiplyUnsafe таблицу не использует и на второй базовой точке остаётся втрое-вшестеро дороже, а
-    // multiply БЕЗ таблицы, наоборот, дороже multiplyUnsafe (измерено 7,1 мс против 2,8). Поэтому выбор
-    // привязан к конкретной точке, а не к удобству вызова.
+    // A POINT WITH A TABLE IS MULTIPLIED VIA multiply, the rest via multiplyUnsafe. Not interchangeable:
+    // multiplyUnsafe ignores the table and stays 3-6x costlier on the second base point, while multiply WITHOUT
+    // a table is costlier than multiplyUnsafe (measured 7.1 ms vs 2.8). The choice is tied to the point.
     if (point === curve.Galt) return point.multiply(s);
     return point.multiplyUnsafe(s);
   }
 
-  // Точка из скаляра на второй базовой точке кривой.
+  // Point from a scalar on the second base point of the curve.
   function mul(curve, s, base) {
     return mPublic(curve, base || curve.G, typeof s === "bigint" ? s : BigInt(s));
   }
@@ -141,7 +122,7 @@ export function createDleq2({ ed25519, secp256k1, keccak256, sha3_512, randomByt
   const encP = (p) => hexBytes(p.toHex());
   const encS = (s) => hexBytes(bigToHex(s));
 
-  // Обязательства по битам: C_i = b_i*G + r_i*G' , причём Σ r_i*2^i = 0, поэтому Σ C_i*2^i = x*G.
+  // Per-bit commitments: C_i = b_i*G + r_i*G', with sum(r_i*2^i) = 0, so sum(C_i*2^i) = x*G.
   function commitments(curve, x) {
     const rs = [], cs = [];
     let sum = 0n, pow = 1n;
@@ -162,7 +143,7 @@ export function createDleq2({ ed25519, secp256k1, keccak256, sha3_512, randomByt
   function modInv(a, m) {
     let [old_r, r] = [a % m, m], [old_s, s] = [1n, 0n];
     while (r !== 0n) { const q = old_r / r; [old_r, r] = [r, old_r - q * r]; [old_s, s] = [s, old_s - q * s]; }
-    if (old_r !== 1n) throw new Error("modInv: не обратим");
+    if (old_r !== 1n) throw new Error("modInv: not invertible");
     return ((old_s % m) + m) % m;
   }
   function sumCommitments(curve, cs) {
@@ -171,11 +152,10 @@ export function createDleq2({ ed25519, secp256k1, keccak256, sha3_512, randomByt
     return sum;
   }
 
-  // OR-доказательство «обязательство к 0 или к 1» для одного бита, по обеим кривым сразу.
+  // OR proof "commitment to 0 or to 1" for one bit, on both curves at once.
   //
-  // ПРИНИМАЕТ БИТ, А НЕ ПОЛОВИНУ, и это не украшательство: биту нужен ровно один бит половины и его
-  // случайности. Из-за этого шаг САМОДОСТАТОЧЕН - ни половины, ни данных других битов он не требует, а
-  // значит именно его можно отдать другому потоку, не передавая туда ключ целиком.
+  // IT TAKES A BIT, NOT A HALF: a bit needs exactly one bit of the half and its randomness. So the step is
+  // self-contained - it needs neither the half nor other bits, so it can go to another thread without the key.
   function ringSig(bitValue, i, cA, cB, rA, rB, context) {
     const j = randScalar(curves.A), k = randScalar(curves.B);
     const pre = (p1, p2) => [ctxUtf8(context), encP(cA), encP(cB), encP(p1), encP(p2)];
@@ -199,13 +179,12 @@ export function createDleq2({ ed25519, secp256k1, keccak256, sha3_512, randomByt
     return { eA, eB, a0: (j + eA1 * rA) % curves.A.order, a1, b0: (k + eB1 * rB) % curves.B.order, b1 };
   }
 
-  // Скаляры уходят в hex: доказательство должно переживать JSON и границу потока - иначе его не передать.
+  // Scalars go to hex: the proof must survive JSON and the thread boundary.
   const sigOut = (s) => ({ eA: bigToHex(s.eA), eB: bigToHex(s.eB), a0: bigToHex(s.a0), a1: bigToHex(s.a1), b0: bigToHex(s.b0), b1: bigToHex(s.b1) });
 
-  // ШАГ 1. ПОДГОТОВКА. Считается ПОСЛЕДОВАТЕЛЬНО и целиком: обязательства зависят от накопленной суммы
-  // предыдущих, поэтому этот шаг не режется. Здесь же готовятся данные по каждому биту - ровно те, что
-  // нужны шагу 2, и ничего сверх: сам бит, его обязательства и его случайности. ПОЛОВИНЫ ЗДЕСЬ БОЛЬШЕ НЕТ,
-  // и это главное свойство: дальше её знать не требуется.
+  // STEP 1. PREPARATION. Computed SEQUENTIALLY and whole: commitments depend on the running sum, so this step is
+  // not split. Per-bit data is prepared here - exactly what step 2 needs: the bit, its commitments and its
+  // randomness. THE HALF IS NO LONGER HERE, and that is the key property.
   function prepareProof(x, context) {
     const XA = mul(curves.A, x), XB = mul(curves.B, x);
     const cA = commitments(curves.A, x), cB = commitments(curves.B, x);
@@ -221,8 +200,8 @@ export function createDleq2({ ed25519, secp256k1, keccak256, sha3_512, randomByt
     return { XA: enc(XA), XB: enc(XB), context: String(context == null ? "" : context), bits };
   }
 
-  // ШАГ 2. ДОКАЗАТЕЛЬСТВО ОДНОГО БИТА. Вызывается на подготовленных данных, самостоятелен и ничего не
-  // знает ни о половине, ни о других битах. Из-за этого шаги независимы, а значит и распараллеливаемы.
+  // STEP 2. PROVE ONE BIT. Called on the prepared data, self-contained, knowing neither the half nor other bits.
+  // So the steps are independent and parallelisable.
   function proveBit(part, context) {
     const sig = ringSig(part.bit === 1 ? 1n : 0n, part.i,
       curves.A.P.fromHex(String(part.cA).replace(/^0x/, "")),
@@ -233,79 +212,75 @@ export function createDleq2({ ed25519, secp256k1, keccak256, sha3_512, randomByt
     return { i: part.i, cA: part.cA, cB: part.cB, sig: sigOut(sig) };
   }
 
-  // ШАГ 3. СБОРКА. Складывать нечего: порядок частей и есть порядок битов, и он проверяется ниже.
+  // STEP 3. ASSEMBLE. Nothing to add: the part order IS the bit order, checked below.
   function assembleProof(prepared, parts) {
     const byIndex = new Map(parts.map((p) => [p.i, p]));
     const proofs = [];
     for (let i = 0; i < BITS; i++) {
       const item = byIndex.get(i);
-      if (!item) throw new Error("assembleProof: нет части для бита " + i);
+      if (!item) throw new Error("assembleProof: no part for bit " + i);
       proofs.push({ cA: item.cA, cB: item.cB, sig: item.sig });
     }
     return { XA: prepared.XA, XB: prepared.XB, proofs };
   }
 
-  // prove ОСТАЁТСЯ ТОЙ ЖЕ ФУНКЦИЕЙ и собрана из тех же трёх шагов: второй реализации одного и того же
-  // здесь не появилось - иначе проверки гоняли бы один код, а работал другой.
+  // prove REMAINS THE SAME FUNCTION, assembled from the same three steps: no second implementation appeared.
   function prove(x, context, onBit) {
     const prepared = prepareProof(x, context);
     const parts = [];
     for (let i = 0; i < BITS; i++) {
-      // Прогресс по ходу счёта. 253 бита - это те самые десять секунд, и без промежуточных сообщений
-      // интерфейс не может показать, что работа идёт, а не встала. Сообщаем каждые 16 бит и на последнем.
+      // Progress during the count. 253 bits is those ten seconds, and without interim messages the interface
+      // cannot show the work is running. Reported every 16 bits and at the last.
       if (onBit && (i % 16 === 0 || i === BITS - 1)) onBit(i + 1, BITS);
       parts.push(proveBit(prepared.bits[i], prepared.context));
     }
     return assembleProof(prepared, parts);
   }
 
-  // СТРОГАЯ ПРОВЕРКА ПОДГРУППЫ, А НЕ ТОЛЬКО МАЛОГО ПОРЯДКА. Прежняя редакция проверяла [8]*P != 0:
-  // точку ЧИСТО малого порядка она отвергала, а точку с малой СОСТАВЛЯЮЩЕЙ (P = Q + T, где T порядка 2, 4
-  // или 8) пропускала - и вырожденное равенство проходило. Строгое условие: [l]*P = 0, где l - порядок
-  // подгруппы. secp256k1 не проверяется: у неё кофактор 1, и вся группа простого порядка.
+  // STRICT SUBGROUP CHECK, NOT JUST SMALL ORDER. The old edition checked [8]*P != 0: it rejected a purely
+  // small-order point but let a point with a small COMPONENT through, so a degenerate equality passed. Strict:
+  // [l]*P = 0. secp256k1 is not checked: cofactor 1, the whole group is prime order.
   function torsionFree(curve, point) {
     if (curve.name !== "ed25519") return true;
-    // ЧТО ИМЕННО ЗДЕСЬ СЧИТАЕТСЯ. isTorsionFree() у @noble/curves - это ровно [n]*P = 0 (проверено по
-    // исходнику пакета: wnaf.mulUnsafe(this, CURVE.n).is0()), то есть точка лежит в подгруппе простого
-    // порядка. Своя попытка записать это через multiplyUnsafe(order) ПАДАЕТ: библиотека требует скаляр
-    // меньше порядка и на самом порядке бросает - то есть слагаемое проверки выглядело бы как отказ.
+    // WHAT IS COUNTED HERE. isTorsionFree() in @noble/curves is exactly [n]*P = 0, i.e. the point is in the
+    // prime-order subgroup. Writing it via multiplyUnsafe(order) FAILS: the library requires a scalar below the
+    // order, so the check term would look like a refusal.
     try { return point.isTorsionFree() === true; } catch { return false; }
   }
-  // ФОРМА ПРОВЕРЯЕТСЯ ДО СЧЁТА. Прежний цикл шёл по длине присланного списка: короткое доказательство
-  // доказывало ДРУГОЕ представление, длинное - жгло время проверки (доказательство ~145 КБ и так считается
-  // секундами). Честный путь всегда шлёт ровно BITS частей. Неразбираемое поле возвращает отказ, а не
-  // исключение наружу: вызывающий обязан получать {ok:false}, а не падать.
+  // FORM IS CHECKED BEFORE COUNTING. The old loop ran over the received list length: a short proof proved
+  // ANOTHER representation, a long one burned check time. An honest path always sends exactly BITS parts. An
+  // unparsable field returns a refusal, not an exception: the caller must get {ok:false}, not crash.
   function verify(proof, context) {
-    if (!proof || typeof proof !== "object") return { ok: false, reason: "доказательство: ожидается объект" };
-    if (typeof proof.XA !== "string" || typeof proof.XB !== "string") return { ok: false, reason: "доказательство: нет XA или XB" };
-    if (!Array.isArray(proof.proofs)) return { ok: false, reason: "доказательство: нет списка частей" };
-    if (proof.proofs.length !== BITS) return { ok: false, reason: "доказательство: частей " + proof.proofs.length + ", а нужно " + BITS };
+    if (!proof || typeof proof !== "object") return { ok: false, reason: "proof: an object is expected" };
+    if (typeof proof.XA !== "string" || typeof proof.XB !== "string") return { ok: false, reason: "proof: no XA or XB" };
+    if (!Array.isArray(proof.proofs)) return { ok: false, reason: "proof: no parts list" };
+    if (proof.proofs.length !== BITS) return { ok: false, reason: "proof: " + proof.proofs.length + " parts, expected " + BITS };
     const P = (curve, h) => curve.P.fromHex(String(h).replace(/^0x/, ""));
     let XA, XB, csA, csB;
     try {
       XA = P(curves.A, proof.XA); XB = P(curves.B, proof.XB);
-      if (!torsionFree(curves.B, XB)) return { ok: false, reason: "доказательство: XB не лежит в подгруппе простого порядка" };
+      if (!torsionFree(curves.B, XB)) return { ok: false, reason: "proof: XB is not in the prime-order subgroup" };
     } catch (e) {
-      return { ok: false, reason: "доказательство: XA или XB не разбирается (" + String((e && e.message) || e) + ")" };
+      return { ok: false, reason: "proof: XA or XB is unparsable (" + String((e && e.message) || e) + ")" };
     }
-    // НОМЕР БИТА НАЗЫВАЕТСЯ И ЗДЕСЬ: без него отказ «где-то в доказательстве» неотличим от порчи любого из
-    // 253 обязательств, а разбирать 145 КБ руками никто не станет.
+    // THE BIT NUMBER IS NAMED HERE TOO: without it, "somewhere in the proof" is indistinguishable from any of
+    // the 253 commitments being corrupt.
     try {
       csA = proof.proofs.map((item, i) => {
-        try { return P(curves.A, item.cA); } catch (e) { throw new Error("бит " + i + ": " + String((e && e.message) || e)); }
+        try { return P(curves.A, item.cA); } catch (e) { throw new Error("bit " + i + ": " + String((e && e.message) || e)); }
       });
       csB = proof.proofs.map((item, i) => {
-        try { return P(curves.B, item.cB); } catch (e) { throw new Error("бит " + i + ": " + String((e && e.message) || e)); }
+        try { return P(curves.B, item.cB); } catch (e) { throw new Error("bit " + i + ": " + String((e && e.message) || e)); }
       });
     } catch (e) {
-      return { ok: false, reason: "доказательство: " + String((e && e.message) || e) };
+      return { ok: false, reason: "proof: " + String((e && e.message) || e) };
     }
-    if (!sumCommitments(curves.A, csA).equals(XA)) return { ok: false, reason: "сумма обязательств не даёт X на secp256k1" };
-    if (!sumCommitments(curves.B, csB).equals(XB)) return { ok: false, reason: "сумма обязательств не даёт X на ed25519" };
+    if (!sumCommitments(curves.A, csA).equals(XA)) return { ok: false, reason: "the commitment sum does not give X on secp256k1" };
+    if (!sumCommitments(curves.B, csB).equals(XB)) return { ok: false, reason: "the commitment sum does not give X on ed25519" };
     for (let i = 0; i < proof.proofs.length; i++) {
       const item = proof.proofs[i];
       try {
-        if (!torsionFree(curves.B, csB[i])) return { ok: false, reason: "бит " + i + ": обязательство не лежит в подгруппе простого порядка" };
+        if (!torsionFree(curves.B, csB[i])) return { ok: false, reason: "bit " + i + ": the commitment is not in the prime-order subgroup" };
         const cA = item.cA, cB = item.cB;
         const sig = Object.fromEntries(Object.entries(item.sig).map(([k, v]) => [k, BigInt(String(v).startsWith("0x") ? v : "0x" + v)]));
         const pA = P(curves.A, cA), pB = P(curves.B, cB);
@@ -318,9 +293,9 @@ export function createDleq2({ ed25519, secp256k1, keccak256, sha3_512, randomByt
         const bH0 = mul(curves.B, sig.b0, curves.B.Galt), ecB = mPublic(curves.B, subP(pB, curves.B.G), eB);
         const eA0 = challenge(curves.A, pre(subP(aG0, ecA), subP(bH0, ecB)), context);
         const eB0 = challenge(curves.B, pre(subP(aG0, ecA), subP(bH0, ecB)), context);
-        if (eA0 !== sig.eA || eB0 !== sig.eB) return { ok: false, reason: "бит " + i + ": вызовы не сошлись" };
+        if (eA0 !== sig.eA || eB0 !== sig.eB) return { ok: false, reason: "bit " + i + ": challenges did not match" };
       } catch (e) {
-        return { ok: false, reason: "бит " + i + ": поля не разбираются (" + String((e && e.message) || e) + ")" };
+        return { ok: false, reason: "bit " + i + ": fields are unparsable (" + String((e && e.message) || e) + ")" };
       }
     }
     return { ok: true };