@ninsei-labs/sdk 0.41.0 → 0.42.1

package/CHANGELOG.md

@@ -1,3 +1,45 @@
+## 0.42.1 — 2026-10-12
+
+THE BID SIDE OF THE QUOTE WALK ROUNDED THE WRONG WAY. The specification fixes a rounding DIRECTION per side, and
+the walk rounded both sides alike: a bid price came out up to 3 wei high and disagreed with the reference at a
+level boundary.
+
+- Per-level rounding follows the side now: a level's cost rounds up on the ask side, where the user pays, and down
+  on the bid side, where the user is paid; the XMR amount a budget yields at a level rounds up on the bid side.
+- The level-fits test is asymmetric: a level is taken whole when `remaining >= full` on the ask side and when
+  `remaining > full` on the bid side.
+- This removes a systematic 1-to-3-wei over-charge on bid prices and the disagreement with the reference at level
+  boundaries.
+
+Checks: `node tools/check.mjs` - all 19 green; `node tools/sync-version.mjs`, `node tools/npm-tag.test.mjs`, the two
+teeth runs and `tools/sweep-refusal.test.mjs` are green too.
+
+## 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

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/index.d.ts

@@ -494,6 +494,81 @@ 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. `RouteRefusalTables` below declares what those tables ARE - each of them a
+ * `readonly RouteRefusalCode[]` - so the union is the tables' TYPE and not a comment standing beside them.
+ *
+ * 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";
+
+/**
+ * WHAT THE FOUR REFUSAL TABLES *ARE*. Each route provider names its own refusals in one table - `COW_REFUSAL_CODES`
+ * (src/legs/cow.mjs), `KYBER_REFUSAL_CODES` (src/legs/kyber.mjs), `UNISWAPX_REFUSAL_CODES` (src/legs/uniswapx.mjs) and
+ * `UNISWAPRELAY_REFUSAL_CODES` (src/legs/uniswaprelay.mjs) - and every one of those tables is a
+ * `readonly RouteRefusalCode[]`. The dependency runs ONE WAY on purpose: a table answers to the union (a code that is
+ * not declared above cannot enter a table), while the union answers to no single table, so the same vocabulary is
+ * met in four modules.
+ *
+ * THEY ARE NOT ON THIS ENTRY'S SURFACE, and this is deliberately NOT a value: the package re-exports no provider and
+ * no table (src/index.mjs), the tables travel in the shipped source (`files` in package.json) and they are the
+ * VOCABULARY, not an API. A `declare const` here that the runtime does not export would be a lie, and the `surface`
+ * check refuses exactly that - so the tables are declared as their TYPE. That is what keeps the union from being a
+ * comment beside the tables: this declaration says what they are, and the `refusals` check says the same thing from
+ * the other side - a table declared here as a plain `readonly string[]` is a named problem there.
+ */
+export interface RouteRefusalTables {
+  readonly COW_REFUSAL_CODES: readonly RouteRefusalCode[];
+  readonly KYBER_REFUSAL_CODES: readonly RouteRefusalCode[];
+  readonly UNISWAPX_REFUSAL_CODES: readonly RouteRefusalCode[];
+  readonly UNISWAPRELAY_REFUSAL_CODES: readonly RouteRefusalCode[];
+}
+
 export interface QuoteRefusal {
   readonly providerId: string;
   readonly displayName: string | null;
@@ -1373,6 +1448,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.41.0",
+  "version": "0.42.1",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -18,7 +18,11 @@
     "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:refusals": "node tools/check.mjs --only=refusals",
+    "check:refusals-teeth": "node tools/check-refusals-teeth.mjs",
+    "check:sweep": "node tools/sweep-refusal.test.mjs", "sync:version": "node tools/sync-version.mjs"
   },
   "types": "./index.d.ts",
   "exports": {
@@ -29,6 +33,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 +64,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/levelsWalkSpec.mjs

@@ -19,7 +19,9 @@
 //   3. the first level sets the minimum deal size (there is no separate min);
 //   4. an EMPTY set = the side is off, and that is NOT an error;
 //   5. the walk goes BOTH ways: "I give asset - how much XMR" and "I give XMR - how much asset";
-//   6. rounding to atomic units is in the maker's favour;
+//   6. rounding to atomic units is in the maker's favour, EACH LEVEL ON ITS OWN: up on ask, where the user pays,
+//      down on bid, where the user is paid; the answer in XMR is rounded the maker's way too, down for a buyer
+//      (ask) and up for a seller (bid);
 //   7. one orientation: volume in XMR, price in the asset per 1 XMR;
 //   8. a fixed swap fee (fee in wei, separate for each side): the buyer pays the walk PLUS the fee, the seller
 //      receives the walk MINUS the fee. It is NOT spread over the volume: otherwise the average price would fall
@@ -83,51 +85,65 @@ export function checkLevels(levels, orientation = "ask") {
   return { ok: true, enabled: true, count: levels.length, minAtomic: toBigInt(levels[0].amount), totalAtomic };
 }
 
-// THE COST OF A CHUNK OF VOLUME IN WEI, ROUNDED UP (rule 6, in the maker's favour).
-function levelCostWei(amountAtomic, priceWeiPerXmr) {
-  const num = amountAtomic * priceWeiPerXmr;
-  return (num + XMR_ATOMIC_PER_ONE - 1n) / XMR_ATOMIC_PER_ONE;
+// ROUND A NON-NEGATIVE FRACTION TO A WHOLE UNIT: up, or down. Money is BigInt only (rule 10); the fraction is
+// non-negative where this is reached (amounts and prices are positive, a budget is positive).
+function divRound(num, den, up) {
+  const q = num / den;
+  return up && q * den < num ? q + 1n : q;
 }
 
-// HOW MANY XMR ATOMS A BUDGET GIVES WITHIN ONE LEVEL, ROUNDED DOWN (rule 6).
-function levelXmrForBudget(budgetWei, priceWeiPerXmr) {
-  return (budgetWei * XMR_ATOMIC_PER_ONE) / priceWeiPerXmr;
+// THE COST OF A CHUNK OF VOLUME IN THE ASSET, ONE LEVEL AT A TIME (rule 6). Rounding is always in the maker's
+// favour: UP on ask, where the user pays, DOWN on bid, where the node pays the user. A walk rounds each level on
+// its own and adds the levels up, as the node does: rounding the sum once would differ by up to a unit per level,
+// and the node would sign the maker another amount than its journal books.
+function levelCostWei(amountAtomic, priceWeiPerXmr, orientation) {
+  return divRound(amountAtomic * priceWeiPerXmr, XMR_ATOMIC_PER_ONE, orientation === "ask");
 }
 
-// THE FULL COST OF A SIDE (the sum of its levels' costs) and its volume - computed once.
-function sideSummary(levels) {
+// HOW MANY XMR ATOMS A BUDGET GIVES WITHIN ONE LEVEL (rule 6). The answer in XMR is rounded the maker's way too:
+// DOWN for a buyer (ask), UP for a seller (bid). At a coarse asset several atomic units pay the same, and a
+// seller sends no more of them than the payout needs.
+function levelXmrForBudget(budgetWei, priceWeiPerXmr, orientation) {
+  return divRound(budgetWei * XMR_ATOMIC_PER_ONE, priceWeiPerXmr, orientation === "bid");
+}
+
+// THE FULL COST OF A SIDE (the sum of its levels' costs, each rounded on its own) and its volume - computed once.
+function sideSummary(levels, orientation) {
   let totalAtomic = 0n;
   let fullCostWei = 0n;
   for (const level of levels) {
     const amount = toBigInt(level.amount);
     const price = toBigInt(level.price);
     totalAtomic += amount;
-    fullCostWei += levelCostWei(amount, price);
+    fullCostWei += levelCostWei(amount, price, orientation);
   }
   return { totalAtomic, fullCostWei };
 }
 
-// THE WALK WITHOUT THE FEE: a budget is given - how much XMR it yields (rounding down within a level, rule 6).
-function walkXmrForBudget(levels, budgetWei) {
+// THE WALK WITHOUT THE FEE: a budget is given - how much XMR it yields (each level rounded on its own, rule 6).
+function walkXmrForBudget(levels, budgetWei, orientation) {
   let remaining = budgetWei;
   let xmrAtomic = 0n;
   for (const level of levels) {
     const amount = toBigInt(level.amount);
     const price = toBigInt(level.price);
-    const full = levelCostWei(amount, price);
-    if (remaining >= full) {
+    const full = levelCostWei(amount, price, orientation);
+    // The maker's way once more: a buyer (ask) takes a level whole even when the budget only just reaches it; a
+    // seller (bid) sends no more than the payout needs, so an exact match is left to the partial step, rounded up.
+    const fits = orientation === "ask" ? remaining >= full : remaining > full;
+    if (fits) {
       xmrAtomic += amount;
       remaining -= full;
       continue;
     }
-    xmrAtomic += levelXmrForBudget(remaining, price);
+    xmrAtomic += levelXmrForBudget(remaining, price, orientation);
     break;
   }
   return xmrAtomic;
 }
 
-// THE WALK WITHOUT THE FEE: an XMR volume is given - what it costs (each chunk's cost rounded up, rule 6).
-function walkCostForXmr(levels, xmrAtomic) {
+// THE WALK WITHOUT THE FEE: an XMR volume is given - what it costs (each chunk's cost rounded on its own, rule 6).
+function walkCostForXmr(levels, xmrAtomic, orientation) {
   let left = xmrAtomic;
   let costWei = 0n;
   for (const level of levels) {
@@ -135,7 +151,7 @@ function walkCostForXmr(levels, xmrAtomic) {
     const amount = toBigInt(level.amount);
     const price = toBigInt(level.price);
     const take = left < amount ? left : amount;
-    costWei += levelCostWei(take, price);
+    costWei += levelCostWei(take, price, orientation);
     left -= take;
   }
   return costWei;
@@ -166,16 +182,16 @@ export function xmrForAsset({ levels, role, feeWei = 0n, assetWei, orientation =
   if (asset === null || fee === null || fee < 0n) return { ok: false, reason: "levels-not-integer", role };
   const budget = role === "buy" ? asset - fee : asset + fee;
   if (budget <= 0n) return { ok: false, reason: "levels-fee-beyond-budget", role };
-  const { fullCostWei } = sideSummary(levels);
+  const { fullCostWei } = sideSummary(levels, orientation);
   if (budget > fullCostWei) return { ok: false, reason: "levels-exceed-side", role };
   // THE SMALLEST TRADE, from the set AS THE MAKER SENT IT (rule 3): callers pass it in minAtomic and the
   // node's deductions never change it. Absent, the set's own first level is used, as it always was.
   const min = minOf(levels, minAtomic);
   // Its cost ON THE EFFECTIVE SET: after deductions the smallest trade may reach into a later level, so the
   // cost is walked, not read off one price.
-  const minCost = walkCostForXmr(levels, min);
+  const minCost = walkCostForXmr(levels, min, orientation);
   if (budget < minCost) return { ok: false, reason: "levels-below-minimum", role };
-  const xmrAtomic = walkXmrForBudget(levels, budget);
+  const xmrAtomic = walkXmrForBudget(levels, budget, orientation);
   return { ok: true, role, xmrAtomic, assetWei: asset };
 }
 
@@ -193,7 +209,7 @@ export function assetForXmr({ levels, role, feeWei = 0n, xmrAtomic, orientation
   if (want > verdict.totalAtomic) return { ok: false, reason: "levels-exceed-side", role };
   // THE SMALLEST TRADE AS THE MAKER SENT IT, never the effective set's first level (rule 3): see minOf.
   if (want < minOf(levels, minAtomic)) return { ok: false, reason: "levels-below-minimum", role };
-  const walkWei = walkCostForXmr(levels, want);
+  const walkWei = walkCostForXmr(levels, want, orientation);
   const assetWei = role === "buy" ? walkWei + fee : walkWei - fee;
   if (assetWei <= 0n) return { ok: false, reason: "levels-fee-beyond-budget", role };
   return { ok: true, role, xmrAtomic: want, assetWei };

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";