magicblock

MagicBlock 开发技能

与 solana-dev 技能搭配使用

对于 MagicBlock 特有的问题，请使用此技能：ER/PER、委托、预言机、Session Keys、cranks、VRF、 Magic Actions、eSPL 和私密支付。对于常规 Solana 或 Anchor 工作，例如项目脚手架、PDA、 账户布局、SPL 代币、客户端、钱包或 LiteSVM/Mollusk 测试，也请加载 solana-dev。

核心概念

Ephemeral Rollups 通过在基础层锁定已委托账户，同时由 ER 克隆账户继续在原始程序所有者下执行，从而实现高性能、低延迟的交易。它们适用于游戏、实时应用和高吞吐量交易场景。

Ephemeral Accounts 仅在 ER 内创建、使用和关闭。它们适用于临时的高频状态，但永远不会提交到 Solana，因此不能作为持久所有权、余额、奖励或结算结果的唯一副本。

委托会临时将基础层账户分配给 Delegation Program，并以其原始程序所有者为所有者将其克隆到 ER。在 ER 上，常规的程序所有权、签名者、权限和账户约束仍然适用；委托状态涉及路由和生命周期管理，而非新的应用授权规则。

委托后的操作通过 delegate_account_with_actions 将指令附加到基础层委托。Delegation Program 会将这些指令存储在委托记录中；验证器会在克隆后于 ER 上运行它们。基础层委托成功并不能证明操作已运行。有关公开或加密载荷、签名者处理和恢复，请阅读 delegation-actions.md。这些操作与提交后在基础层运行的 Magic Actions 不同。

委托调试不变量：正确委托的账户在基础层的所有者应为 delegation program；在路由器 getDelegationStatus 返回的 ER 端点上，所有者应为原始程序；而向该 ER 端点本身发送 getDelegationStatus 后，返回的 isDelegated 应为 true。

对于经过验证的 SDK v0.16.2 快照，请使用 MagicIntentBundleBuilder 来安排提交和提交并取消委托的意图。请勿使用已弃用的自由函数 commit_accounts 和 commit_and_undelegate_accounts。

Private Ephemeral Rollups (PER) 会在由 TEE 支持的验证器中，通过 ER 本地的 EphemeralPermission 限制已委托账户的访问。仅在基础层委托数据账户，然后在 ER 上使用 CreateEphemeralPermissionCpi、UpdateEphemeralPermissionCpi 和 CloseEphemeralPermissionCpi 创建、更新和关闭其权限。请勿创建或委托单独的基础层权限账户。

Magic Actions 是通过 MagicIntentBundleBuilder.add_post_commit_actions(...) 在 ER 交易中安排的基础层指令。每笔尝试执行的基础层交易都会原子性地应用其提交和操作。如果任何 BaseAction 失败，committor 会在重试剩余提交策略之前，移除受影响的 TransactionStrategy 中的所有 BaseAction；其他交易/最终化策略中的操作不在此移除范围内。请观察并核对所有最初安排的操作：仅仅成功安排或最终成功提交，并不能证明其中任何操作已运行。

提交费用和限制涉及 Delegation Program 和验证器。如果不使用费用金库路径，当账户当前 nonce 达到 10 后，普通提交就会失败；已接受的提交仍可能在取消委托时消耗 delegation PDA 的费用预算。使用已委托的付款方和限定于验证器的 magic_fee_vault 时，从提交 26 开始，每个已提交账户会扣除 100_000 lamports。有关费用、退款、赞助、成本估算或费用付款方资金问题，请先阅读 fees-and-commit-economics.md。 Lamports 补充：当委托账户（例如，委托的费用支付方）在 ER 侧需要更多 lamports 时，请使用 SDK 中的 lamportsDelegatedTransferIx。该交易在基础层提交——Ephemeral SPL Token 程序会创建一个一次性 lamports PDA，为其注资并进行委托，以便 ER 为目标账户入账。

Ephemeral SPL Token 有两种使用方式。在 SDK 生命周期模型中，客户端使用 delegateSpl/transferSpl/undelegateIx/withdrawSpl，ER 余额会显示为所有者规范 ATA 地址上的普通 SPL 代币 账户，因此 Anchor 程序可以使用常规 SPL Token CPI。在直接程序模型中，合约使用 ephemeral-spl-api，并显式操作 eATA/全局金库 PDA；不要将规范 ATA 模型套用于该底层接口。私有的基础层→临时层转账现在会将资金转入仅限 ER 使用的 Magic ATA（TS SDK ≥ 0.17.1）。在承诺某项 eSPL 功能可在某个集群上使用之前，请查看 ephemeral-spl-token.md 中的 devnet/mainnet 部署表。

Pricing Oracle 会为 Solana/ER 用户重新发布受支持的市场数据源。安全集成需验证预期的数据源身份、上游发布时间的新鲜度、数值范围、指数、安全算术以及用户价格界限；仅成功反序列化并不代表价格有效。

Session Keys 用于授权临时签名者执行受限的应用操作。会话有效性与 SPL 代币权限相互独立：代币支出还需要明确且有上限的代币委托额度。

架构：

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

默认技术栈

程序

使用 Anchor 和 ephemeral-rollups-sdk；也支持 native 和 Pinocchio。

• 除非任务明确要求升级，否则使用目标仓库现有的 ephemeral-rollups-sdk / Anchor 版本
• SDK 功能标志用于选择 Anchor 版本范围：Anchor 1.x 程序使用 anchor，Anchor >=0.28,<1.0 程序使用 anchor-compat

必需宏：

• 在程序模块上使用 #[ephemeral]，并放在 #[program] 之前——该宏会注入 process_undelegation 回调（委托程序会通过 CPI 调用它以归还账户），以及 commit/undelegate 意图构建器。Commit 和 undelegation 都需要此宏；delegation 本身不需要。在任何执行委托的程序中都应添加此宏，以便之后可以解除其账户的委托。
• 在相应的委托/commit 账户上下文中使用 #[delegate] 和 #[commit]。
• 在 VRF 请求上下文中使用 #[vrf]，并在 VRF 回调上下文中使用 #[vrf_callback]—— 回调宏会验证结果兑现。启用 ephemeral-rollups-sdk 上的 vrf 功能。SDK v0.16.2 重新导出了 VRF，因此新的 Anchor 代码不需要直接依赖 ephemeral-vrf-sdk。请参阅 vrf.md。

**非 Anchor 程序：**使用 ephemeral-rollups-pinocchio crate（委托、commit 和 VRF 都有对应的 Pinocchio 实现）。engine examples 仓库提供了 Anchor 和 Pinocchio 版本的 roll-dice；如果目标程序是 native 而非 Anchor，请使用 Pinocchio。

本技能中的版本是已验证可用的快照或兼容性标记。更改依赖项之前，请检查目标仓库的清单、工具链文件、锁文件以及相关上游源代码。 有关带日期的快照和源代码链接，请参阅 resources.md。

连接

• 用于初始化和委托的基础层连接： https://rpc.magicblock.app/devnet 或 https://rpc.magicblock.app/mainnet
• 用于查询委托状态的 Router 连接： https://devnet-router.magicblock.app/ 或 https://router.magicblock.app/
• 用于操作已委托账户的 Ephemeral Rollup 连接： 使用 Router getDelegationStatus 返回的 fqdn

交易路由

• 委托交易 → 基础层
• 对已委托账户的操作 → Ephemeral Rollup
• 解除委托/commit 交易 → Ephemeral Rollup

操作流程

0. 在设计尚未确定时规划架构

对于新的应用、集成设计、迁移或实施计划，请在编写代码前阅读 architecture-planning.md。判断是否需要 MagicBlock，选择最精简的产品组合，梳理账户和交易路由，定义结算和恢复方式，并选择验证环境。每轮最多提出三个重要问题；否则，请基于明确的假设继续推进。

1. 对操作类型进行分类

• 账户初始化（基础层）
• 委托（基础层）
• 委托后的操作（在基础层安排；克隆后在 ER 上执行）
• 对已委托账户执行的操作（临时 Rollup）
• 提交状态（临时 Rollup）
• 取消委托（临时 Rollup）
• 仅限 ER 的临时账户生命周期（临时 Rollup；绝不提交）
• 异步服务工作（VRF 回调、crank、排队转账或 Magic Action）
• 构建托管 API 交易，然后由客户端签名并提交

2. 选择合适的连接

• 基础层：https://rpc.magicblock.app/devnet 或 https://rpc.magicblock.app/mainnet
• 路由器：https://devnet-router.magicblock.app/ 或 https://router.magicblock.app/
• 临时 Rollup：路由器为该账户的 getDelegationStatus 返回的 fqdn

3. 按照 MagicBlock 特定要求正确实施

对于每项实现，请记录：

• 每笔交易应使用哪个连接
• 操作前对路由器 getDelegationStatus 的检查
• 委托调用与账户定义中的 PDA 种子是否匹配
• 对受支持的基础交易保留预检；仅在存在已知模拟不兼容问题的 ER 路径中使用 skipPreflight: true（说明原因并检查执行日志）
• 委托/取消委托后等待状态传播
• 对于 Ephemeral SPL Token 流程，分别选择存入和取款构建器：使用默认的 shuttle 取款，或显式运行 undelegateIx，等待其基础层提交，然后调用传统的 withdrawSpl(..., { idempotent: false })；直接 CPI 时使用 ephemeral-spl-api 导出内容（而非复制的字节或猜测的种子）
• 对于预言机流程，传入身份、最大有效时长、数值转换、用户限制以及数据过期时的处理方式
• 对于 Session Keys，明确作用范围、过期时间、可选的一次性签名者 lamports 充值、撤销方式、由应用强制执行的支出限额，以及任何单独的 SPL 委托额度
• 对于异步流程，说明接受/安排与完成之间的区别，以及观察、幂等性、超时、重试、退款和对账方式

对于安全敏感的设计、审查和实现，请阅读 security.md。区分协议保证、所需的集成验证、应用策略和 Solana 常规安全要求。不要将应用建议描述为 MagicBlock 协议保证。在审查中，请使用 security.md#review-output 中的模板，针对每项发现报告其运行时、产品状态、标签、来源、后果和测试。

4. 调试实时委托/路由故障

对于 InvalidWritableAccount、缺少私有余额、验证器不匹配或“账户已委托，但 ER 拒绝该账户”之类的问题：

• 从确切的签名或账户公钥开始排查。
• 查询路由器的 getDelegationStatus，并使用其 fqdn 进行 ER 读取/交易。
• 对比基础层所有权、路由器状态、ER 所有权以及近期 ER 交易日志。
• 对于已委托账户，基础层所有权属于委托程序是预期情况。
• 完整操作手册请参阅 debugging.md。

5. 诊断可能的服务端故障

对于可能由服务端引起的意外 RPC、路由、预言机或交易错误：

• 始终获取当前数据；不要根据记忆中的状态作答。使用直接 JSON API https://status.magicblock.app/api/services 作为事实来源。
• 选择代码使用的同一网络：JSON 键为 mainnet 和 devnet。
• 将受影响的端点与正确的区域、服务器和服务对应起来：
  • 区域包括 asia、europe、usa 和 tee。
  • 服务 ID 列在 .meta.services 中；当前包括 er（Ephemeral Rollup）、rpc_router、pricing_oracle 和 vrf_oracle。
  • 使用 .environments[network].regions[region].servers 下的服务器条目；对于 mainnet Asia，其中包括 as.magicblock.app。
• 解读 .live_status[service]：true = 正常运行，false = 已停机，缺失/未定义 = 不适用。
• 将 .metrics[service] 解读为每天的停机分钟数，并与 UTC 时区的 .meta.days 对齐。
• 报告发现时，注明网络、区域、端点、服务状态和相关日期范围。区分实时状态与历史停机情况。
• 对于直接 ER RPC 端点，可选择使用 JSON-RPC getHealth 或 getVersion 进行交叉验证，但不要用单次 RPC 探测代替状态 API。

6. 添加适当的功能

• Cranks，用于定期自动执行交易
• VRF，用于游戏/抽奖中的可验证随机性
• Private payments API，用于私密转账和兑换
• Pricing Oracle，用于经验证的外部市场数据
• Session Keys，用于重复且低摩擦的用户操作
• Ephemeral Accounts，用于明确允许消失的临时状态

组合产品时，请阅读 composition-patterns.md，并将权限、代币控制、预言机有效性、ER 执行、基础结算和异步完成视为相互独立的保证。

7. 交付要求

实现更改时，请提供：

• 确切的变更文件及差异
• 安装/构建/测试命令
• 涉及委托/签名/状态提交的任何风险说明

渐进式披露（按需阅读）

• 架构规划、输出模板和验证环境选择：architecture-planning.md
• 跨产品选择和边界设计：composition-patterns.md
• MagicBlock 专属安全边界和源代码标准：security.md
• 调试 ER/委托故障：debugging.md
• 核心委托模式：delegation.md
• 委托后的 ER 操作，包括私有负载：delegation-actions.md
• 费用、提交限制、委托退款、操作收费和费用金库经济机制：fees-and-commit-economics.md
• Ephemeral Accounts（仅限 ER 的临时状态）：ephemeral-accounts.md
• Magic Actions（提交后在基础层执行的指令）：magic-actions.md
• 为已委托账户补充 lamports：lamports-topup.md
• Ephemeral SPL Token 生命周期（存入、转账、应用程序调用程序 CPI、取消委托、提取、Magic ATA、devnet/mainnet 部署状态）：ephemeral-spl-token.md
• TypeScript 前端设置：typescript-setup.md
• Cranks（定时任务）：cranks.md
• VRF（随机数）：vrf.md
• Pricing Oracle（数据源标识、新鲜度和安全使用）：pricing-oracle.md
• Session Keys（范围受限的临时权限）：session-keys.md
• Private Payments API（包括 gasless、x402/MPP 商户结账、实时功能状态）：private-payments.md
• 本地开发和特定环境验证：local-development.md
• 参考链接和版本：resources.md

Terminal Self-Heal 提案

最终回复前，请根据此技能预期的工作流检查整个执行过程。

检查：

• 预期与实际的用户可见输出
• 命令、脚本、验证和产物结果
• 遗漏的覆盖范围或跳过的工作流步骤
• 过时的说明或脆弱的措辞
• 意外的脚本/输出不匹配
• 验证缺口
• 备用方案或临时处理方式

如果发现缺口，请附上证据进行报告，并请求明确批准后再开展单独的维护任务。正常执行期间，应将已安装的技能文件视为只读。