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 Initialize - Create accounts on Solana base layer Delegate - Transfer account ownership to delegation program Execute - Run fast operations on Ephemeral Rollup Commit - Sync state back to base layer 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