Program Architecture

This document provides a comprehensive overview of the Ignition Stake Pool system architecture, design decisions, and core concepts.

System Overview

The Ignition Stake Pool program implements a liquid staking protocol on FOGO blockchain, allowing users to pool their stake and receive liquid tokens in return. The system is designed for security, efficiency, and scalability while maintaining decentralization.

1

Core Components — On-Chain Program (program/)

The core FOGO blockchain program written in Rust that manages all stake pool operations.

Key Files

• lib.rs (Entry Point): Program constants, PDA derivation, core utilities

• instruction.rs: Complete instruction set with serialization

• processor.rs: Main business logic for all operations

• state.rs: State management and data structures

• error.rs: Custom error types and handling

• big_vec.rs: Efficient storage for large validator lists

• inline_mpl_token_metadata.rs: Token metadata handling

Program Architecture

For detailed field-level specifications, refer to the source code in program/src/state.rs.

2

Core Components — Program Derived Addresses (PDAs)

The system uses PDAs for secure authority management.

// Authority seeds defined in lib.rs
AUTHORITY_DEPOSIT = b"deposit"
AUTHORITY_WITHDRAW = b"withdraw"
TRANSIENT_STAKE_SEED_PREFIX = b"transient"
EPHEMERAL_STAKE_SEED_PREFIX = b"ephemeral"

PDA Structure:

Stake Pool Address + Seeds → PDA
├── [pool_address, "deposit"] → Deposit Authority
├── [pool_address, "withdraw"] → Withdraw Authority
├── [pool_address, "transient", validator, seed] → Transient Stake Account
└── [pool_address, "ephemeral", seed] → Ephemeral Stake Account

3

Core Components — Data Structures

The program maintains several key data structures:

• StakePool: Main pool account containing authorities, fees, and financial state

• ValidatorList: Efficiently stores validator information using BigVec implementation

• ValidatorStakeInfo: Tracks individual validator stake and performance

• Fee Structures: Manages various fee types and future epoch configurations

For detailed field-level specifications, refer to the source code in program/src/state.rs.

4

Core Components — Security Model

Fee Protection Mechanism

// Maximum 3/2 ratio increase per epoch prevents malicious fee increases
pub const MAX_WITHDRAWAL_FEE_INCREASE: Fee = Fee {
    numerator: 3,
    denominator: 2,
};

Key Security Features

• Authority Separation: Different authorities for different operations

• Fee Rate Limiting: Prevents sudden fee increases that could harm users

• PDA Security: All critical authorities use program-derived addresses

• Transient Account Limits: Maximum 10 transient operations per transaction

• Minimum Stake Requirements: 1,000,000 lamports minimum per validator

Compute Budget Management

pub const MAX_VALIDATORS_TO_UPDATE: usize = 4;  // Per instruction limit

Transaction Flow Architecture

1

Deposit Flow

User tokens/Stake → Validation → Pool Integration → Token Minting

Steps:

• Prepare Account & Funds

• Verify Authorities & Amounts

• Update Pool State & Balances

• Issue Pool Tokens to User

2

Withdrawal Flow

Pool Tokens → Validation → Stake Preparation → tokens Transfer

Steps:

• Burn Tokens & Fees

• Check Balances & Permissions

• Deactivate Stake or Use Reserve

• Transfer tokens from Reserve