@ninsei-labs/sdk 0.39.0

package/engine/atomic/halfenc.js

@@ -0,0 +1,205 @@
+// 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.
+// Everything below this header is identical to the source.
+
+// Передача половины ключа: зашифрованная половина, пригодная для публикации в цепи.
+// Разбор и обоснование: .hermes/docs/20-key-shares.md, разделы 5, 12.3, 16, 18.
+//
+// ЧТО ЭТО. Половина 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, у которой на запертость есть отдельный случай).
+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.";
+
+export function halfencUnlocked() {
+  return globalThis.ARRAKIS_ALLOW_HALFENC === true;
+}
+
+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;   // маскируем в меньшем порядке
+
+  function bytesToBig(b) { let v = 0n; for (const x of b) v = (v << 8n) | BigInt(x); return v; }
+  function randScalar(limit) {
+    for (let i = 0; i < 256; i++) {
+      const v = bytesToBig(randomBytes(32));
+      if (v > 0n && v < limit) return v;
+    }
+    throw new Error("randScalar: не удалось за 256 попыток");
+  }
+  const bigToHex = (v) => v.toString(16).padStart(64, "0");
+
+  // Ключ шифрования получателя: публикуется заранее и не связан с половиной ключа траты.
+  function recipientKeyPair() {
+    const priv = randScalar(SEC_ORDER);
+    return { priv, pub: secp256k1.Point.BASE.multiply(priv).toHex() };
+  }
+
+  // Маска выводится из общего секрета ECDH: у отправителя через свою эфемерную пару и ключ получателя,
+  // у получателя - через свой приватный ключ и эфемерную точку. Формула одна и та же.
+  function maskFrom(sharedPointHex, context) {
+    const h = keccak256(Uint8Array.from(Buffer.concat([
+      Buffer.from(sharedPointHex.replace(/^0x/, ""), "hex"),
+      Buffer.from(context || "", "utf8"),
+    ])));
+    return bytesToBig(h) % LIMIT;
+  }
+
+  // ЗАКРЫТИЕ: половина x -> публикуемая посылка для получателя.
+  function seal(x, recipientPubHex, context) {
+    // ЗАМОК НА САМОМ КОНВЕРТЕ: сюда попадает только мёртвая ветка, и «на всякий случай» позвать её нельзя.
+    if (!halfencUnlocked()) throw new Error(HALFENC_LOCK_REASON);
+    if (!(x > 0n && x < LIMIT)) throw new Error("seal: половина вне границ 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 mask = maskFrom(shared.toHex(), context);
+    // Все hex-поля приводятся к одному виду: с префиксом 0x и в нижнем регистре. Иначе объект-посылка
+    // и результат распаковки различались бы представлением одних и тех же байт (на этом и споткнулась
+    // проверка: seal отдавал точки без префикса, а распаковка добавляла его).
+    const canon = (h) => "0x" + String(h).replace(/^0x/i, "").toLowerCase();
+    return {
+      recipient: canon(recipientPubHex),   // кому адресовано
+      ephemeral: canon(ephPub.toHex()),    // эфемерная точка, нужна получателю
+      masked: "0x" + bigToHex((x + mask) % LIMIT),   // замаскированный скаляр
+      context: context || "",
+    };
+  }
+
+  // ВСКРЫТИЕ: получатель восстанавливает половину и ПРОВЕРЯЕТ её по опубликованной точке.
+  function open(sealed, recipientPriv, publicPointHex) {
+    // ЗАМОК И НА ВСКРЫТИИ: вторая половина той же мёртвой ветки.
+    if (!halfencUnlocked()) return { ok: false, reason: HALFENC_LOCK_REASON };
+    if (!sealed || !sealed.ephemeral || !sealed.masked) return { ok: false, reason: "посылка неполная" };
+    const eph = secp256k1.Point.fromHex(sealed.ephemeral.replace(/^0x/, ""));
+    const shared = eph.multiply(recipientPriv);                      // ECDH у получателя
+    const mask = maskFrom(shared.toHex(), sealed.context);
+    const x = (BigInt(sealed.masked) - mask + LIMIT) % LIMIT;
+    if (x === 0n) return { ok: false, reason: "восстановлен ноль" };
+    if (!publicPointHex) return { ok: true, x };
+    // Проверка связки "в шифртексте именно эта половина": x*G обязан совпасть с опубликованной точкой.
+    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: "в шифртексте не та половина" };
+    return { ok: true, x };
+  }
+
+  // Обязательство для контракта: keccak256 тех самых байтов посылки. Живёт внутри фабрики, потому что
+  // хеш-функция передаётся ей снаружи (как и все зависимости), и снаружи видно только через этот объект.
+  function sealedCommitmentOf(hexBytes) {
+    const h = keccak256(hexToBytesArr(hexBytes));
+    return "0x" + bytesToHexStr(h);
+  }
+
+  return { LIMIT, recipientKeyPair, seal, open, packSealed, unpackSealed, sealedCommitmentOf };
+}
+
+// --- Байтовый формат посылки ---------------------------------------------------------------
+//
+// Контракту нужны БАЙТЫ: их keccak256 идёт в sealedCommitment ордера, и те же байты уходят в
+// calldata при lock(). Формат фиксированный и однозначный, потому что от него зависит обязательство:
+// при любой другой раскладке хеш не совпадёт и блокировка будет отвергнута.
+//
+//   0        : версия формата (1)
+//   1..33    : публичный ключ получателя шифрования (33 байта, сжатая точка secp256k1)
+//   34..66   : эфемерная точка отправителя (33 байта, сжатая)
+//   67..98   : замаскированный скаляр (32 байта, big-endian)
+//   99       : длина контекста в байтах (0..255)
+//   100..    : контекст ордера в UTF-8
+//
+// Итого 100 + длина контекста байт. JSON здесь намеренно не используется: порядок ключей и форматирование
+// чисел дали бы разные байты для одного и того же содержимого - а обязательство требует однозначности.
+const FORMAT_VERSION = 1;
+
+function bytesToHexStr(b) {
+  let s = "";
+  for (const x of b) s += x.toString(16).padStart(2, "0");
+  return s;
+}
+function utf8(str) {
+  const s = String(str == null ? "" : str);
+  const out = [];
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c < 0x80) out.push(c);
+    else if (c < 0x800) out.push(0xc0 | (c >> 6), 0x80 | (c & 0x3f));
+    else out.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 0x3f), 0x80 | (c & 0x3f));
+  }
+  return new Uint8Array(out);
+}
+function fromUtf8(b) {
+  let s = "";
+  for (let i = 0; i < b.length; i++) {
+    const c = b[i];
+    if (c < 0x80) s += String.fromCharCode(c);
+    else if (c < 0xe0) s += String.fromCharCode(((c & 0x1f) << 6) | (b[++i] & 0x3f));
+    else s += String.fromCharCode(((c & 0x0f) << 12) | ((b[++i] & 0x3f) << 6) | (b[++i] & 0x3f));
+  }
+  return s;
+}
+const hexToBytesArr = (h) => {
+  const s = String(h || "").replace(/^0x/i, "");
+  const out = new Uint8Array(s.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(s.substr(i * 2, 2), 16);
+  return out;
+};
+
+// Посылка -> байты (hex). Именно эти байты хешируются в обязательство и уходят в calldata.
+export function packSealed(sealed) {
+  if (!sealed || !sealed.recipient || !sealed.ephemeral || !sealed.masked) throw new Error("packSealed: посылка неполная");
+  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 байта (сжатая)");
+  const masked = BigInt(sealed.masked).toString(16).padStart(64, "0");
+  const ctx = utf8(sealed.context);
+  if (ctx.length > 255) throw new Error("packSealed: контекст длиннее 255 байт");
+  return "0x" + bytesToHexStr(Uint8Array.of(FORMAT_VERSION))
+    + bytesToHexStr(recipient) + bytesToHexStr(ephemeral) + masked
+    + ctx.length.toString(16).padStart(2, "0") + bytesToHexStr(ctx);
+}
+
+// Байты -> посылка. Проверяет версию и длины; повреждённые данные не разбираются молча.
+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]);
+  const ctxLen = b[99];
+  if (b.length !== 100 + ctxLen) throw new Error("unpackSealed: длина не совпадает с указанной в контексте");
+  return {
+    recipient: "0x" + bytesToHexStr(b.slice(1, 34)),
+    ephemeral: "0x" + bytesToHexStr(b.slice(34, 67)),
+    masked: "0x" + bytesToHexStr(b.slice(67, 99)),
+    context: fromUtf8(b.slice(100)),
+  };
+}
+

package/engine/atomic/halves.js

@@ -0,0 +1,119 @@
+// 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.
+// 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. Модуль не тянет ничего сам.
+
+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);
+  }
+  const ED_ORDER = ed25519.Point.Fn.ORDER;
+  const SECP_ORDER = secp256k1.Point.Fn.ORDER;
+  // Меньший из порядков: половина обязана помещаться в обе группы (статья §4.3).
+  const LIMIT = ED_ORDER < SECP_ORDER ? ED_ORDER : SECP_ORDER;
+
+  // Отбор с отбраковкой: даёт равномерное распределение, в отличие от приведения по модулю,
+  // которое перекашивает вероятности в сторону малых значений.
+  function newHalf() {
+    for (let i = 0; i < 256; i++) {
+      const bytes = randomBytes(32);
+      let v = 0n;
+      for (const b of bytes) v = (v << 8n) | BigInt(b);
+      if (v > 0n && v < LIMIT) return v;
+    }
+    throw new Error("newHalf: не удалось получить скаляр за 256 попыток");
+  }
+
+  // ВЫВОД ПОЛОВИНЫ ИЗ СЕКРЕТА, А НЕ ИЗ СЛУЧАЙНОСТИ. Нужен ноде провайдера: она не хранит половину под
+  // каждый ордер, а выводит её заново из своего ключа и привязки к ордеру. Один и тот же ордер даёт одну
+  // и ту же половину, разные ордера - разные, посчитать может только владелец секрета.
+  //
+  // ОТБОР С ОТБРАКОВКОЙ, А НЕ ПРИВЕДЕНИЕ ПО МОДУЛЮ - по той же причине, что и в newHalf выше: приведение
+  // перекашивает распределение в сторону малых значений, а половина идёт в адрес Monero, где
+  // распределение обязано быть равномерным. Поэтому берём хеш, и если он не меньше порядка группы -
+  // меняем счётчик и хешируем снова. Счётчик входит в хеш, значит весь путь воспроизводим: тот же ордер
+  // при том же секрете даёт ту же половину и на той же попытке.
+  //
+  // ПОЧЕМУ keccak, А НЕ HMAC. keccak - губка, к удлинению сообщения она невосприимчива, поэтому порядок
+  // «домен, секрет, привязка, счётчик» безопасен и не даёт из одного вывода получить другой. Так модуль
+  // остаётся без зависимости от node:crypto и работает и в браузере.
+  // Домены половин. Отсюда их берут И котирование, И выплата: разойдись строки - и нода выведет половину,
+  // которой не соответствует ни её обязательство, ни собранный адрес, и обнаружит это только отказом.
+  const HALF_DOMAIN = "arrakis-order-half-v1";          // половина ТРАТЫ
+  const VIEW_HALF_DOMAIN = "arrakis-order-view-v1";     // половина ПРОСМОТРА
+
+  function halfFromSeed(seedBytes, binding, domain = HALF_DOMAIN) {
+    if (!seedBytes || seedBytes.length < 16) throw new Error("halfFromSeed: секрет короче 16 байт");
+    if (!binding) throw new Error("halfFromSeed: не задана привязка к ордеру");
+    const dom = new TextEncoder().encode(domain + "|" + String(binding) + "|");
+    for (let counter = 0; counter < 256; counter++) {
+      // Счётчик попытки лежит ЯВНО и четырьмя байтами, а не подменой соседнего байта: раньше он был
+      // вписан трюком (инкремент последнего байта строки домена), и такой код читается как загадка.
+      const input = new Uint8Array(dom.length + seedBytes.length + 4);
+      input.set(dom, 0);
+      input.set(seedBytes, dom.length);
+      input[dom.length + seedBytes.length] = (counter >>> 24) & 0xff;
+      input[dom.length + seedBytes.length + 1] = (counter >>> 16) & 0xff;
+      input[dom.length + seedBytes.length + 2] = (counter >>> 8) & 0xff;
+      input[dom.length + seedBytes.length + 3] = counter & 0xff;
+      const bytes = keccak256(input);
+      let v = 0n;
+      for (const b of bytes) v = (v << 8n) | BigInt(b);
+      if (v > 0n && v < LIMIT) return v;
+    }
+    throw new Error("halfFromSeed: не удалось получить скаляр за 256 попыток");
+  }
+
+  function pointFromHex(P, hex) { return P.fromHex(hex.startsWith("0x") ? hex.slice(2) : hex); }
+
+  // ПОЛОВИНА МОЖЕТ ПРИЙТИ СТРОКОЙ, И ЭТО НОРМАЛЬНО. Файл восстановления хранит половины hex-строками
+  // (BigInt нельзя положить в JSON - на этом уже один раз молча терялась запись сделки). Значит любой
+  // вызывающий, который читает файл, обязан получить половину строкой, а арифметика кривой требует
+  // bigint. Раньше это место принимало только bigint, и восстановление из НАСТОЯЩЕГО файла падало с
+  // "expected bigint, got string" - а проверка восстановления этого не видела, потому что подавала
+  // свежие половины. Приводим здесь, в одном месте, чтобы покрыть всех вызывающих сразу.
+  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));
+      return BigInt("0x" + t);
+    }
+    if (typeof v === "number") return BigInt(v);
+    throw new Error("половина неизвестного вида: " + typeof v);
+  }
+  function hex(P) { return P.toHex(); }
+
+  // Публичные половины на обеих кривых: Ks_i = ks_i*G (edwards25519), Bs_i = ks_i*H (secp256k1).
+  function publicHalves(half) {
+    return {
+      ed: hex(ed25519.Point.BASE.multiply(toScalar(half))),
+      secp: hex(secp256k1.Point.BASE.multiply(toScalar(half))),
+    };
+  }
+
+  // Сумма половин: и приватно (mod l), и публично (сложение точек). Второе равенство - то,
+  // на чём держится сборка общего адреса.
+  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)));
+  }
+
+  return { LIMIT, ED_ORDER, SECP_ORDER, HALF_DOMAIN, VIEW_HALF_DOMAIN, newHalf, halfFromSeed, publicHalves, combineHalves, combinePublic };
+}

package/engine/atomic/order-client.js

@@ -0,0 +1,57 @@
+// 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.
+// Everything below this header is identical to the source.
+
+// Клиент воркера: превращает обмен сообщениями в обычный вызов с колбэком прогресса.
+//
+// Отдельный модуль нужен, чтобы страница не знала ничего про postMessage и идентификаторы запросов:
+// она вызывает buildSide(...) и получает обещание плюс этапы.
+export function createOrderWorker() {
+  if (typeof Worker === "undefined") throw new Error("воркеры недоступны в этом окружении");
+  const worker = new Worker(new URL("./order-worker.js", import.meta.url), { type: "module" });
+  const pending = new Map();
+  let seq = 0;
+
+  worker.onmessage = (event) => {
+    const msg = event.data || {};
+    const entry = pending.get(msg.id);
+    if (!entry) return;
+    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 || "воркер вернул ошибку"));
+  };
+  worker.onerror = (event) => {
+    const err = new Error("воркер упал: " + (event.message || "без сообщения"));
+    for (const [, entry] of pending) entry.reject(err);
+    pending.clear();
+  };
+
+  const call = (type, args = {}, onProgress) => {
+    const id = ++seq;
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject, onProgress });
+      worker.postMessage({ id, type, ...args });
+    });
+  };
+
+  return {
+    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),
+    // Обязательство на половину. Считается в воркере, потому что там же живёт криптография: наружу
+    // уходит только хеш, половина остаётся внутри и в главный поток не попадает.
+    halfCommitment: (ownHalf) => call("commit", { ownHalf }),
+    // Точка по половине: половина контрагента приходит из котировки, а для адреса нужна точка.
+    pointOf: (ownHalf) => call("pointOf", { ownHalf }),
+    // Общий адрес Monero из половин - в воркере, потому что там же криптография.
+    jointAddress: (joint) => call("jointAddress", { joint }),
+    // МАТЕРИАЛ МЕЙКЕРА ОБРАТНОЙ ЗАЯВКИ: обе половины, их точки и обязательство. Доказательства здесь нет и
+    // быть не может: в обратном направлении привязку ордера назначает нода, и до билета доказывать нечего
+    // (order-worker.js, newMakerMaterial). Публичная часть уходит ноде в заявке, приватная остаётся у
+    // мейкера - ею забирают выплату и видят приход XMR.
+    makerMaterial: () => call("newMakerMaterial"),
+    stop: () => worker.terminate(),
+  };
+}

package/engine/atomic/order.js

@@ -0,0 +1,132 @@
+// GENERATED FILE - a byte-for-byte copy of the engine module www/js/atomic/order.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.
+// Everything below this header is identical to the source.
+
+// Сборка стороны ордера атомарного свопа: половина ключа, точки, доказательство, зашифрованная
+// посылка и обязательство для контракта.
+// Разбор: .hermes/docs/20-key-shares.md, разделы 12, 19, 23, 25.
+//
+// ЧТО ЭТО ЗАКРЫВАЕТ. До сих пор модули существовали по отдельности: половины, DLEQ, передача половины,
+// байтовый формат. Здесь они собираются в одну сторону ордера и, главное, здесь КОДОМ выполняются два
+// обязательных условия из раздела 20.5:
+//   1) перед блокировкой проверяется, что в посылке контрагента лежит настоящая половина (сверка с точкой);
+//   2) при этом проверяется и его DLEQ - что обе публичные точки стоят за одним скаляром.
+// Без этих двух проверок схема не даёт гарантии, и они не «на будущее», а здесь.
+//
+// ЧЕСТНОЕ ОГРАНИЧЕНИЕ ДЕМО. Настоящего мейкера (RFQ-узла) ещё нет: в market.js котировки фиктивные.
+// Поэтому сторона контрагента собирается ЛОКАЛЬНО и помечается как заглушка (standIn: true). Это
+// позволяет прогнать полный цикл - от половины до обязательства и до вскрытия - но ценность гарантии
+// появляется только с настоящим контрагентом, у которого свой ключ.
+
+import { createHalves } from "./halves.js";import { halfCommitmentHex } from "./orderHalfCommit.js";
+import { createDleq2 } from "./dleq2.js";
+import { createHalfEnc, packSealed } from "./halfenc.js";
+import { addressFromKeys } from "../monero/address.js";
+import { swapAddressFromHalves } from "../monero/swapKeys.js";
+
+export function createOrderBuilder({ ed25519, secp256k1, keccak256, sha3_512, randomBytes }) {
+  const halves = createHalves({ ed25519, secp256k1, keccak256, randomBytes });
+  const dleq = createDleq2({ ed25519, secp256k1, keccak256, sha3_512, randomBytes });
+  const enc = createHalfEnc({ secp256k1, ed25519, keccak256, randomBytes });
+
+  // Сторона ордера: ДВЕ половины (траты и просмотра), их точки, доказательство и ключ шифрования.
+  //
+  // ЗАЧЕМ ОТДЕЛЬНАЯ ПОЛОВИНА ПРОСМОТРА. Ключ просмотра в Monero независим от ключа траты, и из половины
+  // траты его не вывести. Без суммы половин ПРОСМОТРА кошелёк не найдёт входящие и не сможет сканировать:
+  // половины траты для скана недостаточно. При этом делиться половиной просмотра БЕЗОПАСНО - она даёт
+  // видеть и не даёт тратить; трата требует суммы половин ТРАТЫ.
+  //
+  // ДОКАЗАТЕЛЬСТВА ДЛЯ НЕЁ НЕ НУЖНО, и это осознанно: половина просмотра приходит вместе с котировкой и
+  // сама определяет точку просмотра, поэтому подменять её нечем. Доказательство DLEQ остаётся там, где
+  // оно решает - на половине ТРАТЫ, за которую платят ETH.
+  function newSide(orderContext, standIn = false, onBit) {
+    const half = halves.newHalf();
+    const pub = halves.publicHalves(half);                     // ed25519 и secp256k1
+    const viewHalf = halves.newHalf();
+    const viewPub = halves.publicHalves(viewHalf).ed;          // точка просмотра: из неё собирается адрес
+    const encPair = enc.recipientKeyPair();                    // отдельно от ключа траты
+    const proof = dleq.prove(half, orderContext, onBit);        // привязано к контексту ордера
+    return { half, pub, viewHalf, viewPub, enc: encPair, proof, standIn };
+  }
+
+  // Проверка стороны контрагента - это и есть условие (1) и (2) из раздела 20.5.
+  // Проверка стороны контрагента: доказательство и - если посылка дана - вскрытие ЕГО посылки НАШИМ
+  // приватным ключом со сверкой по ЕГО публичной точке.
+  //
+  // РОЛИ КЛЮЧЕЙ ЗДЕСЬ ПРИНЦИПИАЛЬНЫ, и первая версия этой функции их путала: она вскрывала посылку
+  // приватным ключом самого контрагента, которого у нас нет и быть не может - посылка адресована ему.
+  // Такая проверка не могла пройти никогда, но выглядела как работающая, что хуже всего.
+  function verifySide(side, orderContext, sealedPayloadBytes, ownEncPriv) {
+    const proofOk = dleq.verify(side.proof, orderContext);
+    if (!proofOk.ok) return { ok: false, reason: "DLEQ контрагента не прошёл: " + proofOk.reason };
+    // ДОКАЗАННАЯ ТОЧКА ОБЯЗАНА БЫТЬ ТОЙ ЖЕ, ЧТО УЙДЁТ В ОРДЕР, и этой сверки не было.
+    //
+    // Чего не хватало без неё: доказательство подтверждает, что за парой точек стоит ОДИН скаляр, но НЕ
+    // подтверждает, что доказанная точка ed25519 - та самая, по которой собирается общий адрес и которую
+    // контракт потом заставит раскрыть. Контрагент мог предъявить корректное доказательство для одной
+    // точки, а в ордер подставить другую. На своей стороне всё выглядело бы исправным, а расхождение
+    // вылезло бы в самом конце - при заборе XMR, когда исправлять уже нечем.
+    //
+    // Сверка одна на обе стороны: у своей стороны pub.ed выведена из половины, у контрагента приходит из
+    // котировки; в обоих случаях это ТА точка, которую увидят в контракте.
+    if (side.pub && side.pub.ed && String(side.proof.XB).toLowerCase() !== String(side.pub.ed).toLowerCase()) {
+      return { ok: false, reason: "доказанная точка ed25519 не совпадает с заявленной: " + side.proof.XB + " против " + side.pub.ed };
+    }
+    if (sealedPayloadBytes && ownEncPriv) {
+      const opened = enc.open(enc.unpackSealed(sealedPayloadBytes), ownEncPriv, side.pub.ed);
+      if (!opened.ok) return { ok: false, reason: "посылка контрагента не подтверждает половину: " + opened.reason };
+    }
+    return { ok: true };
+  }
+
+  // Посылка со своей половиной, зашифрованная на ключ контрагента: то, что уходит ему и в контракт.
+  function sealFor(counterparty, ownHalf, orderContext) {
+    const sealed = enc.seal(ownHalf, counterparty.enc.pub, orderContext);
+    const bytes = packSealed(sealed);
+    return { sealed, bytes, commitment: enc.sealedCommitmentOf(bytes) };
+  }
+
+  // Открыть посылку контрагента своей половиной и проверить, что это именно его половина.
+  function openFrom(sealedBytes, ownEncPriv, counterpartyEdPub) {
+    return enc.open(enc.unpackSealed(sealedBytes), ownEncPriv, counterpartyEdPub);
+  }
+
+  // ОБЯЗАТЕЛЬСТВО НА ПОЛОВИНУ - то, что контракт проверяет в `claim` и `refund`, и то, что входит в
+  // `termsHash`. Ровно это считает Solidity: `keccak256` от secp256k1-ТОЧКИ половины (`half·G`), а не от
+  // числа. Значит формула обязана совпадать у приложения и у ноды - поэтому она живёт ОТДЕЛЬНЫМ модулем и
+  // здесь только вызывается, а курс (`secp256k1`) передаётся снаружи: две копии одной формулы расходятся
+  // ровно тогда, когда цепь отвергнет «точно правильную» половину (#123).
+  function halfCommitment(half) {
+    return halfCommitmentHex(half, secp256k1, keccak256);
+  }
+
+  // Общий адрес Monero: сумма публичных половин. Проверяется свойством (a+b)G == aG + bG.
+  function jointAddressPoint(sideA, sideB) {
+    return halves.combinePublic(sideA.pub.ed, sideB.pub.ed);
+  }
+
+  // ТОЧКА ПО ПОЛОВИНЕ. Нужна там, где от контрагента пришла ПОЛОВИНА (так она приходит в котировке под
+  // ордер), а для адреса нужна точка. Точка из половины выводится тем же модулем половин, что и везде.
+  function pointOf(half) {
+    return halves.publicHalves(typeof half === "bigint" ? half : BigInt(half)).ed;
+  }
+
+  // ОБЩИЙ АДРЕС MONERO - то, ради чего схема и построена. Ни одна сторона не знает чужой половины ТРАТЫ:
+  // адрес собирается из СВОЕЙ половины и ЧУЖОЙ ТОЧКИ, потому что (a+b)G == aG + bG. До раскрытия второй
+  // половины расчётом адрес существует, но потратить с него не может никто.
+  //
+  // КОДИРОВЩИК БЕРЁМ ТОТ ЖЕ, ЧТО У КОШЕЛЬКА (monero/address.js). Второй кодировщик разошёлся бы с первым
+  // там, где ошибку видно только отправкой XMR, - и заметил бы её не тот, кто ошибся.
+  //
+  // КЛЮЧ ПРОСМОТРА СОБИРАЕТСЯ ОТДЕЛЬНО И ИЗ СВОИХ ПОЛОВИН: в Monero ключи просмотра и траты независимы, и
+  // подменять один другим нельзя. Без верной половины просмотра пользователь не увидит приход.
+  function jointAddress({ ownSpendHalf, ownViewHalf, otherSpendPoint, otherViewPoint, network }) {
+    return swapAddressFromHalves({
+      halves, addressFromKeys, deps: { keccak256 },
+      ownSpendHalf, ownViewHalf, otherSpendPoint, otherViewPoint, network,
+    });
+  }
+
+  return { halves, dleq, enc, newSide, verifySide, sealFor, openFrom, jointAddressPoint, pointOf, jointAddress, halfCommitment };
+}

package/engine/atomic/orderContext.js

@@ -0,0 +1,70 @@
+// GENERATED FILE - a byte-for-byte copy of the engine module www/js/atomic/orderContext.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.
+// Everything below this header is identical to the source.
+
+// КАНОНИЧЕСКИЙ КОНТЕКСТ ОРДЕРА - то, к чему привязывается доказательство DLEQ.
+//
+// ЗАЧЕМ ОТДЕЛЬНЫЙ МОДУЛЬ. Раньше контекст был произвольной строкой, которую передавал вызывающий, а
+// заглушка контрагента просто дописывала к ней ":контрагент". Внутри одной вкладки это работало, но
+// означало ровно одно: доказательство привязано НИ К ЧЕМУ, что снаружи воспроизвести нельзя. Наш же
+// критерий приёмки (док 27, раздел 11) требует обратного: взял поля ордера с цепи, собрал точку,
+// проверил доказательство, сошлось. Значит контекст обязан собираться ИЗ ПОЛЕЙ ОРДЕРА, и собираться
+// одинаково у всех: у приложения, у ноды провайдера и у любого, кто захочет проверить сделку.
+//
+// ЧТО ВХОДИТ И ЧЕГО НЕ ВХОДИТ. Только УСЛОВИЯ ордера - то, что известно до всякого доказательства:
+// сеть, фабрика, адрес внёсшего, адрес забирающего, сумма, сроки и соль.
+//
+// ОБЯЗАТЕЛЬСТВ И ТОЧЕК ЗДЕСЬ НЕТ, И ЭТО ИСПРАВЛЕНИЕ, А НЕ УПУЩЕНИЕ. Первая версия их включала, и выходил
+// КРУГ: доказательство привязывается к контексту, а контекст брал обязательства и точки - то есть то, что
+// само появляется только ВМЕСТЕ с доказательством. Порядок получался невыполнимым.
+//
+// Структура от этого не слабеет, и вот почему: половина провайдера ВЫВОДИТСЯ из условий ордера, поэтому
+// одни и те же условия дают у него ту же половину, то же обязательство и ту же точку. Меняются условия -
+// меняется всё. А обязательства и точки обеих сторон отдельно закреплены В САМОМ ОРДЕРЕ и в его
+// termsHash: контракт делает их неизменяемыми после фондирования. Два разных места - две разные задачи.
+//
+// Адреса эскроу здесь тоже нет: он выводится из этих полей через CREATE2, то есть следствие, а не вход.
+//
+// ВЕРСИЯ КОНТЕКСТА. Префикс "arrakis-order-v1" отделяет контекст от любых других подписей и доказательств.
+// Менять состав полей можно только вместе с номером версии в префиксе: иначе два разных смысла оказались
+// бы под одной строкой, и проверка проходила бы там, где не должна.
+
+// ВЕРСИЯ ПОДНЯТА ДО v2: состав полей изменился (убраны обязательства и точки), а по нашему же правилу
+// смена смысла - это новая версия, а не дополнение. Выданных котировок в обращении ещё нет, поэтому
+// переход ничего не ломает; дальше так уже не получится.
+// ВЕРСИЯ 3: ИЗМЕНЁН ХЕШ ВЫЗОВА В ДОКАЗАТЕЛЬСТВЕ DLEQ (SHA3-512 и широкое приведение вместо keccak256).
+// Это не косметика: доказательства версии 2 не проходят проверку версии 3, поэтому метка поднята - иначе
+// живая котировка со старым доказательством ломалась бы молча, а причина искалась бы в подписи.
+export const ORDER_CONTEXT_VERSION = "arrakis-order-v3";
+
+const norm = (v) => String(v === undefined || v === null ? "" : v).trim().toLowerCase();
+const dec = (v) => {
+  // Числа приводим к десятичной строке: "0x10" и "16" - одно и то же число, и если оставить как пришло,
+  // два вызывающих дадут разные контексты для одного ордера, а доказательство развалится без причины.
+  if (typeof v === "bigint") return v.toString(10);
+  if (typeof v === "number") return String(Math.trunc(v));
+  const s = norm(v);
+  if (s.startsWith("0x")) return BigInt(s).toString(10);
+  return s;
+};
+
+// Поля перечислены ЯВНО и в фиксированном порядке. Порядок - часть протокола: переставить значит
+// сменить контекст, то есть разом сделать недействительными все выданные котировки под ордер.
+const FIELDS = [
+  "chainId",            // сеть: один и тот же ордер в разных сетях - разные ордера
+  "factory",            // какая фабрика создаёт эскроу
+  "locker",             // кто вносит ETH
+  "claimer",            // кому контракт заплатит
+  "amount",             // сумма в wei
+  "readyBy",            // срок готовности
+  "t1",                 // срок расчёта
+  "salt",               // соль ордера
+];
+
+export function orderContextString(order) {
+  if (!order || typeof order !== "object") throw new Error("для контекста ордера нужен объект с полями ордера");
+  const missing = FIELDS.filter((f) => order[f] === undefined || order[f] === null || order[f] === "");
+  if (missing.length) throw new Error("в контекст ордера не хватает полей: " + missing.join(", "));
+  return ORDER_CONTEXT_VERSION + "|" + FIELDS.map((f) => dec(order[f])).join("|");
+}

package/engine/atomic/orderHalfCommit.js

@@ -0,0 +1,29 @@
+// GENERATED FILE - a byte-for-byte copy of the engine module www/js/atomic/orderHalfCommit.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.
+// Everything below this header is identical to the source.
+
+// ОБЯЗАТЕЛЬСТВО НА ПОЛОВИНУ - одна формула на все стороны.
+//
+// ЧТО СЧИТАЕТ ЦЕПЬ. `keccak256(x || y)` от secp256k1-ТОЧКИ половины `half·G` - то есть АДРЕС этой точки.
+// При раскрытии контракт проверяет не «хеш числа совпал», а что предъявленная половина РАЗМНОЖАЕТСЯ в ту же
+// точку (приём `ecrecover`, `NinseiEscrow.halfMatchesCommit`). Обязательство-ТОЧКА закрывает #123: раньше
+// `keccak256(be32(half))` принимал любое число с совпавшим хешем, и вносящий ETH мог закоммитить хеш мусора,
+// вернуть этим мусором ETH и запереть XMR второй стороны. Связь точки secp256k1 с точкой ed25519 (и адресом
+// Monero) держит DLEQ - её проверяет рискующая сторона ДО платежа.
+//
+// Это же обязательство входит в termsHash и в котировку. Значит формула обязана совпадать у приложения, у
+// ноды провайдера и у любого, кто станет проверять сделку. Две реализации одной формулы расходятся ровно
+// тогда, когда это дороже всего: цепь отвергнет половину, которая «точно правильная».
+//
+// ТОЧКА БЕРЁТСЯ НЕСЖАТОЙ - 64 байта `x || y`, старшим байтом вперёд, как координаты ключа Ethereum.
+// `secp256k1` и `keccak256` передаются снаружи: модуль не тянет зависимостей сам, как и соседние.
+
+export function halfCommitmentHex(half, secp256k1, keccak256) {
+  if (!secp256k1 || !keccak256) throw new Error("нужны secp256k1 и keccak256");
+  const value = BigInt(half);
+  if (value <= 0n) throw new Error("половина должна быть положительным числом");
+  const raw = secp256k1.Point.BASE.multiply(value).toBytes(false);   // 65 байт: 0x04 || x(32) || y(32)
+  const xy = raw.slice(1);                                            // 64 байта: x || y
+  return "0x" + Array.from(keccak256(xy), (b) => b.toString(16).padStart(2, "0")).join("");
+}