magicblock

MagicBlock 临时 Rollup 指南

使用 MagicBlock 临时 Rollup 构建高性能 Solana 应用的综合指南，支持低于 10 ms 的延迟和免 Gas 交易。

概述

MagicBlock 临时 Rollup（ER）是专用的 SVM 运行时，可增强 Solana 的能力：

• 低于 10 ms 的延迟（而 Solana 基础层约为 400 ms）
• 免 Gas 交易，带来流畅的用户体验
• 与现有 Solana 程序完全可组合
• 通过按需 Rollup 实现横向扩展

架构

┌─────────────────────────────────────────────────────────────┐
│                      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   │
└─────────────────────────────────────────────────────────────┘

核心流程

1. 初始化 - 在 Solana 基础层创建账户
2. 委托 - 将账户所有权转移给委托程序
3. 执行 - 在临时 Rollup 上运行快速操作
4. 提交 - 将状态同步回基础层
5. 取消委托 - 将所有权交还给你的程序

先决条件

# 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

快速入门

1. 添加依赖项（Cargo.toml）

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

2. 程序设置（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 客户端设置

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

核心概念

委托

委托会将 PDA 所有权转移给委托程序，从而允许临时验证器处理交易。

#[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>,
}

提交

提交会将 PDA 状态从 ER 更新到基础层，而不会取消委托。

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(())
}

取消委托

将 PDA 所有权交还给你的程序，同时提交最终状态。

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

ER 验证器（Devnet）

区域	验证器身份
亚洲	MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57
欧盟	MEUGGrYPxKk17hCr7wpT6s8dtNokZj5U2L57vjYMS8e
美国	MUS3hc9TCw4cGC12vHNoYcCGzJG1txjgQLZWVoeNHNd
TEE	FnE6VJT5QNZdedZPnCoLsARgBwoE6DeJNjBs2H1gySXA

Magic Router（自动选择最佳验证器）：https://devnet-router.magicblock.app

关键规则

应做事项：

• 为基础层和 ER 分别维护独立连接
• 所有 ER 交易都使用 skipPreflight: true
• 向 ER 发送交易前，先确认委托状态
• 在 Rust 中对已委托账户使用 AccountInfo
• 确保 Rust 和 TypeScript 中的 PDA 种子完全一致

不应做事项：

• 不要将已委托账户的操作发送到基础层
• 不要在同一笔交易中混合基础层和 ER 操作
• 不要未经检查就假定账户所有权
• 不要在读取基础层数据前跳过提交验证

产品

产品	描述
临时 Rollup（ER）	高性能、免 Gas 交易
私有 ER（PER）	使用 Intel TDX 实现隐私保护计算
VRF	用于链上随机性的可验证随机函数
BOLT 框架	面向完全链上游戏的 ECS 架构
Solana 插件	用于增强功能的应用专属扩展

Solana 插件（新）

Solana 插件是可添加到你的 dApp 中的模块化能力，可拓展 Solana 的功能边界。你可以把它们视作自定义工具包：按需接入所需功能。

可用插件

插件	描述	用例
可验证随机性（VRF）	可证明公平的链上随机性	游戏、彩票、NFT 空投
实时价格馈送	精确到毫秒的市场数据	DEX、交易机器人、DeFi
AI 预言机	直接从智能合约调用 AI 模型	动态 NFT、AI Agent

使用 VRF 插件

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

使用 Intel TDX 实现隐私保护

MagicBlock 通过在 Intel TDX 的可信执行环境（TEE）中运行的临时 Rollup，为任何 Solana 程序状态账户提供隐私保护。这支持：

• 在不暴露状态的情况下进行私密计算
• 可验证的执行保证
• 有选择地披露结果

资源

• 文档：https://docs.magicblock.gg
• GitHub：https://github.com/magicblock-labs
• 示例：https://github.com/magicblock-labs/magicblock-engine-examples
• 入门套件：https://github.com/magicblock-labs/starter-kits
• BOLT 手册：https://book.boltengine.gg
• Discord：加入以获取测试网访问权限

技能结构

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