Solana 程序

快速入口

查看其他实现中的基础计数器示例：

GitHub

Native Rust 实现

GitHub

Pinocchio 实现

Guide

本地开发

分步指南

构建你的程序，并通过 MagicBlock 的 Delegation Program DELeGGvXpWV2fqJUhqcF5ZSYMS4JTLjteaAMARRSaeSh 加入 delegation hooks 完成升级：

编写程序并添加 delegation instructions

按照你平常的方式编写 Solana 程序。

在 Base Layer 上 Delegate PDA

添加 CPI hooks，使状态账户能够在 Ephemeral Rollup 会话中完成 delegate、commit 和 undelegate。

这些公共验证器可用于开发环境。请确保在你的委托指令中添加对应的 ER 验证器：

主网

亚洲 (as.magicblock.app): MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57
欧盟 (eu.magicblock.app): MEUGGrYPxKk17hCr7wpT6s8dtNokZj5U2L57vjYMS8e
美国 (us.magicblock.app): MUS3hc9TCw4cGC12vHNoYcCGzJG1txjgQLZWVoeNHNd
TEE (mainnet-tee.magicblock.app): MTEWGuqxUpYZGFJQcp8tLN7x5v9BSeoFHYWQQ3n3xzo

开发网

亚洲 (devnet-as.magicblock.app): MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57
欧盟 (devnet-eu.magicblock.app): MEUGGrYPxKk17hCr7wpT6s8dtNokZj5U2L57vjYMS8e
美国 (devnet-us.magicblock.app): MUS3hc9TCw4cGC12vHNoYcCGzJG1txjgQLZWVoeNHNd
TEE (devnet-tee.magicblock.app): MTEWGuqxUpYZGFJQcp8tLN7x5v9BSeoFHYWQQ3n3xzo

本地网络

本地 ER (localhost:7799): mAGicPQYBMvcYveUZA5F5UNNwyHvfYh5xkLS2Fr1mev

在 ER 上 Commit PDA

使用 Solana CLI 将程序直接部署到 Solana 上。

在 ER 上 Undelegate PDA

在链上和链下发送无需修改且符合 SVM RPC 规范的交易。

Counter 示例

你可能需要以下软件包，其他版本也可能兼容：

软件	版本	安装指南
Solana	3.1.9	安装 Solana
Rust	1.89.0	安装 Rust
Node	24.10.0	安装 Node

代码片段

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

该程序实现了两个主要 instruction：

InitializeCounter：初始化并将计数器设为 0（在 Base Layer 调用）
IncreaseCounter：将已初始化的计数器增加 X（可在 Base Layer 或 ER 调用）

该程序还为计数器的委托与取消委托实现了专用 instruction：

Delegate：将计数器从 Base Layer 委托到 ER（在 Base Layer 调用）
CommitAndUndelegate：安排将计数器从 ER 同步回 Base Layer，并在 ER 上取消委托（在 ER 调用）
Commit：安排将计数器从 ER 同步回 Base Layer（在 ER 调用）
Undelegate：在 Base Layer 上取消委托计数器（通过 validator CPI 在 Base Layer 调用）
IncrementAndCommit：在一次 ER 交易中执行增量并提交（在 ER 调用）
IncrementAndUndelegate：在一次 ER 交易中执行增量、提交并取消委托（在 ER 调用）

The undelegation callback discriminator [196, 28, 41, 206, 48, 37, 51, 167] and its instruction processor must be specified in your program. This instruction triggered by Delegation Program reverts account ownership on the Base Layer after calling undelegation on ER.With [#ephemeral] Anchor macro from MagicBlock’s Ephemeral Rollup SDK, the undelegation callback discriminator and processor are injected into your program.

下面是程序的核心结构：

use borsh::BorshDeserialize;
use solana_program::program_error::ProgramError;

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

#[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 (ix_discriminator, rest) = input.split_at(8);

        // Match instruction discriminator with process and deserialize payload
        Ok(match ix_discriminator {
            [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,
            [5, 0, 0, 0, 0, 0, 0, 0] => {
                let payload = IncreaseCounterPayload::try_from_slice(rest)?;
                Self::IncrementAndCommit {
                    increase_by: payload.increase_by,
                }
            }
            [6, 0, 0, 0, 0, 0, 0, 0] => {
                let payload = IncreaseCounterPayload::try_from_slice(rest)?;
                Self::IncrementAndUndelegate {
                    increase_by: payload.increase_by,
                }
            }
            [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),
        })
    }
}

你的 “Undelegate” instruction 必须使用完全一致的 discriminator。它不会由你主动调用，而是由 Base Layer 上的 validator 在 ER 中完成账户 undelegate 后，通过 CPI 回调进入你的程序。

⬆️ Back to Top

委托 Counter PDA

为了委托 counter PDA，并使其在 Ephemeral Rollup 会话中可写，我们需要添加一个 instruction，其内部会调用 delegate_account 函数。delegate_account 会通过 CPI 调用 delegation program，在验证通过后 delegation program 将获得该账户的所有权。完成这一步后，ephemeral validator 就可以开始在 counter PDA 上处理交易，并通过 delegation program 提交状态差异。

交易（Base Layer）：Delegate

在 Solana Explorer 中查看交易详情

use solana_program::{
    account_info::{next_account_info, AccountInfo},
    entrypoint::ProgramResult,
    msg,
    pubkey::Pubkey,
};
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)?;
    let validator_account = account_info_iter.next();

    // Optional: client-provided validator or default validator
    let validator_pubkey: Option<Pubkey> = validator_account.map(|acc_info| acc_info.key.clone());

    // Prepare counter pda seeds
    let seed_1 = b"counter";
    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: validator_pubkey, // Set delegating ER validator
        ..Default::default()
    };

    delegate_account(delegate_accounts, pda_seeds, delegate_config)?;

    Ok(())
}

⬆️ Back to Top

在 PDA 已委托时进行提交

ephemeral runtime 允许在 PDA 已委托时提交其状态。这通过调用 commit_accounts 函数来完成。

交易（ER）：Commit

在 Solana Explorer 中查看交易详情

交易（Base layer）：Commit

在 Solana Explorer 中查看交易详情

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

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

    MagicIntentBundleBuilder::new(
        initializer.clone(),
        magic_context.clone(),
        magic_program.clone(),
    )
    .commit(&[counter_account.clone()])
    .build_and_invoke()?;

    Ok(())
}

⬆️ Back to Top

取消委托 PDA

取消委托 PDA 是通过在某个 instruction 中调用 commit_and_undelegate_accounts 来完成的。 undelegation 会提交最新状态，并将 PDA 的所有权归还给 owner program。完成 undelegation 和状态最终确认后，validator 会在 Base Layer 上触发一个对 "undelegate" 的 CPI 回调。

交易（ER）：Undelegate

在 Solana Explorer 中查看交易详情

交易（Base layer）：Undelegate

在 Solana Explorer 中查看交易详情

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

// 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
    MagicIntentBundleBuilder::new(
        initializer.clone(),
        magic_context.clone(),
        magic_program.clone(),
    )
    .commit_and_undelegate(&[counter_account.clone()])
    .build_and_invoke()?;

    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

进阶代码片段

Resize PDA
On-Curve Delegation

当调整已委托 PDA 的大小时：

PDA 必须有足够的 lamports，才能在新账户大小下继续保持 rent-exempt。
如果需要额外 lamports，则 payer account 也必须已委托，以补足差额。
PDA 必须由程序持有，且交易中必须包含转移 lamports 所需的 signer。
使用 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

快速访问

GitHub

曲线内账户委托

委托曲线内账户所需的签名者：

需要被委托的曲线内账户
费用支付者

委托曲线内账户所需的指令：

将 System Account 指派给 Delegation Program
委托给 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,
  }
);

仅通过 Magic Program 直接执行 commit 和 undelegate。

// 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 浏览器

查看你在 Solana 上的交易和账户详情：

Solana 浏览器

官方 Solana 浏览器

Solscan

浏览 Solana 区块链

Solana RPC 提供商

通过现有 RPC 提供商发送交易和请求：

Solana

Free Public Nodes

Helius

Free Shared Nodes

Triton

Dedicated High-Performance Nodes

Solana 验证器仪表盘

查看 Solana 验证器基础设施的实时更新：

Solana Beach

Get Validator Insights

Validators App

Discover Validator Metrics

服务状态

订阅 Solana 与 MagicBlock 的服务状态：

Solana Status

Subscribe to Solana Server Updates

MagicBlock Status

Subscribe to MagicBlock Server Status

操作指南

参考资料

ROUTER API

RPC API

快速入口

GitHub

GitHub

Guide

分步指南

Counter 示例

代码片段

委托 Counter PDA

交易（Base Layer）：Delegate

在 PDA 已委托时进行提交

交易（ER）：Commit

交易（Base layer）：Commit

取消委托 PDA

交易（ER）：Undelegate

交易（Base layer）：Undelegate

进阶代码片段

快速访问

GitHub

Solana 浏览器

Solana 浏览器

Solscan

Solana RPC 提供商

Solana

Helius

Triton

Solana 验证器仪表盘

Solana Beach

Validators App

服务状态

Solana Status

MagicBlock Status

​快速入口

GitHub

GitHub

Guide

​分步指南

​Counter 示例

​代码片段

​委托 Counter PDA

交易（Base Layer）：Delegate

​在 PDA 已委托时进行提交

交易（ER）：Commit

交易（Base layer）：Commit

​取消委托 PDA

交易（ER）：Undelegate

交易（Base layer）：Undelegate

​进阶代码片段

​快速访问

GitHub

​Solana 浏览器

Solana 浏览器

Solscan

​Solana RPC 提供商

Solana

Helius

Triton

​Solana 验证器仪表盘

Solana Beach

Validators App

​服务状态

Solana Status

MagicBlock Status

快速入口

分步指南

Counter 示例

代码片段

委托 Counter PDA

在 PDA 已委托时进行提交

取消委托 PDA

进阶代码片段

快速访问

Solana 浏览器

Solana RPC 提供商

Solana 验证器仪表盘

服务状态