@ninsei-labs/sdk 0.39.0

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@ninsei-labs/sdk",
+  "version": "0.39.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "packageManager": "pnpm@9.15.9",
+  "description": "XMR <-> EVM swap engine: quotes, guards, order steps, recovery (no DOM, no user-facing strings)",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/index.mjs",
+  "scripts": {
+    "check": "node tools/check.mjs",
+    "check:syntax": "node tools/check.mjs --only=syntax",
+    "check:import": "node tools/check.mjs --only=import",
+    "check:surface": "node tools/check.mjs --only=surface",
+    "check:mirror": "node tools/check.mjs --only=mirror",
+    "check:language": "node tools/check.mjs --only=language",
+    "check:pack": "node tools/check.mjs --only=pack",
+    "check:secrets": "node tools/check.mjs --only=secrets"
+  },
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.mjs",
+      "default": "./src/index.mjs"
+    },
+    "./adapters": {
+      "default": "./src/adapters/index.mjs"
+    }
+  },
+  "files": [
+    "src",
+    "engine",
+    "index.d.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "xmr",
+    "monero",
+    "evm",
+    "ethereum",
+    "atomic-swap",
+    "cross-chain",
+    "swap",
+    "sdk",
+    "quotes",
+    "guards",
+    "recovery",
+    "esm",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ninsei-Labs/sdk.git"
+  },
+  "homepage": "https://github.com/Ninsei-Labs/sdk#readme",
+  "bugs": {
+    "url": "https://github.com/Ninsei-Labs/sdk/issues"
+  },
+  "dependencies": {
+    "@noble/curves": "^2.4.0",
+    "@noble/hashes": "^2.4.0",
+    "keccak256": "^1.0.6"
+  },
+  "sideEffects": false
+}

package/src/actions.mjs

@@ -0,0 +1,72 @@
+// ORDER ACTIONS: MARKING READY, CLAIMING, REFUNDING.
+//
+// All three go through ONE wallet seam (the `send`/`receipt` role) and through the slot check that in the engine
+// stands BEFORE signing. What is added here is exactly what the engine cannot do: `expect` is MANDATORY.
+//
+// Why it is mandatory. The slot check compares the order we assembled with the one lying on the chain. Without
+// expectations there is nothing to compare against, and the signature goes out under an order whose commitments
+// nobody checked: for marking ready that is granting a foreign address the right to take the settlement, for
+// claiming it is revealing your own half (irreversible), for refunding the same reveal. The transaction still
+// looks successful.
+import { SdkError } from "./errors.mjs";
+import * as engine from "./engine.mjs";
+// THE DEAL FLOW IS NOW A PACKAGE MODULE, NOT AN ENGINE FILE (#32, wave 3): www/js/core/swap-flow.js moved to
+// sdk/src/swap-flow.mjs. The actions therefore call the module directly instead of reaching it through the
+// mirror - there is exactly one implementation, and it lives here.
+import * as flow from "./swap-flow.mjs";
+
+const missingFields = (object, fields) =>
+  fields.filter((k) => object[k] === undefined || object[k] === null || object[k] === "");
+
+const walletOrFail = (wallet) => {
+  const role = ["send", "receipt"];
+  const missing = wallet ? role.filter((k) => typeof wallet[k] !== "function") : role;
+  if (missing.length) throw new SdkError("bad-input", { field: "wallet", missing });
+  return wallet;
+};
+
+const requestOrFail = (request, extra) => {
+  if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
+  const missing = missingFields(request, ["escrow", "expect", ...extra]);
+  if (missing.length) throw new SdkError("bad-input", { field: "request", missing });
+  return request;
+};
+
+// The engine's refusal arrives as text; a CODE goes out. Texts are the interface's business, the core speaks in codes.
+const withCodes = async (step, work) => {
+  try { return await work(); }
+  catch (error) {
+    if (error && typeof error.code === "string") throw error;
+    throw new SdkError("contract-reverted", { step });
+  }
+};
+
+export function createActions({ call = null } = {}) {
+  // WHAT READS THE CHAIN IS ALSO A SEAM, and not only for the checks: the slot check and the signature must go
+  // ONE way, otherwise part of the check goes past the wallet and part does not. By default - the engine's read.
+  const reader = call || engine.evm.readContract;
+  const deps = (wallet) => ({ call: reader, send: (tx) => wallet.send(tx), receipt: (h) => wallet.receipt(h) });
+  return {
+    /** Marking "I saw the XMR on the shared address". Without it, claiming is forbidden by the contract. */
+    async markReady(request, wallet) {
+      requestOrFail(request, []);
+      walletOrFail(wallet);
+      const { escrow, expect, onStep } = request;
+      return await withCodes("mark-ready", () => flow.markReadyOrder({ escrow, expect, onStep, deps: deps(wallet) }));
+    },
+    /** Claiming: it reveals your own half, so expectations are mandatory. */
+    async claim(request, wallet) {
+      requestOrFail(request, ["halfClaimer"]);
+      walletOrFail(wallet);
+      const { escrow, halfClaimer, expect, onStep } = request;
+      return await withCodes("claim", () => flow.claimOrder({ escrow, halfClaimer, expect, onStep, deps: deps(wallet) }));
+    },
+    /** Refunding: it also reveals a half. The core passes the expectations ALWAYS, though the engine does not require them. */
+    async refund(request, wallet) {
+      requestOrFail(request, ["halfLocker"]);
+      walletOrFail(wallet);
+      const { escrow, halfLocker, expect, onStep } = request;
+      return await withCodes("refund", () => flow.refundOrder({ escrow, halfLocker, expect, onStep, deps: deps(wallet) }));
+    },
+  };
+}

package/src/adapters/evm-wallet.mjs

@@ -0,0 +1,126 @@
+// THE EVM WALLET: a wrapper over an EIP-1193 provider.
+//
+// The SDK core knows only the adapter interface (vm, connect, address, chainId, subscribe, driver). The provider is
+// brought by the interface - injected, WalletConnect, anything: the SDK does not look for wallets itself and does
+// not open windows.
+//
+// The EVM leg driver gets the provider through `driver()` and makes eth_* calls through it. For another VM its own
+// adapter will appear (`tronWallet`, `solanaWallet`), and the core will not need to change for it.
+const hexToInt = (value) => (typeof value === "string" && /^0x[0-9a-f]+$/i.test(value) ? Number.parseInt(value, 16) : null);
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+
+import { SdkError } from "../errors.mjs";
+// THE NETWORK REGISTRY - THROUGH THE ENGINE'S SEAM. Adding a network to the wallet (wallet_addEthereumChain)
+// requires the network's name, native coin, rpc and explorer, and all of that is already in the registry the page
+// uses (www/js/evm/session.js, switchChain). The adapter keeps no network table of its own and invents no
+// addresses.
+import { config as engineConfig } from "../engine.mjs";
+
+const hexChainId = (id) => "0x" + Number(id).toString(16);
+// 4902 - the wallet does not know such a network; older wallets answer with text, so we check that too.
+const CHAIN_UNKNOWN = 4902;
+const isUnknownChain = (error) => {
+  const code = error && (error.code || (error.data && error.data.originalError && error.data.originalError.code));
+  return code === CHAIN_UNKNOWN || /unrecognized chain|not added/i.test(String((error && error.message) || ""));
+};
+const isRejected = (error) => (error && error.code === 4001) || /rejected|denied/i.test(String((error && error.message) || ""));
+
+export function evmWallet(provider, { id = "evm" } = {}) {
+  const handoff = [];
+  return {
+    vm: "evm",
+    id,
+    async connect({ chainId = null } = {}) {
+      try {
+        await provider.request({ method: "eth_requestAccounts" });
+      } catch (error) {
+        const rejected = error && (error.code === 4001 || error.code === "ACTION_REJECTED");
+        const failure = new Error(rejected ? "wallet-rejected" : "wallet-not-connected");
+        failure.code = rejected ? "wallet-rejected" : "wallet-not-connected";
+        throw failure;
+      }
+      if (Number.isFinite(chainId)) {
+        const current = hexToInt(await provider.request({ method: "eth_chainId" }).catch(() => null));
+        if (current !== Number(chainId)) await this.switchChain(chainId);
+      }
+    },
+    async disconnect() {
+      while (handoff.length) {
+        const [event, handler] = handoff.pop();
+        if (typeof provider.removeListener === "function") provider.removeListener(event, handler);
+      }
+    },
+    async address() {
+      const accounts = await provider.request({ method: "eth_accounts" }).catch(() => null);
+      const first = Array.isArray(accounts) ? accounts[0] : null;
+      return typeof first === "string" && ADDRESS_RE.test(first) ? first : null;
+    },
+    async chainId() {
+      return hexToInt(await provider.request({ method: "eth_chainId" }).catch(() => null));
+    },
+    subscribe(handler) {
+      if (typeof provider.on !== "function") return () => {};
+      for (const event of ["accountsChanged", "chainChanged"]) {
+        const wrapped = () => handler();
+        provider.on(event, wrapped);
+        handoff.push([event, wrapped]);
+      }
+      return () => {};
+    },
+    // THE SAME PATH AS THE PAGE (www/js/evm/session.js, switchChain): first wallet_switchEthereumChain, and if the
+    // wallet does not know such a network - offer to add it via wallet_addEthereumChain. The data for adding is
+    // taken from the engine's registry, not from a private table.
+    async switchChain(chainId) {
+      const target = Number(chainId);
+      const hex = hexChainId(target);
+      try {
+        await provider.request({ method: "wallet_switchEthereumChain", params: [{ chainId: hex }] });
+      } catch (error) {
+        if (!isUnknownChain(error)) throw new SdkError(isRejected(error) ? "wallet-rejected" : "wrong-chain", { vm: "evm" });
+        const chain = typeof engineConfig.chainByChainId === "function" ? engineConfig.chainByChainId(target) : null;
+        // The network is not in the registry - there is nothing to add it with, and the rpc/explorer must not be
+        // invented: we name the refusal with a code.
+        if (!chain) throw new SdkError("wrong-chain", { vm: "evm", chainId: target });
+        try {
+          await provider.request({
+            method: "wallet_addEthereumChain",
+            params: [{
+              chainId: hex,
+              chainName: chain.name,
+              nativeCurrency: { name: chain.native.symbol, symbol: chain.native.symbol, decimals: chain.native.decimals },
+              rpcUrls: [chain.rpcUrl],
+              blockExplorerUrls: [chain.explorerAddr],
+            }],
+          });
+        } catch (error2) {
+          throw new SdkError(isRejected(error2) ? "wallet-rejected" : "wrong-chain", { vm: "evm" });
+        }
+      }
+    },
+    // SENDING A TRANSACTION AND THE RECEIPT. Without them the funds cannot be locked: signing is possible only in
+    // the wallet, and confirmation of execution arrives as a receipt.
+    //
+    // THERE IS DELIBERATELY NO POLLING HERE: `receipt` asks once and returns the receipt, or null if the transaction
+    // is not in a block yet. The waiting policy (how long, how often, what on refusal) is set by the caller: a
+    // policy of its own inside the adapter would mean two calls wait differently.
+    async send({ to, data = "0x", value = 0n, gas = null }) {
+      if (typeof to !== "string" || !to) throw new SdkError("bad-input", { field: "send.to" });
+      const accounts = await provider.request({ method: "eth_accounts" });
+      const from = Array.isArray(accounts) ? accounts[0] : null;
+      if (!from) throw new SdkError("wallet-not-connected", { step: "send" });
+      const hex = (v) => "0x" + BigInt(v).toString(16);
+      // GAS IS PASSED IF THE CALLER SET IT: every contract call has its own estimate (marking ready, claiming,
+      // refunding), and it comes from the same place as the calldata - the engine's EVM layer.
+      const tx = { from, to, data, value: hex(value) };
+      if (gas !== null && gas !== undefined) tx.gas = hex(gas);
+      return await provider.request({ method: "eth_sendTransaction", params: [tx] });
+    },
+    async receipt(txHash) {
+      if (typeof txHash !== "string" || !txHash) throw new SdkError("bad-input", { field: "receipt.txHash" });
+      return await provider.request({ method: "eth_getTransactionReceipt", params: [txHash] });
+    },
+    driver() {
+      return provider;
+    },
+  };
+}

package/src/adapters/index.mjs

@@ -0,0 +1,21 @@
+// ADAPTERS THE INTERFACE WIRES IN EXPLICITLY.
+//
+// Two different kinds of adapters, and both are here because both are about the environment, not the core:
+//   wallet  - a wrapper over a concrete way to sign (today EVM/EIP-1193; later Tron, Solana);
+//   storage - where unfinished swaps live (localStorage today, memory in tests).
+//
+// This directory is the only place in the SDK allowed to touch the DOM and to know about the browser
+// environment (enforced by machine in tools/check-sdk.mjs).
+export { evmWallet } from "./evm-wallet.mjs";
+export { localStorageAdapter, memoryAdapter } from "./local-storage.mjs";
+export { moneroWallet } from "./monero.mjs";
+// THE MONERO WALLET FOR THE CORE - SEPARATE FROM THE WITHDRAWAL WALLET. `moneroWallet` above plays the XMR
+// withdrawal role (open/sync/sweepUnlocked/relay); `moneroWalletAdapter` plays the SDK wallet role (vm/connect/
+// address/chainId/unlockedBalance/subscribe/driver). One file for two roles would mix their surfaces.
+export { moneroWalletAdapter } from "./monero-wallet.mjs";
+// A TOOL OF THE TEST CONTOUR - SEPARATE FROM THE PAGE'S WALLET. It signs with its own key (the key comes only
+// from the environment or a file) and refuses to sign on a production network by the engine's marker, so it is
+// only good for local runs. A separate line here also because every file in the directory must be reachable
+// through the package's map: otherwise the adapter exists but cannot be imported.
+export { nodeTestEvmWallet, evmRpcReader, evmRpcProvider, testPrivateKeyFromEnv, isProductionChain, addressOfPrivateKey }
+  from "./node-test-evm-wallet.mjs";

package/src/adapters/local-storage.mjs

@@ -0,0 +1,32 @@
+// A READY-MADE STORAGE ADAPTER FOR THE BROWSER. The only SDK file allowed to touch the DOM.
+//
+// Why it is kept separate and wired in explicitly: the SDK core must load in bare Node (this is checked by
+// machine), while `localStorage` exists only in the browser. An interface that needs browser storage writes
+// `import { localStorageAdapter } from "@ninsei-labs/sdk/adapters"` - that is, it makes the DOM decision.
+//
+// The adapter is deliberately thin: the swap storage is the interface's data, and it may replace it with
+// sessionStorage, IndexedDB or memory (tests).
+
+export function localStorageAdapter(scope = "ninsei.sdk") {
+  const key = (name) => scope + "." + name;
+  return {
+    get(name) {
+      return localStorage.getItem(key(name));
+    },
+    set(name, value) {
+      localStorage.setItem(key(name), String(value));
+    },
+    remove(name) {
+      localStorage.removeItem(key(name));
+    },
+  };
+}
+
+export function memoryAdapter(initial = {}) {
+  const map = new Map(Object.entries(initial));
+  return {
+    get: (name) => (map.has(name) ? map.get(name) : null),
+    set: (name, value) => map.set(name, String(value)),
+    remove: (name) => map.delete(name),
+  };
+}

package/src/adapters/monero-wallet.mjs

@@ -0,0 +1,185 @@
+// THE MONERO WALLET ADAPTER FOR THE SDK CORE: network, its own address, free remainder, sync, stop.
+//
+// WHAT THIS IS AND HOW IT DIFFERS FROM ITS NEIGHBOUR. Next to it lies `monero.mjs` - it plays a DIFFERENT role: it
+// is the XMR WITHDRAWAL wallet for `sweep.run` (open / sync / unlockedBalance / sweepUnlocked / relay / close).
+// Here is a wallet connected to the core through THE SAME interface as the EVM wallet (`vm`, `connect`,
+// `disconnect`, `address`, `chainId`, `subscribe`, `driver`) plus `unlockedBalance` - the method the core reads
+// the free remainder with (sdk/src/wallet.mjs). The roles differ, and they must not be mixed: a withdrawal and a
+// wallet have different surfaces.
+//
+// THE LIBRARY COMES FROM OUTSIDE - THERE IS NO WALLET BUILD OF ITS OWN HERE. The wallet is built BY THE SAME CALL
+// the withdrawal page builds it with (sweep/sweep.js): `createWalletFull({ networkType, server: { uri }, password,
+// restoreHeight, seed | privateSpendKey/privateViewKey/primaryAddress })`, then `getAddress(0, 0)`,
+// `setRestoreHeight`, `getRestoreHeight`, `sync`, `getUnlockedBalance`, `close`. The names were taken from the page
+// and verified by a run against the installed monero-ts 0.11.17 build, not chosen from memory. The function is
+// brought through the `createWallet` parameter (in the browser - `api.createWalletFull` from the bundle, in node -
+// from monero-ts): the core drags in neither WASM nor the page's 3.6 MB worker. The same technique as
+// `moneroWallet` for withdrawal.
+//
+// THE NETWORK IS NOT INVENTED. The network name is checked against the core's registry (www/js/core/config.js,
+// XMR_NETWORKS) through the sdk/src/engine.mjs seam, and the SHAPE of its own address - by the same address module
+// as the demo's (www/js/monero/address.js, networkFromShape): an address of another network is rejected with a
+// CODE, not returned as a balance of the wrong chain.
+//
+// REFUSALS - WITH CODES. No library, no network, no node, no key, no height, wallet not connected: an SdkError
+// with a code and params. Neither `null` nor a zero in place of the answer: an empty address and a zero balance
+// look like real data, and that is exactly why they are not returned.
+import { SdkError } from "../errors.mjs";
+import { config as engineConfig, xmrAddress } from "../engine.mjs";
+
+const XMR_VM = "monero";
+// The wallet session label - the same as the withdrawal page's. This is not a secret and not an address, but a session name.
+const DEFAULT_PASSWORD = "arrakis-wallet-session";
+
+/** Monero network names declared by the core's registry. The adapter keeps no table of its own. */
+const knownNetworks = () => {
+  const declared = engineConfig.XMR_NETWORKS || {};
+  return [...new Set(Object.values(declared).filter((v) => typeof v === "string" && v))].sort();
+};
+
+/**
+ * The Monero wallet as an SDK wallet adapter.
+ *
+ * createWallet - the library function (`createWalletFull`): without it there is nothing to build the wallet with,
+ *   and `connect` answers with a code rather than trying to guess the library;
+ * network      - a network name from the core's registry (`stagenet`/`mainnet`/`testnet`), as monero-ts accepts it;
+ * serverUri    - the node (in production - a proxy, on the stand - your own node);
+ * keys         - `{ seed }` or `{ privateSpendKey, privateViewKey, primaryAddress }` - the page's shape;
+ * restoreHeight- the restore height: without it a scan of the whole Monero history takes tens of hours;
+ * expectedAddress - if set, the derived address must match (otherwise the file/key is wrong).
+ */
+export function moneroWalletAdapter({
+  createWallet = null,
+  network = null,
+  serverUri = null,
+  password = DEFAULT_PASSWORD,
+  keys = {},
+  restoreHeight = 0,
+  expectedAddress = null,
+} = {}) {
+  let wallet = null;
+  let address = null;
+  const listeners = new Set();
+
+  const notify = () => {
+    for (const handler of listeners) {
+      try { handler(); } catch { /* a subscriber must not break the wallet */ }
+    }
+  };
+
+  const need = (surface) => {
+    if (wallet === null) throw new SdkError("wallet-not-connected", { vm: XMR_VM, surface });
+    return wallet;
+  };
+
+  // THE KEY SHAPE - the same one the page passes to createWalletFull. The primary address is required when a view
+  // key is set: the page caught this with the message "must provide primary address if providing private view key".
+  const keyFields = () => {
+    if (typeof keys.seed === "string" && keys.seed) return { seed: keys.seed };
+    if (keys.privateSpendKey || keys.privateViewKey) {
+      if (!keys.primaryAddress) throw new SdkError("bad-input", { field: "primaryAddress", why: "required-with-private-keys" });
+      const fields = {};
+      if (keys.privateSpendKey) fields.privateSpendKey = keys.privateSpendKey;
+      if (keys.privateViewKey) fields.privateViewKey = keys.privateViewKey;
+      fields.primaryAddress = keys.primaryAddress;
+      return fields;
+    }
+    throw new SdkError("bad-input", { field: "keys", missing: ["seed", "privateSpendKey"] });
+  };
+
+  const close = async () => {
+    if (wallet === null) return undefined;
+    const current = wallet;
+    wallet = null;
+    address = null;
+    try { await current.close(); } catch { /* stopping must not break the report */ }
+    return undefined;
+  };
+
+  return {
+    vm: XMR_VM,
+    id: XMR_VM,
+
+    // CREATING THE WALLET - BY THE SAME PATH AS THE PAGE. The order of checks: library -> network -> node -> key ->
+    // height. Each missing item is its OWN code with a named field, not a general refusal.
+    async connect() {
+      if (typeof createWallet !== "function") throw new SdkError("bad-input", { field: "createWallet" });
+      const declared = knownNetworks();
+      if (typeof network !== "string" || !network) throw new SdkError("bad-input", { field: "network", known: declared });
+      if (declared.length && !declared.includes(network)) throw new SdkError("bad-input", { field: "network", known: declared, got: network });
+      if (typeof serverUri !== "string" || !serverUri) throw new SdkError("bad-input", { field: "serverUri" });
+      // THE KEY AND THE HEIGHT ARE A CONDITION OF WORK, NOT A SETTING: without the key the wallet cannot be built,
+      // without the height a scan of the whole Monero history takes tens of hours (the page's measurement: the height
+      // is not an optimization but a condition of work).
+      const fields = keyFields();
+      const height = Number(restoreHeight);
+      if (!Number.isFinite(height) || height <= 0) throw new SdkError("bad-input", { field: "restoreHeight", got: restoreHeight });
+
+      await close();
+      const created = await createWallet({
+        networkType: network,
+        server: { uri: serverUri },
+        password,
+        restoreHeight: height,
+        ...fields,
+      });
+      wallet = created;
+      // THE ADDRESS AND THE NETWORK. The address is derived from the keys and is available before syncing; its
+      // network must match the named one. The check is done by the page's code (www/js/monero/address.js), not by a
+      // private prefix form.
+      address = String(await wallet.getAddress(0, 0));
+      const shape = typeof xmrAddress.networkFromShape === "function" ? xmrAddress.networkFromShape(address) : null;
+      if (shape && shape !== network) { await close(); throw new SdkError("wrong-chain", { got: shape, want: network }); }
+      if (expectedAddress && address !== expectedAddress) { await close(); throw new SdkError("recovery-failed", { step: "address" }); }
+      // THE HEIGHT IS SET EXPLICITLY AND READ BACK: on a live run the height passed when the wallet was created was
+      // not applied (the page set it with a second call). We set it - so that the restore height becomes a FACT that
+      // can be read (`driver().getRestoreHeight()`), not a promise.
+      await wallet.setRestoreHeight(height);
+      notify();
+      return undefined;
+    },
+
+    async disconnect() { return await close(); },
+
+    // THE NAME FROM THE PAGE: sweep/sweep.js stops the wallet via close(). The same action, the same name.
+    async close() { return await close(); },
+
+    address() {
+      need("address");
+      return address;
+    },
+
+    // THE MONERO NETWORK IS NAMED BY A WORD (stagenet/mainnet), not by the settlement network's chainId: there is
+    // nothing to compare against - Monero has no leg contract (sdk/src/wallet.mjs, XMR_VM).
+    chainId() { return network; },
+
+    // THE FREE REMAINDER - the same method as the XMR withdrawal (the page: getUnlockedBalance), and the same
+    // atomic units (1 XMR = 10^12). Zero comes as zero ONLY when the wallet is connected and the node answered so.
+    async unlockedBalance() { return await need("unlockedBalance").getUnlockedBalance(); },
+
+    // SYNCING - a separate call (the page calls wallet.sync()). Subscribers are notified AFTER the pass.
+    async sync() {
+      await need("sync").sync();
+      notify();
+      return undefined;
+    },
+
+    // THE MONERO WALLET HAS NO EVENTS (monero-ts has no on/removeListener): a subscriber receives a notification
+    // after connect and after sync, and the subscription promises nothing more. Unsubscribing is the same as the EVM
+    // adapter's.
+    subscribe(handler) {
+      if (typeof handler !== "function") throw new SdkError("bad-input", { field: "handler" });
+      listeners.add(handler);
+      return () => listeners.delete(handler);
+    },
+
+    // SENDING A LEG TRANSACTION IS NOT THE MONERO WALLET'S BUSINESS. The XMR withdrawal can transfer XMR
+    // (sweepUnlocked / relayTxs, see monero.mjs). Here is a refusal with a NAMED surface, not a silent null.
+    async send() { throw new SdkError("not-implemented", { surface: "adapter.send", vm: XMR_VM }); },
+    async receipt() { throw new SdkError("not-implemented", { surface: "adapter.receipt", vm: XMR_VM }); },
+
+    // WHAT THE ADAPTER WORKS WITH: the library's wallet itself (it has getHeight, getDaemonHeight, sweepUnlocked and
+    // the like). Before connecting - null: there is no wallet yet, and pretending there is one is not allowed.
+    driver() { return wallet; },
+  };
+}

package/src/adapters/monero.mjs

@@ -0,0 +1,51 @@
+// THE MONERO WALLET AS AN ADAPTER. The core does not drag in WASM or a worker: the library is provided by whoever
+// builds the page.
+//
+// The method names are the ones the sweep page already calls on monero-ts (sweep/sync/getUnlockedBalance/
+// sweepUnlocked/relayTxs/close), so the adapter sits on top of it without adapters, and the core stays DOM-free.
+//
+// IMPORTANT ABOUT WITHDRAWAL SAFETY: signing and sending are split. sweepUnlocked({ relay: false }) only signs;
+// sending is a separate call. That way the interface has a point where it can show the person what exactly will
+// leave, BEFORE sending rather than after.
+import { SdkError } from "../errors.mjs";
+
+export function moneroWallet({ createWallet, networkType, serverUri, password = "arrakis-sweep-session", fields = {} }) {
+  const build = typeof createWallet === "function" ? createWallet : null;
+  // Refusals - with CODES, as everywhere in the core: the phrase for a person is said by the interface, not the adapter.
+  const need = () => { if (!wallet) throw new SdkError("bad-input", { field: "wallet", state: "closed" }); };
+  let wallet = null;
+
+  return {
+    async open(plan) {
+      if (!build) throw new SdkError("bad-input", { field: "createWallet" });
+      wallet = await build({
+        networkType: plan.networkType || networkType,
+        server: { uri: serverUri },
+        password,
+        restoreHeight: Number(plan.restoreHeight) || 0,
+        address: plan.address,
+        ...fields,
+      });
+      return undefined;
+    },
+    async sync() {
+      need();
+      await wallet.sync();
+    },
+    async unlockedBalance() {
+      need();
+      return await wallet.getUnlockedBalance();
+    },
+    async sweepUnlocked({ address, relay }) {
+      need();
+      return await wallet.sweepUnlocked({ address, relay });
+    },
+    async relay(signed) {
+      need();
+      return await wallet.relayTxs(signed);
+    },
+    async close() {
+      if (wallet) { try { await wallet.close(); } catch { /* closing must not break the report */ } wallet = null; }
+    },
+  };
+}