Ephemeral SPL Token Quickstart

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

Check out example:

GitHub

SPL Tokens Anchor Implementation

Live Example App

Try the SPL Tokens demo

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.