nara-sdk 1.0.88 → 1.0.90

package/index.ts

@@ -124,7 +124,9 @@ export {
   getAgentMemory,
   getConfig as getAgentRegistryConfig,
   setBio,
+  makeSetBioIx,
   setMetadata,
+  makeSetMetadataIx,
   uploadMemory,
   closeBuffer as closeAgentBuffer,
   transferAgentAuthority,
@@ -136,10 +138,12 @@ export {
   setReferral,
   // Agent index
   getAgentIndex,
+  listIndexesByAgent,
   registerAgentIndex,
   unregisterAgentIndex,
   makeRegisterAgentIndexIx,
   makeUnregisterAgentIndexIx,
+  computeIndexHash,
   // Twitter verification
   getAgentTwitter,
   getTweetVerify,
@@ -170,6 +174,7 @@ export {
   type AgentRecord,
   type AgentInfo,
   type AgentIndexInfo,
+  type ReverseIndexInfo,
   type AgentTwitterInfo,
   type TweetVerifyInfo,
   type TweetRecordInfo,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nara-sdk",
-  "version": "1.0.88",
+  "version": "1.0.90",
   "description": "SDK for the Nara chain (Solana-compatible)",
   "module": "index.ts",
   "main": "index.ts",
@@ -35,6 +35,7 @@
   },
   "dependencies": {
     "@coral-xyz/anchor": "^0.32.1",
+    "@noble/hashes": "^1.5.0",
     "@solana/spl-token": "^0.4.14",
     "@solana/web3.js": "^1.98.4",
     "bn.js": "^5.2.2",

package/src/agent_registry.ts

@@ -14,6 +14,7 @@ import * as anchor from "@coral-xyz/anchor";
 import { Program, AnchorProvider, Wallet } from "@coral-xyz/anchor";
 import BN from "bn.js";
 import { getAssociatedTokenAddressSync, TOKEN_2022_PROGRAM_ID } from "@solana/spl-token";
+import { blake3 } from "@noble/hashes/blake3";
 import bs58 from "bs58";
 import type { NaraAgentRegistry } from "./idls/nara_agent_registry";
 import { DEFAULT_AGENT_REGISTRY_PROGRAM_ID } from "./constants";
@@ -64,6 +65,14 @@ export interface AgentIndexInfo {
   createdAt: number;
 }
 
+export interface ReverseIndexInfo {
+  /** Agent PDA that owns this reverse-index entry */
+  agent: PublicKey;
+  /** Index string registered for the agent (UTF-8, up to 128 bytes) */
+  index: string;
+  createdAt: number;
+}
+
 export interface AgentTwitterInfo {
   agentId: string;
   status: number;
@@ -189,9 +198,30 @@ function getTreasuryPda(programId: PublicKey): PublicKey {
   return pda;
 }
 
-function getAgentIndexPda(programId: PublicKey, indexStr: string): PublicKey {
+/**
+ * BLAKE3 of an index string. The chain uses this 32-byte hash both as a PDA
+ * seed (lifting the 32-byte raw-seed limit) and as an integrity check against
+ * the supplied `index_str` (errors with `AgentIndexHashMismatch` on mismatch).
+ */
+export function computeIndexHash(indexStr: string): Buffer {
+  return Buffer.from(blake3(Buffer.from(indexStr, "utf8")));
+}
+
+function getAgentIndexPda(programId: PublicKey, indexHash: Buffer | Uint8Array): PublicKey {
   const [pda] = PublicKey.findProgramAddressSync(
-    [Buffer.from("agent_index"), Buffer.from(indexStr)],
+    [Buffer.from("agent_index"), Buffer.from(indexHash)],
+    programId
+  );
+  return pda;
+}
+
+function getReverseIndexPda(
+  programId: PublicKey,
+  agentPda: PublicKey,
+  indexHash: Buffer | Uint8Array
+): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from("reverse_index"), agentPda.toBytes(), Buffer.from(indexHash)],
     programId
   );
   return pda;
@@ -729,6 +759,23 @@ export async function deleteAgent(
 
 // ─── Bio & Metadata ─────────────────────────────────────────────
 
+/**
+ * Build a setBio instruction without sending it.
+ */
+export async function makeSetBioIx(
+  connection: Connection,
+  authority: PublicKey,
+  agentId: string,
+  bio: string,
+  options?: AgentRegistryOptions
+): Promise<TransactionInstruction> {
+  const program = createProgram(connection, Keypair.generate(), options?.programId);
+  return program.methods
+    .setBio(agentId, bio)
+    .accounts({ authority } as any)
+    .instruction();
+}
+
 /**
  * Set or update the agent's bio.
  */
@@ -739,14 +786,27 @@ export async function setBio(
   bio: string,
   options?: AgentRegistryOptions
 ): Promise<string> {
-  const program = createProgram(connection, wallet, options?.programId);
-  const ix = await program.methods
-    .setBio(agentId, bio)
-    .accounts({ authority: wallet.publicKey } as any)
-    .instruction();
+  const ix = await makeSetBioIx(connection, wallet.publicKey, agentId, bio, options);
   return sendTx(connection, wallet, [ix]);
 }
 
+/**
+ * Build a setMetadata instruction without sending it.
+ */
+export async function makeSetMetadataIx(
+  connection: Connection,
+  authority: PublicKey,
+  agentId: string,
+  data: string,
+  options?: AgentRegistryOptions
+): Promise<TransactionInstruction> {
+  const program = createProgram(connection, Keypair.generate(), options?.programId);
+  return program.methods
+    .setMetadata(agentId, data)
+    .accounts({ authority } as any)
+    .instruction();
+}
+
 /**
  * Set or update the agent's metadata (typically JSON).
  */
@@ -757,11 +817,7 @@ export async function setMetadata(
   data: string,
   options?: AgentRegistryOptions
 ): Promise<string> {
-  const program = createProgram(connection, wallet, options?.programId);
-  const ix = await program.methods
-    .setMetadata(agentId, data)
-    .accounts({ authority: wallet.publicKey } as any)
-    .instruction();
+  const ix = await makeSetMetadataIx(connection, wallet.publicKey, agentId, data, options);
   return sendTx(connection, wallet, [ix]);
 }
 
@@ -1122,6 +1178,23 @@ function parseAgentIndexData(data: Buffer | Uint8Array): AgentIndexInfo {
   return { agent, agentId, createdAt };
 }
 
+/**
+ * Parse ReverseIndex account data (bytemuck zero-copy layout).
+ * Layout (after 8-byte discriminator):
+ *   32 agent | 8 created_at | 4 index_len | 4 _padding |
+ *   128 index | 32 _reserved
+ */
+function parseReverseIndexData(data: Buffer | Uint8Array): ReverseIndexInfo {
+  const buf = Buffer.from(data);
+  let offset = 8;
+  const agent = new PublicKey(buf.subarray(offset, offset + 32)); offset += 32;
+  const createdAt = Number(buf.readBigInt64LE(offset)); offset += 8;
+  const indexLen = buf.readUInt32LE(offset); offset += 4;
+  offset += 4; // _padding
+  const index = buf.subarray(offset, offset + indexLen).toString("utf-8");
+  return { agent, index, createdAt };
+}
+
 /**
  * Look up an agent_index entry by index string.
  * Returns null if no agent has claimed this index.
@@ -1132,12 +1205,39 @@ export async function getAgentIndex(
   options?: AgentRegistryOptions
 ): Promise<AgentIndexInfo | null> {
   const pid = new PublicKey(options?.programId ?? DEFAULT_AGENT_REGISTRY_PROGRAM_ID);
-  const pda = getAgentIndexPda(pid, indexStr);
+  const pda = getAgentIndexPda(pid, computeIndexHash(indexStr));
   const accountInfo = await connection.getAccountInfo(pda);
   if (!accountInfo) return null;
   return parseAgentIndexData(accountInfo.data);
 }
 
+/** ReverseIndex account discriminator (from IDL). */
+const REVERSE_INDEX_DISCRIMINATOR = Buffer.from([130, 180, 241, 155, 193, 32, 173, 207]);
+
+/**
+ * List all index strings registered for a given agent.
+ * Scans the program via `getProgramAccounts` with memcmp filters on the
+ * ReverseIndex discriminator and the `agent` field (offset 8).
+ */
+export async function listIndexesByAgent(
+  connection: Connection,
+  agentId: string,
+  options?: AgentRegistryOptions
+): Promise<ReverseIndexInfo[]> {
+  const pid = new PublicKey(options?.programId ?? DEFAULT_AGENT_REGISTRY_PROGRAM_ID);
+  const agentPda = getAgentPda(pid, agentId);
+
+  const accounts = await connection.getProgramAccounts(pid, {
+    commitment: "confirmed",
+    filters: [
+      { memcmp: { offset: 0, bytes: bs58.encode(REVERSE_INDEX_DISCRIMINATOR) } },
+      { memcmp: { offset: 8, bytes: agentPda.toBase58() } },
+    ],
+  });
+
+  return accounts.map(({ account }) => parseReverseIndexData(account.data));
+}
+
 /**
  * Build a registerAgentIndex instruction without sending it.
  */
@@ -1151,15 +1251,17 @@ export async function makeRegisterAgentIndexIx(
 ): Promise<TransactionInstruction> {
   const program = createProgram(connection, Keypair.generate(), options?.programId);
   const agent = getAgentPda(program.programId, agentId);
+  const indexHash = computeIndexHash(indexStr);
   return program.methods
-    .registerAgentIndex(indexStr)
+    .registerAgentIndex(indexStr, Array.from(indexHash))
     .accounts({ payer, authority, agent } as any)
     .instruction();
 }
 
 /**
  * Register a custom index string that points to the given agent.
- * The (index_str → agent_id) mapping can be looked up via getAgentIndex.
+ * The (index_str → agent_id) mapping can be looked up via getAgentIndex;
+ * the reverse (agent → all index_strs) via listIndexesByAgent.
  */
 export async function registerAgentIndex(
   connection: Connection,
@@ -1168,12 +1270,13 @@ export async function registerAgentIndex(
   indexStr: string,
   options?: AgentRegistryOptions,
   payer?: Keypair
-): Promise<{ signature: string; agentIndexPda: PublicKey }> {
+): Promise<{ signature: string; agentIndexPda: PublicKey; reverseIndexPda: PublicKey }> {
   const payerKp = payer ?? wallet;
   const program = createProgram(connection, payerKp, options?.programId);
   const agent = getAgentPda(program.programId, agentId);
+  const indexHash = computeIndexHash(indexStr);
   const ix = await program.methods
-    .registerAgentIndex(indexStr)
+    .registerAgentIndex(indexStr, Array.from(indexHash))
     .accounts({
       payer: payerKp.publicKey,
       authority: wallet.publicKey,
@@ -1182,7 +1285,11 @@ export async function registerAgentIndex(
     .instruction();
   const signers = payer && !payer.publicKey.equals(wallet.publicKey) ? [wallet] : [];
   const signature = await sendTx(connection, payerKp, [ix], signers);
-  return { signature, agentIndexPda: getAgentIndexPda(program.programId, indexStr) };
+  return {
+    signature,
+    agentIndexPda: getAgentIndexPda(program.programId, indexHash),
+    reverseIndexPda: getReverseIndexPda(program.programId, agent, indexHash),
+  };
 }
 
 /**
@@ -1198,8 +1305,9 @@ export async function makeUnregisterAgentIndexIx(
 ): Promise<TransactionInstruction> {
   const program = createProgram(connection, Keypair.generate(), options?.programId);
   const agent = getAgentPda(program.programId, agentId);
+  const indexHash = computeIndexHash(indexStr);
   return program.methods
-    .unregisterAgentIndex(indexStr)
+    .unregisterAgentIndex(Array.from(indexHash))
     .accounts({ rentDestination, authority, agent } as any)
     .instruction();
 }
@@ -1219,8 +1327,9 @@ export async function unregisterAgentIndex(
 ): Promise<string> {
   const program = createProgram(connection, wallet, options?.programId);
   const agent = getAgentPda(program.programId, agentId);
+  const indexHash = computeIndexHash(indexStr);
   const ix = await program.methods
-    .unregisterAgentIndex(indexStr)
+    .unregisterAgentIndex(Array.from(indexHash))
     .accounts({
       rentDestination: rentDestination ?? wallet.publicKey,
       authority: wallet.publicKey,

package/src/idls/nara_agent_registry.json

@@ -1989,6 +1989,9 @@
         },
         {
           "name": "agent_index",
+          "docs": [
+            "Forward-lookup PDA: keyed by hash(index_str). Globally unique per index_str."
+          ],
           "writable": true,
           "pda": {
             "seeds": [
@@ -2010,7 +2013,44 @@
               },
               {
                 "kind": "arg",
-                "path": "index_str"
+                "path": "index_hash"
+              }
+            ]
+          }
+        },
+        {
+          "name": "reverse_index",
+          "docs": [
+            "Reverse-lookup PDA: keyed by (agent, hash(index_str)). One per agent per index."
+          ],
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  114,
+                  101,
+                  118,
+                  101,
+                  114,
+                  115,
+                  101,
+                  95,
+                  105,
+                  110,
+                  100,
+                  101,
+                  120
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "agent"
+              },
+              {
+                "kind": "arg",
+                "path": "index_hash"
               }
             ]
           }
@@ -2024,6 +2064,15 @@
         {
           "name": "index_str",
           "type": "string"
+        },
+        {
+          "name": "index_hash",
+          "type": {
+            "array": [
+              "u8",
+              32
+            ]
+          }
         }
       ]
     },
@@ -3658,7 +3707,44 @@
               },
               {
                 "kind": "arg",
-                "path": "index_str"
+                "path": "index_hash"
+              }
+            ]
+          }
+        },
+        {
+          "name": "reverse_index",
+          "docs": [
+            "Reverse-lookup PDA, closed alongside the main index entry."
+          ],
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  114,
+                  101,
+                  118,
+                  101,
+                  114,
+                  115,
+                  101,
+                  95,
+                  105,
+                  110,
+                  100,
+                  101,
+                  120
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "agent"
+              },
+              {
+                "kind": "arg",
+                "path": "index_hash"
               }
             ]
           }
@@ -3670,8 +3756,13 @@
       ],
       "args": [
         {
-          "name": "index_str",
-          "type": "string"
+          "name": "index_hash",
+          "type": {
+            "array": [
+              "u8",
+              32
+            ]
+          }
         }
       ]
     },
@@ -4702,6 +4793,19 @@
         63
       ]
     },
+    {
+      "name": "ReverseIndex",
+      "discriminator": [
+        130,
+        180,
+        241,
+        155,
+        193,
+        32,
+        173,
+        207
+      ]
+    },
     {
       "name": "TweetRecord",
       "discriminator": [
@@ -5038,6 +5142,11 @@
       "code": 6050,
       "name": "AgentIndexMismatch",
       "msg": "Agent index does not belong to the given agent"
+    },
+    {
+      "code": 6051,
+      "name": "AgentIndexHashMismatch",
+      "msg": "Agent index hash does not match the provided index string"
     }
   ],
   "types": [
@@ -5479,6 +5588,71 @@
         ]
       }
     },
+    {
+      "name": "ReverseIndex",
+      "docs": [
+        "Reverse-lookup record: given an agent, list all index strings registered for it.",
+        "Seeds: [SEED_REVERSE_INDEX, agent_pda.as_ref(), index_str.as_bytes()]",
+        "",
+        "Clients can fetch all reverse_index entries for a given agent via",
+        "`getProgramAccounts` with a memcmp filter on the `agent` field."
+      ],
+      "serialization": "bytemuck",
+      "repr": {
+        "kind": "c"
+      },
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "agent",
+            "docs": [
+              "The AgentState PDA that owns this reverse-index entry"
+            ],
+            "type": "pubkey"
+          },
+          {
+            "name": "created_at",
+            "docs": [
+              "Unix timestamp when this entry was created"
+            ],
+            "type": "i64"
+          },
+          {
+            "name": "index_len",
+            "docs": [
+              "Length of the index string stored below"
+            ],
+            "type": "u32"
+          },
+          {
+            "name": "_padding",
+            "type": "u32"
+          },
+          {
+            "name": "index",
+            "docs": [
+              "Index string (zero-padded), up to 128 bytes"
+            ],
+            "type": {
+              "array": [
+                "u8",
+                128
+              ]
+            }
+          },
+          {
+            "name": "_reserved",
+            "type": {
+              "array": [
+                "u8",
+                32
+              ]
+            }
+          }
+        ]
+      }
+    },
     {
       "name": "TweetRecord",
       "docs": [

package/src/idls/nara_agent_registry.ts

@@ -1995,6 +1995,9 @@ export type NaraAgentRegistry = {
         },
         {
           "name": "agentIndex",
+          "docs": [
+            "Forward-lookup PDA: keyed by hash(index_str). Globally unique per index_str."
+          ],
           "writable": true,
           "pda": {
             "seeds": [
@@ -2016,7 +2019,44 @@ export type NaraAgentRegistry = {
               },
               {
                 "kind": "arg",
-                "path": "indexStr"
+                "path": "indexHash"
+              }
+            ]
+          }
+        },
+        {
+          "name": "reverseIndex",
+          "docs": [
+            "Reverse-lookup PDA: keyed by (agent, hash(index_str)). One per agent per index."
+          ],
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  114,
+                  101,
+                  118,
+                  101,
+                  114,
+                  115,
+                  101,
+                  95,
+                  105,
+                  110,
+                  100,
+                  101,
+                  120
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "agent"
+              },
+              {
+                "kind": "arg",
+                "path": "indexHash"
               }
             ]
           }
@@ -2030,6 +2070,15 @@ export type NaraAgentRegistry = {
         {
           "name": "indexStr",
           "type": "string"
+        },
+        {
+          "name": "indexHash",
+          "type": {
+            "array": [
+              "u8",
+              32
+            ]
+          }
         }
       ]
     },
@@ -3664,7 +3713,44 @@ export type NaraAgentRegistry = {
               },
               {
                 "kind": "arg",
-                "path": "indexStr"
+                "path": "indexHash"
+              }
+            ]
+          }
+        },
+        {
+          "name": "reverseIndex",
+          "docs": [
+            "Reverse-lookup PDA, closed alongside the main index entry."
+          ],
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  114,
+                  101,
+                  118,
+                  101,
+                  114,
+                  115,
+                  101,
+                  95,
+                  105,
+                  110,
+                  100,
+                  101,
+                  120
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "agent"
+              },
+              {
+                "kind": "arg",
+                "path": "indexHash"
               }
             ]
           }
@@ -3676,8 +3762,13 @@ export type NaraAgentRegistry = {
       ],
       "args": [
         {
-          "name": "indexStr",
-          "type": "string"
+          "name": "indexHash",
+          "type": {
+            "array": [
+              "u8",
+              32
+            ]
+          }
         }
       ]
     },
@@ -4708,6 +4799,19 @@ export type NaraAgentRegistry = {
         63
       ]
     },
+    {
+      "name": "reverseIndex",
+      "discriminator": [
+        130,
+        180,
+        241,
+        155,
+        193,
+        32,
+        173,
+        207
+      ]
+    },
     {
       "name": "tweetRecord",
       "discriminator": [
@@ -5044,6 +5148,11 @@ export type NaraAgentRegistry = {
       "code": 6050,
       "name": "agentIndexMismatch",
       "msg": "Agent index does not belong to the given agent"
+    },
+    {
+      "code": 6051,
+      "name": "agentIndexHashMismatch",
+      "msg": "Agent index hash does not match the provided index string"
     }
   ],
   "types": [
@@ -5485,6 +5594,71 @@ export type NaraAgentRegistry = {
         ]
       }
     },
+    {
+      "name": "reverseIndex",
+      "docs": [
+        "Reverse-lookup record: given an agent, list all index strings registered for it.",
+        "Seeds: [SEED_REVERSE_INDEX, agent_pda.as_ref(), index_str.as_bytes()]",
+        "",
+        "Clients can fetch all reverse_index entries for a given agent via",
+        "`getProgramAccounts` with a memcmp filter on the `agent` field."
+      ],
+      "serialization": "bytemuck",
+      "repr": {
+        "kind": "c"
+      },
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "agent",
+            "docs": [
+              "The AgentState PDA that owns this reverse-index entry"
+            ],
+            "type": "pubkey"
+          },
+          {
+            "name": "createdAt",
+            "docs": [
+              "Unix timestamp when this entry was created"
+            ],
+            "type": "i64"
+          },
+          {
+            "name": "indexLen",
+            "docs": [
+              "Length of the index string stored below"
+            ],
+            "type": "u32"
+          },
+          {
+            "name": "padding",
+            "type": "u32"
+          },
+          {
+            "name": "index",
+            "docs": [
+              "Index string (zero-padded), up to 128 bytes"
+            ],
+            "type": {
+              "array": [
+                "u8",
+                128
+              ]
+            }
+          },
+          {
+            "name": "reserved",
+            "type": {
+              "array": [
+                "u8",
+                32
+              ]
+            }
+          }
+        ]
+      }
+    },
     {
       "name": "tweetRecord",
       "docs": [