@toon-protocol/client 0.10.0 → 0.12.0

package/dist/index.js

@@ -1,10 +1,3 @@
-import {
-  ANON_ASSETS,
-  ANON_VERSION,
-  selectAnonAsset,
-  startManagedAnonProxy
-} from "./chunk-WHAEQLIW.js";
-
 // src/ToonClient.ts
 import { generateSecretKey as generateSecretKey3, getPublicKey as getPublicKey2, finalizeEvent } from "nostr-tools/pure";
 
@@ -263,26 +256,49 @@ function getNetworkStatus(config) {
   if (!network || network === "custom") return void 0;
   return resolveClientNetwork(network).status;
 }
+function proxyIlpEndpoint(proxyUrl) {
+  if (!proxyUrl) return void 0;
+  const trimmed = proxyUrl.replace(/\/+$/, "");
+  return /\/ilp$/i.test(trimmed) ? trimmed : `${trimmed}/ilp`;
+}
 function validateConfig(config) {
   if (config.connector !== void 0) {
     throw new ValidationError(
       "Embedded mode not yet implemented in ToonClient. Use connectorUrl for HTTP mode."
     );
   }
-  if (!config.connectorUrl) {
+  if (!config.connectorUrl && !config.proxyUrl) {
     throw new ValidationError(
-      'connectorUrl is required for HTTP mode. Example: "http://localhost:8080"'
+      'connectorUrl (or proxyUrl) is required for HTTP mode. Example: "http://localhost:8080"'
     );
   }
-  try {
-    const url = new URL(config.connectorUrl);
-    if (!url.protocol.startsWith("http")) {
-      throw new Error("Must be HTTP or HTTPS");
+  if (config.connectorUrl) {
+    try {
+      const url = new URL(config.connectorUrl);
+      if (!url.protocol.startsWith("http")) {
+        throw new Error("Must be HTTP or HTTPS");
+      }
+    } catch (error) {
+      throw new ValidationError(
+        `Invalid connectorUrl: must be a valid HTTP/HTTPS URL (e.g., "http://localhost:8080"). Error: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  for (const [field, value] of [
+    ["proxyUrl", config.proxyUrl],
+    ["faucetUrl", config.faucetUrl]
+  ]) {
+    if (value === void 0) continue;
+    try {
+      const url = new URL(value);
+      if (!url.protocol.startsWith("http")) {
+        throw new Error("Must be HTTP or HTTPS");
+      }
+    } catch (error) {
+      throw new ValidationError(
+        `Invalid ${field}: must be a valid HTTP/HTTPS URL. Error: ${error instanceof Error ? error.message : String(error)}`
+      );
     }
-  } catch (error) {
-    throw new ValidationError(
-      `Invalid connectorUrl: must be a valid HTTP/HTTPS URL (e.g., "http://localhost:8080"). Error: ${error instanceof Error ? error.message : String(error)}`
-    );
   }
   if (config.secretKey !== void 0) {
     if (!config.secretKey || config.secretKey.length !== 32) {
@@ -346,25 +362,6 @@ function validateConfig(config) {
       );
     }
   }
-  if (config.transport) {
-    if (config.transport.type === "socks5") {
-      if (!config.transport.socksProxy?.startsWith("socks5h://")) {
-        throw new ValidationError(
-          'transport.socksProxy must use socks5h:// scheme to prevent DNS leaks. The "h" suffix ensures .anyone hostnames are resolved by the proxy, not locally.'
-        );
-      }
-    } else if (config.transport.type === "gateway") {
-      if (!config.transport.gatewayUrl) {
-        throw new ValidationError(
-          "transport.gatewayUrl is required for gateway transport"
-        );
-      }
-    } else if (config.transport.type !== "direct") {
-      throw new ValidationError(
-        `Unknown transport type: "${config.transport.type}"`
-      );
-    }
-  }
   if (config.chainRpcUrls && config.supportedChains) {
     for (const chain of Object.keys(config.chainRpcUrls)) {
       if (!config.supportedChains.includes(chain)) {
@@ -381,19 +378,21 @@ function applyDefaults(rawConfig) {
     config.mnemonic,
     config.mnemonicAccountIndex ?? 0
   ).secretKey : generateSecretKey2());
+  const connectorHttpEndpoint = config.connectorHttpEndpoint ?? proxyIlpEndpoint(config.proxyUrl);
+  const connectorUrl = config.connectorUrl ?? config.proxyUrl?.replace(/\/+$/, "");
   let btpUrl = config.btpUrl;
-  if (!btpUrl && config.connectorUrl) {
+  if (!btpUrl && connectorUrl && !connectorHttpEndpoint) {
     try {
-      const url = new URL(config.connectorUrl);
+      const url = new URL(connectorUrl);
       const wsProtocol = url.protocol === "https:" ? "wss:" : "ws:";
       btpUrl = `${wsProtocol}//${url.hostname}:3000`;
     } catch {
     }
   }
   let destinationAddress = config.destinationAddress;
-  if (!destinationAddress && config.connectorUrl) {
+  if (!destinationAddress && connectorUrl) {
     try {
-      const url = new URL(config.connectorUrl);
+      const url = new URL(connectorUrl);
       if (url.hostname === "localhost" || url.hostname === "127.0.0.1") {
         if (url.port === "8080") {
           destinationAddress = "g.toon.genesis";
@@ -416,8 +415,10 @@ function applyDefaults(rawConfig) {
     ...config,
     secretKey,
     evmPrivateKey,
-    connectorUrl: config.connectorUrl,
-    // Already validated as required
+    // Satisfied by connectorUrl OR proxyUrl (validateConfig enforced one of them).
+    connectorUrl,
+    // Surface the derived `POST /ilp` endpoint so HTTP mode selects HttpIlpClient.
+    ...connectorHttpEndpoint ? { connectorHttpEndpoint } : {},
     relayUrl: config.relayUrl ?? "ws://localhost:7100",
     queryTimeout: config.queryTimeout ?? 3e4,
     maxRetries: config.maxRetries ?? 3,
@@ -480,6 +481,15 @@ function isBase64(str) {
   return /^[A-Za-z0-9+/]*={0,2}$/.test(str);
 }
 
+// src/utils/store-envelope.ts
+var REQUEST_LINE = "POST /write HTTP/1.1";
+var HEADERS = ["Host: relay", "Content-Type: application/json"];
+function buildStoreWriteEnvelope(event) {
+  const body = JSON.stringify({ event });
+  const head = [REQUEST_LINE, ...HEADERS].join("\r\n");
+  return encodeUtf8(head + "\r\n\r\n" + body);
+}
+
 // src/modes/http.ts
 import { BootstrapService, createDiscoveryTracker } from "@toon-protocol/core";
 
@@ -2698,82 +2708,10 @@ var EvmSigner = class {
   }
 };
 
-// src/transport/index.ts
-function isAnyoneHost(url) {
-  if (!url) return false;
-  try {
-    const withScheme = /:\/\//.test(url) ? url : `ws://${url}`;
-    const host = new URL(withScheme).hostname.toLowerCase();
-    return host.endsWith(".anyone");
-  } catch {
-    return false;
-  }
-}
-async function resolveTransport(transport, originalBtpUrl, originalConnectorUrl, managedProxyOptions) {
-  const hasExplicitProxy = !!transport && (transport.type === "socks5" || transport.type === "gateway");
-  const envProxy = process.env["ANYONE_PROXY_URLS"];
-  if (!hasExplicitProxy && managedProxyOptions?.managedAnonProxy !== false && !envProxy && isAnyoneHost(originalBtpUrl)) {
-    const { startManagedAnonProxy: startManagedAnonProxy2 } = await import("./anon-proxy-W3KMM7GU.js");
-    const { createSocks5WebSocketFactory, createSocks5Fetch } = await import("./socks5-WTJBYGME.js");
-    const proxy = await startManagedAnonProxy2({
-      ...managedProxyOptions?.managedAnonSocksPort !== void 0 ? { socksPort: managedProxyOptions.managedAnonSocksPort } : {}
-    });
-    try {
-      return {
-        createWebSocket: createSocks5WebSocketFactory(proxy.socksProxy),
-        httpClient: createSocks5Fetch(proxy.socksProxy),
-        stopManagedProxy: proxy.stop
-      };
-    } catch (err) {
-      await proxy.stop();
-      throw err;
-    }
-  }
-  if (!transport || transport.type === "direct") {
-    return {};
-  }
-  if (transport.type === "socks5") {
-    const {
-      createSocks5WebSocketFactory,
-      createSocks5Fetch,
-      probeSocks5Proxy
-    } = await import("./socks5-WTJBYGME.js");
-    await probeSocks5Proxy(transport.socksProxy);
-    return {
-      createWebSocket: createSocks5WebSocketFactory(transport.socksProxy),
-      httpClient: createSocks5Fetch(transport.socksProxy)
-    };
-  }
-  if (transport.type === "gateway") {
-    const { rewriteUrlsForGateway } = await import("./gateway-QOK47RKS.js");
-    const rewritten = rewriteUrlsForGateway(
-      transport.gatewayUrl,
-      originalBtpUrl,
-      originalConnectorUrl
-    );
-    return {
-      btpUrl: rewritten.btpUrl,
-      connectorUrl: rewritten.connectorUrl
-    };
-  }
-  throw new Error(
-    `Unknown transport type: "${transport.type}"`
-  );
-}
-
 // src/modes/http.ts
 async function initializeHttpMode(config) {
-  const transport = await resolveTransport(
-    config.transport,
-    config.btpUrl,
-    config.connectorUrl,
-    {
-      ...config.managedAnonProxy !== void 0 ? { managedAnonProxy: config.managedAnonProxy } : {},
-      ...config.managedAnonSocksPort !== void 0 ? { managedAnonSocksPort: config.managedAnonSocksPort } : {}
-    }
-  );
-  const effectiveBtpUrl = transport.btpUrl ?? config.btpUrl;
-  const effectiveConnectorUrl = transport.connectorUrl ?? config.connectorUrl;
+  const effectiveBtpUrl = config.btpUrl;
+  const effectiveConnectorUrl = config.connectorUrl;
   const settlementInfo = buildSettlementInfo(config);
   const discoveredPeer = readDiscoveredIlpPeer({
     btpEndpoint: effectiveBtpUrl,
@@ -2786,8 +2724,7 @@ async function initializeHttpMode(config) {
     btpClient = new BtpRuntimeClient({
       btpUrl: effectiveBtpUrl,
       peerId: config.btpPeerId ?? `client`,
-      authToken: config.btpAuthToken ?? "",
-      createWebSocket: transport.createWebSocket
+      authToken: config.btpAuthToken ?? ""
     });
     await btpClient.connect();
   }
@@ -2799,17 +2736,14 @@ async function initializeHttpMode(config) {
       ...config.btpAuthToken !== void 0 ? { authToken: config.btpAuthToken } : {},
       timeout: config.queryTimeout,
       maxRetries: config.maxRetries,
-      retryDelay: config.retryDelay,
-      ...transport.httpClient !== void 0 ? { httpClient: transport.httpClient } : {},
-      ...transport.createWebSocket !== void 0 ? { createWebSocket: transport.createWebSocket } : {}
+      retryDelay: config.retryDelay
     });
   }
   const runtimeClient = httpIlpClient ?? btpClient ?? new HttpRuntimeClient({
     connectorUrl: effectiveConnectorUrl,
     timeout: config.queryTimeout,
     maxRetries: config.maxRetries,
-    retryDelay: config.retryDelay,
-    httpClient: transport.httpClient
+    retryDelay: config.retryDelay
   });
   let onChainChannelClient = null;
   if (config.chainRpcUrls) {
@@ -2854,10 +2788,7 @@ async function initializeHttpMode(config) {
     runtimeClient,
     adminClient: null,
     btpClient,
-    onChainChannelClient,
-    // Teardown handle for a managed `anon` proxy this init STARTED (undefined
-    // for explicit-proxy/direct/gateway). ToonClient.stop() invokes it.
-    stopManagedProxy: transport.stopManagedProxy
+    onChainChannelClient
   };
 }
 
@@ -3616,6 +3547,258 @@ async function requestBlobStorage(client, secretKey, params) {
   };
 }
 
+// src/adapters/Http402Client.ts
+var Http402Client = class {
+  fetchImpl;
+  resolveClaim;
+  createIlpClient;
+  needsDuplex;
+  constructor(config = {}) {
+    this.fetchImpl = config.fetch ?? fetch;
+    this.resolveClaim = config.resolveClaim;
+    this.createIlpClient = config.createIlpClient ?? ((httpEndpoint) => new HttpIlpClient({ httpEndpoint }));
+    this.needsDuplex = config.needsDuplex ?? false;
+  }
+  /**
+   * `fetch()`-like entry point. Issues the request; on `402` parses the x402
+   * challenge and — when a usable `toon-channel` offer is present and a claim
+   * resolver is configured — pays over TOON and returns the reconstructed
+   * `Response`. Otherwise returns the original 402 unchanged (AC5).
+   */
+  async fetch(url, opts = {}) {
+    const method = (opts.method ?? "GET").toUpperCase();
+    const probe = await this.fetchImpl(url, {
+      method,
+      ...opts.headers ? { headers: opts.headers } : {},
+      ...opts.body !== void 0 ? { body: opts.body } : {},
+      ...opts.timeout !== void 0 ? { signal: AbortSignal.timeout(opts.timeout) } : {}
+    });
+    if (probe.status !== 402) return probe;
+    const challenge = await parseX402Challenge(probe.clone());
+    const accept = challenge.toonChannel;
+    if (!accept || !this.resolveClaim) return probe;
+    return this.payOverToon(url, method, opts, accept, this.resolveClaim);
+  }
+  /**
+   * Open/reuse a channel (via the injected claim resolver), serialize the HTTP
+   * request into the ILP packet `data`, send it to `POST /ilp` with the claim,
+   * and reconstruct the origin `Response` from the FULFILL `data`.
+   */
+  async payOverToon(url, method, opts, accept, resolveClaim) {
+    const destination = opts.destination ?? accept.destination;
+    const claim = await resolveClaim(destination, accept.amount);
+    const requestBytes = serializeHttpRequest({
+      method,
+      url,
+      headers: opts.headers,
+      body: opts.body
+    });
+    const peer = {
+      httpEndpoint: accept.httpEndpoint,
+      supportsUpgrade: accept.supportsUpgrade
+    };
+    const choice = selectIlpTransport(peer, {
+      needsDuplex: this.needsDuplex
+    });
+    const ilpClient = this.createIlpClient(accept.httpEndpoint);
+    const result = await this.sendOverChoice(
+      ilpClient,
+      choice,
+      {
+        destination,
+        amount: String(accept.amount),
+        data: toBase64(requestBytes),
+        ...opts.timeout !== void 0 ? { timeout: opts.timeout } : {}
+      },
+      claim
+    );
+    if (!result.accepted) {
+      throw new ConnectorError(
+        `h402 payment rejected by connector: ${result.code ?? "F00"} ${result.message ?? ""}`.trim()
+      );
+    }
+    if (!result.data) {
+      throw new ConnectorError(
+        "h402 FULFILL carried no data (expected an HTTP response payload)"
+      );
+    }
+    return parseHttpResponse(fromBase64(result.data));
+  }
+  /**
+   * Send the serialized HTTP-in-ILP PREPARE over the selected transport.
+   *
+   * - `http` / `http-upgradable`: stateless one-shot `POST /ilp` with the claim.
+   * - `http-upgradable` additionally exercises {@link HttpIlpClient.upgradeToBtp}
+   *   for the duplex/streaming path (AC4). v1 still drives the actual write over
+   *   the one-shot HTTP method even after upgrading — full duplex body streaming
+   *   is a documented follow-up — but the upgrade call path is wired here.
+   * - `btp`: not reachable from h402 (the x402 offer only carries an
+   *   `httpEndpoint`); guarded for completeness.
+   */
+  async sendOverChoice(ilpClient, choice, params, claim) {
+    if (choice.kind === "http-upgradable") {
+      const btp = await ilpClient.upgradeToBtp();
+      try {
+        return await btp.sendIlpPacketWithClaim(
+          params,
+          claim
+        );
+      } finally {
+        await btp.disconnect().catch(() => {
+        });
+      }
+    }
+    if (choice.kind === "btp") {
+      throw new ToonClientError(
+        "h402 offer resolved to a BTP-only transport; the x402 toon-channel entry must advertise an httpEndpoint",
+        "INVALID_STATE"
+      );
+    }
+    return ilpClient.sendIlpPacketWithClaim(params, claim);
+  }
+};
+function readString(obj, keys) {
+  for (const k of keys) {
+    const v = obj[k];
+    if (typeof v === "string" && v.trim().length > 0) return v.trim();
+  }
+  return void 0;
+}
+function readAmount(obj, keys) {
+  for (const k of keys) {
+    const v = obj[k];
+    if (typeof v === "bigint") return v;
+    if (typeof v === "number" && Number.isFinite(v)) return BigInt(Math.trunc(v));
+    if (typeof v === "string" && /^\d+$/.test(v.trim())) return BigInt(v.trim());
+  }
+  return void 0;
+}
+async function parseX402Challenge(response) {
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    return {};
+  }
+  return parseX402Body(body);
+}
+function parseX402Body(body) {
+  if (typeof body !== "object" || body === null) return {};
+  const b = body;
+  const version = typeof b["x402Version"] === "number" ? b["x402Version"] : void 0;
+  const accepts = Array.isArray(b["accepts"]) ? b["accepts"] : [];
+  for (const raw of accepts) {
+    if (typeof raw !== "object" || raw === null) continue;
+    const entry = raw;
+    const scheme = readString(entry, ["scheme"]);
+    if (scheme !== "toon-channel") continue;
+    const destination = readString(entry, [
+      "destination",
+      "ilpAddress",
+      "payTo"
+    ]);
+    const httpEndpoint = readString(entry, [
+      "httpEndpoint",
+      "ilpEndpoint",
+      "endpoint"
+    ]);
+    const amount = readAmount(entry, ["amount", "price", "maxAmountRequired"]);
+    if (!destination || !httpEndpoint || amount === void 0) continue;
+    const network = readString(entry, ["network", "chain"]);
+    const supportsUpgrade = entry["supportsUpgrade"] === true || entry["upgradable"] === true;
+    return {
+      ...version !== void 0 ? { x402Version: version } : {},
+      toonChannel: {
+        scheme: "toon-channel",
+        ...network !== void 0 ? { network } : {},
+        destination,
+        amount,
+        httpEndpoint,
+        supportsUpgrade
+      }
+    };
+  }
+  return version !== void 0 ? { x402Version: version } : {};
+}
+var CRLF = "\r\n";
+function concatHeadAndBody(head, body) {
+  const headBytes = encodeUtf8(head);
+  const out = new Uint8Array(headBytes.length + body.length);
+  out.set(headBytes, 0);
+  out.set(body, headBytes.length);
+  return out;
+}
+function bodyToBytes(body) {
+  if (body === void 0) return new Uint8Array(0);
+  return typeof body === "string" ? encodeUtf8(body) : body;
+}
+function serializeHttpRequest(req) {
+  const u = new URL(req.url);
+  const target = `${u.pathname}${u.search}` || "/";
+  const bodyBytes = bodyToBytes(req.body);
+  const headers = /* @__PURE__ */ new Map();
+  const put = (name, value) => headers.set(name.toLowerCase(), `${name}: ${value}`);
+  const has = (name) => headers.has(name.toLowerCase());
+  for (const [name, value] of Object.entries(req.headers ?? {})) {
+    put(name, value);
+  }
+  if (!has("host")) put("Host", u.host);
+  if (bodyBytes.length > 0 && !has("content-length")) {
+    put("Content-Length", String(bodyBytes.length));
+  }
+  const lines = [
+    `${req.method.toUpperCase()} ${target} HTTP/1.1`,
+    ...headers.values()
+  ];
+  const head = lines.join(CRLF) + CRLF + CRLF;
+  return concatHeadAndBody(head, bodyBytes);
+}
+function findHeaderEnd(bytes) {
+  for (let i = 0; i + 3 < bytes.length; i++) {
+    if (bytes[i] === 13 && bytes[i + 1] === 10 && bytes[i + 2] === 13 && bytes[i + 3] === 10) {
+      return i + 4;
+    }
+  }
+  return -1;
+}
+function parseHttpResponse(bytes) {
+  const headerEnd = findHeaderEnd(bytes);
+  const headBytes = headerEnd === -1 ? bytes : bytes.subarray(0, headerEnd - 2);
+  const body = headerEnd === -1 ? new Uint8Array(0) : bytes.subarray(headerEnd);
+  const headText = decodeUtf8(headBytes);
+  const lines = headText.split(CRLF).filter((l) => l.length > 0);
+  const statusLine = lines.shift();
+  if (!statusLine) {
+    throw new ConnectorError(
+      "h402 response payload had no HTTP status line"
+    );
+  }
+  const match = /^HTTP\/\d\.\d\s+(\d{3})(?:\s+(.*))?$/.exec(statusLine.trim());
+  if (!match) {
+    throw new ConnectorError(
+      `h402 response payload had a malformed status line: "${statusLine}"`
+    );
+  }
+  const status = parseInt(match[1], 10);
+  const statusText = match[2] ?? "";
+  const headers = new Headers();
+  for (const line of lines) {
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    const name = line.slice(0, idx).trim();
+    const value = line.slice(idx + 1).trim();
+    if (name.length === 0) continue;
+    headers.append(name, value);
+  }
+  const nullBodyStatus = status === 101 || status === 204 || status === 205 || status === 304;
+  const init = { status, headers };
+  if (statusText) init.statusText = statusText;
+  return new Response(
+    nullBodyStatus || body.length === 0 ? null : body.slice(),
+    init
+  );
+}
+
 // src/ToonClient.ts
 var ToonClient = class {
   config;
@@ -3771,13 +3954,7 @@ var ToonClient = class {
         }
       }
       const initialization = await initializeHttpMode(this.config);
-      const {
-        bootstrapService,
-        discoveryTracker,
-        runtimeClient,
-        btpClient,
-        stopManagedProxy
-      } = initialization;
+      const { bootstrapService, discoveryTracker, runtimeClient, btpClient } = initialization;
       if (this.channelManager) {
         const cm = this.channelManager;
         const nostrPubkey = this.getPublicKey();
@@ -3865,8 +4042,7 @@ var ToonClient = class {
         discoveryTracker,
         runtimeClient,
         peersDiscovered: bootstrapResults.length,
-        btpClient: btpClient ?? void 0,
-        ...stopManagedProxy ? { stopManagedProxy } : {}
+        btpClient: btpClient ?? void 0
       };
       return {
         peersDiscovered: bootstrapResults.length,
@@ -3902,13 +4078,9 @@ var ToonClient = class {
       const toonData = this.config.toonEncoder(event);
       const basePricePerByte = 10n;
       const amount = options?.ilpAmount !== void 0 ? String(options.ilpAmount) : String(BigInt(toonData.length) * basePricePerByte);
+      const writeData = buildStoreWriteEnvelope(event);
       const destination = options?.destination ?? this.config.destinationAddress;
-      if (!this.state.btpClient) {
-        throw new ToonClientError(
-          "BTP client required for publishing. Configure btpUrl.",
-          "NO_BTP_CLIENT"
-        );
-      }
+      const transport = this.getClaimTransport();
       let claimMessage;
       if (options?.claim) {
         claimMessage = this.buildClaimMessageForProof(options.claim);
@@ -3937,13 +4109,11 @@ var ToonClient = class {
           "MISSING_CLAIM"
         );
       }
-      const response = await this.state.btpClient.sendIlpPacketWithClaim(
+      const response = await transport.sendIlpPacketWithClaim(
         {
           destination,
           amount,
-          data: toBase64(
-            toonData instanceof Uint8Array ? toonData : new Uint8Array(toonData)
-          )
+          data: toBase64(writeData)
         },
         claimMessage
       );
@@ -3971,6 +4141,46 @@ var ToonClient = class {
       );
     }
   }
+  /**
+   * Payment-aware HTTP fetch over TOON (issue #50). A `fetch()`-like method that
+   * makes paying for an HTTP resource transparent:
+   *
+   *   1. Issues the HTTP request to `url`.
+   *   2. On `402`, parses the x402 `accepts` array and selects the
+   *      `toon-channel` entry (see {@link Http402Client} for the wire shape).
+   *   3. Opens/reuses a payment channel for the entry's ILP destination (via
+   *      ChannelManager), signs a balance proof for the demanded price, and
+   *      re-sends the SAME HTTP request as a transparent HTTP-in-ILP packet to
+   *      the connector's `POST /ilp` (via {@link HttpIlpClient}), with the claim
+   *      in the `ILP-Payment-Channel-Claim` header.
+   *   4. Reconstructs and returns a standard Web `Response` from the FULFILL
+   *      `data`. The caller never sees ILP.
+   *
+   * If the origin offers no `toon-channel` entry, the original `402` Response is
+   * returned unchanged (the caller sees the vanilla x402 challenge).
+   *
+   * The channel/claim plumbing is wired to the live ChannelManager + per-chain
+   * signer via `resolveClaimForDestination` — identical to `publishEvent`. The
+   * `amount` paid comes from the selected x402 entry (the resource's price).
+   *
+   * @throws {ToonClientError} If the client is not started.
+   * @throws {ConnectorError} If the connector rejects the payment or returns no
+   *   HTTP payload.
+   */
+  async h402Fetch(url, opts) {
+    if (!this.state) {
+      throw new ToonClientError(
+        "Client not started. Call start() first.",
+        "INVALID_STATE"
+      );
+    }
+    const client = new Http402Client({
+      ...this.channelManager ? {
+        resolveClaim: (destination, amount) => this.resolveClaimForDestination(destination, amount)
+      } : {}
+    });
+    return client.fetch(url, opts);
+  }
   /**
    * Sends a raw swap ILP packet (Story 12.5) to a Mill peer with an attached
    * balance-proof claim. This is a lower-level surface than `publishEvent`:
@@ -3983,7 +4193,7 @@ var ToonClient = class {
    *       matching `destination`,
    *   (c) neither -> throw MISSING_CLAIM.
    *
-   * @throws {ToonClientError} INVALID_STATE / NO_BTP_CLIENT / MISSING_CLAIM
+   * @throws {ToonClientError} INVALID_STATE / NO_ILP_TRANSPORT / MISSING_CLAIM
    */
   async sendSwapPacket(params) {
     if (!this.state) {
@@ -3992,18 +4202,13 @@ var ToonClient = class {
         "INVALID_STATE"
       );
     }
-    if (!this.state.btpClient) {
-      throw new ToonClientError(
-        "BTP client required for sending swap packets. Configure btpUrl.",
-        "NO_BTP_CLIENT"
-      );
-    }
+    const transport = this.getClaimTransport();
     const claimMessage = await this.resolveClaimForDestination(
       params.destination,
       params.amount,
       params.claim
     );
-    return this.state.btpClient.sendIlpPacketWithClaim(
+    return transport.sendIlpPacketWithClaim(
       {
         destination: params.destination,
         amount: String(params.amount),
@@ -4043,6 +4248,51 @@ var ToonClient = class {
     }
     return EvmSigner.buildClaimMessage(claim, this.getPublicKey());
   }
+  /**
+   * Resolve the ILP transport for a paid (claim-bearing) write.
+   *
+   * The connector is a payment-proxy: paid writes carry an ILP PREPARE plus the
+   * signed payment-channel claim. Either transport speaks the SAME claim
+   * contract — the BTP `payment-channel-claim` protocolData entry and the
+   * ILP-over-HTTP `ILP-Payment-Channel-Claim` header serialize the same claim
+   * JSON — so we route through whichever transport is ACTIVE rather than
+   * hard-requiring BTP.
+   *
+   * Selection (mirrors `modes/http.ts` runtime-client precedence):
+   *   1. `runtimeClient` when it implements `sendIlpPacketWithClaim` — this is
+   *      the HttpIlpClient (proxy `POST /ilp`) when a `proxyUrl`/
+   *      `connectorHttpEndpoint` is configured, else the BtpRuntimeClient.
+   *   2. `btpClient` as an explicit fallback (always present when `btpUrl` is set).
+   *
+   * The level-3 `HttpRuntimeClient` (connector-admin HTTP, no `btpUrl` AND no
+   * proxy) does NOT implement `sendIlpPacketWithClaim`; in that case there is no
+   * paid-write transport and we throw a clear, actionable error.
+   *
+   * @throws {ToonClientError} NO_ILP_TRANSPORT when no active transport can send
+   *   a packet+claim.
+   */
+  getClaimTransport() {
+    const state = this.state;
+    if (!state) {
+      throw new ToonClientError(
+        "Client not started. Call start() first.",
+        "INVALID_STATE"
+      );
+    }
+    const candidates = [
+      state.runtimeClient,
+      state.btpClient
+    ];
+    for (const candidate of candidates) {
+      if (candidate && typeof candidate.sendIlpPacketWithClaim === "function") {
+        return candidate;
+      }
+    }
+    throw new ToonClientError(
+      "No ILP transport for paid writes. Configure `proxyUrl`/`connectorHttpEndpoint` (route through the connector proxy over ILP-over-HTTP) or `btpUrl` (BTP socket).",
+      "NO_ILP_TRANSPORT"
+    );
+  }
   /**
    * Shared claim-resolution logic used by `publishEvent` and `sendSwapPacket`.
    * TODO(12.5 followup): also factor `publishEvent`'s inline claim resolution
@@ -4231,14 +4481,9 @@ var ToonClient = class {
         "MISSING_CLAIM"
       );
     }
-    if (!this.state.btpClient) {
-      throw new ToonClientError(
-        "BTP client required for sending payments. Configure btpUrl.",
-        "NO_BTP_CLIENT"
-      );
-    }
+    const transport = this.getClaimTransport();
     const claimMessage = this.buildClaimMessageForProof(params.claim);
-    return this.state.btpClient.sendIlpPacketWithClaim(
+    return transport.sendIlpPacketWithClaim(
       ilpParams,
       claimMessage
     );
@@ -4256,14 +4501,10 @@ var ToonClient = class {
     if (!this.state) {
       throw new ToonClientError("Client not started", "INVALID_STATE");
     }
-    const stopManagedProxy = this.state.stopManagedProxy;
     try {
       if (this.state.btpClient) {
         await this.state.btpClient.disconnect();
       }
-      if (stopManagedProxy) {
-        await stopManagedProxy();
-      }
       this.state = null;
     } catch (error) {
       throw new ToonClientError(
@@ -4311,26 +4552,6 @@ var ToonClient = class {
   }
 };
 
-// src/transport/hs-hostname.ts
-var HS_HOSTNAME_REGEX = /^[a-z2-7]+\.anyone$/;
-var HS_HOSTNAME_MAX_LENGTH = 80;
-function isRoutableHsHostname(s) {
-  return typeof s === "string" && s.length <= HS_HOSTNAME_MAX_LENGTH && HS_HOSTNAME_REGEX.test(s);
-}
-function assertRoutableHsHostname(hostname) {
-  if (typeof hostname === "string" && /\.anon$/.test(hostname)) {
-    throw new Error(
-      `"${hostname}" is not a routable hidden-service address; use the .anyone TLD (e.g. "${hostname.replace(/\.anon$/, ".anyone")}"). The anon daemon only resolves hidden services under .anyone \u2014 a .anon name is treated as a clearnet address and fails (HostUnreachable).`
-    );
-  }
-  if (!isRoutableHsHostname(hostname)) {
-    throw new Error(
-      `Invalid hidden-service hostname: ${JSON.stringify(hostname)}. Expected a base32 .anyone address matching ${HS_HOSTNAME_REGEX}.`
-    );
-  }
-  return hostname;
-}
-
 // src/adapters/HttpConnectorAdmin.ts
 var HttpConnectorAdmin = class {
   adminUrl;
@@ -5069,6 +5290,75 @@ function buildPetPurchaseRequest(params) {
   };
 }
 
+// src/faucet.ts
+function faucetPath(chain) {
+  switch (chain) {
+    case "evm":
+      return "/api/request";
+    case "solana":
+      return "/api/solana/request";
+    case "mina":
+      return "/api/mina/request";
+  }
+}
+async function fundWallet(faucetUrl, address, chain, options = {}) {
+  if (!faucetUrl) {
+    throw new Error("fundWallet: faucetUrl is required");
+  }
+  if (!address) {
+    throw new Error("fundWallet: address is required");
+  }
+  if (chain === "solana" || chain === "mina") {
+    throw new Error(
+      `fundWallet: ${chain} faucet funding is deferred (WS3) \u2014 not yet implemented`
+    );
+  }
+  const base = faucetUrl.replace(/\/+$/, "");
+  const url = `${base}${faucetPath(chain)}`;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const timeout = options.timeout ?? 3e4;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ address }),
+      signal: controller.signal
+    });
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new NetworkError(
+        `Faucet request timed out after ${timeout}ms (${url})`,
+        error
+      );
+    }
+    throw new NetworkError(
+      `Faucet request failed (${url}): ${error instanceof Error ? error.message : String(error)}`,
+      error instanceof Error ? error : void 0
+    );
+  } finally {
+    clearTimeout(timeoutId);
+  }
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    throw new NetworkError(
+      `Faucet responded ${response.status} ${response.statusText}${detail ? `: ${detail}` : ""} (${url})`
+    );
+  }
+  const body = await response.text().catch(() => "");
+  let parsed = body;
+  if (body) {
+    try {
+      parsed = JSON.parse(body);
+    } catch {
+      parsed = body;
+    }
+  }
+  return { chain, address, response: parsed };
+}
+
 // src/keys/KeyManager.ts
 import { finalizeEvent as finalizeEvent2 } from "nostr-tools/pure";
 import { nip19 } from "nostr-tools";
@@ -6109,14 +6399,11 @@ function writeKeystoreFile(path, keystore) {
   });
 }
 export {
-  ANON_ASSETS,
-  ANON_VERSION,
   BtpRuntimeClient,
   ChannelManager,
   ConnectorError,
   EvmSigner,
-  HS_HOSTNAME_MAX_LENGTH,
-  HS_HOSTNAME_REGEX,
+  Http402Client,
   HttpConnectorAdmin,
   HttpIlpClient,
   HttpRuntimeClient,
@@ -6133,13 +6420,13 @@ export {
   ValidationError,
   applyDefaults,
   applyNetworkPresets,
-  assertRoutableHsHostname,
   buildBackupEvent,
   buildBackupFilter,
   buildPetInteractionRequest,
   buildPetListingEvent,
   buildPetPurchaseRequest,
   buildSettlementInfo,
+  buildStoreWriteEnvelope,
   decryptMnemonic2 as decryptMnemonic,
   deriveFromNsec,
   deriveFullIdentity,
@@ -6147,6 +6434,7 @@ export {
   encryptMnemonic2 as encryptMnemonic,
   filterPetDvmProviders,
   filterPetListings,
+  fundWallet,
   generateKeystore,
   generateMnemonic,
   generateRandomIdentity,
@@ -6154,18 +6442,20 @@ export {
   httpEndpointToBtpUrl,
   importKeystore,
   isPrfSupported,
-  isRoutableHsHostname,
   loadKeystore,
   parseBackupPayload,
+  parseHttpResponse,
   parsePetInteractionEvent,
   parsePetInteractionResult,
   parsePetListing,
+  parseX402Body,
+  parseX402Challenge,
+  proxyIlpEndpoint,
   readDiscoveredIlpPeer,
   readMinaDepositTotal,
   requestBlobStorage,
-  selectAnonAsset,
   selectIlpTransport,
-  startManagedAnonProxy,
+  serializeHttpRequest,
   validateConfig,
   validateMnemonic,
   withRetry,