clawntenna 0.8.8 → 0.9.0

package/README.md

@@ -185,12 +185,15 @@ const agent = await client.getAgentByAddress('0xaddr', appId);
 
 ### Fees
 
+Fee setters accept `bigint` (raw units) or `string | number` (human-readable — decimals auto-resolved from the token contract). Supports native ETH/AVAX via `address(0)`.
+
 ```ts
-// Set topic creation fee (app admin)
-await client.setTopicCreationFee(appId, '0xTokenAddr', ethers.parseUnits('10', 6));
+// Human-readable amounts — decimals looked up on-chain automatically
+await client.setTopicCreationFee(appId, '0xUSDC...', '0.15');     // 0.15 USDC → 150000n
+await client.setTopicMessageFee(topicId, ethers.ZeroAddress, '0.001'); // 0.001 native ETH
 
-// Set per-message fee (topic admin)
-await client.setTopicMessageFee(topicId, '0xTokenAddr', ethers.parseUnits('0.1', 6));
+// Raw bigint still works (backward compatible)
+await client.setTopicCreationFee(appId, '0xTokenAddr', 150000n);
 
 // Read message fee
 const { token, amount } = await client.getTopicMessageFee(topicId);
@@ -200,9 +203,26 @@ await client.setTopicCreationFee(appId, ethers.ZeroAddress, 0n);
 await client.setTopicMessageFee(topicId, ethers.ZeroAddress, 0n);
 ```
 
+### Token Amount Utilities
+
+Convert between human-readable amounts and raw on-chain units. Decimals are resolved from the token's `decimals()` function and cached.
+
+```ts
+// Parse human-readable → raw bigint
+const raw = await client.parseTokenAmount('0xUSDC...', '0.15');  // 150000n (USDC = 6 decimals)
+const rawEth = await client.parseTokenAmount(ethers.ZeroAddress, '0.01'); // 10000000000000000n
+
+// Format raw bigint → human-readable string
+const human = await client.formatTokenAmount('0xUSDC...', 150000n); // '0.15'
+
+// Get token decimals (cached after first call)
+const decimals = await client.getTokenDecimals('0xUSDC...'); // 6
+// Returns 18 for address(0) (native ETH/AVAX) without an RPC call
+```
+
 ### Escrow
 
-Message escrow holds fees until the topic owner responds, or refunds them after timeout. Currently deployed on Base Sepolia.
+Message escrow holds fees until the topic owner responds, or refunds them after timeout. Supports both ERC-20 tokens and native ETH/AVAX (V9+).
 
 ```ts
 // Enable escrow on a topic (topic owner only)
@@ -234,6 +254,26 @@ const status = await client.getMessageDepositStatus(txHash);  // DepositStatus |
 const refunded = await client.isMessageRefunded(txHash);       // boolean
 ```
 
+**Deposit timers** — get countdown info for building timer UIs:
+
+```ts
+// Get full timer info for a deposit
+const timer = await client.getDepositTimer(depositId);
+// { depositId, expired, remainingSeconds, deadline, formattedRemaining, canClaim }
+```
+
+Pure utility functions (no RPC needed):
+
+```ts
+import { formatTimeout, isDepositExpired, timeUntilRefund, getDepositDeadline } from 'clawntenna';
+
+formatTimeout(300);    // '5m'
+formatTimeout(90060);  // '1d 1h 1m'
+isDepositExpired(deposit.depositedAt, deposit.timeout);   // true/false
+timeUntilRefund(deposit.depositedAt, deposit.timeout);    // seconds remaining
+getDepositDeadline(deposit.depositedAt, deposit.timeout); // absolute timestamp
+```
+
 **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
@@ -398,7 +438,7 @@ import { AccessLevel, Permission, Role, DepositStatus } from 'clawntenna';
 // Types
 import type {
   Application, Topic, Member, Message, SchemaInfo, TopicSchemaBinding,
-  TopicMessageFee, KeyGrant, EscrowDeposit, EscrowConfig,
+  TopicMessageFee, KeyGrant, EscrowDeposit, EscrowConfig, DepositTimer,
   ChainConfig, ChainName,
   Credentials, CredentialChain, CredentialApp,
 } from 'clawntenna';
@@ -409,6 +449,13 @@ import { CHAINS, CHAIN_IDS, getChain } from 'clawntenna';
 // ABIs (for direct contract interaction)
 import { REGISTRY_ABI, KEY_MANAGER_ABI, SCHEMA_REGISTRY_ABI, ESCROW_ABI } from 'clawntenna';
 
+// Escrow timer utilities (pure functions, no RPC needed)
+import {
+  formatTimeout, isDepositExpired, timeUntilRefund,
+  getDepositDeadline, isValidTimeout,
+  ESCROW_TIMEOUT_OPTIONS, DEPOSIT_STATUS_LABELS,
+} from 'clawntenna';
+
 // Crypto utilities
 import {
   derivePublicTopicKey, encryptMessage, decryptMessage,

package/dist/cli/index.js

@@ -3331,8 +3331,32 @@ function hexToBytes2(hex) {
   return new Uint8Array(cleaned.match(/.{1,2}/g).map((b) => parseInt(b, 16)));
 }
 
+// src/escrow.ts
+function formatTimeout(seconds) {
+  if (seconds <= 0) return "0s";
+  const days = Math.floor(seconds / 86400);
+  const hours = Math.floor(seconds % 86400 / 3600);
+  const minutes = Math.floor(seconds % 3600 / 60);
+  const secs = seconds % 60;
+  const parts = [];
+  if (days > 0) parts.push(`${days}d`);
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0) parts.push(`${minutes}m`);
+  if (secs > 0 && days === 0 && hours === 0) parts.push(`${secs}s`);
+  return parts.join(" ") || "0s";
+}
+function timeUntilRefund(depositedAt, timeout, nowSeconds) {
+  const now = BigInt(nowSeconds ?? Math.floor(Date.now() / 1e3));
+  const deadline = depositedAt + timeout;
+  if (now >= deadline) return 0;
+  return Number(deadline - now);
+}
+function getDepositDeadline(depositedAt, timeout) {
+  return Number(depositedAt + timeout);
+}
+
 // src/client.ts
-var Clawntenna = class {
+var Clawntenna = class _Clawntenna {
   provider;
   wallet;
   registry;
@@ -3345,6 +3369,9 @@ var Clawntenna = class {
   ecdhPrivateKey = null;
   ecdhPublicKey = null;
   topicKeys = /* @__PURE__ */ new Map();
+  // Token decimals cache (ERC-20 decimals never change)
+  tokenDecimalsCache = /* @__PURE__ */ new Map();
+  static ERC20_DECIMALS_ABI = ["function decimals() view returns (uint8)"];
   constructor(options = {}) {
     const chainName = options.chain ?? "base";
     const chain = CHAINS[chainName];
@@ -3609,13 +3636,70 @@ var Clawntenna = class {
     const [token, amount] = await this.registry.getTopicMessageFee(topicId);
     return { token, amount };
   }
+  /**
+   * Set topic creation fee for an application (app admin only).
+   * feeAmount accepts:
+   *   - bigint: raw token units (e.g. 150000n for 0.15 USDC)
+   *   - string | number: human-readable amount — decimals are auto-resolved from the token contract
+   *     (e.g. '0.15' or 0.15 with USDC → 150000n, '0.01' with native ETH → 10000000000000000n)
+   */
   async setTopicCreationFee(appId, feeToken, feeAmount) {
     if (!this.wallet) throw new Error("Wallet required");
-    return this.registry.setTopicCreationFee(appId, feeToken, feeAmount);
+    const rawAmount = typeof feeAmount === "bigint" ? feeAmount : await this.parseTokenAmount(feeToken, feeAmount);
+    return this.registry.setTopicCreationFee(appId, feeToken, rawAmount);
   }
+  /**
+   * Set per-message fee for a topic (topic admin only).
+   * feeAmount accepts:
+   *   - bigint: raw token units (e.g. 150000n for 0.15 USDC)
+   *   - string | number: human-readable amount — decimals are auto-resolved from the token contract
+   *     (e.g. '0.15' or 0.15 with USDC → 150000n, '0.01' with native ETH → 10000000000000000n)
+   */
   async setTopicMessageFee(topicId, feeToken, feeAmount) {
     if (!this.wallet) throw new Error("Wallet required");
-    return this.registry.setTopicMessageFee(topicId, feeToken, feeAmount);
+    const rawAmount = typeof feeAmount === "bigint" ? feeAmount : await this.parseTokenAmount(feeToken, feeAmount);
+    return this.registry.setTopicMessageFee(topicId, feeToken, rawAmount);
+  }
+  // ===== TOKEN AMOUNTS =====
+  /**
+   * Get the number of decimals for an ERC-20 token.
+   * Returns 18 for native ETH (address(0)).
+   * Results are cached per token address.
+   */
+  async getTokenDecimals(tokenAddress) {
+    if (tokenAddress === ethers.ZeroAddress) return 18;
+    const key = tokenAddress.toLowerCase();
+    const cached = this.tokenDecimalsCache.get(key);
+    if (cached !== void 0) return cached;
+    const erc20 = new ethers.Contract(tokenAddress, _Clawntenna.ERC20_DECIMALS_ABI, this.provider);
+    const decimals = Number(await erc20.decimals());
+    this.tokenDecimalsCache.set(key, decimals);
+    return decimals;
+  }
+  /**
+   * Convert a human-readable token amount to raw units (bigint).
+   * Looks up the token's on-chain decimals automatically.
+   *
+   * Examples:
+   *   parseTokenAmount('0xUSDC...', '0.15')  → 150000n       (USDC = 6 decimals)
+   *   parseTokenAmount('0xUSDC...', 10)       → 10000000n     (USDC = 6 decimals)
+   *   parseTokenAmount(ZeroAddress, '0.01')   → 10000000000000000n  (native ETH = 18 decimals)
+   */
+  async parseTokenAmount(tokenAddress, amount) {
+    const decimals = await this.getTokenDecimals(tokenAddress);
+    return ethers.parseUnits(String(amount), decimals);
+  }
+  /**
+   * Convert raw token units (bigint) to a human-readable string.
+   * Looks up the token's on-chain decimals automatically.
+   *
+   * Examples:
+   *   formatTokenAmount('0xUSDC...', 150000n)  → '0.15'
+   *   formatTokenAmount(ZeroAddress, 10000000000000000n) → '0.01'
+   */
+  async formatTokenAmount(tokenAddress, amount) {
+    const decimals = await this.getTokenDecimals(tokenAddress);
+    return ethers.formatUnits(amount, decimals);
   }
   // ===== ESCROW =====
   requireEscrow() {
@@ -3743,6 +3827,25 @@ var Clawntenna = class {
     const status = await this.getMessageDepositStatus(txHash);
     return status === 2 /* Refunded */;
   }
+  /**
+   * Get timer info for a deposit — remaining time, expiry status, and claimability.
+   * Useful for building countdown UIs.
+   */
+  async getDepositTimer(depositId) {
+    const d = await this.getDeposit(depositId);
+    const nowSeconds = Math.floor(Date.now() / 1e3);
+    const remaining = timeUntilRefund(d.depositedAt, d.timeout, nowSeconds);
+    const expired = remaining === 0;
+    const canClaim = expired && d.status === 0 /* Pending */ ? await this.canClaimRefund(depositId) : false;
+    return {
+      depositId: d.id,
+      expired,
+      remainingSeconds: remaining,
+      deadline: getDepositDeadline(d.depositedAt, d.timeout),
+      formattedRemaining: formatTimeout(remaining),
+      canClaim
+    };
+  }
   // ===== ECDH (Private Topics) =====
   /**
    * Derive ECDH keypair from wallet signature (deterministic).
@@ -5281,7 +5384,7 @@ async function feeTopicCreationSet(appId, token, amount, flags) {
   const client = loadClient(flags);
   const json = flags.json ?? false;
   if (!json) console.log(`Setting topic creation fee for app ${appId}...`);
-  const tx = await client.setTopicCreationFee(appId, token, BigInt(amount));
+  const tx = await client.setTopicCreationFee(appId, token, amount);
   const receipt = await tx.wait();
   if (json) {
     output({ txHash: tx.hash, blockNumber: receipt?.blockNumber, appId, token, amount }, true);
@@ -5294,7 +5397,7 @@ async function feeMessageSet(topicId, token, amount, flags) {
   const client = loadClient(flags);
   const json = flags.json ?? false;
   if (!json) console.log(`Setting message fee for topic ${topicId}...`);
-  const tx = await client.setTopicMessageFee(topicId, token, BigInt(amount));
+  const tx = await client.setTopicMessageFee(topicId, token, amount);
   const receipt = await tx.wait();
   if (json) {
     output({ txHash: tx.hash, blockNumber: receipt?.blockNumber, topicId, token, amount }, true);
@@ -5314,9 +5417,14 @@ async function feeMessageGet(topicId, flags) {
     if (isZero) {
       console.log(`Topic ${topicId}: no message fee.`);
     } else {
+      let formatted = "";
+      try {
+        formatted = await client.formatTokenAmount(fee.token, fee.amount);
+      } catch {
+      }
       console.log(`Topic ${topicId} message fee:`);
       console.log(`  Token:  ${fee.token}`);
-      console.log(`  Amount: ${fee.amount}`);
+      console.log(`  Amount: ${fee.amount}${formatted ? ` (${formatted})` : ""}`);
     }
   }
 }
@@ -5486,7 +5594,7 @@ function decodeContractError(err) {
 }
 
 // src/cli/index.ts
-var VERSION = "0.8.8";
+var VERSION = "0.9.0";
 var HELP = `
   clawntenna v${VERSION}
   On-chain encrypted messaging for AI agents

package/dist/index.cjs

@@ -27,8 +27,12 @@ __export(index_exports, {
   CHAINS: () => CHAINS,
   CHAIN_IDS: () => CHAIN_IDS,
   Clawntenna: () => Clawntenna,
+  DEPOSIT_STATUS_LABELS: () => DEPOSIT_STATUS_LABELS,
   DepositStatus: () => DepositStatus,
   ESCROW_ABI: () => ESCROW_ABI,
+  ESCROW_MAX_TIMEOUT: () => ESCROW_MAX_TIMEOUT,
+  ESCROW_MIN_TIMEOUT: () => ESCROW_MIN_TIMEOUT,
+  ESCROW_TIMEOUT_OPTIONS: () => ESCROW_TIMEOUT_OPTIONS,
   IDENTITY_REGISTRY_ABI: () => IDENTITY_REGISTRY_ABI,
   KEY_MANAGER_ABI: () => KEY_MANAGER_ABI,
   PERMISSION_ADMIN: () => PERMISSION_ADMIN,
@@ -57,9 +61,14 @@ __export(index_exports, {
   encrypt: () => encrypt,
   encryptMessage: () => encryptMessage,
   encryptTopicKeyForUser: () => encryptTopicKeyForUser,
+  formatTimeout: () => formatTimeout,
   getChain: () => getChain,
+  getDepositDeadline: () => getDepositDeadline,
   hexToBytes: () => hexToBytes,
-  keypairFromPrivateKey: () => keypairFromPrivateKey
+  isDepositExpired: () => isDepositExpired,
+  isValidTimeout: () => isValidTimeout,
+  keypairFromPrivateKey: () => keypairFromPrivateKey,
+  timeUntilRefund: () => timeUntilRefund
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -498,7 +507,51 @@ function hexToBytes(hex) {
 
 // src/client.ts
 var import_utils3 = require("@noble/hashes/utils");
-var Clawntenna = class {
+
+// src/escrow.ts
+var ESCROW_MIN_TIMEOUT = 60;
+var ESCROW_MAX_TIMEOUT = 604800;
+var ESCROW_TIMEOUT_OPTIONS = [
+  { value: 300, label: "5 minutes" },
+  { value: 3600, label: "1 hour" },
+  { value: 21600, label: "6 hours" },
+  { value: 86400, label: "1 day" },
+  { value: 259200, label: "3 days" },
+  { value: 604800, label: "7 days" }
+];
+var DEPOSIT_STATUS_LABELS = ["Pending", "Released", "Refunded"];
+function formatTimeout(seconds) {
+  if (seconds <= 0) return "0s";
+  const days = Math.floor(seconds / 86400);
+  const hours = Math.floor(seconds % 86400 / 3600);
+  const minutes = Math.floor(seconds % 3600 / 60);
+  const secs = seconds % 60;
+  const parts = [];
+  if (days > 0) parts.push(`${days}d`);
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0) parts.push(`${minutes}m`);
+  if (secs > 0 && days === 0 && hours === 0) parts.push(`${secs}s`);
+  return parts.join(" ") || "0s";
+}
+function isDepositExpired(depositedAt, timeout, nowSeconds) {
+  const now = BigInt(nowSeconds ?? Math.floor(Date.now() / 1e3));
+  return now >= depositedAt + timeout;
+}
+function timeUntilRefund(depositedAt, timeout, nowSeconds) {
+  const now = BigInt(nowSeconds ?? Math.floor(Date.now() / 1e3));
+  const deadline = depositedAt + timeout;
+  if (now >= deadline) return 0;
+  return Number(deadline - now);
+}
+function getDepositDeadline(depositedAt, timeout) {
+  return Number(depositedAt + timeout);
+}
+function isValidTimeout(seconds) {
+  return Number.isInteger(seconds) && seconds >= ESCROW_MIN_TIMEOUT && seconds <= ESCROW_MAX_TIMEOUT;
+}
+
+// src/client.ts
+var Clawntenna = class _Clawntenna {
   provider;
   wallet;
   registry;
@@ -511,6 +564,9 @@ var Clawntenna = class {
   ecdhPrivateKey = null;
   ecdhPublicKey = null;
   topicKeys = /* @__PURE__ */ new Map();
+  // Token decimals cache (ERC-20 decimals never change)
+  tokenDecimalsCache = /* @__PURE__ */ new Map();
+  static ERC20_DECIMALS_ABI = ["function decimals() view returns (uint8)"];
   constructor(options = {}) {
     const chainName = options.chain ?? "base";
     const chain = CHAINS[chainName];
@@ -775,13 +831,70 @@ var Clawntenna = class {
     const [token, amount] = await this.registry.getTopicMessageFee(topicId);
     return { token, amount };
   }
+  /**
+   * Set topic creation fee for an application (app admin only).
+   * feeAmount accepts:
+   *   - bigint: raw token units (e.g. 150000n for 0.15 USDC)
+   *   - string | number: human-readable amount — decimals are auto-resolved from the token contract
+   *     (e.g. '0.15' or 0.15 with USDC → 150000n, '0.01' with native ETH → 10000000000000000n)
+   */
   async setTopicCreationFee(appId, feeToken, feeAmount) {
     if (!this.wallet) throw new Error("Wallet required");
-    return this.registry.setTopicCreationFee(appId, feeToken, feeAmount);
+    const rawAmount = typeof feeAmount === "bigint" ? feeAmount : await this.parseTokenAmount(feeToken, feeAmount);
+    return this.registry.setTopicCreationFee(appId, feeToken, rawAmount);
   }
+  /**
+   * Set per-message fee for a topic (topic admin only).
+   * feeAmount accepts:
+   *   - bigint: raw token units (e.g. 150000n for 0.15 USDC)
+   *   - string | number: human-readable amount — decimals are auto-resolved from the token contract
+   *     (e.g. '0.15' or 0.15 with USDC → 150000n, '0.01' with native ETH → 10000000000000000n)
+   */
   async setTopicMessageFee(topicId, feeToken, feeAmount) {
     if (!this.wallet) throw new Error("Wallet required");
-    return this.registry.setTopicMessageFee(topicId, feeToken, feeAmount);
+    const rawAmount = typeof feeAmount === "bigint" ? feeAmount : await this.parseTokenAmount(feeToken, feeAmount);
+    return this.registry.setTopicMessageFee(topicId, feeToken, rawAmount);
+  }
+  // ===== TOKEN AMOUNTS =====
+  /**
+   * Get the number of decimals for an ERC-20 token.
+   * Returns 18 for native ETH (address(0)).
+   * Results are cached per token address.
+   */
+  async getTokenDecimals(tokenAddress) {
+    if (tokenAddress === import_ethers.ethers.ZeroAddress) return 18;
+    const key = tokenAddress.toLowerCase();
+    const cached = this.tokenDecimalsCache.get(key);
+    if (cached !== void 0) return cached;
+    const erc20 = new import_ethers.ethers.Contract(tokenAddress, _Clawntenna.ERC20_DECIMALS_ABI, this.provider);
+    const decimals = Number(await erc20.decimals());
+    this.tokenDecimalsCache.set(key, decimals);
+    return decimals;
+  }
+  /**
+   * Convert a human-readable token amount to raw units (bigint).
+   * Looks up the token's on-chain decimals automatically.
+   *
+   * Examples:
+   *   parseTokenAmount('0xUSDC...', '0.15')  → 150000n       (USDC = 6 decimals)
+   *   parseTokenAmount('0xUSDC...', 10)       → 10000000n     (USDC = 6 decimals)
+   *   parseTokenAmount(ZeroAddress, '0.01')   → 10000000000000000n  (native ETH = 18 decimals)
+   */
+  async parseTokenAmount(tokenAddress, amount) {
+    const decimals = await this.getTokenDecimals(tokenAddress);
+    return import_ethers.ethers.parseUnits(String(amount), decimals);
+  }
+  /**
+   * Convert raw token units (bigint) to a human-readable string.
+   * Looks up the token's on-chain decimals automatically.
+   *
+   * Examples:
+   *   formatTokenAmount('0xUSDC...', 150000n)  → '0.15'
+   *   formatTokenAmount(ZeroAddress, 10000000000000000n) → '0.01'
+   */
+  async formatTokenAmount(tokenAddress, amount) {
+    const decimals = await this.getTokenDecimals(tokenAddress);
+    return import_ethers.ethers.formatUnits(amount, decimals);
   }
   // ===== ESCROW =====
   requireEscrow() {
@@ -909,6 +1022,25 @@ var Clawntenna = class {
     const status = await this.getMessageDepositStatus(txHash);
     return status === 2 /* Refunded */;
   }
+  /**
+   * Get timer info for a deposit — remaining time, expiry status, and claimability.
+   * Useful for building countdown UIs.
+   */
+  async getDepositTimer(depositId) {
+    const d = await this.getDeposit(depositId);
+    const nowSeconds = Math.floor(Date.now() / 1e3);
+    const remaining = timeUntilRefund(d.depositedAt, d.timeout, nowSeconds);
+    const expired = remaining === 0;
+    const canClaim = expired && d.status === 0 /* Pending */ ? await this.canClaimRefund(depositId) : false;
+    return {
+      depositId: d.id,
+      expired,
+      remainingSeconds: remaining,
+      deadline: getDepositDeadline(d.depositedAt, d.timeout),
+      formattedRemaining: formatTimeout(remaining),
+      canClaim
+    };
+  }
   // ===== ECDH (Private Topics) =====
   /**
    * Derive ECDH keypair from wallet signature (deterministic).
@@ -1426,8 +1558,12 @@ var Clawntenna = class {
   CHAINS,
   CHAIN_IDS,
   Clawntenna,
+  DEPOSIT_STATUS_LABELS,
   DepositStatus,
   ESCROW_ABI,
+  ESCROW_MAX_TIMEOUT,
+  ESCROW_MIN_TIMEOUT,
+  ESCROW_TIMEOUT_OPTIONS,
   IDENTITY_REGISTRY_ABI,
   KEY_MANAGER_ABI,
   PERMISSION_ADMIN,
@@ -1456,8 +1592,13 @@ var Clawntenna = class {
   encrypt,
   encryptMessage,
   encryptTopicKeyForUser,
+  formatTimeout,
   getChain,
+  getDepositDeadline,
   hexToBytes,
-  keypairFromPrivateKey
+  isDepositExpired,
+  isValidTimeout,
+  keypairFromPrivateKey,
+  timeUntilRefund
 });
 //# sourceMappingURL=index.cjs.map