@toon-protocol/client 0.14.7 → 0.14.8

package/dist/index.d.ts

@@ -1240,6 +1240,30 @@ declare class ToonClient {
         txHash?: string;
         depositTotal: string;
     }>;
+    /**
+     * Close a channel to begin the settlement grace period (first half of
+     * withdraw). Records `closedAt`/`settleableAt` (unix seconds) on the tracked
+     * channel — persisted, so the grace timer survives a daemon restart. Spends
+     * on-chain. EVM today; Solana/Mina are follow-ups.
+     */
+    closeChannel(channelId: string): Promise<{
+        channelId: string;
+        txHash?: string;
+        closedAt: string;
+        settleableAt: string;
+    }>;
+    /**
+     * Settle a closed channel to release collateral (second half of withdraw).
+     * THE time guard: never settle before `settleableAt`. A too-early call throws
+     * a retryable error (carrying the remaining seconds) BEFORE spending gas — the
+     * contract would revert anyway. Spends on-chain. EVM today.
+     */
+    settleChannel(channelId: string): Promise<{
+        channelId: string;
+        txHash?: string;
+    }>;
+    /** Where a tracked channel sits in the withdraw journey. */
+    getChannelCloseState(channelId: string): 'open' | 'closing' | 'settleable' | 'settled';
     /**
      * 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
@@ -2179,6 +2203,41 @@ declare class OnChainChannelClient implements ConnectorChannelClient {
      * caller-supplied current locked amount.
      */
     private depositEvm;
+    /**
+     * Close a channel to begin the settlement grace period. Dispatches by the
+     * channel's cached chain context. EVM `closeChannel` is unilateral (channelId
+     * only); after it confirms we read the `channels()` view for the AUTHORITATIVE
+     * `closedAt` + `settlementTimeout` (block-timestamp seconds) and compute
+     * `settleableAt = closedAt + settlementTimeout`. Solana/Mina are follow-ups.
+     */
+    closeChannel(channelId: string): Promise<{
+        txHash?: string;
+        closedAt: bigint;
+        settlementTimeout: bigint;
+        settleableAt: bigint;
+    }>;
+    /**
+     * Settle a closed channel after its grace period to release collateral. EVM
+     * `settleChannel` is unilateral (channelId only); the contract itself reverts
+     * before `closedAt + settlementTimeout`, so an early call surfaces as a tx
+     * revert here — but the caller (ToonClient/daemon) enforces the time guard
+     * BEFORE spending gas. Solana/Mina are follow-ups.
+     */
+    settleChannel(channelId: string): Promise<{
+        txHash?: string;
+    }>;
+    /**
+     * Read the EVM channel's close-relevant fields so a restarted daemon can
+     * recompute the grace timer from chain (chain is authoritative). EVM-only.
+     */
+    getChannelCloseInfo(channelId: string): Promise<{
+        status: ChannelState['status'];
+        closedAt: bigint;
+        settlementTimeout: bigint;
+        settleableAt: bigint;
+    }>;
+    /** Read + destructure the EVM `channels(bytes32)` view. */
+    private readEvmChannel;
     /**
      * Opens a REAL on-chain Solana payment channel.
      *
@@ -2242,6 +2301,12 @@ declare class OnChainChannelClient implements ConnectorChannelClient {
 interface ChannelStoreEntry {
     nonce: number;
     cumulativeAmount: bigint;
+    /** Unix SECONDS when close was initiated (withdraw flow). */
+    closedAt?: bigint;
+    /** Unix SECONDS the channel becomes settleable (= closedAt + settlementTimeout). */
+    settleableAt?: bigint;
+    /** Unix SECONDS the channel was settled (collateral released). */
+    settledAt?: bigint;
 }
 /**
  * Persistence interface for payment channel nonce/amount state.
@@ -2355,6 +2420,23 @@ declare class ChannelManager {
      * collateral on the next read.
      */
     setDepositTotal(channelId: string, total: bigint): void;
+    /** Persist a channel's full nonce/amount + withdraw-timer state to the store. */
+    private persist;
+    /**
+     * Record that a channel was closed (withdraw flow): stores `closedAt` +
+     * `settleableAt` (unix SECONDS) so the grace timer survives a daemon restart.
+     */
+    setChannelClosed(channelId: string, closedAt: bigint, settleableAt: bigint): void;
+    /** Record that a channel was settled (collateral released). */
+    setChannelSettled(channelId: string, settledAt: bigint): void;
+    /** The `settleableAt` timestamp (unix seconds) for a closed channel, if set. */
+    getSettleableAt(channelId: string): bigint | undefined;
+    /**
+     * Where a channel sits in the withdraw journey, from the tracked timers:
+     * `open` (never closed) → `closing` (closed, grace not elapsed) →
+     * `settleable` (grace elapsed) → `settled`. `nowSec` is injectable for tests.
+     */
+    getChannelCloseState(channelId: string, nowSec?: bigint): 'open' | 'closing' | 'settleable' | 'settled';
     /**
      * Gets all tracked channel IDs.
      */

package/dist/index.js

@@ -2272,6 +2272,20 @@ var TOKEN_NETWORK_ABI = [
     ],
     outputs: []
   },
+  {
+    name: "closeChannel",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [{ name: "channelId", type: "bytes32" }],
+    outputs: []
+  },
+  {
+    name: "settleChannel",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [{ name: "channelId", type: "bytes32" }],
+    outputs: []
+  },
   {
     name: "channels",
     type: "function",
@@ -2520,6 +2534,103 @@ var OnChainChannelClient = class {
     await publicClient.waitForTransactionReceipt({ hash: depositHash });
     return { txHash: depositHash, depositTotal: newTotal };
   }
+  /**
+   * Close a channel to begin the settlement grace period. Dispatches by the
+   * channel's cached chain context. EVM `closeChannel` is unilateral (channelId
+   * only); after it confirms we read the `channels()` view for the AUTHORITATIVE
+   * `closedAt` + `settlementTimeout` (block-timestamp seconds) and compute
+   * `settleableAt = closedAt + settlementTimeout`. Solana/Mina are follow-ups.
+   */
+  async closeChannel(channelId) {
+    const ctx = this.channelContext.get(channelId);
+    if (!ctx) {
+      throw new Error(
+        `No on-chain context for channel "${channelId}" \u2014 it must be opened by this client first.`
+      );
+    }
+    const chainPrefix = ctx.chain.split(":")[0];
+    if (chainPrefix === "solana" || chainPrefix === "mina") {
+      throw new Error(
+        `Close on ${chainPrefix} is not yet supported (EVM today; Solana/Mina follow-up).`
+      );
+    }
+    const { publicClient, walletClient } = this.createClients(ctx.chain);
+    const tokenNetworkAddr = ctx.tokenNetworkAddress;
+    const closeHash = await walletClient.writeContract({
+      address: tokenNetworkAddr,
+      abi: TOKEN_NETWORK_ABI,
+      functionName: "closeChannel",
+      args: [channelId]
+    });
+    await publicClient.waitForTransactionReceipt({ hash: closeHash });
+    const info = await this.readEvmChannel(publicClient, tokenNetworkAddr, channelId);
+    return {
+      txHash: closeHash,
+      closedAt: info.closedAt,
+      settlementTimeout: info.settlementTimeout,
+      settleableAt: info.closedAt + info.settlementTimeout
+    };
+  }
+  /**
+   * Settle a closed channel after its grace period to release collateral. EVM
+   * `settleChannel` is unilateral (channelId only); the contract itself reverts
+   * before `closedAt + settlementTimeout`, so an early call surfaces as a tx
+   * revert here — but the caller (ToonClient/daemon) enforces the time guard
+   * BEFORE spending gas. Solana/Mina are follow-ups.
+   */
+  async settleChannel(channelId) {
+    const ctx = this.channelContext.get(channelId);
+    if (!ctx) {
+      throw new Error(
+        `No on-chain context for channel "${channelId}" \u2014 it must be opened by this client first.`
+      );
+    }
+    const chainPrefix = ctx.chain.split(":")[0];
+    if (chainPrefix === "solana" || chainPrefix === "mina") {
+      throw new Error(
+        `Settle on ${chainPrefix} is not yet supported (EVM today; Solana/Mina follow-up).`
+      );
+    }
+    const { publicClient, walletClient } = this.createClients(ctx.chain);
+    const settleHash = await walletClient.writeContract({
+      address: ctx.tokenNetworkAddress,
+      abi: TOKEN_NETWORK_ABI,
+      functionName: "settleChannel",
+      args: [channelId]
+    });
+    await publicClient.waitForTransactionReceipt({ hash: settleHash });
+    return { txHash: settleHash };
+  }
+  /**
+   * Read the EVM channel's close-relevant fields so a restarted daemon can
+   * recompute the grace timer from chain (chain is authoritative). EVM-only.
+   */
+  async getChannelCloseInfo(channelId) {
+    const ctx = this.channelContext.get(channelId);
+    if (!ctx) throw new Error(`No on-chain context for channel "${channelId}".`);
+    const chainPrefix = ctx.chain.split(":")[0];
+    if (chainPrefix === "solana" || chainPrefix === "mina") {
+      throw new Error(`getChannelCloseInfo on ${chainPrefix} is not supported.`);
+    }
+    const { publicClient } = this.createClients(ctx.chain);
+    const info = await this.readEvmChannel(publicClient, ctx.tokenNetworkAddress, channelId);
+    return {
+      status: STATE_MAP2[info.state] ?? "open",
+      closedAt: info.closedAt,
+      settlementTimeout: info.settlementTimeout,
+      settleableAt: info.closedAt + info.settlementTimeout
+    };
+  }
+  /** Read + destructure the EVM `channels(bytes32)` view. */
+  async readEvmChannel(publicClient, tokenNetworkAddr, channelId) {
+    const res = await publicClient.readContract({
+      address: tokenNetworkAddr,
+      abi: TOKEN_NETWORK_ABI,
+      functionName: "channels",
+      args: [channelId]
+    });
+    return { settlementTimeout: res[0], state: Number(res[1]), closedAt: res[2] };
+  }
   /**
    * Opens a REAL on-chain Solana payment channel.
    *
@@ -3484,7 +3595,12 @@ var ChannelManager = class {
           tokenNetworkAddress: tnAddr,
           tokenAddress: chainContext?.tokenAddress,
           recipient: chainContext?.recipient,
-          depositTotal: chainContext?.depositTotal
+          depositTotal: chainContext?.depositTotal,
+          // Resume the withdraw-flow timers so a daemon restart mid-grace
+          // doesn't strand funds (the gate can't be evaluated without them).
+          ...persisted.closedAt !== void 0 ? { closedAt: persisted.closedAt } : {},
+          ...persisted.settleableAt !== void 0 ? { settleableAt: persisted.settleableAt } : {},
+          ...persisted.settledAt !== void 0 ? { settledAt: persisted.settledAt } : {}
         });
         return;
       }
@@ -3519,12 +3635,7 @@ var ChannelManager = class {
     }
     tracking.nonce += 1;
     tracking.cumulativeAmount += additionalAmount;
-    if (this.store) {
-      this.store.save(channelId, {
-        nonce: tracking.nonce,
-        cumulativeAmount: tracking.cumulativeAmount
-      });
-    }
+    this.persist(channelId);
     const signer = this.chainSigners.get(tracking.chainType);
     if (signer && tracking.chainType !== "evm") {
       if (!tracking.recipient) {
@@ -3624,6 +3735,57 @@ var ChannelManager = class {
     }
     tracking.depositTotal = total;
   }
+  /** Persist a channel's full nonce/amount + withdraw-timer state to the store. */
+  persist(channelId) {
+    if (!this.store) return;
+    const t = this.channels.get(channelId);
+    if (!t) return;
+    this.store.save(channelId, {
+      nonce: t.nonce,
+      cumulativeAmount: t.cumulativeAmount,
+      ...t.closedAt !== void 0 ? { closedAt: t.closedAt } : {},
+      ...t.settleableAt !== void 0 ? { settleableAt: t.settleableAt } : {},
+      ...t.settledAt !== void 0 ? { settledAt: t.settledAt } : {}
+    });
+  }
+  /**
+   * Record that a channel was closed (withdraw flow): stores `closedAt` +
+   * `settleableAt` (unix SECONDS) so the grace timer survives a daemon restart.
+   */
+  setChannelClosed(channelId, closedAt, settleableAt) {
+    const tracking = this.channels.get(channelId);
+    if (!tracking) {
+      throw new Error(`Channel "${channelId}" is not being tracked.`);
+    }
+    tracking.closedAt = closedAt;
+    tracking.settleableAt = settleableAt;
+    this.persist(channelId);
+  }
+  /** Record that a channel was settled (collateral released). */
+  setChannelSettled(channelId, settledAt) {
+    const tracking = this.channels.get(channelId);
+    if (!tracking) {
+      throw new Error(`Channel "${channelId}" is not being tracked.`);
+    }
+    tracking.settledAt = settledAt;
+    this.persist(channelId);
+  }
+  /** The `settleableAt` timestamp (unix seconds) for a closed channel, if set. */
+  getSettleableAt(channelId) {
+    return this.channels.get(channelId)?.settleableAt;
+  }
+  /**
+   * Where a channel sits in the withdraw journey, from the tracked timers:
+   * `open` (never closed) → `closing` (closed, grace not elapsed) →
+   * `settleable` (grace elapsed) → `settled`. `nowSec` is injectable for tests.
+   */
+  getChannelCloseState(channelId, nowSec = BigInt(Math.floor(Date.now() / 1e3))) {
+    const t = this.channels.get(channelId);
+    if (!t || t.closedAt === void 0) return "open";
+    if (t.settledAt !== void 0) return "settled";
+    if (t.settleableAt !== void 0 && nowSec >= t.settleableAt) return "settleable";
+    return "closing";
+  }
   /**
    * Gets all tracked channel IDs.
    */
@@ -3649,7 +3811,10 @@ var JsonFileChannelStore = class {
     const data = this.readFile();
     data[channelId] = {
       nonce: tracking.nonce,
-      cumulativeAmount: tracking.cumulativeAmount.toString()
+      cumulativeAmount: tracking.cumulativeAmount.toString(),
+      ...tracking.closedAt !== void 0 ? { closedAt: tracking.closedAt.toString() } : {},
+      ...tracking.settleableAt !== void 0 ? { settleableAt: tracking.settleableAt.toString() } : {},
+      ...tracking.settledAt !== void 0 ? { settledAt: tracking.settledAt.toString() } : {}
     };
     this.writeFile(data);
   }
@@ -3659,7 +3824,10 @@ var JsonFileChannelStore = class {
     if (!entry) return void 0;
     return {
       nonce: entry.nonce,
-      cumulativeAmount: BigInt(entry.cumulativeAmount)
+      cumulativeAmount: BigInt(entry.cumulativeAmount),
+      ...entry.closedAt !== void 0 ? { closedAt: BigInt(entry.closedAt) } : {},
+      ...entry.settleableAt !== void 0 ? { settleableAt: BigInt(entry.settleableAt) } : {},
+      ...entry.settledAt !== void 0 ? { settledAt: BigInt(entry.settledAt) } : {}
     };
   }
   list() {
@@ -4789,6 +4957,60 @@ var ToonClient = class {
       depositTotal: result.depositTotal.toString()
     };
   }
+  /**
+   * Close a channel to begin the settlement grace period (first half of
+   * withdraw). Records `closedAt`/`settleableAt` (unix seconds) on the tracked
+   * channel — persisted, so the grace timer survives a daemon restart. Spends
+   * on-chain. EVM today; Solana/Mina are follow-ups.
+   */
+  async closeChannel(channelId) {
+    if (!this.channelManager) throw new Error("ChannelManager not initialized");
+    if (!this.onChainChannelClient) {
+      throw new Error("On-chain channel client not configured (no chainRpcUrls).");
+    }
+    const r = await this.onChainChannelClient.closeChannel(channelId);
+    this.channelManager.setChannelClosed(channelId, r.closedAt, r.settleableAt);
+    return {
+      channelId,
+      ...r.txHash ? { txHash: r.txHash } : {},
+      closedAt: r.closedAt.toString(),
+      settleableAt: r.settleableAt.toString()
+    };
+  }
+  /**
+   * Settle a closed channel to release collateral (second half of withdraw).
+   * THE time guard: never settle before `settleableAt`. A too-early call throws
+   * a retryable error (carrying the remaining seconds) BEFORE spending gas — the
+   * contract would revert anyway. Spends on-chain. EVM today.
+   */
+  async settleChannel(channelId) {
+    if (!this.channelManager) throw new Error("ChannelManager not initialized");
+    if (!this.onChainChannelClient) {
+      throw new Error("On-chain channel client not configured (no chainRpcUrls).");
+    }
+    const settleableAt = this.channelManager.getSettleableAt(channelId);
+    if (settleableAt === void 0) {
+      throw new Error(`Channel "${channelId}" is not closed; call closeChannel first.`);
+    }
+    const nowSec = BigInt(Math.floor(Date.now() / 1e3));
+    if (nowSec < settleableAt) {
+      const remaining = settleableAt - nowSec;
+      throw Object.assign(
+        new Error(
+          `Channel "${channelId}" is not settleable yet \u2014 ${remaining}s remain (settleable at ${settleableAt}).`
+        ),
+        { name: "SettleTooEarlyError", retryable: true, settleableAt: settleableAt.toString() }
+      );
+    }
+    const r = await this.onChainChannelClient.settleChannel(channelId);
+    this.channelManager.setChannelSettled(channelId, nowSec);
+    return { channelId, ...r.txHash ? { txHash: r.txHash } : {} };
+  }
+  /** Where a tracked channel sits in the withdraw journey. */
+  getChannelCloseState(channelId) {
+    if (!this.channelManager) throw new Error("ChannelManager not initialized");
+    return this.channelManager.getChannelCloseState(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