u402 Protocol Specification

Version: 0.1.0-draft

Status: Draft

Depends on: x402, UPP, UPC

1. Overview

u402 defines a "private" payment scheme for the x402 protocol. When a server returns HTTP 402 with scheme: "private", the client generates zero-knowledge proofs against the Universal Private Pool and returns them in the payment header. The server settles the proofs on-chain without learning the payer's identity.

1.1 Design Goals

• No key transmission. The client's private keys never leave the client. Only ZK proofs are transmitted.
• Proof-as-authorization. The ZK proof replaces the EIP-3009 signature. It simultaneously proves note ownership, balance sufficiency, and (optionally) ASP compliance.
• Proof-system agnostic. The protocol supports multiple proof systems (PLONK/BLS12-381, Circle STARK/M31) through a proofSystem discriminator.
• x402 compatible. u402 follows x402 v2's plugin architecture. Servers can accept both "exact" (plain x402) and "private" (u402) schemes simultaneously.

2. Payment-Required (Server → Client)

When a server requires private payment, it returns HTTP 402 with a Payment-Required header containing:

{
  "scheme": "private",
  "network": "eip155:11155111",
  "pool": "0x3b5ed60adbd5dd57f47ec54179e4b1c06636285b",
  "asset": "0xTokenAddress",
  "payTo": "0xServiceAddress",
  "amount": "1000000000000000000",
  "aspId": 1,
  "acceptedProofSystems": ["plonk", "circle-stark"]
}

2.1 Field Definitions

3. Payment-Signature (Client → Server)

The client generates two ZK proofs — a transfer (split the agent's note into a payment note and change) and a withdraw (convert the payment note to a public ERC-20 transfer to the service provider).

{
  "scheme": "private",
  "proofSystem": "plonk",
  "transfer": {
    "proof": { ... },
    "nullifier": "0x...",
    "stateRoot": "0x...",
    "aspRoot": "0x...",
    "token": "0xTokenAddress",
    "outputCommitment1": "0x...",
    "outputCommitment2": "0x...",
    "encryptedNote1": "0x...",
    "encryptedNote2": "0x..."
  },
  "withdraw": {
    "proof": { ... },
    "nullifier": "0x...",
    "stateRoot": "0x...",
    "aspRoot": "0x...",
    "aspId": 1,
    "token": "0xTokenAddress",
    "amount": "1000000000000000000",
    "recipient": "0xServiceAddress",
    "isRagequit": false
  }
}

3.1 PLONK Proof Format

When proofSystem is "plonk", the proof object contains:

G1 points are encoded as 128-byte uncompressed coordinates (64 bytes x, 64 bytes y) per EIP-2537 format.

3.2 Circle STARK Proof Format

When proofSystem is "circle-stark", the proof field is a single bytes blob — the serialized STARK proof as produced by the Stwo prover, verified by the on-chain CircleStarkVerifier.

3.3 Transfer Fields

3.4 Withdraw Fields

4. Verification Algorithm (Server)

The server MUST perform the following checks before settling:

4.1 Format Validation

1. scheme equals "private"
2. proofSystem is in the server's acceptedProofSystems list
3. All required fields are present and correctly typed
4. withdraw.recipient equals the server's payTo address
5. withdraw.amount >= the server's required amount
6. withdraw.token equals the server's required asset
7. transfer.token equals withdraw.token
8. transfer.nullifier != withdraw.nullifier (different notes)

4.2 Freshness Validation

9. transfer.stateRoot is a known recent root on the pool contract (isKnownRoot())
10. transfer.nullifier has not been used (!nullifierUsed())
11. withdraw.nullifier has not been used (!nullifierUsed())

4.3 Settlement

12. Call pool.transfer(...) with the transfer proof and public inputs
13. Call pool.withdraw(...) with the withdraw proof and public inputs
14. Verify both transactions succeed

If either transaction reverts, the payment has failed. The server MUST NOT return 200.

5. Settlement Dispatch

The server dispatches to different contract functions based on proofSystem:

PLONK and Circle STARK notes live in separate Merkle trees within the same pool contract. A PLONK transfer creates notes in the Poseidon/BLS12-381 tree; a STARK transfer creates notes in the Keccak/M31 tree.

6. Atomicity

The transfer and withdraw are two separate on-chain transactions. This creates a failure window: the transfer may succeed but the withdraw may fail (e.g., due to root staleness).

6.1 Recommended: Router Contract

A router contract that executes both operations in a single transaction eliminates this risk:

function settleU402(
    TransferCalldata calldata transferData,
    WithdrawCalldata calldata withdrawData
) external {
    pool.transfer(transferData);
    pool.withdraw(withdrawData);
}

If either call reverts, the entire transaction reverts.

6.2 Alternative: Sequential Settlement

If no router is deployed, the server settles sequentially. If the transfer succeeds but the withdraw fails:

• The payment note exists in the pool but has not been withdrawn
• The agent's nullifier is consumed (no double-spend risk)
• The server should retry the withdraw, or return an error so the agent can reclaim the note

7. Error Handling

8. Compliance

u402 inherits UPP's compliance model. The aspId field in both the Payment-Required and withdraw proof determines which ASP's allowlist is checked during proof verification.

• ASP ID > 0: The withdraw circuit verifies that the original deposit address is in the specified ASP's Merkle tree. The verifier learns "this address is in the approved set" without learning which address.
• ASP ID = 0 + ragequit: The original depositor can withdraw to their deposit address regardless of ASP status. No compliance proof required.

Servers choose their compliance requirements by setting aspId. Agents that cannot satisfy a particular ASP can use ragequit to reclaim their funds.

For details on running an ASP, see UPC Operators.

9. Reference Implementations