Atlas

Concept:

Atlas is a permissionless and modular smart contract framework for Execution Abstraction. It provides apps and frontends with an auction system in which Solvers compete to provide optimal solutions for user intents or MEV redistribution. A User Operation is collected by the app's frontend via the Atlas SDK and sent to an app-designated bundler, which combines it with Solver Operations into a single transaction.

DApp Integration

A frontend or API wishing to participate can integrate with Atlas by completing three steps:

1. Embed the Atlas SDK into their frontend or API to generate userOps.
2. Choose an Operations Relay to facilitate communication between users and solvers.
3. Create and publish a DAppControl contract that contains the logic specific to your application.
4. Interact with the Atlas contract to initialize the DAppControl contract and link it to the Atlas SDK on their frontend or API.

Network Overview

Atlas is infrastructure-agnostic; each app may choose how the User Operations and Solver Operations are aggregated by their choice of Operations Relay. Examples include:

1. BloXroute: When Atlas is launched, BloXroute's BDN will support the low latency aggregation of User and Solver Operations.
2. SUAVE: Once live, Operations can be sent to the SUAVE network, aggregated into a transaction by the SUAVE Atlas implementation, and then made available for use by bundlers.
3. On Chain: When gas costs and throughput are not an issue, Solver Operations may be sent on-chain, and then aggregated by any party, including a smart contract.
4. On Another Chain: Solver Operations may be posted and aggregated on another chain, and the output can be used to settle the atlas transaction on the settlement chain.

Auctioneer Overview

Each frontend may choose a party to act as the auctioneer. It is strongly recommended to select the auction beneficiary act as the auctioneer. This is the most trust-minimized solution because the beneficiary can always trust themselves. We expect most -but not all- frontends to select the user as the auctioneer and to handle the auctioneer duties without user input through the Atlas SDK in the frontend/API, as the user also explicity trusts the frontent/API.

The auctioneer is tasked with signing a DAppOperation that includes a CallChainHash. This hash guarantees that the bundler cannot tamper with the execution order of the SolverOperations. Any party can easily generate this hash by making a view call to the getCallChainHash(SolverOperations[]) function. Note that infrastructure networks with programmable guarantees such as SUAVE will not require this as it can be handled trustlessly in-network.

Auctioneer Example: Featuring BloXroute as the Operations Relay

1. User connects to a frontend and receives a session key.
2. User signs their UserOperation, which is propagated over the bloXroute BDN to solvers.
3. The frontend receives SolverOperations back via the BDN.
4. The frontend calls the getCallChainHash() view function via the User's wallet's RPC.
5. The frontend then uses the session key from step 1 to sign the DAppOperation, which includes the CallChainHash.
6. The frontend then propagates the DAppOperation over the BDN to a designated bundler, if the user themselves is not the bundler.

Note that any bundler who tampers with the order of the SolverOperations will cause the transaction to revert, thereby blocking any gas reimbursement from Atlas.

Note that input from the User is only required for step 2; all other steps have no impact on UX.

Note that the bundler should be able to receive ETH without reverting, as they may receive a refund of the msg.value sent with the metacall() if the config dictates that metacall() should return false instead of reverting, or if gasRefundBeneficiary is set to address(0), in which case gas refunds are sent to the bundler.

Atlas Transaction Structure

DAppControl

The DAppControl contract is where frontends and APIs define functions that will execute at specific stages during the Atlas transaction. The contract also contains app-specific settings, such as the address of permitted bundlers, or if the asynchronous processing of User nonces is permitted. These functions and settings are referenced by the Atlas smart contract during execution to create a trustless environment that is maximally composable with the DApp's existing smart contracts - no upgrades or redeployments are required.

The DAppControl contract may define which entities are permitted to act as the Bundler. The frontend can designate one or more of the following:

1. DAppProxy: A specific address (or addresses) is permitted to bundle operations.
2. User: The User is permitted to bundle operations.
3. Builder: The builder ("block.coinbase") is permitted to bundle operations.
4. Solver: The top-bidding Solver is permitted to bundle the User Operation and their own Solver Operation, but may not include the Operations of other Solvers.
5. Conditional: A specific function handles complex Bundler designation logic.
6. Time Limit: For On Chain auctions, any party may trigger the On Chain Bundler to execute the finalized transaction, pursuant to the passing of a minimum auction duration (as specified by the DApp.)

The DAppControl contract must define the following functions:

1. BidFormat: This function defines the base currency (or currencies) of the auction.
2. BidValue: This function defines how to rank bids so that they may be sorted by the auctioneer.
3. AllocateValue*: This function defines how to allocate the bid from the winning solver (if any). It may also serve as a place for the DApp to execute any final logic before the transaction is finalized, as it is the last function called by the Atlas contract.

The DAppControl contract has the option to define functions that execute at the following stages:

1. PreOps*: This function is executed before the User's operation
2. PreSolver*: This function is executed after the User's operation but before a Solver's operation. It occurs inside of a try/catch; if it reverts, the current Solver's solution will fail and the next Solver's solution will begin. If the Solver's operation or the PostSolver function revert, anything accomplished by the PreSolver function will also be reverted.
3. PostSolver*: This function is executed after the User's operation and after a Solver's operation. It occurs inside of a try/catch; if it reverts, the PreSolver function, and the current Solver's operation will also be reverted and the next Solver's solution will begin.

*These functions are executed by the Execution Environment via "delegatecall."

Ex-Post Bids

When bid amounts are known ahead of time by solvers the _bidKnownIteration() function is called and bids are sorted by bid amount, and executed until one is successful. If bid amounts are not known beforehand, such as when they are doing blind on-chain solving, the _bidFindingIteration() function is called to calculate the bid amounts on-chain. This is done by calling the same _executeSolverOperation() used in the _bidKnownIteration() for each solverOp, and checking the balance of the contract before and after to calculate the bid amounts for each solverOp.

Multiple Successful Solvers

In this config, multiple solvers can execute successfully and each pay a bid amount. Atlas will continue to revert solvers who do not pay their bid in this config. This config enables app specific ordering rules, rather than a standard backrun auction. If the MEV is taken by an earlier solver in this config, the next solver should either revert early or search for leftover MEV. The gas accounting will enforce that each solver must cover the gas costs and surcharges associated with only their solver operation (i.e. even if a solver operation succeeds, that solver will not have to pay the gas costs associated with other solver operations, or any non-solver operation calldata or execution gas cost). If there are multiple solvers with bidAmount > 0 that execute successfully, the bid amounts are summed. The sum of the bids is passed to allocateValue() hook. The allocateValue() hook and the _settle() function are called with ctx.solverSuccessful set to false, even though all solvers may have executed successfully and paid their bid. The DappControl will understand and handle this in the allocateValue() hook implementation. This config is not designed to be used with the invertBidValue, solverAuctioneer, requireFulfillment, zeroSolvers, or the exPostBids configs, and this is enforced in AtlasVerification.

Permit69

A user must have an Execution Environment (EE) instance for each DApp they would like to use, and the user address is used as a salt for the create2 deterministic deployment of it. If one is not already available, EEs can be deployed during execution of a user order since their address is known beforehand, this gas cost is covered by the solver so UX is never impacted. The EE performs ops via delegateCalls, so it needs to be able to initiate token transfers from the user. Users only have to approve the Atlas contract once because Permit69 allows Atlas to transfer funds from the user if the request is from a valid EE for that user (checked by verifying that the user address is one of the salts used for the EE address). Permit69 is also used by DApps, but instead transfers tokens that have accumulated in the DAppControl contract, this function performs the same verification of the EE.

ExecutionBase

_availableFundsERC20() is used to check the approved balance of users and dapps to atlas that can be withdrawn via Permit69.

_transferDAppERC20() and _transferUserERC20() are functions that can be implemented by Atlas module developers in DappCon