Escrow
This Escrow component of Atlas handles execution of stages by calling corresponding functions on the
Execution Environment contract.
constructor
constructor(uint256 escrowDuration, uint256 atlasSurchargeRate, uint256 bundlerSurchargeRate, address verification, address simulator, address initialSurchargeRecipient, address l2GasCalculator) internal
_executePreOpsCall
function _executePreOpsCall(struct Context ctx, struct DAppConfig dConfig, struct UserOperation userOp) internal returns (bytes)
Executes the preOps logic defined in the Execution Environment.
Parameters
| Name | Type | Description |
|---|
| ctx | struct Context | Metacall context data from the Context struct. |
| dConfig | struct DAppConfig | Configuration data for the DApp involved, containing execution parameters and settings. |
| userOp | struct UserOperation | UserOperation struct of the current metacall tx. |
Return Values
| Name | Type | Description |
|---|
| [0] | bytes | preOpsData The data returned by the preOps call, if successful. |
_executeUserOperation
function _executeUserOperation(struct Context ctx, struct DAppConfig dConfig, struct UserOperation userOp, bytes returnData) internal returns (bytes)
Executes the user operation logic defined in the Execution Environment.
Parameters
| Name | Type | Description |
|---|
| ctx | struct Context | Metacall context data from the Context struct. |
| dConfig | struct DAppConfig | Configuration data for the DApp involved, containing execution parameters and settings. |
| userOp | struct UserOperation | UserOperation struct containing the user's transaction data. |
| returnData | bytes | Data returned from previous call phases. |
Return Values
| Name | Type | Description |
|---|
| [0] | bytes | userData Data returned from executing the UserOperation, if the call was successful. |
_checkTrustedOpHash
function _checkTrustedOpHash(struct DAppConfig dConfig, bool prevalidated, struct UserOperation userOp, struct SolverOperation solverOp, uint256 result) internal returns (uint256)
Checks if the trusted operation hash matches and sets the appropriate error bit if it doesn't.
Parameters
| Name | Type | Description |
|---|
| dConfig | struct DAppConfig | Configuration data for the DApp involved, containing execution parameters and settings. |
| prevalidated | bool | Boolean flag indicating whether the SolverOperation has been prevalidated to skip certain checks. |
| userOp | struct UserOperation | UserOperation struct containing the user's transaction data relevant to this SolverOperation. |
| solverOp | struct SolverOperation | SolverOperation struct containing the solver's bid and execution data. |
| result | uint256 | The current result bitmask that tracks the status of various checks and validations. |
Return Values
| Name | Type | Description |
|---|
| [0] | uint256 | The updated result bitmask with the AltOpHashMismatch bit set if the operation hash does not match. |
_executeSolverOperation
function _executeSolverOperation(struct Context ctx, struct DAppConfig dConfig, struct UserOperation userOp, struct SolverOperation solverOp, uint256 bidAmount, uint256 gasWaterMark, bool prevalidated, bytes returnData) internal returns (uint256)
Attempts to execute a SolverOperation and determine if it wins the auction.
Parameters
| Name | Type | Description |
|---|
| ctx | struct Context | Context struct containing the current state of the escrow lock. |
| dConfig | struct DAppConfig | Configuration data for the DApp involved, containing execution parameters and settings. |
| userOp | struct UserOperation | UserOperation struct containing the user's transaction data relevant to this SolverOperation. |
| solverOp | struct SolverOperation | SolverOperation struct containing the solver's bid and execution data. |
| bidAmount | uint256 | The amount of bid submitted by the solver for this operation. |
| gasWaterMark | uint256 | The gas left at the start of the current solverOp's execution, to be used to charge/write off solverOp gas. |
| prevalidated | bool | Boolean flag indicating if the solverOp has been prevalidated in bidFind (exPostBids). |
| returnData | bytes | Data returned from UserOp execution, used as input if necessary. |
Return Values
| Name | Type | Description |
|---|
| [0] | uint256 | bidAmount The determined bid amount for the SolverOperation if all validations pass and the operation is executed successfully; otherwise, returns 0. |
_allocateValue
function _allocateValue(struct Context ctx, struct DAppConfig dConfig, uint256 bidAmount, bytes returnData) internal
Allocates the winning bid amount after a successful SolverOperation execution.
This function handles the allocation of the bid amount to the appropriate recipients as defined in the
DApp's configuration. It calls the allocateValue function in the Execution Environment, which is responsible for
distributing the bid amount. Note that balance discrepancies leading to payment failures are typically due to
issues in the DAppControl contract, not the execution environment itself.
Parameters
| Name | Type | Description |
|---|
| ctx | struct Context | Context struct containing the current state of the escrow lock. |
| dConfig | struct DAppConfig | Configuration data for the DApp involved, containing execution parameters and settings. |
| bidAmount | uint256 | The winning solver's bid amount, to be allocated. |
| returnData | bytes | Data returned from the execution of the UserOperation, which may influence how the bid amount is allocated. |
_adjustGasLedgerAtSolverOpStart
function _adjustGasLedgerAtSolverOpStart(struct GasLedger gL, struct DAppConfig dConfig, struct SolverOperation solverOp) internal
Adjusts the gas ledger before evaluating a SolverOperation.
Updates the in-memory gL by decreasing unreachedSolverGas based on the current solverOp's max potential
gas (execution + calldata if not exPostBids) and resets maxApprovedGasSpend to 0. Caller must persist gL
changes to transient storage separately.
Parameters
| Name | Type | Description |
|---|
| gL | struct GasLedger | The GasLedger struct (in memory) to modify. |
| dConfig | struct DAppConfig | DApp configuration containing solverGasLimit and callConfig. |
| solverOp | struct SolverOperation | The SolverOperation being evaluated. |
_validateSolverOpGasAndValue
function _validateSolverOpGasAndValue(struct GasLedger gL, struct DAppConfig dConfig, struct SolverOperation solverOp, uint256 gasWaterMark, uint256 result) internal returns (uint256, uint256 gasLimit)
Validates a SolverOperation's gas requirements against the escrow state.
Performs a series of checks to ensure that a SolverOperation can be executed within the defined parameters
and limits. This includes verifying that the operation is within the gas limit and that the solver has
sufficient balance in escrow to cover the gas costs.
Parameters
| Name | Type | Description |
|---|
| gL | struct GasLedger | The GasLedger memory struct containing the current gas accounting state. |
| dConfig | struct DAppConfig | DApp configuration data, including solver gas limits and operation parameters. |
| solverOp | struct SolverOperation | The SolverOperation being validated. |
| gasWaterMark | uint256 | The initial gas measurement before validation begins, used to ensure enough gas remains for validation logic. |
| result | uint256 | The current result bitmap, which will be updated with the outcome of the gas validation checks. |
Return Values
| Name | Type | Description |
|---|
| [0] | uint256 | result Updated result flags after performing the validation checks, including any new errors encountered. |
| gasLimit | uint256 | The calculated gas limit for the SolverOperation, considering the operation's gas usage and the protocol's gas buffers. |
_validateSolverOpDeadline
function _validateSolverOpDeadline(struct SolverOperation solverOp, struct DAppConfig dConfig) internal view returns (uint256 result)
Validates a SolverOperation's deadline against the current block.
Parameters
| Name | Type | Description |
|---|
| solverOp | struct SolverOperation | The SolverOperation being validated. |
| dConfig | struct DAppConfig | DApp configuration data, including solver gas limits and operation parameters. |
Return Values
| Name | Type | Description |
|---|
| result | uint256 | Updated result flags after performing the validation checks, including any new errors |
_getBidAmount
function _getBidAmount(struct Context ctx, struct DAppConfig dConfig, struct UserOperation userOp, struct SolverOperation solverOp, bytes returnData) internal returns (uint256 bidAmount)
Determines the bid amount for a SolverOperation based on verification and validation results.
This function assesses whether a SolverOperation meets the criteria for execution by verifying it against
the Atlas protocol's rules and the current Context lock state. It checks for valid execution based on the
SolverOperation's specifics, like gas usage and deadlines. The function aims to protect against malicious
bundlers by ensuring solvers are not unfairly charged for on-chain bid finding gas usage. If the operation
passes verification and validation, and if it's eligible for bid amount determination, the function
attempts to execute and determine the bid amount.
Parameters
| Name | Type | Description |
|---|
| ctx | struct Context | The Context struct containing the current state of the escrow lock. |
| dConfig | struct DAppConfig | The DApp configuration data, including parameters relevant to solver bid validation. |
| userOp | struct UserOperation | The UserOperation associated with this SolverOperation, providing context for the bid amount determination. |
| solverOp | struct SolverOperation | The SolverOperation being assessed, containing the solver's bid amount. |
| returnData | bytes | Data returned from the execution of the UserOp call. |
Return Values
| Name | Type | Description |
|---|
| bidAmount | uint256 | The determined bid amount for the SolverOperation if all validations pass and the operation is executed successfully; otherwise, returns 0. |
_handleAltOpHash
function _handleAltOpHash(struct UserOperation userOp, struct SolverOperation solverOp) internal returns (bool)
Validates UserOp hashes provided by the SolverOperation, using the alternative set of hashed parameters.
Parameters
| Name | Type | Description |
|---|
| userOp | struct UserOperation | The UserOperation struct, providing the baseline parameters for comparison. |
| solverOp | struct SolverOperation | The SolverOperation struct being validated against the UserOperation. |
Return Values
| Name | Type | Description |
|---|
| [0] | bool | A boolean value indicating whether the SolverOperation passed the alternative hash check, with true meaning it is considered valid |
_checkSolverBidToken
function _checkSolverBidToken(address solverBidToken, address dConfigBidToken, uint256 result) internal pure returns (uint256)
Checks if the solver's bid token matches the dApp's bid token.
Parameters
| Name | Type | Description |
|---|
| solverBidToken | address | The solver's bid token address. |
| dConfigBidToken | address | The dApp's bid token address. |
| result | uint256 | The current result bitmap, which will be updated with the outcome of the bid token check. |
Return Values
| Name | Type | Description |
|---|
| [0] | uint256 | The updated result bitmap, with the SolverOutcome.InvalidBidToken flag set if the bid token check fails. |
_solverOpWrapper
function _solverOpWrapper(struct Context ctx, struct SolverOperation solverOp, uint256 bidAmount, uint256 gasLimit, bytes returnData) internal returns (uint256 result, struct SolverTracker solverTracker)
Wraps the execution of a SolverOperation and handles potential errors.
Parameters
| Name | Type | Description |
|---|
| ctx | struct Context | The current lock data. |
| solverOp | struct SolverOperation | The SolverOperation struct containing the operation's execution data. |
| bidAmount | uint256 | The bid amount associated with the SolverOperation. |
| gasLimit | uint256 | The gas limit for executing the SolverOperation, calculated based on the operation's requirements and protocol buffers. |
| returnData | bytes | Data returned from the execution of the associated UserOperation, which may be required for the SolverOperation's logic. |
Return Values
| Name | Type | Description |
|---|
| result | uint256 | SolverOutcome enum value encoded as a uint256 bitmap, representing the result of the SolverOperation |
| solverTracker | struct SolverTracker | Tracking data for the solver's bid |
solverCall
function solverCall(struct Context ctx, struct SolverOperation solverOp, uint256 bidAmount, bytes returnData) external payable returns (struct SolverTracker solverTracker)
Executes the SolverOperation logic, including preSolver and postSolver hooks via the Execution
Environment, as well as the actual solver call directly from Atlas to the solver contract.
Parameters
| Name | Type | Description |
|---|
| ctx | struct Context | The Context struct containing lock data and the Execution Environment address. |
| solverOp | struct SolverOperation | The SolverOperation to be executed. |
| bidAmount | uint256 | The bid amount associated with the SolverOperation. |
| returnData | bytes | Data returned from previous call phases. |
Return Values
| Name | Type | Description |
|---|
| solverTracker | struct SolverTracker | Additional data for handling the solver's bid in different scenarios. |
_updateDAppGasLeft
function _updateDAppGasLeft(struct Context ctx, uint256 gasWaterMarkBefore) internal view
Updates ctx.dappGasLeft based on the gas used in the DApp hook call just performed.
Measure the gasWaterMarkBefore using gasleft() just before performing the DApp hook call.
Will revert if the gas used exceeds the remaining dappGasLeft.
Parameters
| Name | Type | Description |
|---|
| ctx | struct Context | Memory pointer to the metacalls' Context object. |
| gasWaterMarkBefore | uint256 | The gasleft() value just before the DApp hook call. |
receive
receive() external payable