8004-solana 0.2.2 → 0.4.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Marco De Rossi
+Copyright (c) 2025-2026 QuantuLabs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -8,6 +8,8 @@
 [![GitHub](https://img.shields.io/badge/GitHub-QuantuLabs%2F8004--solana-blue)](https://github.com/QuantuLabs/8004-solana)
 [![Solana Programs](https://img.shields.io/badge/Programs-8004--solana-purple)](https://github.com/QuantuLabs/8004-solana)
 
+> **[How to register your first agent in 5 steps](./docs/quickstart.html)**
+
 ---
 
 ## About
@@ -52,7 +54,77 @@ const signer = Keypair.fromSecretKey(Uint8Array.from(privateKey));
 const sdk = new SolanaSDK({ signer });
 ```
 
-### 2. Register an Agent
+### 2. Create a Collection (Optional)
+
+Users can create their own collections to organize agents:
+
+```typescript
+import {
+  SolanaSDK,
+  IPFSClient,
+  buildCollectionMetadataJson
+} from '8004-solana';
+
+// 1. Build collection metadata using the helper
+const collectionData = buildCollectionMetadataJson({
+  name: 'My AI Agents',
+  description: 'Production AI agents for automation',
+  image: 'ipfs://QmLogo...',
+  category: 'automation',
+  tags: ['enterprise', 'api'],
+  project: {
+    name: 'Acme Corp',
+    socials: {
+      website: 'https://acme.ai',
+      x: 'acme_ai'
+    }
+  }
+});
+
+// 2. Upload metadata to IPFS
+const ipfs = new IPFSClient({ pinataJwt: process.env.PINATA_JWT });
+const collectionCid = await ipfs.addJson(collectionData);
+
+// 3. Create collection on-chain
+const sdk = new SolanaSDK({ signer });
+const collectionResult = await sdk.createCollection(
+  collectionData.name,              // Collection name (max 32 bytes)
+  `ipfs://${collectionCid}`         // Collection metadata URI
+);
+
+console.log('Collection:', collectionResult.collection?.toBase58());
+
+// 4. Register agents in your collection
+const agentResult = await sdk.registerAgent(
+  'ipfs://QmAgentMetadata...',       // Agent metadata URI
+  collectionResult.collection         // Your collection
+);
+```
+
+**Collection Metadata JSON Schema:**
+
+```json
+{
+  "name": "Acme AI Agents",
+  "description": "Production-ready AI agents for enterprise automation",
+  "image": "ipfs://QmXxx.../logo.png",
+  "external_url": "https://acme.ai/agents",
+  "project": {
+    "name": "Acme Corporation",
+    "socials": {
+      "website": "https://acme.ai",
+      "x": "acme_ai",
+      "github": "acme-ai"
+    }
+  },
+  "category": "automation",
+  "tags": ["enterprise", "automation", "api"]
+}
+```
+
+> See full schemas: [`schemas/collection-metadata.schema.json`](schemas/collection-metadata.schema.json) and [`schemas/agent-metadata.schema.json`](schemas/agent-metadata.schema.json)
+
+### 3. Register an Agent (Detailed)
 
 **Step 1: Setup IPFS Client**
 
@@ -110,8 +182,15 @@ const metadataUri = `ipfs://${metadataCid}`;
 
 ```typescript
 const sdk = new SolanaSDK({ signer });
+
+// Register in default collection
 const result = await sdk.registerAgent(metadataUri);
-console.log(`Agent #${result.agentId} registered!`);
+console.log(`Agent registered! Asset: ${result.asset.toBase58()}`);
+
+// Or register in your own collection
+// Note: Only the collection creator can register agents in their collection
+const myCollection = new PublicKey('YourCollectionPublicKey...');
+const result2 = await sdk.registerAgent(metadataUri, myCollection);
 ```
 
 **Alternative: Use Web URLs**
@@ -130,11 +209,14 @@ const metadata = buildRegistrationFileJson({
 await sdk.registerAgent('https://my-server.com/agent-metadata.json');
 ```
 
-### 3. Load Agent Data
+### 4. Load Agent Data
 
 ```typescript
-// Fetch agent by ID
-const agent = await sdk.loadAgent(agentId);
+import { PublicKey } from '@solana/web3.js';
+
+// Fetch agent by asset (PublicKey)
+const agentAsset = new PublicKey('AgentAssetPublicKey...');
+const agent = await sdk.loadAgent(agentAsset);
 
 if (agent) {
   console.log(`Name: ${agent.nft_name}`);
@@ -144,58 +226,56 @@ if (agent) {
 }
 
 // Or fetch all agents owned by a wallet (requires custom RPC)
-import { PublicKey } from '@solana/web3.js';
-
 const ownerWallet = new PublicKey('YourWalletAddress...');
 const myAgents = await sdk.getAgentsByOwner(ownerWallet);
 
 for (const agent of myAgents) {
-  console.log(`Agent #${agent.agent_id}: ${agent.nft_name}`);
+  console.log(`Agent: ${agent.nft_name} (${agent.getAssetPublicKey().toBase58().slice(0,8)}...)`);
 }
 ```
 
-### 4. Give Feedback
+### 5. Give Feedback
 
 ```typescript
 // Submit feedback for an agent (as a client/user)
 // Score is 0-100, tags are optional keywords
-await sdk.giveFeedback(agentId, {
-  score: 85,                              // Rating out of 100
-  tag1: 'helpful',                        // Optional: first tag
-  tag2: 'accurate',                       // Optional: second tag
-  fileUri: 'ipfs://QmFeedbackDetails',    // Optional: detailed feedback file
-  fileHash: Buffer.alloc(32),             // Optional: SHA256 hash of file
+await sdk.giveFeedback(agentAsset, {
+  score: 85,                                // Rating out of 100
+  tag1: 'helpful',                          // Optional: first tag
+  tag2: 'accurate',                         // Optional: second tag
+  feedbackUri: 'ipfs://QmFeedbackDetails',  // Optional: detailed feedback file
+  feedbackHash: Buffer.alloc(32),           // Optional: SHA256 hash of file
 });
 ```
 
-### 5. Get Reputation
+### 6. Get Reputation
 
 ```typescript
 // Get aggregated reputation stats
-const summary = await sdk.getSummary(agentId);
+const summary = await sdk.getSummary(agentAsset);
 console.log(`Average Score: ${summary.averageScore}/100`);
 console.log(`Total Feedbacks: ${summary.totalFeedbacks}`);
 console.log(`Next Index: ${summary.nextFeedbackIndex}`);
 
 // Read all individual feedbacks (requires custom RPC)
-const feedbacks = await sdk.readAllFeedback(agentId);
+const feedbacks = await sdk.readAllFeedback(agentAsset);
 for (const fb of feedbacks) {
   console.log(`Score: ${fb.score}, Client: ${fb.client.toBase58()}`);
 }
 ```
 
-### 6. Bulk Queries (Indexing)
+### 7. Bulk Queries (Indexer)
 
 ```typescript
 // Get ALL agents with their feedbacks in just 4 RPC calls
 const agents = await sdk.getAllAgents({ includeFeedbacks: true });
 for (const { account, feedbacks } of agents) {
-  console.log(`Agent #${account.agent_id}: ${feedbacks?.length || 0} feedbacks`);
+  console.log(`Agent ${account.getAssetPublicKey().toBase58().slice(0,8)}...: ${feedbacks?.length || 0} feedbacks`);
 }
 
-// Or get ALL feedbacks separately as a Map
+// Or get ALL feedbacks separately as a Map (keyed by asset string)
 const feedbacksMap = await sdk.getAllFeedbacks();
-const agent83Feedbacks = feedbacksMap.get(83n) || [];
+const agentFeedbacks = feedbacksMap.get(agentAsset.toBase58()) || [];
 ```
 
 > **Note**: For advanced queries like `getAllAgents()`, `getAllFeedbacks()`, or `readAllFeedback()`, a custom RPC provider is required.
@@ -210,7 +290,7 @@ const agent83Feedbacks = feedbacksMap.get(83n) || [];
 - **[OASF Taxonomies](docs/OASF.md)** - Skills and domains reference
 - **[Changelog](docs/CHANGELOG.md)** - Version history and breaking changes
 
-**Program ID:** `HvF3JqhahcX7JfhbDRYYCJ7S3f6nJdrqu5yi9shyTREp`
+**Program ID (Devnet):** `HHCVWcqsziJMmp43u2UAgAfH2cBjUFxVdW1M3C3NqzvT`
 
 ---
 
@@ -312,7 +392,7 @@ See the `examples/` directory for complete usage examples:
 | [`agent-update.ts`](examples/agent-update.ts) | On-chain metadata & URI update |
 | [`transfer-agent.ts`](examples/transfer-agent.ts) | Transfer agent ownership |
 | [`server-mode.ts`](examples/server-mode.ts) | Server/client architecture with skipSend |
-| [`basic-indexer.ts`](examples/basic-indexer.ts) | Index all agents to JSON file |
+| [`basic-indexer.ts`](examples/basic-indexer.ts) | Indexer reference → [8004-solana-indexer](https://github.com/QuantuLabs/8004-solana-indexer) |
 
 Run examples:
 ```bash
@@ -352,4 +432,4 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 ---
 
-**Built for the Solana ecosystem** | v0.2.2
+**Built for the Solana ecosystem** | v0.4.0

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

@@ -1,44 +1,71 @@
 /**
- * Agent Mint Resolver
- * Resolves agent_id (bigint) to agent_mint (PublicKey) using Identity Registry accounts
+ * Agent Resolver
+ * v0.3.0 - Asset-based identification
  *
- * 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
+ * NOTE: This class is largely deprecated in v0.3.0 since agents are now
+ * identified directly by their Metaplex Core asset pubkey, not by sequential IDs.
  *
- * 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
+ * The class is kept for backwards compatibility but most methods are deprecated.
+ * Use the asset pubkey directly instead of resolving from agent_id.
  */
 import { Connection, PublicKey } from '@solana/web3.js';
+import { AgentAccount } from './borsh-schemas.js';
+export interface LoadAgentsOptions {
+    /**
+     * Maximum number of accounts to load (default: 1000)
+     * Security: Prevents OOM from unbounded getProgramAccounts
+     */
+    maxAccounts?: number;
+    /**
+     * If true, throw on malformed accounts instead of skipping
+     * Default: false (skip malformed accounts with warning)
+     */
+    strictParsing?: boolean;
+}
 /**
- * Agent Mint Resolver
- * Maps agent_id → agent_mint using Identity Registry accounts
+ * Agent Resolver
+ * v0.3.0 - Validates assets and loads agent accounts
+ *
+ * @deprecated In v0.3.0, agents are identified by their asset pubkey directly.
+ * Use asset pubkeys instead of agent_id numbers.
+ *
+ * Security: Thread-safety protection added in v0.3.0 - cache updates are atomic.
  */
 export declare class AgentMintResolver {
-    private cache;
+    private assetCache;
     private connection;
     private cacheLoaded;
+    private loadingPromise;
     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
+     * @deprecated Use asset pubkey directly. In v0.3.0, agents are identified by asset, not agent_id.
+     *
+     * For backwards compatibility, this method now throws an error.
+     * Use getAgentByAsset() instead.
+     */
+    resolve(_agentId: bigint): Promise<PublicKey>;
+    /**
+     * Get AgentAccount by asset pubkey - v0.3.0
+     * @param asset - Metaplex Core asset pubkey
+     * @returns AgentAccount or null if not found
+     */
+    getAgentByAsset(asset: PublicKey): Promise<AgentAccount | null>;
+    /**
+     * Check if an asset is a registered agent
+     * @param asset - Metaplex Core asset pubkey
+     * @returns true if the asset is a registered agent
      */
-    resolve(agentId: bigint): Promise<PublicKey>;
+    isRegisteredAgent(asset: PublicKey): Promise<boolean>;
     /**
-     * Load all agents from Identity Registry and populate cache
-     * This is much faster than scanning Metaplex (one RPC call vs millions of accounts)
+     * Load all agents from Identity Registry
+     * Security: Limited to maxAccounts (default 1000) to prevent OOM
      */
-    private loadAllAgents;
+    loadAllAgents(options?: LoadAgentsOptions): Promise<Map<string, AgentAccount>>;
+    private doLoadAllAgents;
     /**
-     * Manually add a mapping to cache (used after registration)
-     * @param agentId - Agent ID
-     * @param mint - Agent mint address
+     * @deprecated Use asset pubkey directly. No need to cache agent_id → asset mapping.
      */
-    addToCache(agentId: bigint, mint: PublicKey): void;
+    addToCache(_agentId: bigint, _mint: PublicKey): void;
     /**
      * Clear the cache (useful for testing or forcing refresh)
      */
@@ -48,12 +75,9 @@ export declare class AgentMintResolver {
      */
     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
+     * @deprecated Use loadAllAgents() instead. Agent IDs no longer exist.
      */
-    batchResolve(agentIds: bigint[]): Promise<Map<bigint, PublicKey>>;
+    batchResolve(_agentIds: bigint[]): Promise<Map<bigint, PublicKey>>;
     /**
      * Get cache size (number of loaded agents)
      */

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

@@ -1 +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"}
+{"version":3,"file":"agent-mint-resolver.d.ts","sourceRoot":"","sources":["../../src/core/agent-mint-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAYlD,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,UAAU,CAAwC;IAC1D,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,cAAc,CAAmD;gBAE7D,UAAU,EAAE,UAAU,EAAE,eAAe,CAAC,EAAE,SAAS;IAI/D;;;;;OAKG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAQnD;;;;OAIG;IACG,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAyBrE;;;;OAIG;IACG,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IAK3D;;;OAGG;IACG,aAAa,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;YAS1E,eAAe;IAqE7B;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI;IAIpD;;OAEG;IACH,UAAU,IAAI,IAAI;IAMlB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B;;OAEG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAOxE;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

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

@@ -1,63 +1,102 @@
 /**
- * Agent Mint Resolver
- * Resolves agent_id (bigint) to agent_mint (PublicKey) using Identity Registry accounts
+ * Agent Resolver
+ * v0.3.0 - Asset-based identification
  *
- * 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
+ * NOTE: This class is largely deprecated in v0.3.0 since agents are now
+ * identified directly by their Metaplex Core asset pubkey, not by sequential IDs.
  *
- * 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
+ * The class is kept for backwards compatibility but most methods are deprecated.
+ * Use the asset pubkey directly instead of resolving from agent_id.
  */
 import { AgentAccount } from './borsh-schemas.js';
 import { ACCOUNT_DISCRIMINATORS } from './instruction-discriminators.js';
-import { IDENTITY_PROGRAM_ID } from './pda-helpers.js';
+import { IDENTITY_PROGRAM_ID, PDAHelpers } from './pda-helpers.js';
+import { logger } from '../utils/logger.js';
 import bs58 from 'bs58';
 /**
- * Agent Mint Resolver
- * Maps agent_id → agent_mint using Identity Registry accounts
+ * Security: Default limit for getProgramAccounts to prevent OOM
+ * For production with large agent registries, use an indexer instead.
+ */
+const DEFAULT_MAX_ACCOUNTS = 1000;
+/**
+ * Agent Resolver
+ * v0.3.0 - Validates assets and loads agent accounts
+ *
+ * @deprecated In v0.3.0, agents are identified by their asset pubkey directly.
+ * Use asset pubkeys instead of agent_id numbers.
+ *
+ * Security: Thread-safety protection added in v0.3.0 - cache updates are atomic.
  */
 export class AgentMintResolver {
+    assetCache = new Map();
+    connection;
+    cacheLoaded = false;
+    loadingPromise = null;
     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
+     * @deprecated Use asset pubkey directly. In v0.3.0, agents are identified by asset, not agent_id.
+     *
+     * For backwards compatibility, this method now throws an error.
+     * Use getAgentByAsset() instead.
      */
-    async resolve(agentId) {
-        const cacheKey = agentId.toString();
-        // Check cache first (O(1))
-        if (this.cache.has(cacheKey)) {
-            return this.cache.get(cacheKey);
+    async resolve(_agentId) {
+        throw new Error('AgentMintResolver.resolve() is deprecated in v0.3.0. ' +
+            'Agents are now identified by asset pubkey, not agent_id. ' +
+            'Use asset pubkey directly or getAgentByAsset() to validate an asset.');
+    }
+    /**
+     * Get AgentAccount by asset pubkey - v0.3.0
+     * @param asset - Metaplex Core asset pubkey
+     * @returns AgentAccount or null if not found
+     */
+    async getAgentByAsset(asset) {
+        const cacheKey = asset.toBase58();
+        // Check cache first
+        if (this.assetCache.has(cacheKey)) {
+            return this.assetCache.get(cacheKey);
         }
-        // If cache not loaded, load all agents from Identity Registry
-        if (!this.cacheLoaded) {
-            await this.loadAllAgents();
+        // Derive AgentAccount PDA
+        const [agentPda] = PDAHelpers.getAgentPDA(asset);
+        try {
+            const accountInfo = await this.connection.getAccountInfo(agentPda);
+            if (!accountInfo) {
+                return null;
+            }
+            const agentAccount = AgentAccount.deserialize(Buffer.from(accountInfo.data));
+            this.assetCache.set(cacheKey, agentAccount);
+            return agentAccount;
         }
-        // Now check cache again
-        const mint = this.cache.get(cacheKey);
-        if (!mint) {
-            throw new Error(`Agent #${agentId} not found. The agent may not exist.`);
+        catch {
+            return null;
         }
-        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)
+     * Check if an asset is a registered agent
+     * @param asset - Metaplex Core asset pubkey
+     * @returns true if the asset is a registered agent
      */
-    async loadAllAgents() {
+    async isRegisteredAgent(asset) {
+        const agent = await this.getAgentByAsset(asset);
+        return agent !== null;
+    }
+    /**
+     * Load all agents from Identity Registry
+     * Security: Limited to maxAccounts (default 1000) to prevent OOM
+     */
+    async loadAllAgents(options = {}) {
+        if (this.loadingPromise) {
+            return await this.loadingPromise;
+        }
+        this.loadingPromise = this.doLoadAllAgents(options);
+        return await this.loadingPromise;
+    }
+    async doLoadAllAgents(options) {
+        const maxAccounts = options.maxAccounts ?? DEFAULT_MAX_ACCOUNTS;
+        const strictParsing = options.strictParsing ?? false;
         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: [
                     {
@@ -68,41 +107,60 @@ export class AgentMintResolver {
                     },
                 ],
             });
-            // Parse each account and populate cache
-            for (const { account } of accounts) {
+            // Security: Warn if limit reached - may indicate need for indexer
+            const limitReached = accounts.length > maxAccounts;
+            if (limitReached) {
+                logger.warn(`getProgramAccounts returned ${accounts.length} agents, limiting to ${maxAccounts}. ` +
+                    `Consider using an indexer for production.`);
+            }
+            // Security: Build in temp map, then atomic swap to prevent race conditions
+            const tempCache = new Map();
+            let skippedAccounts = 0;
+            const accountsToProcess = accounts.slice(0, maxAccounts);
+            for (const { account } of accountsToProcess) {
                 try {
                     const agentAccount = AgentAccount.deserialize(Buffer.from(account.data));
-                    const agentId = agentAccount.agent_id.toString();
-                    const agentMint = agentAccount.getMintPublicKey();
-                    this.cache.set(agentId, agentMint);
+                    const assetPubkey = agentAccount.getAssetPublicKey();
+                    tempCache.set(assetPubkey.toBase58(), agentAccount);
                 }
-                catch {
-                    // Skip malformed accounts
-                    continue;
+                catch (parseError) {
+                    if (strictParsing) {
+                        throw new Error(`Failed to parse AgentAccount: ${parseError instanceof Error ? parseError.message : 'Unknown error'}`);
+                    }
+                    skippedAccounts++;
                 }
             }
+            // Security: Log warning if accounts were skipped (may indicate corruption)
+            if (skippedAccounts > 0) {
+                logger.warn(`Skipped ${skippedAccounts} malformed AgentAccount(s) during load. ` +
+                    `Use strictParsing: true to fail on parse errors.`);
+            }
+            // Atomic swap - prevents race condition with concurrent reads
+            this.assetCache = tempCache;
             this.cacheLoaded = true;
-            console.log(`AgentMintResolver: Loaded ${this.cache.size} agents from Identity Registry`);
+            this.loadingPromise = null;
+            return this.assetCache;
         }
         catch (error) {
-            console.error(`Error loading agents from Identity Registry: ${error}`);
-            throw new Error(`Failed to load agents: ${error}`);
+            this.loadingPromise = null;
+            // Security: Don't leak internal error details
+            logger.error('Failed to load agents from Identity Registry', error);
+            throw new Error('Failed to load agents from Identity Registry');
         }
     }
     /**
-     * Manually add a mapping to cache (used after registration)
-     * @param agentId - Agent ID
-     * @param mint - Agent mint address
+     * @deprecated Use asset pubkey directly. No need to cache agent_id → asset mapping.
      */
-    addToCache(agentId, mint) {
-        this.cache.set(agentId.toString(), mint);
+    addToCache(_agentId, _mint) {
+        // No-op in v0.3.0
     }
     /**
      * Clear the cache (useful for testing or forcing refresh)
      */
     clearCache() {
-        this.cache.clear();
+        this.assetCache.clear();
         this.cacheLoaded = false;
+        this.loadingPromise = null;
     }
     /**
      * Force reload all agents from chain
@@ -112,30 +170,17 @@ export class AgentMintResolver {
         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
+     * @deprecated Use loadAllAgents() instead. Agent IDs no longer exist.
      */
-    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;
+    async batchResolve(_agentIds) {
+        throw new Error('AgentMintResolver.batchResolve() is deprecated in v0.3.0. ' +
+            'Use loadAllAgents() to get all registered agents.');
     }
     /**
      * Get cache size (number of loaded agents)
      */
     get size() {
-        return this.cache.size;
+        return this.assetCache.size;
     }
 }
 //# sourceMappingURL=agent-mint-resolver.js.map

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

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