@toon-protocol/client 0.14.3 → 0.14.5

package/README.md

@@ -2,17 +2,17 @@
 
 The **client library** for TOON Protocol — _pay-to-write Nostr over Interledger (ILP)_. Use it to **pay for and publish** writes to a network of service nodes. **Reads are free; writes cost a signed EIP-712 payment-channel claim** against an on-chain deposit.
 
-> **`client` vs `townhouse`.** This package (`@toon-protocol/client`) is what an _app or end user_ uses to **pay** and publish. It does **not** run any relay or node. The nodes are operated separately by **`@toon-protocol/townhouse`** (the operator product, which runs an _apex_ connector plus `town` / `mill` / `dvm` children). Don't confuse the **client** (pays) with **townhouse** (operates), or **`town`** (a single Nostr-relay node) with **townhouse** (the whole operator stack).
+> **`client` vs `relay`.** This package (`@toon-protocol/client`) is what an _app or end user_ uses to **pay** and publish. It does **not** run any relay or node. The nodes are operated separately by **`@toon-protocol/relay`** (the operator product, which runs an _apex_ connector plus `town` / `swap` / `store` children). Don't confuse the **client** (pays) with **relay** (operates), or **`town`** (a single Nostr-relay node) with **relay** (the whole operator stack).
 
 ## Which call pays which node
 
-Every write is an ILP packet carrying a signed payment-channel claim. The client reaches all node types **through a townhouse apex** (`g.townhouse`): the apex validates the claim, takes its fee, and forwards the packet to the destination node, which returns FULFILL (accepted) or REJECT. The method you call determines which node type you pay:
+Every write is an ILP packet carrying a signed payment-channel claim. The client reaches all node types **through a relay apex** (`g.proxy`): the apex validates the claim, takes its fee, and forwards the packet to the destination node, which returns FULFILL (accepted) or REJECT. The method you call determines which node type you pay:
 
 | Client call                       | Node type | What it does                                                                                                                                              |
 | --------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `client.publishEvent(event)`      | **town**  | Publish a Nostr event (e.g. `kind:1`) to the relay.                                                                                                       |
-| `requestBlobStorage(client, …)`   | **dvm**   | NIP-90 compute/storage. Builds and publishes a `kind:5094` event that uploads a blob to Arweave — the job request **is** the payment — and decodes the Arweave tx ID from the FULFILL response. |
-| `client.sendSwapPacket(…)`        | **mill**  | Multi-chain token swap (low-level). Most callers use the higher-level `streamSwap()` from `@toon-protocol/sdk`, which is built on `sendSwapPacket`.       |
+| `requestBlobStorage(client, …)`   | **store** | NIP-90 compute/storage. Builds and publishes a `kind:5094` event that uploads a blob to Arweave — the job request **is** the payment — and decodes the Arweave tx ID from the FULFILL response. |
+| `client.sendSwapPacket(…)`        | **swap**  | Multi-chain token swap (low-level). Most callers use the higher-level `streamSwap()` from `@toon-protocol/sdk`, which is built on `sendSwapPacket`.       |
 
 ## What It Does
 
@@ -21,7 +21,7 @@ This client handles:
 - **ILP Micropayments**: Pay to publish Nostr events (reads are free)
 - **Payment Channels**: Automatic on-chain channel creation with off-chain settlement via signed balance proofs
 - **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-Chain Settlement**: Sign payment-channel claims on EVM (EIP-712), Solana (Ed25519), and Mina (Pallas) from one mnemonic. A relay 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
 - **Network Bootstrap**: Automatically discover and register with ILP peers via NIP-02 follow lists
 - **TOON Encoding**: Native binary format for agent-friendly event encoding
@@ -41,7 +41,7 @@ pnpm add mina-signer
 
 - **Node.js ≥ 20** — these packages are ESM.
 - **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-protocol/relay`](https://www.npmjs.com/package/@toon-protocol/relay) apex (or any
   TOON connector) and pay it. From its operator you need:
   - 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
@@ -167,13 +167,13 @@ console.log('Mina:  ', client.getMinaAddress());   // base58, after start() (nee
 - **Mina is optional**: it requires the `mina-signer` peer dependency (see Installation). Without it, the client still works for Nostr/EVM/Solana and `getMinaAddress()` returns `undefined`.
 - **Security**: JavaScript strings can't be zeroed from memory, so a `mnemonic` may linger in the heap. For high-security contexts, derive keys yourself (e.g. via `KeyManager`) and pass a pre-derived `secretKey`.
 - **Per-chain claim formats.** Each publish carries a balance-proof claim in the format that destination chain's connector verifier expects — EVM via EIP-712, Solana as a raw Ed25519 message over the on-chain payment-channel message (`channel_pda ‖ nonce ‖ transferredAmount`), Mina as a Pallas-Schnorr claim over a Poseidon `balanceCommitment`. `ToonClient` selects the right signer for the negotiated channel automatically; you do not pick the format. Canonical layouts live in `@toon-protocol/core` (`packages/core/src/settlement/`) so client signers and connector verifiers cannot drift.
-- **On-chain redemption is automatic, and driven by the apex — not the client.** You sign off-chain claims; the Townhouse apex validates them, fulfills, and (once a per-channel threshold is crossed) submits the on-chain redemption itself. EVM and Solana credit the recipient on-chain (Solana at channel close, `SETTLE_CHANNEL`). On **Mina** each paid publish redeems on-chain (`claimFromChannel`, the apex co-signs the counterparty signature; the zkApp nonce and balance commitment advance), and **the recipient's tokens are credited at channel close** via the Story 34.4 fund-custody zkApp (`@toon-protocol/connector` ≥3.10.0): the deposit is escrowed on the zkApp account and `settle()` drains it to the participants (recipient + depositor refund). Verified against `@toon-protocol/connector` 3.10.0.
+- **On-chain redemption is automatic, and driven by the apex — not the client.** You sign off-chain claims; the relay apex validates them, fulfills, and (once a per-channel threshold is crossed) submits the on-chain redemption itself. EVM and Solana credit the recipient on-chain (Solana at channel close, `SETTLE_CHANNEL`). On **Mina** each paid publish redeems on-chain (`claimFromChannel`, the apex co-signs the counterparty signature; the zkApp nonce and balance commitment advance), and **the recipient's tokens are credited at channel close** via the Story 34.4 fund-custody zkApp (`@toon-protocol/connector` ≥3.10.0): the deposit is escrowed on the zkApp account and `settle()` drains it to the participants (recipient + depositor refund). Verified against `@toon-protocol/connector` 3.10.0.
 
 ---
 
 ## Uploading a blob to a DVM (Arweave storage)
 
-To store a blob permanently on Arweave, pay a **dvm** node with a `kind:5094` NIP-90 request. The `requestBlobStorage` helper builds the signed event, publishes it through your `ToonClient` (reusing its claim/channel plumbing), and decodes the Arweave transaction ID from the FULFILL response:
+To store a blob permanently on Arweave, pay a **store** node with a `kind:5094` NIP-90 request. The `requestBlobStorage` helper builds the signed event, publishes it through your `ToonClient` (reusing its claim/channel plumbing), and decodes the Arweave transaction ID from the FULFILL response:
 
 ```typescript
 import { ToonClient, requestBlobStorage } from '@toon-protocol/client';
@@ -183,7 +183,7 @@ const result = await requestBlobStorage(client, secretKey, {
   blobData: new Uint8Array([1, 2, 3, 4]),
   contentType: 'application/octet-stream',
   ilpAmount: 50_000n, // USDC micro-units; also used as the event's `bid` if `bid` is omitted
-  destination: 'g.toon.peer1', // the DVM's ILP address (defaults to the client's destinationAddress)
+  destination: 'g.toon.peer1', // the store node's ILP address (defaults to the client's destinationAddress)
 });
 
 if (result.success) {
@@ -239,7 +239,7 @@ await client.publishEvent(event, { claim });
 2. **Channel Creation**: Opens an on-chain payment channel on the negotiated chain — using your derived EVM address (EVM), the Ed25519 channel PDA (Solana), or the deployed zkApp account (Mina) when the matching `solanaChannel` / `minaChannel` config is provided
 3. **Off-chain Payments**: Signed balance proofs (chain-appropriate format) settle payments off-chain
 4. **Auto-tracking**: ChannelManager automatically tracks channels and increments nonces
-5. **On-chain redemption**: A Townhouse apex auto-redeems claims on-chain once a per-channel threshold is crossed (see [Multi-Chain Settlement](#identity--multi-chain-settlement) for the EVM/Solana/Mina specifics and the Mina credit-at-close deferral)
+5. **On-chain redemption**: A relay apex auto-redeems claims on-chain once a per-channel threshold is crossed (see [Multi-Chain Settlement](#identity--multi-chain-settlement) for the EVM/Solana/Mina specifics and the Mina credit-at-close deferral)
 
 ### Using a Separate EVM Key (Advanced)
 
@@ -304,10 +304,9 @@ See [examples/client-example/](../../examples/client-example/) for standalone cl
 ## Related Packages
 
 - **[@toon-protocol/core](../core/)** — Core protocol (peer discovery, bootstrap, `buildBlobStorageRequest`)
-- **[@toon-protocol/relay](../relay/)** — Nostr relay with ILP payment gating (`encodeEventToToon` / `decodeEventFromToon`)
-- **[@toon-protocol/sdk](../sdk/)** — Higher-level helpers including `streamSwap()` for multi-chain swaps via a **mill**
+- **[@toon-protocol/relay](../relay/)** — Operator product running the apex connector plus town/swap/store nodes; also exports `encodeEventToToon` / `decodeEventFromToon` for event encoding
+- **[@toon-protocol/sdk](../sdk/)** — Higher-level helpers including `streamSwap()` for multi-chain swaps via a **swap**
 - **[@toon-protocol/bls](../bls/)** — Business Logic Server (pricing, validation, storage)
-- **[@toon-protocol/townhouse](../townhouse/)** — The operator product that runs the apex + town/mill/dvm nodes you pay
 
 ---
 

package/dist/index.d.ts

@@ -5,6 +5,17 @@ import { NostrEvent, EventTemplate } from 'nostr-tools/pure';
 import { PrivateKeyAccount } from 'viem/accounts';
 export { A2uiDecision, ConsentDecision, ConsentRequest, DispatchGuardInfo, DispatchInput, GenerateContext, GeneratedRenderer, GenerativeDecision, GenerativeFallbackOptions, GenerativeFallbackRenderer, GenerativeFallbackResult, GuardedDispatchInput, IntentClassification, KindRegistry, MIME_A2UI, MIME_MCP_APP, McpUiDecision, NativeDecision, PublishBackOptions, RenderBranch, RenderDecision, RenderTrust, RendererGenerator, RendererPin, RendererPinStore, RendererPublisher, RendererSigner, ResolvedCoordinate, SwapApproval, SwapDecision, SwapRejection, SwapRejectionReason, UiResource, VerifyRendererInput, WidgetIntent, buildConsentRequest, buildRendererEventTemplate, classifyIntent, deterministicGenerator, extractUiResource, guardedRenderDispatch, isTrustDowngrade, publishBackCoordinate, renderDeterministicHtml, renderDispatch, resolveRendererMime, resolveUiCoordinate, resolveUiRenderer, verifyRendererTrust } from './render/index.js';
 
+/** One on-chain wallet token balance. `amount` is base-unit integer, decimal. */
+interface WalletBalance {
+    chain: 'evm' | 'solana' | 'mina';
+    address: string;
+    amount: string;
+    /** Token symbol, when resolved (e.g. `'USDC'`, `'MINA'`). */
+    asset?: string;
+    /** Token decimals, when resolved. */
+    assetScale?: number;
+}
+
 /**
  * Solana payment-channel parameters supplied via `ToonClientConfig.solanaChannel`.
  *
@@ -172,7 +183,7 @@ interface ToonClientConfig {
      * 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;
+     * This is the client-side mirror of the relay node's `network` selector;
      * both resolve the SAME deployed contracts.
      *
      * Precedence: any explicit per-chain field (`supportedChains`,
@@ -1013,7 +1024,7 @@ declare class ToonClient {
     }): Promise<RequestBlobStorageResult>;
     /**
      * Per-chain settlement readiness for the configured `network` tier, mirroring
-     * the townhouse node's status. Returns `undefined` when no named `network` is
+     * the relay 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;
@@ -1099,7 +1110,7 @@ declare class ToonClient {
      */
     h402Fetch(url: string, opts?: H402FetchOptions): Promise<Response>;
     /**
-     * Sends a raw swap ILP packet (Story 12.5) to a Mill peer with an attached
+     * Sends a raw swap ILP packet (Story 12.5) to a swap 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.
@@ -1210,6 +1221,20 @@ declare class ToonClient {
      * Gets the cumulative transferred amount for a tracked channel.
      */
     getChannelCumulativeAmount(channelId: string): bigint;
+    /**
+     * Gets the on-chain deposit total (locked collateral) for a tracked channel.
+     * The available (spendable) balance is this minus the cumulative spent amount.
+     */
+    getChannelDepositTotal(channelId: string): bigint;
+    /**
+     * Read the on-chain settlement-token balance of this client's OWN wallet on
+     * each configured chain (EVM token, Solana SPL, native MINA). A free read — no
+     * signing, no payment. Best-effort per chain: a chain whose config is absent or
+     * whose RPC read fails is omitted rather than failing the whole result, so the
+     * wallet view degrades gracefully. Available after `start()` (Solana/Mina keys
+     * are derived there).
+     */
+    getBalances(): Promise<WalletBalance[]>;
     /**
      * Resolves an ILP destination address to a peer ID.
      * Convention: destination "g.toon.peer1" → peerId "peer1" (last segment).
@@ -1864,7 +1889,7 @@ declare class EvmSigner {
  * 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
+ * NOTE: this is a DIFFERENT message from the swap peer ↔ 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`
@@ -1934,7 +1959,7 @@ interface MinaSignerOptions {
  * 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
+ * NOTE: this is a DIFFERENT message + format from the swap peer ↔ 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
@@ -2274,6 +2299,12 @@ declare class ChannelManager {
      * Gets the cumulative transferred amount for a tracked channel.
      */
     getCumulativeAmount(channelId: string): bigint;
+    /**
+     * Gets the on-chain deposit total (collateral locked at open / via deposits)
+     * for a tracked channel, or `0n` when none was captured. The available
+     * (spendable) balance is `depositTotal - cumulativeAmount`.
+     */
+    getDepositTotal(channelId: string): bigint;
     /**
      * Gets all tracked channel IDs.
      */
@@ -2406,7 +2437,7 @@ declare function buildStoreWriteEnvelope(event: NostrEvent, requestTarget?: stri
  * dependency-free helper that returns the status code + raw body string, which
  * is all the publish/upload paths need.
  *
- * DEFENSIVE: not every FULFILL is HTTP-enveloped (e.g. Mill-swap raw-TOON
+ * DEFENSIVE: not every FULFILL is HTTP-enveloped (e.g. swap peer raw-TOON
  * FULFILLs go through `sendSwapPacket`, not these paths). If the decoded data
  * does not begin with an `HTTP/<v>` status line, `isHttp` is `false` and the
  * caller should fall back to its prior (non-HTTP) interpretation rather than
@@ -2467,7 +2498,7 @@ interface ClientSettlementInfo {
 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
+ * mirroring the relay node's status. Returns `undefined` when `network` is
  * unset or `'custom'` (no preset tier to report on).
  */
 declare function getNetworkStatus(config: ToonClientConfig): NetworkFamilyStatus | undefined;
@@ -3286,7 +3317,7 @@ declare function isPrfSupported(): boolean;
 /**
  * Node-only encrypted mnemonic keystore for @toon-protocol/client.
  *
- * Mirrors the Townhouse node wallet crypto (`packages/townhouse/src/wallet/
+ * Mirrors the relay node wallet crypto (`packages/relay/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
@@ -3301,7 +3332,7 @@ declare function isPrfSupported(): boolean;
  */
 /**
  * Encrypted keystore file format (JSON, all binary fields base64-encoded).
- * Wire-compatible with Townhouse's `EncryptedWallet`.
+ * Wire-compatible with the relay node's `EncryptedWallet`.
  */
 interface EncryptedKeystore {
     /** scrypt salt (base64). */
@@ -3352,7 +3383,7 @@ declare function importKeystore(path: string, mnemonic: string, password: string
 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.
+ * (owner read/write only), mirroring the relay node wallet file permissions.
  */
 declare function writeKeystoreFile(path: string, keystore: EncryptedKeystore): void;
 

package/dist/index.js

@@ -1640,17 +1640,17 @@ function readDiscoveredIlpPeer(peer) {
 }
 function selectIlpTransport(peer, options = {}) {
   const needsDuplex = options.needsDuplex ?? false;
-  const http2 = peer.httpEndpoint?.trim() || void 0;
+  const http3 = peer.httpEndpoint?.trim() || void 0;
   const btp = peer.btpEndpoint?.trim() || void 0;
   const canUpgrade = peer.supportsUpgrade === true;
   if (needsDuplex) {
     if (btp) return { kind: "btp", btpEndpoint: btp };
-    if (http2 && canUpgrade) return { kind: "http-upgradable", httpEndpoint: http2 };
+    if (http3 && canUpgrade) return { kind: "http-upgradable", httpEndpoint: http3 };
     throw new Error(
       "Duplex transport required but peer exposes neither a btpEndpoint nor an upgradable httpEndpoint"
     );
   }
-  if (http2) return { kind: "http", httpEndpoint: http2, canUpgrade };
+  if (http3) return { kind: "http", httpEndpoint: http3, canUpgrade };
   if (btp) return { kind: "btp", btpEndpoint: btp };
   throw new Error("Peer exposes neither an httpEndpoint nor a btpEndpoint");
 }
@@ -3489,6 +3489,18 @@ var ChannelManager = class {
     }
     return tracking.cumulativeAmount;
   }
+  /**
+   * Gets the on-chain deposit total (collateral locked at open / via deposits)
+   * for a tracked channel, or `0n` when none was captured. The available
+   * (spendable) balance is `depositTotal - cumulativeAmount`.
+   */
+  getDepositTotal(channelId) {
+    const tracking = this.channels.get(channelId);
+    if (!tracking) {
+      throw new Error(`Channel "${channelId}" is not being tracked.`);
+    }
+    return tracking.depositTotal ?? 0n;
+  }
   /**
    * Gets all tracked channel IDs.
    */
@@ -3547,6 +3559,91 @@ var JsonFileChannelStore = class {
   }
 };
 
+// src/balance/WalletBalanceReader.ts
+import { createPublicClient as createPublicClient2, http as http2, defineChain as defineChain2 } from "viem";
+var ERC20_READ_ABI = [
+  { name: "balanceOf", type: "function", stateMutability: "view", inputs: [{ name: "account", type: "address" }], outputs: [{ type: "uint256" }] },
+  { name: "decimals", type: "function", stateMutability: "view", inputs: [], outputs: [{ type: "uint8" }] },
+  { name: "symbol", type: "function", stateMutability: "view", inputs: [], outputs: [{ type: "string" }] }
+];
+function parseEvmChainId(chainKey) {
+  const parts = chainKey.split(":");
+  const idStr = parts.length >= 3 ? parts[2] : parts[1];
+  const id = Number.parseInt(idStr ?? "", 10);
+  if (!Number.isFinite(id)) throw new Error(`Invalid EVM chain key "${chainKey}".`);
+  return id;
+}
+async function readEvmTokenBalance(opts) {
+  const chainId = parseEvmChainId(opts.chainKey);
+  const client = createPublicClient2({
+    transport: http2(opts.rpcUrl),
+    chain: defineChain2({
+      id: chainId,
+      name: opts.chainKey,
+      nativeCurrency: { name: "ETH", symbol: "ETH", decimals: 18 },
+      rpcUrls: { default: { http: [opts.rpcUrl] } }
+    })
+  });
+  const token = opts.tokenAddress;
+  const owner = opts.owner;
+  const [amount, decimals, symbol] = await Promise.all([
+    client.readContract({ address: token, abi: ERC20_READ_ABI, functionName: "balanceOf", args: [owner] }),
+    client.readContract({ address: token, abi: ERC20_READ_ABI, functionName: "decimals" }).catch(() => void 0),
+    client.readContract({ address: token, abi: ERC20_READ_ABI, functionName: "symbol" }).catch(() => void 0)
+  ]);
+  const out = { chain: "evm", address: opts.owner, amount: amount.toString() };
+  if (typeof symbol === "string" && symbol) out.asset = symbol;
+  if (decimals !== void 0) out.assetScale = Number(decimals);
+  return out;
+}
+async function readSolanaTokenBalance(opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const res = await fetchImpl(opts.rpcUrl, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "getTokenAccountsByOwner",
+      params: [opts.owner, { mint: opts.mint }, { encoding: "jsonParsed", commitment: "confirmed" }]
+    })
+  });
+  if (!res.ok) throw new Error(`Solana RPC request failed: HTTP ${res.status}`);
+  const json = await res.json();
+  if (json.error) throw new Error(`Solana RPC error: ${json.error.message ?? "unknown"}`);
+  let amount = 0n;
+  let decimals;
+  for (const acc of json.result?.value ?? []) {
+    const ta = acc.account?.data?.parsed?.info?.tokenAmount;
+    if (ta?.amount) amount += BigInt(ta.amount);
+    if (ta?.decimals !== void 0) decimals = ta.decimals;
+  }
+  const out = { chain: "solana", address: opts.owner, amount: amount.toString() };
+  if (decimals !== void 0) out.assetScale = decimals;
+  return out;
+}
+async function readMinaBalance(opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const query = "query($pk:String!){account(publicKey:$pk){balance{total}}}";
+  const res = await fetchImpl(opts.graphqlUrl, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ query, variables: { pk: opts.owner } })
+  });
+  if (!res.ok) throw new Error(`Mina GraphQL request failed: HTTP ${res.status}`);
+  const json = await res.json();
+  if (json.errors && json.errors.length > 0) {
+    throw new Error(`Mina GraphQL error: ${json.errors[0]?.message ?? "unknown"}`);
+  }
+  return {
+    chain: "mina",
+    address: opts.owner,
+    amount: String(json.data?.account?.balance?.total ?? "0"),
+    asset: "MINA",
+    assetScale: 9
+  };
+}
+
 // src/blob-storage.ts
 import { buildBlobStorageRequest } from "@toon-protocol/core";
 var ARWEAVE_TX_ID_REGEX = /^[A-Za-z0-9_-]{43}$/;
@@ -3617,8 +3714,8 @@ async function requestBlobStorage(client, secretKey, params) {
   };
 }
 function extractArweaveTxId(base64Data) {
-  const http2 = parseFulfillHttp(base64Data);
-  if (!http2.isHttp) {
+  const http3 = parseFulfillHttp(base64Data);
+  if (!http3.isHttp) {
     const legacy = decodeUtf8(fromBase64(base64Data));
     if (!ARWEAVE_TX_ID_REGEX.test(legacy)) {
       throw new Error(
@@ -3627,18 +3724,18 @@ function extractArweaveTxId(base64Data) {
     }
     return legacy;
   }
-  if (http2.status < 200 || http2.status >= 300) {
-    const detail = http2.body ? ` - ${http2.body}` : "";
+  if (http3.status < 200 || http3.status >= 300) {
+    const detail = http3.body ? ` - ${http3.body}` : "";
     throw new Error(
-      `Blob upload failed: DVM returned HTTP ${http2.status} ${http2.statusText}`.trimEnd() + detail
+      `Blob upload failed: DVM returned HTTP ${http3.status} ${http3.statusText}`.trimEnd() + detail
     );
   }
   let parsed;
   try {
-    parsed = JSON.parse(http2.body);
+    parsed = JSON.parse(http3.body);
   } catch {
     throw new Error(
-      `Blob upload response body was not valid JSON: "${http2.body}"`
+      `Blob upload response body was not valid JSON: "${http3.body}"`
     );
   }
   const body = parsed;
@@ -3656,7 +3753,7 @@ function extractArweaveTxId(base64Data) {
     }
   }
   throw new Error(
-    `Blob upload response did not contain a valid Arweave tx ID: "${http2.body}"`
+    `Blob upload response did not contain a valid Arweave tx ID: "${http3.body}"`
   );
 }
 
@@ -3987,7 +4084,7 @@ var ToonClient = class {
   }
   /**
    * Per-chain settlement readiness for the configured `network` tier, mirroring
-   * the townhouse node's status. Returns `undefined` when no named `network` is
+   * the relay node's status. Returns `undefined` when no named `network` is
    * set (or `network: 'custom'`), since there is no preset tier to report on.
    */
   getNetworkStatus() {
@@ -4305,7 +4402,7 @@ var ToonClient = class {
     return client.fetch(url, opts);
   }
   /**
-   * Sends a raw swap ILP packet (Story 12.5) to a Mill peer with an attached
+   * Sends a raw swap ILP packet (Story 12.5) to a swap 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.
@@ -4533,6 +4630,59 @@ var ToonClient = class {
     if (!this.channelManager) throw new Error("ChannelManager not initialized");
     return this.channelManager.getCumulativeAmount(channelId);
   }
+  /**
+   * Gets the on-chain deposit total (locked collateral) for a tracked channel.
+   * The available (spendable) balance is this minus the cumulative spent amount.
+   */
+  getChannelDepositTotal(channelId) {
+    if (!this.channelManager) throw new Error("ChannelManager not initialized");
+    return this.channelManager.getDepositTotal(channelId);
+  }
+  /**
+   * Read the on-chain settlement-token balance of this client's OWN wallet on
+   * each configured chain (EVM token, Solana SPL, native MINA). A free read — no
+   * signing, no payment. Best-effort per chain: a chain whose config is absent or
+   * whose RPC read fails is omitted rather than failing the whole result, so the
+   * wallet view degrades gracefully. Available after `start()` (Solana/Mina keys
+   * are derived there).
+   */
+  async getBalances() {
+    const out = [];
+    const evmAddress = this.getEvmAddress();
+    const rpcUrls = this.config.chainRpcUrls;
+    const tokens = this.config.preferredTokens;
+    if (evmAddress && rpcUrls && tokens) {
+      const chainKeys = this.config.supportedChains ?? Object.keys(rpcUrls);
+      const chainKey = chainKeys.find((c) => c.startsWith("evm") && rpcUrls[c] && tokens[c]);
+      const rpcUrl = chainKey ? rpcUrls[chainKey] : void 0;
+      const tokenAddress = chainKey ? tokens[chainKey] : void 0;
+      if (chainKey && rpcUrl && tokenAddress) {
+        try {
+          out.push(await readEvmTokenBalance({ rpcUrl, chainKey, tokenAddress, owner: evmAddress }));
+        } catch {
+        }
+      }
+    }
+    const solAddress = this.getSolanaAddress();
+    const sol = this.config.solanaChannel;
+    if (solAddress && sol?.rpcUrl && sol.tokenMint) {
+      try {
+        out.push(
+          await readSolanaTokenBalance({ rpcUrl: sol.rpcUrl, mint: sol.tokenMint, owner: solAddress })
+        );
+      } catch {
+      }
+    }
+    const minaAddress = this.getMinaAddress();
+    const mina = this.config.minaChannel;
+    if (minaAddress && mina?.graphqlUrl) {
+      try {
+        out.push(await readMinaBalance({ graphqlUrl: mina.graphqlUrl, owner: minaAddress }));
+      } catch {
+      }
+    }
+    return out;
+  }
   /**
    * Resolves an ILP destination address to a peer ID.
    * Convention: destination "g.toon.peer1" → peerId "peer1" (last segment).