> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zkp2p/zkp2p-contracts/llms.txt
> Use this file to discover all available pages before exploring further.

# Interfaces

> Overview of all contract interfaces in the zkp2p protocol

The zkp2p protocol defines a comprehensive set of interfaces that enable modular, extensible on/off-ramp functionality. These interfaces are organized into several categories based on their role in the system.

## Core Protocol Interfaces

### IOrchestrator

The main coordinator for the intent lifecycle.

**Key Methods:**

* `signalIntent()` - Create a new intent to take liquidity
* `fulfillIntent()` - Complete an intent with payment proof
* `cancelIntent()` - Cancel a pending intent
* `releaseFundsToPayer()` - Manual release mechanism
* `pruneIntents()` - Clean up expired intents (escrow-only)

**Key Structs:**

* `Intent` - Complete intent data structure with owner, amount, payment method, conversion rate, and hook configuration
* `SignalIntentParams` - Parameters for creating a new intent
* `FulfillIntentParams` - Parameters for fulfilling an intent with proof

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IOrchestrator.sol)

### IOrchestratorV2

Extended orchestrator with pre-intent hooks, whitelist hooks, and manager fee support.

**New Features:**

* Pre-intent hook validation during `signalIntent()`
* Whitelist hook for access control
* Manager fee snapshots for delegated rate managers
* `cleanupOrphanedIntents()` for anyone to clean up orphaned intents
* Separate `preIntentHookData` and persisted `data` fields

**Additional Methods:**

* `setDepositPreIntentHook()` - Configure pre-intent validation hook
* `setDepositWhitelistHook()` - Configure whitelist access control hook
* `getDepositPreIntentHook()` - Query pre-intent hook for a deposit
* `getDepositWhitelistHook()` - Query whitelist hook for a deposit

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IOrchestratorV2.sol)

### IEscrow

Manages liquidity deposits and fund locking for intents.

**Key Methods:**

* `lockFunds()` - Lock funds for an intent (orchestrator-only)
* `unlockFunds()` - Unlock funds when intent is cancelled
* `unlockAndTransferFunds()` - Unlock and transfer on fulfillment
* `extendIntentExpiry()` - Extend intent expiration time
* `getDeposit()` - Retrieve deposit information
* `getExpiredIntents()` - Find expired intents and reclaimable amounts

**Key Structs:**

* `Deposit` - Deposit configuration including token, ranges, state, and guardian
* `DepositPaymentMethodData` - Payment method configuration with gating service and verification data
* `Currency` - Currency code with minimum conversion rate
* `Intent` - Intent tracking with hash, amount, timestamp, and expiry

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IEscrow.sol)

### IEscrowV2

Extended escrow with oracle-based rates and delegated rate managers.

**New Features:**

* Oracle-based conversion rates with spread configuration
* Delegated rate manager support
* Orchestrator registry for multi-orchestrator deployments
* Batch oracle configuration methods

**Key Structs:**

* `OracleRateConfig` - Oracle adapter, config, spread, and staleness settings
* `RateManagerConfig` - Rate manager address and ID

**Additional Methods:**

* `setOracleRateConfig()` - Configure oracle-based rates for a currency
* `setOracleRateConfigBatch()` - Batch configure oracle rates
* `removeOracleRateConfig()` - Remove oracle rate configuration
* `setRateManager()` - Delegate rate management to external contract
* `clearRateManager()` - Clear rate manager delegation
* `getEffectiveRate()` - Get effective rate (oracle or manual)
* `getManagerFee()` - Get manager fee for a deposit

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IEscrowV2.sol)

## Verification Interfaces

### IPaymentVerifier

Interface for verifying off-chain payment proofs.

**Key Methods:**

* `verifyPayment()` - Verify payment proof and return release amount

**Key Structs:**

* `VerifyPaymentData` - Intent hash, payment proof, and additional data
* `PaymentVerificationResult` - Success flag, intent hash, and release amount

Implementations can verify various proof types:

* Zero-knowledge proofs (zkEmail, Groth16)
* TLS-based proofs (TLSNotary, TLSProxy)
* Attestations from trusted witnesses

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IPaymentVerifier.sol)

### IAttestationVerifier

Verifies attestations from witnesses or TEE environments.

**Key Methods:**

* `verify()` - Verify attestations for a given digest

Supports verification of:

* Multi-signature attestations
* Threshold signatures
* TEE attestations

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IAttestationVerifier.sol)

## Hook Interfaces

### IPostIntentHook

Execute custom logic after intent fulfillment.

**Key Methods:**

* `execute()` - Post-intent hook execution

**Parameters:**

* `_intent` - Full intent data structure
* `_amountNetFees` - Amount available after fees
* `_fulfillIntentData` - Data from fulfillIntent call

Use cases:

* Bridging tokens to another chain
* Swapping tokens
* Staking or yield farming
* Custom distribution logic

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IPostIntentHook.sol)

### IPostIntentHookV2

V2 interface with structured execution context.

**Key Structs:**

* `HookIntentContext` - Intent data without referrer/fees
* `HookExecutionContext` - Complete execution context with token and executable amount

**Key Methods:**

* `execute()` - Execute hook with structured context

Provides cleaner separation between signal-time data (`signalHookData`) and fulfill-time data (`fulfillHookData`).

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IPostIntentHookV2.sol)

### IPreIntentHook

Validate intents before they are signaled (OrchestratorV2 only).

**Key Methods:**

* `validateSignalIntent()` - Validate incoming intent, revert to reject

**Parameters:**

* `PreIntentContext` - Taker, escrow, deposit, amount, payment details, and hook data

Use cases:

* Whitelist/blacklist enforcement
* KYC/compliance checks
* Custom eligibility logic
* Rate validation

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IPreIntentHook.sol)

## Registry Interfaces

### IPaymentVerifierRegistry

Manages payment methods and their verifiers.

**Key Methods:**

* `isPaymentMethod()` - Check if payment method exists
* `getPaymentMethods()` - List all payment methods
* `getVerifier()` - Get verifier for a payment method
* `isCurrency()` - Check if currency is supported for a payment method
* `getCurrencies()` - List currencies for a payment method

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IPaymentVerifierRegistry.sol)

### IEscrowRegistry

Manages whitelisted escrow contracts.

**Key Methods:**

* `isWhitelistedEscrow()` - Check if escrow is whitelisted
* `isAcceptingAllEscrows()` - Check if all escrows are accepted
* `getWhitelistedEscrows()` - List whitelisted escrows

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IEscrowRegistry.sol)

### IOrchestratorRegistry

Manages whitelisted orchestrators (EscrowV2 only).

**Key Methods:**

* `addOrchestrator()` - Add orchestrator to allowlist
* `removeOrchestrator()` - Remove orchestrator from allowlist
* `isOrchestrator()` - Check if address is authorized orchestrator

Enables multi-orchestrator deployments where different orchestrators can serve different use cases.

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IOrchestratorRegistry.sol)

### IPostIntentHookRegistry

Manages whitelisted post-intent hooks.

**Key Methods:**

* `isWhitelistedHook()` - Check if hook is whitelisted
* `getWhitelistedHooks()` - List whitelisted hooks

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IPostIntentHookRegistry.sol)

### IRelayerRegistry

Manages whitelisted relayers for gasless transactions.

**Key Methods:**

* `isWhitelistedRelayer()` - Check if relayer is whitelisted
* `getWhitelistedRelayers()` - List whitelisted relayers

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IRelayerRegistry.sol)

### INullifierRegistry

Prevents double-spending of proofs.

**Key Methods:**

* `addNullifier()` - Register a nullifier
* `isNullified()` - Check if nullifier has been used

Critical for zero-knowledge proof systems to prevent replay attacks.

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/INullifierRegistry.sol)

## Oracle and Rate Interfaces

### IOracleAdapter

Generic interface for reading oracle rates.

**Key Methods:**

* `validateConfig()` - Validate and normalize adapter configuration
* `getRate()` - Get current market rate in preciseUnits (1e18)

**Returns:**

* `valid` - Whether quote is usable
* `rate` - Market rate (fiat per deposit token)
* `updatedAt` - Oracle timestamp

Adapters normalize rates from various sources:

* Chainlink price feeds
* Pyth Network
* Custom oracle implementations

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IOracleAdapter.sol)

### IRateManager

Interface for delegated rate management.

**Key Methods:**

* `getRate()` - Get effective rate for deposit/currency pair
* `getFee()` - Get fee terms for rate manager
* `isRateManager()` - Check if manager ID exists
* `onDepositOptIn()` - Called when deposit opts into delegation

Enables centralized rate and fee management across multiple deposits.

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IRateManager.sol)

## Utility Interfaces

### IProtocolViewer

Read-only interface for aggregated protocol data.

**Key Methods:**

* `getDepositFromIds()` - Get detailed deposit views with all payment methods and currencies
* `getAccountIntents()` - Get all intents for an account with full context

**Key Structs:**

* `DepositView` - Deposit with available liquidity, payment methods, and intents
* `IntentView` - Intent with associated deposit information
* `PaymentMethodDataView` - Payment method with verification data and currencies

Optimized for frontend applications to minimize RPC calls.

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IProtocolViewer.sol)

### IProtocolViewerV2

Extended viewer for V2 contracts with oracle and rate manager support.

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IProtocolViewerV2.sol)

## External Oracle Interfaces

### IChainlinkAggregatorV3

Chainlink price feed interface.

**Key Methods:**

* `latestRoundData()` - Get latest price data
* `decimals()` - Get price decimals

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IChainlinkAggregatorV3.sol)

### IPyth

Pyth Network price feed interface.

**Key Methods:**

* `getPrice()` - Get current price for price ID
* `updatePriceFeeds()` - Update price feeds with off-chain data

[View source](https://github.com/zkp2p/zkp2p-contracts/blob/main/contracts/interfaces/IPyth.sol)

## Version Comparison

### V1 vs V2 Differences

**Orchestrator:**

* V2 adds pre-intent hooks for validation before signaling
* V2 adds whitelist hooks for access control
* V2 adds manager fee snapshots for rate delegation
* V2 separates ephemeral (`preIntentHookData`) from persisted (`data`) hook data
* V2 adds `cleanupOrphanedIntents()` for anyone to clean up

**Escrow:**

* V2 adds oracle-based conversion rates with spread configuration
* V2 adds delegated rate manager support
* V2 adds orchestrator registry for multi-orchestrator deployments
* V2 provides `getEffectiveRate()` and `getManagerFee()` helpers

**Post-Intent Hooks:**

* V2 uses structured `HookExecutionContext` instead of raw `Intent`
* V2 separates signal-time and fulfill-time hook data

## Interface Dependencies

```
IOrchestrator/IOrchestratorV2
├── IEscrow/IEscrowV2 (fund management)
├── IPaymentVerifierRegistry (verification routing)
├── IPostIntentHookRegistry (hook validation)
├── IEscrowRegistry (escrow validation)
├── IRelayerRegistry (relayer validation)
└── IPostIntentHook/IPostIntentHookV2 (optional hooks)

IEscrow/IEscrowV2
├── IPaymentVerifierRegistry (payment method validation)
├── IOrchestratorRegistry (V2 only - orchestrator validation)
├── IOracleAdapter (V2 only - oracle rates)
└── IRateManager (V2 only - delegated rates)

IOrchestratorV2 (additional)
└── IPreIntentHook (pre-intent validation)

IPaymentVerifier
├── IAttestationVerifier (optional - for attestation-based proofs)
└── INullifierRegistry (optional - for ZK proofs)
```