@karpeleslab/chiefstaker-sdk

TypeScript SDK for the ChiefStaker time-weighted staking program on Solana.

ChiefStaker lets token holders stake SPL Token or Token 2022 assets and earn SOL rewards distributed proportionally by a time-weighted formula. Newer stakers start with near-zero weight that grows exponentially toward full weight over a configurable time constant (tau).

Program ID: 3Ecf8gyRURyrBtGHS1XAVXyQik5PqgDch4VkxrH4ECcr

Staking UI: https://www.tibane.net/staking/<mint_address>

Installation

npm install @karpeleslab/chiefstaker-sdk @solana/web3.js

@solana/web3.js v1.90+ is a peer dependency.

Quick start

import { Connection, PublicKey, Keypair } from "@solana/web3.js";
import { ChiefStakerClient } from "@karpeleslab/chiefstaker-sdk";

const connection = new Connection("https://api.mainnet-beta.solana.com");
const client = new ChiefStakerClient(connection);

const mint = new PublicKey("YourTokenMint...");

// Fetch pool state
const pool = await client.getPool(mint);
console.log("Total staked:", pool.totalStaked);

// Fetch your stake
const [poolAddress] = client.findPoolAddress(mint);
const stake = await client.getUserStake(poolAddress, wallet.publicKey);
console.log("My stake:", stake?.amount);

Usage

The SDK provides three layers you can use independently:

1. ChiefStakerClient — high-level class with account fetching, PDA derivation, instruction building, and transaction sending in one place.
2. Instruction builders — standalone create*Instruction() functions that return a TransactionInstruction for composing into your own transactions.
3. Account helpers — fetch*() and deserialize*() functions for reading on-chain state.

Using the client

import { ChiefStakerClient } from "@karpeleslab/chiefstaker-sdk";

const client = new ChiefStakerClient(connection);

You can optionally pass a custom program ID as the second argument.

Staking tokens

const tokenProgram = await client.detectTokenProgram(mint);
const [poolAddress] = client.findPoolAddress(mint);

const ix = client.stake({
  pool: poolAddress,
  mint,
  owner: wallet.publicKey,
  userTokenAccount: myTokenAccount,
  amount: 1_000_000n,
  tokenProgram,
});

await client.sendTransaction([ix], [keypair]);

The pool's metadata PDA is a required account on the stake, unstake, and close paths (it keeps member_count exact). The SDK derives and appends it automatically, so you don't pass it explicitly — an uninitialized metadata account is tolerated on-chain for pools that never called setPoolMetadata.

Unstaking tokens

Pools can be configured with or without an unstake cooldown. Check pool.unstakeCooldownSeconds to determine which flow to use.

Direct unstake (when unstakeCooldownSeconds === 0n):

const ix = client.unstake({
  pool: poolAddress,
  mint,
  owner: wallet.publicKey,
  userTokenAccount: myTokenAccount,
  amount: 500_000n,
  tokenProgram,
});

Cooldown unstake (when unstakeCooldownSeconds > 0n):

// Step 1: Request unstake (starts the cooldown timer)
const requestIx = client.requestUnstake({
  pool: poolAddress,
  owner: wallet.publicKey,
  amount: 500_000n,
});

// Step 2: After cooldown elapses, complete the unstake
const completeIx = client.completeUnstake({
  pool: poolAddress,
  mint,
  owner: wallet.publicKey,
  userTokenAccount: myTokenAccount,
  tokenProgram,
});

// Optional: Cancel a pending request (tokens remain staked)
const cancelIx = client.cancelUnstakeRequest({
  pool: poolAddress,
  owner: wallet.publicKey,
});

Checking pending rewards and weight

Query claimable SOL and current staking weight without sending a transaction:

// Get pending claimable rewards in lamports
const rewards = await client.getClaimableRewards(poolAddress, wallet.publicKey);
console.log(`Claimable: ${Number(rewards) / 1e9} SOL`);

// Get current staking weight (0 to 1)
const weight = await client.getStakeWeight(poolAddress, wallet.publicKey);
console.log(`Weight: ${(weight * 100).toFixed(1)}%`);

Both methods accept an optional currentTime parameter to simulate a future timestamp.

Claiming rewards

SOL rewards accrue based on your time-weighted stake. Claim them at any time:

const ix = client.claimRewards({
  pool: poolAddress,
  owner: wallet.publicKey,
});

Depositing rewards

Anyone can deposit SOL rewards into a pool:

const ix = client.depositRewards({
  pool: poolAddress,
  depositor: wallet.publicKey,
  amount: 1_000_000_000n, // 1 SOL in lamports
});

Pool administration

These operations require the pool authority to sign.

// Update pool settings
const ix = client.updatePoolSettings({
  pool: poolAddress,
  authority: authorityKeypair.publicKey,
  minStakeAmount: 100_000n,           // set minimum stake
  lockDurationSeconds: 86400n,         // 1 day lock after staking
  unstakeCooldownSeconds: 259200n,     // 3 day cooldown to unstake
});

// Transfer authority (set to PublicKey.default to renounce irreversibly)
const ix = client.transferAuthority({
  pool: poolAddress,
  authority: authorityKeypair.publicKey,
  newAuthority: newAuthorityPubkey,
});

Permissionless cranks

These instructions can be called by anyone and require no special authority:

// Rebase pool to prevent overflow (call periodically)
const syncIx = client.syncPool(poolAddress);

// Sync SOL sent directly to the pool PDA (e.g., from pump.fun fees)
const syncRewardsIx = client.syncRewards(poolAddress);

// Set pool metadata for explorer display
const metaIx = client.setPoolMetadata({
  pool: poolAddress,
  mint,
  payer: wallet.publicKey,
});

// Claim pump.fun fee ownership for the pool
const feeIx = client.takeFeeOwnership({
  pool: poolAddress,
  mint,
});

Staking on behalf of another user

Stake tokens for a beneficiary who doesn't need to sign:

const ix = client.stakeOnBehalf({
  pool: poolAddress,
  mint,
  staker: myKeypair.publicKey,        // pays rent and provides tokens
  beneficiary: recipientPubkey,        // receives the staking position
  stakerTokenAccount: myTokenAccount,
  amount: 1_000_000n,
  tokenProgram,
});

Closing a stake account

After fully unstaking and claiming all rewards, reclaim the rent:

const ix = client.closeStakeAccount({
  pool: poolAddress,
  owner: wallet.publicKey,
});

Using with wallet adapters

The client works with any @solana/wallet-adapter compatible wallet:

const ix = client.stake({ /* ... */ });
await client.sendTransactionWithWallet([ix], wallet);

Using standalone instruction builders

If you prefer to compose transactions yourself:

import {
  createStakeInstruction,
  createClaimRewardsInstruction,
} from "@karpeleslab/chiefstaker-sdk";
import { Transaction } from "@solana/web3.js";

const stakeIx = createStakeInstruction({
  pool: poolAddress,
  mint,
  owner: wallet.publicKey,
  userTokenAccount: myTokenAccount,
  amount: 1_000_000n,
  tokenProgram,
});

const claimIx = createClaimRewardsInstruction({
  pool: poolAddress,
  owner: wallet.publicKey,
});

// Combine into a single transaction
const tx = new Transaction().add(stakeIx, claimIx);

Fetching accounts

Single account fetches

import {
  fetchStakingPool,
  fetchUserStake,
  fetchPoolMetadata,
} from "@karpeleslab/chiefstaker-sdk";

// By mint address
const pool = await fetchStakingPool(connection, mint);

// By pool PDA address (if you already know it)
const pool = await client.getPoolByAddress(poolPda);

// User stake
const stake = await fetchUserStake(connection, poolAddress, ownerPubkey);

// Pool metadata
const meta = await fetchPoolMetadata(connection, poolAddress);
console.log(meta.name, meta.tags, meta.memberCount);

Batch fetches

import {
  fetchAllStakingPools,
  fetchUserStakesByPool,
  fetchUserStakesByOwner,
} from "@karpeleslab/chiefstaker-sdk";

// All pools in the program
const allPools = await fetchAllStakingPools(connection);
for (const { address, account } of allPools) {
  console.log(address.toBase58(), account.totalStaked);
}

// All stakers in a specific pool
const stakers = await fetchUserStakesByPool(connection, poolAddress);

// All of a user's stakes across every pool
const myStakes = await fetchUserStakesByOwner(connection, wallet.publicKey);

Raw deserialization

If you already have account data (e.g., from getMultipleAccountsInfo):

import {
  deserializeStakingPool,
  deserializeUserStake,
  deserializePoolMetadata,
} from "@karpeleslab/chiefstaker-sdk";

const accountInfo = await connection.getAccountInfo(poolAddress);
const pool = deserializeStakingPool(accountInfo.data);

PDA derivation

All PDAs can be derived without network calls:

import {
  findPoolAddress,
  findTokenVaultAddress,
  findUserStakeAddress,
  findPoolMetadataAddress,
} from "@karpeleslab/chiefstaker-sdk";

const [pool, poolBump] = findPoolAddress(mint);               // ["pool", mint]
const [vault, vaultBump] = findTokenVaultAddress(pool);        // ["token_vault", pool]
const [stake, stakeBump] = findUserStakeAddress(pool, owner);  // ["stake", pool, owner]
const [meta, metaBump] = findPoolMetadataAddress(pool);        // ["metadata", pool]

Additional PDAs for pump.fun fee integration:

import {
  findSharingConfig,
  findBondingCurve,
  findPumpCreatorVault,
  findCoinCreatorVaultAuth,
} from "@karpeleslab/chiefstaker-sdk";

const [sharingConfig] = findSharingConfig(mint);
const [bondingCurve] = findBondingCurve(mint);
const [creatorVault] = findPumpCreatorVault(sharingConfig);
const [vaultAuth] = findCoinCreatorVaultAuth(sharingConfig);

Error handling

Parse program errors from failed transactions:

import { extractProgramError, ChiefStakerError } from "@karpeleslab/chiefstaker-sdk";

try {
  await client.sendTransaction([ix], [keypair]);
} catch (err) {
  const parsed = extractProgramError(err);
  if (parsed) {
    console.error(`${parsed.name}: ${parsed.message}`);
    // e.g. "StakeLocked: Stake is locked - lock duration has not elapsed"

    if (parsed.code === ChiefStakerError.CooldownRequired) {
      // Use requestUnstake flow instead of direct unstake
    }
  }
}

Account types

StakingPool

Field	Type	Description
mint	PublicKey	Token mint address
tokenVault	PublicKey	PDA holding staked tokens
authority	PublicKey	Admin authority
totalStaked	bigint	Total tokens staked
tauSeconds	bigint	Time constant for weight curve (seconds)
baseTime	bigint	Base time for rebasing (Unix timestamp)
accRewardPerWeightedShare	bigint	Accumulated reward per weighted share (WAD-scaled)
lastUpdateTime	bigint	Last reward update timestamp
bump	number	PDA bump seed
lastSyncedLamports	bigint	Last known lamport balance
minStakeAmount	bigint	Minimum stake amount (0 = no minimum)
lockDurationSeconds	bigint	Lock period after staking (0 = no lock)
unstakeCooldownSeconds	bigint	Cooldown period for unstaking (0 = direct unstake)
initialBaseTime	bigint	Original base_time before rebasing
totalRewardDebt	bigint	Sum of all users' reward_debt (WAD-scaled)
totalResidualUnpaid	bigint	Lamports owed to fully-unstaked users

UserStake

Field	Type	Description
owner	PublicKey	Stake owner
pool	PublicKey	Pool this stake belongs to
amount	bigint	Tokens staked
stakeTime	bigint	When the stake began (Unix timestamp)
expStartFactor	bigint	Exponential factor at stake time (WAD-scaled)
rewardDebt	bigint	Reward debt snapshot (WAD-scaled)
bump	number	PDA bump seed
unstakeRequestAmount	bigint	Pending unstake amount (0 = none)
unstakeRequestTime	bigint	When unstake was requested
lastStakeTime	bigint	Most recent deposit timestamp
baseTimeSnapshot	bigint	Pool base_time when last calibrated
totalRewardsClaimed	bigint	Cumulative SOL claimed (lamports)
claimedRewardsWad	bigint	Cumulative WAD-scaled rewards paid
unstakeRequestSettled	number	1 if pending request was settled at request time

PoolMetadata

Field	Type	Description
pool	PublicKey	Back-reference to pool
name	string	Pool display name
tags	string[]	Tags (e.g. #stakingpool)
url	string	URL
memberCount	bigint	Active staker count
bump	number	PDA bump seed

Constants

import {
  PROGRAM_ID,              // ChiefStaker program
  TOKEN_PROGRAM_ID,        // SPL Token
  TOKEN_2022_PROGRAM_ID,   // Token 2022
  WAD,                     // 10^18 (fixed-point scale)
} from "@karpeleslab/chiefstaker-sdk";

How time-weighted staking works

ChiefStaker uses an exponential decay curve for staking weight:

weight = stake_amount * (1 - e^(-age / tau))

• New stakers start with ~0% weight
• At 1 tau (e.g., 30 days): ~63% weight
• At 3 tau: ~95% weight
• At 5 tau: ~99% weight

This means long-term stakers earn proportionally more rewards than recent stakers, incentivizing commitment. When adding to an existing stake, the maturity percentage is preserved through blending.

License

MIT