使用 Ephemeral SPL Token 进行私密支付

---

​

快速访问

查看示例：

---

​

概述

私密支付是构建在 ER 上的 SPL token 之上的隐私用例。同一套存入 / 转账 / 提取原语以私密可见性运行，因此支付金额、目标和时间 不会被公开广播。 构建私密支付最简单的方式是使用托管的 Ephemeral SPL Token API。它会返回由你签名并提交的 未签名交易。

---

​

隐私模型

私密支付依赖以下机制：

• 私密可见性——转账使用 visibility: "private" 在 Ephemeral Rollup 内执行，因此不会公开广播。
• Stealth handle——向易读名称（例如 alice@magicblock.id）而非原始 public key 发送。 handle 通过 stealth pool 解析为一个或多个目标 key，从而打破链上发送者 → 接收者的直接关联。
• 队列式结算——私密转账可以通过程序的 transfer queue 结算，而不是以可立即关联的方式直接转移。

---

​

认证

读取私密数据和执行 stealth-pool 操作需要 bearer token。调用受保护端点前，请通过 challenge/login 流程获取 token：

---

​

存入

将 token 转入 mint 的 Global Vault，并增加存入者 ephemeral ATA 的余额。

• POST /v1/spl/deposit——构建存入交易。设置 private: true 以保持存入余额私密。

响应包含未签名交易和 sendTo 字段（base 或 ephemeral）。完成签名后，通过 POST /v1/transaction/send 或你自己的 RPC 提交。

---

​

私密转账

• POST /v1/spl/transfer with visibility: "private".

目标有两种模式： 要使用 stealth handle，请先初始化：

• POST /v1/spl/stealth-pool——将一个 handle（不超过 255 个 UTF-8 字节；不会规范化，因此 Alice@… ≠ alice@…）映射到 1–10 个目标 owner key，并可选择在其间拆分支付。
• GET /v1/spl/stealth-pool?handle=…——检查 handle 对应的 pool 是否存在。

---

​

提取

将余额从 Global Vault 转回标准的 base-layer SPL token account。

• POST /v1/spl/withdraw——构建提取交易。

可随时查询余额：

• GET /v1/spl/balance——公开余额。
• GET /v1/spl/private-balance——私密余额（需要 bearer token）。

---

​

开发者须知

• 隐私是一个连续谱。 Ephemeral SPL token 会降低可关联性，但不会隐藏金额、时间，也无法防止 网络层分析。
• handle 不会规范化。 大小写和空白字符都会产生影响，请一致地显示和存储 handle。
• 匹配流程。 Stealth-handle 转账要求 visibility: "private"、fromBalance: "base"、 toBalance: "base"（省略这些字段时也会使用这些默认值）。
• 先签名，再发送。 Builder 端点返回未签名交易；请使用 POST /v1/transaction/send 提交， 并遵循返回的 sendTo。

---

​

后续步骤