> ## 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.

# Escrow

> Core escrow contract that manages deposit lifecycle and liquidity locks

# Escrow Contract

The Escrow contract is the core contract that holds depositor liquidity and manages the deposit lifecycle. It handles deposit creation, fund management, and intent locking/unlocking in coordination with the Orchestrator.

## Overview

* **Contract**: `Escrow.sol`
* **Inherits**: `Ownable`, `Pausable`, `ReentrancyGuard`, `IEscrow`
* **Purpose**: Escrows deposits and manages deposit lifecycle

## Key State Variables

<ParamField path="orchestrator" type="IOrchestrator">
  Address of the orchestrator contract
</ParamField>

<ParamField path="paymentVerifierRegistry" type="IPaymentVerifierRegistry">
  Address of the payment verifier registry contract
</ParamField>

<ParamField path="depositCounter" type="uint256">
  Counter for depositIds
</ParamField>

<ParamField path="dustThreshold" type="uint256">
  Amount below which deposits are considered dust and can be closed
</ParamField>

<ParamField path="maxIntentsPerDeposit" type="uint256">
  Maximum active intents per deposit (suggested to keep below 100 to prevent deposit withdraw DOS)
</ParamField>

<ParamField path="intentExpirationPeriod" type="uint256">
  Time period after which an intent expires
</ParamField>

## Core Functions

### Deposit Management

#### createDeposit

Creates a deposit entry by locking liquidity in the escrow contract.

<ParamField path="_params" type="CreateDepositParams">
  Struct containing all deposit parameters:

  * `token`: The ERC20 token to deposit
  * `amount`: Amount of tokens to deposit
  * `intentAmountRange`: Min and max intent amounts
  * `paymentMethods`: List of supported payment methods
  * `paymentMethodData`: Verification data for each payment method
  * `currencies`: Supported currencies with min conversion rates
  * `delegate`: Optional delegate to manage the deposit
  * `intentGuardian`: Address that can extend intent expiry
  * `retainOnEmpty`: Whether to keep deposit config when empty
</ParamField>

```solidity theme={null}
function createDeposit(CreateDepositParams calldata _params) external whenNotPaused
```

**Events Emitted:**

* `DepositReceived(depositId, depositor, token, amount, intentAmountRange, delegate, intentGuardian)`
* `DepositPaymentMethodAdded(depositId, paymentMethod, payeeDetails, intentGatingService)`
* `DepositCurrencyAdded(depositId, paymentMethod, currencyCode, minConversionRate)`

#### addFunds

Adds additional funds to an existing deposit.

<ParamField path="_depositId" type="uint256">
  The deposit ID to add funds to
</ParamField>

<ParamField path="_amount" type="uint256">
  The amount of tokens to add
</ParamField>

```solidity theme={null}
function addFunds(uint256 _depositId, uint256 _amount) external whenNotPaused
```

#### removeFunds

Removes funds from an existing deposit. Expired intents are pruned if necessary.

<ParamField path="_depositId" type="uint256">
  The deposit ID to remove funds from
</ParamField>

<ParamField path="_amount" type="uint256">
  The amount of tokens to remove
</ParamField>

```solidity theme={null}
function removeFunds(uint256 _depositId, uint256 _amount) external nonReentrant whenNotPaused
```

#### withdrawDeposit

Returns all remaining deposits and any outstanding intents that are expired to the depositor.

<ParamField path="_depositId" type="uint256">
  DepositId the depositor is attempting to withdraw
</ParamField>

```solidity theme={null}
function withdrawDeposit(uint256 _depositId) external nonReentrant
```

### Delegate Management

#### setDelegate

Allows depositor to set a delegate address that can manage a specific deposit.

<ParamField path="_depositId" type="uint256">
  The deposit ID
</ParamField>

<ParamField path="_delegate" type="address">
  The address to set as delegate
</ParamField>

```solidity theme={null}
function setDelegate(uint256 _depositId, address _delegate) external whenNotPaused
```

#### removeDelegate

Allows depositor to remove the delegate for a specific deposit.

```solidity theme={null}
function removeDelegate(uint256 _depositId) external whenNotPaused
```

### Deposit Configuration

#### setCurrencyMinRate

Updates the min conversion rate for a currency for a payment verifier.

<ParamField path="_depositId" type="uint256">
  The deposit ID
</ParamField>

<ParamField path="_paymentMethod" type="bytes32">
  The payment method to update
</ParamField>

<ParamField path="_fiatCurrency" type="bytes32">
  The fiat currency code
</ParamField>

<ParamField path="_newMinConversionRate" type="uint256">
  The new min conversion rate (must be greater than 0)
</ParamField>

```solidity theme={null}
function setCurrencyMinRate(
    uint256 _depositId, 
    bytes32 _paymentMethod, 
    bytes32 _fiatCurrency, 
    uint256 _newMinConversionRate
) external whenNotPaused onlyDepositorOrDelegate(_depositId)
```

#### setIntentRange

Updates the intent amount range for a deposit.

<ParamField path="_depositId" type="uint256">
  The deposit ID
</ParamField>

<ParamField path="_intentAmountRange" type="Range">
  The new intent amount range (min and max)
</ParamField>

```solidity theme={null}
function setIntentRange(
    uint256 _depositId, 
    Range calldata _intentAmountRange
) external whenNotPaused onlyDepositorOrDelegate(_depositId)
```

#### setAcceptingIntents

Allows depositor or delegate to set the accepting intents state for a deposit.

<ParamField path="_depositId" type="uint256">
  The deposit ID
</ParamField>

<ParamField path="_acceptingIntents" type="bool">
  The new accepting intents state
</ParamField>

```solidity theme={null}
function setAcceptingIntents(
    uint256 _depositId, 
    bool _acceptingIntents
) external whenNotPaused onlyDepositorOrDelegate(_depositId)
```

### Orchestrator-Only Functions

#### lockFunds

**ORCHESTRATOR ONLY**: Locks funds for an intent with expiry time.

<ParamField path="_depositId" type="uint256">
  The deposit ID to lock funds from
</ParamField>

<ParamField path="_intentHash" type="bytes32">
  The intent hash this intent corresponds to
</ParamField>

<ParamField path="_amount" type="uint256">
  The amount to lock
</ParamField>

```solidity theme={null}
function lockFunds(
    uint256 _depositId, 
    bytes32 _intentHash,
    uint256 _amount
) external nonReentrant onlyOrchestrator
```

**Events Emitted:**

* `FundsLocked(depositId, intentHash, amount, expiryTime)`

#### unlockFunds

**ORCHESTRATOR ONLY**: Unlocks funds from a cancelled intent.

<ParamField path="_depositId" type="uint256">
  The deposit ID to unlock funds from
</ParamField>

<ParamField path="_intentHash" type="bytes32">
  The intent hash to find and remove the intent for
</ParamField>

```solidity theme={null}
function unlockFunds(uint256 _depositId, bytes32 _intentHash) 
    external 
    nonReentrant
    onlyOrchestrator
```

**Events Emitted:**

* `FundsUnlocked(depositId, intentHash, amount)`

#### unlockAndTransferFunds

**ORCHESTRATOR ONLY**: Unlocks and transfers funds from a fulfilled intent.

<ParamField path="_depositId" type="uint256">
  The deposit ID to transfer from
</ParamField>

<ParamField path="_intentHash" type="bytes32">
  The intent hash to find and remove the intent for
</ParamField>

<ParamField path="_transferAmount" type="uint256">
  The amount to actually transfer (may be less than intent amount)
</ParamField>

<ParamField path="_to" type="address">
  The address to transfer to (orchestrator)
</ParamField>

```solidity theme={null}
function unlockAndTransferFunds(
    uint256 _depositId, 
    bytes32 _intentHash,
    uint256 _transferAmount, 
    address _to
) external nonReentrant onlyOrchestrator
```

**Events Emitted:**

* `FundsUnlockedAndTransferred(depositId, intentHash, intentAmount, transferAmount, to)`

### Intent Guardian Functions

#### extendIntentExpiry

**INTENT GUARDIAN ONLY**: Extends the expiry time of an existing intent.

<ParamField path="_depositId" type="uint256">
  The deposit ID containing the intent
</ParamField>

<ParamField path="_intentHash" type="bytes32">
  The intent hash to extend expiry for
</ParamField>

<ParamField path="_additionalTime" type="uint256">
  The additional time to extend the expiry by
</ParamField>

```solidity theme={null}
function extendIntentExpiry(
    uint256 _depositId, 
    bytes32 _intentHash,
    uint256 _additionalTime
) external
```

**Events Emitted:**

* `IntentExpiryExtended(depositId, intentHash, newExpiryTime)`

### Public Functions

#### pruneExpiredIntents

**ANYONE**: Can be called by anyone to clean up expired intents.

<ParamField path="_depositId" type="uint256">
  The deposit ID to prune expired intents for
</ParamField>

```solidity theme={null}
function pruneExpiredIntents(uint256 _depositId) external nonReentrant
```

## View Functions

#### getDeposit

Returns the deposit struct for a given deposit ID.

```solidity theme={null}
function getDeposit(uint256 _depositId) external view returns (Deposit memory)
```

<ResponseField name="depositor" type="address">
  Address of the depositor
</ResponseField>

<ResponseField name="delegate" type="address">
  Address of the delegate (if any)
</ResponseField>

<ResponseField name="token" type="IERC20">
  The ERC20 token being deposited
</ResponseField>

<ResponseField name="intentAmountRange" type="Range">
  Min and max intent amounts
</ResponseField>

<ResponseField name="acceptingIntents" type="bool">
  Whether the deposit is accepting new intents
</ResponseField>

<ResponseField name="remainingDeposits" type="uint256">
  Available liquidity not locked by intents
</ResponseField>

<ResponseField name="outstandingIntentAmount" type="uint256">
  Total amount locked by active intents
</ResponseField>

#### getDepositIntentHashes

Returns all active intent hashes for a deposit.

```solidity theme={null}
function getDepositIntentHashes(uint256 _depositId) external view returns (bytes32[] memory)
```

#### getDepositPaymentMethods

Returns all payment methods configured for a deposit.

```solidity theme={null}
function getDepositPaymentMethods(uint256 _depositId) external view returns (bytes32[] memory)
```

#### getDepositCurrencies

Returns all currencies for a specific payment method on a deposit.

```solidity theme={null}
function getDepositCurrencies(uint256 _depositId, bytes32 _paymentMethod) 
    external view returns (bytes32[] memory)
```

#### getExpiredIntents

Returns expired intents and the total reclaimable amount.

```solidity theme={null}
function getExpiredIntents(uint256 _depositId) 
    external view returns (bytes32[] memory expiredIntents, uint256 reclaimableAmount)
```

## Events

### DepositReceived

Emitted when a new deposit is created.

```solidity theme={null}
event DepositReceived(
    uint256 indexed depositId,
    address indexed depositor,
    IERC20 token,
    uint256 amount,
    Range intentAmountRange,
    address delegate,
    address intentGuardian
)
```

### FundsLocked

Emitted when funds are locked for an intent.

```solidity theme={null}
event FundsLocked(
    uint256 indexed depositId,
    bytes32 indexed intentHash,
    uint256 amount,
    uint256 expiryTime
)
```

### FundsUnlocked

Emitted when funds are unlocked from a cancelled intent.

```solidity theme={null}
event FundsUnlocked(
    uint256 indexed depositId,
    bytes32 indexed intentHash,
    uint256 amount
)
```

### FundsUnlockedAndTransferred

Emitted when funds are unlocked and transferred for a fulfilled intent.

```solidity theme={null}
event FundsUnlockedAndTransferred(
    uint256 indexed depositId,
    bytes32 indexed intentHash,
    uint256 intentAmount,
    uint256 transferAmount,
    address to
)
```

## Constants

<ParamField path="PRECISE_UNIT" type="uint256">
  `1e18` - Precision unit for calculations
</ParamField>

<ParamField path="MAX_DUST_THRESHOLD" type="uint256">
  `1e6` - Maximum dust threshold (1 USDC)
</ParamField>

<ParamField path="MAX_TOTAL_INTENT_EXPIRATION_PERIOD" type="uint256">
  `86400 * 5` - Maximum intent expiration period (5 days)
</ParamField>

## Example Usage

### Creating a Deposit

```solidity theme={null}
IEscrow.CreateDepositParams memory params = IEscrow.CreateDepositParams({
    token: IERC20(usdcAddress),
    amount: 1000e6, // 1000 USDC
    intentAmountRange: IEscrow.Range(10e6, 500e6),
    paymentMethods: [venmoHash],
    paymentMethodData: [paymentData],
    currencies: [[usdCurrency]],
    delegate: address(0),
    intentGuardian: guardianAddress,
    retainOnEmpty: false
});

escrow.createDeposit(params);
```

### Locking Funds for an Intent

```solidity theme={null}
// Called by Orchestrator only
escrow.lockFunds(depositId, intentHash, 100e6); // Lock 100 USDC
```