@ninsei-labs/sdk 0.41.0 → 0.42.0

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+## 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,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.41.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";

package/src/public/order.d.ts

@@ -0,0 +1,161 @@
+// DECLARATIONS FOR THE `./order` ENTRY: what a signature commits to, and the quote types it commits under.
+//
+// src/public/order.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/atomic/orderContext.js`, `../../engine/atomic/orderHalfCommit.js`,
+// `../quoteEip712Spec.mjs`), and a symbol the barrel does not re-export is not declared here.
+
+/** The order conditions a context is built from. Numbers may be decimal text, hex text or a bigint: one order. */
+export interface OrderContextFields {
+  /** The network: the same order on another network is another order. */
+  readonly chainId: string | number | bigint;
+  /** The factory that creates the escrow. */
+  readonly factory: string;
+  /** The address that deposits the settlement coin. */
+  readonly locker: string;
+  /** The address the contract pays. */
+  readonly claimer: string;
+  /** The amount in wei. */
+  readonly amount: string | number | bigint;
+  /** The readiness deadline. */
+  readonly readyBy: string | number | bigint;
+  /** The settlement deadline. */
+  readonly t1: string | number | bigint;
+  /** The order salt. */
+  readonly salt: string | number | bigint;
+}
+
+/**
+ * The prefix that separates the order context from any other signature or proof, and the version of its field
+ * set. It moves only together with that set, so a proof made under an older prefix never verifies under this one.
+ */
+export declare const ORDER_CONTEXT_VERSION: string;
+
+/**
+ * The canonical context string the DLEQ proof binds to, built from the order fields alone and identically in
+ * every implementation, so the proof can be checked from the on-chain order.
+ *
+ * Refuses (throws) an object without the fields: a partial set is not a context.
+ */
+export declare function orderContextString(order: OrderContextFields): string;
+
+/** The secp256k1 members the half commitment calls: the base point and its uncompressed encoding. */
+export interface Secp256k1BasePoint {
+  readonly multiply: (scalar: bigint) => { readonly toBytes: (isCompressed: boolean) => Uint8Array };
+}
+
+/** The secp256k1 primitive, as the engine and the SDK's own `primitives` module hand it in. */
+export interface Secp256k1Primitive {
+  readonly Point: { readonly BASE: Secp256k1BasePoint };
+}
+
+/** keccak256 over bytes - the same function Solidity's `keccak256` computes. */
+export type Keccak256 = (bytes: Uint8Array) => Uint8Array;
+
+/**
+ * The commitment to a half: `keccak256(x || y)` of the secp256k1 point `half*G`, taken UNCOMPRESSED (64 bytes,
+ * big-byte-first, like Ethereum key coordinates). The chain compares the presented half against the POINT behind
+ * this hash, not against a hash of the number, so this formula must match everywhere it is computed.
+ */
+export declare function halfCommitmentHex(
+  half: bigint | string | number,
+  secp256k1: Secp256k1Primitive,
+  keccak256: Keccak256,
+): string;
+
+/**
+ * The crypto the quote spec is bound to. The spec signs nothing itself: it is handed keccak256 and secp256k1 -
+ * the same two the SDK's `primitives` module exports.
+ */
+export interface QuoteCrypto {
+  readonly keccak256: (bytes: Uint8Array) => Uint8Array;
+  readonly secp256k1: {
+    /** A signature over the digest, `format: "recovered"`, as 65 bytes [recovery, r, s]. */
+    readonly sign: (
+      message: Uint8Array,
+      privateKey: Uint8Array,
+      options?: { readonly format?: string; readonly prehash?: boolean },
+    ) => Uint8Array;
+    readonly Signature: {
+      readonly fromBytes: (bytes: Uint8Array) => {
+        readonly addRecoveryBit: (bit: number) => {
+          readonly recoverPublicKey: (message: Uint8Array) => { readonly toBytes: (isCompressed: boolean) => Uint8Array };
+        };
+      };
+    };
+  };
+}
+
+/**
+ * A signed quote: the fields the provider's signature covers, the factory the EIP-712 domain names, and the
+ * signature itself. Field names and values are the protocol's; a missing field is refused, never read as zero.
+ */
+export interface OrderQuote {
+  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;
+  /** The escrow factory the domain names as `verifyingContract`. */
+  readonly factory: string;
+  /** r || s || v over the digest, 65 bytes, with or without the `0x` prefix; v is normalised to 27/28. */
+  readonly signature: string;
+}
+
+/** The EIP-712 domain type string, assembled from its parts. */
+export declare const EIP712_DOMAIN_TYPE: string;
+
+/** The domain name and its version string: the domain's identity, not the message shape. */
+export declare const ORDER_QUOTE_DOMAIN_NAME: string;
+export declare const ORDER_QUOTE_DOMAIN_VERSION: string;
+
+/** The request-shape generation label. It moves WITH the signed field set; the domain identity does not. */
+export declare const ORDER_QUOTE_VERSION: number;
+
+/** `[name, type]` pairs IN CONTRACT ORDER. The order is the protocol: a rearrangement moves every digest. */
+export declare const ORDER_QUOTE_FIELDS: readonly (readonly [string, string])[];
+
+/** The message type string, assembled from `ORDER_QUOTE_FIELDS`. */
+export declare const ORDER_QUOTE_TYPE: string;
+
+/**
+ * Names of the signed-set fields (`factory` and `signature` included) the quote does not carry. A non-empty
+ * answer means the quote is not verifiable at all.
+ */
+export declare function quoteMissingFields(quote: Partial<OrderQuote> | null | undefined): string[];
+
+/** The EIP-712 domain separator, with `chainId` and the factory taken live from the quote. */
+export declare function quoteDomainSeparator(request: { readonly crypto: QuoteCrypto; readonly quote: OrderQuote }): Uint8Array;
+
+/** The hash of the message struct. */
+export declare function quoteStructHash(request: { readonly crypto: QuoteCrypto; readonly quote: OrderQuote }): Uint8Array;
+
+/** The digest the provider's key signs: `0x1901` || domain separator || struct hash. */
+export declare function quoteDigest(request: { readonly crypto: QuoteCrypto; readonly quote: OrderQuote }): Uint8Array;
+
+/** The signature on the wire: r || s || v with v in {27, 28}, `0x`-prefixed. */
+export declare function signQuoteDigest(request: {
+  readonly crypto: QuoteCrypto;
+  readonly digest: Uint8Array;
+  readonly privateKey: string;
+}): string;
+
+/**
+ * The address that signed the quote, recovered without knowing it beforehand, or null when the quote cannot be
+ * verified at all. Null is a refusal for the caller to name, never consent.
+ */
+export declare function recoverQuoteKey(request: { readonly crypto: QuoteCrypto; readonly quote: OrderQuote }): string | null;

package/src/public/order.mjs

@@ -0,0 +1,22 @@
+// THE ORDER SIDE: what a signature commits to, and the quote types it commits under.
+//
+// The canonical context string, the commitment on a half key, the EIP-712 quote types and digests. Same rule
+// as ./xmr: names only, no second implementation, no browser.
+
+export { ORDER_CONTEXT_VERSION, orderContextString } from "../../engine/atomic/orderContext.js";
+export { halfCommitmentHex } from "../../engine/atomic/orderHalfCommit.js";
+
+export {
+  EIP712_DOMAIN_TYPE,
+  ORDER_QUOTE_DOMAIN_NAME,
+  ORDER_QUOTE_DOMAIN_VERSION,
+  ORDER_QUOTE_FIELDS,
+  ORDER_QUOTE_TYPE,
+  ORDER_QUOTE_VERSION,
+  quoteDigest,
+  quoteDomainSeparator,
+  quoteMissingFields,
+  quoteStructHash,
+  recoverQuoteKey,
+  signQuoteDigest,
+} from "../quoteEip712Spec.mjs";

package/src/public/recovery.d.ts

@@ -0,0 +1,243 @@
+// DECLARATIONS FOR THE `./recovery` ENTRY: the recovery file as it travels - the envelope a wallet writes and a
+// sweep page reads back.
+//
+// src/public/recovery.mjs only NAMES what the engine already offers; these declarations NAME the same thing for a
+// TypeScript consumer. Every signature is copied from the module the barrel re-exports
+// (`engine/recovery/recoveryFile.js`, itself a generated byte-for-byte copy of the engine source), and a symbol
+// the barrel does not re-export is not declared here.
+//
+// NO DOM AND NO ARGUMENTS: the module touches WebCrypto (`crypto.subtle`), `btoa`/`atob` and the text encoders,
+// so the environment hands those in and nothing has to be passed as a parameter here.
+
+/**
+ * The envelope version (encryption) - NOT the payload version inside it. 1 is a file written without AAD, 2 is a
+ * file whose header is authenticated. Both stay readable: people hold version-1 files, and a recovery file is the
+ * only way to claim their XMR.
+ */
+export declare const ENVELOPE_VERSION: number;
+
+/** The payload version (deal content), raised independently of the envelope: 1 keys as fields, 2 the mnemonic, 3 halves. */
+export declare const PAYLOAD_VERSION: number;
+
+/** The mark every Ninsei recovery file carries in its payload, so a foreign file is refused by name. */
+export declare const FILE_MAGIC: string;
+
+/** The deal fields of the envelope header that sit under authentication (`meta`). Each one is optional: a header without `meta` is still a header. */
+export interface RecoveryEnvelopeMeta {
+  /** The deal id the file belongs to. */
+  readonly id?: string | null;
+  /** The side of the deal the file was issued for. */
+  readonly side?: string | null;
+  /** When the file was written, as the deal record carries it. */
+  readonly createdAt?: string | number | null;
+  /** The order terms hash from the contract: the file's tie to the chain. */
+  readonly termsHash?: string | null;
+}
+
+/** The envelope header BEFORE encryption: the same fields also form the AAD of the ciphertext, which is why the writer and the reader build them from one place. */
+export interface RecoveryEnvelopeHeader {
+  readonly v: number;
+  /** The algorithm identifier: one string for the whole module. */
+  readonly alg: string;
+  /** The PBKDF2 iteration count, read FROM THE FILE on decryption so it can be raised without losing already issued files. */
+  readonly iter: number;
+  /** The PBKDF2 salt, base64. */
+  readonly salt: string;
+  /** The AES-GCM IV, base64. */
+  readonly iv: string;
+}
+
+/** The recovery file object as it is written (`ninsei-<id>.json.enc`) and read back. */
+export interface RecoveryEnvelope extends RecoveryEnvelopeHeader {
+  /** The AES-GCM ciphertext of the payload, base64. */
+  readonly ciphertext: string;
+  /** The authenticated deal fields of the header. */
+  readonly meta?: RecoveryEnvelopeMeta | null;
+}
+
+/**
+ * The AAD string: the header fields, in one FIXED order, that AES-GCM authenticates beside the ciphertext.
+ *
+ * Exported on purpose - the string is part of the format, so a check builds it with this same code instead of its
+ * own copy. An absent `meta` contributes nulls; any edit to a header field changes the string and decryption is
+ * refused.
+ */
+export declare function envelopeAad(envelope: RecoveryEnvelope): string;
+
+/** The heights a recovery scan may start from. All three are optional; a source that did not answer is simply not a source. */
+export interface RecoveryScanHeightRequest {
+  /** The escrow's birth height, from the creation receipt. */
+  readonly escrowBirthHeight?: string | number | null;
+  /** The height the application stored when it registered the watch - the source that survives a deal record without one. */
+  readonly serverRestoreHeight?: string | number | null;
+  /** The Monero node's current height. */
+  readonly nodeHeight?: string | number | null;
+}
+
+/**
+ * The height to start the recovery scan from: the smallest KNOWN height, one block lower and never below 1, or null
+ * when no source answered. A scan that starts below the money finds it; one that starts above never does.
+ */
+export declare function scanStartHeight(request?: RecoveryScanHeightRequest): number | null;
+
+/** One side of the payment the payload carries. */
+export interface RecoveryPayment {
+  readonly token?: string | null;
+  readonly amount?: string | number | null;
+}
+
+/** What the deal receives: XMR, at the address the file was issued for. */
+export interface RecoveryReceive {
+  readonly token?: string | null;
+  readonly amount?: string | number | null;
+  readonly address?: string | null;
+}
+
+/** The signed quote as the payload carries it: the signature, and the last eight characters of it as the nonce. */
+export interface RecoveryQuote {
+  readonly signature?: string | null;
+  readonly nonce?: string | null;
+}
+
+/** The escrow of the deal, as the deal record carries it. Fields beyond these travel through unchanged. */
+export interface RecoveryEscrow {
+  readonly address?: string | null;
+  readonly termsHash?: string | null;
+  readonly [key: string]: unknown;
+}
+
+/** A wallet built from HALVES (payload v3): no full spend key exists for anyone, so there is no mnemonic here. */
+export interface RecoveryWalletHalves {
+  readonly source?: string | null;
+  readonly library?: string | null;
+  readonly network?: string | null;
+  readonly address?: string | null;
+  readonly subaddress?: string | null;
+  /** MY half of the spend key. */
+  readonly spendHalf?: string | null;
+  /** MY half of the view key. */
+  readonly viewHalf?: string | null;
+  /** The counterparty's public spend point. */
+  readonly otherSpendPoint?: string | null;
+  /** The counterparty's public view point. */
+  readonly otherViewPoint?: string | null;
+  /** The counterparty's view HALF - not a secret: the full view key sees funds and cannot spend them. */
+  readonly otherViewHalf?: string | null;
+  /** The escrow address the revealed half is read from. */
+  readonly escrowAddress?: string | null;
+  readonly restoreHeight?: number | null;
+}
+
+/** A wallet built from a MNEMONIC (payload v1/v2): the phrase is the single source of both keys. */
+export interface RecoveryWalletMnemonic {
+  readonly source?: string | null;
+  readonly library?: string | null;
+  readonly network?: string | null;
+  readonly address?: string | null;
+  readonly subaddress?: string | null;
+  readonly mnemonic?: string | null;
+  readonly publicSpendKey?: string | null;
+  readonly publicViewKey?: string | null;
+  readonly restoreHeight?: number | null;
+}
+
+/** The Monero wallet data of the payload. Which shape it is follows the payload version. */
+export type RecoveryWallet = RecoveryWalletHalves | RecoveryWalletMnemonic;
+
+/**
+ * The payload inside the ciphertext: everything needed to complete or roll back the deal without the site.
+ *
+ * The fields are OPTIONAL on purpose - a file issued earlier carries fewer of them and must still read, and an
+ * unknown extra key is tolerated rather than refused. `magic`, `swapId`, `moneroWallet` and a supported `version`
+ * are what validation requires, and it names the one that is missing.
+ */
+export interface RecoveryPayload {
+  readonly magic?: string;
+  readonly version?: number;
+  readonly swapId?: string;
+  readonly termsHash?: string | null;
+  readonly side?: string | null;
+  readonly network?: string | null;
+  readonly moneroNetwork?: string | null;
+  readonly createdAt?: string | number | null;
+  readonly pay?: RecoveryPayment | null;
+  readonly receive?: RecoveryReceive | null;
+  readonly rate?: string | number | null;
+  readonly maker?: string | null;
+  readonly quote?: RecoveryQuote | null;
+  readonly escrow?: RecoveryEscrow | null;
+  readonly moneroWallet?: RecoveryWallet | null;
+  /** The deal's timeline, taken from the record unchanged. */
+  readonly deadlines?: unknown;
+  readonly recoveryClient?: string;
+  readonly [key: string]: unknown;
+}
+
+/** The deal record the payload is built from. Only the fields `buildPayload` reads are named here. */
+export interface RecoverySwapRecord {
+  readonly id: string;
+  readonly side?: string | null;
+  readonly network?: string | null;
+  readonly moneroNetwork?: string | null;
+  readonly createdAt?: string | number | null;
+  readonly payToken?: string | null;
+  readonly payAmount?: string | number | null;
+  readonly xmrAmount?: string | number | null;
+  readonly rate?: string | number | null;
+  readonly maker?: string | null;
+  readonly quoteSignature?: string | null;
+  readonly escrow?: RecoveryEscrow | null;
+  readonly timeline?: unknown;
+  readonly [key: string]: unknown;
+}
+
+/** Everything `buildPayload` assembles the payload from. `escrow` is the sender's COPY, not necessarily the one on the deal. */
+export interface RecoveryBuildRequest {
+  readonly swap: RecoverySwapRecord;
+  /** The wallet the file is issued for; without it no wallet block is written at all. */
+  readonly swapWallet?: RecoveryWallet | null;
+  readonly escrow?: RecoveryEscrow | null;
+  readonly receiveAddress?: string | null;
+  readonly restoreHeight?: number | null;
+}
+
+/**
+ * The payload of one deal: the deal fields, the escrow, the wallet data and the deadlines.
+ *
+ * The version tells the truth about the CONTENT, not about the module: a halves wallet is 3 and a mnemonic wallet
+ * is 2, whatever version this build happens to be.
+ */
+export declare function buildPayload(request: RecoveryBuildRequest): RecoveryPayload;
+
+/** The verdict of a successful validation: the warnings a sweep page should show, each one naming what is missing. */
+export interface RecoveryValidation {
+  readonly warnings: readonly string[];
+}
+
+/**
+ * Validates a payload AFTER decryption: garbage can decrypt too, so the magic, the version, the deal id and the
+ * wallet fields are each checked, and a refusal throws with a clear cause - and never with a secret in its text.
+ */
+export declare function validatePayload(payload: RecoveryPayload): RecoveryValidation;
+
+/**
+ * Encrypts one payload into a recovery file envelope: a fresh salt and IV, the key derived from the passphrase, and
+ * the header authenticated as AAD. A passphrase shorter than 12 characters is refused.
+ */
+export declare function encryptPayload(payload: RecoveryPayload, passphrase: string): Promise<RecoveryEnvelope>;
+
+/**
+ * Decrypts a recovery file: the envelope version, the algorithm, the required fields and the iteration count are
+ * checked BEFORE the key is derived, a version-1 file is read without AAD, and the payload is validated before it
+ * is returned. A wrong password and an altered file are both named refusals, never a silent failure.
+ */
+export declare function decryptFile(fileObject: unknown, passphrase: string): Promise<RecoveryPayload>;
+
+/** The whole file as TEXT, ready to be written: the envelope, pretty-printed, with BigInt key halves as hex strings. */
+export declare function createRecoveryFile(payload: RecoveryPayload, passphrase: string): Promise<string>;
+
+/**
+ * The name the file is written under: lowercase, tied to the deal, `ninsei-pending.json.enc` while there is no id
+ * yet. Stable, so a repeated download shows up as a second copy of one name rather than a new random file.
+ */
+export declare function recoveryFileName(swapId?: string | null): string;

package/src/public/recovery.mjs

@@ -0,0 +1,19 @@
+// THE RECOVERY FILE AS IT TRAVELS: the envelope a wallet writes and a sweep page reads back.
+//
+// A sweep page opens a file the user was given earlier and has to prove it is the file this protocol wrote, take
+// the keys out of it and start scanning from the right height. Those rules live in the engine next to this file;
+// this entry only NAMES them, so the page does not keep a copy of them to stay in step with the package.
+
+export {
+  ENVELOPE_VERSION,
+  FILE_MAGIC,
+  PAYLOAD_VERSION,
+  buildPayload,
+  createRecoveryFile,
+  decryptFile,
+  encryptPayload,
+  envelopeAad,
+  recoveryFileName,
+  scanStartHeight,
+  validatePayload,
+} from "../../engine/recovery/recoveryFile.js";

package/src/public/xmr.d.ts

@@ -0,0 +1,318 @@
+// DECLARATIONS FOR THE `./xmr` ENTRY: the Monero side for a consumer that is not the browser.
+//
+// src/public/xmr.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/monero/address.js`, `../../engine/atomic/halves.js`, `../../engine/atomic/dleq2.js`,
+// `../../engine/monero/halvesSweep.js`, `../../engine/core/sellWindow.js`), and a symbol the barrel does not
+// re-export is not declared here.
+//
+// THE PRIMITIVES ARE HANDED IN, NOT IMPORTED. These modules pull no dependencies of their own: the curve and hash
+// libraries arrive as arguments, so the types below describe the MEMBERS THE ENGINE CALLS. A real
+// `@noble/curves`/`@noble/hashes` object satisfies them.
+
+/** The Monero networks this package can build an address for, and check one against. */
+export type MoneroNetwork = "mainnet" | "stagenet" | "testnet";
+
+/** The three shapes of a Monero address. */
+export type MoneroAddressKind = "primary" | "integrated" | "subaddress";
+
+/**
+ * Network and kind -> prefix byte, the reverse table an address is assembled from.
+ *
+ * `fakechain` (monerod's own name for regtest) is deliberately absent: the withdrawal page picks that network up
+ * from the node, and there is no prefix byte to build an address with.
+ */
+export declare const PREFIX_BY_NETWORK: Readonly<Record<MoneroNetwork, Readonly<Record<MoneroAddressKind, number>>>>;
+
+/** The prefix byte of one network and kind. An unknown network or kind is refused, not guessed. */
+export declare function prefixFor(network: MoneroNetwork, kind?: MoneroAddressKind): number;
+
+/**
+ * The quick SHAPE check: base58 alphabet, 95 (plain) or 106 (integrated) characters, and a first letter that
+ * belongs to a Monero prefix. It does NOT verify the checksum - any typo inside passes here. The real check is
+ * `checkAddress`; this one only screens out obvious garbage before the heavy decode.
+ */
+export declare function formatCheck(addr: string | null | undefined): boolean;
+
+/** The network an address's first letter names, or null when the shape is not a Monero address at all. */
+export declare function networkFromShape(addr: string | null | undefined): MoneroNetwork | null;
+
+/** Whether the address is shaped as a stagenet one. */
+export declare function isStagenetShaped(addr: string | null | undefined): boolean;
+
+/**
+ * Block-based Monero base58: a block is a NUMBER, full 8-byte blocks come first (11 characters each) and the
+ * partial remainder goes LAST, so this is not bitcoin-base58 and `bs58` does not fit.
+ */
+export declare function decodeMoneroBase58(str: string): Uint8Array;
+
+/** The inverse of `decodeMoneroBase58`: bytes to a Monero base58 string. */
+export declare function encodeMoneroBase58(bytes: Uint8Array | readonly number[]): string;
+
+/** The address payload without its checksum: prefix + public spend + public view [+ payment id]. */
+export interface AddressPayloadRequest {
+  readonly network: MoneroNetwork;
+  readonly kind?: MoneroAddressKind;
+  /** The 32-byte public spend key, hex. */
+  readonly spendPub: string;
+  /** The 32-byte public view key, hex. */
+  readonly viewPub: string;
+  /** The 8-byte payment id, hex: required for `kind: "integrated"`. */
+  readonly paymentId?: string;
+}
+
+/** The address payload: prefix, both public keys, and the payment id when the address is integrated. */
+export declare function addressPayload(request: AddressPayloadRequest): Uint8Array;
+
+/** keccak256 over bytes. The address checksum is its first four bytes, as in Monero itself. */
+export type Keccak256Bytes = (bytes: Uint8Array) => Uint8Array;
+
+/** What assembling an address needs: keccak256, and a Buffer shim for implementations taking only their own. */
+export interface AddressKeysDeps {
+  readonly keccak256: Keccak256Bytes;
+  readonly Buffer?: { readonly from: (bytes: Uint8Array) => Uint8Array };
+}
+
+/** The address string built from public keys, with the checksum appended. */
+export declare function addressFromKeys(request: AddressPayloadRequest, deps: AddressKeysDeps): string;
+
+/**
+ * The full check: format, block decode, keccak256 checksum and network.
+ *
+ * `verified` says whether the checksum could be verified at all: without the Monero bundle the answer is
+ * `ok: true, verified: false` with the reason named, never a false "checked". A refusal always names WHY.
+ */
+export type AddressCheck =
+  | { readonly ok: false; readonly reason: string }
+  | { readonly ok: true; readonly verified: false; readonly network: MoneroNetwork | null; readonly reason: string }
+  | { readonly ok: true; readonly verified: true; readonly network: MoneroNetwork; readonly kind: MoneroAddressKind; readonly bytes: number };
+
+/** The full check of one address. Refuses an address of another network when `expectNetwork` names one. */
+export declare function checkAddress(addr: string, options?: { readonly expectNetwork?: MoneroNetwork }): Promise<AddressCheck>;
+
+/** An address of the right network, built from the wallet's own keys. Needs the Monero bundle for keccak256. */
+export declare function addressForNetwork(request: AddressPayloadRequest): Promise<string>;
+
+/** A curve point, as the halves and the DLEQ modules call it. */
+export interface CurvePoint {
+  readonly multiply: (scalar: bigint) => CurvePoint;
+  readonly add: (other: CurvePoint) => CurvePoint;
+  readonly toHex: () => string;
+}
+
+/** The curve members the halves module calls. */
+export interface CurvePrimitive {
+  readonly Point: {
+    readonly BASE: CurvePoint;
+    /** The group order: the smaller of the two is the limit a half must fit into. */
+    readonly Fn: { readonly ORDER: bigint };
+    readonly fromHex: (hex: string) => CurvePoint;
+  };
+}
+
+/** The five primitives the halves module is handed. */
+export interface HalvesPrimitives {
+  readonly ed25519: CurvePrimitive;
+  readonly secp256k1: CurvePrimitive;
+  readonly keccak256: Keccak256Bytes;
+  readonly randomBytes: (length: number) => Uint8Array;
+}
+
+/** The halves module: one half of a key per side, public on both curves. */
+export interface Halves {
+  /** The smaller of the two group orders: a half must fit into both groups. */
+  readonly LIMIT: bigint;
+  readonly ED_ORDER: bigint;
+  readonly SECP_ORDER: bigint;
+  /** The domain strings of the spend half and the view half: quoting and payout take them from here. */
+  readonly HALF_DOMAIN: string;
+  readonly VIEW_HALF_DOMAIN: string;
+  /** A uniform scalar below the limit, drawn by rejection sampling. */
+  readonly newHalf: () => bigint;
+  /**
+   * The half derived from a secret and the order binding, so the same order always gives the same half and only
+   * the secret holder can compute it.
+   */
+  readonly halfFromSeed: (seedBytes: Uint8Array, binding: string | number | bigint, domain?: string) => bigint;
+  /** The public halves on both curves. */
+  readonly publicHalves: (half: bigint | string | number) => { readonly ed: string; readonly secp: string };
+  /** The sum of two halves, privately. */
+  readonly combineHalves: (a: bigint | string | number, b: bigint | string | number) => bigint;
+  /** The sum of two halves, publicly (point addition). */
+  readonly combinePublic: (edHexA: string, edHexB: string) => string;
+}
+
+/** Creates the halves module from the five primitives. Each one is required, and its absence is named. */
+export declare function createHalves(primitives: HalvesPrimitives): Halves;
+
+/** A curve point, as the DLEQ module calls it. */
+export interface Dleq2Point {
+  readonly multiply: (scalar: bigint) => Dleq2Point;
+  readonly add: (other: Dleq2Point) => Dleq2Point;
+  readonly subtract: (other: Dleq2Point) => Dleq2Point;
+  readonly equals: (other: Dleq2Point) => boolean;
+  readonly toHex: () => string;
+  /** True when the point is in the prime-order subgroup (`[l]*P = 0`), not merely free of a small component. */
+  readonly isTorsionFree: () => boolean;
+  /** Builds the multiplication table of the given window size at the first multiplication. */
+  readonly precompute: (windowSize: number) => void;
+}
+
+/** The curve members the DLEQ module calls. */
+export interface Dleq2CurvePrimitive {
+  readonly Point: {
+    readonly BASE: Dleq2Point;
+    readonly Fn: { readonly ORDER: bigint };
+    readonly fromHex: (hex: string) => Dleq2Point;
+  };
+}
+
+/** The primitives the DLEQ module is handed. SHA3-512 is mandatory: the challenge is its wide reduction. */
+export interface Dleq2Primitives {
+  readonly ed25519: Dleq2CurvePrimitive;
+  readonly secp256k1: Dleq2CurvePrimitive;
+  readonly keccak256: Keccak256Bytes;
+  /** SHA3-512, NOT keccak256: the challenge is a 64-byte hash read least-significant byte first. */
+  readonly sha3_512: (bytes: Uint8Array) => Uint8Array;
+  readonly randomBytes: (length: number) => Uint8Array;
+}
+
+/** The OR proof of one bit on both curves. Scalars and points travel as hex, so the proof survives JSON. */
+export interface Dleq2Signature {
+  readonly eA: string;
+  readonly eB: string;
+  readonly a0: string;
+  readonly a1: string;
+  readonly b0: string;
+  readonly b1: string;
+}
+
+/** The proof of one bit: the bit's commitments on both curves and the ring signature over them. */
+export interface Dleq2ProofPart {
+  readonly cA: string;
+  readonly cB: string;
+  readonly sig: Dleq2Signature;
+}
+
+/** The proof: the point X on both curves, and one part per bit of the smaller group order. */
+export interface Dleq2Proof {
+  readonly XA: string;
+  readonly XB: string;
+  readonly proofs: readonly Dleq2ProofPart[];
+}
+
+/** One bit prepared for proving: the bit, its commitments and its randomness. The half is NOT here. */
+export interface Dleq2PreparedBit {
+  readonly i: number;
+  readonly bit: 0 | 1;
+  readonly cA: string;
+  readonly cB: string;
+  readonly rA: string;
+  readonly rB: string;
+}
+
+/** Step 1's output: the points and one prepared bit per bit. Depends on the running sum, so it is one piece. */
+export interface Dleq2Prepared {
+  readonly XA: string;
+  readonly XB: string;
+  readonly context: string;
+  readonly bits: readonly Dleq2PreparedBit[];
+}
+
+/** The verifier's answer. A refusal NAMES the bit and the reason; it never throws. */
+export interface Dleq2Verdict {
+  readonly ok: boolean;
+  readonly reason?: string;
+}
+
+/** One of the two curves the module holds, with the alternate base point its ring signature uses. */
+export interface Dleq2Curve {
+  readonly name: string;
+  readonly P: Dleq2CurvePrimitive["Point"];
+  readonly order: bigint;
+  readonly G: Dleq2Point;
+  readonly Galt: Dleq2Point;
+}
+
+/** The DLEQ module: proving is assembled from three steps, and the steps can be run apart. */
+export interface Dleq2 {
+  /** The bit length of the smaller order: the number of proof parts an honest proof carries. */
+  readonly BITS: number;
+  readonly curves: { readonly A: Dleq2Curve; readonly B: Dleq2Curve };
+  /** The whole proof. `onBit` reports progress every 16 bits and at the last. */
+  readonly prove: (x: bigint | string | number, context: string, onBit?: (done: number, total: number) => void) => Dleq2Proof;
+  /** Verifies a proof of untrusted shape: form is checked before counting, and every refusal is named. */
+  readonly verify: (proof: unknown, context: string) => Dleq2Verdict;
+  /** Step 1: the commitments. Sequential by construction. */
+  readonly prepareProof: (x: bigint | string | number, context: string) => Dleq2Prepared;
+  /** Step 2: one bit, on the prepared data alone - it needs neither the half nor the other bits. */
+  readonly proveBit: (part: Dleq2PreparedBit, context: string) => Dleq2ProofPart;
+  /** Step 3: the parts are put in bit order, and a missing bit is refused. */
+  readonly assembleProof: (prepared: Dleq2Prepared, parts: readonly Dleq2ProofPart[]) => Dleq2Proof;
+  /** The strict subgroup check. secp256k1 has cofactor 1 and passes without a check. */
+  readonly torsionFree: (curve: Dleq2Curve, point: Dleq2Point) => boolean;
+}
+
+/** Creates the DLEQ module from the five primitives. Without SHA3-512 it refuses immediately. */
+export declare function createDleq2(primitives: Dleq2Primitives): Dleq2;
+
+/**
+ * What sweeping from a revealed half is handed: the half maths, this side's two halves as the file carries them,
+ * the counterparty's public spend key and view half, and the half the counterparty revealed.
+ */
+export interface SpendKeysFromRevealedHalfRequest {
+  readonly halves: Halves;
+  /** This side's spend half, from the file: it arrives as a string and is converted before any arithmetic. */
+  readonly ownSpendHalf: string | number | bigint;
+  /** This side's view half, from the file. */
+  readonly ownViewHalf: string | number | bigint;
+  /** The counterparty's public spend key, hex: the point the order carried. */
+  readonly otherSpendPoint: string;
+  /** The counterparty's view half, hex. */
+  readonly otherViewHalf: string | number | bigint;
+  /** The revealed half, hex. */
+  readonly revealedHalf: string | number | bigint;
+}
+
+/** The two private keys a sweep writes with, in Monero notation: 64 hex, least significant byte first. */
+export interface SpendKeys {
+  readonly privateSpendKey: string;
+  readonly privateViewKey: string;
+}
+
+/**
+ * The spend and view keys a revealed half yields, or a THROW when the half does not belong to this order.
+ *
+ * The commitment only proves that the HASH of the revealed half matched the order, and ed25519 does not exist in
+ * the EVM, so the check that `(s_a + s_b)*G` equals the order's public spend key happens HERE, before any
+ * synchronisation: a half from another order, or a substituted one, yields no keys.
+ */
+export declare function spendKeysFromRevealedHalf(request: SpendKeysFromRevealedHalfRequest): SpendKeys;
+
+/**
+ * A Monero-notation key read as a number: 64 hex, least significant byte first. A key that is not in that notation
+ * is refused rather than reinterpreted - `BigInt("0x" + key)` silently reverses the byte order and gives another
+ * scalar.
+ */
+export declare function scalarFromMoneroHex(hex: string): bigint;
+
+/**
+ * The XMR sell window: the SOFT on-screen promise (how long the provider holds the price) and the HARD contract
+ * window, which goes into the order binding and can never be shorter than the contract's own.
+ */
+export declare const SELL_WINDOW: {
+  /** The provider's on-screen promise, in seconds. */
+  readonly softSec: number;
+  /** The contract readiness window, in seconds: ten Monero confirmations, and the maximum that goes on chain. */
+  readonly hardSec: number;
+};
+
+/**
+ * How long the sell window lasts, given the named pool state: while the FULL expected amount is not visible in
+ * the pool the promise is extended to the contract maximum, and the contract window is a CEILING on it.
+ */
+export declare function sellWindowSec(request?: {
+  readonly poolSeen?: boolean;
+  readonly soft?: number;
+  readonly hard?: number;
+}): number;

package/src/public/xmr.mjs

@@ -0,0 +1,29 @@
+// THE XMR SIDE, FOR A CONSUMER THAT IS NOT THE BROWSER.
+//
+// A node that quotes, signs and later reveals a half key needs the same arithmetic the page uses: an address
+// built from two public points, the half keys, the DLEQ proof, the maker's sell window. All of it lives in the
+// engine next to this file; this entry only NAMES it, so a node can depend on a released version of this
+// package instead of reaching into another repository's source. Nothing is re-implemented here, and nothing
+// here is browser-specific - these modules touch no window, document or storage.
+
+export {
+  PREFIX_BY_NETWORK,
+  addressForNetwork,
+  addressFromKeys,
+  addressPayload,
+  checkAddress,
+  decodeMoneroBase58,
+  encodeMoneroBase58,
+  formatCheck,
+  isStagenetShaped,
+  networkFromShape,
+  prefixFor,
+} from "../../engine/monero/address.js";
+
+export { createHalves } from "../../engine/atomic/halves.js";
+export { createDleq2 } from "../../engine/atomic/dleq2.js";
+
+// THE SWEEP SIDE: the spend keys a revealed half yields, and the scalar a Monero hex string carries.
+export { scalarFromMoneroHex, spendKeysFromRevealedHalf } from "../../engine/monero/halvesSweep.js";
+
+export { SELL_WINDOW, sellWindowSec } from "../../engine/core/sellWindow.js";

package/src/version.mjs

@@ -0,0 +1,9 @@
+// THE PACKAGE VERSION AS A VALUE, BAKED INTO THE CODE.
+//
+// A consumer that has to agree with a peer on a minor line - a node refusing a client built from a different
+// minor - needs the number at runtime, and a page cannot fetch it: package.json is not part of a bundle and need
+// not be served beside it. So the number is a constant, and this file is GENERATED from package.json by
+// tools/sync-version.mjs. Do not edit it by hand - set the version in package.json and run `npm run sync:version`.
+// The `version` check in tools/check.mjs refuses a mismatch, and refuses a runtime read of package.json here.
+
+export const SDK_VERSION = "0.42.0";