Interactions
Offchain
This diagram describes the interactions starting from the user initiating a swap, to the point where the final Atlas transaction reaches the blockchain.
Flow:
- User Operation Generation:
- Initiation: Users interact with DApp frontend to initiate token swaps.
- Meta-Transaction Creation: The frontend generates an unsigned UserOperation (userOp) adhering to the EIP712 standard.
- Data Encoding: The userOp includes encoded swap details, which will be decoded and processed by the DAppControl contract.
- Auction Process:
- Submission: The frontend shares the generated userOp directly with the Auctioneer.
- Hints Sharing: The Auctioneer provides all solvers with hints derived from the userOp to maintain user swap privacy and front-running protection.
- Solver Analysis: All solvers analyze the provided hints to identify profitable opportunities.
- Bid Submission: Solvers submit their SolverOperations (solverOps) to the Auctioneer.
- Bid Filtering and Selection:
- Simulation: The Auctioneer simulates transactions to evaluate the viability of bids.
- Bid Filtering: Based on simulation results, the Auctioneer filters out non-viable bids under a threshold.
- Selection: The Auctioneer selects multiple profitable solverOps based on bid amounts and simulation results.
- DAppOperation Creation:
- Bundling: The Auctioneer bundles the selected solverOps with the original userOp to form a dAppOperation.
- Return to User:
- The Auctioneer returns the selected solverOps and the created dAppOperation to the frontend.
- Metacall Transaction Formation:
- The frontend constructs an Atlas metacall transaction that includes the userOp, solverOps, and dAppOp.
- Transaction Signing and Submission:
- The frontend requests the user's wallet to sign the metacall transaction.
- The user approves and signs the transaction.
- The frontend, acting as the bundler, submits the signed bundled transaction
Onchain
This flow encapsulates the core on-chain interactions within the smart contracts, from the initial execution of the bundled transaction to the final allocation of values and completion of the swap operation.
Flow:
- Atlas Entrypoint Contract Execution: The bundled transaction (containing userOp, solverOps, and dappOp) is submitted to the Atlas Entrypoint Contract, which manages the execution flow.
- Pre-Ops Call:
- The DAppControl contract executes
_preOpsCall
. - This step handles necessary token transfers and approvals required for the swap.
- The DAppControl contract executes
- Swap Execution:
- The DApp contract is called to perform the token swap.
- It interacts with the DEX router, which in turn communicates with the appropriate TokenPools to execute the actual swap.
- The swap is performed as specified in the userOp.
- Solver Operations Execution:
- The Atlas Entrypoint Contract executes the solverOps.
- This includes paying the bid amount and performing any backrun operations specified by the solver.
- Value Allocation:
- The
_allocateValueCall
function is executed - The swap output is sent to the user during this step.
- The
- Post-Ops Call (Conditional):
- If the operation wasn't fully solved (i.e., if there were any issues or if additional balance checks are needed), the
_postOpsCall
function is executed. - This function ensures that output balances meet the required thresholds.
- If necessary, it handles any token refunds to the user.
- If the operation wasn't fully solved (i.e., if there were any issues or if additional balance checks are needed), the
- Transaction Completion:
- The Atlas Entrypoint Contract finalizes the transaction.
- The final result, including any relevant event emissions, is returned.
Gas Considerations
- Atlas is set up so that the sender (bundler) of the transaction gets repaid their gas fees by the successful solver.
- Any solver that fails, also must pay the gas fees for their portion (their failed solverOp) of the transaction. So even if all solvers fail, the solvers refund their gas costs to the sender so the sender only pays for the gas costs of the rest of the metacall transaction.
- In this flow, the user is the sender of the transaction (the metacall with the userOp, solverOps and dAppOp) and therefore will pay the upfront gas fees and be refunded all or some of the gas costs from the solvers.
- So for the user, they are only paying the net gas costs:
- If a solver is successful, the net gas costs are ~0
- If no solver is successful, the net gas costs are = the userOp (the swap itself) + some Atlas validation checks
- The auctioneer only shares ‘hints’ to the solvers, which in this case is just the pool address of the swap. The solver doesn’t know the amount or the direction of the swap. This is to maintain user privacy and front-running protection. This also means that the solver needs to do ‘onchain solving’ ie they need to include more logic onchain (compared to knowing the entire details of the transaction) to find the optimal backrun solution. Some solverOps can therefore be expensive in terms of gas (500K+ gas). But again, the solver pays for these gas costs whether they succeed or fail.