MagicBlock Engine

Solana execution and state management for ephemeral rollups.

✨ API tour · 🧩 Workspace · 🔬 Runtime internals

Engine is the execution core behind MagicBlock Validator (MBV). It runs Solana transactions over account state in an ephemeral rollup (ER), bringing together the SVM, parallel scheduling, persistent storage, live events, and replication.

MBV takes care of base-chain integration and commit policy; Engine handles local execution and state. Its blocks mark execution boundaries, not consensus or confirmation. This repo is where those execution and storage pieces come together.

A few API examples give a feel for what Engine handles. Configuration and the finer contracts live in the linked crate READMEs.

With storage, authority, and initial state configured in a KeeperBuilder, one handle starts the stores, recovery, execution workers, and block pacing:

use engine::Engine;
use nucleus::shutdown::ShutdownManager;

let mut shutdown = ShutdownManager::default();
let engine = Engine::new(builder, None, &mut shutdown).await?;

Engine can generate its own block boundaries or follow an external pacer. Startup and orchestration →

Independent transactions run concurrently; conflicting account accesses keep their input order. Preview a transaction, then execute it against local state:

let simulation = engine.transaction(transaction.clone())?.simulate(true).await?;
let result = engine.transaction(transaction)?.execute().await?;

For queue-only submission, use engine.transaction(transaction)?.schedule().await?. Execution and simulation results can contain transaction-level failures even when the Engine call succeeds. Cancelling a wait doesn't cancel submitted execution. Transaction semantics →

Delegated and ER-created state is persisted; rebuildable external-chain mirrors stay in memory. Account imports can include follow-up instructions in the same transaction, so activation and the work that depends on it succeed or fail together:

engine.account(key).await?.materialize(account, actions).await?;

MBV validates the external state; Engine enforces lifecycle and slot rules. Materialization can also skip an already handled or superseded image. Account lifecycle and imports →

Subscribe to account changes, transaction results, logs, and blocks. Retained history supports queries and replay alongside those live streams:

let mut account_updates = engine.accounts().subscribe(key);
let mut blocks = engine.blocks().subscribe();

let update = account_updates.recv().await;
let block = blocks.recv().await;

Account and block subscribers have bounded queues; slow receivers are disconnected. Other streams have their own delivery contracts. Subscriptions → · History →

A source serves ordered history over TCP. Followers authenticate it, re-execute transactions locally, and check history and persisted-state boundaries:

Source:   allow follower identities → serve retained history
Follower: trust source authority → replay transactions and block boundaries

Followers resume from a synchronized position while history is retained. Otherwise, snapshot transfer stages state for a host-managed restart. This is execution replication, not consensus between peers. Replication →

Coordinated shutdown drains work and synchronizes storage. Keep Engine and the async runtime alive while services finish:

let reason = shutdown.wait().await;
// Stop accepting new requests.
let reason = reason.combine(shutdown.terminate().await);

On restart, Engine validates stored state and, when needed, restores a retained snapshot and replays history before accepting new work. Recovery depends on retained state; it doesn't guarantee complete queryable crash-tail history, and execution completion alone isn't a disk-sync guarantee. Recovery → · Durability →

Engine uses local forks of Agave's runtime to support its account lifecycle and borrowed storage. Account data is mapped directly into the SBF VM, while storage and commit decisions stay outside the SVM. These adaptations let execution work with Engine's state model without importing validator machinery.

The runtime overview covers the fork boundaries, direct mapping, and compatibility constraints.

Start with the Engine README for the architecture, or pick a crate below. Each README explains its role, design constraints, and source entry points. Validator setup and surrounding services live in MBV.