@soltracer/nft-staking 0.2.9 → 0.3.0

package/INTEGRATION.md

@@ -280,70 +280,86 @@ Early-unstake penalties apply on exit when configured.
 #### Aggregating per-trait bonuses
 
 The on-chain instruction accepts a **single** `u64` `traitBonusRate` per claim — it has no notion of per-trait or
-per-NFT granularity. When a staker has N NFTs each with M bonus-bearing traits, the off-chain trait-authority server is
-responsible for:
-
-1. Resolving the **active staked set** for the wallet (e.g. `client.fetchStakeEntriesByOwner(poolId, wallet)`).
-2. Looking up the bonus metadata for every trait on every staked NFT (this comes from your own catalog — the
-   chain stores no trait data).
-3. **Summing** the per-trait bonuses into one number, using the pool's `traitBonusMode`:
-   - `FixedExtra`: sum absolute reward-per-interval values across all bonus traits.
-   - `BaseMultiplier`: sum BPS values across all bonus traits (the result scales the whole staker rate).
-4. Signing the proof for that aggregated rate with the pool's `traitAuthority` keypair.
-
-Use `aggregateTraitBonusRate` to do step 3 safely (it enforces mode/field consistency and rejects mixing `bonusBps`
-with `fixedExtra` on the same trait):
+per-NFT granularity, and it cannot read NFT metadata. Aggregation lives entirely off-chain in the trait-authority
+server. The intended flow:
+
+1. **Client request.** The wallet calls your API with `{ wallet, poolId, mints }` (the mints it wants to claim against).
+2. **Ownership / stake validation.** The API resolves the wallet's active stake entries
+   (`client.fetchStakeEntriesByOwner(poolId, wallet)`) and **drops** any mint not present — never trust the client's
+   list. Anything that survives is provably staked by `wallet` in `pool`.
+3. **Trait resolution.** For each surviving mint, fetch its trait list from your own source of truth (collection JSON,
+   Metaplex on-chain metadata, indexer, internal DB). The chain stores no trait data.
+4. **Catalog lookup.** Each `(traitType, value)` pair is checked against your project's bonus catalog. Traits without
+   an entry contribute nothing.
+5. **Mode-aware sum.** Bonuses are summed according to the pool's `rewardConfig.traitBonusMode`:
+   - `FixedExtra`: catalog uses `fixedExtra` (raw reward per `rateInterval`); each matched trait adds its value.
+   - `BaseMultiplier`: catalog uses `bonusBps` (10_000 = +100%); each matched trait adds its BPS to a single boost that
+     scales the staker's current `effective_rate` for the accrual window.
+6. **Sign and return.** Sign the resulting `u64` with the pool's `traitAuthority` keypair; return signature + rate to
+   the client.
+
+The SDK ships `computeTraitBonusRate` for steps 4–5. It takes the validated NFT/trait list and a bonus catalog, enforces
+mode/field consistency, and returns both the aggregated rate and a per-NFT breakdown (handy for receipts or UI tooltips):
 
 ```ts
 import {
-  aggregateTraitBonusRate,
   buildTraitProofMessage,
+  computeTraitBonusRate,
+  type NftTraitInput,
+  type TraitBonusCatalogEntry,
 } from "@soltracer/nft-staking"
+import nacl from "tweetnacl"
 
-// 1. Resolve staker's active NFTs
-const entries = await client.fetchStakeEntriesByOwner(poolId, wallet)
-
-// 2. Look up bonuses for each trait of each staked NFT (from your catalog)
-//    BaseMultiplier example — pool grants BPS bonuses per trait.
-const traitBonuses: Array<{ bonusBps?: number; fixedExtra?: number }> = []
-for (const entry of entries) {
-  const meta = await catalog.getNftTraits(entry.nftMint)
-  // meta looks like: [{ traitType: "Background", value: "Mythic", bonusBps: 2500 }, …]
-  for (const trait of meta) {
-    if (trait.bonusBps && trait.bonusBps > 0) {
-      traitBonuses.push({ bonusBps: trait.bonusBps })
-    }
-  }
+// ── Server: POST /claim/trait-proof  body: { wallet, poolId, mints }
+async function buildProof(req: { wallet: PublicKey; poolId: number; mints: string[] }) {
+  // 2. Validate ownership / current stake state.
+  const entries = await client.fetchStakeEntriesByOwner(req.poolId, req.wallet)
+  const stakedSet = new Set(entries.map((e) => e.nftMint.toBase58()))
+  const ownedMints = req.mints.filter((m) => stakedSet.has(m))
+
+  // 3. Resolve traits from your collection catalog.
+  const nfts: NftTraitInput[] = await Promise.all(
+    ownedMints.map(async (mint) => ({
+      mint,
+      traits: await catalog.getTraits(mint), // [{ traitType, value }, ..]
+    })),
+  )
+
+  // 4 + 5. Mode-aware aggregation against the project's bonus catalog.
+  const pool = await client.fetchStakePool(undefined, req.poolId)
+  const bonusCatalog: TraitBonusCatalogEntry[] = [
+    { traitType: "Background", value: "Mythic",     bonusBps: 2500 }, // +25%
+    { traitType: "Eyes",       value: "Laser",      bonusBps: 1000 }, // +10%
+    { traitType: "Head",       value: "Gold Crown", bonusBps:  500 }, //  +5%
+  ]
+  const { traitBonusRate, perNft } = computeTraitBonusRate({
+    traitBonusMode: pool.rewardConfig.traitBonusMode as 0 | 1 | 2,
+    catalog: bonusCatalog,
+    nfts,
+  })
+
+  // 6. Sign the aggregated rate.
+  const stakerAccount = await client.fetchStakerAccount(req.poolId, req.wallet)
+  const message = buildTraitProofMessage({
+    pool: pool.address,
+    wallet: req.wallet,
+    traitBonusRate,
+    totalClaimed: stakerAccount.totalClaimed,
+  })
+  const signature = nacl.sign.detached(message, traitAuthority.secretKey)
+  return { traitBonusRate: traitBonusRate.toString(), signature, perNft }
 }
-
-// 3. Aggregate to a single u64 (mode 2 = BaseMultiplier).
-//    Result: 4_000 means +40% over the staker's current effective_rate for this claim window.
-const pool = await client.fetchStakePool(undefined, poolId)
-const traitBonusRate = aggregateTraitBonusRate(
-  traitBonuses,
-  pool.rewardConfig.traitBonusMode as 0 | 1 | 2,
-)
-
-// 4. Sign the aggregated rate.
-const stakerAccount = await client.fetchStakerAccount(poolId, wallet)
-const message = buildTraitProofMessage({
-  pool: poolPda,
-  wallet,
-  traitBonusRate,
-  totalClaimed: stakerAccount.totalClaimed,
-})
-const signature = nacl.sign.detached(message, traitAuthority.secretKey)
 ```
 
-> ⚠️ Re-aggregate on every claim. The active staked set, traits, and per-trait bonus tables can all change between
-> claims, and the on-chain message also binds `staker.totalClaimed` which advances after every successful claim.
+> ⚠️ Re-run the entire pipeline on every claim. The staked set, NFT traits, and the staker's `totalClaimed` nonce can
+> all change between claims; a stale proof is rejected on-chain.
 
 Examples per mode:
 
-| Mode | Per-trait field | What 1 trait contributes | Final `traitBonusRate` |
+| Mode | Catalog field | What 1 matched trait contributes | Final `traitBonusRate` |
 | --- | --- | --- | --- |
-| `FixedExtra` | `fixedExtra: 100` | +100 reward tokens per `rateInterval` | Sum of every staked NFT's per-trait `fixedExtra`. |
-| `BaseMultiplier` | `bonusBps: 500` | +5% over the staker's current effective rate | Sum of every staked NFT's per-trait BPS. `10_000` ⇒ 2x base. |
+| `FixedExtra` | `fixedExtra: 100` | +100 reward tokens per `rateInterval` | Sum across every matched trait on every validated NFT. |
+| `BaseMultiplier` | `bonusBps: 500` | +5% over the staker's current effective rate | Sum across every matched trait on every validated NFT. `10_000` ⇒ 2x base for that claim window. |
 
 Trait proof messages bind the pool, wallet, signed rate, and the staker account's strictly-monotonic `totalClaimed`
 counter. A new proof is required after every successful claim because `totalClaimed` advances.

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

@@ -63,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;;;;;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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

@@ -44,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) {
@@ -118,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.9",
+  "version": "0.3.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",