@toon-protocol/client 0.11.0 → 0.12.0

package/README.md

@@ -23,7 +23,6 @@ This client handles:
 - **Unified Identity**: One Nostr key = one EVM address (both secp256k1, derived automatically) — or a single BIP-39 **mnemonic** to derive a full multi-chain identity
 - **Multi-Chain Settlement**: Sign payment-channel claims on EVM (EIP-712), Solana (Ed25519), and Mina (Pallas) from one mnemonic. A Townhouse apex validates the claim and redeems it on-chain on the matching chain (EVM/Solana credit the recipient; Mina redeems each claim on-chain with recipient credit-at-close deferred — see [Multi-Chain Settlement notes](#identity--multi-chain-settlement))
 - **Multi-Hop Routing**: Publish to any destination address (`destination` / `destinationAddress`), not just your direct peer
-- **Private Transport**: Optionally reach a townhouse apex at its ATOR `.anyone` address through a SOCKS5h proxy (see [Connecting over `.anyone`](#connecting-to-an-apex-over-anyone))
 - **Network Bootstrap**: Automatically discover and register with ILP peers via NIP-02 follow lists
 - **TOON Encoding**: Native binary format for agent-friendly event encoding
 
@@ -44,8 +43,7 @@ pnpm add mina-signer
 - **A TOON apex to pay.** You don't run any node yourself; you connect to a running
   [`@toon-protocol/townhouse`](https://www.npmjs.com/package/@toon-protocol/townhouse) apex (or any
   TOON connector) and pay it. From its operator you need:
-  - a **connector endpoint** — either an HTTP `connectorUrl`, or an ATOR `.anyone` BTP endpoint reached
-    through a **SOCKS5h** proxy (see [Connecting over `.anyone`](#connecting-to-an-apex-over-anyone));
+  - a **connector endpoint** — an HTTP `connectorUrl` and/or a BTP WebSocket `btpUrl`;
   - a **settlement-chain RPC URL** and a **funded key** on that chain, so the client can open a
     payment channel and sign EIP-712 claims;
   - the **token** and **TokenNetwork** contract addresses that apex accepts on that chain (e.g. USDC).
@@ -256,29 +254,6 @@ const client = new ToonClient({
 
 ---
 
-## Connecting to an apex over `.anyone`
-
-In production a townhouse apex is reachable at an ATOR `.anyone` hidden-service address rather than a plain `ws://` host. To dial it, route the client's BTP/HTTP traffic through a **SOCKS5h** proxy via the `transport` option. The `socks5h://` scheme is required so DNS resolution happens at the proxy (no DNS leaks):
-
-```typescript
-const client = new ToonClient({
-  connectorUrl: 'http://localhost:8080', // local connector admin, if any
-  secretKey,
-  ilpInfo: { pubkey, ilpAddress: `g.toon.${pubkey.slice(0, 8)}`, btpEndpoint: 'ws://abc...xyz.anyone:3000' },
-  btpUrl: 'ws://abc...xyz.anyone:3000', // the apex's BTP endpoint at its .anyone address
-  destinationAddress: 'g.townhouse', // pay the apex; it forwards to the town/dvm/mill child
-  toonEncoder: encodeEventToToon,
-  toonDecoder: decodeEventFromToon,
-
-  // Route the connection through a SOCKS5h proxy (Node.js only).
-  transport: { type: 'socks5', socksProxy: 'socks5h://127.0.0.1:9050' },
-});
-```
-
-In the browser, use `transport: { type: 'gateway', gatewayUrl: 'https://…' }` to proxy through an ator gateway server-side instead. (Default is `{ type: 'direct' }`.)
-
----
-
 ## Documentation
 
 - **[API Reference](docs/api-reference.md)** — Constructor, config interface, and all methods

package/dist/index.d.ts

@@ -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.
@@ -517,7 +496,7 @@ interface BtpRuntimeClientConfig {
     maxRetries?: number;
     /** Delay between reconnection attempts in ms (default: 1000) */
     retryDelay?: number;
-    /** Custom WebSocket constructor (for SOCKS5 proxy support). */
+    /** Custom WebSocket constructor (for testing / custom transports). */
     createWebSocket?: (url: string) => WebSocket;
 }
 /**
@@ -632,11 +611,11 @@ interface HttpIlpClientConfig {
     maxRetries?: number;
     /** Initial retry delay in milliseconds (default: 1000). */
     retryDelay?: number;
-    /** Custom fetch implementation (SOCKS5 mode / testing). */
+    /** Custom fetch implementation (for testing / custom transports). */
     httpClient?: typeof fetch;
     /**
-     * Custom WebSocket constructor for the BTP upgrade path (SOCKS5 mode).
-     * Forwarded to the underlying BtpRuntimeClient.
+     * Custom WebSocket constructor for the BTP upgrade path (for testing /
+     * custom transports). Forwarded to the underlying BtpRuntimeClient.
      */
     createWebSocket?: (url: string) => WebSocket;
 }
@@ -832,7 +811,7 @@ interface Http402ClientConfig {
     resolveClaim?: ClaimResolver;
     /**
      * Builds the {@link HttpIlpClient} for a resolved endpoint. Default: construct
-     * a new `HttpIlpClient({ httpEndpoint })`. Injectable for tests / SOCKS5.
+     * a new `HttpIlpClient({ httpEndpoint })`. Injectable for tests.
      */
     createIlpClient?: HttpIlpClientFactory;
     /**
@@ -1118,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;
@@ -1150,6 +1129,30 @@ declare class ToonClient {
      * `EvmSigner.buildClaimMessage`).
      */
     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
@@ -1251,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.
  */
@@ -2368,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().
@@ -2488,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.
  *
@@ -2500,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;
@@ -2516,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>;
@@ -2532,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;
@@ -2958,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.
  */
@@ -3307,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 ClaimResolver, type ClientTransportConfig, ConnectorError, type DiscoveredIlpPeer, type EVMClaimMessage, type EncryptedKeystore, EvmSigner, type H402FetchOptions, HS_HOSTNAME_MAX_LENGTH, HS_HOSTNAME_REGEX, 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 ManagedAnonProxy, 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 StartManagedAnonProxyOptions, type StatValues, type ToonChannelAccept, 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, parseHttpResponse, parsePetInteractionEvent, parsePetInteractionResult, parsePetListing, parseX402Body, parseX402Challenge, readDiscoveredIlpPeer, readMinaDepositTotal, requestBlobStorage, selectAnonAsset, selectIlpTransport, serializeHttpRequest, 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 };