@toon-protocol/client 0.9.0 → 0.9.2

package/dist/index.d.ts

@@ -1,8 +1,75 @@
 import * as _toon_protocol_core from '@toon-protocol/core';
-import { IlpPeerInfo, IlpSendResult, IlpClient, ConnectorAdminClient, ConnectorChannelClient, OpenChannelParams, OpenChannelResult, ChannelState } from '@toon-protocol/core';
+import { IlpPeerInfo, NetworkFamilyStatus, IlpSendResult, IlpClient, ConnectorAdminClient, ConnectorChannelClient, OpenChannelParams, OpenChannelResult, ChannelState } from '@toon-protocol/core';
 import { NostrEvent } from 'nostr-tools/pure';
 import { PrivateKeyAccount } from 'viem/accounts';
 
+/**
+ * Solana payment-channel parameters supplied via `ToonClientConfig.solanaChannel`.
+ *
+ * Mirrors the `SolanaChannelConfig` consumed by `OnChainChannelClient`, minus
+ * the Ed25519 keypair (derived from the client's `mnemonic`, see
+ * `ToonClientConfig.solanaChannel`).
+ */
+interface SolanaChannelClientOptions {
+    /** Solana JSON-RPC URL used to open the channel + read PDA state. */
+    rpcUrl: string;
+    /** Deployed payment-channel program id (base58). */
+    programId: string;
+    /**
+     * Default SPL token mint (base58) for PDA derivation. The per-channel
+     * negotiated token (the peer's preferred token) takes precedence when present.
+     */
+    tokenMint?: string;
+    /** Challenge-period duration (seconds) for `initialize_channel`. */
+    challengeDuration?: number;
+    /**
+     * Optional on-chain deposit when opening the channel: `amount` in base units
+     * (string) drawn from `payerTokenAccount` (the client's funded SPL token
+     * account / ATA, base58). When omitted, the channel is opened without a
+     * deposit (connector accepts on `opened` status + participant membership).
+     */
+    deposit?: {
+        amount: string;
+        payerTokenAccount: string;
+    };
+}
+/**
+ * Mina payment-channel parameters supplied via `ToonClientConfig.minaChannel`.
+ *
+ * Mirrors the `MinaChannelConfig` consumed by `OnChainChannelClient`, minus the
+ * Mina private key (derived from the client's `mnemonic`, the same key that
+ * produces the registered Mina signer — so the channel-open key and the
+ * claim-signing key are guaranteed identical).
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * PHASE-2 STAGE-3: the client's Mina claim now matches connector 3.9.0's
+ * `MinaClaimMessage` contract — `{ zkAppAddress, tokenId, balanceCommitment,
+ * proof (base64), salt, nonce }`, with the proof a Pallas Schnorr signature over
+ * the connector's `Poseidon([balA,balB,salt]) / Poseidon(zkApp.x)` commitment
+ * (verified field-by-field against the connector's o1js verify). A
+ * Mina-denominated paid publish is ACCEPTED at `validateClaimMessage` and the
+ * apex FULFILLs to town. On-chain SETTLE remains gated for non-EVM dynamic
+ * hidden-service peers by connector#88 (`No chain configured for peer`).
+ * `zkAppAddress` must be a REAL deployed payment-channel zkApp the apex's Mina
+ * provider can resolve on-chain (the e2e harness deploys it deterministically).
+ * ────────────────────────────────────────────────────────────────────────────
+ */
+interface MinaChannelClientOptions {
+    /** Mina GraphQL URL used to open the channel + read zkApp state. */
+    graphqlUrl: string;
+    /** Deployed payment-channel zkApp address (B62 base58). */
+    zkAppAddress: string;
+    /** Channel settlement timeout in slots for `initializeChannel` (default 86400). */
+    challengeDuration?: number;
+    /** Mina token id field (decimal string) for `initializeChannel` (default '1'). */
+    tokenId?: string;
+    /** Optional on-chain deposit (base units, string) after the channel opens. */
+    deposit?: {
+        amount: string;
+    };
+    /** Mina network id for the account/Schnorr prefix (default 'devnet'). */
+    networkId?: 'devnet' | 'mainnet';
+}
 /**
  * Configuration for ToonClient.
  *
@@ -43,9 +110,41 @@ interface ToonClientConfig {
      * Reserved for future implementation.
      */
     connector?: unknown;
+    /**
+     * BIP-39 mnemonic phrase to derive a full multi-chain identity from.
+     *
+     * When provided, the client derives the Nostr (NIP-06) + EVM keys
+     * synchronously at construction and the Solana (Ed25519) + Mina (Pallas) keys
+     * lazily in `start()`, registering per-chain signers so balance-proof claims
+     * can be settled on any of those chains. This is the recommended way to use
+     * non-EVM settlement (the raw `secretKey` path is secp256k1-only).
+     *
+     * Cannot be combined with `secretKey` (ambiguous Nostr identity). May be
+     * combined with `evmPrivateKey` to use a separate EVM key (e.g. hardware
+     * wallet) while still deriving Solana/Mina from the phrase.
+     *
+     * SECURITY: JavaScript strings are immutable and cannot be zeroed from
+     * memory — the phrase may persist in the heap until GC. Prefer
+     * passing a pre-derived `secretKey`/identity in high-security contexts.
+     */
+    mnemonic?: string;
+    /**
+     * BIP-44 account index used when deriving the multi-chain identity from
+     * `mnemonic`. Defaults to 0 (back-compat). A non-zero index derives a
+     * dedicated wallet from a shared mnemonic, producing the SAME addresses as
+     * the SDK's `fromMnemonicFull(mnemonic, { accountIndex })`:
+     *   - Nostr (secp256k1): m/44'/1237'/0'/0/{index}
+     *   - EVM (secp256k1): same key as Nostr
+     *   - Solana (Ed25519): m/44'/501'/{index}'/0' (SLIP-0010)
+     *   - Mina (Pallas): m/44'/12586'/{index}'/0/0
+     *
+     * Ignored unless `mnemonic` is provided.
+     */
+    mnemonicAccountIndex?: number;
     /**
      * 32-byte Nostr private key (hex or Uint8Array).
-     * Optional — if omitted, a keypair is auto-generated in applyDefaults().
+     * Optional — if omitted, a keypair is auto-generated in applyDefaults()
+     * (or derived from `mnemonic` when that is provided instead).
      */
     secretKey?: Uint8Array;
     /** ILP peer information for this client */
@@ -65,6 +164,27 @@ interface ToonClientConfig {
      * (e.g., hardware wallet, custodial key, or legacy key separation).
      */
     evmPrivateKey?: string | Uint8Array;
+    /**
+     * Named network tier. When set (and != `'custom'`), the client defaults all
+     * settlement-related config — RPC/GraphQL URLs, supported chain identifiers,
+     * preferred tokens, EVM TokenNetwork addresses, and the Solana/Mina channel
+     * params (programId / zkApp) — from the shared core presets
+     * (`resolveClientNetwork`), so the caller no longer hand-wires every address.
+     * This is the client-side mirror of the townhouse node's `network` selector;
+     * both resolve the SAME deployed contracts.
+     *
+     * Precedence: any explicit per-chain field (`supportedChains`,
+     * `chainRpcUrls`, `settlementAddresses`, `preferredTokens`, `tokenNetworks`,
+     * `solanaChannel`, `minaChannel`) you also pass OVERRIDES the preset for that
+     * field. `'custom'` keeps the fully-manual path (no preset defaults). When
+     * unset, behaviour is unchanged (fully backward compatible).
+     *
+     * - `mainnet` — Base mainnet + public Solana/Mina (TOON contracts not yet
+     *   deployed → settlement unconfigured, relay-only).
+     * - `testnet` / `devnet` — Base Sepolia + Solana/Mina devnet with the LIVE
+     *   deployed TOON settlement contracts.
+     */
+    network?: 'mainnet' | 'testnet' | 'devnet' | 'custom';
     /** Supported settlement chain identifiers (e.g., ["evm:anvil:31337"]) */
     supportedChains?: string[];
     /** Maps chain identifier to EVM settlement address */
@@ -94,8 +214,66 @@ interface ToonClientConfig {
     initialDeposit?: string;
     /** Challenge period in seconds (default: 86400) */
     settlementTimeout?: number;
+    /**
+     * Solana payment-channel parameters for opening a REAL on-chain channel and
+     * signing a connector-format Solana balance proof.
+     *
+     * When present (and the client has a Solana signer — i.e. it was constructed
+     * from a `mnemonic`), `ToonClient.start()` wires these into the on-chain
+     * channel client so that negotiating a `solana:*` chain opens an on-chain
+     * channel at the connector-parity PDA and pays a Solana-denominated claim.
+     *
+     * The Ed25519 keypair is NOT carried here — it is derived from the same
+     * `mnemonic` that produces the Solana signer, so the channel-open key and the
+     * claim-signing key are guaranteed identical.
+     */
+    solanaChannel?: SolanaChannelClientOptions;
+    /**
+     * Mina payment-channel parameters (graphqlUrl + zkAppAddress). When present
+     * (and the client has a Mina signer — i.e. it was constructed from a
+     * `mnemonic` AND `mina-signer` is installed), `ToonClient.start()` wires these
+     * into the on-chain channel client so negotiating a `mina:*` chain routes
+     * through `openMinaChannel` and pays a Mina-denominated claim.
+     *
+     * The Mina private key is NOT carried here — it is derived from the same
+     * `mnemonic` that produces the Mina signer.
+     *
+     * NOTE (Phase-2 Stage-3 gate): see `MinaChannelClientOptions` — supplying this
+     * wires the negotiation path but the resulting claim does not yet satisfy
+     * connector 3.9.0's Mina claim contract, so a live loop is claim-validation
+     * gated (distinct from the connector #88 on-chain-settle gate).
+     */
+    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;
     /**
@@ -166,7 +344,52 @@ interface SignedBalanceProof extends BalanceProofParams {
     tokenNetworkAddress: string;
     /** ERC-20 token address (e.g. USDC) for self-describing claim verification */
     tokenAddress?: string;
+    /**
+     * Counterparty settlement address the balance proof is bound to.
+     *
+     * Required for Solana/Mina, where the canonical balance-proof message folds
+     * the recipient in (`balanceProofHashSolana` / `balanceProofFieldsMina`).
+     * Unused for the client's EVM path (EIP-712 `BalanceProof` has no recipient
+     * term). Carried here so it flows from signing through to `buildClaimMessage`.
+     */
+    recipient?: string;
+    /**
+     * Mina payment-channel claim fields (connector 3.9.0 `MinaClaimMessage`).
+     *
+     * Populated only by {@link MinaSigner}, which produces the connector's
+     * `Poseidon([balA,balB,salt])` balance commitment + a Pallas Schnorr `proof`
+     * over `[commitment, Field(nonce), Poseidon(zkApp.x)]` rather than reusing the
+     * generic `signature` field. Carried so they flow from signing through to
+     * `MinaSigner.buildClaimMessage`. Absent for EVM/Solana.
+     */
+    mina?: {
+        /** `Poseidon([balanceA, balanceB, salt]).toString()`. */
+        balanceCommitment: string;
+        /** base64-encoded JSON proof `{ commitment, signature: { r, s }, nonce, signerPublicKey }`. */
+        proof: string;
+        /** Decimal salt string. */
+        salt: string;
+        /** Mina token id (default `'MINA'`). */
+        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;
+};
 
 /**
  * ToonClient - High-level client for interacting with TOON network.
@@ -209,6 +432,20 @@ declare class ToonClient {
     private readonly config;
     private state;
     private readonly evmSigner?;
+    private solanaSigner?;
+    /**
+     * Ed25519 signing seed (32 bytes) derived from the mnemonic for the Solana
+     * identity. Retained so `start()` can inject it into the on-chain channel
+     * client's Solana config (same key as `solanaSigner`).
+     */
+    private solanaSeed?;
+    private minaSigner?;
+    /**
+     * Mina private key (big-endian hex scalar, as `deriveFullIdentity` emits)
+     * derived from the mnemonic. Retained so `start()` can inject it into the
+     * on-chain channel client's Mina config (same key as `minaSigner`).
+     */
+    private minaPrivateKey?;
     private channelManager?;
     private readonly peerNegotiations;
     /**
@@ -232,10 +469,34 @@ declare class ToonClient {
      * Works before start() is called.
      */
     getPublicKey(): string;
+    /**
+     * Per-chain settlement readiness for the configured `network` tier, mirroring
+     * the townhouse node's status. Returns `undefined` when no named `network` is
+     * set (or `network: 'custom'`), since there is no preset tier to report on.
+     */
+    getNetworkStatus(): NetworkFamilyStatus | undefined;
     /**
      * Gets the EVM address derived from the Nostr secret key (or explicit evmPrivateKey override).
      */
     getEvmAddress(): string | undefined;
+    /**
+     * Gets the Solana (base58) address, when the client was constructed from a
+     * `mnemonic`. Available only AFTER `start()` (Solana keys are derived
+     * asynchronously). Returns undefined otherwise.
+     */
+    getSolanaAddress(): string | undefined;
+    /**
+     * Gets the Mina (base58) address, when the client was constructed from a
+     * `mnemonic` AND `mina-signer` is installed. Available only AFTER `start()`.
+     * Returns undefined otherwise.
+     */
+    getMinaAddress(): string | undefined;
+    /**
+     * Derive the Solana/Mina keys from the mnemonic and register their signers on
+     * the ChannelManager. Mirrors how the EVM signer is wired, but for the
+     * non-secp256k1 chains. Skips any chain whose optional dependency is missing.
+     */
+    private registerMnemonicChainSigners;
     /**
      * Starts the ToonClient.
      *
@@ -263,7 +524,58 @@ declare class ToonClient {
     publishEvent(event: NostrEvent, options?: {
         destination?: string;
         claim?: SignedBalanceProof;
+        ilpAmount?: bigint;
     }): Promise<PublishEventResult>;
+    /**
+     * 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`:
+     * it forwards the raw `IlpSendResult` so the sender (`streamSwap()`) can
+     * decode FULFILL metadata itself.
+     *
+     * Claim resolution mirrors `publishEvent`:
+     *   (a) explicit `params.claim` -> use it,
+     *   (b) `channelManager` present -> auto-open + auto-sign for the peer
+     *       matching `destination`,
+     *   (c) neither -> throw MISSING_CLAIM.
+     *
+     * @throws {ToonClientError} INVALID_STATE / NO_BTP_CLIENT / MISSING_CLAIM
+     */
+    sendSwapPacket(params: {
+        destination: string;
+        amount: bigint;
+        toonData: Uint8Array;
+        timeout?: number;
+        claim?: SignedBalanceProof;
+    }): Promise<IlpSendResult>;
+    /**
+     * Build a BTP claim message from a pre-signed balance proof using the
+     * CHAIN-APPROPRIATE signer.
+     *
+     * The explicit-claim path (caller signs the balance proof, then passes
+     * `{ claim }`) must wrap the proof with the signer matching the channel's
+     * chain. Hardcoding `EvmSigner.buildClaimMessage` here produced an EVM
+     * `BTPClaimMessage` for a Solana/Mina balance proof — no `blockchain`
+     * discriminator and the base58 channel account placed in the EVM
+     * `channelId` field — which the connector's inbound validator classifies
+     * as EVM and rejects with F06 (`Invalid channelId format`).
+     *
+     * When the proof's `channelId` is tracked we use
+     * `getSignerForChannel(channelId).buildClaimMessage`, which emits the
+     * correct per-chain envelope (e.g. `blockchain:'solana'` + base58
+     * `channelAccount`). When it is not tracked we fall back to the EVM signer
+     * to preserve prior behavior for lightweight/EVM-only callers.
+     *
+     * EVM output is byte-identical to the previous hardcoded path (the EVM
+     * adapter in `getSignerForChannel` delegates to the same
+     * `EvmSigner.buildClaimMessage`).
+     */
+    private buildClaimMessageForProof;
+    /**
+     * Shared claim-resolution logic used by `publishEvent` and `sendSwapPacket`.
+     * TODO(12.5 followup): also factor `publishEvent`'s inline claim resolution
+     * to call this helper. Kept duplicated for now to minimize regression risk.
+     */
+    private resolveClaimForDestination;
     /**
      * Signs a balance proof for the given channel with the specified amount.
      * Delegates to ChannelManager which auto-increments nonce and tracks cumulative amount.
@@ -274,6 +586,22 @@ declare class ToonClient {
      * @throws {ToonClientError} If no EVM signer configured or channel not tracked
      */
     signBalanceProof(channelId: string, amount: bigint): Promise<SignedBalanceProof>;
+    /**
+     * Eagerly open (or return existing) payment channel for the given destination.
+     *
+     * Channels are normally opened lazily on the first `publishEvent()` /
+     * `sendSwapPacket()` call. This method exposes the lazy-open path so
+     * callers (and E2E tests) that need a tracked `channelId` BEFORE publishing
+     * can force the open. Idempotent — returns the existing channel ID for the
+     * peer if one is already open.
+     *
+     * @param destination - Optional ILP destination address. Defaults to
+     *   `config.destinationAddress`.
+     * @returns The channel ID of the (now) open channel.
+     * @throws {ToonClientError} If client not started, no channel manager
+     *   configured, or peer negotiation metadata missing.
+     */
+    openChannel(destination?: string): Promise<string>;
     /**
      * Gets list of tracked payment channel IDs.
      */
@@ -343,6 +671,48 @@ 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.
  */
@@ -679,6 +1049,8 @@ interface BtpRuntimeClientConfig {
     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.
@@ -722,6 +1094,14 @@ declare class BtpRuntimeClient implements IlpClient {
         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.
      */
@@ -761,36 +1141,92 @@ interface ChainSigner {
         transferredAmount: bigint;
         lockedAmount: bigint;
         locksRoot: string;
+        /**
+         * Counterparty settlement address the proof is bound to. Required for
+         * Solana/Mina (folded into the canonical balance-proof message); the EVM
+         * adapter ignores it (EIP-712 has no recipient term).
+         */
+        recipient: string;
         metadata: ChainMetadata;
+        /**
+         * On-chain channel `depositTotal` (base units). When supplied (>0), a Mina
+         * signer binds the conserved `balanceB = depositTotal − balanceA` commitment
+         * required to settle on a funded zkApp (connector#133); EVM/Solana signers
+         * ignore it. When omitted, a Mina signer self-resolves it from chain if it
+         * was configured with a GraphQL URL (#223), else falls back to the legacy
+         * `balanceB = 0` form.
+         */
+        depositTotal?: bigint;
     }): Promise<SignedBalanceProof>;
     buildClaimMessage(proof: SignedBalanceProof, senderId: string): ClaimMessage;
 }
 type ClaimMessage = EVMClaimMessage | SolanaClaimMessage | MinaClaimMessage;
+/**
+ * Solana payment-channel claim — wire-compatible with the connector's
+ * `SolanaClaimMessage` (`@toon-protocol/connector` `btp/btp-claim-types.ts`).
+ * Field names match the connector's `validateSolanaClaim` exactly:
+ * `channelAccount` (base58 PDA), `signerPublicKey` (base58), base64 `signature`.
+ */
 interface SolanaClaimMessage {
     version: '1.0';
     blockchain: 'solana';
     messageId: string;
     timestamp: string;
     senderId: string;
-    channelId: string;
+    /** On-chain PDA account address for the payment channel (base58). */
+    channelAccount: string;
     nonce: number;
+    /** Cumulative transferred amount (string for bigint precision). */
     transferredAmount: string;
+    /** Ed25519 signature over the 48-byte balance-proof message (base64). */
     signature: string;
-    signerAddress: string;
+    /** Base58-encoded Ed25519 public key of the signer. */
+    signerPublicKey: string;
+    /** Solana program id for the payment-channel program (base58). */
     programId: string;
 }
+/**
+ * Mina payment-channel claim — wire-compatible with the connector's
+ * `MinaClaimMessage` (`@toon-protocol/connector` `btp/btp-claim-types.ts`).
+ * Field names + types match `validateMinaClaim` exactly: `zkAppAddress`
+ * (B62-prefixed 55-char base58, the channel id), `tokenId`, `balanceCommitment`
+ * (`Poseidon([balA,balB,salt])` decimal string), integer `nonce`, base64 `proof`,
+ * and `salt`. `transferredAmount`/`balanceB`/`signatureB`/`network` are OPTIONAL
+ * at validation; the apex-as-recipient single-direction claim sends party-A only.
+ */
 interface MinaClaimMessage {
     version: '1.0';
     blockchain: 'mina';
     messageId: string;
     timestamp: string;
     senderId: string;
-    channelId: string;
-    nonce: number;
-    transferredAmount: string;
-    commitment: string;
-    signerAddress: string;
+    /** Deployed payment-channel zkApp address (B62 base58) — the channel id. */
     zkAppAddress: string;
+    /** Mina token id (default `'MINA'`). */
+    tokenId: string;
+    /** `Poseidon([balanceA, balanceB, salt]).toString()`. */
+    balanceCommitment: string;
+    nonce: number;
+    /** base64-encoded JSON `{ commitment, signature: { r, s }, nonce, signerPublicKey }`. */
+    proof: string;
+    /** Commitment salt (decimal string). */
+    salt: string;
+    /** Cumulative transferred amount (optional; string for bigint precision). */
+    transferredAmount?: string;
+    /**
+     * Signer's Mina public key (B62 base58) — the claiming participant.
+     *
+     * Surfaced top-level (in addition to being embedded in `proof`) so the
+     * connector's `SettlementExecutor` can resolve participant keys for the
+     * on-chain `claimFromChannel` on an externally-opened (inbound) channel. The
+     * connector reads `latestClaim.signerPublicKey` directly (not the proof blob);
+     * without it the Mina SDK's `claimFromChannel` throws `ACCOUNT_NOT_FOUND`
+     * ("Participant keys not found in cache and none were supplied"). The
+     * connector accepts this as an optional `MinaClaimMessage` field.
+     */
+    signerPublicKey?: string;
+    /** Mina network id — defaults to `devnet` connector-side when omitted. */
+    network?: 'mainnet' | 'devnet' | 'berkeley' | 'lightnet';
 }
 
 /**
@@ -862,17 +1298,33 @@ declare class EvmSigner {
 }
 
 /**
- * Solana signer for Ed25519 balance proofs.
+ * Solana signer for the connector payment-channel claim path.
  *
- * Signs channel state using Ed25519 (raw, not EIP-712).
- * Dynamically imports @noble/curves to avoid missing-dep errors for non-Solana users.
+ * Signs the connector's on-chain payment-channel balance-proof message — the
+ * raw 48-byte `channel_pda(32) || nonce(8 LE) || transferredAmount(8 LE)` (see
+ * `@toon-protocol/connector` `SolanaPaymentChannelSDK._buildBalanceProofMessage`
+ * + `solana-payment-channel-provider.verifyBalanceProof`). The produced 64-byte
+ * Ed25519 signature verifies on the connector's `verifySolanaClaim` path, which
+ * is what makes a client-issued Solana payment-channel claim (paying the apex
+ * to write) acceptable on connector 3.9.0.
+ *
+ * NOTE: this is a DIFFERENT message from the Mill ↔ sender swap-claim wire
+ * contract (`balanceProofHashSolana`, SDK `verifyEd25519Signature`). The client
+ * here is paying a payment-channel claim to the apex, not issuing a swap claim,
+ * so it must sign the connector's on-chain payment-channel message. `channelId`
+ * MUST be the base58 channel PDA (produced by `OnChainChannelClient.openChannel`).
  */
 declare class SolanaSigner implements ChainSigner {
     readonly chainType: "solana";
+    /** 32-byte Ed25519 seed. */
     private readonly privateKey;
-    private publicKey?;
     private pubkeyBase58Cache?;
-    constructor(privateKey: Uint8Array);
+    /**
+     * @param privateKey - 32-byte Ed25519 seed (e.g. `identity.solana.secretKey.slice(0, 32)`).
+     * @param publicKeyBase58 - Optional base58 public key (e.g. `identity.solana.publicKey`).
+     *   When omitted it is derived lazily from `privateKey`.
+     */
+    constructor(privateKey: Uint8Array, publicKeyBase58?: string);
     private ensurePublicKey;
     get signerIdentifier(): string;
     signBalanceProof(params: {
@@ -881,44 +1333,170 @@ declare class SolanaSigner implements ChainSigner {
         transferredAmount: bigint;
         lockedAmount: bigint;
         locksRoot: string;
+        recipient: string;
         metadata: ChainMetadata;
     }): Promise<SignedBalanceProof>;
     buildClaimMessage(proof: SignedBalanceProof, senderId: string): ClaimMessage;
 }
 
+/** Reads a channel zkApp's on-chain `depositTotal` (base units). */
+type MinaDepositReader = (zkAppAddress: string) => Promise<bigint>;
+/** Optional `MinaSigner` wiring for on-chain `depositTotal` resolution. */
+interface MinaSignerOptions {
+    /**
+     * Mina GraphQL URL used to read the channel's on-chain `depositTotal` when a
+     * caller doesn't supply it to `signBalanceProof`. Enables conserved
+     * `balanceB = depositTotal − balanceA` claims (settleable on funded zkApps).
+     */
+    graphqlUrl?: string;
+    /** Inject a deposit reader (tests / custom transport). Overrides `graphqlUrl`. */
+    depositReader?: MinaDepositReader;
+}
 /**
- * Mina signer for Poseidon commitment balance proofs.
+ * Mina (Pallas) signer for the connector payment-channel claim path.
+ *
+ * Produces the connector 3.9.0 `MinaClaimMessage` contract — `{ zkAppAddress,
+ * tokenId, balanceCommitment, proof (base64), salt, nonce }` — by reproducing
+ * `MinaPaymentChannelSDK.signBalanceProof` exactly (via
+ * {@link buildMinaPaymentChannelProof}):
+ *
+ *   commitment       = Poseidon([Field(balanceA), Field(0), Field(salt)])
+ *   channelHashField = Poseidon([participantA.x, participantB.x, 0])   (see below)
+ *   proof            = base64(JSON{ commitment, signature: { r, s }, nonce, signerPublicKey })
+ *
+ * with the Schnorr signature computed over `[commitment, Field(nonce),
+ * channelHashField]` using the Mina `'devnet'` network id (matching o1js's
+ * hardcoded `Signature.create` prefix). Verified field-by-field against the
+ * connector's o1js `Signature.fromJSON({r,s}).verify` (see the package tests).
+ *
+ * `channelHashField` is the ON-CHAIN participant form
+ * (`Poseidon([client.x, apex.x, 0])`, participantA=client, participantB=apex)
+ * whenever the apex's Mina pubkey is known (the negotiated `recipient`), so the
+ * claim can SETTLE on-chain via the zkApp's `claimFromChannel` (which only
+ * verifies the participant form). When the apex pubkey is unavailable the signer
+ * falls back to the legacy zkApp-x form (`Poseidon([zkApp.x])`); the connector's
+ * off-chain `verifyBalanceProof` accepts EITHER, so off-chain store/FULFILL works
+ * in both cases — only on-chain settle requires the participant form.
+ *
+ * NOTE: this is a DIFFERENT message + format from the Mill ↔ sender swap-claim
+ * wire contract (`balanceProofFieldsMina` in `@toon-protocol/core`, verified by
+ * the SDK's `verifyMinaSignature`). The client here pays a payment-channel claim
+ * to the apex, so it signs the connector's on-chain payment-channel scheme; the
+ * swap-format hash is left untouched (mirrors the Solana #105 separation).
  *
- * Dynamically imports o1js to avoid pulling 50MB into the client bundle
- * for non-Mina users.
+ * `channelId` MUST be the deployed payment-channel zkApp B62 address (the same
+ * address the apex's Mina provider resolves on-chain via `getChannelState`),
+ * which is what `OnChainChannelClient.openMinaChannel` returns.
+ *
+ * `mina-signer` is an OPTIONAL dependency: its crypto (Poseidon, Pallas Schnorr,
+ * the base58 signature codec) is loaded dynamically so the client builds and runs
+ * for non-Mina users without it installed, and WITHOUT pulling the o1js WASM
+ * circuit runtime.
  */
 declare class MinaSigner implements ChainSigner {
     readonly chainType: "mina";
-    private readonly privateKeyBase58;
-    private publicKeyBase58;
-    constructor(privateKeyBase58: string);
+    /** Big-endian hex scalar (or already-`EK…` base58) Mina private key. */
+    private readonly privateKey;
+    private publicKeyBase58?;
+    private readonly depositReader?;
+    /** Per-zkApp `depositTotal` cache (deposits are rare; the connector re-reads). */
+    private readonly depositCache;
+    /**
+     * @param privateKey - Mina private key as big-endian hex scalar (the form
+     *   `deriveFullIdentity()` emits, `identity.mina.privateKey`) or an `EK…`
+     *   base58 key. Converted to the base58check form mina-signer requires.
+     * @param publicKeyBase58 - Optional base58 public key (e.g.
+     *   `identity.mina.publicKey`). When omitted it is derived during signing.
+     * @param options - Optional on-chain `depositTotal` resolution (graphqlUrl or
+     *   an injected reader) so claims conserve balances on funded zkApps.
+     */
+    constructor(privateKey: string, publicKeyBase58?: string, options?: MinaSignerOptions);
+    /**
+     * Resolve the channel's on-chain `depositTotal`, caching per zkApp. Returns
+     * `undefined` when no reader is configured or the read fails — callers then
+     * fall back to the legacy `balanceB = 0` commitment.
+     */
+    private resolveDepositTotal;
     get signerIdentifier(): string;
-    private ensurePublicKey;
+    /** Derive this signer's B62 public key from its (base58) private key. */
+    private deriveOwnPublicKey;
     signBalanceProof(params: {
         channelId: string;
         nonce: number;
         transferredAmount: bigint;
         lockedAmount: bigint;
         locksRoot: string;
+        recipient: string;
         metadata: ChainMetadata;
+        /**
+         * On-chain channel `depositTotal`. When provided (>0), the signed commitment
+         * binds `balanceB = depositTotal − balanceA` (the funder's remaining
+         * balance), matching the connector's claimFromChannel reconstruction
+         * (toon-protocol/connector#133) and the on-chain circuit's
+         * `balanceA + balanceB == depositTotal` invariant. Omitted/0 keeps the
+         * legacy `balanceB = 0` form (off-chain-store-only, non-settleable).
+         */
+        depositTotal?: bigint;
     }): Promise<SignedBalanceProof>;
     buildClaimMessage(proof: SignedBalanceProof, senderId: string): ClaimMessage;
 }
 
 interface SolanaChannelConfig {
     rpcUrl: string;
+    /**
+     * Ed25519 keypair material. Accepts either a 32-byte seed or a 64-byte
+     * `secretKey` (seed || pubkey, as produced by `deriveFullIdentity`). The first
+     * 32 bytes are the signing seed; the public key is derived from it.
+     */
     keypair: Uint8Array;
     programId: string;
+    /**
+     * SPL token mint (base58) for PDA derivation. Optional — the per-channel
+     * negotiated token (`OpenChannelParams.token`) takes precedence when present.
+     */
+    tokenMint?: string;
+    /**
+     * Challenge-period duration in seconds for `initialize_channel`. Defaults to
+     * `OpenChannelParams.settlementTimeout` or 86400.
+     */
+    challengeDuration?: number;
+    /**
+     * Optional deposit amount (base units, string) + the payer's funded SPL token
+     * account (ATA, base58). When omitted, the channel is opened (initialized)
+     * without an on-chain deposit — the connector accepts the claim on channel
+     * `opened` status + participant membership; deposit is only consumed at
+     * on-chain claim/settle time.
+     */
+    deposit?: {
+        amount: string;
+        payerTokenAccount: string;
+    };
 }
 interface MinaChannelConfig {
     graphqlUrl: string;
     privateKey: string;
     zkAppAddress: string;
+    /**
+     * Channel settlement timeout in slots for `initializeChannel`. Defaults to
+     * `OpenChannelParams.settlementTimeout` or 86400.
+     */
+    challengeDuration?: number;
+    /**
+     * Mina token id field (decimal string) for `initializeChannel`. Default '1'
+     * (native MINA). The connector reads this only as on-chain channel metadata.
+     */
+    tokenId?: string;
+    /**
+     * Optional on-chain deposit (base units, string) submitted after the channel
+     * is initialized. When omitted, the channel is opened (OPEN state) without a
+     * deposit — the connector accepts the claim on `opened` status; deposit is
+     * only consumed at on-chain settle time.
+     */
+    deposit?: {
+        amount: string;
+    };
+    /** Mina network id for the account/Schnorr prefix. Default 'devnet'. */
+    networkId?: 'devnet' | 'mainnet';
 }
 interface OnChainChannelClientConfig {
     evmSigner: EvmSigner;
@@ -935,10 +1513,29 @@ interface OnChainChannelClientConfig {
 declare class OnChainChannelClient implements ConnectorChannelClient {
     private readonly evmSigner;
     private readonly chainRpcUrls;
-    private readonly solanaConfig?;
-    private readonly minaConfig?;
+    private solanaConfig?;
+    private minaConfig?;
     private readonly channelContext;
     constructor(config: OnChainChannelClientConfig);
+    /**
+     * Late-binds the Solana channel config.
+     *
+     * `ToonClient.start()` derives the Solana Ed25519 keypair from the client's
+     * mnemonic asynchronously (after this client is constructed), so the keypair
+     * is injected here rather than at construction. Same keypair as the
+     * registered Solana signer — guarantees the channel-open key and the
+     * claim-signing key match.
+     */
+    setSolanaConfig(config: SolanaChannelConfig): void;
+    /**
+     * Late-binds the Mina channel config.
+     *
+     * Parallel to `setSolanaConfig`: `ToonClient.start()` derives the Mina private
+     * key from the client's mnemonic asynchronously (after this client is
+     * constructed), so the key is injected here rather than at construction. Same
+     * key as the registered Mina signer.
+     */
+    setMinaConfig(config: MinaChannelConfig): void;
     /**
      * Parse chain identifier to extract chainId.
      * Format: "evm:{network}:{chainId}" e.g., "evm:anvil:31337"
@@ -958,12 +1555,48 @@ declare class OnChainChannelClient implements ConnectorChannelClient {
      */
     openChannel(params: OpenChannelParams): Promise<OpenChannelResult>;
     /**
-     * Opens a Solana payment channel (PDA creation).
+     * Opens a REAL on-chain Solana payment channel.
+     *
+     * Derives the connector-parity channel PDA
+     * (`[b"channel", min_pubkey, max_pubkey, token_mint]`), submits the
+     * `initialize_channel` instruction (+ optional `deposit`) to the deployed
+     * payment-channel program, and returns the base58 PDA as the channel id. That
+     * PDA is what the claim carries as `channelAccount`, and the on-chain channel
+     * is what the connector's `verifySolanaClaim` reads via
+     * `provider.getChannelState` before accepting the claim.
+     *
+     * Mirrors `openEvmChannel`'s open(+deposit) structure. Idempotent: if the
+     * channel account already exists on-chain, returns its PDA without
+     * re-initializing.
      */
     private openSolanaChannel;
     /**
-     * Opens a Mina payment channel (zkApp state transition).
-     * Dynamically imports o1js to avoid bundle bloat.
+     * Opens a REAL on-chain Mina payment channel on the deployed `PaymentChannel`
+     * zkApp.
+     *
+     * The zkApp is deployed out-of-band (the operator/e2e harness deploys it
+     * deterministically and advertises its B62 address). This client then calls
+     * `initializeChannel` on that zkApp so its on-chain `channelState` becomes
+     * `OPEN` — which is what the connector's `MinaPaymentChannelSDK.getChannelState`
+     * reads to return status `'opened'` (claim verification otherwise fails with
+     * `mina_claim_verification_failed`). The deployed zkApp address IS the channel
+     * id: `MinaClaimMessage.zkAppAddress` is both the claim's channel identifier
+     * AND the channel-hash preimage the off-chain proof binds to (see
+     * `mina-payment-channel.ts`), so the channel-open id and the claim's channel id
+     * are guaranteed identical.
+     *
+     * This is the Mina analog of `openSolanaChannel` (connector#105): the client
+     * opens its own per-channel on-chain state (initialize + optional deposit). The
+     * heavyweight o1js + `@toon-protocol/mina-zkapp` proof work is lazily imported
+     * inside `openMinaChannelOnChain` so npm consumers who never open a Mina
+     * channel don't pay the o1js cost.
+     *
+     * Idempotent: if the on-chain channel is already `OPEN`, the opener returns
+     * without re-initializing.
+     *
+     * NOTE: full on-chain Mina SETTLE remains gated by the connector-side
+     * settlement-executor (the same blocker that stops the Solana SETTLE); reaching
+     * `opened` + a stored claim is parity with Solana.
      */
     private openMinaChannel;
     /**
@@ -1062,6 +1695,8 @@ declare class ChannelManager {
         chainId: number;
         tokenNetworkAddress: string;
         tokenAddress?: string;
+        recipient?: string;
+        depositTotal?: bigint;
     }, initialNonce?: number, initialAmount?: bigint): void;
     /**
      * Signs a balance proof for the given channel.
@@ -1093,6 +1728,26 @@ declare class ChannelManager {
     isTracking(channelId: string): boolean;
 }
 
+/**
+ * Read a Mina payment-channel zkApp's on-chain `depositTotal` via a plain
+ * GraphQL query (no o1js / WASM). Used by {@link MinaSigner} to bind the
+ * conserved `balanceB = depositTotal − balanceA` commitment that a FUNDED zkApp
+ * requires (connector#133); without it the connector's `claimFromChannel`
+ * verification rejects the claim with `F06 - Invalid zk-SNARK proof on claim`.
+ *
+ * The `PaymentChannel` zkApp app-state field order is
+ * `[channelHash, balanceCommitment, nonceField, channelState, depositTotal, …]`
+ * (see `mina-channel-open.ts`), so `depositTotal` is `zkappState[4]`.
+ */
+/**
+ * Query `account(publicKey).zkappState` and return the channel's `depositTotal`
+ * (base units). Throws when the account/state is unavailable so callers can fall
+ * back to the legacy `balanceB = 0` behavior.
+ *
+ * @param fetchImpl - injectable for tests; defaults to global `fetch`.
+ */
+declare function readMinaDepositTotal(graphqlUrl: string, zkAppAddress: string, fetchImpl?: typeof fetch): Promise<bigint>;
+
 /**
  * Configuration options for retry behavior with exponential backoff.
  */
@@ -1130,6 +1785,95 @@ interface RetryOptions {
  */
 declare function withRetry<T>(operation: () => Promise<T>, options: RetryOptions): Promise<T>;
 
+/**
+ * Self-managed `anon` (anyone-protocol / ATOR) SOCKS5h proxy (Node.js only).
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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).
+ *
+ * @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.
+ */
+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 }`.
+ *
+ * @throws If the platform is unsupported, the checksum fails, or anon never binds.
+ */
+declare function startManagedAnonProxy(options?: StartManagedAnonProxyOptions): Promise<ManagedAnonProxy>;
+
 /**
  * Settlement info produced by buildSettlementInfo().
  * Extends the core SettlementConfig shape with ilpAddress for client use.
@@ -1141,6 +1885,27 @@ interface ClientSettlementInfo {
     preferredTokens?: Record<string, string>;
     tokenNetworks?: Record<string, string>;
 }
+/**
+ * Applies named-network preset defaults to a client config.
+ *
+ * When `config.network` is set and != `'custom'`, the settlement-related
+ * fields are defaulted from the shared core presets (`resolveClientNetwork`):
+ * RPC/GraphQL URLs, supported chain identifiers, preferred tokens, EVM
+ * TokenNetwork addresses, and the Solana/Mina channel params. Any explicit
+ * per-chain field on `config` OVERRIDES the preset (explicit always wins).
+ *
+ * `'custom'` and the unset case both pass `config` through untouched, keeping
+ * the fully-manual path and full backward compatibility.
+ *
+ * @returns A shallow copy with preset defaults merged in (never mutates input).
+ */
+declare function applyNetworkPresets(config: ToonClientConfig): ToonClientConfig;
+/**
+ * Returns per-chain settlement readiness for the configured `network` tier,
+ * mirroring the townhouse node's status. Returns `undefined` when `network` is
+ * unset or `'custom'` (no preset tier to report on).
+ */
+declare function getNetworkStatus(config: ToonClientConfig): NetworkFamilyStatus | undefined;
 /**
  * Validates ToonClient configuration.
  *
@@ -1153,10 +1918,30 @@ 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' | 'evmPrivateKey' | 'supportedChains' | 'settlementAddresses' | 'preferredTokens' | 'tokenNetworks' | 'btpUrl' | 'btpAuthToken' | 'btpPeerId' | 'chainRpcUrls' | 'initialDeposit' | 'settlementTimeout' | 'channelStorePath' | 'knownPeers' | 'destinationAddress'>> & {
+type ResolvedConfig = Required<Omit<ToonClientConfig, 'connector' | 'mnemonic' | 'mnemonicAccountIndex' | 'evmPrivateKey' | 'network' | 'supportedChains' | 'settlementAddresses' | 'preferredTokens' | 'tokenNetworks' | 'btpUrl' | 'btpAuthToken' | 'btpPeerId' | 'chainRpcUrls' | 'initialDeposit' | 'settlementTimeout' | 'solanaChannel' | 'minaChannel' | 'channelStorePath' | 'knownPeers' | 'destinationAddress' | 'transport' | 'managedAnonProxy' | 'managedAnonSocksPort'>> & {
     connector?: unknown;
     /** Always present after applyDefaults() — derived from secretKey if not explicitly provided */
     evmPrivateKey: string | Uint8Array;
+    /**
+     * BIP-39 phrase retained so `ToonClient.start()` can derive the Solana/Mina
+     * keys asynchronously and register the corresponding signers. The Nostr/EVM
+     * keys are already resolved synchronously into `secretKey`/`evmPrivateKey`.
+     */
+    mnemonic?: string;
+    /**
+     * BIP-44 account index for mnemonic-based derivation (defaults to 0).
+     * Retained so `ToonClient.start()` derives the Solana/Mina signers at the
+     * 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>;
@@ -1167,6 +1952,8 @@ type ResolvedConfig = Required<Omit<ToonClientConfig, 'connector' | 'evmPrivateK
     chainRpcUrls?: Record<string, string>;
     initialDeposit?: string;
     settlementTimeout?: number;
+    solanaChannel?: ToonClientConfig['solanaChannel'];
+    minaChannel?: ToonClientConfig['minaChannel'];
     channelStorePath?: string;
     knownPeers?: {
         pubkey: string;
@@ -1180,12 +1967,509 @@ type ResolvedConfig = Required<Omit<ToonClientConfig, 'connector' | 'evmPrivateK
  * Auto-generates a Nostr keypair when secretKey is omitted.
  * Derives btpUrl from connectorUrl when not provided.
  */
-declare function applyDefaults(config: ToonClientConfig): ResolvedConfig;
+declare function applyDefaults(rawConfig: ToonClientConfig): ResolvedConfig;
 /**
  * Builds SettlementConfig from client config.
  * Returns undefined if no settlement-related config is present.
  */
-declare function buildSettlementInfo(config: ToonClientConfig): ClientSettlementInfo | undefined;
+declare function buildSettlementInfo(rawConfig: ToonClientConfig): ClientSettlementInfo | undefined;
+
+/**
+ * Pet DVM Client-Side Types
+ *
+ * Locally defined types for pet DVM interaction utilities.
+ * These mirror server-side types but do NOT import from @toon-protocol/pet-dvm,
+ * @toon-protocol/pet-circuit, or @toon-protocol/memvid-node.
+ *
+ * @module pet/types
+ */
+/** Plain-number stat values (all clamped to [1, 100]) */
+interface StatValues {
+    hunger: number;
+    happiness: number;
+    health: number;
+    hygiene: number;
+    energy: number;
+}
+/** Metadata for a pet DVM provider discovered via Kind 10035 events */
+interface PetDvmProvider {
+    /** ILP address of the provider's connector */
+    ilpAddress: string;
+    /** Per-interaction cost from skill.pricing['5900'] */
+    pricing: string;
+    /** Provider's Nostr pubkey (cryptographically bound from event.pubkey) */
+    pubkey: string;
+    /** Feature list from skill.features */
+    features: string[];
+}
+/** Parameters for building a Kind 5900 pet interaction request */
+interface PetInteractionRequestParams {
+    /** Blobbi identifier (non-empty string) */
+    blobbiId: string;
+    /** Action type (0-10, maps to Feed/Play/Clean/etc.) */
+    actionType: number;
+    /** Item identifier (>= 0) */
+    itemId: number;
+    /** Token cost for this interaction (>= 0) */
+    tokenCost: number;
+    /** Whether the pet is currently sleeping */
+    isSleeping: boolean;
+}
+/** Unsigned Nostr event structure compatible with nostr-tools finalizeEvent */
+interface UnsignedNostrEvent {
+    kind: number;
+    created_at: number;
+    tags: string[][];
+    content: string;
+}
+/** Parsed result data from Kind 6900 DVM response (base64 JSON in IlpSendResult.data) */
+interface PetInteractionResultData {
+    /** Current stat values */
+    stats: StatValues;
+    /** Current stage (0=Egg, 1=Baby, 2=Adult) */
+    stage: number;
+    /** Current evolution cycle (>= 0) */
+    cycle: number;
+    /** Unix timestamp of last interaction */
+    lastInteraction: number;
+    /** 64-char hex BLAKE3 hash of brain state */
+    brainHash: string;
+    /** Per-action-type cooldown timestamps */
+    cooldownTimestamps: number[];
+}
+/** Stat snapshot used in interaction result content */
+interface InteractionResultContent {
+    priorStats: StatValues;
+    decayedStats: StatValues;
+    finalStats: StatValues;
+    cycle: number;
+    stage: number;
+    tokenCost: number;
+}
+/** Proof status of a Kind 14919 event */
+type ProofStatus = 'optimistic' | 'proven';
+/** Parameters for building a Kind 30402 pet-for-sale classified listing */
+interface PetListingParams {
+    /** Blobbi identifier (non-empty string) — used as the 'd' tag */
+    blobbiId: string;
+    /** Asking price in USDC (> 0) */
+    askPriceUsdc: number;
+    /** 64-char hex lifecycleHash from on-chain PetZkApp state */
+    lifecycleHash: string;
+    /** Cumulative PET tokens spent (numeric string, >= "0") */
+    totalSpent: string;
+    /** Current stage: 0=Egg, 1=Baby, 2=Adult */
+    stage: number;
+    /** Current pet stats */
+    stats: StatValues;
+    /** Seller's Nostr pubkey (64-char hex) */
+    sellerPubkey: string;
+    /** Preferred relay URL for event relay routing */
+    relayUrl: string;
+    /** Listing expiry as unix timestamp */
+    expiresAt: number;
+}
+/** A parsed pet-for-sale listing (extends PetListingParams with event metadata) */
+interface PetListing extends PetListingParams {
+    /** Nostr event ID of the kind:30402 listing event */
+    eventId: string;
+    /** Unix timestamp when the listing event was created */
+    createdAt: number;
+}
+/** Filter options for filterPetListings() */
+interface PetListingFilterOptions {
+    /** Only include listings for pets at or above this stage */
+    minStage?: number;
+    /** Only include listings at or below this USDC price */
+    maxAskPriceUsdc?: number;
+    /** Only include listings where totalSpent >= this value (numeric string comparison) */
+    minTotalSpent?: string;
+    /** Only include listings from this seller pubkey */
+    sellerPubkey?: string;
+}
+/** Parameters for building a Kind 5900 pet purchase request (transfer-ownership) */
+interface PetPurchaseRequestParams {
+    /** Blobbi identifier being purchased */
+    blobbiId: string;
+    /** Nostr event ID of the kind:30402 listing being purchased */
+    listingEventId: string;
+    /** Buyer's Nostr pubkey (64-char hex) */
+    buyerPubkey: string;
+    /** Token cost for the purchase (>= 0) */
+    tokenCost: number;
+    /** Seller's Nostr pubkey — ILP payment routed to this pubkey (64-char hex) */
+    sellerPubkey: string;
+}
+/** Parsed data from a Kind 14919 pet interaction event */
+interface PetInteractionEventData {
+    /** Blobbi identifier from 'd' tag */
+    blobbiId: string;
+    /** Action type from 'action' tag */
+    actionType: number;
+    /** Item identifier from 'item' tag */
+    itemId: number;
+    /** Token cost from 'cost' tag */
+    tokenCost: number;
+    /** Evolution cycle from 'cycle' tag */
+    cycle: number;
+    /** Stage from 'stage' tag */
+    stage: number;
+    /** Brain hash from 'brain_hash' tag */
+    brainHash: string;
+    /** Proof status: 'optimistic' (no proof tag) or 'proven' (has proof + mina_tx tags) */
+    proofStatus: ProofStatus;
+    /** Parsed content JSON (stats before/after) */
+    content: InteractionResultContent | null;
+    /** Base64 proof data (only present when proven) */
+    proof?: string;
+    /** Mina transaction hash (only present when proven) */
+    minaTx?: string;
+}
+
+/**
+ * Pet DVM Provider Discovery
+ *
+ * Filters Kind 10035 service discovery events to find providers that
+ * support Pet DVM interactions (Kind 5900).
+ *
+ * @module pet/filterPetDvmProviders
+ */
+
+/**
+ * Minimal Nostr event shape needed for filtering.
+ * Using a local interface to avoid importing nostr-tools types.
+ */
+interface NostrEventLike$3 {
+    kind: number;
+    pubkey: string;
+    content: string;
+    tags: string[][];
+    id: string;
+    sig: string;
+    created_at: number;
+}
+/**
+ * Filter Kind 10035 service discovery events to find pet DVM providers.
+ *
+ * Accepts raw NostrEvent[] and internally parses content via parseServiceDiscovery.
+ * Filters events where skill.kinds includes 5900 (PET_INTERACTION_REQUEST_KIND).
+ * Returns provider metadata sorted by price ascending (cheapest first).
+ *
+ * Handles missing/malformed skill descriptors gracefully (returns empty array, no throw).
+ *
+ * @param events - Array of raw Nostr events (kind:10035)
+ * @returns Array of PetDvmProvider metadata, sorted by price ascending
+ */
+declare function filterPetDvmProviders(events: NostrEventLike$3[]): PetDvmProvider[];
+
+/**
+ * Pet Interaction Request Builder (Kind 5900)
+ *
+ * Builds unsigned Kind 5900 Nostr events for pet DVM interaction requests.
+ * Compatible with nostr-tools/pure finalizeEvent for signing.
+ *
+ * @module pet/buildPetInteractionRequest
+ */
+
+/**
+ * Build an unsigned Kind 5900 pet interaction request event.
+ *
+ * All tag values are stringified per Nostr protocol convention.
+ * The returned event is compatible with nostr-tools `finalizeEvent`.
+ *
+ * @param params - Typed interaction parameters
+ * @returns Unsigned Nostr event ready for signing
+ * @throws ValidationError for invalid input
+ */
+declare function buildPetInteractionRequest(params: PetInteractionRequestParams): UnsignedNostrEvent;
+
+/**
+ * Pet Interaction Result Parser (Kind 6900)
+ *
+ * Decodes base64-encoded JSON from IlpSendResult.data field.
+ * Uses browser-safe atob() -- NOT Node.js Buffer -- for ditto React SPA compatibility.
+ *
+ * @module pet/parsePetInteractionResult
+ */
+
+/**
+ * Parse base64-encoded JSON result data from a Kind 6900 DVM response.
+ *
+ * Uses atob() for browser compatibility (ditto React SPA).
+ * Returns null for malformed/missing data (no throw).
+ *
+ * Validates:
+ * - brainHash is 64-char hex
+ * - stats has all 5 fields
+ * - cycle >= 0
+ * - stage 0-2
+ *
+ * @param data - Base64-encoded JSON string from IlpSendResult.data
+ * @returns Parsed PetInteractionResultData or null if invalid
+ */
+declare function parsePetInteractionResult(data: string): PetInteractionResultData | null;
+
+/**
+ * Pet Interaction Event Parser (Kind 14919)
+ *
+ * Parses Kind 14919 optimistic/proven pet interaction events.
+ * Detects proof status from presence of 'proof' + 'mina_tx' tags.
+ *
+ * @module pet/parsePetInteractionEvent
+ */
+
+/**
+ * Minimal Nostr event shape needed for parsing.
+ */
+interface NostrEventLike$2 {
+    kind: number;
+    pubkey: string;
+    content: string;
+    tags: string[][];
+    id: string;
+    sig: string;
+    created_at: number;
+}
+/**
+ * Parse a Kind 14919 pet interaction event.
+ *
+ * Extracts all tag values and detects proof status:
+ * - 'optimistic': no 'proof' tag
+ * - 'proven': has 'proof' + 'mina_tx' tags
+ *
+ * Returns null if required tags are missing.
+ *
+ * @param event - A Nostr event (Kind 14919)
+ * @returns Parsed PetInteractionEventData or null if malformed
+ */
+declare function parsePetInteractionEvent(event: NostrEventLike$2): PetInteractionEventData | null;
+
+/**
+ * Pet Listing Event Builder (Kind 30402)
+ *
+ * Builds unsigned Kind 30402 (NIP-99 classified listing) Nostr events
+ * for pet-for-sale marketplace listings. Every listing includes a
+ * verified biography attachment (lifecycleHash + totalSpent) so buyers
+ * can verify the listing against on-chain PetZkApp state.
+ *
+ * Browser-compatible — no Node.js-only imports.
+ *
+ * @module pet/buildPetListingEvent
+ */
+
+/**
+ * Build an unsigned Kind 30402 pet-for-sale classified listing event.
+ *
+ * The listing uses the NIP-99 classified listing format with TOON-specific
+ * extension tags for verified biography (lifecycleHash, totalSpent).
+ * The `d` tag is set to `blobbiId` for stable parameterized replaceability —
+ * republishing with the same `d` tag updates the listing on relays.
+ *
+ * The returned event is compatible with nostr-tools `finalizeEvent`.
+ *
+ * @param params - Typed listing parameters
+ * @returns Unsigned Nostr event ready for signing and publishing
+ */
+declare function buildPetListingEvent(params: PetListingParams): UnsignedNostrEvent;
+
+/**
+ * Pet Listing Parser (Kind 30402)
+ *
+ * Parses Kind 30402 (NIP-99 classified listing) Nostr events into
+ * typed PetListing objects. Returns null for invalid or malformed events.
+ *
+ * Browser-compatible — no Node.js-only imports.
+ *
+ * @module pet/parsePetListing
+ */
+
+/** Minimal Nostr event shape required for parsing */
+interface NostrEventLike$1 {
+    id: string;
+    kind: number;
+    pubkey: string;
+    tags: string[][];
+    content: string;
+    created_at: number;
+}
+/**
+ * Parse a Kind 30402 pet classified listing event into a PetListing.
+ *
+ * Validation rules:
+ * - event.kind must be 30402
+ * - 'd' tag must be present and non-empty
+ * - 'price' tag must be present with a valid positive numeric first element
+ * - 'lifecycle_hash' tag must be a 64-char hex string
+ * - 'total_spent' tag must be a valid non-negative numeric string
+ * - 'stage' tag must be present
+ *
+ * Stats are parsed from content JSON; unparseable content falls back to DEFAULT_STATS.
+ *
+ * @param event - A Nostr event (expected Kind 30402)
+ * @returns Parsed PetListing or null if invalid
+ */
+declare function parsePetListing(event: NostrEventLike$1): PetListing | null;
+
+/**
+ * Pet Listing Discovery Filter
+ *
+ * Filters and sorts Kind 30402 pet marketplace listing events into
+ * typed PetListing objects. Handles expiry, stage, price, biography
+ * value, and seller filtering. Results sorted by totalSpent descending
+ * (highest biography value first) to surface the most battle-hardened pets.
+ *
+ * Browser-compatible — no Node.js-only imports.
+ *
+ * @module pet/filterPetListings
+ */
+
+/** Minimal Nostr event shape accepted by the filter */
+interface NostrEventLike {
+    id: string;
+    kind: number;
+    pubkey: string;
+    tags: string[][];
+    content: string;
+    created_at: number;
+}
+/**
+ * Filter and sort Kind 30402 pet marketplace listing events.
+ *
+ * Parsing is done via parsePetListing — invalid events are silently dropped.
+ * Expired listings (expiration tag < current unix time) are excluded.
+ * Options allow additional filtering by stage, price, biography value, and seller.
+ * Results are sorted by totalSpent descending (highest biography value first).
+ *
+ * @param events - Array of raw Nostr events to filter
+ * @param options - Optional filter criteria
+ * @returns Filtered and sorted array of PetListing objects
+ */
+declare function filterPetListings(events: NostrEventLike[], options?: PetListingFilterOptions): PetListing[];
+
+/**
+ * Pet Purchase Request Builder (Kind 5900, action type 9)
+ *
+ * Builds unsigned Kind 5900 Nostr events for pet transfer-ownership
+ * purchase requests. Action type 9 is a reserved slot in the pet DVM
+ * protocol — this event signals purchase intent and routes ILP payment
+ * to the seller. The actual Mina on-chain ownership transfer (PetZkApp
+ * .transferOperator) is handled by downstream stories.
+ *
+ * Browser-compatible — no Node.js-only imports.
+ *
+ * @module pet/buildPetPurchaseRequest
+ */
+
+/**
+ * Build an unsigned Kind 5900 pet purchase request event.
+ *
+ * Reuses the existing pet interaction event kind (5900) with action type 9
+ * (transfer-ownership). The `listing` tag references the kind:30402 listing
+ * event being purchased. The `p` tag routes ILP payment to the seller.
+ *
+ * The returned event is compatible with nostr-tools `finalizeEvent`.
+ *
+ * @param params - Typed purchase request parameters
+ * @returns Unsigned Nostr event ready for signing and publishing
+ */
+declare function buildPetPurchaseRequest(params: PetPurchaseRequestParams): UnsignedNostrEvent;
+
+/**
+ * Client-side helper for kind:5094 Arweave blob storage DVM requests.
+ *
+ * This composes the three steps a caller previously had to wire by hand:
+ *   1. Build the kind:5094 event via `buildBlobStorageRequest()` (@toon-protocol/core).
+ *   2. Publish it to the DVM destination over ILP via `ToonClient.publishEvent()`
+ *      (reusing the existing claim / channel plumbing).
+ *   3. Decode the FULFILL `data` field into the Arweave transaction ID.
+ *
+ * ## FULFILL data contract
+ *
+ * For a successful single-packet (non-chunked) blob upload, the DVM provider
+ * returns the Arweave transaction ID as a **UTF-8 string, base64-encoded** in
+ * the ILP FULFILL `data` field (the connector validates that FULFILL data is
+ * base64). An Arweave tx ID is a 43-character base64url string (32 raw bytes).
+ *
+ * So the decode is:
+ *   `txId = utf8(base64decode(result.data))`
+ *
+ * See `packages/sdk/src/arweave/arweave-dvm-handler.ts` for the server side and
+ * `packages/client/tests/e2e/docker-arweave-dvm-e2e.test.ts` for the reference
+ * end-to-end flow this helper mirrors.
+ *
+ * Chunked uploads (multi-packet, via `uploadId` / `chunkIndex` / `totalChunks`
+ * params) are intentionally out of scope for this single-packet helper — the
+ * provider returns `ack:<n>` for intermediate chunks and the tx ID only on the
+ * final chunk. Callers needing chunking should drive `publishEvent()` directly
+ * (see the chunked case in the reference E2E test). Tracked as a follow-up.
+ */
+
+/**
+ * Parameters for {@link requestBlobStorage}.
+ */
+interface RequestBlobStorageParams {
+    /** The raw blob data to store on Arweave. */
+    blobData: Uint8Array;
+    /**
+     * MIME type of the blob. Defaults to `'application/octet-stream'`
+     * (matching `buildBlobStorageRequest`).
+     */
+    contentType?: string;
+    /**
+     * Bid amount in USDC micro-units, as a string (declared in the event's
+     * `bid` tag). Defaults to the stringified `ilpAmount` when omitted.
+     *
+     * At least one of `bid` / `ilpAmount` should be provided so the declared
+     * bid and the paid ILP amount agree.
+     */
+    bid?: string;
+    /**
+     * ILP destination address of the DVM that performs the upload
+     * (e.g. `'g.toon.peer1'`). Falls back to the client's configured
+     * `destinationAddress` when omitted.
+     */
+    destination?: string;
+    /**
+     * Pre-signed balance proof claim for this packet. When omitted, the
+     * client's channel manager auto-opens a channel and auto-signs a claim
+     * (same lazy-channel behavior as `publishEvent`).
+     */
+    claim?: SignedBalanceProof;
+    /**
+     * Explicit ILP payment amount (bigint micro-units). When omitted,
+     * `publishEvent` computes it from the encoded event size. When `bid`
+     * is omitted, this value is stringified to populate the event's bid tag.
+     */
+    ilpAmount?: bigint;
+}
+/**
+ * Typed result of {@link requestBlobStorage}.
+ */
+interface RequestBlobStorageResult {
+    /** Whether the upload succeeded and a tx ID was decoded. */
+    success: boolean;
+    /** The Arweave transaction ID (43-char base64url) when `success` is true. */
+    txId?: string;
+    /** The id of the kind:5094 event that was published. */
+    eventId?: string;
+    /** Error message when `success` is false. */
+    error?: string;
+}
+/**
+ * Requests permanent Arweave blob storage from a DVM in a single ILP packet.
+ *
+ * Mirrors the single-packet flow in
+ * `packages/client/tests/e2e/docker-arweave-dvm-e2e.test.ts`: builds a signed
+ * kind:5094 event, publishes it through the supplied {@link ToonClient}
+ * (reusing its claim/channel plumbing), and decodes the FULFILL `data` field
+ * into an Arweave transaction ID.
+ *
+ * @param client - A started `ToonClient` (call `client.start()` first).
+ * @param secretKey - The Nostr secret key used to sign the kind:5094 event.
+ * @param params - Blob, content type, bid, destination, and payment options.
+ * @returns `{ success, txId?, eventId?, error? }`.
+ */
+declare function requestBlobStorage(client: ToonClient, secretKey: Uint8Array, params: RequestBlobStorageParams): Promise<RequestBlobStorageResult>;
 
 /**
  * Full multi-chain identity derived from a single BIP-39 mnemonic.
@@ -1384,16 +2668,38 @@ declare function generateMnemonic(): string;
  * Validate a BIP-39 mnemonic phrase.
  */
 declare function validateMnemonic(mnemonic: string): boolean;
+/**
+ * Synchronously derive ONLY the Nostr secp256k1 key (NIP-06) from a mnemonic.
+ *
+ * The EVM key shares this same secp256k1 key. Solana (Ed25519) and Mina
+ * (Pallas) require async dynamic imports — use {@link deriveFullIdentity} for
+ * those. This sync subset exists so `ToonClient`'s synchronous constructor can
+ * resolve the Nostr/EVM identity from a `mnemonic` config field without an
+ * async factory; the client derives Solana/Mina lazily in `start()`.
+ */
+declare function deriveNostrKeyFromMnemonic(mnemonic: string, accountIndex?: number): {
+    secretKey: Uint8Array;
+    pubkey: string;
+};
 /**
  * Derive a full multi-chain ToonIdentity from a BIP-39 mnemonic.
  *
+ * All four chains vary by `accountIndex` (default 0), matching the SDK's
+ * {@link https://www.npmjs.com/package/@toon-protocol/sdk `fromMnemonicFull`}
+ * path-per-index scheme so a non-zero index produces the SAME addresses as
+ * `fromMnemonicFull(mnemonic, { accountIndex })`. Index 0 is unchanged from the
+ * historical fixed paths (back-compat).
+ *
  * Chains derived:
- * - Nostr (secp256k1): m/44'/1237'/0'/0/0
+ * - Nostr (secp256k1): m/44'/1237'/0'/0/{accountIndex}
  * - EVM (secp256k1): same key as Nostr
- * - Solana (Ed25519): m/44'/501'/0'/0' (SLIP-0010)
- * - Mina (Pallas): m/44'/12586'/0'/0/0
+ * - Solana (Ed25519): m/44'/501'/{accountIndex}'/0' (SLIP-0010)
+ * - Mina (Pallas): m/44'/12586'/{accountIndex}'/0/0
+ *
+ * @param mnemonic - A valid BIP-39 mnemonic (12 or 24 words).
+ * @param accountIndex - BIP-44 account index (default 0).
  */
-declare function deriveFullIdentity(mnemonic: string): Promise<ToonIdentity>;
+declare function deriveFullIdentity(mnemonic: string, accountIndex?: number): Promise<ToonIdentity>;
 /**
  * Derive a partial identity from an nsec (Nostr-only private key).
  * Nostr + EVM share the same secp256k1 key.
@@ -1441,4 +2747,77 @@ declare function parseBackupPayload(content: string): VaultData;
  */
 declare function isPrfSupported(): boolean;
 
-export { type BackupPayload, type BalanceProofParams, BtpRuntimeClient, type BtpRuntimeClientConfig, ChannelManager, ConnectorError, type EVMClaimMessage, EvmSigner, HttpConnectorAdmin, type HttpConnectorAdminConfig, HttpRuntimeClient, type HttpRuntimeClientConfig, KeyManager, type KeyManagerConfig, NetworkError, OnChainChannelClient, type OnChainChannelClientConfig, type PasskeyInfo, type PublishEventResult, type RetryOptions, type SignedBalanceProof, ToonClient, type ToonClientConfig, ToonClientError, type ToonIdentity, type ToonSigners, type ToonStartResult, ValidationError, type VaultData, applyDefaults, buildBackupEvent, buildBackupFilter, buildSettlementInfo, deriveFromNsec, deriveFullIdentity, generateMnemonic, generateRandomIdentity, isPrfSupported, parseBackupPayload, validateConfig, validateMnemonic, withRetry };
+/**
+ * Node-only encrypted mnemonic keystore for @toon-protocol/client.
+ *
+ * Mirrors the Townhouse node wallet crypto (`packages/townhouse/src/wallet/
+ * crypto.ts`): a BIP-39 mnemonic is encrypted at rest with scrypt (KDF) +
+ * AES-256-GCM (authenticated encryption), serialized as JSON, and written to
+ * disk with mode 0o600. Decryption requires the operator password; a wrong
+ * password fails the GCM auth-tag verification and throws.
+ *
+ * This is the Node-side counterpart to the browser Passkey/IndexedDB
+ * `KeyManager`/`KeyVault` flow — it does NOT touch those. It is guarded against
+ * browser bundling: every entry point throws if `node:crypto`/`node:fs` are not
+ * available (e.g. when accidentally imported in a browser bundle).
+ *
+ * @module
+ */
+/**
+ * Encrypted keystore file format (JSON, all binary fields base64-encoded).
+ * Wire-compatible with Townhouse's `EncryptedWallet`.
+ */
+interface EncryptedKeystore {
+    /** scrypt salt (base64). */
+    salt: string;
+    /** AES-GCM initialization vector (base64). */
+    iv: string;
+    /** AES-256-GCM ciphertext (base64). */
+    ciphertext: string;
+    /** AES-GCM authentication tag (base64). */
+    tag: string;
+    /** Envelope version for forward-compat (currently 1). */
+    version?: number;
+}
+/**
+ * Encrypt a mnemonic with a password using scrypt + AES-256-GCM.
+ * Returns the JSON-serializable encrypted envelope (does NOT write to disk).
+ */
+declare function encryptMnemonic(mnemonic: string, password: string): EncryptedKeystore;
+/**
+ * Decrypt an encrypted keystore envelope with a password.
+ * Throws on a wrong password (GCM auth-tag verification failure) or corruption.
+ */
+declare function decryptMnemonic(encrypted: EncryptedKeystore, password: string): string;
+/**
+ * Generate a fresh 12-word BIP-39 mnemonic, encrypt it under `password`, and
+ * write the encrypted keystore to `path` with mode 0o600.
+ *
+ * Returns the mnemonic (for one-time display/backup) alongside the encrypted
+ * envelope. The caller is responsible for displaying the mnemonic securely and
+ * NOT persisting it in plaintext.
+ */
+declare function generateKeystore(path: string, password: string): {
+    mnemonic: string;
+    keystore: EncryptedKeystore;
+};
+/**
+ * Import an existing BIP-39 mnemonic (12 or 24 words), encrypt it under
+ * `password`, and write the encrypted keystore to `path` with mode 0o600.
+ *
+ * Throws if the mnemonic is not a valid BIP-39 phrase (wrong checksum/word
+ * count) before any file is written.
+ */
+declare function importKeystore(path: string, mnemonic: string, password: string): EncryptedKeystore;
+/**
+ * Load and decrypt a keystore file at `path` with `password`, returning the
+ * plaintext mnemonic. Throws on a wrong password or corruption.
+ */
+declare function loadKeystore(path: string, password: string): string;
+/**
+ * Serialize and write an encrypted keystore to disk with mode 0o600
+ * (owner read/write only), mirroring the Townhouse wallet file permissions.
+ */
+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 EVMClaimMessage, type EncryptedKeystore, EvmSigner, HS_HOSTNAME_MAX_LENGTH, HS_HOSTNAME_REGEX, HttpConnectorAdmin, type HttpConnectorAdminConfig, HttpRuntimeClient, type HttpRuntimeClientConfig, 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 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, importKeystore, isPrfSupported, isRoutableHsHostname, loadKeystore, parseBackupPayload, parsePetInteractionEvent, parsePetInteractionResult, parsePetListing, readMinaDepositTotal, requestBlobStorage, selectAnonAsset, startManagedAnonProxy, validateConfig, validateMnemonic, withRetry, writeKeystoreFile };