Token Transfer

The Token Transfer example demonstrates how to work with custom token accounts in Ephemeral Rollups. While this example uses a simple balance account for clarity, the same patterns apply to SPL tokens, allowing you to build high-frequency token operations with ultra-low latency.

Overview

This example shows:

Creating and delegating balance accounts
Transferring tokens between accounts in ERs
Configurable delegation parameters
Committing and undelegating accounts

While this example uses a simple Balance account, the same delegation patterns work with SPL Token Accounts for real token transfers.

How It Works

Initialize Balance Accounts

Each user has a balance account (PDA) seeded by their public key:

pub fn initialize(ctx: Context<Initialize>) -> Result<()> {
    let acc = &mut ctx.accounts.balance;
    acc.balance = 100;
    Ok()
}

#[derive(Accounts)]
pub struct Initialize<'info> {
    #[account(init, payer = user, space = 8 + 8, seeds = [user.key.as_ref()], bump)]
    pub balance: Account<'info, Balance>,
    #[account(mut)]
    pub user: Signer<'info>,
    pub system_program: Program<'info, System>,
}

#[account]
pub struct Balance {
    pub balance: u64,
}

Delegate with Custom Parameters

The delegation includes configurable parameters for commit frequency and validator selection:

pub fn delegate(ctx: Context<DelegateBalance>, params: DelegateParams) -> Result<()> {
    let config = DelegateConfig {
        commit_frequency_ms: params.commit_frequency_ms,
        validator: params.validator,
    };

    ctx.accounts.delegate_balance(
        &ctx.accounts.payer,
        &[ctx.accounts.payer.key.as_ref()],
        config,
    )?;
    Ok()
}

#[delegate]
#[derive(Accounts)]
pub struct DelegateBalance<'info> {
    #[account(mut)]
    pub payer: Signer<'info>,
    #[account(mut, del, seeds = [payer.key.as_ref()], bump)]
    pub balance: AccountInfo<'info>,
}

#[derive(AnchorSerialize, AnchorDeserialize, Clone)]
pub struct DelegateParams {
    pub commit_frequency_ms: u32,
    pub validator: Option<Pubkey>,
}

Transfer Between Accounts

Once delegated, transfers execute with ultra-low latency in the ER:

pub fn transfer(ctx: Context<Transfer>, amount: u64) -> Result<()> {
    let balance = &mut ctx.accounts.balance;
    let receiver_balance = &mut ctx.accounts.receiver_balance;
    if balance.balance < amount {
        return Err(error!(ErrorCode::InsufficientBalance));
    }
    balance.balance -= amount;
    receiver_balance.balance += amount;
    Ok()
}

#[derive(Accounts)]
pub struct Transfer<'info> {
    #[account(mut)]
    pub payer: Signer<'info>,
    #[account(mut, seeds = [payer.key.as_ref()], bump)]
    pub balance: Account<'info, Balance>,
    /// CHECK: anyone can receive the tokens
    pub receiver: AccountInfo<'info>,
    #[account(init_if_needed, payer = payer, space = 8 + 8, seeds = [receiver.key.as_ref()], bump)]
    pub receiver_balance: Account<'info, Balance>,
    pub system_program: Program<'info, System>,
}

#[error_code]
pub enum ErrorCode {
    #[msg("Insufficient balance for transfer")]
    InsufficientBalance,
}

Undelegate and Commit

When you’re done with high-frequency operations, undelegate to commit final state:

pub fn undelegate(ctx: Context<UndelegateBalance>) -> Result<()> {
    commit_and_undelegate_accounts(
        &ctx.accounts.payer,
        vec![&ctx.accounts.balance.to_account_info()],
        &ctx.accounts.magic_context,
        &ctx.accounts.magic_program,
    )?;
    Ok()
}

#[commit]
#[derive(Accounts)]
pub struct UndelegateBalance<'info> {
    #[account(mut)]
    pub payer: Signer<'info>,
    #[account(mut, seeds = [payer.key.as_ref()], bump)]
    pub balance: Account<'info, Balance>,
}

Program Annotations

The program uses the #[ephemeral] macro to enable ER support:

programs/dummy-transfer/src/lib.rs

use ephemeral_rollups_sdk::anchor::{commit, delegate, ephemeral};
use ephemeral_rollups_sdk::cpi::DelegateConfig;
use ephemeral_rollups_sdk::ephem::commit_and_undelegate_accounts;

#[ephemeral]
#[program]
pub mod dummy_transfer {
    use super::*;
    // ... program code
}

Delegation Configuration

DelegateConfig {
    commit_frequency_ms: 30000, // Commit every 30 seconds
    validator: None,
}

Set commit_frequency_ms based on your use case:

Gaming: 10-30 seconds for responsive state updates
Trading: 5-10 seconds for more frequent commits
High-value operations: Lower values for more frequent base layer syncs

Complete Flow Example

import { Program } from "@coral-xyz/anchor";
import { PublicKey } from "@solana/web3.js";

// 1. Initialize balance account on base layer
const initTx = await program.methods
  .initialize()
  .accounts({
    user: wallet.publicKey,
  })
  .rpc();

// 2. Delegate to ER with custom config
const delegateTx = await program.methods
  .delegate({
    commitFrequencyMs: 30000,
    validator: null,
  })
  .accounts({
    payer: wallet.publicKey,
  })
  .rpc();

// 3. Perform rapid transfers in ER
for (let i = 0; i < 100; i++) {
  await program.methods
    .transfer(new BN(1))
    .accounts({
      payer: wallet.publicKey,
      receiver: recipientPublicKey,
    })
    .rpc(); // Ultra-low latency in ER!
}

// 4. Undelegate and commit final state
const undelegateTx = await program.methods
  .undelegate()
  .accounts({
    payer: wallet.publicKey,
  })
  .rpc();

SPL Token Integration

To use this pattern with real SPL tokens:

Add SPL Token Dependencies

[dependencies]
anchor-spl = "0.32.1"
spl-token = "6.0.0"

Update Account Structure

Replace the Balance account with SPL Token Account:

use anchor_spl::token::{Token, TokenAccount};

#[derive(Accounts)]
pub struct Transfer<'info> {
    #[account(mut)]
    pub authority: Signer<'info>,
    #[account(
        mut,
        associated_token::mint = mint,
        associated_token::authority = authority
    )]
    pub from: Account<'info, TokenAccount>,
    #[account(
        mut,
        associated_token::mint = mint,
        associated_token::authority = to_authority
    )]
    pub to: Account<'info, TokenAccount>,
    pub mint: Account<'info, Mint>,
    pub token_program: Program<'info, Token>,
}

Delegate Token Accounts

pub fn delegate_token_account(ctx: Context<DelegateTokenAccount>) -> Result<()> {
    ctx.accounts.delegate_pda(
        &ctx.accounts.payer,
        &[], // Token accounts don't use seeds
        DelegateConfig::default(),
    )?;
    Ok()
}

What Makes This Advanced?

This example demonstrates:

Custom Delegation Parameters: Fine-grained control over commit frequency and validator selection
Multi-Account Operations: Transferring between multiple delegated accounts
Init-If-Needed Pattern: Automatically creating receiver accounts during transfers
Error Handling: Proper balance validation with custom errors
PDA Management: Using PDAs for user-specific balance accounts

Use Cases

Gaming
DeFi
Social

In-game currency transfers
Rapid item trading between players
Reward distributions
Marketplace transactions

Performance Benefits

Compared to base layer token transfers:

Latency: ~400ms → ~10ms (40x faster)
Cost: ~0.000005 SOL → negligible in ER
Throughput: Thousands of transfers per second
Batching: Execute 100s of transfers before committing

Testing Locally

Install the Local Validator

npm install -g @magicblock-labs/ephemeral-validator

Start the Local Validator

ACCOUNTS_REMOTE=https://rpc.magicblock.app/devnet ACCOUNTS_LIFECYCLE=ephemeral ephemeral-validator

Run Tests

PROVIDER_ENDPOINT=http://localhost:8899 WS_ENDPOINT=ws://localhost:8900 anchor test --skip-build --skip-deploy --skip-local-validator

Testing on Devnet

To run tests on devnet:

anchor test --skip-local-validator --skip-build --skip-deploy

Make sure you have devnet SOL in your wallet before running devnet tests.

Security Considerations

Important:

Always validate account ownership before transfers
Check sufficient balance before debiting
Use proper PDA derivation for user accounts
Set appropriate commit frequencies for your use case
Monitor delegated account states

Adapting for Real Tokens

The key differences when using SPL tokens:

Account Type: TokenAccount instead of custom Balance
Authority: Token account authority, not PDA seeds
Transfer Logic: Use SPL token CPI instead of direct balance updates
Mint Validation: Ensure all accounts use the same mint

Example SPL transfer in ER:

use anchor_spl::token;

pub fn transfer_tokens(ctx: Context<TransferTokens>, amount: u64) -> Result<()> {
    token::transfer(
        CpiContext::new(
            ctx.accounts.token_program.to_account_info(),
            token::Transfer {
                from: ctx.accounts.from.to_account_info(),
                to: ctx.accounts.to.to_account_info(),
                authority: ctx.accounts.authority.to_account_info(),
            },
        ),
        amount,
    )?;
    Ok()
}

This transfer executes in the ER with the same ultra-low latency as the balance example!

Next Steps

Explore Session Keys for gasless token transfers
Learn about Magic Actions to trigger base layer logic on commit
Check out SPL Token documentation for working with real tokens
Review the full source code

Getting Started

Core Concepts

Framework Examples

Advanced Examples

Development

Token Transfer

Token Transfer

Overview

How It Works

Program Annotations

Delegation Configuration

Complete Flow Example

SPL Token Integration

What Makes This Advanced?

Use Cases

Performance Benefits

Testing Locally

Testing on Devnet

Security Considerations

Adapting for Real Tokens

Next Steps

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Framework Examples

Advanced Examples

Development

Documentation Index

​Token Transfer

​Overview

​How It Works

​Program Annotations

​Delegation Configuration

​Complete Flow Example

​SPL Token Integration

​What Makes This Advanced?

​Use Cases

​Performance Benefits

​Testing Locally

​Testing on Devnet

​Security Considerations

​Adapting for Real Tokens

​Next Steps

Build docs developers (and LLMs) love

Token Transfer

Overview

How It Works

Program Annotations

Delegation Configuration

Complete Flow Example

SPL Token Integration

What Makes This Advanced?

Use Cases

Performance Benefits

Testing Locally

Testing on Devnet

Security Considerations

Adapting for Real Tokens

Next Steps