EscrowTypes

EscrowTypes defines the structs and enums used within the Escrow contract as well as the SolverTracker struct used in the AtlasCore contract.

EscrowAccountBalance

struct EscrowAccountBalance {
    uint112 balance;
    uint112 unbonding;
}

Description

The EscrowAccountBalance struct represents the financial state of a user's escrow account within the Atlas Protocol. It tracks both the total bonded balance and the amount currently undergoing the unbonding process.

Fields

Name	Type	Description
balance	uint112	Total bonded balance available in the escrow.
unbonding	uint112	Amount currently unbonding, pending withdrawal.

Usage Notes

• Bond Management: This struct is essential for managing user bonds, ensuring accurate tracking of available and pending balances.
• Security: By separating bonded and unbonding amounts, the protocol can enforce withdrawal restrictions and prevent unauthorized access to funds.

EscrowAccountAccessData

struct EscrowAccountAccessData {
    uint112 bonded;
    uint32 lastAccessedBlock;
    uint24 auctionWins;
    uint24 auctionFails;
    uint64 totalGasValueUsed; // The cumulative ETH value spent on gas in metacalls. Measured in gwei.
}

Description

The EscrowAccountAccessData struct maintains metadata related to a user's escrow account, facilitating tracking of account usage and performance within the protocol.

Fields

Name	Type	Description
bonded	uint112	Amount of funds currently bonded in the escrow.
lastAccessedBlock	uint32	Block number when the escrow account was last accessed, aiding in tracking account activity.
auctionWins	uint24	Number of auctions the user has won, indicating their participation and success in auctions.
auctionFails	uint24	Number of auctions the user has failed, providing insights into their auction performance.
totalGasValueUsed	uint64	Cumulative ETH value (in gwei) spent on gas during metacalls, useful for gas accounting and analytics.

Usage Notes

• Performance Tracking: This struct helps in monitoring user engagement and performance in auction-based operations within the protocol.
• Gas Accounting: Tracking totalGasValueUsed is crucial for accurate gas fee management and potential optimizations.

SolverTracker

struct SolverTracker {
    uint256 bidAmount;
    uint256 floor;
    uint256 ceiling;
    bool etherIsBidToken;
    bool invertsBidValue;
}

Description

The SolverTracker struct is designed to manage and monitor the bidding and performance metrics of solvers participating in operations within the Atlas Protocol. It ensures solvers adhere to bid constraints and provides mechanisms to evaluate their effectiveness.

Fields

Name	Type	Description
bidAmount	uint256	The amount bid by the solver for a particular operation.
floor	uint256	The minimum acceptable bid amount for the operation.
ceiling	uint256	The maximum allowable bid amount for the operation, preventing overbidding.
etherIsBidToken	bool	Indicates whether ETH is used as the bid token (true) or another ERC20 token (false).
invertsBidValue	bool	Determines if lower bids are more favorable (true) or higher bids are more favorable (false).

Usage Notes

• Bid Management: Ensures solvers place bids within defined limits, maintaining fairness and preventing excessive bids.
• Performance Evaluation: By tracking bid amounts and constraints, the protocol can assess solver performance and make informed decisions during auction-based operations.

EscrowTypes - SolverOutcome Enum

SolverOutcome

enum SolverOutcome {
    // No Refund (relay error or hostile user)
    InvalidSignature,
    InvalidUserHash,
    DeadlinePassedAlt,
    GasPriceBelowUsersAlt,
    InvalidTo,
    UserOutOfGas,
    AlteredControl,
    AltOpHashMismatch,
    // Partial Refund but no execution
    DeadlinePassed,
    GasPriceOverCap,
    InvalidSolver,
    InvalidBidToken,
    PerBlockLimit,
    InsufficientEscrow,
    GasPriceBelowUsers,
    CallValueTooHigh,
    PreSolverFailed,
    // execution, with Full Refund
    SolverOpReverted,
    PostSolverFailed,
    BidNotPaid,
    InvertedBidExceedsCeiling,
    BalanceNotReconciled,
    CallbackNotCalled,
    EVMError
}

Description

The SolverOutcome enumeration categorizes the various results that can occur during a solver's operation within the Atlas Protocol. Each outcome represents a specific scenario, facilitating detailed tracking and handling of solver performance and errors.

Enumeration Values

Value	Category	Description	Refund	Execution
InvalidSignature	No Refund	The solver's signature is invalid or unauthorized.	No Refund	No Execution
InvalidUserHash	No Refund	The provided user operation hash doesn't match the expected hash.	No Refund	No Execution
DeadlinePassedAlt	No Refund	An alternative deadline check has failed.	No Refund	No Execution
GasPriceBelowUsersAlt	No Refund	The gas price is below an alternative user-specified threshold.	No Refund	No Execution
InvalidTo	No Refund	The 'to' address in the solver operation is invalid.	No Refund	No Execution
UserOutOfGas	No Refund	The user has run out of gas during the operation.	No Refund	No Execution
AlteredControl	No Refund	The control parameters have been altered unexpectedly.	No Refund	No Execution
AltOpHashMismatch	No Refund	An alternative operation hash mismatch has occurred.	No Refund	No Execution
DeadlinePassed	Partial Refund	The operation's deadline has passed.	Partial Refund	No Execution
GasPriceOverCap	Partial Refund	The gas price exceeds the maximum allowed cap.	Partial Refund	No Execution
InvalidSolver	Partial Refund	The solver address is not authorized or invalid.	Partial Refund	No Execution
InvalidBidToken	Partial Refund	The token used for bidding is invalid.	Partial Refund	No Execution
PerBlockLimit	Partial Refund	The solver has exceeded the per-block operation limit.	Partial Refund	No Execution
InsufficientEscrow	Partial Refund	The solver's escrow balance is insufficient.	Partial Refund	No Execution
GasPriceBelowUsers	Partial Refund	The gas price is below the user-specified minimum.	Partial Refund	No Execution
CallValueTooHigh	Partial Refund	The call value exceeds the allowed limit.	Partial Refund	No Execution
PreSolverFailed	Partial Refund	Pre-solver operations have failed.	Partial Refund	No Execution
SolverOpReverted	Full Refund	The solver's operation was reverted during execution.	Full Refund	Partial Execution
PostSolverFailed	Full Refund	Post-solver operations have failed.	Full Refund	Partial Execution
BidNotPaid	Full Refund	The solver's bid was not paid as required.	Full Refund	Partial Execution
InvertedBidExceedsCeiling	Full Refund	An inverted bid has exceeded the specified ceiling.	Full Refund	Partial Execution
BalanceNotReconciled	Full Refund	The solver's balance could not be reconciled after the operation.	Full Refund	Partial Execution
CallbackNotCalled	Full Refund	A required callback function was not called.	Full Refund	Partial Execution
EVMError	Full Refund	An error occurred in the Ethereum Virtual Machine during execution.	Full Refund	Partial Execution

Usage Notes

• Outcome Tracking: The SolverOutcome enum allows the protocol to monitor and respond to specific scenarios during solver operations, enhancing operational transparency and security.
• Error Handling: By categorizing outcomes, the protocol can implement targeted error handling strategies, ensuring robust and resilient operations.
• Refund Mechanisms: Different outcomes dictate varying refund strategies, balancing cost recovery and incentivization for solvers.
  • No Refund: Typically for errors that are considered the fault of the solver or user, or for potential malicious actions.
  • Partial Refund: For cases where the operation failed due to conditions that may not be entirely under the solver's control.
  • Full Refund: Applied when the solver operation partially executed but ultimately failed, ensuring solvers are not penalized for system-level issues.
• Execution Status: Indicates whether any part of the solver's operation was executed before the failure occurred, which is crucial for understanding the state of the system and any potential side effects.