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

orchestrator · IOrchestrator

Address of the orchestrator contract

paymentVerifierRegistry · IPaymentVerifierRegistry

Address of the payment verifier registry contract

depositCounter · uint256

Counter for depositIds

dustThreshold · uint256

Amount below which deposits are considered dust and can be closed

maxIntentsPerDeposit · uint256

Maximum active intents per deposit (suggested to keep below 100 to prevent deposit withdraw DOS)

intentExpirationPeriod · uint256

Time period after which an intent expires

Core Functions

Deposit Management

createDeposit

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

_params · 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

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.

_depositId · uint256

The deposit ID to add funds to

_amount · uint256

The amount of tokens to add

function addFunds(uint256 _depositId, uint256 _amount) external whenNotPaused

removeFunds

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

_depositId · uint256

The deposit ID to remove funds from

_amount · uint256

The amount of tokens to remove

function removeFunds(uint256 _depositId, uint256 _amount) external nonReentrant whenNotPaused

withdrawDeposit

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

_depositId · uint256

DepositId the depositor is attempting to withdraw

function withdrawDeposit(uint256 _depositId) external nonReentrant

Delegate Management

setDelegate

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

_depositId · uint256

The deposit ID

_delegate · address

The address to set as delegate

function setDelegate(uint256 _depositId, address _delegate) external whenNotPaused

removeDelegate

Allows depositor to remove the delegate for a specific deposit.

function removeDelegate(uint256 _depositId) external whenNotPaused

Deposit Configuration

setCurrencyMinRate

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

_depositId · uint256

The deposit ID

_paymentMethod · bytes32

The payment method to update

_fiatCurrency · bytes32

The fiat currency code

_newMinConversionRate · uint256

The new min conversion rate (must be greater than 0)

function setCurrencyMinRate(
    uint256 _depositId, 
    bytes32 _paymentMethod, 
    bytes32 _fiatCurrency, 
    uint256 _newMinConversionRate
) external whenNotPaused onlyDepositorOrDelegate(_depositId)

setIntentRange

Updates the intent amount range for a deposit.

_depositId · uint256

The deposit ID

_intentAmountRange · Range

The new intent amount range (min and max)

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.

_depositId · uint256

The deposit ID

_acceptingIntents · bool

The new accepting intents state

function setAcceptingIntents(
    uint256 _depositId, 
    bool _acceptingIntents
) external whenNotPaused onlyDepositorOrDelegate(_depositId)

Orchestrator-Only Functions

lockFunds

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

_depositId · uint256

The deposit ID to lock funds from

_intentHash · bytes32

The intent hash this intent corresponds to

_amount · uint256

The amount to lock

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.

_depositId · uint256

The deposit ID to unlock funds from

_intentHash · bytes32

The intent hash to find and remove the intent for

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.

_depositId · uint256

The deposit ID to transfer from

_intentHash · bytes32

The intent hash to find and remove the intent for

_transferAmount · uint256

The amount to actually transfer (may be less than intent amount)

_to · address

The address to transfer to (orchestrator)

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.

_depositId · uint256

The deposit ID containing the intent

_intentHash · bytes32

The intent hash to extend expiry for

_additionalTime · uint256

The additional time to extend the expiry by

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.

_depositId · uint256

The deposit ID to prune expired intents for

function pruneExpiredIntents(uint256 _depositId) external nonReentrant

View Functions

getDeposit

Returns the deposit struct for a given deposit ID.

function getDeposit(uint256 _depositId) external view returns (Deposit memory)

depositor · address

Address of the depositor

delegate · address

Address of the delegate (if any)

token · IERC20

The ERC20 token being deposited

intentAmountRange · Range

Min and max intent amounts

acceptingIntents · bool

Whether the deposit is accepting new intents

remainingDeposits · uint256

Available liquidity not locked by intents

outstandingIntentAmount · uint256

Total amount locked by active intents

getDepositIntentHashes

Returns all active intent hashes for a deposit.

function getDepositIntentHashes(uint256 _depositId) external view returns (bytes32[] memory)

getDepositPaymentMethods

Returns all payment methods configured for a deposit.

function getDepositPaymentMethods(uint256 _depositId) external view returns (bytes32[] memory)

getDepositCurrencies

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

function getDepositCurrencies(uint256 _depositId, bytes32 _paymentMethod) 
    external view returns (bytes32[] memory)

getExpiredIntents

Returns expired intents and the total reclaimable amount.

function getExpiredIntents(uint256 _depositId) 
    external view returns (bytes32[] memory expiredIntents, uint256 reclaimableAmount)

Events

DepositReceived

Emitted when a new deposit is created.

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.

event FundsLocked(
    uint256 indexed depositId,
    bytes32 indexed intentHash,
    uint256 amount,
    uint256 expiryTime
)

FundsUnlocked

Emitted when funds are unlocked from a cancelled intent.

event FundsUnlocked(
    uint256 indexed depositId,
    bytes32 indexed intentHash,
    uint256 amount
)

FundsUnlockedAndTransferred

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

event FundsUnlockedAndTransferred(
    uint256 indexed depositId,
    bytes32 indexed intentHash,
    uint256 intentAmount,
    uint256 transferAmount,
    address to
)

Constants

PRECISE_UNIT · uint256

1e18 - Precision unit for calculations

MAX_DUST_THRESHOLD · uint256

1e6 - Maximum dust threshold (1 USDC)

MAX_TOTAL_INTENT_EXPIRATION_PERIOD · uint256

86400 * 5 - Maximum intent expiration period (5 days)

Example Usage

Creating a Deposit

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

// Called by Orchestrator only
escrow.lockFunds(depositId, intentHash, 100e6); // Lock 100 USDC