@soltracer/nft-staking 0.3.0 → 0.4.0

package/dist/idl.json

@@ -1565,7 +1565,7 @@
                 {
                     "name": "stake_config",
                     "docs": [
-                        "Global stake config \u2014 holds the platform's default trait authority."
+                        "Global stake config — holds the platform's default trait authority."
                     ],
                     "pda": {
                         "seeds": [
@@ -2638,7 +2638,7 @@
                 {
                     "name": "reward_vault",
                     "docs": [
-                        "Reward vault \u2014 required for token-reward pools. Must be drained before closure.",
+                        "Reward vault — required for token-reward pools. Must be drained before closure.",
                         "Pass the pool_authority ATA for the reward mint. Omit for SOL-reward pools."
                     ],
                     "optional": true
@@ -2851,14 +2851,14 @@
                 {
                     "name": "reward_mint",
                     "docs": [
-                        "Reward mint \u2014 the token paid out as rewards (can be any SPL token).",
+                        "Reward mint — the token paid out as rewards (can be any SPL token).",
                         "Ignored if reward_type == Points."
                     ]
                 },
                 {
                     "name": "reward_vault",
                     "docs": [
-                        "Reward vault ATA owned by pool_authority \u2014 created for token rewards."
+                        "Reward vault ATA owned by pool_authority — created for token rewards."
                     ],
                     "writable": true,
                     "pda": {
@@ -6193,7 +6193,7 @@
         {
             "name": "sync_stake_entry_secondary",
             "docs": [
-                "re-sync one StakeEntry's contribution to",
+                "STAKE-FRESH-2026-05-11 (F-H4): 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."
@@ -6383,7 +6383,7 @@
                 {
                     "name": "payer",
                     "docs": [
-                        "Permissionless \u2014 anyone may invoke. Pays no tx fee beyond signer",
+                        "Permissionless — anyone may invoke. Pays no tx fee beyond signer",
                         "requirement and does not need to match the staker."
                     ],
                     "signer": true
@@ -7310,7 +7310,7 @@
                 {
                     "name": "staker_nft_account",
                     "docs": [
-                        "User's NFT token account \u2014 destination for unstaked NFT."
+                        "User's NFT token account — destination for unstaked NFT."
                     ],
                     "writable": true
                 },
@@ -8602,7 +8602,7 @@
         {
             "code": 6038,
             "name": "UtilityNotActive",
-            "msg": "Utility is not active for this project \u2014 check subscription status"
+            "msg": "Utility is not active for this project — check subscription status"
         },
         {
             "code": 6039,
@@ -8636,56 +8636,61 @@
         },
         {
             "code": 6045,
+            "name": "PoolStillActive",
+            "msg": "Pool must be deactivated (is_active = false) before it can be closed"
+        },
+        {
+            "code": 6046,
             "name": "SecondaryRewardRetired",
             "msg": "Secondary reward is retired and cannot be modified"
         },
         {
-            "code": 6046,
+            "code": 6047,
             "name": "SecondaryRewardAlreadyRetired",
             "msg": "Secondary reward is already retired"
         },
         {
-            "code": 6047,
+            "code": 6048,
             "name": "SecondaryRewardMintImmutable",
-            "msg": "Secondary reward mint is immutable \u2014 retire and add a new slot instead"
+            "msg": "Secondary reward mint is immutable — retire and add a new slot instead"
         },
         {
-            "code": 6048,
+            "code": 6049,
             "name": "ClaimLockedUntilExpiry",
-            "msg": "Mid-lock claims are disabled for this tier \u2014 rewards are paid out at unstake"
+            "msg": "Mid-lock claims are disabled for this tier — rewards are paid out at unstake"
         },
         {
-            "code": 6049,
+            "code": 6050,
             "name": "StakerMismatch",
             "msg": "Caller is not the staker for this entry"
         },
         {
-            "code": 6050,
+            "code": 6051,
             "name": "LockTierConfigMissing",
             "msg": "Lock tier config missing - pool was reconfigured with active entries"
         },
         {
-            "code": 6051,
+            "code": 6052,
             "name": "NftAlreadyStaked",
             "msg": "NFT is already staked"
         },
         {
-            "code": 6052,
+            "code": 6053,
             "name": "UserBanned",
             "msg": "User profile is banned"
         },
         {
-            "code": 6053,
+            "code": 6054,
             "name": "UserProfileMismatch",
             "msg": "User profile does not match staker"
         },
         {
-            "code": 6054,
+            "code": 6055,
             "name": "InvalidQuantityBonus",
             "msg": "Invalid quantity bonus configuration"
         },
         {
-            "code": 6055,
+            "code": 6056,
             "name": "BaseStakingDisabled",
             "msg": "Unlocked/base staking is disabled for this pool"
         }
@@ -8758,7 +8763,7 @@
                     {
                         "name": "claim_only_at_end",
                         "docs": [
-                            "If true, mid-lock claims are blocked \u2014 rewards are only accessible at unstake.",
+                            "If true, mid-lock claims are blocked — rewards are only accessible at unstake.",
                             "Ensures the early-unstake penalty cannot be bypassed by claiming before unstaking."
                         ],
                         "type": "bool"
@@ -8854,7 +8859,7 @@
             "name": "PoolSecondaryRewards",
             "docs": [
                 "Separate PDA holding secondary reward configs for a pool.",
-                "Exists only when the pool has secondary rewards \u2014 zero migration needed."
+                "Exists only when the pool has secondary rewards — zero migration needed."
             ],
             "type": {
                 "kind": "struct",
@@ -8876,7 +8881,7 @@
                     {
                         "name": "is_initialized",
                         "docs": [
-                            "Explicit init sentinel \u2014 avoids ambiguous pool_id == 0 check for pool 0 (STAKE-H1)"
+                            "Explicit init sentinel — avoids ambiguous pool_id == 0 check for pool 0 (STAKE-H1)"
                         ],
                         "type": "bool"
                     },
@@ -8937,12 +8942,16 @@
                         "type": "i64"
                     },
                     {
-                        "name": "trait_bonus_mode",
+                        "name": "trait_bonus_enabled",
                         "docs": [
-                            "How trait bonuses are applied at claim time (None / FixedExtra / BaseMultiplier).",
-                            "Trait config is stored off-chain; only the mode is on-chain."
+                            "When `true`, the pool accepts a signed `trait_bonus_rate` from the",
+                            "configured trait authority on every claim. The signed `u64` is added",
+                            "directly to the staker's effective rate for the accrual window —",
+                            "projects compute per-trait math (including any per-NFT multipliers)",
+                            "off-chain and sign the final absolute extra rate. When `false`, any",
+                            "non-zero `trait_bonus_rate` is rejected on-chain."
                         ],
-                        "type": "u8"
+                        "type": "bool"
                     },
                     {
                         "name": "quantity_thresholds",
@@ -9025,7 +9034,7 @@
                     {
                         "name": "retired_at",
                         "docs": [
-                            "unix timestamp at which the slot was",
+                            "STAKE-FRESH-2026-05-11 (F-H3): 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",
@@ -9068,7 +9077,7 @@
         {
             "name": "StakeEntry",
             "docs": [
-                "Per-NFT custody and lock tracking. No reward fields \u2014 rewards are",
+                "Per-NFT custody and lock tracking. No reward fields — rewards are",
                 "accumulated on the parent StakerAccount via `effective_rate`."
             ],
             "type": {
@@ -9131,7 +9140,7 @@
                     {
                         "name": "early_unstake_penalty_bps",
                         "docs": [
-                            "early-unstake penalty (bps) captured at",
+                            "STAKE2-M3 (audit 2026-05-05): 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 +9153,7 @@
         {
             "name": "StakeEntrySecondarySynced",
             "docs": [
-                "emitted when a StakeEntry's",
+                "STAKE-FRESH-2026-05-11 (F-H4): 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 +9318,7 @@
                     {
                         "name": "total_effective_rate",
                         "docs": [
-                            "aggregate of every active staker's",
+                            "STAKE-FRESH-2026-05-11 (F-H1): 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 +9328,7 @@
                     {
                         "name": "last_pool_accrual_ts",
                         "docs": [
-                            "unix timestamp at which the pool's",
+                            "STAKE-FRESH-2026-05-11 (F-H1): 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

@@ -1,9 +1,9 @@
 export { NftStakingClient, type FeeParams, type NftRewardAmount, type NftRewardSummary, type NftRewardSummaryOptions, } from "./client";
-export { NFT_STAKING_PROGRAM_ID, getStakeConfigPda, getStakePoolPda, getStakeEntryPda, getStakerAccountPda, getCollectionPda, getPoolAuthorityPda, getPoolSecondaryRewardsPda, getStakerSecondaryRewardsPda, StakingMode, NftStandard, RewardType, TraitBonusMode, } from "@soltracer/core";
+export { NFT_STAKING_PROGRAM_ID, getStakeConfigPda, getStakePoolPda, getStakeEntryPda, getStakerAccountPda, getCollectionPda, getPoolAuthorityPda, getPoolSecondaryRewardsPda, getStakerSecondaryRewardsPda, StakingMode, NftStandard, RewardType, } from "@soltracer/core";
 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, computeTraitBonusRate, type TraitBonusCatalogEntry, type NftTraitInput, type ComputeTraitBonusResult, } from "./traitProof";
+export { buildTraitProofMessage, TRAIT_PROOF_MSG_LEN, computeTraitBonusRate, prepareTraitProof, ownershipFromClient, InMemoryTraitBonusStore, type TraitBonusCatalogEntry, type NftTraitInput, type PerNftBonus, type TraitBonusComputation, type TraitBonusStore, type NftTraitResolver, type StakedOwnershipResolver, type PrepareTraitProofInput, type PrepareTraitProofResult, } 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,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"}
+{"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,GACX,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,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,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

@@ -1,8 +1,8 @@
 export { NftStakingClient, } from "./client";
-export { NFT_STAKING_PROGRAM_ID, getStakeConfigPda, getStakePoolPda, getStakeEntryPda, getStakerAccountPda, getCollectionPda, getPoolAuthorityPda, getPoolSecondaryRewardsPda, getStakerSecondaryRewardsPda, StakingMode, NftStandard, RewardType, TraitBonusMode, } from "@soltracer/core";
+export { NFT_STAKING_PROGRAM_ID, getStakeConfigPda, getStakePoolPda, getStakeEntryPda, getStakerAccountPda, getCollectionPda, getPoolAuthorityPda, getPoolSecondaryRewardsPda, getStakerSecondaryRewardsPda, StakingMode, NftStandard, RewardType, } from "@soltracer/core";
 export { default as NftStakingIDL } from "./idl.json";
 export * from "./errors";
 export * from "./helpers";
-export { buildTraitProofMessage, TRAIT_PROOF_MSG_LEN, aggregateTraitBonusRate, computeTraitBonusRate, } from "./traitProof";
+export { buildTraitProofMessage, TRAIT_PROOF_MSG_LEN, computeTraitBonusRate, prepareTraitProof, ownershipFromClient, InMemoryTraitBonusStore, } 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,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"}
+{"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,GACX,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,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,GAUxB,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,21 +1,36 @@
 /**
  * Trait-bonus proof builder for NFT-staking `claim_rewards`.
  *
- * The on-chain Ed25519 message embeds `staker.total_claimed` (a strictly
- * monotonic nonce). Callers MUST read the live `StakerAccount.totalClaimed`
- * immediately before signing.
+ * Design summary
+ * --------------
+ * The on-chain `claim_rewards` instruction accepts a SINGLE u64
+ * `traitBonusRate` per claim. When `pool.reward_config.trait_bonus_enabled`
+ * is `true`, that rate is added directly to the staker's effective rate for
+ * the accrual window. The chain has zero per-NFT or per-trait awareness —
+ * ALL bonus math (trait lookups, per-NFT multipliers, caps, etc.) happens
+ * off-chain in the project's trait-authority server, which signs the final
+ * aggregated rate.
  *
- * Message layout — 80 bytes, little-endian where applicable:
+ * Why per-NFT (not per-staker) multipliers
+ * ----------------------------------------
+ * An older design exposed a `BaseMultiplier` mode on-chain that multiplied
+ * the staker's ENTIRE effective rate (all NFTs combined). That meant a
+ * single "Mythic 2x" NFT doubled rewards for every plain NFT in the same
+ * claim — cross-contamination across NFTs. The new model evaluates each
+ * NFT's bonuses independently, applies its own optional multiplier to its
+ * own bonus sum, then sums those isolated per-NFT bonuses into the single
+ * signed `u64`. One NFT's multiplier never touches another NFT's reward.
+ *
+ * Ed25519 message layout — 80 bytes (LE where applicable):
  *
  *   [0..32]   pool                 (PublicKey bytes)
  *   [32..64]  staker wallet        (PublicKey bytes)
- *   [64..72]  trait_bonus_rate u64 (LE)
- *   [72..80]  total_claimed   u64  (LE)
+ *   [64..72]  traitBonusRate u64   (LE)
+ *   [72..80]  totalClaimed   u64   (LE — strictly monotonic replay nonce)
  *
- * Sign this byte payload with the pool's trait-authority Ed25519 keypair
- * (or the global trait authority) and prepend an Ed25519 instruction with
- * the signature, expected pubkey, and message to the same transaction that
- * invokes `claimRewards(..., traitBonusRate)`.
+ * Sign with the pool's trait-authority Ed25519 keypair (or the global
+ * `stakeConfig.authority` when the pool has no override) and prepend the
+ * Ed25519 precompile instruction in the same transaction as `claimRewards`.
  */
 import { type PkInput, type BnInput } from "@soltracer/core";
 /** Fixed message length consumed by the on-chain Ed25519 verifier. */
@@ -23,8 +38,8 @@ export declare const TRAIT_PROOF_MSG_LEN = 80;
 /**
  * Build the 80-byte trait-proof message exactly as the on-chain handler
  * reconstructs it. `totalClaimed` must be the LIVE value of
- * `StakerAccount.totalClaimed` (i.e. fetched within the same client tx
- * preparation window — otherwise the signature will be rejected).
+ * `StakerAccount.totalClaimed` (fetched within the same tx prep window —
+ * otherwise the signature is rejected once the nonce advances).
  */
 export declare function buildTraitProofMessage(params: {
     pool: PkInput;
@@ -34,125 +49,176 @@ export declare function buildTraitProofMessage(params: {
     totalClaimed: BnInput;
 }): Buffer;
 /**
- * Example (off-chain trait-authority server):
- *
- * ```ts
- * import nacl from "tweetnacl"
- * import { Ed25519Program } from "@solana/web3.js"
- * import { buildTraitProofMessage } from "@soltracer/nft-staking"
+ * One catalog row. Each `(traitType, value)` pair maps to ONE absolute bonus
+ * amount measured in the same units as `rewardConfig.baseRate` (raw token
+ * units per `rateInterval`). To express the catalog in human units, multiply
+ * by `10 ** rewardDecimals` before passing it in.
  *
- * 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))
- * ```
+ * Example: catalog row `{ traitType: "Rarity", value: "Mythic", bonus: 25n }`
+ * with a `rateInterval` of 86_400s means "this trait adds 25 raw reward
+ * units per day to the NFT that carries it".
  */
+export interface TraitBonusCatalogEntry {
+    traitType: string;
+    value: string;
+    /** Raw reward units per `rateInterval` to add for this trait. */
+    bonus: bigint;
+}
 /**
- * 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
- * trait-authority server's responsibility.
- *
- * Intended backend flow:
- *
- *   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`.
+ * Storage-agnostic store interface — implement with Prisma, Drizzle, Firestore,
+ * in-memory, etc.
  *
- * 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).
+ * Catalog rows are keyed by **NFT collection mint**, NOT by pool id. A single
+ * collection can be wired into many pools (e.g. a 30-day pool and a 90-day
+ * pool over the same collection) and they all share one set of trait bonuses.
+ * The pool only contributes the trait-bonus *enable flag* and the signing
+ * authority; the bonus values themselves are a property of the collection.
+ */
+export interface TraitBonusStore {
+    /**
+     * Return every catalog entry that applies to an NFT collection.
+     *
+     * `collectionMint` is `pool.collectionMint` (base58). For pools with no
+     * configured collection (open-set pools), pass the empty string or call
+     * with `Pubkey::default().toBase58()` — the store can return `[]`.
+     */
+    listForCollection(collectionMint: string): Promise<TraitBonusCatalogEntry[]>;
+}
+/**
+ * In-memory catalog suitable for tests and small static configurations.
+ * Keys are collection mints (base58).
+ */
+export declare class InMemoryTraitBonusStore implements TraitBonusStore {
+    private readonly entriesByCollection;
+    constructor(entriesByCollection: Map<string, TraitBonusCatalogEntry[]>);
+    static from(entries: Record<string, TraitBonusCatalogEntry[]>): InMemoryTraitBonusStore;
+    listForCollection(collectionMint: string): Promise<TraitBonusCatalogEntry[]>;
+}
+/** Traits attached to a single staked NFT. */
+export interface NftTraitInput {
+    /** Mint of the staked NFT (string only used for diagnostics). */
+    mint: string;
+    /** Trait pairs in `[traitType, value]` form. */
+    traits: Array<{
+        traitType: string;
+        value: string;
+    }>;
+    /**
+     * Optional per-NFT multiplier in BPS applied ONLY to this NFT's own bonus
+     * total. 10_000 = 1× (no change). 20_000 = 2× this NFT's bonus. Multipliers
+     * NEVER cross NFTs — they cannot inflate another NFT's reward.
+     *
+     * Leave undefined (or 10_000) for plain NFTs. Project teams that want to
+     * reward rare NFTs disproportionately apply it here.
+     */
+    multiplierBps?: number;
+}
+export interface PerNftBonus {
+    mint: string;
+    /** Sum of catalog bonuses matched on this NFT, after any per-NFT multiplier. */
+    bonus: bigint;
+}
+export interface TraitBonusComputation {
+    /** Final aggregated `u64` to feed into the signed message and `claimRewards`. */
+    traitBonusRate: bigint;
+    /** Per-NFT breakdown — useful for surfacing "you earned X from this NFT" in UI. */
+    perNft: PerNftBonus[];
+}
+/**
+ * Aggregate trait bonuses into a single absolute `u64` rate.
  *
- * @example
- * ```ts
- * // 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 }] }, ..]
- * })
+ * Algorithm (per NFT, independently):
+ *   1. For every `(traitType, value)` on the NFT, look it up in `catalog`.
+ *   2. Sum every matched `bonus`. Unmatched traits contribute 0.
+ *   3. If `multiplierBps` is set, multiply the NFT's bonus sum by it / 10_000.
+ *      (Floor division — bonuses are integer raw units.)
  *
- * const message = buildTraitProofMessage({
- *   pool, wallet,
- *   traitBonusRate: result.traitBonusRate,
- *   totalClaimed: stakerAccount.totalClaimed,
- * })
- * ```
+ * Final result = sum of per-NFT bonuses. A multiplier on one NFT cannot
+ * touch another NFT's contribution, eliminating the cross-contamination bug
+ * present in the old on-chain `BaseMultiplier` mode.
  */
-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<{
+export declare function computeTraitBonusRate(params: {
+    catalog: TraitBonusCatalogEntry[];
+    nfts: NftTraitInput[];
+}): TraitBonusComputation;
+/**
+ * Resolve the trait list for a staked mint. Implementations typically read
+ * from off-chain metadata, an indexer, or a cached project DB.
+ */
+export type NftTraitResolver = (mint: string) => Promise<{
+    traits: Array<{
         traitType: string;
         value: string;
     }>;
-};
-export type ComputeTraitBonusResult = {
-    /** Aggregated u64 rate to sign and include in the claim. */
+    multiplierBps?: number;
+}>;
+/**
+ * Confirm that a given mint is currently staked by `wallet` in `poolId`.
+ *
+ * MUST return `false` for any mint not actively staked by the caller —
+ * otherwise a malicious client could submit a list of NFTs they do not own
+ * and have your server sign a bonus rate that the on-chain pool will accept.
+ */
+export type StakedOwnershipResolver = (params: {
+    wallet: string;
+    poolId: number | bigint;
+    mint: string;
+}) => Promise<boolean>;
+export interface PrepareTraitProofInput {
+    /** Pool that will receive the claim. */
+    pool: PkInput;
+    /** Wallet doing the claim. */
+    wallet: PkInput;
+    /** Live `StakerAccount.totalClaimed` — read immediately before signing. */
+    totalClaimed: BnInput;
+    /** Pool id — only used for the ownership / stake-state lookup. */
+    poolId: number | bigint;
+    /**
+     * Collection mint configured on the pool (`StakePool.collectionMint`,
+     * base58). The catalog is fetched by this key so the same bonuses apply
+     * across every pool that stakes this collection. Pass an empty string for
+     * open-set pools (the store should return `[]`).
+     */
+    collectionMint: string;
+    /** Mints the client claims to be staking. Each is verified individually. */
+    mints: string[];
+    store: TraitBonusStore;
+    resolveTraits: NftTraitResolver;
+    isStakedBy: StakedOwnershipResolver;
+}
+export interface PrepareTraitProofResult {
+    /** The 80-byte message ready for Ed25519 signing. */
+    message: Buffer;
+    /** Aggregated `u64` rate — pass to `claimRewards({ traitBonusRate })`. */
     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;
+    /** Per-NFT breakdown, including mints that survived ownership verification. */
+    perNft: PerNftBonus[];
+    /** Mints that the client supplied but were rejected as not actively staked. */
+    rejectedMints: string[];
+}
+/**
+ * Full backend orchestration: ownership-verify each mint, resolve traits,
+ * aggregate via `computeTraitBonusRate`, and build the signed message.
+ *
+ * The server is expected to sign `result.message` with the trait-authority
+ * Ed25519 keypair, return both the signature and `traitBonusRate` to the
+ * client, and the client forwards both into the `claimRewards` tx.
+ */
+export declare function prepareTraitProof(input: PrepareTraitProofInput): Promise<PrepareTraitProofResult>;
 /**
- * @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.
+ * Adapter — turn an `NftStakingClient.fetchStakeEntriesByOwner` style call
+ * into a `StakedOwnershipResolver`. Pass in your already-constructed client.
+ *
+ * ```ts
+ * const isStakedBy = ownershipFromClient(client)
+ * ```
  */
-export declare function aggregateTraitBonusRate(traits: ReadonlyArray<{
-    bonusBps?: number | bigint;
-    fixedExtra?: number | bigint;
-}>, traitBonusMode: 0 | 1 | 2): bigint;
+export declare function ownershipFromClient(client: {
+    fetchStakeEntriesByOwner: (owner: PkInput, poolId?: number) => Promise<Array<{
+        poolId: number;
+        nftMint: {
+            toBase58(): string;
+        };
+    }>>;
+}): StakedOwnershipResolver;
 //# sourceMappingURL=traitProof.d.ts.map

package/dist/traitProof.d.ts.map

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