@soltracer/nft-staking 0.2.9 → 0.3.1

package/INTEGRATION.md

@@ -280,70 +280,218 @@ 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:
+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 (mode-aware aggregation only) and `prepareTraitProof` for the full
+pipeline (steps 2–5 plus the 80-byte signable message). Pick whichever fits how much of the flow your stack already
+owns.
+
+#### Managing the bonus catalog (any DB)
+
+The admin UI (Trait Bonuses card) writes a row per `(projectId, poolId, traitType, traitValue)` to your DB. Sample
+Prisma schema used by the reference app:
+
+```prisma
+model TraitBonusConfig {
+  id          String   @id @default(cuid())
+  projectId   String   @map("project_id")
+  poolId      Int      @map("pool_id")
+  traitType   String   @map("trait_type") @db.VarChar(64)
+  traitValue  String   @map("trait_value") @db.VarChar(64)
+  bonusAmount Int      @map("bonus_amount")   // bonusBps (mode 2) or fixedExtra (mode 1)
+  imageUrl    String?  @map("image_url")
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  @@unique([projectId, poolId, traitType, traitValue])
+  @@map("trait_bonus_configs")
+}
+```
+
+You can model this however you like — Drizzle, raw Postgres, Mongo, KV, Firestore, an in-memory map for testing. The
+SDK only needs a `TraitBonusStore` adapter:
+
+```ts
+import type { TraitBonusStore } from "@soltracer/nft-staking"
+
+// Prisma example
+export const prismaTraitBonusStore: TraitBonusStore = {
+  async list({ poolId, projectId }) {
+    const rows = await prisma.traitBonusConfig.findMany({
+      where: { poolId, ...(projectId ? { projectId: String(projectId) } : {}) },
+    })
+    return rows.map((r) => ({
+      traitType: r.traitType,
+      value: r.traitValue,
+      // Pool in BaseMultiplier mode? use bonusBps. FixedExtra? use fixedExtra.
+      bonusBps: r.bonusAmount,
+    }))
+  },
+}
+
+// Drizzle example (drop-in replacement)
+export const drizzleTraitBonusStore: TraitBonusStore = {
+  async list({ poolId, projectId }) {
+    const rows = await db
+      .select()
+      .from(traitBonusConfig)
+      .where(and(eq(traitBonusConfig.poolId, poolId), projectId ? eq(traitBonusConfig.projectId, String(projectId)) : undefined))
+    return rows.map((r) => ({ traitType: r.traitType, value: r.traitValue, bonusBps: r.bonusAmount }))
+  },
+}
+
+// In-memory (for tests / examples)
+export function makeMemoryStore(seed: TraitBonusCatalogEntry[]): TraitBonusStore {
+  return { async list() { return seed } }
+}
+```
+
+Recommended CRUD endpoints (the reference app exposes these as tRPC; HTTP/GraphQL works identically):
 
-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.
+| Operation | Inputs | Behavior |
+| --- | --- | --- |
+| `list` | `{ projectId, poolId }` | Returns all catalog rows for the pool. Used by the admin UI and by `TraitBonusStore.list`. |
+| `create` | `{ projectId, poolId, traitType, traitValue, bonusAmount, imageUrl? }` | Inserts one row. |
+| `update` | `{ id, bonusAmount?, imageUrl? }` | Updates a single row. |
+| `delete` | `{ id }` | Deletes a row. |
+| `upsert` (bulk) | `{ projectId, poolId, bonuses: [...] }` | Idempotent bulk replace via the unique `(projectId, poolId, traitType, traitValue)` index. |
 
-Use `aggregateTraitBonusRate` to do step 3 safely (it enforces mode/field consistency and rejects mixing `bonusBps`
-with `fixedExtra` on the same trait):
+Treat all five as admin-only. Gate them behind a project-authority check (e.g. signed-message session for the
+project's `authority` wallet) so non-admins can't rewrite reward rules.
+
+#### Full backend flow with `prepareTraitProof`
+
+`prepareTraitProof` wires together ownership validation, trait resolution, the store, and the 80-byte message into a
+single async call. You only supply the four pieces that depend on your infrastructure:
 
 ```ts
 import {
-  aggregateTraitBonusRate,
-  buildTraitProofMessage,
+  prepareTraitProof,
+  ownershipFromClient,
+  type NftTraitResolver,
 } 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 })
-    }
+// One-time wiring:
+const traitBonusStore = prismaTraitBonusStore                  // from §"Managing the bonus catalog"
+const resolveTraits: NftTraitResolver = async (mint) => {
+  // Your trait source: Metaplex metadata, indexer, internal DB, collection JSON, etc.
+  const nft = await metadataIndex.getByMint(mint)
+  return nft.attributes.map((a) => ({ traitType: a.trait_type, value: a.value }))
+}
+const validateOwnership = ownershipFromClient(client)          // or your own stake-state index
+
+// ── POST /api/staking/trait-proof
+async function handleProofRequest(req: { wallet: PublicKey; projectId: string; poolId: number; mints: string[] }) {
+  const pool = await client.fetchStakePool(undefined, req.poolId)
+  const staker = await client.fetchStakerAccount(req.poolId, req.wallet)
+
+  const prepared = await prepareTraitProof({
+    pool: { address: pool.address, rewardConfig: pool.rewardConfig },
+    projectId: req.projectId,
+    poolId: req.poolId,
+    wallet: req.wallet,
+    requestedMints: req.mints,
+    store: traitBonusStore,
+    resolveTraits,
+    validateOwnership,
+    totalClaimed: staker.totalClaimed,
+  })
+
+  const signature = nacl.sign.detached(prepared.message, traitAuthority.secretKey)
+
+  return {
+    traitBonusRate: prepared.traitBonusRate.toString(),
+    signature: Buffer.from(signature).toString("base64"),
+    traitAuthority: traitAuthority.publicKey.toBase58(),
+    validatedMints: prepared.validatedMints,
+    rejectedMints: prepared.rejectedMints,
+    perNft: prepared.perNft, // [{ mint, bonus, matchedTraits }] — display in the claim UI
   }
 }
+```
 
-// 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,
-)
+Client side, pass the returned `signature` and `traitBonusRate` (as `BN`) into `client.claimRewards(poolId, { traitBonusRate, fee })`
+and prepend the `Ed25519Program.createInstructionWithPublicKey({ publicKey: traitAuthority, message, signature })`
+instruction to the same transaction.
 
-// 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)
+The original lower-level helpers remain available if you want to compose the pipeline yourself:
+
+```ts
+import {
+  buildTraitProofMessage,
+  computeTraitBonusRate,
+  type NftTraitInput,
+  type TraitBonusCatalogEntry,
+} from "@soltracer/nft-staking"
+import nacl from "tweetnacl"
+
+// ── 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 }
+}
 ```
 
-> ⚠️ 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, prepareTraitProof, ownershipFromClient, type TraitBonusCatalogEntry, type NftTraitInput, type ComputeTraitBonusResult, type TraitBonusStore, type NftTraitResolver, type StakedOwnershipResolver, type PreparedTraitProof, } 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,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,GACxB,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, prepareTraitProof, ownershipFromClient, } 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,EACrB,iBAAiB,EACjB,mBAAmB,GAQpB,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,37 +63,236 @@ 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`:
- *
- * - `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.
+ * 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`.
+ *
+ * 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;
 }>, traitBonusMode: 0 | 1 | 2): bigint;
+/**
+ * Storage adapter for a project's trait-bonus catalog.
+ *
+ * The SDK does not care where you persist this data — Prisma, Drizzle, raw
+ * Postgres, Mongo, KV, in-memory, REST — implement this interface against
+ * whatever backs your admin UI. Each `(traitType, value)` row carries the
+ * bonus for that pair.
+ */
+export interface TraitBonusStore {
+    /**
+     * Return every catalog entry for a given pool. The orchestrator does not
+     * filter by trait — it expects the full set so unmatched traits naturally
+     * contribute nothing.
+     */
+    list(params: {
+        poolId: number;
+        projectId?: string | number;
+    }): Promise<TraitBonusCatalogEntry[]>;
+}
+/**
+ * Resolves the on-chain trait list for a given NFT mint.
+ *
+ * Wire this to whatever your project uses as a source of truth: an indexer,
+ * Metaplex on-chain metadata, your own collection JSON, an internal DB, etc.
+ * Returning an empty array is fine — that NFT simply contributes no bonus.
+ */
+export type NftTraitResolver = (mint: string) => Promise<ReadonlyArray<{
+    traitType: string;
+    value: string;
+}>>;
+/** Validates which `requestedMints` are actually staked in `poolId` by `wallet`. */
+export type StakedOwnershipResolver = (params: {
+    wallet: string;
+    poolId: number;
+    requestedMints: ReadonlyArray<string>;
+}) => Promise<ReadonlyArray<string>>;
+export type PreparedTraitProof = {
+    /** Aggregated u64 rate ready to sign. */
+    traitBonusRate: bigint;
+    /** Mints the user requested that survived ownership validation. */
+    validatedMints: string[];
+    /** Mints the user requested that were rejected (not staked). */
+    rejectedMints: string[];
+    /** Per-NFT contribution breakdown (useful for UI tooltips / audit logs). */
+    perNft: ComputeTraitBonusResult["perNft"];
+    /** Convenience: the raw 80-byte message to feed into `nacl.sign.detached`. */
+    message: Buffer;
+};
+/**
+ * End-to-end backend orchestrator for the trait-proof flow.
+ *
+ * Combines the four user-supplied dependencies — ownership validation, trait
+ * resolution, the bonus-catalog store, and the on-chain staker nonce — into
+ * the single signable payload the on-chain claim instruction expects.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   prepareTraitProof,
+ *   type TraitBonusStore,
+ * } from "@soltracer/nft-staking"
+ *
+ * // 1) Implement the store against your DB once (any DB works).
+ * const traitBonusStore: TraitBonusStore = {
+ *   async list({ poolId, projectId }) {
+ *     const rows = await prisma.traitBonusConfig.findMany({
+ *       where: { poolId, ...(projectId ? { projectId: String(projectId) } : {}) },
+ *     })
+ *     return rows.map((r) => ({
+ *       traitType: r.traitType,
+ *       value: r.traitValue,
+ *       // pool is BaseMultiplier? use bonusBps. FixedExtra? use fixedExtra.
+ *       bonusBps: r.bonusAmount,
+ *     }))
+ *   },
+ * }
+ *
+ * // 2) Prepare the proof on each claim request.
+ * const prepared = await prepareTraitProof({
+ *   client,                       // NftStakingClient
+ *   pool,                         // already-fetched StakePool (has rewardConfig + address)
+ *   wallet: req.wallet,
+ *   requestedMints: req.mints,
+ *   store: traitBonusStore,
+ *   resolveTraits: (mint) => catalog.getTraits(mint),
+ * })
+ *
+ * // 3) Sign and respond.
+ * const signature = nacl.sign.detached(prepared.message, traitAuthority.secretKey)
+ * return {
+ *   traitBonusRate: prepared.traitBonusRate.toString(),
+ *   signature: Buffer.from(signature).toString("base64"),
+ *   perNft: prepared.perNft,
+ *   rejectedMints: prepared.rejectedMints,
+ * }
+ * ```
+ */
+export declare function prepareTraitProof(params: {
+    /** Pool config — must expose `address` and `rewardConfig.traitBonusMode`. */
+    pool: {
+        address: PkInput;
+        rewardConfig: {
+            traitBonusMode: number;
+        };
+    };
+    /** Project ID hint forwarded to the store (DB scoping, optional). */
+    projectId?: string | number;
+    poolId?: number;
+    wallet: PkInput;
+    requestedMints: ReadonlyArray<string>;
+    /** Storage adapter for the bonus catalog. */
+    store: TraitBonusStore;
+    /** Resolves trait list for a single mint. */
+    resolveTraits: NftTraitResolver;
+    /**
+     * Validates which `requestedMints` are actually staked in this pool by
+     * `wallet`. If omitted, the orchestrator trusts the caller — DO NOT skip
+     * this in production. The SDK can drive this for you when you pass a
+     * `client` and `poolId` (see `ownershipFromClient`).
+     */
+    validateOwnership: StakedOwnershipResolver;
+    /**
+     * Current `StakerAccount.totalClaimed` nonce. MUST be the live value;
+     * advance-then-sign in the same request to avoid same-second replay.
+     */
+    totalClaimed: BnInput;
+}): Promise<PreparedTraitProof>;
+/**
+ * Convenience `StakedOwnershipResolver` that uses an `NftStakingClient` to
+ * walk the wallet's stake entries and only allow mints currently staked in
+ * `poolId`. Wire this into `prepareTraitProof({ validateOwnership })` if you
+ * don't already have your own stake index.
+ */
+export declare function ownershipFromClient(client: {
+    fetchStakeEntriesByOwner: (poolId: number, wallet: PkInput) => Promise<Array<{
+        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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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":"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"}

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.");
             }
@@ -134,4 +135,105 @@ export function aggregateTraitBonusRate(traits, traitBonusMode) {
     }
     return sum;
 }
+/**
+ * End-to-end backend orchestrator for the trait-proof flow.
+ *
+ * Combines the four user-supplied dependencies — ownership validation, trait
+ * resolution, the bonus-catalog store, and the on-chain staker nonce — into
+ * the single signable payload the on-chain claim instruction expects.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   prepareTraitProof,
+ *   type TraitBonusStore,
+ * } from "@soltracer/nft-staking"
+ *
+ * // 1) Implement the store against your DB once (any DB works).
+ * const traitBonusStore: TraitBonusStore = {
+ *   async list({ poolId, projectId }) {
+ *     const rows = await prisma.traitBonusConfig.findMany({
+ *       where: { poolId, ...(projectId ? { projectId: String(projectId) } : {}) },
+ *     })
+ *     return rows.map((r) => ({
+ *       traitType: r.traitType,
+ *       value: r.traitValue,
+ *       // pool is BaseMultiplier? use bonusBps. FixedExtra? use fixedExtra.
+ *       bonusBps: r.bonusAmount,
+ *     }))
+ *   },
+ * }
+ *
+ * // 2) Prepare the proof on each claim request.
+ * const prepared = await prepareTraitProof({
+ *   client,                       // NftStakingClient
+ *   pool,                         // already-fetched StakePool (has rewardConfig + address)
+ *   wallet: req.wallet,
+ *   requestedMints: req.mints,
+ *   store: traitBonusStore,
+ *   resolveTraits: (mint) => catalog.getTraits(mint),
+ * })
+ *
+ * // 3) Sign and respond.
+ * const signature = nacl.sign.detached(prepared.message, traitAuthority.secretKey)
+ * return {
+ *   traitBonusRate: prepared.traitBonusRate.toString(),
+ *   signature: Buffer.from(signature).toString("base64"),
+ *   perNft: prepared.perNft,
+ *   rejectedMints: prepared.rejectedMints,
+ * }
+ * ```
+ */
+export async function prepareTraitProof(params) {
+    const wallet = toPk(params.wallet);
+    const poolPk = toPk(params.pool.address);
+    const mode = params.pool.rewardConfig.traitBonusMode;
+    // 1. Ownership / stake validation — drop anything the user does not actually have staked.
+    const validated = await params.validateOwnership({
+        wallet: wallet.toBase58(),
+        poolId: params.poolId ?? 0,
+        requestedMints: params.requestedMints,
+    });
+    const validatedSet = new Set(validated);
+    const validatedMints = params.requestedMints.filter((m) => validatedSet.has(m));
+    const rejectedMints = params.requestedMints.filter((m) => !validatedSet.has(m));
+    // 2 + 3. Resolve traits for each validated mint and load the bonus catalog.
+    const [nftTraits, catalog] = await Promise.all([
+        Promise.all(validatedMints.map(async (mint) => ({
+            mint,
+            traits: await params.resolveTraits(mint),
+        }))),
+        params.store.list({
+            poolId: params.poolId ?? 0,
+            projectId: params.projectId,
+        }),
+    ]);
+    // 4. Mode-aware aggregation.
+    const { traitBonusRate, perNft } = computeTraitBonusRate({
+        traitBonusMode: mode,
+        catalog,
+        nfts: nftTraits,
+    });
+    // 5. Build the signable 80-byte message.
+    const message = buildTraitProofMessage({
+        pool: poolPk,
+        wallet,
+        traitBonusRate,
+        totalClaimed: params.totalClaimed,
+    });
+    return { traitBonusRate, validatedMints, rejectedMints, perNft, message };
+}
+/**
+ * Convenience `StakedOwnershipResolver` that uses an `NftStakingClient` to
+ * walk the wallet's stake entries and only allow mints currently staked in
+ * `poolId`. Wire this into `prepareTraitProof({ validateOwnership })` if you
+ * don't already have your own stake index.
+ */
+export function ownershipFromClient(client) {
+    return async ({ wallet, poolId, requestedMints }) => {
+        const entries = await client.fetchStakeEntriesByOwner(poolId, wallet);
+        const staked = new Set(entries.map((e) => e.nftMint.toBase58()));
+        return requestedMints.filter((m) => staked.has(m));
+    };
+}
 //# sourceMappingURL=traitProof.js.map

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.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",