Quickstart

cargo add ephemeral-rollups-sdk --features anchor

use ephemeral_rollups_sdk::anchor::{
  commit,
  delegate,
  ephemeral
};
use ephemeral_rollups_sdk::cpi::DelegateConfig;
use ephemeral_rollups_sdk::ephem::MagicIntentBundleBuilder;

/// Add delegate function to the context
#[delegate]
#[derive(Accounts)]
pub struct DelegateInput<'info> {
    pub payer: Signer<'info>,
    /// CHECK: The pda to delegate
    #[account(mut, del)]
    pub pda: AccountInfo<'info>,
}

/// Delegate the account to the delegation program
/// Set specific validator based on ER, see https://docs.magicblock.gg/pages/get-started/how-integrate-your-program/local-setup
pub fn delegate(ctx: Context<DelegateInput>) -> Result<()> {
    ctx.accounts.delegate_pda(
        &ctx.accounts.payer,
        &[COUNTER_SEED],
        DelegateConfig {
            // Optionally set a specific validator from the first remaining account
            validator: ctx.remaining_accounts.first().map(|acc| acc.key()),
            ..Default::default()
        },
    )?;
    Ok(())
}

use ephemeral_rollups_sdk::ephem::MagicIntentBundleBuilder;

/// Manually commit the counter state in the Ephemeral Rollup session.
pub fn commit(ctx: Context<IncrementAndCommit>) -> Result<()> {
    MagicIntentBundleBuilder::new(
        ctx.accounts.payer.to_account_info(),
        ctx.accounts.magic_context.to_account_info(),
        ctx.accounts.magic_program.to_account_info(),
    )
    .commit(&[ctx.accounts.counter.to_account_info()])
    .build_and_invoke()?;
    Ok(())
}

/// Increment the counter and commit the new state in the same instruction.
pub fn increment_and_commit(ctx: Context<IncrementAndCommit>) -> Result<()> {
    let counter = &mut ctx.accounts.counter;
    counter.count += 1;
    // Serialize the Anchor account before the CPI sees it
    counter.exit(&crate::ID)?;
    MagicIntentBundleBuilder::new(
        ctx.accounts.payer.to_account_info(),
        ctx.accounts.magic_context.to_account_info(),
        ctx.accounts.magic_program.to_account_info(),
    )
    .commit(&[ctx.accounts.counter.to_account_info()])
    .build_and_invoke()?;
    Ok(())
}

use ephemeral_rollups_sdk::ephem::MagicIntentBundleBuilder;

/// Undelegate the account from the delegation program.
/// Commits the latest state and returns ownership of the PDA back to the owner program.
pub fn undelegate(ctx: Context<IncrementAndCommit>) -> Result<()> {
    MagicIntentBundleBuilder::new(
        ctx.accounts.payer.to_account_info(),
        ctx.accounts.magic_context.to_account_info(),
        ctx.accounts.magic_program.to_account_info(),
    )
    .commit_and_undelegate(&[ctx.accounts.counter.to_account_info()])
    .build_and_invoke()?;
    Ok(())
}

# Devnet: airdrop SOL to your configured keypair before deploying
solana airdrop 2 --url https://api.devnet.solana.com

anchor build && anchor deploy

anchor test --skip-build --skip-deploy --skip-local-validator

const COUNTER_SEED = "counter";

// Set Anchor providers
const provider = new anchor.AnchorProvider(
  new anchor.web3.Connection(
    process.env.PROVIDER_ENDPOINT || "https://api.devnet.solana.com",
    {
      wsEndpoint: process.env.PROVIDER_WS_ENDPOINT || undefined,
      commitment: "confirmed",
    },
  ),
  anchor.Wallet.local(),
);
anchor.setProvider(provider);

const providerEphemeralRollup = new anchor.AnchorProvider(
  new anchor.web3.Connection(
    process.env.EPHEMERAL_PROVIDER_ENDPOINT ||
      "https://devnet-as.magicblock.app/",
    {
      wsEndpoint:
        process.env.EPHEMERAL_WS_ENDPOINT || "wss://devnet-as.magicblock.app/",
      commitment: "confirmed",
    },
  ),
  anchor.Wallet.local(),
);

// Set program and PDA
const program = anchor.workspace.PublicCounter as Program<PublicCounter>;
const [counterPDA] = anchor.web3.PublicKey.findProgramAddressSync(
  [Buffer.from(COUNTER_SEED)],
  program.programId,
);

// Initialize counter on base layer
let initTx = await program.methods
  .initialize()
  .accounts({
    user: provider.wallet.publicKey,
  })
  .transaction();
const initTxHash = await provider.sendAndConfirm(initTx, [
  provider.wallet.payer,
]);

// Increment counter on base layer
let incBaseTx = await program.methods
  .increment()
  .accounts({
    counter: counterPDA,
  })
  .transaction();
const incBaseTxHash = await provider.sendAndConfirm(incBaseTx, [
  provider.wallet.payer,
]);

// Delegate counter to ER
// Pin a specific validator by passing it in remaining_accounts
const ER_VALIDATOR = new anchor.web3.PublicKey(
  "MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57", // Asia ER validator
);
let delTx = await program.methods
  .delegate()
  .accounts({
    payer: provider.wallet.publicKey,
    pda: counterPDA,
  })
  .remainingAccounts([
    { pubkey: ER_VALIDATOR, isSigner: false, isWritable: false },
  ])
  .transaction();
const delTxHash = await provider.sendAndConfirm(delTx, [
  provider.wallet.payer,
]);

// Increment counter in real time on ER
let incErTx = await program.methods
  .increment()
  .accounts({
    counter: counterPDA,
  })
  .transaction();
incErTx.feePayer = providerEphemeralRollup.wallet.publicKey;
incErTx.recentBlockhash = (
  await providerEphemeralRollup.connection.getLatestBlockhash()
).blockhash;
incErTx = await providerEphemeralRollup.wallet.signTransaction(incErTx);
const incErTxHash = await providerEphemeralRollup.sendAndConfirm(incErTx);

// Commit and undelegate counter from ER back to base layer
let undelTx = await program.methods
  .undelegate()
  .accounts({
    payer: providerEphemeralRollup.wallet.publicKey,
  })
  .transaction();
undelTx.feePayer = providerEphemeralRollup.wallet.publicKey;
undelTx.recentBlockhash = (
  await providerEphemeralRollup.connection.getLatestBlockhash()
).blockhash;
undelTx = await providerEphemeralRollup.wallet.signTransaction(undelTx);
const undelTxHash = await providerEphemeralRollup.sendAndConfirm(undelTx);

// program instruction
pub fn update_leaderboard(ctx: Context<UpdateLeaderboard>) -> Result<()> {
    let leaderboard = &mut ctx.accounts.leaderboard;
    let counter_info = &mut ctx.accounts.counter.to_account_info();
    let mut data: &[u8] = &counter_info.try_borrow_data()?;
    let counter = Counter::try_deserialize(&mut data)?;

    if counter.count > leaderboard.high_score {
        leaderboard.high_score = counter.count;
    }

    msg!(
        "Leaderboard updated! High score: {}",
        leaderboard.high_score
    );
    Ok(())
}

// instruction context
#[action]
#[derive(Accounts)]
pub struct UpdateLeaderboard<'info> {
    #[account(mut, seeds = [LEADERBOARD_SEED], bump)]
    pub leaderboard: Account<'info, Leaderboard>,
    /// CHECK: PDA owner depends on: 1) Delegated: Delegation Program; 2) Undelegated: Your program ID
    pub counter: UncheckedAccount<'info>,
}

// commit action instruction on ER
pub fn commit_and_update_leaderboard(ctx: Context<CommitAndUpdateLeaderboard>) -> Result<()> {
    // Build the post-commit action that updates the leaderboard on base layer
    let instruction_data =
        anchor_lang::InstructionData::data(&crate::instruction::UpdateLeaderboard {});
    let action_args = ActionArgs::new(instruction_data);
    let action_accounts = vec![
        ShortAccountMeta {
            pubkey: ctx.accounts.leaderboard.key(),
            is_writable: true,
        },
        ShortAccountMeta {
            pubkey: ctx.accounts.counter.key(),
            is_writable: false,
        },
    ];
    let action = CallHandler {
        destination_program: crate::ID,
        accounts: action_accounts,
        args: action_args,
        // Signer that pays transaction fees for the action from its escrow PDA
        escrow_authority: ctx.accounts.payer.to_account_info(),
        compute_units: 200_000,
    };

    // Schedule commit + post-commit action on magic_context
    MagicIntentBundleBuilder::new(
        ctx.accounts.payer.to_account_info(),
        ctx.accounts.magic_context.to_account_info(),
        ctx.accounts.magic_program.to_account_info(),
    )
    .commit(&[ctx.accounts.counter.to_account_info()])
    .add_post_commit_actions([action])
    .build_and_invoke()?;

    Ok(())
}

// commit action context on ER
#[commit]
#[derive(Accounts)]
pub struct CommitAndUpdateLeaderboard<'info> {
    #[account(mut)]
    pub payer: Signer<'info>,

    #[account(mut, seeds = [COUNTER_SEED], bump)]
    pub counter: Account<'info, Counter>,

    /// CHECK: Leaderboard PDA - not mut here, writable set in handler
    #[account(seeds = [LEADERBOARD_SEED], bump)]
    pub leaderboard: UncheckedAccount<'info>,

    /// CHECK: Your program ID
    pub program_id: AccountInfo<'info>,
}

// Chain several actions — they execute sequentially on base layer after the commit lands.
MagicIntentBundleBuilder::new(
    ctx.accounts.payer.to_account_info(),
    ctx.accounts.magic_context.to_account_info(),
    ctx.accounts.magic_program.to_account_info(),
)
.commit(&[
    ctx.accounts.counter.to_account_info(),
    // ... additional committed accounts
])
.add_post_commit_actions([action_1, action_2, action_3])
.build_and_invoke()?;

// Commit, undelegate, AND execute actions — all atomically on base layer after the ER transaction seals.
MagicIntentBundleBuilder::new(
    ctx.accounts.payer.to_account_info(),
    ctx.accounts.magic_context.to_account_info(),
    ctx.accounts.magic_program.to_account_info(),
)
.commit_and_undelegate(&[ctx.accounts.counter.to_account_info()])
.add_post_commit_actions([action])
.build_and_invoke()?;

import {
  Connection,
  Keypair,
  PublicKey,
  Transaction,
  sendAndConfirmTransaction,
} from "@solana/web3.js";
import {
  lamportsDelegatedTransferIx,
  deriveLamportsPda,
} from "@magicblock-labs/ephemeral-rollups-sdk";

/**
 * Top up a delegated account with lamports.
 *
 * The transaction is submitted on the BASE LAYER. The Ephemeral SPL Token
 * program creates a single-use lamports PDA, funds it from the payer, and
 * delegates it so the ER credits the destination's delegated balance.
 */
async function topUpDelegatedAccount(
  connection: Connection,         // base-layer connection
  payer: Keypair,
  destination: PublicKey,         // delegated account to top up
  amountLamports: bigint,
) {
  // Generate a fresh 32-byte salt per top-up.
  // Re-using a salt collides with an existing lamports PDA and the call fails.
  const salt = crypto.getRandomValues(new Uint8Array(32));

  const [lamportsPda] = deriveLamportsPda(payer.publicKey, destination, salt);

  const ix = await lamportsDelegatedTransferIx(
    payer.publicKey,
    destination,
    amountLamports,
    salt,
  );

  const tx = new Transaction().add(ix);
  tx.feePayer = payer.publicKey;

  // CRITICAL: send to the base-layer RPC, not the ER.
  const sig = await sendAndConfirmTransaction(connection, tx, [payer], {
    commitment: "confirmed",
    skipPreflight: true,
  });

  return { sig, lamportsPda };
}

/// Reuse the same accounts context as a normal delegation
#[delegate]
#[derive(Accounts)]
pub struct DelegateInput<'info> {
    pub payer: Signer<'info>,
    /// CHECK: The pda to delegate
    #[account(mut, del)]
    pub pda: AccountInfo<'info>,
}

use anchor_lang::solana_program::instruction::{AccountMeta, Instruction};
use anchor_lang::InstructionData;
use ephemeral_rollups_sdk::cpi::{
    delegate_account_with_actions, DelegateAccounts, DelegateConfig,
};
use ephemeral_rollups_sdk::dlp_api::compact::ClearText;

/// Delegate the account AND attach a post-delegation action. The action is stored
/// in the delegation record on the base layer and executed automatically by the ER
/// validator inside the rollup, right after the account is delegated — no extra
/// transaction. Here the action is a self-CPI back into `increment`.
pub fn delegate_with_actions(ctx: Context<DelegateInput>) -> Result<()> {
    let counter_key = ctx.accounts.pda.key();

    // The instruction the ER validator runs post-delegation, inside the rollup.
    let increment_action = Instruction {
        program_id: crate::ID,
        accounts: vec![AccountMeta::new(counter_key, false)],
        data: crate::instruction::Increment {}.data(),
    };

    // Convert to the compact, cleartext post-delegation actions payload.
    // (Use `cleartext` for public actions; encrypted actions are built off-chain
    // by a client that holds the validator key.)
    let actions = vec![increment_action].cleartext();

    let payer = ctx.accounts.payer.to_account_info();
    let pda = ctx.accounts.pda.to_account_info();
    let delegate_accounts = DelegateAccounts {
        payer: &payer,
        pda: &pda,
        owner_program: &ctx.accounts.owner_program,
        buffer: &ctx.accounts.buffer_pda,
        delegation_record: &ctx.accounts.delegation_record_pda,
        delegation_metadata: &ctx.accounts.delegation_metadata_pda,
        delegation_program: &ctx.accounts.delegation_program,
        system_program: &ctx.accounts.system_program,
    };

    delegate_account_with_actions(
        delegate_accounts,
        &[COUNTER_SEED],
        DelegateConfig {
            // Optionally set a specific validator from the first remaining account
            validator: ctx.remaining_accounts.first().map(|acc| acc.key()),
            ..Default::default()
        },
        actions,
        // No extra signers are required by the increment action.
        &[],
    )?;
    Ok(())
}