@soltracer/nft-staking 0.2.1 → 0.2.3

package/INTEGRATION.md

@@ -1,8 +1,14 @@
 # @soltracer/nft-staking
 
-SDK client for the solTracer NFT Staking program. Supports Legacy, pNFT, Core, and cNFT staking with escrow or wallet-lock modes, primary and secondary rewards, trait bonuses, lock tiers, and permanent burn mechanics.
+SDK client for the solTracer NFT Staking program. Supports Legacy, pNFT, Core, and cNFT staking with escrow or
+wallet-lock modes, primary and secondary rewards, trait bonuses, lock tiers, and permanent burn mechanics.
 
-The SDK auto-resolves pool state (rewardMint, stakingMode, collectionMint) and all PDA/ATA derivations internally — callers only need to provide the minimum required parameters.
+The SDK auto-resolves pool state (rewardMint, stakingMode, collectionMint) and all PDA/ATA derivations internally —
+callers only need to provide the minimum required parameters.
+
+Staking wallets must have a user-management profile before staking, claiming, unstaking, or burning. The SDK derives the
+profile PDA automatically, but the profile account must already exist. Banned profiles cannot create new stakes; they
+may still claim or exit positions, with accrual capped at the profile ban timestamp.
 
 ## Installation
 
@@ -13,46 +19,47 @@ npm install @soltracer/nft-staking @soltracer/core @coral-xyz/anchor @solana/web
 ## Quick Start
 
 ```ts
-import { NftStakingClient } from "@soltracer/nft-staking";
-import { AnchorProvider } from "@coral-xyz/anchor";
+import { NftStakingClient } from "@soltracer/nft-staking"
+import { AnchorProvider } from "@coral-xyz/anchor"
 
-const provider = AnchorProvider.env();
-const client = NftStakingClient.create(provider, { projectId: 1 });
+const provider = AnchorProvider.env()
+const client = NftStakingClient.create(provider, { projectId: 1 })
 
 // Fetch a staking pool
-const pool = await client.fetchStakePool(undefined, poolId);
+const pool = await client.fetchStakePool(undefined, poolId)
 
 // Stake an NFT (stakingMode auto-resolved from pool)
-const ix = await client.stakeNft(poolId, nftMint);
+const ix = await client.stakeNft(poolId, nftMint)
 
 // Unstake (rewardMint + stakingMode auto-resolved)
-const ix = await client.unstakeNft(poolId, nftMint);
+const ix = await client.unstakeNft(poolId, nftMint)
 
 // Claim rewards (rewardMint auto-resolved)
-const ix = await client.claimRewards(poolId);
+const ix = await client.claimRewards(poolId)
 ```
 
 ## Client Setup
 
 ```ts
 // With project ID bound (recommended — eliminates projectId from every call)
-const client = NftStakingClient.create(provider, { projectId: 1 });
+const client = NftStakingClient.create(provider, { projectId: 1 })
 
 // Without project ID (must pass it per-call, or set later)
-const client = NftStakingClient.create(provider);
-client.setProjectId(1); // set later, chainable
+const client = NftStakingClient.create(provider)
+client.setProjectId(1) // set later, chainable
 
 // From custom IDL
-const client = NftStakingClient.fromIdl(customIdl, provider, { projectId: 1 });
+const client = NftStakingClient.fromIdl(customIdl, provider, { projectId: 1 })
 ```
 
 ## Fee Parameters
 
-Optional referral account for fee distribution. Fee PDA accounts (feeConfig, treasury, priceFeed) are resolved automatically.
+Optional referral account for fee distribution. Fee PDA accounts (feeConfig, treasury, priceFeed) are resolved
+automatically.
 
 ```ts
 interface FeeParams {
-  referralAccount?: string; // base58 pubkey
+  referralAccount?: string // base58 pubkey
 }
 ```
 
@@ -61,34 +68,53 @@ interface FeeParams {
 ### Pool & Config
 
 ```ts
-const config = await client.fetchStakeConfig();        // uses bound projectId
-const config = await client.fetchStakeConfig(2);       // explicit projectId
-const pool = await client.fetchStakePool(undefined, poolId);
-const pools = await client.fetchAllPools();
+const config = await client.fetchStakeConfig() // uses bound projectId
+const config = await client.fetchStakeConfig(2) // explicit projectId
+const pool = await client.fetchStakePool(undefined, poolId)
+const pools = await client.fetchAllPools()
 ```
 
 ### Stake Entries
 
 ```ts
-const entry = await client.fetchStakeEntry(poolId, nftMint);
-const entries = await client.fetchStakeEntriesByOwner(poolId, owner);
-const batch = await client.fetchStakeEntriesForMints(poolId, [mint1, mint2]);
-const all = await client.fetchAllStakeEntriesByPool(poolId);
-const cross = await client.fetchStakeEntriesAcrossPools([poolId1, poolId2], [mint1, mint2]);
+const entry = await client.fetchStakeEntry(poolId, nftMint)
+const entries = await client.fetchStakeEntriesByOwner(poolId, owner)
+const batch = await client.fetchStakeEntriesForMints(poolId, [mint1, mint2])
+const all = await client.fetchAllStakeEntriesByPool(poolId)
+const cross = await client.fetchStakeEntriesAcrossPools([poolId1, poolId2], [mint1, mint2])
 ```
 
 ### Staker Accounts
 
 ```ts
-const staker = await client.fetchStakerAccount(poolId, wallet);
-const stakers = await client.fetchAllStakersByPool(poolId);
+const staker = await client.fetchStakerAccount(poolId, wallet)
+const stakers = await client.fetchAllStakersByPool(poolId)
+
+const summary = await client.fetchStakerRewardSummary(poolId, wallet, {
+  rewardDecimals: 6, // optional: avoids a mint-account decimals fetch
+  secondaryRewardDecimals: { [secondaryMint.toBase58()]: 6 },
+  includeVaultBalances: true,
+})
 ```
 
+`fetchStakerRewardSummary()` returns display-ready raw and UI amounts for primary and secondary rewards:
+
+- `primary.totalAccrued`, `primary.claimable`, `primary.unclaimable`.
+- `secondary[i].totalAccrued`, `secondary[i].claimable`, `secondary[i].unclaimable`.
+- `claimableBase` / `unclaimableBase` before quantity bonuses.
+- `vaultBalance` when `includeVaultBalances` is true.
+- `entries.claimableActive` and `entries.unclaimableActive` for explaining how many NFTs are currently claimable versus
+  claim-at-end locked.
+
+Raw amounts are base units. UI amounts are divided by the returned `decimals`. The SDK caches mint decimals per client
+instance, and callers can pass `rewardDecimals` / `secondaryRewardDecimals` from project metadata or a token registry to
+avoid recurring mint-account RPC reads.
+
 ### Secondary Rewards
 
 ```ts
-const poolSecondary = await client.fetchPoolSecondaryRewards(poolId);
-const stakerSecondary = await client.fetchStakerSecondaryRewards(poolId, wallet);
+const poolSecondary = await client.fetchPoolSecondaryRewards(poolId)
+const stakerSecondary = await client.fetchStakerSecondaryRewards(poolId, wallet)
 ```
 
 ## Admin Instructions
@@ -96,7 +122,7 @@ const stakerSecondary = await client.fetchStakerSecondaryRewards(poolId, wallet)
 ### Initialize & Create Pools
 
 ```ts
-const ix = await client.initializeStakeConfig();
+const ix = await client.initializeStakeConfig()
 
 const ix = await client.createStakePool(
   0, // stakingMode: 0 = Escrow, 1 = WalletLock
@@ -108,12 +134,15 @@ const ix = await client.createStakePool(
     traitBonusMode: 0,
     quantityThresholds: [],
   },
-  [{ lockDuration: 0, rewardRate: 100, earlyUnstakePenaltyBps: 0 }],
+  [{ lockDuration: 30 * 86400, rewardRate: 150, earlyUnstakePenaltyBps: 500, claimOnlyAtEnd: false }],
   collectionMint,
-  { rewardEndAt: 0, maxStaked: 0 } // optional
-);
+  { rewardEndAt: 0, maxStaked: 0, allowUnlockedStaking: true }, // optional
+)
 ```
 
+Lock tier reward rates override the base rate for NFTs staked into that tier. Set `allowUnlockedStaking: false` for
+pools where every stake must choose a lock tier.
+
 ### Update Pool
 
 ```ts
@@ -134,57 +163,68 @@ const ix = await client.updateStakePool(poolId, {
 RewardMint is auto-resolved from pool state:
 
 ```ts
-const fund = await client.fundRewardVault(poolId, amount);
-const withdraw = await client.withdrawRewardVault(poolId, amount);
+const fund = await client.fundRewardVault(poolId, amount)
+const withdraw = await client.withdrawRewardVault(poolId, amount)
 
 // Or explicit rewardMint if needed:
-const fund = await client.fundRewardVault(poolId, amount, { rewardMint: mintPk });
+const fund = await client.fundRewardVault(poolId, amount, { rewardMint: mintPk })
 ```
 
 ### Close Pool
 
 ```ts
-const ix = await client.closeStakePool(poolId);
+const ix = await client.closeStakePool(poolId)
 ```
 
 ### Secondary Rewards Management
 
 ```ts
-const add = await client.addPoolSecondaryReward(poolId, rewardMint, baseRate, lockTierRates);
-const remove = await client.removePoolSecondaryReward(poolId, rewardIndex);
-const fund = await client.fundSecondaryVault(poolId, rewardIndex, amount, rewardMint);
-const withdraw = await client.withdrawSecondaryVault(poolId, rewardIndex, amount, rewardMint);
+const add = await client.addPoolSecondaryReward(poolId, rewardMint, baseRate, lockTierRates)
+const remove = await client.removePoolSecondaryReward(poolId, rewardIndex)
+const fund = await client.fundSecondaryVault(poolId, rewardIndex, amount, rewardMint)
+const withdraw = await client.withdrawSecondaryVault(poolId, rewardIndex, amount, rewardMint)
 ```
 
 ## User Instructions
 
 ### Staking Legacy/pNFT
 
-StakingMode is auto-resolved from pool:
+StakingMode is auto-resolved from pool. Programmable-NFT token-record PDAs (`tokenRecord` + `destinationTokenRecord`)
+are auto-detected on-chain by probing the source token-record account — legacy NFTs pass `null` for both, pNFTs pass the
+derived PDAs. No client flag required.
 
 ```ts
-const stake = await client.stakeNft(poolId, nftMint, { lockTierIndex: 0, fee, gateProof });
-const unstake = await client.unstakeNft(poolId, nftMint, { fee });
+const stake = await client.stakeNft(poolId, nftMint, { lockTierIndex: 0, fee, gateProof })
+const unstake = await client.unstakeNft(poolId, nftMint, { fee })
 ```
 
+An NFT can only be actively staked once across all pools. The program maintains a global asset lock PDA for each staked
+mint/asset ID and closes it when the asset is unstaked or burned.
+
 ### Staking Core NFTs
 
 Collection is auto-resolved from pool:
 
 ```ts
-const stake = await client.stakeCoreNft(poolId, nftAsset, { lockTierIndex: 0, fee });
-const unstake = await client.unstakeCoreNft(poolId, nftAsset, { fee });
+const stake = await client.stakeCoreNft(poolId, nftAsset, { lockTierIndex: 0, fee })
+const unstake = await client.unstakeCoreNft(poolId, nftAsset, { fee })
 ```
 
 ### Staking cNFTs
 
 ```ts
 const cnftParams = {
-  nftAssetId, merkleTree, cnftRoot, cnftDataHash,
-  cnftCreatorHash, cnftNonce, cnftIndex, proofNodes,
-};
-const stake = await client.stakeCnft(poolId, cnftParams, { fee, gateProof });
-const unstake = await client.unstakeCnft(poolId, cnftParams, { fee });
+  nftAssetId,
+  merkleTree,
+  cnftRoot,
+  cnftDataHash,
+  cnftCreatorHash,
+  cnftNonce,
+  cnftIndex,
+  proofNodes,
+}
+const stake = await client.stakeCnft(poolId, cnftParams, { fee, gateProof })
+const unstake = await client.unstakeCnft(poolId, cnftParams, { fee })
 ```
 
 ### Claiming Rewards
@@ -192,53 +232,152 @@ const unstake = await client.unstakeCnft(poolId, cnftParams, { fee });
 RewardMint is auto-resolved from pool:
 
 ```ts
-const claim = await client.claimRewards(poolId, { traitBonusRate, fee });
+const claim = await client.claimRewards(poolId, { traitBonusRate, fee })
 ```
 
+Current on-chain behavior: if any active stake entry in the pool has a live `claimOnlyAtEnd` lock, primary and secondary
+claim instructions are blocked until `claimLockedUntil`. Use `fetchStakerRewardSummary()` to show claimable versus
+unclaimable buckets for the intended per-NFT UX. The summary identifies base/unlocked rewards separately from
+claim-at-end locked rewards, but the current claim instruction does not yet support a partial claim of only the unlocked
+bucket.
+
+Early-unstake penalties apply on exit when configured.
+
+### Trait Bonus Claims
+
+`RewardConfig.traitBonusMode` controls how a signed `traitBonusRate` is interpreted:
+
+- `0` / `None`: trait bonus proofs are disabled; nonzero `traitBonusRate` is rejected.
+- `1` / `FixedExtra`: `traitBonusRate` is a raw extra reward rate per interval, added temporarily for the claim accrual
+  window.
+- `2` / `BaseMultiplier`: `traitBonusRate` is bonus basis points over the staker's current base effective rate. `10_000`
+  means +100%, so total accrual for that window is 2x base.
+
+Trait proof messages bind the pool, wallet, signed rate, and the staker account's strictly-monotonic `totalClaimed`
+counter (audit fix F-H2 — replaces the prior `lastUpdateAt` nonce to eliminate same-second replay). A new proof is
+required after every successful claim because `totalClaimed` advances.
+
+Use the SDK's `buildTraitProofMessage` helper to assemble the exact 80-byte payload the on-chain verifier rebuilds
+(`pool ‖ wallet ‖ rate u64 LE ‖ totalClaimed u64 LE`):
+
+```ts
+import nacl from "tweetnacl"
+import { Ed25519Program, Transaction } from "@solana/web3.js"
+import { buildTraitProofMessage } from "@soltracer/nft-staking"
+
+const stakerAccount = await client.fetchStakerAccount(poolId, wallet)
+const message = buildTraitProofMessage({
+  pool,
+  wallet,
+  traitBonusRate, // BN
+  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, fee })
+await provider.sendAndConfirm(new Transaction().add(ed25519Ix, claimIx))
+```
+
+The Ed25519 verifier instruction MUST be in the same transaction as `claimRewards` and the signing pubkey MUST match
+`pool.traitAuthority` (or the global trait authority if configured).
+
+### Merkle Gate Proofs
+
+Pools with a non-zero `merkleRoot` enforce wallet- or mint-allowlist gating at stake time. The on-chain verifier uses
+`sha256(leaf)` for leaves and `sha256(min(a,b) ‖ max(a,b))` for internal nodes (canonical ordering — proofs do not carry
+position bits). Build the tree once when seeding the root via `updateStakePool`, then derive per-stake proofs:
+
+```ts
+import {
+  GATE_TYPE_WALLET,
+  buildMerkleTree,
+  getMerkleProof,
+  proofToAnchorArg,
+  rootToAnchorArg,
+} from "@soltracer/nft-staking"
+
+// One-time: seed pool gate
+const tree = buildMerkleTree(allowedWallets) // PublicKey[]
+await client.updateStakePool(poolId, {
+  merkleRoot: rootToAnchorArg(tree.root),
+  gateType: GATE_TYPE_WALLET,
+})
+
+// Per-stake call
+const gateProof = proofToAnchorArg(getMerkleProof(tree, staker))
+await client.stakeNft(poolId, nftMint, { gateProof })
+```
+
+For `GATE_TYPE_TOKEN_MINT` pools, pass the gated mints to `buildMerkleTree` and supply `getMerkleProof(tree, nftMint)`.
+
 ### Secondary Reward Claims
 
 ```ts
-const init = await client.initStakerSecondary(poolId);
-const claim = await client.claimSecondaryRewards(poolId, [{ mint: mintPk }], { fee });
+const init = await client.initStakerSecondary(poolId)
+const claim = await client.claimSecondaryRewards(poolId, [{ mint: mintPk }], { fee })
 ```
 
+Secondary reward claims use the same profile and claim-lock checks as primary rewards. Quantity thresholds also apply to
+secondary payouts.
+
+All secondary mints claimed in one transaction must use the same token program. If a pool uses both SPL Token and
+Token-2022 secondary mints, claim them in separate transactions.
+
+### Reward Exhaustion
+
+Primary token claims are all-or-nothing: if the reward vault balance is below the computed payout after trait and
+quantity bonuses, the claim fails with `InsufficientRewardBalance`. The program does not do partial primary claims.
+Primary vault withdrawals are protected by `totalObligationPending`, but trait and quantity bonus surplus still needs
+operator funding beyond base obligations.
+
+Secondary token claims are also all-or-nothing for the supplied secondary set. Secondary rewards do not currently
+maintain a pool-wide obligation mirror, so operators should keep secondary vaults funded above the displayed claimable
+totals from `fetchStakerRewardSummary({ includeVaultBalances: true })` and avoid withdrawing below pending user-facing
+liabilities.
+
 ### Burn Permanently-Locked Assets
 
 StakingMode/collection auto-resolved from pool:
 
 ```ts
-const burnNft = await client.burnStakedNft(poolId, nftMint, { fee });
-const burnCore = await client.burnStakedCoreNft(poolId, nftAsset, { fee });
+const burnNft = await client.burnStakedNft(poolId, nftMint, { fee })
+const burnCore = await client.burnStakedCoreNft(poolId, nftAsset, { fee })
 ```
 
 ### Spend Points
 
 ```ts
-const spend = await client.spendPoints(poolId, amount, { fee });
+const spend = await client.spendPoints(poolId, amount, { fee })
 ```
 
 ## What the SDK Resolves Internally
 
-| Parameter | Auto-resolved from |
-|---|---|
-| `rewardMint` | Pool `rewardConfig.rewardMint` |
-| `stakingMode` | Pool `stakingMode` |
-| `collectionMint` | Pool `collectionMint` |
-| `projectId` | Client instance (set via `create()` or `setProjectId()`) |
-| Fee accounts | PDA derivation from program ID |
-| Token program | Mint account owner detection (SPL vs Token-2022) |
-| ATAs | Derived from wallet + mint + token program |
-| All PDAs | Anchor seed derivation |
-| Decimal normalization | Mint account data byte 44 |
+| Parameter             | Auto-resolved from                                       |
+| --------------------- | -------------------------------------------------------- |
+| `rewardMint`          | Pool `rewardConfig.rewardMint`                           |
+| `stakingMode`         | Pool `stakingMode`                                       |
+| `collectionMint`      | Pool `collectionMint`                                    |
+| `projectId`           | Client instance (set via `create()` or `setProjectId()`) |
+| Fee accounts          | PDA derivation from program ID                           |
+| Token program         | Mint account owner detection (SPL vs Token-2022)         |
+| ATAs                  | Derived from wallet + mint + token program               |
+| User profile          | Derived from wallet via user-management PDA              |
+| Global stake lock     | Derived from NFT mint/Core asset/cNFT asset ID           |
+| All PDAs              | Anchor seed derivation                                   |
+| Decimal normalization | Mint account data byte 44                                |
 
 Pool data is cached for 30s to minimize redundant RPC calls.
 
 ## Exports
 
-| Export | Type |
-|---|---|
-| `NftStakingClient` | Class |
-| `FeeParams` | TypeScript interface |
+| Export                   | Type                                             |
+| ------------------------ | ------------------------------------------------ |
+| `NftStakingClient`       | Class                                            |
+| `FeeParams`              | TypeScript interface                             |
 | `NFT_STAKING_PROGRAM_ID` | `PublicKey` (re-exported from `@soltracer/core`) |
-| `NftStakingIDLType` | IDL type |
-| `NftStakingIDL` | IDL JSON |
+| `NftStakingIDLType`      | IDL type                                         |
+| `NftStakingIDL`          | IDL JSON                                         |