sendaifun/magicblock

MagicBlock Ephemeral Rollups Guide

A comprehensive guide for building high-performance Solana applications with MagicBlock Ephemeral Rollups - enabling sub-10ms latency and gasless transactions.

Overview

MagicBlock Ephemeral Rollups (ER) are specialized SVM runtimes that enhance Solana with:

• Sub-10ms latency (vs ~400ms on base Solana)
• Gasless transactions for seamless UX
• Full composability with existing Solana programs
• Horizontal scaling via on-demand rollups

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Your Application                        │
├─────────────────────────────────────────────────────────────┤
│  Base Layer (Solana)          │  Ephemeral Rollup (ER)      │
│  - Initialize accounts        │  - Execute operations       │
│  - Delegate accounts          │  - Process at ~10-50ms      │
│  - Final state commits        │  - Zero gas fees            │
│  - ~400ms finality            │  - Commit state to Solana   │
└─────────────────────────────────────────────────────────────┘

Core Flow

1. Initialize - Create accounts on Solana base layer
2. Delegate - Transfer account ownership to delegation program
3. Execute - Run fast operations on Ephemeral Rollup
4. Commit - Sync state back to base layer
5. Undelegate - Return ownership to your program

Prerequisites

# Required versions
Solana: 2.3.13
Rust: 1.85.0
Anchor: 0.32.1
Node: 24.10.0

# Install Anchor (if needed)
cargo install --git https://github.com/coral-xyz/anchor anchor-cli

Quick Start

1. Add Dependencies (Cargo.toml)

[dependencies]
anchor-lang = "0.32.1"
ephemeral-rollups-sdk = { version = "0.6.5", features = ["anchor", "disable-realloc"] }

2. Program Setup (lib.rs)

use anchor_lang::prelude::*;
use ephemeral_rollups_sdk::anchor::{delegate_account, commit_accounts, ephemeral};
use ephemeral_rollups_sdk::cpi::DelegationProgram;

declare_id!("YourProgramId111111111111111111111111111111");

#[ephemeral]  // Required: enables ER support
#[program]
pub mod my_program {
    use super::*;

    pub fn initialize(ctx: Context<Initialize>) -> Result<()> {
        ctx.accounts.state.value = 0;
        Ok(())
    }

    #[delegate]  // Auto-injects delegation accounts
    pub fn delegate(ctx: Context<Delegate>) -> Result<()> {
        Ok(())
    }

    pub fn increment(ctx: Context<Update>) -> Result<()> {
        ctx.accounts.state.value += 1;
        Ok(())
    }

    #[commit]  // Auto-injects commit accounts
    pub fn undelegate(ctx: Context<Undelegate>) -> Result<()> {
        Ok(())
    }
}

3. TypeScript Client Setup

import { Connection, PublicKey } from "@solana/web3.js";
import { AnchorProvider, Program } from "@coral-xyz/anchor";
import { DELEGATION_PROGRAM_ID } from "@magicblock-labs/ephemeral-rollups-sdk";

// CRITICAL: Separate connections for each layer
const baseConnection = new Connection("https://api.devnet.solana.com");
const erConnection = new Connection("https://devnet.magicblock.app");

// Create providers
const baseProvider = new AnchorProvider(baseConnection, wallet, { commitment: "confirmed" });
const erProvider = new AnchorProvider(erConnection, wallet, {
  commitment: "confirmed",
  skipPreflight: true,  // Required for ER
});

// Check delegation status
async function isDelegated(pubkey: PublicKey): Promise<boolean> {
  const info = await baseConnection.getAccountInfo(pubkey);
  return info?.owner.equals(DELEGATION_PROGRAM_ID) ?? false;
}

Key Concepts

Delegation

Delegation transfers PDA ownership to the delegation program, allowing the Ephemeral Validator to process transactions.

#[derive(Accounts)]
pub struct Delegate<'info> {
    #[account(mut)]
    pub payer: Signer<'info>,
    /// CHECK: Will be delegated
    #[account(mut, del)]  // 'del' marks for delegation
    pub state: AccountInfo<'info>,
    pub delegation_program: Program<'info, DelegationProgram>,
}

Commit

Commits update PDA state from ER to base layer without undelegating.

use ephemeral_rollups_sdk::anchor::commit_accounts;

pub fn commit(ctx: Context<Commit>) -> Result<()> {
    commit_accounts(
        &ctx.accounts.payer,
        vec![&ctx.accounts.state.to_account_info()],
        &ctx.accounts.magic_context,
        &ctx.accounts.magic_program,
    )?;
    Ok(())
}

Undelegation

Returns PDA ownership to your program while committing final state.

#[commit]  // Handles commit + undelegate
pub fn undelegate(ctx: Context<Undelegate>) -> Result<()> {
    Ok(())
}

ER Validators (Devnet)

| Region | Validator Identity | |--------|-------------------| | Asia | MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57 | | EU | MEUGGrYPxKk17hCr7wpT6s8dtNokZj5U2L57vjYMS8e | | US | MUS3hc9TCw4cGC12vHNoYcCGzJG1txjgQLZWVoeNHNd | | TEE | FnE6VJT5QNZdedZPnCoLsARgBwoE6DeJNjBs2H1gySXA |

Magic Router (auto-selects best): https://devnet-router.magicblock.app

Critical Rules

DO:

• Maintain separate connections for base layer and ER
• Use skipPreflight: true for all ER transactions
• Verify delegation status before sending to ER
• Use AccountInfo for delegated accounts in Rust
• Match PDA seeds exactly between Rust and TypeScript

DON'T:

• Send delegated account operations to base layer
• Mix base layer and ER operations in single transaction
• Assume account ownership without checking
• Skip commitment verification before base layer reads

Products

| Product | Description | |---------|-------------| | Ephemeral Rollup (ER) | High-performance, gasless transactions | | Private ER (PER) | Privacy-preserving computation with Intel TDX | | VRF | Verifiable random function for on-chain randomness | | BOLT Framework | ECS architecture for fully on-chain games | | Solana Plugins | App-specific extensions for enhanced capabilities |

Solana Plugins (New)

Solana Plugins are modular capabilities that can be added to your dApp to extend what's possible on Solana. Think of them as your custom toolkit: plug in what you need, when you need it.

Available Plugins

| Plugin | Description | Use Cases | |--------|-------------|-----------| | Verifiable Randomness (VRF) | Provably fair on-chain randomness | Games, lotteries, NFT drops | | Real-Time Price Feeds | Up-to-the-millisecond market data | DEXs, trading bots, DeFi | | AI Oracles | Call AI models directly from smart contracts | Dynamic NFTs, AI agents |

Using VRF Plugin

import { requestRandomness, getRandomnessResult } from "@magicblock-labs/vrf-sdk";

// Request randomness
const requestTx = await requestRandomness({
  payer: wallet.publicKey,
  seed: Buffer.from("my_game_seed"),
});

// Get result after confirmation
const result = await getRandomnessResult(requestId);
console.log("Random value:", result.randomness);

Privacy with Intel TDX

MagicBlock enables privacy in any Solana program state account through Ephemeral Rollups running in Trusted Execution Environments (TEE) on Intel TDX. This allows:

• Private computation without exposing state
• Verifiable execution guarantees
• Selective disclosure of results

Resources

• Documentation: https://docs.magicblock.gg
• GitHub: https://github.com/magicblock-labs
• Examples: https://github.com/magicblock-labs/magicblock-engine-examples
• Starter Kits: https://github.com/magicblock-labs/starter-kits
• BOLT Book: https://book.boltengine.gg
• Discord: Join for testnet access

Skill Structure

magicblock/
├── SKILL.md                          # This file
├── resources/
│   ├── api-reference.md              # Complete API reference
│   └── program-ids.md                # All program IDs and constants
├── examples/
│   ├── anchor-counter/README.md      # Basic counter with delegation
│   ├── delegation-flow/README.md     # Full delegation lifecycle
│   ├── vrf-randomness/README.md      # VRF integration
│   └── crank-automation/README.md    # Scheduled tasks
├── templates/
│   ├── program-template.rs           # Rust program starter
│   └── client-template.ts            # TypeScript client starter
└── docs/
    ├── advanced-patterns.md          # Complex patterns
    └── troubleshooting.md            # Common issues