nara-sdk 1.0.41 → 1.0.43

package/index.ts

@@ -26,7 +26,16 @@ export {
   parseQuestReward,
   computeAnswerHash,
   createQuestion,
+  stake,
+  unstake,
+  getStakeInfo,
+  initializeQuest,
+  setMaxRewardCount,
+  setMinRewardCount,
+  transferQuestAuthority,
+  getQuestConfig,
   type QuestInfo,
+  type StakeInfo,
   type ZkProof,
   type ZkProofHex,
   type SubmitAnswerResult,
@@ -105,6 +114,7 @@ export {
   updatePointsConfig,
   setReferral,
   updateReferralConfig,
+  updateActivityConfig,
   type AgentRecord,
   type AgentInfo,
   type MemoryMode,

package/package.json

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

package/src/agent_registry.ts

@@ -998,3 +998,25 @@ export async function updateReferralConfig(
     .signers([wallet])
     .rpc();
 }
+
+/**
+ * Update the activity reward configuration (admin-only).
+ * @param activityReward - Points awarded per activity
+ * @param referralActivityReward - Points awarded to referrer per activity
+ */
+export async function updateActivityConfig(
+  connection: Connection,
+  wallet: Keypair,
+  activityReward: number | anchor.BN,
+  referralActivityReward: number | anchor.BN,
+  options?: AgentRegistryOptions
+): Promise<string> {
+  const program = createProgram(connection, wallet, options?.programId);
+  const ar = typeof activityReward === "number" ? new anchor.BN(activityReward) : activityReward;
+  const rar = typeof referralActivityReward === "number" ? new anchor.BN(referralActivityReward) : referralActivityReward;
+  return program.methods
+    .updateActivityConfig(ar, rar)
+    .accounts({ admin: wallet.publicKey } as any)
+    .signers([wallet])
+    .rpc();
+}

package/src/idls/nara_quest.json

@@ -203,6 +203,216 @@
       ],
       "args": []
     },
+    {
+      "name": "set_max_reward_count",
+      "discriminator": [
+        247,
+        62,
+        67,
+        243,
+        249,
+        243,
+        102,
+        62
+      ],
+      "accounts": [
+        {
+          "name": "game_config",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  113,
+                  117,
+                  101,
+                  115,
+                  116,
+                  95,
+                  99,
+                  111,
+                  110,
+                  102,
+                  105,
+                  103
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "name": "authority",
+          "signer": true
+        }
+      ],
+      "args": [
+        {
+          "name": "max_reward_count",
+          "type": "u32"
+        }
+      ]
+    },
+    {
+      "name": "set_min_reward_count",
+      "discriminator": [
+        108,
+        213,
+        24,
+        47,
+        93,
+        149,
+        58,
+        4
+      ],
+      "accounts": [
+        {
+          "name": "game_config",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  113,
+                  117,
+                  101,
+                  115,
+                  116,
+                  95,
+                  99,
+                  111,
+                  110,
+                  102,
+                  105,
+                  103
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "name": "authority",
+          "signer": true
+        }
+      ],
+      "args": [
+        {
+          "name": "min_reward_count",
+          "type": "u32"
+        }
+      ]
+    },
+    {
+      "name": "stake",
+      "discriminator": [
+        206,
+        176,
+        202,
+        18,
+        200,
+        209,
+        179,
+        108
+      ],
+      "accounts": [
+        {
+          "name": "pool",
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  113,
+                  117,
+                  101,
+                  115,
+                  116,
+                  95,
+                  112,
+                  111,
+                  111,
+                  108
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "name": "stake_record",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  113,
+                  117,
+                  101,
+                  115,
+                  116,
+                  95,
+                  115,
+                  116,
+                  97,
+                  107,
+                  101
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "user"
+              }
+            ]
+          }
+        },
+        {
+          "name": "stake_vault",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  113,
+                  117,
+                  101,
+                  115,
+                  116,
+                  95,
+                  115,
+                  116,
+                  97,
+                  107,
+                  101,
+                  95,
+                  118,
+                  97,
+                  117,
+                  108,
+                  116
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "name": "user",
+          "writable": true,
+          "signer": true
+        },
+        {
+          "name": "system_program",
+          "address": "11111111111111111111111111111111"
+        }
+      ],
+      "args": [
+        {
+          "name": "amount",
+          "type": "u64"
+        }
+      ]
+    },
     {
       "name": "submit_answer",
       "discriminator": [
@@ -268,6 +478,34 @@
             ]
           }
         },
+        {
+          "name": "stake_record",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  113,
+                  117,
+                  101,
+                  115,
+                  116,
+                  95,
+                  115,
+                  116,
+                  97,
+                  107,
+                  101
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "user"
+              }
+            ]
+          }
+        },
         {
           "name": "vault",
           "writable": true,
@@ -393,6 +631,116 @@
           "type": "pubkey"
         }
       ]
+    },
+    {
+      "name": "unstake",
+      "discriminator": [
+        90,
+        95,
+        107,
+        42,
+        205,
+        124,
+        50,
+        225
+      ],
+      "accounts": [
+        {
+          "name": "pool",
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  113,
+                  117,
+                  101,
+                  115,
+                  116,
+                  95,
+                  112,
+                  111,
+                  111,
+                  108
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "name": "stake_record",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  113,
+                  117,
+                  101,
+                  115,
+                  116,
+                  95,
+                  115,
+                  116,
+                  97,
+                  107,
+                  101
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "user"
+              }
+            ]
+          }
+        },
+        {
+          "name": "stake_vault",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  113,
+                  117,
+                  101,
+                  115,
+                  116,
+                  95,
+                  115,
+                  116,
+                  97,
+                  107,
+                  101,
+                  95,
+                  118,
+                  97,
+                  117,
+                  108,
+                  116
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "name": "user",
+          "writable": true,
+          "signer": true
+        },
+        {
+          "name": "system_program",
+          "address": "11111111111111111111111111111111"
+        }
+      ],
+      "args": [
+        {
+          "name": "amount",
+          "type": "u64"
+        }
+      ]
     }
   ],
   "accounts": [
@@ -422,6 +770,19 @@
         188
       ]
     },
+    {
+      "name": "StakeRecord",
+      "discriminator": [
+        174,
+        163,
+        11,
+        208,
+        150,
+        236,
+        11,
+        205
+      ]
+    },
     {
       "name": "WinnerRecord",
       "discriminator": [
@@ -491,6 +852,26 @@
       "code": 6007,
       "name": "AlreadyAnswered",
       "msg": "Already answered this round"
+    },
+    {
+      "code": 6008,
+      "name": "InvalidMinRewardCount",
+      "msg": "min_reward_count must be > 0 and <= max_reward_count"
+    },
+    {
+      "code": 6009,
+      "name": "InvalidMaxRewardCount",
+      "msg": "max_reward_count must be >= min_reward_count"
+    },
+    {
+      "code": 6010,
+      "name": "UnstakeNotReady",
+      "msg": "Cannot unstake until round advances or deadline passes"
+    },
+    {
+      "code": 6011,
+      "name": "InsufficientStakeBalance",
+      "msg": "Unstake amount exceeds staked balance"
     }
   ],
   "types": [
@@ -535,6 +916,14 @@
             "name": "authority",
             "type": "pubkey"
           },
+          {
+            "name": "min_reward_count",
+            "type": "u32"
+          },
+          {
+            "name": "max_reward_count",
+            "type": "u32"
+          },
           {
             "name": "_padding",
             "type": {
@@ -593,6 +982,39 @@
             "name": "difficulty",
             "type": "u32"
           },
+          {
+            "name": "stake_requirement",
+            "type": "u64"
+          },
+          {
+            "name": "min_winner_stake",
+            "type": "u64"
+          },
+          {
+            "name": "_padding",
+            "type": {
+              "array": [
+                "u8",
+                64
+              ]
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "StakeRecord",
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "amount",
+            "type": "u64"
+          },
+          {
+            "name": "stake_round",
+            "type": "u64"
+          },
           {
             "name": "_padding",
             "type": {

package/src/idls/nara_quest.ts

@@ -209,6 +209,216 @@ export type NaraQuest = {
       ],
       "args": []
     },
+    {
+      "name": "setMaxRewardCount",
+      "discriminator": [
+        247,
+        62,
+        67,
+        243,
+        249,
+        243,
+        102,
+        62
+      ],
+      "accounts": [
+        {
+          "name": "gameConfig",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  113,
+                  117,
+                  101,
+                  115,
+                  116,
+                  95,
+                  99,
+                  111,
+                  110,
+                  102,
+                  105,
+                  103
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "name": "authority",
+          "signer": true
+        }
+      ],
+      "args": [
+        {
+          "name": "maxRewardCount",
+          "type": "u32"
+        }
+      ]
+    },
+    {
+      "name": "setMinRewardCount",
+      "discriminator": [
+        108,
+        213,
+        24,
+        47,
+        93,
+        149,
+        58,
+        4
+      ],
+      "accounts": [
+        {
+          "name": "gameConfig",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  113,
+                  117,
+                  101,
+                  115,
+                  116,
+                  95,
+                  99,
+                  111,
+                  110,
+                  102,
+                  105,
+                  103
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "name": "authority",
+          "signer": true
+        }
+      ],
+      "args": [
+        {
+          "name": "minRewardCount",
+          "type": "u32"
+        }
+      ]
+    },
+    {
+      "name": "stake",
+      "discriminator": [
+        206,
+        176,
+        202,
+        18,
+        200,
+        209,
+        179,
+        108
+      ],
+      "accounts": [
+        {
+          "name": "pool",
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  113,
+                  117,
+                  101,
+                  115,
+                  116,
+                  95,
+                  112,
+                  111,
+                  111,
+                  108
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "name": "stakeRecord",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  113,
+                  117,
+                  101,
+                  115,
+                  116,
+                  95,
+                  115,
+                  116,
+                  97,
+                  107,
+                  101
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "user"
+              }
+            ]
+          }
+        },
+        {
+          "name": "stakeVault",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  113,
+                  117,
+                  101,
+                  115,
+                  116,
+                  95,
+                  115,
+                  116,
+                  97,
+                  107,
+                  101,
+                  95,
+                  118,
+                  97,
+                  117,
+                  108,
+                  116
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "name": "user",
+          "writable": true,
+          "signer": true
+        },
+        {
+          "name": "systemProgram",
+          "address": "11111111111111111111111111111111"
+        }
+      ],
+      "args": [
+        {
+          "name": "amount",
+          "type": "u64"
+        }
+      ]
+    },
     {
       "name": "submitAnswer",
       "discriminator": [
@@ -274,6 +484,34 @@ export type NaraQuest = {
             ]
           }
         },
+        {
+          "name": "stakeRecord",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  113,
+                  117,
+                  101,
+                  115,
+                  116,
+                  95,
+                  115,
+                  116,
+                  97,
+                  107,
+                  101
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "user"
+              }
+            ]
+          }
+        },
         {
           "name": "vault",
           "writable": true,
@@ -399,6 +637,116 @@ export type NaraQuest = {
           "type": "pubkey"
         }
       ]
+    },
+    {
+      "name": "unstake",
+      "discriminator": [
+        90,
+        95,
+        107,
+        42,
+        205,
+        124,
+        50,
+        225
+      ],
+      "accounts": [
+        {
+          "name": "pool",
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  113,
+                  117,
+                  101,
+                  115,
+                  116,
+                  95,
+                  112,
+                  111,
+                  111,
+                  108
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "name": "stakeRecord",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  113,
+                  117,
+                  101,
+                  115,
+                  116,
+                  95,
+                  115,
+                  116,
+                  97,
+                  107,
+                  101
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "user"
+              }
+            ]
+          }
+        },
+        {
+          "name": "stakeVault",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  113,
+                  117,
+                  101,
+                  115,
+                  116,
+                  95,
+                  115,
+                  116,
+                  97,
+                  107,
+                  101,
+                  95,
+                  118,
+                  97,
+                  117,
+                  108,
+                  116
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "name": "user",
+          "writable": true,
+          "signer": true
+        },
+        {
+          "name": "systemProgram",
+          "address": "11111111111111111111111111111111"
+        }
+      ],
+      "args": [
+        {
+          "name": "amount",
+          "type": "u64"
+        }
+      ]
     }
   ],
   "accounts": [
@@ -428,6 +776,19 @@ export type NaraQuest = {
         188
       ]
     },
+    {
+      "name": "stakeRecord",
+      "discriminator": [
+        174,
+        163,
+        11,
+        208,
+        150,
+        236,
+        11,
+        205
+      ]
+    },
     {
       "name": "winnerRecord",
       "discriminator": [
@@ -497,6 +858,26 @@ export type NaraQuest = {
       "code": 6007,
       "name": "alreadyAnswered",
       "msg": "Already answered this round"
+    },
+    {
+      "code": 6008,
+      "name": "invalidMinRewardCount",
+      "msg": "min_reward_count must be > 0 and <= max_reward_count"
+    },
+    {
+      "code": 6009,
+      "name": "invalidMaxRewardCount",
+      "msg": "max_reward_count must be >= min_reward_count"
+    },
+    {
+      "code": 6010,
+      "name": "unstakeNotReady",
+      "msg": "Cannot unstake until round advances or deadline passes"
+    },
+    {
+      "code": 6011,
+      "name": "insufficientStakeBalance",
+      "msg": "Unstake amount exceeds staked balance"
     }
   ],
   "types": [
@@ -541,6 +922,14 @@ export type NaraQuest = {
             "name": "authority",
             "type": "pubkey"
           },
+          {
+            "name": "minRewardCount",
+            "type": "u32"
+          },
+          {
+            "name": "maxRewardCount",
+            "type": "u32"
+          },
           {
             "name": "padding",
             "type": {
@@ -599,6 +988,39 @@ export type NaraQuest = {
             "name": "difficulty",
             "type": "u32"
           },
+          {
+            "name": "stakeRequirement",
+            "type": "u64"
+          },
+          {
+            "name": "minWinnerStake",
+            "type": "u64"
+          },
+          {
+            "name": "padding",
+            "type": {
+              "array": [
+                "u8",
+                64
+              ]
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "stakeRecord",
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "amount",
+            "type": "u64"
+          },
+          {
+            "name": "stakeRound",
+            "type": "u64"
+          },
           {
             "name": "padding",
             "type": {

package/src/quest.ts

@@ -49,6 +49,17 @@ export interface QuestInfo {
   deadline: number;
   timeRemaining: number;
   expired: boolean;
+  /** Minimum stake required to submit an answer (in NARA) */
+  stakeRequirement: number;
+  /** Minimum stake to be eligible for rewards (in NARA) */
+  minWinnerStake: number;
+}
+
+export interface StakeInfo {
+  /** Current staked amount (in NARA) */
+  amount: number;
+  /** Round when the stake was made */
+  stakeRound: number;
 }
 
 export interface ZkProof {
@@ -77,6 +88,8 @@ export interface QuestOptions {
   circuitWasmPath?: string | Uint8Array;
   /** File path (Node.js), URL string, or pre-loaded Uint8Array (browser) */
   zkeyPath?: string | Uint8Array;
+  /** "auto" = auto top-up stake to stakeRequirement; number = stake exact NARA amount */
+  stake?: "auto" | number;
 }
 
 export interface ActivityLog {
@@ -211,6 +224,25 @@ function getWinnerRecordPda(
   return pda;
 }
 
+function getStakeRecordPda(
+  programId: PublicKey,
+  user: PublicKey
+): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [new TextEncoder().encode("quest_stake"), user.toBytes()],
+    programId
+  );
+  return pda;
+}
+
+function getStakeVaultPda(programId: PublicKey): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [new TextEncoder().encode("quest_stake_vault")],
+    programId
+  );
+  return pda;
+}
+
 // ─── SDK functions ───────────────────────────────────────────────
 
 /**
@@ -246,6 +278,8 @@ export async function getQuestInfo(
     deadline,
     timeRemaining: secsLeft,
     expired: secsLeft <= 0,
+    stakeRequirement: Number(pool.stakeRequirement.toString()) / LAMPORTS_PER_SOL,
+    minWinnerStake: Number(pool.minWinnerStake.toString()) / LAMPORTS_PER_SOL,
   };
 }
 
@@ -332,31 +366,66 @@ export async function submitAnswer(
 ): Promise<SubmitAnswerResult> {
   const program = createProgram(connection, wallet, options?.programId);
 
-  if (activityLog) {
-    const { makeLogActivityIx, makeLogActivityWithReferralIx } = await import("./agent_registry");
+  // Build optional stake instruction
+  let stakeIx: any = null;
+  if (options?.stake !== undefined) {
+    let stakeLamports: BN;
+    if (options.stake === "auto") {
+      const quest = await getQuestInfo(connection, wallet, options);
+      const stakeInfo = await getStakeInfo(connection, wallet.publicKey, options);
+      const required = quest.stakeRequirement;
+      const current = stakeInfo?.amount ?? 0;
+      const deficit = required - current;
+      if (deficit > 0) {
+        stakeLamports = new BN(Math.round(deficit * LAMPORTS_PER_SOL));
+      } else {
+        stakeLamports = new BN(0);
+      }
+    } else {
+      stakeLamports = new BN(Math.round(options.stake * LAMPORTS_PER_SOL));
+    }
+    if (!stakeLamports.isZero()) {
+      stakeIx = await program.methods
+        .stake(stakeLamports)
+        .accounts({ user: wallet.publicKey } as any)
+        .instruction();
+    }
+  }
+
+  // If we need a composite transaction (stake and/or activityLog)
+  if (stakeIx || activityLog) {
     const submitIx = await program.methods
       .submitAnswer(proof.proofA as any, proof.proofB as any, proof.proofC as any, agent, model)
       .accounts({ user: wallet.publicKey, payer: wallet.publicKey })
       .instruction();
-    const logIx = activityLog.referralAgentId
-      ? await makeLogActivityWithReferralIx(
-          connection,
-          wallet.publicKey,
-          activityLog.agentId,
-          activityLog.model,
-          activityLog.activity,
-          activityLog.log,
-          activityLog.referralAgentId
-        )
-      : await makeLogActivityIx(
-          connection,
-          wallet.publicKey,
-          activityLog.agentId,
-          activityLog.model,
-          activityLog.activity,
-          activityLog.log
-        );
-    const tx = new Transaction().add(submitIx).add(logIx);
+
+    const tx = new Transaction();
+    if (stakeIx) tx.add(stakeIx);
+    tx.add(submitIx);
+
+    if (activityLog) {
+      const { makeLogActivityIx, makeLogActivityWithReferralIx } = await import("./agent_registry");
+      const logIx = activityLog.referralAgentId
+        ? await makeLogActivityWithReferralIx(
+            connection,
+            wallet.publicKey,
+            activityLog.agentId,
+            activityLog.model,
+            activityLog.activity,
+            activityLog.log,
+            activityLog.referralAgentId
+          )
+        : await makeLogActivityIx(
+            connection,
+            wallet.publicKey,
+            activityLog.agentId,
+            activityLog.model,
+            activityLog.activity,
+            activityLog.log
+          );
+      tx.add(logIx);
+    }
+
     tx.feePayer = wallet.publicKey;
     tx.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
     tx.sign(wallet);
@@ -469,6 +538,68 @@ export async function computeAnswerHash(answer: string): Promise<number[]> {
   return Array.from(bigintToBytes32(BigInt(hashStr)));
 }
 
+/**
+ * Stake NARA to participate in quests.
+ *
+ * @param amount - Amount to stake in NARA
+ */
+export async function stake(
+  connection: Connection,
+  wallet: Keypair,
+  amount: number,
+  options?: QuestOptions
+): Promise<string> {
+  const program = createProgram(connection, wallet, options?.programId);
+  const lamports = new BN(Math.round(amount * LAMPORTS_PER_SOL));
+  return program.methods
+    .stake(lamports)
+    .accounts({ user: wallet.publicKey } as any)
+    .signers([wallet])
+    .rpc();
+}
+
+/**
+ * Unstake NARA. Can only unstake after the round advances or deadline passes.
+ *
+ * @param amount - Amount to unstake in NARA
+ */
+export async function unstake(
+  connection: Connection,
+  wallet: Keypair,
+  amount: number,
+  options?: QuestOptions
+): Promise<string> {
+  const program = createProgram(connection, wallet, options?.programId);
+  const lamports = new BN(Math.round(amount * LAMPORTS_PER_SOL));
+  return program.methods
+    .unstake(lamports)
+    .accounts({ user: wallet.publicKey } as any)
+    .signers([wallet])
+    .rpc();
+}
+
+/**
+ * Get stake info for a user. Returns null if no stake record exists.
+ */
+export async function getStakeInfo(
+  connection: Connection,
+  user: PublicKey,
+  options?: QuestOptions
+): Promise<StakeInfo | null> {
+  const kp = Keypair.generate();
+  const program = createProgram(connection, kp, options?.programId);
+  const stakeRecordPda = getStakeRecordPda(program.programId, user);
+  try {
+    const record = await program.account.stakeRecord.fetch(stakeRecordPda);
+    return {
+      amount: record.amount.toNumber() / LAMPORTS_PER_SOL,
+      stakeRound: record.stakeRound.toNumber(),
+    };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Create a new quest question on-chain (authority only).
  *
@@ -504,3 +635,94 @@ export async function createQuestion(
 
   return signature;
 }
+
+// ─── Admin functions ───────────────────────────────────────────────
+
+/**
+ * Initialize the quest program (one-time setup). The caller becomes the authority.
+ */
+export async function initializeQuest(
+  connection: Connection,
+  wallet: Keypair,
+  options?: QuestOptions
+): Promise<string> {
+  const program = createProgram(connection, wallet, options?.programId);
+  return program.methods
+    .initialize()
+    .accounts({ authority: wallet.publicKey } as any)
+    .signers([wallet])
+    .rpc();
+}
+
+/**
+ * Set the maximum reward count (authority only).
+ */
+export async function setMaxRewardCount(
+  connection: Connection,
+  wallet: Keypair,
+  maxRewardCount: number,
+  options?: QuestOptions
+): Promise<string> {
+  const program = createProgram(connection, wallet, options?.programId);
+  return program.methods
+    .setMaxRewardCount(maxRewardCount)
+    .accounts({ authority: wallet.publicKey } as any)
+    .signers([wallet])
+    .rpc();
+}
+
+/**
+ * Set the minimum reward count (authority only).
+ */
+export async function setMinRewardCount(
+  connection: Connection,
+  wallet: Keypair,
+  minRewardCount: number,
+  options?: QuestOptions
+): Promise<string> {
+  const program = createProgram(connection, wallet, options?.programId);
+  return program.methods
+    .setMinRewardCount(minRewardCount)
+    .accounts({ authority: wallet.publicKey } as any)
+    .signers([wallet])
+    .rpc();
+}
+
+/**
+ * Transfer quest program authority to a new address (authority only).
+ */
+export async function transferQuestAuthority(
+  connection: Connection,
+  wallet: Keypair,
+  newAuthority: PublicKey,
+  options?: QuestOptions
+): Promise<string> {
+  const program = createProgram(connection, wallet, options?.programId);
+  return program.methods
+    .transferAuthority(newAuthority)
+    .accounts({ authority: wallet.publicKey } as any)
+    .signers([wallet])
+    .rpc();
+}
+
+/**
+ * Get quest program config (authority, min/max reward count).
+ */
+export async function getQuestConfig(
+  connection: Connection,
+  options?: QuestOptions
+): Promise<{ authority: PublicKey; minRewardCount: number; maxRewardCount: number }> {
+  const kp = Keypair.generate();
+  const program = createProgram(connection, kp, options?.programId);
+  const programId = new PublicKey(options?.programId ?? DEFAULT_QUEST_PROGRAM_ID);
+  const [configPda] = PublicKey.findProgramAddressSync(
+    [new TextEncoder().encode("quest_config")],
+    programId
+  );
+  const config = await program.account.gameConfig.fetch(configPda);
+  return {
+    authority: config.authority,
+    minRewardCount: config.minRewardCount,
+    maxRewardCount: config.maxRewardCount,
+  };
+}