8004-solana 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marco De Rossi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,418 @@
+# 8004-solana
+
+> TypeScript SDK for ERC-8004 on Solana
+> Agent identity, reputation and validation standard
+
+[![npm](https://img.shields.io/npm/v/8004-solana)](https://www.npmjs.com/package/8004-solana)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub](https://img.shields.io/badge/GitHub-QuantuLabs%2F8004--solana--ts-blue)](https://github.com/QuantuLabs/8004-solana-ts)
+[![Solana Programs](https://img.shields.io/badge/Programs-8004--solana-purple)](https://github.com/QuantuLabs/8004-solana)
+
+> **v0.2.0** - Consolidated program architecture with Metaplex Core
+
+---
+
+## About
+
+**8004-solana-ts** is a TypeScript SDK implementing the [ERC-8004 standard](https://eips.ethereum.org/EIPS/eip-8004) on Solana. It provides a seamless way to:
+
+- **Register agents as NFTs** on Solana blockchain
+- **Manage agent metadata** and endpoints (MCP, A2A)
+- **Submit and query reputation feedback**
+- **Track agent ownership** and transfers
+- **OASF taxonomies** support (skills & domains)
+
+Built with compatibility in mind - API aligned with the reference [agent0-ts SDK](https://github.com/agent0lab/agent0-ts).
+
+---
+
+## Installation
+
+```bash
+npm install 8004-solana
+# or
+yarn add 8004-solana
+# or
+pnpm add 8004-solana
+```
+
+### Or install from GitHub
+
+```bash
+npm install github:QuantuLabs/8004-solana-ts
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { SolanaSDK } from '8004-solana';
+import { Keypair } from '@solana/web3.js';
+
+// 1. Setup SDK with signer
+const signer = Keypair.fromSecretKey(Uint8Array.from(JSON.parse(process.env.SOLANA_PRIVATE_KEY!)));
+const sdk = new SolanaSDK({ signer });
+
+// 2. Register a new agent
+const registration = await sdk.registerAgent('ipfs://QmAgentMetadata');
+const agentId = registration.agentId!;
+console.log(`✓ Agent #${agentId} registered`);
+
+// 3. Set on-chain metadata (optional)
+await sdk.setMetadata(agentId, 'version', '1.0.0');
+await sdk.setMetadata(agentId, 'certification', 'verified', true); // immutable
+console.log('✓ On-chain metadata set');
+
+// 4. Load agent data
+const agent = await sdk.loadAgent(agentId);
+console.log(`Agent: ${agent?.nft_name}, Owner: ${agent?.getOwnerPublicKey().toBase58()}`);
+
+// 5. Give feedback (from another user)
+await sdk.giveFeedback(agentId, {
+  score: 85,
+  tag1: 'helpful',
+  tag2: 'accurate',
+  fileUri: 'ipfs://QmFeedbackDetails',
+  fileHash: Buffer.alloc(32),
+});
+console.log('✓ Feedback submitted');
+
+// 6. Get reputation summary
+const summary = await sdk.getReputationSummary(agentId);
+console.log(`Score: ${summary.averageScore}/100 (${summary.count} reviews)`);
+
+// 7. Transfer agent (optional)
+// await sdk.transferAgent(agentId, newOwnerPublicKey);
+```
+
+> **Note**: For advanced queries like `getAgentsByOwner()`, a custom RPC provider is recommended.
+> Free tiers are available - see [RPC Provider Recommendations](#rpc-provider-recommendations).
+
+📁 **More examples**: See the [`examples/`](#examples) directory for complete usage patterns.
+
+---
+
+## SolanaSDK API Reference
+
+### Constructor
+
+```typescript
+import { SolanaSDK } from '8004-solana';
+import { Keypair } from '@solana/web3.js';
+
+// Default: devnet, read-only
+const sdk = new SolanaSDK();
+
+// With signer (for write operations)
+const sdk = new SolanaSDK({ signer: Keypair.generate() });
+
+// Custom RPC (for advanced queries)
+const sdk = new SolanaSDK({ rpcUrl: 'https://your-rpc.helius.dev' });
+
+// Full config
+const sdk = new SolanaSDK({
+  cluster: 'devnet',      // 'devnet' | 'mainnet-beta' (default: 'devnet')
+  rpcUrl: 'https://...',  // Optional custom RPC
+  signer: keypair,        // Optional signer for write operations
+});
+```
+
+### Utility Methods
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `isReadOnly` | `boolean` | True if SDK has no signer |
+| `canWrite` | `boolean` | True if SDK can perform write operations |
+| `chainId()` | `Promise<string>` | Returns `solana-{cluster}` (e.g., `solana-devnet`) |
+| `getCluster()` | `Cluster` | Returns current cluster name |
+| `registries()` | `Record<string, string>` | Returns program IDs (`IDENTITY`, `REPUTATION`, `VALIDATION`) |
+| `getProgramIds()` | `object` | Returns program IDs as PublicKey objects |
+| `getRpcUrl()` | `string` | Returns current RPC URL |
+| `supportsAdvancedQueries()` | `boolean` | True if RPC supports getProgramAccounts with memcmp |
+
+### Agent Read Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `loadAgent` | `(agentId: number \| bigint) => Promise<AgentAccount \| null>` | Load agent data from chain |
+| `getAgent` | `(agentId: number \| bigint) => Promise<AgentAccount \| null>` | Alias for loadAgent |
+| `agentExists` | `(agentId: number \| bigint) => Promise<boolean>` | Check if agent exists |
+| `getAgentOwner` | `(agentId: number \| bigint) => Promise<PublicKey \| null>` | Get agent owner |
+| `isAgentOwner` | `(agentId, address) => Promise<boolean>` | Check if address owns agent |
+
+### Agent Write Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `registerAgent` | `(tokenUri?, metadata?) => Promise<TransactionResult>` | Register new agent |
+| `transferAgent` | `(agentId, newOwner) => Promise<TransactionResult>` | Transfer agent ownership |
+| `setAgentUri` | `(agentId, newUri) => Promise<TransactionResult>` | Update agent URI |
+| `setMetadata` | `(agentId, key, value, immutable?) => Promise<TransactionResult>` | Set on-chain metadata (optional, PDA-based) |
+
+**On-chain Metadata (v0.2.0, optional):**
+
+Store arbitrary key-value pairs directly on-chain. This is optional - most agent data should be in the IPFS registration file.
+
+```typescript
+// Set mutable on-chain metadata (default)
+await sdk.setMetadata(agentId, 'version', '1.0.0');
+
+// Set immutable on-chain metadata (cannot be modified or deleted)
+await sdk.setMetadata(agentId, 'certification', 'verified', true);
+```
+
+### Reputation Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getSummary` | `(agentId, minScore?, clientFilter?) => Promise<ReputationSummary>` | Get full reputation summary |
+| `getReputationSummary` | `(agentId) => Promise<{count, averageScore}>` | Get simplified reputation stats |
+| `giveFeedback` | `(agentId, feedbackFile) => Promise<TransactionResult>` | Submit feedback |
+| `getFeedback` | `(agentId, client, index) => Promise<Feedback \| null>` | Read specific feedback |
+| `readFeedback` | `(agentId, client, index) => Promise<Feedback \| null>` | Alias for getFeedback |
+| `revokeFeedback` | `(agentId, index) => Promise<TransactionResult>` | Revoke submitted feedback |
+| `getLastIndex` | `(agentId, client) => Promise<bigint>` | Get last feedback index |
+| `appendResponse` | `(agentId, client, index, uri, hash) => Promise<TransactionResult>` | Add response to feedback |
+
+### Validation Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `requestValidation` | `(agentId, validator, methodId, uri, hash) => Promise<TransactionResult>` | Request validation |
+| `respondToValidation` | `(agentId, requestIndex, score, uri, hash, status) => Promise<TransactionResult>` | Respond to validation |
+
+### Advanced Queries (Requires Custom RPC)
+
+These methods require a custom RPC provider (Helius, Triton, etc.) that supports `getProgramAccounts`:
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getAgentsByOwner` | `(owner: PublicKey) => Promise<AgentAccount[]>` | Get all agents owned by address |
+| `readAllFeedback` | `(agentId, includeRevoked?) => Promise<Feedback[]>` | Get all feedback for agent |
+| `getClients` | `(agentId) => Promise<PublicKey[]>` | Get all clients who gave feedback |
+
+---
+
+## Architecture
+
+Built on a consolidated Solana program implementing ERC-8004:
+
+| Program | Program ID | Description |
+|---------|------------|-------------|
+| **AgentRegistry8004** | `HvF3JqhahcX7JfhbDRYYCJ7S3f6nJdrqu5yi9shyTREp` | Identity, Reputation & Validation (consolidated) |
+
+**v0.2.0 Changes:**
+- Single consolidated program (was 3 separate programs)
+- Uses **Metaplex Core** for NFTs (was Token Metadata)
+- Global feedback index (was per-client)
+- 89 tests passing on devnet
+
+---
+
+## RPC Provider Recommendations
+
+The default Solana devnet RPC works for basic operations but has rate limits.
+For **production use** or **advanced queries** (like `getProgramAccounts`), use a custom RPC provider.
+
+**Good news**: Free tiers are sufficient for most use cases!
+
+| Provider | Free Tier | Features | Signup |
+|----------|-----------|----------|--------|
+| **Helius** | 100k req/month | Full devnet support, getProgramAccounts | https://helius.dev |
+| **QuickNode** | 10M credits/month | Multi-chain support | https://quicknode.com |
+| **Alchemy** | 300M CU/month | WebSockets, enhanced APIs | https://alchemy.com |
+| **Triton** | Free tier available | Solana-focused | https://triton.one |
+
+### When do you need a custom RPC?
+
+| Operation | Default RPC | Custom RPC |
+|-----------|-------------|------------|
+| `loadAgent()` | Works | Works |
+| `giveFeedback()` | Works | Works |
+| `getSummary()` | Works | Works |
+| `getAgentsByOwner()` | **Fails** | Works |
+| `readAllFeedback()` | **Fails** | Works |
+| `getClients()` | **Fails** | Works |
+
+**Recommendation**: Start with default RPC. Switch to Helius free tier when you need advanced queries.
+
+```typescript
+const sdk = new SolanaSDK({
+  rpcUrl: 'https://your-helius-rpc.helius.dev',
+  signer: yourKeypair,
+});
+
+// Now advanced queries work
+const agents = await sdk.getAgentsByOwner(ownerPublicKey);
+```
+
+---
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/QuantuLabs/8004-solana-ts.git
+cd 8004-solana-ts
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npx tsx test-sdk-full-coverage.ts
+
+# Lint
+npm run lint
+
+# Format
+npm run format
+```
+
+---
+
+## Current Status
+
+### v0.2.0 - Consolidated Program Architecture
+
+**What's New:**
+- Single consolidated program (Identity + Reputation + Validation)
+- **Metaplex Core** NFTs (lighter, faster than Token Metadata)
+- Global feedback index for simpler PDA derivation
+- 89 comprehensive tests on devnet
+
+**Breaking Changes from v0.1.0:**
+- Program IDs changed (now single program)
+- Agent PDA uses Core asset address, not mint
+- Feedback PDA uses global index (no client address in seeds)
+- Response PDA removed client from seeds
+
+**Implemented:**
+- Agent registration with Metaplex Core
+- Metadata management + extensions
+- Permissionless feedback system
+- Reputation tracking with cached aggregates
+- Validation requests and responses
+- NFT-based agent identity
+- Interface parity with agent0-ts
+
+**Requires Custom RPC:**
+- `getAgentsByOwner()` - Requires getProgramAccounts
+- `readAllFeedback()` - Requires getProgramAccounts
+- `getClients()` - Requires getProgramAccounts
+
+---
+
+## Operation Costs (Devnet Measured v0.2.0)
+
+Costs measured via SDK E2E tests on Solana devnet:
+
+| Operation | Total Cost | Lamports | Notes |
+|-----------|------------|----------|-------|
+| Register Agent | **0.00651 SOL** | 6,507,280 | Core asset + AgentAccount |
+| Set On-chain Metadata (1st) | **0.00319 SOL** | 3,192,680 | +MetadataEntryPda |
+| Set On-chain Metadata (update) | 0.000005 SOL | 5,000 | TX fee only |
+| Give Feedback (1st) | 0.00332 SOL | 3,324,920 | Feedback + AgentReputation init |
+| Give Feedback (2nd+) | 0.00209 SOL | 2,086,040 | FeedbackAccount only |
+| Append Response (1st) | 0.00275 SOL | 2,747,240 | Response + ResponseIndex init |
+| Append Response (2nd+) | 0.00163 SOL | 1,626,680 | ResponseAccount only |
+| Revoke Feedback | 0.000005 SOL | 5,000 | TX fee only |
+| Request Validation | 0.00183 SOL | 1,828,520 | ValidationRequest |
+| Respond to Validation | 0.000005 SOL | 5,000 | TX fee only |
+| **Full Lifecycle** | **0.0245 SOL** | 24,521,040 | Complete test cycle |
+
+### First vs Subsequent Cost Savings
+
+| Operation | 1st Call | 2nd+ Calls | Savings |
+|-----------|----------|------------|---------|
+| Set On-chain Metadata | 0.00319 SOL | 0.000005 SOL | **-99%** |
+| Give Feedback | 0.00332 SOL | 0.00209 SOL | **-37%** |
+| Append Response | 0.00275 SOL | 0.00163 SOL | **-41%** |
+
+First operation creates init_if_needed accounts. Subsequent calls skip initialization.
+
+### v0.2.0 Optimizations
+
+| Optimization | Before | After | Savings |
+|--------------|--------|-------|---------|
+| FeedbackAccount | 375 bytes | 171 bytes | **-54%** |
+| ResponseAccount | 309 bytes | 105 bytes | **-66%** |
+| MetadataEntryPda | Vec (fixed) | Individual PDAs | Unlimited entries |
+
+**v0.2.0 Changes:**
+- **Hash-only storage**: URIs stored in events, only hashes on-chain
+- **Individual Metadata PDAs**: Unlimited entries, deletable for rent recovery
+- **Immutable on-chain metadata option**: Lock metadata permanently
+
+---
+
+## Contributing
+
+Contributions welcome! This is a **public build** project.
+
+### How to Contribute
+
+1. **Fork** the repository
+2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
+3. **Commit** your changes (`git commit -m 'feat: add amazing feature'`)
+4. **Push** to the branch (`git push origin feature/amazing-feature`)
+5. **Open** a Pull Request
+
+### Contribution Guidelines
+
+- Follow existing code style
+- Add tests for new features
+- Update documentation
+- Use conventional commits
+
+---
+
+## Examples
+
+See the `examples/` directory for complete usage examples:
+
+| Example | Description |
+|---------|-------------|
+| [`quick-start.ts`](examples/quick-start.ts) | Basic read/write operations |
+| [`feedback-usage.ts`](examples/feedback-usage.ts) | Submit and read feedback |
+| [`agent-update.ts`](examples/agent-update.ts) | Update agent metadata |
+| [`transfer-agent.ts`](examples/transfer-agent.ts) | Transfer agent ownership |
+| [`server-mode.ts`](examples/server-mode.ts) | Server/client architecture with skipSend |
+
+Run examples:
+```bash
+# Set your private key (JSON array format)
+export SOLANA_PRIVATE_KEY='[1,2,3,...]'
+
+# Run example
+npx tsx examples/quick-start.ts
+```
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+
+## Links
+
+- **ERC-8004 Standard**: [eips.ethereum.org/EIPS/eip-8004](https://eips.ethereum.org/EIPS/eip-8004)
+- **agent0-ts Reference SDK**: [github.com/agent0lab/agent0-ts](https://github.com/agent0lab/agent0-ts)
+- **Solana Programs**: [github.com/QuantuLabs/8004-solana](https://github.com/QuantuLabs/8004-solana)
+
+---
+
+## Acknowledgments
+
+- Built with inspiration from the [agent0](https://github.com/agent0lab/agent0-ts) ecosystem
+- Implements [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) standard on Solana
+- Powered by Solana blockchain and Metaplex Core
+
+---
+
+**Built for the Solana ecosystem** | v0.2.0

package/dist/core/agent-mint-resolver.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Agent Mint Resolver
+ * Resolves agent_id (bigint) to agent_mint (PublicKey) using Identity Registry accounts
+ *
+ * Strategy:
+ * - Scan the Identity Registry program (not Metaplex!) for AgentAccount PDAs
+ * - Each AgentAccount contains agent_id and agent_mint
+ * - Load all agents once and cache for O(1) subsequent lookups
+ *
+ * This is MUCH faster than scanning Metaplex (millions of NFTs) because:
+ * - Identity Registry has only ~27 agents vs millions of Metaplex metadata accounts
+ * - Single getProgramAccounts call fetches all mappings
+ */
+import { Connection, PublicKey } from '@solana/web3.js';
+/**
+ * Agent Mint Resolver
+ * Maps agent_id → agent_mint using Identity Registry accounts
+ */
+export declare class AgentMintResolver {
+    private cache;
+    private connection;
+    private cacheLoaded;
+    constructor(connection: Connection, _collectionMint?: PublicKey);
+    /**
+     * Resolve agent_id to agent_mint PublicKey
+     * @param agentId - Sequential agent ID (0, 1, 2...)
+     * @returns agent_mint PublicKey
+     * @throws Error if agent not found
+     */
+    resolve(agentId: bigint): Promise<PublicKey>;
+    /**
+     * Load all agents from Identity Registry and populate cache
+     * This is much faster than scanning Metaplex (one RPC call vs millions of accounts)
+     */
+    private loadAllAgents;
+    /**
+     * Manually add a mapping to cache (used after registration)
+     * @param agentId - Agent ID
+     * @param mint - Agent mint address
+     */
+    addToCache(agentId: bigint, mint: PublicKey): void;
+    /**
+     * Clear the cache (useful for testing or forcing refresh)
+     */
+    clearCache(): void;
+    /**
+     * Force reload all agents from chain
+     */
+    refresh(): Promise<void>;
+    /**
+     * Batch resolve multiple agent IDs
+     * More efficient than resolving one at a time
+     * @param agentIds - Array of agent IDs to resolve
+     * @returns Map of agent_id → agent_mint
+     */
+    batchResolve(agentIds: bigint[]): Promise<Map<bigint, PublicKey>>;
+    /**
+     * Get cache size (number of loaded agents)
+     */
+    get size(): number;
+}
+//# sourceMappingURL=agent-mint-resolver.d.ts.map

package/dist/core/agent-mint-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-mint-resolver.d.ts","sourceRoot":"","sources":["../../src/core/agent-mint-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAMxD;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,WAAW,CAAkB;gBAEzB,UAAU,EAAE,UAAU,EAAE,eAAe,CAAC,EAAE,SAAS;IAK/D;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAwBlD;;;OAGG;YACW,aAAa;IAuC3B;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI;IAIlD;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAiBvE;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/core/agent-mint-resolver.js

@@ -0,0 +1,141 @@
+/**
+ * Agent Mint Resolver
+ * Resolves agent_id (bigint) to agent_mint (PublicKey) using Identity Registry accounts
+ *
+ * Strategy:
+ * - Scan the Identity Registry program (not Metaplex!) for AgentAccount PDAs
+ * - Each AgentAccount contains agent_id and agent_mint
+ * - Load all agents once and cache for O(1) subsequent lookups
+ *
+ * This is MUCH faster than scanning Metaplex (millions of NFTs) because:
+ * - Identity Registry has only ~27 agents vs millions of Metaplex metadata accounts
+ * - Single getProgramAccounts call fetches all mappings
+ */
+import { AgentAccount } from './borsh-schemas.js';
+import { ACCOUNT_DISCRIMINATORS } from './instruction-discriminators.js';
+import { IDENTITY_PROGRAM_ID } from './pda-helpers.js';
+import bs58 from 'bs58';
+/**
+ * Agent Mint Resolver
+ * Maps agent_id → agent_mint using Identity Registry accounts
+ */
+export class AgentMintResolver {
+    constructor(connection, _collectionMint) {
+        this.cache = new Map();
+        this.cacheLoaded = false;
+        this.connection = connection;
+        // collectionMint is no longer needed (was for Metaplex filtering)
+    }
+    /**
+     * Resolve agent_id to agent_mint PublicKey
+     * @param agentId - Sequential agent ID (0, 1, 2...)
+     * @returns agent_mint PublicKey
+     * @throws Error if agent not found
+     */
+    async resolve(agentId) {
+        const cacheKey = agentId.toString();
+        // Check cache first (O(1))
+        if (this.cache.has(cacheKey)) {
+            return this.cache.get(cacheKey);
+        }
+        // If cache not loaded, load all agents from Identity Registry
+        if (!this.cacheLoaded) {
+            await this.loadAllAgents();
+        }
+        // Now check cache again
+        const mint = this.cache.get(cacheKey);
+        if (!mint) {
+            throw new Error(`Agent #${agentId} not found. The agent may not exist.`);
+        }
+        return mint;
+    }
+    /**
+     * Load all agents from Identity Registry and populate cache
+     * This is much faster than scanning Metaplex (one RPC call vs millions of accounts)
+     */
+    async loadAllAgents() {
+        try {
+            // Get AgentAccount discriminator bytes for filtering
+            const discriminatorBytes = bs58.encode(ACCOUNT_DISCRIMINATORS.AgentAccount);
+            // Fetch ALL AgentAccount PDAs from Identity Registry (single RPC call)
+            const accounts = await this.connection.getProgramAccounts(IDENTITY_PROGRAM_ID, {
+                filters: [
+                    {
+                        memcmp: {
+                            offset: 0,
+                            bytes: discriminatorBytes,
+                        },
+                    },
+                ],
+            });
+            // Parse each account and populate cache
+            for (const { account } of accounts) {
+                try {
+                    const agentAccount = AgentAccount.deserialize(Buffer.from(account.data));
+                    const agentId = agentAccount.agent_id.toString();
+                    const agentMint = agentAccount.getMintPublicKey();
+                    this.cache.set(agentId, agentMint);
+                }
+                catch {
+                    // Skip malformed accounts
+                    continue;
+                }
+            }
+            this.cacheLoaded = true;
+            console.log(`AgentMintResolver: Loaded ${this.cache.size} agents from Identity Registry`);
+        }
+        catch (error) {
+            console.error(`Error loading agents from Identity Registry: ${error}`);
+            throw new Error(`Failed to load agents: ${error}`);
+        }
+    }
+    /**
+     * Manually add a mapping to cache (used after registration)
+     * @param agentId - Agent ID
+     * @param mint - Agent mint address
+     */
+    addToCache(agentId, mint) {
+        this.cache.set(agentId.toString(), mint);
+    }
+    /**
+     * Clear the cache (useful for testing or forcing refresh)
+     */
+    clearCache() {
+        this.cache.clear();
+        this.cacheLoaded = false;
+    }
+    /**
+     * Force reload all agents from chain
+     */
+    async refresh() {
+        this.clearCache();
+        await this.loadAllAgents();
+    }
+    /**
+     * Batch resolve multiple agent IDs
+     * More efficient than resolving one at a time
+     * @param agentIds - Array of agent IDs to resolve
+     * @returns Map of agent_id → agent_mint
+     */
+    async batchResolve(agentIds) {
+        // Ensure cache is loaded
+        if (!this.cacheLoaded) {
+            await this.loadAllAgents();
+        }
+        const results = new Map();
+        for (const agentId of agentIds) {
+            const mint = this.cache.get(agentId.toString());
+            if (mint) {
+                results.set(agentId, mint);
+            }
+        }
+        return results;
+    }
+    /**
+     * Get cache size (number of loaded agents)
+     */
+    get size() {
+        return this.cache.size;
+    }
+}
+//# sourceMappingURL=agent-mint-resolver.js.map

package/dist/core/agent-mint-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-mint-resolver.js","sourceRoot":"","sources":["../../src/core/agent-mint-resolver.ts"],"names":[],"mappings":"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"}