使用 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 是否存在。

---

​

费用与 gasless 转账

visibility 和 gasless 是两个相互独立的请求字段：visibility 决定转账如何路由，gasless 决定由谁支付 gas。私密转账的成本由始终收取的隐私费用加上所选的 gas 支付方式构成。 每笔私密 base → base 转账都会收取 0.1%（10 bps）的隐私费用，以被转账的 token 计价收取——而不是 SOL。gas 有两种支付方式： 当 gasless: true 时，配置的 sponsor 会成为交易的 fee payer 并共同签名，同时 API 会在交易前置一条 token 转账指令，从发送方余额中向 sponsor 支付固定 0.2 USDC/USDT 的 relay 费用作为补偿。由于 relay 费用是固定的，gasless 转账要求最低金额为 0.5 USDC/USDT；该最低金额仅适用于 gasless 模式，而不适用于私密转账本身。低于该金额的转账仍可通过省略 gasless 并保持 visibility: "private" 来发送。 首次私密转账还可能包含一次性 约 0.00204 SOL 的租金，用于创建 ephemeral token account。所有以 token 计价的费用会在转账响应的 fees.tokens 字段中返回，以 SOL 计价的成本则在 fees.lamports 中返回。 当 from 是 off-curve 的 PDA owner 时，gasless: true 会被忽略（gasless 需要钱包作为发送方）；转账仍会按请求指定的 visibility 执行，由发送方支付费用。

---

​

提取

将余额从 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。

---

​

后续步骤