Magic Actions

Automatic on-chain handlers triggered when committing from Ephemeral Rollups

Magic Actions

Magic Actions enable you to execute automatic on-chain handlers when committing accounts from Ephemeral Rollups back to the base layer. This powerful pattern allows you to perform base chain operations (like updating global state) automatically whenever ER state is committed.

What Are Magic Actions?

Magic Actions are instruction handlers that execute automatically on the base chain when you commit delegated accounts from an Ephemeral Rollup. They enable:

• Updating global leaderboards when player scores are committed
• Triggering reward distributions based on ER activity
• Synchronizing cross-program state
• Executing base-layer-only operations (like SPL token transfers) on commit

Magic Actions execute on the base layer (Solana mainnet/devnet) using funds from an escrow account, allowing automated base chain interactions without user signatures.

How It Works

Required Imports

use ephemeral_rollups_sdk::anchor::{action, commit, delegate, ephemeral};
use ephemeral_rollups_sdk::ephem::{CallHandler, CommitType, MagicAction, MagicInstructionBuilder};
use ephemeral_rollups_sdk::{ActionArgs, ShortAccountMeta};

Account Context Annotations

Action Handler Context

#[action]
#[derive(Accounts)]
pub struct UpdateLeaderboard<'info> {
    #[account(mut, seeds = [LEADERBOARD_SEED], bump)]
    pub leaderboard: Account<'info, Leaderboard>,
    /// CHECK: Account may be delegated or undelegated
    pub counter: UncheckedAccount<'info>,
}

Managing Escrow Accounts

Create & Fund

import { createTopUpEscrowInstruction, escrowPdaFromEscrowAuthority } from "@magicblock-labs/ephemeral-rollups-sdk";

const escrowPda = escrowPdaFromEscrowAuthority(wallet.publicKey);
const topUpIx = createTopUpEscrowInstruction(
  escrowPda,
  wallet.publicKey,
  wallet.publicKey,
  10000 // lamports to fund the escrow
);

Close Escrow

import { createCloseEscrowInstruction } from "@magicblock-labs/ephemeral-rollups-sdk";

const closeEscrowIx = createCloseEscrowInstruction(
  escrowPdaFromEscrowAuthority(wallet.publicKey),
  wallet.publicKey
);

const tx = new Transaction().add(closeEscrowIx);
const signature = await sendAndConfirmTransaction(
  connection,
  tx,
  [wallet.payer],
  { skipPreflight: true }
);

Ensure your escrow account has sufficient funds to cover the transaction fees for all Magic Actions you plan to execute. Each action consumes base layer transaction fees from the escrow.

What Makes This Advanced?

Magic Actions represent an advanced pattern because they:

1. Bridge ER and Base Layer: Automatically execute base chain logic when ER state is committed
2. Gasless Automation: Use escrow accounts to pay for base layer fees without user interaction
3. Cross-Program Coordination: Update global state (like leaderboards) based on individual player actions in ERs
4. Composability: Chain multiple actions together in a single commit operation

Use Cases

• Global Leaderboards: Update rankings when player scores are committed from game ERs
• Tournament Systems: Trigger prize distributions when tournament state is finalized
• Cross-Chain State: Synchronize ER state with base layer contracts
• Token Operations: Execute SPL token transfers on the base layer when ER conditions are met

Example: Counter with Leaderboard

programs/magic-actions/src/lib.rs

pub const COUNTER_SEED: &[u8] = b"counter";
pub const LEADERBOARD_SEED: &[u8] = b"leaderboard";

#[account]
pub struct Counter {
    pub count: u64,
}

#[account]
pub struct Leaderboard {
    pub high_score: u64,
}

The counter is delegated and runs in an ER with ultra-low latency. The leaderboard stays on the base layer for global visibility. When the counter is committed, the Magic Action automatically checks if the score beats the high score and updates the leaderboard.

Next Steps

• Learn about Cranks for scheduled automated execution
• Explore Session Keys for gasless user transactions
• Check the full source code