Quickstart

Any Solana program can be upgraded with Ephemeral Rollups by adding delegation capabilities.

---

Quick Access

Check out basic counter example:

GitHub

Anchor Implementation

GitHub

React Implementation

---

---

Step-By-Step Guide

The lifecycle of integrating Ephemeral Rollups in your program is as follows:

1. Write your program

   Write your Solana program as you normally would.

2. Add delegation and undelegation hooks in your program

   Add CPI hooks to delegate, commit and undelegate state accounts through Ephemeral Rollup sessions.

3. Deploy your program on Solana.

   Deploy your program directly on Solana using Anchor or Solana CLI.

4. Ready to execute transactions for delegation and real-time speed

   Send transactions without modifications on-chain and off-chain that also comply with the SVM RPC specification.

---

Counter Example

The following software packages may be required, other versions may also be compatible:

Software	Version	Installation Guide
Solana	2.3.13	Install Solana
Rust	1.85.0	Install Rust
Anchor	0.32.1	Install Anchor
Node	24.10.0	Install Node

Code Snippets

1. Write program

The program implements two main instructions:

1. initialize: Sets the counter to 0
2. increment: Increments the counter by 1

The program implements specific instructions for delegating and undelegating the counter:

1. Delegate: Delegates counter from Base Layer to ER (called on Base Layer)
2. CommitAndUndelegate: Schedules sync of counter from ER to Base Layer, and undelegates counter on ER (called on ER)
3. Commit: Schedules sync of counter from ER to Base Layer (called on ER)
4. Undelegate:
   • Schedules sync and undelegation of counter (called on ER)
   • Undelegation triggered through callback instruction injected through #[ephemeral] (called on Base Layer through validator CPI)

#[ephemeral]
#[program]
pub mod anchor_counter {
    use super::*;

    /// Initialize the counter.
    pub fn initialize(ctx: Context<Initialize>) -> Result<()> {
        let counter = &mut ctx.accounts.counter;
        counter.count = 0;
        Ok(())
    }

    /// Increment the counter.
    pub fn increment(ctx: Context<Increment>) -> Result<()> {
        let counter = &mut ctx.accounts.counter;
        counter.count += 1;
        Ok(())
    }

    /// Delegate the account to the delegation program
    /// Set specific validator based on ER, see https://docs.magicblock.gg/pages/get-started/how-integrate-your-program/local-setup
    pub fn delegate(ctx: Context<DelegateInput>) -> Result<()> {
    // ...
    }

    /// Increment the counter and manually commit the account in the Ephemeral Rollup session.
    pub fn increment_and_commit(ctx: Context<IncrementAndCommit>) -> Result<()> {
    // ...
    }

    /// Undelegate the account from the delegation program
    pub fn undelegate(ctx: Context<IncrementAndCommit>) -> Result<()> {
    // ...
    }
}

/// Context for initializing counter
#[derive(Accounts)]
pub struct Initialize<'info> {
    #[account(init_if_needed, payer = user, space = 8 + 8, seeds = [TEST_PDA_SEED], bump)]
    pub counter: Account<'info, Counter>,
    #[account(mut)]
    pub user: Signer<'info>,
    pub system_program: Program<'info, System>,
}


/// Context for incrementing counter
#[derive(Accounts)]
pub struct Increment<'info> {
    #[account(mut, seeds = [TEST_PDA_SEED], bump)]
    pub counter: Account<'info, Counter>,
}

/// Counter struct
#[account]
pub struct Counter {
    pub count: u64,
}

/// Other context for delegation

Nothing special here, just a simple Anchor program that increments a counter. The only difference is that we’re adding the ephemeral macro for undelegation and delegate macro to inject some useful logic to interact with the delegation program.

⬆️ Back to Top

2. Delegate

1. Add ephemeral-rollups-sdk with Anchor features to your program

cargo add ephemeral-rollups-sdk --features anchor

Import delegate, commit, ephemeral, DelegateConfig, commit_accounts and commit_and_undelegate_accounts:

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

2. Add delegate macro and instruction, ephemeral macro, and undelegate instruction to your program. Specify your preferred delegation config such as auto commits and specific ER validator:

/// Add delegate function to the context
#[delegate]
#[derive(Accounts)]
pub struct DelegateInput<'info> {
    pub payer: Signer<'info>,
    /// CHECK: Checked by the delegate program
    pub validator: Option<AccountInfo<'info>>,
    /// CHECK The pda to delegate
    #[account(mut, del)]
    pub pda: AccountInfo<'info>,
}

/// Delegate the account to the delegation program
/// Set specific validator based on ER, see https://docs.magicblock.gg/pages/get-started/how-integrate-your-program/local-setup
pub fn delegate(ctx: Context<DelegateInput>) -> Result<()> {
    ctx.accounts.delegate_pda(
        &ctx.accounts.payer,
        &[TEST_PDA_SEED],
        DelegateConfig {
            // Optionally set a specific validator from the first remaining account
            validator: ctx.remaining_accounts.first().map(|acc| acc.key()),
            ..Default::default()
        },
    )?;
    Ok(())
}

/// Increment the counter and manually commit the account in the Ephemeral Rollup session.
pub fn increment_and_commit(ctx: Context<IncrementAndCommit>) -> Result<()> {
    let counter = &mut ctx.accounts.counter;
    counter.count += 1;
    commit_accounts(
        &ctx.accounts.payer,
        vec![&ctx.accounts.counter.to_account_info()],
        &ctx.accounts.magic_context,
        &ctx.accounts.magic_program,
    )?;
    Ok(())
}

/// Undelegate the account from the delegation program
pub fn undelegate(ctx: Context<IncrementAndCommit>) -> Result<()> {
    commit_and_undelegate_accounts(
        &ctx.accounts.payer,
        vec![&ctx.accounts.counter.to_account_info()],
        &ctx.accounts.magic_context,
        &ctx.accounts.magic_program,
    )?;
    Ok(())
}

Delegation is the process of transferring ownership of one or more of your program’s PDAs to the delegation program. Ephemeral Validators will then be able to use the PDAs to perform transactions in the SVM runtime.

Commit is the process of updating the state of the PDAs from ER to the base layer. After the finalization process, the PDAs remain locked on base layer.

Undelegation is the process of transferring ownership of the PDAs back to your program. On undelegation, the state is committed and it trigger the finalization process. Once state it validated, the PDAs are unlocked and can be used as normal on base layer.

These public validators are supported for development. Make sure to add the specific ER validator account when delegating:

• Asia (devnet-as.magicblock.app): MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57

• EU (devnet-eu.magicblock.app): MEUGGrYPxKk17hCr7wpT6s8dtNokZj5U2L57vjYMS8e

• US (devnet-us.magicblock.app): MUS3hc9TCw4cGC12vHNoYcCGzJG1txjgQLZWVoeNHNd

• TEE (tee.magicblock.app): FnE6VJT5QNZdedZPnCoLsARgBwoE6DeJNjBs2H1gySXA

• Local ER (localhost): mAGicPQYBMvcYveUZA5F5UNNwyHvfYh5xkLS2Fr1mev

⬆️ Back to Top

3. Deploy

Now you’re program is upgraded and ready! Build and deploy to the desired cluster:

anchor build && anchor deploy

⬆️ Back to Top

4. Test

Ready to execute transactions for delegation and real-time speed.

These public validators are supported for development. Make sure to add the specific ER validator account when delegating:

• Asia (devnet-as.magicblock.app): MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57

• EU (devnet-eu.magicblock.app): MEUGGrYPxKk17hCr7wpT6s8dtNokZj5U2L57vjYMS8e

• US (devnet-us.magicblock.app): MUS3hc9TCw4cGC12vHNoYcCGzJG1txjgQLZWVoeNHNd

• TEE (tee.magicblock.app): FnE6VJT5QNZdedZPnCoLsARgBwoE6DeJNjBs2H1gySXA

• Local ER (localhost): mAGicPQYBMvcYveUZA5F5UNNwyHvfYh5xkLS2Fr1mev

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

Run the following test:

// Set ER Validator
const ER_VALIDATOR = new web3.PublicKey(
  "MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57"
); // Asia ER Validator

// Set Anchor providers
const provider = anchor.AnchorProvider.env();
anchor.setProvider(provider);
const providerEphemeralRollup = new anchor.AnchorProvider(
  new anchor.web3.Connection("https://devnet-as.magicblock.app/", {
    wsEndpoint: "wss://devnet.magicblock.app/",
  }),
  anchor.Wallet.local()
);

// Set program and pda
const program = anchor.workspace.AnchorCounter as Program<AnchorCounter>;
const [pda] = anchor.web3.PublicKey.findProgramAddressSync(
  [Buffer.from(SEED_TEST_PDA)],
  program.programId
);

// Initialize Counter on Base Layer
let initTx = await program.methods
  .increment()
  .accounts({
    counter: pda,
  })
  .transaction();
initTx.feePayer = provider.wallet.publicKey;
initTx.recentBlockhash = (
  await provider.connection.getLatestBlockhash()
).blockhash;
initTx = await provider.connection.signTransaction(initTx);
const dinitTxHash = await provider.sendAndConfirm(initTx);

// Delegate Counter on Base Layer to ER
let delTx = await program.methods
  .increment()
  .accounts({
    payer: provider.wallet.publicKey,
    validator: ER_VALIDATOR,
    pda: pda,
  })
  .transaction();
delTx.feePayer = provider.connection.wallet.publicKey;
delTx.recentBlockhash = (
  await provider.connection.getLatestBlockhash()
).blockhash;
delTx = await provider.wallet.signTransaction(delTx);
const delTxHash = await provider.sendAndConfirm(delTx);

// Increment Counter in real-time on ER
let incTx = await program.methods
  .increment()
  .accounts({
    counter: pda,
  })
  .transaction();
incTx.feePayer = providerEphemeralRollup.wallet.publicKey;
incTx.recentBlockhash = (
  await providerEphemeralRollup.connection.getLatestBlockhash()
).blockhash;
incTx = await providerEphemeralRollup.wallet.signTransaction(incTx);
const incTxHash = await providerEphemeralRollup.sendAndConfirm(incTx);

To make it easier to integrate via the frontend, we created the Magic Router. You send transactions directly to the magic router, and we can determine for you whether it should be routed to the Ephemeral Rollup or base layer.

These public RPC endpoints are currently free and supported for development:
Magic Router Devnet: https://devnet-router.magicblock.app
Solana Devnet: https://api.devnet.solana.com
ER Devnet: https://devnet.magicblock.app
TEE Devnet: https://tee.magicblock.app/
Find out more details here .

⬆️ Back to Top

---

Advanced Code Snippets

Resize PDA

When resizing a delegated PDA:

• PDA must have enough lamports to remain rent-exempt for the new account size.
• If additional lamports are needed, the payer account must be delegated to provide the difference.
• PDA must be owned by the program, and the transaction must include any signer(s) required for transferring lamports.
• Use system_instruction::allocate

#[account]
pub struct Counter {
    pub count: u64,
    pub extra_data: Vec<u8>,
}

#[derive(Accounts)]
pub struct ResizeCounter<'info> {
    #[account(mut)]
    pub counter: Account<'info, Counter>,
    #[account(mut)]
    pub payer: Signer<'info>,
    pub system_program: Program<'info, System>,
}

    // Resize the counter (e.g., to store more extra_data)
    pub fn resize_counter(ctx: Context<ResizeCounter>, new_size: usize) -> Result<()> {
        let account_to_resize = &mut ctx.accounts.counter.to_account_info();
        let payer = &mut ctx.accounts.payer.to_account_info();

        // Calculate rent-exemption for the new size
        let rent = Rent::get()?;
        let min_balance = rent.minimum_balance(new_size);

        // Top up lamports if needed
        let current_lamports = **account_to_resize.lamports.borrow();
        if current_lamports < min_balance {
            let to_transfer = min_balance - current_lamports;
            **payer.try_borrow_mut_lamports()? -= to_transfer;
            **account_to_resize.try_borrow_mut_lamports()? += to_transfer;
        }

        // Resize account
        account_to_resize.resize(new_size)?;

        Ok(())
    }

⬆️ Back to Top

Magic Router

Initialize connection with Magic Router before you send transactions dynamically.

These public RPC endpoints are currently free and supported for development:
Magic Router Devnet: https://devnet-router.magicblock.app

Choose your preferred SDK to initialize, send and confirm transactions:

• ephemeral-rollups-kit for @solana/kit
• ephemeral-rollups-sdk for @solana/web.js

kit

import { Connection } from "@magicblock-labs/ephemeral-rollups-kit";

// Initialize connection
const connection = await Connection.create(
  "https://devnet-router.magicblock.app",
  "wss://devnet-router.magicblock.app"
);

// ... create transaction

// Send and confirm transaction
const txHash = await connection.sendAndConfirmTransaction(
  transactionMessage,
  [userKeypair],
  { commitment: "confirmed", skipPreflight: true }
);

⬆️ Back to Top

Magic Action

Quick Access

Magic Actions Example

Explore reference implementation on GitHub

Attach one or more instructions that run automatically on the Solana base layer immediately after an Ephemeral Rollup (ER) commit. Learn more about Magic Action

1) Create action instruction

The instruction update_leaderboard runs on the base layer immediately after commit.

// program instruction
pub fn update_leaderboard(ctx: Context<UpdateLeaderboard>) -> Result<()> {
    let leaderboard = &mut ctx.accounts.leaderboard;
    let counter_info = &mut ctx.accounts.counter.to_account_info();
    let mut data: &[u8] = &counter_info.try_borrow_data()?;
    let counter = Counter::try_deserialize(&mut data)?;

    if counter.count > leaderboard.high_score {
        leaderboard.high_score = counter.count;
    }

    msg!(
        "Leaderboard updated! High score: {}",
        leaderboard.high_score
    );
    Ok(())
}

// instruction context
#[action]
#[derive(Accounts)]
pub struct UpdateLeaderboard<'info> {
    #[account(mut, seeds = [LEADERBOARD_SEED], bump)]
    pub leaderboard: Account<'info, Leaderboard>,
    /// CHECK: PDA owner depends on: 1) Delegated: Delegation Program; 2) Undelegated: Your program ID
    pub counter: UncheckedAccount<'info>,
}

2) Build the commit instruction with the action

The commit instruction commit_and_update_leaderboard runs on the ER and schedules the commit with action.

// commit action instruction on ER
pub fn commit_and_update_leaderboard(ctx: Context<CommitAndUpdateLeaderboard>) -> Result<()> {
    // Create action instruction
    let instruction_data =
        anchor_lang::InstructionData::data(&crate::instruction::UpdateLeaderboard {});
    let action_args = ActionArgs::new(instruction_data);
    let action_accounts = vec![
        ShortAccountMeta {
            pubkey: ctx.accounts.leaderboard.key(),
            is_writable: true,
        },
        ShortAccountMeta {
            pubkey: ctx.accounts.counter.key(),
            is_writable: false,
        },
    ];
    let action = CallHandler {
        destination_program: crate::ID,
        accounts: action_accounts,
        args: action_args,
        escrow_authority: ctx.accounts.payer.to_account_info(), // Signer authorized to pay transaction fees for action from escrow PDA
        compute_units: 200_000,
    };

    // Build commit and action instruction
    let magic_action = MagicInstructionBuilder {
        payer: ctx.accounts.payer.to_account_info(),
        magic_context: ctx.accounts.magic_context.to_account_info(),
        magic_program: ctx.accounts.magic_program.to_account_info(),
        magic_action: MagicAction::Commit(CommitType::WithHandler {
            commited_accounts: vec![ctx.accounts.counter.to_account_info()],
            call_handlers: vec![action],
        }),
    };

    // Invoke
    magic_action.build_and_invoke()?;

    Ok(())
}

// commit action context on ER
#[commit]
#[derive(Accounts)]
pub struct CommitAndUpdateLeaderboard<'info> {
    #[account(mut)]
    pub payer: Signer<'info>,

    #[account(mut, seeds = [TEST_PDA_SEED], bump)]
    pub counter: Account<'info, Counter>,

    /// CHECK: Leaderboard PDA - not mut here, writable set in handler
    #[account(seeds = [LEADERBOARD_SEED], bump)]
    pub leaderboard: UncheckedAccount<'info>,

    /// CHECK: Your program ID
    pub program_id: AccountInfo<'info>,
}

Execute multiple actions

You can commit multiple accounts and chain several actions. Actions execute sequentially.

let magic_builder = MagicInstructionBuilder {
    payer: ctx.accounts.payer.to_account_info(),
    magic_context: ctx.accounts.magic_context.to_account_info(),
    magic_program: ctx.accounts.magic_program.to_account_info(),
    magic_action: MagicAction::Commit(CommitType::WithHandler {
        commited_accounts: vec![ctx.accounts.counter.to_account_info(), ...],
        call_handlers: vec![call_handler, ...],
    }),
};

Other actions

Actions can be executed with undelegation and without any commits.

// Undelegate + Action
let magic_action = MagicInstructionBuilder {
    payer: ctx.accounts.payer.to_account_info(),
    magic_context: ctx.accounts.magic_context.to_account_info(),
    magic_program: ctx.accounts.magic_program.to_account_info(),
    magic_action: MagicAction::CommitAndUndelegate(CommitType::WithHandler {
        commited_accounts: vec![ctx.accounts.counter.to_account_info()],
        call_handlers: vec![action],
    }),
};

// Action only
let magic_action = MagicInstructionBuilder {
    payer: ctx.accounts.payer.to_account_info(),
    magic_context: ctx.accounts.magic_context.to_account_info(),
    magic_program: ctx.accounts.magic_program.to_account_info(),
    magic_action: MagicAction::BaseActions(vec![action]),
};

⬆️ Back to Top

On-Curve Delegation

Quick Access

GitHub

On-Curve Delegation

Required signers for delegating an on-curve account:

1. On-curve account to be delegated
2. Fee payer

Required instructions for delegating on-curve accounts:

1. Assign System Account to Delegation Program
2. Delegate to Delegation Program

kit

// Create assign instruction
// The on-curve account must sign this instruction to change its owner
const accountSigner = await cryptoKeyPairToTransactionSigner(userKeypair);
const delegationProgramAddress = address(DELEGATION_PROGRAM_ID.toString());
const assignInstruction = getAssignInstruction({
  account: accountSigner,
  programAddress: delegationProgramAddress,
});

// Create delegate instruction
const delegateInstruction = await createDelegateInstruction({
  payer: feePayerAddress,
  delegatedAccount: userAddress,
  ownerProgram: ownerProgramAddress,
  validator: validatorAddress,
});

// Prepare transaction
const transactionMessage = pipe(
  createTransactionMessage({ version: 0 }),
  (tx) => setTransactionMessageFeePayer(feePayerAddress, tx),
  (tx) =>
    appendTransactionMessageInstructions(
      [assignInstruction, delegateInstruction],
      tx
    )
);
// Send and confirm transaction (fee payer need to sign, on-curve account cannot be signer since delegated)
const txHash = await connection.sendAndConfirmTransaction(
  transactionMessage,
  [userKeypair, feePayerKeypair],
  { commitment: "confirmed", skipPreflight: true }
);

Direct commit and undelegate through Magic Program only.

kit

// Create commit and undelegate instruction
const commitAndUndelegateInstruction = createCommitAndUndelegateInstruction(
  userAddress,
  [userAddress]
);

// Prepare transaction
const transactionMessage = pipe(
  createTransactionMessage({ version: 0 }),
  (tx) => setTransactionMessageFeePayer(feePayerAddress, tx),
  (tx) =>
    appendTransactionMessageInstructions([commitAndUndelegateInstruction], tx)
);

// Send and confirm transaction on ephemeral connection
const txHash = await ephemeralConnection.sendAndConfirmTransaction(
  transactionMessage,
  [userKeypair, feePayerKeypair],
  { commitment: "confirmed", skipPreflight: true }
);

⬆️ Back to Top

---

Quick Access

Learn more about private ER, Rust Native implementation, and local development:

Private Ephemeral Rollups (PER)

Quickstart

Rust Native

Quickstart

Guide

Local Development

---

Solana Explorer

Get insights about your transactions and accounts on Solana:

Solana Explorer

Official Solana Explorer

Solscan

Explore Solana Blockchain

Solana RPC Providers

Send transactions and requests through existing RPC providers:

Solana

Free Public Nodes

Helius

Free Shared Nodes

Triton

Dedicated High-Performance Nodes

Solana Validator Dashboard

Find real-time updates on Solana’s validator infrastructure:

Solana Beach

Get Validator Insights

Validators App

Discover Validator Metrics

Server Status

Subscribe to Solana’s and MagicBlock’s server status:

Solana Status

Subscribe to Solana Server Updates

MagicBlock Status

Subscribe to MagicBlock Server Status

---

MagicBlock Products

Ephemeral Rollup (ER)

Execute real-time, zero-fee transactions securely on Solana.

Private Ephemeral Rollup (PER)

Protect sensitive data with privacy-preserving computation.

Verifiable Randomness Function (VRF)

Generate provably fair randomness directly on-chain.

---