API Version: v1.6.0

CCIP v1.6.0 SVM Base Token Pool Library Reference

Base Token Pool Library

The Base Token Pool library provides foundational components and shared functionality for CCIP token pool implementations on SVM-based blockchains. This library is not deployable as a standalone program but serves as a dependency for concrete token pool implementations like BurnMint and Lock-Release pools.

Core Components

The Base Token Pool library provides several key modules:

Common Module (common.rs)

Contains shared data structures, constants, validation functions, and events used across all token pool implementations.

Rate Limiter Module (rate_limiter.rs)

Implements token bucket rate limiting functionality to control cross-chain transfer rates.

Data Structures

Core Configuration Structures

BaseConfig

The fundamental configuration structure used by all token pools.

pub struct BaseConfig {
    // Token configuration
    pub token_program: Pubkey,      // SPL Token or Token-2022 program ID
    pub mint: Pubkey,               // Token mint address
    pub decimals: u8,               // Token decimals
    pub pool_signer: Pubkey,        // Pool signer PDA
    pub pool_token_account: Pubkey, // Pool's associated token account

    // Ownership and administration
    pub owner: Pubkey,              // Current pool owner
    pub proposed_owner: Pubkey,     // Proposed new owner (for ownership transfer)
    pub rate_limit_admin: Pubkey,   // Rate limit administrator

    // CCIP integration
    pub router_onramp_authority: Pubkey, // Router's onramp authority PDA
    pub router: Pubkey,                  // CCIP Router program address
    pub rmn_remote: Pubkey,              // RMN Remote program address

    // Lock-Release specific (unused in BurnMint pools)
    pub rebalancer: Pubkey,         // Rebalancer address for liquidity management
    pub can_accept_liquidity: bool, // Whether pool accepts liquidity operations

    // Access control
    pub list_enabled: bool,         // Whether allowlist is enabled
    pub allow_list: Vec<Pubkey>,    // Allowlisted addresses for pool operations
}

Key Methods:

  • init(): Initializes BaseConfig with default values
  • transfer_ownership(): Proposes ownership transfer
  • accept_ownership(): Accepts proposed ownership transfer
  • set_router(): Updates router address and derives new onramp authority
  • set_rmn(): Updates RMN remote address
  • set_rebalancer(): Sets rebalancer address (Lock-Release pools only)
  • set_can_accept_liquidity(): Enables/disables liquidity operations
BaseChain

Configuration for a specific remote chain destination.

pub struct BaseChain {
    pub remote: RemoteConfig,                    // Remote chain token and pool configuration
    pub inbound_rate_limit: RateLimitTokenBucket,  // Rate limiting for incoming transfers
    pub outbound_rate_limit: RateLimitTokenBucket, // Rate limiting for outgoing transfers
}

Key Methods:

  • set(): Updates remote chain configuration
  • append_remote_pool_addresses(): Adds remote pool addresses
  • set_chain_rate_limit(): Configures rate limits for the chain
RemoteConfig

Configuration for tokens and pools on remote chains.

pub struct RemoteConfig {
    pub pool_addresses: Vec<RemoteAddress>, // Remote pool addresses (supports multiple versions)
    pub token_address: RemoteAddress,       // Remote token address
    pub decimals: u8,                       // Remote token decimals
}
RemoteAddress

Represents an address on a remote chain (supports various address formats).

pub struct RemoteAddress {
    pub address: Vec<u8>, // Address bytes (max 64 bytes)
}

Cross-Chain Transfer Structures

LockOrBurnInV1

Input parameters for locking or burning tokens (source chain operation).

pub struct LockOrBurnInV1 {
    pub receiver: Vec<u8>,           // Recipient address on destination chain
    pub remote_chain_selector: u64, // Destination chain ID
    pub original_sender: Pubkey,     // Original transaction sender
    pub amount: u64,                 // Amount to lock/burn (local decimals)
    pub local_token: Pubkey,         // Local token mint address
    pub msg_total_nonce: u64,        // Message nonce from onramp
}
LockOrBurnOutV1

Output from lock or burn operations.

pub struct LockOrBurnOutV1 {
    pub dest_token_address: RemoteAddress, // Remote token address
    pub dest_pool_data: Vec<u8>,           // ABI-encoded local token decimals
}
ReleaseOrMintInV1

Input parameters for releasing or minting tokens (destination chain operation).

pub struct ReleaseOrMintInV1 {
    pub original_sender: RemoteAddress,   // Original sender on source chain
    pub remote_chain_selector: u64,      // Source chain ID
    pub receiver: Pubkey,                 // Token recipient on this chain
    pub amount: [u8; 32],                 // Amount in source decimals (u256)
    pub local_token: Pubkey,              // Local token mint address
    pub source_pool_address: RemoteAddress, // Source pool address (must be validated)
    pub source_pool_data: Vec<u8>,        // Data from source pool
    pub offchain_token_data: Vec<u8>,     // Untrusted offchain data
}
ReleaseOrMintOutV1

Output from release or mint operations.

pub struct ReleaseOrMintOutV1 {
    pub destination_amount: u64, // Amount released/minted (local decimals)
}

Rate Limiting

The library provides comprehensive rate limiting functionality using a token bucket algorithm.

RateLimitTokenBucket

Implements rate limiting for cross-chain transfers.

pub struct RateLimitTokenBucket {
    pub tokens: u64,       // Current tokens in bucket
    pub last_updated: u64, // Last refill timestamp
    cfg: RateLimitConfig,  // Rate limit configuration
}

Key Methods:

  • consume<C: Timestamper>(): Attempts to consume tokens from bucket
  • set_token_bucket_config(): Updates rate limit configuration

RateLimitConfig

Configuration for rate limiting behavior.

pub struct RateLimitConfig {
    pub enabled: bool,  // Whether rate limiting is enabled
    pub capacity: u64,  // Maximum tokens in bucket
    pub rate: u64,      // Tokens per second refill rate
}

Validation Rules:

  • When enabled: rate < capacity and rate != 0
  • When disabled: rate == 0 and capacity == 0

Constants and Seeds

The library defines critical constants used for PDA derivation across all pool implementations:

// PDA Seeds
pub const POOL_CHAINCONFIG_SEED: &[u8] = b"ccip_tokenpool_chainconfig";
pub const POOL_STATE_SEED: &[u8] = b"ccip_tokenpool_config";
pub const POOL_SIGNER_SEED: &[u8] = b"ccip_tokenpool_signer";
pub const CONFIG_SEED: &[u8] = b"config";

// Router Integration
pub const EXTERNAL_TOKEN_POOLS_SIGNER: &[u8] = b"external_token_pools_signer";
pub const ALLOWED_OFFRAMP: &[u8] = b"allowed_offramp";

// Other Constants
pub const ANCHOR_DISCRIMINATOR: usize = 8;

Validation Functions

The library provides critical validation functions that ensure security and correctness of cross-chain operations.

validate_lock_or_burn

Validates parameters for locking or burning tokens on the source chain.

pub fn validate_lock_or_burn<'info>(
    lock_or_burn_in: &LockOrBurnInV1,
    config_mint: Pubkey,
    outbound_rate_limit: &mut RateLimitTokenBucket,
    allow_list_enabled: bool,
    allow_list: &[Pubkey],
    rmn_remote: AccountInfo<'info>,
    rmn_remote_curses: AccountInfo<'info>,
    rmn_remote_config: AccountInfo<'info>,
) -> Result<()>

Validation Checks:

  1. Token Validation: Ensures local_token matches the pool's configured mint
  2. Allowlist Check: Validates original_sender is allowlisted (if enabled)
  3. Curse Check: Verifies destination chain is not cursed via RMN Remote CPI
  4. Rate Limiting: Consumes tokens from outbound rate limit bucket

validate_release_or_mint

Validates parameters for releasing or minting tokens on the destination chain.

pub fn validate_release_or_mint<'info>(
    release_or_mint_in: &ReleaseOrMintInV1,
    parsed_amount: u64,
    config_mint: Pubkey,
    pool_addresses: &[RemoteAddress],
    inbound_rate_limit: &mut RateLimitTokenBucket,
    rmn_remote: AccountInfo<'info>,
    rmn_remote_curses: AccountInfo<'info>,
    rmn_remote_config: AccountInfo<'info>,
) -> Result<()>

Validation Checks:

  1. Token Validation: Ensures local_token matches the pool's configured mint
  2. Source Pool Validation: Verifies source_pool_address is in the configured pool addresses list
  3. Curse Check: Verifies source chain is not cursed via RMN Remote CPI
  4. Rate Limiting: Consumes tokens from inbound rate limit bucket

verify_uncursed_cpi

Performs CPI to RMN Remote to verify a chain is not cursed.

pub fn verify_uncursed_cpi<'info>(
    rmn_remote: AccountInfo<'info>,
    rmn_remote_config: AccountInfo<'info>,
    rmn_remote_curses: AccountInfo<'info>,
    chain_selector: u64,
) -> Result<()>

Utility Functions

to_svm_token_amount

Converts cross-chain token amounts to local SVM amounts, handling decimal differences.

pub fn to_svm_token_amount(
    incoming_amount_bytes: [u8; 32], // LE encoded u256 from source chain
    incoming_decimal: u8,            // Source token decimals
    local_decimal: u8,               // Local token decimals
) -> Result<u64>

Conversion Logic:

  • More incoming decimals: Divides by 10^(incoming_decimal - local_decimal)
  • Fewer incoming decimals: Multiplies by 10^(local_decimal - incoming_decimal)
  • Equal decimals: No conversion needed
  • Overflow protection: Validates result fits in u64

Account Meta Utilities

CcipAccountMeta

Serializable version of Solana's AccountMeta for cross-program communication.

pub struct CcipAccountMeta {
    pub pubkey: Pubkey,
    pub is_signer: bool,
    pub is_writable: bool,
}

ToMeta Trait

Provides convenient methods for creating CcipAccountMeta instances.

pub trait ToMeta {
    fn readonly(self) -> CcipAccountMeta;
    fn writable(self) -> CcipAccountMeta;
    fn signer(self) -> CcipAccountMeta;
}

Error Types

The library defines comprehensive error types used across all pool implementations:

pub enum CcipTokenPoolError {
    // Authorization errors
    InvalidInitPoolPermissions,
    Unauthorized,
    InvalidPoolCaller,

    // Configuration errors
    InvalidInputs,
    InvalidVersion,
    InvalidRMNRemoteAddress,

    // Token operation errors
    InvalidSender,
    InvalidSourcePoolAddress,
    InvalidToken,
    InvalidTokenAmountConversion,

    // Allowlist errors
    AllowlistKeyAlreadyExisted,
    AllowlistKeyDidNotExist,

    // Remote pool errors
    RemotePoolAddressAlreadyExisted,
    NonemptyPoolAddressesInit,

    // Rate limiting errors (RL prefix)
    RLBucketOverfilled,
    RLMaxCapacityExceeded,
    RLRateLimitReached,
    RLInvalidRateLimitRate,
    RLDisabledNonZeroRateLimit,

    // Lock-Release specific errors
    LiquidityNotAccepted,
    TransferZeroTokensNotAllowed,

    // Other
    InvalidDerivationStage,
}

Events

The library defines events that are emitted by pool implementations. See the Events API Reference for detailed documentation of all events including:

  • Configuration events (GlobalConfigUpdated, RemoteChainConfigured, etc.)
  • Token operation events (Burned, Minted, Locked, Released)
  • Administrative events (OwnershipTransferred, RouterUpdated, etc.)
  • Rate limiting events (TokensConsumed, ConfigChanged)

Usage by Pool Implementations

The Base Token Pool library is used by concrete pool implementations as follows:

Import Pattern

use base_token_pool::{
    common::*,
    rate_limiter::*,
};

Structure Embedding

Pool implementations embed base structures:

#[account]
#[derive(InitSpace)]
pub struct State {
    pub version: u8,
    pub config: BaseConfig,  // Embedded base configuration
}

#[account]
#[derive(InitSpace)]
pub struct ChainConfig {
    pub base: BaseChain,     // Embedded base chain configuration
}

Validation Integration

Pool operations call base validation functions:

// In lock_or_burn_tokens instruction
validate_lock_or_burn(
    &lock_or_burn,
    ctx.accounts.state.config.mint,
    &mut ctx.accounts.chain_config.base.outbound_rate_limit,
    ctx.accounts.state.config.list_enabled,
    &ctx.accounts.state.config.allow_list,
    ctx.accounts.rmn_remote.to_account_info(),
    ctx.accounts.rmn_remote_curses.to_account_info(),
    ctx.accounts.rmn_remote_config.to_account_info(),
)?;

This shared foundation ensures consistency, security, and maintainability across all CCIP token pool implementations on SVM-based blockchains.

Get the latest Chainlink content straight to your inbox.