Skip to main content

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us