Solana Program

Quick Access

Check out basic counter example in other implementations:

GitHub

Native Rust Implementation

Guide

Local Development

Step-By-Step Guide

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

Write program and add delegation instructions

Write your Solana program as you normally would.

Delegate PDA on Base Layer

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

Commit PDA on ER

Deploy your program directly on Solana using Solana CLI.

Undelegate PDA on ER

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
Node	24.10.0	Install Node

Code Snippets

1. Write Program
2. Delegate
3. Commit
4. Undelegate

The program implements two main instructions:

InitializeCounter: Initialize and sets the counter to 0 (called on Base Layer)
IncreaseCounter: Increments the initialized counter by X amount (called on Base Layer or ER)

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

Delegate: Delegates counter from Base Layer to ER (called on Base Layer)
CommitAndUndelegate: Schedules sync of counter from ER to Base Layer, and undelegates counter on ER (called on ER)
Commit: Schedules sync of counter from ER to Base Layer (called on ER)
Undelegate: Undelegates counter on the Base Layer (called on Base Layer through validator CPI)

Here’s the core structure of our program:

pub enum ProgramInstruction {
    InitializeCounter,
    IncreaseCounter {
        increase_by: u64
    },
    Delegate,
    CommitAndUndelegate,
    Commit,
    Undelegate {
        pda_seeds: Vec<Vec<u8>>
    }
}

#[derive(BorshDeserialize)]
struct IncreaseCounterPayload {
    increase_by: u64,
}

impl ProgramInstruction {
    pub fn unpack(input: &[u8]) -> Result<Self, ProgramError> {
        // Ensure the input has at least 8 bytes for the variant
        if input.len() < 8 {
            return Err(ProgramError::InvalidInstructionData);
        }

        // Extract the first 8 bytes as variant
        let (variant_bytes, rest) = input.split_at(8);
        let mut variant = [0u8; 8];
        variant.copy_from_slice(variant_bytes);

        Ok(match variant {
            [0, 0, 0, 0, 0, 0, 0, 0] => Self::InitializeCounter,
            [1, 0, 0, 0, 0, 0, 0, 0] => {
                let payload = IncreaseCounterPayload::try_from_slice(rest)?;
                Self::IncreaseCounter {
                    increase_by: payload.increase_by,
                }
            },
            [2, 0, 0, 0, 0, 0, 0, 0] => Self::Delegate,
            [3, 0, 0, 0, 0, 0, 0, 0] => Self::CommitAndUndelegate,
            [4, 0, 0, 0, 0, 0, 0, 0] => Self::Commit,
            [196, 28, 41, 206, 48, 37, 51, 167] => {
                let pda_seeds: Vec<Vec<u8>> = Vec::<Vec<u8>>::try_from_slice(rest)?;
                Self::Undelegate {
                    pda_seeds
                }
            }
            _ => return Err(ProgramError::InvalidInstructionData),
        })
    }
}

Your “Undelegate” instruction must have the exact discriminator. It is never called by you, instead the validator on the Base Layer will callback with a CPI into your program after undelegating your account on ER.

⬆️ Back to Top

Delegating the Counter PDA

In order to delegate the counter PDA, and make it writable in an Ephemeral Rollup session, we need to add an instruction which internally calls the delegate_account function. delegate_account will CPI to the delegation program, which upon validation will gain ownership of the account. After this step, an ephemeral validator can start processing transactions on the counter PDA and propose state diff trough the delegation program.

Transaction (Base Layer): Delegate

Inspect transactions details on Solana Explorer

use solana_program::{
    account_info::{next_account_info, AccountInfo},
    pubkey::Pubkey,
    entrypoint::ProgramResult,
    program_error::ProgramError,
};
use ephemeral_rollups_sdk::cpi::{delegate_account, DelegateAccounts, DelegateConfig};

// For Base Layer only
// Set specific validator based on ER, see https://docs.magicblock.gg/pages/get-started/how-integrate-your-program/local-setup
pub fn process_delegate(
\_program_id: &Pubkey,
accounts: &[AccountInfo],
) -> ProgramResult {

    // Get accounts
    let account_info_iter = &mut accounts.iter();
    let initializer = next_account_info(account_info_iter)?;
    let system_program = next_account_info(account_info_iter)?;
    let pda_to_delegate = next_account_info(account_info_iter)?;
    let owner_program = next_account_info(account_info_iter)?;
    let delegation_buffer = next_account_info(account_info_iter)?;
    let delegation_record = next_account_info(account_info_iter)?;
    let delegation_metadata = next_account_info(account_info_iter)?;
    let delegation_program = next_account_info(account_info_iter)?;

    // Optional: client-provided validator or default validator
    let default_validator = pubkey!("mAGicPQYBMvcYveUZA5F5UNNwyHvfYh5xkLS2Fr1mev"); // Local ER validator
    let validator_pubkey = match validator_account {
        Some(acc_info) => acc_info.key.clone(),
        None => default_validator,
    };

    // Prepare counter pda seeds
    let seed_1 = b"counter_account";
    let seed_2 = initializer.key.as_ref();
    let pda_seeds: &[&[u8]] = &[seed_1, seed_2];

    let delegate_accounts = DelegateAccounts {
        payer: initializer,
        pda: pda_to_delegate,
        owner_program,
        buffer: delegation_buffer,
        delegation_record,
        delegation_metadata,
        delegation_program,
        system_program,
    };

    let delegate_config = DelegateConfig {
        validator: Some(validator_pubkey), // Set delegating ER validator
        ..Default::default()
    };

    delegate_account(delegate_accounts, pda_seeds, delegate_config)?;

    Ok(())

}

⬆️ Back to Top

Committing while the PDA is delegated

The ephemeral runtime allow to commit the state of the PDA while it is delegated. This is done by calling the commit_accounts function.

Transaction (ER): Commit

Inspect transaction details on Solana Explorer

Transaction (Base layer): Commit

Inspect transaction details on Solana Explorer

use solana_program::{
    account_info::{next_account_info, AccountInfo},
    pubkey::Pubkey,
    entrypoint::ProgramResult,
    program_error::ProgramError,
};
use ephemeral_rollups_sdk::ephem::{commit_accounts};

// For ER only
pub fn process_commit(
    _program_id: &Pubkey,
    accounts: &[AccountInfo],
) -> ProgramResult {
    // Get accounts
    let account_info_iter = &mut accounts.iter();
    let initializer = next_account_info(account_info_iter)?;
    let counter_account = next_account_info(account_info_iter)?;
    let magic_program = next_account_info(account_info_iter)?;
    let magic_context = next_account_info(account_info_iter)?;

    // Signer should be the same as the initializer
    if !initializer.is_signer {
        msg!("Initializer {} should be the signer", initializer.key);
        return Err(ProgramError::MissingRequiredSignature);
    }

    commit_accounts(
        initializer,
        vec![counter_account],
        magic_context,
        magic_program,
    )?;

    Ok(())
}

⬆️ Back to Top

Undelegating the PDA

Undelegating the PDA is done by calling the commit_and_undelegate_accounts as part of some instruction. Undelegation commit the latest state and give back the ownership of the PDA to the owner program. After undelegating and finalizing the state, the validator will create a callback CPI into “undelegate” on the Base Layer.

Transaction (ER): Undelegate

Inspect transaction details on Solana Explorer

Transaction (Base layer): Undelegate

Inspect transaction details on Solana Explorer

use solana_program::{
    account_info::{next_account_info, AccountInfo},
    pubkey::Pubkey,
    entrypoint::ProgramResult,
    program_error::ProgramError,
};
use ephemeral_rollups_sdk::cpi::{undelegate_account};
use ephemeral_rollups_sdk::ephem::{commit_and_undelegate_accounts, commit_accounts};

// For ER only
pub fn process_commit_and_undelegate(
    _program_id: &Pubkey,
    accounts: &[AccountInfo],
) -> ProgramResult {
    // Get accounts
    let account_info_iter = &mut accounts.iter();
    let initializer = next_account_info(account_info_iter)?;
    let counter_account = next_account_info(account_info_iter)?;
    let magic_program = next_account_info(account_info_iter)?;
    let magic_context = next_account_info(account_info_iter)?;

    // Signer should be the same as the initializer
    if !initializer.is_signer {
        msg!("Initializer {} should be the signer", initializer.key);
        return Err(ProgramError::MissingRequiredSignature);
    }

    // Commit and undelegate counter_account on ER
    commit_and_undelegate_accounts(
        initializer,
        vec![counter_account],
        magic_context,
        magic_program,
    )?;

    Ok(())

}

// For Base Layer CPI callback
pub fn process_undelegate(
    program_id: &Pubkey,
    accounts: &[AccountInfo],
    pda_seeds: Vec<Vec<u8>>
) -> ProgramResult {
    // Get accounts
    let account_info_iter = &mut accounts.iter();
    let delegated_pda = next_account_info(account_info_iter)?;
    let delegation_buffer = next_account_info(account_info_iter)?;
    let initializer = next_account_info(account_info_iter)?;
    let system_program = next_account_info(account_info_iter)?;

    // CPI on Solana
    undelegate_account(
        delegated_pda,
        program_id,
        delegation_buffer,
        initializer,
        system_program,
        pda_seeds,
    )?;

    Ok(())

}

⬆️ Back to Top

Advanced Code Snippets

Resize PDA
On-Curve Delegation

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

#[derive(BorshSerialize, BorshDeserialize, Debug)]
pub struct Counter {
    pub count: u64,
}

// Resize counter account
pub fn resize_counter_account(
    counter_acc: &AccountInfo,
    payer: &AccountInfo,
    program_id: &Pubkey,
    new_size: usize,
    bump: u8,
) -> ProgramResult {
    let rent = Rent::get()?;
    let lamports_required = rent.minimum_balance(new_size);

    let current_lamports = counter_acc.lamports();
    if lamports_required > current_lamports {
        let lamports_to_add = lamports_required - current_lamports;
        invoke_signed(
            &system_instruction::transfer(
                &payer.key,
                &counter_acc.key,
                lamports_to_add,
            ),
            &[payer.clone(), counter_acc.clone()],
            &[&[COUNTER_SEED, &[bump]]],
        )?;
    }

    // Allocate new size
    invoke_signed(
        &system_instruction::allocate(&counter_acc.key, new_size as u64),
        &[counter_acc.clone()],
        &[&[COUNTER_SEED, &[bump]]],
    )?;

    // Assign back to program
    invoke_signed(
        &system_instruction::assign(&counter_acc.key, program_id),
        &[counter_acc.clone()],
        &[&[COUNTER_SEED, &[bump]]],
    )?;

    msg!("Counter account resized to {} bytes", new_size);
    Ok(())
}

⬆️ Back to Top

Quick Access

GitHub

On-Curve Delegation

Required signers for delegating an on-curve account:

On-curve account to be delegated
Fee payer

Required instructions for delegating on-curve accounts:

Assign System Account to Delegation Program
Delegate to Delegation Program

// 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 }
);

// Create assign instruction
const assignInstruction = SystemProgram.assign({
  accountPubkey: userPubkey,
  programId: DELEGATION_PROGRAM_ID,
});

// Create delegate instruction
const delegateInstruction = createDelegateInstruction({
  payer: feePayerKeypair.publicKey,
  delegatedAccount: userPubkey,
  ownerProgram: ownerProgram,
  validator: validator,
});

// Create and send transaction (fee payer need to sign, on-curve account cannot be signer since delegated)
const tx = new Transaction().add(assignInstruction, delegateInstruction);
tx.feePayer = feePayerKeypair.publicKey;
const txSignature = await sendAndConfirmTransaction(
  connectionBaseLayer,
  tx,
  [userKeypair, feePayerKeypair],
  {
    skipPreflight: true,
  }
);

Direct commit and undelegate through Magic Program only.

// 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 }
);

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

// Send and confirm transaction on ephemeral connection
const tx = new Transaction().add(commitAndUndelegateInstruction);
tx.feePayer = feePayerKeypair.publicKey;
const txSignature = await sendAndConfirmTransaction(
  ephemeralConnection,
  tx,
  [userKeypair, feePayerKeypair],
  {
    skipPreflight: true,
  }
);

⬆️ Back to Top

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

How-to-Guide

Reference Material

API

Quick Access

GitHub

Guide

Step-By-Step Guide

Counter Example

Code Snippets

Delegating the Counter PDA

Transaction (Base Layer): Delegate

Committing while the PDA is delegated

Transaction (ER): Commit

Transaction (Base layer): Commit

Undelegating the PDA

Transaction (ER): Undelegate

Transaction (Base layer): Undelegate

Advanced Code Snippets

Quick Access

GitHub

Solana Explorer

Solana Explorer

Solscan

Solana RPC Providers

Solana

Helius

Triton

Solana Validator Dashboard

Solana Beach

Validators App

Server Status

Solana Status

MagicBlock Status

​Quick Access

GitHub

Guide

​Step-By-Step Guide

​Counter Example

​Code Snippets

​Delegating the Counter PDA

Transaction (Base Layer): Delegate

​Committing while the PDA is delegated

Transaction (ER): Commit

Transaction (Base layer): Commit

​Undelegating the PDA

Transaction (ER): Undelegate

Transaction (Base layer): Undelegate

​Advanced Code Snippets

​Quick Access

GitHub

​Solana Explorer

Solana Explorer

Solscan

​Solana RPC Providers

Solana

Helius

Triton

​Solana Validator Dashboard

Solana Beach

Validators App

​Server Status

Solana Status

MagicBlock Status

Quick Access

Step-By-Step Guide

Counter Example

Code Snippets

Delegating the Counter PDA

Committing while the PDA is delegated

Undelegating the PDA

Advanced Code Snippets

Quick Access

Solana Explorer

Solana RPC Providers

Solana Validator Dashboard

Server Status