Smart Contract Integration

Building with an AI coding agent? Install the MagicBlock Dev Skill to give your agent MagicBlock-specific patterns — delegation flows, Magic Actions, cranks, VRF, and more.Hit an error? Ask your coding agent with the skill installed, not the docs assistant. The assistant only sees the docs, so it cannot debug your code.Quick install for Claude Code:

npx skills add https://github.com/magicblock-labs/magicblock-dev-skill

Using Cursor, Codex, Windsurf, Cline, or another agent? See the AI Dev Skill page for all install targets.

Quick Access

binary-prediction

eATA custody end to end

rewards-delegated-vrf

Base-layer post-commit payouts

spl-tokens

Non-custody transfers

This guide is for on-chain programs — a DEX, AMM, prediction market, escrow, or game — that hold user funds and move them at Ephemeral Rollup speed. The core pattern: a program-owned account, delegated to the ER, with your program signing token transfers as a PDA.

Moving tokens from a client instead of on-chain? See the Quickstart.

Two custody models

Model	You delegate…	Tokens move…	Use when
eATA custody	a program-owned ephemeral ATA (eATA)	on the ER, PDA-signed	you settle or pay out inside the rollup (e.g. a market fill)
State PDA + post-commit payout	only a state PDA; real ATAs stay on base	on the base layer, as a post-commit action	funds stay on L1 and settle on commit

The walkthrough below covers eATA custody, with the post-commit variant in the advanced snippets.

Step-By-Step Guide

Give your program authority over an eATA, delegate it, move funds PDA-signed on the ER, then settle back to Solana:

Make your program ER-aware

Add the #[ephemeral] attribute and import the SDK helpers.

Create the custody PDA and eATA

Own an eATA under the Ephemeral SPL Token program from your custody PDA.

Delegate the eATA

CPI into the Ephemeral SPL Token program to delegate it to the ER.

Move tokens PDA-signed

Sign the transfer as the custody PDA inside the rollup.

Commit & undelegate

Return the account to the base layer.

Custody Example

The following software packages may be required, other versions may also be compatible:

Software	Version	Installation Guide
Solana	3.1.9	Install Solana
Rust	1.89.0	Install Rust
Anchor	1.0.2	Install Anchor
Node	24.10.0	Install Node

Code Snippets

1. ER-aware program

Wrap #[program] with #[ephemeral] and import the SDK helpers you need.

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

#[ephemeral]
#[program]
pub mod your_program {
    use super::*;
    // ...
}

⬆️ Back to Top

2. Create eATA

Your program owns a state PDA (for example, a Pool) that is the authority over the funds. Custody on the ER uses an ephemeral ATA (eATA) owned by that PDA, derived from [owner, mint] under the Ephemeral SPL Token program (SPLxh1LVZzEkX99H6rqYizhytLWPZVV296zyYDPagv2).

// The eATA is owned by your custody PDA (e.g. a Pool), derived under the
// Ephemeral SPL Token program from [owner, mint].
let (eata, _bump) = Pubkey::find_program_address(
    &[owner.as_ref(), mint.as_ref()],
    &EPHEMERAL_SPL_TOKEN_PROGRAM_ID,
);

// At initialize, create the eATA (InitializeEphemeralAta) and the per-mint
// global vault that backs every eATA (InitializeGlobalVault), then fund it.

⬆️ Back to Top

3. Delegate eATA

Delegate the eATA with a CPI to the Ephemeral SPL Token program (DelegateEphemeralAta, discriminator 4).

Delegating a plain PDA-owned ATA directly to the ER is not supported — token custody on the ER goes through an eATA. To delegate program state (not a token account), use the SDK’s #[delegate] macro instead.

// Delegate the eATA with a CPI to the Ephemeral SPL Token program.
// An optional trailing validator pubkey routes to a specific validator.
let mut data = vec![4]; // DelegateEphemeralAta
if let Some(validator) = validator {
    data.extend_from_slice(validator.as_ref());
}

let instruction = Instruction {
    program_id: EPHEMERAL_SPL_TOKEN_PROGRAM_ID,
    accounts: vec![
        AccountMeta::new(payer.key(), true),
        AccountMeta::new(ephemeral_ata.key(), false),
        AccountMeta::new_readonly(EPHEMERAL_SPL_TOKEN_PROGRAM_ID, false),
        AccountMeta::new(buffer.key(), false),
        AccountMeta::new(record.key(), false),
        AccountMeta::new(metadata.key(), false),
        AccountMeta::new_readonly(delegation_program.key(), false),
        AccountMeta::new_readonly(system_program.key(), false),
    ],
    data,
};
invoke(&instruction, &account_infos)?;

⬆️ Back to Top

4. PDA-signed transfer

With the eATA delegated, move tokens inside the rollup with an SPL Token CPI signed by the custody PDA via CpiContext::new_with_signer. The signer seeds are [POOL_SEED, bump] — the program authorizes the payout itself, with no user signature.

use anchor_spl::token::{self, Transfer as SplTransfer};

// The custody PDA signs the transfer — no user signature required.
let bump_seed = [pool_bump];
let signer_seeds: &[&[&[u8]]] = &[&[POOL_SEED, &bump_seed]];

let cpi_accounts = SplTransfer {
    from,
    to,
    authority: pool, // the Pool PDA
};
let cpi_ctx = CpiContext::new_with_signer(token_program.to_account_info(), cpi_accounts, signer_seeds);
token::transfer(cpi_ctx, amount)?;

⬆️ Back to Top

Commit & undelegate

Commit the ER state and return the account to the base layer with MagicIntentBundleBuilder.

// The #[commit] attribute on the accounts context supplies
// magic_context and magic_program.
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.pool.to_account_info()])
.build_and_invoke()?;

⬆️ Back to Top

Advanced Code Snippets

Non-custody transfer
Base-layer post-commit payout

If your program doesn’t custody funds — it moves tokens between two already-delegated accounts on a user’s behalf — no PDA signer is needed. The authority is the user’s Signer, with a plain CpiContext::new.

// No PDA signer — the authority is the user's Signer.
let cpi_accounts = SplTransfer {
    from: ctx.accounts.from.to_account_info(),
    to: ctx.accounts.to.to_account_info(),
    authority: ctx.accounts.payer.to_account_info(),
};
token::transfer(CpiContext::new(ctx.accounts.token_program.to_account_info(), cpi_accounts), amount)?;

⬆️ Back to Top

To keep real token accounts on the base layer and delegate only program state, schedule the payout as a post-commit action that runs PDA-signed on the base layer right after a commit — using transfer_checked (Token-2022 compatible) and committing with the action attached.

// Keep real token accounts on base, delegate only program state, and pay out
// PDA-signed on the base layer right after the commit. Use the PDA AccountInfo
// as the payer and pass its seeds to build_and_invoke_signed.
MagicIntentBundleBuilder::new(
    payer_pda.to_account_info(),
    magic_context.to_account_info(),
    magic_program.to_account_info(),
)
    .magic_fee_vault(magic_fee_vault.to_account_info())
    .commit(&[state_pda.to_account_info()])
    .add_post_commit_actions([action])
    .build_and_invoke_signed(&[payer_seeds])?;

The post-commit handler is a normal base-layer instruction — anyone can call it directly, not only the delegation program. Because it signs the transfer with your PDA, it must authenticate the caller; otherwise any wallet can invoke it directly and move your program’s tokens without authorization. Require the injected escrow account as a signer and pin it to ephemeral_balance_pda_from_payer(escrow_auth, 255), and bind escrow_auth to your paying PDA. See Authenticate the caller.

⬆️ Back to Top

Solana Explorer

Get insights about your transactions and accounts on Solana:

Solana Explorer

Official Solana Explorer

Solscan

Explore Solana Blockchain

Solana RPC Providers

Send transactions and requests through existing RPC providers:

Solana

Free Public Nodes

Helius

Free Shared Nodes

Triton

Dedicated High-Performance Nodes

Solana Validator Dashboard

Find real-time updates on Solana’s validator infrastructure:

Solana Beach

Get Validator Insights

Validators App

Discover Validator Metrics

Server Status

Subscribe to Solana’s and MagicBlock’s server status:

Solana Status

Subscribe to Solana Server Updates

MagicBlock Status

Subscribe to MagicBlock Server Status

Get Started

Guides

API Reference

Quick Access

binary-prediction

rewards-delegated-vrf

spl-tokens

Two custody models

Step-By-Step Guide

Custody Example

Code Snippets

1. ER-aware program

2. Create eATA

3. Delegate eATA

4. PDA-signed transfer

Commit & undelegate

Advanced Code Snippets

Solana Explorer

Solana Explorer

Solscan

Solana RPC Providers

Solana

Helius

Triton

Solana Validator Dashboard

Solana Beach

Validators App

Server Status

Solana Status

MagicBlock Status

​Quick Access

binary-prediction

rewards-delegated-vrf

spl-tokens

​Two custody models

​Step-By-Step Guide

​Custody Example

​Code Snippets

​1. ER-aware program

​2. Create eATA

​3. Delegate eATA

​4. PDA-signed transfer

​ Commit & undelegate

​Advanced Code Snippets

​Solana Explorer

Solana Explorer

Solscan

​Solana RPC Providers

Solana

Helius

Triton

​Solana Validator Dashboard

Solana Beach

Validators App

​Server Status

Solana Status

MagicBlock Status

Quick Access

Two custody models

Step-By-Step Guide

Custody Example

Code Snippets

1. ER-aware program

2. Create eATA

3. Delegate eATA

4. PDA-signed transfer

Commit & undelegate

Advanced Code Snippets

Solana Explorer

Solana RPC Providers

Solana Validator Dashboard

Server Status