⚡ MagicBlock Engine - Integration Examples

Scaling solution for performant, composable games and applications.

✨Overview

This repository contains examples of how to use the different features available in an Ephemeral Rollup (ER). Read more about Ephemeral Rollups here.

To view integrated demos for specific usecases, please look at MagicBlock Starter Kits.

👷 Examples

🧱 Basic Examples

Core feature demos like delegation, randomness and privacy - the place to start.

➕ Counter / Anchor Counter program in Anchor.	🦀 Counter / Native Rust Counter program in native Rust.	🪵 Counter / Pinocchio Counter program built with Pinocchio.
🔒 Private Counter / Anchor Anchor counter with permissions.	🪵 Private Counter / Pinocchio Pinocchio counter with magic permission accounts.	💰 SPL Tokens / Anchor SPL token delegation, ER transfers, and withdrawal back to base layer.
🎲 Roll Dice / Anchor Dice roll using a verifiable random function (VRF) on the ER.	🎲 Roll Dice / Pinocchio Pinocchio VRF dice variant.
📊 Oracle Priced Purchase / Anchor USD-priced token purchase using real-time oracle prices.

🧩 Feature Examples

Focused demos of individual capabilities — on-curve delegation, actions, ephemeral accounts, cranks, sessions.

📈 On-Curve Delegation / Client Delegate on-curve accounts to the ER and manage their lifecycle.	✨ Magic Actions / Anchor Execute base-chain actions from inside an Ephemeral Rollup.	✨ Delegation Actions / Anchor Attach actions that the ER runs automatically right after delegation.
💬 Ephemeral Account Chats / Anchor Anchor chat program using "magic accounts" (ER-only).	⏱️ Crank Counter / Anchor Counter driven by MagicBlock's scheduled crank system.	🔑 Session Keys / Anchor Counter using gpl-session keys for delegated-signer auth on both base chain and ER.
📈 Binary Prediction / Anchor Up/down SPL-token prediction flow using session keys and an ER price oracle.

🎨 Templates

End-to-end app templates you can fork and build on.

🛡️ Private Payments Next.js demo for MagicBlock private payments.	🏆 Rewards (Delegated VRF) / Anchor Rewards distribution program using delegated VRF.	✊ Rock Paper Scissor / Anchor Two-player RPS with hidden moves on the ER until reveal.
🪄 Magic Gachapon MagicBlock VRF gachapon demo that mints a Metaplex Core NFT reward.

Testing

To run local tests for any example project, use the following steps:

1. Install Dependencies (Local nodes + example directory):

   npm install -g @magicblock-labs/ephemeral-validator@latest
   cd <example-directory>
   yarn install

2. Setup local nodes:

   yarn setup

3. Run Tests Locally:

   yarn test:local

Example: To test the pinocchio-roll-dice example:

cd roll-dice/pinocchio
yarn build
yarn test:local

Local nodes

Setting up local nodes:

• A Solana Test Validator preloaded with all the needed programs to work with ER.
• A local Ephemeral Rollup.
• The Query Filtering Service that replicates the privacy logic happening on TEE nodes, without hardware attestation.

graph LR
  User((User))
  SN["Solana Node:8899"]
  ER["Ephemeral Rollup:7799"]
  QFS["Query Filtering Service:6699"]

  SN <--> ER
  ER <--> QFS
  QFS <--> User

Loading

Set the endpoint to the QFS if you want to test privacy features, or to the ER directly otherwise.

Backward Compatibility

Older pre-Anchor 1.0 versions of the migrated programs are kept in 00-LEGACY_EXAMPLES. The 00- prefix keeps these compatibility references listed before the active examples in alphabetical folder views. These examples are for users who still need the previous Anchor 0.32.1 implementations while upgrading to the current Anchor 1.0 programs.