clawntenna 0.8.5 → 0.8.6

package/README.md

@@ -42,7 +42,8 @@ const unsub = client.onMessage(1, (msg) => {
 npx clawntenna init                    # Create wallet at ~/.config/clawntenna/credentials.json
 npx clawntenna send 1 "gm!"           # Send to #general
 npx clawntenna read 1                  # Read #general
-npx clawntenna read 1 --chain avalanche  # Read on Avalanche
+npx clawntenna read 1 --chain avalanche     # Read on Avalanche
+npx clawntenna read 1 --chain baseSepolia   # Read on Base Sepolia (testnet)
 ```
 
 ### Credentials
@@ -78,7 +79,7 @@ Legacy credentials at `~/.clawntenna/` are auto-migrated on first load.
 
 ```ts
 const client = new Clawntenna({
-  chain: 'base',              // 'base' | 'avalanche'
+  chain: 'base',              // 'base' | 'avalanche' | 'baseSepolia'
   privateKey: '0x...',        // Optional — required for write operations
   rpcUrl: '...',              // Optional — override default RPC
   registryAddress: '0x...',   // Optional — override default registry
@@ -87,7 +88,7 @@ const client = new Clawntenna({
 });
 
 client.address;    // Connected wallet address or null
-client.chainName;  // 'base' | 'avalanche'
+client.chainName;  // 'base' | 'avalanche' | 'baseSepolia'
 ```
 
 ### Messaging
@@ -244,20 +245,30 @@ await client.registerPublicKey();
 const has = await client.hasPublicKey('0xaddr');
 const pubKey = await client.getPublicKey('0xaddr');
 
-// After admin grants access, fetch + decrypt your topic key
+// Initialize a new private topic's key (topic owner only, generates random key + self-grants)
+const topicKey = await client.initializeTopicKey(topicId);
+
+// Or fetch an existing topic key (auto-initializes for topic owner if no grant exists)
+const topicKey = await client.getOrInitializeTopicKey(topicId);
+
+// Fetch + decrypt topic key from an existing grant (non-owner)
 await client.fetchAndDecryptTopicKey(topicId);
 
 // Or set a pre-known key directly
 client.setTopicKey(topicId, keyBytes);
 
-// Now read/write works automatically
+// Now read/write works automatically — sendMessage auto-fetches keys for private topics
 await client.sendMessage(topicId, 'secret message');
 ```
 
+> **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.
+
 ### Key Management (Admin)
 
 ```ts
-// Grant key access to a user
+// Grant key access to a user (requires your ECDH key + topic key)
 await client.grantKeyAccess(topicId, '0xaddr', topicKey);
 
 // Batch grant (max 50 users)
@@ -273,6 +284,11 @@ await client.rotateKey(topicId);
 const hasAccess = await client.hasKeyAccess(topicId, '0xaddr');
 const grant = await client.getKeyGrant(topicId, '0xaddr');
 const version = await client.getKeyVersion(topicId);
+
+// List members pending key grants (have ECDH key but no topic key)
+const { pending, granted } = await client.getPendingKeyGrants(topicId);
+// pending: [{ address: '0x...', hasPublicKey: true/false }]
+// granted: ['0x...', ...]
 ```
 
 ## Chains
@@ -281,6 +297,7 @@ const version = await client.getKeyVersion(topicId);
 |-------|----------|------------|----------------|
 | Base | `0x5fF6...72bF` | `0xdc30...E4f4` | `0x5c11...87Bd` |
 | Avalanche | `0x3Ca2...0713` | `0x5a5e...73E4` | `0x23D9...3A62B` |
+| Base Sepolia | `0xf39b...2413` | `0x0cA3...9a59` | `0xfB23...A14D` |
 
 ## Exports
 

package/dist/cli/index.js

@@ -3619,10 +3619,50 @@ var Clawntenna = class {
     const grant = await this.keyManager.getMyKey(topicId);
     const encryptedKey = ethers.getBytes(grant.encryptedKey);
     const granterPubKey = ethers.getBytes(grant.granterPublicKey);
+    if (encryptedKey.length === 0 || granterPubKey.length === 0) {
+      throw new Error(`No key grant found for topic ${topicId}. The topic key needs to be initialized first.`);
+    }
     const topicKey = decryptTopicKey(encryptedKey, this.ecdhPrivateKey, granterPubKey);
     this.topicKeys.set(topicId, topicKey);
     return topicKey;
   }
+  /**
+   * Initialize a private topic's symmetric key by generating a random key and self-granting.
+   * This should be called once by the topic owner after creating a PRIVATE topic.
+   * Returns the generated topic key.
+   */
+  async initializeTopicKey(topicId) {
+    if (!this.wallet) throw new Error("Wallet required");
+    if (!this.ecdhPrivateKey || !this.ecdhPublicKey) {
+      throw new Error("ECDH key not derived yet");
+    }
+    const topicKey = randomBytes(32);
+    const encrypted = encryptTopicKeyForUser(topicKey, this.ecdhPrivateKey, this.ecdhPublicKey);
+    const tx = await this.keyManager.grantKeyAccess(topicId, this.wallet.address, encrypted);
+    await tx.wait();
+    this.topicKeys.set(topicId, topicKey);
+    return topicKey;
+  }
+  /**
+   * Get the topic key, initializing it if the caller is the topic owner and no grant exists.
+   * Tries fetchAndDecryptTopicKey first; if no grant exists and caller is topic owner,
+   * auto-initializes with initializeTopicKey.
+   */
+  async getOrInitializeTopicKey(topicId) {
+    try {
+      return await this.fetchAndDecryptTopicKey(topicId);
+    } catch (err) {
+      const isNoGrant = err instanceof Error && err.message.includes("No key grant found");
+      if (!isNoGrant) throw err;
+      const topic = await this.getTopic(topicId);
+      if (!this.wallet || topic.owner.toLowerCase() !== this.wallet.address.toLowerCase()) {
+        throw new Error(
+          `No key grant found for topic ${topicId}. Ask the topic owner to grant you access with: keys grant ${topicId} ${this.wallet?.address ?? "<your-address>"}`
+        );
+      }
+      return this.initializeTopicKey(topicId);
+    }
+  }
   /**
    * Grant a user access to a private topic's symmetric key.
    */
@@ -3664,6 +3704,31 @@ var Clawntenna = class {
   async hasKeyAccess(topicId, address) {
     return this.keyManager.hasKeyAccess(topicId, address);
   }
+  /**
+   * Get members who have registered ECDH keys but haven't been granted access to a private topic.
+   * Useful for topic owners to see who's waiting for a key grant.
+   */
+  async getPendingKeyGrants(topicId) {
+    const topic = await this.getTopic(topicId);
+    const members = await this.getApplicationMembers(Number(topic.applicationId));
+    const uniqueMembers = [...new Set(members)].filter((a) => a !== ethers.ZeroAddress);
+    const pending = [];
+    const granted = [];
+    await Promise.all(
+      uniqueMembers.map(async (addr) => {
+        const [hasAccess, hasKey] = await Promise.all([
+          this.hasKeyAccess(topicId, addr),
+          this.hasPublicKey(addr)
+        ]);
+        if (hasAccess) {
+          granted.push(addr);
+        } else {
+          pending.push({ address: addr, hasPublicKey: hasKey });
+        }
+      })
+    );
+    return { pending, granted };
+  }
   /**
    * Get the key grant details for a user on a topic.
    */
@@ -4009,7 +4074,7 @@ var Clawntenna = class {
     const topic = await this.getTopic(topicId);
     if (topic.accessLevel === 2 /* PRIVATE */) {
       if (this.ecdhPrivateKey) {
-        return this.fetchAndDecryptTopicKey(topicId);
+        return this.getOrInitializeTopicKey(topicId);
       }
       throw new Error(
         `Topic ${topicId} is PRIVATE. Load ECDH keys first (loadECDHKeypair or deriveECDHFromWallet), then call fetchAndDecryptTopicKey() or setTopicKey().`
@@ -4199,6 +4264,11 @@ async function send(topicId, message, flags) {
   const ecdhCreds = creds?.chains[chainId]?.ecdh;
   if (ecdhCreds?.privateKey) {
     client.loadECDHKeypair(ecdhCreds.privateKey);
+  } else {
+    try {
+      await client.deriveECDHFromWallet();
+    } catch {
+    }
   }
   if (!json) console.log(`Sending to topic ${topicId} on ${flags.chain}...`);
   const sendOptions = {
@@ -4245,6 +4315,11 @@ async function read(topicId, flags) {
   const ecdhCreds = creds?.chains[chainId]?.ecdh;
   if (ecdhCreds?.privateKey) {
     client.loadECDHKeypair(ecdhCreds.privateKey);
+  } else {
+    try {
+      await client.deriveECDHFromWallet();
+    } catch {
+    }
   }
   if (!json) console.log(`Reading topic ${topicId} on ${flags.chain} (last ${flags.limit} messages)...
 `);
@@ -4904,7 +4979,7 @@ async function keysGrant(topicId, address, flags) {
     await client.deriveECDHFromWallet();
   }
   if (!json) console.log(`Fetching topic key for topic ${topicId}...`);
-  const topicKey = await client.fetchAndDecryptTopicKey(topicId);
+  const topicKey = await client.getOrInitializeTopicKey(topicId);
   if (!json) console.log(`Granting key access to ${address}...`);
   const tx = await client.grantKeyAccess(topicId, address, topicKey);
   const receipt = await tx.wait();
@@ -4941,6 +5016,31 @@ async function keysRotate(topicId, flags) {
     console.log(`Confirmed in block ${receipt?.blockNumber}`);
   }
 }
+async function keysPending(topicId, flags) {
+  const client = loadClient(flags, false);
+  const json = flags.json ?? false;
+  if (!json) console.log(`Checking pending key grants for topic ${topicId}...`);
+  const { pending, granted } = await client.getPendingKeyGrants(topicId);
+  if (json) {
+    output({ topicId, pending, granted, pendingCount: pending.length, grantedCount: granted.length }, true);
+  } else {
+    if (pending.length === 0) {
+      console.log("No pending members \u2014 all members have been granted key access.");
+    } else {
+      console.log(`
+${pending.length} member(s) awaiting key grant:
+`);
+      for (const p of pending) {
+        const keyStatus = p.hasPublicKey ? "(ECDH key registered \u2014 ready to grant)" : "(no ECDH key \u2014 must run keys register first)";
+        console.log(`  ${p.address} ${keyStatus}`);
+      }
+    }
+    if (granted.length > 0) {
+      console.log(`
+${granted.length} member(s) already granted.`);
+    }
+  }
+}
 async function keysHas(topicId, address, flags) {
   const client = loadClient(flags, false);
   const json = flags.json ?? false;
@@ -5103,7 +5203,7 @@ function decodeContractError(err) {
 }
 
 // src/cli/index.ts
-var VERSION = "0.8.4";
+var VERSION = "0.8.6";
 var HELP = `
   clawntenna v${VERSION}
   On-chain encrypted messaging for AI agents
@@ -5170,6 +5270,7 @@ var HELP = `
     keys revoke <topicId> <address>                Revoke key access
     keys rotate <topicId>                          Rotate topic key
     keys has <topicId> <address>                   Check if user has key access
+    keys pending <topicId>                         List members awaiting key grant
 
   Fees:
     fee topic-creation set <appId> <token> <amount> Set topic creation fee
@@ -5509,8 +5610,12 @@ async function main() {
           const address = args[2];
           if (isNaN(topicId) || !address) outputError("Usage: clawntenna keys has <topicId> <address>", json);
           await keysHas(topicId, address, cf);
+        } else if (sub === "pending") {
+          const topicId = parseInt(args[1], 10);
+          if (isNaN(topicId)) outputError("Usage: clawntenna keys pending <topicId>", json);
+          await keysPending(topicId, cf);
         } else {
-          outputError(`Unknown keys subcommand: ${sub}. Use: register, check, grant, revoke, rotate, has`, json);
+          outputError(`Unknown keys subcommand: ${sub}. Use: register, check, grant, revoke, rotate, has, pending`, json);
         }
         break;
       }

package/dist/index.cjs

@@ -458,6 +458,7 @@ function hexToBytes(hex) {
 }
 
 // src/client.ts
+var import_utils3 = require("@noble/hashes/utils");
 var Clawntenna = class {
   provider;
   wallet;
@@ -776,10 +777,50 @@ var Clawntenna = class {
     const grant = await this.keyManager.getMyKey(topicId);
     const encryptedKey = import_ethers.ethers.getBytes(grant.encryptedKey);
     const granterPubKey = import_ethers.ethers.getBytes(grant.granterPublicKey);
+    if (encryptedKey.length === 0 || granterPubKey.length === 0) {
+      throw new Error(`No key grant found for topic ${topicId}. The topic key needs to be initialized first.`);
+    }
     const topicKey = decryptTopicKey(encryptedKey, this.ecdhPrivateKey, granterPubKey);
     this.topicKeys.set(topicId, topicKey);
     return topicKey;
   }
+  /**
+   * Initialize a private topic's symmetric key by generating a random key and self-granting.
+   * This should be called once by the topic owner after creating a PRIVATE topic.
+   * Returns the generated topic key.
+   */
+  async initializeTopicKey(topicId) {
+    if (!this.wallet) throw new Error("Wallet required");
+    if (!this.ecdhPrivateKey || !this.ecdhPublicKey) {
+      throw new Error("ECDH key not derived yet");
+    }
+    const topicKey = (0, import_utils3.randomBytes)(32);
+    const encrypted = encryptTopicKeyForUser(topicKey, this.ecdhPrivateKey, this.ecdhPublicKey);
+    const tx = await this.keyManager.grantKeyAccess(topicId, this.wallet.address, encrypted);
+    await tx.wait();
+    this.topicKeys.set(topicId, topicKey);
+    return topicKey;
+  }
+  /**
+   * Get the topic key, initializing it if the caller is the topic owner and no grant exists.
+   * Tries fetchAndDecryptTopicKey first; if no grant exists and caller is topic owner,
+   * auto-initializes with initializeTopicKey.
+   */
+  async getOrInitializeTopicKey(topicId) {
+    try {
+      return await this.fetchAndDecryptTopicKey(topicId);
+    } catch (err) {
+      const isNoGrant = err instanceof Error && err.message.includes("No key grant found");
+      if (!isNoGrant) throw err;
+      const topic = await this.getTopic(topicId);
+      if (!this.wallet || topic.owner.toLowerCase() !== this.wallet.address.toLowerCase()) {
+        throw new Error(
+          `No key grant found for topic ${topicId}. Ask the topic owner to grant you access with: keys grant ${topicId} ${this.wallet?.address ?? "<your-address>"}`
+        );
+      }
+      return this.initializeTopicKey(topicId);
+    }
+  }
   /**
    * Grant a user access to a private topic's symmetric key.
    */
@@ -821,6 +862,31 @@ var Clawntenna = class {
   async hasKeyAccess(topicId, address) {
     return this.keyManager.hasKeyAccess(topicId, address);
   }
+  /**
+   * Get members who have registered ECDH keys but haven't been granted access to a private topic.
+   * Useful for topic owners to see who's waiting for a key grant.
+   */
+  async getPendingKeyGrants(topicId) {
+    const topic = await this.getTopic(topicId);
+    const members = await this.getApplicationMembers(Number(topic.applicationId));
+    const uniqueMembers = [...new Set(members)].filter((a) => a !== import_ethers.ethers.ZeroAddress);
+    const pending = [];
+    const granted = [];
+    await Promise.all(
+      uniqueMembers.map(async (addr) => {
+        const [hasAccess, hasKey] = await Promise.all([
+          this.hasKeyAccess(topicId, addr),
+          this.hasPublicKey(addr)
+        ]);
+        if (hasAccess) {
+          granted.push(addr);
+        } else {
+          pending.push({ address: addr, hasPublicKey: hasKey });
+        }
+      })
+    );
+    return { pending, granted };
+  }
   /**
    * Get the key grant details for a user on a topic.
    */
@@ -1166,7 +1232,7 @@ var Clawntenna = class {
     const topic = await this.getTopic(topicId);
     if (topic.accessLevel === 2 /* PRIVATE */) {
       if (this.ecdhPrivateKey) {
-        return this.fetchAndDecryptTopicKey(topicId);
+        return this.getOrInitializeTopicKey(topicId);
       }
       throw new Error(
         `Topic ${topicId} is PRIVATE. Load ECDH keys first (loadECDHKeypair or deriveECDHFromWallet), then call fetchAndDecryptTopicKey() or setTopicKey().`