@toon-protocol/client 0.14.10 → 0.14.12

package/dist/index.d.ts

@@ -1264,6 +1264,21 @@ declare class ToonClient {
     }>;
     /** Where a tracked channel sits in the withdraw journey. */
     getChannelCloseState(channelId: string): 'open' | 'closing' | 'settleable' | 'settled';
+    getSettleableAt(channelId: string): bigint | undefined;
+    /**
+     * Re-hydrate a RESUMED channel's on-chain deposit. Persisted channel state
+     * omits `depositTotal`, so after a daemon restart the tracked deposit is `0`
+     * and the wallet shows 0 spendable even though real collateral is locked
+     * on-chain. Read the participant's `deposit` from the `participants` mapping
+     * and update the tracked total so `depositTotal - cumulativeAmount` is right.
+     * Best-effort by caller (await + catch); returns the on-chain deposit, or
+     * `undefined` when it can't be read (no channel manager / on-chain client /
+     * EVM address).
+     */
+    rehydrateChannelDeposit(channelId: string, opts: {
+        chain: string;
+        tokenNetworkAddress: string;
+    }): Promise<bigint | undefined>;
     /**
      * 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
@@ -1358,6 +1373,26 @@ declare class ConnectorError extends ToonClientError {
 declare class ValidationError extends ToonClientError {
     constructor(message: string, cause?: Error);
 }
+/**
+ * Thrown when the one-time on-chain payment-channel OPEN reverts because the
+ * local settlement wallet has no native gas to pay for its own
+ * approve/openChannel/setTotalDeposit transactions. This is the channel OPEN
+ * only — per-write settlement rides ILP-over-HTTP and never spends gas. We
+ * remap ONLY this case so callers get an actionable message (fund the wallet)
+ * instead of the raw viem "...exceeds the balance of the account" string
+ * (toon-meta#65). Retryable once the wallet is funded; the underlying viem/RPC
+ * error is preserved as `cause`.
+ */
+declare class ChannelFundingError extends ToonClientError {
+    readonly retryable = true;
+    constructor(message: string, cause?: Error);
+}
+/**
+ * True when `err` (or any error in its nested `cause` chain) is an
+ * insufficient-native-gas revert. viem wraps the node error one or more levels
+ * deep, so the whole chain is flattened and scanned.
+ */
+declare function isInsufficientGasError(err: unknown): boolean;
 
 /**
  * Configuration options for HttpRuntimeClient.
@@ -2238,6 +2273,23 @@ declare class OnChainChannelClient implements ConnectorChannelClient {
     }>;
     /** Read + destructure the EVM `channels(bytes32)` view. */
     private readEvmChannel;
+    /**
+     * Read a participant's on-chain channel state — `deposit` (locked collateral),
+     * `nonce`, and `transferredAmount` — straight from the `participants` mapping.
+     * Takes the chain + token-network explicitly so it works for a channel that
+     * was RESUMED from disk (no in-memory `channelContext` yet), which is exactly
+     * when the daemon needs to re-hydrate the deposit it doesn't persist.
+     */
+    readEvmParticipantState(opts: {
+        chain: string;
+        tokenNetworkAddress: string;
+        channelId: string;
+        participant: string;
+    }): Promise<{
+        deposit: bigint;
+        nonce: bigint;
+        transferredAmount: bigint;
+    }>;
     /**
      * Opens a REAL on-chain Solana payment channel.
      *
@@ -2284,14 +2336,22 @@ declare class OnChainChannelClient implements ConnectorChannelClient {
      */
     private openMinaChannel;
     /**
-     * Opens an EVM payment channel on-chain.
+     * Opens an EVM payment channel on-chain, remapping the one-time
+     * insufficient-native-gas revert into an actionable {@link ChannelFundingError}
+     * so callers surface "fund the wallet" instead of the raw viem
+     * "...exceeds the balance of the account" string (toon-meta#65). Only the gas
+     * case is remapped; every other error propagates unchanged.
+     */
+    private openEvmChannel;
+    /**
+     * Raw EVM channel-open (no gas-error remapping — see {@link openEvmChannel}).
      *
      * 1. Approve token spend if needed
      * 2. Call TokenNetwork.openChannel()
      * 3. Extract channelId from ChannelOpened event
      * 4. Deposit initial funds if specified
      */
-    private openEvmChannel;
+    private openEvmChannelUnchecked;
     /**
      * Gets the current state of a payment channel from on-chain data.
      */
@@ -3519,4 +3579,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, ChannelManager, type ClaimMessage, type ClaimResolver, ConnectorError, type DiscoveredIlpPeer, type EVMClaimMessage, type EncryptedKeystore, EvmSigner, type FaucetChain, type FundWalletOptions, type FundWalletResult, type H402FetchOptions, Http402Client, type Http402ClientConfig, HttpConnectorAdmin, type HttpConnectorAdminConfig, HttpIlpClient, type HttpIlpClientConfig, type HttpIlpClientFactory, HttpRuntimeClient, type HttpRuntimeClientConfig, ILP_CLAIM_HEADER, ILP_CLAIM_WRAPPED_HEADER, ILP_PEER_ID_HEADER, type IlpTransportChoice, type InteractionResultContent, KeyManager, type KeyManagerConfig, type MinaClaimMessage, type MinaDepositReader, MinaSigner, type MinaSignerOptions, NetworkError, OnChainChannelClient, type OnChainChannelClientConfig, type ParsedFulfillHttp, type ParsedX402Challenge, type PasskeyInfo, type PetDvmProvider, type PetInteractionEventData, type PetInteractionRequestParams, type PetInteractionResultData, type PetListing, type PetListingFilterOptions, type PetListingParams, type PetPurchaseRequestParams, type ProofStatus, type PublishEventResult, type RequestBlobStorageParams, type RequestBlobStorageResult, type RetryOptions, type SelectIlpTransportOptions, type SignedBalanceProof, type SolanaChannelClientOptions, type SolanaClaimMessage, SolanaSigner, type StatValues, type ToonChannelAccept, ToonClient, type ToonClientConfig, ToonClientError, type ToonIdentity, type ToonSigners, type ToonStartResult, type UnsignedNostrEvent, ValidationError, type VaultData, applyDefaults, applyNetworkPresets, buildBackupEvent, buildBackupFilter, buildPetInteractionRequest, buildPetListingEvent, buildPetPurchaseRequest, buildSettlementInfo, buildStoreWriteEnvelope, decryptMnemonic, defaultFaucetTimeout, deriveFromNsec, deriveFullIdentity, deriveNostrKeyFromMnemonic, encryptMnemonic, filterPetDvmProviders, filterPetListings, fundWallet, generateKeystore, generateMnemonic, generateRandomIdentity, getNetworkStatus, httpEndpointToBtpUrl, importKeystore, isPrfSupported, loadKeystore, parseBackupPayload, parseFulfillHttp, parseFulfillHttpBytes, parseHttpResponse, parsePetInteractionEvent, parsePetInteractionResult, parsePetListing, 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, type InteractionResultContent, KeyManager, type KeyManagerConfig, type MinaClaimMessage, type MinaDepositReader, MinaSigner, type MinaSignerOptions, NetworkError, OnChainChannelClient, type OnChainChannelClientConfig, type ParsedFulfillHttp, type ParsedX402Challenge, type PasskeyInfo, type PetDvmProvider, type PetInteractionEventData, type PetInteractionRequestParams, type PetInteractionResultData, type PetListing, type PetListingFilterOptions, type PetListingParams, type PetPurchaseRequestParams, type ProofStatus, type PublishEventResult, type RequestBlobStorageParams, type RequestBlobStorageResult, type RetryOptions, type SelectIlpTransportOptions, type SignedBalanceProof, type SolanaChannelClientOptions, type SolanaClaimMessage, SolanaSigner, type StatValues, type ToonChannelAccept, ToonClient, type ToonClientConfig, ToonClientError, type ToonIdentity, type ToonSigners, type ToonStartResult, type UnsignedNostrEvent, ValidationError, type VaultData, applyDefaults, applyNetworkPresets, buildBackupEvent, buildBackupFilter, buildPetInteractionRequest, buildPetListingEvent, buildPetPurchaseRequest, buildSettlementInfo, buildStoreWriteEnvelope, decryptMnemonic, defaultFaucetTimeout, deriveFromNsec, deriveFullIdentity, deriveNostrKeyFromMnemonic, encryptMnemonic, filterPetDvmProviders, filterPetListings, fundWallet, generateKeystore, generateMnemonic, generateRandomIdentity, getNetworkStatus, httpEndpointToBtpUrl, importKeystore, isInsufficientGasError, isPrfSupported, loadKeystore, parseBackupPayload, parseFulfillHttp, parseFulfillHttpBytes, parseHttpResponse, parsePetInteractionEvent, parsePetInteractionResult, parsePetListing, parseX402Body, parseX402Challenge, proxyIlpEndpoint, readDiscoveredIlpPeer, readMinaDepositTotal, requestBlobStorage, selectIlpTransport, serializeHttpRequest, validateConfig, validateMnemonic, withRetry, writeKeystoreFile };

package/dist/index.js

@@ -80,6 +80,29 @@ var PeerAlreadyExistsError = class extends ToonClientError {
     this.name = "PeerAlreadyExistsError";
   }
 };
+var ChannelFundingError = class extends ToonClientError {
+  retryable = true;
+  constructor(message, cause) {
+    super(message, "CHANNEL_FUNDING", cause);
+    this.name = "ChannelFundingError";
+  }
+};
+var INSUFFICIENT_GAS_MARKERS = [
+  "exceeds the balance of the account",
+  "insufficient funds for gas",
+  "insufficient funds for intrinsic transaction cost",
+  "insufficient funds for transfer"
+];
+function isInsufficientGasError(err) {
+  const parts = [];
+  let cur = err;
+  for (let i = 0; i < 10 && cur != null; i++) {
+    parts.push(cur instanceof Error ? cur.message : String(cur));
+    cur = cur instanceof Error ? cur.cause : void 0;
+  }
+  const text = parts.join(" | ").toLowerCase();
+  return INSUFFICIENT_GAS_MARKERS.some((m) => text.includes(m));
+}
 
 // src/keys/KeyDerivation.ts
 import { generateSecretKey, getPublicKey } from "nostr-tools/pure";
@@ -2300,6 +2323,17 @@ var TOKEN_NETWORK_ABI = [
       { name: "participant2", type: "address" }
     ]
   },
+  {
+    name: "participants",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ type: "bytes32" }, { type: "address" }],
+    outputs: [
+      { name: "deposit", type: "uint256" },
+      { name: "nonce", type: "uint256" },
+      { name: "transferredAmount", type: "uint256" }
+    ]
+  },
   {
     name: "ChannelOpened",
     type: "event",
@@ -2631,6 +2665,23 @@ var OnChainChannelClient = class {
     });
     return { settlementTimeout: res[0], state: Number(res[1]), closedAt: res[2] };
   }
+  /**
+   * Read a participant's on-chain channel state — `deposit` (locked collateral),
+   * `nonce`, and `transferredAmount` — straight from the `participants` mapping.
+   * Takes the chain + token-network explicitly so it works for a channel that
+   * was RESUMED from disk (no in-memory `channelContext` yet), which is exactly
+   * when the daemon needs to re-hydrate the deposit it doesn't persist.
+   */
+  async readEvmParticipantState(opts) {
+    const { publicClient } = this.createClients(opts.chain);
+    const res = await publicClient.readContract({
+      address: opts.tokenNetworkAddress,
+      abi: TOKEN_NETWORK_ABI,
+      functionName: "participants",
+      args: [opts.channelId, opts.participant]
+    });
+    return { deposit: res[0], nonce: res[1], transferredAmount: res[2] };
+  }
   /**
    * Opens a REAL on-chain Solana payment channel.
    *
@@ -2762,14 +2813,33 @@ var OnChainChannelClient = class {
     };
   }
   /**
-   * Opens an EVM payment channel on-chain.
+   * Opens an EVM payment channel on-chain, remapping the one-time
+   * insufficient-native-gas revert into an actionable {@link ChannelFundingError}
+   * so callers surface "fund the wallet" instead of the raw viem
+   * "...exceeds the balance of the account" string (toon-meta#65). Only the gas
+   * case is remapped; every other error propagates unchanged.
+   */
+  async openEvmChannel(params) {
+    try {
+      return await this.openEvmChannelUnchecked(params);
+    } catch (err) {
+      if (!isInsufficientGasError(err)) throw err;
+      const chainFamily = params.chain.split(":")[0] || params.chain;
+      throw new ChannelFundingError(
+        `Settlement wallet ${this.evmSigner.address} has no gas on ${chainFamily} to open a payment channel. Run toon_fund_wallet (or fund the wallet) and retry.`,
+        err instanceof Error ? err : void 0
+      );
+    }
+  }
+  /**
+   * Raw EVM channel-open (no gas-error remapping — see {@link openEvmChannel}).
    *
    * 1. Approve token spend if needed
    * 2. Call TokenNetwork.openChannel()
    * 3. Extract channelId from ChannelOpened event
    * 4. Deposit initial funds if specified
    */
-  async openEvmChannel(params) {
+  async openEvmChannelUnchecked(params) {
     const {
       chain,
       tokenNetwork,
@@ -5010,6 +5080,33 @@ var ToonClient = class {
     if (!this.channelManager) throw new Error("ChannelManager not initialized");
     return this.channelManager.getChannelCloseState(channelId);
   }
+  getSettleableAt(channelId) {
+    if (!this.channelManager) throw new Error("ChannelManager not initialized");
+    return this.channelManager.getSettleableAt(channelId);
+  }
+  /**
+   * Re-hydrate a RESUMED channel's on-chain deposit. Persisted channel state
+   * omits `depositTotal`, so after a daemon restart the tracked deposit is `0`
+   * and the wallet shows 0 spendable even though real collateral is locked
+   * on-chain. Read the participant's `deposit` from the `participants` mapping
+   * and update the tracked total so `depositTotal - cumulativeAmount` is right.
+   * Best-effort by caller (await + catch); returns the on-chain deposit, or
+   * `undefined` when it can't be read (no channel manager / on-chain client /
+   * EVM address).
+   */
+  async rehydrateChannelDeposit(channelId, opts) {
+    if (!this.channelManager || !this.onChainChannelClient) return void 0;
+    const participant = this.getEvmAddress();
+    if (!participant) return void 0;
+    const { deposit } = await this.onChainChannelClient.readEvmParticipantState({
+      chain: opts.chain,
+      tokenNetworkAddress: opts.tokenNetworkAddress,
+      channelId,
+      participant
+    });
+    this.channelManager.setDepositTotal(channelId, deposit);
+    return deposit;
+  }
   /**
    * 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
@@ -7045,6 +7142,7 @@ function writeKeystoreFile(path, keystore) {
 }
 export {
   BtpRuntimeClient,
+  ChannelFundingError,
   ChannelManager,
   ConnectorError,
   EvmSigner,
@@ -7102,6 +7200,7 @@ export {
   guardedRenderDispatch,
   httpEndpointToBtpUrl,
   importKeystore,
+  isInsufficientGasError,
   isPrfSupported,
   isTrustDowngrade,
   loadKeystore,