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을 통해 하나 이상의 목적지 key로 해석되어 온체인에서 발신자 → 수신자의 직접 연결을 끊습니다.
  • 대기열 기반 정산 — 프라이빗 전송은 즉시 연결할 수 있는 직접 이동 대신 프로그램의 transfer queue를 통해 정산할 수 있습니다.
여기서 프라이버시는 전체 관찰 가능성을 없애는 것이 아니라 연결 가능성을 낮춥니다. 금액과 시점은 네트워크 수준에서 추론될 수 있습니다. 가정을 바탕으로 위협 모델을 수립하세요.

​
인증

프라이빗 데이터 조회와 stealth-pool 작업에는 bearer token이 필요합니다. 보호된 endpoint를 호출하기 전에 challenge/login 흐름으로 token을 발급받으세요:
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".
목적지 모드는 두 가지입니다: stealth handle을 사용하려면 먼저 초기화하세요:
  • POST /v1/spl/stealth-pool — handle(UTF-8 255 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)의 프라이버시 수수료가 부과되며, SOL이 아니라 전송되는 token으로 청구됩니다. gas는 두 가지 방식으로 지불할 수 있습니다: 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 통합 경로.