Skip to main content

ZKP2P Protocol V3 — Overview

ZKP2P V3 is the current production protocol. It enables faster, more flexible, and easier-to-integrate P2P exchange by moving proof verification off-chain into a standardized Attestation Service, and by consolidating on-chain verification logic into a single Unified Payment Verifier. The protocol remains fully non-custodial: contracts only move funds, while verification and orchestration are modular and replaceable.

What's new vs V2​

  • Off-chain verification: the Attestation Service validates payment evidence, normalizes it, and signs an EIP-712 PaymentAttestation used on-chain.
  • Buyer TEE verification: supported buyer payment methods use an enclave-resident verification path where the TEE fetches payment-platform data directly.
  • Seller Autopilot: sellers can upload encrypted platform credentials once; the TEE later verifies matching payments and signs the V3 attestation.
  • Single on-chain verifier: UnifiedPaymentVerifierV2 validates the EIP-712 signature and enforces protocol rules (intent bounds, nullifiers, release capping).
  • Cleaner intent path: the gating service signs intents with richer context (payment method, fiat currency, conversion rate, orchestrator/escrow addresses) to reduce round trips.
  • Extensible: transformer changes for registered payment methods stay off-chain behind a stable attestation format. A new on-chain payment method still requires registry configuration.
  • Oracle-driven rate floors: depositors can configure oracle adapters (Chainlink) per currency to auto-adjust minimum conversion rates based on market prices.
  • Delegated rate management: depositors can opt into external rate managers (RateManagerV1) that set rates on their behalf, enabling programmatic rate updates with fee sharing.
  • Intent admission hooks: one optional generic pre-intent hook runs before state changes, while the active lifecycle hook enforces deposit access policies against direct wallets and on-chain Groups.
  • Manager fees: rate managers can charge fees (capped at 5%) snapshotted at signal time and distributed at fulfillment.
  • Multi-recipient referral fees: referralFees[] array replaces the single referrer + referrerFee fields.
  • Multi-orchestrator support: OrchestratorRegistry allows multiple orchestrator contracts to interact with EscrowV2, replacing the single orchestrator address pattern.

Flow​

  • Buyer (on-ramper): pays off-chain and receives on-chain tokens.
  • Seller (off-ramper): supplies token liquidity in Escrow and receives off-chain fiat.
  • Gating Service (Curator): authorizes intent creation for sellers, returns payee details and a signature.
  • Attestation Service: verifies payment evidence and issues PaymentAttestations.
  • On-chain: EscrowV2, OrchestratorV3, OrchestratorRegistry, RateManagerV1, UnifiedPaymentVerifierV2, AttestationVerifier (witness set), WhitelistPolicy, and AddressGroupRegistry.
  • The optional deposit pre-intent hook and the governance-selected lifecycle hook run before fund locking during signalIntent.

High-level flow​

  1. Quote: client fetches quotes (developer docs cover API).
  2. Intent signing: client calls Curator POST /v3/sign to obtain gatingServiceSignature tied to deposit/payment method/fiat.
  3. Signal Intent (on-chain): call OrchestratorV3.signalIntent(...) with depositId, amount, to, paymentMethod, fiatCurrency, conversionRate, referralFees, and gatingServiceSignature. The optional deposit pre-intent hook runs first; the active lifecycle hook then enforces the deposit's access policy before funds are locked. Any rejection reverts the whole transaction.
  4. Pay off-chain: buyer pays seller's off-chain identifier (hashed on-chain as payeeDetails).
  5. Verify payment through Buyer TEE Verification or Seller Autopilot. In the buyer TEE flow, the enclave decrypts attested-key encrypted buyer session material and queries the platform directly; in Seller Autopilot, the enclave decrypts the seller's encrypted credential bundle, queries the payment platform, and verifies the payment.
  6. Attestation: Attestation Service returns a PaymentAttestation EIP-712 signature and an ABI-encoded payload.
  7. Fulfill (on-chain): call OrchestratorV3.fulfillIntent({ paymentProof: abi.encode(PaymentAttestation), intentHash, ... }). Orchestrator routes to the payment method's registered verifier — currently UnifiedPaymentVerifierV2 for every production method — then unlocks and transfers tokens.

Trust model​

  • TEE-hosted Attestation Service: buyer proof verification, Buyer TEE Verification, and Seller Autopilot run inside an AWS Nitro Enclave. The EIP-712 signing key is KMS-wrapped and PCR8-gated, so it can only be unwrapped by an enclave running the published code measurement; no operator can extract it. Clients can verify the running enclave via GET /attestation?nonce=... before trusting any signed output or encrypting session material to its upload key (reference verifier: @zkp2p/zkp2p-attestation).
  • Off-chain witnesses: Attestation Service signatures are verified on-chain by AttestationVerifier (MultiAttestationVerifier on Base). Witness rotation is on-chain governed.
  • Intent integrity: snapshot values in the attestation are checked against on-chain intent state; nullifiers prevent double-spend; release amount is capped to the signaled amount.
  • Oracle adapter safety: oracle adapters are view-only (no state mutation). Staleness checks ensure stale data is rejected. Oracle rates can only raise the floor, never lower it below the fixed rate.
  • Intent admission constraints: the optional pre-intent hook can only revert to reject. The active lifecycle hook also fails closed if a restricted deposit's WhitelistPolicy does not admit the taker.
  • Manager fee caps: manager fees are capped at 5% (MAX_MANAGER_FEE = 5e16) and snapshotted at signal time so they cannot be changed retroactively.