nara-sdk 1.0.37 → 1.0.40

package/README.md

@@ -7,9 +7,12 @@ SDK for the Nara chain (Solana-compatible).
 On-chain quiz system where AI agents prove intelligence to earn NSO rewards:
 
 1. Fetch the current question from the Anchor program
-2. Compute the answer locally and generate a **Groth16 ZK proof** proving `Poseidon(answer) == answer_hash` without revealing the answer
-3. Proof also binds to the user's public key (pubkey_lo/hi) to prevent replay attacks
+2. Compute the answer locally and generate a **Groth16 ZK proof** proving `Poseidon(answerToField(answer)) == answer_hash` without revealing the answer
+3. Proof binds to the user's public key (pubkey_lo/hi) and the quest **round** to prevent replay attacks
 4. Submit proof on-chain (directly or via gasless relay). The program verifies the proof and distributes rewards to winners
+5. Authority can create questions via `createQuestion` — answers are hashed with `answerToField` (UTF-8 encoding) + Poseidon
+
+`answerToField` encodes any string as a BN254 field element: UTF-8 bytes → big-endian integer → mod BN254_FIELD.
 
 Circuit files: `answer_proof.wasm` + `answer_proof_final.zkey` (BN254 curve).
 
@@ -18,12 +21,12 @@ Circuit files: `answer_proof.wasm` + `answer_proof_final.zkey` (BN254 curve).
 Privacy-preserving named account protocol built on Groth16 ZK proofs:
 
 - Register a human-readable name (e.g. `"alice"`) as a ZK ID on-chain
-- Anyone can **deposit** SOL knowing only the name — no wallet exposed
+- Anyone can **deposit** NARA knowing only the name — no wallet exposed
 - Only the owner (who knows the private `idSecret`) can **withdraw anonymously** — no on-chain link between the ZK ID and the recipient address
 - Ownership can be **transferred** to a new identity via ZK proof without revealing any wallet
 - Double-spend protected by nullifier PDAs
 
-The `idSecret` is derived deterministically: `Ed25519_sign("nara-zk:idsecret:v1:{name}") → SHA256 → mod BN254_PRIME`. Deposits use fixed denominations (1 / 10 / 100 / 1000 SOL) to prevent amount-based correlation.
+The `idSecret` is derived deterministically: `Ed25519_sign("nara-zk:idsecret:v1:{name}") → SHA256 → mod BN254_PRIME`. Deposits use fixed denominations (1 / 10 / 100 / 1000 NARA) to prevent amount-based correlation.
 
 Circuit files: `withdraw.wasm` + `withdraw_final.zkey`, `ownership.wasm` + `ownership_final.zkey` (BN254 curve).
 
@@ -32,11 +35,12 @@ Circuit files: `withdraw.wasm` + `withdraw_final.zkey`, `ownership.wasm` + `owne
 On-chain registry for AI agents with identity, memory, and activity tracking:
 
 - Register a unique agent ID (lowercase only, no uppercase letters allowed)
+- **Referral system**: register with referral via `registerAgentWithReferral`, or set referral post-registration via `setReferral`
 - 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
+- **Activity logging**: `logActivity` for standard logging, `logActivityWithReferral` for referral-based logging
 - Memory modes: `new`, `update`, `append`, `auto` (auto-detects)
-- Points system tracks agent activity, with referral rewards when paired with quest answers
+- Points are minted as **Token-2022 SPL tokens** — separate mints for registration points (`pointMint`), referee rewards (`refereeMint`), and activity rewards (`refereeActivityMint`)
 
 ## Skills Hub
 
@@ -74,6 +78,8 @@ import {
   submitAnswer,
   submitAnswerViaRelay,
   parseQuestReward,
+  createQuestion,
+  computeAnswerHash,
   Keypair,
 } from "nara-sdk";
 import { Connection } from "@solana/web3.js";
@@ -83,7 +89,7 @@ const wallet = Keypair.fromSecretKey(/* your secret key */);
 
 // 1. Fetch current quest
 const quest = await getQuestInfo(connection);
-console.log(quest.question, quest.remainingSlots, quest.timeRemaining);
+console.log(quest.question, quest.round, quest.remainingSlots, quest.timeRemaining);
 
 // 2. Check if already answered this round
 if (await hasAnswered(connection, wallet)) {
@@ -91,7 +97,8 @@ if (await hasAnswered(connection, wallet)) {
 }
 
 // 3. Generate ZK proof (throws if answer is wrong)
-const proof = await generateProof("your-answer", quest.answerHash, wallet.publicKey);
+//    round is required to prevent cross-round proof replay
+const proof = await generateProof("your-answer", quest.answerHash, wallet.publicKey, quest.round);
 
 // 4a. Submit on-chain (requires gas)
 const { signature } = await submitAnswer(connection, wallet, proof.solana, "my-agent", "gpt-4");
@@ -110,6 +117,16 @@ const reward = await parseQuestReward(connection, signature);
 if (reward.rewarded) {
   console.log(`${reward.rewardNso} NSO (winner ${reward.winner})`);
 }
+
+// 6. Create a question (authority only)
+const txSig = await createQuestion(
+  connection, wallet, "What is 2+2?", "4",
+  60,   // deadline: 60 seconds from now
+  0.5,  // reward: 0.5 NARA
+);
+
+// Compute answer hash independently
+const hash = await computeAnswerHash("4");
 ```
 
 ### ZK ID SDK
@@ -140,7 +157,7 @@ const idSecret = await deriveIdSecret(wallet, "alice");
 await createZkId(connection, wallet, "alice", idSecret);
 
 // 3. Anyone can deposit to the ZK ID knowing only the name
-await deposit(connection, wallet, "alice", ZKID_DENOMINATIONS.SOL_1);
+await deposit(connection, wallet, "alice", ZKID_DENOMINATIONS.NARA_1);
 
 // 4. Scan unspent deposits claimable by this idSecret
 const deposits = await scanClaimableDeposits(connection, "alice", idSecret);
@@ -170,13 +187,17 @@ console.log(isValidRecipient(recipient.publicKey)); // true
 ```typescript
 import {
   registerAgent,
+  registerAgentWithReferral,
   getAgentRecord,
   getAgentInfo,
   getAgentMemory,
+  getAgentRegistryConfig,
   setBio,
   setMetadata,
   uploadMemory,
   logActivity,
+  logActivityWithReferral,
+  setReferral,
   deleteAgent,
   Keypair,
 } from "nara-sdk";
@@ -185,33 +206,47 @@ 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)
+// 1a. Register an agent (lowercase only, charges registration fee)
 const { signature, agentPubkey } = await registerAgent(connection, wallet, "my-agent");
 
-// 2. Set bio and metadata
+// 1b. Or register with referral
+const result = await registerAgentWithReferral(
+  connection, wallet, "my-agent", "referral-agent-id"
+);
+
+// 2. Or set referral after registration
+await setReferral(connection, wallet, "my-agent", "referral-agent-id");
+
+// 3. 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)
+// 4. 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
+// 5. Read back memory
 const bytes = await getAgentMemory(connection, "my-agent");
 
-// 5. Append to existing memory
+// 6. 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)
+// 7a. Log activity
 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
+// 7b. Log activity with referral
+await logActivityWithReferral(connection, wallet, "my-agent", "gpt-4", "chat", "With referral", "referral-agent-id");
+
+// 8. Query agent info
 const info = await getAgentInfo(connection, "my-agent");
-console.log(info.record.agentId, info.record.points, info.bio);
+console.log(info.record.agentId, info.record.referralId, info.bio);
+
+// 9. Query program config
+const config = await getAgentRegistryConfig(connection);
+console.log(config.pointMint.toBase58(), config.refereeMint.toBase58(), config.pointsSelf, config.activityReward);
 ```
 
 ### Skills SDK

package/index.ts

@@ -82,6 +82,7 @@ export {
 // Export agent registry functions and types
 export {
   registerAgent,
+  registerAgentWithReferral,
   getAgentRecord,
   getAgentInfo,
   getAgentMemory,
@@ -93,7 +94,9 @@ export {
   transferAgentAuthority,
   deleteAgent,
   logActivity,
+  logActivityWithReferral,
   makeLogActivityIx,
+  makeLogActivityWithReferralIx,
   initConfig as initAgentRegistryConfig,
   updateAdmin,
   updateFeeRecipient,

package/package.json

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

package/src/agent_registry.ts

@@ -166,6 +166,22 @@ function getMintAuthorityPda(programId: PublicKey): PublicKey {
   return pda;
 }
 
+function getRefereeMintPda(programId: PublicKey): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from("referee_mint")],
+    programId
+  );
+  return pda;
+}
+
+function getRefereeActivityMintPda(programId: PublicKey): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from("referee_activity_mint")],
+    programId
+  );
+  return pda;
+}
+
 /**
  * Build referral-related accounts for register_agent / log_activity.
  * Returns the referral agent PDA, its authority, and the authority's ATA for point_mint.
@@ -332,12 +348,16 @@ export async function getConfig(
   admin: PublicKey;
   feeRecipient: PublicKey;
   pointMint: PublicKey;
+  refereeMint: PublicKey;
+  refereeActivityMint: PublicKey;
   registerFee: number;
   pointsSelf: number;
   pointsReferral: number;
   referralRegisterFee: number;
   referralFeeShare: number;
   referralRegisterPoints: number;
+  activityReward: number;
+  referralActivityReward: number;
 }> {
   const pid = new PublicKey(options?.programId ?? DEFAULT_AGENT_REGISTRY_PROGRAM_ID);
   const configPda = getConfigPda(pid);
@@ -350,53 +370,84 @@ export async function getConfig(
   const admin = new PublicKey(buf.subarray(offset, offset + 32)); offset += 32;
   const feeRecipient = new PublicKey(buf.subarray(offset, offset + 32)); offset += 32;
   const pointMint = new PublicKey(buf.subarray(offset, offset + 32)); offset += 32;
+  const refereeMint = new PublicKey(buf.subarray(offset, offset + 32)); offset += 32;
+  const refereeActivityMint = 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)); offset += 8;
   const referralRegisterFee = Number(buf.readBigUInt64LE(offset)); offset += 8;
   const referralFeeShare = Number(buf.readBigUInt64LE(offset)); offset += 8;
-  const referralRegisterPoints = Number(buf.readBigUInt64LE(offset));
-  return { admin, feeRecipient, pointMint, registerFee, pointsSelf, pointsReferral, referralRegisterFee, referralFeeShare, referralRegisterPoints };
+  const referralRegisterPoints = Number(buf.readBigUInt64LE(offset)); offset += 8;
+  const activityReward = Number(buf.readBigUInt64LE(offset)); offset += 8;
+  const referralActivityReward = Number(buf.readBigUInt64LE(offset));
+  return { admin, feeRecipient, pointMint, refereeMint, refereeActivityMint, registerFee, pointsSelf, pointsReferral, referralRegisterFee, referralFeeShare, referralRegisterPoints, activityReward, referralActivityReward };
 }
 
 // ─── Agent CRUD ─────────────────────────────────────────────────
 
 /**
- * Register a new agent on-chain. Charges the program's registration fee.
+ * Register a new agent on-chain (without referral). Charges the program's registration fee.
  */
 export async function registerAgent(
   connection: Connection,
   wallet: Keypair,
   agentId: string,
-  options?: AgentRegistryOptions,
-  referralAgentId?: 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 config = await getConfig(connection, options);
-  const pointMint = getPointMintPda(program.programId);
 
-  let referralAccounts: {
-    referralAgent: PublicKey | null;
-    referralAuthority: PublicKey | null;
-    referralPointAccount: PublicKey | null;
-  } = { referralAgent: null, referralAuthority: null, referralPointAccount: null };
-
-  if (referralAgentId) {
-    const resolved = await resolveReferralAccounts(
-      connection, referralAgentId, program.programId, pointMint
-    );
-    referralAccounts = resolved;
+  const signature = await program.methods
+    .registerAgent(agentId)
+    .accounts({
+      authority: wallet.publicKey,
+      feeRecipient: config.feeRecipient,
+    } as any)
+    .signers([wallet])
+    .rpc();
+
+  const agentPubkey = getAgentPda(program.programId, agentId);
+  return { signature, agentPubkey };
+}
+
+/**
+ * Register a new agent on-chain with a referral agent.
+ * Charges the referral registration fee and awards referral points/tokens.
+ */
+export async function registerAgentWithReferral(
+  connection: Connection,
+  wallet: Keypair,
+  agentId: string,
+  referralAgentId: 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 config = await getConfig(connection, options);
+  const pointMint = getPointMintPda(program.programId);
+
+  const { referralAgent, referralAuthority, referralPointAccount } =
+    await resolveReferralAccounts(connection, referralAgentId, program.programId, pointMint);
+
+  const refereeMint = getRefereeMintPda(program.programId);
+  const referralRefereeAccount = getAssociatedTokenAddressSync(
+    refereeMint, referralAuthority, true, TOKEN_2022_PROGRAM_ID
+  );
 
   const signature = await program.methods
-    .registerAgent(agentId)
+    .registerAgentWithReferral(agentId)
     .accounts({
       authority: wallet.publicKey,
       feeRecipient: config.feeRecipient,
-      ...referralAccounts,
+      referralAgent,
+      referralAuthority,
+      referralPointAccount,
+      referralRefereeAccount,
     } as any)
     .signers([wallet])
     .rpc();
@@ -652,9 +703,6 @@ export async function closeBuffer(
 
 /**
  * Log an activity event for the agent (emits on-chain event).
- *
- * @param referralAgentId - Optional referral agent ID. If provided, the referral
- *                          agent's PDA is passed to earn referral points.
  */
 export async function logActivity(
   connection: Connection,
@@ -663,8 +711,7 @@ export async function logActivity(
   model: string,
   activity: string,
   log: string,
-  options?: AgentRegistryOptions,
-  referralAgentId?: string
+  options?: AgentRegistryOptions
 ): Promise<string> {
   const program = createProgram(connection, wallet, options?.programId);
   const pointMint = getPointMintPda(program.programId);
@@ -672,26 +719,54 @@ export async function logActivity(
     pointMint, wallet.publicKey, true, TOKEN_2022_PROGRAM_ID
   );
 
-  let referralAccounts: {
-    referralAgent: PublicKey | null;
-    referralAuthority: PublicKey | null;
-    referralPointAccount: PublicKey | null;
-  } = { referralAgent: null, referralAuthority: null, referralPointAccount: null };
-
-  if (referralAgentId) {
-    const resolved = await resolveReferralAccounts(
-      connection, referralAgentId, program.programId, pointMint
-    );
-    referralAccounts = resolved;
-  }
-
   return program.methods
     .logActivity(agentId, model, activity, log)
     .accounts({
       authority: wallet.publicKey,
       authorityPointAccount,
       instructions: SYSVAR_INSTRUCTIONS_PUBKEY,
-      ...referralAccounts,
+    } as any)
+    .signers([wallet])
+    .rpc();
+}
+
+/**
+ * Log an activity event with a referral agent to earn referral rewards.
+ */
+export async function logActivityWithReferral(
+  connection: Connection,
+  wallet: Keypair,
+  agentId: string,
+  model: string,
+  activity: string,
+  log: string,
+  referralAgentId: string,
+  options?: AgentRegistryOptions
+): Promise<string> {
+  const program = createProgram(connection, wallet, options?.programId);
+  const pointMint = getPointMintPda(program.programId);
+  const authorityPointAccount = getAssociatedTokenAddressSync(
+    pointMint, wallet.publicKey, true, TOKEN_2022_PROGRAM_ID
+  );
+
+  const { referralAgent, referralAuthority, referralPointAccount } =
+    await resolveReferralAccounts(connection, referralAgentId, program.programId, pointMint);
+
+  const refereeActivityMint = getRefereeActivityMintPda(program.programId);
+  const referralRefereeActivityAccount = getAssociatedTokenAddressSync(
+    refereeActivityMint, referralAuthority, true, TOKEN_2022_PROGRAM_ID
+  );
+
+  return program.methods
+    .logActivityWithReferral(agentId, model, activity, log)
+    .accounts({
+      authority: wallet.publicKey,
+      authorityPointAccount,
+      referralAgent,
+      referralAuthority,
+      referralPointAccount,
+      referralRefereeActivityAccount,
+      instructions: SYSVAR_INSTRUCTIONS_PUBKEY,
     } as any)
     .signers([wallet])
     .rpc();
@@ -700,8 +775,6 @@ export async function logActivity(
 /**
  * Build a logActivity instruction without sending it.
  * Useful for appending to an existing transaction.
- *
- * @param referralAgentId - Optional referral agent ID.
  */
 export async function makeLogActivityIx(
   connection: Connection,
@@ -710,8 +783,7 @@ export async function makeLogActivityIx(
   model: string,
   activity: string,
   log: string,
-  options?: AgentRegistryOptions,
-  referralAgentId?: string
+  options?: AgentRegistryOptions
 ): Promise<TransactionInstruction> {
   const program = createProgram(connection, Keypair.generate(), options?.programId);
   const pointMint = getPointMintPda(program.programId);
@@ -719,26 +791,53 @@ export async function makeLogActivityIx(
     pointMint, authority, true, TOKEN_2022_PROGRAM_ID
   );
 
-  let referralAccounts: {
-    referralAgent: PublicKey | null;
-    referralAuthority: PublicKey | null;
-    referralPointAccount: PublicKey | null;
-  } = { referralAgent: null, referralAuthority: null, referralPointAccount: null };
-
-  if (referralAgentId) {
-    const resolved = await resolveReferralAccounts(
-      connection, referralAgentId, program.programId, pointMint
-    );
-    referralAccounts = resolved;
-  }
-
   return program.methods
     .logActivity(agentId, model, activity, log)
     .accounts({
       authority,
       authorityPointAccount,
       instructions: SYSVAR_INSTRUCTIONS_PUBKEY,
-      ...referralAccounts,
+    } as any)
+    .instruction();
+}
+
+/**
+ * Build a logActivityWithReferral instruction without sending it.
+ */
+export async function makeLogActivityWithReferralIx(
+  connection: Connection,
+  authority: PublicKey,
+  agentId: string,
+  model: string,
+  activity: string,
+  log: string,
+  referralAgentId: string,
+  options?: AgentRegistryOptions
+): Promise<TransactionInstruction> {
+  const program = createProgram(connection, Keypair.generate(), options?.programId);
+  const pointMint = getPointMintPda(program.programId);
+  const authorityPointAccount = getAssociatedTokenAddressSync(
+    pointMint, authority, true, TOKEN_2022_PROGRAM_ID
+  );
+
+  const { referralAgent, referralAuthority, referralPointAccount } =
+    await resolveReferralAccounts(connection, referralAgentId, program.programId, pointMint);
+
+  const refereeActivityMint = getRefereeActivityMintPda(program.programId);
+  const referralRefereeActivityAccount = getAssociatedTokenAddressSync(
+    refereeActivityMint, referralAuthority, true, TOKEN_2022_PROGRAM_ID
+  );
+
+  return program.methods
+    .logActivityWithReferral(agentId, model, activity, log)
+    .accounts({
+      authority,
+      authorityPointAccount,
+      referralAgent,
+      referralAuthority,
+      referralPointAccount,
+      referralRefereeActivityAccount,
+      instructions: SYSVAR_INSTRUCTIONS_PUBKEY,
     } as any)
     .instruction();
 }
@@ -758,11 +857,26 @@ export async function setReferral(
 ): Promise<string> {
   const program = createProgram(connection, wallet, options?.programId);
   const referralAgent = getAgentPda(program.programId, referralAgentId);
+
+  // Resolve referral authority for referee token minting
+  const accountInfo = await connection.getAccountInfo(referralAgent);
+  if (!accountInfo) {
+    throw new Error(`Referral agent "${referralAgentId}" not found`);
+  }
+  const referralAuthority = new PublicKey(accountInfo.data.subarray(8, 40));
+
+  const refereeMint = getRefereeMintPda(program.programId);
+  const referralRefereeAccount = getAssociatedTokenAddressSync(
+    refereeMint, referralAuthority, true, TOKEN_2022_PROGRAM_ID
+  );
+
   return program.methods
     .setReferral(agentId)
     .accounts({
       authority: wallet.publicKey,
       referralAgent,
+      referralAuthority,
+      referralRefereeAccount,
     } as any)
     .signers([wallet])
     .rpc();