Skip to main content

​
クイックアクセス

サンプルを確認：

GitHub

SPL Token の Anchor 実装

ライブサンプルアプリ

プライベート決済を試す

​
概要

プライベート決済は、ER 上の SPL token を基盤とするプライバシー用途です。同じ入金 / 送金 / 出金プリミティブをプライベート可視性 で実行するため、支払額、送信先、タイミングは公開されず保護されます。
このプリミティブを初めて使う場合は、先に Ephemeral SPL Token の 概要をお読みください。このガイドでは eATA / Global Vault / 委任モデルを理解している前提で説明します。
プライベート決済を構築する最も簡単な方法は、ホステッド Ephemeral SPL Token API です。 署名して送信できる未署名トランザクションを返します。

API リファレンス

入金、送金、出金、残高、stealth pool、認証用の endpoint。

リファレンスプログラム

オンチェーンの Ephemeral SPL Token プログラム。

​
プライバシーモデル

プライベート決済は次の仕組みに依存します：
  • プライベート可視性 — visibility: "private" で Ephemeral Rollup 内の送金を実行するため、 公開されません。
  • Stealth handle — raw public key の代わりに alice@magicblock.id のような読みやすい名前へ 送金します。handle は stealth pool を介して 1 つ以上の送信先 key に解決され、オンチェーンの 送信者 → 受信者という直接のつながりを断ちます。
  • キュー型決済 — プライベート送金は、直接かつ即座に関連付けられる移動ではなく、 プログラムの transfer queue を通じて決済できます。
ここでのプライバシーは関連付け可能性を下げるもので、観測可能性を完全になくすものでは ありません。金額やタイミングはネットワークレベルで推測される可能性があります。前提に基づいて 脅威モデルを作成してください。

​
認証

プライベートデータの読み取りと stealth-pool 操作には bearer token が必要です。保護された endpoint を呼び出す前に challenge/login フローで取得します：
1

challenge をリクエスト

GET /v1/spl/challenge はユーザーが署名するメッセージを返します。
2

ログイン

POST /v1/spl/login は署名済み challenge を bearer token と交換します。
3

保護された endpoint を呼び出す

GET /v1/spl/private-balance と POST /v1/spl/stealth-pool では Authorization: Bearer <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".
送信先には 2 つのモードがあります： stealth handle を使用するには、最初に初期化します：
  • POST /v1/spl/stealth-pool — handle（255 UTF-8 byte 以下。正規化されないため Alice@… ≠ alice@…）を 1〜10 個の送信先 owner key にマッピングし、必要に応じて 支払いを分割します。
  • GET /v1/spl/stealth-pool?handle=… — handle の pool が存在するか確認します。
handle は正確な UTF-8 byte のまま保存されます。GET が返すのは pool の存在有無だけで、 送信先 key は返しません。

​
手数料と gasless 送金

visibility と gasless は互いに独立したリクエストフィールドです。visibility は送金のルーティング方法を、gasless は gas の支払い者を決めます。プライベート送金のコストは、常に発生するプライバシー手数料と、選択した gas の支払い方法の合計です。 すべてのプライベート base → base 送金には 0.1%（10 bps）のプライバシー手数料がかかり、送金対象の token で徴収されます — SOL ではありません。gas の支払い方法は 2 通りあります: gasless: true の場合、設定済みの sponsor がトランザクションの fee payer となって共同署名し、API は送信者の残高から sponsor に固定 0.2 USDC/USDT の relay 手数料を支払う token 送金 instruction をトランザクションの先頭に追加します。relay 手数料は固定額のため、gasless 送金には 0.5 USDC/USDT の最低金額が設定されています。この最低金額は gasless モードにのみ適用され、プライベート送金全般には適用されません。それ未満の金額も、gasless を省略すれば visibility: "private" のまま送金できます。 初回のプライベート送金では、ephemeral token account の作成に一度だけ 約 0.00204 SOL の rent がかかる場合があります。token 建ての手数料はすべて送金レスポンスの fees.tokens に、SOL 建てのコストは fees.lamports に返されます。
最低金額未満、または未対応の mint による gasless: true リクエストは 400 エラー（INVALID_GASLESS_TRANSFER_AMOUNT / INVALID_GASLESS_TRANSFER_MINT）で拒否されます。 API がリクエストの visibility を変更することはありません。送金が public になるのは リクエストがそう指定した場合だけです。gasless のエラー処理でリクエストを再構築する クライアントは、プライバシーを意図する場合 visibility: "private" を維持してください。
from が off-curve の PDA owner の場合、gasless: true は無視されます（gasless にはウォレット送信者が必要です）。その場合もリクエストで指定された visibility のまま送金が実行され、送信者が fee payer になります。

​
出金

残高を 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 は正規化されません。 大文字/小文字と空白が区別されるため、一貫して表示・保存してください。
  • フローを一致させます。 Stealth-handle 送金には visibility: "private"、 fromBalance: "base"、toBalance: "base" が必要です（フィールド省略時のデフォルトでもあります）。
  • 署名してから送信します。 Builder endpoint は未署名トランザクションを返します。 POST /v1/transaction/send で送信し、返された sendTo に従ってください。

​
次のステップ

Ephemeral SPL Token — 概要

プライベート決済を支えるプリミティブ。

SDK クイックスタート

オンチェーン / SDK の統合パス。