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

package/engine/ui/dom.js

@@ -1,9 +1,8 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/ui/dom.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.
 
-// Крошечные DOM-хелперы. Никаких фреймворков: демка должна читаться глазами.
+// Tiny DOM helpers. No frameworks: the demo must be readable by eye.
 
 export function h(tag, attrs = {}, children = []) {
   const el = document.createElement(tag);
@@ -12,8 +11,8 @@ export function h(tag, attrs = {}, children = []) {
     if (k === "class") el.className = v;
     else if (k === "html") el.innerHTML = v;
     else if (k === "text") el.textContent = v;
-    // style пишем только через CSSOM: атрибут style="..." запрещён политикой CSP
-    // (style-src-attr), а el.style.* и cssText - разрешены. Так эта ловушка не вернётся.
+    // style is written only through CSSOM: the style="..." attribute is banned by the CSP policy
+    // (style-src-attr), while el.style.* and cssText are allowed. So this trap does not return.
     else if (k === "style") {
       if (typeof v === "string") el.style.cssText = v;
       else Object.assign(el.style, v);

package/engine/ui/walletModal.js

@@ -1,22 +1,13 @@
 // GENERATED FILE - a byte-for-byte copy of the engine module www/js/ui/walletModal.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.
 
-// Своя модалка подключения кошелька: выбор браузерного кошелька и QR для WalletConnect.
-//
-// Список браузерных кошельков приходит снаружи (setChoices) - обнаружением занимается
-// www/js/evm/injected.js по EIP-6963. Здесь только отрисовка: CSP запрещает inline-стили, поэтому
-// всё идёт через dom.h(), а иконки кошельков - data:-URL, что разрешено img-src 'self' data:.
-//
-// Почему не модалка Reown (@reown/appkit): она рисует свои стили inline - и атрибутом style="",
-// и целыми <style>-блоками. CSP демки запрещает и то, и другое (ловушка №1 в
-// .hermes/docs/05-frontend-stack.md), ослаблять её ради модалки мы не стали. Поэтому модалку
-// рисуем сами через dom.h() (стили идут через CSSOM), а QR - генератором qrcode из бандла
-// в виде data:-URL (img-src 'self' data: в CSP это разрешает).
-//
-// Никаких секретов здесь нет: в QR лежит открытая ссылка сессии WalletConnect (wc:...),
-// её и показывать пользователю не страшно - такое же показывает любая dapp.
+// A wallet-connect modal: browser-wallet choice and a QR for WalletConnect.
+// The browser-wallet list comes from outside (setChoices); detection is evm/injected.js by EIP-6963. Here is
+// only rendering: the CSP bans inline styles, so everything goes through dom.h(), and wallet icons are data: URLs.
+// NOT the Reown (@reown/appkit) modal: it draws its own inline styles and <style> blocks, both banned by the demo
+// CSP, and we did not weaken it for a modal. So we draw the modal ourselves and the QR with a qrcode generator as a data: URL.
+// No secrets here: the QR holds the public WalletConnect session URI (wc:...), safe to show like any dapp.
 
 import { h, copy } from "./dom.js";
 
@@ -30,7 +21,7 @@ export function openWalletModal({ title = "Connect a wallet", subtitle = "", hin
         (refs.closeBtn = h("button", { class: "ar-modal-close", type: "button", title: "Close", text: "\u00d7" })),
       ]),
       (refs.subtitle = h("div", { class: "ar-modal-sub", text: subtitle })),
-      // Список браузерных кошельков: пустой, пока не пришёл от обнаружения (тогда и не виден).
+      // The browser-wallet list: empty until detection delivers it (then invisible).
       (refs.choices = h("div", { class: "ar-modal-choices" })),
       (refs.qrBox = h("div", { class: "ar-modal-qr", hidden: true }, [(refs.qr = h("img", { alt: "WalletConnect QR code" }))])),
       (refs.uri = h("code", { class: "ar-modal-uri" })),
@@ -48,12 +39,10 @@ export function openWalletModal({ title = "Connect a wallet", subtitle = "", hin
   const closed = { value: false };
   let onCancel = null;
 
-  // Два разных выхода из модалки, и разница принципиальная:
-  //   close()  - закрывает программно (например, сессия успешно установлена);
-  //   cancel() - пользователь отказался: вот тут-то и надо гасить сессию, которую мы просили.
-  // Путать их нельзя: раньше успешное подключение закрывало модалку, а та дёргала обработчик
-  // отмены и удаляла только что созданную сессию (в логе SDK это видно как wc_sessionDelete
-  // через 85 мс после wc_sessionSettle).
+  // TWO DIFFERENT EXITS FROM THE MODAL, and the difference is fundamental: close() closes it programmatically
+  // (e.g. the session settled), while cancel() is the user refusing - and THAT is when we must kill the session
+  // we asked for. They must not be confused: before, a successful connect closed the modal, which fired the
+  // cancel handler and deleted the just-created session.
   function close() {
     if (closed.value) return;
     closed.value = true;
@@ -75,9 +64,9 @@ export function openWalletModal({ title = "Connect a wallet", subtitle = "", hin
     if (e.target === overlay) cancel();
   });
 
-  // setChoices([{ key, name, icon, hint, onClick }]) - список браузерных кошельков и WalletConnect.
-  // Иконки только из data:-URL (их отдаёт сам кошелёк по EIP-6963): внешние адреса в CSP демки не
-  // разрешены, и это правильно - картинка из сети не должна влиять на то, какой кошелёк выбран.
+  // setChoices([{ key, name, icon, hint, onClick }]) - the browser-wallet list plus WalletConnect. Icons are
+  // data: URLs only (the wallet itself provides them): external addresses are not allowed by the demo CSP, and
+  // rightly so - a network image must not influence which wallet is chosen.
   function setChoices(list) {
     refs.choices.innerHTML = "";
     refs.choices.hidden = !list || !list.length;
@@ -91,8 +80,8 @@ export function openWalletModal({ title = "Connect a wallet", subtitle = "", hin
           item.hint ? h("span", { class: "ar-modal-choice-hint", text: item.hint }) : null,
         ]),
       ]);
-      // Дальше модалку гасит тот, кто обработал выбор: у браузерного кошелька окно показывает сам
-      // кошелёк, а у WalletConnect нужно ещё показать QR.
+      // The rest of the modal is closed by whoever handled the choice: a browser wallet shows its own window,
+      // while WalletConnect still needs the QR shown.
       btn.addEventListener("click", () => {
         if (closed.value) return;
         item.onClick();
@@ -114,14 +103,14 @@ export function openWalletModal({ title = "Connect a wallet", subtitle = "", hin
       if (closed.value) return;
       if (qrDataUrl) {
         refs.qr.src = qrDataUrl;
-        // Рамку показываем только когда QR реально есть: до выбора WalletConnect это пустое место.
+        // The frame is shown only when a QR actually exists: before WalletConnect is chosen this is empty.
         refs.qrBox.hidden = false;
       }
       if (uri !== undefined) refs.uri.textContent = uri || "";
       if (subtitle !== undefined) refs.subtitle.textContent = subtitle || "";
       if (hintText !== undefined) refs.hint.textContent = hintText || "";
-      // error важнее status: иначе переданное «попробуйте ещё раз» перетирает сам текст ошибки, и
-      // причина отказа видна только в тосте (раньше error влиял лишь на цвет - мёртвый параметр).
+      // error is more important than status: otherwise a generic "try again" overwrites the error text, and
+      // the refusal reason is visible only in the toast.
       const line = error || status;
       if (line !== undefined) {
         refs.status.className = "ar-modal-status" + (error ? " ar-modal-status-error" : "");

package/index.d.ts

@@ -47,6 +47,8 @@ export interface NinseiOptions {
    * transaction, so the swap and the escrow funding are one transaction (Uniswap, SushiSwap); "async" - the
    * settlement arrives later as a separate action, and then the record must also say what ends execution
    * (CoWSwap). A path that assumes "one transaction" refuses an asynchronous provider BY NAME, not silently.
+   * The registered identifiers are `declared` (our own router routes, "sync") and `cowswap` (the CoWSwap intent
+   * auction, "async") - see `sdk.config.routing.providers`.
    */
   routing?: { prefer?: readonly string[] };
   /**
@@ -348,6 +350,12 @@ export interface WalletAdapter {
    * by the caller, not the adapter - otherwise two calls would wait differently.
    */
   receipt(txHash: string): Promise<unknown>;
+  /**
+   * SIGN TYPED DATA (EIP-712). Not a transaction: no gas, no money moves, so a person without their own coin can
+   * give it. What is signed is decided by the CALLER (ready typed data arrives here). Optional - a wallet that
+   * cannot sign typed data leaves it out, and a caller sees `not-implemented`, not silence.
+   */
+  signTypedData?(typedData: unknown): Promise<string>;
   /** Switching the network, if this VM can do it from the SDK. No method - `not-implemented`, not silence. */
   switchChain?(chainId: number | string): Promise<void>;
   driver(): unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninsei-labs/sdk",
-  "version": "0.39.3",
+  "version": "0.40.0-develop.1",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/src/adapters/evm-wallet.mjs

@@ -119,6 +119,22 @@ export function evmWallet(provider, { id = "evm" } = {}) {
       if (typeof txHash !== "string" || !txHash) throw new SdkError("bad-input", { field: "receipt.txHash" });
       return await provider.request({ method: "eth_getTransactionReceipt", params: [txHash] });
     },
+    // SIGNING TYPED DATA (EIP-712) - the same call the page makes (www/js/evm/session.js, signTypedData). This is not
+    // a transaction: no gas, no money moves, so a person without their own ETH can give it. What is signed is DECIDED
+    // BY THE CALLER (ready typed data arrives here - e.g. a CoWSwap order from src/legs/cow.mjs); the shape is not
+    // assembled here, else there would be a second record of the protocol.
+    async signTypedData(typedData) {
+      if (!typedData || typeof typedData !== "object") throw new SdkError("bad-input", { field: "signTypedData" });
+      const accounts = await provider.request({ method: "eth_accounts" });
+      const from = Array.isArray(accounts) ? accounts[0] : null;
+      if (!from) throw new SdkError("wallet-not-connected", { step: "signTypedData" });
+      // The argument order [address, JSON] is as EIP-712 requires and as MetaMask and WalletConnect accept.
+      const signature = await provider.request({ method: "eth_signTypedData_v4", params: [from, JSON.stringify(typedData)] });
+      if (typeof signature !== "string" || !/^0x[0-9a-fA-F]{130}$/.test(signature)) {
+        throw new SdkError("wallet-rejected", { step: "signTypedData", why: "bad-signature-shape" });
+      }
+      return signature;
+    },
     driver() {
       return provider;
     },

package/src/adapters/monero-wallet.mjs

@@ -29,7 +29,7 @@ import { config as engineConfig, xmrAddress } from "../engine.mjs";
 
 const XMR_VM = "monero";
 // The wallet session label - the same as the withdrawal page's. This is not a secret and not an address, but a session name.
-const DEFAULT_PASSWORD = "arrakis-wallet-session";
+const DEFAULT_PASSWORD = "ninsei-wallet-session";
 
 /** Monero network names declared by the core's registry. The adapter keeps no table of its own. */
 const knownNetworks = () => {

package/src/adapters/monero.mjs

@@ -9,7 +9,7 @@
 // leave, BEFORE sending rather than after.
 import { SdkError } from "../errors.mjs";
 
-export function moneroWallet({ createWallet, networkType, serverUri, password = "arrakis-sweep-session", fields = {} }) {
+export function moneroWallet({ createWallet, networkType, serverUri, password = "ninsei-sweep-session", fields = {} }) {
   const build = typeof createWallet === "function" ? createWallet : null;
   // Refusals - with CODES, as everywhere in the core: the phrase for a person is said by the interface, not the adapter.
   const need = () => { if (!wallet) throw new SdkError("bad-input", { field: "wallet", state: "closed" }); };

package/src/adapters/node-test-evm-wallet.mjs

@@ -32,11 +32,11 @@ const keccak256 = (bytes) => new Uint8Array(keccakPkg(Buffer.from(bytes)));
 
 // THE ENVIRONMENT VARIABLE NAMES - HERE, IN ONE PLACE: the run and the adapter must look at the same name,
 // otherwise the key "is there" but the adapter does not see it.
-export const KEY_ENV = "ARRAKIS_TEST_EVM_KEY";
-export const KEY_FILE_ENV = "ARRAKIS_TEST_EVM_KEY_FILE";
-export const RPC_ENV = "ARRAKIS_TEST_EVM_RPC";
-export const CHAIN_ENV = "ARRAKIS_TEST_EVM_CHAIN";
-export const CLAIMER_ENV = "ARRAKIS_TEST_EVM_CLAIMER";
+export const KEY_ENV = "NINSEI_TEST_EVM_KEY";
+export const KEY_FILE_ENV = "NINSEI_TEST_EVM_KEY_FILE";
+export const RPC_ENV = "NINSEI_TEST_EVM_RPC";
+export const CHAIN_ENV = "NINSEI_TEST_EVM_CHAIN";
+export const CLAIMER_ENV = "NINSEI_TEST_EVM_CLAIMER";
 
 // AN EXPLICIT WHITELIST OF TEST NETWORKS - HERE, NOT IN THE ENGINE, and WHY. The engine's "production network" rule
 // (sdk/src/swap-flow.mjs: escrow.mode === "live" && !testnet) today does not trigger ON ANY recorded network: for

package/src/config.mjs

@@ -99,7 +99,7 @@ export const DEFAULT_XMR_NODES = Object.freeze({
     { url: "https://mainnet.xmr.kernal.eu:18089", operator: "kernal.eu" },
   ],
   stagenet: [
-    { url: "https://xmr.arrakisswap.trade", operator: "arrakisswap" },
+    { url: "https://xmr.arrakisswap.trade", operator: "ninseiswap" },
     { url: "https://stagenet.xmr.kernal.eu:38089", operator: "kernal.eu" },
   ],
 });

package/src/engine.mjs

@@ -31,6 +31,10 @@ export * as order from "../engine/atomic/order.js";
 export * as halfenc from "../engine/atomic/halfenc.js";
 // The engine's EVM layer: talking to the chain (order terms, sending, reading) - through this seam.
 export * as evm from "../engine/evm/index.js";
+// THE DEX LEG'S OWN GUARDS - THROUGH THE SAME SEAM. priceGateVerdict ("the price is not the market") and
+// dexLegVerdict (amount coverage + price) live in www/js/evm/dex.js and are re-exported here so a route provider
+// that is NOT the declared Uniswap path (CoWSwap, an aggregator) applies THE SAME guards rather than lookalikes.
+export * as dex from "../engine/evm/dex.js";
 // THE DEAL ENGINE NO LONGER LIVES IN www/js (#32, wave 3): the order flow moved into the package
 // (sdk/src/swap-flow.mjs) and is declared in sdk/index.d.ts. The page reaches it through the bridge, so the
 // mirror no longer carries core/swap-flow.js - what stays in the seam is the ORDER CLIENT (the half worker),

package/src/legs/cow-spec.mjs

@@ -0,0 +1,254 @@
+// EIP-712 TYPED DATA FOR A COW PROTOCOL ORDER - THE SPEC, IN THE SDK'S OWN STYLE.
+//
+// WHY A SEPARATE SPEC AND NOT A NEW LIBRARY. This repository builds EIP-712 typed data itself
+// (src/quoteEip712Spec.mjs is the same pattern for the order quote): the encoding words, the domain separator, the
+// struct hash and the digest are assembled here from the repository's own crypto primitives (src/primitives.mjs),
+// and the SIGNING reuses the existing signer (signQuoteDigest from src/quoteEip712Spec.mjs, which signs ANY 32-byte
+// digest). No dependency is added.
+//
+// EVERY EXTERNAL FACT IS PINNED TO ITS SOURCE, and where a value can be recomputed it is (the check does it):
+//   * ORDER type, field types and order      - cowprotocol/contracts, lib GPv2Order.sol
+//     (github.com/cowprotocol/contracts/blob/main/src/contracts/libraries/GPv2Order.sol): the TYPE_HASH is the
+//     keccak256 of the string built from GPv2Order.Data, and the contract HARD-CODES that hash next to the struct;
+//   * the TYPE_HASH constant, the kind/balance markers - the same file (TYPE_HASH, KIND_SELL, KIND_BUY,
+//     BALANCE_ERC20 are the contract's own constants; keccak256("sell"), keccak256("buy"), keccak256("erc20"));
+//   * the DOMAIN name "Gnosis Protocol", version "v2", and the domain separator shape built as
+//     keccak256(abi.encode(DOMAIN_TYPE_HASH, DOMAIN_NAME, DOMAIN_VERSION, chainId, address(this)))
+//     - cowprotocol/contracts, mixin GPv2Signing.sol
+//     (github.com/cowprotocol/contracts/blob/main/src/contracts/mixins/GPv2Signing.sol);
+//   * the settlement contract address 0x9008D19f58AAbD9eD0D60971565AA8510560ab41 (deterministic, identical on every
+//     supported network) - docs.cow.fi, "Core" contracts (docs.cow.fi/cow-protocol/reference/contracts/core);
+//   * the order UID = 56 bytes = digest(32) ++ owner(20) ++ validTo(4), and UID_LENGTH 56 - GPv2Order.sol.
+//
+// THE one fact that is NOT taken from memory is the RESULT: the check recomputes the digest of a REAL settled
+// order and demands it equal the digest half of that order's on-chain UID (fetched from the CoW order book).
+//
+// The domain type string is assembled from parts ON PURPOSE, exactly as in quoteEip712Spec.mjs: a single literal of
+// it is a phrase of several space-separated words, and the SDK reads such literals as user-facing text. Do not
+// "simplify" it. The domain NAME is assembled the same way for the same reason.
+import { keccak256, secp256k1 } from "../primitives.mjs";
+import { signQuoteDigest } from "../quoteEip712Spec.mjs";
+
+// The domain name and version, from GPv2Signing.sol (DOMAIN_NAME = keccak256("Gnosis Protocol"),
+// DOMAIN_VERSION = keccak256("v2")). Built from parts so no literal here is a multi-word phrase (see the header).
+export const COW_DOMAIN_NAME = ["Gnosis", "Protocol"].join(" ");
+export const COW_DOMAIN_VERSION = "v2";
+
+// The settlement contract that verifies the signature, identical on every network CoW supports (docs.cow.fi, Core).
+export const COW_SETTLEMENT = "0x9008D19f58AAbD9eD0D60971565AA8510560ab41";
+
+// The marker for "an order is buying native coin": it has meaning ONLY in buyToken (using it as sellToken makes the
+// settlement revert). Source: cowprotocol contracts TS docs (BUY_ETH_ADDRESS) and docs.cow.fi native-token swaps.
+export const COW_BUY_ETH_ADDRESS = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+
+// The type strings, assembled from their fields so the order is the single source of truth here (as in GPv2Order).
+const DOMAIN_TYPE_PARTS = ["EIP712Domain(", "string name,", "string version,", "uint256 chainId,", "address verifyingContract)"];
+export const COW_DOMAIN_TYPE = DOMAIN_TYPE_PARTS.join("");
+
+// The message, field by field and IN THIS ORDER - the order is the protocol (GPv2Order.Data). The types match the
+// contract's type-hash expression: kind, sellTokenBalance and buyTokenBalance are `string` in the TYPE (their value
+// is the keccak256 of the marker string), while in the struct they are the pre-hashed bytes32 markers.
+export const COW_ORDER_FIELDS = [
+  ["sellToken", "address"],
+  ["buyToken", "address"],
+  ["receiver", "address"],
+  ["sellAmount", "uint256"],
+  ["buyAmount", "uint256"],
+  ["validTo", "uint32"],
+  ["appData", "bytes32"],
+  ["feeAmount", "uint256"],
+  ["kind", "string"],
+  ["partiallyFillable", "bool"],
+  ["sellTokenBalance", "string"],
+  ["buyTokenBalance", "string"],
+];
+export const COW_ORDER_TYPE = "Order(" + COW_ORDER_FIELDS.map((f) => f[1] + " " + f[0]).join(",") + ")";
+
+// The contract's OWN type-hash constant (GPv2Order.TYPE_HASH). It is NOT trusted: the check recomputes
+// keccak256(COW_ORDER_TYPE) and demands it equal this - so a typo in the field list above reddens rather than
+// silently signing orders the settlement would reject.
+export const COW_ORDER_TYPE_HASH = "0xd5a25ba2e97094ad7d83dc28a6572da797d6b3e7fc6663bd93efb789fc17e489";
+
+// The order-kind and token-balance markers (GPv2Order.KIND_SELL / KIND_BUY / BALANCE_ERC20), derived here from the
+// repository's own keccak256 rather than copied: the check compares them against the contract's constants.
+export const COW_KINDS = ["sell", "buy"];
+export const COW_BALANCES = ["erc20", "external", "internal"];
+export const cowKindMarker = (kind) => bytesToHex(keccak256(String(kind)));
+export const cowBalanceMarker = (balance) => bytesToHex(keccak256(String(balance)));
+
+// Error tokens are SINGLE WORDS (the SDK forbids multi-word literals in sdk/src): the spec names a failure by token
+// and the caller maps it to its own code.
+const boom = (token) => { throw new Error(token); };
+
+const utf8 = (s) => new TextEncoder().encode(String(s));
+const concat = (...arrays) => {
+  const total = arrays.reduce((n, a) => n + a.length, 0);
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const a of arrays) { out.set(a, at); at += a.length; }
+  return out;
+};
+const hexToBytes = (hex) => {
+  const h = String(hex).replace(/^0x/, "");
+  if (h.length % 2) boom("cow-odd-hex");
+  const out = new Uint8Array(h.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    const byte = parseInt(h.slice(i * 2, i * 2 + 2), 16);
+    if (Number.isNaN(byte)) boom("cow-bad-hex");
+    out[i] = byte;
+  }
+  return out;
+};
+const bytesToHex = (bytes) => {
+  let s = "0x";
+  for (const b of bytes) s += b.toString(16).padStart(2, "0");
+  return s;
+};
+const asBigInt = (v) => {
+  if (typeof v === "bigint") return v;
+  const s = String(v === undefined || v === null ? "" : v).trim();
+  if (/^0x[0-9a-fA-F]+$/.test(s)) return BigInt(s);
+  if (/^[0-9]+$/.test(s)) return BigInt(s);
+  boom("cow-bad-number");
+};
+const wordUint = (v, bits) => {
+  const n = asBigInt(v);
+  if (n < 0n) boom("cow-negative");
+  if (n >= (1n << BigInt(bits))) boom("cow-overflow");
+  const out = new Uint8Array(32);
+  let x = n;
+  for (let i = 31; i >= 0 && x > 0n; i--) { out[i] = Number(x & 0xffn); x >>= 8n; }
+  return out;
+};
+const wordAddress = (v) => {
+  const s = String(v === undefined || v === null ? "" : v).trim();
+  if (!/^(0x)?[0-9a-fA-F]{40}$/.test(s)) boom("cow-bad-address");
+  const out = new Uint8Array(32);
+  out.set(hexToBytes(s.replace(/^0x/, "")), 12);
+  return out;
+};
+const wordBytes32 = (v) => {
+  const s = String(v === undefined || v === null ? "" : v).trim();
+  if (!/^(0x)?[0-9a-fA-F]{64}$/.test(s)) boom("cow-bad-bytes32");
+  return hexToBytes(s.replace(/^0x/, ""));
+};
+const wordBool = (v) => {
+  const out = new Uint8Array(32);
+  if (v === true || v === "true" || v === 1 || v === "1") out[31] = 1;
+  else if (v === false || v === "false" || v === 0 || v === "0" || v === undefined || v === null) out[31] = 0;
+  else boom("cow-bad-bool");
+  return out;
+};
+// A `string` field in EIP-712 is encoded as the keccak256 of its UTF-8 bytes - this is why the contract's
+// KIND_SELL equals keccak256("sell").
+const wordString = (v) => keccak256(utf8(v));
+
+const encodeField = (type, value) => {
+  if (type === "address") return wordAddress(value);
+  if (type === "bytes32") return wordBytes32(value);
+  if (type === "uint32") return wordUint(value, 32);
+  if (type === "uint256") return wordUint(value, 256);
+  if (type === "bool") return wordBool(value);
+  if (type === "string") return wordString(value);
+  boom("cow-bad-type");
+};
+
+// The fields an order cannot do without. An absent field is not "probably zero": the caller refuses, not signs.
+export const cowOrderMissingFields = (order) => {
+  const missing = [];
+  for (const [name] of COW_ORDER_FIELDS) {
+    const v = order ? order[name] : undefined;
+    if (v === undefined || v === null || v === "") missing.push(name);
+  }
+  return missing;
+};
+
+// The EIP-712 domain. chainId and verifyingContract come LIVE from the order's context, not cached: the digest must
+// change when either does, else an order could move between networks or settlement contracts.
+export const cowDomainSeparator = ({ chainId, settlement = COW_SETTLEMENT }) => keccak256(concat(
+  keccak256(utf8(COW_DOMAIN_TYPE)),
+  keccak256(utf8(COW_DOMAIN_NAME)),
+  keccak256(utf8(COW_DOMAIN_VERSION)),
+  wordUint(chainId, 256),
+  wordAddress(settlement),
+));
+
+export const cowStructHash = (order) => {
+  const parts = [keccak256(utf8(COW_ORDER_TYPE))];
+  for (const [name, type] of COW_ORDER_FIELDS) parts.push(encodeField(type, order ? order[name] : undefined));
+  return keccak256(concat(...parts));
+};
+
+// The digest the wallet key signs. Anything that changes here changes the recovered address.
+export const cowOrderDigest = ({ order, chainId, settlement = COW_SETTLEMENT }) =>
+  keccak256(concat(Uint8Array.from([0x19, 0x01]), cowDomainSeparator({ chainId, settlement }), cowStructHash(order)));
+
+export const cowOrderDigestHex = (ctx) => bytesToHex(cowOrderDigest(ctx));
+
+/**
+ * The order UID: 56 bytes = digest(32) ++ owner(20) ++ validTo(uint32). The order book returns this from
+ * POST /api/v1/orders and addresses the order by it. GPv2Order.packOrderUidParams.
+ */
+export const cowOrderUid = ({ digest, owner, validTo }) => {
+  const d = hexToBytes(digest);                      // must be 32 bytes
+  if (d.length !== 32) boom("cow-bad-digest");
+  const o = hexToBytes(owner);                       // must be 20 bytes
+  if (o.length !== 20) boom("cow-bad-owner");
+  const v = wordUint(validTo, 32).slice(28);         // the last 4 bytes of the uint32 word, big-endian
+  return bytesToHex(concat(d, o, v));
+};
+
+/**
+ * The typed data a wallet signs (eth_signTypedData_v4). The message carries the kind and balances as STRINGS
+ * ("sell", "erc20"), matching the type - the wallet shows them readably, and the digest the settlement computes
+ * replaces them with their keccak256 (see wordString).
+ */
+export const cowOrderTypedData = ({ order, chainId, settlement = COW_SETTLEMENT }) => ({
+  domain: { name: COW_DOMAIN_NAME, version: COW_DOMAIN_VERSION, chainId: Number(chainId), verifyingContract: settlement },
+  types: {
+    EIP712Domain: [
+      { name: "name", type: "string" },
+      { name: "version", type: "string" },
+      { name: "chainId", type: "uint256" },
+      { name: "verifyingContract", type: "address" },
+    ],
+    Order: COW_ORDER_FIELDS.map(([name, type]) => ({ name, type })),
+  },
+  primaryType: "Order",
+  message: {
+    sellToken: order.sellToken,
+    buyToken: order.buyToken,
+    receiver: order.receiver,
+    sellAmount: String(order.sellAmount),
+    buyAmount: String(order.buyAmount),
+    validTo: Number(order.validTo),
+    appData: order.appData,
+    feeAmount: String(order.feeAmount),
+    kind: String(order.kind),
+    partiallyFillable: Boolean(order.partiallyFillable),
+    sellTokenBalance: String(order.sellTokenBalance),
+    buyTokenBalance: String(order.buyTokenBalance),
+  },
+});
+
+// SIGN THE DIGEST THROUGH THE REPOSITORY'S EXISTING SIGNER: signQuoteDigest signs any 32-byte digest and returns
+// r || s || v with v in {27, 28}. No second signer is written here.
+export const signCowOrderDigest = ({ digest, privateKey }) =>
+  signQuoteDigest({ crypto: { secp256k1 }, digest, privateKey });
+
+// Recover the signer of a digest from a signature (the same rule the quote check uses): lowercase 0x address, or
+// null when the signature is not usable. The caller turns null into a NAMED refusal, never into consent.
+export const recoverCowOrderSigner = ({ digest, signature }) => {
+  try {
+    const sig = hexToBytes(String(signature).replace(/^0x/, ""));
+    if (sig.length !== 65) return null;
+    let v = sig[64];
+    if (v >= 27) v -= 27;
+    if (v !== 0 && v !== 1) return null;
+    const pub = secp256k1.Signature.fromBytes(concat(sig.slice(0, 32), sig.slice(32, 64)))
+      .addRecoveryBit(v).recoverPublicKey(digest);
+    return bytesToHex(keccak256(pub.toBytes(false).slice(1)).slice(12));
+  } catch {
+    return null;
+  }
+};