@soltracer/nft-staking 0.2.8 → 0.3.0

package/dist/idl.json

@@ -6193,7 +6193,7 @@
         {
             "name": "sync_stake_entry_secondary",
             "docs": [
-                "STAKE-FRESH-2026-05-11 (F-H4): re-sync one StakeEntry's contribution to",
+                "re-sync one StakeEntry's contribution to",
                 "`pool_secondary.rewards[secondary_index]`. Permissionless. Lets",
                 "existing stakers begin accruing on a secondary that was added",
                 "post-stake (or pick up a rate-update) without unstaking."
@@ -9025,7 +9025,7 @@
                     {
                         "name": "retired_at",
                         "docs": [
-                            "STAKE-FRESH-2026-05-11 (F-H3): unix timestamp at which the slot was",
+                            "unix timestamp at which the slot was",
                             "retired. `0` while active. Used by `accrue_secondary` /",
                             "`accrue_and_sub_secondary` to cap per-staker accrual at the moment of",
                             "retirement so the time window between a staker's last interaction and",
@@ -9131,7 +9131,7 @@
                     {
                         "name": "early_unstake_penalty_bps",
                         "docs": [
-                            "STAKE2-M3 (audit 2026-05-05): early-unstake penalty (bps) captured at",
+                            "early-unstake penalty (bps) captured at",
                             "stake time. Read at unstake instead of `pool.lock_configs[tier].early_unstake_penalty_bps`",
                             "so the authority cannot retroactively raise the penalty after the",
                             "staker has committed. Zero when the entry has no lock."
@@ -9144,7 +9144,7 @@
         {
             "name": "StakeEntrySecondarySynced",
             "docs": [
-                "STAKE-FRESH-2026-05-11 (F-H4): emitted when a StakeEntry's",
+                "emitted when a StakeEntry's",
                 "secondary_rate_contributions[index] is re-synced to the pool's current",
                 "config (e.g. after an admin added a new secondary slot post-stake)."
             ],
@@ -9309,7 +9309,7 @@
                     {
                         "name": "total_effective_rate",
                         "docs": [
-                            "STAKE-FRESH-2026-05-11 (F-H1): aggregate of every active staker's",
+                            "aggregate of every active staker's",
                             "`effective_rate`. Maintained at every stake/unstake/burn site.",
                             "Used by [`pool_settle`] to advance obligation for stakers who have",
                             "not yet visited the pool since `last_pool_accrual_ts`."
@@ -9319,7 +9319,7 @@
                     {
                         "name": "last_pool_accrual_ts",
                         "docs": [
-                            "STAKE-FRESH-2026-05-11 (F-H1): unix timestamp at which the pool's",
+                            "unix timestamp at which the pool's",
                             "total obligation was last advanced. Bumped by every handler that",
                             "touches the pool (via [`pool_settle`])."
                         ],

package/dist/index.d.ts

@@ -4,6 +4,6 @@ export { type NftStaking as NftStakingIDLType } from "./idl";
 export { default as NftStakingIDL } from "./idl.json";
 export * from "./errors";
 export * from "./helpers";
-export { buildTraitProofMessage, TRAIT_PROOF_MSG_LEN, aggregateTraitBonusRate } from "./traitProof";
+export { buildTraitProofMessage, TRAIT_PROOF_MSG_LEN, aggregateTraitBonusRate, computeTraitBonusRate, type TraitBonusCatalogEntry, type NftTraitInput, type ComputeTraitBonusResult, } from "./traitProof";
 export { GATE_TYPE_NONE, GATE_TYPE_WALLET, GATE_TYPE_TOKEN_MINT, type GateType, type MerkleTree, hashLeaf, hashPair, buildMerkleTree, getMerkleProof, proofToAnchorArg, rootToAnchorArg, } from "./merkle";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,UAAU,CAAA;AACjB,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,0BAA0B,EAC1B,4BAA4B,EAC5B,WAAW,EACX,WAAW,EACX,UAAU,EACV,cAAc,GACf,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,KAAK,UAAU,IAAI,iBAAiB,EAAE,MAAM,OAAO,CAAA;AAC5D,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,YAAY,CAAA;AACrD,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA;AACzB,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AACnG,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,eAAe,GAChB,MAAM,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,UAAU,CAAA;AACjB,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,0BAA0B,EAC1B,4BAA4B,EAC5B,WAAW,EACX,WAAW,EACX,UAAU,EACV,cAAc,GACf,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,KAAK,UAAU,IAAI,iBAAiB,EAAE,MAAM,OAAO,CAAA;AAC5D,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,YAAY,CAAA;AACrD,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA;AACzB,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,uBAAuB,GAC7B,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,eAAe,GAChB,MAAM,UAAU,CAAA"}

package/dist/index.js

@@ -3,6 +3,6 @@ export { NFT_STAKING_PROGRAM_ID, getStakeConfigPda, getStakePoolPda, getStakeEnt
 export { default as NftStakingIDL } from "./idl.json";
 export * from "./errors";
 export * from "./helpers";
-export { buildTraitProofMessage, TRAIT_PROOF_MSG_LEN, aggregateTraitBonusRate } from "./traitProof";
+export { buildTraitProofMessage, TRAIT_PROOF_MSG_LEN, aggregateTraitBonusRate, computeTraitBonusRate, } from "./traitProof";
 export { GATE_TYPE_NONE, GATE_TYPE_WALLET, GATE_TYPE_TOKEN_MINT, hashLeaf, hashPair, buildMerkleTree, getMerkleProof, proofToAnchorArg, rootToAnchorArg, } from "./merkle";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,GAKjB,MAAM,UAAU,CAAA;AACjB,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,0BAA0B,EAC1B,4BAA4B,EAC5B,WAAW,EACX,WAAW,EACX,UAAU,EACV,cAAc,GACf,MAAM,iBAAiB,CAAA;AAExB,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,YAAY,CAAA;AACrD,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA;AACzB,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AACnG,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EAGpB,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,eAAe,GAChB,MAAM,UAAU,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,GAKjB,MAAM,UAAU,CAAA;AACjB,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,0BAA0B,EAC1B,4BAA4B,EAC5B,WAAW,EACX,WAAW,EACX,UAAU,EACV,cAAc,GACf,MAAM,iBAAiB,CAAA;AAExB,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,YAAY,CAAA;AACrD,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA;AACzB,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,GAItB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EAGpB,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,eAAe,GAChB,MAAM,UAAU,CAAA"}

package/dist/traitProof.d.ts

@@ -1,10 +1,9 @@
 /**
  * Trait-bonus proof builder for NFT-staking `claim_rewards`.
  *
- * Audit 2026-05-11 F-H2: the on-chain Ed25519 message embeds
- * `staker.total_claimed` (strictly monotonic) instead of `last_update_at`,
- * eliminating same-second replay. Callers MUST read the live
- * `StakerAccount.totalClaimed` immediately before signing.
+ * The on-chain Ed25519 message embeds `staker.total_claimed` (a strictly
+ * monotonic nonce). Callers MUST read the live `StakerAccount.totalClaimed`
+ * immediately before signing.
  *
  * Message layout — 80 bytes, little-endian where applicable:
  *
@@ -64,35 +63,94 @@ export declare function buildTraitProofMessage(params: {
  * The on-chain `claim_rewards` instruction accepts a **single** `u64`
  * `traitBonusRate` per claim — the chain knows nothing about per-trait
  * granularity. Aggregation across N staked NFTs (each with M traits) is the
- * caller's responsibility, and the math depends on the pool's
- * `rewardConfig.traitBonusMode`:
+ * trait-authority server's responsibility.
  *
- * - `0` / `None` — proofs disabled. Any non-zero rate is rejected.
- * - `1` / `FixedExtra` — `traitBonusRate` is **absolute extra reward per
- *   `rateInterval`** added to the staker's effective rate for the claim
- *   accrual window. Sum per-trait fixed bonuses across every active staked
- *   NFT (and every bonus-bearing trait on each).
- * - `2` / `BaseMultiplier` — `traitBonusRate` is **bonus BPS** applied to the
- *   staker's CURRENT `effective_rate` (already includes lock-tier rates).
- *   `10_000` = +100% (2x base for the window). Sum per-trait BPS bonuses the
- *   same way — the bonus is a scalar over the whole staker rate.
+ * Intended backend flow:
  *
- * `bonusBps` and `fixedExtra` fields are mutually exclusive; mixing both in
- * one trait entry throws. Traits without bonuses can be omitted.
+ *   1. Client sends `{ wallet, poolId, mints: [..] }` to your API.
+ *   2. API validates `mints` are currently staked by `wallet` in `pool`
+ *      (e.g. via `fetchStakeEntriesByOwner`) and DROPS any it cannot prove.
+ *   3. API resolves each surviving NFT's trait list from its own metadata
+ *      source (off-chain JSON, on-chain metaplex data, indexer, etc.).
+ *   4. API looks up each `(traitType, value)` pair in the project's bonus
+ *      catalog. Unmatched traits contribute nothing.
+ *   5. API sums the matched bonuses according to the pool's
+ *      `rewardConfig.traitBonusMode` and signs the resulting `u64`.
+ *
+ * Modes:
+ *
+ * - `0` / `None` — proofs disabled. Always returns `0n`.
+ * - `1` / `FixedExtra` — bonuses are **absolute reward per `rateInterval`**.
+ *   Summed and added on top of the staker's effective rate for the accrual
+ *   window. Catalog entries MUST use `fixedExtra`.
+ * - `2` / `BaseMultiplier` — bonuses are **BPS over the staker's current
+ *   `effective_rate`** (which already includes lock-tier rates). `10_000`
+ *   means +100% (2x base). Summed BPS apply once to the staker rate.
+ *   Catalog entries MUST use `bonusBps`.
+ *
+ * Catalog entries with both `bonusBps` and `fixedExtra` set, or with the wrong
+ * field for the active mode, are rejected. Mints can repeat the same trait
+ * type/value — each NFT contributes independently.
+ *
+ * @returns `{ traitBonusRate, perNft }` where `perNft` is the per-mint
+ * breakdown (useful for receipts, debugging, or surfacing a tooltip in the UI).
  *
  * @example
  * ```ts
- * // Pool is in BaseMultiplier mode. Each staked NFT exposes its trait list.
- * const traits = [
- *   // NFT 1 — "Gold" head (+5%), "Laser Eyes" (+10%)
- *   { bonusBps: 500 }, { bonusBps: 1000 },
- *   // NFT 2 — "Mythic Background" (+25%)
- *   { bonusBps: 2500 },
- * ]
- * const rate = aggregateTraitBonusRate(traits, 2) // → 4000 (i.e. +40% for the window)
- * const message = buildTraitProofMessage({ pool, wallet, traitBonusRate: rate, totalClaimed })
+ * // Backend after ownership validation:
+ * const result = computeTraitBonusRate({
+ *   traitBonusMode: pool.rewardConfig.traitBonusMode as 0 | 1 | 2,
+ *   catalog: [
+ *     { traitType: "Background", value: "Mythic",     bonusBps: 2500 },
+ *     { traitType: "Eyes",       value: "Laser",      bonusBps: 1000 },
+ *     { traitType: "Head",       value: "Gold Crown", bonusBps:  500 },
+ *   ],
+ *   nfts: validatedStakedNfts, // [{ mint, traits: [{ traitType, value }] }, ..]
+ * })
+ *
+ * const message = buildTraitProofMessage({
+ *   pool, wallet,
+ *   traitBonusRate: result.traitBonusRate,
+ *   totalClaimed: stakerAccount.totalClaimed,
+ * })
  * ```
  */
+export type TraitBonusCatalogEntry = {
+    traitType: string;
+    value: string;
+    /** Bonus BPS — required when `traitBonusMode === 2` (BaseMultiplier). */
+    bonusBps?: number | bigint;
+    /** Extra reward per `rateInterval` — required when `traitBonusMode === 1` (FixedExtra). */
+    fixedExtra?: number | bigint;
+};
+export type NftTraitInput = {
+    mint: PkInput | string;
+    /** Ordered or unordered list of an NFT's traits, after ownership validation. */
+    traits: ReadonlyArray<{
+        traitType: string;
+        value: string;
+    }>;
+};
+export type ComputeTraitBonusResult = {
+    /** Aggregated u64 rate to sign and include in the claim. */
+    traitBonusRate: bigint;
+    /** Per-NFT breakdown (mint → total bonus contributed + matched-trait count). */
+    perNft: Array<{
+        mint: string;
+        bonus: bigint;
+        matchedTraits: number;
+    }>;
+};
+export declare function computeTraitBonusRate(params: {
+    traitBonusMode: 0 | 1 | 2;
+    catalog: ReadonlyArray<TraitBonusCatalogEntry>;
+    nfts: ReadonlyArray<NftTraitInput>;
+}): ComputeTraitBonusResult;
+/**
+ * @deprecated Use `computeTraitBonusRate` instead — it accepts the real per-NFT
+ * trait input and a bonus catalog, mirroring the backend flow. Retained for
+ * call sites that already pre-resolved a flat bonus array.
+ */
 export declare function aggregateTraitBonusRate(traits: ReadonlyArray<{
     bonusBps?: number | bigint;
     fixedExtra?: number | bigint;

package/dist/traitProof.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"traitProof.d.ts","sourceRoot":"","sources":["../src/traitProof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAQ,KAAK,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAElE,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,KAAK,CAAA;AAcrC;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,IAAI,EAAE,OAAO,CAAA;IACb,MAAM,EAAE,OAAO,CAAA;IACf,cAAc,EAAE,OAAO,CAAA;IACvB,8DAA8D;IAC9D,YAAY,EAAE,OAAO,CAAA;CACtB,GAAG,MAAM,CAOT;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAC,EACnF,cAAc,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GACxB,MAAM,CAqCR"}
+{"version":3,"file":"traitProof.d.ts","sourceRoot":"","sources":["../src/traitProof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAQ,KAAK,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAElE,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,KAAK,CAAA;AAcrC;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,IAAI,EAAE,OAAO,CAAA;IACb,MAAM,EAAE,OAAO,CAAA;IACf,cAAc,EAAE,OAAO,CAAA;IACvB,8DAA8D;IAC9D,YAAY,EAAE,OAAO,CAAA;CACtB,GAAG,MAAM,CAOT;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,MAAM,MAAM,sBAAsB,GAAG;IACnC,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAC1B,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAC7B,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,OAAO,GAAG,MAAM,CAAA;IACtB,gFAAgF;IAChF,MAAM,EAAE,aAAa,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC5D,CAAA;AAED,MAAM,MAAM,uBAAuB,GAAG;IACpC,4DAA4D;IAC5D,cAAc,EAAE,MAAM,CAAA;IACtB,gFAAgF;IAChF,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACtE,CAAA;AAiCD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,cAAc,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACzB,OAAO,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAA;IAC9C,IAAI,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;CACnC,GAAG,uBAAuB,CAuC1B;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAC,EACnF,cAAc,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GACxB,MAAM,CAmCR"}

package/dist/traitProof.js

@@ -1,10 +1,9 @@
 /**
  * Trait-bonus proof builder for NFT-staking `claim_rewards`.
  *
- * Audit 2026-05-11 F-H2: the on-chain Ed25519 message embeds
- * `staker.total_claimed` (strictly monotonic) instead of `last_update_at`,
- * eliminating same-second replay. Callers MUST read the live
- * `StakerAccount.totalClaimed` immediately before signing.
+ * The on-chain Ed25519 message embeds `staker.total_claimed` (a strictly
+ * monotonic nonce). Callers MUST read the live `StakerAccount.totalClaimed`
+ * immediately before signing.
  *
  * Message layout — 80 bytes, little-endian where applicable:
  *
@@ -45,64 +44,67 @@ export function buildTraitProofMessage(params) {
     u64LE(params.totalClaimed).copy(msg, 72);
     return msg;
 }
+function normalizeKey(s) {
+    return s.trim().toLowerCase();
+}
+function bonusFromCatalogEntry(entry, traitBonusMode) {
+    const bps = BigInt(entry.bonusBps ?? 0);
+    const extra = BigInt(entry.fixedExtra ?? 0);
+    if (bps !== 0n && extra !== 0n) {
+        throw new Error(`computeTraitBonusRate: catalog entry "${entry.traitType}=${entry.value}" sets both bonusBps and fixedExtra; pick one.`);
+    }
+    if (traitBonusMode === 1) {
+        if (bps !== 0n) {
+            throw new Error(`computeTraitBonusRate: traitBonusMode = FixedExtra but catalog entry "${entry.traitType}=${entry.value}" uses bonusBps. Use fixedExtra (raw reward per interval).`);
+        }
+        return extra;
+    }
+    if (extra !== 0n) {
+        throw new Error(`computeTraitBonusRate: traitBonusMode = BaseMultiplier but catalog entry "${entry.traitType}=${entry.value}" uses fixedExtra. Use bonusBps (10_000 = +100%).`);
+    }
+    return bps;
+}
+export function computeTraitBonusRate(params) {
+    if (params.traitBonusMode === 0) {
+        return { traitBonusRate: 0n, perNft: [] };
+    }
+    const mode = params.traitBonusMode;
+    // Build a lookup keyed by normalized "type::value".
+    // Validates every catalog entry up-front so misconfigured entries are
+    // surfaced even if no NFT references them.
+    const lookup = new Map();
+    for (const entry of params.catalog) {
+        const key = `${normalizeKey(entry.traitType)}::${normalizeKey(entry.value)}`;
+        if (lookup.has(key)) {
+            throw new Error(`computeTraitBonusRate: duplicate catalog entry for "${entry.traitType}=${entry.value}".`);
+        }
+        lookup.set(key, bonusFromCatalogEntry(entry, mode));
+    }
+    let total = 0n;
+    const perNft = [];
+    for (const nft of params.nfts) {
+        let nftBonus = 0n;
+        let matched = 0;
+        for (const trait of nft.traits) {
+            const hit = lookup.get(`${normalizeKey(trait.traitType)}::${normalizeKey(trait.value)}`);
+            if (hit === undefined || hit === 0n)
+                continue;
+            nftBonus += hit;
+            matched += 1;
+        }
+        total += nftBonus;
+        perNft.push({
+            mint: typeof nft.mint === "string" ? nft.mint : toPk(nft.mint).toBase58(),
+            bonus: nftBonus,
+            matchedTraits: matched,
+        });
+    }
+    return { traitBonusRate: total, perNft };
+}
 /**
- * Example (off-chain trait-authority server):
- *
- * ```ts
- * import nacl from "tweetnacl"
- * import { Ed25519Program } from "@solana/web3.js"
- * import { buildTraitProofMessage } from "@soltracer/nft-staking"
- *
- * const message = buildTraitProofMessage({
- *   pool,
- *   wallet: staker,
- *   traitBonusRate,
- *   totalClaimed: stakerAccount.totalClaimed,
- * })
- * const signature = nacl.sign.detached(message, traitAuthority.secretKey)
- * const ed25519Ix = Ed25519Program.createInstructionWithPublicKey({
- *   publicKey: traitAuthority.publicKey.toBytes(),
- *   message,
- *   signature,
- * })
- * const claimIx = await client.claimRewards(poolId, { traitBonusRate })
- * await provider.sendAndConfirm(new Transaction().add(ed25519Ix, claimIx))
- * ```
- */
-/**
- * Mode-aware trait-bonus rate aggregator.
- *
- * The on-chain `claim_rewards` instruction accepts a **single** `u64`
- * `traitBonusRate` per claim — the chain knows nothing about per-trait
- * granularity. Aggregation across N staked NFTs (each with M traits) is the
- * caller's responsibility, and the math depends on the pool's
- * `rewardConfig.traitBonusMode`:
- *
- * - `0` / `None` — proofs disabled. Any non-zero rate is rejected.
- * - `1` / `FixedExtra` — `traitBonusRate` is **absolute extra reward per
- *   `rateInterval`** added to the staker's effective rate for the claim
- *   accrual window. Sum per-trait fixed bonuses across every active staked
- *   NFT (and every bonus-bearing trait on each).
- * - `2` / `BaseMultiplier` — `traitBonusRate` is **bonus BPS** applied to the
- *   staker's CURRENT `effective_rate` (already includes lock-tier rates).
- *   `10_000` = +100% (2x base for the window). Sum per-trait BPS bonuses the
- *   same way — the bonus is a scalar over the whole staker rate.
- *
- * `bonusBps` and `fixedExtra` fields are mutually exclusive; mixing both in
- * one trait entry throws. Traits without bonuses can be omitted.
- *
- * @example
- * ```ts
- * // Pool is in BaseMultiplier mode. Each staked NFT exposes its trait list.
- * const traits = [
- *   // NFT 1 — "Gold" head (+5%), "Laser Eyes" (+10%)
- *   { bonusBps: 500 }, { bonusBps: 1000 },
- *   // NFT 2 — "Mythic Background" (+25%)
- *   { bonusBps: 2500 },
- * ]
- * const rate = aggregateTraitBonusRate(traits, 2) // → 4000 (i.e. +40% for the window)
- * const message = buildTraitProofMessage({ pool, wallet, traitBonusRate: rate, totalClaimed })
- * ```
+ * @deprecated Use `computeTraitBonusRate` instead — it accepts the real per-NFT
+ * trait input and a bonus catalog, mirroring the backend flow. Retained for
+ * call sites that already pre-resolved a flat bonus array.
  */
 export function aggregateTraitBonusRate(traits, traitBonusMode) {
     if (traitBonusMode === 0) {
@@ -119,14 +121,12 @@ export function aggregateTraitBonusRate(traits, traitBonusMode) {
             throw new Error("aggregateTraitBonusRate: a single trait must set bonusBps OR fixedExtra, not both.");
         }
         if (traitBonusMode === 1) {
-            // FixedExtra — sum absolute per-interval bonuses.
             if (bps !== 0n) {
                 throw new Error("aggregateTraitBonusRate: traitBonusMode = FixedExtra expects fixedExtra (per-interval reward), not bonusBps.");
             }
             sum += extra;
         }
         else {
-            // BaseMultiplier — sum BPS bonuses.
             if (extra !== 0n) {
                 throw new Error("aggregateTraitBonusRate: traitBonusMode = BaseMultiplier expects bonusBps (10_000 = +100%), not fixedExtra.");
             }

package/dist/traitProof.js.map

@@ -1 +1 @@
-{"version":3,"file":"traitProof.js","sourceRoot":"","sources":["../src/traitProof.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"traitProof.js","sourceRoot":"","sources":["../src/traitProof.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soltracer/nft-staking",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",