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) internal
Sets the initial accounting values for the metacall transaction.
Parameters
| Name | Type | Description |
|---|---|---|
| gasMarker | uint256 | The gas marker used to calculate the initial accounting values. |
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 payable
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)
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 |
|---|---|---|
| [0] | uint256 | uint256 The current shortfall amount, or 0 if there is no shortfall. |
_deficit
function _deficit() internal view returns (uint256)
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 amount owed, if any, by the solver after reconciliation. |
_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(address owner, uint256 amount, uint256 gasValueUsed, bool solverWon) internal returns (uint256 deficit)
Takes AtlETH from the owner's bonded balance and, if necessary, from the owner's unbonding balance to increase transient solver deposits.
Parameters
| Name | Type | Description |
|---|---|---|
| owner | address | The address of the owner from whom AtlETH is taken. |
| amount | uint256 | The amount of AtlETH to be taken. |
| gasValueUsed | uint256 | The ETH value of gas used in the SolverOperation. |
| solverWon | bool | A boolean indicating whether the solver won the bid. |
Return Values
| Name | Type | Description |
|---|---|---|
| deficit | uint256 | The amount of AtlETH that was not repaid, if any. |
_credit
function _credit(address owner, uint256 amount, uint256 gasValueUsed) internal
Increases the owner's bonded balance by the specified amount.
Parameters
| Name | Type | Description |
|---|---|---|
| owner | address | The address of the owner whose bonded balance will be increased. |
| amount | uint256 | The amount by which to increase the owner's bonded balance. |
| gasValueUsed | uint256 | The ETH value of gas used in the SolverOperation. |
_handleSolverAccounting
function _handleSolverAccounting(struct SolverOperation solverOp, uint256 gasWaterMark, uint256 result, bool includeCalldata) 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. |
| gasWaterMark | uint256 | The gasleft() watermark taken at the start of executing the SolverOperation. |
| result | uint256 | The result bitmap of the SolverOperation execution. |
| includeCalldata | bool | Whether to include calldata cost in the gas calculation. |
_writeOffBidFindGasCost
function _writeOffBidFindGasCost(uint256 gasUsed) internal
_adjustAccountingForFees
function _adjustAccountingForFees(struct Context ctx, uint256 solverGasLimit) internal returns (uint256 adjustedWithdrawals, uint256 adjustedDeposits, uint256 adjustedClaims, uint256 adjustedWriteoffs, uint256 netAtlasGasSurcharge)
This function is called internally to adjust the accounting for fees based on the gas usage.
Note: The behavior of this function depends on whether _bidFindingIteration() or _bidKnownIteration() is
used, as they both use a different order of execution.
Parameters
| Name | Type | Description |
|---|---|---|
| ctx | struct Context | Context struct containing relevant context information for the Atlas auction. |
| solverGasLimit | uint256 | The maximum gas limit for a solver, as set in the DAppConfig |
Return Values
| Name | Type | Description |
|---|---|---|
| adjustedWithdrawals | uint256 | Withdrawals of the current metacall, adjusted by adding the Atlas gas surcharge. |
| adjustedDeposits | uint256 | Deposits of the current metacall, no adjustments applied. |
| adjustedClaims | uint256 | Claims of the current metacall, adjusted by subtracting the unused gas scaled to include bundler surcharge. |
| adjustedWriteoffs | uint256 | Writeoffs of the current metacall, adjusted by adding the bundler gas overage penalty if applicable. |
| netAtlasGasSurcharge | uint256 | The net gas surcharge of the metacall, taken by Atlas. |
_settle
function _settle(struct Context ctx, uint256 solverGasLimit, address gasRefundBeneficiary) internal returns (uint256 claimsPaidToBundler, uint256 netAtlasGasSurcharge)
Settle makes the final adjustments to accounting variables based on gas used in the metacall. AtlETH is either taken (via _assign) or given (via _credit) to the winning solver, the bundler is sent the appropriate refund for gas spent, and Atlas' gas surcharge is updated.
Parameters
| Name | Type | Description |
|---|---|---|
| ctx | struct Context | Context struct containing relevant context information for the Atlas auction. |
| solverGasLimit | uint256 | The dApp's maximum gas limit for a solver, as set in the DAppConfig. |
| gasRefundBeneficiary | address | The address to receive the gas refund. |
Return Values
| Name | Type | Description |
|---|---|---|
| claimsPaidToBundler | uint256 | The amount of ETH paid to the bundler in this function. |
| netAtlasGasSurcharge | uint256 | The net gas surcharge of the metacall, taken by Atlas. |
_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. |
_getCalldataCost
function _getCalldataCost(uint256 calldataLength) internal view returns (uint256 calldataCost)
Calculates the gas cost of the calldata used to execute a SolverOperation.
Parameters
| Name | Type | Description |
|---|---|---|
| calldataLength | uint256 | The length of the data field in the SolverOperation. |
Return Values
| Name | Type | Description |
|---|---|---|
| calldataCost | uint256 | The gas cost of the calldata used to execute the SolverOperation. |
_isBalanceReconciled
function _isBalanceReconciled() internal view returns (bool)
Checks if the current balance is reconciled.
Compares the deposits with the sum of claims, withdrawals, fees, and write-offs to ensure the balance is correct.
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | bool | True if the balance is reconciled, false otherwise. |