AtlasVerification

The AtlasVerification contract is a critical component of the Atlas Protocol, designed to verify the integrity and validity of operations within metacall transactions. Its primary functions include:

1. Leveraging EIP712 for structured data hashing and signature verification
2. Ensuring that calldata from users, solvers, and dApps complies with the protocol's security and operational standards
3. Integrating with the NonceManager contract to manage nonce validations, enhancing protection against replay attacks
4. Collaborating with the DAppIntegration contract to handle dApp signatory configurations, reinforcing safeguards against unauthorized access

Through these mechanisms, the AtlasVerification contract plays a crucial role in maintaining the security and integrity of the Atlas Protocol ecosystem.

Constructor

constructor(address atlas) EIP712("AtlasVerification", "1.0") DAppIntegration(atlas) { }

Description

Initializes the AtlasVerification contract by setting up the EIP712 domain for structured data hashing and integrating with the specified Atlas contract. This setup is essential for ensuring that all signatures and hashed data conform to the EIP712 standard, enabling secure and verifiable interactions within the protocol.

Parameters

Name	Type	Description
atlas	address	The address of the Atlas contract to integrate with.

Requirements

• Valid Atlas Address: The atlas address must point to a deployed and functioning Atlas contract that adheres to the expected interface.
• EIP712 Compliance: Ensures that all hashed data and signatures conform to the EIP712 standard, enabling interoperability and security.

Events Emitted

None

Usage Notes

• EIP712 Setup: Establishes the domain separator and type hashing for the contract, which are fundamental for signature verification processes.
• Integration: Connects the verification logic with the main Atlas contract, facilitating seamless operation within the protocol's ecosystem.

validateCalls

function validateCalls(
    DAppConfig calldata dConfig,
    UserOperation calldata userOp,
    SolverOperation[] calldata solverOps,
    DAppOperation calldata dAppOp,
    uint256 msgValue,
    address msgSender,
    bool isSimulation
) external returns (ValidCallsResult);

Description

Verifies the validity of the metacall calldata components, ensuring that all operations initiated by users, solvers, and dApps are legitimate and conform to the protocol's rules. This function performs a series of checks, including signature validations, nonce verifications, deadline assessments, and configuration consistency to uphold the integrity of each metacall transaction.

Parameters

Name	Type	Description
dConfig	DAppConfig	Configuration data for the dApp involved, containing execution parameters and settings.
userOp	UserOperation	The UserOperation struct of the metacall.
solverOps	SolverOperation[]	An array of SolverOperation structs.
dAppOp	DAppOperation	The DAppOperation struct of the metacall.
msgValue	uint256	The ETH value sent with the metacall transaction.
msgSender	address	The forwarded msg.sender of the original metacall transaction in the Atlas contract.
isSimulation	bool	Indicates if the call is a simulation.

Return Values

Name	Type	Description
ValidCallsResult	ValidCallsResult	The result of the validation process, represented as an enum indicating success or specific failure reasons.

Requirements

• Caller Authorization: Must be called by the Atlas contract. If not, the function reverts with AtlasErrors.InvalidCaller().
• Signature Validity: Ensures that all signatures from users, solvers, and dApps are valid and correspond to the provided data.
• Nonce Integrity: Validates that nonces are correctly sequenced or uniquely used to prevent replay attacks.
• Deadline Compliance: Checks that the current block number does not exceed any specified deadlines in the operations.
• Gas Price Constraints: Verifies that the transaction's gas price does not exceed user-specified limits.
• Value Consistency: Ensures that the ETH value sent with the transaction meets or exceeds the value required by the user operation.
• Configuration Consistency: Confirms that the call configurations in the dApp configuration and user operations match as expected.

Events Emitted

None

Usage Notes

• Comprehensive Validation: Performs multiple layers of validation to ensure that every aspect of the metacall is secure and adheres to protocol standards.
• Simulation Handling: Allows for validation without state changes when isSimulation is true, facilitating testing and analysis without affecting the protocol's state.
• Flexible Execution: Supports both scenarios where dApps allow trusted operation hashes and where they require strict signature verifications.

verifySolverOp

function verifySolverOp(
    SolverOperation calldata solverOp,
    bytes32 userOpHash,
    uint256 userMaxFeePerGas,
    address bundler,
    bool allowsTrustedOpHash
) external view returns (uint256 result);

Description

Validates the integrity and compliance of a SolverOperation within a metacall. This function checks the solver's signature, ensures that the solver's parameters align with user specifications, and verifies that the solver is authorized to perform the operation. The validation result is returned as a bitmap indicating specific outcomes or failures.

Parameters

Name	Type	Description
solverOp	SolverOperation	The SolverOperation struct to verify.
userOpHash	bytes32	The hash of the associated UserOperation struct.
userMaxFeePerGas	uint256	The maximum fee per gas the user is willing to pay.
bundler	address	The address of the bundler.
allowsTrustedOpHash	bool	Indicates if trusted operation hashes are allowed.

Return Values

Name	Type	Description
result	uint256	A bitmap representing the outcome of the verification, indicating success or specific failure reasons based on the SolverOutcome enum.

Requirements

• Solver Authorization: The solver must either be the bundler or possess a valid signature. If not, the verification fails with SolverOutcome.InvalidSignature.
• User Operation Hash Match: The solverOp.userOpHash must match the provided userOpHash. Mismatches result in SolverOutcome.InvalidUserHash.
• Recipient Address Validation: The solverOp.to must point to the Atlas contract. Incorrect addresses trigger SolverOutcome.InvalidTo.
• Gas Price Compliance: The transaction's gas price must not exceed the solver's maxFeePerGas. Exceeding this limit results in SolverOutcome.GasPriceOverCap.
• Solver's Gas Price Adequacy: The solver's maxFeePerGas must meet or exceed the user's maxFeePerGas. Failures here lead to either SolverOutcome.GasPriceBelowUsersAlt or SolverOutcome.GasPriceBelowUsers, depending on the allowsTrustedOpHash flag.
• Solver Identity Validation: The solver must not be the Atlas contract itself or the verification contract. Violations cause SolverOutcome.InvalidSolver.

Events Emitted

None

Usage Notes

• Security Enforcement: Ensures that only authorized and properly incentivized solvers can execute operations, maintaining the protocol's security and efficiency.
• Outcome Specificity: By returning a bitmap of SolverOutcome, it allows callers to programmatically determine the exact reason for any verification failure, facilitating better error handling and debugging.

verifyCallConfig

function verifyCallConfig(uint32 callConfig) external pure returns (ValidCallsResult);

Description

Validates the configuration settings specified in a callConfig parameter. This function ensures that the provided call configurations adhere to protocol rules, preventing invalid or conflicting configurations that could compromise the execution of metacalls.

Parameters

Name	Type	Description
callConfig	uint32	The call configuration struct to verify.

Return Values

Name	Type	Description
ValidCallsResult	ValidCallsResult	The result of the call configuration validation, represented as an enum indicating success or specific failure reasons.

Requirements

• Mutually Exclusive Settings: Ensures that certain configuration flags do not conflict. For example, both needsPreOpsReturnData and needsUserReturnData cannot be enabled simultaneously.
• Sequential Nonce Constraints: Validates that only one type of nonce system (user or dApp) is set to sequential, preventing dual sequential configurations that could lead to operational conflicts.
• Bid Configuration Validation: Ensures that bid-related configurations, such as invertBidValue and exPostBids, are not set in a way that makes bid determination ambiguous or unfeasible.

Usage Notes

• Configuration Integrity: Maintains the integrity and consistency of call configurations, ensuring that metacall executions proceed without configuration-induced errors.
• Protocol Compliance: Enforces protocol rules regarding call configurations, preventing unauthorized or unintended operational behaviors.

getSolverPayload

function getSolverPayload(SolverOperation calldata solverOp) external view returns (bytes32 payload);

Description

Generates and returns the EIP712-compliant hash of a SolverOperation struct. This payload is used in the signature verification process to ensure that the solver's operation data has not been tampered with and originates from a legitimate source.

Parameters

Name	Type	Description
solverOp	SolverOperation	The SolverOperation struct to hash.

Return Values

Name	Type	Description
payload	bytes32	The EIP712-compliant hash of the provided SolverOperation struct.

Requirements

• EIP712 Compliance: The payload must conform to the EIP712 standard to ensure compatibility with signature verification mechanisms.
• Accurate Struct Encoding: All fields within the SolverOperation struct must be correctly encoded to produce an accurate hash.

Usage Notes

• Signature Verification: Utilized in the verification process to authenticate solver operations, ensuring that only authorized solvers can execute operations.
• Data Integrity: Guarantees that the operation data remains unaltered from its original submission, maintaining the protocol's reliability.

getDAppOperationPayload

function getDAppOperationPayload(DAppOperation calldata dAppOp) public view returns (bytes32 payload);

Description

Generates and returns the EIP712-compliant hash of a DAppOperation struct. This payload is essential for verifying the authenticity and integrity of dApp operations within a metacall, ensuring that the operation data is trustworthy and originates from an authorized source.

Parameters

Name	Type	Description
dAppOp	DAppOperation	The DAppOperation struct to hash.

Return Values

Name	Type	Description
payload	bytes32	The EIP712-compliant hash of the provided DAppOperation struct.

Requirements

• EIP712 Compliance: The payload must adhere to the EIP712 standard to ensure seamless integration with signature verification processes.
• Accurate Struct Encoding: All fields within the DAppOperation struct must be accurately encoded to produce a valid hash.

Usage Notes

• dApp Signature Verification: Essential for authenticating dApp operations, ensuring that only authorized dApps can initiate or modify operations within the protocol.
• Operational Security: Prevents unauthorized or malicious dApps from injecting invalid or harmful operations, maintaining the protocol's security and integrity.

getDomainSeparator

function getDomainSeparator() external view returns (bytes32 domainSeparator);

Description

Retrieves the EIP712 domain separator used in the signature verification process. The domain separator is a unique identifier for the contract and the current version, ensuring that signatures are bound to this specific contract instance and cannot be reused across different domains.

Parameters

None

Return Values

Name	Type	Description
domainSeparator	bytes32	The EIP712 domain separator for the AtlasVerification contract.

Requirements

• EIP712 Domain Configuration: Must correctly reflect the contract's name and version as defined during contract initialization.
• Immutable After Deployment: The domain separator should remain constant post-deployment to ensure consistent signature verification.

Usage Notes

• Signature Verification: Utilized in conjunction with hashed operation payloads to verify that signatures are specific to this contract instance.
• Security Assurance: Prevents cross-contract signature reuse, ensuring that signatures are only valid within the intended domain.

getUserOperationPayload

function getUserOperationPayload(UserOperation calldata userOp) public view returns (bytes32 payload);

Description

Generates and returns the EIP712-compliant hash of a UserOperation struct. This payload is utilized in the signature verification process to authenticate user operations, ensuring that the operation data is legitimate and has not been tampered with.

Parameters

Name	Type	Description
userOp	UserOperation	The UserOperation struct to hash.

Return Values

Name	Type	Description
payload	bytes32	The EIP712-compliant hash of the provided UserOperation struct.

Requirements

• EIP712 Compliance: The payload must adhere to the EIP712 standard to ensure compatibility with signature verification mechanisms.
• Accurate Struct Encoding: All fields within the UserOperation struct must be correctly encoded to produce an accurate hash.

Usage Notes

• User Signature Verification: Essential for authenticating user-initiated operations, ensuring that only authorized users can perform actions within the protocol.
• Replay Attack Prevention: By hashing the entire operation data, it ensures that each signature is unique and bound to a specific operation, preventing replay attacks.

getUserOperationHash

function getUserOperationHash(UserOperation calldata userOp) public view returns (bytes32 userOpHash);

Description

Generates and returns the hash of a UserOperation struct, which is used for inter-operation references and signature verification. This function ensures that the hash accurately represents the operation data, facilitating secure and verifiable interactions within the protocol.

Parameters

Name	Type	Description
userOp	UserOperation	The UserOperation struct to hash.

Return Values

Name	Type	Description
userOpHash	bytes32	The hash of the provided UserOperation struct for inter-operation references.

Requirements

• Consistent Hashing: Must consistently produce the same hash for identical UserOperation structs to ensure reliable verification.
• EIP712 Compatibility: Aligns with the EIP712 standard to facilitate seamless signature verification processes.

Usage Notes

• Inter-Operation References: Used to link user operations with corresponding dApp and solver operations, ensuring coherence and traceability within metacall transactions.
• Signature Binding: Binds user signatures to specific operations, preventing unauthorized alterations or replay of operations.

Events Emitted

AtlasVerification does not emit any events. All verification-related state changes and validations are handled internally within the contract to maintain efficiency and reduce unnecessary logging overhead.

[Previous content remains unchanged]

Inherited External Functions

The AtlasVerification contract inherits from several parent contracts and libraries, each contributing specific functionalities essential for the contract's operation. Below is a breakdown of the inherited external functions provided by these parent contracts:

From EIP712

The EIP712 contract from OpenZeppelin facilitates the implementation of the EIP712 standard for hashing and signing of typed structured data. It provides functions to generate domain-specific hashes used in signature verification.

Functions

_hashTypedDataV4

function _hashTypedDataV4(bytes32 structHash) internal view virtual returns (bytes32);

Description: Returns the hash of the fully encoded EIP712 message for the given struct hash.

Usage: Used internally to generate hashes for structured data before signature verification.

DOMAIN_SEPARATOR

function _domainSeparatorV4() internal view returns (bytes32);

Description: Returns the domain separator used in the encoding of the signature for the current contract.

Usage: Provides the domain-specific context required for EIP712-compliant signatures.

Usage Notes

• Structured Data Hashing: Essential for creating hashes that are compliant with EIP712, enabling secure and standardized signature processes.
• Domain Context: Ensures that signatures are bound to a specific domain (contract and version), preventing cross-contract replay attacks.

From NonceManager

The NonceManager contract manages and validates nonces for users and dApp signatories, preventing replay attacks and ensuring the correct sequencing of operations.

Functions

userSequentialNonceTrackers

function userSequentialNonceTrackers(address account) external view returns (uint256 lastUsedSeqNonce);

Description: Returns the last used sequential nonce for a user.

Usage: Helps in determining the next valid sequential nonce for a user.

dAppSequentialNonceTrackers

function dAppSequentialNonceTrackers(address account) external view returns (uint256 lastUsedSeqNonce);

Description: Returns the last used sequential nonce for a dApp signatory.

Usage: Ensures that dApp operations are processed in the correct sequence.

userNonSequentialNonceTrackers

function userNonSequentialNonceTrackers(address account, uint248 wordIndex) external view returns (uint256 bitmap);

Description: Returns the non-sequential nonce bitmap for a user at a specific word index.

Usage: Facilitates tracking of non-sequential nonces for users, allowing for flexible operation ordering.

Usage Notes

• Replay Protection: Ensures that each nonce is unique and cannot be reused, preventing replay attacks.
• Sequential Integrity: Maintains the correct order of operations for both users and dApp signatories, ensuring protocol reliability.

From DAppIntegration

The DAppIntegration contract manages the integration of dApps and their authorized signatories within the Atlas Protocol, handling governance configurations and signatory management.

Functions

initializeGovernance

function initializeGovernance(address control) external;

Description: Integrates a new dApp into the Atlas Protocol by initializing its governance structure.

Usage: Sets the initial governance signatory for a dApp's DAppControl contract.

addSignatory

function addSignatory(address control, address signatory) external;

Description: Adds a new signatory to a dApp's list of approved signatories.

Usage: Allows governance entities to delegate signing authority to additional addresses.

removeSignatory

function removeSignatory(address control, address signatory) external;

Description: Removes an existing signatory from a dApp's list of approved signatories.

Usage: Enables governance entities or the signatory themselves to revoke signing authority.

changeDAppGovernance

function changeDAppGovernance(address oldGovernance, address newGovernance) external;

Description: Transfers governance authority from an old governance address to a new one for a specified dApp.

Usage: Facilitates secure governance transitions within dApps.

disableDApp

function disableDApp(address control) external;

Description: Disables a dApp's integration within the Atlas Protocol.

Usage: Removes governance signatories and revokes all authorized signatories for a dApp.

getGovFromControl

function getGovFromControl(address control) external view returns (address);

Description: Retrieves the governance address associated with a specified DAppControl contract.

Usage: Verifies the current governance entity linked to a dApp's control contract.

isDAppSignatory

function isDAppSignatory(address control, address signatory) external view returns (bool);

Description: Checks whether a specified address is an authorized signatory for a given DAppControl contract.

Usage: Verifies signatory roles for access control and security.

signatories

function signatories(bytes32 key) external view returns (bool);

Description: Checks whether a specific signatory is active for a given dApp by evaluating the provided key.

Usage: Utilizes hashed keys to securely track active signatories.

dAppSignatories

function dAppSignatories(address control) external view returns (address[] memory);

Description: Retrieves the list of all approved signatories for a specified DAppControl contract.

Usage: Enumerates all authorized signatories for comprehensive access control management.

Usage Notes

• Governance Management: Provides robust functions for initializing, updating, and revoking dApp governance and signatories.
• Security Enforcement: Ensures that only authorized governance entities can manage signatories, preventing unauthorized access or modifications.

Conclusion

The AtlasVerification contract is an integral part of the Atlas Protocol, ensuring the security and integrity of metacall transactions through rigorous validation and verification mechanisms. By leveraging EIP712 for structured data hashing, integrating with NonceManager for nonce validations, and interfacing with DAppIntegration for dApp governance management, it provides a comprehensive framework for secure and reliable protocol operations. The contract's external functions facilitate the verification of user, solver, and dApp operations, preventing unauthorized actions and maintaining the protocol's robustness against potential security threats.

Key features include:

• EIP712-compliant signature verification for all operation types
• Comprehensive validation of metacall components, including configurations, nonces, and gas parameters
• Flexible support for both sequential and non-sequential nonce systems
• Integration with dApp governance and signatory management
• Efficient payload generation for various operation types