magicblock
Build and debug MagicBlock apps on Solana. Covers Ephemeral Rollups for gasless, real-time, low-latency, high-frequency transactions (games, trading, payments, social); private execution and private SPL payments (PER/TEE); verifiable randomness (VRF); price feeds; cranks and scheduled tasks; session keys; and delegate, commit, and undelegate flows. Use when a Solana app needs gasless or high-throughput transactions, an onchain game, private or confidential transfers, onchain randomness, or automation, even if MagicBlock is not named. Also use for MagicBlock integration, settlement, and production troubleshooting.
How do I install this agent skill?
npx skills add https://github.com/magicblock-labs/magicblock-dev-skill --skill magicblockIs this agent skill safe to install?
- Gen Agent Trust Hubfail
This skill provides a comprehensive developer toolkit for the MagicBlock ecosystem on Solana, covering Ephemeral Rollups, Private Payments, and Session Keys. It utilizes official MagicBlock infrastructure and standard developer packages, while providing extensive guidance on security best practices for blockchain integration.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
- Runlayerwarn
5/6 files flagged
What does this agent skill do?
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.
Post-delegation actions attach instructions to a base-layer delegation with
delegate_account_with_actions. The Delegation Program stores them in the delegation record; the
validator runs them on the ER after cloning. Base-layer delegation success does not prove that the
action ran. For public or encrypted payloads, signer handling, and recovery, read
delegation-actions.md. These are distinct from post-commit
Magic Actions, which run on the base layer.
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 reported isDelegated: true by
getDelegationStatus sent to that ER endpoint itself.
With the SDK 0.18.x pin (and 0.17.x), 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. For new code, do not create or delegate a separate base-layer permission account. That is application guidance, not a protocol rule: the legacy v1 base-layer permission path still works (see delegation.md).
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 fees and limits span the Delegation Program and validator. Without the fee-vault path,
a plain commit fails with 0xA0000000 once the account's commit nonce reaches 10, so commit 11
fails when commits land one at a time. On 1.x the check reads the last landed nonce, so commits
queued before earlier ones land are not counted yet; 2.0 counts queued commits. That is a hard cap
until the account is undelegated; commit-and-undelegate stays allowed so it can exit. Re-delegating resets the count but
does not make commits free: the delegation deposit pays a 3M session fee plus 1M per commit after the
first at undelegation. For short seeds without actions the deposit is about 2.8M–3.3M lamports, so
nothing is refunded once a session has committed twice; longer seeds or actions raise the deposit
and can leave a refund. With a delegated
payer and validator-scoped magic_fee_vault, commit 26 onward debits 1_000_000 lamports per
committed account on the live validators (8886db2; the v1.1.1 tag charged 100_000). The live
validators refuse to commit an account larger than 10,240 bytes, so do not delegate accounts you will
need to commit above that size. Read
fees-and-commit-economics.md first for fee, refund,
sponsorship, cost-estimation, or fee-payer funding questions.
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. Private base→ephemeral transfers now
credit an ER-only Magic ATA (TS SDK ≥ 0.17.1). Before you promise that an eSPL feature works on
a cluster, check the devnet/mainnet deployment table in
ephemeral-spl-token.md.
Pricing Oracle republishes Pyth Lazer feeds into accounts updated on the ER. Read them on the
ER only: the base-layer copies are delegated and stale (mainnet SOL/USD was 462 days old on
2026-11-19). The stored exponent is +8 on every feed, so take the exponent from the feed list.
Feeds are PriceUpdateV3 accounts owned by PriCems…; Account<PriceUpdateV2> rejects them. A safe
integration verifies the feed account and owner, upstream publish-time freshness, value domain,
checked arithmetic, and user price bounds; successful deserialization alone is not price validation.
See pricing-oracle.md.
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:
anchorfor Anchor 1.x programs, oranchor-compatfor Anchor >=0.28,<1.0 programs (SDK 0.18.x and earlier). SDK 0.20.0 removedanchor-compat(#317), so new code should target Anchor 1.x - Product features are opt-in:
access-control(PER),spl(eSPL),vrf, andcrank
Required macros:
#[ephemeral]on the program module, before#[program]— injects theprocess_undelegationcallback (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 thevrffeature onephemeral-rollups-sdk. SDK 0.17+ re-exports VRF behind that feature, so new Anchor code does not need a directephemeral-vrf-sdkdependency. In 0.17,create_request_randomness_ixis the scoped request (0.16 called itcreate_request_scoped_randomness_ix); 0.18 deprecates it in favour ofcreate_request_randomness_ix_const. On 0.20.0,#[vrf]does not compile. See vrf.md.
Non-Anchor programs: use the
ephemeral-rollups-pinocchio crate (delegation, commit, and VRF have Pinocchio equivalents). The
engine examples repo ships Anchor and Pinocchio variants of roll-dice; use Pinocchio when
the target program is native rather than Anchor.
Versions in this skill are known-good snapshots or compatibility markers. Before changing dependencies, inspect the target repository's manifests, toolchain files, lockfiles, and relevant upstream sources. See resources.md for the dated snapshot and source links.
Validators (checked 2026-11-19). Validator 2.0 is released: v2.0.2 is the GitHub Latest
release and npm latest is 2.0.1. Only devnet-us runs it (getVersion reports core 2.0.0,
commit 9456c18), and the devnet router can place delegations there. The other public and TEE ERs
report magicblock-core 1.1.1 but run V1 branch head 8886db2, not the v1.1.1 tag. 8886db2
differs from the tag in the fee-vault commit fee and in the no-vault limit on commit_finalize; see
fees-and-commit-economics.md. 2.0 moves scheduled tasks to
Hydra and changes the commit receipt log (cranks.md,
delegation.md). Check getVersion on the target ER before relying on
either behavior: 2.0 reports core, 1.x reports magicblock-core.
SDK lines. Pin ephemeral-rollups-sdk (Rust) and @magicblock-labs/ephemeral-rollups-sdk (npm,
dist-tag legacy) to 0.18.x for the public ERs; it supports validator 1.x and 2.0. 0.20.x is the
2.0 line (anchor-lang ≥ 1.2.2, no anchor-compat, kit ^8); use it only against 2.0 endpoints. Its
Rust #[vrf] fails to compile (E0433 slot_hashes), and its TS GetCommitmentSignature throws on
v1 logs. 0.17.x's GetCommitmentSignature throws on v2 logs. cargo add without a version and npm
@latest resolve to 0.20. See resources.md.
Connections
- Base layer connection for initialization and delegation:
https://rpc.magicblock.app/devnetorhttps://rpc.magicblock.app/mainnet - Router connection for delegation status:
https://devnet-router.magicblock.app/orhttps://router.magicblock.app/ - Ephemeral rollup connection for operations on delegated accounts:
use the
fqdnreturned by routergetDelegationStatus
Transaction routing
- Delegate transactions → Base Layer
- Operations on delegated accounts → Ephemeral Rollup
- Undelegate/commit transactions → Ephemeral Rollup
Operating procedure
0. Plan architecture when the design is not fixed
For a new application, integration design, migration, or implementation plan, read architecture-planning.md before writing code. Decide whether MagicBlock is needed, select the smallest product set, map accounts and transaction routing, define settlement and recovery, and choose validation environments. Ask at most three material questions per round; otherwise proceed with explicit assumptions.
1. Classify the operation type
- Account initialization (base layer)
- Delegation (base layer)
- Post-delegation action (scheduled on base layer; executed on the ER after cloning)
- Operations on delegated accounts (ephemeral rollup)
- Commit state (ephemeral rollup)
- Undelegation (ephemeral rollup)
- ER-only Ephemeral Account lifecycle (ephemeral rollup; never commits)
- Asynchronous service work (VRF callback, crank, queued transfer, or Magic Action)
- Hosted API transaction construction followed by client signing/submission
2. Pick the right connection
- Base layer:
https://rpc.magicblock.app/devnetorhttps://rpc.magicblock.app/mainnet - Router:
https://devnet-router.magicblock.app/orhttps://router.magicblock.app/ - Ephemeral rollup: the
fqdnreturned by routergetDelegationStatusfor the account
3. Implement with MagicBlock-specific correctness
For each implementation, record:
- Which connection to use for each transaction
- Router
getDelegationStatuschecks before operations - PDA seeds matching between delegate call and account definition
- Preserving preflight for supported base transactions. On the ER, preflight is not a simulation:
the transaction executes and is recorded either way, and
skipPreflight: trueonly makessendTransactionreturn before execution, so it hides the execution error. If you skip it, check the ER transaction status and logs - Waiting for state propagation after delegate/undelegate
- For Ephemeral SPL Token flows, selecting the deposit and withdrawal builders independently: use the
default shuttle withdrawal, or explicitly run
undelegateIx, wait for its base commit, and call the legacywithdrawSpl(..., { idempotent: false }); useephemeral-spl-apiexports (not copied bytes or guessed seeds) for direct CPI - For oracle flows, feed identity, maximum age, numeric conversion, user limits, and stale-feed behavior
- For Session Keys, scope, expiry, optional one-time signer lamports top-up, revocation, application- enforced spending limits, and any separate SPL delegate allowance
- For asynchronous flows, the difference between acceptance/scheduling and completion, plus observation, idempotency, timeout, retry, refund, and reconciliation
For security-sensitive designs, reviews, and implementations, read security.md. Separate protocol guarantees from required integration validation, application policy, and ordinary Solana security. Do not present an application recommendation as a MagicBlock protocol guarantee. In a review, report each finding with its runtime, product state, label, source, consequence, and test, using the template in security.md#review-output.
4. Debug live delegation/routing failures
For InvalidWritableAccount, missing private balances, validator mismatch, or
"account is delegated but ER rejects it" reports:
- Start from the exact signature or account pubkey.
- Query router
getDelegationStatusand use itsfqdnfor ER reads/transactions. - Compare base ownership, router status, ER ownership, and recent ER transaction logs.
- Treat base ownership by the delegation program as expected for a delegated account.
- Base-layer settlement transactions are v1 transactions: fetch them with
maxSupportedTransactionVersion: 1. - See debugging.md for the full runbook.
5. Diagnose possible service-side failures
For unexpected RPC, routing, oracle, or transaction errors that could be service-side:
- Always fetch current data; do not answer from remembered status. Use the direct JSON API
https://status.magicblock.app/api/servicesas the source of truth. - Select the same network the code uses: JSON keys are
mainnetanddevnet. - Match the affected endpoint to the right region/server and service:
- Regions are
asia,europe,usa, andtee; mainnet also hasasia-tyoandsouthamerica. - Service IDs are listed in
.meta.services; currentlyer(Ephemeral Rollup),rpc_router,pricing_oracle, andvrf_oracle. - Use the server entries under
.environments[network].regions[region].servers; for mainnet Asia this includesas.magicblock.app.
- Regions are
- Interpret
.live_status[service]:true= Operational,false= Down, missing/undefined = N/A. - Interpret
.metrics[service]as downtime minutes per day aligned with.meta.daysin UTC. - When reporting findings, include the network, region, endpoint, service status, and relevant date range. Distinguish live status from historical downtime.
- For direct ER RPC endpoints, optionally correlate with JSON-RPC
getHealthorgetVersion, but do not let a single RPC probe replace the status API.
6. Add appropriate features
- Cranks for recurring automated transactions (SDK
crankfeature; see cranks.md for Hydra and validator 2.0 changes) - VRF for verifiable randomness in games/lotteries
- Private payments API for private transfers and swaps
- Pricing Oracle for verified external market data
- Session Keys for repeated low-friction user actions
- Ephemeral Accounts for temporary state that is explicitly allowed to disappear
When combining products, read composition-patterns.md and keep authority, token control, oracle validity, ER execution, base settlement, and asynchronous completion as separate guarantees.
7. Deliverables expectations
When you implement changes, provide:
- Exact files changed + diffs
- Commands to install/build/test
- Risk notes for anything touching delegation/signing/state commits
Progressive disclosure (read when needed)
- Architecture planning, output templates, and validation-environment selection: architecture-planning.md
- Cross-product selection and boundary design: composition-patterns.md
- MagicBlock-specific security boundaries and source standards: security.md
- Debugging ER/delegation failures: debugging.md
- Core delegation patterns: delegation.md
- Post-delegation ER actions, including private payloads: delegation-actions.md
- Fees, commit limits, delegation refunds, action charges, and fee-vault economics: fees-and-commit-economics.md
- Ephemeral Accounts (ER-only temporary state): ephemeral-accounts.md
- Magic Actions (post-commit base-layer instructions): magic-actions.md
- Topping up a delegated account with lamports: lamports-topup.md
- Ephemeral SPL Token lifecycle (deposit, transfer, app-program CPI, undelegate, withdraw, Magic ATAs, devnet/mainnet deployment status): ephemeral-spl-token.md
- TypeScript frontend setup: typescript-setup.md
- Cranks (scheduled tasks): cranks.md
- VRF (randomness): vrf.md
- Pricing Oracle (feed identity, freshness, and safe consumption): pricing-oracle.md
- Session Keys (scoped temporary authority): session-keys.md
- Private Payments API (incl. gasless, x402/MPP merchant checkouts, live-feature status): private-payments.md
- Local development, in-process MagicSVM tests (ER lifecycle, cranks, VRF callbacks), and environment-specific validation: local-development.md
- Reference links & versions: resources.md
Terminal Self-Heal Proposal
Before the final response, review the entire run against this skill's intended workflow.
Check:
- expected vs actual user-visible outputs
- command, script, validation, and artifact results
- missed coverage or skipped workflow steps
- stale instructions or brittle wording
- unexpected script/output mismatches
- verification gaps
- fallback or impromptu behavior
If gaps are found, report them with evidence and request explicit approval for a separate maintenance task. Treat installed skill files as read-only during normal execution.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/magicblock-labs/magicblock-dev-skill/magicblock">View magicblock on skillZs</a>