@toon-protocol/client 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _toon_protocol_core from '@toon-protocol/core';
-import { IlpPeerInfo, NetworkFamilyStatus, IlpSendResult, IlpClient, ConnectorAdminClient, ConnectorChannelClient, OpenChannelParams, OpenChannelResult, ChannelState } from '@toon-protocol/core';
+import { IlpPeerInfo, IlpClient, IlpSendResult, NetworkFamilyStatus, ConnectorAdminClient, ConnectorChannelClient, OpenChannelParams, OpenChannelResult, ChannelState } from '@toon-protocol/core';
 import { NostrEvent, EventTemplate } from 'nostr-tools/pure';
 import { PrivateKeyAccount } from 'viem/accounts';
 
@@ -213,6 +213,30 @@ interface ToonClientConfig {
      * core release with these fields ship).
      */
     connectorHttpEndpoint?: string;
+    /**
+     * Connector-PROXY base URL for the deployed devnet/testnet edge (e.g.
+     * `https://proxy.devnet.toonprotocol.dev`). The connector is now a
+     * payment-proxy that serves ILP-over-HTTP at `POST /ilp`; setting `proxyUrl`
+     * is the high-level way to route paid writes through that proxy WITHOUT a
+     * persistent BTP socket.
+     *
+     * When set, `applyDefaults` derives `connectorHttpEndpoint` from it (appending
+     * `/ilp` to the base unless the URL already ends in `/ilp`), so the existing
+     * {@link HttpIlpClient} transport selection (`selectIlpTransport`) picks the
+     * stateless one-shot HTTP transport for `publishEvent`/`sendSwapPacket`/
+     * `sendPayment`. An explicit `connectorHttpEndpoint` always wins over this.
+     *
+     * The eventual home for these endpoints is a `@toon-protocol/core` devnet
+     * preset; until that ships, set this field explicitly.
+     */
+    proxyUrl?: string;
+    /**
+     * Faucet base URL for the deployed devnet (e.g.
+     * `https://faucet.devnet.toonprotocol.dev`). Consumed by the {@link fundWallet}
+     * helper to drip test funds to the client's chain address before publishing.
+     * Has no effect on the runtime transport; it is config carried for tooling/e2e.
+     */
+    faucetUrl?: string;
     /**
      * Whether the uplink connector accepts a BTP `Upgrade` over its HTTP endpoint
      * (mirrors `IlpPeerInfo.supportsUpgrade`, toon PR #29). Only consulted when
@@ -267,34 +291,6 @@ interface ToonClientConfig {
     minaChannel?: MinaChannelClientOptions;
     /** File path for persisting payment channel nonce/amount state across restarts */
     channelStorePath?: string;
-    /**
-     * Transport configuration for privacy-preserving connections.
-     *
-     * - `direct` (default): No privacy overlay, connect directly.
-     * - `socks5`: Route connections through a SOCKS5 proxy (Node.js only).
-     *   Requires `socks5h://` scheme for DNS leak prevention.
-     * - `gateway`: Route connections through an ator gateway URL (browser-compatible).
-     *   The gateway proxies through ator server-side.
-     */
-    transport?: ClientTransportConfig;
-    /**
-     * Self-managed `anon` (anyone-protocol / ATOR) SOCKS5h proxy (Node.js only).
-     *
-     * When the `btpUrl` host ends in `.anyone` and NO explicit proxy is configured
-     * (`transport.socksProxy` / `transport.type === 'gateway'`) and the
-     * `ANYONE_PROXY_URLS` env var is unset, the SDK auto-downloads + spawns its own
-     * `anon` daemon, waits for it to bootstrap + bind a loopback SOCKS5 port, and
-     * routes BTP/HTTP through it — ZERO manual proxy setup. `client.stop()` tears
-     * the daemon down.
-     *
-     * - `undefined` (default): auto — managed proxy starts for `.anyone` hosts.
-     * - `false`: opt out — never auto-start (you must supply your own proxy).
-     *
-     * Ignored in browser bundles (the node-only daemon module is never loaded).
-     */
-    managedAnonProxy?: boolean;
-    /** Loopback SOCKS port the managed `anon` daemon binds. Default 9050. */
-    managedAnonSocksPort?: number;
     /** Nostr relay URL for peer discovery. Default: 'ws://localhost:7100' */
     relayUrl?: string;
     /**
@@ -394,23 +390,6 @@ interface SignedBalanceProof extends BalanceProofParams {
         tokenId: string;
     };
 }
-/**
- * Transport configuration for privacy-preserving connections.
- *
- * Node.js: Use `socks5` to route WebSocket and HTTP through a SOCKS5 proxy.
- * Browser: Use `gateway` to route through a server-side ator gateway.
- */
-type ClientTransportConfig = {
-    type: 'direct';
-} | {
-    type: 'socks5';
-    /** SOCKS5 proxy URL. MUST use `socks5h://` scheme (DNS leak prevention). */
-    socksProxy: string;
-} | {
-    type: 'gateway';
-    /** Gateway base URL that proxies connections through ator server-side. */
-    gatewayUrl: string;
-};
 
 /**
  * Client-side helper for kind:5094 Arweave blob storage DVM requests.
@@ -509,6 +488,417 @@ interface RequestBlobStorageResult {
  */
 declare function requestBlobStorage(client: ToonClient, secretKey: Uint8Array, params: RequestBlobStorageParams): Promise<RequestBlobStorageResult>;
 
+interface BtpRuntimeClientConfig {
+    btpUrl: string;
+    peerId: string;
+    authToken: string;
+    /** Max reconnection attempts on send failure (default: 3) */
+    maxRetries?: number;
+    /** Delay between reconnection attempts in ms (default: 1000) */
+    retryDelay?: number;
+    /** Custom WebSocket constructor (for testing / custom transports). */
+    createWebSocket?: (url: string) => WebSocket;
+}
+/**
+ * BTP transport implementing IlpClient.
+ * Uses IsomorphicBtpClient (browser-native, no Node.js dependencies).
+ */
+declare class BtpRuntimeClient implements IlpClient {
+    private btpClient;
+    private readonly config;
+    private _isConnected;
+    constructor(config: BtpRuntimeClientConfig);
+    /**
+     * Connects to the BTP peer via WebSocket.
+     */
+    connect(): Promise<void>;
+    /**
+     * Attempts to reconnect by creating a fresh client and connecting.
+     */
+    reconnect(): Promise<void>;
+    /**
+     * Disconnects from the BTP peer.
+     */
+    disconnect(): Promise<void>;
+    get isConnected(): boolean;
+    /**
+     * Sends an ILP packet via BTP with auto-reconnect on connection errors.
+     * Satisfies IlpClient interface.
+     */
+    sendIlpPacket(params: {
+        destination: string;
+        amount: string;
+        data: string;
+        timeout?: number;
+    }): Promise<IlpSendResult>;
+    /**
+     * Sends a balance proof claim via BTP protocol data, then sends an ILP packet.
+     * Auto-reconnects on connection errors.
+     */
+    sendIlpPacketWithClaim(params: {
+        destination: string;
+        amount: string;
+        data: string;
+        timeout?: number;
+    }, claim: Record<string, unknown>): Promise<IlpSendResult>;
+    /**
+     * Send a standalone `payment-channel-claim` BTP MESSAGE (no ILP packet
+     * attached). The connector's ClaimReceiver consumes this fire-and-forget
+     * to register cumulative claim state independently of the per-packet
+     * forwarding path. Auto-reconnects on connection errors.
+     */
+    sendClaimMessage(claim: Record<string, unknown>): Promise<void>;
+    private _sendClaimMessageOnce;
+    /**
+     * Single-attempt ILP packet send. Reconnects if not connected.
+     */
+    private _sendIlpPacketOnce;
+    /**
+     * Single-attempt claim + ILP packet send. Reconnects if not connected.
+     */
+    private _sendIlpPacketWithClaimOnce;
+}
+
+/**
+ * ILP-over-HTTP (RFC-0035) transport for the TOON client.
+ *
+ * The connector now serves ILP-over-HTTP on the SAME port as BTP (connector
+ * PR #181). This adapter lets a client do stateless one-shot writes over HTTP
+ * (`POST /ilp`) and upgrade to a duplex BTP session when it needs to receive
+ * server-initiated packets or act as a peer.
+ *
+ * Wire contract (targets connector PR #181's `/ilp`):
+ *  - One-shot write: `POST /ilp`
+ *      body:    OER-encoded ILP PREPARE (`application/octet-stream`)
+ *      header:  `ILP-Payment-Channel-Claim: base64(JSON of the claim)` — the
+ *               SAME claim JSON the BTP path attaches as the
+ *               `payment-channel-claim` protocolData entry.
+ *      optional: `ILP-Peer-Id` + `Authorization: Bearer <secret>` identity.
+ *      response: `200 OK` with an OER FULFILL or REJECT body. HTTP non-2xx is
+ *                reserved for TRANSPORT errors (400/401/413/5xx); ILP-level
+ *                rejects come back as a 200 + REJECT body.
+ *  - Upgrade to BTP: standard HTTP `Upgrade` with `Sec-WebSocket-Protocol: btp`
+ *      plus the same `ILP-Peer-Id` + `Authorization` headers. The connector
+ *      pre-authenticates the BTP session from those headers (continuity), so
+ *      after `101` we send BTP frames WITHOUT a separate in-band auth frame.
+ *      Omitting the auth headers falls back to the normal BTP auth-frame flow.
+ *
+ * Reuses `serializeIlpPrepare`/`deserializeIlpPacket` from `btp/protocol.ts` —
+ * the SAME OER codec the BTP path uses. Claim signing/construction is owned by
+ * the caller (BootstrapService); this transport never builds or signs claims.
+ */
+
+/** Header carrying the base64(JSON) payment-channel claim. */
+declare const ILP_CLAIM_HEADER = "ILP-Payment-Channel-Claim";
+/** Header carrying a NIP-59 wrapped (gift-wrapped) claim. */
+declare const ILP_CLAIM_WRAPPED_HEADER = "ILP-Payment-Channel-Claim-Wrapped";
+/** Header carrying the peer identity. */
+declare const ILP_PEER_ID_HEADER = "ILP-Peer-Id";
+interface HttpIlpClientConfig {
+    /** The peer's `POST /ilp` URL (the `httpEndpoint` from discovery). */
+    httpEndpoint: string;
+    /**
+     * Optional peer identity. With no `peerId`/`authToken` the connector treats
+     * the request as an anonymous no-auth peer (permissionless default) and
+     * derives an ephemeral id from the claim signer.
+     */
+    peerId?: string;
+    /** Bearer secret for `Authorization`. Omit for the no-auth peer path. */
+    authToken?: string;
+    /** Request timeout in milliseconds (default: 30000). */
+    timeout?: number;
+    /** Max retry attempts for transport-level network failures (default: 3). */
+    maxRetries?: number;
+    /** Initial retry delay in milliseconds (default: 1000). */
+    retryDelay?: number;
+    /** Custom fetch implementation (for testing / custom transports). */
+    httpClient?: typeof fetch;
+    /**
+     * Custom WebSocket constructor for the BTP upgrade path (for testing /
+     * custom transports). Forwarded to the underlying BtpRuntimeClient.
+     */
+    createWebSocket?: (url: string) => WebSocket;
+}
+/**
+ * Stateless ILP-over-HTTP transport implementing `IlpClient`.
+ *
+ * Use this for pure one-shot consumers (publish-and-forget writes). When the
+ * client needs a duplex session — to receive server-initiated packets or to act
+ * as a peer — call {@link upgradeToBtp} to obtain a connected BtpRuntimeClient
+ * that reuses the existing BTP code path.
+ */
+declare class HttpIlpClient implements IlpClient {
+    private readonly httpEndpoint;
+    private readonly peerId;
+    private readonly authToken;
+    private readonly timeout;
+    private readonly retryConfig;
+    private readonly httpClient;
+    private readonly createWebSocket;
+    constructor(config: HttpIlpClientConfig);
+    /**
+     * Send an ILP PREPARE via `POST /ilp` WITHOUT a claim. The connector accepts
+     * this only on free/zero-amount routes; paid writes must use
+     * {@link sendIlpPacketWithClaim}. Satisfies the IlpClient interface.
+     */
+    sendIlpPacket(params: {
+        destination: string;
+        amount: string;
+        data: string;
+        timeout?: number;
+    }): Promise<IlpSendResult>;
+    /**
+     * Send an ILP PREPARE via `POST /ilp` with the payment-channel claim attached
+     * as the `ILP-Payment-Channel-Claim` header. `claim` is the SAME JSON object
+     * the BTP path attaches as the `payment-channel-claim` protocolData entry —
+     * we base64(JSON.stringify(claim)) it, byte-for-byte identical to BTP.
+     */
+    sendIlpPacketWithClaim(params: {
+        destination: string;
+        amount: string;
+        data: string;
+        timeout?: number;
+    }, claim: unknown): Promise<IlpSendResult>;
+    /**
+     * Upgrade to a duplex BTP session over the SAME endpoint.
+     *
+     * Derives the `ws(s)://` URL from `httpEndpoint`, opens a WebSocket with
+     * `Sec-WebSocket-Protocol: btp` and the same `ILP-Peer-Id` + `Authorization`
+     * headers, and returns a connected {@link BtpRuntimeClient}. When auth headers
+     * are present the connector pre-authenticates the session (no in-band auth
+     * frame); without them the BtpRuntimeClient falls back to the normal BTP
+     * auth-frame flow.
+     *
+     * NOTE: passing per-connection headers + a subprotocol to a WebSocket is
+     * Node-only (the `ws` package). Browsers cannot set arbitrary request headers
+     * on a WebSocket handshake, so a browser consumer must use the gateway
+     * transport or BTP-with-auth-frame instead.
+     */
+    upgradeToBtp(): Promise<BtpRuntimeClient>;
+    private authHeaders;
+    /**
+     * Single attempt: serialize the PREPARE, POST it, and map the response.
+     * @throws {NetworkError} On connection/timeout failures (retried).
+     * @throws {ConnectorError} On non-retryable transport errors (5xx / unexpected).
+     */
+    private postPrepare;
+    /**
+     * Map a `200 OK` body (OER FULFILL/REJECT) to an IlpSendResult; map a non-2xx
+     * to a transport error. Per the wire contract, ILP-level rejects arrive as a
+     * 200 + REJECT body — only HTTP non-2xx means a transport-layer failure.
+     */
+    private mapResponse;
+    private mapTransportError;
+}
+/**
+ * Derive the BTP WebSocket URL from a `POST /ilp` HTTP endpoint. The connector
+ * serves BTP on the SAME path, so we only swap the scheme (http→ws, https→wss).
+ */
+declare function httpEndpointToBtpUrl(httpEndpoint: string): string;
+
+/**
+ * Payment-aware HTTP fetch over TOON (the "h402" flow).
+ *
+ * This adapter makes paying for an HTTP resource transparent: it issues an
+ * ordinary HTTP request, and when the origin answers `402 Payment Required`
+ * with an x402-style challenge that offers a `toon-channel` payment option, it
+ * opens/reuses a payment channel, signs a balance-proof claim, and re-sends the
+ * SAME HTTP request as a "transparent HTTP-in-ILP" packet to the connector's
+ * `POST /ilp` endpoint (via {@link HttpIlpClient}). The connector terminates the
+ * payment, forwards the request to the origin, and returns the origin's HTTP
+ * response inside the ILP FULFILL `data`. We reconstruct a normal Web `Response`
+ * from those bytes — the caller never sees ILP.
+ *
+ * ─── x402 wire contract (the 402 challenge body) ────────────────────────────
+ * The connector side (the 402 greeting + the `accepts` entries) is a separate,
+ * NOT-YET-BUILT dependency, so we parse DEFENSIVELY (mirroring
+ * `readDiscoveredIlpPeer` in selectIlpTransport.ts): a slightly different
+ * connector shape should degrade gracefully (fall back to the vanilla 402)
+ * rather than throw.
+ *
+ * Expected 402 JSON body (x402 v1-ish):
+ * ```jsonc
+ * {
+ *   "x402Version": 1,
+ *   "accepts": [
+ *     {
+ *       "scheme": "toon-channel",      // REQUIRED — selects the TOON option.
+ *       "network": "evm:base:8453",    // optional — chain key (informational).
+ *       "destination": "g.toon.apex",  // ILP destination address to pay (the
+ *                                      //   connector route that fronts the URL).
+ *       "amount": "1000",              // price in ILP base units (string|number).
+ *       "httpEndpoint": "https://apex/ilp", // the connector's POST /ilp URL.
+ *       "supportsUpgrade": true        // optional — host accepts the BTP upgrade.
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * Field aliases read defensively (first present wins):
+ *   - destination: `destination` | `ilpAddress` | `payTo` | `maxAmountRequired`'s
+ *     sibling `payTo`. (We do NOT invent a value — a missing destination makes
+ *     the entry unusable and we fall back to the vanilla 402.)
+ *   - amount:      `amount` | `price` | `maxAmountRequired`.
+ *   - httpEndpoint:`httpEndpoint` | `ilpEndpoint` | `endpoint`.
+ *   - upgrade:     `supportsUpgrade` | `upgradable`.
+ *
+ * ─── HTTP-in-ILP framing ────────────────────────────────────────────────────
+ * The raw HTTP request/response is serialized as minimal HTTP/1.1 wire bytes
+ * (request-line / status-line + headers + CRLFCRLF + body) and carried as the
+ * ILP packet `data` (base64). See {@link serializeHttpRequest} /
+ * {@link parseHttpResponse}. This keeps the connector free to forward the bytes
+ * verbatim and lets us rebuild a standard `Response`.
+ *
+ * Claim signing/construction is owned by the CALLER (ToonClient wires the live
+ * ChannelManager + signer). This adapter never builds or validates claims —
+ * payment-claim validation lives ONLY in the connector.
+ */
+
+/** A single parsed `accepts` entry that offers the `toon-channel` scheme. */
+interface ToonChannelAccept {
+    /** Always `'toon-channel'` for a matched entry. */
+    scheme: 'toon-channel';
+    /** Optional chain key, e.g. `evm:base:8453` — informational. */
+    network?: string;
+    /** ILP destination address to pay (the connector route fronting the URL). */
+    destination: string;
+    /** Price in ILP base units. */
+    amount: bigint;
+    /** The connector's `POST /ilp` URL. */
+    httpEndpoint: string;
+    /** Whether the host accepts the BTP upgrade over the HTTP endpoint. */
+    supportsUpgrade: boolean;
+}
+/** The parsed x402 402 body, with the selected `toon-channel` entry (if any). */
+interface ParsedX402Challenge {
+    x402Version?: number;
+    /** The first usable `toon-channel` accepts entry, or `undefined`. */
+    toonChannel?: ToonChannelAccept;
+}
+/** Options for {@link Http402Client.fetch} / `ToonClient.h402Fetch`. */
+interface H402FetchOptions {
+    /** HTTP method. Default `'GET'`. */
+    method?: string;
+    /** Request headers. */
+    headers?: Record<string, string>;
+    /** Request body. */
+    body?: string | Uint8Array;
+    /** Request timeout in milliseconds. */
+    timeout?: number;
+    /** Optional explicit ILP destination override (else the x402 entry's value). */
+    destination?: string;
+}
+/**
+ * Caller-supplied hook that signs a balance-proof claim for `(destination,
+ * amount)` and returns the chain-appropriate claim message to attach to the ILP
+ * PREPARE. ToonClient wires this to its ChannelManager + per-chain signer (the
+ * exact same plumbing as `publishEvent`). The returned value is forwarded
+ * opaquely as the `ILP-Payment-Channel-Claim` header by {@link HttpIlpClient}.
+ */
+type ClaimResolver = (destination: string, amount: bigint) => Promise<unknown>;
+/** Factory for an {@link HttpIlpClient} given a resolved `POST /ilp` endpoint. */
+type HttpIlpClientFactory = (httpEndpoint: string) => HttpIlpClient;
+interface Http402ClientConfig {
+    /**
+     * Underlying HTTP fetch for the INITIAL (un-paid) request that probes for a
+     * 402. Default: global `fetch`.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Resolves + signs the payment-channel claim. REQUIRED to pay; if omitted,
+     * a 402 with a `toon-channel` offer is surfaced unchanged (vanilla challenge).
+     */
+    resolveClaim?: ClaimResolver;
+    /**
+     * Builds the {@link HttpIlpClient} for a resolved endpoint. Default: construct
+     * a new `HttpIlpClient({ httpEndpoint })`. Injectable for tests.
+     */
+    createIlpClient?: HttpIlpClientFactory;
+    /**
+     * AC4: request a duplex transport for the paid send. When `true` and the
+     * toon-channel entry advertises `supportsUpgrade`, {@link selectIlpTransport}
+     * returns `http-upgradable` and the send path calls
+     * {@link HttpIlpClient.upgradeToBtp} before writing — the wiring for
+     * large/streaming responses. Default `false` (stateless one-shot HTTP).
+     *
+     * NOTE (v1 limitation): even on the upgrade path the actual write is still a
+     * one-shot `sendIlpPacketWithClaim`; full duplex body streaming over the BTP
+     * session is a documented follow-up. The selection + upgrade CALL PATH is
+     * wired and exercised here so the streaming consumer can take over the
+     * returned session in a later iteration.
+     */
+    needsDuplex?: boolean;
+}
+/**
+ * Reusable h402 fetch engine. `ToonClient.h402Fetch` is a thin wrapper that
+ * constructs this with the live claim/channel plumbing.
+ */
+declare class Http402Client {
+    private readonly fetchImpl;
+    private readonly resolveClaim?;
+    private readonly createIlpClient;
+    private readonly needsDuplex;
+    constructor(config?: Http402ClientConfig);
+    /**
+     * `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).
+     */
+    fetch(url: string, opts?: H402FetchOptions): Promise<Response>;
+    /**
+     * 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`.
+     */
+    private payOverToon;
+    /**
+     * 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.
+     */
+    private sendOverChoice;
+}
+/**
+ * Parse a 402 `Response` body into a {@link ParsedX402Challenge}, selecting the
+ * first usable `toon-channel` entry. Reads every field defensively; a malformed
+ * body, a non-JSON body, or an entry missing its `destination`/`httpEndpoint`
+ * yields `{ toonChannel: undefined }` so the caller falls back to the vanilla
+ * 402 rather than throwing.
+ */
+declare function parseX402Challenge(response: Response): Promise<ParsedX402Challenge>;
+/** Pure parser over an already-decoded x402 body (testable without a Response). */
+declare function parseX402Body(body: unknown): ParsedX402Challenge;
+/**
+ * Serialize a raw HTTP request to HTTP/1.1 wire bytes:
+ * `METHOD path HTTP/1.1\r\n` + `Host:` + headers + `\r\n\r\n` + body.
+ *
+ * The request-line target is the URL's path+query (origin-form); we add a
+ * `Host` header from the URL authority and a `Content-Length` when there's a
+ * body, unless the caller already supplied them. Header names are matched
+ * case-insensitively so we never duplicate `Host`/`Content-Length`.
+ */
+declare function serializeHttpRequest(req: {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array;
+}): Uint8Array;
+/**
+ * Parse HTTP/1.1 wire bytes (status-line + headers + CRLFCRLF + body) into a
+ * standard Web `Response`. Used to reconstruct the origin response from the ILP
+ * FULFILL `data`.
+ *
+ * @throws {ConnectorError} If the bytes are not a parseable HTTP/1.1 response.
+ */
+declare function parseHttpResponse(bytes: Uint8Array): Response;
+
 /**
  * ToonClient - High-level client for interacting with TOON network.
  *
@@ -668,6 +1058,33 @@ declare class ToonClient {
         claim?: SignedBalanceProof;
         ilpAmount?: bigint;
     }): Promise<PublishEventResult>;
+    /**
+     * 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.
+     */
+    h402Fetch(url: string, opts?: H402FetchOptions): Promise<Response>;
     /**
      * 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`:
@@ -680,7 +1097,7 @@ declare class ToonClient {
      *       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
      */
     sendSwapPacket(params: {
         destination: string;
@@ -711,7 +1128,31 @@ declare class ToonClient {
      * adapter in `getSignerForChannel` delegates to the same
      * `EvmSigner.buildClaimMessage`).
      */
-    private buildClaimMessageForProof;
+    private buildClaimMessageForProof;
+    /**
+     * 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.
+     */
+    private getClaimTransport;
     /**
      * Shared claim-resolution logic used by `publishEvent` and `sendSwapPacket`.
      * TODO(12.5 followup): also factor `publishEvent`'s inline claim resolution
@@ -813,48 +1254,6 @@ declare class ToonClient {
     getDiscoveredPeers(): _toon_protocol_core.DiscoveredPeer[];
 }
 
-/**
- * Hidden-service hostname validation for the anyone-protocol / ATOR network.
- *
- * The `anon` binary routes hidden-service hostnames under the **`.anyone`** TLD
- * ONLY. A `<host>.anon` name is NOT recognized as a hidden service — anon treats
- * it as a clearnet name and tries to exit-resolve it, which fails
- * (`resolve failed` / `HostUnreachable`). Only `<host>.anyone` triggers anon's
- * `parse_extended_hostname: Anyone dns address lookup` and is validated.
- *
- * Historically the client and the toon-client pod accepted BOTH `.anon` and
- * `.anyone`, so a `.anon` address was silently accepted and then failed deep in
- * the transport with an opaque error. This module makes `.anyone` the single
- * accepted/routable HS TLD and rejects `.anon` up front with an actionable
- * message (see issue #201).
- *
- * This is a pure, browser-safe helper (no Node built-ins) so it can be imported
- * from any transport path.
- */
-/**
- * A `<host>.anyone` hidden-service hostname. The label is base32 (`a-z2-7`),
- * matching the on-wire onion-style address alphabet anon uses.
- */
-declare const HS_HOSTNAME_REGEX: RegExp;
-/** Max length of an HS hostname (defensive bound against pathological input). */
-declare const HS_HOSTNAME_MAX_LENGTH = 80;
-/**
- * Returns true iff `s` is a routable `.anyone` hidden-service hostname.
- * Does NOT accept the legacy `.anon` TLD (see {@link assertRoutableHsHostname}).
- */
-declare function isRoutableHsHostname(s: unknown): s is string;
-/**
- * Validates that `hostname` is a routable `.anyone` hidden-service address.
- *
- * - `<host>.anyone` → returns the hostname unchanged.
- * - `<host>.anon`   → throws with an actionable message pointing at `.anyone`
- *   (anon does NOT route `.anon`; it would silently fail in the transport).
- * - anything else   → throws a generic format error.
- *
- * @throws {Error} if the hostname is not a routable `.anyone` HS address.
- */
-declare function assertRoutableHsHostname(hostname: unknown): string;
-
 /**
  * Base error class for all TOON client errors.
  */
@@ -1183,214 +1582,6 @@ declare class HttpConnectorAdmin implements ConnectorAdminClient {
     private handleErrorResponse;
 }
 
-interface BtpRuntimeClientConfig {
-    btpUrl: string;
-    peerId: string;
-    authToken: string;
-    /** Max reconnection attempts on send failure (default: 3) */
-    maxRetries?: number;
-    /** Delay between reconnection attempts in ms (default: 1000) */
-    retryDelay?: number;
-    /** Custom WebSocket constructor (for SOCKS5 proxy support). */
-    createWebSocket?: (url: string) => WebSocket;
-}
-/**
- * BTP transport implementing IlpClient.
- * Uses IsomorphicBtpClient (browser-native, no Node.js dependencies).
- */
-declare class BtpRuntimeClient implements IlpClient {
-    private btpClient;
-    private readonly config;
-    private _isConnected;
-    constructor(config: BtpRuntimeClientConfig);
-    /**
-     * Connects to the BTP peer via WebSocket.
-     */
-    connect(): Promise<void>;
-    /**
-     * Attempts to reconnect by creating a fresh client and connecting.
-     */
-    reconnect(): Promise<void>;
-    /**
-     * Disconnects from the BTP peer.
-     */
-    disconnect(): Promise<void>;
-    get isConnected(): boolean;
-    /**
-     * Sends an ILP packet via BTP with auto-reconnect on connection errors.
-     * Satisfies IlpClient interface.
-     */
-    sendIlpPacket(params: {
-        destination: string;
-        amount: string;
-        data: string;
-        timeout?: number;
-    }): Promise<IlpSendResult>;
-    /**
-     * Sends a balance proof claim via BTP protocol data, then sends an ILP packet.
-     * Auto-reconnects on connection errors.
-     */
-    sendIlpPacketWithClaim(params: {
-        destination: string;
-        amount: string;
-        data: string;
-        timeout?: number;
-    }, claim: Record<string, unknown>): Promise<IlpSendResult>;
-    /**
-     * Send a standalone `payment-channel-claim` BTP MESSAGE (no ILP packet
-     * attached). The connector's ClaimReceiver consumes this fire-and-forget
-     * to register cumulative claim state independently of the per-packet
-     * forwarding path. Auto-reconnects on connection errors.
-     */
-    sendClaimMessage(claim: Record<string, unknown>): Promise<void>;
-    private _sendClaimMessageOnce;
-    /**
-     * Single-attempt ILP packet send. Reconnects if not connected.
-     */
-    private _sendIlpPacketOnce;
-    /**
-     * Single-attempt claim + ILP packet send. Reconnects if not connected.
-     */
-    private _sendIlpPacketWithClaimOnce;
-}
-
-/**
- * ILP-over-HTTP (RFC-0035) transport for the TOON client.
- *
- * The connector now serves ILP-over-HTTP on the SAME port as BTP (connector
- * PR #181). This adapter lets a client do stateless one-shot writes over HTTP
- * (`POST /ilp`) and upgrade to a duplex BTP session when it needs to receive
- * server-initiated packets or act as a peer.
- *
- * Wire contract (targets connector PR #181's `/ilp`):
- *  - One-shot write: `POST /ilp`
- *      body:    OER-encoded ILP PREPARE (`application/octet-stream`)
- *      header:  `ILP-Payment-Channel-Claim: base64(JSON of the claim)` — the
- *               SAME claim JSON the BTP path attaches as the
- *               `payment-channel-claim` protocolData entry.
- *      optional: `ILP-Peer-Id` + `Authorization: Bearer <secret>` identity.
- *      response: `200 OK` with an OER FULFILL or REJECT body. HTTP non-2xx is
- *                reserved for TRANSPORT errors (400/401/413/5xx); ILP-level
- *                rejects come back as a 200 + REJECT body.
- *  - Upgrade to BTP: standard HTTP `Upgrade` with `Sec-WebSocket-Protocol: btp`
- *      plus the same `ILP-Peer-Id` + `Authorization` headers. The connector
- *      pre-authenticates the BTP session from those headers (continuity), so
- *      after `101` we send BTP frames WITHOUT a separate in-band auth frame.
- *      Omitting the auth headers falls back to the normal BTP auth-frame flow.
- *
- * Reuses `serializeIlpPrepare`/`deserializeIlpPacket` from `btp/protocol.ts` —
- * the SAME OER codec the BTP path uses. Claim signing/construction is owned by
- * the caller (BootstrapService); this transport never builds or signs claims.
- */
-
-/** Header carrying the base64(JSON) payment-channel claim. */
-declare const ILP_CLAIM_HEADER = "ILP-Payment-Channel-Claim";
-/** Header carrying a NIP-59 wrapped (gift-wrapped) claim. */
-declare const ILP_CLAIM_WRAPPED_HEADER = "ILP-Payment-Channel-Claim-Wrapped";
-/** Header carrying the peer identity. */
-declare const ILP_PEER_ID_HEADER = "ILP-Peer-Id";
-interface HttpIlpClientConfig {
-    /** The peer's `POST /ilp` URL (the `httpEndpoint` from discovery). */
-    httpEndpoint: string;
-    /**
-     * Optional peer identity. With no `peerId`/`authToken` the connector treats
-     * the request as an anonymous no-auth peer (permissionless default) and
-     * derives an ephemeral id from the claim signer.
-     */
-    peerId?: string;
-    /** Bearer secret for `Authorization`. Omit for the no-auth peer path. */
-    authToken?: string;
-    /** Request timeout in milliseconds (default: 30000). */
-    timeout?: number;
-    /** Max retry attempts for transport-level network failures (default: 3). */
-    maxRetries?: number;
-    /** Initial retry delay in milliseconds (default: 1000). */
-    retryDelay?: number;
-    /** Custom fetch implementation (SOCKS5 mode / testing). */
-    httpClient?: typeof fetch;
-    /**
-     * Custom WebSocket constructor for the BTP upgrade path (SOCKS5 mode).
-     * Forwarded to the underlying BtpRuntimeClient.
-     */
-    createWebSocket?: (url: string) => WebSocket;
-}
-/**
- * Stateless ILP-over-HTTP transport implementing `IlpClient`.
- *
- * Use this for pure one-shot consumers (publish-and-forget writes). When the
- * client needs a duplex session — to receive server-initiated packets or to act
- * as a peer — call {@link upgradeToBtp} to obtain a connected BtpRuntimeClient
- * that reuses the existing BTP code path.
- */
-declare class HttpIlpClient implements IlpClient {
-    private readonly httpEndpoint;
-    private readonly peerId;
-    private readonly authToken;
-    private readonly timeout;
-    private readonly retryConfig;
-    private readonly httpClient;
-    private readonly createWebSocket;
-    constructor(config: HttpIlpClientConfig);
-    /**
-     * Send an ILP PREPARE via `POST /ilp` WITHOUT a claim. The connector accepts
-     * this only on free/zero-amount routes; paid writes must use
-     * {@link sendIlpPacketWithClaim}. Satisfies the IlpClient interface.
-     */
-    sendIlpPacket(params: {
-        destination: string;
-        amount: string;
-        data: string;
-        timeout?: number;
-    }): Promise<IlpSendResult>;
-    /**
-     * Send an ILP PREPARE via `POST /ilp` with the payment-channel claim attached
-     * as the `ILP-Payment-Channel-Claim` header. `claim` is the SAME JSON object
-     * the BTP path attaches as the `payment-channel-claim` protocolData entry —
-     * we base64(JSON.stringify(claim)) it, byte-for-byte identical to BTP.
-     */
-    sendIlpPacketWithClaim(params: {
-        destination: string;
-        amount: string;
-        data: string;
-        timeout?: number;
-    }, claim: unknown): Promise<IlpSendResult>;
-    /**
-     * Upgrade to a duplex BTP session over the SAME endpoint.
-     *
-     * Derives the `ws(s)://` URL from `httpEndpoint`, opens a WebSocket with
-     * `Sec-WebSocket-Protocol: btp` and the same `ILP-Peer-Id` + `Authorization`
-     * headers, and returns a connected {@link BtpRuntimeClient}. When auth headers
-     * are present the connector pre-authenticates the session (no in-band auth
-     * frame); without them the BtpRuntimeClient falls back to the normal BTP
-     * auth-frame flow.
-     *
-     * NOTE: passing per-connection headers + a subprotocol to a WebSocket is
-     * Node-only (the `ws` package). Browsers cannot set arbitrary request headers
-     * on a WebSocket handshake, so a browser consumer must use the gateway
-     * transport or BTP-with-auth-frame instead.
-     */
-    upgradeToBtp(): Promise<BtpRuntimeClient>;
-    private authHeaders;
-    /**
-     * Single attempt: serialize the PREPARE, POST it, and map the response.
-     * @throws {NetworkError} On connection/timeout failures (retried).
-     * @throws {ConnectorError} On non-retryable transport errors (5xx / unexpected).
-     */
-    private postPrepare;
-    /**
-     * Map a `200 OK` body (OER FULFILL/REJECT) to an IlpSendResult; map a non-2xx
-     * to a transport error. Per the wire contract, ILP-level rejects arrive as a
-     * 200 + REJECT body — only HTTP non-2xx means a transport-layer failure.
-     */
-    private mapResponse;
-    private mapTransportError;
-}
-/**
- * Derive the BTP WebSocket URL from a `POST /ilp` HTTP endpoint. The connector
- * serves BTP on the SAME path, so we only swap the scheme (http→ws, https→wss).
- */
-declare function httpEndpointToBtpUrl(httpEndpoint: string): string;
-
 /**
  * Transport selection policy for the client ILP layer.
  *
@@ -2138,93 +2329,42 @@ interface RetryOptions {
 declare function withRetry<T>(operation: () => Promise<T>, options: RetryOptions): Promise<T>;
 
 /**
- * Self-managed `anon` (anyone-protocol / ATOR) SOCKS5h proxy (Node.js only).
+ * Store-write HTTP envelope for the payment-proxy (HTTP-in-ILP) path.
  *
- * Lets a `@toon-protocol/client` consumer reach a `.anyone` hidden service with
- * ZERO manual proxy setup: the SDK downloads, verifies, extracts, and spawns its
- * own `anon` daemon, waits for it to bootstrap + bind a loopback SOCKS5 port, and
- * hands back a `socks5h://127.0.0.1:<port>` URL. The proven reference is the
- * server-side pod entrypoint `docker/src/entrypoint-toon-client.ts` (`writeTorrc`,
- * `spawnAnon`, `waitForAnonSocks`, `tcpProbe`); this module ports that daemon
- * logic into the client package and adds the binary download + checksum gate so it
- * works without an OS-level `anon` install.
+ * The deployed connector is a payment-proxy: it terminates a paid write by
+ * decoding the ILP PREPARE `data` as a literal RFC 7230 HTTP/1.1 request and
+ * reverse-proxying it to the relay store's `POST /write` (see the connector's
+ * `HttpProxyHandler.decodeHttpRequest`). The ILP `data` MUST therefore be a
+ * full HTTP request envelope:
  *
- * BROWSER SAFETY: this module is dynamically imported only from `resolveTransport`
- * when a managed proxy is actually needed (Node-only path). Every Node built-in is
- * pulled in lazily via the ESM-safe `require(...)` built off `import.meta.url`
- * (the same pattern as `socks5.ts`), so a browser bundler that statically analyses
- * the package never reaches `node:child_process`/`node:fs`/`node:https`/`node:net`.
- */
-/**
- * Pinned `anon` release. "beta" is the channel slug embedded in the per-platform
- * zip asset names (e.g. `anon-beta-macos-arm64.zip`).
- */
-declare const ANON_VERSION = "v0.4.10.0-beta";
-/**
- * Per-platform `anon` zip asset descriptor. `sha256` is the pinned checksum of the
- * release zip. All supported platforms are pinned (issue #204); the type stays
- * `string | null` and the download gate still defensively refuses a `null` entry,
- * so adding a new (not-yet-hashed) platform fails closed rather than skipping
- * verification.
- */
-interface AnonAsset {
-    /** Release asset file name, e.g. `anon-beta-macos-arm64.zip`. */
-    assetName: string;
-    /** Pinned sha256 of the zip, or null when not yet pinned (issue #204). */
-    sha256: string | null;
-}
-/**
- * Platform → asset map keyed by `${os.platform()}-${os.arch()}` (Node values).
- * Only macOS + Linux on x64/arm64 are supported (the `anon` releases that ship a
- * SOCKS-capable binary). Windows is intentionally absent.
+ *   POST /write HTTP/1.1\r\n
+ *   Host: relay\r\n
+ *   Content-Type: application/json\r\n
+ *   \r\n
+ *   {"event": <signed nostr event object>}
  *
- * Pinned checksums (issue #204): all four supported platforms are pinned to the
- * sha256 of the `v0.4.10.0-beta` release zips (downloaded + hashed; the
- * darwin-arm64 value matches the previously-verified manual flow).
- */
-declare const ANON_ASSETS: Record<string, AnonAsset>;
-/**
- * Resolves the `anon` release asset for a platform/arch pair (Node
- * `os.platform()` / `os.arch()` values).
+ * Sending the bare TOON-encoded event (no request-line) makes the proxy reject
+ * with `F01 - Invalid HTTP envelope: malformed request-line`. The relay's
+ * `/write` handler parses the body as JSON and reads `body.event` as a full
+ * signed Nostr event OBJECT (it runs `verifyEvent(event)` + `store(event)`), so
+ * the body carries the event object verbatim — NOT the TOON string.
  *
- * @throws If the platform/arch combination has no known `anon` asset.
- */
-declare function selectAnonAsset(platform: string, arch: string): AnonAsset;
-/**
- * Handle returned by `startManagedAnonProxy`. `socksProxy` is the loopback
- * `socks5h://` URL to wire into `transport: { type: 'socks5', socksProxy }`.
- * `stop()` SIGTERMs the daemon and is idempotent.
+ * This helper is the single source of truth for that envelope so the proxy
+ * paid-write path (`ToonClient.publishEvent`) and any future caller stay
+ * byte-compatible with the deployed store. It is isomorphic (Node + browser):
+ * `JSON.stringify` escapes non-ASCII to `\uXXXX`, so the serialized envelope is
+ * pure ASCII and `encodeUtf8` matches the bytes the store expects.
  */
-interface ManagedAnonProxy {
-    socksProxy: string;
-    stop(): Promise<void>;
-}
-/**
- * Options for `startManagedAnonProxy`. All have sensible defaults; tests inject
- * the deps to avoid real downloads/spawns.
- */
-interface StartManagedAnonProxyOptions {
-    /** Cache dir for the binary + torrc + data. Default: {@link defaultCacheDir}. */
-    cacheDir?: string;
-    /** Loopback SOCKS5 port. Default 9050. */
-    socksPort?: number;
-    /** Bootstrap deadline in ms. Default 180_000. */
-    bootstrapTimeoutMs?: number;
-    /** Logger. Default: no-op. */
-    log?: (msg: string) => void;
-    /** os.platform() override (tests). */
-    platform?: string;
-    /** os.arch() override (tests). */
-    arch?: string;
-}
+
 /**
- * Downloads (if needed) + spawns a managed `anon` daemon and waits for its SOCKS5
- * port to bind. Returns a {@link ManagedAnonProxy} whose `socksProxy` is ready for
- * `transport: { type: 'socks5', socksProxy }`.
+ * Wrap a signed Nostr event in the `POST /write` HTTP envelope the deployed
+ * payment-proxy reverse-proxies to the relay store.
  *
- * @throws If the platform is unsupported, the checksum fails, or anon never binds.
+ * @param event - A finalized (signed) Nostr event — passed through to the store
+ *   as the JSON `event` field verbatim (the store re-verifies the signature).
+ * @returns The envelope bytes to use as the ILP PREPARE `data`.
  */
-declare function startManagedAnonProxy(options?: StartManagedAnonProxyOptions): Promise<ManagedAnonProxy>;
+declare function buildStoreWriteEnvelope(event: NostrEvent): Uint8Array;
 
 /**
  * Settlement info produced by buildSettlementInfo().
@@ -2258,6 +2398,16 @@ declare function applyNetworkPresets(config: ToonClientConfig): ToonClientConfig
  * unset or `'custom'` (no preset tier to report on).
  */
 declare function getNetworkStatus(config: ToonClientConfig): NetworkFamilyStatus | undefined;
+/**
+ * Normalize a connector-proxy base URL into its `POST /ilp` endpoint.
+ *
+ * `https://proxy.devnet.toonprotocol.dev`      → `https://proxy.devnet.toonprotocol.dev/ilp`
+ * `https://proxy.devnet.toonprotocol.dev/ilp`  → unchanged (idempotent)
+ * `https://proxy.devnet.toonprotocol.dev/`     → `https://proxy.devnet.toonprotocol.dev/ilp`
+ *
+ * Returns `undefined` for an empty/falsy input so callers can `??`-chain it.
+ */
+declare function proxyIlpEndpoint(proxyUrl: string | undefined): string | undefined;
 /**
  * Validates ToonClient configuration.
  *
@@ -2270,7 +2420,7 @@ declare function validateConfig(config: ToonClientConfig): void;
  * The resolved config type after defaults are applied.
  * secretKey is guaranteed to be present (auto-generated if omitted).
  */
-type ResolvedConfig = Required<Omit<ToonClientConfig, 'connector' | 'mnemonic' | 'mnemonicAccountIndex' | 'evmPrivateKey' | 'network' | 'supportedChains' | 'settlementAddresses' | 'preferredTokens' | 'tokenNetworks' | 'btpUrl' | 'btpAuthToken' | 'btpPeerId' | 'connectorHttpEndpoint' | 'connectorSupportsUpgrade' | 'chainRpcUrls' | 'initialDeposit' | 'settlementTimeout' | 'solanaChannel' | 'minaChannel' | 'channelStorePath' | 'knownPeers' | 'destinationAddress' | 'transport' | 'managedAnonProxy' | 'managedAnonSocksPort'>> & {
+type ResolvedConfig = Required<Omit<ToonClientConfig, 'connector' | 'mnemonic' | 'mnemonicAccountIndex' | 'evmPrivateKey' | 'network' | 'supportedChains' | 'settlementAddresses' | 'preferredTokens' | 'tokenNetworks' | 'btpUrl' | 'btpAuthToken' | 'btpPeerId' | 'connectorHttpEndpoint' | 'proxyUrl' | 'faucetUrl' | 'connectorSupportsUpgrade' | 'chainRpcUrls' | 'initialDeposit' | 'settlementTimeout' | 'solanaChannel' | 'minaChannel' | 'channelStorePath' | 'knownPeers' | 'destinationAddress'>> & {
     connector?: unknown;
     /** Always present after applyDefaults() — derived from secretKey if not explicitly provided */
     evmPrivateKey: string | Uint8Array;
@@ -2286,14 +2436,8 @@ type ResolvedConfig = Required<Omit<ToonClientConfig, 'connector' | 'mnemonic' |
      * same index as the synchronously-resolved Nostr/EVM keys.
      */
     mnemonicAccountIndex?: number;
-    /** Transport privacy config (optional — defaults to direct). */
-    transport?: ClientTransportConfig;
     /** Named network tier, retained for `getNetworkStatus()`. */
     network?: ToonClientConfig['network'];
-    /** Self-managed `anon` SOCKS5h proxy opt-out (default auto). */
-    managedAnonProxy?: boolean;
-    /** Loopback SOCKS port for the managed `anon` daemon (default 9050). */
-    managedAnonSocksPort?: number;
     supportedChains?: string[];
     settlementAddresses?: Record<string, string>;
     preferredTokens?: Record<string, string>;
@@ -2302,6 +2446,8 @@ type ResolvedConfig = Required<Omit<ToonClientConfig, 'connector' | 'mnemonic' |
     btpAuthToken?: string;
     btpPeerId?: string;
     connectorHttpEndpoint?: string;
+    proxyUrl?: string;
+    faucetUrl?: string;
     connectorSupportsUpgrade?: boolean;
     chainRpcUrls?: Record<string, string>;
     initialDeposit?: string;
@@ -2728,6 +2874,51 @@ declare function filterPetListings(events: NostrEventLike[], options?: PetListin
  */
 declare function buildPetPurchaseRequest(params: PetPurchaseRequestParams): UnsignedNostrEvent;
 
+/**
+ * Devnet faucet helper.
+ *
+ * The deployed TOON devnet exposes a faucet that drips test funds to a given
+ * chain address so a client can open payment channels and pay for writes:
+ *
+ *   EVM     `POST {faucetUrl}/api/request`        body `{ address }` → 100 ETH + 10k USDC
+ *   Solana  `POST {faucetUrl}/api/solana/request` body `{ address }` → SOL + USDC
+ *   Mina    `POST {faucetUrl}/api/mina/request`   body `{ address }` → native MINA only
+ *
+ * Devnet edge (today): `https://faucet.devnet.toonprotocol.dev`.
+ *
+ * EVM is implemented fully. Solana/Mina are deferred to a later milestone (WS3)
+ * and throw a clear error so callers don't silently assume funding happened.
+ */
+/** Supported faucet chains. */
+type FaucetChain = 'evm' | 'solana' | 'mina';
+/** Result of a successful faucet drip. */
+interface FundWalletResult {
+    /** The chain that was funded. */
+    chain: FaucetChain;
+    /** The funded address (echoed back). */
+    address: string;
+    /** Raw parsed JSON body from the faucet (shape is faucet-defined). */
+    response: unknown;
+}
+/** Options for {@link fundWallet}. */
+interface FundWalletOptions {
+    /** Custom fetch implementation (for testing / custom transports). */
+    fetchImpl?: typeof fetch;
+    /** Request timeout in milliseconds (default: 30000). */
+    timeout?: number;
+}
+/**
+ * Drip test funds to `address` on `chain` from the devnet `faucetUrl`.
+ *
+ * @param faucetUrl - Faucet base URL, e.g. `https://faucet.devnet.toonprotocol.dev`.
+ *   A trailing `/` is tolerated.
+ * @param address - The chain address to fund (EVM 0x address, Solana base58, etc).
+ * @param chain - `'evm'` (implemented) | `'solana'` | `'mina'` (deferred — throw).
+ * @throws {Error} If `faucetUrl`/`address` is missing, or the chain is deferred.
+ * @throws {NetworkError} On transport failure or a non-2xx faucet response.
+ */
+declare function fundWallet(faucetUrl: string, address: string, chain: FaucetChain, options?: FundWalletOptions): Promise<FundWalletResult>;
+
 /**
  * Full multi-chain identity derived from a single BIP-39 mnemonic.
  */
@@ -3077,4 +3268,4 @@ declare function loadKeystore(path: string, password: string): string;
  */
 declare function writeKeystoreFile(path: string, keystore: EncryptedKeystore): void;
 
-export { ANON_ASSETS, ANON_VERSION, type AnonAsset, type BackupPayload, type BalanceProofParams, BtpRuntimeClient, type BtpRuntimeClientConfig, type ChainMetadata, type ChainSigner, ChannelManager, type ClaimMessage, type ClientTransportConfig, ConnectorError, type DiscoveredIlpPeer, type EVMClaimMessage, type EncryptedKeystore, EvmSigner, HS_HOSTNAME_MAX_LENGTH, HS_HOSTNAME_REGEX, HttpConnectorAdmin, type HttpConnectorAdminConfig, HttpIlpClient, type HttpIlpClientConfig, HttpRuntimeClient, type HttpRuntimeClientConfig, ILP_CLAIM_HEADER, ILP_CLAIM_WRAPPED_HEADER, ILP_PEER_ID_HEADER, type IlpTransportChoice, type InteractionResultContent, KeyManager, type KeyManagerConfig, type ManagedAnonProxy, type MinaClaimMessage, type MinaDepositReader, MinaSigner, type MinaSignerOptions, NetworkError, OnChainChannelClient, type OnChainChannelClientConfig, type PasskeyInfo, type PetDvmProvider, type PetInteractionEventData, type PetInteractionRequestParams, type PetInteractionResultData, type PetListing, type PetListingFilterOptions, type PetListingParams, type PetPurchaseRequestParams, type ProofStatus, type PublishEventResult, type RequestBlobStorageParams, type RequestBlobStorageResult, type RetryOptions, type SelectIlpTransportOptions, type SignedBalanceProof, type SolanaChannelClientOptions, type SolanaClaimMessage, SolanaSigner, type StartManagedAnonProxyOptions, type StatValues, ToonClient, type ToonClientConfig, ToonClientError, type ToonIdentity, type ToonSigners, type ToonStartResult, type UnsignedNostrEvent, ValidationError, type VaultData, applyDefaults, applyNetworkPresets, assertRoutableHsHostname, buildBackupEvent, buildBackupFilter, buildPetInteractionRequest, buildPetListingEvent, buildPetPurchaseRequest, buildSettlementInfo, decryptMnemonic, deriveFromNsec, deriveFullIdentity, deriveNostrKeyFromMnemonic, encryptMnemonic, filterPetDvmProviders, filterPetListings, generateKeystore, generateMnemonic, generateRandomIdentity, getNetworkStatus, httpEndpointToBtpUrl, importKeystore, isPrfSupported, isRoutableHsHostname, loadKeystore, parseBackupPayload, parsePetInteractionEvent, parsePetInteractionResult, parsePetListing, readDiscoveredIlpPeer, readMinaDepositTotal, requestBlobStorage, selectAnonAsset, selectIlpTransport, startManagedAnonProxy, validateConfig, validateMnemonic, withRetry, writeKeystoreFile };
+export { type BackupPayload, type BalanceProofParams, BtpRuntimeClient, type BtpRuntimeClientConfig, type ChainMetadata, type ChainSigner, ChannelManager, type ClaimMessage, type ClaimResolver, ConnectorError, type DiscoveredIlpPeer, type EVMClaimMessage, type EncryptedKeystore, EvmSigner, type FaucetChain, type FundWalletOptions, type FundWalletResult, type H402FetchOptions, Http402Client, type Http402ClientConfig, HttpConnectorAdmin, type HttpConnectorAdminConfig, HttpIlpClient, type HttpIlpClientConfig, type HttpIlpClientFactory, HttpRuntimeClient, type HttpRuntimeClientConfig, ILP_CLAIM_HEADER, ILP_CLAIM_WRAPPED_HEADER, ILP_PEER_ID_HEADER, type IlpTransportChoice, type InteractionResultContent, KeyManager, type KeyManagerConfig, type MinaClaimMessage, type MinaDepositReader, MinaSigner, type MinaSignerOptions, NetworkError, OnChainChannelClient, type OnChainChannelClientConfig, type ParsedX402Challenge, type PasskeyInfo, type PetDvmProvider, type PetInteractionEventData, type PetInteractionRequestParams, type PetInteractionResultData, type PetListing, type PetListingFilterOptions, type PetListingParams, type PetPurchaseRequestParams, type ProofStatus, type PublishEventResult, type RequestBlobStorageParams, type RequestBlobStorageResult, type RetryOptions, type SelectIlpTransportOptions, type SignedBalanceProof, type SolanaChannelClientOptions, type SolanaClaimMessage, SolanaSigner, type StatValues, type ToonChannelAccept, ToonClient, type ToonClientConfig, ToonClientError, type ToonIdentity, type ToonSigners, type ToonStartResult, type UnsignedNostrEvent, ValidationError, type VaultData, applyDefaults, applyNetworkPresets, buildBackupEvent, buildBackupFilter, buildPetInteractionRequest, buildPetListingEvent, buildPetPurchaseRequest, buildSettlementInfo, buildStoreWriteEnvelope, decryptMnemonic, deriveFromNsec, deriveFullIdentity, deriveNostrKeyFromMnemonic, encryptMnemonic, filterPetDvmProviders, filterPetListings, fundWallet, generateKeystore, generateMnemonic, generateRandomIdentity, getNetworkStatus, httpEndpointToBtpUrl, importKeystore, isPrfSupported, loadKeystore, parseBackupPayload, parseHttpResponse, parsePetInteractionEvent, parsePetInteractionResult, parsePetListing, parseX402Body, parseX402Challenge, proxyIlpEndpoint, readDiscoveredIlpPeer, readMinaDepositTotal, requestBlobStorage, selectIlpTransport, serializeHttpRequest, validateConfig, validateMnemonic, withRetry, writeKeystoreFile };