nara-sdk 1.0.87 → 1.0.88

package/index.ts

@@ -134,6 +134,12 @@ export {
   makeLogActivityIx,
   makeLogActivityWithReferralIx,
   setReferral,
+  // Agent index
+  getAgentIndex,
+  registerAgentIndex,
+  unregisterAgentIndex,
+  makeRegisterAgentIndexIx,
+  makeUnregisterAgentIndexIx,
   // Twitter verification
   getAgentTwitter,
   getTweetVerify,
@@ -163,6 +169,7 @@ export {
   withdrawTwitterVerifyFees,
   type AgentRecord,
   type AgentInfo,
+  type AgentIndexInfo,
   type AgentTwitterInfo,
   type TweetVerifyInfo,
   type TweetRecordInfo,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nara-sdk",
-  "version": "1.0.87",
+  "version": "1.0.88",
   "description": "SDK for the Nara chain (Solana-compatible)",
   "module": "index.ts",
   "main": "index.ts",

package/src/agent_registry.ts

@@ -56,6 +56,14 @@ export interface AgentInfo {
   metadata: string | null;
 }
 
+export interface AgentIndexInfo {
+  /** Agent PDA that owns this index entry */
+  agent: PublicKey;
+  /** agent_id of the owning agent */
+  agentId: string;
+  createdAt: number;
+}
+
 export interface AgentTwitterInfo {
   agentId: string;
   status: number;
@@ -181,6 +189,14 @@ function getTreasuryPda(programId: PublicKey): PublicKey {
   return pda;
 }
 
+function getAgentIndexPda(programId: PublicKey, indexStr: string): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from("agent_index"), Buffer.from(indexStr)],
+    programId
+  );
+  return pda;
+}
+
 function getTwitterPda(programId: PublicKey, agentPda: PublicKey): PublicKey {
   const [pda] = PublicKey.findProgramAddressSync(
     [Buffer.from("twitter"), agentPda.toBuffer()],
@@ -1087,6 +1103,133 @@ export async function setReferral(
   return sendTx(connection, wallet, [ix]);
 }
 
+// ─── Agent Index ────────────────────────────────────────────────
+
+/**
+ * Parse AgentIndex account data (bytemuck zero-copy layout).
+ * Layout (after 8-byte discriminator):
+ *   32 agent | 8 created_at | 4 agent_id_len | 4 _padding |
+ *   32 agent_id | 32 _reserved
+ */
+function parseAgentIndexData(data: Buffer | Uint8Array): AgentIndexInfo {
+  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 agentIdLen = buf.readUInt32LE(offset); offset += 4;
+  offset += 4; // _padding
+  const agentId = buf.subarray(offset, offset + agentIdLen).toString("utf-8");
+  return { agent, agentId, createdAt };
+}
+
+/**
+ * Look up an agent_index entry by index string.
+ * Returns null if no agent has claimed this index.
+ */
+export async function getAgentIndex(
+  connection: Connection,
+  indexStr: string,
+  options?: AgentRegistryOptions
+): Promise<AgentIndexInfo | null> {
+  const pid = new PublicKey(options?.programId ?? DEFAULT_AGENT_REGISTRY_PROGRAM_ID);
+  const pda = getAgentIndexPda(pid, indexStr);
+  const accountInfo = await connection.getAccountInfo(pda);
+  if (!accountInfo) return null;
+  return parseAgentIndexData(accountInfo.data);
+}
+
+/**
+ * Build a registerAgentIndex instruction without sending it.
+ */
+export async function makeRegisterAgentIndexIx(
+  connection: Connection,
+  payer: PublicKey,
+  authority: PublicKey,
+  agentId: string,
+  indexStr: string,
+  options?: AgentRegistryOptions
+): Promise<TransactionInstruction> {
+  const program = createProgram(connection, Keypair.generate(), options?.programId);
+  const agent = getAgentPda(program.programId, agentId);
+  return program.methods
+    .registerAgentIndex(indexStr)
+    .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.
+ */
+export async function registerAgentIndex(
+  connection: Connection,
+  wallet: Keypair,
+  agentId: string,
+  indexStr: string,
+  options?: AgentRegistryOptions,
+  payer?: Keypair
+): Promise<{ signature: string; agentIndexPda: PublicKey }> {
+  const payerKp = payer ?? wallet;
+  const program = createProgram(connection, payerKp, options?.programId);
+  const agent = getAgentPda(program.programId, agentId);
+  const ix = await program.methods
+    .registerAgentIndex(indexStr)
+    .accounts({
+      payer: payerKp.publicKey,
+      authority: wallet.publicKey,
+      agent,
+    } as any)
+    .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) };
+}
+
+/**
+ * Build an unregisterAgentIndex instruction without sending it.
+ */
+export async function makeUnregisterAgentIndexIx(
+  connection: Connection,
+  rentDestination: PublicKey,
+  authority: PublicKey,
+  agentId: string,
+  indexStr: string,
+  options?: AgentRegistryOptions
+): Promise<TransactionInstruction> {
+  const program = createProgram(connection, Keypair.generate(), options?.programId);
+  const agent = getAgentPda(program.programId, agentId);
+  return program.methods
+    .unregisterAgentIndex(indexStr)
+    .accounts({ rentDestination, authority, agent } as any)
+    .instruction();
+}
+
+/**
+ * Unregister a custom index string and reclaim rent.
+ * The signing wallet must be the agent's authority.
+ * @param rentDestination - Account to receive reclaimed rent (defaults to wallet pubkey).
+ */
+export async function unregisterAgentIndex(
+  connection: Connection,
+  wallet: Keypair,
+  agentId: string,
+  indexStr: string,
+  options?: AgentRegistryOptions,
+  rentDestination?: PublicKey
+): Promise<string> {
+  const program = createProgram(connection, wallet, options?.programId);
+  const agent = getAgentPda(program.programId, agentId);
+  const ix = await program.methods
+    .unregisterAgentIndex(indexStr)
+    .accounts({
+      rentDestination: rentDestination ?? wallet.publicKey,
+      authority: wallet.publicKey,
+      agent,
+    } as any)
+    .instruction();
+  return sendTx(connection, wallet, [ix]);
+}
+
 // ─── Admin functions ────────────────────────────────────────────
 
 /**

package/src/idls/nara_agent_registry.json

@@ -1959,6 +1959,74 @@
         }
       ]
     },
+    {
+      "name": "register_agent_index",
+      "discriminator": [
+        193,
+        207,
+        223,
+        226,
+        130,
+        228,
+        161,
+        207
+      ],
+      "accounts": [
+        {
+          "name": "payer",
+          "writable": true,
+          "signer": true
+        },
+        {
+          "name": "authority",
+          "signer": true,
+          "relations": [
+            "agent"
+          ]
+        },
+        {
+          "name": "agent"
+        },
+        {
+          "name": "agent_index",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  97,
+                  103,
+                  101,
+                  110,
+                  116,
+                  95,
+                  105,
+                  110,
+                  100,
+                  101,
+                  120
+                ]
+              },
+              {
+                "kind": "arg",
+                "path": "index_str"
+              }
+            ]
+          }
+        },
+        {
+          "name": "system_program",
+          "address": "11111111111111111111111111111111"
+        }
+      ],
+      "args": [
+        {
+          "name": "index_str",
+          "type": "string"
+        }
+      ]
+    },
     {
       "name": "register_agent_with_referral",
       "discriminator": [
@@ -3540,6 +3608,73 @@
         }
       ]
     },
+    {
+      "name": "unregister_agent_index",
+      "discriminator": [
+        245,
+        18,
+        46,
+        12,
+        147,
+        155,
+        203,
+        169
+      ],
+      "accounts": [
+        {
+          "name": "rent_destination",
+          "writable": true
+        },
+        {
+          "name": "authority",
+          "signer": true,
+          "relations": [
+            "agent"
+          ]
+        },
+        {
+          "name": "agent"
+        },
+        {
+          "name": "agent_index",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  97,
+                  103,
+                  101,
+                  110,
+                  116,
+                  95,
+                  105,
+                  110,
+                  100,
+                  101,
+                  120
+                ]
+              },
+              {
+                "kind": "arg",
+                "path": "index_str"
+              }
+            ]
+          }
+        },
+        {
+          "name": "system_program",
+          "address": "11111111111111111111111111111111"
+        }
+      ],
+      "args": [
+        {
+          "name": "index_str",
+          "type": "string"
+        }
+      ]
+    },
     {
       "name": "update_activity_config",
       "discriminator": [
@@ -4502,6 +4637,19 @@
     }
   ],
   "accounts": [
+    {
+      "name": "AgentIndex",
+      "discriminator": [
+        241,
+        154,
+        35,
+        103,
+        180,
+        141,
+        49,
+        179
+      ]
+    },
     {
       "name": "AgentState",
       "discriminator": [
@@ -4875,6 +5023,21 @@
       "code": 6047,
       "name": "TwitterNotRejected",
       "msg": "Twitter binding is not in rejected status"
+    },
+    {
+      "code": 6048,
+      "name": "AgentIndexEmpty",
+      "msg": "Agent index string is empty"
+    },
+    {
+      "code": 6049,
+      "name": "AgentIndexTooLong",
+      "msg": "Agent index string too long"
+    },
+    {
+      "code": 6050,
+      "name": "AgentIndexMismatch",
+      "msg": "Agent index does not belong to the given agent"
     }
   ],
   "types": [
@@ -4922,6 +5085,69 @@
         ]
       }
     },
+    {
+      "name": "AgentIndex",
+      "docs": [
+        "Per-agent custom index entry. Lets an agent claim arbitrary index strings",
+        "that point back to its agent_id.",
+        "Seeds: [SEED_AGENT_INDEX, index_str.as_bytes()]"
+      ],
+      "serialization": "bytemuck",
+      "repr": {
+        "kind": "c"
+      },
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "agent",
+            "docs": [
+              "The AgentState PDA that owns this index entry"
+            ],
+            "type": "pubkey"
+          },
+          {
+            "name": "created_at",
+            "docs": [
+              "Unix timestamp when this index was registered"
+            ],
+            "type": "i64"
+          },
+          {
+            "name": "agent_id_len",
+            "docs": [
+              "Length of the agent_id stored below"
+            ],
+            "type": "u32"
+          },
+          {
+            "name": "_padding",
+            "type": "u32"
+          },
+          {
+            "name": "agent_id",
+            "docs": [
+              "agent_id of the owning agent (zero-padded)"
+            ],
+            "type": {
+              "array": [
+                "u8",
+                32
+              ]
+            }
+          },
+          {
+            "name": "_reserved",
+            "type": {
+              "array": [
+                "u8",
+                32
+              ]
+            }
+          }
+        ]
+      }
+    },
     {
       "name": "AgentState",
       "docs": [

package/src/idls/nara_agent_registry.ts

@@ -1965,6 +1965,74 @@ export type NaraAgentRegistry = {
         }
       ]
     },
+    {
+      "name": "registerAgentIndex",
+      "discriminator": [
+        193,
+        207,
+        223,
+        226,
+        130,
+        228,
+        161,
+        207
+      ],
+      "accounts": [
+        {
+          "name": "payer",
+          "writable": true,
+          "signer": true
+        },
+        {
+          "name": "authority",
+          "signer": true,
+          "relations": [
+            "agent"
+          ]
+        },
+        {
+          "name": "agent"
+        },
+        {
+          "name": "agentIndex",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  97,
+                  103,
+                  101,
+                  110,
+                  116,
+                  95,
+                  105,
+                  110,
+                  100,
+                  101,
+                  120
+                ]
+              },
+              {
+                "kind": "arg",
+                "path": "indexStr"
+              }
+            ]
+          }
+        },
+        {
+          "name": "systemProgram",
+          "address": "11111111111111111111111111111111"
+        }
+      ],
+      "args": [
+        {
+          "name": "indexStr",
+          "type": "string"
+        }
+      ]
+    },
     {
       "name": "registerAgentWithReferral",
       "discriminator": [
@@ -3546,6 +3614,73 @@ export type NaraAgentRegistry = {
         }
       ]
     },
+    {
+      "name": "unregisterAgentIndex",
+      "discriminator": [
+        245,
+        18,
+        46,
+        12,
+        147,
+        155,
+        203,
+        169
+      ],
+      "accounts": [
+        {
+          "name": "rentDestination",
+          "writable": true
+        },
+        {
+          "name": "authority",
+          "signer": true,
+          "relations": [
+            "agent"
+          ]
+        },
+        {
+          "name": "agent"
+        },
+        {
+          "name": "agentIndex",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  97,
+                  103,
+                  101,
+                  110,
+                  116,
+                  95,
+                  105,
+                  110,
+                  100,
+                  101,
+                  120
+                ]
+              },
+              {
+                "kind": "arg",
+                "path": "indexStr"
+              }
+            ]
+          }
+        },
+        {
+          "name": "systemProgram",
+          "address": "11111111111111111111111111111111"
+        }
+      ],
+      "args": [
+        {
+          "name": "indexStr",
+          "type": "string"
+        }
+      ]
+    },
     {
       "name": "updateActivityConfig",
       "discriminator": [
@@ -4508,6 +4643,19 @@ export type NaraAgentRegistry = {
     }
   ],
   "accounts": [
+    {
+      "name": "agentIndex",
+      "discriminator": [
+        241,
+        154,
+        35,
+        103,
+        180,
+        141,
+        49,
+        179
+      ]
+    },
     {
       "name": "agentState",
       "discriminator": [
@@ -4881,6 +5029,21 @@ export type NaraAgentRegistry = {
       "code": 6047,
       "name": "twitterNotRejected",
       "msg": "Twitter binding is not in rejected status"
+    },
+    {
+      "code": 6048,
+      "name": "agentIndexEmpty",
+      "msg": "Agent index string is empty"
+    },
+    {
+      "code": 6049,
+      "name": "agentIndexTooLong",
+      "msg": "Agent index string too long"
+    },
+    {
+      "code": 6050,
+      "name": "agentIndexMismatch",
+      "msg": "Agent index does not belong to the given agent"
     }
   ],
   "types": [
@@ -4928,6 +5091,69 @@ export type NaraAgentRegistry = {
         ]
       }
     },
+    {
+      "name": "agentIndex",
+      "docs": [
+        "Per-agent custom index entry. Lets an agent claim arbitrary index strings",
+        "that point back to its agent_id.",
+        "Seeds: [SEED_AGENT_INDEX, index_str.as_bytes()]"
+      ],
+      "serialization": "bytemuck",
+      "repr": {
+        "kind": "c"
+      },
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "agent",
+            "docs": [
+              "The AgentState PDA that owns this index entry"
+            ],
+            "type": "pubkey"
+          },
+          {
+            "name": "createdAt",
+            "docs": [
+              "Unix timestamp when this index was registered"
+            ],
+            "type": "i64"
+          },
+          {
+            "name": "agentIdLen",
+            "docs": [
+              "Length of the agent_id stored below"
+            ],
+            "type": "u32"
+          },
+          {
+            "name": "padding",
+            "type": "u32"
+          },
+          {
+            "name": "agentId",
+            "docs": [
+              "agent_id of the owning agent (zero-padded)"
+            ],
+            "type": {
+              "array": [
+                "u8",
+                32
+              ]
+            }
+          },
+          {
+            "name": "reserved",
+            "type": {
+              "array": [
+                "u8",
+                32
+              ]
+            }
+          }
+        ]
+      }
+    },
     {
       "name": "agentState",
       "docs": [