mycomesh-consumer 0.2.1 → 0.4.0

package/README.md

@@ -8,26 +8,32 @@ Requires Node.js 20 or newer. No Docker or Python.
 
 ```sh
 npm install --global mycomesh-consumer
-mycomesh-consumer init
-mycomesh-consumer setup --owner-key-file owner.key --faucet 100000000 --deposit 100000000
-mycomesh-consumer request "What is MycoMesh?"
-mycomesh-consumer serve          # http://127.0.0.1:8110/v1 (responses, chat/completions, models; streaming)
+mycomesh-consumer init            # payment key + password-protected owner wallet
+mycomesh-consumer setup --deposit 20000000
+mycomesh-consumer request --stream "What is MycoMesh?"
+mycomesh-consumer serve           # http://127.0.0.1:8110/v1 (responses, chat/completions, models; live streaming)
 ```
 
-- `init` creates the payment key in `~/.mycomesh/v11` (it never leaves the machine).
-- `setup` uses the owner account (which needs Sepolia ETH for gas) to deposit
-  tUSDC and authorize the payment key up to `--max-per-request` units per request.
-  `--faucet UNITS` first mints testnet tUSDC to the owner.
-- `balance --owner-key-file owner.key` shows the deposit.
+- `init` creates the payment key and an owner wallet in `~/.mycomesh/v11`. The wallet is an
+  Ethereum V3 keystore (MetaMask can import it) protected by a password from
+  `MYCOMESH_WALLET_PASSWORD` or a terminal prompt; `--owner-key-file` uses your own key instead.
+- `setup --deposit UNITS` deposits tUSDC and authorizes the payment key up to `--max-per-request`
+  units per request. On the testnet it first tops the wallet up from the faucet (gas ETH and tUSDC);
+  `faucet` does that on its own.
+- `balance` shows the deposit.
 - `request "..." [--model gpt-5.5] [--provider SIGNER]` prints the verified answer,
   the fee and the settlement key.
-- `serve` runs a local OpenAI-compatible endpoint for Codex and other clients;
-  set `MYCOMESH_CONSUMER_API_KEY` to require a bearer token.
-- `dispute <settlement-key|last> --owner-key-file owner.key --statement "..."`
+- `serve` runs the local web console at `http://127.0.0.1:8110/` (chat, wallet, deposit and
+  withdrawal, request history and disputes, network status) and an OpenAI-compatible endpoint for
+  Codex and other clients; set `MYCOMESH_CONSUMER_API_KEY` to require a bearer token. Only pages from
+  this machine can call it: other websites and DNS-rebinding hosts are refused.
+- `withdraw [UNITS]` requests a withdrawal; run it again after the delay to receive the funds.
+- `dispute <settlement-key|last> --statement "..."`
   reveals a recorded request and response to a randomly drawn Provider-AI jury
   within the 24-hour dispute window. The 1 tUSDC reporter bond is returned and a
   bounty paid when fraud is confirmed.
 
 Each response is decrypted locally and checked against the Provider-signed
-receipt before it is shown. The bundled network manifest is
+receipt before it is shown; streamed text is checked against it too. Relays come from the bundled
+manifest and the on-chain Relay directory. The bundled network manifest is
 `networks/mycomesh-v11-sepolia.json`; use `--network FILE` for another.

package/networks/mycomesh-v11-sepolia.json

@@ -5,6 +5,7 @@
   "settlement": "0xd46b7efb1e650e83cdeb4a36fdfef33499e54842",
   "stablecoin": "0xbce27efad4191277167fe76819581a97959048cf",
   "registry": "0x0ff3210e8e8abf5f5bfa73a39e60db7416b6c8c7",
+  "relay_directory": "0xa0aaad9393f51cb5786c69f152133a174588bdab",
   "deployment_block": 11809185,
   "rpc_urls": [
     "https://ethereum-sepolia-rpc.publicnode.com",
@@ -12,6 +13,7 @@
     "https://sepolia.gateway.tenderly.co"
   ],
   "tls_ca_file": "mycomesh-testnet-ca.crt",
+  "faucet_url": "https://136.0.3.126:10443",
   "relays": [
     {
       "url": "https://136.0.3.126:10443",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mycomesh-consumer",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "MycoMesh V11 Consumer: a custodied deposit, relay-blind encrypted requests to any Provider, and a local OpenAI-compatible endpoint.",
   "repository": {
     "type": "git",
@@ -16,6 +16,7 @@
   "files": [
     "bin/mycomesh-consumer.mjs",
     "src/*.mjs",
+    "src/web/*.html",
     "networks/mycomesh-v11-sepolia.json",
     "networks/mycomesh-testnet-ca.crt",
     "README.md"

package/src/account.mjs

@@ -0,0 +1,93 @@
+// Consumer account operations shared by the CLI and the local web console.
+import { addressOf, encodeCall } from "./eip712.mjs";
+import { rpcCall, sendTransaction } from "./chain.mjs";
+import { directoryRelays, httpJson } from "./consumer.mjs";
+import { buildEvidence, evidenceHash, openDisputeCall, reportId } from "./disputes.mjs";
+
+export const STATUSES = ["none", "pending", "disputed", "released", "confirmed", "dismissed", "timed_out", "jury_unavailable", "voided"];
+
+async function words(network, to, signature, pairs = []) {
+  const raw = (await rpcCall(network.rpc_urls, "eth_call", [{ to, data: encodeCall(signature, pairs) }, "latest"])).slice(2);
+  return Array.from({ length: raw.length / 64 }, (_, i) => BigInt(`0x${raw.slice(i * 64, i * 64 + 64)}`));
+}
+
+/** Balances of the owner wallet and the payment key's grant; amounts are strings of base units. */
+export async function walletStatus(network, owner, key) {
+  const [eth, [tokens], [deposit], withdrawal, grant, params] = await Promise.all([
+    rpcCall(network.rpc_urls, "eth_getBalance", [owner, "latest"]),
+    words(network, network.stablecoin, "balanceOf(address)", [["address", owner]]),
+    words(network, network.settlement, "availableBalance(address)", [["address", owner]]),
+    words(network, network.settlement, "withdrawals(address)", [["address", owner]]),
+    key ? words(network, network.settlement, "keyGrants(address)", [["address", key]]) : Promise.resolve(null),
+    words(network, network.settlement, "params()"),
+  ]);
+  return {
+    owner, key, eth_wei: BigInt(eth).toString(), wallet_tokens: tokens.toString(), deposit: deposit.toString(),
+    withdrawal: { amount: withdrawal[0].toString(), available_at: Number(withdrawal[1]) },
+    grant: grant && { active: Boolean(grant[3]) && `0x${grant[0].toString(16).padStart(40, "0")}` === owner.toLowerCase(),
+      max_per_request: grant[1].toString() },
+    dispute_window: Number(params[0]), reporter_bond: params[3].toString(), faucet: Boolean(network.faucet_url),
+  };
+}
+
+export async function faucet(network, address) {
+  if (!network.faucet_url) throw new Error("this network has no faucet");
+  const reply = await httpJson(`${network.faucet_url}/v11/faucet`, { method: "POST", body: { address }, ca: network.tls_ca, timeoutMs: 400_000 });
+  if (reply.status !== 200) throw new Error(`faucet: ${reply.body?.error || reply.status}`);
+  return reply.body;
+}
+
+/** Deposit and grant the payment key; on testnets, top the wallet up from the faucet first. */
+export async function setup(network, { ownerPrivate, key, deposit, limit, forceFaucet = false, log = () => {} }) {
+  const owner = addressOf(ownerPrivate);
+  const status = await walletStatus(network, owner, key);
+  if (network.faucet_url && (forceFaucet || BigInt(status.eth_wei) < 2_000_000_000_000_000n || BigInt(status.wallet_tokens) < deposit)) {
+    log(`funding ${owner} from the testnet faucet...`);
+    await faucet(network, owner);
+  }
+  const send = (to, data) => sendTransaction(network.rpc_urls, ownerPrivate, { to, data });
+  await send(network.stablecoin, encodeCall("approve(address,uint256)", [["address", network.settlement], ["uint", deposit]]));
+  await send(network.settlement, encodeCall("deposit(uint256)", [["uint", deposit]]));
+  if (!status.grant?.active || BigInt(status.grant.max_per_request) !== limit) {
+    await send(network.settlement, encodeCall("registerKey(address,uint256,uint64)", [["address", key], ["uint", limit], ["uint", 0]]));
+  }
+  return { owner, key, deposit: deposit.toString(), max_per_request: limit.toString() };
+}
+
+/** Withdrawals take two steps: request (funds stop backing requests), then withdraw after the delay. */
+export async function requestWithdrawal(network, ownerPrivate, amount) {
+  await sendTransaction(network.rpc_urls, ownerPrivate, { to: network.settlement,
+    data: encodeCall("requestWithdrawal(uint256)", [["uint", amount]]) });
+}
+
+export async function completeWithdrawal(network, ownerPrivate) {
+  await sendTransaction(network.rpc_urls, ownerPrivate, { to: network.settlement, data: encodeCall("withdraw()", []) });
+}
+
+export async function settlementStatus(network, key) {
+  const fields = await words(network, network.settlement, "settlementInfo(bytes32)", [["bytes32", key]]);
+  return { status: STATUSES[Number(fields[14])] || "unknown", release_at: Number(fields[13]), fee: fields[10].toString() };
+}
+
+/** Commit the evidence on-chain (with the reporter bond), then hand it to every Relay's dispute desk. */
+export async function dispute(network, ownerPrivate, record, { reasonCode, statement }) {
+  const evidence = buildEvidence(record, { reasonCode, statement });
+  const digest = evidenceHash(evidence);
+  const [bond] = (await words(network, network.settlement, "params()")).slice(3, 4);
+  if (bond > 0n) {
+    await sendTransaction(network.rpc_urls, ownerPrivate, { to: network.stablecoin,
+      data: encodeCall("approve(address,uint256)", [["address", network.settlement], ["uint", bond]]) });
+  }
+  await sendTransaction(network.rpc_urls, ownerPrivate, { to: network.settlement, data: openDisputeCall(record.settlement_key, digest) });
+  let relays = network.relays;
+  try { relays = [...relays, ...await directoryRelays(network)]; } catch {}
+  const accepted = [];
+  for (const relay of relays) {
+    try {
+      const reply = await httpJson(`${relay.url}/v11/evidence`, { method: "POST", body: evidence, ca: network.tls_ca, timeoutMs: 30_000 });
+      if (reply.status === 200) accepted.push(relay.url);
+    } catch {}
+  }
+  return { settlement_key: record.settlement_key, evidence_hash: digest,
+    report_id: reportId(record.settlement_key, addressOf(ownerPrivate), digest), relays_accepted: accepted };
+}

package/src/cli.mjs

@@ -1,32 +1,40 @@
-// mycomesh-consumer (V11): init, setup, balance, request, serve.
+// mycomesh-consumer (V11): init, wallet, faucet, setup, balance, request, serve, dispute.
 import { randomBytes } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
-import { addressOf, encodeCall, settlementKey } from "./eip712.mjs";
-import { availableBalance, rpcCall, sendTransaction } from "./chain.mjs";
-import { Consumer, httpJson, loadNetwork, serveConsumer } from "./consumer.mjs";
-import { buildEvidence, evidenceHash, loadRequest, openDisputeCall, reportId } from "./disputes.mjs";
+import { addressOf, settlementKey } from "./eip712.mjs";
+import { availableBalance } from "./chain.mjs";
+import { completeWithdrawal, dispute, faucet, requestWithdrawal, setup, walletStatus } from "./account.mjs";
+import { Consumer, loadNetwork, serveConsumer } from "./consumer.mjs";
+import { createWallet, ownerAddress, ownerKey, walletAddress } from "./wallet.mjs";
+import { loadRequest } from "./disputes.mjs";
 
 const DEFAULT_NETWORK = join(dirname(fileURLToPath(import.meta.url)), "../networks/mycomesh-v11-sepolia.json");
 
 const USAGE = `Usage: mycomesh-consumer <command> [options]
 
-  init                     create the local payment key (never leaves this machine)
+  init                     create the local payment key and the password-protected owner wallet
   address                  print the payment key address
-  setup --owner-key-file F --deposit UNITS [--max-per-request UNITS] [--faucet UNITS]
+  wallet                   print the owner wallet address (a V3 keystore; MetaMask can import it)
+  faucet                   testnet: get gas ETH and tUSDC for the owner wallet
+  setup --deposit UNITS [--max-per-request UNITS]
                            deposit into the settlement contract and authorize the payment key
-                           (--faucet first mints testnet tUSDC to the owner)
+                           (on testnets, tops the wallet up from the faucet first)
   balance [--owner ADDR]   show the custodied deposit
-  request "prompt"         send one request and print the verified answer
-  serve [--port 8110]      run the local OpenAI-compatible endpoint (default)
-  dispute <settlement-key|last> --owner-key-file F [--reason CODE] [--statement TEXT]
+  withdraw [UNITS]         request a withdrawal of the deposit; run again after the delay to receive it
+  request "prompt" [--stream]
+                           send one request and print the verified answer
+  serve [--port 8110]      run the local web console and OpenAI-compatible endpoint (default)
+  dispute <settlement-key|last> [--reason CODE] [--statement TEXT]
                            reveal a recorded request and response to a Provider-AI jury
                            (within 24 hours; the reporter bond is returned if fraud is confirmed)
 
-Common: --network FILE (default: the bundled MycoMesh V11 Sepolia manifest), --data-dir DIR, --model ID, --max-fee UNITS, --provider SIGNER`;
+Common: --network FILE (default: the bundled MycoMesh V11 Sepolia manifest), --data-dir DIR, --model ID,
+  --max-fee UNITS, --provider SIGNER, --owner-key-file F (raw key or keystore instead of the local wallet).
+The wallet password comes from MYCOMESH_WALLET_PASSWORD or a terminal prompt.`;
 
 function dataDir(value) {
   const dir = value || process.env.MYCOMESH_CONSUMER_DATA_DIR || join(homedir(), ".mycomesh", "v11");
@@ -59,71 +67,83 @@ export async function main(argv = process.argv.slice(2), { stdout = process.stdo
       model: { type: "string", default: "gpt-5.5" }, "max-fee": { type: "string", default: "1000000" },
       port: { type: "string", default: "8110" }, host: { type: "string", default: "127.0.0.1" },
       "max-output-tokens": { type: "string", default: "4096" }, help: { type: "boolean" },
-      reason: { type: "string", default: "unrelated_response" }, faucet: { type: "string" }, provider: { type: "string" }, statement: { type: "string", default: "" },
+      reason: { type: "string", default: "unrelated_response" }, faucet: { type: "boolean" }, provider: { type: "string" },
+      statement: { type: "string", default: "" }, stream: { type: "boolean" },
     },
   });
   const [command = "serve", ...rest] = positionals;
   if (values.help || command === "help") { stdout.write(`${USAGE}\n`); return 0; }
   const dir = dataDir(values["data-dir"]);
-  if (command === "init" || command === "address") {
-    stdout.write(`${addressOf(paymentKey(dir, command === "init"))}\n`);
+  if (command === "address") {
+    stdout.write(`${addressOf(paymentKey(dir))}\n`);
+    return 0;
+  }
+  if (command === "init") {
+    stdout.write(`${addressOf(paymentKey(dir, true))}\n`);
+    if (!values["owner-key-file"]) {
+      stdout.write(`owner wallet ${walletAddress(await createWallet(dir))} (${join(dir, "owner-wallet.json")})\n`);
+    }
+    return 0;
+  }
+  if (command === "wallet") {
+    stdout.write(`${values["owner-key-file"] ? ownerAddress(values["owner-key-file"], dir) : walletAddress(await createWallet(dir))}\n`);
     return 0;
   }
   const network = loadNetwork(values.network || process.env.MYCOMESH_NETWORK || DEFAULT_NETWORK);
+  if (command === "faucet") {
+    const address = values.owner || ownerAddress(values["owner-key-file"], dir) || walletAddress(await createWallet(dir));
+    stdout.write(`${JSON.stringify(await faucet(network, address))}\n`);
+    return 0;
+  }
   if (command === "setup") {
     const keyPrivate = paymentKey(dir);
-    const owner = readKey(values["owner-key-file"]);
-    const deposit = BigInt(values.deposit);
-    const limit = BigInt(values["max-per-request"] || values["max-fee"]);
-    if (values.faucet) {
-      await sendTransaction(network.rpc_urls, owner, { to: network.stablecoin,
-        data: encodeCall("mint(address,uint256)", [["address", addressOf(owner)], ["uint", BigInt(values.faucet)]]) });
+    if (!values.deposit) throw new Error("--deposit UNITS is required");
+    if (!values["owner-key-file"]) await createWallet(dir);
+    const result = await setup(network, {
+      ownerPrivate: await ownerKey(values["owner-key-file"], dir), key: addressOf(keyPrivate), deposit: BigInt(values.deposit),
+      limit: BigInt(values["max-per-request"] || values["max-fee"]), forceFaucet: values.faucet,
+      log: (line) => stdout.write(`${line}\n`),
+    });
+    stdout.write(`deposited ${result.deposit} and authorized ${result.key} up to ${result.max_per_request} per request\n`);
+    return 0;
+  }
+  if (command === "withdraw") {
+    const owner = await ownerKey(values["owner-key-file"], dir);
+    const status = await walletStatus(network, addressOf(owner), null);
+    if (BigInt(status.withdrawal.amount) > 0n) {
+      if (status.withdrawal.available_at > Math.floor(Date.now() / 1000)) {
+        throw new Error(`the withdrawal of ${status.withdrawal.amount} unlocks at ${new Date(status.withdrawal.available_at * 1000).toISOString()}`);
+      }
+      await completeWithdrawal(network, owner);
+      stdout.write(`withdrew ${status.withdrawal.amount}\n`);
+      return 0;
     }
-    await sendTransaction(network.rpc_urls, owner, { to: network.stablecoin,
-      data: encodeCall("approve(address,uint256)", [["address", network.settlement], ["uint", deposit]]) });
-    await sendTransaction(network.rpc_urls, owner, { to: network.settlement, data: encodeCall("deposit(uint256)", [["uint", deposit]]) });
-    await sendTransaction(network.rpc_urls, owner, { to: network.settlement,
-      data: encodeCall("registerKey(address,uint256,uint64)", [["address", addressOf(keyPrivate)], ["uint", limit], ["uint", 0]]) });
-    stdout.write(`deposited ${deposit} and authorized ${addressOf(keyPrivate)} up to ${limit} per request\n`);
+    const amount = BigInt(rest[0] || status.deposit);
+    await requestWithdrawal(network, owner, amount);
+    stdout.write(`requested a withdrawal of ${amount}; run \`withdraw\` again after the delay\n`);
     return 0;
   }
   if (command === "balance") {
-    const owner = values.owner || (values["owner-key-file"] ? addressOf(readKey(values["owner-key-file"])) : null);
-    if (!owner) throw new Error("--owner or --owner-key-file is required");
+    const owner = values.owner || ownerAddress(values["owner-key-file"], dir);
+    if (!owner) throw new Error("--owner, --owner-key-file or a local wallet (`init`) is required");
     stdout.write(`${await availableBalance(network, owner)}\n`);
     return 0;
   }
   if (command === "dispute") {
-    const owner = readKey(values["owner-key-file"]);
-    const record = loadRequest(dir, rest[0] || "last");
-    const evidence = buildEvidence(record, { reasonCode: values.reason, statement: values.statement || rest.slice(1).join(" ") });
-    const digest = evidenceHash(evidence);
-    // The reporter bond comes from the owner's wallet and is returned when fraud is confirmed.
-    const params = await rpcCall(network.rpc_urls, "eth_call", [{ to: network.settlement, data: encodeCall("params()", []) }, "latest"]);
-    const bond = BigInt(`0x${params.slice(2 + 64 * 3, 2 + 64 * 4)}`);
-    if (bond > 0n) {
-      await sendTransaction(network.rpc_urls, owner, { to: network.stablecoin,
-        data: encodeCall("approve(address,uint256)", [["address", network.settlement], ["uint", bond]]) });
-    }
-    await sendTransaction(network.rpc_urls, owner, { to: network.settlement, data: openDisputeCall(record.settlement_key, digest) });
-    const accepted = [];
-    for (const relay of network.relays) {
-      try {
-        const reply = await httpJson(`${relay.url}/v11/evidence`, { method: "POST", body: evidence, ca: network.tls_ca, timeoutMs: 30_000 });
-        if (reply.status === 200) accepted.push(relay.url);
-      } catch {}
-    }
-    stdout.write(`${JSON.stringify({ settlement_key: record.settlement_key, evidence_hash: digest,
-      report_id: reportId(record.settlement_key, addressOf(owner), digest), relays_accepted: accepted })}\n`);
-    return accepted.length ? 0 : 2;
+    const owner = await ownerKey(values["owner-key-file"], dir);
+    const result = await dispute(network, owner, loadRequest(dir, rest[0] || "last"),
+      { reasonCode: values.reason, statement: values.statement || rest.slice(1).join(" ") });
+    stdout.write(`${JSON.stringify(result)}\n`);
+    return result.relays_accepted.length ? 0 : 2;
   }
   const keyPrivate = paymentKey(dir);
   const consumer = new Consumer({ network, keyPrivate, maxFee: Number(values["max-fee"]), journalDir: dir });
   if (command === "request") {
     const { response, receipt } = await consumer.request({
       endpoint: "responses", model: values.model, content: rest.join(" "), maxOutputTokens: Number(values["max-output-tokens"]),
-      provider: values.provider,
+      provider: values.provider, onDelta: values.stream ? (text) => process.stderr.write(text) : undefined,
     });
+    if (values.stream) process.stderr.write("\n");
     const output = response.output;
     stdout.write(`${JSON.stringify({ output_text: output.output_text ?? output, fee: receipt.receipt.actual_fee,
       provider: receipt.authorization.provider_signer, request_id: receipt.authorization.request_id,
@@ -131,9 +151,11 @@ export async function main(argv = process.argv.slice(2), { stdout = process.stdo
     return 0;
   }
   if (command === "serve") {
-    const server = await serveConsumer(consumer, { host: values.host, port: Number(values.port), apiKey: process.env.MYCOMESH_CONSUMER_API_KEY });
+    const server = await serveConsumer(consumer, { host: values.host, port: Number(values.port),
+      apiKey: process.env.MYCOMESH_CONSUMER_API_KEY, dataDir: dir });
     const { port } = server.address();
     stdout.write(`MycoMesh V11 Consumer on http://${values.host}:${port}/v1 (payment key ${consumer.key})\n`);
+    stdout.write(`Web console: http://127.0.0.1:${port}/\n`);
     return new Promise(() => {});
   }
   throw new Error(`unknown command ${command}\n${USAGE}`);

package/src/console.mjs

@@ -0,0 +1,86 @@
+// The local web console: the Bitcoin-node model, a UI served by this machine to this machine.
+// The browser only ever talks to 127.0.0.1; this process reaches the network and verifies everything.
+import { readFileSync } from "node:fs";
+import { addressOf } from "./eip712.mjs";
+import { completeWithdrawal, dispute, faucet, requestWithdrawal, settlementStatus, setup, walletStatus } from "./account.mjs";
+import { listRequests, loadRequest } from "./disputes.mjs";
+import { outputText } from "./protocol.mjs";
+import { createWallet, ownerAddress, unlockWallet, walletAddress } from "./wallet.mjs";
+
+const PAGE = new URL("./web/console.html", import.meta.url);
+
+/**
+ * Only this machine's own pages may call the local node: reject other Host
+ * names (DNS rebinding) and cross-site Origins (a web page spending the deposit).
+ */
+export function localRequestAllowed(req, port) {
+  const allowed = new Set([`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`]);
+  if (!allowed.has(String(req.headers.host || ""))) return false;
+  const origin = req.headers.origin;
+  return !origin || allowed.has(origin.replace(/^http:\/\//, ""));
+}
+
+export function consoleRoutes({ consumer, dataDir }) {
+  const network = consumer.network;
+  const owner = () => ownerAddress(undefined, dataDir);
+  const withWallet = (body) => unlockWallet(dataDir, body.password);
+  const units = (value, name) => {
+    if (!/^[0-9]+$/.test(String(value ?? ""))) throw Object.assign(new Error(`${name} must be a whole number of base units`), { status: 400 });
+    return BigInt(value);
+  };
+  return {
+    "GET /": () => ({ type: "text/html; charset=utf-8", body: readFileSync(PAGE, "utf8") }),
+    "GET /api/status": async () => {
+      const address = owner();
+      return {
+        network: { id: network.network_id, chain_id: network.chain_id, settlement: network.settlement, faucet: Boolean(network.faucet_url) },
+        payment_key: consumer.key, max_fee: String(consumer.maxFee),
+        wallet: address ? await walletStatus(network, address, consumer.key) : null,
+      };
+    },
+    "GET /api/network": async () => {
+      const relays = [];
+      for (const relay of await consumer.relays()) {
+        let health = null; let providers = [];
+        try { health = (await consumer.fetchJson(`${relay.url}/health`, { ca: network.tls_ca, timeoutMs: 5_000 })).body; } catch {}
+        try { providers = await consumer.providers(relay); } catch {}
+        relays.push({ url: relay.url, signer: relay.signer, healthy: Boolean(health?.ok), providers: providers.map((p) => ({
+          signer: p.provider_signer, models: p.models, prices: p.prices, capacity: p.capacity })) });
+      }
+      return { relays };
+    },
+    "GET /api/history": async () => {
+      const entries = listRequests(dataDir, outputText, 50);
+      await Promise.all(entries.map(async (entry) => {
+        try { Object.assign(entry, await settlementStatus(network, entry.settlement_key)); } catch { entry.status = "unknown"; }
+      }));
+      return { entries };
+    },
+    "POST /api/wallet": async (body) => ({ owner: walletAddress(await createWallet(dataDir, body.password)) }),
+    "POST /api/faucet": async () => {
+      const address = owner();
+      if (!address) throw Object.assign(new Error("create the wallet first"), { status: 400 });
+      return faucet(network, address);
+    },
+    "POST /api/setup": async (body) => setup(network, {
+      ownerPrivate: withWallet(body), key: consumer.key, deposit: units(body.deposit, "deposit"),
+      limit: units(body.max_per_request ?? consumer.maxFee, "max_per_request"),
+    }),
+    "POST /api/withdraw": async (body) => {
+      const ownerPrivate = withWallet(body);
+      const status = await walletStatus(network, addressOf(ownerPrivate), null);
+      if (BigInt(status.withdrawal.amount) > 0n) {
+        if (status.withdrawal.available_at > Math.floor(Date.now() / 1000)) {
+          throw Object.assign(new Error("the pending withdrawal is still locked"), { status: 409 });
+        }
+        await completeWithdrawal(network, ownerPrivate);
+        return { withdrawn: status.withdrawal.amount };
+      }
+      const amount = body.amount ? units(body.amount, "amount") : BigInt(status.deposit);
+      await requestWithdrawal(network, ownerPrivate, amount);
+      return { requested: amount.toString() };
+    },
+    "POST /api/dispute": async (body) => dispute(network, withWallet(body), loadRequest(dataDir, String(body.settlement_key)),
+      { reasonCode: String(body.reason_code || "unrelated_response"), statement: String(body.statement || "") }),
+  };
+}