简介 - MagicBlock Documentation

Ephemeral SPL Token Program

链上 Ephemeral SPL Token 程序

私密支付示例

查看私密支付示例应用及其 API 流程

概述

Ephemeral SPL Token API 用于在 Solana 与 MagicBlock ephemeral rollups 之间构建未签名的 SPL token 存入、转账、提取、swap 与 mint 初始化交易。它还提供余额查询、mint 初始化状态、stealth pool，以及为读取私密数据签发 bearer token 的钱包 challenge/login 流程。官方公开参考可见 payments.magicblock.app/reference。

元信息

健康状态 - 检查 API 健康状态与可用性
发送交易 - 将已签名交易提交到 base layer 或 ephemeral RPC

认证

挑战 - 生成需由钱包签名的 challenge 字符串
登录 - 用已签名的 challenge 换取 bearer token

SPL

存入 SPL Token - 构建从 Solana 进入 ephemeral rollup 的未签名存入交易
转移 SPL Token - 构建未签名的公开或私密 SPL 转账
提取 SPL Token - 构建返回 Solana 的未签名提取交易
取消委托 Ephemeral ATA - 构建未签名交易，为某个 mint 取消委托钱包的 eATA
初始化 Mint - 构建未签名交易，为某个 mint 初始化 validator-scoped transfer queue
确保 Transfer Queue Crank 运行 - 验证 mint 的 transfer queue 并强制尝试运行一次 crank
余额 - 获取某地址在基础链上的 SPL token 余额
私密余额 - 获取某地址在 ephemeral rollup 上的 SPL token 余额（需认证）
Mint 是否已初始化 - 检查某个 mint 是否已在 ephemeral RPC 上拥有 validator-scoped transfer queue

Stealth Pool

创建 Stealth Pool - 将 handle 映射到私密转账的目标 key（需认证）
获取 Stealth Pool 状态 - 检查某个 handle 的 stealth pool 是否存在

Swap

Swap 报价 - 获取两个 SPL mint 之间的 swap 报价
兑换 - 构建未签名的 swap 交易（公开直通或带定时转账的私密模式）

MCP

MCP - 访问无状态的 Streamable HTTP MCP 端点

┌────────────────────────────────────────────┐
│ 1. Deposit                                │
├────────────────────────────────────────────┤
│ • Build an unsigned deposit transaction   │
│ • Solana base balance → ephemeral rollup  │
└────────────────────────────────────────────┘
                     ↓
┌────────────────────────────────────────────┐
│ 2. Transfer / Swap                        │
├────────────────────────────────────────────┤
│ • Build SPL transfer or swap              │
│ • base/ephemeral → base/ephemeral         │
│ • public or private (delayed + split)     │
└────────────────────────────────────────────┘
                     ↓
┌────────────────────────────────────────────┐
│ 3. Withdraw                               │
├────────────────────────────────────────────┤
│ • Build an unsigned withdrawal            │
│ • ephemeral rollup → Solana base balance  │
└────────────────────────────────────────────┘

认证流程

读取 Private Ephemeral Rollup 内私密数据的端点需要 bearer token:

GET /v1/spl/challenge?pubkey=<wallet> 返回 challenge 字符串
钱包对该 challenge 进行签名
POST /v1/spl/login 提交 { pubkey, challenge, signature } 返回 token
在 /v1/spl/private-balance (必需) 以及需要连接 Private Ephemeral Rollup 的 /v1/spl/transfer 请求 (可选) 上设置 Authorization: Bearer <token>

响应格式

交易构建端点成功时会返回一个未签名交易载荷:

{
  "kind": "deposit",
  "version": "legacy",
  "transactionBase64": "base64-encoded-transaction",
  "sendTo": "base",
  "recentBlockhash": "blockhash",
  "lastValidBlockHeight": 284512337,
  "instructionCount": 3,
  "requiredSigners": ["3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"]
}

客户端流程为:

调用 API
解码 transactionBase64
如有需要,客户端可对交易进行调整
用所需钱包签名
提交到 sendTo 指定的 RPC ("base" 或 "ephemeral")

开始使用

指南

API 参考

简介

Ephemeral SPL Token Program

私密支付示例

概述

元信息

认证

SPL

Stealth Pool

Swap

MCP

认证流程

响应格式

Ephemeral SPL Token Program

私密支付示例

​概述

​元信息

​认证

​SPL

​Stealth Pool

​Swap

​MCP

​认证流程

​响应格式

概述

元信息

认证

SPL

Stealth Pool

Swap

MCP

认证流程

响应格式