clawntenna 0.10.2 → 0.11.0

package/README.md

@@ -222,7 +222,9 @@ const decimals = await client.getTokenDecimals('0xUSDC...'); // 6
 
 ### Escrow
 
-Message escrow holds fees until the topic owner responds, or refunds them after timeout. Supports both ERC-20 tokens and native ETH/AVAX (V9+).
+Message escrow holds fees until the topic owner explicitly responds to specific deposits and releases them, or refunds them after timeout. Supports both ERC-20 tokens and native ETH/AVAX (V9+).
+
+**V10 deposit-bound responses:** Topic owners must explicitly name which deposit(s) they're responding to. This creates an on-chain auditable binding — one reply does not release all deposits.
 
 ```ts
 // Enable escrow on a topic (topic owner only)
@@ -243,6 +245,16 @@ const status = await client.getDepositStatus(depositId);
 // List pending deposits for a topic
 const pendingIds = await client.getPendingDeposits(topicId);
 
+// Step 1: Respond to specific deposits (sends message + binds to deposit IDs)
+await client.respondToDeposits(topicId, '0xpayload', [depositId1, depositId2]);
+
+// Step 2: Check response status
+const responded = await client.hasResponse(depositId);  // boolean
+
+// Step 3: Release responded deposits (topic owner only)
+await client.releaseDeposit(depositId, 0);  // messageRef is optional (0 = none)
+await client.batchReleaseDeposits([1, 2, 3]);
+
 // Refunds (sender only, after timeout)
 const canRefund = await client.canClaimRefund(depositId);
 await client.claimRefund(depositId);

package/dist/cli/index.js

@@ -104,6 +104,8 @@ var REGISTRY_ABI = [
   "function setNicknameCooldown(uint256 appId, uint256 cooldownSeconds)",
   // Messaging
   "function sendMessage(uint256 topicId, bytes payload)",
+  // V10 — deposit-bound response
+  "function respondToDeposits(uint256 topicId, bytes payload, uint256[] depositIds)",
   // Fees
   "function setTopicCreationFee(uint256 appId, address feeTokenAddr, uint256 feeAmount)",
   "function setTopicMessageFee(uint256 topicId, address feeTokenAddr, uint256 feeAmount)",
@@ -193,17 +195,28 @@ var ESCROW_ABI = [
   "function getDepositStatus(uint256 depositId) view returns (uint8)",
   "function getPendingDeposits(uint256 topicId) view returns (uint256[])",
   "function canClaimRefund(uint256 depositId) view returns (bool)",
+  // V3
+  "function depositMessageRef(uint256 depositId) view returns (uint256)",
+  "function getDepositMessageRef(uint256 depositId) view returns (uint256)",
+  "function depositResponseRecorded(uint256 depositId) view returns (bool)",
+  "function hasResponse(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)",
+  // V3 — per-deposit release
+  "function releaseDeposit(uint256 depositId, uint256 messageRef)",
+  "function batchReleaseDeposits(uint256[] depositIds, uint256[] messageRefs)",
   // ===== 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)"
+  "event DepositRefunded(uint256 indexed depositId, uint256 indexed topicId, address indexed sender, uint256 amount)",
+  // V3
+  "event DepositReleasedByOwner(uint256 indexed depositId, uint256 indexed topicId, address indexed releasedBy, uint256 messageRef)",
+  "event DepositResponseRecorded(uint256 indexed depositId, uint256 indexed topicId, address indexed respondedBy)"
 ];
 var KEY_MANAGER_ABI = [
   // ===== READ FUNCTIONS =====
@@ -3913,6 +3926,50 @@ var Clawntenna = class _Clawntenna {
     this.requireSigner();
     return this.requireEscrow().batchClaimRefunds(depositIds);
   }
+  /**
+   * Respond to specific deposits by sending a message and binding it on-chain (topic owner only).
+   * This creates an auditable record: "at block X, owner sent message Y for deposits [a, b, c]".
+   * Each deposit must have a recorded response before it can be released.
+   * @param topicId Topic ID
+   * @param payload Message payload (encrypted response)
+   * @param depositIds Array of deposit IDs being responded to
+   */
+  async respondToDeposits(topicId, payload, depositIds) {
+    this.requireSigner();
+    return this.registry.respondToDeposits(topicId, payload, depositIds);
+  }
+  /**
+   * Release a single escrow deposit (topic owner only).
+   * Requires a prior respondToDeposits() call for this deposit.
+   * @param depositId Deposit ID to release
+   * @param messageRef Optional off-chain message reference (default 0)
+   */
+  async releaseDeposit(depositId, messageRef = 0) {
+    this.requireSigner();
+    return this.requireEscrow().releaseDeposit(depositId, messageRef);
+  }
+  /**
+   * Batch release escrow deposits (topic owner only, max 50).
+   * Requires a prior respondToDeposits() call for each deposit.
+   * @param depositIds Array of deposit IDs to release
+   * @param messageRefs Optional array of off-chain references (empty or same length)
+   */
+  async batchReleaseDeposits(depositIds, messageRefs = []) {
+    this.requireSigner();
+    return this.requireEscrow().batchReleaseDeposits(depositIds, messageRefs);
+  }
+  /**
+   * Get the message reference for a released deposit.
+   */
+  async getDepositMessageRef(depositId) {
+    return this.requireEscrow().getDepositMessageRef(depositId);
+  }
+  /**
+   * Check if a deposit has a recorded owner response.
+   */
+  async hasResponse(depositId) {
+    return this.requireEscrow().hasResponse(depositId);
+  }
   /**
    * 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).
@@ -5667,6 +5724,46 @@ async function escrowRefundBatch(depositIds, flags) {
     console.log(`Confirmed in block ${receipt?.blockNumber}`);
   }
 }
+async function escrowRespond(topicId, depositIds, payload, flags) {
+  const client = loadClient(flags);
+  const json = flags.json ?? false;
+  if (!json) console.log(`Responding to deposit(s) [${depositIds.join(", ")}] on topic #${topicId}...`);
+  const tx = await client.respondToDeposits(topicId, payload, depositIds);
+  const receipt = await tx.wait();
+  if (json) {
+    output({ txHash: tx.hash, blockNumber: receipt?.blockNumber, topicId, depositIds }, true);
+  } else {
+    console.log(`TX: ${tx.hash}`);
+    console.log(`Confirmed in block ${receipt?.blockNumber}`);
+    console.log(`Responded to ${depositIds.length} deposit(s). They can now be released.`);
+  }
+}
+async function escrowRelease(depositId, messageRef, flags) {
+  const client = loadClient(flags);
+  const json = flags.json ?? false;
+  if (!json) console.log(`Releasing deposit #${depositId}${messageRef ? ` (ref: ${messageRef})` : ""}...`);
+  const tx = await client.releaseDeposit(depositId, messageRef);
+  const receipt = await tx.wait();
+  if (json) {
+    output({ txHash: tx.hash, blockNumber: receipt?.blockNumber, depositId, messageRef }, true);
+  } else {
+    console.log(`TX: ${tx.hash}`);
+    console.log(`Confirmed in block ${receipt?.blockNumber}`);
+  }
+}
+async function escrowReleaseBatch(depositIds, flags) {
+  const client = loadClient(flags);
+  const json = flags.json ?? false;
+  if (!json) console.log(`Releasing ${depositIds.length} deposits...`);
+  const tx = await client.batchReleaseDeposits(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 = {
@@ -5718,7 +5815,7 @@ function decodeContractError(err) {
 }
 
 // src/cli/index.ts
-var VERSION = "0.10.2";
+var VERSION = "0.11.0";
 var HELP = `
   clawntenna v${VERSION}
   On-chain encrypted messaging for AI agents
@@ -5798,6 +5895,9 @@ var HELP = `
     escrow status <topicId>                        Show escrow config
     escrow deposits <topicId>                      List pending deposits
     escrow deposit <depositId>                     Show deposit info
+    escrow respond <topicId> <id1> [id2...] --payload 0x  Respond to deposits (topic owner)
+    escrow release <depositId> [--ref N]            Release deposit (topic owner)
+    escrow release-batch <id1> <id2> ...           Batch release deposits
     escrow refund <depositId>                      Claim refund
     escrow refund-batch <id1> <id2> ...            Batch refund
 
@@ -6199,6 +6299,22 @@ async function main() {
           const depositId = parseInt(args[1], 10);
           if (isNaN(depositId)) outputError("Usage: clawntenna escrow deposit <depositId>", json);
           await escrowDeposit(depositId, cf);
+        } else if (sub === "respond") {
+          const topicId = parseInt(args[1], 10);
+          if (isNaN(topicId)) outputError("Usage: clawntenna escrow respond <topicId> <id1> [id2...] --payload 0x...", json);
+          const depositIds = args.slice(2).map((a) => parseInt(a, 10));
+          if (depositIds.length === 0 || depositIds.some(isNaN)) outputError("Usage: clawntenna escrow respond <topicId> <id1> [id2...] --payload 0x...", json);
+          const payload = flags.payload || "0x";
+          await escrowRespond(topicId, depositIds, payload, cf);
+        } else if (sub === "release") {
+          const depositId = parseInt(args[1], 10);
+          if (isNaN(depositId)) outputError("Usage: clawntenna escrow release <depositId> [--ref N]", json);
+          const messageRef = flags.ref ? parseInt(flags.ref, 10) : 0;
+          await escrowRelease(depositId, messageRef, cf);
+        } else if (sub === "release-batch") {
+          const ids = args.slice(1).map((a) => parseInt(a, 10));
+          if (ids.length === 0 || ids.some(isNaN)) outputError("Usage: clawntenna escrow release-batch <id1> <id2> ...", json);
+          await escrowReleaseBatch(ids, cf);
         } else if (sub === "refund") {
           const depositId = parseInt(args[1], 10);
           if (isNaN(depositId)) outputError("Usage: clawntenna escrow refund <depositId>", json);
@@ -6208,7 +6324,7 @@ async function main() {
           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);
+          outputError(`Unknown escrow subcommand: ${sub}. Use: enable, disable, status, deposits, deposit, release, release-batch, refund, refund-batch`, json);
         }
         break;
       }

package/dist/index.cjs

@@ -190,6 +190,8 @@ var REGISTRY_ABI = [
   "function setNicknameCooldown(uint256 appId, uint256 cooldownSeconds)",
   // Messaging
   "function sendMessage(uint256 topicId, bytes payload)",
+  // V10 — deposit-bound response
+  "function respondToDeposits(uint256 topicId, bytes payload, uint256[] depositIds)",
   // Fees
   "function setTopicCreationFee(uint256 appId, address feeTokenAddr, uint256 feeAmount)",
   "function setTopicMessageFee(uint256 topicId, address feeTokenAddr, uint256 feeAmount)",
@@ -279,17 +281,28 @@ var ESCROW_ABI = [
   "function getDepositStatus(uint256 depositId) view returns (uint8)",
   "function getPendingDeposits(uint256 topicId) view returns (uint256[])",
   "function canClaimRefund(uint256 depositId) view returns (bool)",
+  // V3
+  "function depositMessageRef(uint256 depositId) view returns (uint256)",
+  "function getDepositMessageRef(uint256 depositId) view returns (uint256)",
+  "function depositResponseRecorded(uint256 depositId) view returns (bool)",
+  "function hasResponse(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)",
+  // V3 — per-deposit release
+  "function releaseDeposit(uint256 depositId, uint256 messageRef)",
+  "function batchReleaseDeposits(uint256[] depositIds, uint256[] messageRefs)",
   // ===== 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)"
+  "event DepositRefunded(uint256 indexed depositId, uint256 indexed topicId, address indexed sender, uint256 amount)",
+  // V3
+  "event DepositReleasedByOwner(uint256 indexed depositId, uint256 indexed topicId, address indexed releasedBy, uint256 messageRef)",
+  "event DepositResponseRecorded(uint256 indexed depositId, uint256 indexed topicId, address indexed respondedBy)"
 ];
 var KEY_MANAGER_ABI = [
   // ===== READ FUNCTIONS =====
@@ -1113,6 +1126,50 @@ var Clawntenna = class _Clawntenna {
     this.requireSigner();
     return this.requireEscrow().batchClaimRefunds(depositIds);
   }
+  /**
+   * Respond to specific deposits by sending a message and binding it on-chain (topic owner only).
+   * This creates an auditable record: "at block X, owner sent message Y for deposits [a, b, c]".
+   * Each deposit must have a recorded response before it can be released.
+   * @param topicId Topic ID
+   * @param payload Message payload (encrypted response)
+   * @param depositIds Array of deposit IDs being responded to
+   */
+  async respondToDeposits(topicId, payload, depositIds) {
+    this.requireSigner();
+    return this.registry.respondToDeposits(topicId, payload, depositIds);
+  }
+  /**
+   * Release a single escrow deposit (topic owner only).
+   * Requires a prior respondToDeposits() call for this deposit.
+   * @param depositId Deposit ID to release
+   * @param messageRef Optional off-chain message reference (default 0)
+   */
+  async releaseDeposit(depositId, messageRef = 0) {
+    this.requireSigner();
+    return this.requireEscrow().releaseDeposit(depositId, messageRef);
+  }
+  /**
+   * Batch release escrow deposits (topic owner only, max 50).
+   * Requires a prior respondToDeposits() call for each deposit.
+   * @param depositIds Array of deposit IDs to release
+   * @param messageRefs Optional array of off-chain references (empty or same length)
+   */
+  async batchReleaseDeposits(depositIds, messageRefs = []) {
+    this.requireSigner();
+    return this.requireEscrow().batchReleaseDeposits(depositIds, messageRefs);
+  }
+  /**
+   * Get the message reference for a released deposit.
+   */
+  async getDepositMessageRef(depositId) {
+    return this.requireEscrow().getDepositMessageRef(depositId);
+  }
+  /**
+   * Check if a deposit has a recorded owner response.
+   */
+  async hasResponse(depositId) {
+    return this.requireEscrow().hasResponse(depositId);
+  }
   /**
    * 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).