Solidity API

GasAccounting

GasAccounting manages the accounting of gas surcharges and escrow balances for the Atlas protocol.

constructor

constructor(uint256 escrowDuration, uint256 atlasSurchargeRate, uint256 bundlerSurchargeRate, address verification, address simulator, address initialSurchargeRecipient, address l2GasCalculator) internal

_initializeAccountingValues

function _initializeAccountingValues(uint256 gasMarker, uint256 allSolverOpsGas) internal

Sets the initial gas accounting values for the metacall transaction in transient storage.

Resets t_gasLedger, t_borrowsLedger, t_solverLock, and t_solverTo at the start of each metacall. Initializes remainingMaxGas with the overall gas estimate and unreachedSolverGas with the precalculated gas for all potential solver operations. Sets initial repays based on msg.value.

Parameters

Name	Type	Description
gasMarker	uint256	The gas measurement at the start of the metacall, which includes Execution gas limits, Calldata gas costs, and an additional buffer for safety.
allSolverOpsGas	uint256	The sum of (C + E) gas limits for all solverOps in the metacall.

contribute

function contribute() external payable

Contributes ETH to the contract, increasing the deposits if a non-zero value is sent.

borrow

function borrow(uint256 amount) external

Borrows ETH from the contract, transferring the specified amount to the caller if available.

Borrowing is only available until the end of the SolverOperation phase, for solver protection.

Parameters

Name	Type	Description
amount	uint256	The amount of ETH to borrow.

shortfall

function shortfall() external view returns (uint256 gasLiability, uint256 borrowLiability)

Calculates the current shortfall currently owed by the winning solver.

The shortfall is calculated (claims + withdrawals + fees - writeoffs) - deposits. If this value is less than zero, shortfall returns 0 as there is no shortfall because the solver is in surplus.

Return Values

Name	Type	Description
gasLiability	uint256	The total gas charge (base + surcharges) owed by the solver. Can be repaid using bonded balance or native token.
borrowLiability	uint256	The total value of ETH borrowed but not yet repaid, only repayable using native token.

reconcile

function reconcile(uint256 maxApprovedGasSpend) external payable returns (uint256 owed)

Allows a solver to settle any outstanding ETH owed, either to repay gas used by their solverOp or to repay any ETH borrowed from Atlas. This debt can be paid either by sending ETH when calling this function (msg.value) or by approving Atlas to use a certain amount of the solver's bonded AtlETH.

The solver can call this function multiple times until the owed amount is zero. Note: reconcile() must be called by the solver to avoid a CallbackNotCalled error in solverCall().

Parameters

Name	Type	Description
maxApprovedGasSpend	uint256	The maximum amount of the solver's bonded AtlETH that Atlas can deduct to cover the solver's debt.

Return Values

Name	Type	Description
owed	uint256	The gas and borrow liability owed by the solver. The full gasLiability + borrowLiability amount is returned, unless the fulfilled, in which case 0 is returned.

_contribute

function _contribute() internal

Internal function to handle ETH contribution, increasing deposits if a non-zero value is sent.

_borrow

function _borrow(uint256 amount) internal returns (bool valid)

Borrows ETH from the contract, transferring the specified amount to the caller if available.

Borrowing should never be allowed after the SolverOperation phase, for solver safety. This is enforced in the external borrow function, and the only other time this internal _borrow function is called is in _solverOpInner which happens at the beginning of the SolverOperation phase.

Parameters

Name	Type	Description
amount	uint256	The amount of ETH to borrow.

Return Values

Name	Type	Description
valid	bool	A boolean indicating whether the borrowing operation was successful.

_assign

function _assign(struct EscrowAccountAccessData accountData, address account, uint256 amount) internal returns (uint256 deficit)

Takes AtlETH from the owner's bonded balance and, if necessary, from the owner's unbonding balance.

No GasLedger accounting changes are made in this function - should be done separately.

Parameters

Name	Type	Description
accountData	struct EscrowAccountAccessData	The EscrowAccountAccessData memory struct of the account being charged.
account	address	The address of the account from which AtlETH is taken.
amount	uint256	The amount of AtlETH to be taken.

Return Values

Name	Type	Description
deficit	uint256	The amount of AtlETH that was not repaid, if any.

_credit

function _credit(struct EscrowAccountAccessData accountData, uint256 amount) internal

Increases the owner's bonded balance by the specified amount.

Parameters

Name	Type	Description
accountData	struct EscrowAccountAccessData	The EscrowAccountAccessData memory struct of the account being credited.
amount	uint256	The amount by which to increase the owner's bonded balance.

_handleSolverFailAccounting

function _handleSolverFailAccounting(struct SolverOperation solverOp, uint256 dConfigSolverGasLimit, uint256 gasWaterMark, uint256 result, bool exPostBids) internal

Accounts for the gas cost of a failed SolverOperation, either by increasing writeoffs (if the bundler is blamed for the failure) or by assigning the gas cost to the solver's bonded AtlETH balance (if the solver is blamed for the failure).

Parameters

Name	Type	Description
solverOp	struct SolverOperation	The current SolverOperation for which to account.
dConfigSolverGasLimit	uint256	The gas limit for the solver operation, as specified in the DAppConfig.
gasWaterMark	uint256	The gasleft() watermark taken at the start of executing the SolverOperation.
result	uint256	The result bitmap of the SolverOperation execution.
exPostBids	bool	A boolean indicating whether exPostBids is set to true in the current metacall.

_writeOffBidFindGas

function _writeOffBidFindGas(uint256 gasUsed) internal

Records the gas used during the bidFind phase of exPostBids as a write-off.

Gas used for bidFind is considered an overhead paid by the bundler (via reduced refund) and is not charged to any specific solver. It's added to writeoffsGas in the GasLedger.

Parameters

Name	Type	Description
gasUsed	uint256	The amount of gas consumed during the bidFind phase.

_chargeUnreachedSolversForCalldata

function _chargeUnreachedSolversForCalldata(struct SolverOperation[] solverOps, struct GasLedger gL, uint256 winningSolverIdx, bytes32 userOpHash, uint256 maxFeePerGas, address bundler, bool allowsTrustedOpHash) internal returns (uint256 unreachedCalldataValuePaid)

Charges solvers that were not reached during the metacall for the calldata gas cost of their solverOps.

_Iterates through solverOps starting from the index after winningSolverIdx. For each unreached operation, VERIFICATION.verifySolverOp is called to determine fault.

• If bundler fault: The calldata gas is added to gL.writeoffsGas (reducing bundler's refund).
• If solver fault: Attempts to charge the solver's bonded AtlETH using _assign for the calldata gas cost (no surcharges added). Any deficit is added to gL.writeoffsGas. The gas cost of executing this loop is also added to gL.writeoffsGas to ensure the bundler pays for it._

Parameters

Name	Type	Description
solverOps	struct SolverOperation[]	The SolverOperation array containing the solvers' transaction data.
gL	struct GasLedger	The GasLedger struct (memory); gL.writeoffsGas is updated within this function.
winningSolverIdx	uint256	Index of the winning/last attempted solver; the loop starts after this index.
userOpHash	bytes32	Hash of the UserOperation, used for verification.
maxFeePerGas	uint256	userOp.maxFeePerGas, used for verification.
bundler	address	The metacall caller (msg.sender), used for verification.
allowsTrustedOpHash	bool	Flag indicating with trustedOpHash is enabled in the metacall.

Return Values

Name	Type	Description
unreachedCalldataValuePaid	uint256	Total value successfully charged to unreached solvers (cost - deficits).

_settle

function _settle(struct Context ctx, struct GasLedger gL, uint256 gasMarker, address gasRefundBeneficiary, uint256 unreachedCalldataValuePaid) internal returns (uint256 claimsPaidToBundler, uint256 netAtlasGasSurcharge)

Finalizes gas accounting at the end of the metacall, settles balances, and pays refunds/surcharges.

Parameters

Name	Type	Description
ctx	struct Context	The context struct (memory), used for ctx.bundler and ctx.solverSuccessful.
gL	struct GasLedger	The final state of the GasLedger struct (memory), used for gas calculations.
gasMarker	uint256	The initial gas measurement taken at the start of the metacall.
gasRefundBeneficiary	address	The address designated to receive the bundler's gas refund. Defaults to ctx.bundler.
unreachedCalldataValuePaid	uint256	The total value successfully collected from unreached solvers for their calldata costs (from _chargeUnreachedSolversForCalldata).

Return Values

Name	Type	Description
claimsPaidToBundler	uint256	The net amount of ETH transferred to the gasRefundBeneficiary.
netAtlasGasSurcharge	uint256	The net amount of ETH taken as Atlas surcharge during the metacall.

_updateAnalytics

function _updateAnalytics(struct EscrowAccountAccessData aData, bool auctionWon, uint256 gasValueUsed) internal pure

Updates auctionWins, auctionFails, and totalGasUsed values of a solver's EscrowAccountAccessData.

This function is only ever called in the context of bidFind = false so no risk of doublecounting changes.

Parameters

Name	Type	Description
aData	struct EscrowAccountAccessData	The Solver's EscrowAccountAccessData struct to update.
auctionWon	bool	A boolean indicating whether the solver's solverOp won the auction.
gasValueUsed	uint256	The ETH value of gas used by the solverOp. Should be calculated as gasUsed * tx.gasprice.

_isBalanceReconciled

function _isBalanceReconciled() internal view returns (bool)

Checks all obligations have been reconciled: native borrows AND gas liabilities.

Return Values

Name	Type	Description
[0]	bool	True if both dimensions are reconciled, false otherwise.