Skip to content

spec: add shielded EVM payments for exact scheme (privacy pools)#1951

Open
mmchougule wants to merge 2 commits intox402-foundation:mainfrom
mmchougule:spec/exact-evm-shielded
Open

spec: add shielded EVM payments for exact scheme (privacy pools)#1951
mmchougule wants to merge 2 commits intox402-foundation:mainfrom
mmchougule:spec/exact-evm-shielded

Conversation

@mmchougule
Copy link
Copy Markdown

@mmchougule mmchougule commented Apr 7, 2026

Summary

Adds specs/schemes/exact/scheme_exact_evm_shielded.md — a new assetTransferMethod: "shielded" for the exact scheme on EVM chains.

Enables privacy-preserving x402 payments where the payer's wallet address is hidden behind a ZK proof verified on-chain by the privacy pool contract. The facilitator confirms the resulting ERC-20 Transfer event matches the payment requirements.

How it works

On-chain (privacy pool contract handles):

  • Client generates a groth16 ZK proof proving ownership of a shielded UTXO
  • Proof includes nullifiers that mark the UTXO as spent (double-spend prevention)
  • Pool contract verifies the proof, checks nullifiers, executes the ERC-20 transfer
  • If the tx succeeds, the ZK proof was valid and funds are transferred

Facilitator verification:

  • Client sends txHash in PAYMENT-SIGNATURE header
  • Facilitator fetches tx receipt (non-reverted = pool contract accepted the proof)
  • Checks ERC-20 Transfer event: from is registered pool contract, to matches payTo, value >= required
  • Tracks txHash to prevent same payment being reused for multiple API calls

Design decisions

  • Fits under exact scheme as a new assetTransferMethod — same payment semantics as EIP-3009/Permit2/ERC-7710, different transfer mechanism
  • ZK proof verification and nullifier double-spend prevention happen on-chain in the pool contract — facilitator doesn't need to verify proofs
  • General — works with any privacy pool that verifies ZK proofs and emits standard ERC-20 Transfer events
  • Client-driven settlement — client submits the unshield tx, facilitator is verify-only

Closes #1953

Adds `specs/schemes/exact/scheme_exact_evm_shielded.md` — the specification
for a new `assetTransferMethod: "shielded"` under the existing `exact` scheme
on EVM chains.

This enables privacy-preserving x402 payments where the payer's identity is
hidden behind a ZK proof verified by an on-chain privacy pool (e.g., Railgun).
The facilitator verifies payments by inspecting the standard ERC-20 Transfer
event emitted during unshield — no viewing keys or trial decryption required.

Key properties:
- Settlement: Client-driven (unshield on-chain before verification)
- Verification: ERC-20 Transfer event from registered pool contract
- Privacy: Sender hidden via ZK proof; amount visible to facilitator
- Token: Any ERC-20 supported by the privacy pool (USDC, USDT, DAI)
- Gas: Client pays, or gasless via ERC-4337

This is designed to be general — works with any privacy pool that emits
standard ERC-20 Transfer events, not tied to a specific implementation.

Relates to x402-foundation#1633
@github-actions github-actions bot added the specs Spec changes or additions label Apr 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

specs Spec changes or additions

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add shielded EVM payments as assetTransferMethod for exact scheme

1 participant