Escrow

Overview

The Escrow contract allows users to lock ERC-20 tokens in order to receive off-chain payments. Users deposit tokens specifying:

Which off-chain payment verifiers they accept.
Conversion rates for various fiat currencies.
A gating service (optional) that can sign a user’s intent to claim funds.

When a taker signals an intent to pay off-chain, they specify how many tokens they want to claim and through which payment verifier. Upon proving the off-chain payment has occurred (by calling fulfillIntent), the escrow releases the on-chain tokens to the taker (minus applicable fees).

Constants

uint256 internal constant PRECISE_UNIT = 1e18;
uint256 constant CIRCOM_PRIME_FIELD = ...;
uint256 constant MAX_SUSTAINABILITY_FEE = 5e16; // 5%

State Variables

uint256 public immutable chainId; The chain ID where this contract is deployed.
mapping(address => uint256[]) public accountDeposits; Which deposits belong to a given address.
mapping(address => bytes32) public accountIntent; Tracks a single active intent for each address.
mapping(uint256 => mapping(address => DepositVerifierData)) public depositVerifierData; Links a deposit ID + verifier to the relevant verification data (e.g., payee details).
mapping(uint256 => address[]) public depositVerifiers; Lists all verifiers associated with a deposit.
mapping(uint256 => mapping(address => mapping(bytes32 => uint256))) public depositCurrencyConversionRate; For a given deposit ID and verifier, maps fiat currency -> conversion rate.
mapping(uint256 => mapping(address => bytes32[])) public depositCurrencies; For a given deposit ID and verifier, stores an array of fiat currencies.
mapping(uint256 => Deposit) public deposits; The core deposit data.
mapping(bytes32 => Intent) public intents; All signaled intents (by their intent hash).
Whitelist / Governance
- bool public acceptAllPaymentVerifiers;
- mapping(address => bool) public whitelistedPaymentVerifiers;
- mapping(address => uint256) public paymentVerifierFeeShare;
uint256 public intentExpirationPeriod; After which an intent is considered expired.
uint256 public sustainabilityFee; Fee (in PRECISE_UNIT terms) taken from each successful intent fulfillment.
address public sustainabilityFeeRecipient; Where the sustainability fee is sent.
uint256 public depositCounter; Incremented to create unique deposit IDs.

Constructor

constructor(
    address _owner,
    uint256 _chainId,
    uint256 _intentExpirationPeriod,
    uint256 _sustainabilityFee,
    address _sustainabilityFeeRecipient
) Ownable() { ... }

Parameters:

_owner: The address to set as the contract owner (can pause, unpause, and manage verifiers).
_chainId: The chain ID for which this escrow is valid.
_intentExpirationPeriod: Time (in seconds) after which an open intent can be pruned.
_sustainabilityFee: Percentage (in 1e18 precision) charged upon successful intent fulfillment.
_sustainabilityFeeRecipient: Address to receive the sustainability fees.

Transfers ownership to _owner and sets initial contract state.

External Functions

createDeposit

function createDeposit(
    IERC20 _token,
    uint256 _amount,
    Range calldata _intentAmountRange,
    address[] calldata _verifiers,
    DepositVerifierData[] calldata _verifierData,
    Currency[][] calldata _currencies
)
    external
    whenNotPaused

Description: Deposits _amount of _token into escrow. You specify:

A range of intent sizes (_intentAmountRange).
Which verifiers (_verifiers) the deposit will accept.
Gating + payee details for each verifier (_verifierData).
Which currencies (and rates) each verifier can handle (_currencies).

Requirements:

User must have approved this contract to transfer _amount of _token.
The deposit is unique (each call yields a new depositId).
_amount must be >= min of _intentAmountRange.
_verifiers length must match _verifierData and _currencies length.
Each verifier must be whitelisted or acceptAllPaymentVerifiers must be true.
Each currency’s conversionRate must be > 0.

Effects:

Increments depositCounter.
Stores the deposit data.
Locks the tokens in this contract.
Emits DepositReceived and DepositVerifierAdded (and DepositCurrencyAdded) events.

signalIntent

function signalIntent(
    uint256 _depositId,
    uint256 _amount,
    address _to,
    address _verifier,
    bytes32 _fiatCurrency,
    bytes calldata _gatingServiceSignature
)
    external
    whenNotPaused

Description: A taker declares an intent to pay the deposit’s off-chain counterpart. This:

Ensures the deposit is still acceptingIntents.
Validates _amount against deposit’s range.
Optionally checks a gating service signature.
Reserves _amount from the deposit’s remainingDeposits.
Records a new Intent in intents.

Requirements:

Caller must not have another active Intent (accountIntent[msg.sender] == 0).
_amount is within the deposit’s intentAmountRange.
_fiatCurrency is recognized in depositCurrencyConversionRate[_depositId][_verifier].

Effects:

May prune expired intents if liquidity is insufficient.
Emits IntentSignaled upon success.

cancelIntent

function cancelIntent(bytes32 _intentHash) external

Description: Allows the intent owner to cancel an intent. This frees up the escrowed amount. Reverts if msg.sender is not the intent owner.

fulfillIntent

function fulfillIntent(bytes calldata _paymentProof, bytes32 _intentHash) external whenNotPaused

Description: Attempts to prove that the off-chain payment has been made according to the associated payment verifier. On success:

The escrowed tokens are transferred to the specified to address.
Fees are taken out for sustainability and optionally the payment verifier.

Parameters:

_paymentProof – The proof data for verifying off-chain payment (e.g., TLSNotary, ZK, etc.).
_intentHash – The ID of the signaled intent.

Reverts if:

The verifier check fails.
The _intentHash does not match the proof’s extracted intent hash.

Emits:

IntentFulfilled event.

releaseFundsToPayer

function releaseFundsToPayer(bytes32 _intentHash) external

Description: Allows the deposit owner (not the intent owner) to push funds to the off-chain payer’s to address, effectively acknowledging the payment or an alternative arrangement.

Effects:

Removes the intent from state.
Transfers tokens to the intent.owner or intent.to.
Emits IntentFulfilled event with zero verifier address.

updateDepositConversionRate

function updateDepositConversionRate(
    uint256 _depositId, 
    address _verifier, 
    bytes32 _fiatCurrency, 
    uint256 _newConversionRate
)
    external
    whenNotPaused

Description: The depositor can adjust the deposit’s conversion rate for a specific currency and verifier. Only future intents will be affected; existing ones store the old rate.

withdrawDeposit

function withdrawDeposit(uint256 _depositId) external

Description: Withdraws any unencumbered tokens from the deposit. Prunes any expired intents (making more tokens claimable). If no tokens remain (and no open intents), the deposit is fully closed and removed.

Governance Functions

addWhitelistedPaymentVerifier

function addWhitelistedPaymentVerifier(address _verifier, uint256 _feeShare) external onlyOwner

Adds a payment verifier to the whitelist, with a certain _feeShare.

removeWhitelistedPaymentVerifier

function removeWhitelistedPaymentVerifier(address _verifier) external onlyOwner

Removes a verifier from the whitelist.

updatePaymentVerifierFeeShare

function updatePaymentVerifierFeeShare(address _verifier, uint256 _feeShare) external onlyOwner

Updates the fee share for a given whitelisted verifier.

updateAcceptAllPaymentVerifiers

function updateAcceptAllPaymentVerifiers(bool _acceptAllPaymentVerifiers) external onlyOwner

Toggles whether any verifier address can be used (bypassing the whitelist).

setSustainabilityFee

function setSustainabilityFee(uint256 _fee) external onlyOwner

Sets the global sustainability fee (max 5%). Fee is taken upon intent fulfillment.

setSustainabilityFeeRecipient

function setSustainabilityFeeRecipient(address _feeRecipient) external onlyOwner

Sets the address receiving protocol fees.

setIntentExpirationPeriod

function setIntentExpirationPeriod(uint256 _intentExpirationPeriod) external onlyOwner

Updates how long an intent remains valid before it can be pruned.

pauseEscrow / unpauseEscrow

function pauseEscrow() external onlyOwner
function unpauseEscrow() external onlyOwner

Pauses or unpauses the contract’s core functions:

Paused: Creates deposit, updates conversion rate, signals/fulfills intent are disabled.
Unpaused: Resumes all functionalities.

External View Functions

getPrunableIntents

function getPrunableIntents(uint256 _depositId) 
    external 
    view 
    returns (bytes32[] memory prunableIntents, uint256 reclaimedAmount);

Returns a list of expired (prunable) intent hashes for a deposit and the total amount they occupy.

getDeposit

function getDeposit(uint256 _depositId) 
    public 
    view 
    returns (DepositView memory depositView);

Returns a DepositView, including:

The deposit details.
Available liquidity (accounting for expired intents).
Associated verifiers/currency data.

getAccountDeposits

function getAccountDeposits(address _account) 
    external 
    view 
    returns (DepositView[] memory depositArray);

Returns the set of deposits belonging to _account.

getDepositFromIds

function getDepositFromIds(uint256[] memory _depositIds) 
    external 
    view 
    returns (DepositView[] memory depositArray);

Returns the DepositView[] for a given list of deposit IDs (part of IEscrow interface).

getIntent

function getIntent(bytes32 _intentHash) 
    public 
    view 
    returns (IntentView memory intentView);

Provides the IntentView, linking the intent to its deposit.

getIntents

function getIntents(bytes32[] calldata _intentHashes) 
    external 
    view 
    returns (IntentView[] memory intentArray);

Batch retrieval of multiple intents.

getAccountIntent

function getAccountIntent(address _account) 
    external 
    view 
    returns (IntentView memory intentView);

Returns the active intent (if any) for a given account.

PreviousSmart Contracts NextIEscrow

Last updated 5 months ago