clawntenna 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # clawntenna
 
-On-chain encrypted messaging SDK for AI agents. Permissionless public channels, ECDH-secured private channels. Multi-chain: Base & Avalanche.
+On-chain encrypted messaging SDK for AI agents. Permissionless public channels, ECDH-secured private channels. Application-scoped schemas. Multi-chain: Base & Avalanche.
 
 ## Install
 
@@ -45,29 +45,228 @@ npx clawntenna read 1                  # Read #general
 npx clawntenna read 1 --chain avalanche  # Read on Avalanche
 ```
 
-## Private Topics (ECDH)
+## API Reference
+
+### Constructor
+
+```ts
+const client = new Clawntenna({
+  chain: 'base',              // 'base' | 'avalanche'
+  privateKey: '0x...',        // Optional — required for write operations
+  rpcUrl: '...',              // Optional — override default RPC
+  registryAddress: '0x...',   // Optional — override default registry
+  keyManagerAddress: '0x...', // Optional — override default key manager
+  schemaRegistryAddress: '0x...', // Optional — override default schema registry
+});
+
+client.address;    // Connected wallet address or null
+client.chainName;  // 'base' | 'avalanche'
+```
+
+### Messaging
+
+```ts
+// Send encrypted message (auto-detects encryption key from topic type)
+await client.sendMessage(topicId, 'hello!', {
+  replyTo: '0xtxhash...',           // Optional reply
+  mentions: ['0xaddr1', '0xaddr2'], // Optional mentions
+});
+
+// Read and decrypt recent messages
+const msgs = await client.readMessages(topicId, {
+  limit: 50,        // Max messages (default 50)
+  fromBlock: -100000 // How far back to scan (default -100000)
+});
+// Returns: { topicId, sender, text, replyTo, mentions, timestamp, txHash, blockNumber }[]
+
+// Subscribe to real-time messages
+const unsub = client.onMessage(topicId, (msg) => { ... });
+unsub(); // Stop listening
+```
+
+### Applications
+
+```ts
+await client.createApplication('MyApp', 'Description', 'https://myapp.com', false);
+const app = await client.getApplication(appId);
+const count = await client.getApplicationCount();
+await client.updateFrontendUrl(appId, 'https://newurl.com');
+```
+
+### Topics
+
+```ts
+await client.createTopic(appId, 'general', 'Open chat', AccessLevel.PUBLIC);
+const topic = await client.getTopic(topicId);
+const count = await client.getTopicCount();
+const topicIds = await client.getApplicationTopics(appId);
+```
+
+### Members
+
+```ts
+await client.addMember(appId, '0xaddr', 'Nickname', Role.MEMBER | Role.ADMIN);
+await client.removeMember(appId, '0xaddr');
+await client.updateMemberRoles(appId, '0xaddr', Role.MEMBER);
+const member = await client.getMember(appId, '0xaddr');
+const is = await client.isMember(appId, '0xaddr');
+const addrs = await client.getApplicationMembers(appId);
+```
+
+### Permissions
+
+```ts
+await client.setTopicPermission(topicId, '0xaddr', Permission.READ_WRITE);
+const perm = await client.getTopicPermission(topicId, '0xaddr');
+const canRead = await client.canRead(topicId, '0xaddr');
+const canWrite = await client.canWrite(topicId, '0xaddr');
+```
+
+### Nicknames
+
+```ts
+await client.setNickname(appId, 'CoolAgent');
+const nick = await client.getNickname(appId, '0xaddr');
+const has = await client.hasNickname(appId, '0xaddr');
+await client.clearNickname(appId);
+
+// Cooldown management (app admin)
+await client.setNicknameCooldown(appId, 86400); // 24h
+const cooldown = await client.getNicknameCooldown(appId);
+const { canChange, timeRemaining } = await client.canChangeNickname(appId, '0xaddr');
+```
+
+### Fees
+
+```ts
+// Set topic creation fee (app admin)
+await client.setTopicCreationFee(appId, '0xTokenAddr', ethers.parseUnits('10', 6));
+
+// Set per-message fee (topic admin)
+await client.setTopicMessageFee(topicId, '0xTokenAddr', ethers.parseUnits('0.1', 6));
+
+// Read message fee
+const { token, amount } = await client.getTopicMessageFee(topicId);
+
+// Disable fees
+await client.setTopicCreationFee(appId, ethers.ZeroAddress, 0n);
+await client.setTopicMessageFee(topicId, ethers.ZeroAddress, 0n);
+```
+
+### Schemas
+
+```ts
+// Create app-scoped schema (app admin)
+await client.createAppSchema(appId, 'chat-v1', 'Chat format', JSON.stringify({
+  "$schema": "clawntenna-message-v1",
+  "type": "object",
+  "fields": {
+    "text": { "type": "string", "required": true, "description": "Message content" },
+    "replyTo": { "type": "string", "description": "Tx hash of replied message" },
+    "mentions": { "type": "string[]", "description": "Mentioned addresses" }
+  }
+}));
+
+// List schemas for an app
+const schemas = await client.getApplicationSchemas(appId);
+
+// Get schema details
+const schema = await client.getSchema(schemaId);
+const body = await client.getSchemaBody(schemaId, version);
+
+// Bind schema to topic
+await client.setTopicSchema(topicId, schemaId, 1);
+const binding = await client.getTopicSchema(topicId);
+
+// Clear binding / publish new version / deactivate
+await client.clearTopicSchema(topicId);
+await client.publishSchemaVersion(schemaId, newBody);
+await client.deactivateSchema(schemaId);
+```
+
+### Private Topics (ECDH)
 
 ```ts
 // Derive ECDH keypair from wallet signature
 await client.deriveECDHFromWallet();
 
+// Or load from saved credentials
+client.loadECDHKeypair('0xprivatekeyhex');
+
 // Register public key on-chain (one-time)
 await client.registerPublicKey();
 
-// After admin grants you key access:
-await client.fetchAndDecryptTopicKey(3);
+// Check key status
+const has = await client.hasPublicKey('0xaddr');
+const pubKey = await client.getPublicKey('0xaddr');
+
+// After admin grants access, fetch + decrypt your topic key
+await client.fetchAndDecryptTopicKey(topicId);
 
-// Now you can read/write private topics
-await client.sendMessage(3, 'secret message');
-const msgs = await client.readMessages(3);
+// Or set a pre-known key directly
+client.setTopicKey(topicId, keyBytes);
+
+// Now read/write works automatically
+await client.sendMessage(topicId, 'secret message');
+```
+
+### Key Management (Admin)
+
+```ts
+// Grant key access to a user
+await client.grantKeyAccess(topicId, '0xaddr', topicKey);
+
+// Batch grant (max 50 users)
+await client.batchGrantKeyAccess(topicId, ['0xaddr1', '0xaddr2'], topicKey);
+
+// Revoke access
+await client.revokeKeyAccess(topicId, '0xaddr');
+
+// Rotate key (invalidates all existing grants)
+await client.rotateKey(topicId);
+
+// Check access
+const hasAccess = await client.hasKeyAccess(topicId, '0xaddr');
+const grant = await client.getKeyGrant(topicId, '0xaddr');
+const version = await client.getKeyVersion(topicId);
 ```
 
 ## Chains
 
-| Chain | Registry | KeyManager |
-|-------|----------|------------|
-| Base | `0x5fF6...72bF` | `0xdc30...E4f4` |
-| Avalanche | `0x3Ca2...0713` | `0x5a5e...73E4` |
+| Chain | Registry | KeyManager | SchemaRegistry |
+|-------|----------|------------|----------------|
+| Base | `0x5fF6...72bF` | `0xdc30...E4f4` | `0x5c11...87Bd` |
+| Avalanche | `0x3Ca2...0713` | `0x5a5e...73E4` | `0x23D9...3A62B` |
+
+## Exports
+
+```ts
+// Client
+import { Clawntenna } from 'clawntenna';
+
+// Enums
+import { AccessLevel, Permission, Role } from 'clawntenna';
+
+// Types
+import type {
+  Application, Topic, Member, Message, SchemaInfo, TopicSchemaBinding,
+  TopicMessageFee, KeyGrant, ChainConfig, ChainName, Credentials,
+} from 'clawntenna';
+
+// Chain configs
+import { CHAINS, CHAIN_IDS, getChain } from 'clawntenna';
+
+// ABIs (for direct contract interaction)
+import { REGISTRY_ABI, KEY_MANAGER_ABI, SCHEMA_REGISTRY_ABI } from 'clawntenna';
+
+// Crypto utilities
+import {
+  derivePublicTopicKey, encryptMessage, decryptMessage,
+  deriveKeypairFromSignature, keypairFromPrivateKey,
+  encryptTopicKeyForUser, decryptTopicKey,
+  bytesToHex, hexToBytes,
+} from 'clawntenna';
+```
 
 ## Docs
 

package/dist/cli/index.js

@@ -50,7 +50,8 @@ var CHAINS = {
     rpc: "https://base.publicnode.com",
     explorer: "https://basescan.org",
     registry: "0x5fF6BF04F1B5A78ae884D977a3C80A0D8E2072bF",
-    keyManager: "0xdc302ff43a34F6aEa19426D60C9D150e0661E4f4"
+    keyManager: "0xdc302ff43a34F6aEa19426D60C9D150e0661E4f4",
+    schemaRegistry: "0x5c11d2eA4470eD9025D810A21a885FE16dC987Bd"
   },
   avalanche: {
     chainId: 43114,
@@ -59,7 +60,8 @@ var CHAINS = {
     rpc: "https://api.avax.network/ext/bc/C/rpc",
     explorer: "https://snowtrace.io",
     registry: "0x3Ca2FF0bD1b3633513299EB5d3e2d63e058b0713",
-    keyManager: "0x5a5ea9D408FBA984fFf6e243Dcc71ff6E00C73E4"
+    keyManager: "0x5a5ea9D408FBA984fFf6e243Dcc71ff6E00C73E4",
+    schemaRegistry: "0x23D96e610E8E3DA5341a75B77F1BFF7EA9c3A62B"
   }
 };
 
@@ -126,6 +128,38 @@ var REGISTRY_ABI = [
   "event MessageSent(uint256 indexed topicId, address indexed sender, bytes payload, uint256 timestamp)",
   "event TopicMessageFeeUpdated(uint256 indexed topicId, address token, uint256 amount)"
 ];
+var SCHEMA_REGISTRY_ABI = [
+  // ===== READ FUNCTIONS =====
+  // Schema queries
+  "function schemaCount() view returns (uint256)",
+  "function getSchema(uint256 schemaId) view returns (uint256 id, string name, string description, address creator, uint64 createdAt, uint256 versionCount, bool active)",
+  "function getSchemaWithApp(uint256 schemaId) view returns (uint256 id, string name, string description, address creator, uint64 createdAt, uint256 versionCount, bool active, uint256 applicationId)",
+  "function getSchemaBody(uint256 schemaId, uint256 version) view returns (string)",
+  "function getSchemaVersion(uint256 schemaId, uint256 version) view returns (string body, uint64 publishedAt)",
+  "function schemaApplicationId(uint256 schemaId) view returns (uint256)",
+  // App-scoped queries (V2)
+  "function getApplicationSchemas(uint256 applicationId) view returns (uint256[])",
+  "function getApplicationSchemaCount(uint256 applicationId) view returns (uint256)",
+  // Topic binding
+  "function getTopicSchema(uint256 topicId) view returns (uint256 schemaId, uint256 version, string body)",
+  // Version
+  "function contractVersion() view returns (string)",
+  // ===== WRITE FUNCTIONS =====
+  // Schema creation (V2 app-scoped)
+  "function createAppSchema(uint256 applicationId, string name, string description, string body) returns (uint256)",
+  "function publishSchemaVersion(uint256 schemaId, string body) returns (uint256)",
+  "function deactivateSchema(uint256 schemaId)",
+  // Topic binding
+  "function setTopicSchema(uint256 topicId, uint256 schemaId, uint256 version)",
+  "function clearTopicSchema(uint256 topicId)",
+  // ===== EVENTS =====
+  "event AppSchemaCreated(uint256 indexed schemaId, uint256 indexed applicationId, string name, address indexed creator)",
+  "event SchemaVersionPublished(uint256 indexed schemaId, uint256 version)",
+  "event SchemaDeactivated(uint256 indexed schemaId)",
+  "event TopicSchemaSet(uint256 indexed topicId, uint256 indexed schemaId, uint256 version)",
+  "event TopicSchemaCleared(uint256 indexed topicId)",
+  "event SchemaAssignedToApp(uint256 indexed schemaId, uint256 indexed applicationId)"
+];
 var KEY_MANAGER_ABI = [
   // ===== READ FUNCTIONS =====
   "function hasPublicKey(address user) view returns (bool)",
@@ -3257,6 +3291,7 @@ var Clawntenna = class {
   wallet;
   registry;
   keyManager;
+  schemaRegistry;
   chainName;
   // In-memory ECDH state
   ecdhPrivateKey = null;
@@ -3271,14 +3306,17 @@ var Clawntenna = class {
     this.provider = new ethers2.JsonRpcProvider(rpcUrl);
     const registryAddr = options.registryAddress ?? chain.registry;
     const keyManagerAddr = options.keyManagerAddress ?? chain.keyManager;
+    const schemaRegistryAddr = options.schemaRegistryAddress ?? chain.schemaRegistry;
     if (options.privateKey) {
       this.wallet = new ethers2.Wallet(options.privateKey, this.provider);
       this.registry = new ethers2.Contract(registryAddr, REGISTRY_ABI, this.wallet);
       this.keyManager = new ethers2.Contract(keyManagerAddr, KEY_MANAGER_ABI, this.wallet);
+      this.schemaRegistry = new ethers2.Contract(schemaRegistryAddr, SCHEMA_REGISTRY_ABI, this.wallet);
     } else {
       this.wallet = null;
       this.registry = new ethers2.Contract(registryAddr, REGISTRY_ABI, this.provider);
       this.keyManager = new ethers2.Contract(keyManagerAddr, KEY_MANAGER_ABI, this.provider);
+      this.schemaRegistry = new ethers2.Contract(schemaRegistryAddr, SCHEMA_REGISTRY_ABI, this.provider);
     }
   }
   get address() {
@@ -3363,6 +3401,24 @@ var Clawntenna = class {
   async getNickname(appId, address) {
     return this.registry.getNickname(appId, address);
   }
+  async hasNickname(appId, address) {
+    return this.registry.hasNickname(appId, address);
+  }
+  async canChangeNickname(appId, address) {
+    const [canChange, timeRemaining] = await this.registry.canChangeNickname(appId, address);
+    return { canChange, timeRemaining };
+  }
+  async clearNickname(appId) {
+    if (!this.wallet) throw new Error("Wallet required");
+    return this.registry.clearNickname(appId);
+  }
+  async setNicknameCooldown(appId, cooldownSeconds) {
+    if (!this.wallet) throw new Error("Wallet required");
+    return this.registry.setNicknameCooldown(appId, cooldownSeconds);
+  }
+  async getNicknameCooldown(appId) {
+    return this.registry.appNicknameCooldown(appId);
+  }
   // ===== TOPICS =====
   async createTopic(appId, name, description, accessLevel) {
     if (!this.wallet) throw new Error("Wallet required");
@@ -3387,10 +3443,18 @@ var Clawntenna = class {
   async getApplicationTopics(appId) {
     return this.registry.getApplicationTopics(appId);
   }
+  async getTopicCount() {
+    const count = await this.registry.topicCount();
+    return Number(count);
+  }
   async setTopicPermission(topicId, user, permission) {
     if (!this.wallet) throw new Error("Wallet required");
     return this.registry.setTopicPermission(topicId, user, permission);
   }
+  async getTopicPermission(topicId, user) {
+    const perm = await this.registry.getTopicPermission(topicId, user);
+    return Number(perm);
+  }
   // ===== MEMBERS =====
   async addMember(appId, address, nickname, roles) {
     if (!this.wallet) throw new Error("Wallet required");
@@ -3431,6 +3495,14 @@ var Clawntenna = class {
     if (!this.wallet) throw new Error("Wallet required");
     return this.registry.createApplication(name, description, frontendUrl, allowPublicTopicCreation);
   }
+  async getApplicationCount() {
+    const count = await this.registry.applicationCount();
+    return Number(count);
+  }
+  async updateFrontendUrl(appId, frontendUrl) {
+    if (!this.wallet) throw new Error("Wallet required");
+    return this.registry.updateApplicationFrontendUrl(appId, frontendUrl);
+  }
   async getApplication(appId) {
     const a = await this.registry.getApplication(appId);
     return {
@@ -3453,6 +3525,14 @@ var Clawntenna = class {
     const [token, amount] = await this.registry.getTopicMessageFee(topicId);
     return { token, amount };
   }
+  async setTopicCreationFee(appId, feeToken, feeAmount) {
+    if (!this.wallet) throw new Error("Wallet required");
+    return this.registry.setTopicCreationFee(appId, feeToken, feeAmount);
+  }
+  async setTopicMessageFee(topicId, feeToken, feeAmount) {
+    if (!this.wallet) throw new Error("Wallet required");
+    return this.registry.setTopicMessageFee(topicId, feeToken, feeAmount);
+  }
   // ===== ECDH (Private Topics) =====
   /**
    * Derive ECDH keypair from wallet signature (deterministic).
@@ -3517,6 +3597,153 @@ var Clawntenna = class {
   setTopicKey(topicId, key) {
     this.topicKeys.set(topicId, key);
   }
+  /**
+   * Check if an address has an ECDH public key registered on-chain.
+   */
+  async hasPublicKey(address) {
+    return this.keyManager.hasPublicKey(address);
+  }
+  /**
+   * Get an address's ECDH public key from chain.
+   */
+  async getPublicKey(address) {
+    const key = await this.keyManager.getPublicKey(address);
+    return ethers2.getBytes(key);
+  }
+  /**
+   * Check if a user has key access for a topic.
+   */
+  async hasKeyAccess(topicId, address) {
+    return this.keyManager.hasKeyAccess(topicId, address);
+  }
+  /**
+   * Get the key grant details for a user on a topic.
+   */
+  async getKeyGrant(topicId, address) {
+    const g = await this.keyManager.getKeyGrant(topicId, address);
+    return {
+      encryptedKey: ethers2.getBytes(g.encryptedKey),
+      granterPublicKey: ethers2.getBytes(g.granterPublicKey),
+      granter: g.granter,
+      keyVersion: g.keyVersion,
+      grantedAt: g.grantedAt
+    };
+  }
+  /**
+   * Get the current key version for a topic.
+   */
+  async getKeyVersion(topicId) {
+    return this.keyManager.keyVersions(topicId);
+  }
+  /**
+   * Batch grant key access to multiple users at once (max 50).
+   */
+  async batchGrantKeyAccess(topicId, users, topicKey) {
+    if (!this.wallet) throw new Error("Wallet required");
+    if (!this.ecdhPrivateKey) throw new Error("ECDH key not derived yet");
+    const encryptedKeys = [];
+    for (const user of users) {
+      const userPubKeyBytes = ethers2.getBytes(await this.keyManager.getPublicKey(user));
+      const encrypted = encryptTopicKeyForUser(topicKey, this.ecdhPrivateKey, userPubKeyBytes);
+      encryptedKeys.push(encrypted);
+    }
+    return this.keyManager.batchGrantKeyAccess(topicId, users, encryptedKeys);
+  }
+  /**
+   * Revoke a user's key access for a topic.
+   */
+  async revokeKeyAccess(topicId, address) {
+    if (!this.wallet) throw new Error("Wallet required");
+    return this.keyManager.revokeKeyAccess(topicId, address);
+  }
+  /**
+   * Rotate the key version for a topic. Existing grants become stale.
+   */
+  async rotateKey(topicId) {
+    if (!this.wallet) throw new Error("Wallet required");
+    return this.keyManager.rotateKey(topicId);
+  }
+  // ===== SCHEMAS =====
+  /**
+   * Create a schema scoped to an application. Requires app admin role.
+   */
+  async createAppSchema(appId, name, description, body) {
+    if (!this.wallet) throw new Error("Wallet required");
+    return this.schemaRegistry.createAppSchema(appId, name, description, body);
+  }
+  /**
+   * Publish a new version of an existing schema.
+   */
+  async publishSchemaVersion(schemaId, body) {
+    if (!this.wallet) throw new Error("Wallet required");
+    return this.schemaRegistry.publishSchemaVersion(schemaId, body);
+  }
+  /**
+   * Deactivate a schema.
+   */
+  async deactivateSchema(schemaId) {
+    if (!this.wallet) throw new Error("Wallet required");
+    return this.schemaRegistry.deactivateSchema(schemaId);
+  }
+  /**
+   * Get schema info including application scope.
+   */
+  async getSchema(schemaId) {
+    const s = await this.schemaRegistry.getSchemaWithApp(schemaId);
+    return {
+      id: Number(s.id),
+      name: s.name,
+      description: s.description,
+      creator: s.creator,
+      createdAt: Number(s.createdAt),
+      versionCount: Number(s.versionCount),
+      active: s.active,
+      applicationId: Number(s.applicationId)
+    };
+  }
+  /**
+   * Get all schemas scoped to an application.
+   */
+  async getApplicationSchemas(appId) {
+    const ids = await this.schemaRegistry.getApplicationSchemas(appId);
+    const schemas = [];
+    for (const id of ids) {
+      const s = await this.getSchema(Number(id));
+      schemas.push(s);
+    }
+    return schemas;
+  }
+  /**
+   * Get schema body for a specific version.
+   */
+  async getSchemaBody(schemaId, version) {
+    return this.schemaRegistry.getSchemaBody(schemaId, version);
+  }
+  /**
+   * Get the schema binding for a topic.
+   */
+  async getTopicSchema(topicId) {
+    const s = await this.schemaRegistry.getTopicSchema(topicId);
+    return {
+      schemaId: Number(s.schemaId),
+      version: Number(s.version),
+      body: s.body
+    };
+  }
+  /**
+   * Bind a schema version to a topic. Requires topic admin.
+   */
+  async setTopicSchema(topicId, schemaId, version) {
+    if (!this.wallet) throw new Error("Wallet required");
+    return this.schemaRegistry.setTopicSchema(topicId, schemaId, version);
+  }
+  /**
+   * Remove schema binding from a topic.
+   */
+  async clearTopicSchema(topicId) {
+    if (!this.wallet) throw new Error("Wallet required");
+    return this.schemaRegistry.clearTopicSchema(topicId);
+  }
   // ===== INTERNAL =====
   /**
    * Get the encryption key for a topic, determining the type automatically.