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

package/engine/recovery/recoveryFile.js

@@ -1,96 +1,92 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/recovery/recoveryFile.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.
 
-// Recovery-файл сделки: реальная криптография в браузере (WebCrypto).
+// The deal recovery file: real cryptography in the browser (WebCrypto).
 //
-// Litepaper §5: без сохранённого recovery-файла сделка не фондируется; если вкладка
-// потеряна, этот файл - единственный способ забрать XMR или вернуть ETH (в том числе
-// через standalone-клиент без сайта). Поэтому здесь настоящий AES-GCM, а не заглушка:
-// файл можно расшифровать только паролем, который знает пользователь.
+// Litepaper §5: without a saved recovery file a deal is not funded; if the tab is lost, this file is the only way
+// to claim the XMR or refund the ETH (including through a standalone client without the site). So it is real
+// AES-GCM, not a stub: the file can be decrypted only with the password the user knows.
 //
-// Формат файла (Arrakis-swap-<id>.json.enc):
+// File format (Ninsei-swap-<id>.json.enc):
 //   { v:2, alg:"AES-GCM-256/PBKDF2-SHA256", iter, salt, iv, ciphertext, meta:{id,side,createdAt} }
-// Внутри ciphertext - payload (см. buildPayload), и его формат версионирован отдельно:
-// версия оболочки (v) и версия payload (version) меняются независимо - шифрование и
-// содержимое сделки это разные вещи.
+// Inside ciphertext is the payload (see buildPayload), versioned separately: the envelope version (v) and the
+// payload version (version) change independently - encryption and deal content are different things.
 //
-// ЧТО ЛЕЖИТ В PAYLOAD И ПОЧЕМУ ИМЕННО ЭТО
-// v3: МОЯ ПОЛОВИНА ключа траты и МОЯ ПОЛОВИНА ключа просмотра (spendHalf, viewHalf) плюс ПУБЛИЧНЫЕ точки
-//   контрагента (otherSpendPoint, otherViewPoint). Полного ключа траты не существует НИ У КОГО: адрес
-//   собран как сумма половин, и потратить может только тот, у кого окажутся обе. Вторую даёт цепь -
-//   поэтому в файле лежит ещё и адрес эскроу: из него метание прочитает раскрытую половину.
-//   Точки контрагента публичны (они и так в адресе и в ордере), но без них адрес из половин не собрать.
-// v2: mnemonic - единственный источник ключей: и ключ траты, и view key выводятся из
-//   него. Ключи в payload НЕ дублируются: копия секрета в файле - это
-//   лишний способ его потерять и лишний повод рассинхронизировать поля
-//   (раньше в файле лежали и seedHex, и оба приватных ключа).
+// WHAT IS IN THE PAYLOAD, AND WHY EXACTLY THIS
+// v3: MY HALF of the spend key and MY HALF of the view key (spendHalf, viewHalf) plus the counterparty's PUBLIC
+//   points (otherSpendPoint, otherViewPoint). No full spend key exists for ANYONE: the address is a sum of halves,
+//   and only the holder of both can spend. The second half is given by the chain - hence the escrow address is in
+//   the file too: the sweep reads the revealed half from it. The counterparty's points are public (they are in the
+//   address and the order anyway), but without them the address cannot be assembled from the halves.
+// v2: the mnemonic is the single source of keys: both the spend key and the view key derive from it. Keys are NOT
+//   duplicated in the payload: a copy of the secret in the file is one more way to lose it and one more reason for
+//   the fields to drift (the file used to carry both seedHex and the two private keys).
 //   publicSpendKey /
 //   publicViewKey /
-//   address           - для проверки: если из мнемоники выводится другой адрес, файл повреждён
-//                       или подменён, и восстанавливать по нему кошелёк нельзя.
-//   restoreHeight     - высота, с которой начинать скан. Без неё кошелёк сканирует историю
-//                       Monero с нуля, а это десятки часов (замерено: ~35 блоков/с). Высота
-//                       создания сделки - корректный пол: лок XMR случится не раньше.
+//   address - for checking: if the mnemonic derives another address, the file is corrupt or substituted, and a
+//     wallet must not be restored from it.
+//   restoreHeight - the height to start the scan from. Without it the wallet scans Monero history from zero,
+//     which is tens of hours (measured ~35 blocks/s). The deal's creation height is a correct floor: the XMR lock
+//     cannot happen earlier.
 //
-// ЧЕГО В ФАЙЛЕ НЕТ: ключа траты в открытом виде (только внутри шифротекста), номера карты,
-// адреса вывода и вообще ничего, что не нужно для завершения или отката сделки.
+// WHAT IS NOT IN THE FILE: the spend key in the clear (only inside the ciphertext), a card number, a withdrawal
+// address, and anything not needed to complete or roll back the deal.
 //
-// ВИДА КОТИРОВКИ В PAYLOAD НЕТ, и НАБОР КЛЮЧЕЙ payload не проверяется: файл, выпущенный раньше, с лишним
-// ключом вида читается по-прежнему (лишний ключ просто остаётся непрочитанным), а новый выпускается без него.
-// Формат от этого не меняется: PAYLOAD_VERSION остаётся 3 - вид котировки к версии файла отношения не имел.
+// THERE IS NO QUOTE KIND IN THE PAYLOAD, and the payload key set is not checked: a file issued earlier with an
+// extra kind key is still read (the extra key just goes unread) and new files are issued without it. The format
+// does not change: PAYLOAD_VERSION stays 3 - the quote kind never had to do with the file version.
 
-// ПАРАМЕТРЫ ШИФРОВАНИЯ НАЗВАНЫ ЯВНО И НЕ БЕРУТСЯ ИЗ УМОЛЧАНИЙ WEB-CRYPTO.
-// Длина тега и длина ключа - часть ФОРМАТА, а не деталь реализации: файл, выпущенный сегодня, обязан
-// читаться через годы, поэтому оба числа стоят в каждом вызове (encrypt/decrypt/deriveKey), лежат в
-// замороженных объектах и подтверждены ЗАМЕРОМ в tools/check-recovery.mjs: длина тега (шифротекст минус
-// открытый текст = 16 байт) и длина выведенного ключа (256 бит - доказано расшифровкой данным ключом,
-// выведенным отдельно как 256 бит). Число итераций PBKDF2 - тоже часть формата, но оно ОСОЗНАННО
-// изменяемо: растёт со временем, и тогда старые файлы читаются по своему числу (см. ITER_MIN ниже).
+// THE ENCRYPTION PARAMETERS ARE NAMED EXPLICITLY AND ARE NOT TAKEN FROM WEB-CRYPTO DEFAULTS.
+// The tag length and the key length are part of the FORMAT, not an implementation detail: a file issued today must
+// be readable years later, so both numbers stand in every call (encrypt/decrypt/deriveKey), live in frozen objects
+// and were confirmed by MEASUREMENT: the tag length (ciphertext minus plaintext = 16 bytes) and the derived key
+// length (256 bits - proven by decrypting with a key derived separately as 256 bits). The PBKDF2 iteration count
+// is also part of the format, but it is DELIBERATELY changeable: it grows with time, and old files are then read
+// by their own count (see ITER_MIN below).
 //
-// ЧИСЛО ИТЕРАЦИЙ: 600 000 - РЕКОМЕНДАЦИЯ OWASP ДЛЯ PBKDF2-HMAC-SHA256.
-// Источник: OWASP Password Storage Cheat Sheet, раздел PBKDF2 - «PBKDF2-HMAC-SHA256: 600,000 iterations
-// (recommended)»; там же: при требовании FIPS-140 брать PBKDF2 с «work factor of 600,000 or more» и
-// внутренним HMAC-SHA-256, а сами числа получены замерами на GPU RTX 4000 (на декабрь 2022).
-// ПОЧЕМУ PBKDF2, А НЕ Argon2id/scrypt, КОТОРЫЕ OWASP СТАВИТ ВЫШЕ: в браузере доступно только то, что даёт
-// WebCrypto, а в нём из password-hashing есть ОДИН PBKDF2 - Argon2id и scrypt в стандарт не входят. Выбирать
-// не из чего, поэтому важна хотя бы верная для PBKDF2 цифра.
-// ПОЧЕМУ 210 000 БЫЛО НЕВЕРНО: это число стоит в таблице OWASP для PBKDF2-HMAC-SHA512 (220 000), а у нас
-// HMAC-SHA256 - то есть счёт был втрое ниже рекомендации для нашего же алгоритма.
-// ЧЕГО ЭТО НЕ ДАЁТ, ЧТОБЫ НЕ ОБМАНЫВАТЬСЯ: итерации поднимают цену ОДНОЙ догадки (замер на машине
-// разработки: 210k - 109 мс, 600k - 283 мс; на слабом устройстве в браузере заметно больше), но не
-// спасают от слабого пароля: офлайн-перебор упирается в ЭНТРОПИЮ пароля, а не в счёт. Минимум в 12 знаков
-// остаётся слабым местом - записано в .hermes/docs/10-recovery-file.md.
+//
+// THE ITERATION COUNT: 600,000 - OWASP's recommendation for PBKDF2-HMAC-SHA256, i.e. when FIPS-140 requires
+// a "work factor of 600,000 or more" with an internal HMAC-SHA-256 (the numbers come from GPU measurements on an
+// RTX 4000, as of December 2022).
+// WHY PBKDF2 AND NOT Argon2id/scrypt, WHICH OWASP RANKS HIGHER: a browser offers only what WebCrypto gives, and
+// among password-hashing it has ONE - PBKDF2; Argon2id and scrypt are not in the standard. There is nothing to
+// choose from, so at least the number correct for PBKDF2 matters.
+// WHY 210,000 WAS WRONG: that number is in the OWASP table for PBKDF2-HMAC-SHA512 (220,000), while we use
+// HMAC-SHA256 - the count was three times below the recommendation for our own algorithm.
+// WHAT THIS DOES NOT GIVE, SO AS NOT TO BE MISLED: iterations raise the price of ONE guess (measured on the
+// development machine: 210k - 109 ms, 600k - 283 ms; noticeably more on a weak device in a browser) but do not
+// save a weak password: an offline brute force is bounded by the password ENTROPY, not by the count. The 12-char
+// minimum remains the weak spot.
 const ITER = 600_000;
-// ПОЛ ДЛЯ ЧУЖИХ ФАЙЛОВ. Число итераций приходит ИЗ ФАЙЛА (иначе нельзя поднять его, не потеряв старые
-// файлы), поэтому слабое значение обязано упереться в отказ: файл с числом ниже пола не расшифровываем.
+// A FLOOR FOR FOREIGN FILES. The iteration count comes FROM THE FILE (otherwise it could not be raised without
+// losing old files), so a weak value must meet a refusal: a file below the floor is not decrypted.
 const ITER_MIN = 100_000;
 const ITER_MAX = 10_000_000;
-// Идентификатор алгоритма - ОДНА строка на весь модуль: раньше он был вписан дважды (запись и чтение),
-// и расхождение между копиями выяснилось бы только на живом файле.
+// The algorithm identifier is ONE string for the whole module: it used to be written twice (write and read), and a
+// divergence between the copies would surface only on a live file.
 const ALG_ID = "AES-GCM-256/PBKDF2-SHA256";
 const AES = Object.freeze({ name: "AES-GCM", tagLength: 128, keyBits: 256 });
 const KDF = Object.freeze({ name: "PBKDF2", hash: "SHA-256" });
 const te = new TextEncoder();
 const td = new TextDecoder();
 
-export const FILE_MAGIC = "ARRAKIS-SWAP-RECOVERY";
+export const FILE_MAGIC = "NINSEI-SWAP-RECOVERY";
 
-// Версия оболочки (шифрование) и версия полезной нагрузки (состав сделки) - разные числа.
-// ВЕРСИЯ КОНВЕРТА: 1 - без AAD (все файлы, выпущенные до 28.09.2026), 2 - заголовок аутентифицирован (AAD).
-// Читать обязаны ОБЕ: у людей на руках файлы версии 1, и потерять их нельзя. Версия поднимается, когда
-// меняется САМ КОНВЕРТ, а не полезная нагрузка внутри.
+// The envelope version (encryption) and the payload version (deal content) are different numbers.
+// ENVELOPE VERSION: 1 - no AAD (all files issued before it was added), 2 - the header is authenticated (AAD).
+// BOTH must be readable: people hold version-1 files and they must not be lost. The version is raised when the
+// ENVELOPE itself changes, not the payload inside.
 export const ENVELOPE_VERSION = 2;
 const READABLE_ENVELOPE_VERSIONS = [1, 2];
 export const PAYLOAD_VERSION = 3;
-// v1 - самые первые файлы (seedHex и оба ключа отдельными полями), v2 - мнемоника как единственный
-// источник, v3 - ПОЛОВИНЫ. Читать обязаны все три: у людей на руках есть файлы всех версий, и файл
-// восстановления - единственный способ забрать свои XMR. Выбрасывать старые версии нельзя.
+// v1 - the very first files (seedHex and both keys as separate fields), v2 - the mnemonic as the single source,
+// v3 - HALVES. All three must be readable: people hold files of every version, and a recovery file is the only way
+// to claim your XMR. Old versions must not be dropped.
 const SUPPORTED_PAYLOAD_VERSIONS = [1, 2, 3];
-// СЕТИ, КОТОРЫЕ ЧИТАТЕЛЬ ФАЙЛА ЗНАЕТ. Три стандартные плюс fakechain - официальное имя regtest-режима
-// monerod: нода контура CI называет себя именно так, и файл, выпущенный на такой сети, обязан читаться.
-// Список поимённый: сеть вне него отвергается как неизвестная, и это остаётся в силе.
+// NETWORKS THE FILE READER KNOWS. The three standard ones plus fakechain - the official name of monerod's regtest
+// mode: the CI contour node calls itself exactly that, and a file issued on such a network must be readable. The
+// list is by name: a network outside it is rejected as unknown, and that stays.
 const NETWORKS = ["mainnet", "stagenet", "testnet", "fakechain"];
 
 function b64(bytes) {
@@ -101,20 +97,20 @@ function unb64(str) {
   return Uint8Array.from(atob(str), (c) => c.charCodeAt(0));
 }
 
-// ЧИСЛО ИТЕРАЦИЙ - ПАРАМЕТР, А НЕ КОНСТАНТА ВЫЗОВА. При шифровании это ITER, при чтении - число ИЗ
-// ФАЙЛА: формат его хранит именно для того, чтобы счёт можно было поднять, не потеряв уже выпущенные
-// файлы. Прежде чтение брало константу и поле iter не читало вовсе - то есть повышение счёта сломало бы
-// все старые файлы молча, а само поле в файле было бы украшением.
-// AAD: ПОД АУТЕНТИФИКАЦИЕЙ ЗАГОЛОВОК, А НЕ ТОЛЬКО ШИФРОТЕКСТ. AES-GCM проверяет целостность того, что
-// передано ему как additionalData. Без AAD (так было в версии 1) под проверкой был ТОЛЬКО шифротекст, а
-// `meta` - идентификатор сделки, сторона, время, хеш условий - лежит рядом и правился бы без следа, и
-// читатель взял бы подменённое. Строку собирают и писатель, и читатель ИЗ ОДНИХ ПОЛЕЙ В ОДНОМ ПОРЯДКЕ:
-// правка любого поля меняет строку, и расшифровка отвергается.
-// ПОЧЕМУ МАССИВ, А НЕ ОБЪЕКТ: порядок ключей в объекте - деталь реализации JSON, и «одинаковый» объект
-// может дать разный текст. И почему ?? null: отсутствующее поле в массиве дало бы undefined, а это уже
-// другое значение.
-// ЭКСПОРТИРУЕТСЯ НАРОЧНО: строка - часть ФОРМАТА, и проверки обязаны собирать её тем же кодом, а не
-// собственной копией (копия разошлась бы с форматом ровно там, где это дороже всего).
+// THE ITERATION COUNT IS A PARAMETER, NOT A CALL CONSTANT. On encryption it is ITER, on reading it is the number
+// FROM THE FILE: the format stores it precisely so the count can be raised without losing already issued files.
+// Reading used to take the constant and ignore the iter field entirely - so raising the count would have silently
+// broken all old files, and the field in the file would have been decoration.
+// AAD: THE HEADER IS UNDER AUTHENTICATION, NOT ONLY THE CIPHERTEXT. AES-GCM checks the integrity of what is passed
+// to it as additionalData. Without AAD (as in version 1) only the ciphertext was covered, while `meta` - the deal
+// id, side, time, terms hash - sits beside it and could be edited without a trace, and the reader would take the
+// substituted value. The string is built by both writer and reader FROM THE SAME FIELDS IN THE SAME ORDER: any
+// field edit changes the string and decryption is rejected.
+// WHY AN ARRAY, NOT AN OBJECT: key order in an object is a JSON implementation detail and an "identical" object
+// can yield different text. And why ?? null: a missing field in the array would give undefined, which is another
+// value.
+// EXPORTED ON PURPOSE: the string is part of the FORMAT, and checks must build it with the same code, not their
+// own copy (a copy would diverge from the format exactly where it costs most).
 export function envelopeAad(envelope) {
   const m = envelope.meta || {};
   return JSON.stringify([
@@ -134,21 +130,21 @@ async function deriveKey(passphrase, salt, iterations) {
   );
 }
 
-// ВЫСОТА, С КОТОРОЙ НАЧИНАТЬ СКАН ПРИ ВОССТАНОВЛЕНИИ. Чистая функция: никуда не ходит, поэтому её
-// проверяют без ноды - и это важно, потому что именно здесь раньше и терялась высота.
+// THE HEIGHT TO START THE RECOVERY SCAN FROM. A pure function: it goes nowhere, so it is checked without a node -
+// and that matters, because this is exactly where the height used to get lost.
 //
-// ПОЧЕМУ ИСТОЧНИКОВ ДВА. Высоту брали ТОЛЬКО у ноды Monero, и когда нода не ответила, в файл честно
-// ложился null. Восстановление после этого сканировало историю с нуля (десятки часов), хотя точная
-// высота сделки уже была на руках: эскроу заводится транзакцией, и её блок лежит в квитанции. Нода -
-// чужая служба, которая может лежать (боевой прокси отдавал 502), а сделка - своя и уже есть.
+// WHY TWO SOURCES. The height was taken ONLY from the Monero node, and when the node did not answer, null was
+// honestly written into the file. Recovery then scanned history from zero (tens of hours), although the exact deal
+// height was at hand: the escrow is created by a transaction and its block is in the receipt. The node is someone
+// else's service that may be down (a live proxy returned 502), while the deal is our own and already exists.
 //
-// БЕРЁМ МЕНЬШУЮ И ОТСТУПАЕМ НА БЛОК. Поступление XMR может лечь блоком раньше записанной высоты
-// (на живом прогоне транзакция оказалась в 2206634 при высоте 2206635), а скан, начавшийся ниже денег,
-// их находит; начавшийся выше - не находит никогда. Поэтому Math.min и минус один, но не ниже единицы.
-// ТРЕТИЙ ИСТОЧНИК - ПРИЛОЖЕНИЕ. В записях прежних сделок поля birthHeight нет (оно появилось позже), но
-// высоту при регистрации наблюдения приложение разрешило само и хранит; страница забирает её у своего
-// сервера. Это НАШ источник, поэтому он не зависит от того, отвечает ли сейчас нода Monero, и именно он
-// спасает уже выпущенные файлы: у них в записи высоты нет вовсе.
+// TAKE THE SMALLER AND STEP BACK A BLOCK. The XMR arrival may land a block earlier than the recorded height, and a
+// scan that starts below the money finds it; one that starts above never does. Hence Math.min and minus one, but
+// never below one.
+// THE THIRD SOURCE - THE APPLICATION. Old deal records have no birthHeight field (it appeared later), but the app
+// resolved and stored the height when it registered the watch; the page gets it from its server. This is OUR
+// source, so it does not depend on whether the Monero node answers now, and it is what saves already issued
+// files: their record has no height at all.
 export function scanStartHeight({ escrowBirthHeight = null, serverRestoreHeight = null, nodeHeight = null } = {}) {
   const known = [escrowBirthHeight, serverRestoreHeight, nodeHeight]
     .map((v) => Number(v))
@@ -157,21 +153,19 @@ export function scanStartHeight({ escrowBirthHeight = null, serverRestoreHeight
   return Math.max(1, Math.min(...known) - 1);
 }
 
-// Полезная нагрузка: всё, что нужно, чтобы завершить или откатить сделку без сайта.
-// restoreHeight передаёт вызывающий - сюда его кладёт scanStartHeight выше, а модуль не
-// ходит в сеть сам, чтобы его можно было тестировать без ноды.
+// The payload: everything needed to complete or roll back the deal without the site. restoreHeight is passed by
+// the caller - scanStartHeight puts it here, and the module does not go to the network itself so it can be tested
+// without a node.
 export function buildPayload({ swap, swapWallet, escrow, receiveAddress, restoreHeight = null }) {
   return {
     magic: FILE_MAGIC,
-    // ВЕРСИЯ ОТРАЖАЕТ СОСТАВ, А НЕ ВЕРСИЮ МОДУЛЯ. Раньше здесь стоял PAYLOAD_VERSION, и после появления
-    // половин файл, собранный из мнемоники, получал номер 3 - то есть заявлял состав, которого в нём нет,
-    // и проверка справедливо его отвергала. Номер должен говорить правду о содержимом: у файла с половин
-    // тройка, у файла с мнемоникой двойка.
+    // THE VERSION REFLECTS THE CONTENT, NOT THE MODULE VERSION. It used to hold PAYLOAD_VERSION, so after halves
+    // appeared a file built from a mnemonic got number 3 - claiming content it did not have, and the check rightly
+    // rejected it. The number must tell the truth about the content: a halves file is three, a mnemonic file is two.
     version: swapWallet && swapWallet.spendHalf ? 3 : 2,
     swapId: swap.id,
-    // Хеш условий ордера с КОНТРАКТА (keccak256(locker, claimer, hashlock, amount, t0, t1, адрес эскроу, chainid)).
-    // Он и есть привязка файла к цепи: зная условия, можно проверить, что файл относится именно к этому ордеру.
-    // Поле НЕОБЯЗАТЕЛЬНОЕ: у файлов, выпущенных раньше, его нет, и читаться они должны по-прежнему.
+    // The order terms hash FROM THE CONTRACT. It is the file's tie to the chain: knowing the terms, one can check
+    // the file belongs to this very order. The field is OPTIONAL: files issued earlier lack it and must still read.
     termsHash: (swap.escrow && swap.escrow.termsHash) || null,
     side: swap.side,
     network: swap.network,
@@ -183,8 +177,8 @@ export function buildPayload({ swap, swapWallet, escrow, receiveAddress, restore
     maker: swap.maker,
     quote: { signature: swap.quoteSignature, nonce: swap.quoteSignature ? swap.quoteSignature.slice(-8) : null },
     escrow: escrow || swap.escrow || null,
-    // v3 (половины) и v2 (мнемоника) - разные составы, и они несовместимы: в v3 мнемоники НЕТ,
-    // потому что полного ключа траты не существует. Что писать - решает источник кошелька.
+    // v3 (halves) and v2 (mnemonic) are different content, incompatible: v3 has NO mnemonic, because no full spend
+    // key exists. What to write is decided by the wallet source.
     moneroWallet: swapWallet
       ? swapWallet.spendHalf
         ? {
@@ -197,10 +191,10 @@ export function buildPayload({ swap, swapWallet, escrow, receiveAddress, restore
             viewHalf: swapWallet.viewHalf,
             otherSpendPoint: swapWallet.otherSpendPoint,
             otherViewPoint: swapWallet.otherViewPoint,
-            // ПОЛОВИНА ПРОСМОТРА КОНТРАГЕНТА - и это не секрет. Полный ключ ПРОСМОТРА (сумма двух половин)
-            // позволяет ВИДЕТЬ входящие и не позволяет их потратить; трата требует суммы половин ТРАТЫ.
-            // Без чужой половины просмотра кошелёк не сможет найти наши XMR в цепи: половины траты для
-            // скана недостаточно, ключи просмотра и траты в Monero независимы.
+            // THE COUNTERPARTY'S VIEW HALF - and it is not a secret. The full VIEW key (the sum of two halves) lets
+            // one SEE incoming funds and not spend them; spending needs the sum of the SPEND halves. Without the
+            // other view half the wallet cannot find our XMR on chain: the spend halves alone are not enough for
+            // the scan, and Monero's view and spend keys are independent.
             otherViewHalf: swapWallet.otherViewHalf || null,
             escrowAddress: (escrow && escrow.address) || (swap.escrow && swap.escrow.address) || null,
             restoreHeight: Number.isFinite(restoreHeight) ? restoreHeight : null,
@@ -218,54 +212,53 @@ export function buildPayload({ swap, swapWallet, escrow, receiveAddress, restore
           }
       : null,
     deadlines: swap.timeline,
-    recoveryClient: "any standalone client implementing the Arrakis swap protocol (see litepaper §5.3)",
+    recoveryClient: "any standalone client implementing the Ninsei swap protocol (see litepaper §5.3)",
   };
 }
 
-// Проверка payload ПОСЛЕ расшифровки. Отдельная функция, потому что расшифровать можно и
-// мусор (пароль подошёл, а внутри не то), и потому что тесты должны бить по каждому полю
-// отдельно. Бросает с понятной причиной, а не падает в глубине восстановления кошелька.
-// Секреты в тексте ошибок не появляются: мнемоника - это ключ траты.
+// Payload validation AFTER decryption. A separate function, because garbage can decrypt too (the password
+// matched but the content is wrong) and because checks must hit each field separately. It throws with a clear
+// cause instead of failing deep inside wallet recovery. No secrets appear in error text: a mnemonic is a spend key.
 export function validatePayload(payload) {
   const fail = (m) => {
-    throw new Error("Повреждённый recovery-файл: " + m);
+    throw new Error("Corrupt recovery file: " + m);
   };
-  if (!payload || typeof payload !== "object") fail("внутри не объект");
-  if (payload.magic !== FILE_MAGIC) fail("чужой файл (нет метки Arrakis)");
+  if (!payload || typeof payload !== "object") fail("the content is not an object");
+  if (payload.magic !== FILE_MAGIC) fail("foreign file (no Ninsei mark)");
   if (!SUPPORTED_PAYLOAD_VERSIONS.includes(payload.version)) {
-    fail(`версия данных ${payload.version} не поддерживается (умеем ${SUPPORTED_PAYLOAD_VERSIONS.join(", ")})`);
+    fail(`payload version ${payload.version} is not supported (we support ${SUPPORTED_PAYLOAD_VERSIONS.join(", ")})`);
   }
-  if (!payload.swapId) fail("нет идентификатора сделки");
+  if (!payload.swapId) fail("no deal id");
   const m = payload.moneroWallet;
-  if (!m || typeof m !== "object") fail("нет данных кошелька Monero");
+  if (!m || typeof m !== "object") fail("no Monero wallet data");
   if (payload.version >= 3) {
-    // ПОЛОВИНЫ. Мнемоники здесь нет и быть не должно: полного ключа траты не существует ни у одной
-    // стороны, и файл, в котором он вдруг окажется, означает, что кошелёк собран не по схеме.
+    // HALVES. There is no mnemonic here and there must not be: no full spend key exists for either side, and a
+    // file that somehow contains one means the wallet was not built by the scheme.
     for (const field of ["spendHalf", "viewHalf", "otherSpendPoint", "otherViewPoint", "otherViewHalf"]) {
-      if (!m[field]) fail("в файле половин нет поля " + field);
+      if (!m[field]) fail("the halves file has no field " + field);
     }
-    if (m.mnemonic) fail("файл половин содержит мнемонику - кошелёк собран не по схеме");
+    if (m.mnemonic) fail("the halves file contains a mnemonic - the wallet was not built by the scheme");
   } else {
-    if (!m.mnemonic) fail("нет мнемоники - восстановить кошелёк нечем");
+    if (!m.mnemonic) fail("no mnemonic - there is nothing that can restore the wallet");
     const words = String(m.mnemonic).trim().split(/\s+/).length;
-    if (words !== 25 && words !== 13 && words !== 24) fail(`мнемоника не похожа на Monero-фразу (слов: ${words})`);
+    if (words !== 25 && words !== 13 && words !== 24) fail(`the mnemonic does not look like a Monero phrase (${words} words)`);
   }
-  if (!m.address) fail("нет адреса кошелька - не с чем сверять восстановленный");
+  if (!m.address) fail("no wallet address - nothing to check the restored one against");
   const net = m.network || payload.moneroNetwork;
-  if (!NETWORKS.includes(net)) fail(`неизвестная сеть "${net}"`);
+  if (!NETWORKS.includes(net)) fail(`unknown network "${net}"`);
   if (m.network && payload.moneroNetwork && m.network !== payload.moneroNetwork) {
-    fail(`сеть кошелька (${m.network}) не совпадает с сетью сделки (${payload.moneroNetwork})`);
+    fail(`the wallet network (${m.network}) does not match the deal network (${payload.moneroNetwork})`);
   }
 
   const warnings = [];
   if (!Number.isFinite(m.restoreHeight) || m.restoreHeight <= 0) {
     warnings.push(
-      "нет высоты восстановления (restoreHeight): кошелёк будет сканировать историю с нуля, " +
-        "а это десятки часов - укажи высоту лока XMR вручную"
+      "no restore height (restoreHeight): the wallet will scan history from zero, " +
+        "which is tens of hours - set the XMR lock height manually"
     );
   }
   if (payload.version === 1) {
-    warnings.push("файл старого формата (v1): ключи в нём лежали отдельными полями, ключ траты берём из мнемоники");
+    warnings.push("an old-format file (v1): its keys were separate fields, the spend key is taken from the mnemonic");
   }
   return { warnings };
 }
@@ -275,7 +268,7 @@ export async function encryptPayload(payload, passphrase) {
   const salt = crypto.getRandomValues(new Uint8Array(16));
   const iv = crypto.getRandomValues(new Uint8Array(12));
   const key = await deriveKey(passphrase, salt, ITER);
-  // Заголовок собирается ДО шифрования: он же служит AAD, то есть шифротекст привязан к его содержимому.
+  // The header is built BEFORE encryption: it also serves as the AAD, so the ciphertext is tied to its content.
   const meta = { id: payload.swapId, side: payload.side, createdAt: payload.createdAt, termsHash: payload.termsHash || null };
   const header = { v: ENVELOPE_VERSION, alg: ALG_ID, iter: ITER, salt: b64(salt), iv: b64(iv) };
   const ct = await crypto.subtle.encrypt(
@@ -286,9 +279,9 @@ export async function encryptPayload(payload, passphrase) {
   return { ...header, ciphertext: b64(ct), meta };
 }
 
-// Расшифровка. Ошибки AES-GCM (неверный пароль, изменённый шифротекст) приходят как
-// OperationError без деталей - переводим в человеческое сообщение, иначе пользователь
-// видит «operation failed» и не понимает, пароль не тот или файл битый.
+// Decryption. AES-GCM errors (wrong password, altered ciphertext) arrive as OperationError with no detail - we
+// turn them into a human message, else the user sees "operation failed" and cannot tell a wrong password from a
+// corrupt file.
 export async function decryptFile(fileObject, passphrase) {
   if (!fileObject || typeof fileObject !== "object") throw new Error("Not a recovery file (expecting JSON)");
   if (!READABLE_ENVELOPE_VERSIONS.includes(fileObject.v)) throw new Error(`Unsupported recovery file version: ${fileObject.v}`);
@@ -296,8 +289,8 @@ export async function decryptFile(fileObject, passphrase) {
   for (const field of ["salt", "iv", "ciphertext"]) {
     if (typeof fileObject[field] !== "string" || !fileObject[field]) throw new Error(`Recovery file is missing "${field}"`);
   }
-  // ЧИСЛО ИТЕРАЦИЙ ЧИТАЕТСЯ ИЗ ФАЙЛА И ПРОВЕРЯЕТСЯ. Ниже пола - отказ: слабый счёт не должен приводить
-  // к тихой расшифровке. Выше потолка - тоже отказ: это уже не файл, а попытка занять процессор.
+  // THE ITERATION COUNT IS READ FROM THE FILE AND CHECKED. Below the floor - a refusal: a weak count must not lead
+  // to a quiet decryption. Above the ceiling - also a refusal: that is no longer a file but an attempt to occupy the CPU.
   const iter = Number(fileObject.iter);
   if (!Number.isInteger(iter) || iter < ITER_MIN) {
     throw new Error(`Recovery file declares too few PBKDF2 iterations: ${fileObject.iter} (minimum ${ITER_MIN})`);
@@ -308,8 +301,8 @@ export async function decryptFile(fileObject, passphrase) {
   const salt = unb64(fileObject.salt);
   const iv = unb64(fileObject.iv);
   const key = await deriveKey(passphrase, salt, iter);
-  // AAD ПОДМЕШИВАЕТСЯ ТОЛЬКО НАЧИНАЯ С ВЕРСИИ 2. Файлу версии 1 её подставить нельзя: он шифровался без
-  // AAD, и с ней не расшифровался бы ни у кого - то есть «улучшение» обнулило бы все старые файлы.
+  // AAD IS MIXED IN ONLY FROM VERSION 2. A version-1 file cannot take it: it was encrypted without AAD and would
+  // decrypt for nobody with one - so the "improvement" would have wiped every old file.
   const additionalData = fileObject.v >= 2 ? te.encode(envelopeAad(fileObject)) : undefined;
   const decryptAlg = additionalData
     ? { name: AES.name, iv, tagLength: AES.tagLength, additionalData }
@@ -318,28 +311,28 @@ export async function decryptFile(fileObject, passphrase) {
   try {
     pt = await crypto.subtle.decrypt(decryptAlg, key, unb64(fileObject.ciphertext));
   } catch {
-    throw new Error("Не удалось расшифровать файл: неверный пароль или файл изменён");
+    throw new Error("Could not decrypt the file: wrong password or the file was altered");
   }
   let payload;
   try {
     payload = JSON.parse(td.decode(pt));
   } catch {
-    throw new Error("Расшифровалось, но внутри не JSON - файл повреждён");
+    throw new Error("It decrypted, but the content is not JSON - the file is corrupt");
   }
   validatePayload(payload);
-  // У ВЕРСИИ 1 ЗАГОЛОВОК НЕ АУТЕНТИФИЦИРОВАН, ПОЭТОМУ СВЕРЯЕМ ЕГО С СОДЕРЖИМЫМ. Подменить meta у старого
-  // файла можно (AAD там нет), но разойтись с данными внутри шифротекста ему не дадут: идентификатор
-  // сделки обязан совпасть. Для версии 2 это уже избыточно - её проверяет AAD.
+  // IN VERSION 1 THE HEADER IS NOT AUTHENTICATED, SO WE CHECK IT AGAINST THE CONTENT. The meta of an old file can
+  // be substituted (no AAD), but it cannot disagree with the data inside the ciphertext: the deal id must match.
+  // For version 2 this is already redundant - AAD checks it.
   if (fileObject.meta && fileObject.meta.id != null && payload.swapId != null &&
       String(fileObject.meta.id) !== String(payload.swapId)) {
-    throw new Error("Идентификатор сделки в заголовке не совпал с содержимым файла: файл изменён");
+    throw new Error("The deal id in the header does not match the file content: the file was altered");
   }
   return payload;
 }
 
-// BigInt В JSON НЕ СЕРИАЛИЗУЕТСЯ, а половины ключей это BigInt: JSON.stringify на них ПАДАЕТ, и файл
-// восстановления не выпускается. Приводим BigInt к шестнадцатеричной строке - тот же смысл, но сериализуемый.
-// Такой же обработчик стоит в записи состояния (core/store.js): это одна и та же граница сериализации.
+// BigInt DOES NOT SERIALISE IN JSON, and key halves are BigInt: JSON.stringify FAILS on them and the recovery file
+// is never issued. We turn BigInt into a hex string - same meaning, serialisable. The same handler sits in state
+// writing (core/store.js): it is the same serialisation boundary.
 const bigintSafe = (key, value) => (typeof value === "bigint" ? "0x" + value.toString(16) : value);
 export async function createRecoveryFile(payload, passphrase) {
   const file = await encryptPayload(payload, passphrase);
@@ -347,20 +340,20 @@ export async function createRecoveryFile(payload, passphrase) {
 }
 
 export function recoveryFileName(swapId) {
-  // Имя файла - строчными и с привязкой к свопу: по нему видно, к какой сделке файл относится, и его
-  // можно сверить с id на сервере (там он тот же). Раньше было "Arrakis-swap-<id>.json.enc": заглавная
-  // буква в начале и никакой связи с конкретным свопом, если id ещё нет.
-  // Если id ещё нет (файл качают до создания свопа) - имя ФИКСИРОВАННОЕ, без случайного хвоста.
+  // The file name is lowercase and tied to the swap: it shows which deal the file belongs to, and it can be
+  // checked against the id on the server (same there). It used to be "Ninsei-swap-<id>.json.enc": a capital letter
+  // and no tie to a specific swap when there is no id yet.
+  // If there is no id yet (the file is downloaded before the swap is created) the name is FIXED, with no random tail.
   //
-  // Раньше здесь был случайный хвост: он не давал файлам перезаписывать друг друга, но на практике каждое
-  // нажатие кнопки "Download recovery file" рождало НОВОЕ имя, и в загрузках оказывалась кипа похожих
-  // файлов непонятного происхождения. Именно это выглядело как "каждый раз скачивается другой файл".
-  // Теперь имя стабильное, а повторное скачивание браузер сам пометит как (1) - это понятнее, чем новая
-  // случайная строка. Имя совпадает с тем, что уже используется на сервере для незавершённого дела.
+  // There used to be a random tail here: it stopped files overwriting each other, but in practice every click of
+  // "Download recovery file" produced a NEW name and the downloads filled with a heap of look-alike files of
+  // unclear origin. That is exactly what looked like "a different file every time". Now the name is stable and a
+  // repeated download is marked (1) by the browser - clearer than a new random string. The name matches the one
+  // already used on the server for an unfinished deal.
   const raw = String(swapId || "").trim();
   const known = raw && raw !== "pending" ? raw : "pending";
-  // Нижний регистр и только безопасные символы: имя уходит в файловую систему, где регистр и спецсимволы
-  // ведут себя по-разному на Windows, Linux и macOS.
+  // Lowercase and safe characters only: the name goes to a filesystem, where case and special characters behave
+  // differently on Windows, Linux and macOS.
   const safe = known.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
-  return `arrakis-${safe}.json.enc`;
+  return `ninsei-${safe}.json.enc`;
 }