clawntenna 0.8.8 → 0.9.0

package/dist/index.d.cts

@@ -136,6 +136,14 @@ interface EscrowConfig {
     enabled: boolean;
     timeout: bigint;
 }
+interface DepositTimer {
+    depositId: bigint;
+    expired: boolean;
+    remainingSeconds: number;
+    deadline: number;
+    formattedRemaining: string;
+    canClaim: boolean;
+}
 interface ClawtennaOptions {
     chain?: ChainName;
     chainId?: number;
@@ -209,6 +217,8 @@ declare class Clawntenna {
     private ecdhPrivateKey;
     private ecdhPublicKey;
     private topicKeys;
+    private tokenDecimalsCache;
+    private static ERC20_DECIMALS_ABI;
     constructor(options?: ClawtennaOptions);
     get address(): string | null;
     /**
@@ -254,8 +264,47 @@ declare class Clawntenna {
     updateFrontendUrl(appId: number, frontendUrl: string): Promise<ethers.TransactionResponse>;
     getApplication(appId: number): Promise<Application>;
     getTopicMessageFee(topicId: number): Promise<TopicMessageFee>;
-    setTopicCreationFee(appId: number, feeToken: string, feeAmount: bigint): Promise<ethers.TransactionResponse>;
-    setTopicMessageFee(topicId: number, feeToken: string, feeAmount: bigint): Promise<ethers.TransactionResponse>;
+    /**
+     * 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)
+     */
+    setTopicCreationFee(appId: number, feeToken: string, feeAmount: bigint | string | number): Promise<ethers.TransactionResponse>;
+    /**
+     * 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)
+     */
+    setTopicMessageFee(topicId: number, feeToken: string, feeAmount: bigint | string | number): Promise<ethers.TransactionResponse>;
+    /**
+     * Get the number of decimals for an ERC-20 token.
+     * Returns 18 for native ETH (address(0)).
+     * Results are cached per token address.
+     */
+    getTokenDecimals(tokenAddress: string): Promise<number>;
+    /**
+     * 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)
+     */
+    parseTokenAmount(tokenAddress: string, amount: string | number): Promise<bigint>;
+    /**
+     * 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'
+     */
+    formatTokenAmount(tokenAddress: string, amount: bigint): Promise<string>;
     private requireEscrow;
     /**
      * Enable escrow for a topic (topic owner only).
@@ -312,6 +361,11 @@ declare class Clawntenna {
      * Returns false if no escrow deposit exists for the tx.
      */
     isMessageRefunded(txHash: string): Promise<boolean>;
+    /**
+     * Get timer info for a deposit — remaining time, expiry status, and claimability.
+     * Useful for building countdown UIs.
+     */
+    getDepositTimer(depositId: number): Promise<DepositTimer>;
     /**
      * Derive ECDH keypair from wallet signature (deterministic).
      * Requires a signer capable of signing messages.
@@ -572,6 +626,53 @@ declare const IDENTITY_REGISTRY_ABI: readonly ["function register() returns (uin
 declare const ESCROW_ABI: readonly ["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)", "function enableEscrow(uint256 topicId, uint64 timeoutSeconds)", "function disableEscrow(uint256 topicId)", "function claimRefund(uint256 depositId)", "function batchClaimRefunds(uint256[] depositIds)", "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)"];
 declare const KEY_MANAGER_ABI: readonly ["function hasPublicKey(address user) view returns (bool)", "function getPublicKey(address user) view returns (bytes)", "function publicKeys(address) view returns (bytes)", "function hasKeyAccess(uint256 topicId, address user) view returns (bool)", "function getMyKey(uint256 topicId) view returns (bytes encryptedKey, bytes granterPublicKey, address granter, uint256 keyVersion, uint256 currentVersion)", "function getKeyGrant(uint256 topicId, address user) view returns (tuple(bytes encryptedKey, bytes granterPublicKey, address granter, uint256 keyVersion, uint64 grantedAt))", "function keyVersions(uint256 topicId) view returns (uint256)", "function registerPublicKey(bytes publicKey)", "function grantKeyAccess(uint256 topicId, address user, bytes encryptedKey)", "function batchGrantKeyAccess(uint256 topicId, address[] users, bytes[] encryptedKeys)", "function revokeKeyAccess(uint256 topicId, address user)", "function rotateKey(uint256 topicId)", "function exportUserData(address user, uint256[] topicIds) view returns (bytes)", "event PublicKeyRegistered(address indexed user, bytes publicKey)", "event PublicKeyUpdated(address indexed user, bytes publicKey)", "event KeyAccessGranted(uint256 indexed topicId, address indexed user, address indexed granter, uint256 version)", "event KeyAccessRevoked(uint256 indexed topicId, address indexed user)", "event KeyRotated(uint256 indexed topicId, uint256 newVersion)"];
 
+/**
+ * Pure escrow timer utilities — no ethers.js dependency.
+ */
+declare const ESCROW_MIN_TIMEOUT = 60;
+declare const ESCROW_MAX_TIMEOUT = 604800;
+declare const ESCROW_TIMEOUT_OPTIONS: readonly [{
+    readonly value: 300;
+    readonly label: "5 minutes";
+}, {
+    readonly value: 3600;
+    readonly label: "1 hour";
+}, {
+    readonly value: 21600;
+    readonly label: "6 hours";
+}, {
+    readonly value: 86400;
+    readonly label: "1 day";
+}, {
+    readonly value: 259200;
+    readonly label: "3 days";
+}, {
+    readonly value: 604800;
+    readonly label: "7 days";
+}];
+declare const DEPOSIT_STATUS_LABELS: readonly ["Pending", "Released", "Refunded"];
+/**
+ * Format a timeout in seconds into a human-readable string.
+ * Examples: 300 → "5m", 3600 → "1h", 86400 → "1d", 5400 → "1h 30m"
+ */
+declare function formatTimeout(seconds: number): string;
+/**
+ * Check whether a deposit has expired (eligible for refund).
+ */
+declare function isDepositExpired(depositedAt: bigint, timeout: bigint, nowSeconds?: number): boolean;
+/**
+ * Seconds remaining until a deposit becomes refundable. Returns 0 if already expired.
+ */
+declare function timeUntilRefund(depositedAt: bigint, timeout: bigint, nowSeconds?: number): number;
+/**
+ * Get the absolute deadline timestamp (seconds since epoch) when a deposit becomes refundable.
+ */
+declare function getDepositDeadline(depositedAt: bigint, timeout: bigint): number;
+/**
+ * Validate that a timeout value is within allowed bounds.
+ */
+declare function isValidTimeout(seconds: number): boolean;
+
 /**
  * Derive AES-256 key for a public/public_limited topic.
  * Uses PBKDF2 with SHA-256, matching the web frontend exactly.
@@ -649,4 +750,4 @@ declare function decryptTopicKey(encryptedKey: Uint8Array, ourPrivateKey: Uint8A
 declare function bytesToHex(bytes: Uint8Array): string;
 declare function hexToBytes(hex: string): Uint8Array;
 
-export { ACCESS_PRIVATE, ACCESS_PUBLIC, ACCESS_PUBLIC_LIMITED, AccessLevel, type Application, CHAINS, CHAIN_IDS, type ChainConfig, type ChainName, Clawntenna, type ClawtennaOptions, type CredentialApp, type CredentialChain, type Credentials, type CredentialsV1, DepositStatus, ESCROW_ABI, type EncryptedPayload, type EscrowConfig, type EscrowDeposit, IDENTITY_REGISTRY_ABI, KEY_MANAGER_ABI, type KeyGrant, type Member, type Message, type MessageContent, PERMISSION_ADMIN, PERMISSION_NONE, PERMISSION_READ, PERMISSION_READ_WRITE, PERMISSION_WRITE, Permission, REGISTRY_ABI, ROLE_ADMIN, ROLE_MEMBER, ROLE_OWNER_DELEGATE, ROLE_SUPPORT_MANAGER, ROLE_TOPIC_MANAGER, type ReadOptions, Role, SCHEMA_REGISTRY_ABI, type SchemaInfo, type SendOptions, type Topic, type TopicMessageFee, type TopicSchemaBinding, bytesToHex, computeSharedSecret, decrypt, decryptMessage, decryptTopicKey, deriveAESKeyFromSecret, deriveKeyFromPassphrase, deriveKeypairFromSignature, derivePublicTopicKey, encrypt, encryptMessage, encryptTopicKeyForUser, getChain, hexToBytes, keypairFromPrivateKey };
+export { ACCESS_PRIVATE, ACCESS_PUBLIC, ACCESS_PUBLIC_LIMITED, AccessLevel, type Application, CHAINS, CHAIN_IDS, type ChainConfig, type ChainName, Clawntenna, type ClawtennaOptions, type CredentialApp, type CredentialChain, type Credentials, type CredentialsV1, DEPOSIT_STATUS_LABELS, DepositStatus, type DepositTimer, ESCROW_ABI, ESCROW_MAX_TIMEOUT, ESCROW_MIN_TIMEOUT, ESCROW_TIMEOUT_OPTIONS, type EncryptedPayload, type EscrowConfig, type EscrowDeposit, IDENTITY_REGISTRY_ABI, KEY_MANAGER_ABI, type KeyGrant, type Member, type Message, type MessageContent, PERMISSION_ADMIN, PERMISSION_NONE, PERMISSION_READ, PERMISSION_READ_WRITE, PERMISSION_WRITE, Permission, REGISTRY_ABI, ROLE_ADMIN, ROLE_MEMBER, ROLE_OWNER_DELEGATE, ROLE_SUPPORT_MANAGER, ROLE_TOPIC_MANAGER, type ReadOptions, Role, SCHEMA_REGISTRY_ABI, type SchemaInfo, type SendOptions, type Topic, type TopicMessageFee, type TopicSchemaBinding, bytesToHex, computeSharedSecret, decrypt, decryptMessage, decryptTopicKey, deriveAESKeyFromSecret, deriveKeyFromPassphrase, deriveKeypairFromSignature, derivePublicTopicKey, encrypt, encryptMessage, encryptTopicKeyForUser, formatTimeout, getChain, getDepositDeadline, hexToBytes, isDepositExpired, isValidTimeout, keypairFromPrivateKey, timeUntilRefund };

package/dist/index.d.ts

@@ -136,6 +136,14 @@ interface EscrowConfig {
     enabled: boolean;
     timeout: bigint;
 }
+interface DepositTimer {
+    depositId: bigint;
+    expired: boolean;
+    remainingSeconds: number;
+    deadline: number;
+    formattedRemaining: string;
+    canClaim: boolean;
+}
 interface ClawtennaOptions {
     chain?: ChainName;
     chainId?: number;
@@ -209,6 +217,8 @@ declare class Clawntenna {
     private ecdhPrivateKey;
     private ecdhPublicKey;
     private topicKeys;
+    private tokenDecimalsCache;
+    private static ERC20_DECIMALS_ABI;
     constructor(options?: ClawtennaOptions);
     get address(): string | null;
     /**
@@ -254,8 +264,47 @@ declare class Clawntenna {
     updateFrontendUrl(appId: number, frontendUrl: string): Promise<ethers.TransactionResponse>;
     getApplication(appId: number): Promise<Application>;
     getTopicMessageFee(topicId: number): Promise<TopicMessageFee>;
-    setTopicCreationFee(appId: number, feeToken: string, feeAmount: bigint): Promise<ethers.TransactionResponse>;
-    setTopicMessageFee(topicId: number, feeToken: string, feeAmount: bigint): Promise<ethers.TransactionResponse>;
+    /**
+     * 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)
+     */
+    setTopicCreationFee(appId: number, feeToken: string, feeAmount: bigint | string | number): Promise<ethers.TransactionResponse>;
+    /**
+     * 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)
+     */
+    setTopicMessageFee(topicId: number, feeToken: string, feeAmount: bigint | string | number): Promise<ethers.TransactionResponse>;
+    /**
+     * Get the number of decimals for an ERC-20 token.
+     * Returns 18 for native ETH (address(0)).
+     * Results are cached per token address.
+     */
+    getTokenDecimals(tokenAddress: string): Promise<number>;
+    /**
+     * 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)
+     */
+    parseTokenAmount(tokenAddress: string, amount: string | number): Promise<bigint>;
+    /**
+     * 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'
+     */
+    formatTokenAmount(tokenAddress: string, amount: bigint): Promise<string>;
     private requireEscrow;
     /**
      * Enable escrow for a topic (topic owner only).
@@ -312,6 +361,11 @@ declare class Clawntenna {
      * Returns false if no escrow deposit exists for the tx.
      */
     isMessageRefunded(txHash: string): Promise<boolean>;
+    /**
+     * Get timer info for a deposit — remaining time, expiry status, and claimability.
+     * Useful for building countdown UIs.
+     */
+    getDepositTimer(depositId: number): Promise<DepositTimer>;
     /**
      * Derive ECDH keypair from wallet signature (deterministic).
      * Requires a signer capable of signing messages.
@@ -572,6 +626,53 @@ declare const IDENTITY_REGISTRY_ABI: readonly ["function register() returns (uin
 declare const ESCROW_ABI: readonly ["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)", "function enableEscrow(uint256 topicId, uint64 timeoutSeconds)", "function disableEscrow(uint256 topicId)", "function claimRefund(uint256 depositId)", "function batchClaimRefunds(uint256[] depositIds)", "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)"];
 declare const KEY_MANAGER_ABI: readonly ["function hasPublicKey(address user) view returns (bool)", "function getPublicKey(address user) view returns (bytes)", "function publicKeys(address) view returns (bytes)", "function hasKeyAccess(uint256 topicId, address user) view returns (bool)", "function getMyKey(uint256 topicId) view returns (bytes encryptedKey, bytes granterPublicKey, address granter, uint256 keyVersion, uint256 currentVersion)", "function getKeyGrant(uint256 topicId, address user) view returns (tuple(bytes encryptedKey, bytes granterPublicKey, address granter, uint256 keyVersion, uint64 grantedAt))", "function keyVersions(uint256 topicId) view returns (uint256)", "function registerPublicKey(bytes publicKey)", "function grantKeyAccess(uint256 topicId, address user, bytes encryptedKey)", "function batchGrantKeyAccess(uint256 topicId, address[] users, bytes[] encryptedKeys)", "function revokeKeyAccess(uint256 topicId, address user)", "function rotateKey(uint256 topicId)", "function exportUserData(address user, uint256[] topicIds) view returns (bytes)", "event PublicKeyRegistered(address indexed user, bytes publicKey)", "event PublicKeyUpdated(address indexed user, bytes publicKey)", "event KeyAccessGranted(uint256 indexed topicId, address indexed user, address indexed granter, uint256 version)", "event KeyAccessRevoked(uint256 indexed topicId, address indexed user)", "event KeyRotated(uint256 indexed topicId, uint256 newVersion)"];
 
+/**
+ * Pure escrow timer utilities — no ethers.js dependency.
+ */
+declare const ESCROW_MIN_TIMEOUT = 60;
+declare const ESCROW_MAX_TIMEOUT = 604800;
+declare const ESCROW_TIMEOUT_OPTIONS: readonly [{
+    readonly value: 300;
+    readonly label: "5 minutes";
+}, {
+    readonly value: 3600;
+    readonly label: "1 hour";
+}, {
+    readonly value: 21600;
+    readonly label: "6 hours";
+}, {
+    readonly value: 86400;
+    readonly label: "1 day";
+}, {
+    readonly value: 259200;
+    readonly label: "3 days";
+}, {
+    readonly value: 604800;
+    readonly label: "7 days";
+}];
+declare const DEPOSIT_STATUS_LABELS: readonly ["Pending", "Released", "Refunded"];
+/**
+ * Format a timeout in seconds into a human-readable string.
+ * Examples: 300 → "5m", 3600 → "1h", 86400 → "1d", 5400 → "1h 30m"
+ */
+declare function formatTimeout(seconds: number): string;
+/**
+ * Check whether a deposit has expired (eligible for refund).
+ */
+declare function isDepositExpired(depositedAt: bigint, timeout: bigint, nowSeconds?: number): boolean;
+/**
+ * Seconds remaining until a deposit becomes refundable. Returns 0 if already expired.
+ */
+declare function timeUntilRefund(depositedAt: bigint, timeout: bigint, nowSeconds?: number): number;
+/**
+ * Get the absolute deadline timestamp (seconds since epoch) when a deposit becomes refundable.
+ */
+declare function getDepositDeadline(depositedAt: bigint, timeout: bigint): number;
+/**
+ * Validate that a timeout value is within allowed bounds.
+ */
+declare function isValidTimeout(seconds: number): boolean;
+
 /**
  * Derive AES-256 key for a public/public_limited topic.
  * Uses PBKDF2 with SHA-256, matching the web frontend exactly.
@@ -649,4 +750,4 @@ declare function decryptTopicKey(encryptedKey: Uint8Array, ourPrivateKey: Uint8A
 declare function bytesToHex(bytes: Uint8Array): string;
 declare function hexToBytes(hex: string): Uint8Array;
 
-export { ACCESS_PRIVATE, ACCESS_PUBLIC, ACCESS_PUBLIC_LIMITED, AccessLevel, type Application, CHAINS, CHAIN_IDS, type ChainConfig, type ChainName, Clawntenna, type ClawtennaOptions, type CredentialApp, type CredentialChain, type Credentials, type CredentialsV1, DepositStatus, ESCROW_ABI, type EncryptedPayload, type EscrowConfig, type EscrowDeposit, IDENTITY_REGISTRY_ABI, KEY_MANAGER_ABI, type KeyGrant, type Member, type Message, type MessageContent, PERMISSION_ADMIN, PERMISSION_NONE, PERMISSION_READ, PERMISSION_READ_WRITE, PERMISSION_WRITE, Permission, REGISTRY_ABI, ROLE_ADMIN, ROLE_MEMBER, ROLE_OWNER_DELEGATE, ROLE_SUPPORT_MANAGER, ROLE_TOPIC_MANAGER, type ReadOptions, Role, SCHEMA_REGISTRY_ABI, type SchemaInfo, type SendOptions, type Topic, type TopicMessageFee, type TopicSchemaBinding, bytesToHex, computeSharedSecret, decrypt, decryptMessage, decryptTopicKey, deriveAESKeyFromSecret, deriveKeyFromPassphrase, deriveKeypairFromSignature, derivePublicTopicKey, encrypt, encryptMessage, encryptTopicKeyForUser, getChain, hexToBytes, keypairFromPrivateKey };
+export { ACCESS_PRIVATE, ACCESS_PUBLIC, ACCESS_PUBLIC_LIMITED, AccessLevel, type Application, CHAINS, CHAIN_IDS, type ChainConfig, type ChainName, Clawntenna, type ClawtennaOptions, type CredentialApp, type CredentialChain, type Credentials, type CredentialsV1, DEPOSIT_STATUS_LABELS, DepositStatus, type DepositTimer, ESCROW_ABI, ESCROW_MAX_TIMEOUT, ESCROW_MIN_TIMEOUT, ESCROW_TIMEOUT_OPTIONS, type EncryptedPayload, type EscrowConfig, type EscrowDeposit, IDENTITY_REGISTRY_ABI, KEY_MANAGER_ABI, type KeyGrant, type Member, type Message, type MessageContent, PERMISSION_ADMIN, PERMISSION_NONE, PERMISSION_READ, PERMISSION_READ_WRITE, PERMISSION_WRITE, Permission, REGISTRY_ABI, ROLE_ADMIN, ROLE_MEMBER, ROLE_OWNER_DELEGATE, ROLE_SUPPORT_MANAGER, ROLE_TOPIC_MANAGER, type ReadOptions, Role, SCHEMA_REGISTRY_ABI, type SchemaInfo, type SendOptions, type Topic, type TopicMessageFee, type TopicSchemaBinding, bytesToHex, computeSharedSecret, decrypt, decryptMessage, decryptTopicKey, deriveAESKeyFromSecret, deriveKeyFromPassphrase, deriveKeypairFromSignature, derivePublicTopicKey, encrypt, encryptMessage, encryptTopicKeyForUser, formatTimeout, getChain, getDepositDeadline, hexToBytes, isDepositExpired, isValidTimeout, keypairFromPrivateKey, timeUntilRefund };

package/dist/index.js

@@ -433,7 +433,51 @@ function hexToBytes(hex) {
 
 // src/client.ts
 import { randomBytes as randomBytes3 } from "@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;
@@ -446,6 +490,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];
@@ -710,13 +757,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() {
@@ -844,6 +948,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).
@@ -1360,8 +1483,12 @@ export {
   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,
@@ -1390,8 +1517,13 @@ export {
   encrypt,
   encryptMessage,
   encryptTopicKeyForUser,
+  formatTimeout,
   getChain,
+  getDepositDeadline,
   hexToBytes,
-  keypairFromPrivateKey
+  isDepositExpired,
+  isValidTimeout,
+  keypairFromPrivateKey,
+  timeUntilRefund
 };
 //# sourceMappingURL=index.js.map