Protocol Documentation

Technical documentation for the ZKP2P protocol - a permissionless, non-custodial P2P protocol for exchanging off-chain fiat for on-chain crypto.

Protocol Overview

ZKP2P enables peer-to-peer fiat-to-crypto exchanges using privacy-preserving payment verification without exposing sensitive data on-chain.

Core flow:

1. Seller deposits tokens to Escrow with accepted payment methods/currencies
2. Buyer creates intent (locks liquidity)
3. Buyer makes off-chain fiat payment (Venmo, Revolut, etc.)
4. PeerAuth captures the payment metadata required by the selected verification path
5. The Attestation Service verifies payment → Escrow releases tokens to buyer

Current Architecture

User → PeerAuth → Attestation Service → UnifiedPaymentVerifier → Escrow
                             ↓
                  EIP-712 attestation

• Orchestrator: Manages intent lifecycle
• Escrow: Custody-focused, handles deposits/releases
• UnifiedPaymentVerifier: Validates EIP-712 signed attestations
• Attestation Service: Off-chain proof validation

Directory Structure

protocol/
├── zkp2p-protocol.md           # High-level overview, version history
├── gating-service.md           # Identity verification service
├── v3/
│   ├── overview.md             # V3 architecture summary
│   ├── attestation-service.md  # Proof verification API
│   ├── buyer-tee-verification.md  # TEE verification for buyers
│   ├── seller-autopilot.md     # Automated seller release
│   ├── smart-contracts.md      # Contract overview
│   ├── deployments.md          # Contract addresses, payment methods
│   └── smart-contracts/
│       ├── escrow/
│       ├── orchestrator.md
│       ├── unified-payment-verifier.md
│       ├── pre-intent-hooks.md
│       └── post-intent-hooks.md
└── peerauth-extension/
    └── index.md                # Current extension overview

Key Terminology

Term	Definition
Intent	Buyer's commitment to purchase, locks seller liquidity
Deposit	Seller's token position in Escrow
Verifier	Contract/service that validates payment proofs
Attestation	EIP-712 signed proof of payment (V3)
Nullifier	Unique identifier preventing double-spend
zkTLS	Zero-knowledge TLS proof (TLSNotary or Reclaim)

Documentation Patterns

Deployments Tables

Contract addresses use HTML tables with chain icons:

<table>
  <tr>
    <th>Contract</th>
    <th>Address</th>
  </tr>
  <tr>
    <td>Escrow</td>
    <td><code>0x...</code></td>
  </tr>
</table>

Payment Method Identifiers

V3 uses bytes32 identifiers:

• keccak256("venmo") → payment method
• keccak256("USD") → currency

Code Examples

• Solidity for contract interfaces
• TypeScript for SDK usage
• Include precision notes (USDC = 6 decimals, rates = 18 decimals)

Common Updates

1. New deployment: Update deployments.md with contract addresses
2. New payment method: Add to supported methods table in deployments
3. Contract changes: Verify against the current @zkp2p/contracts-v2 package and deployment metadata