Ephemeral SPL Token Quickstart - MagicBlock Documentation

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.Quick install for Claude Code:

npx add-skill 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

Check out example:

GitHub

SPL Tokens Anchor Implementation

Live Example App

Try private payments

Snippets target @magicblock-labs/ephemeral-rollups-sdk v0.14.3 with the legacy-vault path. The idempotent-shuttle path targets v0.15.3 — keep the same path across delegateSpl / undelegateIx / withdrawSpl within one lifecycle.

Step-By-Step Guide

Move SPL tokens through the full lifecycle against the Ephemeral SPL Token program SPLxh1LVZzEkX99H6rqYizhytLWPZVV296zyYDPagv2 — delegate, transact on the ER, then settle back to Solana:

Delegate the token account

Delegate an owner’s balance to a validator on the base layer. The first delegation for a mint creates the shared Global Vault.

Transfer on the ER

Move tokens between eATAs inside the rollup — public or private.

Undelegate & commit

Undelegate on the ER and wait for the commit back to base.

Withdraw to base

Move the balance out of the Global Vault to a base-layer token account.

Ephemeral SPL Token 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

Install the SDK:

yarn add @magicblock-labs/ephemeral-rollups-sdk@0.14.3

Code Snippets

1. Delegate
2. Transfer
3. Undelegate
4. Withdraw
ER-aware program

delegateSpl delegates an owner’s balance to a validator. The first delegation for a mint creates the shared Global Vault (initVaultIfMissing: true); later ones reuse it. Send on the base layer, and fund the rent sponsor (deriveRentPda()) before delegating.

// Legacy vault flow — keep the same idempotent setting across
// delegateSpl / undelegateIx / withdrawSpl within one lifecycle.
const delegateOpts = { validator, idempotent: false as const, payer: admin.publicKey };

const ixs = await delegateSpl(owner.publicKey, mint.publicKey, amount, {
  ...delegateOpts,
  initVaultIfMissing, // true for the first owner of this mint, false after
});

await provider.sendAndConfirm(
  new anchor.web3.Transaction().add(...ixs),
  [owner, admin],
  { commitment: "confirmed", skipPreflight: true },
);

⬆️ Back to Top

transferSpl moves tokens between eATAs inside the rollup. Send on the ephemeral provider. Set visibility: "private" for a private payment or "public" for a normal fast transfer.

// Delegation confirms on base before the ER clones the account —
// poll the ER view before transferring.
await waitForErTokenAccount(ata, expectedAmount);

const transferIxs = await transferSpl(
  recipientA.publicKey,
  recipientB.publicKey,
  mint.publicKey,
  2n,
  { visibility: "public", fromBalance: "ephemeral", toBalance: "ephemeral" },
);

await providerEphemeralRollup.sendAndConfirm(
  new anchor.web3.Transaction().add(...transferIxs),
  [recipientA],
  { commitment: "confirmed", skipPreflight: true },
);

⬆️ Back to Top

Undelegate each owner on the ER (one per transaction), then wait for the commit back to base with GetCommitmentSignature before withdrawing.

const sgn = await providerEphemeralRollup.sendAndConfirm(
  new anchor.web3.Transaction().add(undelegateIx(owner.publicKey, mint.publicKey)),
  [owner],
  { commitment: "confirmed", skipPreflight: true },
);

// Wait for the commit back to base before withdrawing, or the withdraw
// races the commit and fails with InvalidAccountOwner.
const commit = await GetCommitmentSignature(sgn, providerEphemeralRollup.connection);
await connection.confirmTransaction(commit, "confirmed");

⬆️ Back to Top

withdrawSpl moves the balance out of the Global Vault back to the owner’s base-layer ATA.

const withdrawIxs = await withdrawSpl(owner.publicKey, mint.publicKey, amount, {
  idempotent: false,
});

await provider.sendAndConfirm(
  new anchor.web3.Transaction().add(...withdrawIxs),
  [owner],
  { commitment: "confirmed" },
);

⬆️ Back to Top

To route the ER-side transfer through your own program instead of the SDK helper, add the #[ephemeral] attribute — the instruction is a plain SPL Token CPI. See Smart Contract Integration for custody and PDA-signed transfers.

use anchor_lang::prelude::*;
use anchor_spl::token::{self, Token, TokenAccount, Transfer as SplTransfer};
use ephemeral_rollups_sdk::anchor::ephemeral;

#[ephemeral]
#[program]
pub mod spl_tokens {
    use super::*;

    /// Transfer `amount` of SPL tokens from `from` to `to`.
    pub fn transfer(ctx: Context<TransferTokens>, amount: u64) -> Result<()> {
        require!(amount > 0, ErrorCode::InvalidAmount);
        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(),
        };
        let cpi_ctx = CpiContext::new(ctx.accounts.token_program.to_account_info(), cpi_accounts);
        token::transfer(cpi_ctx, amount)?;
        Ok(())
    }
}

⬆️ Back to Top

Run it locally: yarn → yarn build → yarn setup (boots the local base + ER cluster; leave running) → yarn test:local in a second terminal.

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

MagicBlock Products

Ephemeral Rollup (ER)

Execute real-time, zero-fee transactions securely on Solana.

Private Ephemeral Rollup (PER)

Protect sensitive data with compliance — built on top of Ephemeral Rollups.