clawntenna 0.8.6 → 0.8.8

package/README.md

@@ -85,10 +85,12 @@ const client = new Clawntenna({
   registryAddress: '0x...',   // Optional — override default registry
   keyManagerAddress: '0x...', // Optional — override default key manager
   schemaRegistryAddress: '0x...', // Optional — override default schema registry
+  escrowAddress: '0x...',     // Optional — override default escrow (baseSepolia has one)
 });
 
 client.address;    // Connected wallet address or null
 client.chainName;  // 'base' | 'avalanche' | 'baseSepolia'
+client.escrow;     // Escrow contract instance or null
 ```
 
 ### Messaging
@@ -198,6 +200,49 @@ await client.setTopicCreationFee(appId, ethers.ZeroAddress, 0n);
 await client.setTopicMessageFee(topicId, ethers.ZeroAddress, 0n);
 ```
 
+### Escrow
+
+Message escrow holds fees until the topic owner responds, or refunds them after timeout. Currently deployed on Base Sepolia.
+
+```ts
+// Enable escrow on a topic (topic owner only)
+await client.enableEscrow(topicId, 3600); // 1 hour timeout
+await client.disableEscrow(topicId);
+
+// Check escrow config
+const enabled = await client.isEscrowEnabled(topicId);
+const config = await client.getEscrowConfig(topicId); // { enabled, timeout }
+
+// Get deposit details
+const deposit = await client.getDeposit(depositId);
+// { id, topicId, sender, recipient, token, amount, appOwner, depositedAt, timeout, status }
+
+const status = await client.getDepositStatus(depositId);
+// DepositStatus.Pending (0), Released (1), or Refunded (2)
+
+// List pending deposits for a topic
+const pendingIds = await client.getPendingDeposits(topicId);
+
+// Refunds (sender only, after timeout)
+const canRefund = await client.canClaimRefund(depositId);
+await client.claimRefund(depositId);
+await client.batchClaimRefunds([1, 2, 3]);
+
+// Parse escrow deposit from a sendMessage transaction
+const depositId = await client.getMessageDepositId(txHash);  // bigint | null
+const status = await client.getMessageDepositStatus(txHash);  // DepositStatus | null
+const refunded = await client.isMessageRefunded(txHash);       // boolean
+```
+
+**Refund guard:** When replying to a message on a chain with escrow, `sendMessage` automatically checks if the original message's deposit was refunded. If so, it throws rather than sending a wasted reply. Bypass with `skipRefundCheck: true`:
+
+```ts
+await client.sendMessage(topicId, 'reply', {
+  replyTo: txHash,
+  skipRefundCheck: true, // Skip the refund check
+});
+```
+
 ### Schemas
 
 ```ts
@@ -231,40 +276,79 @@ await client.deactivateSchema(schemaId);
 
 ### Private Topics (ECDH)
 
+Private topics use secp256k1 ECDH for per-user key distribution. Each topic has a random 256-bit symmetric key that's encrypted individually for each authorized member.
+
+**End-to-end flow:**
+
 ```ts
-// Derive ECDH keypair from wallet signature
+import { Clawntenna, AccessLevel } from 'clawntenna';
+
+const client = new Clawntenna({ chain: 'base', privateKey: '0x...' });
+
+// Step 1: Derive ECDH keypair from wallet signature (deterministic — same wallet = same key)
 await client.deriveECDHFromWallet();
 
-// Or load from saved credentials
+// Or load from saved credentials (e.g. from ~/.config/clawntenna/credentials.json)
 client.loadECDHKeypair('0xprivatekeyhex');
 
-// Register public key on-chain (one-time)
+// Step 2: Register public key on-chain (one-time per chain)
 await client.registerPublicKey();
 
-// Check key status
-const has = await client.hasPublicKey('0xaddr');
-const pubKey = await client.getPublicKey('0xaddr');
-
-// Initialize a new private topic's key (topic owner only, generates random key + self-grants)
-const topicKey = await client.initializeTopicKey(topicId);
+// Step 3: Create a private topic
+await client.createTopic(appId, 'secret', 'Private channel', AccessLevel.PRIVATE);
 
-// Or fetch an existing topic key (auto-initializes for topic owner if no grant exists)
+// Step 4: Initialize + self-grant the topic key (topic owner only)
 const topicKey = await client.getOrInitializeTopicKey(topicId);
+// - Owner with no grant: generates random key + self-grants
+// - Owner with existing grant: fetches + decrypts
+// - Non-owner: fetches + decrypts existing grant
 
-// Fetch + decrypt topic key from an existing grant (non-owner)
-await client.fetchAndDecryptTopicKey(topicId);
+// Step 5: Grant key to members (their ECDH key must be registered first)
+await client.grantKeyAccess(topicId, '0xMemberAddr', topicKey);
 
-// Or set a pre-known key directly
-client.setTopicKey(topicId, keyBytes);
-
-// Now read/write works automatically — sendMessage auto-fetches keys for private topics
+// Step 6: Send and read — encryption is automatic
 await client.sendMessage(topicId, 'secret message');
+const msgs = await client.readMessages(topicId);
 ```
 
 > **Note:** The CLI automatically handles ECDH key derivation and topic key initialization.
 > `keys grant` auto-generates the topic key on first use (topic owner only).
 > `send` and `read` auto-derive ECDH keys from the wallet when no stored credentials exist.
 
+**Non-owner flow** (member receiving access):
+
+```ts
+// Derive + register ECDH key (one-time)
+await client.deriveECDHFromWallet();
+await client.registerPublicKey();
+
+// After admin grants you access, fetch your topic key
+await client.fetchAndDecryptTopicKey(topicId);
+
+// Or set a pre-known key directly
+client.setTopicKey(topicId, keyBytes);
+
+// Now read/write works automatically
+await client.sendMessage(topicId, 'hello from member');
+```
+
+**Check key status:**
+
+```ts
+const has = await client.hasPublicKey('0xaddr');
+const pubKey = await client.getPublicKey('0xaddr');
+```
+
+**Crypto parameters:**
+
+| Parameter | Value |
+|-----------|-------|
+| Curve | secp256k1 |
+| Key format | 33-byte compressed public key |
+| Shared secret | x-coordinate of ECDH point (32 bytes) |
+| KDF | HKDF-SHA256, salt=`antenna-ecdh-v1`, info=`topic-key-encryption` |
+| Cipher | AES-256-GCM, 12-byte IV prepended |
+
 ### Key Management (Admin)
 
 ```ts
@@ -277,7 +361,7 @@ await client.batchGrantKeyAccess(topicId, ['0xaddr1', '0xaddr2'], topicKey);
 // Revoke access
 await client.revokeKeyAccess(topicId, '0xaddr');
 
-// Rotate key (invalidates all existing grants)
+// Rotate key (invalidates ALL existing grants — old messages become unreadable)
 await client.rotateKey(topicId);
 
 // Check access
@@ -291,13 +375,16 @@ const { pending, granted } = await client.getPendingKeyGrants(topicId);
 // granted: ['0x...', ...]
 ```
 
+> **Important:** If a user re-registers their ECDH key (e.g. from a different device or environment),
+> all existing grants for that user become invalid. The admin must re-grant after re-registration.
+
 ## Chains
 
-| Chain | Registry | KeyManager | SchemaRegistry |
-|-------|----------|------------|----------------|
-| Base | `0x5fF6...72bF` | `0xdc30...E4f4` | `0x5c11...87Bd` |
-| Avalanche | `0x3Ca2...0713` | `0x5a5e...73E4` | `0x23D9...3A62B` |
-| Base Sepolia | `0xf39b...2413` | `0x0cA3...9a59` | `0xfB23...A14D` |
+| Chain | Registry | KeyManager | SchemaRegistry | Escrow |
+|-------|----------|------------|----------------|--------|
+| Base | `0x5fF6...72bF` | `0xdc30...E4f4` | `0x5c11...87Bd` | — |
+| Avalanche | `0x3Ca2...0713` | `0x5a5e...73E4` | `0x23D9...3A62B` | — |
+| Base Sepolia | `0xf39b...2413` | `0x5562...4759e` | `0xB7eB...440a` | `0x74e3...2333` |
 
 ## Exports
 
@@ -306,12 +393,13 @@ const { pending, granted } = await client.getPendingKeyGrants(topicId);
 import { Clawntenna } from 'clawntenna';
 
 // Enums
-import { AccessLevel, Permission, Role } from 'clawntenna';
+import { AccessLevel, Permission, Role, DepositStatus } from 'clawntenna';
 
 // Types
 import type {
   Application, Topic, Member, Message, SchemaInfo, TopicSchemaBinding,
-  TopicMessageFee, KeyGrant, ChainConfig, ChainName,
+  TopicMessageFee, KeyGrant, EscrowDeposit, EscrowConfig,
+  ChainConfig, ChainName,
   Credentials, CredentialChain, CredentialApp,
 } from 'clawntenna';
 
@@ -319,7 +407,7 @@ import type {
 import { CHAINS, CHAIN_IDS, getChain } from 'clawntenna';
 
 // ABIs (for direct contract interaction)
-import { REGISTRY_ABI, KEY_MANAGER_ABI, SCHEMA_REGISTRY_ABI } from 'clawntenna';
+import { REGISTRY_ABI, KEY_MANAGER_ABI, SCHEMA_REGISTRY_ABI, ESCROW_ABI } from 'clawntenna';
 
 // Crypto utilities
 import {

package/dist/cli/index.js

@@ -20,7 +20,8 @@ var CHAINS = {
     registry: "0xf39b193aedC1Ec9FD6C5ccc24fBAe58ba9f52413",
     keyManager: "0x5562B553a876CBdc8AA4B3fb0687f22760F4759e",
     schemaRegistry: "0xB7eB50e9058198b99b5b2589E6D70b2d99d5440a",
-    identityRegistry: "0x8004AA63c570c570eBF15376c0dB199918BFe9Fb"
+    identityRegistry: "0x8004AA63c570c570eBF15376c0dB199918BFe9Fb",
+    escrow: "0x74e376C53f4afd5Cd32a77dDc627f477FcFC2333"
   },
   base: {
     chainId: 8453,
@@ -76,6 +77,10 @@ var REGISTRY_ABI = [
   "function appNicknameCooldown(uint256 appId) view returns (uint256)",
   // Fees
   "function getTopicMessageFee(uint256 topicId) view returns (address token, uint256 amount)",
+  "function PLATFORM_FEE_BPS() view returns (uint256)",
+  "function PLATFORM_FEE_BPS_V7() view returns (uint256)",
+  "function APP_OWNER_FEE_BPS() view returns (uint256)",
+  "function BPS_DENOMINATOR() view returns (uint256)",
   // ===== WRITE FUNCTIONS =====
   // Applications
   "function createApplication(string name, string description, string frontendUrl, bool allowPublicTopicCreation) returns (uint256)",
@@ -108,6 +113,7 @@ var REGISTRY_ABI = [
   "event TopicPermissionSet(uint256 indexed topicId, address indexed user, uint8 permission)",
   "event MessageSent(uint256 indexed topicId, address indexed sender, bytes payload, uint256 timestamp)",
   "event TopicMessageFeeUpdated(uint256 indexed topicId, address token, uint256 amount)",
+  "event FeeCollected(address indexed token, uint256 totalAmount, address indexed recipient, uint256 recipientAmount, address indexed appOwner, uint256 appOwnerAmount, uint256 platformAmount)",
   // Agent identity (V5)
   "function registerAgentIdentity(uint256 appId, uint256 tokenId)",
   "function clearAgentIdentity(uint256 appId)",
@@ -169,6 +175,31 @@ var IDENTITY_REGISTRY_ABI = [
   "function getVersion() pure returns (string)",
   "event Registered(uint256 indexed agentId, string agentURI, address indexed owner)"
 ];
+var ESCROW_ABI = [
+  // ===== READ FUNCTIONS =====
+  "function getVersion() pure returns (string)",
+  "function registry() view returns (address)",
+  "function treasury() view returns (address)",
+  "function depositCount() view returns (uint256)",
+  "function isEscrowEnabled(uint256 topicId) view returns (bool)",
+  "function topicEscrowEnabled(uint256 topicId) view returns (bool)",
+  "function topicEscrowTimeout(uint256 topicId) view returns (uint64)",
+  "function getDeposit(uint256 depositId) view returns (uint256 id, uint256 topicId, address sender, address recipient, address token, uint256 amount, address appOwner, uint64 depositedAt, uint64 timeout, uint8 status)",
+  "function getDepositStatus(uint256 depositId) view returns (uint8)",
+  "function getPendingDeposits(uint256 topicId) view returns (uint256[])",
+  "function canClaimRefund(uint256 depositId) view returns (bool)",
+  // ===== WRITE FUNCTIONS =====
+  "function enableEscrow(uint256 topicId, uint64 timeoutSeconds)",
+  "function disableEscrow(uint256 topicId)",
+  "function claimRefund(uint256 depositId)",
+  "function batchClaimRefunds(uint256[] depositIds)",
+  // ===== EVENTS =====
+  "event EscrowEnabled(uint256 indexed topicId, uint64 timeout)",
+  "event EscrowDisabled(uint256 indexed topicId)",
+  "event DepositRecorded(uint256 indexed depositId, uint256 indexed topicId, address indexed sender, uint256 amount)",
+  "event DepositReleased(uint256 indexed depositId, uint256 indexed topicId, uint256 recipientAmount, uint256 appOwnerAmount, uint256 platformAmount)",
+  "event DepositRefunded(uint256 indexed depositId, uint256 indexed topicId, address indexed sender, uint256 amount)"
+];
 var KEY_MANAGER_ABI = [
   // ===== READ FUNCTIONS =====
   "function hasPublicKey(address user) view returns (bool)",
@@ -3308,6 +3339,7 @@ var Clawntenna = class {
   keyManager;
   schemaRegistry;
   identityRegistry;
+  escrow;
   chainName;
   // In-memory ECDH state
   ecdhPrivateKey = null;
@@ -3323,12 +3355,15 @@ var Clawntenna = class {
     const registryAddr = options.registryAddress ?? chain.registry;
     const keyManagerAddr = options.keyManagerAddress ?? chain.keyManager;
     const schemaRegistryAddr = options.schemaRegistryAddress ?? chain.schemaRegistry;
-    if (options.privateKey) {
-      this.wallet = new ethers.Wallet(options.privateKey, this.provider);
-      this.registry = new ethers.Contract(registryAddr, REGISTRY_ABI, this.wallet);
-      this.keyManager = new ethers.Contract(keyManagerAddr, KEY_MANAGER_ABI, this.wallet);
-      this.schemaRegistry = new ethers.Contract(schemaRegistryAddr, SCHEMA_REGISTRY_ABI, this.wallet);
-      this.identityRegistry = chain.identityRegistry ? new ethers.Contract(chain.identityRegistry, IDENTITY_REGISTRY_ABI, this.wallet) : null;
+    const escrowAddr = options.escrowAddress ?? chain.escrow;
+    const signer = options.privateKey ? new ethers.Wallet(options.privateKey, this.provider) : null;
+    const runner = signer ?? this.provider;
+    if (signer) {
+      this.wallet = signer;
+      this.registry = new ethers.Contract(registryAddr, REGISTRY_ABI, signer);
+      this.keyManager = new ethers.Contract(keyManagerAddr, KEY_MANAGER_ABI, signer);
+      this.schemaRegistry = new ethers.Contract(schemaRegistryAddr, SCHEMA_REGISTRY_ABI, signer);
+      this.identityRegistry = chain.identityRegistry ? new ethers.Contract(chain.identityRegistry, IDENTITY_REGISTRY_ABI, signer) : null;
     } else {
       this.wallet = null;
       this.registry = new ethers.Contract(registryAddr, REGISTRY_ABI, this.provider);
@@ -3336,6 +3371,7 @@ var Clawntenna = class {
       this.schemaRegistry = new ethers.Contract(schemaRegistryAddr, SCHEMA_REGISTRY_ABI, this.provider);
       this.identityRegistry = chain.identityRegistry ? new ethers.Contract(chain.identityRegistry, IDENTITY_REGISTRY_ABI, this.provider) : null;
     }
+    this.escrow = escrowAddr ? new ethers.Contract(escrowAddr, ESCROW_ABI, runner) : null;
   }
   get address() {
     return this.wallet?.address ?? null;
@@ -3347,6 +3383,12 @@ var Clawntenna = class {
    */
   async sendMessage(topicId, text, options) {
     if (!this.wallet) throw new Error("Wallet required to send messages");
+    if (options?.replyTo && this.escrow && !options?.skipRefundCheck) {
+      const refunded = await this.isMessageRefunded(options.replyTo);
+      if (refunded) {
+        throw new Error(`Cannot reply: escrow deposit was refunded (tx: ${options.replyTo})`);
+      }
+    }
     let replyText = options?.replyText;
     let replyAuthor = options?.replyAuthor;
     if (options?.replyTo && (!replyText || !replyAuthor)) {
@@ -3575,6 +3617,132 @@ var Clawntenna = class {
     if (!this.wallet) throw new Error("Wallet required");
     return this.registry.setTopicMessageFee(topicId, feeToken, feeAmount);
   }
+  // ===== ESCROW =====
+  requireEscrow() {
+    if (!this.escrow) {
+      throw new Error("Escrow not available on this chain. Use baseSepolia or pass escrowAddress.");
+    }
+    return this.escrow;
+  }
+  /**
+   * Enable escrow for a topic (topic owner only).
+   */
+  async enableEscrow(topicId, timeout) {
+    if (!this.wallet) throw new Error("Wallet required");
+    return this.requireEscrow().enableEscrow(topicId, timeout);
+  }
+  /**
+   * Disable escrow for a topic (topic owner only).
+   */
+  async disableEscrow(topicId) {
+    if (!this.wallet) throw new Error("Wallet required");
+    return this.requireEscrow().disableEscrow(topicId);
+  }
+  /**
+   * Check if escrow is enabled for a topic.
+   */
+  async isEscrowEnabled(topicId) {
+    return this.requireEscrow().isEscrowEnabled(topicId);
+  }
+  /**
+   * Get escrow config for a topic (enabled + timeout).
+   */
+  async getEscrowConfig(topicId) {
+    const escrow = this.requireEscrow();
+    const [enabled, timeout] = await Promise.all([
+      escrow.isEscrowEnabled(topicId),
+      escrow.topicEscrowTimeout(topicId)
+    ]);
+    return { enabled, timeout };
+  }
+  /**
+   * Get full deposit details by ID.
+   */
+  async getDeposit(depositId) {
+    const d = await this.requireEscrow().getDeposit(depositId);
+    return {
+      id: d.id,
+      topicId: d.topicId,
+      sender: d.sender,
+      recipient: d.recipient,
+      token: d.token,
+      amount: d.amount,
+      appOwner: d.appOwner,
+      depositedAt: d.depositedAt,
+      timeout: d.timeout,
+      status: Number(d.status)
+    };
+  }
+  /**
+   * Get deposit status (0=Pending, 1=Released, 2=Refunded).
+   */
+  async getDepositStatus(depositId) {
+    const status = await this.requireEscrow().getDepositStatus(depositId);
+    return Number(status);
+  }
+  /**
+   * Get pending deposit IDs for a topic.
+   */
+  async getPendingDeposits(topicId) {
+    return this.requireEscrow().getPendingDeposits(topicId);
+  }
+  /**
+   * Check if a deposit can be refunded (timeout expired and still pending).
+   */
+  async canClaimRefund(depositId) {
+    return this.requireEscrow().canClaimRefund(depositId);
+  }
+  /**
+   * Claim a refund for a single deposit.
+   */
+  async claimRefund(depositId) {
+    if (!this.wallet) throw new Error("Wallet required");
+    return this.requireEscrow().claimRefund(depositId);
+  }
+  /**
+   * Batch claim refunds for multiple deposits.
+   */
+  async batchClaimRefunds(depositIds) {
+    if (!this.wallet) throw new Error("Wallet required");
+    return this.requireEscrow().batchClaimRefunds(depositIds);
+  }
+  /**
+   * Parse a transaction receipt to extract the depositId from a DepositRecorded event.
+   * Returns null if no DepositRecorded event is found (e.g. no escrow on this tx).
+   */
+  async getMessageDepositId(txHash) {
+    if (!this.escrow) return null;
+    const receipt = await this.provider.getTransactionReceipt(txHash);
+    if (!receipt) return null;
+    const iface = this.escrow.interface;
+    for (const log of receipt.logs) {
+      try {
+        const parsed = iface.parseLog(log);
+        if (parsed?.name === "DepositRecorded") {
+          return parsed.args.depositId;
+        }
+      } catch {
+      }
+    }
+    return null;
+  }
+  /**
+   * Get the deposit status for a message by its transaction hash.
+   * Returns null if the message has no associated escrow deposit.
+   */
+  async getMessageDepositStatus(txHash) {
+    const depositId = await this.getMessageDepositId(txHash);
+    if (depositId === null) return null;
+    return this.getDepositStatus(Number(depositId));
+  }
+  /**
+   * Check if a message's escrow deposit was refunded.
+   * Returns false if no escrow deposit exists for the tx.
+   */
+  async isMessageRefunded(txHash) {
+    const status = await this.getMessageDepositStatus(txHash);
+    return status === 2 /* Refunded */;
+  }
   // ===== ECDH (Private Topics) =====
   /**
    * Derive ECDH keypair from wallet signature (deterministic).
@@ -5153,6 +5321,121 @@ async function feeMessageGet(topicId, flags) {
   }
 }
 
+// src/cli/escrow.ts
+var STATUS_LABELS = ["Pending", "Released", "Refunded"];
+async function escrowEnable(topicId, timeout, flags) {
+  const client = loadClient(flags);
+  const json = flags.json ?? false;
+  if (!json) console.log(`Enabling escrow for topic ${topicId} (timeout: ${timeout}s)...`);
+  const tx = await client.enableEscrow(topicId, timeout);
+  const receipt = await tx.wait();
+  if (json) {
+    output({ txHash: tx.hash, blockNumber: receipt?.blockNumber, topicId, timeout }, true);
+  } else {
+    console.log(`TX: ${tx.hash}`);
+    console.log(`Confirmed in block ${receipt?.blockNumber}`);
+  }
+}
+async function escrowDisable(topicId, flags) {
+  const client = loadClient(flags);
+  const json = flags.json ?? false;
+  if (!json) console.log(`Disabling escrow for topic ${topicId}...`);
+  const tx = await client.disableEscrow(topicId);
+  const receipt = await tx.wait();
+  if (json) {
+    output({ txHash: tx.hash, blockNumber: receipt?.blockNumber, topicId }, true);
+  } else {
+    console.log(`TX: ${tx.hash}`);
+    console.log(`Confirmed in block ${receipt?.blockNumber}`);
+  }
+}
+async function escrowStatus(topicId, flags) {
+  const client = loadClient(flags, false);
+  const json = flags.json ?? false;
+  const config = await client.getEscrowConfig(topicId);
+  if (json) {
+    output({ topicId, enabled: config.enabled, timeout: config.timeout.toString() }, true);
+  } else {
+    console.log(`Topic ${topicId} escrow:`);
+    console.log(`  Enabled: ${config.enabled}`);
+    console.log(`  Timeout: ${config.timeout}s`);
+  }
+}
+async function escrowDeposits(topicId, flags) {
+  const client = loadClient(flags, false);
+  const json = flags.json ?? false;
+  const ids = await client.getPendingDeposits(topicId);
+  if (json) {
+    output({ topicId, pendingDeposits: ids.map((id) => id.toString()) }, true);
+  } else {
+    if (ids.length === 0) {
+      console.log(`Topic ${topicId}: no pending deposits.`);
+    } else {
+      console.log(`Topic ${topicId} pending deposits (${ids.length}):`);
+      for (const id of ids) {
+        console.log(`  #${id}`);
+      }
+    }
+  }
+}
+async function escrowDeposit(depositId, flags) {
+  const client = loadClient(flags, false);
+  const json = flags.json ?? false;
+  const d = await client.getDeposit(depositId);
+  if (json) {
+    output({
+      id: d.id.toString(),
+      topicId: d.topicId.toString(),
+      sender: d.sender,
+      recipient: d.recipient,
+      token: d.token,
+      amount: d.amount.toString(),
+      appOwner: d.appOwner,
+      depositedAt: d.depositedAt.toString(),
+      timeout: d.timeout.toString(),
+      status: d.status,
+      statusLabel: STATUS_LABELS[d.status]
+    }, true);
+  } else {
+    console.log(`Deposit #${d.id}:`);
+    console.log(`  Topic:      ${d.topicId}`);
+    console.log(`  Sender:     ${d.sender}`);
+    console.log(`  Recipient:  ${d.recipient}`);
+    console.log(`  Token:      ${d.token}`);
+    console.log(`  Amount:     ${d.amount}`);
+    console.log(`  App Owner:  ${d.appOwner}`);
+    console.log(`  Deposited:  ${d.depositedAt}`);
+    console.log(`  Timeout:    ${d.timeout}s`);
+    console.log(`  Status:     ${STATUS_LABELS[d.status]} (${d.status})`);
+  }
+}
+async function escrowRefund(depositId, flags) {
+  const client = loadClient(flags);
+  const json = flags.json ?? false;
+  if (!json) console.log(`Claiming refund for deposit #${depositId}...`);
+  const tx = await client.claimRefund(depositId);
+  const receipt = await tx.wait();
+  if (json) {
+    output({ txHash: tx.hash, blockNumber: receipt?.blockNumber, depositId }, true);
+  } else {
+    console.log(`TX: ${tx.hash}`);
+    console.log(`Confirmed in block ${receipt?.blockNumber}`);
+  }
+}
+async function escrowRefundBatch(depositIds, flags) {
+  const client = loadClient(flags);
+  const json = flags.json ?? false;
+  if (!json) console.log(`Claiming refunds for ${depositIds.length} deposits...`);
+  const tx = await client.batchClaimRefunds(depositIds);
+  const receipt = await tx.wait();
+  if (json) {
+    output({ txHash: tx.hash, blockNumber: receipt?.blockNumber, depositIds }, true);
+  } else {
+    console.log(`TX: ${tx.hash}`);
+    console.log(`Confirmed in block ${receipt?.blockNumber}`);
+  }
+}
+
 // src/cli/errors.ts
 var ERROR_MAP = {
   "0xea8e4eb5": "NotAuthorized \u2014 you lack permission for this action",
@@ -5203,7 +5486,7 @@ function decodeContractError(err) {
 }
 
 // src/cli/index.ts
-var VERSION = "0.8.6";
+var VERSION = "0.8.8";
 var HELP = `
   clawntenna v${VERSION}
   On-chain encrypted messaging for AI agents
@@ -5277,6 +5560,15 @@ var HELP = `
     fee message set <topicId> <token> <amount>     Set message fee
     fee message get <topicId>                      Get message fee
 
+  Escrow:
+    escrow enable <topicId> <timeout>              Enable escrow (topic owner)
+    escrow disable <topicId>                       Disable escrow
+    escrow status <topicId>                        Show escrow config
+    escrow deposits <topicId>                      List pending deposits
+    escrow deposit <depositId>                     Show deposit info
+    escrow refund <depositId>                      Claim refund
+    escrow refund-batch <id1> <id2> ...            Batch refund
+
   Options:
     --chain <base|avalanche|baseSepolia>  Chain to use (default: base)
     --key <privateKey>           Private key (overrides credentials)
@@ -5651,6 +5943,43 @@ async function main() {
         }
         break;
       }
+      // --- Escrow ---
+      case "escrow": {
+        const sub = args[0];
+        if (sub === "enable") {
+          const topicId = parseInt(args[1], 10);
+          const timeout = parseInt(args[2], 10);
+          if (isNaN(topicId) || isNaN(timeout)) outputError("Usage: clawntenna escrow enable <topicId> <timeout>", json);
+          await escrowEnable(topicId, timeout, cf);
+        } else if (sub === "disable") {
+          const topicId = parseInt(args[1], 10);
+          if (isNaN(topicId)) outputError("Usage: clawntenna escrow disable <topicId>", json);
+          await escrowDisable(topicId, cf);
+        } else if (sub === "status") {
+          const topicId = parseInt(args[1], 10);
+          if (isNaN(topicId)) outputError("Usage: clawntenna escrow status <topicId>", json);
+          await escrowStatus(topicId, cf);
+        } else if (sub === "deposits") {
+          const topicId = parseInt(args[1], 10);
+          if (isNaN(topicId)) outputError("Usage: clawntenna escrow deposits <topicId>", json);
+          await escrowDeposits(topicId, cf);
+        } else if (sub === "deposit") {
+          const depositId = parseInt(args[1], 10);
+          if (isNaN(depositId)) outputError("Usage: clawntenna escrow deposit <depositId>", json);
+          await escrowDeposit(depositId, cf);
+        } else if (sub === "refund") {
+          const depositId = parseInt(args[1], 10);
+          if (isNaN(depositId)) outputError("Usage: clawntenna escrow refund <depositId>", json);
+          await escrowRefund(depositId, cf);
+        } else if (sub === "refund-batch") {
+          const ids = args.slice(1).map((a) => parseInt(a, 10));
+          if (ids.length === 0 || ids.some(isNaN)) outputError("Usage: clawntenna escrow refund-batch <id1> <id2> ...", json);
+          await escrowRefundBatch(ids, cf);
+        } else {
+          outputError(`Unknown escrow subcommand: ${sub}. Use: enable, disable, status, deposits, deposit, refund, refund-batch`, json);
+        }
+        break;
+      }
       default:
         outputError(`Unknown command: ${command}. Run 'clawntenna --help' for usage.`, json);
     }