magicblock

# MagicBlock Development Skill

## Pair with the `solana-dev` skill

Use this skill for MagicBlock-specific concerns: ER/PER, delegation, oracles, Session Keys, cranks, VRF,
Magic Actions, eSPL, and private payments. For general Solana or Anchor work such as scaffolding, PDAs,
account layouts, SPL tokens, clients, wallets, or LiteSVM/Mollusk testing, also load `solana-dev`.

## Key Concepts

**Ephemeral Rollups** enable high-performance, low-latency transactions by locking a delegated
account on the base layer while an ER clone continues to execute under the account's original program
owner. They are useful for gaming, real-time apps, and fast transaction throughput.

**Ephemeral Accounts** are born, used, and closed only inside an ER. They are useful for temporary
high-frequency state, but they never commit to Solana and therefore cannot be the only copy of durable
ownership, balances, rewards, or settlement results.

**Delegation** temporarily assigns the base-layer account to the Delegation Program and clones it into
the ER with its original program owner. Normal program ownership, signer, authority, and account
constraints still apply on the ER; delegation status is a routing and lifecycle concern, not a new
application authorization rule.

**Delegation debugging invariant**: a properly delegated account looks owned by
the delegation program on base, owned by the original program on the ER endpoint
returned by router `getDelegationStatus`, and cloned into the ER with
`delegated=true`.

For the verified SDK v0.16.2 snapshot, use **MagicIntentBundleBuilder** to
schedule commit and commit-and-undelegate intents. Do not use the deprecated
free functions `commit_accounts` and `commit_and_undelegate_accounts`.

**Private Ephemeral Rollups (PER)** gate a delegated account inside a TEE-backed validator with an ER-local `EphemeralPermission`. Delegate only the data account on the base layer, then create, update, and close its permission on the ER with `CreateEphemeralPermissionCpi`, `UpdateEphemeralPermissionCpi`, and `CloseEphemeralPermissionCpi`. Do not create or delegate a separate base-layer permission account.

**Magic Actions** are base-layer instructions scheduled inside an ER transaction via
`MagicIntentBundleBuilder.add_post_commit_actions(...)`. Each attempted base-layer transaction applies
its commit and actions atomically. If any BaseAction fails, the committor removes every BaseAction in
that affected `TransactionStrategy` before retrying its remaining commit strategy; actions in other
transaction/finalize strategies are outside that removal scope. Observe and reconcile every originally
scheduled action: scheduling or eventual commit success alone does not prove that any of them ran.

**Commit sponsorship**: every delegated account gets 10 free commits to base layer by default. To lift
the cap, either re-delegate (refreshes the quota) or attach the validator-scoped `magic_fee_vault` PDA
and a delegated fee payer to the intent bundle. The delegated payer is debited; the fee vault is the
validated destination credited with that commit fee.

**Lamports top-up**: when a delegated account (e.g. a delegated fee payer) needs more lamports on the ER side, use `lamportsDelegatedTransferIx` from the SDK. The transaction is submitted on **base layer** — the Ephemeral SPL Token program creates a single-use lamports PDA, funds it, and delegates it so the ER credits the destination.

**Ephemeral SPL Token** has two surfaces. In the SDK lifecycle model, clients use
`delegateSpl`/`transferSpl`/`undelegateIx`/`withdrawSpl`, and the ER balance appears as a normal SPL token
account at the owner's canonical ATA address, so Anchor programs can use plain SPL Token CPI. In the
direct-program model, contracts use `ephemeral-spl-api` and explicitly work with the eATA/global-vault
PDAs; do not apply the canonical-ATA model to that raw surface.

**Pricing Oracle** republishes supported market feeds for Solana/ER consumers. A safe integration
verifies the expected feed identity, upstream publish-time freshness, value domain, exponent, checked
arithmetic, and user price bounds; successful deserialization alone is not price validation.

**Session Keys** authorize a temporary signer for constrained application actions. Session validity is
separate from SPL token authority: token spending also requires an explicit, bounded token delegate
allowance.

**Architecture**:
```
┌─────────────────┐     delegate      ┌─────────────────────┐
│   Base Layer    │ ───────────────►  │  Ephemeral Rollup   │
│    (Solana)     │                   │    (MagicBlock)     │
│                 │  ◄───────────────  │                     │
└─────────────────┘    undelegate     └─────────────────────┘
     ~400ms                                  ~10-50ms
```

## Default stack

### Programs

Use Anchor with `ephemeral-rollups-sdk`; native and Pinocchio are also supported.

- Use the target repo's existing `ephemeral-rollups-sdk` / Anchor versions unless the task is an explicit upgrade
- The SDK feature flag selects the Anchor range: `anchor` for Anchor 1.x programs, or `anchor-compat` for Anchor >=0.28,<1.0 programs

**Required macros:**

- `#[ephemeral]` on the program module, **before** `#[program]` — injects the `process_undelegation` callback (the delegation program CPIs into it to return the account) and the commit/undelegate intent builders. Commit and undelegation require it; delegation itself does not. Include it on any program that delegates so its accounts can later be undelegated.
- `#[delegate]` and `#[commit]` on the respective delegation/commit account contexts.
- `#[vrf]` on a VRF *request* context **and** `#[vrf_callback]` on the VRF *callback* context — the
  callback macro authenticates fulfillment. Enable the `vrf` feature on `ephemeral-rollups-sdk`.
  SDK v0.16.2 re-exports VRF, so new Anchor code does not need a direct
  `ephemeral-vrf-sdk` dependency. See [vrf.md](references/vrf.md).

**Non-Anchor programs:** use t