clawntenna 0.8.8 → 0.10.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,