@ninsei-labs/sdk 0.40.0 → 0.42.0

package/CHANGELOG.md

@@ -1,3 +1,40 @@
+## 0.42.0 — 2026-10-12
+
+EVERY ENTRY THIS PACKAGE PUBLISHES CARRIES ITS OWN DECLARATIONS, AND THE SWEEP PAGE'S TWO PRIMITIVES ARE ON
+`./xmr`. A node that imported a subpath got no types at all - only the root had them - while a sweep page kept its
+own copies of two rules the engine already carries. Both are closed here.
+
+- `./xmr`, `./order`, `./evm`, `./core` and `./recovery` each carry a declaration file next to their barrel
+  (`src/public/<entry>.d.ts`) declaring exactly the symbols that barrel re-exports, with the signatures read off the
+  engine modules. `./recovery` opens the recovery file a sweep page reads back: `ENVELOPE_VERSION`, `FILE_MAGIC`,
+  `PAYLOAD_VERSION`, `createRecoveryFile`, `decryptFile`, `scanStartHeight` and the rest of its 11 symbols.
+- `./xmr` gains the sweep side: `spendKeysFromRevealedHalf` (the spend and view keys a revealed half yields, with the
+  check that `(s_a + s_b)*G` equals the order's public spend key before anything is swept) and `scalarFromMoneroHex`
+  (a Monero-notation key read as a number, never through `BigInt("0x" + key)`, which reverses the byte order).
+- A `types` check keeps the declarations and the runtime equal in both directions: every subpath with an import or
+  default target must declare `types` (a subpath left without them must be named, with its reason, in the check's own
+  table - `./adapters` is), the declared file must exist and read as declarations, and every symbol the barrel
+  re-exports must be declared, and nothing else. `tools/check-types-teeth.mjs` is its breaking run: four patches, each
+  RED with its own named reason, each file restored byte for byte.
+- `SDK_VERSION` is baked into `src/version.mjs` from `package.json` by `npm run sync:version`: a page cannot fetch
+  `package.json`, so the version is a value in the code, and the `version` check refuses a mismatch and refuses a
+  runtime read of the file. `engines.node` moves to `>=22`.
+- `RouteRefusalCode` declares all 33 codes the four route providers refuse with, and a `refusals` check refuses to let
+  the provider tables and the type drift apart in either direction.
+
+Nothing that already existed changed behaviour: the synchronous swap path is untouched.
+
+## 0.41.0 — 2026-10-11
+
+THE DEPOSITOR PATH IS GONE. The factory no longer offers `createOrderAndFundByDepositor`, so the package must
+stop building a call to a selector that does not exist in the deployed factory.
+
+- `src/swap-flow.mjs` no longer carries or relays `depositorSignature`: the funding path is the one where the
+  payer and the refund recipient are always the same address.
+- The engine mirror loses `evm/depositor.js` (47 modules instead of 48) and the EIP-712 spec comment now names
+  the order-quote form.
+- A consumer that meant to fund someone else's quote funds through `createOrderAndFund`.
+
 ## 0.40.0 — 2026-10-11
 
 THE ASYNCHRONOUS ROUTE PROVIDERS REACH `latest`. This release moves the tag from 0.39.3; the demo pins this exact

package/README.md

@@ -31,6 +31,13 @@ value that looks like data is more dangerous than a refusal.
 `index.d.ts` is the single source of truth about the API shape, and this is checked: `tools/check-sdk.mjs`
 compares the list of what the SDK returns with what is declared in the contract (both ways).
 
+EVERY PUBLISHED SUBPATH CARRIES ITS OWN DECLARATIONS: `.` (`index.d.ts`), `./xmr`, `./order`, `./evm`,
+`./core` and `./recovery` (`src/public/<entry>.d.ts`). Each of them declares exactly the symbols its barrel
+re-exports, so a typed consumer sees the same surface the runtime has, and nothing else.
+`tools/check.mjs --only=types` keeps the two sides equal (a subpath without a `types` target, a declarations
+file that does not read as declarations, or a symbol declared on one side only is red), and
+`tools/check-types-teeth.mjs` is its breaking run.
+
 ```js
 import { createNinsei } from "@ninsei-labs/sdk";
 
@@ -209,3 +216,7 @@ The tag is passed to `npm publish` explicitly (`--tag <tag>`), and `tools/npm-ta
 can go wrong **by name** - a prerelease that would take `latest`, and a plain version that would slide into a
 channel someone else owns. A manual run of the release workflow may override the tag with an input; when it does,
 the log says so. The derivation and its refusals are covered by `node tools/npm-tag.test.mjs`.
+
+Before the tag, the version constant moves with the version: `npm run sync:version` writes `src/version.mjs` from
+`package.json`. The number is BAKED into the code on purpose - a page cannot fetch `package.json`, and the file
+need not be served beside a bundle - so `npm run check` refuses both a mismatch and a runtime read of it.

package/engine/core/config.js

@@ -46,7 +46,7 @@ export const ENDPOINTS = Object.freeze({
 // with the page's actual origin, so a hard-coded host breaks the session on any other host.
 const PAGE_ORIGIN = typeof location !== "undefined" ? location.origin : "";
 
-// THE EIP-712 SIGNING DOMAIN (name/version) for the depositor signature. It is NOT a brand literal in the signer: it
+// THE EIP-712 SIGNING DOMAIN (name/version) for a signed order quote. It is NOT a brand literal in the signer: it
 // belongs to the registry contract (it returns DOMAIN_SEPARATOR()), so it is taken from the config here. The defaults
 // reproduce today's result byte for byte.
 export const SIGNING_DOMAIN = Object.freeze({ name: "NinseiEscrowFactory", version: "1" });

package/engine/evm/factory.js

@@ -19,9 +19,6 @@ export const FACTORY_METHODS = {
   predict: "0x0824d205",
   // create the escrow AND deposit funds in ONE transaction (a value transfer with the call).
   createOrderAndFund: "0x4703a9d3",
-  // create the escrow and deposit when the DEPOSITOR is recovered FROM THE SIGNATURE over the quote digest:
-  // anyone may send the transaction, and `locker` is set to the signer.
-  createOrderAndFundByDepositor: "0x2acd187b",
 };
 
 // The OrderCreated event topic. It grew the registry address, the provider and the signing key:
@@ -129,15 +126,6 @@ export function encodeCreateOrderAndFund(quote) {
   return FACTORY_METHODS.createOrderAndFund + quoteCallArgs(quote);
 }
 
-// CREATE AND DEPOSIT when the depositor is recovered FROM ITS SIGNATURE over the quote digest. Anyone may send
-// the transaction, so there are TWO signers: quote.signature (the provider, checked by the escrow) and
-// depositorSignature (the depositor, checked by the factory, which requires the recovered address to equal
-// quote.locker). Both over ONE digest.
-export function encodeCreateOrderAndFundByDepositor(quote, depositorSignature) {
-  return FACTORY_METHODS.createOrderAndFundByDepositor + quoteWords(quote) +
-    signatureWords(quote.signature) + signatureWords(depositorSignature) + lockerHalfWords(quote);
-}
-
 // predict() answer - one address in a 32-byte word.
 export function decodeAddress(returnedHex) {
   const hex = String(returnedHex || "").replace(/^0x/, "");

package/engine/evm/funding.js

@@ -14,10 +14,7 @@
 // keccak256 is passed in as a dependency, as in the address module: the caller loads the key library, not this
 // module. Monero and Ethereum share Keccak-256, so the hash computed by the bundle matches what Solidity checks.
 
-import { encodeCreateOrderAndFund, encodeCreateOrderAndFundByDepositor, encodePredict, decodeAddress, ORDER_CREATED_TOPIC } from "./factory.js";
-// THE DEPOSITOR BY SIGNATURE: the signature shape comes from one place (evm/depositor.js), next to the protocol
-// shape. Checking the shape here would be a second record of the same rule.
-import { depositorSignatureShape } from "./depositor.js";
+import { encodeCreateOrderAndFund, encodePredict, decodeAddress, ORDER_CREATED_TOPIC } from "./factory.js";
 import { encodeStatus, decodeStatus } from "./escrow.js";
 // THE FEE: rate, amount and recipient are PART OF THE SIGNED QUOTE. The factory no longer has them (the router was
 // removed), so the amount comes from the quote and is cross-checked by the formula mirror. Without a quote there
@@ -152,7 +149,7 @@ async function waitReceipt(receiptReader, hash, { tries = 12, delayMs = 1500 } =
 
 // The full funding path. Steps are returned outward so the interface can show each one: predict is a free call,
 // createOrder and lock are transactions in the user's wallet.
-export async function fundOrder({ factory, locker, claimer, commitHalfLocker, commitHalfClaimer, edPointLocker, edPointClaimer, edViewPointLocker, salt: providedSalt, amountWei, amountLabel, claimWindowSeconds, readyWindowSeconds, readyBy, t1, quote, depositorSignature = null, call, send, receipt, onStep }) {
+export async function fundOrder({ factory, locker, claimer, commitHalfLocker, commitHalfClaimer, edPointLocker, edPointClaimer, edViewPointLocker, salt: providedSalt, amountWei, amountLabel, claimWindowSeconds, readyWindowSeconds, readyBy, t1, quote, call, send, receipt, onStep }) {
   if (!factory) throw new Error("no escrow factory address set for this network");
   if (!locker) throw new Error("no EVM wallet connected: there is nobody to deposit");
   if (!claimer) throw new Error("the order recipient (claimer) is not set");
@@ -243,20 +240,10 @@ export async function fundOrder({ factory, locker, claimer, commitHalfLocker, co
     ? " (order " + amountWei + " + fee " + fee.feeWei + ")"
     : "";
   onStep?.("locking " + (amountLabel || "funds") + feeWords + " in one transaction - confirm in wallet");
-  // WHICH FACTORY DOOR THE DEPOSIT GOES THROUGH, AND IT IS NOT DECORATION. If a depositor signature is present, we
-  // deposit via part A: createOrderAndFundByDepositor recovers the depositor FROM THE SIGNATURE over the quote
-  // digest, so anyone may send the transaction (a relayer, our service) while the `locker` role (right to refund,
-  // right to mark readiness) stays with the signer. Without a signature, the old createOrderAndFund: one wallet
-  // deposits and sends, and the direct swap works as before. On neither path may the sender change the order terms
-  // - both signatures cover THE SAME quote digest.
-  if (depositorSignature !== null && depositorSignature !== undefined && depositorSignature !== "") {
-    const shape = depositorSignatureShape(depositorSignature);
-    if (!shape.ok) throw new Error("the depositor signature is unusable: " + shape.reason);
-  }
-  const relayedByDepositor = Boolean(depositorSignature);
-  const createData = relayedByDepositor
-    ? encodeCreateOrderAndFundByDepositor(quoteEnc, depositorSignature)
-    : encodeCreateOrderAndFund(quoteEnc);
+  // WHICH FACTORY DOOR THE DEPOSIT GOES THROUGH. There is ONE path: createOrderAndFund, where the wallet that
+  // sends the transaction becomes the locker. The sender may not change the order terms - the quote signature
+  // covers THE SAME digest the escrow checks.
+  const createData = encodeCreateOrderAndFund(quoteEnc);
   const createHash = await send({
     to: factory,
     data: createData,
@@ -300,8 +287,5 @@ export async function fundOrder({ factory, locker, claimer, commitHalfLocker, co
   // THE FEE GOES OUTWARD: it went into the transaction and the deal record must keep it - otherwise the record
   // cannot tell how much the person deposited, and it would diverge from what the chain shows.
   return { feeWei: fee.feeWei, feeTotalWei: totalValueWei, feeBps: fee.bps, feeWasLegacyFactory: Boolean(fee.legacy),
-           // WHICH FACTORY PATH RAN: visible outside, not only in the wallet's calldata. By it the checks and the
-           // deal record know whether the ETH returns to the signer and not to the sender.
-           depositorPath: relayedByDepositor,
            escrow: escrowToUse, predictedEscrow: escrow, escrowMismatch: Boolean(actualEscrow && actualEscrow !== String(escrow).toLowerCase()), salt, birthBlock, terms, createHash, lockHash };
 }

package/engine/evm/index.js

@@ -32,9 +32,8 @@ import { fundOrder } from "./funding.js";
 export * from "./factory.js";
 export * from "./escrow.js";
 export * from "./funding.js";
-// The depositor signature form (evm/depositor.js) and the permit verdict (evm/permit.js) go through the SAME
-// engine seam: the page and the SDK share one protocol code, not two lookalikes.
-export * from "./depositor.js";
+// The permit verdict (evm/permit.js) goes through the SAME engine seam: the page and the SDK share one
+// protocol code, not two lookalikes.
 export * from "./permit.js";
 // THE ASYNCHRONOUS ROUTE, EXECUTED - through the same engine seam as the decision that chooses it. The page reaches
 // it through the bridge; the SDK carries the same module in its engine mirror (tools/build-sdk-engine.mjs).
@@ -87,13 +86,10 @@ export async function simulateEscrowFunding(tx) {
 // could not pass even the first step. Neither syntax nor checks saw this, because the live path is never run.
 // FOUR FIELDS AND TWO DEADLINES EXPLICITLY. The deadlines come ready (readyBy, t1), not computed from now:
 // they go into the context the proof binds to, so they must be fixed before it.
-export async function fundOrderLive({ factory, locker, claimer, commitHalfLocker, commitHalfClaimer, edPointLocker, edPointClaimer, edViewPointLocker, salt, amountWei, amountLabel, claimWindowSeconds = 3600, readyWindowSeconds = 14400, readyBy, t1, quote, depositorSignature, onStep }) {
+export async function fundOrderLive({ factory, locker, claimer, commitHalfLocker, commitHalfClaimer, edPointLocker, edPointClaimer, edViewPointLocker, salt, amountWei, amountLabel, claimWindowSeconds = 3600, readyWindowSeconds = 14400, readyBy, t1, quote, onStep }) {
   return fundOrder({
     factory,
     quote,                         // signed quote: carries the fee, registry address and provider
-    // THE DEPOSITOR SIGNATURE OVER THE QUOTE DIGEST. Present: funding goes via
-    // createOrderAndFundByDepositor and anyone may send the transaction. Absent: the old path.
-    depositorSignature,
     locker,
     claimer,
     commitHalfLocker,

package/engine/evm/permit.js

@@ -22,8 +22,8 @@
 // cannot cover the gas - the swap settles first and the escrow is funded after it. See usdcWithoutEthVerdict below
 // and www/js/evm/asyncRoute.js - and it is a NAMED refusal only when no provider serves the network.
 //
-// THE DEPOSITOR SIGNATURE IS A DIFFERENT ALLOWANCE. It lets a relayer SEND the order-creation transaction, but
-// not pull the token. Pulling USDC needs a separate TOKEN allowance (approve or permit) addressed to the puller.
+// A RELAYED ORDER NEEDS A SEPARATE TOKEN ALLOWANCE. Letting a relayer SEND the order-creation transaction does
+// not let it pull the token. Pulling USDC needs a separate TOKEN allowance (approve or permit) addressed to the puller.
 
 // THE BALANCE-DRIVEN PATH CHOICE. Whether a provider serves a network ASYNCHRONOUSLY (an intent auction whose
 // settlement arrives later - see www/js/evm/asyncRoute.js) is what decides the path for a person with no own
@@ -179,7 +179,7 @@ export function usdcWithoutEthVerdict({
   if (!isAddr(orchestrator)) {
     return {
       ok: false, blocked: true, kind: "no-orchestrator", path: null,
-      reason: "no executor contract: only a contract could pull a token by the user signature and deposit native into the escrow in one transaction, and this build has none. The depositor signature without it lets a relayer SEND the order creation, but not pull the token",
+      reason: "no executor contract: only a contract could pull a token by the user signature and deposit native into the escrow in one transaction, and this build has none",
     };
   }
   if (permitSupported === false) {

package/engine/evm/session.js

@@ -551,12 +551,10 @@ export async function signMessage(message) {
 }
 
 // SIGNING TYPED DATA with the wallet (EIP-712, eth_signTypedData_v4). This is also NOT a transaction: the
-// signature moves no money and costs no gas, so a person WITHOUT their own ETH can give it. With it the
-// depositor lets the factory record his address in the order, and anyone may send the transaction for him
-// (the createOrderAndFundByDepositor path).
+// signature moves no money and costs no gas, so a wallet without its own ETH can give it.
 //
-// WHAT EXACTLY IS SIGNED IS DECIDED BY THE CALLER: ready typed data arrives here (www/js/evm/depositor.js),
-// not a string. Assembling the shape here would be a second record of the protocol next to the real one.
+// WHAT EXACTLY IS SIGNED IS DECIDED BY THE CALLER: ready typed data arrives here as an object, not a string.
+// Assembling the shape here would be a second record of the protocol next to the real one.
 export async function signTypedData(typedData) {
   if (!provider || state.status !== "connected") {
     throw new Error("wallet not connected: typed-data signing is impossible");

package/engine/sdk/bridge.js

@@ -68,7 +68,7 @@ import { height as nodeHeightValue } from "../monero/node.js";
 
 // THE CORE ADDRESS AS A STRING - THE BUILT BUNDLE UNDER www/: the page gets the core as ONE module, not a pile
 // of sdk/ sources; ?v=<hash> keeps the cache fresh.
-const SDK_BUNDLE = "/assets/vendors/sdk/sdk-browser.js?v=3ce64c53";
+const SDK_BUNDLE = "/assets/vendors/sdk/sdk-browser.js?v=69d79c13";
 
 // A NAMED SEAM FOR CHECKS - THE SAME TECHNIQUE AS sdkBookUse BELOW. The asynchronous path is driven against a
 // stand-in order book (the demo network has no provider), and the ordinary escrow funding that follows a settled

package/index.d.ts

@@ -494,6 +494,58 @@ export interface QuoteOffer {
   readonly networks: { readonly asset: string | null; readonly currency: string | null; readonly stated: boolean };
 }
 
+/**
+ * Every code a route provider of this package refuses with.
+ *
+ * The providers already name them in their own tables (`COW_REFUSAL_CODES` and its three siblings), and the
+ * battery proves each of those is reachable; what was missing was the TYPE, so an interface could enumerate
+ * them instead of meeting a string it cannot switch on. `broken` is shared by all four: it is the code for a
+ * case a provider could not classify.
+ *
+ * These are OUR codes, and they are what a person's message should be phrased from. A provider's OWN reason
+ * stays opaque on purpose (`QuoteRefusal.why`): that is data the provider sent, not a name of ours, so it is
+ * deliberately NOT part of this union.
+ */
+export type RouteRefusalCode =
+  // cow
+  | "cow-bad-order"
+  | "cow-bad-response"
+  | "cow-not-settled"
+  | "cow-order-unknown"
+  | "cow-refused"
+  | "cow-sign-failed"
+  | "cow-unknown-network"
+  | "cow-unreachable"
+  // kyber
+  | "kyber-bad-order"
+  | "kyber-bad-response"
+  | "kyber-not-settled"
+  | "kyber-order-unknown"
+  | "kyber-refused"
+  | "kyber-sign-failed"
+  | "kyber-unknown-network"
+  | "kyber-unreachable"
+  // uniswapx
+  | "uniswapx-bad-order"
+  | "uniswapx-bad-response"
+  | "uniswapx-no-submitter"
+  | "uniswapx-not-settled"
+  | "uniswapx-order-unknown"
+  | "uniswapx-refused"
+  | "uniswapx-sign-failed"
+  | "uniswapx-unknown-network"
+  | "uniswapx-unreachable"
+  // uniswap-relay
+  | "uniswap-relay-bad-order"
+  | "uniswap-relay-bad-response"
+  | "uniswap-relay-no-discovery"
+  | "uniswap-relay-not-settled"
+  | "uniswap-relay-sign-failed"
+  | "uniswap-relay-unknown-network"
+  | "uniswap-relay-unreachable"
+  // shared
+  | "broken";
+
 export interface QuoteRefusal {
   readonly providerId: string;
   readonly displayName: string | null;
@@ -1373,6 +1425,7 @@ export declare class SdkError extends Error {
 }
 
 /** The step codes the SDK works with (`state.step`): the same list as the `StepCode` type. */
+export declare const SDK_VERSION: string;
 export declare const STEP_CODES: readonly StepCode[];
 /** The check codes a preflight verdict names (`checks[].code`): the same list as the `CheckCode` type. */
 export declare const CHECK_CODES: readonly CheckCode[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninsei-labs/sdk",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -18,7 +18,9 @@
     "check:mirror": "node tools/check.mjs --only=mirror",
     "check:pack": "node tools/check.mjs --only=pack",
     "check:secrets": "node tools/check.mjs --only=secrets",
-    "check:sweep": "node tools/sweep-refusal.test.mjs"
+    "check:types": "node tools/check.mjs --only=types",
+    "check:types-teeth": "node tools/check-types-teeth.mjs",
+    "check:sweep": "node tools/sweep-refusal.test.mjs", "sync:version": "node tools/sync-version.mjs"
   },
   "types": "./index.d.ts",
   "exports": {
@@ -29,6 +31,26 @@
     },
     "./adapters": {
       "default": "./src/adapters/index.mjs"
+    },
+    "./xmr": {
+      "types": "./src/public/xmr.d.ts",
+      "default": "./src/public/xmr.mjs"
+    },
+    "./order": {
+      "types": "./src/public/order.d.ts",
+      "default": "./src/public/order.mjs"
+    },
+    "./evm": {
+      "types": "./src/public/evm.d.ts",
+      "default": "./src/public/evm.mjs"
+    },
+    "./core": {
+      "types": "./src/public/core.d.ts",
+      "default": "./src/public/core.mjs"
+    },
+    "./recovery": {
+      "types": "./src/public/recovery.d.ts",
+      "default": "./src/public/recovery.mjs"
     }
   },
   "files": [
@@ -40,7 +62,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "keywords": [
     "xmr",

package/src/index.mjs

@@ -270,6 +270,7 @@ export function createNinsei(options) {
 }
 
 export { SdkError, ERROR_CODES, STEP_CODES, CHECK_CODES };
+export { SDK_VERSION } from "./version.mjs";
 
 // THE LEVEL WALK IS ON THE PACKAGE SURFACE. A maker publishes a level set (chunks of volume with their own prices)
 // and both the node and the client compute a firm price by WALKING it - the client must reach the SAME price before

package/src/public/core.d.ts

@@ -0,0 +1,13 @@
+// DECLARATIONS FOR THE `./core` ENTRY.
+//
+// src/public/core.mjs only NAMES what the engine already offers; these declarations NAME the same thing for a
+// TypeScript consumer. Every signature is copied from the engine module the barrel re-exports
+// (`../../engine/core/format.js`), and a symbol the barrel does not re-export is not declared here.
+
+/**
+ * The number a person entered, in units, or null when the text carries no number.
+ *
+ * A comma without a dot is the decimal separator ("0,05" is 0.05) and a comma beside a dot separates thousands
+ * ("1,234.5" is 1234.5), so what the field shows and what the rest of the code computes cannot diverge.
+ */
+export declare function parseAmount(raw: string | number | null | undefined): number | null;

package/src/public/core.mjs

@@ -0,0 +1,6 @@
+// NEUTRAL HELPERS that the entries above and their consumers share: a decimal amount typed as text, in units.
+//
+// One function today. It is a separate entry because it belongs to neither the XMR side nor the EVM side, and a
+// consumer forced to import it from either would learn a false lesson about where it lives.
+
+export { parseAmount } from "../../engine/core/format.js";

package/src/public/evm.d.ts

@@ -0,0 +1,184 @@
+// DECLARATIONS FOR THE `./evm` ENTRY: factory calldata and the arithmetic of a claim.
+//
+// src/public/evm.mjs only NAMES what the engine already offers; these declarations NAME the same thing for a
+// TypeScript consumer. Every signature is copied from the modules the barrel re-exports
+// (`../../engine/evm/factory.js`, `../../engine/evm/claimGas.js`), and a symbol the barrel does not re-export is
+// not declared here.
+
+/** The factory's calldata selectors, computed from the contract's own signatures. */
+export declare const FACTORY_METHODS: {
+  readonly predict: string;
+  readonly createOrderAndFund: string;
+};
+
+/** The factory getters read to check the single shared escrow implementation every clone runs. */
+export declare const FACTORY_READS: {
+  readonly implementation: string;
+  readonly implementationCodeHash: string;
+};
+
+/** The OrderCreated event topic: the same value the contract declares. */
+export declare const ORDER_CREATED_TOPIC: string;
+
+/** The signed quote fields IN CONTRACT ORDER. The order is part of the ABI: a rearrangement is another call. */
+export declare const QUOTE_FIELDS: readonly string[];
+
+/**
+ * Everything `predict` and `createOrderAndFund` encode: the signed quote, the provider's signature, and the three
+ * depositor fields that travel as separate arguments (they go into the escrow's init code).
+ */
+export interface FactoryQuote {
+  readonly provider: string;
+  readonly quoteKey: string;
+  readonly registry: string;
+  readonly cashier: string;
+  readonly locker: string;
+  readonly claimer: string;
+  readonly amount: string | number | bigint;
+  readonly readyBy: string | number | bigint;
+  readonly t1: string | number | bigint;
+  readonly salt: string;
+  readonly commitHalfClaimer: string;
+  readonly edPointClaimer: string;
+  readonly chainId: string | number | bigint;
+  readonly feeBps: string | number | bigint;
+  readonly fee: string | number | bigint;
+  readonly feeRecipient: string;
+  readonly validUntil: string | number | bigint;
+  readonly nonce: string | number | bigint;
+  readonly xmrAmount: string | number | bigint;
+  /** r || s || v over the quote digest, 65 bytes, with or without the `0x` prefix. */
+  readonly signature: string;
+  readonly commitHalfLocker: string;
+  readonly edPointLocker: string;
+  readonly edViewPointLocker: string;
+}
+
+/**
+ * One calldata word: the value right-aligned to `bytes` (32 unless another width is asked for). Decimal digits are
+ * turned into hex as a NUMBER, so padding cannot change the value. Refuses anything that is neither.
+ */
+export declare function word(value: string | number | bigint, bytes?: number): string;
+
+/** The `predict` call: the argument set matches `encodeCreateOrderAndFund` byte for byte. */
+export declare function encodePredict(quote: FactoryQuote): string;
+
+/** The `createOrderAndFund` call: creation and deposit in one transaction. */
+export declare function encodeCreateOrderAndFund(quote: FactoryQuote): string;
+
+/** `predict()`'s answer - one address in a 32-byte word. */
+export declare function decodeAddress(returnedHex: string): string;
+
+/** `implementation()`'s answer. */
+export declare function decodeImplementation(returnedHex: string): string;
+
+/** `implementationCodeHash()`'s answer - one bytes32 word. */
+export declare function decodeImplementationCodeHash(returnedHex: string): string;
+
+/** The getter's calldata by name: it takes no arguments, so the selector is the whole call. */
+export declare function encodeFactoryRead(name: "implementation" | "implementationCodeHash"): string;
+
+/**
+ * The verdict on the escrow implementation, by the same three conditions the factory applies at order creation:
+ * the address is named and its code is non-empty, the recorded hash matches, and the hash is in the interface
+ * policy if one is set. Refusals are named, never silent.
+ */
+export type FactoryImplementationVerdict =
+  | {
+      readonly ok: false;
+      readonly why: string;
+      readonly codeHash?: string;
+      readonly got?: string;
+      readonly want?: string;
+    }
+  | { readonly ok: true; readonly codeHash: string };
+
+/**
+ * What the verdict is read from. `code` is the implementation's on-chain code; `hashCode` recomputes it when the
+ * carrier can hash bytes. An unreadable base is not zero: the reason names what was missing.
+ */
+export interface FactoryImplementationRequest {
+  readonly implementation?: string;
+  readonly implementationCodeHash?: string;
+  readonly code?: string | null;
+  readonly hashCode?: ((code: string) => string) | null;
+  /** The interface's own list of known builds. An empty or absent list means "no policy". */
+  readonly policy?: readonly string[] | null;
+}
+
+/** The verdict on the implementation, from the fields alone. */
+export declare function verifyFactoryImplementation(request?: FactoryImplementationRequest): FactoryImplementationVerdict;
+
+/**
+ * The verdict read at the factory itself: `implementation()`/`implementationCodeHash()` and the code at the
+ * implementation's address, then the same three conditions. The chain is injected - `read` is
+ * `eth_call({to, data}) -> hex` and `code` is `eth_getCode(address) -> hex` - so the module performs no call of
+ * its own. An unreadable pair or code is a named refusal, because an old factory without these getters reverts.
+ */
+export type FactoryImplementationOnChainVerdict =
+  | {
+      readonly ok: false;
+      readonly why: string;
+      readonly factory?: string;
+      readonly implementation?: string;
+      readonly codeHash?: string;
+      readonly got?: string;
+      readonly want?: string;
+    }
+  | { readonly ok: true; readonly codeHash: string; readonly implementation: string; readonly implementationCodeHash: string };
+
+export interface FactoryImplementationOnChainRequest {
+  readonly factory?: string;
+  readonly read?: (request: { readonly to: string; readonly data: string }) => Promise<string>;
+  readonly code?: (address: string) => Promise<string>;
+  readonly policy?: readonly string[] | null;
+  readonly hashCode?: ((code: string) => string) | null;
+}
+
+/** The pair read at the factory, with the same verdict the factory applies. */
+export declare function verifyFactoryImplementationOnChain(
+  request?: FactoryImplementationOnChainRequest,
+): Promise<FactoryImplementationOnChainVerdict>;
+
+/**
+ * The claim gas limit, MEASURED on a live chain with a margin: an honest claim costs 120 721 gas. The same
+ * number on both sides of the reverse swap.
+ */
+export declare const CLAIM_GAS_LIMIT: bigint;
+
+/** The network's tip floor. Zero where the network needs no tip, which is policy and not a constant here. */
+export declare const CLAIM_TIP_FLOOR_WEI: bigint;
+
+/** Margin for base-fee growth between the ticket and the claim, in basis points, as a node setting. */
+export declare const DEFAULT_GIFT_RESERVE_BPS: bigint;
+
+/** The fee of a claim in EIP-1559 terms: `2 x baseFee + tip`, tip not below the floor. */
+export interface ClaimMaxFeeRequest {
+  readonly baseFeeWei?: string | number | bigint | null;
+  readonly priorityFeeWei?: string | number | bigint | null;
+  readonly minTipWei?: string | number | bigint | null;
+}
+
+/** `maxFeePerGas`, or null when the base fee is unreadable or zero (no fee fields is not a zero fee). */
+export declare function claimMaxFeePerGasWei(request?: ClaimMaxFeeRequest): bigint | null;
+
+/** What the balance needs for the claim. */
+export interface ClaimRequiredRequest {
+  readonly gasLimit?: string | number | bigint | null;
+  readonly maxFeePerGasWei?: string | number | bigint | null;
+}
+
+/** `gasLimit x maxFeePerGas`, or null when either factor is unmeasured. */
+export declare function claimRequiredWei(request?: ClaimRequiredRequest): bigint | null;
+
+/** The gift the node sends to a claimer who holds no native coin. */
+export interface ClaimGasGiftRequest {
+  readonly baseFeeWei?: string | number | bigint | null;
+  readonly priorityFeeWei?: string | number | bigint | null;
+  readonly minTipWei?: string | number | bigint | null;
+  readonly gasLimit?: string | number | bigint | null;
+  readonly reserveBps?: string | number | bigint | null;
+}
+
+/** The claim cost the client requires, plus the reserve margin. The ONE computation of the gift size. */
+export declare function claimGasGiftWei(request?: ClaimGasGiftRequest): bigint | null;

package/src/public/evm.mjs

@@ -0,0 +1,29 @@
+// THE EVM SIDE: factory calldata and the arithmetic of a claim.
+//
+// A node verifies a deployed factory against the implementation it was told about, and prices the gas gift for
+// a claim. Both used to be reachable only through the page. Names only.
+
+export {
+  FACTORY_METHODS,
+  FACTORY_READS,
+  ORDER_CREATED_TOPIC,
+  QUOTE_FIELDS,
+  decodeAddress,
+  decodeImplementation,
+  decodeImplementationCodeHash,
+  encodeCreateOrderAndFund,
+  encodeFactoryRead,
+  encodePredict,
+  verifyFactoryImplementation,
+  verifyFactoryImplementationOnChain,
+  word,
+} from "../../engine/evm/factory.js";
+
+export {
+  CLAIM_GAS_LIMIT,
+  CLAIM_TIP_FLOOR_WEI,
+  DEFAULT_GIFT_RESERVE_BPS,
+  claimGasGiftWei,
+  claimMaxFeePerGasWei,
+  claimRequiredWei,
+} from "../../engine/evm/claimGas.js";