@toon-protocol/client 0.15.0 → 0.16.0

package/dist/index.d.ts

@@ -15,6 +15,108 @@ interface WalletBalance {
     /** Token decimals, when resolved. */
     assetScale?: number;
 }
+/**
+ * One asset amount within a chain's wallet view — the native coin or one token.
+ * `amount` is a base-unit integer, decimal string.
+ */
+interface WalletTokenAmount {
+    /** Asset symbol (e.g. `'ETH'`, `'SOL'`, `'MINA'`, `'USDC'`), when known. */
+    symbol?: string;
+    /** Base-unit integer, decimal string. */
+    amount: string;
+    /** Decimals for formatting (ETH 18, SOL 9, MINA 9, USDC 6). */
+    decimals?: number;
+    /** Token contract / SPL mint address. Absent for the native coin. */
+    address?: string;
+}
+/**
+ * The full wallet view for ONE chain the identity is configured for: the native
+ * coin plus every configured token, keyed by the chain's full key (e.g.
+ * `'evm:31337'`). `unreadable` marks a chain whose RPC could not be reached at
+ * all — the caller renders a per-chain notice rather than crashing.
+ */
+interface WalletChainBalances {
+    chain: 'evm' | 'solana' | 'mina';
+    /** Full chain key, e.g. `'evm:31337'`, `'solana'`, `'mina'`. */
+    chainKey: string;
+    address: string;
+    /** Native-coin balance, when readable. */
+    native?: WalletTokenAmount;
+    /** Configured token balances (e.g. USDC), each best-effort. */
+    tokens: WalletTokenAmount[];
+    /** True when nothing on this chain could be read (RPC unreachable). */
+    unreadable?: boolean;
+    /** First read error, when any read failed (for diagnostics). */
+    error?: string;
+}
+/** Read an ERC-20 token balance (balance + decimals + symbol) for `owner`. */
+declare function readEvmTokenBalance(opts: {
+    rpcUrl: string;
+    chainKey: string;
+    tokenAddress: string;
+    owner: string;
+}): Promise<WalletBalance>;
+/** Read the native ETH balance (wei) for `owner` via `eth_getBalance`. */
+declare function readEvmNativeBalance(opts: {
+    rpcUrl: string;
+    chainKey: string;
+    owner: string;
+}): Promise<WalletTokenAmount>;
+/** Read the native SOL balance (lamports) for `owner` via the `getBalance` RPC. */
+declare function readSolanaNativeBalance(opts: {
+    rpcUrl: string;
+    owner: string;
+    fetchImpl?: typeof fetch;
+}): Promise<WalletTokenAmount>;
+/** Read the SPL-token balance for `owner`'s token account(s) of `mint`. */
+declare function readSolanaTokenBalance(opts: {
+    rpcUrl: string;
+    mint: string;
+    owner: string;
+    fetchImpl?: typeof fetch;
+}): Promise<WalletBalance>;
+/** Read the native MINA balance (nanomina) for `owner` via the Mina GraphQL API. */
+declare function readMinaBalance(opts: {
+    graphqlUrl: string;
+    owner: string;
+    fetchImpl?: typeof fetch;
+}): Promise<WalletBalance>;
+/**
+ * Per-chain inputs for {@link readWalletBalances}: the resolved RPC URL, the
+ * identity's address on that chain, and the configured token (USDC) — sourced by
+ * the caller from the network topology / presets, never hardcoded here. A chain
+ * key absent from the object is simply not read.
+ */
+interface WalletBalanceSources {
+    evm?: {
+        chainKey: string;
+        rpcUrl: string;
+        owner: string;
+        tokenAddress?: string;
+    };
+    solana?: {
+        chainKey?: string;
+        rpcUrl: string;
+        owner: string;
+        tokenMint?: string;
+    };
+    mina?: {
+        chainKey?: string;
+        graphqlUrl: string;
+        owner: string;
+    };
+    /** Injectable fetch (Solana/Mina JSON-RPC & GraphQL) for tests. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Read the full wallet view — native coin + configured tokens — for every chain
+ * in `sources`, keyed per chain. FREE: read-only RPC, no signing. Each chain is
+ * read independently and in parallel; a chain whose RPC is unreachable degrades
+ * to `{ unreadable: true, error }` instead of failing the others. Within a chain
+ * the native and token reads are independent, so a native read can succeed even
+ * if the token read fails (and vice versa).
+ */
+declare function readWalletBalances(sources: WalletBalanceSources): Promise<WalletChainBalances[]>;
 
 /**
  * Solana payment-channel parameters supplied via `ToonClientConfig.solanaChannel`.
@@ -1317,6 +1419,22 @@ declare class ToonClient {
      * are derived there).
      */
     getBalances(): Promise<WalletBalance[]>;
+    /**
+     * The FULL multi-chain wallet view (#299): for every chain the identity is
+     * configured for, the native coin (ETH / SOL / MINA) AND every configured
+     * token (USDC), grouped per chain with the identity's address on that chain.
+     * A superset of {@link getBalances} — which stays scoped to the channel's
+     * settlement token — kept as a separate reader so channel-settlement callers
+     * are unaffected.
+     *
+     * FREE: read-only RPC, no signing, no payment. Works on an UNSTARTED client:
+     * the Solana/Mina addresses (which the signers only register during
+     * `start()`) are derived on demand from the retained mnemonic — the SAME keys
+     * `start()` would register and that `rig fund` prints — so all configured
+     * chains appear even before a start. Best-effort per chain: an unreachable
+     * RPC yields `{ unreadable: true }` for that chain, never failing the others.
+     */
+    getWalletBalances(): Promise<WalletChainBalances[]>;
     /**
      * Resolves an ILP destination address to a peer ID.
      * Convention: destination "g.toon.peer1" → peerId "peer1" (last segment).
@@ -3208,4 +3326,4 @@ declare function loadKeystore(path: string, password: string): string;
  */
 declare function writeKeystoreFile(path: string, keystore: EncryptedKeystore): void;
 
-export { type BackupPayload, type BalanceProofParams, BtpRuntimeClient, type BtpRuntimeClientConfig, type ChainMetadata, type ChainSigner, ChannelFundingError, ChannelManager, type ClaimMessage, type ClaimResolver, ConnectorError, type DiscoveredIlpPeer, type EVMClaimMessage, type EncryptedKeystore, EvmSigner, type FaucetChain, type FundWalletOptions, type FundWalletResult, type H402FetchOptions, Http402Client, type Http402ClientConfig, HttpConnectorAdmin, type HttpConnectorAdminConfig, HttpIlpClient, type HttpIlpClientConfig, type HttpIlpClientFactory, HttpRuntimeClient, type HttpRuntimeClientConfig, ILP_CLAIM_HEADER, ILP_CLAIM_WRAPPED_HEADER, ILP_PEER_ID_HEADER, type IlpTransportChoice, KeyManager, type KeyManagerConfig, type MinaClaimMessage, type MinaDepositReader, MinaSigner, type MinaSignerOptions, NetworkError, OnChainChannelClient, type OnChainChannelClientConfig, type ParsedFulfillHttp, type ParsedX402Challenge, type PasskeyInfo, type PublishEventResult, type RequestBlobStorageParams, type RequestBlobStorageResult, type RetryOptions, type SelectIlpTransportOptions, type SignedBalanceProof, type SolanaChannelClientOptions, type SolanaClaimMessage, SolanaSigner, type ToonChannelAccept, ToonClient, type ToonClientConfig, ToonClientError, type ToonIdentity, type ToonSigners, type ToonStartResult, ValidationError, type VaultData, applyDefaults, applyNetworkPresets, buildBackupEvent, buildBackupFilter, buildSettlementInfo, buildStoreWriteEnvelope, decryptMnemonic, defaultFaucetTimeout, deriveFromNsec, deriveFullIdentity, deriveNostrKeyFromMnemonic, encryptMnemonic, extractArweaveTxId, fundWallet, generateKeystore, generateMnemonic, generateRandomIdentity, getNetworkStatus, httpEndpointToBtpUrl, importKeystore, isInsufficientGasError, isPrfSupported, loadKeystore, parseBackupPayload, parseFulfillHttp, parseFulfillHttpBytes, parseHttpResponse, parseX402Body, parseX402Challenge, proxyIlpEndpoint, readDiscoveredIlpPeer, readMinaDepositTotal, requestBlobStorage, selectIlpTransport, serializeHttpRequest, validateConfig, validateMnemonic, withRetry, writeKeystoreFile };
+export { type BackupPayload, type BalanceProofParams, BtpRuntimeClient, type BtpRuntimeClientConfig, type ChainMetadata, type ChainSigner, ChannelFundingError, ChannelManager, type ClaimMessage, type ClaimResolver, ConnectorError, type DiscoveredIlpPeer, type EVMClaimMessage, type EncryptedKeystore, EvmSigner, type FaucetChain, type FundWalletOptions, type FundWalletResult, type H402FetchOptions, Http402Client, type Http402ClientConfig, HttpConnectorAdmin, type HttpConnectorAdminConfig, HttpIlpClient, type HttpIlpClientConfig, type HttpIlpClientFactory, HttpRuntimeClient, type HttpRuntimeClientConfig, ILP_CLAIM_HEADER, ILP_CLAIM_WRAPPED_HEADER, ILP_PEER_ID_HEADER, type IlpTransportChoice, KeyManager, type KeyManagerConfig, type MinaClaimMessage, type MinaDepositReader, MinaSigner, type MinaSignerOptions, NetworkError, OnChainChannelClient, type OnChainChannelClientConfig, type ParsedFulfillHttp, type ParsedX402Challenge, type PasskeyInfo, type PublishEventResult, type RequestBlobStorageParams, type RequestBlobStorageResult, type RetryOptions, type SelectIlpTransportOptions, type SignedBalanceProof, type SolanaChannelClientOptions, type SolanaClaimMessage, SolanaSigner, type ToonChannelAccept, ToonClient, type ToonClientConfig, ToonClientError, type ToonIdentity, type ToonSigners, type ToonStartResult, ValidationError, type VaultData, type WalletBalance, type WalletBalanceSources, type WalletChainBalances, type WalletTokenAmount, applyDefaults, applyNetworkPresets, buildBackupEvent, buildBackupFilter, buildSettlementInfo, buildStoreWriteEnvelope, decryptMnemonic, defaultFaucetTimeout, deriveFromNsec, deriveFullIdentity, deriveNostrKeyFromMnemonic, encryptMnemonic, extractArweaveTxId, fundWallet, generateKeystore, generateMnemonic, generateRandomIdentity, getNetworkStatus, httpEndpointToBtpUrl, importKeystore, isInsufficientGasError, isPrfSupported, loadKeystore, parseBackupPayload, parseFulfillHttp, parseFulfillHttpBytes, parseHttpResponse, parseX402Body, parseX402Challenge, proxyIlpEndpoint, readDiscoveredIlpPeer, readEvmNativeBalance, readEvmTokenBalance, readMinaBalance, readMinaDepositTotal, readSolanaNativeBalance, readSolanaTokenBalance, readWalletBalances, requestBlobStorage, selectIlpTransport, serializeHttpRequest, validateConfig, validateMnemonic, withRetry, writeKeystoreFile };

package/dist/index.js

@@ -3957,6 +3957,38 @@ async function readEvmTokenBalance(opts) {
   if (decimals !== void 0) out.assetScale = Number(decimals);
   return out;
 }
+async function readEvmNativeBalance(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 wei = await client.getBalance({ address: opts.owner });
+  return { symbol: "ETH", amount: wei.toString(), decimals: 18 };
+}
+async function readSolanaNativeBalance(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: "getBalance",
+      params: [opts.owner, { 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"}`);
+  const lamports = BigInt(json.result?.value ?? 0);
+  return { symbol: "SOL", amount: lamports.toString(), decimals: 9 };
+}
 async function readSolanaTokenBalance(opts) {
   const fetchImpl = opts.fetchImpl ?? fetch;
   const res = await fetchImpl(opts.rpcUrl, {
@@ -4004,6 +4036,95 @@ async function readMinaBalance(opts) {
     assetScale: 9
   };
 }
+var errText = (e) => e instanceof Error ? e.message : String(e);
+function foldNative(out, settled, errors) {
+  if (settled.status === "fulfilled") out.native = settled.value;
+  else errors.push(errText(settled.reason));
+}
+function foldToken(out, settled, tokenAddress, errors) {
+  if (settled.status === "rejected") {
+    errors.push(errText(settled.reason));
+    return;
+  }
+  const bal = settled.value;
+  if (!bal) return;
+  out.tokens.push({
+    symbol: bal.asset,
+    amount: bal.amount,
+    decimals: bal.assetScale,
+    ...tokenAddress ? { address: tokenAddress } : {}
+  });
+}
+function finalizeChain(out, errors) {
+  if (errors.length > 0) out.error = errors[0];
+  if (out.native === void 0 && out.tokens.length === 0) out.unreadable = true;
+}
+async function readWalletBalances(sources) {
+  const { fetchImpl } = sources;
+  const tasks = [];
+  if (sources.evm) {
+    const { chainKey, rpcUrl, owner, tokenAddress } = sources.evm;
+    tasks.push(
+      (async () => {
+        const out = { chain: "evm", chainKey, address: owner, tokens: [] };
+        const errors = [];
+        const [nativeR, tokenR] = await Promise.allSettled([
+          readEvmNativeBalance({ rpcUrl, chainKey, owner }),
+          tokenAddress ? readEvmTokenBalance({ rpcUrl, chainKey, tokenAddress, owner }) : Promise.resolve(void 0)
+        ]);
+        foldNative(out, nativeR, errors);
+        foldToken(out, tokenR, tokenAddress, errors);
+        finalizeChain(out, errors);
+        return out;
+      })()
+    );
+  }
+  if (sources.solana) {
+    const { chainKey = "solana", rpcUrl, owner, tokenMint } = sources.solana;
+    tasks.push(
+      (async () => {
+        const out = { chain: "solana", chainKey, address: owner, tokens: [] };
+        const errors = [];
+        const [nativeR, tokenR] = await Promise.allSettled([
+          readSolanaNativeBalance({ rpcUrl, owner, fetchImpl }),
+          tokenMint ? readSolanaTokenBalance({ rpcUrl, mint: tokenMint, owner, fetchImpl }) : Promise.resolve(void 0)
+        ]);
+        foldNative(out, nativeR, errors);
+        if (tokenR.status === "fulfilled" && tokenR.value && tokenR.value.asset === void 0) {
+          tokenR.value.asset = "USDC";
+        }
+        foldToken(out, tokenR, tokenMint, errors);
+        finalizeChain(out, errors);
+        return out;
+      })()
+    );
+  }
+  if (sources.mina) {
+    const { chainKey = "mina", graphqlUrl, owner } = sources.mina;
+    tasks.push(
+      (async () => {
+        const out = { chain: "mina", chainKey, address: owner, tokens: [] };
+        const errors = [];
+        const nativeR = await Promise.allSettled([readMinaBalance({ graphqlUrl, owner, fetchImpl })]);
+        foldNative(
+          out,
+          nativeR[0].status === "fulfilled" ? {
+            status: "fulfilled",
+            value: {
+              symbol: nativeR[0].value.asset,
+              amount: nativeR[0].value.amount,
+              decimals: nativeR[0].value.assetScale
+            }
+          } : nativeR[0],
+          errors
+        );
+        finalizeChain(out, errors);
+        return out;
+      })()
+    );
+  }
+  return Promise.all(tasks);
+}
 
 // src/blob-storage.ts
 import { buildBlobStorageRequest } from "@toon-protocol/core";
@@ -5154,6 +5275,74 @@ var ToonClient = class {
     }
     return out;
   }
+  /**
+   * The FULL multi-chain wallet view (#299): for every chain the identity is
+   * configured for, the native coin (ETH / SOL / MINA) AND every configured
+   * token (USDC), grouped per chain with the identity's address on that chain.
+   * A superset of {@link getBalances} — which stays scoped to the channel's
+   * settlement token — kept as a separate reader so channel-settlement callers
+   * are unaffected.
+   *
+   * FREE: read-only RPC, no signing, no payment. Works on an UNSTARTED client:
+   * the Solana/Mina addresses (which the signers only register during
+   * `start()`) are derived on demand from the retained mnemonic — the SAME keys
+   * `start()` would register and that `rig fund` prints — so all configured
+   * chains appear even before a start. Best-effort per chain: an unreachable
+   * RPC yields `{ unreadable: true }` for that chain, never failing the others.
+   */
+  async getWalletBalances() {
+    const sources = {};
+    let derived;
+    let derivedTried = false;
+    const ensureDerived = async () => {
+      if (derivedTried) return derived;
+      derivedTried = true;
+      if (this.config.mnemonic) {
+        derived = await deriveFullIdentity(
+          this.config.mnemonic,
+          this.config.mnemonicAccountIndex ?? 0
+        );
+      }
+      return derived;
+    };
+    const evmAddress = this.getEvmAddress();
+    const rpcUrls = this.config.chainRpcUrls;
+    const tokens = this.config.preferredTokens;
+    if (evmAddress && rpcUrls) {
+      const usableEvm = (c) => c.startsWith("evm") && Boolean(rpcUrls[c]);
+      const settlementKeys = Object.keys(this.config.settlementAddresses ?? {});
+      const chainKeys = this.config.supportedChains ?? Object.keys(rpcUrls);
+      const chainKey = settlementKeys.find(usableEvm) ?? chainKeys.find(usableEvm);
+      if (chainKey && rpcUrls[chainKey]) {
+        sources.evm = {
+          chainKey,
+          rpcUrl: rpcUrls[chainKey],
+          owner: evmAddress,
+          ...tokens?.[chainKey] ? { tokenAddress: tokens[chainKey] } : {}
+        };
+      }
+    }
+    const sol = this.config.solanaChannel;
+    if (sol?.rpcUrl) {
+      const solAddress = this.getSolanaAddress() ?? (await ensureDerived())?.solana.publicKey;
+      if (solAddress) {
+        sources.solana = {
+          chainKey: "solana",
+          rpcUrl: sol.rpcUrl,
+          owner: solAddress,
+          ...sol.tokenMint ? { tokenMint: sol.tokenMint } : {}
+        };
+      }
+    }
+    const mina = this.config.minaChannel;
+    if (mina?.graphqlUrl) {
+      const minaAddress = this.getMinaAddress() ?? (await ensureDerived())?.mina.publicKey;
+      if (minaAddress) {
+        sources.mina = { chainKey: "mina", graphqlUrl: mina.graphqlUrl, owner: minaAddress };
+      }
+    }
+    return readWalletBalances(sources);
+  }
   /**
    * Resolves an ILP destination address to a peer ID.
    * Convention: destination "g.toon.peer1" → peerId "peer1" (last segment).
@@ -6781,7 +6970,13 @@ export {
   proxyIlpEndpoint,
   publishBackCoordinate,
   readDiscoveredIlpPeer,
+  readEvmNativeBalance,
+  readEvmTokenBalance,
+  readMinaBalance,
   readMinaDepositTotal,
+  readSolanaNativeBalance,
+  readSolanaTokenBalance,
+  readWalletBalances,
   renderDeterministicHtml,
   renderDispatch,
   requestBlobStorage,