API Reference

This document provides a comprehensive API reference for all Ignition Stake Pool components including the FOGO blockchain program instructions, TypeScript SDK, CLI commands, and Python client.

Program Instructions API

Program ID

SP1s4uFeTAX9jsXXmwyDs1gxYYf7cdDZ8qHUHVxE1yr

Core Data Structures

The program uses several key data structures for managing pool state. For complete struct definitions and field-level details, refer to the source code in program/src/state.rs.

Key Structures:

• StakePool: Main pool account (~555 bytes)

• ValidatorStakeInfo: Individual validator information (~88 bytes per validator)

• Fee: Numerator/denominator fee structure

• FutureEpoch: Time-based configuration changes

Refer to the program source code for detailed field specifications.

Program Instructions Reference

Pool Management Instructions

Initialize

Creates a new stake pool.

Initialize {
    fee: Fee,                       // Management fee on rewards
    withdrawal_fee: Fee,            // Fee on withdrawals
    deposit_fee: Fee,               // Fee on deposits
    referral_fee: u8,               // Referral fee percentage (0-100)
    max_validators: u32,            // Maximum expected validators
}

Accounts (10):

1. [w] New StakePool account

2. [s] Manager

3. [] Staker

4. [] Stake pool withdraw authority (PDA)

5. [w] Validator list storage account

6. [] Reserve stake account

7. [] Pool token mint

8. [] Manager fee account

9. [] Token program

10. [] (Optional) Deposit authority

PDA Seeds:

• Withdraw Authority: [stake_pool_address, b"withdraw"]

• Deposit Authority: [stake_pool_address, b"deposit"]

SetManager

Updates the pool manager.

SetManager

Accounts (4):

1. [w] Stake pool

2. [s] Current manager

3. [s] New manager

4. [] New manager fee account

SetFee

Updates pool fees.

SetFee {
    fee: FeeType,
}

pub enum FeeType {
    SolReferral(u8),
    StakeReferral(u8),
    Epoch(Fee),
    StakeDeposit(Fee),
    SolDeposit(Fee),
    StakeWithdrawal(Fee),
    SolWithdrawal(Fee),
}

Accounts (2):

1. [w] Stake pool

2. [s] Manager

Validator Management Instructions

AddValidatorToPool

Adds a validator to the stake pool.

AddValidatorToPool(u32)  // Optional validator seed

Accounts (13):

1. [w] Stake pool

2. [s] Staker

3. [w] Reserve stake account

4. [] Withdraw authority

5. [w] Validator list

6. [w] Validator stake account

7. [] Validator vote account

8. [] Rent sysvar

9. [] Clock sysvar

10. [] Stake history sysvar

11. [] Stake config sysvar

12. [] System program

13. [] Stake program

RemoveValidatorFromPool

Removes a validator from the stake pool.

RemoveValidatorFromPool

Accounts (8):

1. [w] Stake pool

2. [s] Staker

3. [] Withdraw authority

4. [w] Validator list

5. [w] Validator stake account

6. [w] Transient stake account

7. [] Clock sysvar

8. [] Stake program

IncreaseValidatorStake

Increases stake on a validator from the reserve.

IncreaseValidatorStake {
    lamports: u64,
    transient_stake_seed: u64,
}

Accounts (14):

1. [] Stake pool

2. [s] Staker

3. [] Withdraw authority

4. [w] Validator list

5. [w] Reserve stake

6. [w] Transient stake account

7. [] Validator stake account

8. [] Validator vote account

9. [] Clock sysvar

10. [] Rent sysvar

11. [] Stake history sysvar

12. [] Stake config sysvar

13. [] System program

14. [] Stake program

User Operations Instructions

DepositSol

Deposits tokens into the pool's reserve.

DepositSol(u64)  // Amount in lamports

Accounts (11):

1. [w] Stake pool

2. [] Withdraw authority

3. [w] Reserve stake account

4. [s] Funding account

5. [w] Destination pool token account

6. [w] Manager fee account

7. [w] Referrer pool token account

8. [w] Pool token mint

9. [] System program

10. [] Token program

11. [s] (Optional) tokens deposit authority

WithdrawSol

Withdraws tokens from the pool's reserve.

WithdrawSol(u64)  // Pool tokens to burn

Accounts (13):

1. [w] Stake pool

2. [] Withdraw authority

3. [s] User transfer authority

4. [w] Source pool token account

5. [w] Reserve stake account

6. [w] Destination system account

7. [w] Manager fee account

8. [w] Pool token mint

9. [] Clock sysvar

10. [] Stake history sysvar

11. [] Stake program

12. [] Token program

13. [s] (Optional) tokens withdraw authority

DepositWsolWithSession

Deposits wrapped SOL (WSOL) into the pool using a session token (FOGO blockchain specific).

DepositWsolWithSession {
    amount: u64,  // Amount in lamports
}

Accounts (12):

1. [w] Stake pool

2. [] Withdraw authority

3. [w] Reserve stake account

4. [s] Session authority

5. [w] User pool token account

6. [w] Manager fee account

7. [w] Referrer pool token account

8. [w] Pool token mint

9. [] System program

10. [] Token program

11. [] Session token account

12. [s] User wallet (payer)

Description: Enables gasless deposits on FOGO blockchain using session tokens. Session authority signs on behalf of users for improved UX.

WithdrawWsolWithSession

Withdraws wrapped SOL (WSOL) from the pool using a session token (FOGO blockchain specific).

WithdrawWsolWithSession {
    amount: u64,  // Pool tokens to burn
}

Accounts (13):

1. [w] Stake pool

2. [] Withdraw authority

3. [s] Session authority

4. [w] User pool token account

5. [w] Reserve stake account

6. [w] Destination WSOL account

7. [w] Manager fee account

8. [w] Pool token mint

9. [] Clock sysvar

10. [] Stake history sysvar

11. [] Stake program

12. [] Token program

13. [] Session token account

Description: Enables gasless withdrawals on FOGO blockchain using session tokens. Session authority validates and processes withdrawals without requiring individual wallet signatures.

DepositStake

Deposits a stake account into the pool.

DepositStake

Accounts (15):

1. [w] Stake pool

2. [w] Validator list

3. [s]/[] Deposit authority

4. [] Withdraw authority

5. [w] Stake account to deposit

6. [w] Validator stake account

7. [w] Reserve stake account

8. [w] Destination pool token account

9. [w] Manager fee account

10. [w] Referrer pool token account

11. [w] Pool token mint

12. [] Clock sysvar

13. [] Stake history sysvar

14. [] Token program

15. [] Stake program

WithdrawStake

Withdraws stake from the pool.

WithdrawStake(u64)  // Pool tokens to burn

Accounts (13):

1. [w] Stake pool

2. [w] Validator list

3. [] Withdraw authority

4. [w] Source validator/reserve stake

5. [w] Destination stake account

6. [] New stake authority

7. [s] User transfer authority

8. [w] Source pool token account

9. [w] Manager fee account

10. [w] Pool token mint

11. [] Clock sysvar

12. [] Token program

13. [] Stake program

Maintenance Instructions

UpdateValidatorListBalance

Updates validator balances and processes transient stakes.

UpdateValidatorListBalance {
    start_index: u32,
    no_merge: bool,
}

Accounts (7 + 2N):

1. [] Stake pool

2. [] Withdraw authority

3. [w] Validator list

4. [w] Reserve stake

5. [] Clock sysvar

6. [] Stake history sysvar

7. [] Stake program

8. [] N pairs of (validator stake, transient stake)

UpdateStakePoolBalance

Updates the pool's total balance.

UpdateStakePoolBalance

Accounts (7):

1. [w] Stake pool

2. [] Withdraw authority

3. [w] Validator list

4. [] Reserve stake

5. [w] Manager fee account

6. [w] Pool token mint

7. [] Token program

TypeScript SDK API

Installation

npm install @solana/spl-stake-pool @solana/web3.js @solana/spl-token

Core Functions

getStakePoolAccount

async function getStakePoolAccount(
  connection: Connection,
  stakePoolAddress: PublicKey
): Promise<StakePoolAccount>

Retrieves and deserializes a stake pool account.

Parameters:

• connection: FOGO RPC connection

• stakePoolAddress: Stake pool public key

Returns:

• StakePoolAccount: Object containing pubkey and decoded account data

Example:

const pool = await getStakePoolAccount(connection, poolPubkey);
console.log('Total lamports:', pool.account.data.totalLamports);

getStakePoolAccounts

async function getStakePoolAccounts(
  connection: Connection,
  stakePoolProgramAddress: PublicKey
): Promise<(StakePoolAccount | ValidatorListAccount | undefined)[]>

Retrieves all stake pool and validator list accounts.

Parameters:

• connection: FOGO RPC connection

• stakePoolProgramAddress: Program ID

Returns:

• Array of stake pool and validator list accounts

depositSol

async function depositSol(
  connection: Connection,
  stakePoolAddress: PublicKey,
  from: PublicKey,
  lamports: number,
  destinationTokenAccount?: PublicKey,
  referrerTokenAccount?: PublicKey,
  depositAuthority?: PublicKey
): Promise<{ instructions: TransactionInstruction[], signers: Signer[] }>

Creates instructions for tokens deposit.

Parameters:

• connection: FOGO RPC connection

• stakePoolAddress: Stake pool public key

• from: Source tokens account

• lamports: Amount to deposit in lamports

• destinationTokenAccount: Pool token destination (optional)

• referrerTokenAccount: Referrer token account (optional)

• depositAuthority: Required deposit authority (optional)

Returns:

• Object with transaction instructions and required signers

withdrawSol

async function withdrawSol(
  connection: Connection,
  stakePoolAddress: PublicKey,
  tokenOwner: PublicKey,
  solReceiver: PublicKey,
  amount: number,
  solWithdrawAuthority?: PublicKey
): Promise<{ instructions: TransactionInstruction[], signers: Signer[] }>

Creates instructions for tokens withdrawal.

Parameters:

• connection: FOGO RPC connection

• stakePoolAddress: Stake pool public key

• tokenOwner: Pool token owner

• solReceiver: tokens destination account

• amount: Pool tokens to burn

• solWithdrawAuthority: Required withdraw authority (optional)

Returns:

• Object with transaction instructions and required signers

depositWsolWithSession

async function depositWsolWithSession(
  connection: Connection,
  stakePoolAddress: PublicKey,
  sessionAuthority: PublicKey,
  userTokenAccount: PublicKey,
  amount: number,
  referrerTokenAccount?: PublicKey
): Promise<{ instructions: TransactionInstruction[], signers: Signer[] }>

Creates instructions for WSOL deposit using FOGO session tokens (gasless transaction).

Parameters:

• connection: FOGO RPC connection

• stakePoolAddress: Stake pool public key

• sessionAuthority: Session token authority

• userTokenAccount: User's pool token account

• amount: Amount of WSOL to deposit in lamports

• referrerTokenAccount: Referrer token account (optional)

Returns:

• Object with transaction instructions and required signers

Description: This function enables gasless deposits on FOGO blockchain by leveraging session tokens. The session authority signs transactions on behalf of users, providing a seamless UX without requiring wallet signatures for each transaction.

withdrawWsolWithSession

async function withdrawWsolWithSession(
  connection: Connection,
  stakePoolAddress: PublicKey,
  sessionAuthority: PublicKey,
  userTokenAccount: PublicKey,
  wsolReceiver: PublicKey,
  amount: number
): Promise<{ instructions: TransactionInstruction[], signers: Signer[] }>

Creates instructions for WSOL withdrawal using FOGO session tokens (gasless transaction).

Parameters:

• connection: FOGO RPC connection

• stakePoolAddress: Stake pool public key

• sessionAuthority: Session token authority

• userTokenAccount: User's pool token account

• wsolReceiver: Destination WSOL account

• amount: Pool tokens to burn

Returns:

• Object with transaction instructions and required signers

Description: This function enables gasless withdrawals on FOGO blockchain by leveraging session tokens. The session authority validates and processes withdrawals, allowing users to unstake without signing individual transactions.

depositStake

async function depositStake(
  connection: Connection,
  stakePoolAddress: PublicKey,
  authorizedPubkey: PublicKey,
  validatorVote: PublicKey,
  depositStake: PublicKey,
  poolTokenReceiverAccount?: PublicKey
): Promise<{ instructions: TransactionInstruction[], signers: Signer[] }>

Creates instructions for stake account deposit.

withdrawStake

async function withdrawStake(
  connection: Connection,
  stakePoolAddress: PublicKey,
  tokenOwner: PublicKey,
  amount: number,
  useReserve?: boolean,
  voteAccountAddress?: PublicKey,
  stakeReceiver?: PublicKey,
  poolTokenAccount?: PublicKey,
  validatorComparator?: (a: ValidatorAccount, b: ValidatorAccount) => number
): Promise<{
  instructions: TransactionInstruction[],
  signers: Signer[],
  stakeReceiver: PublicKey,
  totalRentFreeBalances: number
}>

Creates instructions for stake withdrawal.

Validator Management Functions

addValidatorToPool

async function addValidatorToPool(
  connection: Connection,
  stakePoolAddress: PublicKey,
  validatorVote: PublicKey,
  seed?: number
): Promise<{ instructions: TransactionInstruction[] }>

removeValidatorFromPool

async function removeValidatorFromPool(
  connection: Connection,
  stakePoolAddress: PublicKey,
  validatorVote: PublicKey,
  seed?: number
): Promise<{ instructions: TransactionInstruction[] }>

increaseValidatorStake

async function increaseValidatorStake(
  connection: Connection,
  stakePoolAddress: PublicKey,
  validatorVote: PublicKey,
  lamports: number,
  ephemeralStakeSeed?: number
): Promise<{ instructions: TransactionInstruction[] }>

decreaseValidatorStake

async function decreaseValidatorStake(
  connection: Connection,
  stakePoolAddress: PublicKey,
  validatorVote: PublicKey,
  lamports: number,
  ephemeralStakeSeed?: number
): Promise<{ instructions: TransactionInstruction[] }>

Pool Information Functions

stakePoolInfo

async function stakePoolInfo(
  connection: Connection,
  stakePoolAddress: PublicKey
): Promise<StakePoolInfo>

Retrieves comprehensive stake pool information.

Returns:

interface StakePoolInfo {
  address: string;
  poolWithdrawAuthority: string;
  manager: string;
  staker: string;
  stakeDepositAuthority: string;
  maxValidators: number;
  validatorList: ValidatorInfo[];
  poolMint: string;
  totalLamports: string;
  poolTokenSupply: string;
  lastUpdateEpoch: string;
  fees: {
    epochFee: Fee;
    stakeDepositFee: Fee;
    stakeWithdrawalFee: Fee;
    solDepositFee: Fee;
    solWithdrawalFee: Fee;
  };
  details: {
    reserveStakeLamports: number;
    stakeAccounts: StakeAccountInfo[];
    totalPoolTokens: number;
    currentNumberOfValidators: number;
    updateRequired: boolean;
  };
}

updateStakePool

async function updateStakePool(
  connection: Connection,
  stakePool: StakePoolAccount,
  noMerge?: boolean
): Promise<{
  updateListInstructions: TransactionInstruction[],
  finalInstructions: TransactionInstruction[]
}>

Creates all instructions needed to update a stake pool.

Utility Functions

lamportsToSol / solToLamports

function lamportsToSol(lamports: number): number
function solToLamports(sol: number): number

Convert between tokens and lamports.

calcLamportsWithdrawAmount

function calcLamportsWithdrawAmount(
  stakePool: StakePool,
  poolTokens: BN
): BN

Calculate tokens amount for given pool tokens.

Constants

// Program IDs
export const STAKE_POOL_PROGRAM_ID: PublicKey;
export const DEVNET_STAKE_POOL_PROGRAM_ID: PublicKey;

// Limits
export const MAX_VALIDATORS_TO_UPDATE = 4;
export const MINIMUM_ACTIVE_STAKE = 1_000_000;

Common Error Solutions

Error	Cause	Solution
StakeListOutOfDate	Validator list needs update	Run update-validator-list-balance
ValidatorAlreadyAdded	Validator already in pool	Check validator list before adding
FeeTooHigh	Fee numerator >= denominator	Set reasonable fee values
WithdrawTooLarge	Insufficient pool balance	Check available withdrawal amount
CalculationFailure	Math overflow	Use reasonable amounts