ExecutionEnvironment

The ExecutionEnvironment contract is a fundamental component of the Atlas Protocol, responsible for managing and executing user and solver operations within a metacall transaction. It implements the IExecutionEnvironment interface, ensuring a standardized set of functions for interaction with the Atlas ecosystem.

Each unique combination of a User address and a DAppControl address deploys its own instance of this contract, ensuring isolated and secure execution environments tailored to specific interactions. The Factory contract leverages the ExecutionEnvironment in conjunction with the create2 opcode to deploy these sandboxed environments deterministically. This approach guarantees that each ExecutionEnvironment instance is uniquely and predictably deployed, enhancing both security and isolation for individual User and DAppControl interactions.

By implementing the IExecutionEnvironment interface, the contract provides a consistent API for core functions such as preOpsWrapper, userWrapper, and other essential operations, facilitating seamless integration with other components of the Atlas Protocol.

preOpsWrapper

function preOpsWrapper(UserOperation calldata userOp) external validUser(userOp) onlyAtlasEnvironment returns (bytes memory);

Description

Called by the Atlas contract before executing a UserOperation. It delegates the call to the preOpsCall function of the DAppControl contract associated with the current metacall transaction.

Parameters

Name	Type	Description
userOp	UserOperation	The user operation being executed.

Return Values

Name	Type	Description
preOpsData	bytes	Data to be passed to the next call phase.

Requirements

• The caller must be the Atlas contract (enforced by onlyAtlasEnvironment modifier).
• The UserOperation must be valid (enforced by validUser modifier).

Usage Notes

• This function is crucial for executing any preliminary operations before the main user operation.
• The returned data can be used to influence subsequent execution phases.

userWrapper

function userWrapper(UserOperation calldata userOp) external payable validUser(userOp) onlyAtlasEnvironment returns (bytes memory returnData);

Description

Executes the main UserOperation. Depending on the CallConfig, it either uses delegatecall or a standard call to execute the user's operation.

Parameters

Name	Type	Description
userOp	UserOperation	The user operation being executed.

Return Values

Name	Type	Description
returnData	bytes	Data returned from the user operation call.

Requirements

• The caller must be the Atlas contract.
• The UserOperation must be valid.
• If using delegatecall, the contract must have sufficient balance to cover the operation's value.

Usage Notes

• The choice between delegatecall and standard call is determined by the CallConfig.
• This function is the core of user operation execution within the ExecutionEnvironment.

postOpsWrapper

function postOpsWrapper(bool solved, bytes calldata returnData) external onlyAtlasEnvironment;

Description

Called by the Atlas contract after completing a metacall transaction. It delegates the call to the postOpsCall function of the DAppControl contract.

Parameters

Name	Type	Description
solved	bool	Indicates if a winning SolverOperation was successful.
returnData	bytes	Data returned from the previous call phase.

Return Values

None

Requirements

• The caller must be the Atlas contract.

Usage Notes

• This function is important for executing any cleanup or finalization logic after the main operation.

solverPreTryCatch

function solverPreTryCatch(
    uint256 bidAmount,
    SolverOperation calldata solverOp,
    bytes calldata returnData
) external payable onlyAtlasEnvironment validSolver(solverOp) returns (SolverTracker memory solverTracker);

Description

Handles the pre-execution phase of a SolverOperation. It initializes the SolverTracker with bid information and executes any pre-solver hooks if required by the CallConfig.

Parameters

Name	Type	Description
bidAmount	uint256	The solver's bid amount.
solverOp	SolverOperation	The solver operation being executed.
returnData	bytes	Data returned from the previous call phase.

Return Values

Name	Type	Description
solverTracker	SolverTracker	Bid tracking information for the solver.

Requirements

• The caller must be the Atlas contract.
• The SolverOperation must be valid.

Usage Notes

• This function is crucial for setting up the solver's execution context and handling pre-execution logic.

solverPostTryCatch

function solverPostTryCatch(
    SolverOperation calldata solverOp,
    bytes calldata returnData,
    SolverTracker memory solverTracker
) external payable onlyAtlasEnvironment returns (SolverTracker memory);

Description

Handles the post-execution phase of a SolverOperation. It updates the SolverTracker based on the outcome and ensures bid conditions are met.

Parameters

Name	Type	Description
solverOp	SolverOperation	The solver operation being executed.
returnData	bytes	Data returned from the previous call phase.
solverTracker	SolverTracker	Bid tracking information for the solver.

Return Values

Name	Type	Description
solverTracker	SolverTracker	Updated bid tracking information.

Requirements

• The caller must be the Atlas contract.

Usage Notes

• This function is essential for finalizing solver operations and ensuring all bid conditions are satisfied.

allocateValue

function allocateValue(
    address bidToken,
    uint256 bidAmount,
    bytes memory allocateData
) external onlyAtlasEnvironment returns (bool allocateValueSucceeded);

Description

Allocates value based on the outcome of a successful SolverOperation. It delegates the call to the allocateValueCall function of the DAppControl contract and handles potential failures based on the CallConfig.

Parameters

Name	Type	Description
bidToken	address	Address of the token used for the bid.
bidAmount	uint256	Amount of the bid.
allocateData	bytes	Data returned from the previous call phase.

Return Values

Name	Type	Description
allocateValueSucceeded	bool	Indicates if the allocation was successful.

Requirements

• The caller must be the Atlas contract.

Usage Notes

• This function is crucial for distributing value after successful solver operations.
• The behavior on allocation failure can be configured in the CallConfig.

withdrawERC20

function withdrawERC20(address token, uint256 amount) external;

Description

Allows the environment owner to withdraw ERC20 tokens from the ExecutionEnvironment.

Parameters

Name	Type	Description
token	address	Address of the ERC20 token to withdraw.
amount	uint256	Amount of the ERC20 token to withdraw.

Return Values

None

Requirements

• The caller must be the environment owner.
• The Atlas protocol must be in an unlocked state.
• The contract must have sufficient balance of the specified token.

Usage Notes

• This function provides a way for the owner to retrieve ERC20 tokens from the execution environment.

withdrawEther

function withdrawEther(uint256 amount) external;

Description

Enables the environment owner to withdraw Ether from the ExecutionEnvironment.

Parameters

Name	Type	Description
amount	uint256	Amount of Ether to withdraw.

Return Values

None

Requirements

• The caller must be the environment owner.
• The Atlas protocol must be in an unlocked state.
• The contract must have sufficient Ether balance.

Usage Notes

• This function allows the owner to retrieve Ether from the execution environment.

getUser

function getUser() external pure returns (address user);

Description

Retrieves the address of the user associated with this ExecutionEnvironment.

Parameters

None

Return Values

Name	Type	Description
user	address	Address of the user.

Requirements

None

Usage Notes

• This function is useful for identifying the user associated with the execution environment.

getControl

function getControl() external pure returns (address control);

Description

Fetches the address of the DAppControl contract associated with the current metacall transaction.

Parameters

None

Return Values

Name	Type	Description
control	address	Address of the DAppControl contract.

Requirements

None

Usage Notes

• This function helps in identifying the DAppControl contract governing the current execution context.

getConfig

function getConfig() external pure returns (uint32 config);

Description

Returns the CallConfig of the current metacall transaction in uint32 form.

Parameters

None

Return Values

Name	Type	Description
config	uint32	Configuration flags in bitmask format.

Requirements

None

Usage Notes

• This function is crucial for understanding the current execution configuration.

getEscrow

function getEscrow() external view returns (address);

Description

Retrieves the address of the Atlas/Escrow contract.

Parameters

None

Return Values

Name	Type	Description
address	address	Address of the Atlas/Escrow contract.

Requirements

None

Usage Notes

• This function is useful for interactions that require knowledge of the Escrow contract address.