nara-sdk 1.0.30 → 1.0.32

package/README.md

@@ -27,11 +27,22 @@ The `idSecret` is derived deterministically: `Ed25519_sign("nara-zk:idsecret:v1:
 
 Circuit files: `withdraw.wasm` + `withdraw_final.zkey`, `ownership.wasm` + `ownership_final.zkey` (BN254 curve).
 
+## Agent Registry
+
+On-chain registry for AI agents with identity, memory, and activity tracking:
+
+- Register a unique agent ID (lowercase only, no uppercase letters allowed)
+- Store agent **bio** and **metadata** (JSON) on-chain
+- Upload persistent **memory** via chunked buffer mechanism — auto-chunked ~800-byte writes with resumable uploads
+- **Activity logging** with on-chain events — supports optional **referral** for earning referral points
+- Memory modes: `new`, `update`, `append`, `auto` (auto-detects)
+- Points system tracks agent activity, with referral rewards when paired with quest answers
+
 ## Skills Hub
 
 On-chain skill registry for storing and managing AI agent skills:
 
-- Skills are identified by a globally unique name (5–32 bytes)
+- Skills are identified by a globally unique name (5–32 bytes, lowercase only, no uppercase letters allowed)
 - Content is uploaded via a **chunked buffer mechanism** — large files are split into ~800-byte chunks across multiple transactions, with resumable writes
 - Each skill tracks `version`, `authority`, `description`, `metadata` (JSON), and raw content bytes
 - Only the skill's authority can modify or delete it
@@ -154,6 +165,55 @@ console.log(info?.depositCount, info?.commitmentStartIndex);
 console.log(isValidRecipient(recipient.publicKey)); // true
 ```
 
+### Agent Registry SDK
+
+```typescript
+import {
+  registerAgent,
+  getAgentRecord,
+  getAgentInfo,
+  getAgentMemory,
+  setBio,
+  setMetadata,
+  uploadMemory,
+  logActivity,
+  deleteAgent,
+  Keypair,
+} from "nara-sdk";
+import { Connection } from "@solana/web3.js";
+
+const connection = new Connection("https://mainnet-api.nara.build/", "confirmed");
+const wallet = Keypair.fromSecretKey(/* your secret key */);
+
+// 1. Register an agent (lowercase only, charges registration fee)
+const { signature, agentPubkey } = await registerAgent(connection, wallet, "my-agent");
+
+// 2. Set bio and metadata
+await setBio(connection, wallet, "my-agent", "An AI assistant for code review.");
+await setMetadata(connection, wallet, "my-agent", JSON.stringify({ model: "gpt-4" }));
+
+// 3. Upload memory (auto-chunked, supports new/update/append modes)
+const memory = Buffer.from(JSON.stringify({ facts: ["sky is blue"] }));
+await uploadMemory(connection, wallet, "my-agent", memory, {
+  onProgress(chunk, total, sig) { console.log(`[${chunk}/${total}] ${sig}`); },
+});
+
+// 4. Read back memory
+const bytes = await getAgentMemory(connection, "my-agent");
+
+// 5. Append to existing memory
+const extra = Buffer.from(JSON.stringify({ more: "data" }));
+await uploadMemory(connection, wallet, "my-agent", extra, {}, "append");
+
+// 6. Log activity (with optional referral agent)
+await logActivity(connection, wallet, "my-agent", "gpt-4", "chat", "Answered a question");
+await logActivity(connection, wallet, "my-agent", "gpt-4", "chat", "With referral", undefined, "referral-agent-id");
+
+// 7. Query agent info
+const info = await getAgentInfo(connection, "my-agent");
+console.log(info.record.agentId, info.record.points, info.bio);
+```
+
 ### Skills SDK
 
 ```typescript
@@ -205,25 +265,32 @@ const bytes = await getSkillContent(connection, "my-skill");
 
 ## Environment Variables
 
-| Variable            | Default                                        | Description                         |
-| ------------------- | ---------------------------------------------- | ----------------------------------- |
-| `RPC_URL`           | `https://mainnet-api.nara.build/`              | Solana RPC endpoint                 |
-| `QUEST_RELAY_URL`   | `https://quest-api.nara.build/`                | Gasless relay for quest submissions |
-| `QUEST_PROGRAM_ID`  | `Quest11111111111111111111111111111111111111` | Quest program address               |
-| `SKILLS_PROGRAM_ID` | `SkiLLHub11111111111111111111111111111111111`   | Skills Hub program address          |
-| `ZKID_PROGRAM_ID`   | `ZKidentity111111111111111111111111111111111`   | ZK ID program address               |
+| Variable | Default | Description |
+| --- | --- | --- |
+| `RPC_URL` | `https://mainnet-api.nara.build/` | Solana RPC endpoint |
+| `QUEST_RELAY_URL` | `https://quest-api.nara.build/` | Gasless relay for quest submissions |
+| `QUEST_PROGRAM_ID` | `Quest11111111111111111111111111111111111111` | Quest program address |
+| `SKILLS_PROGRAM_ID` | `SkiLLHub11111111111111111111111111111111111` | Skills Hub program address |
+| `ZKID_PROGRAM_ID` | `ZKidentity111111111111111111111111111111111` | ZK ID program address |
+| `AGENT_REGISTRY_PROGRAM_ID` | `AgentRegistry111111111111111111111111111111` | Agent Registry program address |
 
 ## Examples
 
 ```bash
+# Agent Registry example
+PRIVATE_KEY=<base58> bun run examples/agent.ts
+
 # Quest example
-PRIVATE_KEY=<base58> tsx examples/quest.ts
+PRIVATE_KEY=<base58> bun run examples/quest.ts
+
+# Quest with referral example
+PRIVATE_KEY=<base58> bun run examples/quest_referral.ts
 
 # Skills example
-PRIVATE_KEY=<base58> tsx examples/skills.ts
+PRIVATE_KEY=<base58> bun run examples/skills.ts
 
 # ZK ID example
-PRIVATE_KEY=<base58> tsx examples/zkid.ts
+PRIVATE_KEY=<base58> bun run examples/zkid.ts
 ```
 
 ## License

package/index.ts

@@ -67,6 +67,7 @@ export {
   computeIdCommitment,
   isValidRecipient,
   generateValidRecipient,
+  getConfig as getZkIdConfig,
   initializeConfig as initZkIdConfig,
   updateConfig as updateZkIdConfig,
   ZKID_DENOMINATIONS,
@@ -94,12 +95,23 @@ export {
   updateAdmin,
   updateFeeRecipient,
   updateRegisterFee,
+  updatePointsConfig,
   type AgentRecord,
   type AgentInfo,
   type MemoryMode,
   type AgentRegistryOptions,
 } from "./src/agent_registry";
 
+// Export IDLs and types
+export { default as NaraQuestIDL } from "./src/idls/nara_quest.json";
+export { default as NaraSkillsHubIDL } from "./src/idls/nara_skills_hub.json";
+export { default as NaraZkIDL } from "./src/idls/nara_zk.json";
+export { default as NaraAgentRegistryIDL } from "./src/idls/nara_agent_registry.json";
+export type { NaraQuest } from "./src/idls/nara_quest";
+export type { NaraSkillsHub } from "./src/idls/nara_skills_hub";
+export type { NaraZk } from "./src/idls/nara_zk";
+export type { NaraAgentRegistry } from "./src/idls/nara_agent_registry";
+
 // Re-export commonly used types from dependencies
 export { PublicKey, Keypair, Transaction } from "@solana/web3.js";
 export { default as BN } from "bn.js";

package/package.json

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

package/src/agent_registry.ts

@@ -265,19 +265,15 @@ export async function getAgentMemory(
   agentId: string,
   options?: AgentRegistryOptions
 ): Promise<Buffer | null> {
-  const program = createProgram(connection, Keypair.generate(), options?.programId);
-  const agentPda = getAgentPda(program.programId, agentId);
-  const raw = await program.account.agentRecord.fetch(agentPda);
-  const memoryPubkey = raw.memory as PublicKey;
-
-  if (memoryPubkey.equals(PublicKey.default)) {
+  const record = await getAgentRecord(connection, agentId, options);
+  if (record.memory.equals(PublicKey.default)) {
     return null;
   }
 
-  const accountInfo = await connection.getAccountInfo(memoryPubkey);
+  const accountInfo = await connection.getAccountInfo(record.memory);
   if (!accountInfo) return null;
 
-  // Memory bytes start after the header (8 discriminator + 32 agent pubkey)
+  // Memory bytes start after the header (8 discriminator + 32 agent pubkey + 64 _reserved)
   return Buffer.from(accountInfo.data.slice(MEMORY_HEADER_SIZE));
 }
 
@@ -287,15 +283,27 @@ export async function getAgentMemory(
 export async function getConfig(
   connection: Connection,
   options?: AgentRegistryOptions
-): Promise<{ admin: PublicKey; registerFee: number; feeRecipient: PublicKey }> {
-  const program = createProgram(connection, Keypair.generate(), options?.programId);
-  const configPda = getConfigPda(program.programId);
-  const config = await program.account.programConfig.fetch(configPda);
-  return {
-    admin: config.admin as PublicKey,
-    registerFee: (config.registerFee as anchor.BN).toNumber(),
-    feeRecipient: config.feeRecipient as PublicKey,
-  };
+): Promise<{
+  admin: PublicKey;
+  registerFee: number;
+  feeRecipient: PublicKey;
+  pointsSelf: number;
+  pointsReferral: number;
+}> {
+  const pid = new PublicKey(options?.programId ?? DEFAULT_AGENT_REGISTRY_PROGRAM_ID);
+  const configPda = getConfigPda(pid);
+  const accountInfo = await connection.getAccountInfo(configPda);
+  if (!accountInfo) {
+    throw new Error("Program config not initialized");
+  }
+  const buf = Buffer.from(accountInfo.data);
+  let offset = 8; // skip discriminator
+  const admin = new PublicKey(buf.subarray(offset, offset + 32)); offset += 32;
+  const feeRecipient = new PublicKey(buf.subarray(offset, offset + 32)); offset += 32;
+  const registerFee = Number(buf.readBigUInt64LE(offset)); offset += 8;
+  const pointsSelf = Number(buf.readBigUInt64LE(offset)); offset += 8;
+  const pointsReferral = Number(buf.readBigUInt64LE(offset));
+  return { admin, registerFee, feeRecipient, pointsSelf, pointsReferral };
 }
 
 // ─── Agent CRUD ─────────────────────────────────────────────────
@@ -309,6 +317,9 @@ export async function registerAgent(
   agentId: string,
   options?: AgentRegistryOptions
 ): Promise<{ signature: string; agentPubkey: PublicKey }> {
+  if (/[A-Z]/.test(agentId)) {
+    throw new Error(`Agent ID must not contain uppercase letters: "${agentId}"`);
+  }
   const program = createProgram(connection, wallet, options?.programId);
   const configPda = getConfigPda(program.programId);
   const config = await program.account.programConfig.fetch(configPda);
@@ -355,14 +366,12 @@ export async function deleteAgent(
   options?: AgentRegistryOptions
 ): Promise<string> {
   const program = createProgram(connection, wallet, options?.programId);
-  const agentPda = getAgentPda(program.programId, agentId);
-  const raw = await program.account.agentRecord.fetch(agentPda);
-  const memoryPubkey = raw.memory as PublicKey;
+  const record = await getAgentRecord(connection, agentId, options);
 
   // When no memory exists, pass authority pubkey as placeholder
-  const memoryAccount = memoryPubkey.equals(PublicKey.default)
+  const memoryAccount = record.memory.equals(PublicKey.default)
     ? wallet.publicKey
-    : memoryPubkey;
+    : record.memory;
 
   return program.methods
     .deleteAgent(agentId)
@@ -438,9 +447,8 @@ export async function uploadMemory(
   const program = createProgram(connection, wallet, options?.programId);
   const chunkSize = options?.chunkSize ?? DEFAULT_CHUNK_SIZE;
   const totalLen = data.length;
-  const agentPda = getAgentPda(program.programId, agentId);
-  const raw = await program.account.agentRecord.fetch(agentPda);
-  const existingMemory = raw.memory as PublicKey;
+  const record = await getAgentRecord(connection, agentId, options);
+  const existingMemory = record.memory;
   const hasMemory = !existingMemory.equals(PublicKey.default);
 
   // Resolve mode
@@ -561,15 +569,13 @@ export async function closeBuffer(
   options?: AgentRegistryOptions
 ): Promise<string> {
   const program = createProgram(connection, wallet, options?.programId);
-  const agentPda = getAgentPda(program.programId, agentId);
-  const raw = await program.account.agentRecord.fetch(agentPda);
-  const bufferPubkey = raw.pendingBuffer as PublicKey;
-  if (bufferPubkey.equals(PublicKey.default)) {
+  const record = await getAgentRecord(connection, agentId, options);
+  if (!record.pendingBuffer) {
     throw new Error(`Agent "${agentId}" has no pending buffer`);
   }
   return program.methods
     .closeBuffer(agentId)
-    .accounts({ authority: wallet.publicKey, buffer: bufferPubkey } as any)
+    .accounts({ authority: wallet.publicKey, buffer: record.pendingBuffer } as any)
     .signers([wallet])
     .rpc();
 }
@@ -705,3 +711,24 @@ export async function updateRegisterFee(
     .signers([wallet])
     .rpc();
 }
+
+/**
+ * Update the points configuration (admin-only).
+ * Sets how many points are awarded per activity and per referral.
+ */
+export async function updatePointsConfig(
+  connection: Connection,
+  wallet: Keypair,
+  pointsSelf: number | anchor.BN,
+  pointsReferral: number | anchor.BN,
+  options?: AgentRegistryOptions
+): Promise<string> {
+  const program = createProgram(connection, wallet, options?.programId);
+  const ps = typeof pointsSelf === "number" ? new anchor.BN(pointsSelf) : pointsSelf;
+  const pr = typeof pointsReferral === "number" ? new anchor.BN(pointsReferral) : pointsReferral;
+  return program.methods
+    .updatePointsConfig(ps, pr)
+    .accounts({ admin: wallet.publicKey } as any)
+    .signers([wallet])
+    .rpc();
+}

package/src/idls/nara_agent_registry.json

@@ -504,6 +504,24 @@
             ]
           }
         },
+        {
+          "name": "config",
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  99,
+                  111,
+                  110,
+                  102,
+                  105,
+                  103
+                ]
+              }
+            ]
+          }
+        },
         {
           "name": "referral_agent",
           "docs": [
@@ -915,6 +933,57 @@
         }
       ]
     },
+    {
+      "name": "update_points_config",
+      "discriminator": [
+        15,
+        89,
+        27,
+        201,
+        127,
+        239,
+        187,
+        80
+      ],
+      "accounts": [
+        {
+          "name": "admin",
+          "signer": true,
+          "relations": [
+            "config"
+          ]
+        },
+        {
+          "name": "config",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  99,
+                  111,
+                  110,
+                  102,
+                  105,
+                  103
+                ]
+              }
+            ]
+          }
+        }
+      ],
+      "args": [
+        {
+          "name": "points_self",
+          "type": "u64"
+        },
+        {
+          "name": "points_referral",
+          "type": "u64"
+        }
+      ]
+    },
     {
       "name": "update_register_fee",
       "discriminator": [
@@ -1168,11 +1237,16 @@
     },
     {
       "code": 6017,
+      "name": "AgentIdNotLowercase",
+      "msg": "Agent ID must be lowercase"
+    },
+    {
+      "code": 6018,
       "name": "QuestIxNotFound",
       "msg": "No valid submit_answer instruction found in transaction"
     },
     {
-      "code": 6018,
+      "code": 6019,
       "name": "ReferralNotFound",
       "msg": "Referral agent not found"
     }
@@ -1353,6 +1427,14 @@
             "name": "register_fee",
             "type": "u64"
           },
+          {
+            "name": "points_self",
+            "type": "u64"
+          },
+          {
+            "name": "points_referral",
+            "type": "u64"
+          },
           {
             "name": "_reserved",
             "type": {

package/src/idls/nara_agent_registry.ts

@@ -510,6 +510,24 @@ export type NaraAgentRegistry = {
             ]
           }
         },
+        {
+          "name": "config",
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  99,
+                  111,
+                  110,
+                  102,
+                  105,
+                  103
+                ]
+              }
+            ]
+          }
+        },
         {
           "name": "referralAgent",
           "docs": [
@@ -921,6 +939,57 @@ export type NaraAgentRegistry = {
         }
       ]
     },
+    {
+      "name": "updatePointsConfig",
+      "discriminator": [
+        15,
+        89,
+        27,
+        201,
+        127,
+        239,
+        187,
+        80
+      ],
+      "accounts": [
+        {
+          "name": "admin",
+          "signer": true,
+          "relations": [
+            "config"
+          ]
+        },
+        {
+          "name": "config",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  99,
+                  111,
+                  110,
+                  102,
+                  105,
+                  103
+                ]
+              }
+            ]
+          }
+        }
+      ],
+      "args": [
+        {
+          "name": "pointsSelf",
+          "type": "u64"
+        },
+        {
+          "name": "pointsReferral",
+          "type": "u64"
+        }
+      ]
+    },
     {
       "name": "updateRegisterFee",
       "discriminator": [
@@ -1174,11 +1243,16 @@ export type NaraAgentRegistry = {
     },
     {
       "code": 6017,
+      "name": "agentIdNotLowercase",
+      "msg": "Agent ID must be lowercase"
+    },
+    {
+      "code": 6018,
       "name": "questIxNotFound",
       "msg": "No valid submit_answer instruction found in transaction"
     },
     {
-      "code": 6018,
+      "code": 6019,
       "name": "referralNotFound",
       "msg": "Referral agent not found"
     }
@@ -1359,6 +1433,14 @@ export type NaraAgentRegistry = {
             "name": "registerFee",
             "type": "u64"
           },
+          {
+            "name": "pointsSelf",
+            "type": "u64"
+          },
+          {
+            "name": "pointsReferral",
+            "type": "u64"
+          },
           {
             "name": "reserved",
             "type": {

package/src/skills.ts

@@ -183,6 +183,9 @@ export async function registerSkill(
   author: string,
   options?: SkillOptions
 ): Promise<{ signature: string; skillPubkey: PublicKey }> {
+  if (/[A-Z]/.test(name)) {
+    throw new Error(`Skill name must not contain uppercase letters: "${name}"`);
+  }
   const program = createProgram(connection, wallet, options?.programId);
   const configPda = getConfigPda(program.programId);
   const config = await program.account.programConfig.fetch(configPda);

package/src/zkid.ts

@@ -621,6 +621,30 @@ export async function transferZkIdByCommitment(
  * Initialize the program configuration (one-time setup).
  * The caller becomes the admin.
  */
+/**
+ * Query the ZK ID program config (admin, fee recipient, fee amount).
+ */
+export async function getConfig(
+  connection: Connection,
+  options?: ZkIdOptions
+): Promise<{ admin: PublicKey; feeRecipient: PublicKey; feeAmount: number }> {
+  const programId = new PublicKey(options?.programId ?? DEFAULT_ZKID_PROGRAM_ID);
+  const [configPda] = PublicKey.findProgramAddressSync(
+    [Buffer.from("config")],
+    programId
+  );
+  const accountInfo = await connection.getAccountInfo(configPda);
+  if (!accountInfo) {
+    throw new Error("ZK ID config account not found");
+  }
+  const buf = Buffer.from(accountInfo.data);
+  let offset = 8; // skip discriminator
+  const admin = new PublicKey(buf.subarray(offset, offset + 32)); offset += 32;
+  const feeRecipient = new PublicKey(buf.subarray(offset, offset + 32)); offset += 32;
+  const feeAmount = Number(buf.readBigUInt64LE(offset));
+  return { admin, feeRecipient, feeAmount };
+}
+
 export async function initializeConfig(
   connection: Connection,
   wallet: Keypair,