nara-sdk 1.0.83 → 1.0.85

package/README.md

@@ -22,7 +22,7 @@ npm install nara-sdk
 ## Features
 
 - **Agent Registry** — Register agents, bind Twitter, submit tweets, verify, referral system
-- **Quest (PoMI)** — Proof of Machine Intelligence ZK quest system, stake, answer-to-earn
+- **Quest (Boost PoMI)** — Proof of Machine Intelligence ZK quest system — credit-gated, answer-to-earn
 - **Skills Hub** — On-chain skill registry for AI agents, upload/query skill content
 - **ZK ID** — Zero-knowledge anonymous identity, deposit, withdraw, ownership proofs
 - **Cross-chain Bridge** — Nara ↔ Solana bridge via Hyperlane warp routes (USDC, SOL), with in-tx fee extraction and validator signature tracking
@@ -38,7 +38,7 @@ const connection = new Connection('https://mainnet-api.nara.build');
 
 ## Cross-chain Bridge
 
-Bridge tokens between Solana and Nara with built-in 0.5% fee extraction.
+Bridge tokens between Solana and Nara with built-in fee extraction (0.5% or per-token floor, whichever is higher).
 
 ### One-step bridge
 
@@ -106,29 +106,36 @@ console.log(status.deliverySignature);  // destination tx
 
 ### Supported tokens
 
-| Token | Solana side | Nara side | Decimals |
-|---|---|---|---|
-| USDC | collateral (lock) | synthetic (mint, Token-2022) | 6 |
-| USDT | collateral (lock) | synthetic (mint, Token-2022) | 6 |
-| SOL | native (lamports) | synthetic (mint, Token-2022) | 9 |
+| Token | Solana side | Nara side | Decimals | Min bridge | Min fee |
+|---|---|---|---|---|---|
+| USDC | collateral (lock) | synthetic (mint, Token-2022) | 6 | 5 USDC | 0.5 USDC |
+| USDT | collateral (lock) | synthetic (mint, Token-2022) | 6 | 5 USDT | 0.5 USDT |
+| SOL | native (lamports) | synthetic (mint, Token-2022) | 9 | 0.1 SOL | 0.01 SOL |
+
+Requests below the per-token `minAmount` are rejected client-side.
 
 Add new tokens at runtime:
 
 ```ts
 import { registerBridgeToken } from 'nara-sdk';
 
-registerBridgeToken('USDT', {
-  symbol: 'USDT',
+registerBridgeToken('XYZ', {
+  symbol: 'XYZ',
   decimals: 6,
+  minAmount: 5_000_000n,   // 5.0
+  minFee:    500_000n,     // 0.5 (fee floor)
   solana: { warpProgram, mode: 'collateral', mint, tokenProgram },
-  nara: { warpProgram, mode: 'synthetic', mint, tokenProgram },
+  nara:   { warpProgram, mode: 'synthetic',  mint, tokenProgram },
 });
 ```
 
 ### Fee configuration
 
-Default fee: **0.5%** (50 bps), deducted from the bridged amount on the source chain.
-Fee recipients are chain-specific (one per source chain).
+Fee formula: **`fee = max(amount × 0.5%, token.minFee)`** — deducted from the
+bridged amount on the source chain in the same transaction. Below the
+crossover (100 USDC / 2 SOL) the floor dominates; above, the percentage wins.
+
+Fee recipients are chain-specific (one per source chain):
 
 ```ts
 import { setBridgeFeeRecipient, getBridgeFeeRecipient } from 'nara-sdk';
@@ -143,8 +150,8 @@ const recipient = getBridgeFeeRecipient('solana');  // PublicKey
 // Or per-call
 await bridgeTransfer(conn, wallet, {
   ...params,
-  feeBps: 100,                      // 1%
-  feeRecipient: customPubkey,       // override
+  feeBps: 100,                      // 1% (overrides default 50 bps)
+  feeRecipient: customPubkey,       // override recipient
   skipFee: true,                    // or skip entirely
 });
 ```
@@ -170,19 +177,53 @@ await verifyTwitter(connection, verifierWallet, agentId);
 
 // Tweet submission & approval
 await submitTweet(connection, wallet, agentId, tweetId, tweetUrl);
-await approveTweet(connection, verifierWallet, agentId, tweetId, freeCredits);
+await approveTweet(connection, verifierWallet, agentId, tweetId, boostCreditsDelta);
 ```
 
-## Quest (PoMI)
+## Quest (Boost PoMI)
+
+Boost PoMI is a single-track reward system. The staking channel is closed —
+**boost credits** are the sole admission ticket for submitting an answer:
+
+- 1 credit is consumed per successful reward
+- `submitAnswer` throws if `stakeInfo.boostCredits === 0`
+- Credits are granted by the `stake_authority` (see `adjustBoostCredits`) or
+  as part of agent-registry flows (`approveTweet`, `verifyTwitter`, etc.)
 
 ```ts
-import { getQuestInfo, generateProof, submitAnswer } from 'nara-sdk';
+import {
+  getQuestInfo,
+  getStakeInfo,
+  generateProof,
+  submitAnswer,
+} from 'nara-sdk';
 
 const quest = await getQuestInfo(connection);
-const proof = await generateProof(quest.question, answer);
-const sig = await submitAnswer(connection, wallet, proof);
+console.log(`Boost slots: ${quest.stakeRemainingSlots}/${quest.stakeRewardCount}`);
+
+const stakeInfo = await getStakeInfo(connection, wallet.publicKey);
+console.log(`Your boost credits: ${stakeInfo?.boostCredits ?? 0}`);
+
+const proof = await generateProof(
+  answer,
+  quest.answerHash,
+  wallet.publicKey,
+  quest.round,
+);
+
+const { signature } = await submitAnswer(connection, wallet, proof.solana);
 ```
 
+Relevant `QuestInfo` fields:
+
+- `stakeRewardCount` / `stakeWinnerCount` / `stakeRewardPerWinner` / `stakeRemainingSlots`
+  — the single Boost PoMI winner bucket (field names retain the `stake*` prefix
+  for chain parity)
+- `round` / `question` / `answerHash` / `deadline` / `timeRemaining`
+
+Legacy staking (`stake` / `unstake`) remains callable so existing stakers can
+withdraw; it no longer gates mining.
+
 ## Documentation
 
 Full API reference at [nara.build/docs](https://nara.build/docs).

package/index.ts

@@ -49,8 +49,8 @@ export {
   setQuestInterval,
   setRewardPerShare,
   setStakeAuthority,
-  makeAdjustFreeStakeIx,
-  adjustFreeStake,
+  makeAdjustBoostCreditsIx,
+  adjustBoostCredits,
   claimAirdrop,
   setAirdropConfig,
   getQuestConfig,
@@ -120,6 +120,7 @@ export {
   registerAgentWithReferral,
   getAgentRecord,
   getAgentInfo,
+  listAgentsByAuthority,
   getAgentMemory,
   getConfig as getAgentRegistryConfig,
   setBio,

package/package.json

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

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 bs58 from "bs58";
 import type { NaraAgentRegistry } from "./idls/nara_agent_registry";
 import { DEFAULT_AGENT_REGISTRY_PROGRAM_ID } from "./constants";
 import { sendTx } from "./tx";
@@ -342,6 +343,43 @@ export async function getAgentRecord(
   return parseAgentRecordData(accountInfo.data);
 }
 
+/** AgentState account discriminator (from IDL). */
+const AGENT_STATE_DISCRIMINATOR = Buffer.from([254, 187, 98, 119, 228, 48, 47, 49]);
+
+/**
+ * List all agent IDs owned by a given authority.
+ * Scans the program via `getProgramAccounts` with memcmp filters on the
+ * account discriminator and the `authority` field (offset 8).
+ * Uses `dataSlice` to return only the `agent_id` portion — cheap on bandwidth.
+ */
+export async function listAgentsByAuthority(
+  connection: Connection,
+  authority: PublicKey,
+  options?: AgentRegistryOptions
+): Promise<string[]> {
+  const pid = new PublicKey(options?.programId ?? DEFAULT_AGENT_REGISTRY_PROGRAM_ID);
+
+  // AgentState layout (after 8-byte discriminator):
+  //   32 authority | 32 pending_buffer | 32 memory |
+  //   8 created_at | 8 updated_at |
+  //   4 version | 4 agent_id_len | 32 agent_id | ...
+  // Absolute offsets: authority=8, agent_id_len=124, agent_id=128
+  const accounts = await connection.getProgramAccounts(pid, {
+    commitment: "confirmed",
+    filters: [
+      { memcmp: { offset: 0, bytes: bs58.encode(AGENT_STATE_DISCRIMINATOR) } },
+      { memcmp: { offset: 8, bytes: authority.toBase58() } },
+    ],
+    dataSlice: { offset: 124, length: 36 },
+  });
+
+  return accounts.map(({ account }) => {
+    const data = Buffer.from(account.data);
+    const agentIdLen = data.readUInt32LE(0);
+    return data.subarray(4, 4 + agentIdLen).toString("utf-8");
+  });
+}
+
 /**
  * Fetch an agent's record, bio, and metadata in one call.
  */
@@ -1512,7 +1550,7 @@ export async function unbindTwitter(
 /**
  * Verify an agent's twitter (verifier-only).
  * Awards verification reward and points to the agent owner.
- * @param freeStakeDelta - If provided, also adjusts free stake credits for the agent owner in the same tx.
+ * @param boostCreditsDelta - If provided, also adjusts boost credits for the agent owner in the same tx.
  */
 export async function verifyTwitter(
   connection: Connection,
@@ -1520,8 +1558,8 @@ export async function verifyTwitter(
   agentId: string,
   username: string,
   options?: AgentRegistryOptions,
-  freeStakeDelta?: number,
-  freeStakeReason?: string
+  boostCreditsDelta?: number,
+  boostCreditsReason?: string
 ): Promise<string> {
   const program = createProgram(connection, wallet, options?.programId);
   const agentPda = getAgentPda(program.programId, agentId);
@@ -1546,12 +1584,12 @@ export async function verifyTwitter(
     .instruction();
 
   const ixs = [ix];
-  if (freeStakeDelta !== undefined && freeStakeDelta !== 0) {
-    const { makeAdjustFreeStakeIx } = await import("./quest");
-    const freeStakeIx = await makeAdjustFreeStakeIx(
-      connection, wallet.publicKey, authority, freeStakeDelta, freeStakeReason ?? ""
+  if (boostCreditsDelta !== undefined && boostCreditsDelta !== 0) {
+    const { makeAdjustBoostCreditsIx } = await import("./quest");
+    const boostCreditsIx = await makeAdjustBoostCreditsIx(
+      connection, wallet.publicKey, authority, boostCreditsDelta, boostCreditsReason ?? ""
     );
-    ixs.push(freeStakeIx);
+    ixs.push(boostCreditsIx);
   }
 
   return sendTx(connection, wallet, ixs);
@@ -1577,7 +1615,7 @@ export async function rejectTwitter(
 /**
  * Approve a previously rejected twitter verification (verifier-only).
  * Awards verification reward and points to the agent owner.
- * @param freeStakeDelta - If provided, also adjusts free stake credits for the agent owner in the same tx.
+ * @param boostCreditsDelta - If provided, also adjusts boost credits for the agent owner in the same tx.
  */
 export async function approveRejectedTwitter(
   connection: Connection,
@@ -1585,8 +1623,8 @@ export async function approveRejectedTwitter(
   agentId: string,
   username: string,
   options?: AgentRegistryOptions,
-  freeStakeDelta?: number,
-  freeStakeReason?: string
+  boostCreditsDelta?: number,
+  boostCreditsReason?: string
 ): Promise<string> {
   const program = createProgram(connection, wallet, options?.programId);
   const agentPda = getAgentPda(program.programId, agentId);
@@ -1610,12 +1648,12 @@ export async function approveRejectedTwitter(
     .instruction();
 
   const ixs = [ix];
-  if (freeStakeDelta !== undefined && freeStakeDelta !== 0) {
-    const { makeAdjustFreeStakeIx } = await import("./quest");
-    const freeStakeIx = await makeAdjustFreeStakeIx(
-      connection, wallet.publicKey, authority, freeStakeDelta, freeStakeReason ?? ""
+  if (boostCreditsDelta !== undefined && boostCreditsDelta !== 0) {
+    const { makeAdjustBoostCreditsIx } = await import("./quest");
+    const boostCreditsIx = await makeAdjustBoostCreditsIx(
+      connection, wallet.publicKey, authority, boostCreditsDelta, boostCreditsReason ?? ""
     );
-    ixs.push(freeStakeIx);
+    ixs.push(boostCreditsIx);
   }
 
   return sendTx(connection, wallet, ixs);
@@ -1624,7 +1662,7 @@ export async function approveRejectedTwitter(
 /**
  * Approve a tweet verification (verifier-only).
  * Awards tweet verify reward and points to the agent owner.
- * @param freeStakeDelta - If provided, also adjusts free stake credits for the agent owner in the same tx.
+ * @param boostCreditsDelta - If provided, also adjusts boost credits for the agent owner in the same tx.
  */
 export async function approveTweet(
   connection: Connection,
@@ -1632,8 +1670,8 @@ export async function approveTweet(
   agentId: string,
   tweetId: bigint,
   options?: AgentRegistryOptions,
-  freeStakeDelta?: number,
-  freeStakeReason?: string
+  boostCreditsDelta?: number,
+  boostCreditsReason?: string
 ): Promise<string> {
   const program = createProgram(connection, wallet, options?.programId);
   const agentPda = getAgentPda(program.programId, agentId);
@@ -1658,12 +1696,12 @@ export async function approveTweet(
     .instruction();
 
   const ixs = [ix];
-  if (freeStakeDelta !== undefined && freeStakeDelta !== 0) {
-    const { makeAdjustFreeStakeIx } = await import("./quest");
-    const freeStakeIx = await makeAdjustFreeStakeIx(
-      connection, wallet.publicKey, authority, freeStakeDelta, freeStakeReason ?? ""
+  if (boostCreditsDelta !== undefined && boostCreditsDelta !== 0) {
+    const { makeAdjustBoostCreditsIx } = await import("./quest");
+    const boostCreditsIx = await makeAdjustBoostCreditsIx(
+      connection, wallet.publicKey, authority, boostCreditsDelta, boostCreditsReason ?? ""
     );
-    ixs.push(freeStakeIx);
+    ixs.push(boostCreditsIx);
   }
 
   return sendTx(connection, wallet, ixs);

package/src/idls/nara_quest.json

@@ -761,6 +761,10 @@
         {
           "name": "max_reward_count",
           "type": "u32"
+        },
+        {
+          "name": "free_stake_multiplier",
+          "type": "u32"
         }
       ]
     },
@@ -1883,8 +1887,8 @@
     },
     {
       "code": 6017,
-      "name": "FreeCreditsOverflow",
-      "msg": "Free credits overflow"
+      "name": "BoostCreditsOverflow",
+      "msg": "Boost credits overflow"
     },
     {
       "code": 6018,
@@ -1910,6 +1914,16 @@
       "code": 6022,
       "name": "InsufficientAirdrop",
       "msg": "Airdrop fund has insufficient balance"
+    },
+    {
+      "code": 6023,
+      "name": "InvalidMultiplier",
+      "msg": "Multiplier must be >= 1"
+    },
+    {
+      "code": 6024,
+      "name": "NoCredits",
+      "msg": "Boost PoMI requires free credits"
     }
   ],
   "types": [
@@ -2006,12 +2020,16 @@
             "name": "max_airdrop_count",
             "type": "u32"
           },
+          {
+            "name": "free_stake_multiplier",
+            "type": "u32"
+          },
           {
             "name": "_padding",
             "type": {
               "array": [
                 "u8",
-                20
+                16
               ]
             }
           }
@@ -2049,15 +2067,15 @@
             "type": "u64"
           },
           {
-            "name": "reward_count",
+            "name": "stake_reward_count",
             "type": "u32"
           },
           {
-            "name": "reward_per_winner",
+            "name": "stake_reward_per_winner",
             "type": "u64"
           },
           {
-            "name": "winner_count",
+            "name": "stake_winner_count",
             "type": "u32"
           },
           {
@@ -2080,12 +2098,24 @@
             "name": "avg_participant_stake",
             "type": "u64"
           },
+          {
+            "name": "free_reward_count",
+            "type": "u32"
+          },
+          {
+            "name": "free_reward_per_winner",
+            "type": "u64"
+          },
+          {
+            "name": "free_winner_count",
+            "type": "u32"
+          },
           {
             "name": "_padding",
             "type": {
               "array": [
                 "u8",
-                64
+                48
               ]
             }
           }
@@ -2102,15 +2132,19 @@
             "type": "u64"
           },
           {
-            "name": "free_credits",
+            "name": "boost_credits",
             "type": "u32"
           },
+          {
+            "name": "user_pubkey",
+            "type": "pubkey"
+          },
           {
             "name": "_padding",
             "type": {
               "array": [
                 "u8",
-                60
+                28
               ]
             }
           }

package/src/idls/nara_quest.ts

@@ -767,6 +767,10 @@ export type NaraQuest = {
         {
           "name": "maxRewardCount",
           "type": "u32"
+        },
+        {
+          "name": "freeStakeMultiplier",
+          "type": "u32"
         }
       ]
     },
@@ -1889,8 +1893,8 @@ export type NaraQuest = {
     },
     {
       "code": 6017,
-      "name": "freeCreditsOverflow",
-      "msg": "Free credits overflow"
+      "name": "boostCreditsOverflow",
+      "msg": "Boost credits overflow"
     },
     {
       "code": 6018,
@@ -1916,6 +1920,16 @@ export type NaraQuest = {
       "code": 6022,
       "name": "insufficientAirdrop",
       "msg": "Airdrop fund has insufficient balance"
+    },
+    {
+      "code": 6023,
+      "name": "invalidMultiplier",
+      "msg": "Multiplier must be >= 1"
+    },
+    {
+      "code": 6024,
+      "name": "noCredits",
+      "msg": "Boost PoMI requires free credits"
     }
   ],
   "types": [
@@ -2012,12 +2026,16 @@ export type NaraQuest = {
             "name": "maxAirdropCount",
             "type": "u32"
           },
+          {
+            "name": "freeStakeMultiplier",
+            "type": "u32"
+          },
           {
             "name": "padding",
             "type": {
               "array": [
                 "u8",
-                20
+                16
               ]
             }
           }
@@ -2055,15 +2073,15 @@ export type NaraQuest = {
             "type": "u64"
           },
           {
-            "name": "rewardCount",
+            "name": "stakeRewardCount",
             "type": "u32"
           },
           {
-            "name": "rewardPerWinner",
+            "name": "stakeRewardPerWinner",
             "type": "u64"
           },
           {
-            "name": "winnerCount",
+            "name": "stakeWinnerCount",
             "type": "u32"
           },
           {
@@ -2086,12 +2104,24 @@ export type NaraQuest = {
             "name": "avgParticipantStake",
             "type": "u64"
           },
+          {
+            "name": "freeRewardCount",
+            "type": "u32"
+          },
+          {
+            "name": "freeRewardPerWinner",
+            "type": "u64"
+          },
+          {
+            "name": "freeWinnerCount",
+            "type": "u32"
+          },
           {
             "name": "padding",
             "type": {
               "array": [
                 "u8",
-                64
+                48
               ]
             }
           }
@@ -2108,15 +2138,19 @@ export type NaraQuest = {
             "type": "u64"
           },
           {
-            "name": "freeCredits",
+            "name": "boostCredits",
             "type": "u32"
           },
+          {
+            "name": "userPubkey",
+            "type": "pubkey"
+          },
           {
             "name": "padding",
             "type": {
               "array": [
                 "u8",
-                60
+                28
               ]
             }
           }

package/src/quest.ts

@@ -45,34 +45,42 @@ export interface QuestInfo {
   round: string;
   question: string;
   answerHash: number[];
-  rewardPerWinner: number;
+  /** Total reward pool for the round, in NARA */
   totalReward: number;
-  rewardCount: number;
-  winnerCount: number;
-  remainingSlots: number;
+  /**
+   * Boost PoMI winner bucket (single reward track).
+   * Named `stake*` for chain-field parity — the underlying pool fields are still
+   * `stake_reward_count` / `stake_reward_per_winner` / `stake_winner_count`.
+   */
+  stakeRewardCount: number;
+  stakeWinnerCount: number;
+  stakeRewardPerWinner: number;
+  stakeRemainingSlots: number;
   difficulty: number;
   deadline: number;
   timeRemaining: number;
   expired: boolean;
-  /** High stake requirement for the current round (in NARA, decays over time) */
+  /** @deprecated Legacy stake decay field. Staking channel is closed; value is informational only. */
   stakeHigh: number;
-  /** Low stake requirement for the current round (in NARA, floor after decay) */
+  /** @deprecated Legacy stake decay field. Staking channel is closed; value is informational only. */
   stakeLow: number;
-  /** Running average participant stake for the current round (in NARA) */
+  /** @deprecated Legacy field. Pool no longer accumulates avg participant stake. */
   avgParticipantStake: number;
   /** Unix timestamp when the current question was created */
   createdAt: number;
-  /** Current effective stake requirement after parabolic decay (in NARA) */
+  /** @deprecated Legacy stake requirement. Boost PoMI gates on boost credits, not stake. */
   effectiveStakeRequirement: number;
 }
 
 export interface StakeInfo {
-  /** Current staked amount (in NARA) */
+  /** Legacy staked amount (in NARA). Staking channel is closed; use `unstake` to withdraw. */
   amount: number;
-  /** Round when the stake was made */
+  /** Round when the stake was last touched */
   stakeRound: number;
-  /** Free stake credits (admin-assigned, bypass stake requirement) */
-  freeCredits: number;
+  /** Boost PoMI credits — required to submit an answer (consumed -1 per successful reward) */
+  boostCredits: number;
+  /** On-chain record of the user's pubkey (populated on stake / adjust / answer) */
+  userPubkey: string;
 }
 
 export interface ZkProof {
@@ -101,7 +109,12 @@ 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 */
+  /**
+   * @deprecated Boost PoMI no longer gates on stake; credits are the sole admission ticket.
+   * If set, a legacy `stake` instruction is still bundled before `submit_answer`:
+   *   - number: stake the exact NARA amount
+   *   - "auto": no-op (kept for API compatibility)
+   */
   stake?: "auto" | number;
 }
 
@@ -323,16 +336,19 @@ export async function getQuestInfo(
     stakeHigh, stakeLow, createdAtMs, decayMs, nowMs
   );
 
+  const stakeRewardCount = pool.stakeRewardCount;
+  const stakeWinnerCount = pool.stakeWinnerCount;
+
   return {
     active,
     round: pool.round.toString(),
     question: pool.question,
     answerHash: Array.from(pool.answerHash),
-    rewardPerWinner: pool.rewardPerWinner.toNumber() / LAMPORTS_PER_SOL,
     totalReward: pool.rewardAmount.toNumber() / LAMPORTS_PER_SOL,
-    rewardCount: pool.rewardCount,
-    winnerCount: pool.winnerCount,
-    remainingSlots: Math.max(0, pool.rewardCount - pool.winnerCount),
+    stakeRewardCount,
+    stakeWinnerCount,
+    stakeRewardPerWinner: pool.stakeRewardPerWinner.toNumber() / LAMPORTS_PER_SOL,
+    stakeRemainingSlots: Math.max(0, stakeRewardCount - stakeWinnerCount),
     difficulty: pool.difficulty,
     deadline,
     timeRemaining: secsLeft,
@@ -414,6 +430,12 @@ export async function generateProof(
 
 /**
  * Submit a quest answer on-chain (direct submission, requires gas).
+ *
+ * Boost PoMI: the caller must have at least 1 boost credit; on a successful
+ * reward, 1 credit is consumed. Without credits the on-chain program rejects
+ * with `NoCredits` (6024); this function pre-checks and throws early with a
+ * clearer message.
+ *
  * If `activityLog` is provided, a logActivity instruction from the Agent Registry
  * is appended to the same transaction.
  */
@@ -428,37 +450,22 @@ export async function submitAnswer(
 ): Promise<SubmitAnswerResult> {
   const program = createProgram(connection, wallet, options?.programId);
 
-  // Build optional stake instruction
+  // Boost PoMI: fail fast if the user has no credits
+  const stakeInfo = await getStakeInfo(connection, wallet.publicKey, options);
+  if (!stakeInfo || stakeInfo.boostCredits <= 0) {
+    throw new Error(
+      "Boost PoMI requires boost credits. Your balance is 0 — acquire credits before submitting an answer."
+    );
+  }
+
+  // Legacy optional stake instruction (staking channel is closed but still callable)
   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 freeCredits = stakeInfo?.freeCredits ?? 0;
-
-      if (freeCredits > 0) {
-        // 本轮使用免质押额度，不需要补质押
-        stakeLamports = new BN(0);
-      } else {
-        const required = quest.effectiveStakeRequirement;
-        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 (typeof options?.stake === "number" && options.stake > 0) {
+    const stakeLamports = new BN(Math.round(options.stake * LAMPORTS_PER_SOL));
+    stakeIx = await program.methods
+      .stake(stakeLamports)
+      .accounts({ user: wallet.publicKey } as any)
+      .instruction();
   }
 
   const submitIx = await program.methods
@@ -565,12 +572,19 @@ export async function parseQuestReward(
   let winner = "";
   const logs: string[] = txInfo.meta?.logMessages ?? [];
   for (const log of logs) {
-    const m = log.match(/reward (\d+) lamports \(winner (\d+\/\d+)\)/);
+    // Boost PoMI success:       "Boost PoMI reward N lamports (winner W/T, credits remaining: R)"
+    // Vault-insufficient notice: "Answer verified but vault insufficient (winner W/T, credit preserved)"
+    const m = log.match(/reward (\d+) lamports \(winner (\d+\/\d+)/);
     if (m) {
       rewardLamports = parseInt(m[1]!);
       winner = m[2]!;
       break;
     }
+    const v = log.match(/vault insufficient \(winner (\d+\/\d+)/);
+    if (v) {
+      winner = v[1]!;
+      // rewardLamports stays 0
+    }
   }
 
   return {
@@ -677,7 +691,8 @@ export async function getStakeInfo(
   return {
     amount,
     stakeRound: record.stakeRound.toNumber(),
-    freeCredits: record.freeCredits,
+    boostCredits: record.boostCredits,
+    userPubkey: record.userPubkey.toBase58(),
   };
 }
 
@@ -758,17 +773,22 @@ export async function initializeQuest(
 
 /**
  * Set the reward config (authority only).
+ *
+ * @param freeStakeMultiplier - Legacy field (>= 1). Currently unused by Boost PoMI
+ *                              reward calculation; defaults to 1. Kept exposed in
+ *                              case chain re-enables it.
  */
 export async function setRewardConfig(
   connection: Connection,
   wallet: Keypair,
   minRewardCount: number,
   maxRewardCount: number,
+  freeStakeMultiplier: number = 1,
   options?: QuestOptions
 ): Promise<string> {
   const program = createProgram(connection, wallet, options?.programId);
   const ix = await program.methods
-    .setRewardConfig(minRewardCount, maxRewardCount)
+    .setRewardConfig(minRewardCount, maxRewardCount, freeStakeMultiplier)
     .accounts({ authority: wallet.publicKey } as any)
     .instruction();
   return sendTx(connection, wallet, [ix]);
@@ -933,9 +953,10 @@ export async function setStakeAuthority(
 }
 
 /**
- * Build an adjustFreeStake instruction without sending it.
+ * Build an adjustBoostCredits instruction without sending it.
+ * (Wraps the on-chain `adjustFreeStake` instruction — legacy chain-side name.)
  */
-export async function makeAdjustFreeStakeIx(
+export async function makeAdjustBoostCreditsIx(
   connection: Connection,
   caller: PublicKey,
   user: PublicKey,
@@ -951,12 +972,12 @@ export async function makeAdjustFreeStakeIx(
 }
 
 /**
- * Adjust free stake credits for a user (stake_authority or authority only).
- * @param user - The user whose free credits to adjust
+ * Adjust boost credits for a user (stake_authority or authority only).
+ * @param user - The user whose boost credits to adjust
  * @param delta - Amount to adjust (positive to add, negative to remove)
  * @param reason - Reason for the adjustment (logged on-chain)
  */
-export async function adjustFreeStake(
+export async function adjustBoostCredits(
   connection: Connection,
   wallet: Keypair,
   user: PublicKey,
@@ -964,7 +985,7 @@ export async function adjustFreeStake(
   reason: string,
   options?: QuestOptions
 ): Promise<string> {
-  const ix = await makeAdjustFreeStakeIx(connection, wallet.publicKey, user, delta, reason, options);
+  const ix = await makeAdjustBoostCreditsIx(connection, wallet.publicKey, user, delta, reason, options);
   return sendTx(connection, wallet, [ix]);
 }