// SPDX-License-Identifier: MIT

pragma solidity 0.8.29;

// Messaging
import {IRegistry} from "../aztec-interfaces/IRegistry.sol";
import {IInbox} from "../aztec-interfaces/messagebridge/IInbox.sol";
import {IOutbox} from "../aztec-interfaces/messagebridge/IOutbox.sol";
import {IRollup} from "../aztec-interfaces/IRollup.sol";
import {DataStructures} from "../aztec-interfaces/CoreDataStructures.sol";
import {ILocalRootProvider, IGigaRootRecipient} from  "../interfaces/IRootMessengers.sol";
// hash for message passing to L2
import {Hash} from "../aztec-interfaces/crypto/Hash.sol";
import {IL1BridgeAdapter} from "../interfaces/IL1BridgeAdapter.sol";

contract L1AztecBridgeAdapter is IL1BridgeAdapter, ILocalRootProvider, IGigaRootRecipient {
    event NewGigaRootSentToAztec(bytes32 indexed newGigaRoot, bytes32 key, uint256 index); //newGigaRoot is also the content hash! wow!'
    
    modifier onlyGigaBridge() {
        require(msg.sender == gigaBridge, "Not gigaBridge");
        _; // what is that?
    }

    modifier onlyDeployer() {
        require(msg.sender == deployer, "Not the deployer");
        _; // what is that?
    }
    // IRegistry public registry; not used
    bytes32 public l2AztecBridgeAdapter;
    // most recent warp toad state root from the L2
    uint256 public mostRecentL2Root;
    // the L2 block that the most recent L2 root came from
    uint256 public mostRecentL2RootBlockNumber;

    IRollup public rollup;
    IOutbox public outbox;
    IInbox public inbox;
    uint256 public rollupVersion;

    address public gigaBridge;

    address deployer;

    bool isInitialized = false;
    constructor() {
        deployer = msg.sender;
    }
    /**
     * @notice Initialize the portal
     * @param _registry - The registry address
     * @param _l2AztecBridgeAdapter - The L2 bridge address
     */
    function initialize(
        address _registry,
        bytes32 _l2AztecBridgeAdapter,
        address _gigaRootBridge
    ) external onlyDeployer() {
        require(isInitialized == false, "cant initialize twice");
        isInitialized = true;

        l2AztecBridgeAdapter = _l2AztecBridgeAdapter;

        rollup = IRollup(IRegistry(_registry).getCanonicalRollup());
        outbox = rollup.getOutbox();
        inbox = rollup.getInbox();
        rollupVersion = rollup.getVersion();

        gigaBridge = _gigaRootBridge;
    }

    /**
     * @notice adds an L2 message which can only be consumed publicly on Aztec
     * @param _newGigaRoot - The new gigaRoot to send to L2 as a message
     */
    function receiveGigaRoot(
        uint256 _newGigaRoot
    ) external payable onlyGigaBridge {
        _bridgeGigaRootToL2(_newGigaRoot);
    }

    function _bridgeGigaRootToL2(uint256 _newGigaRoot) internal {
        // l2AztecBridgeAdapter is the Aztec address of the contract that will be retrieving the
        // message on the L2
        DataStructures.L2Actor memory actor = DataStructures.L2Actor(
            l2AztecBridgeAdapter,
            rollupVersion
        );

        // Aztec docs assume that the message being passed is larger than a Field element
        // so it recommends you hash it and verify the hash on the L2 when retrieving the message.
        // Luckily for us, the GigaRoot is the size of a Field so we don't have to hash it
        // and can directly retrieve it on the L2.
        bytes32 contentHash = bytes32(_newGigaRoot);

        // `secret` is used to make the consumption of a message on the L2 private.
        // we don't care about keeping message consumption private at all so to
        // simplify things we hardcode the secret as 0 in the noir side and hardcode
        // Hash(0) here in the L1
        bytes32 secretHash = 0x001dc7b0244cb71a4609d526300ba6771064bd046848666f7bfe577053d630c5;

        // Send message to rollup
        (bytes32 key, uint256 index) = inbox.sendL2Message(
            actor,
            contentHash,
            secretHash
        );

        // Emit event
        emit NewGigaRootSentToAztec(contentHash, key, index);
    } 

    function getLocalRootAndBlock() view external returns (uint256, uint256) {
        require(
            mostRecentL2Root > 0,
            "An L2 root hasn't yet been bridged to this contract. refreshRoot must be called."
        );
        require(
            mostRecentL2RootBlockNumber > 0,
            "An L2 root hasn't yet been bridged to this contract. refreshRoot must be called."
        );
        return (mostRecentL2Root, mostRecentL2RootBlockNumber);
    }

    /**
     * @notice gets the L2 root from the portal
     * @dev Second part of getting the L2 root to L1, must be initiated from L2 first as it will consume a message from outbox
     * @param _newL2Root - the merkle root currently on the L2 to add into the GigaRoot
     * @param _bridgedL2BlockNumber - the block number that is in the content hash (should exactly match the block _newL2Root is from)
     * @param _witnessL2BlockNumber - the block number where we retrieve the message proof from (should exactly match the block at which the witness (aka _path) is retrieved )
     * @param _leafIndex - The amount to withdraw
     * @param _path - Must match the caller of the message (specified from L2) to consume it.
     */
    function getNewRootFromL2(
        bytes32 _newL2Root,
        uint256 _bridgedL2BlockNumber,
        uint256 _witnessL2BlockNumber,
        uint256 _leafIndex,
        bytes32[] calldata _path
    ) external {
        // this hash should match the hash created on the aztec side of this root bridge
        // adapter
        bytes32 contentHash = getContentHash(_newL2Root, _bridgedL2BlockNumber);

        DataStructures.L2ToL1Msg memory message = DataStructures.L2ToL1Msg({
            sender: DataStructures.L2Actor(l2AztecBridgeAdapter, rollupVersion),
            recipient: DataStructures.L1Actor(address(this), block.chainid),
            content: contentHash
        });

        outbox.consume(message, _witnessL2BlockNumber, _leafIndex, _path);

        // convert from bytes32 to uint256
        uint256 newL2RootCast = uint256(_newL2Root);

        if (mostRecentL2RootBlockNumber <= _bridgedL2BlockNumber ) {
            emit ReceivedNewL2Root(newL2RootCast, _bridgedL2BlockNumber);
            mostRecentL2Root = newL2RootCast;
            mostRecentL2RootBlockNumber = _bridgedL2BlockNumber;
        }
        // TODO put in history
    }

    // hashes _newL2Root and _l2BlockNumber so it's representation can fit inside of a
    // Field element.  This should match how they are hashed in the Aztec side of this bridge
    // adapter
    function getContentHash(
        bytes32 _newL2Root,
        uint256 _bridgedL2BlockNumber
    ) public pure returns (bytes32) {
        return Hash.sha256ToField(abi.encode(_newL2Root, _bridgedL2BlockNumber));
    }
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.4.0) (interfaces/IERC1363.sol)

pragma solidity >=0.6.2;

import {IERC20} from "./IERC20.sol";
import {IERC165} from "./IERC165.sol";

/**
 * @title IERC1363
 * @dev Interface of the ERC-1363 standard as defined in the https://eips.ethereum.org/EIPS/eip-1363[ERC-1363].
 *
 * Defines an extension interface for ERC-20 tokens that supports executing code on a recipient contract
 * after `transfer` or `transferFrom`, or code on a spender contract after `approve`, in a single transaction.
 */
interface IERC1363 is IERC20, IERC165 {
    /*
     * Note: the ERC-165 identifier for this interface is 0xb0202a11.
     * 0xb0202a11 ===
     *   bytes4(keccak256('transferAndCall(address,uint256)')) ^
     *   bytes4(keccak256('transferAndCall(address,uint256,bytes)')) ^
     *   bytes4(keccak256('transferFromAndCall(address,address,uint256)')) ^
     *   bytes4(keccak256('transferFromAndCall(address,address,uint256,bytes)')) ^
     *   bytes4(keccak256('approveAndCall(address,uint256)')) ^
     *   bytes4(keccak256('approveAndCall(address,uint256,bytes)'))
     */

    /**
     * @dev Moves a `value` amount of tokens from the caller's account to `to`
     * and then calls {IERC1363Receiver-onTransferReceived} on `to`.
     * @param to The address which you want to transfer to.
     * @param value The amount of tokens to be transferred.
     * @return A boolean value indicating whether the operation succeeded unless throwing.
     */
    function transferAndCall(address to, uint256 value) external returns (bool);

    /**
     * @dev Moves a `value` amount of tokens from the caller's account to `to`
     * and then calls {IERC1363Receiver-onTransferReceived} on `to`.
     * @param to The address which you want to transfer to.
     * @param value The amount of tokens to be transferred.
     * @param data Additional data with no specified format, sent in call to `to`.
     * @return A boolean value indicating whether the operation succeeded unless throwing.
     */
    function transferAndCall(address to, uint256 value, bytes calldata data) external returns (bool);

    /**
     * @dev Moves a `value` amount of tokens from `from` to `to` using the allowance mechanism
     * and then calls {IERC1363Receiver-onTransferReceived} on `to`.
     * @param from The address which you want to send tokens from.
     * @param to The address which you want to transfer to.
     * @param value The amount of tokens to be transferred.
     * @return A boolean value indicating whether the operation succeeded unless throwing.
     */
    function transferFromAndCall(address from, address to, uint256 value) external returns (bool);

    /**
     * @dev Moves a `value` amount of tokens from `from` to `to` using the allowance mechanism
     * and then calls {IERC1363Receiver-onTransferReceived} on `to`.
     * @param from The address which you want to send tokens from.
     * @param to The address which you want to transfer to.
     * @param value The amount of tokens to be transferred.
     * @param data Additional data with no specified format, sent in call to `to`.
     * @return A boolean value indicating whether the operation succeeded unless throwing.
     */
    function transferFromAndCall(address from, address to, uint256 value, bytes calldata data) external returns (bool);

    /**
     * @dev Sets a `value` amount of tokens as the allowance of `spender` over the
     * caller's tokens and then calls {IERC1363Spender-onApprovalReceived} on `spender`.
     * @param spender The address which will spend the funds.
     * @param value The amount of tokens to be spent.
     * @return A boolean value indicating whether the operation succeeded unless throwing.
     */
    function approveAndCall(address spender, uint256 value) external returns (bool);

    /**
     * @dev Sets a `value` amount of tokens as the allowance of `spender` over the
     * caller's tokens and then calls {IERC1363Spender-onApprovalReceived} on `spender`.
     * @param spender The address which will spend the funds.
     * @param value The amount of tokens to be spent.
     * @param data Additional data with no specified format, sent in call to `spender`.
     * @return A boolean value indicating whether the operation succeeded unless throwing.
     */
    function approveAndCall(address spender, uint256 value, bytes calldata data) external returns (bool);
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.4.0) (interfaces/IERC165.sol)

pragma solidity >=0.4.16;

import {IERC165} from "../utils/introspection/IERC165.sol";

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.4.0) (interfaces/IERC20.sol)

pragma solidity >=0.4.16;

import {IERC20} from "../token/ERC20/IERC20.sol";

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.4.0) (token/ERC20/IERC20.sol)

pragma solidity >=0.4.16;

/**
 * @dev Interface of the ERC-20 standard as defined in the ERC.
 */
interface IERC20 {
    /**
     * @dev Emitted when `value` tokens are moved from one account (`from`) to
     * another (`to`).
     *
     * Note that `value` may be zero.
     */
    event Transfer(address indexed from, address indexed to, uint256 value);

    /**
     * @dev Emitted when the allowance of a `spender` for an `owner` is set by
     * a call to {approve}. `value` is the new allowance.
     */
    event Approval(address indexed owner, address indexed spender, uint256 value);

    /**
     * @dev Returns the value of tokens in existence.
     */
    function totalSupply() external view returns (uint256);

    /**
     * @dev Returns the value of tokens owned by `account`.
     */
    function balanceOf(address account) external view returns (uint256);

    /**
     * @dev Moves a `value` amount of tokens from the caller's account to `to`.
     *
     * Returns a boolean value indicating whether the operation succeeded.
     *
     * Emits a {Transfer} event.
     */
    function transfer(address to, uint256 value) external returns (bool);

    /**
     * @dev Returns the remaining number of tokens that `spender` will be
     * allowed to spend on behalf of `owner` through {transferFrom}. This is
     * zero by default.
     *
     * This value changes when {approve} or {transferFrom} are called.
     */
    function allowance(address owner, address spender) external view returns (uint256);

    /**
     * @dev Sets a `value` amount of tokens as the allowance of `spender` over the
     * caller's tokens.
     *
     * Returns a boolean value indicating whether the operation succeeded.
     *
     * IMPORTANT: Beware that changing an allowance with this method brings the risk
     * that someone may use both the old and the new allowance by unfortunate
     * transaction ordering. One possible solution to mitigate this race
     * condition is to first reduce the spender's allowance to 0 and set the
     * desired value afterwards:
     * https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729
     *
     * Emits an {Approval} event.
     */
    function approve(address spender, uint256 value) external returns (bool);

    /**
     * @dev Moves a `value` amount of tokens from `from` to `to` using the
     * allowance mechanism. `value` is then deducted from the caller's
     * allowance.
     *
     * Returns a boolean value indicating whether the operation succeeded.
     *
     * Emits a {Transfer} event.
     */
    function transferFrom(address from, address to, uint256 value) external returns (bool);
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.3.0) (token/ERC20/utils/SafeERC20.sol)

pragma solidity ^0.8.20;

import {IERC20} from "../IERC20.sol";
import {IERC1363} from "../../../interfaces/IERC1363.sol";

/**
 * @title SafeERC20
 * @dev Wrappers around ERC-20 operations that throw on failure (when the token
 * contract returns false). Tokens that return no value (and instead revert or
 * throw on failure) are also supported, non-reverting calls are assumed to be
 * successful.
 * To use this library you can add a `using SafeERC20 for IERC20;` statement to your contract,
 * which allows you to call the safe operations as `token.safeTransfer(...)`, etc.
 */
library SafeERC20 {
    /**
     * @dev An operation with an ERC-20 token failed.
     */
    error SafeERC20FailedOperation(address token);

    /**
     * @dev Indicates a failed `decreaseAllowance` request.
     */
    error SafeERC20FailedDecreaseAllowance(address spender, uint256 currentAllowance, uint256 requestedDecrease);

    /**
     * @dev Transfer `value` amount of `token` from the calling contract to `to`. If `token` returns no value,
     * non-reverting calls are assumed to be successful.
     */
    function safeTransfer(IERC20 token, address to, uint256 value) internal {
        _callOptionalReturn(token, abi.encodeCall(token.transfer, (to, value)));
    }

    /**
     * @dev Transfer `value` amount of `token` from `from` to `to`, spending the approval given by `from` to the
     * calling contract. If `token` returns no value, non-reverting calls are assumed to be successful.
     */
    function safeTransferFrom(IERC20 token, address from, address to, uint256 value) internal {
        _callOptionalReturn(token, abi.encodeCall(token.transferFrom, (from, to, value)));
    }

    /**
     * @dev Variant of {safeTransfer} that returns a bool instead of reverting if the operation is not successful.
     */
    function trySafeTransfer(IERC20 token, address to, uint256 value) internal returns (bool) {
        return _callOptionalReturnBool(token, abi.encodeCall(token.transfer, (to, value)));
    }

    /**
     * @dev Variant of {safeTransferFrom} that returns a bool instead of reverting if the operation is not successful.
     */
    function trySafeTransferFrom(IERC20 token, address from, address to, uint256 value) internal returns (bool) {
        return _callOptionalReturnBool(token, abi.encodeCall(token.transferFrom, (from, to, value)));
    }

    /**
     * @dev Increase the calling contract's allowance toward `spender` by `value`. If `token` returns no value,
     * non-reverting calls are assumed to be successful.
     *
     * IMPORTANT: If the token implements ERC-7674 (ERC-20 with temporary allowance), and if the "client"
     * smart contract uses ERC-7674 to set temporary allowances, then the "client" smart contract should avoid using
     * this function. Performing a {safeIncreaseAllowance} or {safeDecreaseAllowance} operation on a token contract
     * that has a non-zero temporary allowance (for that particular owner-spender) will result in unexpected behavior.
     */
    function safeIncreaseAllowance(IERC20 token, address spender, uint256 value) internal {
        uint256 oldAllowance = token.allowance(address(this), spender);
        forceApprove(token, spender, oldAllowance + value);
    }

    /**
     * @dev Decrease the calling contract's allowance toward `spender` by `requestedDecrease`. If `token` returns no
     * value, non-reverting calls are assumed to be successful.
     *
     * IMPORTANT: If the token implements ERC-7674 (ERC-20 with temporary allowance), and if the "client"
     * smart contract uses ERC-7674 to set temporary allowances, then the "client" smart contract should avoid using
     * this function. Performing a {safeIncreaseAllowance} or {safeDecreaseAllowance} operation on a token contract
     * that has a non-zero temporary allowance (for that particular owner-spender) will result in unexpected behavior.
     */
    function safeDecreaseAllowance(IERC20 token, address spender, uint256 requestedDecrease) internal {
        unchecked {
            uint256 currentAllowance = token.allowance(address(this), spender);
            if (currentAllowance < requestedDecrease) {
                revert SafeERC20FailedDecreaseAllowance(spender, currentAllowance, requestedDecrease);
            }
            forceApprove(token, spender, currentAllowance - requestedDecrease);
        }
    }

    /**
     * @dev Set the calling contract's allowance toward `spender` to `value`. If `token` returns no value,
     * non-reverting calls are assumed to be successful. Meant to be used with tokens that require the approval
     * to be set to zero before setting it to a non-zero value, such as USDT.
     *
     * NOTE: If the token implements ERC-7674, this function will not modify any temporary allowance. This function
     * only sets the "standard" allowance. Any temporary allowance will remain active, in addition to the value being
     * set here.
     */
    function forceApprove(IERC20 token, address spender, uint256 value) internal {
        bytes memory approvalCall = abi.encodeCall(token.approve, (spender, value));

        if (!_callOptionalReturnBool(token, approvalCall)) {
            _callOptionalReturn(token, abi.encodeCall(token.approve, (spender, 0)));
            _callOptionalReturn(token, approvalCall);
        }
    }

    /**
     * @dev Performs an {ERC1363} transferAndCall, with a fallback to the simple {ERC20} transfer if the target has no
     * code. This can be used to implement an {ERC721}-like safe transfer that rely on {ERC1363} checks when
     * targeting contracts.
     *
     * Reverts if the returned value is other than `true`.
     */
    function transferAndCallRelaxed(IERC1363 token, address to, uint256 value, bytes memory data) internal {
        if (to.code.length == 0) {
            safeTransfer(token, to, value);
        } else if (!token.transferAndCall(to, value, data)) {
            revert SafeERC20FailedOperation(address(token));
        }
    }

    /**
     * @dev Performs an {ERC1363} transferFromAndCall, with a fallback to the simple {ERC20} transferFrom if the target
     * has no code. This can be used to implement an {ERC721}-like safe transfer that rely on {ERC1363} checks when
     * targeting contracts.
     *
     * Reverts if the returned value is other than `true`.
     */
    function transferFromAndCallRelaxed(
        IERC1363 token,
        address from,
        address to,
        uint256 value,
        bytes memory data
    ) internal {
        if (to.code.length == 0) {
            safeTransferFrom(token, from, to, value);
        } else if (!token.transferFromAndCall(from, to, value, data)) {
            revert SafeERC20FailedOperation(address(token));
        }
    }

    /**
     * @dev Performs an {ERC1363} approveAndCall, with a fallback to the simple {ERC20} approve if the target has no
     * code. This can be used to implement an {ERC721}-like safe transfer that rely on {ERC1363} checks when
     * targeting contracts.
     *
     * NOTE: When the recipient address (`to`) has no code (i.e. is an EOA), this function behaves as {forceApprove}.
     * Opposedly, when the recipient address (`to`) has code, this function only attempts to call {ERC1363-approveAndCall}
     * once without retrying, and relies on the returned value to be true.
     *
     * Reverts if the returned value is other than `true`.
     */
    function approveAndCallRelaxed(IERC1363 token, address to, uint256 value, bytes memory data) internal {
        if (to.code.length == 0) {
            forceApprove(token, to, value);
        } else if (!token.approveAndCall(to, value, data)) {
            revert SafeERC20FailedOperation(address(token));
        }
    }

    /**
     * @dev Imitates a Solidity high-level call (i.e. a regular function call to a contract), relaxing the requirement
     * on the return value: the return value is optional (but if data is returned, it must not be false).
     * @param token The token targeted by the call.
     * @param data The call data (encoded using abi.encode or one of its variants).
     *
     * This is a variant of {_callOptionalReturnBool} that reverts if call fails to meet the requirements.
     */
    function _callOptionalReturn(IERC20 token, bytes memory data) private {
        uint256 returnSize;
        uint256 returnValue;
        assembly ("memory-safe") {
            let success := call(gas(), token, 0, add(data, 0x20), mload(data), 0, 0x20)
            // bubble errors
            if iszero(success) {
                let ptr := mload(0x40)
                returndatacopy(ptr, 0, returndatasize())
                revert(ptr, returndatasize())
            }
            returnSize := returndatasize()
            returnValue := mload(0)
        }

        if (returnSize == 0 ? address(token).code.length == 0 : returnValue != 1) {
            revert SafeERC20FailedOperation(address(token));
        }
    }

    /**
     * @dev Imitates a Solidity high-level call (i.e. a regular function call to a contract), relaxing the requirement
     * on the return value: the return value is optional (but if data is returned, it must not be false).
     * @param token The token targeted by the call.
     * @param data The call data (encoded using abi.encode or one of its variants).
     *
     * This is a variant of {_callOptionalReturn} that silently catches all reverts and returns a bool instead.
     */
    function _callOptionalReturnBool(IERC20 token, bytes memory data) private returns (bool) {
        bool success;
        uint256 returnSize;
        uint256 returnValue;
        assembly ("memory-safe") {
            success := call(gas(), token, 0, add(data, 0x20), mload(data), 0, 0x20)
            returnSize := returndatasize()
            returnValue := mload(0)
        }
        return success && (returnSize == 0 ? address(token).code.length > 0 : returnValue == 1);
    }
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.4.0) (utils/Arrays.sol)
// This file was procedurally generated from scripts/generate/templates/Arrays.js.

pragma solidity ^0.8.20;

import {Comparators} from "./Comparators.sol";
import {SlotDerivation} from "./SlotDerivation.sol";
import {StorageSlot} from "./StorageSlot.sol";
import {Math} from "./math/Math.sol";

/**
 * @dev Collection of functions related to array types.
 */
library Arrays {
    using SlotDerivation for bytes32;
    using StorageSlot for bytes32;

    /**
     * @dev Sort an array of uint256 (in memory) following the provided comparator function.
     *
     * This function does the sorting "in place", meaning that it overrides the input. The object is returned for
     * convenience, but that returned value can be discarded safely if the caller has a memory pointer to the array.
     *
     * NOTE: this function's cost is `O(n · log(n))` in average and `O(n²)` in the worst case, with n the length of the
     * array. Using it in view functions that are executed through `eth_call` is safe, but one should be very careful
     * when executing this as part of a transaction. If the array being sorted is too large, the sort operation may
     * consume more gas than is available in a block, leading to potential DoS.
     *
     * IMPORTANT: Consider memory side-effects when using custom comparator functions that access memory in an unsafe way.
     */
    function sort(
        uint256[] memory array,
        function(uint256, uint256) pure returns (bool) comp
    ) internal pure returns (uint256[] memory) {
        _quickSort(_begin(array), _end(array), comp);
        return array;
    }

    /**
     * @dev Variant of {sort} that sorts an array of uint256 in increasing order.
     */
    function sort(uint256[] memory array) internal pure returns (uint256[] memory) {
        sort(array, Comparators.lt);
        return array;
    }

    /**
     * @dev Sort an array of address (in memory) following the provided comparator function.
     *
     * This function does the sorting "in place", meaning that it overrides the input. The object is returned for
     * convenience, but that returned value can be discarded safely if the caller has a memory pointer to the array.
     *
     * NOTE: this function's cost is `O(n · log(n))` in average and `O(n²)` in the worst case, with n the length of the
     * array. Using it in view functions that are executed through `eth_call` is safe, but one should be very careful
     * when executing this as part of a transaction. If the array being sorted is too large, the sort operation may
     * consume more gas than is available in a block, leading to potential DoS.
     *
     * IMPORTANT: Consider memory side-effects when using custom comparator functions that access memory in an unsafe way.
     */
    function sort(
        address[] memory array,
        function(address, address) pure returns (bool) comp
    ) internal pure returns (address[] memory) {
        sort(_castToUint256Array(array), _castToUint256Comp(comp));
        return array;
    }

    /**
     * @dev Variant of {sort} that sorts an array of address in increasing order.
     */
    function sort(address[] memory array) internal pure returns (address[] memory) {
        sort(_castToUint256Array(array), Comparators.lt);
        return array;
    }

    /**
     * @dev Sort an array of bytes32 (in memory) following the provided comparator function.
     *
     * This function does the sorting "in place", meaning that it overrides the input. The object is returned for
     * convenience, but that returned value can be discarded safely if the caller has a memory pointer to the array.
     *
     * NOTE: this function's cost is `O(n · log(n))` in average and `O(n²)` in the worst case, with n the length of the
     * array. Using it in view functions that are executed through `eth_call` is safe, but one should be very careful
     * when executing this as part of a transaction. If the array being sorted is too large, the sort operation may
     * consume more gas than is available in a block, leading to potential DoS.
     *
     * IMPORTANT: Consider memory side-effects when using custom comparator functions that access memory in an unsafe way.
     */
    function sort(
        bytes32[] memory array,
        function(bytes32, bytes32) pure returns (bool) comp
    ) internal pure returns (bytes32[] memory) {
        sort(_castToUint256Array(array), _castToUint256Comp(comp));
        return array;
    }

    /**
     * @dev Variant of {sort} that sorts an array of bytes32 in increasing order.
     */
    function sort(bytes32[] memory array) internal pure returns (bytes32[] memory) {
        sort(_castToUint256Array(array), Comparators.lt);
        return array;
    }

    /**
     * @dev Performs a quick sort of a segment of memory. The segment sorted starts at `begin` (inclusive), and stops
     * at end (exclusive). Sorting follows the `comp` comparator.
     *
     * Invariant: `begin <= end`. This is the case when initially called by {sort} and is preserved in subcalls.
     *
     * IMPORTANT: Memory locations between `begin` and `end` are not validated/zeroed. This function should
     * be used only if the limits are within a memory array.
     */
    function _quickSort(uint256 begin, uint256 end, function(uint256, uint256) pure returns (bool) comp) private pure {
        unchecked {
            if (end - begin < 0x40) return;

            // Use first element as pivot
            uint256 pivot = _mload(begin);
            // Position where the pivot should be at the end of the loop
            uint256 pos = begin;

            for (uint256 it = begin + 0x20; it < end; it += 0x20) {
                if (comp(_mload(it), pivot)) {
                    // If the value stored at the iterator's position comes before the pivot, we increment the
                    // position of the pivot and move the value there.
                    pos += 0x20;
                    _swap(pos, it);
                }
            }

            _swap(begin, pos); // Swap pivot into place
            _quickSort(begin, pos, comp); // Sort the left side of the pivot
            _quickSort(pos + 0x20, end, comp); // Sort the right side of the pivot
        }
    }

    /**
     * @dev Pointer to the memory location of the first element of `array`.
     */
    function _begin(uint256[] memory array) private pure returns (uint256 ptr) {
        assembly ("memory-safe") {
            ptr := add(array, 0x20)
        }
    }

    /**
     * @dev Pointer to the memory location of the first memory word (32bytes) after `array`. This is the memory word
     * that comes just after the last element of the array.
     */
    function _end(uint256[] memory array) private pure returns (uint256 ptr) {
        unchecked {
            return _begin(array) + array.length * 0x20;
        }
    }

    /**
     * @dev Load memory word (as a uint256) at location `ptr`.
     */
    function _mload(uint256 ptr) private pure returns (uint256 value) {
        assembly {
            value := mload(ptr)
        }
    }

    /**
     * @dev Swaps the elements memory location `ptr1` and `ptr2`.
     */
    function _swap(uint256 ptr1, uint256 ptr2) private pure {
        assembly {
            let value1 := mload(ptr1)
            let value2 := mload(ptr2)
            mstore(ptr1, value2)
            mstore(ptr2, value1)
        }
    }

    /// @dev Helper: low level cast address memory array to uint256 memory array
    function _castToUint256Array(address[] memory input) private pure returns (uint256[] memory output) {
        assembly {
            output := input
        }
    }

    /// @dev Helper: low level cast bytes32 memory array to uint256 memory array
    function _castToUint256Array(bytes32[] memory input) private pure returns (uint256[] memory output) {
        assembly {
            output := input
        }
    }

    /// @dev Helper: low level cast address comp function to uint256 comp function
    function _castToUint256Comp(
        function(address, address) pure returns (bool) input
    ) private pure returns (function(uint256, uint256) pure returns (bool) output) {
        assembly {
            output := input
        }
    }

    /// @dev Helper: low level cast bytes32 comp function to uint256 comp function
    function _castToUint256Comp(
        function(bytes32, bytes32) pure returns (bool) input
    ) private pure returns (function(uint256, uint256) pure returns (bool) output) {
        assembly {
            output := input
        }
    }

    /**
     * @dev Searches a sorted `array` and returns the first index that contains
     * a value greater or equal to `element`. If no such index exists (i.e. all
     * values in the array are strictly less than `element`), the array length is
     * returned. Time complexity O(log n).
     *
     * NOTE: The `array` is expected to be sorted in ascending order, and to
     * contain no repeated elements.
     *
     * IMPORTANT: Deprecated. This implementation behaves as {lowerBound} but lacks
     * support for repeated elements in the array. The {lowerBound} function should
     * be used instead.
     */
    function findUpperBound(uint256[] storage array, uint256 element) internal view returns (uint256) {
        uint256 low = 0;
        uint256 high = array.length;

        if (high == 0) {
            return 0;
        }

        while (low < high) {
            uint256 mid = Math.average(low, high);

            // Note that mid will always be strictly less than high (i.e. it will be a valid array index)
            // because Math.average rounds towards zero (it does integer division with truncation).
            if (unsafeAccess(array, mid).value > element) {
                high = mid;
            } else {
                low = mid + 1;
            }
        }

        // At this point `low` is the exclusive upper bound. We will return the inclusive upper bound.
        if (low > 0 && unsafeAccess(array, low - 1).value == element) {
            return low - 1;
        } else {
            return low;
        }
    }

    /**
     * @dev Searches an `array` sorted in ascending order and returns the first
     * index that contains a value greater or equal than `element`. If no such index
     * exists (i.e. all values in the array are strictly less than `element`), the array
     * length is returned. Time complexity O(log n).
     *
     * See C++'s https://en.cppreference.com/w/cpp/algorithm/lower_bound[lower_bound].
     */
    function lowerBound(uint256[] storage array, uint256 element) internal view returns (uint256) {
        uint256 low = 0;
        uint256 high = array.length;

        if (high == 0) {
            return 0;
        }

        while (low < high) {
            uint256 mid = Math.average(low, high);

            // Note that mid will always be strictly less than high (i.e. it will be a valid array index)
            // because Math.average rounds towards zero (it does integer division with truncation).
            if (unsafeAccess(array, mid).value < element) {
                // this cannot overflow because mid < high
                unchecked {
                    low = mid + 1;
                }
            } else {
                high = mid;
            }
        }

        return low;
    }

    /**
     * @dev Searches an `array` sorted in ascending order and returns the first
     * index that contains a value strictly greater than `element`. If no such index
     * exists (i.e. all values in the array are strictly less than `element`), the array
     * length is returned. Time complexity O(log n).
     *
     * See C++'s https://en.cppreference.com/w/cpp/algorithm/upper_bound[upper_bound].
     */
    function upperBound(uint256[] storage array, uint256 element) internal view returns (uint256) {
        uint256 low = 0;
        uint256 high = array.length;

        if (high == 0) {
            return 0;
        }

        while (low < high) {
            uint256 mid = Math.average(low, high);

            // Note that mid will always be strictly less than high (i.e. it will be a valid array index)
            // because Math.average rounds towards zero (it does integer division with truncation).
            if (unsafeAccess(array, mid).value > element) {
                high = mid;
            } else {
                // this cannot overflow because mid < high
                unchecked {
                    low = mid + 1;
                }
            }
        }

        return low;
    }

    /**
     * @dev Same as {lowerBound}, but with an array in memory.
     */
    function lowerBoundMemory(uint256[] memory array, uint256 element) internal pure returns (uint256) {
        uint256 low = 0;
        uint256 high = array.length;

        if (high == 0) {
            return 0;
        }

        while (low < high) {
            uint256 mid = Math.average(low, high);

            // Note that mid will always be strictly less than high (i.e. it will be a valid array index)
            // because Math.average rounds towards zero (it does integer division with truncation).
            if (unsafeMemoryAccess(array, mid) < element) {
                // this cannot overflow because mid < high
                unchecked {
                    low = mid + 1;
                }
            } else {
                high = mid;
            }
        }

        return low;
    }

    /**
     * @dev Same as {upperBound}, but with an array in memory.
     */
    function upperBoundMemory(uint256[] memory array, uint256 element) internal pure returns (uint256) {
        uint256 low = 0;
        uint256 high = array.length;

        if (high == 0) {
            return 0;
        }

        while (low < high) {
            uint256 mid = Math.average(low, high);

            // Note that mid will always be strictly less than high (i.e. it will be a valid array index)
            // because Math.average rounds towards zero (it does integer division with truncation).
            if (unsafeMemoryAccess(array, mid) > element) {
                high = mid;
            } else {
                // this cannot overflow because mid < high
                unchecked {
                    low = mid + 1;
                }
            }
        }

        return low;
    }

    /**
     * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check.
     *
     * WARNING: Only use if you are certain `pos` is lower than the array length.
     */
    function unsafeAccess(address[] storage arr, uint256 pos) internal pure returns (StorageSlot.AddressSlot storage) {
        bytes32 slot;
        assembly ("memory-safe") {
            slot := arr.slot
        }
        return slot.deriveArray().offset(pos).getAddressSlot();
    }

    /**
     * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check.
     *
     * WARNING: Only use if you are certain `pos` is lower than the array length.
     */
    function unsafeAccess(bytes32[] storage arr, uint256 pos) internal pure returns (StorageSlot.Bytes32Slot storage) {
        bytes32 slot;
        assembly ("memory-safe") {
            slot := arr.slot
        }
        return slot.deriveArray().offset(pos).getBytes32Slot();
    }

    /**
     * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check.
     *
     * WARNING: Only use if you are certain `pos` is lower than the array length.
     */
    function unsafeAccess(uint256[] storage arr, uint256 pos) internal pure returns (StorageSlot.Uint256Slot storage) {
        bytes32 slot;
        assembly ("memory-safe") {
            slot := arr.slot
        }
        return slot.deriveArray().offset(pos).getUint256Slot();
    }

    /**
     * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check.
     *
     * WARNING: Only use if you are certain `pos` is lower than the array length.
     */
    function unsafeAccess(bytes[] storage arr, uint256 pos) internal pure returns (StorageSlot.BytesSlot storage) {
        bytes32 slot;
        assembly ("memory-safe") {
            slot := arr.slot
        }
        return slot.deriveArray().offset(pos).getBytesSlot();
    }

    /**
     * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check.
     *
     * WARNING: Only use if you are certain `pos` is lower than the array length.
     */
    function unsafeAccess(string[] storage arr, uint256 pos) internal pure returns (StorageSlot.StringSlot storage) {
        bytes32 slot;
        assembly ("memory-safe") {
            slot := arr.slot
        }
        return slot.deriveArray().offset(pos).getStringSlot();
    }

    /**
     * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check.
     *
     * WARNING: Only use if you are certain `pos` is lower than the array length.
     */
    function unsafeMemoryAccess(address[] memory arr, uint256 pos) internal pure returns (address res) {
        assembly {
            res := mload(add(add(arr, 0x20), mul(pos, 0x20)))
        }
    }

    /**
     * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check.
     *
     * WARNING: Only use if you are certain `pos` is lower than the array length.
     */
    function unsafeMemoryAccess(bytes32[] memory arr, uint256 pos) internal pure returns (bytes32 res) {
        assembly {
            res := mload(add(add(arr, 0x20), mul(pos, 0x20)))
        }
    }

    /**
     * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check.
     *
     * WARNING: Only use if you are certain `pos` is lower than the array length.
     */
    function unsafeMemoryAccess(uint256[] memory arr, uint256 pos) internal pure returns (uint256 res) {
        assembly {
            res := mload(add(add(arr, 0x20), mul(pos, 0x20)))
        }
    }

    /**
     * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check.
     *
     * WARNING: Only use if you are certain `pos` is lower than the array length.
     */
    function unsafeMemoryAccess(bytes[] memory arr, uint256 pos) internal pure returns (bytes memory res) {
        assembly {
            res := mload(add(add(arr, 0x20), mul(pos, 0x20)))
        }
    }

    /**
     * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check.
     *
     * WARNING: Only use if you are certain `pos` is lower than the array length.
     */
    function unsafeMemoryAccess(string[] memory arr, uint256 pos) internal pure returns (string memory res) {
        assembly {
            res := mload(add(add(arr, 0x20), mul(pos, 0x20)))
        }
    }

    /**
     * @dev Helper to set the length of a dynamic array. Directly writing to `.length` is forbidden.
     *
     * WARNING: this does not clear elements if length is reduced, of initialize elements if length is increased.
     */
    function unsafeSetLength(address[] storage array, uint256 len) internal {
        assembly ("memory-safe") {
            sstore(array.slot, len)
        }
    }

    /**
     * @dev Helper to set the length of a dynamic array. Directly writing to `.length` is forbidden.
     *
     * WARNING: this does not clear elements if length is reduced, of initialize elements if length is increased.
     */
    function unsafeSetLength(bytes32[] storage array, uint256 len) internal {
        assembly ("memory-safe") {
            sstore(array.slot, len)
        }
    }

    /**
     * @dev Helper to set the length of a dynamic array. Directly writing to `.length` is forbidden.
     *
     * WARNING: this does not clear elements if length is reduced, of initialize elements if length is increased.
     */
    function unsafeSetLength(uint256[] storage array, uint256 len) internal {
        assembly ("memory-safe") {
            sstore(array.slot, len)
        }
    }

    /**
     * @dev Helper to set the length of a dynamic array. Directly writing to `.length` is forbidden.
     *
     * WARNING: this does not clear elements if length is reduced, of initialize elements if length is increased.
     */
    function unsafeSetLength(bytes[] storage array, uint256 len) internal {
        assembly ("memory-safe") {
            sstore(array.slot, len)
        }
    }

    /**
     * @dev Helper to set the length of a dynamic array. Directly writing to `.length` is forbidden.
     *
     * WARNING: this does not clear elements if length is reduced, of initialize elements if length is increased.
     */
    function unsafeSetLength(string[] storage array, uint256 len) internal {
        assembly ("memory-safe") {
            sstore(array.slot, len)
        }
    }
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.1.0) (utils/Comparators.sol)

pragma solidity ^0.8.20;

/**
 * @dev Provides a set of functions to compare values.
 *
 * _Available since v5.1._
 */
library Comparators {
    function lt(uint256 a, uint256 b) internal pure returns (bool) {
        return a < b;
    }

    function gt(uint256 a, uint256 b) internal pure returns (bool) {
        return a > b;
    }
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.3.0) (utils/cryptography/MessageHashUtils.sol)

pragma solidity ^0.8.20;

import {Strings} from "../Strings.sol";

/**
 * @dev Signature message hash utilities for producing digests to be consumed by {ECDSA} recovery or signing.
 *
 * The library provides methods for generating a hash of a message that conforms to the
 * https://eips.ethereum.org/EIPS/eip-191[ERC-191] and https://eips.ethereum.org/EIPS/eip-712[EIP 712]
 * specifications.
 */
library MessageHashUtils {
    /**
     * @dev Returns the keccak256 digest of an ERC-191 signed data with version
     * `0x45` (`personal_sign` messages).
     *
     * The digest is calculated by prefixing a bytes32 `messageHash` with
     * `"\x19Ethereum Signed Message:\n32"` and hashing the result. It corresponds with the
     * hash signed when using the https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_sign[`eth_sign`] JSON-RPC method.
     *
     * NOTE: The `messageHash` parameter is intended to be the result of hashing a raw message with
     * keccak256, although any bytes32 value can be safely used because the final digest will
     * be re-hashed.
     *
     * See {ECDSA-recover}.
     */
    function toEthSignedMessageHash(bytes32 messageHash) internal pure returns (bytes32 digest) {
        assembly ("memory-safe") {
            mstore(0x00, "\x19Ethereum Signed Message:\n32") // 32 is the bytes-length of messageHash
            mstore(0x1c, messageHash) // 0x1c (28) is the length of the prefix
            digest := keccak256(0x00, 0x3c) // 0x3c is the length of the prefix (0x1c) + messageHash (0x20)
        }
    }

    /**
     * @dev Returns the keccak256 digest of an ERC-191 signed data with version
     * `0x45` (`personal_sign` messages).
     *
     * The digest is calculated by prefixing an arbitrary `message` with
     * `"\x19Ethereum Signed Message:\n" + len(message)` and hashing the result. It corresponds with the
     * hash signed when using the https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_sign[`eth_sign`] JSON-RPC method.
     *
     * See {ECDSA-recover}.
     */
    function toEthSignedMessageHash(bytes memory message) internal pure returns (bytes32) {
        return
            keccak256(bytes.concat("\x19Ethereum Signed Message:\n", bytes(Strings.toString(message.length)), message));
    }

    /**
     * @dev Returns the keccak256 digest of an ERC-191 signed data with version
     * `0x00` (data with intended validator).
     *
     * The digest is calculated by prefixing an arbitrary `data` with `"\x19\x00"` and the intended
     * `validator` address. Then hashing the result.
     *
     * See {ECDSA-recover}.
     */
    function toDataWithIntendedValidatorHash(address validator, bytes memory data) internal pure returns (bytes32) {
        return keccak256(abi.encodePacked(hex"19_00", validator, data));
    }

    /**
     * @dev Variant of {toDataWithIntendedValidatorHash-address-bytes} optimized for cases where `data` is a bytes32.
     */
    function toDataWithIntendedValidatorHash(
        address validator,
        bytes32 messageHash
    ) internal pure returns (bytes32 digest) {
        assembly ("memory-safe") {
            mstore(0x00, hex"19_00")
            mstore(0x02, shl(96, validator))
            mstore(0x16, messageHash)
            digest := keccak256(0x00, 0x36)
        }
    }

    /**
     * @dev Returns the keccak256 digest of an EIP-712 typed data (ERC-191 version `0x01`).
     *
     * The digest is calculated from a `domainSeparator` and a `structHash`, by prefixing them with
     * `\x19\x01` and hashing the result. It corresponds to the hash signed by the
     * https://eips.ethereum.org/EIPS/eip-712[`eth_signTypedData`] JSON-RPC method as part of EIP-712.
     *
     * See {ECDSA-recover}.
     */
    function toTypedDataHash(bytes32 domainSeparator, bytes32 structHash) internal pure returns (bytes32 digest) {
        assembly ("memory-safe") {
            let ptr := mload(0x40)
            mstore(ptr, hex"19_01")
            mstore(add(ptr, 0x02), domainSeparator)
            mstore(add(ptr, 0x22), structHash)
            digest := keccak256(ptr, 0x42)
        }
    }
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.4.0) (utils/introspection/IERC165.sol)

pragma solidity >=0.4.16;

/**
 * @dev Interface of the ERC-165 standard, as defined in the
 * https://eips.ethereum.org/EIPS/eip-165[ERC].
 *
 * Implementers can declare support of contract interfaces, which can then be
 * queried by others ({ERC165Checker}).
 *
 * For an implementation, see {ERC165}.
 */
interface IERC165 {
    /**
     * @dev Returns true if this contract implements the interface defined by
     * `interfaceId`. See the corresponding
     * https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[ERC section]
     * to learn more about how these ids are created.
     *
     * This function call must use less than 30 000 gas.
     */
    function supportsInterface(bytes4 interfaceId) external view returns (bool);
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.3.0) (utils/math/Math.sol)

pragma solidity ^0.8.20;

import {Panic} from "../Panic.sol";
import {SafeCast} from "./SafeCast.sol";

/**
 * @dev Standard math utilities missing in the Solidity language.
 */
library Math {
    enum Rounding {
        Floor, // Toward negative infinity
        Ceil, // Toward positive infinity
        Trunc, // Toward zero
        Expand // Away from zero
    }

    /**
     * @dev Return the 512-bit addition of two uint256.
     *
     * The result is stored in two 256 variables such that sum = high * 2²⁵⁶ + low.
     */
    function add512(uint256 a, uint256 b) internal pure returns (uint256 high, uint256 low) {
        assembly ("memory-safe") {
            low := add(a, b)
            high := lt(low, a)
        }
    }

    /**
     * @dev Return the 512-bit multiplication of two uint256.
     *
     * The result is stored in two 256 variables such that product = high * 2²⁵⁶ + low.
     */
    function mul512(uint256 a, uint256 b) internal pure returns (uint256 high, uint256 low) {
        // 512-bit multiply [high low] = x * y. Compute the product mod 2²⁵⁶ and mod 2²⁵⁶ - 1, then use
        // the Chinese Remainder Theorem to reconstruct the 512 bit result. The result is stored in two 256
        // variables such that product = high * 2²⁵⁶ + low.
        assembly ("memory-safe") {
            let mm := mulmod(a, b, not(0))
            low := mul(a, b)
            high := sub(sub(mm, low), lt(mm, low))
        }
    }

    /**
     * @dev Returns the addition of two unsigned integers, with a success flag (no overflow).
     */
    function tryAdd(uint256 a, uint256 b) internal pure returns (bool success, uint256 result) {
        unchecked {
            uint256 c = a + b;
            success = c >= a;
            result = c * SafeCast.toUint(success);
        }
    }

    /**
     * @dev Returns the subtraction of two unsigned integers, with a success flag (no overflow).
     */
    function trySub(uint256 a, uint256 b) internal pure returns (bool success, uint256 result) {
        unchecked {
            uint256 c = a - b;
            success = c <= a;
            result = c * SafeCast.toUint(success);
        }
    }

    /**
     * @dev Returns the multiplication of two unsigned integers, with a success flag (no overflow).
     */
    function tryMul(uint256 a, uint256 b) internal pure returns (bool success, uint256 result) {
        unchecked {
            uint256 c = a * b;
            assembly ("memory-safe") {
                // Only true when the multiplication doesn't overflow
                // (c / a == b) || (a == 0)
                success := or(eq(div(c, a), b), iszero(a))
            }
            // equivalent to: success ? c : 0
            result = c * SafeCast.toUint(success);
        }
    }

    /**
     * @dev Returns the division of two unsigned integers, with a success flag (no division by zero).
     */
    function tryDiv(uint256 a, uint256 b) internal pure returns (bool success, uint256 result) {
        unchecked {
            success = b > 0;
            assembly ("memory-safe") {
                // The `DIV` opcode returns zero when the denominator is 0.
                result := div(a, b)
            }
        }
    }

    /**
     * @dev Returns the remainder of dividing two unsigned integers, with a success flag (no division by zero).
     */
    function tryMod(uint256 a, uint256 b) internal pure returns (bool success, uint256 result) {
        unchecked {
            success = b > 0;
            assembly ("memory-safe") {
                // The `MOD` opcode returns zero when the denominator is 0.
                result := mod(a, b)
            }
        }
    }

    /**
     * @dev Unsigned saturating addition, bounds to `2²⁵⁶ - 1` instead of overflowing.
     */
    function saturatingAdd(uint256 a, uint256 b) internal pure returns (uint256) {
        (bool success, uint256 result) = tryAdd(a, b);
        return ternary(success, result, type(uint256).max);
    }

    /**
     * @dev Unsigned saturating subtraction, bounds to zero instead of overflowing.
     */
    function saturatingSub(uint256 a, uint256 b) internal pure returns (uint256) {
        (, uint256 result) = trySub(a, b);
        return result;
    }

    /**
     * @dev Unsigned saturating multiplication, bounds to `2²⁵⁶ - 1` instead of overflowing.
     */
    function saturatingMul(uint256 a, uint256 b) internal pure returns (uint256) {
        (bool success, uint256 result) = tryMul(a, b);
        return ternary(success, result, type(uint256).max);
    }

    /**
     * @dev Branchless ternary evaluation for `a ? b : c`. Gas costs are constant.
     *
     * IMPORTANT: This function may reduce bytecode size and consume less gas when used standalone.
     * However, the compiler may optimize Solidity ternary operations (i.e. `a ? b : c`) to only compute
     * one branch when needed, making this function more expensive.
     */
    function ternary(bool condition, uint256 a, uint256 b) internal pure returns (uint256) {
        unchecked {
            // branchless ternary works because:
            // b ^ (a ^ b) == a
            // b ^ 0 == b
            return b ^ ((a ^ b) * SafeCast.toUint(condition));
        }
    }

    /**
     * @dev Returns the largest of two numbers.
     */
    function max(uint256 a, uint256 b) internal pure returns (uint256) {
        return ternary(a > b, a, b);
    }

    /**
     * @dev Returns the smallest of two numbers.
     */
    function min(uint256 a, uint256 b) internal pure returns (uint256) {
        return ternary(a < b, a, b);
    }

    /**
     * @dev Returns the average of two numbers. The result is rounded towards
     * zero.
     */
    function average(uint256 a, uint256 b) internal pure returns (uint256) {
        // (a + b) / 2 can overflow.
        return (a & b) + (a ^ b) / 2;
    }

    /**
     * @dev Returns the ceiling of the division of two numbers.
     *
     * This differs from standard division with `/` in that it rounds towards infinity instead
     * of rounding towards zero.
     */
    function ceilDiv(uint256 a, uint256 b) internal pure returns (uint256) {
        if (b == 0) {
            // Guarantee the same behavior as in a regular Solidity division.
            Panic.panic(Panic.DIVISION_BY_ZERO);
        }

        // The following calculation ensures accurate ceiling division without overflow.
        // Since a is non-zero, (a - 1) / b will not overflow.
        // The largest possible result occurs when (a - 1) / b is type(uint256).max,
        // but the largest value we can obtain is type(uint256).max - 1, which happens
        // when a = type(uint256).max and b = 1.
        unchecked {
            return SafeCast.toUint(a > 0) * ((a - 1) / b + 1);
        }
    }

    /**
     * @dev Calculates floor(x * y / denominator) with full precision. Throws if result overflows a uint256 or
     * denominator == 0.
     *
     * Original credit to Remco Bloemen under MIT license (https://xn--2-umb.com/21/muldiv) with further edits by
     * Uniswap Labs also under MIT license.
     */
    function mulDiv(uint256 x, uint256 y, uint256 denominator) internal pure returns (uint256 result) {
        unchecked {
            (uint256 high, uint256 low) = mul512(x, y);

            // Handle non-overflow cases, 256 by 256 division.
            if (high == 0) {
                // Solidity will revert if denominator == 0, unlike the div opcode on its own.
                // The surrounding unchecked block does not change this fact.
                // See https://docs.soliditylang.org/en/latest/control-structures.html#checked-or-unchecked-arithmetic.
                return low / denominator;
            }

            // Make sure the result is less than 2²⁵⁶. Also prevents denominator == 0.
            if (denominator <= high) {
                Panic.panic(ternary(denominator == 0, Panic.DIVISION_BY_ZERO, Panic.UNDER_OVERFLOW));
            }

            ///////////////////////////////////////////////
            // 512 by 256 division.
            ///////////////////////////////////////////////

            // Make division exact by subtracting the remainder from [high low].
            uint256 remainder;
            assembly ("memory-safe") {
                // Compute remainder using mulmod.
                remainder := mulmod(x, y, denominator)

                // Subtract 256 bit number from 512 bit number.
                high := sub(high, gt(remainder, low))
                low := sub(low, remainder)
            }

            // Factor powers of two out of denominator and compute largest power of two divisor of denominator.
            // Always >= 1. See https://cs.stackexchange.com/q/138556/92363.

            uint256 twos = denominator & (0 - denominator);
            assembly ("memory-safe") {
                // Divide denominator by twos.
                denominator := div(denominator, twos)

                // Divide [high low] by twos.
                low := div(low, twos)

                // Flip twos such that it is 2²⁵⁶ / twos. If twos is zero, then it becomes one.
                twos := add(div(sub(0, twos), twos), 1)
            }

            // Shift in bits from high into low.
            low |= high * twos;

            // Invert denominator mod 2²⁵⁶. Now that denominator is an odd number, it has an inverse modulo 2²⁵⁶ such
            // that denominator * inv ≡ 1 mod 2²⁵⁶. Compute the inverse by starting with a seed that is correct for
            // four bits. That is, denominator * inv ≡ 1 mod 2⁴.
            uint256 inverse = (3 * denominator) ^ 2;

            // Use the Newton-Raphson iteration to improve the precision. Thanks to Hensel's lifting lemma, this also
            // works in modular arithmetic, doubling the correct bits in each step.
            inverse *= 2 - denominator * inverse; // inverse mod 2⁸
            inverse *= 2 - denominator * inverse; // inverse mod 2¹⁶
            inverse *= 2 - denominator * inverse; // inverse mod 2³²
            inverse *= 2 - denominator * inverse; // inverse mod 2⁶⁴
            inverse *= 2 - denominator * inverse; // inverse mod 2¹²⁸
            inverse *= 2 - denominator * inverse; // inverse mod 2²⁵⁶

            // Because the division is now exact we can divide by multiplying with the modular inverse of denominator.
            // This will give us the correct result modulo 2²⁵⁶. Since the preconditions guarantee that the outcome is
            // less than 2²⁵⁶, this is the final result. We don't need to compute the high bits of the result and high
            // is no longer required.
            result = low * inverse;
            return result;
        }
    }

    /**
     * @dev Calculates x * y / denominator with full precision, following the selected rounding direction.
     */
    function mulDiv(uint256 x, uint256 y, uint256 denominator, Rounding rounding) internal pure returns (uint256) {
        return mulDiv(x, y, denominator) + SafeCast.toUint(unsignedRoundsUp(rounding) && mulmod(x, y, denominator) > 0);
    }

    /**
     * @dev Calculates floor(x * y >> n) with full precision. Throws if result overflows a uint256.
     */
    function mulShr(uint256 x, uint256 y, uint8 n) internal pure returns (uint256 result) {
        unchecked {
            (uint256 high, uint256 low) = mul512(x, y);
            if (high >= 1 << n) {
                Panic.panic(Panic.UNDER_OVERFLOW);
            }
            return (high << (256 - n)) | (low >> n);
        }
    }

    /**
     * @dev Calculates x * y >> n with full precision, following the selected rounding direction.
     */
    function mulShr(uint256 x, uint256 y, uint8 n, Rounding rounding) internal pure returns (uint256) {
        return mulShr(x, y, n) + SafeCast.toUint(unsignedRoundsUp(rounding) && mulmod(x, y, 1 << n) > 0);
    }

    /**
     * @dev Calculate the modular multiplicative inverse of a number in Z/nZ.
     *
     * If n is a prime, then Z/nZ is a field. In that case all elements are inversible, except 0.
     * If n is not a prime, then Z/nZ is not a field, and some elements might not be inversible.
     *
     * If the input value is not inversible, 0 is returned.
     *
     * NOTE: If you know for sure that n is (big) a prime, it may be cheaper to use Fermat's little theorem and get the
     * inverse using `Math.modExp(a, n - 2, n)`. See {invModPrime}.
     */
    function invMod(uint256 a, uint256 n) internal pure returns (uint256) {
        unchecked {
            if (n == 0) return 0;

            // The inverse modulo is calculated using the Extended Euclidean Algorithm (iterative version)
            // Used to compute integers x and y such that: ax + ny = gcd(a, n).
            // When the gcd is 1, then the inverse of a modulo n exists and it's x.
            // ax + ny = 1
            // ax = 1 + (-y)n
            // ax ≡ 1 (mod n) # x is the inverse of a modulo n

            // If the remainder is 0 the gcd is n right away.
            uint256 remainder = a % n;
            uint256 gcd = n;

            // Therefore the initial coefficients are:
            // ax + ny = gcd(a, n) = n
            // 0a + 1n = n
            int256 x = 0;
            int256 y = 1;

            while (remainder != 0) {
                uint256 quotient = gcd / remainder;

                (gcd, remainder) = (
                    // The old remainder is the next gcd to try.
                    remainder,
                    // Compute the next remainder.
                    // Can't overflow given that (a % gcd) * (gcd // (a % gcd)) <= gcd
                    // where gcd is at most n (capped to type(uint256).max)
                    gcd - remainder * quotient
                );

                (x, y) = (
                    // Increment the coefficient of a.
                    y,
                    // Decrement the coefficient of n.
                    // Can overflow, but the result is casted to uint256 so that the
                    // next value of y is "wrapped around" to a value between 0 and n - 1.
                    x - y * int256(quotient)
                );
            }

            if (gcd != 1) return 0; // No inverse exists.
            return ternary(x < 0, n - uint256(-x), uint256(x)); // Wrap the result if it's negative.
        }
    }

    /**
     * @dev Variant of {invMod}. More efficient, but only works if `p` is known to be a prime greater than `2`.
     *
     * From https://en.wikipedia.org/wiki/Fermat%27s_little_theorem[Fermat's little theorem], we know that if p is
     * prime, then `a**(p-1) ≡ 1 mod p`. As a consequence, we have `a * a**(p-2) ≡ 1 mod p`, which means that
     * `a**(p-2)` is the modular multiplicative inverse of a in Fp.
     *
     * NOTE: this function does NOT check that `p` is a prime greater than `2`.
     */
    function invModPrime(uint256 a, uint256 p) internal view returns (uint256) {
        unchecked {
            return Math.modExp(a, p - 2, p);
        }
    }

    /**
     * @dev Returns the modular exponentiation of the specified base, exponent and modulus (b ** e % m)
     *
     * Requirements:
     * - modulus can't be zero
     * - underlying staticcall to precompile must succeed
     *
     * IMPORTANT: The result is only valid if the underlying call succeeds. When using this function, make
     * sure the chain you're using it on supports the precompiled contract for modular exponentiation
     * at address 0x05 as specified in https://eips.ethereum.org/EIPS/eip-198[EIP-198]. Otherwise,
     * the underlying function will succeed given the lack of a revert, but the result may be incorrectly
     * interpreted as 0.
     */
    function modExp(uint256 b, uint256 e, uint256 m) internal view returns (uint256) {
        (bool success, uint256 result) = tryModExp(b, e, m);
        if (!success) {
            Panic.panic(Panic.DIVISION_BY_ZERO);
        }
        return result;
    }

    /**
     * @dev Returns the modular exponentiation of the specified base, exponent and modulus (b ** e % m).
     * It includes a success flag indicating if the operation succeeded. Operation will be marked as failed if trying
     * to operate modulo 0 or if the underlying precompile reverted.
     *
     * IMPORTANT: The result is only valid if the success flag is true. When using this function, make sure the chain
     * you're using it on supports the precompiled contract for modular exponentiation at address 0x05 as specified in
     * https://eips.ethereum.org/EIPS/eip-198[EIP-198]. Otherwise, the underlying function will succeed given the lack
     * of a revert, but the result may be incorrectly interpreted as 0.
     */
    function tryModExp(uint256 b, uint256 e, uint256 m) internal view returns (bool success, uint256 result) {
        if (m == 0) return (false, 0);
        assembly ("memory-safe") {
            let ptr := mload(0x40)
            // | Offset    | Content    | Content (Hex)                                                      |
            // |-----------|------------|--------------------------------------------------------------------|
            // | 0x00:0x1f | size of b  | 0x0000000000000000000000000000000000000000000000000000000000000020 |
            // | 0x20:0x3f | size of e  | 0x0000000000000000000000000000000000000000000000000000000000000020 |
            // | 0x40:0x5f | size of m  | 0x0000000000000000000000000000000000000000000000000000000000000020 |
            // | 0x60:0x7f | value of b | 0x<.............................................................b> |
            // | 0x80:0x9f | value of e | 0x<.............................................................e> |
            // | 0xa0:0xbf | value of m | 0x<.............................................................m> |
            mstore(ptr, 0x20)
            mstore(add(ptr, 0x20), 0x20)
            mstore(add(ptr, 0x40), 0x20)
            mstore(add(ptr, 0x60), b)
            mstore(add(ptr, 0x80), e)
            mstore(add(ptr, 0xa0), m)

            // Given the result < m, it's guaranteed to fit in 32 bytes,
            // so we can use the memory scratch space located at offset 0.
            success := staticcall(gas(), 0x05, ptr, 0xc0, 0x00, 0x20)
            result := mload(0x00)
        }
    }

    /**
     * @dev Variant of {modExp} that supports inputs of arbitrary length.
     */
    function modExp(bytes memory b, bytes memory e, bytes memory m) internal view returns (bytes memory) {
        (bool success, bytes memory result) = tryModExp(b, e, m);
        if (!success) {
            Panic.panic(Panic.DIVISION_BY_ZERO);
        }
        return result;
    }

    /**
     * @dev Variant of {tryModExp} that supports inputs of arbitrary length.
     */
    function tryModExp(
        bytes memory b,
        bytes memory e,
        bytes memory m
    ) internal view returns (bool success, bytes memory result) {
        if (_zeroBytes(m)) return (false, new bytes(0));

        uint256 mLen = m.length;

        // Encode call args in result and move the free memory pointer
        result = abi.encodePacked(b.length, e.length, mLen, b, e, m);

        assembly ("memory-safe") {
            let dataPtr := add(result, 0x20)
            // Write result on top of args to avoid allocating extra memory.
            success := staticcall(gas(), 0x05, dataPtr, mload(result), dataPtr, mLen)
            // Overwrite the length.
            // result.length > returndatasize() is guaranteed because returndatasize() == m.length
            mstore(result, mLen)
            // Set the memory pointer after the returned data.
            mstore(0x40, add(dataPtr, mLen))
        }
    }

    /**
     * @dev Returns whether the provided byte array is zero.
     */
    function _zeroBytes(bytes memory byteArray) private pure returns (bool) {
        for (uint256 i = 0; i < byteArray.length; ++i) {
            if (byteArray[i] != 0) {
                return false;
            }
        }
        return true;
    }

    /**
     * @dev Returns the square root of a number. If the number is not a perfect square, the value is rounded
     * towards zero.
     *
     * This method is based on Newton's method for computing square roots; the algorithm is restricted to only
     * using integer operations.
     */
    function sqrt(uint256 a) internal pure returns (uint256) {
        unchecked {
            // Take care of easy edge cases when a == 0 or a == 1
            if (a <= 1) {
                return a;
            }

            // In this function, we use Newton's method to get a root of `f(x) := x² - a`. It involves building a
            // sequence x_n that converges toward sqrt(a). For each iteration x_n, we also define the error between
            // the current value as `ε_n = | x_n - sqrt(a) |`.
            //
            // For our first estimation, we consider `e` the smallest power of 2 which is bigger than the square root
            // of the target. (i.e. `2**(e-1) ≤ sqrt(a) < 2**e`). We know that `e ≤ 128` because `(2¹²⁸)² = 2²⁵⁶` is
            // bigger than any uint256.
            //
            // By noticing that
            // `2**(e-1) ≤ sqrt(a) < 2**e → (2**(e-1))² ≤ a < (2**e)² → 2**(2*e-2) ≤ a < 2**(2*e)`
            // we can deduce that `e - 1` is `log2(a) / 2`. We can thus compute `x_n = 2**(e-1)` using a method similar
            // to the msb function.
            uint256 aa = a;
            uint256 xn = 1;

            if (aa >= (1 << 128)) {
                aa >>= 128;
                xn <<= 64;
            }
            if (aa >= (1 << 64)) {
                aa >>= 64;
                xn <<= 32;
            }
            if (aa >= (1 << 32)) {
                aa >>= 32;
                xn <<= 16;
            }
            if (aa >= (1 << 16)) {
                aa >>= 16;
                xn <<= 8;
            }
            if (aa >= (1 << 8)) {
                aa >>= 8;
                xn <<= 4;
            }
            if (aa >= (1 << 4)) {
                aa >>= 4;
                xn <<= 2;
            }
            if (aa >= (1 << 2)) {
                xn <<= 1;
            }

            // We now have x_n such that `x_n = 2**(e-1) ≤ sqrt(a) < 2**e = 2 * x_n`. This implies ε_n ≤ 2**(e-1).
            //
            // We can refine our estimation by noticing that the middle of that interval minimizes the error.
            // If we move x_n to equal 2**(e-1) + 2**(e-2), then we reduce the error to ε_n ≤ 2**(e-2).
            // This is going to be our x_0 (and ε_0)
            xn = (3 * xn) >> 1; // ε_0 := | x_0 - sqrt(a) | ≤ 2**(e-2)

            // From here, Newton's method give us:
            // x_{n+1} = (x_n + a / x_n) / 2
            //
            // One should note that:
            // x_{n+1}² - a = ((x_n + a / x_n) / 2)² - a
            //              = ((x_n² + a) / (2 * x_n))² - a
            //              = (x_n⁴ + 2 * a * x_n² + a²) / (4 * x_n²) - a
            //              = (x_n⁴ + 2 * a * x_n² + a² - 4 * a * x_n²) / (4 * x_n²)
            //              = (x_n⁴ - 2 * a * x_n² + a²) / (4 * x_n²)
            //              = (x_n² - a)² / (2 * x_n)²
            //              = ((x_n² - a) / (2 * x_n))²
            //              ≥ 0
            // Which proves that for all n ≥ 1, sqrt(a) ≤ x_n
            //
            // This gives us the proof of quadratic convergence of the sequence:
            // ε_{n+1} = | x_{n+1} - sqrt(a) |
            //         = | (x_n + a / x_n) / 2 - sqrt(a) |
            //         = | (x_n² + a - 2*x_n*sqrt(a)) / (2 * x_n) |
            //         = | (x_n - sqrt(a))² / (2 * x_n) |
            //         = | ε_n² / (2 * x_n) |
            //         = ε_n² / | (2 * x_n) |
            //
            // For the first iteration, we have a special case where x_0 is known:
            // ε_1 = ε_0² / | (2 * x_0) |
            //     ≤ (2**(e-2))² / (2 * (2**(e-1) + 2**(e-2)))
            //     ≤ 2**(2*e-4) / (3 * 2**(e-1))
            //     ≤ 2**(e-3) / 3
            //     ≤ 2**(e-3-log2(3))
            //     ≤ 2**(e-4.5)
            //
            // For the following iterations, we use the fact that, 2**(e-1) ≤ sqrt(a) ≤ x_n:
            // ε_{n+1} = ε_n² / | (2 * x_n) |
            //         ≤ (2**(e-k))² / (2 * 2**(e-1))
            //         ≤ 2**(2*e-2*k) / 2**e
            //         ≤ 2**(e-2*k)
            xn = (xn + a / xn) >> 1; // ε_1 := | x_1 - sqrt(a) | ≤ 2**(e-4.5)  -- special case, see above
            xn = (xn + a / xn) >> 1; // ε_2 := | x_2 - sqrt(a) | ≤ 2**(e-9)    -- general case with k = 4.5
            xn = (xn + a / xn) >> 1; // ε_3 := | x_3 - sqrt(a) | ≤ 2**(e-18)   -- general case with k = 9
            xn = (xn + a / xn) >> 1; // ε_4 := | x_4 - sqrt(a) | ≤ 2**(e-36)   -- general case with k = 18
            xn = (xn + a / xn) >> 1; // ε_5 := | x_5 - sqrt(a) | ≤ 2**(e-72)   -- general case with k = 36
            xn = (xn + a / xn) >> 1; // ε_6 := | x_6 - sqrt(a) | ≤ 2**(e-144)  -- general case with k = 72

            // Because e ≤ 128 (as discussed during the first estimation phase), we know have reached a precision
            // ε_6 ≤ 2**(e-144) < 1. Given we're operating on integers, then we can ensure that xn is now either
            // sqrt(a) or sqrt(a) + 1.
            return xn - SafeCast.toUint(xn > a / xn);
        }
    }

    /**
     * @dev Calculates sqrt(a), following the selected rounding direction.
     */
    function sqrt(uint256 a, Rounding rounding) internal pure returns (uint256) {
        unchecked {
            uint256 result = sqrt(a);
            return result + SafeCast.toUint(unsignedRoundsUp(rounding) && result * result < a);
        }
    }

    /**
     * @dev Return the log in base 2 of a positive value rounded towards zero.
     * Returns 0 if given 0.
     */
    function log2(uint256 x) internal pure returns (uint256 r) {
        // If value has upper 128 bits set, log2 result is at least 128
        r = SafeCast.toUint(x > 0xffffffffffffffffffffffffffffffff) << 7;
        // If upper 64 bits of 128-bit half set, add 64 to result
        r |= SafeCast.toUint((x >> r) > 0xffffffffffffffff) << 6;
        // If upper 32 bits of 64-bit half set, add 32 to result
        r |= SafeCast.toUint((x >> r) > 0xffffffff) << 5;
        // If upper 16 bits of 32-bit half set, add 16 to result
        r |= SafeCast.toUint((x >> r) > 0xffff) << 4;
        // If upper 8 bits of 16-bit half set, add 8 to result
        r |= SafeCast.toUint((x >> r) > 0xff) << 3;
        // If upper 4 bits of 8-bit half set, add 4 to result
        r |= SafeCast.toUint((x >> r) > 0xf) << 2;

        // Shifts value right by the current result and use it as an index into this lookup table:
        //
        // | x (4 bits) |  index  | table[index] = MSB position |
        // |------------|---------|-----------------------------|
        // |    0000    |    0    |        table[0] = 0         |
        // |    0001    |    1    |        table[1] = 0         |
        // |    0010    |    2    |        table[2] = 1         |
        // |    0011    |    3    |        table[3] = 1         |
        // |    0100    |    4    |        table[4] = 2         |
        // |    0101    |    5    |        table[5] = 2         |
        // |    0110    |    6    |        table[6] = 2         |
        // |    0111    |    7    |        table[7] = 2         |
        // |    1000    |    8    |        table[8] = 3         |
        // |    1001    |    9    |        table[9] = 3         |
        // |    1010    |   10    |        table[10] = 3        |
        // |    1011    |   11    |        table[11] = 3        |
        // |    1100    |   12    |        table[12] = 3        |
        // |    1101    |   13    |        table[13] = 3        |
        // |    1110    |   14    |        table[14] = 3        |
        // |    1111    |   15    |        table[15] = 3        |
        //
        // The lookup table is represented as a 32-byte value with the MSB positions for 0-15 in the last 16 bytes.
        assembly ("memory-safe") {
            r := or(r, byte(shr(r, x), 0x0000010102020202030303030303030300000000000000000000000000000000))
        }
    }

    /**
     * @dev Return the log in base 2, following the selected rounding direction, of a positive value.
     * Returns 0 if given 0.
     */
    function log2(uint256 value, Rounding rounding) internal pure returns (uint256) {
        unchecked {
            uint256 result = log2(value);
            return result + SafeCast.toUint(unsignedRoundsUp(rounding) && 1 << result < value);
        }
    }

    /**
     * @dev Return the log in base 10 of a positive value rounded towards zero.
     * Returns 0 if given 0.
     */
    function log10(uint256 value) internal pure returns (uint256) {
        uint256 result = 0;
        unchecked {
            if (value >= 10 ** 64) {
                value /= 10 ** 64;
                result += 64;
            }
            if (value >= 10 ** 32) {
                value /= 10 ** 32;
                result += 32;
            }
            if (value >= 10 ** 16) {
                value /= 10 ** 16;
                result += 16;
            }
            if (value >= 10 ** 8) {
                value /= 10 ** 8;
                result += 8;
            }
            if (value >= 10 ** 4) {
                value /= 10 ** 4;
                result += 4;
            }
            if (value >= 10 ** 2) {
                value /= 10 ** 2;
                result += 2;
            }
            if (value >= 10 ** 1) {
                result += 1;
            }
        }
        return result;
    }

    /**
     * @dev Return the log in base 10, following the selected rounding direction, of a positive value.
     * Returns 0 if given 0.
     */
    function log10(uint256 value, Rounding rounding) internal pure returns (uint256) {
        unchecked {
            uint256 result = log10(value);
            return result + SafeCast.toUint(unsignedRoundsUp(rounding) && 10 ** result < value);
        }
    }

    /**
     * @dev Return the log in base 256 of a positive value rounded towards zero.
     * Returns 0 if given 0.
     *
     * Adding one to the result gives the number of pairs of hex symbols needed to represent `value` as a hex string.
     */
    function log256(uint256 x) internal pure returns (uint256 r) {
        // If value has upper 128 bits set, log2 result is at least 128
        r = SafeCast.toUint(x > 0xffffffffffffffffffffffffffffffff) << 7;
        // If upper 64 bits of 128-bit half set, add 64 to result
        r |= SafeCast.toUint((x >> r) > 0xffffffffffffffff) << 6;
        // If upper 32 bits of 64-bit half set, add 32 to result
        r |= SafeCast.toUint((x >> r) > 0xffffffff) << 5;
        // If upper 16 bits of 32-bit half set, add 16 to result
        r |= SafeCast.toUint((x >> r) > 0xffff) << 4;
        // Add 1 if upper 8 bits of 16-bit half set, and divide accumulated result by 8
        return (r >> 3) | SafeCast.toUint((x >> r) > 0xff);
    }

    /**
     * @dev Return the log in base 256, following the selected rounding direction, of a positive value.
     * Returns 0 if given 0.
     */
    function log256(uint256 value, Rounding rounding) internal pure returns (uint256) {
        unchecked {
            uint256 result = log256(value);
            return result + SafeCast.toUint(unsignedRoundsUp(rounding) && 1 << (result << 3) < value);
        }
    }

    /**
     * @dev Returns whether a provided rounding mode is considered rounding up for unsigned integers.
     */
    function unsignedRoundsUp(Rounding rounding) internal pure returns (bool) {
        return uint8(rounding) % 2 == 1;
    }
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.1.0) (utils/math/SafeCast.sol)
// This file was procedurally generated from scripts/generate/templates/SafeCast.js.

pragma solidity ^0.8.20;

/**
 * @dev Wrappers over Solidity's uintXX/intXX/bool casting operators with added overflow
 * checks.
 *
 * Downcasting from uint256/int256 in Solidity does not revert on overflow. This can
 * easily result in undesired exploitation or bugs, since developers usually
 * assume that overflows raise errors. `SafeCast` restores this intuition by
 * reverting the transaction when such an operation overflows.
 *
 * Using this library instead of the unchecked operations eliminates an entire
 * class of bugs, so it's recommended to use it always.
 */
library SafeCast {
    /**
     * @dev Value doesn't fit in an uint of `bits` size.
     */
    error SafeCastOverflowedUintDowncast(uint8 bits, uint256 value);

    /**
     * @dev An int value doesn't fit in an uint of `bits` size.
     */
    error SafeCastOverflowedIntToUint(int256 value);

    /**
     * @dev Value doesn't fit in an int of `bits` size.
     */
    error SafeCastOverflowedIntDowncast(uint8 bits, int256 value);

    /**
     * @dev An uint value doesn't fit in an int of `bits` size.
     */
    error SafeCastOverflowedUintToInt(uint256 value);

    /**
     * @dev Returns the downcasted uint248 from uint256, reverting on
     * overflow (when the input is greater than largest uint248).
     *
     * Counterpart to Solidity's `uint248` operator.
     *
     * Requirements:
     *
     * - input must fit into 248 bits
     */
    function toUint248(uint256 value) internal pure returns (uint248) {
        if (value > type(uint248).max) {
            revert SafeCastOverflowedUintDowncast(248, value);
        }
        return uint248(value);
    }

    /**
     * @dev Returns the downcasted uint240 from uint256, reverting on
     * overflow (when the input is greater than largest uint240).
     *
     * Counterpart to Solidity's `uint240` operator.
     *
     * Requirements:
     *
     * - input must fit into 240 bits
     */
    function toUint240(uint256 value) internal pure returns (uint240) {
        if (value > type(uint240).max) {
            revert SafeCastOverflowedUintDowncast(240, value);
        }
        return uint240(value);
    }

    /**
     * @dev Returns the downcasted uint232 from uint256, reverting on
     * overflow (when the input is greater than largest uint232).
     *
     * Counterpart to Solidity's `uint232` operator.
     *
     * Requirements:
     *
     * - input must fit into 232 bits
     */
    function toUint232(uint256 value) internal pure returns (uint232) {
        if (value > type(uint232).max) {
            revert SafeCastOverflowedUintDowncast(232, value);
        }
        return uint232(value);
    }

    /**
     * @dev Returns the downcasted uint224 from uint256, reverting on
     * overflow (when the input is greater than largest uint224).
     *
     * Counterpart to Solidity's `uint224` operator.
     *
     * Requirements:
     *
     * - input must fit into 224 bits
     */
    function toUint224(uint256 value) internal pure returns (uint224) {
        if (value > type(uint224).max) {
            revert SafeCastOverflowedUintDowncast(224, value);
        }
        return uint224(value);
    }

    /**
     * @dev Returns the downcasted uint216 from uint256, reverting on
     * overflow (when the input is greater than largest uint216).
     *
     * Counterpart to Solidity's `uint216` operator.
     *
     * Requirements:
     *
     * - input must fit into 216 bits
     */
    function toUint216(uint256 value) internal pure returns (uint216) {
        if (value > type(uint216).max) {
            revert SafeCastOverflowedUintDowncast(216, value);
        }
        return uint216(value);
    }

    /**
     * @dev Returns the downcasted uint208 from uint256, reverting on
     * overflow (when the input is greater than largest uint208).
     *
     * Counterpart to Solidity's `uint208` operator.
     *
     * Requirements:
     *
     * - input must fit into 208 bits
     */
    function toUint208(uint256 value) internal pure returns (uint208) {
        if (value > type(uint208).max) {
            revert SafeCastOverflowedUintDowncast(208, value);
        }
        return uint208(value);
    }

    /**
     * @dev Returns the downcasted uint200 from uint256, reverting on
     * overflow (when the input is greater than largest uint200).
     *
     * Counterpart to Solidity's `uint200` operator.
     *
     * Requirements:
     *
     * - input must fit into 200 bits
     */
    function toUint200(uint256 value) internal pure returns (uint200) {
        if (value > type(uint200).max) {
            revert SafeCastOverflowedUintDowncast(200, value);
        }
        return uint200(value);
    }

    /**
     * @dev Returns the downcasted uint192 from uint256, reverting on
     * overflow (when the input is greater than largest uint192).
     *
     * Counterpart to Solidity's `uint192` operator.
     *
     * Requirements:
     *
     * - input must fit into 192 bits
     */
    function toUint192(uint256 value) internal pure returns (uint192) {
        if (value > type(uint192).max) {
            revert SafeCastOverflowedUintDowncast(192, value);
        }
        return uint192(value);
    }

    /**
     * @dev Returns the downcasted uint184 from uint256, reverting on
     * overflow (when the input is greater than largest uint184).
     *
     * Counterpart to Solidity's `uint184` operator.
     *
     * Requirements:
     *
     * - input must fit into 184 bits
     */
    function toUint184(uint256 value) internal pure returns (uint184) {
        if (value > type(uint184).max) {
            revert SafeCastOverflowedUintDowncast(184, value);
        }
        return uint184(value);
    }

    /**
     * @dev Returns the downcasted uint176 from uint256, reverting on
     * overflow (when the input is greater than largest uint176).
     *
     * Counterpart to Solidity's `uint176` operator.
     *
     * Requirements:
     *
     * - input must fit into 176 bits
     */
    function toUint176(uint256 value) internal pure returns (uint176) {
        if (value > type(uint176).max) {
            revert SafeCastOverflowedUintDowncast(176, value);
        }
        return uint176(value);
    }

    /**
     * @dev Returns the downcasted uint168 from uint256, reverting on
     * overflow (when the input is greater than largest uint168).
     *
     * Counterpart to Solidity's `uint168` operator.
     *
     * Requirements:
     *
     * - input must fit into 168 bits
     */
    function toUint168(uint256 value) internal pure returns (uint168) {
        if (value > type(uint168).max) {
            revert SafeCastOverflowedUintDowncast(168, value);
        }
        return uint168(value);
    }

    /**
     * @dev Returns the downcasted uint160 from uint256, reverting on
     * overflow (when the input is greater than largest uint160).
     *
     * Counterpart to Solidity's `uint160` operator.
     *
     * Requirements:
     *
     * - input must fit into 160 bits
     */
    function toUint160(uint256 value) internal pure returns (uint160) {
        if (value > type(uint160).max) {
            revert SafeCastOverflowedUintDowncast(160, value);
        }
        return uint160(value);
    }

    /**
     * @dev Returns the downcasted uint152 from uint256, reverting on
     * overflow (when the input is greater than largest uint152).
     *
     * Counterpart to Solidity's `uint152` operator.
     *
     * Requirements:
     *
     * - input must fit into 152 bits
     */
    function toUint152(uint256 value) internal pure returns (uint152) {
        if (value > type(uint152).max) {
            revert SafeCastOverflowedUintDowncast(152, value);
        }
        return uint152(value);
    }

    /**
     * @dev Returns the downcasted uint144 from uint256, reverting on
     * overflow (when the input is greater than largest uint144).
     *
     * Counterpart to Solidity's `uint144` operator.
     *
     * Requirements:
     *
     * - input must fit into 144 bits
     */
    function toUint144(uint256 value) internal pure returns (uint144) {
        if (value > type(uint144).max) {
            revert SafeCastOverflowedUintDowncast(144, value);
        }
        return uint144(value);
    }

    /**
     * @dev Returns the downcasted uint136 from uint256, reverting on
     * overflow (when the input is greater than largest uint136).
     *
     * Counterpart to Solidity's `uint136` operator.
     *
     * Requirements:
     *
     * - input must fit into 136 bits
     */
    function toUint136(uint256 value) internal pure returns (uint136) {
        if (value > type(uint136).max) {
            revert SafeCastOverflowedUintDowncast(136, value);
        }
        return uint136(value);
    }

    /**
     * @dev Returns the downcasted uint128 from uint256, reverting on
     * overflow (when the input is greater than largest uint128).
     *
     * Counterpart to Solidity's `uint128` operator.
     *
     * Requirements:
     *
     * - input must fit into 128 bits
     */
    function toUint128(uint256 value) internal pure returns (uint128) {
        if (value > type(uint128).max) {
            revert SafeCastOverflowedUintDowncast(128, value);
        }
        return uint128(value);
    }

    /**
     * @dev Returns the downcasted uint120 from uint256, reverting on
     * overflow (when the input is greater than largest uint120).
     *
     * Counterpart to Solidity's `uint120` operator.
     *
     * Requirements:
     *
     * - input must fit into 120 bits
     */
    function toUint120(uint256 value) internal pure returns (uint120) {
        if (value > type(uint120).max) {
            revert SafeCastOverflowedUintDowncast(120, value);
        }
        return uint120(value);
    }

    /**
     * @dev Returns the downcasted uint112 from uint256, reverting on
     * overflow (when the input is greater than largest uint112).
     *
     * Counterpart to Solidity's `uint112` operator.
     *
     * Requirements:
     *
     * - input must fit into 112 bits
     */
    function toUint112(uint256 value) internal pure returns (uint112) {
        if (value > type(uint112).max) {
            revert SafeCastOverflowedUintDowncast(112, value);
        }
        return uint112(value);
    }

    /**
     * @dev Returns the downcasted uint104 from uint256, reverting on
     * overflow (when the input is greater than largest uint104).
     *
     * Counterpart to Solidity's `uint104` operator.
     *
     * Requirements:
     *
     * - input must fit into 104 bits
     */
    function toUint104(uint256 value) internal pure returns (uint104) {
        if (value > type(uint104).max) {
            revert SafeCastOverflowedUintDowncast(104, value);
        }
        return uint104(value);
    }

    /**
     * @dev Returns the downcasted uint96 from uint256, reverting on
     * overflow (when the input is greater than largest uint96).
     *
     * Counterpart to Solidity's `uint96` operator.
     *
     * Requirements:
     *
     * - input must fit into 96 bits
     */
    function toUint96(uint256 value) internal pure returns (uint96) {
        if (value > type(uint96).max) {
            revert SafeCastOverflowedUintDowncast(96, value);
        }
        return uint96(value);
    }

    /**
     * @dev Returns the downcasted uint88 from uint256, reverting on
     * overflow (when the input is greater than largest uint88).
     *
     * Counterpart to Solidity's `uint88` operator.
     *
     * Requirements:
     *
     * - input must fit into 88 bits
     */
    function toUint88(uint256 value) internal pure returns (uint88) {
        if (value > type(uint88).max) {
            revert SafeCastOverflowedUintDowncast(88, value);
        }
        return uint88(value);
    }

    /**
     * @dev Returns the downcasted uint80 from uint256, reverting on
     * overflow (when the input is greater than largest uint80).
     *
     * Counterpart to Solidity's `uint80` operator.
     *
     * Requirements:
     *
     * - input must fit into 80 bits
     */
    function toUint80(uint256 value) internal pure returns (uint80) {
        if (value > type(uint80).max) {
            revert SafeCastOverflowedUintDowncast(80, value);
        }
        return uint80(value);
    }

    /**
     * @dev Returns the downcasted uint72 from uint256, reverting on
     * overflow (when the input is greater than largest uint72).
     *
     * Counterpart to Solidity's `uint72` operator.
     *
     * Requirements:
     *
     * - input must fit into 72 bits
     */
    function toUint72(uint256 value) internal pure returns (uint72) {
        if (value > type(uint72).max) {
            revert SafeCastOverflowedUintDowncast(72, value);
        }
        return uint72(value);
    }

    /**
     * @dev Returns the downcasted uint64 from uint256, reverting on
     * overflow (when the input is greater than largest uint64).
     *
     * Counterpart to Solidity's `uint64` operator.
     *
     * Requirements:
     *
     * - input must fit into 64 bits
     */
    function toUint64(uint256 value) internal pure returns (uint64) {
        if (value > type(uint64).max) {
            revert SafeCastOverflowedUintDowncast(64, value);
        }
        return uint64(value);
    }

    /**
     * @dev Returns the downcasted uint56 from uint256, reverting on
     * overflow (when the input is greater than largest uint56).
     *
     * Counterpart to Solidity's `uint56` operator.
     *
     * Requirements:
     *
     * - input must fit into 56 bits
     */
    function toUint56(uint256 value) internal pure returns (uint56) {
        if (value > type(uint56).max) {
            revert SafeCastOverflowedUintDowncast(56, value);
        }
        return uint56(value);
    }

    /**
     * @dev Returns the downcasted uint48 from uint256, reverting on
     * overflow (when the input is greater than largest uint48).
     *
     * Counterpart to Solidity's `uint48` operator.
     *
     * Requirements:
     *
     * - input must fit into 48 bits
     */
    function toUint48(uint256 value) internal pure returns (uint48) {
        if (value > type(uint48).max) {
            revert SafeCastOverflowedUintDowncast(48, value);
        }
        return uint48(value);
    }

    /**
     * @dev Returns the downcasted uint40 from uint256, reverting on
     * overflow (when the input is greater than largest uint40).
     *
     * Counterpart to Solidity's `uint40` operator.
     *
     * Requirements:
     *
     * - input must fit into 40 bits
     */
    function toUint40(uint256 value) internal pure returns (uint40) {
        if (value > type(uint40).max) {
            revert SafeCastOverflowedUintDowncast(40, value);
        }
        return uint40(value);
    }

    /**
     * @dev Returns the downcasted uint32 from uint256, reverting on
     * overflow (when the input is greater than largest uint32).
     *
     * Counterpart to Solidity's `uint32` operator.
     *
     * Requirements:
     *
     * - input must fit into 32 bits
     */
    function toUint32(uint256 value) internal pure returns (uint32) {
        if (value > type(uint32).max) {
            revert SafeCastOverflowedUintDowncast(32, value);
        }
        return uint32(value);
    }

    /**
     * @dev Returns the downcasted uint24 from uint256, reverting on
     * overflow (when the input is greater than largest uint24).
     *
     * Counterpart to Solidity's `uint24` operator.
     *
     * Requirements:
     *
     * - input must fit into 24 bits
     */
    function toUint24(uint256 value) internal pure returns (uint24) {
        if (value > type(uint24).max) {
            revert SafeCastOverflowedUintDowncast(24, value);
        }
        return uint24(value);
    }

    /**
     * @dev Returns the downcasted uint16 from uint256, reverting on
     * overflow (when the input is greater than largest uint16).
     *
     * Counterpart to Solidity's `uint16` operator.
     *
     * Requirements:
     *
     * - input must fit into 16 bits
     */
    function toUint16(uint256 value) internal pure returns (uint16) {
        if (value > type(uint16).max) {
            revert SafeCastOverflowedUintDowncast(16, value);
        }
        return uint16(value);
    }

    /**
     * @dev Returns the downcasted uint8 from uint256, reverting on
     * overflow (when the input is greater than largest uint8).
     *
     * Counterpart to Solidity's `uint8` operator.
     *
     * Requirements:
     *
     * - input must fit into 8 bits
     */
    function toUint8(uint256 value) internal pure returns (uint8) {
        if (value > type(uint8).max) {
            revert SafeCastOverflowedUintDowncast(8, value);
        }
        return uint8(value);
    }

    /**
     * @dev Converts a signed int256 into an unsigned uint256.
     *
     * Requirements:
     *
     * - input must be greater than or equal to 0.
     */
    function toUint256(int256 value) internal pure returns (uint256) {
        if (value < 0) {
            revert SafeCastOverflowedIntToUint(value);
        }
        return uint256(value);
    }

    /**
     * @dev Returns the downcasted int248 from int256, reverting on
     * overflow (when the input is less than smallest int248 or
     * greater than largest int248).
     *
     * Counterpart to Solidity's `int248` operator.
     *
     * Requirements:
     *
     * - input must fit into 248 bits
     */
    function toInt248(int256 value) internal pure returns (int248 downcasted) {
        downcasted = int248(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(248, value);
        }
    }

    /**
     * @dev Returns the downcasted int240 from int256, reverting on
     * overflow (when the input is less than smallest int240 or
     * greater than largest int240).
     *
     * Counterpart to Solidity's `int240` operator.
     *
     * Requirements:
     *
     * - input must fit into 240 bits
     */
    function toInt240(int256 value) internal pure returns (int240 downcasted) {
        downcasted = int240(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(240, value);
        }
    }

    /**
     * @dev Returns the downcasted int232 from int256, reverting on
     * overflow (when the input is less than smallest int232 or
     * greater than largest int232).
     *
     * Counterpart to Solidity's `int232` operator.
     *
     * Requirements:
     *
     * - input must fit into 232 bits
     */
    function toInt232(int256 value) internal pure returns (int232 downcasted) {
        downcasted = int232(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(232, value);
        }
    }

    /**
     * @dev Returns the downcasted int224 from int256, reverting on
     * overflow (when the input is less than smallest int224 or
     * greater than largest int224).
     *
     * Counterpart to Solidity's `int224` operator.
     *
     * Requirements:
     *
     * - input must fit into 224 bits
     */
    function toInt224(int256 value) internal pure returns (int224 downcasted) {
        downcasted = int224(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(224, value);
        }
    }

    /**
     * @dev Returns the downcasted int216 from int256, reverting on
     * overflow (when the input is less than smallest int216 or
     * greater than largest int216).
     *
     * Counterpart to Solidity's `int216` operator.
     *
     * Requirements:
     *
     * - input must fit into 216 bits
     */
    function toInt216(int256 value) internal pure returns (int216 downcasted) {
        downcasted = int216(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(216, value);
        }
    }

    /**
     * @dev Returns the downcasted int208 from int256, reverting on
     * overflow (when the input is less than smallest int208 or
     * greater than largest int208).
     *
     * Counterpart to Solidity's `int208` operator.
     *
     * Requirements:
     *
     * - input must fit into 208 bits
     */
    function toInt208(int256 value) internal pure returns (int208 downcasted) {
        downcasted = int208(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(208, value);
        }
    }

    /**
     * @dev Returns the downcasted int200 from int256, reverting on
     * overflow (when the input is less than smallest int200 or
     * greater than largest int200).
     *
     * Counterpart to Solidity's `int200` operator.
     *
     * Requirements:
     *
     * - input must fit into 200 bits
     */
    function toInt200(int256 value) internal pure returns (int200 downcasted) {
        downcasted = int200(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(200, value);
        }
    }

    /**
     * @dev Returns the downcasted int192 from int256, reverting on
     * overflow (when the input is less than smallest int192 or
     * greater than largest int192).
     *
     * Counterpart to Solidity's `int192` operator.
     *
     * Requirements:
     *
     * - input must fit into 192 bits
     */
    function toInt192(int256 value) internal pure returns (int192 downcasted) {
        downcasted = int192(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(192, value);
        }
    }

    /**
     * @dev Returns the downcasted int184 from int256, reverting on
     * overflow (when the input is less than smallest int184 or
     * greater than largest int184).
     *
     * Counterpart to Solidity's `int184` operator.
     *
     * Requirements:
     *
     * - input must fit into 184 bits
     */
    function toInt184(int256 value) internal pure returns (int184 downcasted) {
        downcasted = int184(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(184, value);
        }
    }

    /**
     * @dev Returns the downcasted int176 from int256, reverting on
     * overflow (when the input is less than smallest int176 or
     * greater than largest int176).
     *
     * Counterpart to Solidity's `int176` operator.
     *
     * Requirements:
     *
     * - input must fit into 176 bits
     */
    function toInt176(int256 value) internal pure returns (int176 downcasted) {
        downcasted = int176(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(176, value);
        }
    }

    /**
     * @dev Returns the downcasted int168 from int256, reverting on
     * overflow (when the input is less than smallest int168 or
     * greater than largest int168).
     *
     * Counterpart to Solidity's `int168` operator.
     *
     * Requirements:
     *
     * - input must fit into 168 bits
     */
    function toInt168(int256 value) internal pure returns (int168 downcasted) {
        downcasted = int168(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(168, value);
        }
    }

    /**
     * @dev Returns the downcasted int160 from int256, reverting on
     * overflow (when the input is less than smallest int160 or
     * greater than largest int160).
     *
     * Counterpart to Solidity's `int160` operator.
     *
     * Requirements:
     *
     * - input must fit into 160 bits
     */
    function toInt160(int256 value) internal pure returns (int160 downcasted) {
        downcasted = int160(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(160, value);
        }
    }

    /**
     * @dev Returns the downcasted int152 from int256, reverting on
     * overflow (when the input is less than smallest int152 or
     * greater than largest int152).
     *
     * Counterpart to Solidity's `int152` operator.
     *
     * Requirements:
     *
     * - input must fit into 152 bits
     */
    function toInt152(int256 value) internal pure returns (int152 downcasted) {
        downcasted = int152(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(152, value);
        }
    }

    /**
     * @dev Returns the downcasted int144 from int256, reverting on
     * overflow (when the input is less than smallest int144 or
     * greater than largest int144).
     *
     * Counterpart to Solidity's `int144` operator.
     *
     * Requirements:
     *
     * - input must fit into 144 bits
     */
    function toInt144(int256 value) internal pure returns (int144 downcasted) {
        downcasted = int144(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(144, value);
        }
    }

    /**
     * @dev Returns the downcasted int136 from int256, reverting on
     * overflow (when the input is less than smallest int136 or
     * greater than largest int136).
     *
     * Counterpart to Solidity's `int136` operator.
     *
     * Requirements:
     *
     * - input must fit into 136 bits
     */
    function toInt136(int256 value) internal pure returns (int136 downcasted) {
        downcasted = int136(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(136, value);
        }
    }

    /**
     * @dev Returns the downcasted int128 from int256, reverting on
     * overflow (when the input is less than smallest int128 or
     * greater than largest int128).
     *
     * Counterpart to Solidity's `int128` operator.
     *
     * Requirements:
     *
     * - input must fit into 128 bits
     */
    function toInt128(int256 value) internal pure returns (int128 downcasted) {
        downcasted = int128(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(128, value);
        }
    }

    /**
     * @dev Returns the downcasted int120 from int256, reverting on
     * overflow (when the input is less than smallest int120 or
     * greater than largest int120).
     *
     * Counterpart to Solidity's `int120` operator.
     *
     * Requirements:
     *
     * - input must fit into 120 bits
     */
    function toInt120(int256 value) internal pure returns (int120 downcasted) {
        downcasted = int120(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(120, value);
        }
    }

    /**
     * @dev Returns the downcasted int112 from int256, reverting on
     * overflow (when the input is less than smallest int112 or
     * greater than largest int112).
     *
     * Counterpart to Solidity's `int112` operator.
     *
     * Requirements:
     *
     * - input must fit into 112 bits
     */
    function toInt112(int256 value) internal pure returns (int112 downcasted) {
        downcasted = int112(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(112, value);
        }
    }

    /**
     * @dev Returns the downcasted int104 from int256, reverting on
     * overflow (when the input is less than smallest int104 or
     * greater than largest int104).
     *
     * Counterpart to Solidity's `int104` operator.
     *
     * Requirements:
     *
     * - input must fit into 104 bits
     */
    function toInt104(int256 value) internal pure returns (int104 downcasted) {
        downcasted = int104(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(104, value);
        }
    }

    /**
     * @dev Returns the downcasted int96 from int256, reverting on
     * overflow (when the input is less than smallest int96 or
     * greater than largest int96).
     *
     * Counterpart to Solidity's `int96` operator.
     *
     * Requirements:
     *
     * - input must fit into 96 bits
     */
    function toInt96(int256 value) internal pure returns (int96 downcasted) {
        downcasted = int96(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(96, value);
        }
    }

    /**
     * @dev Returns the downcasted int88 from int256, reverting on
     * overflow (when the input is less than smallest int88 or
     * greater than largest int88).
     *
     * Counterpart to Solidity's `int88` operator.
     *
     * Requirements:
     *
     * - input must fit into 88 bits
     */
    function toInt88(int256 value) internal pure returns (int88 downcasted) {
        downcasted = int88(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(88, value);
        }
    }

    /**
     * @dev Returns the downcasted int80 from int256, reverting on
     * overflow (when the input is less than smallest int80 or
     * greater than largest int80).
     *
     * Counterpart to Solidity's `int80` operator.
     *
     * Requirements:
     *
     * - input must fit into 80 bits
     */
    function toInt80(int256 value) internal pure returns (int80 downcasted) {
        downcasted = int80(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(80, value);
        }
    }

    /**
     * @dev Returns the downcasted int72 from int256, reverting on
     * overflow (when the input is less than smallest int72 or
     * greater than largest int72).
     *
     * Counterpart to Solidity's `int72` operator.
     *
     * Requirements:
     *
     * - input must fit into 72 bits
     */
    function toInt72(int256 value) internal pure returns (int72 downcasted) {
        downcasted = int72(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(72, value);
        }
    }

    /**
     * @dev Returns the downcasted int64 from int256, reverting on
     * overflow (when the input is less than smallest int64 or
     * greater than largest int64).
     *
     * Counterpart to Solidity's `int64` operator.
     *
     * Requirements:
     *
     * - input must fit into 64 bits
     */
    function toInt64(int256 value) internal pure returns (int64 downcasted) {
        downcasted = int64(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(64, value);
        }
    }

    /**
     * @dev Returns the downcasted int56 from int256, reverting on
     * overflow (when the input is less than smallest int56 or
     * greater than largest int56).
     *
     * Counterpart to Solidity's `int56` operator.
     *
     * Requirements:
     *
     * - input must fit into 56 bits
     */
    function toInt56(int256 value) internal pure returns (int56 downcasted) {
        downcasted = int56(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(56, value);
        }
    }

    /**
     * @dev Returns the downcasted int48 from int256, reverting on
     * overflow (when the input is less than smallest int48 or
     * greater than largest int48).
     *
     * Counterpart to Solidity's `int48` operator.
     *
     * Requirements:
     *
     * - input must fit into 48 bits
     */
    function toInt48(int256 value) internal pure returns (int48 downcasted) {
        downcasted = int48(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(48, value);
        }
    }

    /**
     * @dev Returns the downcasted int40 from int256, reverting on
     * overflow (when the input is less than smallest int40 or
     * greater than largest int40).
     *
     * Counterpart to Solidity's `int40` operator.
     *
     * Requirements:
     *
     * - input must fit into 40 bits
     */
    function toInt40(int256 value) internal pure returns (int40 downcasted) {
        downcasted = int40(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(40, value);
        }
    }

    /**
     * @dev Returns the downcasted int32 from int256, reverting on
     * overflow (when the input is less than smallest int32 or
     * greater than largest int32).
     *
     * Counterpart to Solidity's `int32` operator.
     *
     * Requirements:
     *
     * - input must fit into 32 bits
     */
    function toInt32(int256 value) internal pure returns (int32 downcasted) {
        downcasted = int32(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(32, value);
        }
    }

    /**
     * @dev Returns the downcasted int24 from int256, reverting on
     * overflow (when the input is less than smallest int24 or
     * greater than largest int24).
     *
     * Counterpart to Solidity's `int24` operator.
     *
     * Requirements:
     *
     * - input must fit into 24 bits
     */
    function toInt24(int256 value) internal pure returns (int24 downcasted) {
        downcasted = int24(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(24, value);
        }
    }

    /**
     * @dev Returns the downcasted int16 from int256, reverting on
     * overflow (when the input is less than smallest int16 or
     * greater than largest int16).
     *
     * Counterpart to Solidity's `int16` operator.
     *
     * Requirements:
     *
     * - input must fit into 16 bits
     */
    function toInt16(int256 value) internal pure returns (int16 downcasted) {
        downcasted = int16(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(16, value);
        }
    }

    /**
     * @dev Returns the downcasted int8 from int256, reverting on
     * overflow (when the input is less than smallest int8 or
     * greater than largest int8).
     *
     * Counterpart to Solidity's `int8` operator.
     *
     * Requirements:
     *
     * - input must fit into 8 bits
     */
    function toInt8(int256 value) internal pure returns (int8 downcasted) {
        downcasted = int8(value);
        if (downcasted != value) {
            revert SafeCastOverflowedIntDowncast(8, value);
        }
    }

    /**
     * @dev Converts an unsigned uint256 into a signed int256.
     *
     * Requirements:
     *
     * - input must be less than or equal to maxInt256.
     */
    function toInt256(uint256 value) internal pure returns (int256) {
        // Note: Unsafe cast below is okay because `type(int256).max` is guaranteed to be positive
        if (value > uint256(type(int256).max)) {
            revert SafeCastOverflowedUintToInt(value);
        }
        return int256(value);
    }

    /**
     * @dev Cast a boolean (false or true) to a uint256 (0 or 1) with no jump.
     */
    function toUint(bool b) internal pure returns (uint256 u) {
        assembly ("memory-safe") {
            u := iszero(iszero(b))
        }
    }
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.1.0) (utils/math/SignedMath.sol)

pragma solidity ^0.8.20;

import {SafeCast} from "./SafeCast.sol";

/**
 * @dev Standard signed math utilities missing in the Solidity language.
 */
library SignedMath {
    /**
     * @dev Branchless ternary evaluation for `a ? b : c`. Gas costs are constant.
     *
     * IMPORTANT: This function may reduce bytecode size and consume less gas when used standalone.
     * However, the compiler may optimize Solidity ternary operations (i.e. `a ? b : c`) to only compute
     * one branch when needed, making this function more expensive.
     */
    function ternary(bool condition, int256 a, int256 b) internal pure returns (int256) {
        unchecked {
            // branchless ternary works because:
            // b ^ (a ^ b) == a
            // b ^ 0 == b
            return b ^ ((a ^ b) * int256(SafeCast.toUint(condition)));
        }
    }

    /**
     * @dev Returns the largest of two signed numbers.
     */
    function max(int256 a, int256 b) internal pure returns (int256) {
        return ternary(a > b, a, b);
    }

    /**
     * @dev Returns the smallest of two signed numbers.
     */
    function min(int256 a, int256 b) internal pure returns (int256) {
        return ternary(a < b, a, b);
    }

    /**
     * @dev Returns the average of two signed numbers without overflow.
     * The result is rounded towards zero.
     */
    function average(int256 a, int256 b) internal pure returns (int256) {
        // Formula from the book "Hacker's Delight"
        int256 x = (a & b) + ((a ^ b) >> 1);
        return x + (int256(uint256(x) >> 255) & (a ^ b));
    }

    /**
     * @dev Returns the absolute unsigned value of a signed value.
     */
    function abs(int256 n) internal pure returns (uint256) {
        unchecked {
            // Formula from the "Bit Twiddling Hacks" by Sean Eron Anderson.
            // Since `n` is a signed integer, the generated bytecode will use the SAR opcode to perform the right shift,
            // taking advantage of the most significant (or "sign" bit) in two's complement representation.
            // This opcode adds new most significant bits set to the value of the previous most significant bit. As a result,
            // the mask will either be `bytes32(0)` (if n is positive) or `~bytes32(0)` (if n is negative).
            int256 mask = n >> 255;

            // A `bytes32(0)` mask leaves the input unchanged, while a `~bytes32(0)` mask complements it.
            return uint256((n + mask) ^ mask);
        }
    }
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.1.0) (utils/Panic.sol)

pragma solidity ^0.8.20;

/**
 * @dev Helper library for emitting standardized panic codes.
 *
 * ```solidity
 * contract Example {
 *      using Panic for uint256;
 *
 *      // Use any of the declared internal constants
 *      function foo() { Panic.GENERIC.panic(); }
 *
 *      // Alternatively
 *      function foo() { Panic.panic(Panic.GENERIC); }
 * }
 * ```
 *
 * Follows the list from https://github.com/ethereum/solidity/blob/v0.8.24/libsolutil/ErrorCodes.h[libsolutil].
 *
 * _Available since v5.1._
 */
// slither-disable-next-line unused-state
library Panic {
    /// @dev generic / unspecified error
    uint256 internal constant GENERIC = 0x00;
    /// @dev used by the assert() builtin
    uint256 internal constant ASSERT = 0x01;
    /// @dev arithmetic underflow or overflow
    uint256 internal constant UNDER_OVERFLOW = 0x11;
    /// @dev division or modulo by zero
    uint256 internal constant DIVISION_BY_ZERO = 0x12;
    /// @dev enum conversion error
    uint256 internal constant ENUM_CONVERSION_ERROR = 0x21;
    /// @dev invalid encoding in storage
    uint256 internal constant STORAGE_ENCODING_ERROR = 0x22;
    /// @dev empty array pop
    uint256 internal constant EMPTY_ARRAY_POP = 0x31;
    /// @dev array out of bounds access
    uint256 internal constant ARRAY_OUT_OF_BOUNDS = 0x32;
    /// @dev resource error (too large allocation or too large array)
    uint256 internal constant RESOURCE_ERROR = 0x41;
    /// @dev calling invalid internal function
    uint256 internal constant INVALID_INTERNAL_FUNCTION = 0x51;

    /// @dev Reverts with a panic code. Recommended to use with
    /// the internal constants with predefined codes.
    function panic(uint256 code) internal pure {
        assembly ("memory-safe") {
            mstore(0x00, 0x4e487b71)
            mstore(0x20, code)
            revert(0x1c, 0x24)
        }
    }
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.3.0) (utils/SlotDerivation.sol)
// This file was procedurally generated from scripts/generate/templates/SlotDerivation.js.

pragma solidity ^0.8.20;

/**
 * @dev Library for computing storage (and transient storage) locations from namespaces and deriving slots
 * corresponding to standard patterns. The derivation method for array and mapping matches the storage layout used by
 * the solidity language / compiler.
 *
 * See https://docs.soliditylang.org/en/v0.8.20/internals/layout_in_storage.html#mappings-and-dynamic-arrays[Solidity docs for mappings and dynamic arrays.].
 *
 * Example usage:
 * ```solidity
 * contract Example {
 *     // Add the library methods
 *     using StorageSlot for bytes32;
 *     using SlotDerivation for bytes32;
 *
 *     // Declare a namespace
 *     string private constant _NAMESPACE = "<namespace>"; // eg. OpenZeppelin.Slot
 *
 *     function setValueInNamespace(uint256 key, address newValue) internal {
 *         _NAMESPACE.erc7201Slot().deriveMapping(key).getAddressSlot().value = newValue;
 *     }
 *
 *     function getValueInNamespace(uint256 key) internal view returns (address) {
 *         return _NAMESPACE.erc7201Slot().deriveMapping(key).getAddressSlot().value;
 *     }
 * }
 * ```
 *
 * TIP: Consider using this library along with {StorageSlot}.
 *
 * NOTE: This library provides a way to manipulate storage locations in a non-standard way. Tooling for checking
 * upgrade safety will ignore the slots accessed through this library.
 *
 * _Available since v5.1._
 */
library SlotDerivation {
    /**
     * @dev Derive an ERC-7201 slot from a string (namespace).
     */
    function erc7201Slot(string memory namespace) internal pure returns (bytes32 slot) {
        assembly ("memory-safe") {
            mstore(0x00, sub(keccak256(add(namespace, 0x20), mload(namespace)), 1))
            slot := and(keccak256(0x00, 0x20), not(0xff))
        }
    }

    /**
     * @dev Add an offset to a slot to get the n-th element of a structure or an array.
     */
    function offset(bytes32 slot, uint256 pos) internal pure returns (bytes32 result) {
        unchecked {
            return bytes32(uint256(slot) + pos);
        }
    }

    /**
     * @dev Derive the location of the first element in an array from the slot where the length is stored.
     */
    function deriveArray(bytes32 slot) internal pure returns (bytes32 result) {
        assembly ("memory-safe") {
            mstore(0x00, slot)
            result := keccak256(0x00, 0x20)
        }
    }

    /**
     * @dev Derive the location of a mapping element from the key.
     */
    function deriveMapping(bytes32 slot, address key) internal pure returns (bytes32 result) {
        assembly ("memory-safe") {
            mstore(0x00, and(key, shr(96, not(0))))
            mstore(0x20, slot)
            result := keccak256(0x00, 0x40)
        }
    }

    /**
     * @dev Derive the location of a mapping element from the key.
     */
    function deriveMapping(bytes32 slot, bool key) internal pure returns (bytes32 result) {
        assembly ("memory-safe") {
            mstore(0x00, iszero(iszero(key)))
            mstore(0x20, slot)
            result := keccak256(0x00, 0x40)
        }
    }

    /**
     * @dev Derive the location of a mapping element from the key.
     */
    function deriveMapping(bytes32 slot, bytes32 key) internal pure returns (bytes32 result) {
        assembly ("memory-safe") {
            mstore(0x00, key)
            mstore(0x20, slot)
            result := keccak256(0x00, 0x40)
        }
    }

    /**
     * @dev Derive the location of a mapping element from the key.
     */
    function deriveMapping(bytes32 slot, uint256 key) internal pure returns (bytes32 result) {
        assembly ("memory-safe") {
            mstore(0x00, key)
            mstore(0x20, slot)
            result := keccak256(0x00, 0x40)
        }
    }

    /**
     * @dev Derive the location of a mapping element from the key.
     */
    function deriveMapping(bytes32 slot, int256 key) internal pure returns (bytes32 result) {
        assembly ("memory-safe") {
            mstore(0x00, key)
            mstore(0x20, slot)
            result := keccak256(0x00, 0x40)
        }
    }

    /**
     * @dev Derive the location of a mapping element from the key.
     */
    function deriveMapping(bytes32 slot, string memory key) internal pure returns (bytes32 result) {
        assembly ("memory-safe") {
            let length := mload(key)
            let begin := add(key, 0x20)
            let end := add(begin, length)
            let cache := mload(end)
            mstore(end, slot)
            result := keccak256(begin, add(length, 0x20))
            mstore(end, cache)
        }
    }

    /**
     * @dev Derive the location of a mapping element from the key.
     */
    function deriveMapping(bytes32 slot, bytes memory key) internal pure returns (bytes32 result) {
        assembly ("memory-safe") {
            let length := mload(key)
            let begin := add(key, 0x20)
            let end := add(begin, length)
            let cache := mload(end)
            mstore(end, slot)
            result := keccak256(begin, add(length, 0x20))
            mstore(end, cache)
        }
    }
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.1.0) (utils/StorageSlot.sol)
// This file was procedurally generated from scripts/generate/templates/StorageSlot.js.

pragma solidity ^0.8.20;

/**
 * @dev Library for reading and writing primitive types to specific storage slots.
 *
 * Storage slots are often used to avoid storage conflict when dealing with upgradeable contracts.
 * This library helps with reading and writing to such slots without the need for inline assembly.
 *
 * The functions in this library return Slot structs that contain a `value` member that can be used to read or write.
 *
 * Example usage to set ERC-1967 implementation slot:
 * ```solidity
 * contract ERC1967 {
 *     // Define the slot. Alternatively, use the SlotDerivation library to derive the slot.
 *     bytes32 internal constant _IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;
 *
 *     function _getImplementation() internal view returns (address) {
 *         return StorageSlot.getAddressSlot(_IMPLEMENTATION_SLOT).value;
 *     }
 *
 *     function _setImplementation(address newImplementation) internal {
 *         require(newImplementation.code.length > 0);
 *         StorageSlot.getAddressSlot(_IMPLEMENTATION_SLOT).value = newImplementation;
 *     }
 * }
 * ```
 *
 * TIP: Consider using this library along with {SlotDerivation}.
 */
library StorageSlot {
    struct AddressSlot {
        address value;
    }

    struct BooleanSlot {
        bool value;
    }

    struct Bytes32Slot {
        bytes32 value;
    }

    struct Uint256Slot {
        uint256 value;
    }

    struct Int256Slot {
        int256 value;
    }

    struct StringSlot {
        string value;
    }

    struct BytesSlot {
        bytes value;
    }

    /**
     * @dev Returns an `AddressSlot` with member `value` located at `slot`.
     */
    function getAddressSlot(bytes32 slot) internal pure returns (AddressSlot storage r) {
        assembly ("memory-safe") {
            r.slot := slot
        }
    }

    /**
     * @dev Returns a `BooleanSlot` with member `value` located at `slot`.
     */
    function getBooleanSlot(bytes32 slot) internal pure returns (BooleanSlot storage r) {
        assembly ("memory-safe") {
            r.slot := slot
        }
    }

    /**
     * @dev Returns a `Bytes32Slot` with member `value` located at `slot`.
     */
    function getBytes32Slot(bytes32 slot) internal pure returns (Bytes32Slot storage r) {
        assembly ("memory-safe") {
            r.slot := slot
        }
    }

    /**
     * @dev Returns a `Uint256Slot` with member `value` located at `slot`.
     */
    function getUint256Slot(bytes32 slot) internal pure returns (Uint256Slot storage r) {
        assembly ("memory-safe") {
            r.slot := slot
        }
    }

    /**
     * @dev Returns a `Int256Slot` with member `value` located at `slot`.
     */
    function getInt256Slot(bytes32 slot) internal pure returns (Int256Slot storage r) {
        assembly ("memory-safe") {
            r.slot := slot
        }
    }

    /**
     * @dev Returns a `StringSlot` with member `value` located at `slot`.
     */
    function getStringSlot(bytes32 slot) internal pure returns (StringSlot storage r) {
        assembly ("memory-safe") {
            r.slot := slot
        }
    }

    /**
     * @dev Returns an `StringSlot` representation of the string storage pointer `store`.
     */
    function getStringSlot(string storage store) internal pure returns (StringSlot storage r) {
        assembly ("memory-safe") {
            r.slot := store.slot
        }
    }

    /**
     * @dev Returns a `BytesSlot` with member `value` located at `slot`.
     */
    function getBytesSlot(bytes32 slot) internal pure returns (BytesSlot storage r) {
        assembly ("memory-safe") {
            r.slot := slot
        }
    }

    /**
     * @dev Returns an `BytesSlot` representation of the bytes storage pointer `store`.
     */
    function getBytesSlot(bytes storage store) internal pure returns (BytesSlot storage r) {
        assembly ("memory-safe") {
            r.slot := store.slot
        }
    }
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.4.0) (utils/Strings.sol)

pragma solidity ^0.8.20;

import {Math} from "./math/Math.sol";
import {SafeCast} from "./math/SafeCast.sol";
import {SignedMath} from "./math/SignedMath.sol";

/**
 * @dev String operations.
 */
library Strings {
    using SafeCast for *;

    bytes16 private constant HEX_DIGITS = "0123456789abcdef";
    uint8 private constant ADDRESS_LENGTH = 20;
    uint256 private constant SPECIAL_CHARS_LOOKUP =
        (1 << 0x08) | // backspace
            (1 << 0x09) | // tab
            (1 << 0x0a) | // newline
            (1 << 0x0c) | // form feed
            (1 << 0x0d) | // carriage return
            (1 << 0x22) | // double quote
            (1 << 0x5c); // backslash

    /**
     * @dev The `value` string doesn't fit in the specified `length`.
     */
    error StringsInsufficientHexLength(uint256 value, uint256 length);

    /**
     * @dev The string being parsed contains characters that are not in scope of the given base.
     */
    error StringsInvalidChar();

    /**
     * @dev The string being parsed is not a properly formatted address.
     */
    error StringsInvalidAddressFormat();

    /**
     * @dev Converts a `uint256` to its ASCII `string` decimal representation.
     */
    function toString(uint256 value) internal pure returns (string memory) {
        unchecked {
            uint256 length = Math.log10(value) + 1;
            string memory buffer = new string(length);
            uint256 ptr;
            assembly ("memory-safe") {
                ptr := add(add(buffer, 0x20), length)
            }
            while (true) {
                ptr--;
                assembly ("memory-safe") {
                    mstore8(ptr, byte(mod(value, 10), HEX_DIGITS))
                }
                value /= 10;
                if (value == 0) break;
            }
            return buffer;
        }
    }

    /**
     * @dev Converts a `int256` to its ASCII `string` decimal representation.
     */
    function toStringSigned(int256 value) internal pure returns (string memory) {
        return string.concat(value < 0 ? "-" : "", toString(SignedMath.abs(value)));
    }

    /**
     * @dev Converts a `uint256` to its ASCII `string` hexadecimal representation.
     */
    function toHexString(uint256 value) internal pure returns (string memory) {
        unchecked {
            return toHexString(value, Math.log256(value) + 1);
        }
    }

    /**
     * @dev Converts a `uint256` to its ASCII `string` hexadecimal representation with fixed length.
     */
    function toHexString(uint256 value, uint256 length) internal pure returns (string memory) {
        uint256 localValue = value;
        bytes memory buffer = new bytes(2 * length + 2);
        buffer[0] = "0";
        buffer[1] = "x";
        for (uint256 i = 2 * length + 1; i > 1; --i) {
            buffer[i] = HEX_DIGITS[localValue & 0xf];
            localValue >>= 4;
        }
        if (localValue != 0) {
            revert StringsInsufficientHexLength(value, length);
        }
        return string(buffer);
    }

    /**
     * @dev Converts an `address` with fixed length of 20 bytes to its not checksummed ASCII `string` hexadecimal
     * representation.
     */
    function toHexString(address addr) internal pure returns (string memory) {
        return toHexString(uint256(uint160(addr)), ADDRESS_LENGTH);
    }

    /**
     * @dev Converts an `address` with fixed length of 20 bytes to its checksummed ASCII `string` hexadecimal
     * representation, according to EIP-55.
     */
    function toChecksumHexString(address addr) internal pure returns (string memory) {
        bytes memory buffer = bytes(toHexString(addr));

        // hash the hex part of buffer (skip length + 2 bytes, length 40)
        uint256 hashValue;
        assembly ("memory-safe") {
            hashValue := shr(96, keccak256(add(buffer, 0x22), 40))
        }

        for (uint256 i = 41; i > 1; --i) {
            // possible values for buffer[i] are 48 (0) to 57 (9) and 97 (a) to 102 (f)
            if (hashValue & 0xf > 7 && uint8(buffer[i]) > 96) {
                // case shift by xoring with 0x20
                buffer[i] ^= 0x20;
            }
            hashValue >>= 4;
        }
        return string(buffer);
    }

    /**
     * @dev Returns true if the two strings are equal.
     */
    function equal(string memory a, string memory b) internal pure returns (bool) {
        return bytes(a).length == bytes(b).length && keccak256(bytes(a)) == keccak256(bytes(b));
    }

    /**
     * @dev Parse a decimal string and returns the value as a `uint256`.
     *
     * Requirements:
     * - The string must be formatted as `[0-9]*`
     * - The result must fit into an `uint256` type
     */
    function parseUint(string memory input) internal pure returns (uint256) {
        return parseUint(input, 0, bytes(input).length);
    }

    /**
     * @dev Variant of {parseUint-string} that parses a substring of `input` located between position `begin` (included) and
     * `end` (excluded).
     *
     * Requirements:
     * - The substring must be formatted as `[0-9]*`
     * - The result must fit into an `uint256` type
     */
    function parseUint(string memory input, uint256 begin, uint256 end) internal pure returns (uint256) {
        (bool success, uint256 value) = tryParseUint(input, begin, end);
        if (!success) revert StringsInvalidChar();
        return value;
    }

    /**
     * @dev Variant of {parseUint-string} that returns false if the parsing fails because of an invalid character.
     *
     * NOTE: This function will revert if the result does not fit in a `uint256`.
     */
    function tryParseUint(string memory input) internal pure returns (bool success, uint256 value) {
        return _tryParseUintUncheckedBounds(input, 0, bytes(input).length);
    }

    /**
     * @dev Variant of {parseUint-string-uint256-uint256} that returns false if the parsing fails because of an invalid
     * character.
     *
     * NOTE: This function will revert if the result does not fit in a `uint256`.
     */
    function tryParseUint(
        string memory input,
        uint256 begin,
        uint256 end
    ) internal pure returns (bool success, uint256 value) {
        if (end > bytes(input).length || begin > end) return (false, 0);
        return _tryParseUintUncheckedBounds(input, begin, end);
    }

    /**
     * @dev Implementation of {tryParseUint-string-uint256-uint256} that does not check bounds. Caller should make sure that
     * `begin <= end <= input.length`. Other inputs would result in undefined behavior.
     */
    function _tryParseUintUncheckedBounds(
        string memory input,
        uint256 begin,
        uint256 end
    ) private pure returns (bool success, uint256 value) {
        bytes memory buffer = bytes(input);

        uint256 result = 0;
        for (uint256 i = begin; i < end; ++i) {
            uint8 chr = _tryParseChr(bytes1(_unsafeReadBytesOffset(buffer, i)));
            if (chr > 9) return (false, 0);
            result *= 10;
            result += chr;
        }
        return (true, result);
    }

    /**
     * @dev Parse a decimal string and returns the value as a `int256`.
     *
     * Requirements:
     * - The string must be formatted as `[-+]?[0-9]*`
     * - The result must fit in an `int256` type.
     */
    function parseInt(string memory input) internal pure returns (int256) {
        return parseInt(input, 0, bytes(input).length);
    }

    /**
     * @dev Variant of {parseInt-string} that parses a substring of `input` located between position `begin` (included) and
     * `end` (excluded).
     *
     * Requirements:
     * - The substring must be formatted as `[-+]?[0-9]*`
     * - The result must fit in an `int256` type.
     */
    function parseInt(string memory input, uint256 begin, uint256 end) internal pure returns (int256) {
        (bool success, int256 value) = tryParseInt(input, begin, end);
        if (!success) revert StringsInvalidChar();
        return value;
    }

    /**
     * @dev Variant of {parseInt-string} that returns false if the parsing fails because of an invalid character or if
     * the result does not fit in a `int256`.
     *
     * NOTE: This function will revert if the absolute value of the result does not fit in a `uint256`.
     */
    function tryParseInt(string memory input) internal pure returns (bool success, int256 value) {
        return _tryParseIntUncheckedBounds(input, 0, bytes(input).length);
    }

    uint256 private constant ABS_MIN_INT256 = 2 ** 255;

    /**
     * @dev Variant of {parseInt-string-uint256-uint256} that returns false if the parsing fails because of an invalid
     * character or if the result does not fit in a `int256`.
     *
     * NOTE: This function will revert if the absolute value of the result does not fit in a `uint256`.
     */
    function tryParseInt(
        string memory input,
        uint256 begin,
        uint256 end
    ) internal pure returns (bool success, int256 value) {
        if (end > bytes(input).length || begin > end) return (false, 0);
        return _tryParseIntUncheckedBounds(input, begin, end);
    }

    /**
     * @dev Implementation of {tryParseInt-string-uint256-uint256} that does not check bounds. Caller should make sure that
     * `begin <= end <= input.length`. Other inputs would result in undefined behavior.
     */
    function _tryParseIntUncheckedBounds(
        string memory input,
        uint256 begin,
        uint256 end
    ) private pure returns (bool success, int256 value) {
        bytes memory buffer = bytes(input);

        // Check presence of a negative sign.
        bytes1 sign = begin == end ? bytes1(0) : bytes1(_unsafeReadBytesOffset(buffer, begin)); // don't do out-of-bound (possibly unsafe) read if sub-string is empty
        bool positiveSign = sign == bytes1("+");
        bool negativeSign = sign == bytes1("-");
        uint256 offset = (positiveSign || negativeSign).toUint();

        (bool absSuccess, uint256 absValue) = tryParseUint(input, begin + offset, end);

        if (absSuccess && absValue < ABS_MIN_INT256) {
            return (true, negativeSign ? -int256(absValue) : int256(absValue));
        } else if (absSuccess && negativeSign && absValue == ABS_MIN_INT256) {
            return (true, type(int256).min);
        } else return (false, 0);
    }

    /**
     * @dev Parse a hexadecimal string (with or without "0x" prefix), and returns the value as a `uint256`.
     *
     * Requirements:
     * - The string must be formatted as `(0x)?[0-9a-fA-F]*`
     * - The result must fit in an `uint256` type.
     */
    function parseHexUint(string memory input) internal pure returns (uint256) {
        return parseHexUint(input, 0, bytes(input).length);
    }

    /**
     * @dev Variant of {parseHexUint-string} that parses a substring of `input` located between position `begin` (included) and
     * `end` (excluded).
     *
     * Requirements:
     * - The substring must be formatted as `(0x)?[0-9a-fA-F]*`
     * - The result must fit in an `uint256` type.
     */
    function parseHexUint(string memory input, uint256 begin, uint256 end) internal pure returns (uint256) {
        (bool success, uint256 value) = tryParseHexUint(input, begin, end);
        if (!success) revert StringsInvalidChar();
        return value;
    }

    /**
     * @dev Variant of {parseHexUint-string} that returns false if the parsing fails because of an invalid character.
     *
     * NOTE: This function will revert if the result does not fit in a `uint256`.
     */
    function tryParseHexUint(string memory input) internal pure returns (bool success, uint256 value) {
        return _tryParseHexUintUncheckedBounds(input, 0, bytes(input).length);
    }

    /**
     * @dev Variant of {parseHexUint-string-uint256-uint256} that returns false if the parsing fails because of an
     * invalid character.
     *
     * NOTE: This function will revert if the result does not fit in a `uint256`.
     */
    function tryParseHexUint(
        string memory input,
        uint256 begin,
        uint256 end
    ) internal pure returns (bool success, uint256 value) {
        if (end > bytes(input).length || begin > end) return (false, 0);
        return _tryParseHexUintUncheckedBounds(input, begin, end);
    }

    /**
     * @dev Implementation of {tryParseHexUint-string-uint256-uint256} that does not check bounds. Caller should make sure that
     * `begin <= end <= input.length`. Other inputs would result in undefined behavior.
     */
    function _tryParseHexUintUncheckedBounds(
        string memory input,
        uint256 begin,
        uint256 end
    ) private pure returns (bool success, uint256 value) {
        bytes memory buffer = bytes(input);

        // skip 0x prefix if present
        bool hasPrefix = (end > begin + 1) && bytes2(_unsafeReadBytesOffset(buffer, begin)) == bytes2("0x"); // don't do out-of-bound (possibly unsafe) read if sub-string is empty
        uint256 offset = hasPrefix.toUint() * 2;

        uint256 result = 0;
        for (uint256 i = begin + offset; i < end; ++i) {
            uint8 chr = _tryParseChr(bytes1(_unsafeReadBytesOffset(buffer, i)));
            if (chr > 15) return (false, 0);
            result *= 16;
            unchecked {
                // Multiplying by 16 is equivalent to a shift of 4 bits (with additional overflow check).
                // This guarantees that adding a value < 16 will not cause an overflow, hence the unchecked.
                result += chr;
            }
        }
        return (true, result);
    }

    /**
     * @dev Parse a hexadecimal string (with or without "0x" prefix), and returns the value as an `address`.
     *
     * Requirements:
     * - The string must be formatted as `(0x)?[0-9a-fA-F]{40}`
     */
    function parseAddress(string memory input) internal pure returns (address) {
        return parseAddress(input, 0, bytes(input).length);
    }

    /**
     * @dev Variant of {parseAddress-string} that parses a substring of `input` located between position `begin` (included) and
     * `end` (excluded).
     *
     * Requirements:
     * - The substring must be formatted as `(0x)?[0-9a-fA-F]{40}`
     */
    function parseAddress(string memory input, uint256 begin, uint256 end) internal pure returns (address) {
        (bool success, address value) = tryParseAddress(input, begin, end);
        if (!success) revert StringsInvalidAddressFormat();
        return value;
    }

    /**
     * @dev Variant of {parseAddress-string} that returns false if the parsing fails because the input is not a properly
     * formatted address. See {parseAddress-string} requirements.
     */
    function tryParseAddress(string memory input) internal pure returns (bool success, address value) {
        return tryParseAddress(input, 0, bytes(input).length);
    }

    /**
     * @dev Variant of {parseAddress-string-uint256-uint256} that returns false if the parsing fails because input is not a properly
     * formatted address. See {parseAddress-string-uint256-uint256} requirements.
     */
    function tryParseAddress(
        string memory input,
        uint256 begin,
        uint256 end
    ) internal pure returns (bool success, address value) {
        if (end > bytes(input).length || begin > end) return (false, address(0));

        bool hasPrefix = (end > begin + 1) && bytes2(_unsafeReadBytesOffset(bytes(input), begin)) == bytes2("0x"); // don't do out-of-bound (possibly unsafe) read if sub-string is empty
        uint256 expectedLength = 40 + hasPrefix.toUint() * 2;

        // check that input is the correct length
        if (end - begin == expectedLength) {
            // length guarantees that this does not overflow, and value is at most type(uint160).max
            (bool s, uint256 v) = _tryParseHexUintUncheckedBounds(input, begin, end);
            return (s, address(uint160(v)));
        } else {
            return (false, address(0));
        }
    }

    function _tryParseChr(bytes1 chr) private pure returns (uint8) {
        uint8 value = uint8(chr);

        // Try to parse `chr`:
        // - Case 1: [0-9]
        // - Case 2: [a-f]
        // - Case 3: [A-F]
        // - otherwise not supported
        unchecked {
            if (value > 47 && value < 58) value -= 48;
            else if (value > 96 && value < 103) value -= 87;
            else if (value > 64 && value < 71) value -= 55;
            else return type(uint8).max;
        }

        return value;
    }

    /**
     * @dev Escape special characters in JSON strings. This can be useful to prevent JSON injection in NFT metadata.
     *
     * WARNING: This function should only be used in double quoted JSON strings. Single quotes are not escaped.
     *
     * NOTE: This function escapes all unicode characters, and not just the ones in ranges defined in section 2.5 of
     * RFC-4627 (U+0000 to U+001F, U+0022 and U+005C). ECMAScript's `JSON.parse` does recover escaped unicode
     * characters that are not in this range, but other tooling may provide different results.
     */
    function escapeJSON(string memory input) internal pure returns (string memory) {
        bytes memory buffer = bytes(input);
        bytes memory output = new bytes(2 * buffer.length); // worst case scenario
        uint256 outputLength = 0;

        for (uint256 i; i < buffer.length; ++i) {
            bytes1 char = bytes1(_unsafeReadBytesOffset(buffer, i));
            if (((SPECIAL_CHARS_LOOKUP & (1 << uint8(char))) != 0)) {
                output[outputLength++] = "\\";
                if (char == 0x08) output[outputLength++] = "b";
                else if (char == 0x09) output[outputLength++] = "t";
                else if (char == 0x0a) output[outputLength++] = "n";
                else if (char == 0x0c) output[outputLength++] = "f";
                else if (char == 0x0d) output[outputLength++] = "r";
                else if (char == 0x5c) output[outputLength++] = "\\";
                else if (char == 0x22) {
                    // solhint-disable-next-line quotes
                    output[outputLength++] = '"';
                }
            } else {
                output[outputLength++] = char;
            }
        }
        // write the actual length and deallocate unused memory
        assembly ("memory-safe") {
            mstore(output, outputLength)
            mstore(0x40, add(output, shl(5, shr(5, add(outputLength, 63)))))
        }

        return string(output);
    }

    /**
     * @dev Reads a bytes32 from a bytes array without bounds checking.
     *
     * NOTE: making this function internal would mean it could be used with memory unsafe offset, and marking the
     * assembly block as such would prevent some optimizations.
     */
    function _unsafeReadBytesOffset(bytes memory buffer, uint256 offset) private pure returns (bytes32 value) {
        // This is not memory safe in the general case, but all calls to this private function are within bounds.
        assembly ("memory-safe") {
            value := mload(add(add(buffer, 0x20), offset))
        }
    }
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.4.0) (utils/structs/EnumerableSet.sol)
// This file was procedurally generated from scripts/generate/templates/EnumerableSet.js.

pragma solidity ^0.8.20;

import {Arrays} from "../Arrays.sol";
import {Math} from "../math/Math.sol";

/**
 * @dev Library for managing
 * https://en.wikipedia.org/wiki/Set_(abstract_data_type)[sets] of primitive
 * types.
 *
 * Sets have the following properties:
 *
 * - Elements are added, removed, and checked for existence in constant time
 * (O(1)).
 * - Elements are enumerated in O(n). No guarantees are made on the ordering.
 * - Set can be cleared (all elements removed) in O(n).
 *
 * ```solidity
 * contract Example {
 *     // Add the library methods
 *     using EnumerableSet for EnumerableSet.AddressSet;
 *
 *     // Declare a set state variable
 *     EnumerableSet.AddressSet private mySet;
 * }
 * ```
 *
 * The following types are supported:
 *
 * - `bytes32` (`Bytes32Set`) since v3.3.0
 * - `address` (`AddressSet`) since v3.3.0
 * - `uint256` (`UintSet`) since v3.3.0
 * - `string` (`StringSet`) since v5.4.0
 * - `bytes` (`BytesSet`) since v5.4.0
 *
 * [WARNING]
 * ====
 * Trying to delete such a structure from storage will likely result in data corruption, rendering the structure
 * unusable.
 * See https://github.com/ethereum/solidity/pull/11843[ethereum/solidity#11843] for more info.
 *
 * In order to clean an EnumerableSet, you can either remove all elements one by one or create a fresh instance using an
 * array of EnumerableSet.
 * ====
 */
library EnumerableSet {
    // To implement this library for multiple types with as little code
    // repetition as possible, we write it in terms of a generic Set type with
    // bytes32 values.
    // The Set implementation uses private functions, and user-facing
    // implementations (such as AddressSet) are just wrappers around the
    // underlying Set.
    // This means that we can only create new EnumerableSets for types that fit
    // in bytes32.

    struct Set {
        // Storage of set values
        bytes32[] _values;
        // Position is the index of the value in the `values` array plus 1.
        // Position 0 is used to mean a value is not in the set.
        mapping(bytes32 value => uint256) _positions;
    }

    /**
     * @dev Add a value to a set. O(1).
     *
     * Returns true if the value was added to the set, that is if it was not
     * already present.
     */
    function _add(Set storage set, bytes32 value) private returns (bool) {
        if (!_contains(set, value)) {
            set._values.push(value);
            // The value is stored at length-1, but we add 1 to all indexes
            // and use 0 as a sentinel value
            set._positions[value] = set._values.length;
            return true;
        } else {
            return false;
        }
    }

    /**
     * @dev Removes a value from a set. O(1).
     *
     * Returns true if the value was removed from the set, that is if it was
     * present.
     */
    function _remove(Set storage set, bytes32 value) private returns (bool) {
        // We cache the value's position to prevent multiple reads from the same storage slot
        uint256 position = set._positions[value];

        if (position != 0) {
            // Equivalent to contains(set, value)
            // To delete an element from the _values array in O(1), we swap the element to delete with the last one in
            // the array, and then remove the last element (sometimes called as 'swap and pop').
            // This modifies the order of the array, as noted in {at}.

            uint256 valueIndex = position - 1;
            uint256 lastIndex = set._values.length - 1;

            if (valueIndex != lastIndex) {
                bytes32 lastValue = set._values[lastIndex];

                // Move the lastValue to the index where the value to delete is
                set._values[valueIndex] = lastValue;
                // Update the tracked position of the lastValue (that was just moved)
                set._positions[lastValue] = position;
            }

            // Delete the slot where the moved value was stored
            set._values.pop();

            // Delete the tracked position for the deleted slot
            delete set._positions[value];

            return true;
        } else {
            return false;
        }
    }

    /**
     * @dev Removes all the values from a set. O(n).
     *
     * WARNING: This function has an unbounded cost that scales with set size. Developers should keep in mind that
     * using it may render the function uncallable if the set grows to the point where clearing it consumes too much
     * gas to fit in a block.
     */
    function _clear(Set storage set) private {
        uint256 len = _length(set);
        for (uint256 i = 0; i < len; ++i) {
            delete set._positions[set._values[i]];
        }
        Arrays.unsafeSetLength(set._values, 0);
    }

    /**
     * @dev Returns true if the value is in the set. O(1).
     */
    function _contains(Set storage set, bytes32 value) private view returns (bool) {
        return set._positions[value] != 0;
    }

    /**
     * @dev Returns the number of values on the set. O(1).
     */
    function _length(Set storage set) private view returns (uint256) {
        return set._values.length;
    }

    /**
     * @dev Returns the value stored at position `index` in the set. O(1).
     *
     * Note that there are no guarantees on the ordering of values inside the
     * array, and it may change when more values are added or removed.
     *
     * Requirements:
     *
     * - `index` must be strictly less than {length}.
     */
    function _at(Set storage set, uint256 index) private view returns (bytes32) {
        return set._values[index];
    }

    /**
     * @dev Return the entire set in an array
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function _values(Set storage set) private view returns (bytes32[] memory) {
        return set._values;
    }

    /**
     * @dev Return a slice of the set in an array
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function _values(Set storage set, uint256 start, uint256 end) private view returns (bytes32[] memory) {
        unchecked {
            end = Math.min(end, _length(set));
            start = Math.min(start, end);

            uint256 len = end - start;
            bytes32[] memory result = new bytes32[](len);
            for (uint256 i = 0; i < len; ++i) {
                result[i] = Arrays.unsafeAccess(set._values, start + i).value;
            }
            return result;
        }
    }

    // Bytes32Set

    struct Bytes32Set {
        Set _inner;
    }

    /**
     * @dev Add a value to a set. O(1).
     *
     * Returns true if the value was added to the set, that is if it was not
     * already present.
     */
    function add(Bytes32Set storage set, bytes32 value) internal returns (bool) {
        return _add(set._inner, value);
    }

    /**
     * @dev Removes a value from a set. O(1).
     *
     * Returns true if the value was removed from the set, that is if it was
     * present.
     */
    function remove(Bytes32Set storage set, bytes32 value) internal returns (bool) {
        return _remove(set._inner, value);
    }

    /**
     * @dev Removes all the values from a set. O(n).
     *
     * WARNING: Developers should keep in mind that this function has an unbounded cost and using it may render the
     * function uncallable if the set grows to the point where clearing it consumes too much gas to fit in a block.
     */
    function clear(Bytes32Set storage set) internal {
        _clear(set._inner);
    }

    /**
     * @dev Returns true if the value is in the set. O(1).
     */
    function contains(Bytes32Set storage set, bytes32 value) internal view returns (bool) {
        return _contains(set._inner, value);
    }

    /**
     * @dev Returns the number of values in the set. O(1).
     */
    function length(Bytes32Set storage set) internal view returns (uint256) {
        return _length(set._inner);
    }

    /**
     * @dev Returns the value stored at position `index` in the set. O(1).
     *
     * Note that there are no guarantees on the ordering of values inside the
     * array, and it may change when more values are added or removed.
     *
     * Requirements:
     *
     * - `index` must be strictly less than {length}.
     */
    function at(Bytes32Set storage set, uint256 index) internal view returns (bytes32) {
        return _at(set._inner, index);
    }

    /**
     * @dev Return the entire set in an array
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function values(Bytes32Set storage set) internal view returns (bytes32[] memory) {
        bytes32[] memory store = _values(set._inner);
        bytes32[] memory result;

        assembly ("memory-safe") {
            result := store
        }

        return result;
    }

    /**
     * @dev Return a slice of the set in an array
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function values(Bytes32Set storage set, uint256 start, uint256 end) internal view returns (bytes32[] memory) {
        bytes32[] memory store = _values(set._inner, start, end);
        bytes32[] memory result;

        assembly ("memory-safe") {
            result := store
        }

        return result;
    }

    // AddressSet

    struct AddressSet {
        Set _inner;
    }

    /**
     * @dev Add a value to a set. O(1).
     *
     * Returns true if the value was added to the set, that is if it was not
     * already present.
     */
    function add(AddressSet storage set, address value) internal returns (bool) {
        return _add(set._inner, bytes32(uint256(uint160(value))));
    }

    /**
     * @dev Removes a value from a set. O(1).
     *
     * Returns true if the value was removed from the set, that is if it was
     * present.
     */
    function remove(AddressSet storage set, address value) internal returns (bool) {
        return _remove(set._inner, bytes32(uint256(uint160(value))));
    }

    /**
     * @dev Removes all the values from a set. O(n).
     *
     * WARNING: Developers should keep in mind that this function has an unbounded cost and using it may render the
     * function uncallable if the set grows to the point where clearing it consumes too much gas to fit in a block.
     */
    function clear(AddressSet storage set) internal {
        _clear(set._inner);
    }

    /**
     * @dev Returns true if the value is in the set. O(1).
     */
    function contains(AddressSet storage set, address value) internal view returns (bool) {
        return _contains(set._inner, bytes32(uint256(uint160(value))));
    }

    /**
     * @dev Returns the number of values in the set. O(1).
     */
    function length(AddressSet storage set) internal view returns (uint256) {
        return _length(set._inner);
    }

    /**
     * @dev Returns the value stored at position `index` in the set. O(1).
     *
     * Note that there are no guarantees on the ordering of values inside the
     * array, and it may change when more values are added or removed.
     *
     * Requirements:
     *
     * - `index` must be strictly less than {length}.
     */
    function at(AddressSet storage set, uint256 index) internal view returns (address) {
        return address(uint160(uint256(_at(set._inner, index))));
    }

    /**
     * @dev Return the entire set in an array
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function values(AddressSet storage set) internal view returns (address[] memory) {
        bytes32[] memory store = _values(set._inner);
        address[] memory result;

        assembly ("memory-safe") {
            result := store
        }

        return result;
    }

    /**
     * @dev Return a slice of the set in an array
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function values(AddressSet storage set, uint256 start, uint256 end) internal view returns (address[] memory) {
        bytes32[] memory store = _values(set._inner, start, end);
        address[] memory result;

        assembly ("memory-safe") {
            result := store
        }

        return result;
    }

    // UintSet

    struct UintSet {
        Set _inner;
    }

    /**
     * @dev Add a value to a set. O(1).
     *
     * Returns true if the value was added to the set, that is if it was not
     * already present.
     */
    function add(UintSet storage set, uint256 value) internal returns (bool) {
        return _add(set._inner, bytes32(value));
    }

    /**
     * @dev Removes a value from a set. O(1).
     *
     * Returns true if the value was removed from the set, that is if it was
     * present.
     */
    function remove(UintSet storage set, uint256 value) internal returns (bool) {
        return _remove(set._inner, bytes32(value));
    }

    /**
     * @dev Removes all the values from a set. O(n).
     *
     * WARNING: Developers should keep in mind that this function has an unbounded cost and using it may render the
     * function uncallable if the set grows to the point where clearing it consumes too much gas to fit in a block.
     */
    function clear(UintSet storage set) internal {
        _clear(set._inner);
    }

    /**
     * @dev Returns true if the value is in the set. O(1).
     */
    function contains(UintSet storage set, uint256 value) internal view returns (bool) {
        return _contains(set._inner, bytes32(value));
    }

    /**
     * @dev Returns the number of values in the set. O(1).
     */
    function length(UintSet storage set) internal view returns (uint256) {
        return _length(set._inner);
    }

    /**
     * @dev Returns the value stored at position `index` in the set. O(1).
     *
     * Note that there are no guarantees on the ordering of values inside the
     * array, and it may change when more values are added or removed.
     *
     * Requirements:
     *
     * - `index` must be strictly less than {length}.
     */
    function at(UintSet storage set, uint256 index) internal view returns (uint256) {
        return uint256(_at(set._inner, index));
    }

    /**
     * @dev Return the entire set in an array
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function values(UintSet storage set) internal view returns (uint256[] memory) {
        bytes32[] memory store = _values(set._inner);
        uint256[] memory result;

        assembly ("memory-safe") {
            result := store
        }

        return result;
    }

    /**
     * @dev Return a slice of the set in an array
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function values(UintSet storage set, uint256 start, uint256 end) internal view returns (uint256[] memory) {
        bytes32[] memory store = _values(set._inner, start, end);
        uint256[] memory result;

        assembly ("memory-safe") {
            result := store
        }

        return result;
    }

    struct StringSet {
        // Storage of set values
        string[] _values;
        // Position is the index of the value in the `values` array plus 1.
        // Position 0 is used to mean a value is not in the set.
        mapping(string value => uint256) _positions;
    }

    /**
     * @dev Add a value to a set. O(1).
     *
     * Returns true if the value was added to the set, that is if it was not
     * already present.
     */
    function add(StringSet storage set, string memory value) internal returns (bool) {
        if (!contains(set, value)) {
            set._values.push(value);
            // The value is stored at length-1, but we add 1 to all indexes
            // and use 0 as a sentinel value
            set._positions[value] = set._values.length;
            return true;
        } else {
            return false;
        }
    }

    /**
     * @dev Removes a value from a set. O(1).
     *
     * Returns true if the value was removed from the set, that is if it was
     * present.
     */
    function remove(StringSet storage set, string memory value) internal returns (bool) {
        // We cache the value's position to prevent multiple reads from the same storage slot
        uint256 position = set._positions[value];

        if (position != 0) {
            // Equivalent to contains(set, value)
            // To delete an element from the _values array in O(1), we swap the element to delete with the last one in
            // the array, and then remove the last element (sometimes called as 'swap and pop').
            // This modifies the order of the array, as noted in {at}.

            uint256 valueIndex = position - 1;
            uint256 lastIndex = set._values.length - 1;

            if (valueIndex != lastIndex) {
                string memory lastValue = set._values[lastIndex];

                // Move the lastValue to the index where the value to delete is
                set._values[valueIndex] = lastValue;
                // Update the tracked position of the lastValue (that was just moved)
                set._positions[lastValue] = position;
            }

            // Delete the slot where the moved value was stored
            set._values.pop();

            // Delete the tracked position for the deleted slot
            delete set._positions[value];

            return true;
        } else {
            return false;
        }
    }

    /**
     * @dev Removes all the values from a set. O(n).
     *
     * WARNING: Developers should keep in mind that this function has an unbounded cost and using it may render the
     * function uncallable if the set grows to the point where clearing it consumes too much gas to fit in a block.
     */
    function clear(StringSet storage set) internal {
        uint256 len = length(set);
        for (uint256 i = 0; i < len; ++i) {
            delete set._positions[set._values[i]];
        }
        Arrays.unsafeSetLength(set._values, 0);
    }

    /**
     * @dev Returns true if the value is in the set. O(1).
     */
    function contains(StringSet storage set, string memory value) internal view returns (bool) {
        return set._positions[value] != 0;
    }

    /**
     * @dev Returns the number of values on the set. O(1).
     */
    function length(StringSet storage set) internal view returns (uint256) {
        return set._values.length;
    }

    /**
     * @dev Returns the value stored at position `index` in the set. O(1).
     *
     * Note that there are no guarantees on the ordering of values inside the
     * array, and it may change when more values are added or removed.
     *
     * Requirements:
     *
     * - `index` must be strictly less than {length}.
     */
    function at(StringSet storage set, uint256 index) internal view returns (string memory) {
        return set._values[index];
    }

    /**
     * @dev Return the entire set in an array
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function values(StringSet storage set) internal view returns (string[] memory) {
        return set._values;
    }

    /**
     * @dev Return a slice of the set in an array
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function values(StringSet storage set, uint256 start, uint256 end) internal view returns (string[] memory) {
        unchecked {
            end = Math.min(end, length(set));
            start = Math.min(start, end);

            uint256 len = end - start;
            string[] memory result = new string[](len);
            for (uint256 i = 0; i < len; ++i) {
                result[i] = Arrays.unsafeAccess(set._values, start + i).value;
            }
            return result;
        }
    }

    struct BytesSet {
        // Storage of set values
        bytes[] _values;
        // Position is the index of the value in the `values` array plus 1.
        // Position 0 is used to mean a value is not in the set.
        mapping(bytes value => uint256) _positions;
    }

    /**
     * @dev Add a value to a set. O(1).
     *
     * Returns true if the value was added to the set, that is if it was not
     * already present.
     */
    function add(BytesSet storage set, bytes memory value) internal returns (bool) {
        if (!contains(set, value)) {
            set._values.push(value);
            // The value is stored at length-1, but we add 1 to all indexes
            // and use 0 as a sentinel value
            set._positions[value] = set._values.length;
            return true;
        } else {
            return false;
        }
    }

    /**
     * @dev Removes a value from a set. O(1).
     *
     * Returns true if the value was removed from the set, that is if it was
     * present.
     */
    function remove(BytesSet storage set, bytes memory value) internal returns (bool) {
        // We cache the value's position to prevent multiple reads from the same storage slot
        uint256 position = set._positions[value];

        if (position != 0) {
            // Equivalent to contains(set, value)
            // To delete an element from the _values array in O(1), we swap the element to delete with the last one in
            // the array, and then remove the last element (sometimes called as 'swap and pop').
            // This modifies the order of the array, as noted in {at}.

            uint256 valueIndex = position - 1;
            uint256 lastIndex = set._values.length - 1;

            if (valueIndex != lastIndex) {
                bytes memory lastValue = set._values[lastIndex];

                // Move the lastValue to the index where the value to delete is
                set._values[valueIndex] = lastValue;
                // Update the tracked position of the lastValue (that was just moved)
                set._positions[lastValue] = position;
            }

            // Delete the slot where the moved value was stored
            set._values.pop();

            // Delete the tracked position for the deleted slot
            delete set._positions[value];

            return true;
        } else {
            return false;
        }
    }

    /**
     * @dev Removes all the values from a set. O(n).
     *
     * WARNING: Developers should keep in mind that this function has an unbounded cost and using it may render the
     * function uncallable if the set grows to the point where clearing it consumes too much gas to fit in a block.
     */
    function clear(BytesSet storage set) internal {
        uint256 len = length(set);
        for (uint256 i = 0; i < len; ++i) {
            delete set._positions[set._values[i]];
        }
        Arrays.unsafeSetLength(set._values, 0);
    }

    /**
     * @dev Returns true if the value is in the set. O(1).
     */
    function contains(BytesSet storage set, bytes memory value) internal view returns (bool) {
        return set._positions[value] != 0;
    }

    /**
     * @dev Returns the number of values on the set. O(1).
     */
    function length(BytesSet storage set) internal view returns (uint256) {
        return set._values.length;
    }

    /**
     * @dev Returns the value stored at position `index` in the set. O(1).
     *
     * Note that there are no guarantees on the ordering of values inside the
     * array, and it may change when more values are added or removed.
     *
     * Requirements:
     *
     * - `index` must be strictly less than {length}.
     */
    function at(BytesSet storage set, uint256 index) internal view returns (bytes memory) {
        return set._values[index];
    }

    /**
     * @dev Return the entire set in an array
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function values(BytesSet storage set) internal view returns (bytes[] memory) {
        return set._values;
    }

    /**
     * @dev Return a slice of the set in an array
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function values(BytesSet storage set, uint256 start, uint256 end) internal view returns (bytes[] memory) {
        unchecked {
            end = Math.min(end, length(set));
            start = Math.min(start, end);

            uint256 len = end - start;
            bytes[] memory result = new bytes[](len);
            for (uint256 i = 0; i < len; ++i) {
                result[i] = Arrays.unsafeAccess(set._values, start + i).value;
            }
            return result;
        }
    }
}

// GENERATED FILE - DO NOT EDIT, RUN yarn remake-constants in yarn-project/constants
// SPDX-License-Identifier: Apache-2.0
// Copyright 2023 Aztec Labs.
pragma solidity >=0.8.27;

/**
 * @title Constants Library
 * @author Aztec Labs
 * @notice Library that contains constants used throughout the Aztec protocol
 */
library Constants {
  // Prime field modulus
  uint256 internal constant P =
    21888242871839275222246405745257275088548364400416034343698204186575808495617;

  uint256 internal constant MAX_FIELD_VALUE =
    21888242871839275222246405745257275088548364400416034343698204186575808495616;
  uint256 internal constant ARGS_LENGTH = 16;
  uint256 internal constant MAX_FR_CALLDATA_TO_ALL_ENQUEUED_CALLS = 16000;
  uint256 internal constant MAX_NOTE_HASHES_PER_CALL = 16;
  uint256 internal constant MAX_NULLIFIERS_PER_CALL = 16;
  uint256 internal constant MAX_PRIVATE_CALL_STACK_LENGTH_PER_CALL = 5;
  uint256 internal constant MAX_ENQUEUED_CALLS_PER_CALL = 16;
  uint256 internal constant MAX_L2_TO_L1_MSGS_PER_CALL = 2;
  uint256 internal constant MAX_PUBLIC_DATA_UPDATE_REQUESTS_PER_CALL = 63;
  uint256 internal constant MAX_PUBLIC_DATA_READS_PER_CALL = 64;
  uint256 internal constant MAX_NOTE_HASH_READ_REQUESTS_PER_CALL = 16;
  uint256 internal constant MAX_NULLIFIER_READ_REQUESTS_PER_CALL = 16;
  uint256 internal constant MAX_NULLIFIER_NON_EXISTENT_READ_REQUESTS_PER_CALL = 16;
  uint256 internal constant MAX_L1_TO_L2_MSG_READ_REQUESTS_PER_CALL = 16;
  uint256 internal constant MAX_KEY_VALIDATION_REQUESTS_PER_CALL = 16;
  uint256 internal constant MAX_PRIVATE_LOGS_PER_CALL = 16;
  uint256 internal constant MAX_PUBLIC_LOGS_PER_CALL = 4;
  uint256 internal constant MAX_CONTRACT_CLASS_LOGS_PER_CALL = 1;
  uint256 internal constant ARCHIVE_HEIGHT = 29;
  uint256 internal constant VK_TREE_HEIGHT = 6;
  uint256 internal constant PROTOCOL_CONTRACT_TREE_HEIGHT = 3;
  uint256 internal constant FUNCTION_TREE_HEIGHT = 5;
  uint256 internal constant NOTE_HASH_TREE_HEIGHT = 40;
  uint256 internal constant PUBLIC_DATA_TREE_HEIGHT = 40;
  uint256 internal constant NULLIFIER_TREE_HEIGHT = 40;
  uint256 internal constant L1_TO_L2_MSG_TREE_HEIGHT = 39;
  uint256 internal constant ARTIFACT_FUNCTION_TREE_MAX_HEIGHT = 5;
  uint256 internal constant NULLIFIER_TREE_ID = 0;
  uint256 internal constant NOTE_HASH_TREE_ID = 1;
  uint256 internal constant PUBLIC_DATA_TREE_ID = 2;
  uint256 internal constant L1_TO_L2_MESSAGE_TREE_ID = 3;
  uint256 internal constant ARCHIVE_TREE_ID = 4;
  uint256 internal constant NOTE_HASH_SUBTREE_HEIGHT = 6;
  uint256 internal constant NULLIFIER_SUBTREE_HEIGHT = 6;
  uint256 internal constant PUBLIC_DATA_SUBTREE_HEIGHT = 6;
  uint256 internal constant L1_TO_L2_MSG_SUBTREE_HEIGHT = 4;
  uint256 internal constant NOTE_HASH_SUBTREE_SIBLING_PATH_LENGTH = 34;
  uint256 internal constant NULLIFIER_SUBTREE_SIBLING_PATH_LENGTH = 34;
  uint256 internal constant L1_TO_L2_MSG_SUBTREE_SIBLING_PATH_LENGTH = 35;
  uint256 internal constant MAX_NOTE_HASHES_PER_TX = 64;
  uint256 internal constant MAX_NULLIFIERS_PER_TX = 64;
  uint256 internal constant MAX_PRIVATE_CALL_STACK_LENGTH_PER_TX = 8;
  uint256 internal constant MAX_ENQUEUED_CALLS_PER_TX = 32;
  uint256 internal constant PROTOCOL_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX = 1;
  uint256 internal constant MAX_TOTAL_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX = 64;
  uint256 internal constant MAX_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX = 63;
  uint256 internal constant MAX_PUBLIC_DATA_READS_PER_TX = 64;
  uint256 internal constant MAX_L2_TO_L1_MSGS_PER_TX = 8;
  uint256 internal constant MAX_NOTE_HASH_READ_REQUESTS_PER_TX = 64;
  uint256 internal constant MAX_NULLIFIER_READ_REQUESTS_PER_TX = 64;
  uint256 internal constant MAX_NULLIFIER_NON_EXISTENT_READ_REQUESTS_PER_TX = 64;
  uint256 internal constant MAX_L1_TO_L2_MSG_READ_REQUESTS_PER_TX = 64;
  uint256 internal constant MAX_KEY_VALIDATION_REQUESTS_PER_TX = 64;
  uint256 internal constant MAX_PRIVATE_LOGS_PER_TX = 32;
  uint256 internal constant MAX_PUBLIC_LOGS_PER_TX = 8;
  uint256 internal constant MAX_CONTRACT_CLASS_LOGS_PER_TX = 1;
  uint256 internal constant NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP = 16;
  uint256 internal constant PRIVATE_KERNEL_INIT_INDEX = 0;
  uint256 internal constant PRIVATE_KERNEL_INNER_INDEX = 1;
  uint256 internal constant PRIVATE_KERNEL_TAIL_INDEX = 2;
  uint256 internal constant PRIVATE_KERNEL_TAIL_TO_PUBLIC_INDEX = 3;
  uint256 internal constant TUBE_VK_INDEX = 4;
  uint256 internal constant PRIVATE_BASE_ROLLUP_VK_INDEX = 6;
  uint256 internal constant PUBLIC_BASE_ROLLUP_VK_INDEX = 7;
  uint256 internal constant MERGE_ROLLUP_INDEX = 8;
  uint256 internal constant BLOCK_ROOT_ROLLUP_INDEX = 9;
  uint256 internal constant BLOCK_ROOT_ROLLUP_SINGLE_TX_INDEX = 10;
  uint256 internal constant BLOCK_ROOT_ROLLUP_EMPTY_INDEX = 11;
  uint256 internal constant BLOCK_MERGE_ROLLUP_INDEX = 12;
  uint256 internal constant ROOT_ROLLUP_INDEX = 13;
  uint256 internal constant BASE_PARITY_INDEX = 14;
  uint256 internal constant ROOT_PARITY_INDEX = 15;
  uint256 internal constant PRIVATE_KERNEL_RESET_INDEX = 20;
  uint256 internal constant FUNCTION_SELECTOR_NUM_BYTES = 4;
  uint256 internal constant INITIALIZATION_SLOT_SEPARATOR = 1000000000;
  uint256 internal constant INITIAL_L2_BLOCK_NUM = 1;
  uint256 internal constant FIELDS_PER_BLOB = 4096;
  uint256 internal constant BLOBS_PER_BLOCK = 3;
  uint256 internal constant PUBLIC_LOG_DATA_SIZE_IN_FIELDS = 13;
  uint256 internal constant PUBLIC_LOG_SIZE_IN_FIELDS = 14;
  uint256 internal constant PRIVATE_LOG_SIZE_IN_FIELDS = 18;
  uint256 internal constant AZTEC_MAX_EPOCH_DURATION = 48;
  uint256 internal constant GENESIS_BLOCK_HASH =
    20646204262468251631976884937192820660867507115079672078981654411421834866549;
  uint256 internal constant GENESIS_ARCHIVE_ROOT =
    1002640778211850180189505934749257244705296832326768971348723156503780793518;
  uint256 internal constant FEE_JUICE_INITIAL_MINT = 200000000000000000000000;
  uint256 internal constant PUBLIC_DISPATCH_SELECTOR = 3578010381;
  uint256 internal constant MAX_PACKED_PUBLIC_BYTECODE_SIZE_IN_FIELDS = 3000;
  uint256 internal constant MAX_PACKED_BYTECODE_SIZE_PER_PRIVATE_FUNCTION_IN_FIELDS = 3000;
  uint256 internal constant MAX_PACKED_BYTECODE_SIZE_PER_UNCONSTRAINED_FUNCTION_IN_FIELDS = 3000;
  uint256 internal constant REGISTERER_PRIVATE_FUNCTION_BROADCASTED_ADDITIONAL_FIELDS = 19;
  uint256 internal constant REGISTERER_UNCONSTRAINED_FUNCTION_BROADCASTED_ADDITIONAL_FIELDS = 12;
  uint256 internal constant REGISTERER_CONTRACT_CLASS_REGISTERED_MAGIC_VALUE =
    11121068431693264234253912047066709627593769337094408533543930778360;
  uint256 internal constant REGISTERER_PRIVATE_FUNCTION_BROADCASTED_MAGIC_VALUE =
    2889881020989534926461066592611988634597302675057895885580456197069;
  uint256 internal constant REGISTERER_UNCONSTRAINED_FUNCTION_BROADCASTED_MAGIC_VALUE =
    24399338136397901754495080759185489776044879232766421623673792970137;
  uint256 internal constant DEPLOYER_CONTRACT_INSTANCE_DEPLOYED_MAGIC_VALUE =
    14061769416655647708490531650437236735160113654556896985372298487345;
  uint256 internal constant DEPLOYER_CONTRACT_INSTANCE_UPDATED_MAGIC_VALUE =
    1534834688047131268740281708431107902615560100979874281215533519862;
  uint256 internal constant MAX_PROTOCOL_CONTRACTS = 7;
  uint256 internal constant CANONICAL_AUTH_REGISTRY_ADDRESS = 1;
  uint256 internal constant DEPLOYER_CONTRACT_ADDRESS = 2;
  uint256 internal constant REGISTERER_CONTRACT_ADDRESS = 3;
  uint256 internal constant MULTI_CALL_ENTRYPOINT_ADDRESS = 4;
  uint256 internal constant FEE_JUICE_ADDRESS = 5;
  uint256 internal constant ROUTER_ADDRESS = 6;
  uint256 internal constant REGISTERER_CONTRACT_BYTECODE_CAPSULE_SLOT = 79025834455612;
  uint256 internal constant FEE_JUICE_BALANCES_SLOT = 1;
  uint256 internal constant UPDATED_CLASS_IDS_SLOT = 1;
  uint256 internal constant DEFAULT_NPK_M_X =
    582240093077765400562621227108555700500271598878376310175765873770292988861;
  uint256 internal constant DEFAULT_NPK_M_Y =
    10422444662424639723529825114205836958711284159673861467999592572974769103684;
  uint256 internal constant DEFAULT_IVPK_M_X =
    339708709767762472786445938838804872781183545349360029270386718856175781484;
  uint256 internal constant DEFAULT_IVPK_M_Y =
    12719619215050539905199178334954929730355853796706924300730604757520758976849;
  uint256 internal constant DEFAULT_OVPK_M_X =
    12212787719617305570587928860288475454328008955283046946846066128763901043335;
  uint256 internal constant DEFAULT_OVPK_M_Y =
    3646747884782549389807830220601404629716007431341772952958971658285958854707;
  uint256 internal constant DEFAULT_TPK_M_X =
    728059161893070741164607238299536939695876538801885465230641192969135857403;
  uint256 internal constant DEFAULT_TPK_M_Y =
    14575718736702206050102425029229426215631664471161015518982549597389390371695;
  uint256 internal constant AZTEC_ADDRESS_LENGTH = 1;
  uint256 internal constant GAS_FEES_LENGTH = 2;
  uint256 internal constant GAS_LENGTH = 2;
  uint256 internal constant GAS_SETTINGS_LENGTH = 8;
  uint256 internal constant CALL_CONTEXT_LENGTH = 4;
  uint256 internal constant CONTENT_COMMITMENT_LENGTH = 4;
  uint256 internal constant CONTRACT_INSTANCE_LENGTH = 16;
  uint256 internal constant CONTRACT_STORAGE_READ_LENGTH = 3;
  uint256 internal constant CONTRACT_STORAGE_UPDATE_REQUEST_LENGTH = 3;
  uint256 internal constant ETH_ADDRESS_LENGTH = 1;
  uint256 internal constant FUNCTION_DATA_LENGTH = 2;
  uint256 internal constant FUNCTION_LEAF_PREIMAGE_LENGTH = 5;
  uint256 internal constant GLOBAL_VARIABLES_LENGTH = 9;
  uint256 internal constant APPEND_ONLY_TREE_SNAPSHOT_LENGTH = 2;
  uint256 internal constant APPEND_ONLY_TREE_SNAPSHOT_LENGTH_BYTES = 36;
  uint256 internal constant SPONGE_BLOB_LENGTH = 11;
  uint256 internal constant BLOB_PUBLIC_INPUTS = 6;
  uint256 internal constant BLOB_PUBLIC_INPUTS_BYTES = 112;
  uint256 internal constant L1_TO_L2_MESSAGE_LENGTH = 6;
  uint256 internal constant L2_TO_L1_MESSAGE_LENGTH = 3;
  uint256 internal constant SCOPED_L2_TO_L1_MESSAGE_LENGTH = 4;
  uint256 internal constant MAX_BLOCK_NUMBER_LENGTH = 2;
  uint256 internal constant KEY_VALIDATION_REQUEST_LENGTH = 4;
  uint256 internal constant KEY_VALIDATION_REQUEST_AND_GENERATOR_LENGTH = 5;
  uint256 internal constant SCOPED_KEY_VALIDATION_REQUEST_AND_GENERATOR_LENGTH = 6;
  uint256 internal constant PARTIAL_STATE_REFERENCE_LENGTH = 6;
  uint256 internal constant READ_REQUEST_LENGTH = 2;
  uint256 internal constant TREE_LEAF_READ_REQUEST_LENGTH = 2;
  uint256 internal constant PRIVATE_LOG_DATA_LENGTH = 20;
  uint256 internal constant SCOPED_PRIVATE_LOG_DATA_LENGTH = 21;
  uint256 internal constant CONTRACT_CLASS_LOG_DATA_SIZE_IN_FIELDS = 3019;
  uint256 internal constant CONTRACT_CLASS_LOG_SIZE_IN_FIELDS = 3020;
  uint256 internal constant LOG_HASH_LENGTH = 3;
  uint256 internal constant SCOPED_LOG_HASH_LENGTH = 4;
  uint256 internal constant NOTE_HASH_LENGTH = 2;
  uint256 internal constant SCOPED_NOTE_HASH_LENGTH = 3;
  uint256 internal constant NULLIFIER_LENGTH = 3;
  uint256 internal constant SCOPED_NULLIFIER_LENGTH = 4;
  uint256 internal constant PUBLIC_DATA_WRITE_LENGTH = 2;
  uint256 internal constant PUBLIC_CALL_STACK_ITEM_COMPRESSED_LENGTH = 12;
  uint256 internal constant PRIVATE_CALL_REQUEST_LENGTH = 8;
  uint256 internal constant PUBLIC_CALL_REQUEST_LENGTH = 4;
  uint256 internal constant COUNTED_PUBLIC_CALL_REQUEST_LENGTH = 5;
  uint256 internal constant PUBLIC_INNER_CALL_REQUEST_LENGTH = 13;
  uint256 internal constant ROLLUP_VALIDATION_REQUESTS_LENGTH = 2;
  uint256 internal constant STATE_REFERENCE_LENGTH = 8;
  uint256 internal constant TREE_SNAPSHOTS_LENGTH = 8;
  uint256 internal constant TX_CONTEXT_LENGTH = 10;
  uint256 internal constant TX_REQUEST_LENGTH = 14;
  uint256 internal constant TOTAL_FEES_LENGTH = 1;
  uint256 internal constant TOTAL_MANA_USED_LENGTH = 1;
  uint256 internal constant BLOCK_HEADER_LENGTH = 25;
  uint256 internal constant BLOCK_HEADER_LENGTH_BYTES = 648;
  uint256 internal constant PRIVATE_CIRCUIT_PUBLIC_INPUTS_LENGTH = 724;
  uint256 internal constant PUBLIC_CIRCUIT_PUBLIC_INPUTS_LENGTH = 908;
  uint256 internal constant PRIVATE_CONTEXT_INPUTS_LENGTH = 40;
  uint256 internal constant FEE_RECIPIENT_LENGTH = 2;
  uint256 internal constant AGGREGATION_OBJECT_LENGTH = 16;
  uint256 internal constant IPA_CLAIM_LENGTH = 10;
  uint256 internal constant SCOPED_READ_REQUEST_LEN = 3;
  uint256 internal constant PUBLIC_DATA_READ_LENGTH = 3;
  uint256 internal constant PRIVATE_VALIDATION_REQUESTS_LENGTH = 772;
  uint256 internal constant PRIVATE_TO_ROLLUP_ACCUMULATED_DATA_LENGTH = 740;
  uint256 internal constant TX_CONSTANT_DATA_LENGTH = 37;
  uint256 internal constant COMBINED_CONSTANT_DATA_LENGTH = 46;
  uint256 internal constant PRIVATE_ACCUMULATED_DATA_LENGTH = 1380;
  uint256 internal constant PRIVATE_KERNEL_CIRCUIT_PUBLIC_INPUTS_LENGTH = 2197;
  uint256 internal constant PRIVATE_TO_PUBLIC_ACCUMULATED_DATA_LENGTH = 868;
  uint256 internal constant PRIVATE_TO_AVM_ACCUMULATED_DATA_LENGTH = 160;
  uint256 internal constant NUM_PRIVATE_TO_AVM_ACCUMULATED_DATA_ARRAYS = 3;
  uint256 internal constant PRIVATE_TO_PUBLIC_KERNEL_CIRCUIT_PUBLIC_INPUTS_LENGTH = 1782;
  uint256 internal constant PRIVATE_TO_ROLLUP_KERNEL_CIRCUIT_PUBLIC_INPUTS_LENGTH = 782;
  uint256 internal constant CONSTANT_ROLLUP_DATA_LENGTH = 13;
  uint256 internal constant BASE_OR_MERGE_PUBLIC_INPUTS_LENGTH = 52;
  uint256 internal constant BLOCK_ROOT_OR_BLOCK_MERGE_PUBLIC_INPUTS_LENGTH = 986;
  uint256 internal constant ROOT_ROLLUP_PUBLIC_INPUTS_LENGTH = 972;
  uint256 internal constant GET_NOTES_ORACLE_RETURN_LENGTH = 674;
  uint256 internal constant NOTE_HASHES_NUM_BYTES_PER_BASE_ROLLUP = 2048;
  uint256 internal constant NULLIFIERS_NUM_BYTES_PER_BASE_ROLLUP = 2048;
  uint256 internal constant PUBLIC_DATA_WRITES_NUM_BYTES_PER_BASE_ROLLUP = 4096;
  uint256 internal constant PRIVATE_LOGS_NUM_BYTES_PER_BASE_ROLLUP = 18432;
  uint256 internal constant CONTRACTS_NUM_BYTES_PER_BASE_ROLLUP = 32;
  uint256 internal constant CONTRACT_DATA_NUM_BYTES_PER_BASE_ROLLUP = 64;
  uint256 internal constant CONTRACT_DATA_NUM_BYTES_PER_BASE_ROLLUP_UNPADDED = 52;
  uint256 internal constant L2_TO_L1_MSGS_NUM_BYTES_PER_BASE_ROLLUP = 256;
  uint256 internal constant LOGS_HASHES_NUM_BYTES_PER_BASE_ROLLUP = 64;
  uint256 internal constant NUM_MSGS_PER_BASE_PARITY = 4;
  uint256 internal constant NUM_BASE_PARITY_PER_ROOT_PARITY = 4;
  uint256 internal constant RECURSIVE_PROOF_LENGTH = 456;
  uint256 internal constant NESTED_RECURSIVE_PROOF_LENGTH = 456;
  uint256 internal constant IPA_PROOF_LENGTH = 69;
  uint256 internal constant RECURSIVE_ROLLUP_HONK_PROOF_LENGTH = 535;
  uint256 internal constant NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH = 535;
  uint256 internal constant TUBE_PROOF_LENGTH = 535;
  uint256 internal constant HONK_VERIFICATION_KEY_LENGTH_IN_FIELDS = 128;
  uint256 internal constant ROLLUP_HONK_VERIFICATION_KEY_LENGTH_IN_FIELDS = 139;
  uint256 internal constant CLIENT_IVC_VERIFICATION_KEY_LENGTH_IN_FIELDS = 143;
  uint256 internal constant MAX_PUBLIC_BYTECODE_SIZE_IN_BYTES = 96000;
  uint256 internal constant MAX_PUBLIC_CALLS_TO_UNIQUE_CONTRACT_CLASS_IDS = 21;
  uint256 internal constant MEM_TAG_FF = 0;
  uint256 internal constant MEM_TAG_U1 = 1;
  uint256 internal constant MEM_TAG_U8 = 2;
  uint256 internal constant MEM_TAG_U16 = 3;
  uint256 internal constant MEM_TAG_U32 = 4;
  uint256 internal constant MEM_TAG_U64 = 5;
  uint256 internal constant MEM_TAG_U128 = 6;
  uint256 internal constant SENDER_KERNEL_INPUTS_COL_OFFSET = 0;
  uint256 internal constant ADDRESS_KERNEL_INPUTS_COL_OFFSET = 1;
  uint256 internal constant IS_STATIC_CALL_KERNEL_INPUTS_COL_OFFSET = 3;
  uint256 internal constant CHAIN_ID_KERNEL_INPUTS_COL_OFFSET = 4;
  uint256 internal constant VERSION_KERNEL_INPUTS_COL_OFFSET = 5;
  uint256 internal constant BLOCK_NUMBER_KERNEL_INPUTS_COL_OFFSET = 6;
  uint256 internal constant TIMESTAMP_KERNEL_INPUTS_COL_OFFSET = 7;
  uint256 internal constant FEE_PER_DA_GAS_KERNEL_INPUTS_COL_OFFSET = 8;
  uint256 internal constant FEE_PER_L2_GAS_KERNEL_INPUTS_COL_OFFSET = 9;
  uint256 internal constant DA_START_GAS_KERNEL_INPUTS_COL_OFFSET = 10;
  uint256 internal constant L2_START_GAS_KERNEL_INPUTS_COL_OFFSET = 11;
  uint256 internal constant DA_END_GAS_KERNEL_INPUTS_COL_OFFSET = 12;
  uint256 internal constant L2_END_GAS_KERNEL_INPUTS_COL_OFFSET = 13;
  uint256 internal constant TRANSACTION_FEE_KERNEL_INPUTS_COL_OFFSET = 14;
  uint256 internal constant START_NOTE_HASH_EXISTS_WRITE_OFFSET = 0;
  uint256 internal constant START_NULLIFIER_EXISTS_OFFSET = 16;
  uint256 internal constant START_NULLIFIER_NON_EXISTS_OFFSET = 32;
  uint256 internal constant START_L1_TO_L2_MSG_EXISTS_WRITE_OFFSET = 48;
  uint256 internal constant START_SSTORE_WRITE_OFFSET = 64;
  uint256 internal constant START_SLOAD_WRITE_OFFSET = 127;
  uint256 internal constant START_EMIT_NOTE_HASH_WRITE_OFFSET = 191;
  uint256 internal constant START_EMIT_NULLIFIER_WRITE_OFFSET = 207;
  uint256 internal constant START_EMIT_L2_TO_L1_MSG_WRITE_OFFSET = 223;
  uint256 internal constant START_EMIT_UNENCRYPTED_LOG_WRITE_OFFSET = 225;
  uint256 internal constant DEFAULT_GAS_LIMIT = 1000000000;
  uint256 internal constant MAX_L2_GAS_PER_TX_PUBLIC_PORTION = 6000000;
  uint256 internal constant DEFAULT_TEARDOWN_GAS_LIMIT = 6000000;
  uint256 internal constant DA_BYTES_PER_FIELD = 32;
  uint256 internal constant DA_GAS_PER_BYTE = 16;
  uint256 internal constant FIXED_DA_GAS = 512;
  uint256 internal constant FIXED_L2_GAS = 512;
  uint256 internal constant FIXED_AVM_STARTUP_L2_GAS = 20000;
  uint256 internal constant L2_GAS_DISTRIBUTED_STORAGE_PREMIUM = 1024;
  uint256 internal constant L2_GAS_PER_READ_MERKLE_HASH = 36;
  uint256 internal constant L2_GAS_PER_WRITE_MERKLE_HASH = 36;
  uint256 internal constant L2_GAS_PER_PUBLIC_DATA_UPDATE = 6784;
  uint256 internal constant L2_GAS_PER_NOTE_HASH = 3904;
  uint256 internal constant L2_GAS_PER_NULLIFIER = 5344;
  uint256 internal constant L2_GAS_PER_PUBLIC_DATA_READ = 1440;
  uint256 internal constant L2_GAS_PER_NOTE_HASH_READ_REQUEST = 1440;
  uint256 internal constant L2_GAS_PER_NULLIFIER_READ_REQUEST = 1440;
  uint256 internal constant L2_GAS_PER_L1_TO_L2_MSG_READ_REQUEST = 1404;
  uint256 internal constant L2_GAS_PER_LOG_BYTE = 4;
  uint256 internal constant L2_GAS_PER_PRIVATE_LOG = 0;
  uint256 internal constant L2_GAS_PER_CONTRACT_CLASS_LOG = 0;
  uint256 internal constant L2_GAS_PER_L2_TO_L1_MSG = 200;
  uint256 internal constant TX_START_PREFIX = 8392562855083340404;
  uint256 internal constant REVERT_CODE_PREFIX = 1;
  uint256 internal constant TX_FEE_PREFIX = 2;
  uint256 internal constant NOTES_PREFIX = 3;
  uint256 internal constant NULLIFIERS_PREFIX = 4;
  uint256 internal constant L2_L1_MSGS_PREFIX = 5;
  uint256 internal constant PUBLIC_DATA_UPDATE_REQUESTS_PREFIX = 6;
  uint256 internal constant PRIVATE_LOGS_PREFIX = 7;
  uint256 internal constant PUBLIC_LOGS_PREFIX = 8;
  uint256 internal constant CONTRACT_CLASS_LOGS_PREFIX = 9;
  uint256 internal constant PROOF_TYPE_PLONK = 0;
  uint256 internal constant PROOF_TYPE_HONK = 1;
  uint256 internal constant PROOF_TYPE_OINK = 2;
  uint256 internal constant PROOF_TYPE_PG = 3;
  uint256 internal constant PROOF_TYPE_AVM = 4;
  uint256 internal constant PROOF_TYPE_ROLLUP_HONK = 5;
  uint256 internal constant PROOF_TYPE_ROOT_ROLLUP_HONK = 6;
  uint256 internal constant TWO_POW_64 = 18446744073709551616;
  uint256 internal constant DEFAULT_UPDATE_DELAY = 3600;
  uint256 internal constant MINIMUM_UPDATE_DELAY = 25;
  uint256 internal constant UPDATES_VALUE_SIZE = 1;
  uint256 internal constant UPDATES_SHARED_MUTABLE_VALUES_LEN = 3;
  uint256 internal constant GRUMPKIN_ONE_X = 1;
  uint256 internal constant GRUMPKIN_ONE_Y =
    17631683881184975370165255887551781615748388533673675138860;
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

/**
 * @title Data Structures Library
 * @author Aztec Labs
 * @notice Library that contains data structures used throughout the Aztec protocol
 */
library DataStructures {
    // docs:start:l1_actor
    /**
     * @notice Actor on L1.
     * @param actor - The address of the actor
     * @param chainId - The chainId of the actor
     */
    struct L1Actor {
        address actor;
        uint256 chainId;
    }
    // docs:end:l1_actor

    // docs:start:l2_actor
    /**
     * @notice Actor on L2.
     * @param actor - The aztec address of the actor
     * @param version - Ahe Aztec instance the actor is on
     */
    struct L2Actor {
        bytes32 actor;
        uint256 version;
    }
    // docs:end:l2_actor

    // docs:start:l1_to_l2_msg
    /**
     * @notice Struct containing a message from L1 to L2
     * @param sender - The sender of the message
     * @param recipient - The recipient of the message
     * @param content - The content of the message (application specific) padded to bytes32 or hashed if larger.
     * @param secretHash - The secret hash of the message (make it possible to hide when a specific message is consumed on L2).
     * @param index - Global leaf index on the L1 to L2 messages tree.
     */
    struct L1ToL2Msg {
        L1Actor sender;
        L2Actor recipient;
        bytes32 content;
        bytes32 secretHash;
        uint256 index;
    }
    // docs:end:l1_to_l2_msg

    // docs:start:l2_to_l1_msg
    /**
     * @notice Struct containing a message from L2 to L1
     * @param sender - The sender of the message
     * @param recipient - The recipient of the message
     * @param content - The content of the message (application specific) padded to bytes32 or hashed if larger.
     * @dev Not to be confused with L2ToL1Message in Noir circuits
     */
    struct L2ToL1Msg {
        DataStructures.L2Actor sender;
        DataStructures.L1Actor recipient;
        bytes32 content;
    }
    // docs:end:l2_to_l1_msg
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

import {Timestamp, Slot, Epoch} from "./TimeLib.sol";

/**
 * @title Errors Library
 * @author Aztec Labs
 * @notice Library that contains errors used throughout the Aztec protocol
 * Errors are prefixed with the contract name to make it easy to identify where the error originated
 * when there are multiple contracts that could have thrown the error.
 *
 * Sigs are provided for easy reference, but don't trust; verify! run `forge inspect src/core/libraries/Errors.sol:Errors errors`
 */
library Errors {
    // DEVNET related
    error DevNet__NoPruningAllowed(); // 0x6984c590
    error DevNet__InvalidProposer(address expected, address actual); // 0x11e6e6f7

    // Inbox
    error Inbox__Unauthorized(); // 0xe5336a6b
    error Inbox__ActorTooLarge(bytes32 actor); // 0xa776a06e
    error Inbox__VersionMismatch(uint256 expected, uint256 actual); // 0x47452014
    error Inbox__ContentTooLarge(bytes32 content); // 0x47452014
    error Inbox__SecretHashTooLarge(bytes32 secretHash); // 0xecde7e2c
    error Inbox__MustBuildBeforeConsume(); // 0xc4901999

    // Outbox
    error Outbox__Unauthorized(); // 0x2c9490c2
    error Outbox__InvalidChainId(); // 0x577ec7c4
    error Outbox__VersionMismatch(uint256 expected, uint256 actual);
    error Outbox__NothingToConsume(bytes32 messageHash); // 0xfb4fb506
    error Outbox__IncompatibleEntryArguments(
        bytes32 messageHash,
        uint64 storedFee,
        uint64 feePassed,
        uint32 storedVersion,
        uint32 versionPassed,
        uint32 storedDeadline,
        uint32 deadlinePassed
    ); // 0x5e789f34
    error Outbox__InvalidPathLength(uint256 expected, uint256 actual); // 0x481bcd9c
    error Outbox__RootAlreadySetAtBlock(uint256 l2BlockNumber); // 0x3eccfd3e
    error Outbox__InvalidRecipient(address expected, address actual); // 0x57aad581
    error Outbox__AlreadyNullified(uint256 l2BlockNumber, uint256 leafIndex); // 0xfd71c2d4
    error Outbox__NothingToConsumeAtBlock(uint256 l2BlockNumber); // 0xa4508f22
    error Outbox__BlockNotProven(uint256 l2BlockNumber); // 0x0e194a6d

    // Rollup
    error Rollup__InsufficientBondAmount(uint256 minimum, uint256 provided); // 0xa165f276
    error Rollup__InsufficientFundsInEscrow(
        uint256 required,
        uint256 available
    ); // 0xa165f276
    error Rollup__InvalidArchive(bytes32 expected, bytes32 actual); // 0xb682a40e
    error Rollup__InvalidBlockHash(bytes32 expected, bytes32 actual);
    error Rollup__InvalidBlockNumber(uint256 expected, uint256 actual); // 0xe5edf847
    error Rollup__InvalidChainId(uint256 expected, uint256 actual); // 0x37b5bc12
    error Rollup__InvalidInHash(bytes32 expected, bytes32 actual); // 0xcd6f4233
    error Rollup__InvalidPreviousArchive(bytes32 expected, bytes32 actual); // 0xb682a40e
    error Rollup__InvalidPreviousBlockHash(bytes32 expected, bytes32 actual);
    error Rollup__InvalidProof(); // 0xa5b2ba17
    error Rollup__InvalidProposedArchive(bytes32 expected, bytes32 actual); // 0x32532e73
    error Rollup__InvalidTimestamp(Timestamp expected, Timestamp actual); // 0x3132e895
    error Rollup__InvalidVersion(uint256 expected, uint256 actual); // 0x9ef30794
    error Rollup__InvalidBlobHash(bytes32 blobHash); // 0xc4a168c6
    error Rollup__InvalidBlobProof(bytes32 blobHash); // 0x5ca17bef
    error Rollup__InvalidBlobPublicInputsHash(bytes32 expected, bytes32 actual); // 0xfe6b4994
    error Rollup__NoEpochToProve(); // 0xcbaa3951
    error Rollup__NonSequentialProving(); // 0x1e5be132
    error Rollup__NothingToPrune(); // 0x850defd3
    error Rollup__SlotAlreadyInChain(Slot lastSlot, Slot proposedSlot); // 0x83510bd0
    error Rollup__TimestampInFuture(Timestamp max, Timestamp actual); // 0x89f30690
    error Rollup__TimestampTooOld(); // 0x72ed9c81
    error Rollup__TryingToProveNonExistingBlock(); // 0x34ef4954
    error Rollup__UnavailableTxs(bytes32 txsHash); // 0x414906c3
    error Rollup__NonZeroDaFee(); // 0xd9c75f52
    error Rollup__InvalidBasisPointFee(uint256 basisPointFee); // 0x4292d136
    error Rollup__InvalidManaBaseFee(uint256 expected, uint256 actual); // 0x73b6d896
    error Rollup__StartAndEndNotSameEpoch(Epoch start, Epoch end);
    error Rollup__StartIsNotFirstBlockOfEpoch();
    error Rollup__StartIsNotBuildingOnProven();
    error Rollup__AlreadyClaimed(address prover, Epoch epoch);
    error Rollup__NotPastDeadline(Slot deadline, Slot currentSlot);
    error Rollup__PastDeadline(Slot deadline, Slot currentSlot);
    error Rollup__ProverHaveAlreadySubmitted(address prover, Epoch epoch);
    error Rollup__ManaLimitExceeded();

    // HeaderLib
    error HeaderLib__InvalidHeaderSize(uint256 expected, uint256 actual); // 0xf3ccb247
    error HeaderLib__InvalidSlotNumber(Slot expected, Slot actual); // 0x09ba91ff

    // MerkleLib
    error MerkleLib__InvalidRoot(
        bytes32 expected,
        bytes32 actual,
        bytes32 leaf,
        uint256 leafIndex
    ); // 0x5f216bf1

    // SignatureLib
    error SignatureLib__CannotVerifyEmpty(); // 0xc7690a37
    error SignatureLib__InvalidSignature(address expected, address recovered); // 0xd9cbae6c

    // SampleLib
    error SampleLib__IndexOutOfBounds(uint256 requested, uint256 bound); // 0xa12fc559
    error SampleLib__SampleLargerThanIndex(uint256 sample, uint256 index); // 0xa11b0f79

    // Sequencer Selection (ValidatorSelection)
    error ValidatorSelection__EpochNotSetup(); // 0x10816cae
    error ValidatorSelection__InvalidProposer(address expected, address actual); // 0xa8843a68
    error ValidatorSelection__InvalidDeposit(
        address attester,
        address proposer
    ); // 0x533169bd
    error ValidatorSelection__InsufficientAttestations(
        uint256 minimumNeeded,
        uint256 provided
    ); // 0xaf47297f
    error ValidatorSelection__InsufficientAttestationsProvided(
        uint256 minimumNeeded,
        uint256 provided
    ); // 0x4d4f66ac

    // Staking
    error Staking__AlreadyActive(address attester); // 0x5e206fa4
    error Staking__AlreadyRegistered(address); // 0x18047699
    error Staking__CannotSlashExitedStake(address); // 0x45bf4940
    error Staking__FailedToRemove(address); // 0xa7d7baab
    error Staking__InvalidDeposit(address attester, address proposer); // 0xf33fe8c6
    error Staking__InsufficientStake(uint256, uint256); // 0x903aee24
    error Staking__NoOneToSlash(address); // 0x7e2f7f1c
    error Staking__NotExiting(address); // 0xef566ee0
    error Staking__NotSlasher(address, address); // 0x23a6f432
    error Staking__NotWithdrawer(address, address); // 0x8e668e5d
    error Staking__NothingToExit(address); // 0xd2aac9b6
    error Staking__WithdrawalNotUnlockedYet(Timestamp, Timestamp); // 0x88e1826c

    // Fee Juice Portal
    error FeeJuicePortal__AlreadyInitialized(); // 0xc7a172fe
    error FeeJuicePortal__InvalidInitialization(); // 0xfd9b3208
    error FeeJuicePortal__Unauthorized(); // 0x67e3691e

    // Proof Commitment Escrow
    error ProofCommitmentEscrow__InsufficientBalance(
        uint256 balance,
        uint256 requested
    ); // 0x09b8b789
    error ProofCommitmentEscrow__NotOwner(address caller); // 0x2ac332c1
    error ProofCommitmentEscrow__WithdrawRequestNotReady(
        uint256 current,
        Timestamp readyAt
    ); // 0xb32ab8a7

    // FeeLib
    error FeeLib__InvalidFeeAssetPriceModifier(); // 0xf2fb32ad
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

import {DataStructures} from "../CoreDataStructures.sol";

/**
 * @title Hash library
 * @author Aztec Labs
 * @notice Library that contains helper functions to compute hashes for data structures and convert to field elements
 * Using sha256 as the hash function since it hits a good balance between gas cost and circuit size.
 */
library Hash {
    /**
     * @notice Computes the sha256 hash of the L1 to L2 message and converts it to a field element
     * @param _message - The L1 to L2 message to hash
     * @return The hash of the provided message as a field element
     */
    function sha256ToField(
        DataStructures.L1ToL2Msg memory _message
    ) internal pure returns (bytes32) {
        return
            sha256ToField(
                abi.encode(
                    _message.sender,
                    _message.recipient,
                    _message.content,
                    _message.secretHash,
                    _message.index
                )
            );
    }

    /**
     * @notice Computes the sha256 hash of the L2 to L1 message and converts it to a field element
     * @param _message - The L2 to L1 message to hash
     * @return The hash of the provided message as a field element
     */
    function sha256ToField(
        DataStructures.L2ToL1Msg memory _message
    ) internal pure returns (bytes32) {
        return
            sha256ToField(
                abi.encode(
                    _message.sender,
                    _message.recipient,
                    _message.content
                )
            );
    }

    /**
     * @notice Computes the sha256 hash of the provided data and converts it to a field element
     * @dev Truncating one byte to convert the hash to a field element. We prepend a byte rather than cast bytes31(bytes32) to match Noir's to_be_bytes.
     * @param _data - The bytes to hash
     * @return The hash of the provided data as a field element
     */
    function sha256ToField(bytes memory _data) internal pure returns (bytes32) {
        return bytes32(bytes.concat(new bytes(1), bytes31(sha256(_data))));
    }

    /**
     * @notice Computes the sha256 hash of the provided data and converts it to a field element
     * @dev Truncating one byte to convert the hash to a field element.
     * @param _data - A bytes32 value to hash
     * @return The hash of the provided data as a field element
     */
    function sha256ToField(bytes32 _data) internal pure returns (bytes32) {
        return sha256ToField(abi.encodePacked(_data));
    }
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

import {Hash} from "./Hash.sol";
import {Errors} from "../CoreErrors.sol";

/**
 * @title Merkle Library
 * @author Aztec Labs
 * @notice Library that contains functions useful when interacting with Merkle Trees
 */
library MerkleLib {
    /**
     * @notice Verifies the membership of a leaf and path against an expected root.
     * @dev In the case of a mismatched root, and subsequent inability to verify membership, this function throws.
     * @param _path - The sibling path of the message as a leaf, used to prove message inclusion
     * @param _leaf - The hash of the message we are trying to prove inclusion for
     * @param _index - The index of the message inside the L2 to L1 message tree
     * @param _expectedRoot - The expected root to check the validity of the message and sibling path with.
     * @notice -
     * E.g. A sibling path for a leaf at index 3 (L) in a tree of depth 3 (between 5 and 8 leafs) consists of the 3 elements denoted as *'s
     * d0:                                            [ root ]
     * d1:                      [ ]                                               [*]
     * d2:         [*]                      [ ]                       [ ]                     [ ]
     * d3:   [ ]         [ ]          [*]         [L]           [ ]         [ ]          [ ]        [ ].
     * And the elements would be ordered as: [ d3_index_2, d2_index_0, d1_index_1 ].
     */
    function verifyMembership(
        bytes32[] calldata _path,
        bytes32 _leaf,
        uint256 _index,
        bytes32 _expectedRoot
    ) internal pure {
        bytes32 subtreeRoot = _leaf;
        /// @notice - We use the indexAtHeight to see whether our child of the next subtree is at the left or the right side
        uint256 indexAtHeight = _index;

        for (uint256 height = 0; height < _path.length; height++) {
            /// @notice - This affects the way we concatenate our two children to then hash and calculate the root, as any odd indexes (index bit-masked with least significant bit) are right-sided children.
            bool isRight = (indexAtHeight & 1) == 1;

            subtreeRoot = isRight
                ? Hash.sha256ToField(bytes.concat(_path[height], subtreeRoot))
                : Hash.sha256ToField(bytes.concat(subtreeRoot, _path[height]));
            /// @notice - We divide by two here to get the index of the parent of the current subtreeRoot in its own layer
            indexAtHeight >>= 1;
        }

        require(
            subtreeRoot == _expectedRoot,
            Errors.MerkleLib__InvalidRoot(
                _expectedRoot,
                subtreeRoot,
                _leaf,
                _index
            )
        );
    }

    /**
     * @notice Computes the minimum and maximum path size of an unbalanced tree.
     * @dev Follows structure of rollup circuits by greedy filling subtrees.
     * @param _numTxs - The number of txs to form into subtrees.
     * @return (min, max) - The min and max path sizes.
     */
    function computeMinMaxPathLength(
        uint256 _numTxs
    ) internal pure returns (uint256, uint256) {
        if (_numTxs < 2) {
            return (0, 0);
        }

        uint256 numSubtrees = 0;
        uint256 currentSubtreeSize = 1;
        uint256 currentSubtreeHeight = 0;
        uint256 firstSubtreeHeight;
        uint256 finalSubtreeHeight;
        while (_numTxs != 0) {
            // If size & txs == 0, the subtree doesn't exist for this number of txs
            if (currentSubtreeSize & _numTxs == 0) {
                currentSubtreeSize <<= 1;
                currentSubtreeHeight++;
                continue;
            }
            // Assign the smallest rightmost subtree height
            if (numSubtrees == 0) finalSubtreeHeight = currentSubtreeHeight;
            // Assign the largest leftmost subtree height
            if (_numTxs - currentSubtreeSize == 0)
                firstSubtreeHeight = currentSubtreeHeight;
            _numTxs -= currentSubtreeSize;
            currentSubtreeSize <<= 1;
            currentSubtreeHeight++;
            numSubtrees++;
        }
        if (numSubtrees == 1) {
            // We have a balanced tree
            return (firstSubtreeHeight, firstSubtreeHeight);
        }
        uint256 min = finalSubtreeHeight + numSubtrees - 1;
        uint256 max = firstSubtreeHeight + 1;
        return (min, max);
    }

    /**
     * @notice Calculates a tree height from the amount of elements in the tree
     * @dev - This mirrors the function in TestUtil, but assumes _size is an exact power of 2 or = 1
     * @param _size - The number of elements in the tree
     */
    function calculateTreeHeightFromSize(
        uint256 _size
    ) internal pure returns (uint256) {
        /// We need the height of the tree that will contain all of our leaves,
        /// hence the next highest power of two from the amount of leaves - Math.ceil(Math.log2(x))
        uint256 height = 0;

        if (_size == 1) {
            return 0;
        }

        /// While size > 1, we divide by two, and count how many times we do this; producing a rudimentary way of calculating Math.Floor(Math.log2(x))
        while (_size > 1) {
            _size >>= 1;
            height++;
        }
        return height;
    }

    /**
     * @notice Computes the root for a binary Merkle-tree given the leafs.
     * @dev Uses sha256.
     * @param _leafs - The 32 bytes leafs to build the tree of.
     * @return The root of the Merkle tree.
     */
    function computeRoot(
        bytes32[] memory _leafs
    ) internal pure returns (bytes32) {
        // @todo Must pad the tree
        uint256 treeDepth = 0;
        while (2 ** treeDepth < _leafs.length) {
            treeDepth++;
        }
        uint256 treeSize = 2 ** treeDepth;
        assembly {
            mstore(_leafs, treeSize)
        }

        for (uint256 i = 0; i < treeDepth; i++) {
            for (uint256 j = 0; j < treeSize; j += 2) {
                _leafs[j / 2] = Hash.sha256ToField(
                    bytes.concat(_leafs[j], _leafs[j + 1])
                );
            }
            treeSize /= 2;
        }

        return _leafs[0];
    }

    /**
     * @notice Computes the root for a binary unbalanced Merkle-tree given the leaves.
     * @dev Filled in greedily with subtrees. Useful for outHash tree.
     * @param _leaves - The 32 bytes leafs to build the tree of.
     * @return The root of the Merkle tree.
     */
    function computeUnbalancedRoot(
        bytes32[] memory _leaves
    ) internal pure returns (bytes32) {
        // e.g. an unbalanced tree of 7 txs will contain subtrees of 4, 2, and 1 tx(s) = 111
        // e.g. an unbalanced tree of 9 txs will contain subtrees of 8 and 1 tx(s) = 1001
        // We collect the roots of each subtree
        bytes32 root;
        uint256 currentSubtreeSize = 1;
        uint256 numTxs = _leaves.length;
        // We must calculate the smaller rightmost subtrees first, hence starting at 1
        while (numTxs != 0) {
            // If size & txs == 0, the subtree doesn't exist for this number of txs
            if (currentSubtreeSize & numTxs == 0) {
                currentSubtreeSize <<= 1;
                continue;
            }
            bytes32[] memory leavesInSubtree = new bytes32[](
                currentSubtreeSize
            );
            uint256 start = numTxs - currentSubtreeSize;
            for (uint256 i = start; i < numTxs; i++) {
                leavesInSubtree[i - start] = _leaves[i];
            }
            bytes32 subtreeRoot = computeRoot(leavesInSubtree);
            root = numTxs == _leaves.length
                ? subtreeRoot
                : Hash.sha256ToField(bytes.concat(subtreeRoot, root));
            numTxs -= currentSubtreeSize;
            currentSubtreeSize <<= 1;
        }
        return root;
    }
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

import {Errors} from "../CoreErrors.sol";
import {SlotDerivation} from "../SlotDerivation.sol";
import {TransientSlot} from "../TransientSlot.sol";

/**
 * @title   SampleLib
 * @author  Anaxandridas II
 * @notice  A tiny library to draw committee indices using a sample without replacement algorithm.
 */
library SampleLib {
    using SlotDerivation for string;
    using SlotDerivation for bytes32;
    using TransientSlot for *;

    // Namespace for transient storage keys used within this library
    string private constant OVERRIDE_NAMESPACE = "Aztec.SampleLib.Override";

    /**
     * Compute Committee
     *
     * @param _committeeSize - The size of the committee
     * @param _indexCount - The total number of indices
     * @param _seed - The seed to use for shuffling
     *
     * @dev assumption, _committeeSize <= _indexCount
     *
     * @return indices - The indices of the committee
     */
    function computeCommittee(
        uint256 _committeeSize,
        uint256 _indexCount,
        uint256 _seed
    ) internal returns (uint256[] memory) {
        require(
            _committeeSize <= _indexCount,
            Errors.SampleLib__SampleLargerThanIndex(_committeeSize, _indexCount)
        );

        uint256[] memory sampledIndices = new uint256[](_committeeSize);

        uint256 upperLimit = _indexCount - 1;

        for (uint256 index = 0; index < _committeeSize; index++) {
            uint256 sampledIndex = computeSampleIndex(index, upperLimit, _seed);

            // Get index, or its swapped override
            sampledIndices[index] = getValue(sampledIndex);
            if (upperLimit > 0) {
                // Swap with the last index
                setOverrideValue(sampledIndex, getValue(upperLimit));
                // Decrement the upper limit
                upperLimit--;
            }
        }

        return sampledIndices;
    }

    function setOverrideValue(uint256 _index, uint256 _value) internal {
        OVERRIDE_NAMESPACE
            .erc7201Slot()
            .deriveMapping(_index)
            .asUint256()
            .tstore(_value);
    }

    function getValue(uint256 _index) internal view returns (uint256) {
        uint256 overrideValue = getOverrideValue(_index);
        if (overrideValue != 0) {
            return overrideValue;
        }

        return _index;
    }

    function getOverrideValue(uint256 _index) internal view returns (uint256) {
        return
            OVERRIDE_NAMESPACE
                .erc7201Slot()
                .deriveMapping(_index)
                .asUint256()
                .tload();
    }

    /**
     * @notice  Compute the sample index for a given index, seed and index count.
     *
     * @param _index - The index to shuffle
     * @param _indexCount - The total number of indices
     * @param _seed - The seed to use for shuffling
     *
     * @return shuffledIndex - The shuffled index
     */
    function computeSampleIndex(
        uint256 _index,
        uint256 _indexCount,
        uint256 _seed
    ) internal pure returns (uint256) {
        // Cannot modulo by 0
        if (_indexCount == 0) {
            return 0;
        }

        return
            uint256(keccak256(abi.encodePacked(_seed, _index))) % _indexCount;
    }
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity ^0.8.27;

import {Errors} from "../CoreErrors.sol";

struct Signature {
    bool isEmpty;
    uint8 v;
    bytes32 r;
    bytes32 s;
}

library SignatureLib {
    /**
     * @notice The domain separator for the signatures
     */
    enum SignatureDomainSeparator {
        blockProposal,
        blockAttestation
    }

    /**
     * @notice Verified a signature, throws if the signature is invalid or empty
     *
     * @param _signature - The signature to verify
     * @param _signer - The expected signer of the signature
     * @param _digest - The digest that was signed
     */
    function verify(
        Signature memory _signature,
        address _signer,
        bytes32 _digest
    ) internal pure {
        require(!_signature.isEmpty, Errors.SignatureLib__CannotVerifyEmpty());
        address recovered = ecrecover(
            _digest,
            _signature.v,
            _signature.r,
            _signature.s
        );
        require(
            _signer == recovered,
            Errors.SignatureLib__InvalidSignature(_signer, recovered)
        );
    }

    function toBytes(
        Signature memory _signature
    ) internal pure returns (bytes memory) {
        return abi.encodePacked(_signature.r, _signature.s, _signature.v);
    }
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

import {IRollup} from "./IRollup.sol";
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {IInbox} from "./messagebridge/IInbox.sol";

interface IFeeJuicePortal {
    event DepositToAztecPublic(
        bytes32 indexed to,
        uint256 amount,
        bytes32 secretHash,
        bytes32 key,
        uint256 index
    );
    event FeesDistributed(address indexed to, uint256 amount);

    function initialize() external;
    function distributeFees(address _to, uint256 _amount) external;
    function depositToAztecPublic(
        bytes32 _to,
        uint256 _amount,
        bytes32 _secretHash
    ) external returns (bytes32, uint256);

    // solhint-disable-next-line func-name-mixedcase
    function UNDERLYING() external view returns (IERC20);
    // solhint-disable-next-line func-name-mixedcase
    function L2_TOKEN_ADDRESS() external view returns (bytes32);
    // solhint-disable-next-line func-name-mixedcase
    function VERSION() external view returns (uint256);
    // solhint-disable-next-line func-name-mixedcase
    function INBOX() external view returns (IInbox);
    // solhint-disable-next-line func-name-mixedcase
    function ROLLUP() external view returns (IRollup);
}

// SPDX-License-Identifier: Apache-2.0
pragma solidity >=0.8.27;

import {IRollup} from "./IRollup.sol";
import {IRewardDistributor} from "./IRewardDistributor.sol";

interface IRegistry {
    event InstanceAdded(address indexed instance, uint256 indexed version);
    event GovernanceUpdated(address indexed governance);

    function addRollup(IRollup _rollup) external;
    function updateGovernance(address _governance) external;

    // docs:start:registry_get_canonical_rollup
    function getCanonicalRollup() external view returns (IRollup);
    // docs:end:registry_get_canonical_rollup

    // docs:start:registry_get_rollup
    function getRollup(uint256 _chainId) external view returns (IRollup);
    // docs:end:registry_get_rollup

    // docs:start:registry_number_of_versions
    function numberOfVersions() external view returns (uint256);
    // docs:end:registry_number_of_versions

    function getGovernance() external view returns (address);

    function getRewardDistributor() external view returns (IRewardDistributor);

    function getVersion(uint256 _index) external view returns (uint256);
}

// SPDX-License-Identifier: Apache-2.0
pragma solidity >=0.8.27;

interface IRewardDistributor {
  function claim(address _to) external returns (uint256);
  function claimBlockRewards(address _to, uint256 _amount) external returns (uint256);
  function canonicalRollup() external view returns (address);
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

import {IFeeJuicePortal} from "./IFeeJuicePortal.sol";
import {IVerifier} from "./IVerifier.sol";
import {IInbox} from "./messagebridge/IInbox.sol";
import {IOutbox} from "./messagebridge/IOutbox.sol";
import {Signature} from "./crypto/SignatureLib.sol";
import {FeeHeader, L1FeeData, ManaBaseFeeComponents} from "./rollup/FeeLib.sol";
import {FeeAssetPerEthE9, EthValue, FeeAssetValue} from "./rollup/FeeLib.sol";
import {ProposeArgs} from "./rollup/ProposeLib.sol";
import {Timestamp, Slot, Epoch} from "./TimeLib.sol";
import {IRewardDistributor} from "./IRewardDistributor.sol";
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";

struct PublicInputArgs {
    bytes32 previousArchive;
    bytes32 endArchive;
    bytes32 previousBlockHash; // @todo #8829 Not needed as public input, unconstrained on L1
    bytes32 endBlockHash; // @todo #8829 Not needed as public input, unconstrained on L1
    Timestamp endTimestamp;
    bytes32 outHash;
    address proverId;
}

struct SubmitEpochRootProofArgs {
    uint256 start; // inclusive
    uint256 end; // inclusive
    PublicInputArgs args;
    bytes32[] fees;
    bytes blobPublicInputs;
    bytes aggregationObject;
    bytes proof;
}

struct BlockLog {
    bytes32 archive;
    bytes32 blockHash;
    Slot slotNumber;
}

struct ChainTips {
    uint256 pendingBlockNumber;
    uint256 provenBlockNumber;
}

struct SubEpochRewards {
    uint256 summedCount;
    mapping(address prover => bool proofSubmitted) hasSubmitted;
}

struct EpochRewards {
    uint256 longestProvenLength;
    uint256 rewards;
    mapping(uint256 length => SubEpochRewards) subEpoch;
}

/**
 * @notice Struct for storing flags for block header validation
 * @param ignoreDA - True will ignore DA check, otherwise checks
 * @param ignoreSignature - True will ignore the signatures, otherwise checks
 */
struct BlockHeaderValidationFlags {
    bool ignoreDA;
    bool ignoreSignatures;
}

struct GenesisState {
    bytes32 vkTreeRoot;
    bytes32 protocolContractTreeRoot;
    bytes32 genesisArchiveRoot;
    bytes32 genesisBlockHash;
}

struct RollupConfigInput {
    uint256 aztecSlotDuration;
    uint256 aztecEpochDuration;
    uint256 targetCommitteeSize;
    uint256 aztecProofSubmissionWindow;
    uint256 minimumStake;
    uint256 slashingQuorum;
    uint256 slashingRoundSize;
    uint256 manaTarget;
    EthValue provingCostPerMana;
}

struct RollupConfig {
    uint256 proofSubmissionWindow;
    IERC20 feeAsset;
    IFeeJuicePortal feeAssetPortal;
    IRewardDistributor rewardDistributor;
    bytes32 vkTreeRoot;
    bytes32 protocolContractTreeRoot;
    IVerifier epochProofVerifier;
    IInbox inbox;
    IOutbox outbox;
    uint256 version;
}

// The below blobPublicInputsHashes are filled when proposing a block, then used to verify an epoch proof.
// TODO(#8955): When implementing batched kzg proofs, store one instance per epoch rather than block
struct RollupStore {
    ChainTips tips; // put first such that the struct slot structure is easy to follow for cheatcodes
    mapping(uint256 blockNumber => BlockLog log) blocks;
    mapping(uint256 blockNumber => bytes32) blobPublicInputsHashes;
    mapping(address => uint256) sequencerRewards;
    mapping(Epoch => EpochRewards) epochRewards;
    // @todo Below can be optimised with a bitmap as we can benefit from provers likely proving for epochs close
    // to one another.
    mapping(address prover => mapping(Epoch epoch => bool claimed)) proverClaimed;
    RollupConfig config;
}

struct CheatDepositArgs {
    address attester;
    address proposer;
    address withdrawer;
    uint256 amount;
}

interface ITestRollup {
    event ManaTargetUpdated(uint256 indexed manaTarget);

    function setEpochVerifier(address _verifier) external;
    function setVkTreeRoot(bytes32 _vkTreeRoot) external;
    function setProtocolContractTreeRoot(
        bytes32 _protocolContractTreeRoot
    ) external;
    function cheat__InitialiseValidatorSet(
        CheatDepositArgs[] memory _args
    ) external;
    function updateManaTarget(uint256 _manaTarget) external;
}

interface IRollupCore {
    event L2BlockProposed(
        uint256 indexed blockNumber,
        bytes32 indexed archive,
        bytes32[] versionedBlobHashes
    );
    event L2ProofVerified(
        uint256 indexed blockNumber,
        address indexed proverId
    );
    event PrunedPending(uint256 provenBlockNumber, uint256 pendingBlockNumber);

    function claimSequencerRewards(
        address _recipient
    ) external returns (uint256);
    function claimProverRewards(
        address _recipient,
        Epoch[] memory _epochs
    ) external returns (uint256);

    function prune() external;
    function updateL1GasFeeOracle() external;

    function setProvingCostPerMana(EthValue _provingCostPerMana) external;

    function propose(
        ProposeArgs calldata _args,
        Signature[] memory _signatures,
        bytes calldata _blobInput
    ) external;

    function submitEpochRootProof(
        SubmitEpochRootProofArgs calldata _args
    ) external;

    // solhint-disable-next-line func-name-mixedcase
    function L1_BLOCK_AT_GENESIS() external view returns (uint256);
}

interface IRollup is IRollupCore {
    function validateHeader(
        bytes calldata _header,
        Signature[] memory _signatures,
        bytes32 _digest,
        Timestamp _currentTime,
        bytes32 _blobsHash,
        BlockHeaderValidationFlags memory _flags
    ) external;

    function canProposeAtTime(
        Timestamp _ts,
        bytes32 _archive
    ) external returns (Slot, uint256);

    function getTips() external view returns (ChainTips memory);

    function status(
        uint256 _myHeaderBlockNumber
    )
        external
        view
        returns (
            uint256 provenBlockNumber,
            bytes32 provenArchive,
            uint256 pendingBlockNumber,
            bytes32 pendingArchive,
            bytes32 archiveOfMyBlock,
            Epoch provenEpochNumber
        );

    function getEpochProofPublicInputs(
        uint256 _start,
        uint256 _end,
        PublicInputArgs calldata _args,
        bytes32[] calldata _fees,
        bytes calldata _blobPublicInputs,
        bytes calldata _aggregationObject
    ) external view returns (bytes32[] memory);

    function validateBlobs(
        bytes calldata _blobsInputs
    ) external view returns (bytes32[] memory, bytes32, bytes32);

    function getManaBaseFeeComponentsAt(
        Timestamp _timestamp,
        bool _inFeeAsset
    ) external view returns (ManaBaseFeeComponents memory);
    function getManaBaseFeeAt(
        Timestamp _timestamp,
        bool _inFeeAsset
    ) external view returns (uint256);
    function getL1FeesAt(
        Timestamp _timestamp
    ) external view returns (L1FeeData memory);
    function getFeeAssetPerEth() external view returns (FeeAssetPerEthE9);

    function getEpochForBlock(
        uint256 _blockNumber
    ) external view returns (Epoch);
    function canPruneAtTime(Timestamp _ts) external view returns (bool);

    function archive() external view returns (bytes32);
    function archiveAt(uint256 _blockNumber) external view returns (bytes32);
    function getProvenBlockNumber() external view returns (uint256);
    function getPendingBlockNumber() external view returns (uint256);
    function getBlock(
        uint256 _blockNumber
    ) external view returns (BlockLog memory);
    function getFeeHeader(
        uint256 _blockNumber
    ) external view returns (FeeHeader memory);
    function getBlobPublicInputsHash(
        uint256 _blockNumber
    ) external view returns (bytes32);

    function getSequencerRewards(
        address _sequencer
    ) external view returns (uint256);
    function getCollectiveProverRewardsForEpoch(
        Epoch _epoch
    ) external view returns (uint256);
    function getSpecificProverRewardsForEpoch(
        Epoch _epoch,
        address _prover
    ) external view returns (uint256);
    function getHasSubmitted(
        Epoch _epoch,
        uint256 _length,
        address _prover
    ) external view returns (bool);

    function getProofSubmissionWindow() external view returns (uint256);
    function getManaTarget() external view returns (uint256);
    function getManaLimit() external view returns (uint256);
    function getProvingCostPerManaInEth() external view returns (EthValue);

    function getProvingCostPerManaInFeeAsset()
        external
        view
        returns (FeeAssetValue);

    function getFeeAsset() external view returns (IERC20);
    function getFeeAssetPortal() external view returns (IFeeJuicePortal);
    function getRewardDistributor() external view returns (IRewardDistributor);
    function getBurnAddress() external view returns (address);

    function getInbox() external view returns (IInbox);
    function getOutbox() external view returns (IOutbox);
    function getVersion() external view returns (uint256);
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

import {Timestamp} from "./TimeMath.sol";
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";

// None -> Does not exist in our setup
// Validating -> Participating as validator
// Living -> Not participating as validator, but have funds in setup,
// 			 hit if slashes and going below the minimum
// Exiting -> In the process of exiting the system
enum Status {
    NONE,
    VALIDATING,
    LIVING,
    EXITING
}

struct ValidatorInfo {
    uint256 stake;
    address withdrawer;
    address proposer;
    Status status;
}

struct OperatorInfo {
    address proposer;
    address attester;
}

struct Exit {
    Timestamp exitableAt;
    address recipient;
}

struct StakingStorage {
    IERC20 stakingAsset;
    address slasher;
    uint256 minimumStake;
    Timestamp exitDelay;
    EnumerableSet.AddressSet attesters;
    mapping(address attester => ValidatorInfo) info;
    mapping(address attester => Exit) exits;
}

interface IStakingCore {
    event Deposit(
        address indexed attester,
        address indexed proposer,
        address indexed withdrawer,
        uint256 amount
    );
    event WithdrawInitiated(
        address indexed attester,
        address indexed recipient,
        uint256 amount
    );
    event WithdrawFinalised(
        address indexed attester,
        address indexed recipient,
        uint256 amount
    );
    event Slashed(address indexed attester, uint256 amount);

    function deposit(
        address _attester,
        address _proposer,
        address _withdrawer,
        uint256 _amount
    ) external;
    function initiateWithdraw(
        address _attester,
        address _recipient
    ) external returns (bool);
    function finaliseWithdraw(address _attester) external;
    function slash(address _attester, uint256 _amount) external;
}

interface IStaking is IStakingCore {
    function getInfo(
        address _attester
    ) external view returns (ValidatorInfo memory);
    function getExit(address _attester) external view returns (Exit memory);
    function getActiveAttesterCount() external view returns (uint256);
    function getAttesterAtIndex(uint256 _index) external view returns (address);
    function getProposerAtIndex(uint256 _index) external view returns (address);
    function getProposerForAttester(
        address _attester
    ) external view returns (address);
    function getOperatorAtIndex(
        uint256 _index
    ) external view returns (OperatorInfo memory);
    function getSlasher() external view returns (address);
    function getStakingAsset() external view returns (IERC20);
    function getMinimumStake() external view returns (uint256);
    function getExitDelay() external view returns (Timestamp);
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

import {Timestamp, Slot, Epoch} from "./TimeLib.sol";

/**
 * @notice  The data structure for an epoch
 * @param committee - The attesters for the epoch
 * @param sampleSeed - The seed used to sample the attesters of the epoch
 * @param nextSeed - The seed used to influence the NEXT epoch
 */
struct EpochData {
    address[] committee;
    uint256 sampleSeed;
    uint256 nextSeed;
}

struct ValidatorSelectionStorage {
    // A mapping to snapshots of the validator set
    mapping(Epoch => EpochData) epochs;
    // The last stored randao value, same value as `seed` in the last inserted epoch
    uint256 lastSeed;
    uint256 targetCommitteeSize;
}

interface IValidatorSelectionCore {
    function setupEpoch() external;
}

interface IValidatorSelection is IValidatorSelectionCore {
    // Likely changing to optimize in Pleistarchus
    function getCurrentProposer() external returns (address);
    function getProposerAt(Timestamp _ts) external returns (address);

    // Non view as uses transient storage
    function getCurrentEpochCommittee() external returns (address[] memory);
    function getCommitteeAt(Timestamp _ts) external returns (address[] memory);
    function getEpochCommittee(
        Epoch _epoch
    ) external returns (address[] memory);

    // Stable
    function getCurrentEpoch() external view returns (Epoch);
    function getCurrentSlot() external view returns (Slot);

    // Consider removing below this point
    function getTimestampForSlot(
        Slot _slotNumber
    ) external view returns (Timestamp);

    // Likely removal of these to replace with a size and indiviual getter
    // Get the current epoch committee
    function getAttesters() external view returns (address[] memory);

    function getSampleSeedAt(Timestamp _ts) external view returns (uint256);
    function getCurrentSampleSeed() external view returns (uint256);

    function getEpochAt(Timestamp _ts) external view returns (Epoch);
    function getSlotAt(Timestamp _ts) external view returns (Slot);
    function getEpochAtSlot(Slot _slotNumber) external view returns (Epoch);

    function getGenesisTime() external view returns (Timestamp);
    function getSlotDuration() external view returns (uint256);
    function getEpochDuration() external view returns (uint256);
    function getTargetCommitteeSize() external view returns (uint256);
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

interface IVerifier {
  function verify(bytes calldata _proof, bytes32[] calldata _publicInputs)
    external
    view
    returns (bool);
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

import {DataStructures} from "../CoreDataStructures.sol";

/**
 * @title Inbox
 * @author Aztec Labs
 * @notice Lives on L1 and is used to pass messages into the rollup from L1.
 */
interface IInbox {
    /**
     * @notice Emitted when a message is sent
     * @param l2BlockNumber - The L2 block number in which the message is included
     * @param index - The index of the message in the L1 to L2 messages tree
     * @param hash - The hash of the message
     */
    event MessageSent(
        uint256 indexed l2BlockNumber,
        uint256 index,
        bytes32 indexed hash
    );

    // docs:start:send_l1_to_l2_message
    /**
     * @notice Inserts a new message into the Inbox
     * @dev Emits `MessageSent` with data for easy access by the sequencer
     * @param _recipient - The recipient of the message
     * @param _content - The content of the message (application specific)
     * @param _secretHash - The secret hash of the message (make it possible to hide when a specific message is consumed on L2)
     * @return The key of the message in the set and its leaf index in the tree
     */
    function sendL2Message(
        DataStructures.L2Actor memory _recipient,
        bytes32 _content,
        bytes32 _secretHash
    ) external returns (bytes32, uint256);
    // docs:end:send_l1_to_l2_message

    // docs:start:consume
    /**
     * @notice Consumes the current tree, and starts a new one if needed
     * @dev Only callable by the rollup contract
     * @dev In the first iteration we return empty tree root because first block's messages tree is always
     * empty because there has to be a 1 block lag to prevent sequencer DOS attacks
     *
     * @param _toConsume - The block number to consume
     *
     * @return The root of the consumed tree
     */
    function consume(uint256 _toConsume) external returns (bytes32);
    // docs:end:consume

    function getRoot(uint256 _blockNumber) external view returns (bytes32);
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

import {DataStructures} from "../CoreDataStructures.sol";

/**
 * @title IOutbox
 * @author Aztec Labs
 * @notice Lives on L1 and is used to consume L2 -> L1 messages. Messages are inserted by the Rollup
 * and will be consumed by the portal contracts.
 */
interface IOutbox {
    event RootAdded(
        uint256 indexed l2BlockNumber,
        bytes32 indexed root,
        uint256 minHeight
    );
    event MessageConsumed(
        uint256 indexed l2BlockNumber,
        bytes32 indexed root,
        bytes32 indexed messageHash,
        uint256 leafIndex
    );

    // docs:start:outbox_insert
    /**
     * @notice Inserts the root of a merkle tree containing all of the L2 to L1 messages in
     * a block specified by _l2BlockNumber.
     * @dev Only callable by the rollup contract
     * @dev Emits `RootAdded` upon inserting the root successfully
     * @param _l2BlockNumber - The L2 Block Number in which the L2 to L1 messages reside
     * @param _root - The merkle root of the tree where all the L2 to L1 messages are leaves
     * @param _minHeight - The min height of the merkle tree that the root corresponds to
     */
    function insert(
        uint256 _l2BlockNumber,
        bytes32 _root,
        uint256 _minHeight
    ) external;
    // docs:end:outbox_insert

    // docs:start:outbox_consume
    /**
     * @notice Consumes an entry from the Outbox
     * @dev Only useable by portals / recipients of messages
     * @dev Emits `MessageConsumed` when consuming messages
     * @param _message - The L2 to L1 message
     * @param _l2BlockNumber - The block number specifying the block that contains the message we want to consume
     * @param _leafIndex - The index inside the merkle tree where the message is located
     * @param _path - The sibling path used to prove inclusion of the message, the _path length directly depends
     * on the total amount of L2 to L1 messages in the block. i.e. the length of _path is equal to the depth of the
     * L1 to L2 message tree.
     */
    function consume(
        DataStructures.L2ToL1Msg calldata _message,
        uint256 _l2BlockNumber,
        uint256 _leafIndex,
        bytes32[] calldata _path
    ) external;
    // docs:end:outbox_consume

    // docs:start:outbox_has_message_been_consumed_at_block_and_index
    /**
     * @notice Checks to see if an index of the L2 to L1 message tree for a specific block has been consumed
     * @dev - This function does not throw. Out-of-bounds access is considered valid, but will always return false
     * @param _l2BlockNumber - The block number specifying the block that contains the index of the message we want to check
     * @param _leafIndex - The index of the message inside the merkle tree
     */
    function hasMessageBeenConsumedAtBlockAndIndex(
        uint256 _l2BlockNumber,
        uint256 _leafIndex
    ) external view returns (bool);
    // docs:end:outbox_has_message_been_consumed_at_block_and_index

    /**
     * @notice  Fetch the root data for a given block number
     *          Returns (0, 0) if the block is not proven
     *
     * @param _l2BlockNumber - The block number to fetch the root data for
     *
     * @return root - The root of the merkle tree containing the L2 to L1 messages
     * @return minHeight - The min height for the merkle tree that the root corresponds to
     */
    function getRootData(
        uint256 _l2BlockNumber
    ) external view returns (bytes32 root, uint256 minHeight);
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

import {Constants} from "../ConstantsGen.sol";
import {Hash} from "../crypto/Hash.sol";
import {Errors} from "../CoreErrors.sol";
import {Vm} from "../Vm.sol";

library BlobLib {
    address public constant VM_ADDRESS =
        address(uint160(uint256(keccak256("hevm cheat code"))));

    /**
     * @notice  Get the blob base fee
     *
     * @dev     If we are in a foundry test, we use the cheatcode to get the blob base fee.
     *          Otherwise, we use the `block.blobbasefee`
     *
     * @return uint256 - The blob base fee
     */
    function getBlobBaseFee() internal view returns (uint256) {
        if (VM_ADDRESS.code.length > 0) {
            return Vm(VM_ADDRESS).getBlobBaseFee();
        }
        return block.blobbasefee;
    }

    /**
     * @notice  Validate an L2 block's blobs and return the hashed blobHashes and public inputs.
     * Input bytes:
     * input[:1] - num blobs in block
     * input[1:] - 192 * num blobs of the above _blobInput
     * @param _blobsInput - The above bytes to verify a blob
     */
    function validateBlobs(
        bytes calldata _blobsInput,
        bool _checkBlob
    )
        internal
        view
        returns (
            // All of the blob hashes included in this blob
            bytes32[] memory blobHashes,
            bytes32 blobsHashesCommitment,
            bytes32 blobPublicInputsHash
        )
    {
        // We cannot input the incorrect number of blobs below, as the blobsHash
        // and epoch proof verification will fail.
        uint8 numBlobs = uint8(_blobsInput[0]);
        blobHashes = new bytes32[](numBlobs);
        bytes memory blobPublicInputs;
        for (uint256 i = 0; i < numBlobs; i++) {
            // Add 1 for the numBlobs prefix
            uint256 blobInputStart = i * 192 + 1;
            // Since an invalid blob hash here would fail the consensus checks of
            // the header, the `blobInput` is implicitly accepted by consensus as well.
            blobHashes[i] = validateBlob(
                _blobsInput[blobInputStart:blobInputStart + 192],
                i,
                _checkBlob
            );
            // We want to extract the 112 bytes we use for public inputs:
            //  * input[32:64]   - z
            //  * input[64:96]   - y
            //  * input[96:144]  - commitment C
            // Out of 192 bytes per blob.
            blobPublicInputs = abi.encodePacked(
                blobPublicInputs,
                _blobsInput[blobInputStart + 32:blobInputStart +
                    32 +
                    Constants.BLOB_PUBLIC_INPUTS_BYTES]
            );
        }
        // Return the hash of all z, y, and Cs, so we can use them in proof verification later
        blobPublicInputsHash = sha256(blobPublicInputs);
        // Hash the EVM blob hashes for the block header
        blobsHashesCommitment = Hash.sha256ToField(
            abi.encodePacked(blobHashes)
        );
    }

    /**
     * @notice  Validate a blob.
     * Input bytes:
     * input[:32]     - versioned_hash
     * input[32:64]   - z
     * input[64:96]   - y
     * input[96:144]  - commitment C
     * input[144:192] - proof (a commitment to the quotient polynomial q(X))
     *  - This can be relaxed to happen at the time of `submitProof` instead
     * @notice Apparently there is no guarantee that the blobs will be processed in the order sent
     * so the use of blobhash(_blobNumber) may fail in production
     * @param _blobInput - The above bytes to verify a blob
     */
    function validateBlob(
        bytes calldata _blobInput,
        uint256 _blobNumber,
        bool _checkBlob
    ) internal view returns (bytes32 blobHash) {
        if (!_checkBlob) {
            return bytes32(_blobInput[0:32]);
        }
        assembly {
            blobHash := blobhash(_blobNumber)
        }
        require(
            blobHash == bytes32(_blobInput[0:32]),
            Errors.Rollup__InvalidBlobHash(blobHash)
        );

        // Staticcall the point eval precompile https://eips.ethereum.org/EIPS/eip-4844#point-evaluation-precompile :
        (bool success, ) = address(0x0a).staticcall(_blobInput);
        require(success, Errors.Rollup__InvalidBlobProof(blobHash));
    }
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";
import {SafeCast} from "@openzeppelin/contracts/utils/math/SafeCast.sol";
import {SignedMath} from "@openzeppelin/contracts/utils/math/SignedMath.sol";

import {Errors} from "../CoreErrors.sol";

import {Slot, Timestamp, TimeLib} from "../TimeLib.sol";
import {BlobLib} from "./BlobLib.sol";

// The lowest number of fee asset per eth is 10 with a precision of 1e9.
uint256 constant MINIMUM_FEE_ASSET_PER_ETH = 10e9;
uint256 constant MAX_FEE_ASSET_PRICE_MODIFIER = 1e6;
uint256 constant FEE_ASSET_PRICE_UPDATE_FRACTION = 100e6;

uint256 constant L1_GAS_PER_BLOCK_PROPOSED = 150000;
uint256 constant L1_GAS_PER_EPOCH_VERIFIED = 1000000;

uint256 constant MINIMUM_CONGESTION_MULTIPLIER = 1e9;

// The magic values are used to have the fakeExponential case where
// (numerator / denominator) is close to 0.117, as that leads to ~1.125 multiplier
// per increase by TARGET of the numerator;
uint256 constant MAGIC_CONGESTION_VALUE_DIVISOR = 1e8;
uint256 constant MAGIC_CONGESTION_VALUE_MULTIPLIER = 854700854;

uint256 constant BLOB_GAS_PER_BLOB = 2 ** 17;
uint256 constant GAS_PER_BLOB_POINT_EVALUATION = 50_000;
uint256 constant BLOBS_PER_BLOCK = 3;

struct OracleInput {
    int256 feeAssetPriceModifier;
}

struct ManaBaseFeeComponents {
    uint256 congestionCost;
    uint256 congestionMultiplier;
    uint256 dataCost;
    uint256 gasCost;
    uint256 provingCost;
}

struct FeeHeader {
    uint256 excessMana;
    uint256 manaUsed;
    uint256 feeAssetPriceNumerator;
    uint256 congestionCost;
    uint256 provingCost;
}

struct L1FeeData {
    uint256 baseFee;
    uint256 blobFee;
}

struct L1GasOracleValues {
    L1FeeData pre;
    L1FeeData post;
    Slot slotOfChange;
}

type EthValue is uint256;

type FeeAssetValue is uint256;

// Precision of 1e9
type FeeAssetPerEthE9 is uint256;

function addEthValue(EthValue _a, EthValue _b) pure returns (EthValue) {
    return EthValue.wrap(EthValue.unwrap(_a) + EthValue.unwrap(_b));
}

function subEthValue(EthValue _a, EthValue _b) pure returns (EthValue) {
    return EthValue.wrap(EthValue.unwrap(_a) - EthValue.unwrap(_b));
}

using {addEthValue as +, subEthValue as -} for EthValue global;

library PriceLib {
    function toEth(
        FeeAssetValue _feeAssetValue,
        FeeAssetPerEthE9 _feeAssetPerEth
    ) internal pure returns (EthValue) {
        return
            EthValue.wrap(
                Math.mulDiv(
                    FeeAssetValue.unwrap(_feeAssetValue),
                    1e9,
                    FeeAssetPerEthE9.unwrap(_feeAssetPerEth),
                    Math.Rounding.Ceil
                )
            );
    }

    function toFeeAsset(
        EthValue _ethValue,
        FeeAssetPerEthE9 _feeAssetPerEth
    ) internal pure returns (FeeAssetValue) {
        return
            FeeAssetValue.wrap(
                Math.mulDiv(
                    EthValue.unwrap(_ethValue),
                    FeeAssetPerEthE9.unwrap(_feeAssetPerEth),
                    1e9,
                    Math.Rounding.Ceil
                )
            );
    }
}

struct CompressedFeeHeader {
    uint64 congestionCost;
    uint64 provingCost;
    uint48 feeAssetPriceNumerator;
    uint48 excessMana;
    uint32 manaUsed;
}

library FeeHeaderLib {
    using SafeCast for uint256;

    function getManaUsed(
        CompressedFeeHeader storage _compressedFeeHeader
    ) internal view returns (uint256) {
        return _compressedFeeHeader.manaUsed;
    }

    function getCongestionCost(
        CompressedFeeHeader storage _compressedFeeHeader
    ) internal view returns (uint256) {
        return _compressedFeeHeader.congestionCost;
    }

    function getProvingCost(
        CompressedFeeHeader storage _compressedFeeHeader
    ) internal view returns (uint256) {
        return _compressedFeeHeader.provingCost;
    }

    function compress(
        FeeHeader memory _feeHeader
    ) internal pure returns (CompressedFeeHeader memory) {
        return
            CompressedFeeHeader({
                excessMana: _feeHeader.excessMana.toUint48(),
                manaUsed: _feeHeader.manaUsed.toUint32(),
                feeAssetPriceNumerator: _feeHeader
                    .feeAssetPriceNumerator
                    .toUint48(),
                congestionCost: _feeHeader.congestionCost.toUint64(),
                provingCost: _feeHeader.provingCost.toUint64()
            });
    }

    function decompress(
        CompressedFeeHeader memory _compressedFeeHeader
    ) internal pure returns (FeeHeader memory) {
        return
            FeeHeader({
                excessMana: _compressedFeeHeader.excessMana,
                manaUsed: _compressedFeeHeader.manaUsed,
                feeAssetPriceNumerator: _compressedFeeHeader
                    .feeAssetPriceNumerator,
                congestionCost: _compressedFeeHeader.congestionCost,
                provingCost: _compressedFeeHeader.provingCost
            });
    }
}

struct FeeStore {
    uint256 manaTarget;
    uint256 congestionUpdateFraction;
    EthValue provingCostPerMana;
    L1GasOracleValues l1GasOracleValues;
    mapping(uint256 blockNumber => CompressedFeeHeader feeHeader) feeHeaders;
}

library FeeLib {
    using Math for uint256;
    using SafeCast for int256;
    using SafeCast for uint256;
    using SignedMath for int256;
    using PriceLib for EthValue;
    using TimeLib for Slot;
    using TimeLib for Timestamp;

    using FeeHeaderLib for FeeHeader;
    using FeeHeaderLib for CompressedFeeHeader;

    Slot internal constant LIFETIME = Slot.wrap(5);
    Slot internal constant LAG = Slot.wrap(2);

    bytes32 private constant FEE_STORE_POSITION =
        keccak256("aztec.fee.storage");

    function initialize(
        uint256 _manaTarget,
        EthValue _provingCostPerMana
    ) internal {
        FeeStore storage feeStore = getStorage();

        feeStore.manaTarget = _manaTarget;
        feeStore.congestionUpdateFraction =
            (_manaTarget * MAGIC_CONGESTION_VALUE_MULTIPLIER) /
            MAGIC_CONGESTION_VALUE_DIVISOR;
        feeStore.provingCostPerMana = _provingCostPerMana;

        feeStore.feeHeaders[0] = FeeHeader({
            excessMana: 0,
            feeAssetPriceNumerator: 0,
            manaUsed: 0,
            congestionCost: 0,
            provingCost: 0
        }).compress();

        feeStore.l1GasOracleValues = L1GasOracleValues({
            pre: L1FeeData({baseFee: 1 gwei, blobFee: 1}),
            post: L1FeeData({
                baseFee: block.basefee,
                blobFee: BlobLib.getBlobBaseFee()
            }),
            slotOfChange: LIFETIME
        });
    }

    function updateManaTarget(uint256 _manaTarget) internal {
        FeeStore storage feeStore = getStorage();
        feeStore.manaTarget = _manaTarget;
        feeStore.congestionUpdateFraction =
            (_manaTarget * MAGIC_CONGESTION_VALUE_MULTIPLIER) /
            MAGIC_CONGESTION_VALUE_DIVISOR;
    }

    function writeFeeHeader(
        uint256 _blockNumber,
        int256 _feeAssetPriceModifier,
        uint256 _manaUsed,
        uint256 _congestionCost,
        uint256 _provingCost
    ) internal {
        require(
            SignedMath.abs(_feeAssetPriceModifier) <=
                MAX_FEE_ASSET_PRICE_MODIFIER,
            Errors.FeeLib__InvalidFeeAssetPriceModifier()
        );
        FeeStore storage feeStore = getStorage();
        CompressedFeeHeader storage parentFeeHeader = feeStore.feeHeaders[
            _blockNumber - 1
        ];
        feeStore.feeHeaders[_blockNumber] = FeeHeader({
            excessMana: FeeLib.computeExcessMana(parentFeeHeader),
            feeAssetPriceNumerator: FeeLib.clampedAdd(
                parentFeeHeader.feeAssetPriceNumerator,
                _feeAssetPriceModifier
            ),
            manaUsed: _manaUsed,
            congestionCost: _congestionCost,
            provingCost: _provingCost
        }).compress();
    }

    function updateL1GasFeeOracle() internal {
        Slot slot = Timestamp.wrap(block.timestamp).slotFromTimestamp();
        // The slot where we find a new queued value acceptable
        FeeStore storage feeStore = getStorage();

        Slot acceptableSlot = feeStore.l1GasOracleValues.slotOfChange +
            (LIFETIME - LAG);

        if (slot < acceptableSlot) {
            return;
        }

        feeStore.l1GasOracleValues.pre = feeStore.l1GasOracleValues.post;
        feeStore.l1GasOracleValues.post = L1FeeData({
            baseFee: block.basefee,
            blobFee: BlobLib.getBlobBaseFee()
        });
        feeStore.l1GasOracleValues.slotOfChange = slot + LAG;
    }

    function getL1FeesAt(
        Timestamp _timestamp
    ) internal view returns (L1FeeData memory) {
        FeeStore storage feeStore = getStorage();
        return
            _timestamp.slotFromTimestamp() <
                feeStore.l1GasOracleValues.slotOfChange
                ? feeStore.l1GasOracleValues.pre
                : feeStore.l1GasOracleValues.post;
    }

    function getManaBaseFeeComponentsAt(
        uint256 _blockOfInterest,
        Timestamp _timestamp,
        bool _inFeeAsset
    ) internal view returns (ManaBaseFeeComponents memory) {
        FeeStore storage feeStore = getStorage();

        uint256 manaTarget = feeStore.manaTarget;

        if (manaTarget == 0) {
            return
                ManaBaseFeeComponents({
                    dataCost: 0,
                    gasCost: 0,
                    provingCost: 0,
                    congestionCost: 0,
                    congestionMultiplier: 0
                });
        }

        EthValue gasCostPerMana;
        EthValue dataCostPerMana;
        EthValue total;
        {
            uint256 gasUsed = L1_GAS_PER_BLOCK_PROPOSED +
                BLOBS_PER_BLOCK *
                GAS_PER_BLOB_POINT_EVALUATION +
                L1_GAS_PER_EPOCH_VERIFIED /
                TimeLib.getStorage().epochDuration;

            L1FeeData memory fees = FeeLib.getL1FeesAt(_timestamp);
            gasCostPerMana = EthValue.wrap(
                Math.mulDiv(
                    gasUsed,
                    fees.baseFee,
                    manaTarget,
                    Math.Rounding.Ceil
                )
            );
            dataCostPerMana = EthValue.wrap(
                Math.mulDiv(
                    BLOBS_PER_BLOCK * BLOB_GAS_PER_BLOB,
                    fees.blobFee,
                    manaTarget,
                    Math.Rounding.Ceil
                )
            );
            total =
                dataCostPerMana +
                gasCostPerMana +
                feeStore.provingCostPerMana;
        }

        CompressedFeeHeader storage parentFeeHeader = feeStore.feeHeaders[
            _blockOfInterest
        ];
        uint256 excessMana = FeeLib.clampedAdd(
            parentFeeHeader.excessMana + parentFeeHeader.manaUsed,
            -int256(manaTarget)
        );
        uint256 congestionMultiplier_ = congestionMultiplier(excessMana);

        EthValue congestionCost = EthValue.wrap(
            Math.mulDiv(
                EthValue.unwrap(total),
                congestionMultiplier_,
                MINIMUM_CONGESTION_MULTIPLIER,
                Math.Rounding.Floor
            )
        ) - total;

        FeeAssetPerEthE9 feeAssetPrice = _inFeeAsset
            ? FeeLib.getFeeAssetPerEthAtBlock(_blockOfInterest)
            : FeeAssetPerEthE9.wrap(1e9);

        return
            ManaBaseFeeComponents({
                dataCost: FeeAssetValue.unwrap(
                    dataCostPerMana.toFeeAsset(feeAssetPrice)
                ),
                gasCost: FeeAssetValue.unwrap(
                    gasCostPerMana.toFeeAsset(feeAssetPrice)
                ),
                provingCost: FeeAssetValue.unwrap(
                    feeStore.provingCostPerMana.toFeeAsset(feeAssetPrice)
                ),
                congestionCost: FeeAssetValue.unwrap(
                    congestionCost.toFeeAsset(feeAssetPrice)
                ),
                congestionMultiplier: congestionMultiplier_
            });
    }

    function getManaLimit() internal view returns (uint256) {
        FeeStore storage feeStore = getStorage();
        return feeStore.manaTarget * 2;
    }

    function getFeeAssetPerEthAtBlock(
        uint256 _blockNumber
    ) internal view returns (FeeAssetPerEthE9) {
        FeeStore storage feeStore = getStorage();
        return
            getFeeAssetPerEth(
                feeStore.feeHeaders[_blockNumber].feeAssetPriceNumerator
            );
    }

    function computeExcessMana(
        CompressedFeeHeader storage _feeHeader
    ) internal view returns (uint256) {
        FeeStore storage feeStore = getStorage();
        return
            clampedAdd(
                _feeHeader.excessMana + _feeHeader.manaUsed,
                -int256(feeStore.manaTarget)
            );
    }

    function congestionMultiplier(
        uint256 _numerator
    ) internal view returns (uint256) {
        FeeStore storage feeStore = getStorage();
        return
            fakeExponential(
                MINIMUM_CONGESTION_MULTIPLIER,
                _numerator,
                feeStore.congestionUpdateFraction
            );
    }

    function getFeeAssetPerEth(
        uint256 _numerator
    ) internal pure returns (FeeAssetPerEthE9) {
        return
            FeeAssetPerEthE9.wrap(
                fakeExponential(
                    MINIMUM_FEE_ASSET_PER_ETH,
                    _numerator,
                    FEE_ASSET_PRICE_UPDATE_FRACTION
                )
            );
    }

    function summedBaseFee(
        ManaBaseFeeComponents memory _components
    ) internal pure returns (uint256) {
        return
            _components.dataCost +
            _components.gasCost +
            _components.provingCost +
            _components.congestionCost;
    }

    function getStorage()
        internal
        pure
        returns (FeeStore storage storageStruct)
    {
        bytes32 position = FEE_STORE_POSITION;
        assembly {
            storageStruct.slot := position
        }
    }

    /**
     * @notice  Clamps the addition of a signed integer to a uint256
     *          Useful for running values, whose minimum value will be 0
     *          but should not throw if going below.
     * @param _a The base value
     * @param _b The value to add
     * @return The clamped value
     */
    function clampedAdd(uint256 _a, int256 _b) internal pure returns (uint256) {
        if (_b >= 0) {
            return _a + _b.toUint256();
        }

        uint256 sub = SignedMath.abs(_b);

        if (_a > sub) {
            return _a - sub;
        }

        return 0;
    }

    /**
     * @notice An approximation of the exponential function: factor * e ** (numerator / denominator)
     *
     *         The function is the same as used in EIP-4844
     *         https://github.com/ethereum/EIPs/blob/master/EIPS/eip-4844.md
     *
     *         Approximated using a taylor series.
     *         For shorthand below, let `a = factor`, `x = numerator`, `d = denominator`
     *
     *         f(x) =  a
     *              + (a * x) / d
     *              + (a * x ** 2) / (2 * d ** 2)
     *              + (a * x ** 3) / (6 * d ** 3)
     *              + (a * x ** 4) / (24 * d ** 4)
     *              + (a * x ** 5) / (120 * d ** 5)
     *              + ...
     *
     *         For integer precision purposes, we will multiply by the denominator for intermediary steps and then
     *         finally do a division by it.
     *         The notation below might look slightly strange, but it is to try to convey the program flow below.
     *
     *         e(x) = (          a * d
     *                 +         a * d * x / d
     *                 +       ((a * d * x / d) * x) / (2 * d)
     *                 +     ((((a * d * x / d) * x) / (2 * d)) * x) / (3 * d)
     *                 +   ((((((a * d * x / d) * x) / (2 * d)) * x) / (3 * d)) * x) / (4 * d)
     *                 + ((((((((a * d * x / d) * x) / (2 * d)) * x) / (3 * d)) * x) / (4 * d)) * x) / (5 * d)
     *                 + ...
     *                 ) / d
     *
     *         The notation might make it a bit of a pain to look at, but f(x) and e(x) are the same.
     *         Gotta love integer math.
     *
     * @dev   Notice that as _numerator grows, the computation will quickly overflow.
     *        As long as the `_denominator` is fairly small, it won't bring us back down to not overflow
     *        For our purposes, this is acceptable, as if we have a fee that is so high that it would overflow and throw
     *        then we would have other problems.
     *
     * @param _factor The base value
     * @param _numerator The numerator
     * @param _denominator The denominator
     * @return The approximated value `_factor * e ** (_numerator / _denominator)`
     */
    function fakeExponential(
        uint256 _factor,
        uint256 _numerator,
        uint256 _denominator
    ) private pure returns (uint256) {
        uint256 i = 1;
        uint256 output = 0;
        uint256 numeratorAccumulator = _factor * _denominator;
        while (numeratorAccumulator > 0) {
            output += numeratorAccumulator;
            numeratorAccumulator =
                (numeratorAccumulator * _numerator) /
                (_denominator * i);
            i += 1;
        }
        return output / _denominator;
    }
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

import {Constants} from "../ConstantsGen.sol";
import {Errors} from "../CoreErrors.sol";

import {Slot, Timestamp} from "../TimeLib.sol";

struct AppendOnlyTreeSnapshot {
    bytes32 root;
    uint32 nextAvailableLeafIndex;
}

struct PartialStateReference {
    AppendOnlyTreeSnapshot noteHashTree;
    AppendOnlyTreeSnapshot nullifierTree;
    AppendOnlyTreeSnapshot contractTree;
    AppendOnlyTreeSnapshot publicDataTree;
}

struct StateReference {
    AppendOnlyTreeSnapshot l1ToL2MessageTree;
    // Note: Can't use "partial" name here as in protocol specs because it is a reserved solidity keyword
    PartialStateReference partialStateReference;
}

struct GasFees {
    uint256 feePerDaGas;
    uint256 feePerL2Gas;
}

struct GlobalVariables {
    uint256 chainId;
    uint256 version;
    uint256 blockNumber;
    Slot slotNumber;
    Timestamp timestamp;
    address coinbase;
    bytes32 feeRecipient;
    GasFees gasFees;
}

struct ContentCommitment {
    uint256 numTxs;
    bytes32 blobsHash;
    bytes32 inHash;
    bytes32 outHash;
}

struct Header {
    AppendOnlyTreeSnapshot lastArchive;
    ContentCommitment contentCommitment;
    StateReference stateReference;
    GlobalVariables globalVariables;
    uint256 totalFees;
    uint256 totalManaUsed;
}

/**
 * @title Header Library
 * @author Aztec Labs
 * @notice Decoding and validating an L2 block header
 * Concerned with readability and velocity of development not giving a damn about gas costs.
 *
 * -------------------
 * You can use https://gist.github.com/LHerskind/724a7e362c97e8ac2902c6b961d36830 to generate the below outline.
 * -------------------
 * L2 Block Header specification
 * -------------------
 *
 *  | byte start                                                                       | num bytes    | name
 *  | ---                                                                              | ---          | ---
 *  |                                                                                  |              | Header {
 *  | 0x0000                                                                           | 0x20         |   lastArchive.root
 *  | 0x0020                                                                           | 0x04         |   lastArchive.nextAvailableLeafIndex
 *  |                                                                                  |              |   ContentCommitment {
 *  | 0x0024                                                                           | 0x20         |     numTxs
 *  | 0x0044                                                                           | 0x20         |     blobsHash
 *  | 0x0064                                                                           | 0x20         |     inHash
 *  | 0x0084                                                                           | 0x20         |     outHash
 *  |                                                                                  |              |   StateReference {
 *  | 0x00a4                                                                           | 0x20         |     l1ToL2MessageTree.root
 *  | 0x00c4                                                                           | 0x04         |     l1ToL2MessageTree.nextAvailableLeafIndex
 *  |                                                                                  |              |     PartialStateReference {
 *  | 0x00c8                                                                           | 0x20         |       noteHashTree.root
 *  | 0x00e8                                                                           | 0x04         |       noteHashTree.nextAvailableLeafIndex
 *  | 0x00ec                                                                           | 0x20         |       nullifierTree.root
 *  | 0x010c                                                                           | 0x04         |       nullifierTree.nextAvailableLeafIndex
 *  | 0x0110                                                                           | 0x20         |       publicDataTree.root
 *  | 0x0130                                                                           | 0x04         |       publicDataTree.nextAvailableLeafIndex
 *  |                                                                                  |              |     }
 *  |                                                                                  |              |   }
 *  |                                                                                  |              |   GlobalVariables {
 *  | 0x0134                                                                           | 0x20         |     chainId
 *  | 0x0154                                                                           | 0x20         |     version
 *  | 0x0174                                                                           | 0x20         |     blockNumber
 *  | 0x0194                                                                           | 0x20         |     slotNumber
 *  | 0x01b4                                                                           | 0x20         |     timestamp
 *  | 0x01d4                                                                           | 0x14         |     coinbase
 *  | 0x01e8                                                                           | 0x20         |     feeRecipient
 *  | 0x0208                                                                           | 0x20         |     gasFees.feePerDaGas
 *  | 0x0228                                                                           | 0x20         |     gasFees.feePerL2Gas
 *  |                                                                                  |              |   }
 *  |                                                                                  |              | }
 *  | 0x0248                                                                           | 0x20         | total_fees
 *  | 0x0268                                                                           | 0x20         | total_mana_used
 *  | ---                                                                              | ---          | ---
 */
library HeaderLib {
    uint256 private constant HEADER_LENGTH =
        Constants.BLOCK_HEADER_LENGTH_BYTES; // Header byte length

    /**
     * @notice Decodes the header
     * @param _header - The header calldata
     * @return The decoded header
     */
    function decode(
        bytes calldata _header
    ) internal pure returns (Header memory) {
        require(
            _header.length == HEADER_LENGTH,
            Errors.HeaderLib__InvalidHeaderSize(HEADER_LENGTH, _header.length)
        );

        Header memory header;

        // Reading lastArchive
        header.lastArchive = AppendOnlyTreeSnapshot(
            bytes32(_header[0x0000:0x0020]),
            uint32(bytes4(_header[0x0020:0x0024]))
        );

        // Reading ContentCommitment
        header.contentCommitment.numTxs = uint256(
            bytes32(_header[0x0024:0x0044])
        );
        header.contentCommitment.blobsHash = bytes32(_header[0x0044:0x0064]);
        header.contentCommitment.inHash = bytes32(_header[0x0064:0x0084]);
        header.contentCommitment.outHash = bytes32(_header[0x0084:0x00a4]);

        // Reading StateReference
        header.stateReference.l1ToL2MessageTree = AppendOnlyTreeSnapshot(
            bytes32(_header[0x00a4:0x00c4]),
            uint32(bytes4(_header[0x00c4:0x00c8]))
        );
        header
            .stateReference
            .partialStateReference
            .noteHashTree = AppendOnlyTreeSnapshot(
            bytes32(_header[0x00c8:0x00e8]),
            uint32(bytes4(_header[0x00e8:0x00ec]))
        );
        header
            .stateReference
            .partialStateReference
            .nullifierTree = AppendOnlyTreeSnapshot(
            bytes32(_header[0x00ec:0x010c]),
            uint32(bytes4(_header[0x010c:0x0110]))
        );
        header
            .stateReference
            .partialStateReference
            .publicDataTree = AppendOnlyTreeSnapshot(
            bytes32(_header[0x0110:0x0130]),
            uint32(bytes4(_header[0x0130:0x0134]))
        );

        // Reading GlobalVariables
        header.globalVariables.chainId = uint256(
            bytes32(_header[0x0134:0x0154])
        );
        header.globalVariables.version = uint256(
            bytes32(_header[0x0154:0x0174])
        );
        header.globalVariables.blockNumber = uint256(
            bytes32(_header[0x0174:0x0194])
        );
        header.globalVariables.slotNumber = Slot.wrap(
            uint256(bytes32(_header[0x0194:0x01b4]))
        );
        header.globalVariables.timestamp = Timestamp.wrap(
            uint256(bytes32(_header[0x01b4:0x01d4]))
        );
        header.globalVariables.coinbase = address(
            bytes20(_header[0x01d4:0x01e8])
        );
        header.globalVariables.feeRecipient = bytes32(_header[0x01e8:0x0208]);
        header.globalVariables.gasFees.feePerDaGas = uint256(
            bytes32(_header[0x0208:0x0228])
        );
        header.globalVariables.gasFees.feePerL2Gas = uint256(
            bytes32(_header[0x0228:0x0248])
        );

        // Reading totalFees
        header.totalFees = uint256(bytes32(_header[0x0248:0x0268]));

        // Reading totalManaUsed
        header.totalManaUsed = uint256(bytes32(_header[0x0268:0x0288]));

        return header;
    }
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

import {RollupStore, IRollupCore, BlockLog, BlockHeaderValidationFlags} from "../IRollup.sol";
import {MerkleLib} from "../crypto/MerkleLib.sol";
import {SignatureLib} from "../crypto/SignatureLib.sol";
import {Signature} from "../crypto/SignatureLib.sol";
import {Errors} from "../CoreErrors.sol";
import {OracleInput, FeeLib, ManaBaseFeeComponents} from "./FeeLib.sol";
import {StakingLib} from "../staking/StakingLib.sol";
import {Timestamp, Slot, Epoch, TimeLib} from "../TimeLib.sol";
import {ValidatorSelectionLib} from "../validator-selection/ValidatorSelectionLib.sol";
import {BlobLib} from "./BlobLib.sol";
import {Header, HeaderLib} from "./HeaderLib.sol";
import {STFLib} from "./STFLib.sol";

struct ProposeArgs {
    bytes32 archive;
    bytes32 blockHash;
    OracleInput oracleInput;
    bytes header;
    bytes32[] txHashes;
}

struct InterimProposeValues {
    bytes32[] blobHashes;
    bytes32 blobsHashesCommitment;
    bytes32 blobPublicInputsHash;
    bytes32 inHash;
    uint256 outboxMinsize;
}

/**
 * @param header - The proposed block header
 * @param attestations - The signatures for the attestations
 * @param digest - The digest that signatures signed
 * @param currentTime - The time of execution
 * @param blobsHashesCommitment - The blobs hash for this block, provided for simpler future simulation
 * @param flags - Flags specific to the execution, whether certain checks should be skipped
 */
struct ValidateHeaderArgs {
    Header header;
    Signature[] attestations;
    bytes32 digest;
    Timestamp currentTime;
    uint256 manaBaseFee;
    bytes32 blobsHashesCommitment;
    BlockHeaderValidationFlags flags;
}

library ProposeLib {
    using TimeLib for Timestamp;
    using TimeLib for Slot;
    using TimeLib for Epoch;

    /**
     * @notice  Publishes the body and propose the block
     * @dev     `eth_log_handlers` rely on this function
     *
     * @param _args - The arguments to propose the block
     * @param _signatures - Signatures from the validators
     * @param _blobInput - The blob evaluation KZG proof, challenge, and opening required for the precompile.
     */
    function propose(
        ProposeArgs calldata _args,
        Signature[] memory _signatures,
        bytes calldata _blobInput,
        bool _checkBlob
    ) internal {
        if (STFLib.canPruneAtTime(Timestamp.wrap(block.timestamp))) {
            STFLib.prune();
        }
        FeeLib.updateL1GasFeeOracle();

        InterimProposeValues memory v;
        // Since an invalid blob hash here would fail the consensus checks of
        // the header, the `blobInput` is implicitly accepted by consensus as well.
        (
            v.blobHashes,
            v.blobsHashesCommitment,
            v.blobPublicInputsHash
        ) = BlobLib.validateBlobs(_blobInput, _checkBlob);

        Header memory header = HeaderLib.decode(_args.header);

        ValidatorSelectionLib.setupEpoch(StakingLib.getStorage());

        ManaBaseFeeComponents memory components = getManaBaseFeeComponentsAt(
            Timestamp.wrap(block.timestamp),
            true
        );

        validateHeader(
            ValidateHeaderArgs({
                header: header,
                attestations: _signatures,
                digest: digest(_args),
                currentTime: Timestamp.wrap(block.timestamp),
                manaBaseFee: FeeLib.summedBaseFee(components),
                blobsHashesCommitment: v.blobsHashesCommitment,
                flags: BlockHeaderValidationFlags({
                    ignoreDA: false,
                    ignoreSignatures: false
                })
            })
        );

        RollupStore storage rollupStore = STFLib.getStorage();
        uint256 blockNumber = ++rollupStore.tips.pendingBlockNumber;

        rollupStore.blocks[blockNumber] = BlockLog({
            archive: _args.archive,
            blockHash: _args.blockHash,
            slotNumber: header.globalVariables.slotNumber
        });

        FeeLib.writeFeeHeader(
            blockNumber,
            _args.oracleInput.feeAssetPriceModifier,
            header.totalManaUsed,
            components.congestionCost,
            components.provingCost
        );

        rollupStore.blobPublicInputsHashes[blockNumber] = v
            .blobPublicInputsHash;

        // @note  The block number here will always be >=1 as the genesis block is at 0
        v.inHash = rollupStore.config.inbox.consume(blockNumber);
        require(
            header.contentCommitment.inHash == v.inHash,
            Errors.Rollup__InvalidInHash(
                v.inHash,
                header.contentCommitment.inHash
            )
        );

        // TODO(#7218): Revert to fixed height tree for outbox, currently just providing min as interim
        // Min size = smallest path of the rollup tree + 1
        (v.outboxMinsize, ) = MerkleLib.computeMinMaxPathLength(
            header.contentCommitment.numTxs
        );
        rollupStore.config.outbox.insert(
            blockNumber,
            header.contentCommitment.outHash,
            v.outboxMinsize + 1
        );

        emit IRollupCore.L2BlockProposed(
            blockNumber,
            _args.archive,
            v.blobHashes
        );
    }

    // @note: not view as sampling validators uses tstore
    function validateHeader(ValidateHeaderArgs memory _args) internal {
        require(
            block.chainid == _args.header.globalVariables.chainId,
            Errors.Rollup__InvalidChainId(
                block.chainid,
                _args.header.globalVariables.chainId
            )
        );

        require(
            _args.header.totalManaUsed <= FeeLib.getManaLimit(),
            Errors.Rollup__ManaLimitExceeded()
        );

        RollupStore storage rollupStore = STFLib.getStorage();

        require(
            _args.header.globalVariables.version == rollupStore.config.version,
            Errors.Rollup__InvalidVersion(
                rollupStore.config.version,
                _args.header.globalVariables.version
            )
        );

        uint256 pendingBlockNumber = STFLib.getEffectivePendingBlockNumber(
            _args.currentTime
        );

        require(
            _args.header.globalVariables.blockNumber == pendingBlockNumber + 1,
            Errors.Rollup__InvalidBlockNumber(
                pendingBlockNumber + 1,
                _args.header.globalVariables.blockNumber
            )
        );

        bytes32 tipArchive = rollupStore.blocks[pendingBlockNumber].archive;
        require(
            tipArchive == _args.header.lastArchive.root,
            Errors.Rollup__InvalidArchive(
                tipArchive,
                _args.header.lastArchive.root
            )
        );

        Slot slot = _args.header.globalVariables.slotNumber;
        Slot lastSlot = rollupStore.blocks[pendingBlockNumber].slotNumber;
        require(
            slot > lastSlot,
            Errors.Rollup__SlotAlreadyInChain(lastSlot, slot)
        );

        Slot currentSlot = _args.currentTime.slotFromTimestamp();
        require(
            slot == currentSlot,
            Errors.HeaderLib__InvalidSlotNumber(currentSlot, slot)
        );

        Timestamp timestamp = TimeLib.toTimestamp(slot);
        require(
            _args.header.globalVariables.timestamp == timestamp,
            Errors.Rollup__InvalidTimestamp(
                timestamp,
                _args.header.globalVariables.timestamp
            )
        );

        require(
            timestamp <= _args.currentTime,
            Errors.Rollup__TimestampInFuture(_args.currentTime, timestamp)
        );

        require(
            _args.flags.ignoreDA ||
                _args.header.contentCommitment.blobsHash ==
                _args.blobsHashesCommitment,
            Errors.Rollup__UnavailableTxs(
                _args.header.contentCommitment.blobsHash
            )
        );

        require(
            _args.header.globalVariables.gasFees.feePerDaGas == 0,
            Errors.Rollup__NonZeroDaFee()
        );
        require(
            _args.header.globalVariables.gasFees.feePerL2Gas ==
                _args.manaBaseFee,
            Errors.Rollup__InvalidManaBaseFee(
                _args.manaBaseFee,
                _args.header.globalVariables.gasFees.feePerL2Gas
            )
        );

        ValidatorSelectionLib.verify(
            StakingLib.getStorage(),
            slot,
            slot.epochFromSlot(),
            _args.attestations,
            _args.digest,
            _args.flags
        );
    }

    /**
     * @notice  Gets the mana base fee components
     *          For more context, consult:
     *          https://github.com/AztecProtocol/engineering-designs/blob/main/in-progress/8757-fees/design.md
     *
     * @param _timestamp - The timestamp of the block
     * @param _inFeeAsset - Whether to return the fee in the fee asset or ETH
     *
     * @return The mana base fee components
     */
    function getManaBaseFeeComponentsAt(
        Timestamp _timestamp,
        bool _inFeeAsset
    ) internal view returns (ManaBaseFeeComponents memory) {
        uint256 blockOfInterest = STFLib.getEffectivePendingBlockNumber(
            _timestamp
        );
        return
            FeeLib.getManaBaseFeeComponentsAt(
                blockOfInterest,
                _timestamp,
                _inFeeAsset
            );
    }

    function digest(ProposeArgs memory _args) internal pure returns (bytes32) {
        return
            keccak256(
                abi.encode(
                    SignatureLib.SignatureDomainSeparator.blockAttestation,
                    _args
                )
            );
    }
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

import {RollupStore, IRollupCore, BlockLog, GenesisState} from "../IRollup.sol";
import {Errors} from "../CoreErrors.sol";
import {Timestamp, Slot, Epoch, TimeLib} from "../TimeLib.sol";

library STFLib {
    using TimeLib for Slot;
    using TimeLib for Epoch;
    using TimeLib for Timestamp;

    // @note  This is also used in the cheatcodes, so if updating, please also update the cheatcode.
    bytes32 private constant STF_STORAGE_POSITION =
        keccak256("aztec.stf.storage");

    function initialize(GenesisState memory _genesisState) internal {
        RollupStore storage rollupStore = STFLib.getStorage();

        rollupStore.config.vkTreeRoot = _genesisState.vkTreeRoot;
        rollupStore.config.protocolContractTreeRoot = _genesisState
            .protocolContractTreeRoot;

        rollupStore.blocks[0] = BlockLog({
            archive: _genesisState.genesisArchiveRoot,
            blockHash: _genesisState.genesisBlockHash,
            slotNumber: Slot.wrap(0)
        });
    }

    function prune() internal {
        RollupStore storage rollupStore = STFLib.getStorage();
        uint256 pending = rollupStore.tips.pendingBlockNumber;

        // @note  We are not deleting the blocks, but we are "winding back" the pendingTip to the last block that was proven.
        //        We can do because any new block proposed will overwrite a previous block in the block log,
        //        so no values should "survive".
        //        People must therefore read the chain using the pendingTip as a boundary.
        rollupStore.tips.pendingBlockNumber = rollupStore
            .tips
            .provenBlockNumber;

        emit IRollupCore.PrunedPending(
            rollupStore.tips.provenBlockNumber,
            pending
        );
    }

    function getEffectivePendingBlockNumber(
        Timestamp _timestamp
    ) internal view returns (uint256) {
        RollupStore storage rollupStore = STFLib.getStorage();
        return
            STFLib.canPruneAtTime(_timestamp)
                ? rollupStore.tips.provenBlockNumber
                : rollupStore.tips.pendingBlockNumber;
    }

    function getEpochForBlock(
        uint256 _blockNumber
    ) internal view returns (Epoch) {
        RollupStore storage rollupStore = STFLib.getStorage();
        require(
            _blockNumber <= rollupStore.tips.pendingBlockNumber,
            Errors.Rollup__InvalidBlockNumber(
                rollupStore.tips.pendingBlockNumber,
                _blockNumber
            )
        );
        return rollupStore.blocks[_blockNumber].slotNumber.epochFromSlot();
    }

    function canPruneAtTime(Timestamp _ts) internal view returns (bool) {
        RollupStore storage rollupStore = STFLib.getStorage();
        if (
            rollupStore.tips.pendingBlockNumber ==
            rollupStore.tips.provenBlockNumber
        ) {
            return false;
        }

        Epoch oldestPendingEpoch = getEpochForBlock(
            rollupStore.tips.provenBlockNumber + 1
        );
        Slot deadline = oldestPendingEpoch.toSlots() +
            Slot.wrap(rollupStore.config.proofSubmissionWindow);

        return deadline < _ts.slotFromTimestamp();
    }

    function getStorage()
        internal
        pure
        returns (RollupStore storage storageStruct)
    {
        bytes32 position = STF_STORAGE_POSITION;
        assembly {
            storageStruct.slot := position
        }
    }
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.1.0) (utils/SlotDerivation.sol)
// This file was procedurally generated from scripts/generate/templates/SlotDerivation.js.

pragma solidity ^0.8.20;

/**
 * @dev Library for computing storage (and transient storage) locations from namespaces and deriving slots
 * corresponding to standard patterns. The derivation method for array and mapping matches the storage layout used by
 * the solidity language / compiler.
 *
 * See https://docs.soliditylang.org/en/v0.8.20/internals/layout_in_storage.html#mappings-and-dynamic-arrays[Solidity docs for mappings and dynamic arrays.].
 *
 * Example usage:
 * ```solidity
 * contract Example {
 *     // Add the library methods
 *     using StorageSlot for bytes32;
 *     using SlotDerivation for bytes32;
 *
 *     // Declare a namespace
 *     string private constant _NAMESPACE = "<namespace>"; // eg. OpenZeppelin.Slot
 *
 *     function setValueInNamespace(uint256 key, address newValue) internal {
 *         _NAMESPACE.erc7201Slot().deriveMapping(key).getAddressSlot().value = newValue;
 *     }
 *
 *     function getValueInNamespace(uint256 key) internal view returns (address) {
 *         return _NAMESPACE.erc7201Slot().deriveMapping(key).getAddressSlot().value;
 *     }
 * }
 * ```
 *
 * TIP: Consider using this library along with {StorageSlot}.
 *
 * NOTE: This library provides a way to manipulate storage locations in a non-standard way. Tooling for checking
 * upgrade safety will ignore the slots accessed through this library.
 *
 * _Available since v5.1._
 */
library SlotDerivation {
    /**
     * @dev Derive an ERC-7201 slot from a string (namespace).
     */
    function erc7201Slot(
        string memory namespace
    ) internal pure returns (bytes32 slot) {
        assembly ("memory-safe") {
            mstore(
                0x00,
                sub(keccak256(add(namespace, 0x20), mload(namespace)), 1)
            )
            slot := and(keccak256(0x00, 0x20), not(0xff))
        }
    }

    /**
     * @dev Add an offset to a slot to get the n-th element of a structure or an array.
     */
    function offset(
        bytes32 slot,
        uint256 pos
    ) internal pure returns (bytes32 result) {
        unchecked {
            return bytes32(uint256(slot) + pos);
        }
    }

    /**
     * @dev Derive the location of the first element in an array from the slot where the length is stored.
     */
    function deriveArray(bytes32 slot) internal pure returns (bytes32 result) {
        assembly ("memory-safe") {
            mstore(0x00, slot)
            result := keccak256(0x00, 0x20)
        }
    }

    /**
     * @dev Derive the location of a mapping element from the key.
     */
    function deriveMapping(
        bytes32 slot,
        address key
    ) internal pure returns (bytes32 result) {
        assembly ("memory-safe") {
            mstore(0x00, and(key, shr(96, not(0))))
            mstore(0x20, slot)
            result := keccak256(0x00, 0x40)
        }
    }

    /**
     * @dev Derive the location of a mapping element from the key.
     */
    function deriveMapping(
        bytes32 slot,
        bool key
    ) internal pure returns (bytes32 result) {
        assembly ("memory-safe") {
            mstore(0x00, iszero(iszero(key)))
            mstore(0x20, slot)
            result := keccak256(0x00, 0x40)
        }
    }

    /**
     * @dev Derive the location of a mapping element from the key.
     */
    function deriveMapping(
        bytes32 slot,
        bytes32 key
    ) internal pure returns (bytes32 result) {
        assembly ("memory-safe") {
            mstore(0x00, key)
            mstore(0x20, slot)
            result := keccak256(0x00, 0x40)
        }
    }

    /**
     * @dev Derive the location of a mapping element from the key.
     */
    function deriveMapping(
        bytes32 slot,
        uint256 key
    ) internal pure returns (bytes32 result) {
        assembly ("memory-safe") {
            mstore(0x00, key)
            mstore(0x20, slot)
            result := keccak256(0x00, 0x40)
        }
    }

    /**
     * @dev Derive the location of a mapping element from the key.
     */
    function deriveMapping(
        bytes32 slot,
        int256 key
    ) internal pure returns (bytes32 result) {
        assembly ("memory-safe") {
            mstore(0x00, key)
            mstore(0x20, slot)
            result := keccak256(0x00, 0x40)
        }
    }

    /**
     * @dev Derive the location of a mapping element from the key.
     */
    function deriveMapping(
        bytes32 slot,
        string memory key
    ) internal pure returns (bytes32 result) {
        assembly ("memory-safe") {
            let length := mload(key)
            let begin := add(key, 0x20)
            let end := add(begin, length)
            let cache := mload(end)
            mstore(end, slot)
            result := keccak256(begin, add(length, 0x20))
            mstore(end, cache)
        }
    }

    /**
     * @dev Derive the location of a mapping element from the key.
     */
    function deriveMapping(
        bytes32 slot,
        bytes memory key
    ) internal pure returns (bytes32 result) {
        assembly ("memory-safe") {
            let length := mload(key)
            let begin := add(key, 0x20)
            let end := add(begin, length)
            let cache := mload(end)
            mstore(end, slot)
            result := keccak256(begin, add(length, 0x20))
            mstore(end, cache)
        }
    }
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

import {Status, ValidatorInfo, Exit, Timestamp, StakingStorage, IStakingCore} from "../IStaking.sol";
import {Errors} from "../CoreErrors.sol";
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";

library StakingLib {
    using SafeERC20 for IERC20;
    using EnumerableSet for EnumerableSet.AddressSet;

    bytes32 private constant STAKING_SLOT =
        keccak256("aztec.core.staking.storage");

    function initialize(
        IERC20 _stakingAsset,
        uint256 _minimumStake,
        Timestamp _exitDelay,
        address _slasher
    ) internal {
        StakingStorage storage store = getStorage();
        store.stakingAsset = _stakingAsset;
        store.minimumStake = _minimumStake;
        store.exitDelay = _exitDelay;
        store.slasher = _slasher;
    }

    function finaliseWithdraw(address _attester) internal {
        StakingStorage storage store = getStorage();
        ValidatorInfo storage validator = store.info[_attester];
        require(
            validator.status == Status.EXITING,
            Errors.Staking__NotExiting(_attester)
        );

        Exit storage exit = store.exits[_attester];
        require(
            exit.exitableAt <= Timestamp.wrap(block.timestamp),
            Errors.Staking__WithdrawalNotUnlockedYet(
                Timestamp.wrap(block.timestamp),
                exit.exitableAt
            )
        );

        uint256 amount = validator.stake;
        address recipient = exit.recipient;

        delete store.exits[_attester];
        delete store.info[_attester];

        store.stakingAsset.transfer(recipient, amount);

        emit IStakingCore.WithdrawFinalised(_attester, recipient, amount);
    }

    function slash(address _attester, uint256 _amount) internal {
        StakingStorage storage store = getStorage();
        require(
            msg.sender == store.slasher,
            Errors.Staking__NotSlasher(store.slasher, msg.sender)
        );

        ValidatorInfo storage validator = store.info[_attester];
        require(
            validator.status != Status.NONE,
            Errors.Staking__NoOneToSlash(_attester)
        );

        // There is a special, case, if exiting and past the limit, it is untouchable!
        require(
            !(validator.status == Status.EXITING &&
                store.exits[_attester].exitableAt <=
                Timestamp.wrap(block.timestamp)),
            Errors.Staking__CannotSlashExitedStake(_attester)
        );
        validator.stake -= _amount;

        // If the attester was validating AND is slashed below the MINIMUM_STAKE we update him to LIVING
        // When LIVING, he can only start exiting, we don't "really" exit him, because that cost
        // gas and cost edge cases around recipient, so lets just avoid that.
        if (
            validator.status == Status.VALIDATING &&
            validator.stake < store.minimumStake
        ) {
            require(
                store.attesters.remove(_attester),
                Errors.Staking__FailedToRemove(_attester)
            );
            validator.status = Status.LIVING;
        }

        emit IStakingCore.Slashed(_attester, _amount);
    }

    function deposit(
        address _attester,
        address _proposer,
        address _withdrawer,
        uint256 _amount
    ) internal {
        require(
            _attester != address(0) && _proposer != address(0),
            Errors.Staking__InvalidDeposit(_attester, _proposer)
        );
        StakingStorage storage store = getStorage();
        require(
            _amount >= store.minimumStake,
            Errors.Staking__InsufficientStake(_amount, store.minimumStake)
        );
        store.stakingAsset.transferFrom(msg.sender, address(this), _amount);
        require(
            store.info[_attester].status == Status.NONE,
            Errors.Staking__AlreadyRegistered(_attester)
        );
        require(
            store.attesters.add(_attester),
            Errors.Staking__AlreadyActive(_attester)
        );

        // If BLS, need to check possession of private key to avoid attacks.

        store.info[_attester] = ValidatorInfo({
            stake: _amount,
            withdrawer: _withdrawer,
            proposer: _proposer,
            status: Status.VALIDATING
        });

        emit IStakingCore.Deposit(_attester, _proposer, _withdrawer, _amount);
    }

    function initiateWithdraw(
        address _attester,
        address _recipient
    ) internal returns (bool) {
        StakingStorage storage store = getStorage();
        ValidatorInfo storage validator = store.info[_attester];

        require(
            msg.sender == validator.withdrawer,
            Errors.Staking__NotWithdrawer(validator.withdrawer, msg.sender)
        );
        require(
            validator.status == Status.VALIDATING ||
                validator.status == Status.LIVING,
            Errors.Staking__NothingToExit(_attester)
        );
        if (validator.status == Status.VALIDATING) {
            require(
                store.attesters.remove(_attester),
                Errors.Staking__FailedToRemove(_attester)
            );
        }

        // Note that the "amount" is not stored here, but reusing the `validators`
        // We always exit fully.
        // @note The attester might be chosen for the epoch, so the delay must be long enough
        //       to allow for that.
        store.exits[_attester] = Exit({
            exitableAt: Timestamp.wrap(block.timestamp) + store.exitDelay,
            recipient: _recipient
        });
        validator.status = Status.EXITING;

        emit IStakingCore.WithdrawInitiated(
            _attester,
            _recipient,
            validator.stake
        );

        return true;
    }

    function getStorage()
        internal
        pure
        returns (StakingStorage storage storageStruct)
    {
        bytes32 position = STAKING_SLOT;
        assembly {
            storageStruct.slot := position
        }
    }
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

// solhint-disable-next-line no-unused-import
import {Timestamp, Slot, Epoch, SlotLib, EpochLib} from "./TimeMath.sol";

struct TimeStorage {
    uint256 genesisTime;
    uint256 slotDuration; // Number of seconds in a slot
    uint256 epochDuration; // Number of slots in an epoch
}

library TimeLib {
    bytes32 private constant TIME_STORAGE_POSITION =
        keccak256("aztec.time.storage");

    function initialize(
        uint256 _genesisTime,
        uint256 _slotDuration,
        uint256 _epochDuration
    ) internal {
        TimeStorage storage store = getStorage();
        store.genesisTime = _genesisTime;
        store.slotDuration = _slotDuration;
        store.epochDuration = _epochDuration;
    }

    function toTimestamp(Slot _a) internal view returns (Timestamp) {
        TimeStorage storage store = getStorage();
        return
            Timestamp.wrap(store.genesisTime) +
            Timestamp.wrap(Slot.unwrap(_a) * store.slotDuration);
    }

    function slotFromTimestamp(Timestamp _a) internal view returns (Slot) {
        TimeStorage storage store = getStorage();
        return
            Slot.wrap(
                (Timestamp.unwrap(_a) - store.genesisTime) / store.slotDuration
            );
    }

    function positionInEpoch(Slot _a) internal view returns (uint256) {
        return Slot.unwrap(_a) % getStorage().epochDuration;
    }

    function toSlots(Epoch _a) internal view returns (Slot) {
        return Slot.wrap(Epoch.unwrap(_a) * getStorage().epochDuration);
    }

    function toTimestamp(Epoch _a) internal view returns (Timestamp) {
        return toTimestamp(toSlots(_a));
    }

    function epochFromTimestamp(Timestamp _a) internal view returns (Epoch) {
        TimeStorage storage store = getStorage();
        return
            Epoch.wrap(
                (Timestamp.unwrap(_a) - store.genesisTime) /
                    (store.epochDuration * store.slotDuration)
            );
    }

    function epochFromSlot(Slot _a) internal view returns (Epoch) {
        return Epoch.wrap(Slot.unwrap(_a) / getStorage().epochDuration);
    }

    function getStorage()
        internal
        pure
        returns (TimeStorage storage storageStruct)
    {
        bytes32 position = TIME_STORAGE_POSITION;
        assembly {
            storageStruct.slot := position
        }
    }
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

type Timestamp is uint256;

type Slot is uint256;

type Epoch is uint256;

library SlotLib {
  function unwrap(Slot _a) internal pure returns (uint256) {
    return Slot.unwrap(_a);
  }
}

library EpochLib {
  function unwrap(Epoch _a) internal pure returns (uint256) {
    return Epoch.unwrap(_a);
  }
}

using SlotLib for Slot;
using EpochLib for Epoch;

function addTimestamp(Timestamp _a, Timestamp _b) pure returns (Timestamp) {
  return Timestamp.wrap(Timestamp.unwrap(_a) + Timestamp.unwrap(_b));
}

function subTimestamp(Timestamp _a, Timestamp _b) pure returns (Timestamp) {
  return Timestamp.wrap(Timestamp.unwrap(_a) - Timestamp.unwrap(_b));
}

function ltTimestamp(Timestamp _a, Timestamp _b) pure returns (bool) {
  return Timestamp.unwrap(_a) < Timestamp.unwrap(_b);
}

function lteTimestamp(Timestamp _a, Timestamp _b) pure returns (bool) {
  return Timestamp.unwrap(_a) <= Timestamp.unwrap(_b);
}

function gtTimestamp(Timestamp _a, Timestamp _b) pure returns (bool) {
  return Timestamp.unwrap(_a) > Timestamp.unwrap(_b);
}

function gteTimestamp(Timestamp _a, Timestamp _b) pure returns (bool) {
  return Timestamp.unwrap(_a) >= Timestamp.unwrap(_b);
}

function neqTimestamp(Timestamp _a, Timestamp _b) pure returns (bool) {
  return Timestamp.unwrap(_a) != Timestamp.unwrap(_b);
}

function eqTimestamp(Timestamp _a, Timestamp _b) pure returns (bool) {
  return Timestamp.unwrap(_a) == Timestamp.unwrap(_b);
}

// Slot

function addSlot(Slot _a, Slot _b) pure returns (Slot) {
  return Slot.wrap(Slot.unwrap(_a) + Slot.unwrap(_b));
}

function subSlot(Slot _a, Slot _b) pure returns (Slot) {
  return Slot.wrap(Slot.unwrap(_a) - Slot.unwrap(_b));
}

function eqSlot(Slot _a, Slot _b) pure returns (bool) {
  return Slot.unwrap(_a) == Slot.unwrap(_b);
}

function neqSlot(Slot _a, Slot _b) pure returns (bool) {
  return Slot.unwrap(_a) != Slot.unwrap(_b);
}

function ltSlot(Slot _a, Slot _b) pure returns (bool) {
  return Slot.unwrap(_a) < Slot.unwrap(_b);
}

function lteSlot(Slot _a, Slot _b) pure returns (bool) {
  return Slot.unwrap(_a) <= Slot.unwrap(_b);
}

function gtSlot(Slot _a, Slot _b) pure returns (bool) {
  return Slot.unwrap(_a) > Slot.unwrap(_b);
}

function gteSlot(Slot _a, Slot _b) pure returns (bool) {
  return Slot.unwrap(_a) >= Slot.unwrap(_b);
}

// Epoch

function eqEpoch(Epoch _a, Epoch _b) pure returns (bool) {
  return Epoch.unwrap(_a) == Epoch.unwrap(_b);
}

function neqEpoch(Epoch _a, Epoch _b) pure returns (bool) {
  return Epoch.unwrap(_a) != Epoch.unwrap(_b);
}

function subEpoch(Epoch _a, Epoch _b) pure returns (Epoch) {
  return Epoch.wrap(Epoch.unwrap(_a) - Epoch.unwrap(_b));
}

function addEpoch(Epoch _a, Epoch _b) pure returns (Epoch) {
  return Epoch.wrap(Epoch.unwrap(_a) + Epoch.unwrap(_b));
}

function gteEpoch(Epoch _a, Epoch _b) pure returns (bool) {
  return Epoch.unwrap(_a) >= Epoch.unwrap(_b);
}

function gtEpoch(Epoch _a, Epoch _b) pure returns (bool) {
  return Epoch.unwrap(_a) > Epoch.unwrap(_b);
}

function lteEpoch(Epoch _a, Epoch _b) pure returns (bool) {
  return Epoch.unwrap(_a) <= Epoch.unwrap(_b);
}

function ltEpoch(Epoch _a, Epoch _b) pure returns (bool) {
  return Epoch.unwrap(_a) < Epoch.unwrap(_b);
}

using {
  addTimestamp as +,
  subTimestamp as -,
  ltTimestamp as <,
  gtTimestamp as >,
  lteTimestamp as <=,
  gteTimestamp as >=,
  neqTimestamp as !=,
  eqTimestamp as ==
} for Timestamp global;

using {
  addEpoch as +,
  subEpoch as -,
  eqEpoch as ==,
  neqEpoch as !=,
  gteEpoch as >=,
  gtEpoch as >,
  lteEpoch as <=,
  ltEpoch as <
} for Epoch global;

using {
  eqSlot as ==,
  neqSlot as !=,
  gteSlot as >=,
  gtSlot as >,
  lteSlot as <=,
  ltSlot as <,
  addSlot as +,
  subSlot as -
} for Slot global;

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.1.0) (utils/TransientSlot.sol)
// This file was procedurally generated from scripts/generate/templates/TransientSlot.js.

pragma solidity ^0.8.24;

/**
 * @dev Library for reading and writing value-types to specific transient storage slots.
 *
 * Transient slots are often used to store temporary values that are removed after the current transaction.
 * This library helps with reading and writing to such slots without the need for inline assembly.
 *
 *  * Example reading and writing values using transient storage:
 * ```solidity
 * contract Lock {
 *     using TransientSlot for *;
 *
 *     // Define the slot. Alternatively, use the SlotDerivation library to derive the slot.
 *     bytes32 internal constant _LOCK_SLOT = 0xf4678858b2b588224636b8522b729e7722d32fc491da849ed75b3fdf3c84f542;
 *
 *     modifier locked() {
 *         require(!_LOCK_SLOT.asBoolean().tload());
 *
 *         _LOCK_SLOT.asBoolean().tstore(true);
 *         _;
 *         _LOCK_SLOT.asBoolean().tstore(false);
 *     }
 * }
 * ```
 *
 * TIP: Consider using this library along with {SlotDerivation}.
 */
library TransientSlot {
    /**
     * @dev UDVT that represents a slot holding an address.
     */
    type AddressSlot is bytes32;

    /**
     * @dev Cast an arbitrary slot to a AddressSlot.
     */
    function asAddress(bytes32 slot) internal pure returns (AddressSlot) {
        return AddressSlot.wrap(slot);
    }

    /**
     * @dev UDVT that represents a slot holding a bool.
     */
    type BooleanSlot is bytes32;

    /**
     * @dev Cast an arbitrary slot to a BooleanSlot.
     */
    function asBoolean(bytes32 slot) internal pure returns (BooleanSlot) {
        return BooleanSlot.wrap(slot);
    }

    /**
     * @dev UDVT that represents a slot holding a bytes32.
     */
    type Bytes32Slot is bytes32;

    /**
     * @dev Cast an arbitrary slot to a Bytes32Slot.
     */
    function asBytes32(bytes32 slot) internal pure returns (Bytes32Slot) {
        return Bytes32Slot.wrap(slot);
    }

    /**
     * @dev UDVT that represents a slot holding a uint256.
     */
    type Uint256Slot is bytes32;

    /**
     * @dev Cast an arbitrary slot to a Uint256Slot.
     */
    function asUint256(bytes32 slot) internal pure returns (Uint256Slot) {
        return Uint256Slot.wrap(slot);
    }

    /**
     * @dev UDVT that represents a slot holding a int256.
     */
    type Int256Slot is bytes32;

    /**
     * @dev Cast an arbitrary slot to a Int256Slot.
     */
    function asInt256(bytes32 slot) internal pure returns (Int256Slot) {
        return Int256Slot.wrap(slot);
    }

    /**
     * @dev Load the value held at location `slot` in transient storage.
     */
    function tload(AddressSlot slot) internal view returns (address value) {
        assembly ("memory-safe") {
            value := tload(slot)
        }
    }

    /**
     * @dev Store `value` at location `slot` in transient storage.
     */
    function tstore(AddressSlot slot, address value) internal {
        assembly ("memory-safe") {
            tstore(slot, value)
        }
    }

    /**
     * @dev Load the value held at location `slot` in transient storage.
     */
    function tload(BooleanSlot slot) internal view returns (bool value) {
        assembly ("memory-safe") {
            value := tload(slot)
        }
    }

    /**
     * @dev Store `value` at location `slot` in transient storage.
     */
    function tstore(BooleanSlot slot, bool value) internal {
        assembly ("memory-safe") {
            tstore(slot, value)
        }
    }

    /**
     * @dev Load the value held at location `slot` in transient storage.
     */
    function tload(Bytes32Slot slot) internal view returns (bytes32 value) {
        assembly ("memory-safe") {
            value := tload(slot)
        }
    }

    /**
     * @dev Store `value` at location `slot` in transient storage.
     */
    function tstore(Bytes32Slot slot, bytes32 value) internal {
        assembly ("memory-safe") {
            tstore(slot, value)
        }
    }

    /**
     * @dev Load the value held at location `slot` in transient storage.
     */
    function tload(Uint256Slot slot) internal view returns (uint256 value) {
        assembly ("memory-safe") {
            value := tload(slot)
        }
    }

    /**
     * @dev Store `value` at location `slot` in transient storage.
     */
    function tstore(Uint256Slot slot, uint256 value) internal {
        assembly ("memory-safe") {
            tstore(slot, value)
        }
    }

    /**
     * @dev Load the value held at location `slot` in transient storage.
     */
    function tload(Int256Slot slot) internal view returns (int256 value) {
        assembly ("memory-safe") {
            value := tload(slot)
        }
    }

    /**
     * @dev Store `value` at location `slot` in transient storage.
     */
    function tstore(Int256Slot slot, int256 value) internal {
        assembly ("memory-safe") {
            tstore(slot, value)
        }
    }
}

// SPDX-License-Identifier: Apache-2.0
// Copyright 2024 Aztec Labs.
pragma solidity >=0.8.27;

import {BlockHeaderValidationFlags} from "../IRollup.sol";
import {StakingStorage} from "../IStaking.sol";
import {EpochData, ValidatorSelectionStorage} from "../IValidatorSelection.sol";
import {SampleLib} from "../crypto/SampleLib.sol";
import {SignatureLib, Signature} from "../crypto/SignatureLib.sol";
import {Errors} from "../CoreErrors.sol";
import {Timestamp, Slot, Epoch, TimeLib} from "../TimeLib.sol";
import {MessageHashUtils} from "@openzeppelin/contracts/utils/cryptography/MessageHashUtils.sol";
import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";

library ValidatorSelectionLib {
    using EnumerableSet for EnumerableSet.AddressSet;
    using MessageHashUtils for bytes32;
    using SignatureLib for Signature;
    using TimeLib for Timestamp;

    bytes32 private constant VALIDATOR_SELECTION_STORAGE_POSITION =
        keccak256("aztec.validator_selection.storage");

    function initialize(uint256 _targetCommitteeSize) internal {
        ValidatorSelectionStorage storage store = getStorage();
        store.targetCommitteeSize = _targetCommitteeSize;
    }

    /**
     * @notice  Performs a setup of an epoch if needed. The setup will
     *          - Sample the validator set for the epoch
     *          - Set the seed for the epoch
     *          - Update the last seed
     *
     * @dev     Since this is a reference optimising for simplicity, we store the actual validator set in the epoch structure.
     *          This is very heavy on gas, so start crying because the gas here will melt the poles
     *          https://i.giphy.com/U1aN4HTfJ2SmgB2BBK.webp
     */
    function setupEpoch(StakingStorage storage _stakingStore) internal {
        Epoch epochNumber = Timestamp
            .wrap(block.timestamp)
            .epochFromTimestamp();
        ValidatorSelectionStorage storage store = getStorage();
        EpochData storage epoch = store.epochs[epochNumber];

        if (epoch.sampleSeed == 0) {
            epoch.sampleSeed = getSampleSeed(epochNumber);
            epoch.nextSeed = store.lastSeed = computeNextSeed(epochNumber);
            epoch.committee = sampleValidators(_stakingStore, epoch.sampleSeed);
        }
    }

    /**
     * @notice  Propose a pending block from the point-of-view of sequencer selection. Will:
     *          - Setup the epoch if needed (if epoch committee is empty skips the rest)
     *          - Validate that the proposer is the proposer of the slot
     *          - Validate that the signatures for attestations are indeed from the validatorset
     *          - Validate that the number of valid attestations is sufficient
     *
     * @dev     Cases where errors are thrown:
     *          - If the epoch is not setup
     *          - If the proposer is not the real proposer AND the proposer is not open
     *          - If the number of valid attestations is insufficient
     *
     * @param _slot - The slot of the block
     * @param _signatures - The signatures of the committee members
     * @param _digest - The digest of the block
     */
    function verify(
        StakingStorage storage _stakingStore,
        Slot _slot,
        Epoch _epochNumber,
        Signature[] memory _signatures,
        bytes32 _digest,
        BlockHeaderValidationFlags memory _flags
    ) internal {
        // Same logic as we got in getProposerAt
        // Done do avoid duplicate computing the committee
        address[] memory committee = getCommitteeAt(
            _stakingStore,
            _epochNumber
        );
        address attester = committee.length == 0
            ? address(0)
            : committee[
                computeProposerIndex(
                    _epochNumber,
                    _slot,
                    getSampleSeed(_epochNumber),
                    committee.length
                )
            ];
        address proposer = _stakingStore.info[attester].proposer;

        // @todo Consider getting rid of this option.
        // If the proposer is open, we allow anyone to propose without needing any signatures
        if (proposer == address(0)) {
            return;
        }

        require(
            proposer == msg.sender,
            Errors.ValidatorSelection__InvalidProposer(proposer, msg.sender)
        );

        if (_flags.ignoreSignatures) {
            return;
        }

        uint256 needed = (committee.length * 2) / 3 + 1;
        require(
            _signatures.length >= needed,
            Errors.ValidatorSelection__InsufficientAttestationsProvided(
                needed,
                _signatures.length
            )
        );

        // Validate the attestations
        uint256 validAttestations = 0;

        bytes32 digest = _digest.toEthSignedMessageHash();
        for (uint256 i = 0; i < _signatures.length; i++) {
            // To avoid stack too deep errors
            Signature memory signature = _signatures[i];
            if (signature.isEmpty) {
                continue;
            }

            // The verification will throw if invalid
            signature.verify(committee[i], digest);
            validAttestations++;
        }

        require(
            validAttestations >= needed,
            Errors.ValidatorSelection__InsufficientAttestations(
                needed,
                validAttestations
            )
        );
    }

    function getProposerAt(
        StakingStorage storage _stakingStore,
        Slot _slot,
        Epoch _epochNumber
    ) internal returns (address) {
        // @note this is deliberately "bad" for the simple reason of code reduction.
        //       it does not need to actually return the full committee and then draw from it
        //       it can just return the proposer directly, but then we duplicate the code
        //       which we just don't have room for right now...
        address[] memory committee = getCommitteeAt(
            _stakingStore,
            _epochNumber
        );
        if (committee.length == 0) {
            return address(0);
        }

        address attester = committee[
            computeProposerIndex(
                _epochNumber,
                _slot,
                getSampleSeed(_epochNumber),
                committee.length
            )
        ];

        return _stakingStore.info[attester].proposer;
    }

    /**
     * @notice  Samples a validator set for a specific epoch
     *
     * @dev     Only used internally, should never be called for anything but the "next" epoch
     *          Allowing us to always use `lastSeed`.
     *
     * @return The validators for the given epoch
     */
    function sampleValidators(
        StakingStorage storage _stakingStore,
        uint256 _seed
    ) internal returns (address[] memory) {
        uint256 validatorSetSize = _stakingStore.attesters.length();
        if (validatorSetSize == 0) {
            return new address[](0);
        }

        ValidatorSelectionStorage storage store = getStorage();
        uint256 targetCommitteeSize = store.targetCommitteeSize;

        // If we have less validators than the target committee size, we just return the full set
        if (validatorSetSize <= targetCommitteeSize) {
            return _stakingStore.attesters.values();
        }

        uint256[] memory indices = SampleLib.computeCommittee(
            targetCommitteeSize,
            validatorSetSize,
            _seed
        );

        address[] memory committee = new address[](targetCommitteeSize);
        for (uint256 i = 0; i < targetCommitteeSize; i++) {
            committee[i] = _stakingStore.attesters.at(indices[i]);
        }
        return committee;
    }

    function getCommitteeAt(
        StakingStorage storage _stakingStore,
        Epoch _epochNumber
    ) internal returns (address[] memory) {
        ValidatorSelectionStorage storage store = getStorage();
        EpochData storage epoch = store.epochs[_epochNumber];

        if (epoch.sampleSeed != 0) {
            uint256 committeeSize = epoch.committee.length;
            if (committeeSize == 0) {
                return new address[](0);
            }
            return epoch.committee;
        }

        // Allow anyone if there is no validator set
        if (_stakingStore.attesters.length() == 0) {
            return new address[](0);
        }

        // Emulate a sampling of the validators
        uint256 sampleSeed = getSampleSeed(_epochNumber);
        return sampleValidators(_stakingStore, sampleSeed);
    }

    /**
     * @notice  Get the sample seed for an epoch
     *
     * @dev     This should behave as walking past the line, but it does not currently do that.
     *          If there are entire skips, e.g., 1, 2, 5 and we then go back and try executing
     *          for 4 we will get an invalid value because we will read lastSeed which is from 5.
     *
     * @dev     The `_epoch` will never be 0 nor in the future
     *
     * @dev     The return value will be equal to keccak256(n, block.prevrandao) for n being the last epoch
     *          setup.
     *
     * @return The sample seed for the epoch
     */
    function getSampleSeed(Epoch _epoch) internal view returns (uint256) {
        if (Epoch.unwrap(_epoch) == 0) {
            return type(uint256).max;
        }
        ValidatorSelectionStorage storage store = getStorage();
        uint256 sampleSeed = store.epochs[_epoch].sampleSeed;
        if (sampleSeed != 0) {
            return sampleSeed;
        }

        sampleSeed = store.epochs[_epoch - Epoch.wrap(1)].nextSeed;
        if (sampleSeed != 0) {
            return sampleSeed;
        }

        return store.lastSeed;
    }

    function getStorage()
        internal
        pure
        returns (ValidatorSelectionStorage storage storageStruct)
    {
        bytes32 position = VALIDATOR_SELECTION_STORAGE_POSITION;
        assembly {
            storageStruct.slot := position
        }
    }

    /**
     * @notice  Computes the nextSeed for an epoch
     *
     * @dev     We include the `_epoch` instead of using the randao directly to avoid issues with foundry testing
     *          where randao == 0.
     *
     * @param _epoch - The epoch to compute the seed for
     *
     * @return The computed seed
     */
    function computeNextSeed(Epoch _epoch) private view returns (uint256) {
        return uint256(keccak256(abi.encode(_epoch, block.prevrandao)));
    }

    /**
     * @notice  Computes the index of the committee member that acts as proposer for a given slot
     *
     * @param _epoch - The epoch to compute the proposer index for
     * @param _slot - The slot to compute the proposer index for
     * @param _seed - The seed to use for the computation
     * @param _size - The size of the committee
     *
     * @return The index of the proposer
     */
    function computeProposerIndex(
        Epoch _epoch,
        Slot _slot,
        uint256 _seed,
        uint256 _size
    ) private pure returns (uint256) {
        return uint256(keccak256(abi.encode(_epoch, _slot, _seed))) % _size;
    }
}

// Automatically @generated by scripts/vm.py. Do not modify manually.

// SPDX-License-Identifier: MIT OR Apache-2.0
pragma solidity >=0.6.2 <0.9.0;
pragma experimental ABIEncoderV2;

/// The `VmSafe` interface does not allow manipulation of the EVM state or other actions that may
/// result in Script simulations differing from on-chain execution. It is recommended to only use
/// these cheats in scripts.
interface VmSafe {
    /// A modification applied to either `msg.sender` or `tx.origin`. Returned by `readCallers`.
    enum CallerMode {
        // No caller modification is currently active.
        None,
        // A one time broadcast triggered by a `vm.broadcast()` call is currently active.
        Broadcast,
        // A recurrent broadcast triggered by a `vm.startBroadcast()` call is currently active.
        RecurrentBroadcast,
        // A one time prank triggered by a `vm.prank()` call is currently active.
        Prank,
        // A recurrent prank triggered by a `vm.startPrank()` call is currently active.
        RecurrentPrank
    }

    /// The kind of account access that occurred.
    enum AccountAccessKind {
        // The account was called.
        Call,
        // The account was called via delegatecall.
        DelegateCall,
        // The account was called via callcode.
        CallCode,
        // The account was called via staticcall.
        StaticCall,
        // The account was created.
        Create,
        // The account was selfdestructed.
        SelfDestruct,
        // Synthetic access indicating the current context has resumed after a previous sub-context (AccountAccess).
        Resume,
        // The account's balance was read.
        Balance,
        // The account's codesize was read.
        Extcodesize,
        // The account's codehash was read.
        Extcodehash,
        // The account's code was copied.
        Extcodecopy
    }

    /// Forge execution contexts.
    enum ForgeContext {
        // Test group execution context (test, coverage or snapshot).
        TestGroup,
        // `forge test` execution context.
        Test,
        // `forge coverage` execution context.
        Coverage,
        // `forge snapshot` execution context.
        Snapshot,
        // Script group execution context (dry run, broadcast or resume).
        ScriptGroup,
        // `forge script` execution context.
        ScriptDryRun,
        // `forge script --broadcast` execution context.
        ScriptBroadcast,
        // `forge script --resume` execution context.
        ScriptResume,
        // Unknown `forge` execution context.
        Unknown
    }

    /// The transaction type (`txType`) of the broadcast.
    enum BroadcastTxType {
        // Represents a CALL broadcast tx.
        Call,
        // Represents a CREATE broadcast tx.
        Create,
        // Represents a CREATE2 broadcast tx.
        Create2
    }

    /// An Ethereum log. Returned by `getRecordedLogs`.
    struct Log {
        // The topics of the log, including the signature, if any.
        bytes32[] topics;
        // The raw data of the log.
        bytes data;
        // The address of the log's emitter.
        address emitter;
    }

    /// An RPC URL and its alias. Returned by `rpcUrlStructs`.
    struct Rpc {
        // The alias of the RPC URL.
        string key;
        // The RPC URL.
        string url;
    }

    /// An RPC log object. Returned by `eth_getLogs`.
    struct EthGetLogs {
        // The address of the log's emitter.
        address emitter;
        // The topics of the log, including the signature, if any.
        bytes32[] topics;
        // The raw data of the log.
        bytes data;
        // The block hash.
        bytes32 blockHash;
        // The block number.
        uint64 blockNumber;
        // The transaction hash.
        bytes32 transactionHash;
        // The transaction index in the block.
        uint64 transactionIndex;
        // The log index.
        uint256 logIndex;
        // Whether the log was removed.
        bool removed;
    }

    /// A single entry in a directory listing. Returned by `readDir`.
    struct DirEntry {
        // The error message, if any.
        string errorMessage;
        // The path of the entry.
        string path;
        // The depth of the entry.
        uint64 depth;
        // Whether the entry is a directory.
        bool isDir;
        // Whether the entry is a symlink.
        bool isSymlink;
    }

    /// Metadata information about a file.
    /// This structure is returned from the `fsMetadata` function and represents known
    /// metadata about a file such as its permissions, size, modification
    /// times, etc.
    struct FsMetadata {
        // True if this metadata is for a directory.
        bool isDir;
        // True if this metadata is for a symlink.
        bool isSymlink;
        // The size of the file, in bytes, this metadata is for.
        uint256 length;
        // True if this metadata is for a readonly (unwritable) file.
        bool readOnly;
        // The last modification time listed in this metadata.
        uint256 modified;
        // The last access time of this metadata.
        uint256 accessed;
        // The creation time listed in this metadata.
        uint256 created;
    }

    /// A wallet with a public and private key.
    struct Wallet {
        // The wallet's address.
        address addr;
        // The wallet's public key `X`.
        uint256 publicKeyX;
        // The wallet's public key `Y`.
        uint256 publicKeyY;
        // The wallet's private key.
        uint256 privateKey;
    }

    /// The result of a `tryFfi` call.
    struct FfiResult {
        // The exit code of the call.
        int32 exitCode;
        // The optionally hex-decoded `stdout` data.
        bytes stdout;
        // The `stderr` data.
        bytes stderr;
    }

    /// Information on the chain and fork.
    struct ChainInfo {
        // The fork identifier. Set to zero if no fork is active.
        uint256 forkId;
        // The chain ID of the current fork.
        uint256 chainId;
    }

    /// The result of a `stopAndReturnStateDiff` call.
    struct AccountAccess {
        // The chain and fork the access occurred.
        ChainInfo chainInfo;
        // The kind of account access that determines what the account is.
        // If kind is Call, DelegateCall, StaticCall or CallCode, then the account is the callee.
        // If kind is Create, then the account is the newly created account.
        // If kind is SelfDestruct, then the account is the selfdestruct recipient.
        // If kind is a Resume, then account represents a account context that has resumed.
        AccountAccessKind kind;
        // The account that was accessed.
        // It's either the account created, callee or a selfdestruct recipient for CREATE, CALL or SELFDESTRUCT.
        address account;
        // What accessed the account.
        address accessor;
        // If the account was initialized or empty prior to the access.
        // An account is considered initialized if it has code, a
        // non-zero nonce, or a non-zero balance.
        bool initialized;
        // The previous balance of the accessed account.
        uint256 oldBalance;
        // The potential new balance of the accessed account.
        // That is, all balance changes are recorded here, even if reverts occurred.
        uint256 newBalance;
        // Code of the account deployed by CREATE.
        bytes deployedCode;
        // Value passed along with the account access
        uint256 value;
        // Input data provided to the CREATE or CALL
        bytes data;
        // If this access reverted in either the current or parent context.
        bool reverted;
        // An ordered list of storage accesses made during an account access operation.
        StorageAccess[] storageAccesses;
        // Call depth traversed during the recording of state differences
        uint64 depth;
    }

    /// The storage accessed during an `AccountAccess`.
    struct StorageAccess {
        // The account whose storage was accessed.
        address account;
        // The slot that was accessed.
        bytes32 slot;
        // If the access was a write.
        bool isWrite;
        // The previous value of the slot.
        bytes32 previousValue;
        // The new value of the slot.
        bytes32 newValue;
        // If the access was reverted.
        bool reverted;
    }

    /// Gas used. Returned by `lastCallGas`.
    struct Gas {
        // The gas limit of the call.
        uint64 gasLimit;
        // The total gas used.
        uint64 gasTotalUsed;
        // DEPRECATED: The amount of gas used for memory expansion. Ref: <https://github.com/foundry-rs/foundry/pull/7934#pullrequestreview-2069236939>
        uint64 gasMemoryUsed;
        // The amount of gas refunded.
        int64 gasRefunded;
        // The amount of gas remaining.
        uint64 gasRemaining;
    }

    /// The result of the `stopDebugTraceRecording` call
    struct DebugStep {
        // The stack before executing the step of the run.
        // stack\[0\] represents the top of the stack.
        // and only stack data relevant to the opcode execution is contained.
        uint256[] stack;
        // The memory input data before executing the step of the run.
        // only input data relevant to the opcode execution is contained.
        // e.g. for MLOAD, it will have memory\[offset:offset+32\] copied here.
        // the offset value can be get by the stack data.
        bytes memoryInput;
        // The opcode that was accessed.
        uint8 opcode;
        // The call depth of the step.
        uint64 depth;
        // Whether the call end up with out of gas error.
        bool isOutOfGas;
        // The contract address where the opcode is running
        address contractAddr;
    }

    /// Represents a transaction's broadcast details.
    struct BroadcastTxSummary {
        // The hash of the transaction that was broadcasted
        bytes32 txHash;
        // Represent the type of transaction among CALL, CREATE, CREATE2
        BroadcastTxType txType;
        // The address of the contract that was called or created.
        // This is address of the contract that is created if the txType is CREATE or CREATE2.
        address contractAddress;
        // The block number the transaction landed in.
        uint64 blockNumber;
        // Status of the transaction, retrieved from the transaction receipt.
        bool success;
    }

    /// Holds a signed EIP-7702 authorization for an authority account to delegate to an implementation.
    struct SignedDelegation {
        // The y-parity of the recovered secp256k1 signature (0 or 1).
        uint8 v;
        // First 32 bytes of the signature.
        bytes32 r;
        // Second 32 bytes of the signature.
        bytes32 s;
        // The current nonce of the authority account at signing time.
        // Used to ensure signature can't be replayed after account nonce changes.
        uint64 nonce;
        // Address of the contract implementation that will be delegated to.
        // Gets encoded into delegation code: 0xef0100 || implementation.
        address implementation;
    }

    /// Represents a "potential" revert reason from a single subsequent call when using `vm.assumeNoReverts`.
    /// Reverts that match will result in a FOUNDRY::ASSUME rejection, whereas unmatched reverts will be surfaced
    /// as normal.
    struct PotentialRevert {
        // The allowed origin of the revert opcode; address(0) allows reverts from any address
        address reverter;
        // When true, only matches on the beginning of the revert data, otherwise, matches on entire revert data
        bool partialMatch;
        // The data to use to match encountered reverts
        bytes revertData;
    }

    /// An EIP-2930 access list item.
    struct AccessListItem {
        // The address to be added in access list.
        address target;
        // The storage keys to be added in access list.
        bytes32[] storageKeys;
    }

    // ======== Crypto ========

    /// Derives a private key from the name, labels the account with that name, and returns the wallet.
    function createWallet(
        string calldata walletLabel
    ) external returns (Wallet memory wallet);

    /// Generates a wallet from the private key and returns the wallet.
    function createWallet(
        uint256 privateKey
    ) external returns (Wallet memory wallet);

    /// Generates a wallet from the private key, labels the account with that name, and returns the wallet.
    function createWallet(
        uint256 privateKey,
        string calldata walletLabel
    ) external returns (Wallet memory wallet);

    /// Derive a private key from a provided mnenomic string (or mnenomic file path)
    /// at the derivation path `m/44'/60'/0'/0/{index}`.
    function deriveKey(
        string calldata mnemonic,
        uint32 index
    ) external pure returns (uint256 privateKey);

    /// Derive a private key from a provided mnenomic string (or mnenomic file path)
    /// at `{derivationPath}{index}`.
    function deriveKey(
        string calldata mnemonic,
        string calldata derivationPath,
        uint32 index
    ) external pure returns (uint256 privateKey);

    /// Derive a private key from a provided mnenomic string (or mnenomic file path) in the specified language
    /// at the derivation path `m/44'/60'/0'/0/{index}`.
    function deriveKey(
        string calldata mnemonic,
        uint32 index,
        string calldata language
    ) external pure returns (uint256 privateKey);

    /// Derive a private key from a provided mnenomic string (or mnenomic file path) in the specified language
    /// at `{derivationPath}{index}`.
    function deriveKey(
        string calldata mnemonic,
        string calldata derivationPath,
        uint32 index,
        string calldata language
    ) external pure returns (uint256 privateKey);

    /// Derives secp256r1 public key from the provided `privateKey`.
    function publicKeyP256(
        uint256 privateKey
    ) external pure returns (uint256 publicKeyX, uint256 publicKeyY);

    /// Adds a private key to the local forge wallet and returns the address.
    function rememberKey(uint256 privateKey) external returns (address keyAddr);

    /// Derive a set number of wallets from a mnemonic at the derivation path `m/44'/60'/0'/0/{0..count}`.
    /// The respective private keys are saved to the local forge wallet for later use and their addresses are returned.
    function rememberKeys(
        string calldata mnemonic,
        string calldata derivationPath,
        uint32 count
    ) external returns (address[] memory keyAddrs);

    /// Derive a set number of wallets from a mnemonic in the specified language at the derivation path `m/44'/60'/0'/0/{0..count}`.
    /// The respective private keys are saved to the local forge wallet for later use and their addresses are returned.
    function rememberKeys(
        string calldata mnemonic,
        string calldata derivationPath,
        string calldata language,
        uint32 count
    ) external returns (address[] memory keyAddrs);

    /// Signs data with a `Wallet`.
    /// Returns a compact signature (`r`, `vs`) as per EIP-2098, where `vs` encodes both the
    /// signature's `s` value, and the recovery id `v` in a single bytes32.
    /// This format reduces the signature size from 65 to 64 bytes.
    function signCompact(
        Wallet calldata wallet,
        bytes32 digest
    ) external returns (bytes32 r, bytes32 vs);

    /// Signs `digest` with `privateKey` using the secp256k1 curve.
    /// Returns a compact signature (`r`, `vs`) as per EIP-2098, where `vs` encodes both the
    /// signature's `s` value, and the recovery id `v` in a single bytes32.
    /// This format reduces the signature size from 65 to 64 bytes.
    function signCompact(
        uint256 privateKey,
        bytes32 digest
    ) external pure returns (bytes32 r, bytes32 vs);

    /// Signs `digest` with signer provided to script using the secp256k1 curve.
    /// Returns a compact signature (`r`, `vs`) as per EIP-2098, where `vs` encodes both the
    /// signature's `s` value, and the recovery id `v` in a single bytes32.
    /// This format reduces the signature size from 65 to 64 bytes.
    /// If `--sender` is provided, the signer with provided address is used, otherwise,
    /// if exactly one signer is provided to the script, that signer is used.
    /// Raises error if signer passed through `--sender` does not match any unlocked signers or
    /// if `--sender` is not provided and not exactly one signer is passed to the script.
    function signCompact(
        bytes32 digest
    ) external pure returns (bytes32 r, bytes32 vs);

    /// Signs `digest` with signer provided to script using the secp256k1 curve.
    /// Returns a compact signature (`r`, `vs`) as per EIP-2098, where `vs` encodes both the
    /// signature's `s` value, and the recovery id `v` in a single bytes32.
    /// This format reduces the signature size from 65 to 64 bytes.
    /// Raises error if none of the signers passed into the script have provided address.
    function signCompact(
        address signer,
        bytes32 digest
    ) external pure returns (bytes32 r, bytes32 vs);

    /// Signs `digest` with `privateKey` using the secp256r1 curve.
    function signP256(
        uint256 privateKey,
        bytes32 digest
    ) external pure returns (bytes32 r, bytes32 s);

    /// Signs data with a `Wallet`.
    function sign(
        Wallet calldata wallet,
        bytes32 digest
    ) external returns (uint8 v, bytes32 r, bytes32 s);

    /// Signs `digest` with `privateKey` using the secp256k1 curve.
    function sign(
        uint256 privateKey,
        bytes32 digest
    ) external pure returns (uint8 v, bytes32 r, bytes32 s);

    /// Signs `digest` with signer provided to script using the secp256k1 curve.
    /// If `--sender` is provided, the signer with provided address is used, otherwise,
    /// if exactly one signer is provided to the script, that signer is used.
    /// Raises error if signer passed through `--sender` does not match any unlocked signers or
    /// if `--sender` is not provided and not exactly one signer is passed to the script.
    function sign(
        bytes32 digest
    ) external pure returns (uint8 v, bytes32 r, bytes32 s);

    /// Signs `digest` with signer provided to script using the secp256k1 curve.
    /// Raises error if none of the signers passed into the script have provided address.
    function sign(
        address signer,
        bytes32 digest
    ) external pure returns (uint8 v, bytes32 r, bytes32 s);

    // ======== Environment ========

    /// Gets the environment variable `name` and parses it as `address`.
    /// Reverts if the variable was not found or could not be parsed.
    function envAddress(
        string calldata name
    ) external view returns (address value);

    /// Gets the environment variable `name` and parses it as an array of `address`, delimited by `delim`.
    /// Reverts if the variable was not found or could not be parsed.
    function envAddress(
        string calldata name,
        string calldata delim
    ) external view returns (address[] memory value);

    /// Gets the environment variable `name` and parses it as `bool`.
    /// Reverts if the variable was not found or could not be parsed.
    function envBool(string calldata name) external view returns (bool value);

    /// Gets the environment variable `name` and parses it as an array of `bool`, delimited by `delim`.
    /// Reverts if the variable was not found or could not be parsed.
    function envBool(
        string calldata name,
        string calldata delim
    ) external view returns (bool[] memory value);

    /// Gets the environment variable `name` and parses it as `bytes32`.
    /// Reverts if the variable was not found or could not be parsed.
    function envBytes32(
        string calldata name
    ) external view returns (bytes32 value);

    /// Gets the environment variable `name` and parses it as an array of `bytes32`, delimited by `delim`.
    /// Reverts if the variable was not found or could not be parsed.
    function envBytes32(
        string calldata name,
        string calldata delim
    ) external view returns (bytes32[] memory value);

    /// Gets the environment variable `name` and parses it as `bytes`.
    /// Reverts if the variable was not found or could not be parsed.
    function envBytes(
        string calldata name
    ) external view returns (bytes memory value);

    /// Gets the environment variable `name` and parses it as an array of `bytes`, delimited by `delim`.
    /// Reverts if the variable was not found or could not be parsed.
    function envBytes(
        string calldata name,
        string calldata delim
    ) external view returns (bytes[] memory value);

    /// Gets the environment variable `name` and returns true if it exists, else returns false.
    function envExists(
        string calldata name
    ) external view returns (bool result);

    /// Gets the environment variable `name` and parses it as `int256`.
    /// Reverts if the variable was not found or could not be parsed.
    function envInt(string calldata name) external view returns (int256 value);

    /// Gets the environment variable `name` and parses it as an array of `int256`, delimited by `delim`.
    /// Reverts if the variable was not found or could not be parsed.
    function envInt(
        string calldata name,
        string calldata delim
    ) external view returns (int256[] memory value);

    /// Gets the environment variable `name` and parses it as `bool`.
    /// Reverts if the variable could not be parsed.
    /// Returns `defaultValue` if the variable was not found.
    function envOr(
        string calldata name,
        bool defaultValue
    ) external view returns (bool value);

    /// Gets the environment variable `name` and parses it as `uint256`.
    /// Reverts if the variable could not be parsed.
    /// Returns `defaultValue` if the variable was not found.
    function envOr(
        string calldata name,
        uint256 defaultValue
    ) external view returns (uint256 value);

    /// Gets the environment variable `name` and parses it as an array of `address`, delimited by `delim`.
    /// Reverts if the variable could not be parsed.
    /// Returns `defaultValue` if the variable was not found.
    function envOr(
        string calldata name,
        string calldata delim,
        address[] calldata defaultValue
    ) external view returns (address[] memory value);

    /// Gets the environment variable `name` and parses it as an array of `bytes32`, delimited by `delim`.
    /// Reverts if the variable could not be parsed.
    /// Returns `defaultValue` if the variable was not found.
    function envOr(
        string calldata name,
        string calldata delim,
        bytes32[] calldata defaultValue
    ) external view returns (bytes32[] memory value);

    /// Gets the environment variable `name` and parses it as an array of `string`, delimited by `delim`.
    /// Reverts if the variable could not be parsed.
    /// Returns `defaultValue` if the variable was not found.
    function envOr(
        string calldata name,
        string calldata delim,
        string[] calldata defaultValue
    ) external view returns (string[] memory value);

    /// Gets the environment variable `name` and parses it as an array of `bytes`, delimited by `delim`.
    /// Reverts if the variable could not be parsed.
    /// Returns `defaultValue` if the variable was not found.
    function envOr(
        string calldata name,
        string calldata delim,
        bytes[] calldata defaultValue
    ) external view returns (bytes[] memory value);

    /// Gets the environment variable `name` and parses it as `int256`.
    /// Reverts if the variable could not be parsed.
    /// Returns `defaultValue` if the variable was not found.
    function envOr(
        string calldata name,
        int256 defaultValue
    ) external view returns (int256 value);

    /// Gets the environment variable `name` and parses it as `address`.
    /// Reverts if the variable could not be parsed.
    /// Returns `defaultValue` if the variable was not found.
    function envOr(
        string calldata name,
        address defaultValue
    ) external view returns (address value);

    /// Gets the environment variable `name` and parses it as `bytes32`.
    /// Reverts if the variable could not be parsed.
    /// Returns `defaultValue` if the variable was not found.
    function envOr(
        string calldata name,
        bytes32 defaultValue
    ) external view returns (bytes32 value);

    /// Gets the environment variable `name` and parses it as `string`.
    /// Reverts if the variable could not be parsed.
    /// Returns `defaultValue` if the variable was not found.
    function envOr(
        string calldata name,
        string calldata defaultValue
    ) external view returns (string memory value);

    /// Gets the environment variable `name` and parses it as `bytes`.
    /// Reverts if the variable could not be parsed.
    /// Returns `defaultValue` if the variable was not found.
    function envOr(
        string calldata name,
        bytes calldata defaultValue
    ) external view returns (bytes memory value);

    /// Gets the environment variable `name` and parses it as an array of `bool`, delimited by `delim`.
    /// Reverts if the variable could not be parsed.
    /// Returns `defaultValue` if the variable was not found.
    function envOr(
        string calldata name,
        string calldata delim,
        bool[] calldata defaultValue
    ) external view returns (bool[] memory value);

    /// Gets the environment variable `name` and parses it as an array of `uint256`, delimited by `delim`.
    /// Reverts if the variable could not be parsed.
    /// Returns `defaultValue` if the variable was not found.
    function envOr(
        string calldata name,
        string calldata delim,
        uint256[] calldata defaultValue
    ) external view returns (uint256[] memory value);

    /// Gets the environment variable `name` and parses it as an array of `int256`, delimited by `delim`.
    /// Reverts if the variable could not be parsed.
    /// Returns `defaultValue` if the variable was not found.
    function envOr(
        string calldata name,
        string calldata delim,
        int256[] calldata defaultValue
    ) external view returns (int256[] memory value);

    /// Gets the environment variable `name` and parses it as `string`.
    /// Reverts if the variable was not found or could not be parsed.
    function envString(
        string calldata name
    ) external view returns (string memory value);

    /// Gets the environment variable `name` and parses it as an array of `string`, delimited by `delim`.
    /// Reverts if the variable was not found or could not be parsed.
    function envString(
        string calldata name,
        string calldata delim
    ) external view returns (string[] memory value);

    /// Gets the environment variable `name` and parses it as `uint256`.
    /// Reverts if the variable was not found or could not be parsed.
    function envUint(
        string calldata name
    ) external view returns (uint256 value);

    /// Gets the environment variable `name` and parses it as an array of `uint256`, delimited by `delim`.
    /// Reverts if the variable was not found or could not be parsed.
    function envUint(
        string calldata name,
        string calldata delim
    ) external view returns (uint256[] memory value);

    /// Returns true if `forge` command was executed in given context.
    function isContext(
        ForgeContext context
    ) external view returns (bool result);

    /// Sets environment variables.
    function setEnv(string calldata name, string calldata value) external;

    // ======== EVM ========

    /// Gets all accessed reads and write slot from a `vm.record` session, for a given address.
    function accesses(
        address target
    )
        external
        returns (bytes32[] memory readSlots, bytes32[] memory writeSlots);

    /// Gets the address for a given private key.
    function addr(uint256 privateKey) external pure returns (address keyAddr);

    /// Gets all the logs according to specified filter.
    function eth_getLogs(
        uint256 fromBlock,
        uint256 toBlock,
        address target,
        bytes32[] calldata topics
    ) external returns (EthGetLogs[] memory logs);

    /// Gets the current `block.blobbasefee`.
    /// You should use this instead of `block.blobbasefee` if you use `vm.blobBaseFee`, as `block.blobbasefee` is assumed to be constant across a transaction,
    /// and as a result will get optimized out by the compiler.
    /// See https://github.com/foundry-rs/foundry/issues/6180
    function getBlobBaseFee() external view returns (uint256 blobBaseFee);

    /// Gets the current `block.number`.
    /// You should use this instead of `block.number` if you use `vm.roll`, as `block.number` is assumed to be constant across a transaction,
    /// and as a result will get optimized out by the compiler.
    /// See https://github.com/foundry-rs/foundry/issues/6180
    function getBlockNumber() external view returns (uint256 height);

    /// Gets the current `block.timestamp`.
    /// You should use this instead of `block.timestamp` if you use `vm.warp`, as `block.timestamp` is assumed to be constant across a transaction,
    /// and as a result will get optimized out by the compiler.
    /// See https://github.com/foundry-rs/foundry/issues/6180
    function getBlockTimestamp() external view returns (uint256 timestamp);

    /// Gets the map key and parent of a mapping at a given slot, for a given address.
    function getMappingKeyAndParentOf(
        address target,
        bytes32 elementSlot
    ) external returns (bool found, bytes32 key, bytes32 parent);

    /// Gets the number of elements in the mapping at the given slot, for a given address.
    function getMappingLength(
        address target,
        bytes32 mappingSlot
    ) external returns (uint256 length);

    /// Gets the elements at index idx of the mapping at the given slot, for a given address. The
    /// index must be less than the length of the mapping (i.e. the number of keys in the mapping).
    function getMappingSlotAt(
        address target,
        bytes32 mappingSlot,
        uint256 idx
    ) external returns (bytes32 value);

    /// Gets the nonce of an account.
    function getNonce(address account) external view returns (uint64 nonce);

    /// Get the nonce of a `Wallet`.
    function getNonce(Wallet calldata wallet) external returns (uint64 nonce);

    /// Gets all the recorded logs.
    function getRecordedLogs() external returns (Log[] memory logs);

    /// Returns state diffs from current `vm.startStateDiffRecording` session.
    function getStateDiff() external view returns (string memory diff);

    /// Returns state diffs from current `vm.startStateDiffRecording` session, in json format.
    function getStateDiffJson() external view returns (string memory diff);

    /// Gets the gas used in the last call from the callee perspective.
    function lastCallGas() external view returns (Gas memory gas);

    /// Loads a storage slot from an address.
    function load(
        address target,
        bytes32 slot
    ) external view returns (bytes32 data);

    /// Pauses gas metering (i.e. gas usage is not counted). Noop if already paused.
    function pauseGasMetering() external;

    /// Records all storage reads and writes.
    function record() external;

    /// Record all the transaction logs.
    function recordLogs() external;

    /// Reset gas metering (i.e. gas usage is set to gas limit).
    function resetGasMetering() external;

    /// Resumes gas metering (i.e. gas usage is counted again). Noop if already on.
    function resumeGasMetering() external;

    /// Performs an Ethereum JSON-RPC request to the current fork URL.
    function rpc(
        string calldata method,
        string calldata params
    ) external returns (bytes memory data);

    /// Performs an Ethereum JSON-RPC request to the given endpoint.
    function rpc(
        string calldata urlOrAlias,
        string calldata method,
        string calldata params
    ) external returns (bytes memory data);

    /// Records the debug trace during the run.
    function startDebugTraceRecording() external;

    /// Starts recording all map SSTOREs for later retrieval.
    function startMappingRecording() external;

    /// Record all account accesses as part of CREATE, CALL or SELFDESTRUCT opcodes in order,
    /// along with the context of the calls
    function startStateDiffRecording() external;

    /// Stop debug trace recording and returns the recorded debug trace.
    function stopAndReturnDebugTraceRecording()
        external
        returns (DebugStep[] memory step);

    /// Returns an ordered array of all account accesses from a `vm.startStateDiffRecording` session.
    function stopAndReturnStateDiff()
        external
        returns (AccountAccess[] memory accountAccesses);

    /// Stops recording all map SSTOREs for later retrieval and clears the recorded data.
    function stopMappingRecording() external;

    // ======== Filesystem ========

    /// Closes file for reading, resetting the offset and allowing to read it from beginning with readLine.
    /// `path` is relative to the project root.
    function closeFile(string calldata path) external;

    /// Copies the contents of one file to another. This function will **overwrite** the contents of `to`.
    /// On success, the total number of bytes copied is returned and it is equal to the length of the `to` file as reported by `metadata`.
    /// Both `from` and `to` are relative to the project root.
    function copyFile(
        string calldata from,
        string calldata to
    ) external returns (uint64 copied);

    /// Creates a new, empty directory at the provided path.
    /// This cheatcode will revert in the following situations, but is not limited to just these cases:
    /// - User lacks permissions to modify `path`.
    /// - A parent of the given path doesn't exist and `recursive` is false.
    /// - `path` already exists and `recursive` is false.
    /// `path` is relative to the project root.
    function createDir(string calldata path, bool recursive) external;

    /// Deploys a contract from an artifact file. Takes in the relative path to the json file or the path to the
    /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
    function deployCode(
        string calldata artifactPath
    ) external returns (address deployedAddress);

    /// Deploys a contract from an artifact file. Takes in the relative path to the json file or the path to the
    /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
    /// Additionally accepts abi-encoded constructor arguments.
    function deployCode(
        string calldata artifactPath,
        bytes calldata constructorArgs
    ) external returns (address deployedAddress);

    /// Deploys a contract from an artifact file. Takes in the relative path to the json file or the path to the
    /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
    /// Additionally accepts `msg.value`.
    function deployCode(
        string calldata artifactPath,
        uint256 value
    ) external returns (address deployedAddress);

    /// Deploys a contract from an artifact file. Takes in the relative path to the json file or the path to the
    /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
    /// Additionally accepts abi-encoded constructor arguments and `msg.value`.
    function deployCode(
        string calldata artifactPath,
        bytes calldata constructorArgs,
        uint256 value
    ) external returns (address deployedAddress);

    /// Deploys a contract from an artifact file, using the CREATE2 salt. Takes in the relative path to the json file or the path to the
    /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
    function deployCode(
        string calldata artifactPath,
        bytes32 salt
    ) external returns (address deployedAddress);

    /// Deploys a contract from an artifact file, using the CREATE2 salt. Takes in the relative path to the json file or the path to the
    /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
    /// Additionally accepts abi-encoded constructor arguments.
    function deployCode(
        string calldata artifactPath,
        bytes calldata constructorArgs,
        bytes32 salt
    ) external returns (address deployedAddress);

    /// Deploys a contract from an artifact file, using the CREATE2 salt. Takes in the relative path to the json file or the path to the
    /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
    /// Additionally accepts `msg.value`.
    function deployCode(
        string calldata artifactPath,
        uint256 value,
        bytes32 salt
    ) external returns (address deployedAddress);

    /// Deploys a contract from an artifact file, using the CREATE2 salt. Takes in the relative path to the json file or the path to the
    /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
    /// Additionally accepts abi-encoded constructor arguments and `msg.value`.
    function deployCode(
        string calldata artifactPath,
        bytes calldata constructorArgs,
        uint256 value,
        bytes32 salt
    ) external returns (address deployedAddress);

    /// Returns true if the given path points to an existing entity, else returns false.
    function exists(string calldata path) external view returns (bool result);

    /// Performs a foreign function call via the terminal.
    function ffi(
        string[] calldata commandInput
    ) external returns (bytes memory result);

    /// Given a path, query the file system to get information about a file, directory, etc.
    function fsMetadata(
        string calldata path
    ) external view returns (FsMetadata memory metadata);

    /// Gets the artifact path from code (aka. creation code).
    function getArtifactPathByCode(
        bytes calldata code
    ) external view returns (string memory path);

    /// Gets the artifact path from deployed code (aka. runtime code).
    function getArtifactPathByDeployedCode(
        bytes calldata deployedCode
    ) external view returns (string memory path);

    /// Returns the most recent broadcast for the given contract on `chainId` matching `txType`.
    /// For example:
    /// The most recent deployment can be fetched by passing `txType` as `CREATE` or `CREATE2`.
    /// The most recent call can be fetched by passing `txType` as `CALL`.
    function getBroadcast(
        string calldata contractName,
        uint64 chainId,
        BroadcastTxType txType
    ) external view returns (BroadcastTxSummary memory);

    /// Returns all broadcasts for the given contract on `chainId` with the specified `txType`.
    /// Sorted such that the most recent broadcast is the first element, and the oldest is the last. i.e descending order of BroadcastTxSummary.blockNumber.
    function getBroadcasts(
        string calldata contractName,
        uint64 chainId,
        BroadcastTxType txType
    ) external view returns (BroadcastTxSummary[] memory);

    /// Returns all broadcasts for the given contract on `chainId`.
    /// Sorted such that the most recent broadcast is the first element, and the oldest is the last. i.e descending order of BroadcastTxSummary.blockNumber.
    function getBroadcasts(
        string calldata contractName,
        uint64 chainId
    ) external view returns (BroadcastTxSummary[] memory);

    /// Gets the creation bytecode from an artifact file. Takes in the relative path to the json file or the path to the
    /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
    function getCode(
        string calldata artifactPath
    ) external view returns (bytes memory creationBytecode);

    /// Gets the deployed bytecode from an artifact file. Takes in the relative path to the json file or the path to the
    /// artifact in the form of <path>:<contract>:<version> where <contract> and <version> parts are optional.
    function getDeployedCode(
        string calldata artifactPath
    ) external view returns (bytes memory runtimeBytecode);

    /// Returns the most recent deployment for the current `chainId`.
    function getDeployment(
        string calldata contractName
    ) external view returns (address deployedAddress);

    /// Returns the most recent deployment for the given contract on `chainId`
    function getDeployment(
        string calldata contractName,
        uint64 chainId
    ) external view returns (address deployedAddress);

    /// Returns all deployments for the given contract on `chainId`
    /// Sorted in descending order of deployment time i.e descending order of BroadcastTxSummary.blockNumber.
    /// The most recent deployment is the first element, and the oldest is the last.
    function getDeployments(
        string calldata contractName,
        uint64 chainId
    ) external view returns (address[] memory deployedAddresses);

    /// Returns true if the path exists on disk and is pointing at a directory, else returns false.
    function isDir(string calldata path) external view returns (bool result);

    /// Returns true if the path exists on disk and is pointing at a regular file, else returns false.
    function isFile(string calldata path) external view returns (bool result);

    /// Get the path of the current project root.
    function projectRoot() external view returns (string memory path);

    /// Prompts the user for a string value in the terminal.
    function prompt(
        string calldata promptText
    ) external returns (string memory input);

    /// Prompts the user for an address in the terminal.
    function promptAddress(
        string calldata promptText
    ) external returns (address);

    /// Prompts the user for a hidden string value in the terminal.
    function promptSecret(
        string calldata promptText
    ) external returns (string memory input);

    /// Prompts the user for hidden uint256 in the terminal (usually pk).
    function promptSecretUint(
        string calldata promptText
    ) external returns (uint256);

    /// Prompts the user for uint256 in the terminal.
    function promptUint(string calldata promptText) external returns (uint256);

    /// Reads the directory at the given path recursively, up to `maxDepth`.
    /// `maxDepth` defaults to 1, meaning only the direct children of the given directory will be returned.
    /// Follows symbolic links if `followLinks` is true.
    function readDir(
        string calldata path
    ) external view returns (DirEntry[] memory entries);

    /// See `readDir(string)`.
    function readDir(
        string calldata path,
        uint64 maxDepth
    ) external view returns (DirEntry[] memory entries);

    /// See `readDir(string)`.
    function readDir(
        string calldata path,
        uint64 maxDepth,
        bool followLinks
    ) external view returns (DirEntry[] memory entries);

    /// Reads the entire content of file to string. `path` is relative to the project root.
    function readFile(
        string calldata path
    ) external view returns (string memory data);

    /// Reads the entire content of file as binary. `path` is relative to the project root.
    function readFileBinary(
        string calldata path
    ) external view returns (bytes memory data);

    /// Reads next line of file to string.
    function readLine(
        string calldata path
    ) external view returns (string memory line);

    /// Reads a symbolic link, returning the path that the link points to.
    /// This cheatcode will revert in the following situations, but is not limited to just these cases:
    /// - `path` is not a symbolic link.
    /// - `path` does not exist.
    function readLink(
        string calldata linkPath
    ) external view returns (string memory targetPath);

    /// Removes a directory at the provided path.
    /// This cheatcode will revert in the following situations, but is not limited to just these cases:
    /// - `path` doesn't exist.
    /// - `path` isn't a directory.
    /// - User lacks permissions to modify `path`.
    /// - The directory is not empty and `recursive` is false.
    /// `path` is relative to the project root.
    function removeDir(string calldata path, bool recursive) external;

    /// Removes a file from the filesystem.
    /// This cheatcode will revert in the following situations, but is not limited to just these cases:
    /// - `path` points to a directory.
    /// - The file doesn't exist.
    /// - The user lacks permissions to remove the file.
    /// `path` is relative to the project root.
    function removeFile(string calldata path) external;

    /// Performs a foreign function call via terminal and returns the exit code, stdout, and stderr.
    function tryFfi(
        string[] calldata commandInput
    ) external returns (FfiResult memory result);

    /// Returns the time since unix epoch in milliseconds.
    function unixTime() external view returns (uint256 milliseconds);

    /// Writes data to file, creating a file if it does not exist, and entirely replacing its contents if it does.
    /// `path` is relative to the project root.
    function writeFile(string calldata path, string calldata data) external;

    /// Writes binary data to a file, creating a file if it does not exist, and entirely replacing its contents if it does.
    /// `path` is relative to the project root.
    function writeFileBinary(
        string calldata path,
        bytes calldata data
    ) external;

    /// Writes line to file, creating a file if it does not exist.
    /// `path` is relative to the project root.
    function writeLine(string calldata path, string calldata data) external;

    // ======== JSON ========

    /// Checks if `key` exists in a JSON object.
    function keyExistsJson(
        string calldata json,
        string calldata key
    ) external view returns (bool);

    /// Parses a string of JSON data at `key` and coerces it to `address`.
    function parseJsonAddress(
        string calldata json,
        string calldata key
    ) external pure returns (address);

    /// Parses a string of JSON data at `key` and coerces it to `address[]`.
    function parseJsonAddressArray(
        string calldata json,
        string calldata key
    ) external pure returns (address[] memory);

    /// Parses a string of JSON data at `key` and coerces it to `bool`.
    function parseJsonBool(
        string calldata json,
        string calldata key
    ) external pure returns (bool);

    /// Parses a string of JSON data at `key` and coerces it to `bool[]`.
    function parseJsonBoolArray(
        string calldata json,
        string calldata key
    ) external pure returns (bool[] memory);

    /// Parses a string of JSON data at `key` and coerces it to `bytes`.
    function parseJsonBytes(
        string calldata json,
        string calldata key
    ) external pure returns (bytes memory);

    /// Parses a string of JSON data at `key` and coerces it to `bytes32`.
    function parseJsonBytes32(
        string calldata json,
        string calldata key
    ) external pure returns (bytes32);

    /// Parses a string of JSON data at `key` and coerces it to `bytes32[]`.
    function parseJsonBytes32Array(
        string calldata json,
        string calldata key
    ) external pure returns (bytes32[] memory);

    /// Parses a string of JSON data at `key` and coerces it to `bytes[]`.
    function parseJsonBytesArray(
        string calldata json,
        string calldata key
    ) external pure returns (bytes[] memory);

    /// Parses a string of JSON data at `key` and coerces it to `int256`.
    function parseJsonInt(
        string calldata json,
        string calldata key
    ) external pure returns (int256);

    /// Parses a string of JSON data at `key` and coerces it to `int256[]`.
    function parseJsonIntArray(
        string calldata json,
        string calldata key
    ) external pure returns (int256[] memory);

    /// Returns an array of all the keys in a JSON object.
    function parseJsonKeys(
        string calldata json,
        string calldata key
    ) external pure returns (string[] memory keys);

    /// Parses a string of JSON data at `key` and coerces it to `string`.
    function parseJsonString(
        string calldata json,
        string calldata key
    ) external pure returns (string memory);

    /// Parses a string of JSON data at `key` and coerces it to `string[]`.
    function parseJsonStringArray(
        string calldata json,
        string calldata key
    ) external pure returns (string[] memory);

    /// Parses a string of JSON data at `key` and coerces it to type array corresponding to `typeDescription`.
    function parseJsonTypeArray(
        string calldata json,
        string calldata key,
        string calldata typeDescription
    ) external pure returns (bytes memory);

    /// Parses a string of JSON data and coerces it to type corresponding to `typeDescription`.
    function parseJsonType(
        string calldata json,
        string calldata typeDescription
    ) external pure returns (bytes memory);

    /// Parses a string of JSON data at `key` and coerces it to type corresponding to `typeDescription`.
    function parseJsonType(
        string calldata json,
        string calldata key,
        string calldata typeDescription
    ) external pure returns (bytes memory);

    /// Parses a string of JSON data at `key` and coerces it to `uint256`.
    function parseJsonUint(
        string calldata json,
        string calldata key
    ) external pure returns (uint256);

    /// Parses a string of JSON data at `key` and coerces it to `uint256[]`.
    function parseJsonUintArray(
        string calldata json,
        string calldata key
    ) external pure returns (uint256[] memory);

    /// ABI-encodes a JSON object.
    function parseJson(
        string calldata json
    ) external pure returns (bytes memory abiEncodedData);

    /// ABI-encodes a JSON object at `key`.
    function parseJson(
        string calldata json,
        string calldata key
    ) external pure returns (bytes memory abiEncodedData);

    /// See `serializeJson`.
    function serializeAddress(
        string calldata objectKey,
        string calldata valueKey,
        address value
    ) external returns (string memory json);

    /// See `serializeJson`.
    function serializeAddress(
        string calldata objectKey,
        string calldata valueKey,
        address[] calldata values
    ) external returns (string memory json);

    /// See `serializeJson`.
    function serializeBool(
        string calldata objectKey,
        string calldata valueKey,
        bool value
    ) external returns (string memory json);

    /// See `serializeJson`.
    function serializeBool(
        string calldata objectKey,
        string calldata valueKey,
        bool[] calldata values
    ) external returns (string memory json);

    /// See `serializeJson`.
    function serializeBytes32(
        string calldata objectKey,
        string calldata valueKey,
        bytes32 value
    ) external returns (string memory json);

    /// See `serializeJson`.
    function serializeBytes32(
        string calldata objectKey,
        string calldata valueKey,
        bytes32[] calldata values
    ) external returns (string memory json);

    /// See `serializeJson`.
    function serializeBytes(
        string calldata objectKey,
        string calldata valueKey,
        bytes calldata value
    ) external returns (string memory json);

    /// See `serializeJson`.
    function serializeBytes(
        string calldata objectKey,
        string calldata valueKey,
        bytes[] calldata values
    ) external returns (string memory json);

    /// See `serializeJson`.
    function serializeInt(
        string calldata objectKey,
        string calldata valueKey,
        int256 value
    ) external returns (string memory json);

    /// See `serializeJson`.
    function serializeInt(
        string calldata objectKey,
        string calldata valueKey,
        int256[] calldata values
    ) external returns (string memory json);

    /// Serializes a key and value to a JSON object stored in-memory that can be later written to a file.
    /// Returns the stringified version of the specific JSON file up to that moment.
    function serializeJson(
        string calldata objectKey,
        string calldata value
    ) external returns (string memory json);

    /// See `serializeJson`.
    function serializeJsonType(
        string calldata typeDescription,
        bytes calldata value
    ) external pure returns (string memory json);

    /// See `serializeJson`.
    function serializeJsonType(
        string calldata objectKey,
        string calldata valueKey,
        string calldata typeDescription,
        bytes calldata value
    ) external returns (string memory json);

    /// See `serializeJson`.
    function serializeString(
        string calldata objectKey,
        string calldata valueKey,
        string calldata value
    ) external returns (string memory json);

    /// See `serializeJson`.
    function serializeString(
        string calldata objectKey,
        string calldata valueKey,
        string[] calldata values
    ) external returns (string memory json);

    /// See `serializeJson`.
    function serializeUintToHex(
        string calldata objectKey,
        string calldata valueKey,
        uint256 value
    ) external returns (string memory json);

    /// See `serializeJson`.
    function serializeUint(
        string calldata objectKey,
        string calldata valueKey,
        uint256 value
    ) external returns (string memory json);

    /// See `serializeJson`.
    function serializeUint(
        string calldata objectKey,
        string calldata valueKey,
        uint256[] calldata values
    ) external returns (string memory json);

    /// Write a serialized JSON object to a file. If the file exists, it will be overwritten.
    function writeJson(string calldata json, string calldata path) external;

    /// Write a serialized JSON object to an **existing** JSON file, replacing a value with key = <value_key.>
    /// This is useful to replace a specific value of a JSON file, without having to parse the entire thing.
    function writeJson(
        string calldata json,
        string calldata path,
        string calldata valueKey
    ) external;

    /// Checks if `key` exists in a JSON object
    /// `keyExists` is being deprecated in favor of `keyExistsJson`. It will be removed in future versions.
    function keyExists(
        string calldata json,
        string calldata key
    ) external view returns (bool);

    // ======== Scripting ========

    /// Designate the next call as an EIP-7702 transaction
    function attachDelegation(
        SignedDelegation calldata signedDelegation
    ) external;

    /// Takes a signed transaction and broadcasts it to the network.
    function broadcastRawTransaction(bytes calldata data) external;

    /// Has the next call (at this call depth only) create transactions that can later be signed and sent onchain.
    /// Broadcasting address is determined by checking the following in order:
    /// 1. If `--sender` argument was provided, that address is used.
    /// 2. If exactly one signer (e.g. private key, hw wallet, keystore) is set when `forge broadcast` is invoked, that signer is used.
    /// 3. Otherwise, default foundry sender (1804c8AB1F12E6bbf3894d4083f33e07309d1f38) is used.
    function broadcast() external;

    /// Has the next call (at this call depth only) create a transaction with the address provided
    /// as the sender that can later be signed and sent onchain.
    function broadcast(address signer) external;

    /// Has the next call (at this call depth only) create a transaction with the private key
    /// provided as the sender that can later be signed and sent onchain.
    function broadcast(uint256 privateKey) external;

    /// Returns addresses of available unlocked wallets in the script environment.
    function getWallets() external returns (address[] memory wallets);

    /// Sign an EIP-7702 authorization and designate the next call as an EIP-7702 transaction
    function signAndAttachDelegation(
        address implementation,
        uint256 privateKey
    ) external returns (SignedDelegation memory signedDelegation);

    /// Sign an EIP-7702 authorization and designate the next call as an EIP-7702 transaction for specific nonce
    function signAndAttachDelegation(
        address implementation,
        uint256 privateKey,
        uint64 nonce
    ) external returns (SignedDelegation memory signedDelegation);

    /// Sign an EIP-7702 authorization for delegation
    function signDelegation(
        address implementation,
        uint256 privateKey
    ) external returns (SignedDelegation memory signedDelegation);

    /// Sign an EIP-7702 authorization for delegation for specific nonce
    function signDelegation(
        address implementation,
        uint256 privateKey,
        uint64 nonce
    ) external returns (SignedDelegation memory signedDelegation);

    /// Has all subsequent calls (at this call depth only) create transactions that can later be signed and sent onchain.
    /// Broadcasting address is determined by checking the following in order:
    /// 1. If `--sender` argument was provided, that address is used.
    /// 2. If exactly one signer (e.g. private key, hw wallet, keystore) is set when `forge broadcast` is invoked, that signer is used.
    /// 3. Otherwise, default foundry sender (1804c8AB1F12E6bbf3894d4083f33e07309d1f38) is used.
    function startBroadcast() external;

    /// Has all subsequent calls (at this call depth only) create transactions with the address
    /// provided that can later be signed and sent onchain.
    function startBroadcast(address signer) external;

    /// Has all subsequent calls (at this call depth only) create transactions with the private key
    /// provided that can later be signed and sent onchain.
    function startBroadcast(uint256 privateKey) external;

    /// Stops collecting onchain transactions.
    function stopBroadcast() external;

    // ======== String ========

    /// Returns true if `search` is found in `subject`, false otherwise.
    function contains(
        string calldata subject,
        string calldata search
    ) external returns (bool result);

    /// Returns the index of the first occurrence of a `key` in an `input` string.
    /// Returns `NOT_FOUND` (i.e. `type(uint256).max`) if the `key` is not found.
    /// Returns 0 in case of an empty `key`.
    function indexOf(
        string calldata input,
        string calldata key
    ) external pure returns (uint256);

    /// Parses the given `string` into an `address`.
    function parseAddress(
        string calldata stringifiedValue
    ) external pure returns (address parsedValue);

    /// Parses the given `string` into a `bool`.
    function parseBool(
        string calldata stringifiedValue
    ) external pure returns (bool parsedValue);

    /// Parses the given `string` into `bytes`.
    function parseBytes(
        string calldata stringifiedValue
    ) external pure returns (bytes memory parsedValue);

    /// Parses the given `string` into a `bytes32`.
    function parseBytes32(
        string calldata stringifiedValue
    ) external pure returns (bytes32 parsedValue);

    /// Parses the given `string` into a `int256`.
    function parseInt(
        string calldata stringifiedValue
    ) external pure returns (int256 parsedValue);

    /// Parses the given `string` into a `uint256`.
    function parseUint(
        string calldata stringifiedValue
    ) external pure returns (uint256 parsedValue);

    /// Replaces occurrences of `from` in the given `string` with `to`.
    function replace(
        string calldata input,
        string calldata from,
        string calldata to
    ) external pure returns (string memory output);

    /// Splits the given `string` into an array of strings divided by the `delimiter`.
    function split(
        string calldata input,
        string calldata delimiter
    ) external pure returns (string[] memory outputs);

    /// Converts the given `string` value to Lowercase.
    function toLowercase(
        string calldata input
    ) external pure returns (string memory output);

    /// Converts the given value to a `string`.
    function toString(
        address value
    ) external pure returns (string memory stringifiedValue);

    /// Converts the given value to a `string`.
    function toString(
        bytes calldata value
    ) external pure returns (string memory stringifiedValue);

    /// Converts the given value to a `string`.
    function toString(
        bytes32 value
    ) external pure returns (string memory stringifiedValue);

    /// Converts the given value to a `string`.
    function toString(
        bool value
    ) external pure returns (string memory stringifiedValue);

    /// Converts the given value to a `string`.
    function toString(
        uint256 value
    ) external pure returns (string memory stringifiedValue);

    /// Converts the given value to a `string`.
    function toString(
        int256 value
    ) external pure returns (string memory stringifiedValue);

    /// Converts the given `string` value to Uppercase.
    function toUppercase(
        string calldata input
    ) external pure returns (string memory output);

    /// Trims leading and trailing whitespace from the given `string` value.
    function trim(
        string calldata input
    ) external pure returns (string memory output);

    // ======== Testing ========

    /// Compares two `uint256` values. Expects difference to be less than or equal to `maxDelta`.
    /// Formats values with decimals in failure message.
    function assertApproxEqAbsDecimal(
        uint256 left,
        uint256 right,
        uint256 maxDelta,
        uint256 decimals
    ) external pure;

    /// Compares two `uint256` values. Expects difference to be less than or equal to `maxDelta`.
    /// Formats values with decimals in failure message. Includes error message into revert string on failure.
    function assertApproxEqAbsDecimal(
        uint256 left,
        uint256 right,
        uint256 maxDelta,
        uint256 decimals,
        string calldata error
    ) external pure;

    /// Compares two `int256` values. Expects difference to be less than or equal to `maxDelta`.
    /// Formats values with decimals in failure message.
    function assertApproxEqAbsDecimal(
        int256 left,
        int256 right,
        uint256 maxDelta,
        uint256 decimals
    ) external pure;

    /// Compares two `int256` values. Expects difference to be less than or equal to `maxDelta`.
    /// Formats values with decimals in failure message. Includes error message into revert string on failure.
    function assertApproxEqAbsDecimal(
        int256 left,
        int256 right,
        uint256 maxDelta,
        uint256 decimals,
        string calldata error
    ) external pure;

    /// Compares two `uint256` values. Expects difference to be less than or equal to `maxDelta`.
    function assertApproxEqAbs(
        uint256 left,
        uint256 right,
        uint256 maxDelta
    ) external pure;

    /// Compares two `uint256` values. Expects difference to be less than or equal to `maxDelta`.
    /// Includes error message into revert string on failure.
    function assertApproxEqAbs(
        uint256 left,
        uint256 right,
        uint256 maxDelta,
        string calldata error
    ) external pure;

    /// Compares two `int256` values. Expects difference to be less than or equal to `maxDelta`.
    function assertApproxEqAbs(
        int256 left,
        int256 right,
        uint256 maxDelta
    ) external pure;

    /// Compares two `int256` values. Expects difference to be less than or equal to `maxDelta`.
    /// Includes error message into revert string on failure.
    function assertApproxEqAbs(
        int256 left,
        int256 right,
        uint256 maxDelta,
        string calldata error
    ) external pure;

    /// Compares two `uint256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
    /// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
    /// Formats values with decimals in failure message.
    function assertApproxEqRelDecimal(
        uint256 left,
        uint256 right,
        uint256 maxPercentDelta,
        uint256 decimals
    ) external pure;

    /// Compares two `uint256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
    /// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
    /// Formats values with decimals in failure message. Includes error message into revert string on failure.
    function assertApproxEqRelDecimal(
        uint256 left,
        uint256 right,
        uint256 maxPercentDelta,
        uint256 decimals,
        string calldata error
    ) external pure;

    /// Compares two `int256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
    /// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
    /// Formats values with decimals in failure message.
    function assertApproxEqRelDecimal(
        int256 left,
        int256 right,
        uint256 maxPercentDelta,
        uint256 decimals
    ) external pure;

    /// Compares two `int256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
    /// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
    /// Formats values with decimals in failure message. Includes error message into revert string on failure.
    function assertApproxEqRelDecimal(
        int256 left,
        int256 right,
        uint256 maxPercentDelta,
        uint256 decimals,
        string calldata error
    ) external pure;

    /// Compares two `uint256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
    /// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
    function assertApproxEqRel(
        uint256 left,
        uint256 right,
        uint256 maxPercentDelta
    ) external pure;

    /// Compares two `uint256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
    /// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
    /// Includes error message into revert string on failure.
    function assertApproxEqRel(
        uint256 left,
        uint256 right,
        uint256 maxPercentDelta,
        string calldata error
    ) external pure;

    /// Compares two `int256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
    /// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
    function assertApproxEqRel(
        int256 left,
        int256 right,
        uint256 maxPercentDelta
    ) external pure;

    /// Compares two `int256` values. Expects relative difference in percents to be less than or equal to `maxPercentDelta`.
    /// `maxPercentDelta` is an 18 decimal fixed point number, where 1e18 == 100%
    /// Includes error message into revert string on failure.
    function assertApproxEqRel(
        int256 left,
        int256 right,
        uint256 maxPercentDelta,
        string calldata error
    ) external pure;

    /// Asserts that two `uint256` values are equal, formatting them with decimals in failure message.
    function assertEqDecimal(
        uint256 left,
        uint256 right,
        uint256 decimals
    ) external pure;

    /// Asserts that two `uint256` values are equal, formatting them with decimals in failure message.
    /// Includes error message into revert string on failure.
    function assertEqDecimal(
        uint256 left,
        uint256 right,
        uint256 decimals,
        string calldata error
    ) external pure;

    /// Asserts that two `int256` values are equal, formatting them with decimals in failure message.
    function assertEqDecimal(
        int256 left,
        int256 right,
        uint256 decimals
    ) external pure;

    /// Asserts that two `int256` values are equal, formatting them with decimals in failure message.
    /// Includes error message into revert string on failure.
    function assertEqDecimal(
        int256 left,
        int256 right,
        uint256 decimals,
        string calldata error
    ) external pure;

    /// Asserts that two `bool` values are equal.
    function assertEq(bool left, bool right) external pure;

    /// Asserts that two `bool` values are equal and includes error message into revert string on failure.
    function assertEq(
        bool left,
        bool right,
        string calldata error
    ) external pure;

    /// Asserts that two `string` values are equal.
    function assertEq(
        string calldata left,
        string calldata right
    ) external pure;

    /// Asserts that two `string` values are equal and includes error message into revert string on failure.
    function assertEq(
        string calldata left,
        string calldata right,
        string calldata error
    ) external pure;

    /// Asserts that two `bytes` values are equal.
    function assertEq(bytes calldata left, bytes calldata right) external pure;

    /// Asserts that two `bytes` values are equal and includes error message into revert string on failure.
    function assertEq(
        bytes calldata left,
        bytes calldata right,
        string calldata error
    ) external pure;

    /// Asserts that two arrays of `bool` values are equal.
    function assertEq(
        bool[] calldata left,
        bool[] calldata right
    ) external pure;

    /// Asserts that two arrays of `bool` values are equal and includes error message into revert string on failure.
    function assertEq(
        bool[] calldata left,
        bool[] calldata right,
        string calldata error
    ) external pure;

    /// Asserts that two arrays of `uint256 values are equal.
    function assertEq(
        uint256[] calldata left,
        uint256[] calldata right
    ) external pure;

    /// Asserts that two arrays of `uint256` values are equal and includes error message into revert string on failure.
    function assertEq(
        uint256[] calldata left,
        uint256[] calldata right,
        string calldata error
    ) external pure;

    /// Asserts that two arrays of `int256` values are equal.
    function assertEq(
        int256[] calldata left,
        int256[] calldata right
    ) external pure;

    /// Asserts that two arrays of `int256` values are equal and includes error message into revert string on failure.
    function assertEq(
        int256[] calldata left,
        int256[] calldata right,
        string calldata error
    ) external pure;

    /// Asserts that two `uint256` values are equal.
    function assertEq(uint256 left, uint256 right) external pure;

    /// Asserts that two arrays of `address` values are equal.
    function assertEq(
        address[] calldata left,
        address[] calldata right
    ) external pure;

    /// Asserts that two arrays of `address` values are equal and includes error message into revert string on failure.
    function assertEq(
        address[] calldata left,
        address[] calldata right,
        string calldata error
    ) external pure;

    /// Asserts that two arrays of `bytes32` values are equal.
    function assertEq(
        bytes32[] calldata left,
        bytes32[] calldata right
    ) external pure;

    /// Asserts that two arrays of `bytes32` values are equal and includes error message into revert string on failure.
    function assertEq(
        bytes32[] calldata left,
        bytes32[] calldata right,
        string calldata error
    ) external pure;

    /// Asserts that two arrays of `string` values are equal.
    function assertEq(
        string[] calldata left,
        string[] calldata right
    ) external pure;

    /// Asserts that two arrays of `string` values are equal and includes error message into revert string on failure.
    function assertEq(
        string[] calldata left,
        string[] calldata right,
        string calldata error
    ) external pure;

    /// Asserts that two arrays of `bytes` values are equal.
    function assertEq(
        bytes[] calldata left,
        bytes[] calldata right
    ) external pure;

    /// Asserts that two arrays of `bytes` values are equal and includes error message into revert string on failure.
    function assertEq(
        bytes[] calldata left,
        bytes[] calldata right,
        string calldata error
    ) external pure;

    /// Asserts that two `uint256` values are equal and includes error message into revert string on failure.
    function assertEq(
        uint256 left,
        uint256 right,
        string calldata error
    ) external pure;

    /// Asserts that two `int256` values are equal.
    function assertEq(int256 left, int256 right) external pure;

    /// Asserts that two `int256` values are equal and includes error message into revert string on failure.
    function assertEq(
        int256 left,
        int256 right,
        string calldata error
    ) external pure;

    /// Asserts that two `address` values are equal.
    function assertEq(address left, address right) external pure;

    /// Asserts that two `address` values are equal and includes error message into revert string on failure.
    function assertEq(
        address left,
        address right,
        string calldata error
    ) external pure;

    /// Asserts that two `bytes32` values are equal.
    function assertEq(bytes32 left, bytes32 right) external pure;

    /// Asserts that two `bytes32` values are equal and includes error message into revert string on failure.
    function assertEq(
        bytes32 left,
        bytes32 right,
        string calldata error
    ) external pure;

    /// Asserts that the given condition is false.
    function assertFalse(bool condition) external pure;

    /// Asserts that the given condition is false and includes error message into revert string on failure.
    function assertFalse(bool condition, string calldata error) external pure;

    /// Compares two `uint256` values. Expects first value to be greater than or equal to second.
    /// Formats values with decimals in failure message.
    function assertGeDecimal(
        uint256 left,
        uint256 right,
        uint256 decimals
    ) external pure;

    /// Compares two `uint256` values. Expects first value to be greater than or equal to second.
    /// Formats values with decimals in failure message. Includes error message into revert string on failure.
    function assertGeDecimal(
        uint256 left,
        uint256 right,
        uint256 decimals,
        string calldata error
    ) external pure;

    /// Compares two `int256` values. Expects first value to be greater than or equal to second.
    /// Formats values with decimals in failure message.
    function assertGeDecimal(
        int256 left,
        int256 right,
        uint256 decimals
    ) external pure;

    /// Compares two `int256` values. Expects first value to be greater than or equal to second.
    /// Formats values with decimals in failure message. Includes error message into revert string on failure.
    function assertGeDecimal(
        int256 left,
        int256 right,
        uint256 decimals,
        string calldata error
    ) external pure;

    /// Compares two `uint256` values. Expects first value to be greater than or equal to second.
    function assertGe(uint256 left, uint256 right) external pure;

    /// Compares two `uint256` values. Expects first value to be greater than or equal to second.
    /// Includes error message into revert string on failure.
    function assertGe(
        uint256 left,
        uint256 right,
        string calldata error
    ) external pure;

    /// Compares two `int256` values. Expects first value to be greater than or equal to second.
    function assertGe(int256 left, int256 right) external pure;

    /// Compares two `int256` values. Expects first value to be greater than or equal to second.
    /// Includes error message into revert string on failure.
    function assertGe(
        int256 left,
        int256 right,
        string calldata error
    ) external pure;

    /// Compares two `uint256` values. Expects first value to be greater than second.
    /// Formats values with decimals in failure message.
    function assertGtDecimal(
        uint256 left,
        uint256 right,
        uint256 decimals
    ) external pure;

    /// Compares two `uint256` values. Expects first value to be greater than second.
    /// Formats values with decimals in failure message. Includes error message into revert string on failure.
    function assertGtDecimal(
        uint256 left,
        uint256 right,
        uint256 decimals,
        string calldata error
    ) external pure;

    /// Compares two `int256` values. Expects first value to be greater than second.
    /// Formats values with decimals in failure message.
    function assertGtDecimal(
        int256 left,
        int256 right,
        uint256 decimals
    ) external pure;

    /// Compares two `int256` values. Expects first value to be greater than second.
    /// Formats values with decimals in failure message. Includes error message into revert string on failure.
    function assertGtDecimal(
        int256 left,
        int256 right,
        uint256 decimals,
        string calldata error
    ) external pure;

    /// Compares two `uint256` values. Expects first value to be greater than second.
    function assertGt(uint256 left, uint256 right) external pure;

    /// Compares two `uint256` values. Expects first value to be greater than second.
    /// Includes error message into revert string on failure.
    function assertGt(
        uint256 left,
        uint256 right,
        string calldata error
    ) external pure;

    /// Compares two `int256` values. Expects first value to be greater than second.
    function assertGt(int256 left, int256 right) external pure;

    /// Compares two `int256` values. Expects first value to be greater than second.
    /// Includes error message into revert string on failure.
    function assertGt(
        int256 left,
        int256 right,
        string calldata error
    ) external pure;

    /// Compares two `uint256` values. Expects first value to be less than or equal to second.
    /// Formats values with decimals in failure message.
    function assertLeDecimal(
        uint256 left,
        uint256 right,
        uint256 decimals
    ) external pure;

    /// Compares two `uint256` values. Expects first value to be less than or equal to second.
    /// Formats values with decimals in failure message. Includes error message into revert string on failure.
    function assertLeDecimal(
        uint256 left,
        uint256 right,
        uint256 decimals,
        string calldata error
    ) external pure;

    /// Compares two `int256` values. Expects first value to be less than or equal to second.
    /// Formats values with decimals in failure message.
    function assertLeDecimal(
        int256 left,
        int256 right,
        uint256 decimals
    ) external pure;

    /// Compares two `int256` values. Expects first value to be less than or equal to second.
    /// Formats values with decimals in failure message. Includes error message into revert string on failure.
    function assertLeDecimal(
        int256 left,
        int256 right,
        uint256 decimals,
        string calldata error
    ) external pure;

    /// Compares two `uint256` values. Expects first value to be less than or equal to second.
    function assertLe(uint256 left, uint256 right) external pure;

    /// Compares two `uint256` values. Expects first value to be less than or equal to second.
    /// Includes error message into revert string on failure.
    function assertLe(
        uint256 left,
        uint256 right,
        string calldata error
    ) external pure;

    /// Compares two `int256` values. Expects first value to be less than or equal to second.
    function assertLe(int256 left, int256 right) external pure;

    /// Compares two `int256` values. Expects first value to be less than or equal to second.
    /// Includes error message into revert string on failure.
    function assertLe(
        int256 left,
        int256 right,
        string calldata error
    ) external pure;

    /// Compares two `uint256` values. Expects first value to be less than second.
    /// Formats values with decimals in failure message.
    function assertLtDecimal(
        uint256 left,
        uint256 right,
        uint256 decimals
    ) external pure;

    /// Compares two `uint256` values. Expects first value to be less than second.
    /// Formats values with decimals in failure message. Includes error message into revert string on failure.
    function assertLtDecimal(
        uint256 left,
        uint256 right,
        uint256 decimals,
        string calldata error
    ) external pure;

    /// Compares two `int256` values. Expects first value to be less than second.
    /// Formats values with decimals in failure message.
    function assertLtDecimal(
        int256 left,
        int256 right,
        uint256 decimals
    ) external pure;

    /// Compares two `int256` values. Expects first value to be less than second.
    /// Formats values with decimals in failure message. Includes error message into revert string on failure.
    function assertLtDecimal(
        int256 left,
        int256 right,
        uint256 decimals,
        string calldata error
    ) external pure;

    /// Compares two `uint256` values. Expects first value to be less than second.
    function assertLt(uint256 left, uint256 right) external pure;

    /// Compares two `uint256` values. Expects first value to be less than second.
    /// Includes error message into revert string on failure.
    function assertLt(
        uint256 left,
        uint256 right,
        string calldata error
    ) external pure;

    /// Compares two `int256` values. Expects first value to be less than second.
    function assertLt(int256 left, int256 right) external pure;

    /// Compares two `int256` values. Expects first value to be less than second.
    /// Includes error message into revert string on failure.
    function assertLt(
        int256 left,
        int256 right,
        string calldata error
    ) external pure;

    /// Asserts that two `uint256` values are not equal, formatting them with decimals in failure message.
    function assertNotEqDecimal(
        uint256 left,
        uint256 right,
        uint256 decimals
    ) external pure;

    /// Asserts that two `uint256` values are not equal, formatting them with decimals in failure message.
    /// Includes error message into revert string on failure.
    function assertNotEqDecimal(
        uint256 left,
        uint256 right,
        uint256 decimals,
        string calldata error
    ) external pure;

    /// Asserts that two `int256` values are not equal, formatting them with decimals in failure message.
    function assertNotEqDecimal(
        int256 left,
        int256 right,
        uint256 decimals
    ) external pure;

    /// Asserts that two `int256` values are not equal, formatting them with decimals in failure message.
    /// Includes error message into revert string on failure.
    function assertNotEqDecimal(
        int256 left,
        int256 right,
        uint256 decimals,
        string calldata error
    ) external pure;

    /// Asserts that two `bool` values are not equal.
    function assertNotEq(bool left, bool right) external pure;

    /// Asserts that two `bool` values are not equal and includes error message into revert string on failure.
    function assertNotEq(
        bool left,
        bool right,
        string calldata error
    ) external pure;

    /// Asserts that two `string` values are not equal.
    function assertNotEq(
        string calldata left,
        string calldata right
    ) external pure;

    /// Asserts that two `string` values are not equal and includes error message into revert string on failure.
    function assertNotEq(
        string calldata left,
        string calldata right,
        string calldata error
    ) external pure;

    /// Asserts that two `bytes` values are not equal.
    function assertNotEq(
        bytes calldata left,
        bytes calldata right
    ) external pure;

    /// Asserts that two `bytes` values are not equal and includes error message into revert string on failure.
    function assertNotEq(
        bytes calldata left,
        bytes calldata right,
        string calldata error
    ) external pure;

    /// Asserts that two arrays of `bool` values are not equal.
    function assertNotEq(
        bool[] calldata left,
        bool[] calldata right
    ) external pure;

    /// Asserts that two arrays of `bool` values are not equal and includes error message into revert string on failure.
    function assertNotEq(
        bool[] calldata left,
        bool[] calldata right,
        string calldata error
    ) external pure;

    /// Asserts that two arrays of `uint256` values are not equal.
    function assertNotEq(
        uint256[] calldata left,
        uint256[] calldata right
    ) external pure;

    /// Asserts that two arrays of `uint256` values are not equal and includes error message into revert string on failure.
    function assertNotEq(
        uint256[] calldata left,
        uint256[] calldata right,
        string calldata error
    ) external pure;

    /// Asserts that two arrays of `int256` values are not equal.
    function assertNotEq(
        int256[] calldata left,
        int256[] calldata right
    ) external pure;

    /// Asserts that two arrays of `int256` values are not equal and includes error message into revert string on failure.
    function assertNotEq(
        int256[] calldata left,
        int256[] calldata right,
        string calldata error
    ) external pure;

    /// Asserts that two `uint256` values are not equal.
    function assertNotEq(uint256 left, uint256 right) external pure;

    /// Asserts that two arrays of `address` values are not equal.
    function assertNotEq(
        address[] calldata left,
        address[] calldata right
    ) external pure;

    /// Asserts that two arrays of `address` values are not equal and includes error message into revert string on failure.
    function assertNotEq(
        address[] calldata left,
        address[] calldata right,
        string calldata error
    ) external pure;

    /// Asserts that two arrays of `bytes32` values are not equal.
    function assertNotEq(
        bytes32[] calldata left,
        bytes32[] calldata right
    ) external pure;

    /// Asserts that two arrays of `bytes32` values are not equal and includes error message into revert string on failure.
    function assertNotEq(
        bytes32[] calldata left,
        bytes32[] calldata right,
        string calldata error
    ) external pure;

    /// Asserts that two arrays of `string` values are not equal.
    function assertNotEq(
        string[] calldata left,
        string[] calldata right
    ) external pure;

    /// Asserts that two arrays of `string` values are not equal and includes error message into revert string on failure.
    function assertNotEq(
        string[] calldata left,
        string[] calldata right,
        string calldata error
    ) external pure;

    /// Asserts that two arrays of `bytes` values are not equal.
    function assertNotEq(
        bytes[] calldata left,
        bytes[] calldata right
    ) external pure;

    /// Asserts that two arrays of `bytes` values are not equal and includes error message into revert string on failure.
    function assertNotEq(
        bytes[] calldata left,
        bytes[] calldata right,
        string calldata error
    ) external pure;

    /// Asserts that two `uint256` values are not equal and includes error message into revert string on failure.
    function assertNotEq(
        uint256 left,
        uint256 right,
        string calldata error
    ) external pure;

    /// Asserts that two `int256` values are not equal.
    function assertNotEq(int256 left, int256 right) external pure;

    /// Asserts that two `int256` values are not equal and includes error message into revert string on failure.
    function assertNotEq(
        int256 left,
        int256 right,
        string calldata error
    ) external pure;

    /// Asserts that two `address` values are not equal.
    function assertNotEq(address left, address right) external pure;

    /// Asserts that two `address` values are not equal and includes error message into revert string on failure.
    function assertNotEq(
        address left,
        address right,
        string calldata error
    ) external pure;

    /// Asserts that two `bytes32` values are not equal.
    function assertNotEq(bytes32 left, bytes32 right) external pure;

    /// Asserts that two `bytes32` values are not equal and includes error message into revert string on failure.
    function assertNotEq(
        bytes32 left,
        bytes32 right,
        string calldata error
    ) external pure;

    /// Asserts that the given condition is true.
    function assertTrue(bool condition) external pure;

    /// Asserts that the given condition is true and includes error message into revert string on failure.
    function assertTrue(bool condition, string calldata error) external pure;

    /// If the condition is false, discard this run's fuzz inputs and generate new ones.
    function assume(bool condition) external pure;

    /// Discard this run's fuzz inputs and generate new ones if next call reverted.
    function assumeNoRevert() external pure;

    /// Discard this run's fuzz inputs and generate new ones if next call reverts with the potential revert parameters.
    function assumeNoRevert(
        PotentialRevert calldata potentialRevert
    ) external pure;

    /// Discard this run's fuzz inputs and generate new ones if next call reverts with the any of the potential revert parameters.
    function assumeNoRevert(
        PotentialRevert[] calldata potentialReverts
    ) external pure;

    /// Writes a breakpoint to jump to in the debugger.
    function breakpoint(string calldata char) external pure;

    /// Writes a conditional breakpoint to jump to in the debugger.
    function breakpoint(string calldata char, bool value) external pure;

    /// Returns true if the current Foundry version is greater than or equal to the given version.
    /// The given version string must be in the format `major.minor.patch`.
    /// This is equivalent to `foundryVersionCmp(version) >= 0`.
    function foundryVersionAtLeast(
        string calldata version
    ) external view returns (bool);

    /// Compares the current Foundry version with the given version string.
    /// The given version string must be in the format `major.minor.patch`.
    /// Returns:
    /// -1 if current Foundry version is less than the given version
    /// 0 if current Foundry version equals the given version
    /// 1 if current Foundry version is greater than the given version
    /// This result can then be used with a comparison operator against `0`.
    /// For example, to check if the current Foundry version is greater than or equal to `1.0.0`:
    /// `if (foundryVersionCmp("1.0.0") >= 0) { ... }`
    function foundryVersionCmp(
        string calldata version
    ) external view returns (int256);

    /// Returns the Foundry version.
    /// Format: <cargo_version>-<tag>+<git_sha_short>.<unix_build_timestamp>.<profile>
    /// Sample output: 0.3.0-nightly+3cb96bde9b.1737036656.debug
    /// Note: Build timestamps may vary slightly across platforms due to separate CI jobs.
    /// For reliable version comparisons, use UNIX format (e.g., >= 1700000000)
    /// to compare timestamps while ignoring minor time differences.
    function getFoundryVersion() external view returns (string memory version);

    /// Returns the RPC url for the given alias.
    function rpcUrl(
        string calldata rpcAlias
    ) external view returns (string memory json);

    /// Returns all rpc urls and their aliases as structs.
    function rpcUrlStructs() external view returns (Rpc[] memory urls);

    /// Returns all rpc urls and their aliases `[alias, url][]`.
    function rpcUrls() external view returns (string[2][] memory urls);

    /// Suspends execution of the main thread for `duration` milliseconds.
    function sleep(uint256 duration) external;

    // ======== Toml ========

    /// Checks if `key` exists in a TOML table.
    function keyExistsToml(
        string calldata toml,
        string calldata key
    ) external view returns (bool);

    /// Parses a string of TOML data at `key` and coerces it to `address`.
    function parseTomlAddress(
        string calldata toml,
        string calldata key
    ) external pure returns (address);

    /// Parses a string of TOML data at `key` and coerces it to `address[]`.
    function parseTomlAddressArray(
        string calldata toml,
        string calldata key
    ) external pure returns (address[] memory);

    /// Parses a string of TOML data at `key` and coerces it to `bool`.
    function parseTomlBool(
        string calldata toml,
        string calldata key
    ) external pure returns (bool);

    /// Parses a string of TOML data at `key` and coerces it to `bool[]`.
    function parseTomlBoolArray(
        string calldata toml,
        string calldata key
    ) external pure returns (bool[] memory);

    /// Parses a string of TOML data at `key` and coerces it to `bytes`.
    function parseTomlBytes(
        string calldata toml,
        string calldata key
    ) external pure returns (bytes memory);

    /// Parses a string of TOML data at `key` and coerces it to `bytes32`.
    function parseTomlBytes32(
        string calldata toml,
        string calldata key
    ) external pure returns (bytes32);

    /// Parses a string of TOML data at `key` and coerces it to `bytes32[]`.
    function parseTomlBytes32Array(
        string calldata toml,
        string calldata key
    ) external pure returns (bytes32[] memory);

    /// Parses a string of TOML data at `key` and coerces it to `bytes[]`.
    function parseTomlBytesArray(
        string calldata toml,
        string calldata key
    ) external pure returns (bytes[] memory);

    /// Parses a string of TOML data at `key` and coerces it to `int256`.
    function parseTomlInt(
        string calldata toml,
        string calldata key
    ) external pure returns (int256);

    /// Parses a string of TOML data at `key` and coerces it to `int256[]`.
    function parseTomlIntArray(
        string calldata toml,
        string calldata key
    ) external pure returns (int256[] memory);

    /// Returns an array of all the keys in a TOML table.
    function parseTomlKeys(
        string calldata toml,
        string calldata key
    ) external pure returns (string[] memory keys);

    /// Parses a string of TOML data at `key` and coerces it to `string`.
    function parseTomlString(
        string calldata toml,
        string calldata key
    ) external pure returns (string memory);

    /// Parses a string of TOML data at `key` and coerces it to `string[]`.
    function parseTomlStringArray(
        string calldata toml,
        string calldata key
    ) external pure returns (string[] memory);

    /// Parses a string of TOML data at `key` and coerces it to type array corresponding to `typeDescription`.
    function parseTomlTypeArray(
        string calldata toml,
        string calldata key,
        string calldata typeDescription
    ) external pure returns (bytes memory);

    /// Parses a string of TOML data and coerces it to type corresponding to `typeDescription`.
    function parseTomlType(
        string calldata toml,
        string calldata typeDescription
    ) external pure returns (bytes memory);

    /// Parses a string of TOML data at `key` and coerces it to type corresponding to `typeDescription`.
    function parseTomlType(
        string calldata toml,
        string calldata key,
        string calldata typeDescription
    ) external pure returns (bytes memory);

    /// Parses a string of TOML data at `key` and coerces it to `uint256`.
    function parseTomlUint(
        string calldata toml,
        string calldata key
    ) external pure returns (uint256);

    /// Parses a string of TOML data at `key` and coerces it to `uint256[]`.
    function parseTomlUintArray(
        string calldata toml,
        string calldata key
    ) external pure returns (uint256[] memory);

    /// ABI-encodes a TOML table.
    function parseToml(
        string calldata toml
    ) external pure returns (bytes memory abiEncodedData);

    /// ABI-encodes a TOML table at `key`.
    function parseToml(
        string calldata toml,
        string calldata key
    ) external pure returns (bytes memory abiEncodedData);

    /// Takes serialized JSON, converts to TOML and write a serialized TOML to a file.
    function writeToml(string calldata json, string calldata path) external;

    /// Takes serialized JSON, converts to TOML and write a serialized TOML table to an **existing** TOML file, replacing a value with key = <value_key.>
    /// This is useful to replace a specific value of a TOML file, without having to parse the entire thing.
    function writeToml(
        string calldata json,
        string calldata path,
        string calldata valueKey
    ) external;

    // ======== Utilities ========

    /// Compute the address of a contract created with CREATE2 using the given CREATE2 deployer.
    function computeCreate2Address(
        bytes32 salt,
        bytes32 initCodeHash,
        address deployer
    ) external pure returns (address);

    /// Compute the address of a contract created with CREATE2 using the default CREATE2 deployer.
    function computeCreate2Address(
        bytes32 salt,
        bytes32 initCodeHash
    ) external pure returns (address);

    /// Compute the address a contract will be deployed at for a given deployer address and nonce.
    function computeCreateAddress(
        address deployer,
        uint256 nonce
    ) external pure returns (address);

    /// Utility cheatcode to copy storage of `from` contract to another `to` contract.
    function copyStorage(address from, address to) external;

    /// Returns ENS namehash for provided string.
    function ensNamehash(string calldata name) external pure returns (bytes32);

    /// Gets the label for the specified address.
    function getLabel(
        address account
    ) external view returns (string memory currentLabel);

    /// Labels an address in call traces.
    function label(address account, string calldata newLabel) external;

    /// Pauses collection of call traces. Useful in cases when you want to skip tracing of
    /// complex calls which are not useful for debugging.
    function pauseTracing() external view;

    /// Returns a random `address`.
    function randomAddress() external returns (address);

    /// Returns a random `bool`.
    function randomBool() external view returns (bool);

    /// Returns a random byte array value of the given length.
    function randomBytes(uint256 len) external view returns (bytes memory);

    /// Returns a random fixed-size byte array of length 4.
    function randomBytes4() external view returns (bytes4);

    /// Returns a random fixed-size byte array of length 8.
    function randomBytes8() external view returns (bytes8);

    /// Returns a random `int256` value.
    function randomInt() external view returns (int256);

    /// Returns a random `int256` value of given bits.
    function randomInt(uint256 bits) external view returns (int256);

    /// Returns a random uint256 value.
    function randomUint() external returns (uint256);

    /// Returns random uint256 value between the provided range (=min..=max).
    function randomUint(uint256 min, uint256 max) external returns (uint256);

    /// Returns a random `uint256` value of given bits.
    function randomUint(uint256 bits) external view returns (uint256);

    /// Unpauses collection of call traces.
    function resumeTracing() external view;

    /// Utility cheatcode to set arbitrary storage for given target address.
    function setArbitraryStorage(address target) external;

    /// Utility cheatcode to set arbitrary storage for given target address and overwrite
    /// any storage slots that have been previously set.
    function setArbitraryStorage(address target, bool overwrite) external;

    /// Randomly shuffles an array.
    function shuffle(
        uint256[] calldata array
    ) external returns (uint256[] memory);

    /// Sorts an array in ascending order.
    function sort(uint256[] calldata array) external returns (uint256[] memory);

    /// Encodes a `bytes` value to a base64url string.
    function toBase64URL(
        bytes calldata data
    ) external pure returns (string memory);

    /// Encodes a `string` value to a base64url string.
    function toBase64URL(
        string calldata data
    ) external pure returns (string memory);

    /// Encodes a `bytes` value to a base64 string.
    function toBase64(
        bytes calldata data
    ) external pure returns (string memory);

    /// Encodes a `string` value to a base64 string.
    function toBase64(
        string calldata data
    ) external pure returns (string memory);
}

/// The `Vm` interface does allow manipulation of the EVM state. These are all intended to be used
/// in tests, but it is not recommended to use these cheats in scripts.
interface Vm is VmSafe {
    // ======== EVM ========

    /// Utility cheatcode to set an EIP-2930 access list for all subsequent transactions.
    function accessList(AccessListItem[] calldata access) external;

    /// Returns the identifier of the currently active fork. Reverts if no fork is currently active.
    function activeFork() external view returns (uint256 forkId);

    /// In forking mode, explicitly grant the given address cheatcode access.
    function allowCheatcodes(address account) external;

    /// Sets `block.blobbasefee`
    function blobBaseFee(uint256 newBlobBaseFee) external;

    /// Sets the blobhashes in the transaction.
    /// Not available on EVM versions before Cancun.
    /// If used on unsupported EVM versions it will revert.
    function blobhashes(bytes32[] calldata hashes) external;

    /// Sets `block.chainid`.
    function chainId(uint256 newChainId) external;

    /// Clears all mocked calls.
    function clearMockedCalls() external;

    /// Clones a source account code, state, balance and nonce to a target account and updates in-memory EVM state.
    function cloneAccount(address source, address target) external;

    /// Sets `block.coinbase`.
    function coinbase(address newCoinbase) external;

    /// Marks the slots of an account and the account address as cold.
    function cool(address target) external;

    /// Utility cheatcode to mark specific storage slot as cold, simulating no prior read.
    function coolSlot(address target, bytes32 slot) external;

    /// Creates a new fork with the given endpoint and the _latest_ block and returns the identifier of the fork.
    function createFork(
        string calldata urlOrAlias
    ) external returns (uint256 forkId);

    /// Creates a new fork with the given endpoint and block and returns the identifier of the fork.
    function createFork(
        string calldata urlOrAlias,
        uint256 blockNumber
    ) external returns (uint256 forkId);

    /// Creates a new fork with the given endpoint and at the block the given transaction was mined in,
    /// replays all transaction mined in the block before the transaction, and returns the identifier of the fork.
    function createFork(
        string calldata urlOrAlias,
        bytes32 txHash
    ) external returns (uint256 forkId);

    /// Creates and also selects a new fork with the given endpoint and the latest block and returns the identifier of the fork.
    function createSelectFork(
        string calldata urlOrAlias
    ) external returns (uint256 forkId);

    /// Creates and also selects a new fork with the given endpoint and block and returns the identifier of the fork.
    function createSelectFork(
        string calldata urlOrAlias,
        uint256 blockNumber
    ) external returns (uint256 forkId);

    /// Creates and also selects new fork with the given endpoint and at the block the given transaction was mined in,
    /// replays all transaction mined in the block before the transaction, returns the identifier of the fork.
    function createSelectFork(
        string calldata urlOrAlias,
        bytes32 txHash
    ) external returns (uint256 forkId);

    /// Sets an address' balance.
    function deal(address account, uint256 newBalance) external;

    /// Removes the snapshot with the given ID created by `snapshot`.
    /// Takes the snapshot ID to delete.
    /// Returns `true` if the snapshot was successfully deleted.
    /// Returns `false` if the snapshot does not exist.
    function deleteStateSnapshot(
        uint256 snapshotId
    ) external returns (bool success);

    /// Removes _all_ snapshots previously created by `snapshot`.
    function deleteStateSnapshots() external;

    /// Sets `block.difficulty`.
    /// Not available on EVM versions from Paris onwards. Use `prevrandao` instead.
    /// Reverts if used on unsupported EVM versions.
    function difficulty(uint256 newDifficulty) external;

    /// Dump a genesis JSON file's `allocs` to disk.
    function dumpState(string calldata pathToStateJson) external;

    /// Sets an address' code.
    function etch(address target, bytes calldata newRuntimeBytecode) external;

    /// Sets `block.basefee`.
    function fee(uint256 newBasefee) external;

    /// Gets the blockhashes from the current transaction.
    /// Not available on EVM versions before Cancun.
    /// If used on unsupported EVM versions it will revert.
    function getBlobhashes() external view returns (bytes32[] memory hashes);

    /// Returns true if the account is marked as persistent.
    function isPersistent(
        address account
    ) external view returns (bool persistent);

    /// Load a genesis JSON file's `allocs` into the in-memory EVM state.
    function loadAllocs(string calldata pathToAllocsJson) external;

    /// Marks that the account(s) should use persistent storage across fork swaps in a multifork setup
    /// Meaning, changes made to the state of this account will be kept when switching forks.
    function makePersistent(address account) external;

    /// See `makePersistent(address)`.
    function makePersistent(address account0, address account1) external;

    /// See `makePersistent(address)`.
    function makePersistent(
        address account0,
        address account1,
        address account2
    ) external;

    /// See `makePersistent(address)`.
    function makePersistent(address[] calldata accounts) external;

    /// Reverts a call to an address with specified revert data.
    function mockCallRevert(
        address callee,
        bytes calldata data,
        bytes calldata revertData
    ) external;

    /// Reverts a call to an address with a specific `msg.value`, with specified revert data.
    function mockCallRevert(
        address callee,
        uint256 msgValue,
        bytes calldata data,
        bytes calldata revertData
    ) external;

    /// Reverts a call to an address with specified revert data.
    /// Overload to pass the function selector directly `token.approve.selector` instead of `abi.encodeWithSelector(token.approve.selector)`.
    function mockCallRevert(
        address callee,
        bytes4 data,
        bytes calldata revertData
    ) external;

    /// Reverts a call to an address with a specific `msg.value`, with specified revert data.
    /// Overload to pass the function selector directly `token.approve.selector` instead of `abi.encodeWithSelector(token.approve.selector)`.
    function mockCallRevert(
        address callee,
        uint256 msgValue,
        bytes4 data,
        bytes calldata revertData
    ) external;

    /// Mocks a call to an address, returning specified data.
    /// Calldata can either be strict or a partial match, e.g. if you only
    /// pass a Solidity selector to the expected calldata, then the entire Solidity
    /// function will be mocked.
    function mockCall(
        address callee,
        bytes calldata data,
        bytes calldata returnData
    ) external;

    /// Mocks a call to an address with a specific `msg.value`, returning specified data.
    /// Calldata match takes precedence over `msg.value` in case of ambiguity.
    function mockCall(
        address callee,
        uint256 msgValue,
        bytes calldata data,
        bytes calldata returnData
    ) external;

    /// Mocks a call to an address, returning specified data.
    /// Calldata can either be strict or a partial match, e.g. if you only
    /// pass a Solidity selector to the expected calldata, then the entire Solidity
    /// function will be mocked.
    /// Overload to pass the function selector directly `token.approve.selector` instead of `abi.encodeWithSelector(token.approve.selector)`.
    function mockCall(
        address callee,
        bytes4 data,
        bytes calldata returnData
    ) external;

    /// Mocks a call to an address with a specific `msg.value`, returning specified data.
    /// Calldata match takes precedence over `msg.value` in case of ambiguity.
    /// Overload to pass the function selector directly `token.approve.selector` instead of `abi.encodeWithSelector(token.approve.selector)`.
    function mockCall(
        address callee,
        uint256 msgValue,
        bytes4 data,
        bytes calldata returnData
    ) external;

    /// Mocks multiple calls to an address, returning specified data for each call.
    function mockCalls(
        address callee,
        bytes calldata data,
        bytes[] calldata returnData
    ) external;

    /// Mocks multiple calls to an address with a specific `msg.value`, returning specified data for each call.
    function mockCalls(
        address callee,
        uint256 msgValue,
        bytes calldata data,
        bytes[] calldata returnData
    ) external;

    /// Whenever a call is made to `callee` with calldata `data`, this cheatcode instead calls
    /// `target` with the same calldata. This functionality is similar to a delegate call made to
    /// `target` contract from `callee`.
    /// Can be used to substitute a call to a function with another implementation that captures
    /// the primary logic of the original function but is easier to reason about.
    /// If calldata is not a strict match then partial match by selector is attempted.
    function mockFunction(
        address callee,
        address target,
        bytes calldata data
    ) external;

    /// Utility cheatcode to remove any EIP-2930 access list set by `accessList` cheatcode.
    function noAccessList() external;

    /// Sets the *next* call's `msg.sender` to be the input address.
    function prank(address msgSender) external;

    /// Sets the *next* call's `msg.sender` to be the input address, and the `tx.origin` to be the second input.
    function prank(address msgSender, address txOrigin) external;

    /// Sets the *next* delegate call's `msg.sender` to be the input address.
    function prank(address msgSender, bool delegateCall) external;

    /// Sets the *next* delegate call's `msg.sender` to be the input address, and the `tx.origin` to be the second input.
    function prank(
        address msgSender,
        address txOrigin,
        bool delegateCall
    ) external;

    /// Sets `block.prevrandao`.
    /// Not available on EVM versions before Paris. Use `difficulty` instead.
    /// If used on unsupported EVM versions it will revert.
    function prevrandao(bytes32 newPrevrandao) external;

    /// Sets `block.prevrandao`.
    /// Not available on EVM versions before Paris. Use `difficulty` instead.
    /// If used on unsupported EVM versions it will revert.
    function prevrandao(uint256 newPrevrandao) external;

    /// Reads the current `msg.sender` and `tx.origin` from state and reports if there is any active caller modification.
    function readCallers()
        external
        returns (CallerMode callerMode, address msgSender, address txOrigin);

    /// Resets the nonce of an account to 0 for EOAs and 1 for contract accounts.
    function resetNonce(address account) external;

    /// Revert the state of the EVM to a previous snapshot
    /// Takes the snapshot ID to revert to.
    /// Returns `true` if the snapshot was successfully reverted.
    /// Returns `false` if the snapshot does not exist.
    /// **Note:** This does not automatically delete the snapshot. To delete the snapshot use `deleteStateSnapshot`.
    function revertToState(uint256 snapshotId) external returns (bool success);

    /// Revert the state of the EVM to a previous snapshot and automatically deletes the snapshots
    /// Takes the snapshot ID to revert to.
    /// Returns `true` if the snapshot was successfully reverted and deleted.
    /// Returns `false` if the snapshot does not exist.
    function revertToStateAndDelete(
        uint256 snapshotId
    ) external returns (bool success);

    /// Revokes persistent status from the address, previously added via `makePersistent`.
    function revokePersistent(address account) external;

    /// See `revokePersistent(address)`.
    function revokePersistent(address[] calldata accounts) external;

    /// Sets `block.height`.
    function roll(uint256 newHeight) external;

    /// Updates the currently active fork to given block number
    /// This is similar to `roll` but for the currently active fork.
    function rollFork(uint256 blockNumber) external;

    /// Updates the currently active fork to given transaction. This will `rollFork` with the number
    /// of the block the transaction was mined in and replays all transaction mined before it in the block.
    function rollFork(bytes32 txHash) external;

    /// Updates the given fork to given block number.
    function rollFork(uint256 forkId, uint256 blockNumber) external;

    /// Updates the given fork to block number of the given transaction and replays all transaction mined before it in the block.
    function rollFork(uint256 forkId, bytes32 txHash) external;

    /// Takes a fork identifier created by `createFork` and sets the corresponding forked state as active.
    function selectFork(uint256 forkId) external;

    /// Set blockhash for the current block.
    /// It only sets the blockhash for blocks where `block.number - 256 <= number < block.number`.
    function setBlockhash(uint256 blockNumber, bytes32 blockHash) external;

    /// Sets the nonce of an account. Must be higher than the current nonce of the account.
    function setNonce(address account, uint64 newNonce) external;

    /// Sets the nonce of an account to an arbitrary value.
    function setNonceUnsafe(address account, uint64 newNonce) external;

    /// Snapshot capture the gas usage of the last call by name from the callee perspective.
    function snapshotGasLastCall(
        string calldata name
    ) external returns (uint256 gasUsed);

    /// Snapshot capture the gas usage of the last call by name in a group from the callee perspective.
    function snapshotGasLastCall(
        string calldata group,
        string calldata name
    ) external returns (uint256 gasUsed);

    /// Snapshot the current state of the evm.
    /// Returns the ID of the snapshot that was created.
    /// To revert a snapshot use `revertToState`.
    function snapshotState() external returns (uint256 snapshotId);

    /// Snapshot capture an arbitrary numerical value by name.
    /// The group name is derived from the contract name.
    function snapshotValue(string calldata name, uint256 value) external;

    /// Snapshot capture an arbitrary numerical value by name in a group.
    function snapshotValue(
        string calldata group,
        string calldata name,
        uint256 value
    ) external;

    /// Sets all subsequent calls' `msg.sender` to be the input address until `stopPrank` is called.
    function startPrank(address msgSender) external;

    /// Sets all subsequent calls' `msg.sender` to be the input address until `stopPrank` is called, and the `tx.origin` to be the second input.
    function startPrank(address msgSender, address txOrigin) external;

    /// Sets all subsequent delegate calls' `msg.sender` to be the input address until `stopPrank` is called.
    function startPrank(address msgSender, bool delegateCall) external;

    /// Sets all subsequent delegate calls' `msg.sender` to be the input address until `stopPrank` is called, and the `tx.origin` to be the second input.
    function startPrank(
        address msgSender,
        address txOrigin,
        bool delegateCall
    ) external;

    /// Start a snapshot capture of the current gas usage by name.
    /// The group name is derived from the contract name.
    function startSnapshotGas(string calldata name) external;

    /// Start a snapshot capture of the current gas usage by name in a group.
    function startSnapshotGas(
        string calldata group,
        string calldata name
    ) external;

    /// Resets subsequent calls' `msg.sender` to be `address(this)`.
    function stopPrank() external;

    /// Stop the snapshot capture of the current gas by latest snapshot name, capturing the gas used since the start.
    function stopSnapshotGas() external returns (uint256 gasUsed);

    /// Stop the snapshot capture of the current gas usage by name, capturing the gas used since the start.
    /// The group name is derived from the contract name.
    function stopSnapshotGas(
        string calldata name
    ) external returns (uint256 gasUsed);

    /// Stop the snapshot capture of the current gas usage by name in a group, capturing the gas used since the start.
    function stopSnapshotGas(
        string calldata group,
        string calldata name
    ) external returns (uint256 gasUsed);

    /// Stores a value to an address' storage slot.
    function store(address target, bytes32 slot, bytes32 value) external;

    /// Fetches the given transaction from the active fork and executes it on the current state.
    function transact(bytes32 txHash) external;

    /// Fetches the given transaction from the given fork and executes it on the current state.
    function transact(uint256 forkId, bytes32 txHash) external;

    /// Sets `tx.gasprice`.
    function txGasPrice(uint256 newGasPrice) external;

    /// Utility cheatcode to mark specific storage slot as warm, simulating a prior read.
    function warmSlot(address target, bytes32 slot) external;

    /// Sets `block.timestamp`.
    function warp(uint256 newTimestamp) external;

    /// `deleteSnapshot` is being deprecated in favor of `deleteStateSnapshot`. It will be removed in future versions.
    function deleteSnapshot(uint256 snapshotId) external returns (bool success);

    /// `deleteSnapshots` is being deprecated in favor of `deleteStateSnapshots`. It will be removed in future versions.
    function deleteSnapshots() external;

    /// `revertToAndDelete` is being deprecated in favor of `revertToStateAndDelete`. It will be removed in future versions.
    function revertToAndDelete(
        uint256 snapshotId
    ) external returns (bool success);

    /// `revertTo` is being deprecated in favor of `revertToState`. It will be removed in future versions.
    function revertTo(uint256 snapshotId) external returns (bool success);

    /// `snapshot` is being deprecated in favor of `snapshotState`. It will be removed in future versions.
    function snapshot() external returns (uint256 snapshotId);

    // ======== Testing ========

    /// Expect a call to an address with the specified `msg.value` and calldata, and a *minimum* amount of gas.
    function expectCallMinGas(
        address callee,
        uint256 msgValue,
        uint64 minGas,
        bytes calldata data
    ) external;

    /// Expect given number of calls to an address with the specified `msg.value` and calldata, and a *minimum* amount of gas.
    function expectCallMinGas(
        address callee,
        uint256 msgValue,
        uint64 minGas,
        bytes calldata data,
        uint64 count
    ) external;

    /// Expects a call to an address with the specified calldata.
    /// Calldata can either be a strict or a partial match.
    function expectCall(address callee, bytes calldata data) external;

    /// Expects given number of calls to an address with the specified calldata.
    function expectCall(
        address callee,
        bytes calldata data,
        uint64 count
    ) external;

    /// Expects a call to an address with the specified `msg.value` and calldata.
    function expectCall(
        address callee,
        uint256 msgValue,
        bytes calldata data
    ) external;

    /// Expects given number of calls to an address with the specified `msg.value` and calldata.
    function expectCall(
        address callee,
        uint256 msgValue,
        bytes calldata data,
        uint64 count
    ) external;

    /// Expect a call to an address with the specified `msg.value`, gas, and calldata.
    function expectCall(
        address callee,
        uint256 msgValue,
        uint64 gas,
        bytes calldata data
    ) external;

    /// Expects given number of calls to an address with the specified `msg.value`, gas, and calldata.
    function expectCall(
        address callee,
        uint256 msgValue,
        uint64 gas,
        bytes calldata data,
        uint64 count
    ) external;

    /// Expects the deployment of the specified bytecode by the specified address using the CREATE opcode
    function expectCreate(bytes calldata bytecode, address deployer) external;

    /// Expects the deployment of the specified bytecode by the specified address using the CREATE2 opcode
    function expectCreate2(bytes calldata bytecode, address deployer) external;

    /// Prepare an expected anonymous log with (bool checkTopic1, bool checkTopic2, bool checkTopic3, bool checkData.).
    /// Call this function, then emit an anonymous event, then call a function. Internally after the call, we check if
    /// logs were emitted in the expected order with the expected topics and data (as specified by the booleans).
    function expectEmitAnonymous(
        bool checkTopic0,
        bool checkTopic1,
        bool checkTopic2,
        bool checkTopic3,
        bool checkData
    ) external;

    /// Same as the previous method, but also checks supplied address against emitting contract.
    function expectEmitAnonymous(
        bool checkTopic0,
        bool checkTopic1,
        bool checkTopic2,
        bool checkTopic3,
        bool checkData,
        address emitter
    ) external;

    /// Prepare an expected anonymous log with all topic and data checks enabled.
    /// Call this function, then emit an anonymous event, then call a function. Internally after the call, we check if
    /// logs were emitted in the expected order with the expected topics and data.
    function expectEmitAnonymous() external;

    /// Same as the previous method, but also checks supplied address against emitting contract.
    function expectEmitAnonymous(address emitter) external;

    /// Prepare an expected log with (bool checkTopic1, bool checkTopic2, bool checkTopic3, bool checkData.).
    /// Call this function, then emit an event, then call a function. Internally after the call, we check if
    /// logs were emitted in the expected order with the expected topics and data (as specified by the booleans).
    function expectEmit(
        bool checkTopic1,
        bool checkTopic2,
        bool checkTopic3,
        bool checkData
    ) external;

    /// Same as the previous method, but also checks supplied address against emitting contract.
    function expectEmit(
        bool checkTopic1,
        bool checkTopic2,
        bool checkTopic3,
        bool checkData,
        address emitter
    ) external;

    /// Prepare an expected log with all topic and data checks enabled.
    /// Call this function, then emit an event, then call a function. Internally after the call, we check if
    /// logs were emitted in the expected order with the expected topics and data.
    function expectEmit() external;

    /// Same as the previous method, but also checks supplied address against emitting contract.
    function expectEmit(address emitter) external;

    /// Expect a given number of logs with the provided topics.
    function expectEmit(
        bool checkTopic1,
        bool checkTopic2,
        bool checkTopic3,
        bool checkData,
        uint64 count
    ) external;

    /// Expect a given number of logs from a specific emitter with the provided topics.
    function expectEmit(
        bool checkTopic1,
        bool checkTopic2,
        bool checkTopic3,
        bool checkData,
        address emitter,
        uint64 count
    ) external;

    /// Expect a given number of logs with all topic and data checks enabled.
    function expectEmit(uint64 count) external;

    /// Expect a given number of logs from a specific emitter with all topic and data checks enabled.
    function expectEmit(address emitter, uint64 count) external;

    /// Expects an error on next call that starts with the revert data.
    function expectPartialRevert(bytes4 revertData) external;

    /// Expects an error on next call to reverter address, that starts with the revert data.
    function expectPartialRevert(bytes4 revertData, address reverter) external;

    /// Expects an error on next call with any revert data.
    function expectRevert() external;

    /// Expects an error on next call that exactly matches the revert data.
    function expectRevert(bytes4 revertData) external;

    /// Expects a `count` number of reverts from the upcoming calls from the reverter address that match the revert data.
    function expectRevert(
        bytes4 revertData,
        address reverter,
        uint64 count
    ) external;

    /// Expects a `count` number of reverts from the upcoming calls from the reverter address that exactly match the revert data.
    function expectRevert(
        bytes calldata revertData,
        address reverter,
        uint64 count
    ) external;

    /// Expects an error on next call that exactly matches the revert data.
    function expectRevert(bytes calldata revertData) external;

    /// Expects an error with any revert data on next call to reverter address.
    function expectRevert(address reverter) external;

    /// Expects an error from reverter address on next call, with any revert data.
    function expectRevert(bytes4 revertData, address reverter) external;

    /// Expects an error from reverter address on next call, that exactly matches the revert data.
    function expectRevert(bytes calldata revertData, address reverter) external;

    /// Expects a `count` number of reverts from the upcoming calls with any revert data or reverter.
    function expectRevert(uint64 count) external;

    /// Expects a `count` number of reverts from the upcoming calls that match the revert data.
    function expectRevert(bytes4 revertData, uint64 count) external;

    /// Expects a `count` number of reverts from the upcoming calls that exactly match the revert data.
    function expectRevert(bytes calldata revertData, uint64 count) external;

    /// Expects a `count` number of reverts from the upcoming calls from the reverter address.
    function expectRevert(address reverter, uint64 count) external;

    /// Only allows memory writes to offsets [0x00, 0x60) ∪ [min, max) in the current subcontext. If any other
    /// memory is written to, the test will fail. Can be called multiple times to add more ranges to the set.
    function expectSafeMemory(uint64 min, uint64 max) external;

    /// Only allows memory writes to offsets [0x00, 0x60) ∪ [min, max) in the next created subcontext.
    /// If any other memory is written to, the test will fail. Can be called multiple times to add more ranges
    /// to the set.
    function expectSafeMemoryCall(uint64 min, uint64 max) external;

    /// Marks a test as skipped. Must be called at the top level of a test.
    function skip(bool skipTest) external;

    /// Marks a test as skipped with a reason. Must be called at the top level of a test.
    function skip(bool skipTest, string calldata reason) external;

    /// Stops all safe memory expectation in the current subcontext.
    function stopExpectSafeMemory() external;
}

// SPDX-License-Identifier: MIT

pragma solidity 0.8.29;

interface IL1BridgeAdapter {

    // gigaRoot is emitted as a bytes32 here because thats how it's recovered on the
    //  L2 side of this rootBridgeAdapter.  Key and index are also used to
    // retrieve this newGigaRoot on L2
    event ReceivedNewL2Root(uint256 indexed newL2Root, uint256 l2Block);

    // /**
    //  * @notice adds an L2 message which can only be consumed publicly on L1
    //  * @param _newGigaRoot - The new gigaRoot to send to L2 as a message
    //  */
    // function receiveGigaRoot(
    //     uint256 _newGigaRoot
    // ) external;

    // function getLocalRootAndBlock() view external returns (uint256, uint256);
}

// SPDX-License-Identifier: MIT

pragma solidity 0.8.29;

interface IGigaRootProvider {
    function sendGigaRoot(address _gigaRootRecipient) external payable;
    function gigaRoot() external returns(uint256);
}

interface IGigaRootRecipient {
    function receiveGigaRoot(uint256 _gigaRoot) payable external;
    //function receiveGigaRoot(uint256 _gigaRoot, uint256 _gasLimit) payable external;
}


interface ILocalRootProvider {
    function getLocalRootAndBlock() external returns (uint256, uint256);
}

interface ILocalRootRecipient {
    //only gigaBridge does this
    //function updateGigaRoot(address[] memory _localRootProvider) external;
}

{
  "optimizer": {
    "enabled": true,
    "runs": 1000
  },
  "evmVersion": "cancun",
  "outputSelection": {
    "*": {
      "*": [
        "evm.bytecode",
        "evm.deployedBytecode",
        "devdoc",
        "userdoc",
        "metadata",
        "abi"
      ]
    }
  }
}

[{"inputs":[],"stateMutability":"nonpayable","type":"constructor"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"bytes32","name":"newGigaRoot","type":"bytes32"},{"indexed":false,"internalType":"bytes32","name":"key","type":"bytes32"},{"indexed":false,"internalType":"uint256","name":"index","type":"uint256"}],"name":"NewGigaRootSentToAztec","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"uint256","name":"newL2Root","type":"uint256"},{"indexed":false,"internalType":"uint256","name":"l2Block","type":"uint256"}],"name":"ReceivedNewL2Root","type":"event"},{"inputs":[{"internalType":"bytes32","name":"_newL2Root","type":"bytes32"},{"internalType":"uint256","name":"_bridgedL2BlockNumber","type":"uint256"}],"name":"getContentHash","outputs":[{"internalType":"bytes32","name":"","type":"bytes32"}],"stateMutability":"pure","type":"function"},{"inputs":[],"name":"getLocalRootAndBlock","outputs":[{"internalType":"uint256","name":"","type":"uint256"},{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"bytes32","name":"_newL2Root","type":"bytes32"},{"internalType":"uint256","name":"_bridgedL2BlockNumber","type":"uint256"},{"internalType":"uint256","name":"_witnessL2BlockNumber","type":"uint256"},{"internalType":"uint256","name":"_leafIndex","type":"uint256"},{"internalType":"bytes32[]","name":"_path","type":"bytes32[]"}],"name":"getNewRootFromL2","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"gigaBridge","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"inbox","outputs":[{"internalType":"contract IInbox","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_registry","type":"address"},{"internalType":"bytes32","name":"_l2AztecBridgeAdapter","type":"bytes32"},{"internalType":"address","name":"_gigaRootBridge","type":"address"}],"name":"initialize","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"l2AztecBridgeAdapter","outputs":[{"internalType":"bytes32","name":"","type":"bytes32"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"mostRecentL2Root","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"mostRecentL2RootBlockNumber","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"outbox","outputs":[{"internalType":"contract IOutbox","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"_newGigaRoot","type":"uint256"}],"name":"receiveGigaRoot","outputs":[],"stateMutability":"payable","type":"function"},{"inputs":[],"name":"rollup","outputs":[{"internalType":"contract IRollup","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"rollupVersion","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"}]

0x60806040526008805460ff60a01b19169055348015601b575f5ffd5b50600880546001600160a01b03191633179055610d738061003b5f395ff3fe6080604052600436106100ce575f3560e01c8063b08938871161007c578063d0623e6d11610057578063d0623e6d146101f6578063d26b3e6e1461020a578063df37416514610229578063fb0e722b14610248575f5ffd5b8063b08938871461018b578063cb23bcb5146101a0578063ce11e6ab146101d7575f5ffd5b806395e2c676116100ac57806395e2c6761461012e578063ac0437101461014d578063ae5582fa14610162575f5ffd5b806327e74ca3146100d25780632f4eb62d146100e75780634bd1a1c61461010f575b5f5ffd5b6100e56100e0366004610abe565b610267565b005b3480156100f2575f5ffd5b506100fc60015481565b6040519081526020015b60405180910390f35b34801561011a575f5ffd5b506100e5610129366004610ad5565b6102d2565b348015610139575f5ffd5b506100fc610148366004610b6b565b6103f4565b348015610158575f5ffd5b506100fc60025481565b34801561016d575f5ffd5b5061017661042f565b60408051928352602083019190915201610106565b348015610196575f5ffd5b506100fc60065481565b3480156101ab575f5ffd5b506003546101bf906001600160a01b031681565b6040516001600160a01b039091168152602001610106565b3480156101e2575f5ffd5b506004546101bf906001600160a01b031681565b348015610201575f5ffd5b506100fc5f5481565b348015610215575f5ffd5b506100e5610224366004610b9f565b610577565b348015610234575f5ffd5b506007546101bf906001600160a01b031681565b348015610253575f5ffd5b506005546101bf906001600160a01b031681565b6007546001600160a01b031633146102c65760405162461bcd60e51b815260206004820152600e60248201527f4e6f74206769676142726964676500000000000000000000000000000000000060448201526064015b60405180910390fd5b6102cf816108fe565b50565b5f6102dd87876103f4565b6040805160a0810182525f54606082019081526006546080830152815281518083018352308152466020808301919091528201528082018390526004805492517f7fb3496700000000000000000000000000000000000000000000000000000000815293945090926001600160a01b0390921691637fb349679161036b9185918b918b918b918b9101610bde565b5f604051808303815f87803b158015610382575f5ffd5b505af1158015610394573d5f5f3e3d5ffd5b50506002548a9250891090506103e957807f475b5c7799f48003a7afb7bac86d23c4d2cfd499581b90657c981e4616318a2c896040516103d691815260200190565b60405180910390a2600181905560028890555b505050505050505050565b5f6104288383604051602001610414929190918252602082015260400190565b604051602081830303815290604052610a23565b9392505050565b5f5f5f600154116104ce5760405162461bcd60e51b815260206004820152605060248201527f416e204c3220726f6f74206861736e277420796574206265656e20627269646760448201527f656420746f207468697320636f6e74726163742e2072656672657368526f6f7460648201527f206d7573742062652063616c6c65642e00000000000000000000000000000000608482015260a4016102bd565b5f6002541161056b5760405162461bcd60e51b815260206004820152605060248201527f416e204c3220726f6f74206861736e277420796574206265656e20627269646760448201527f656420746f207468697320636f6e74726163742e2072656672657368526f6f7460648201527f206d7573742062652063616c6c65642e00000000000000000000000000000000608482015260a4016102bd565b50506001546002549091565b6008546001600160a01b031633146105d15760405162461bcd60e51b815260206004820152601060248201527f4e6f7420746865206465706c6f7965720000000000000000000000000000000060448201526064016102bd565b600854600160a01b900460ff161561062b5760405162461bcd60e51b815260206004820152601560248201527f63616e7420696e697469616c697a65207477696365000000000000000000000060448201526064016102bd565b600880547fffffffffffffffffffffff00ffffffffffffffffffffffffffffffffffffffff16600160a01b1790555f829055604080517f971b0e6b00000000000000000000000000000000000000000000000000000000815290516001600160a01b0385169163971b0e6b9160048083019260209291908290030181865afa1580156106b9573d5f5f3e3d5ffd5b505050506040513d601f19601f820116820180604052508101906106dd9190610c83565b6003805473ffffffffffffffffffffffffffffffffffffffff19166001600160a01b03929092169182179055604080517fa32fbb7b000000000000000000000000000000000000000000000000000000008152905163a32fbb7b916004808201926020929091908290030181865afa15801561075b573d5f5f3e3d5ffd5b505050506040513d601f19601f8201168201806040525081019061077f9190610c83565b6004805473ffffffffffffffffffffffffffffffffffffffff19166001600160a01b03928316178155600354604080517f368c093c0000000000000000000000000000000000000000000000000000000081529051919093169263368c093c92818101926020929091908290030181865afa158015610800573d5f5f3e3d5ffd5b505050506040513d601f19601f820116820180604052508101906108249190610c83565b6005805473ffffffffffffffffffffffffffffffffffffffff19166001600160a01b03928316179055600354604080517f0d8e6e2c00000000000000000000000000000000000000000000000000000000815290519190921691630d8e6e2c9160048083019260209291908290030181865afa1580156108a6573d5f5f3e3d5ffd5b505050506040513d601f19601f820116820180604052508101906108ca9190610c9e565b6006556007805473ffffffffffffffffffffffffffffffffffffffff19166001600160a01b03929092169190911790555050565b6040805180820182525f805482526006546020830190815260055493517f1f6d510b0000000000000000000000000000000000000000000000000000000081528351600482015290516024820152604481018590527e1dc7b0244cb71a4609d526300ba6771064bd046848666f7bfe577053d630c56064820181905292938593929182916001600160a01b031690631f6d510b9060840160408051808303815f875af11580156109b0573d5f5f3e3d5ffd5b505050506040513d601f19601f820116820180604052508101906109d49190610cb5565b91509150837f64986607a90a031414cac90eb78251d467a1219888fd4297669057a9718533458383604051610a13929190918252602082015260400190565b60405180910390a2505050505050565b6040805160018082528183019092525f9160208201818036833701905050600283604051610a519190610cee565b602060405180830381855afa158015610a6c573d5f5f3e3d5ffd5b5050506040513d601f19601f82011682018060405250810190610a8f9190610c9e565b604051602001610aa0929190610cf9565b604051602081830303815290604052610ab890610d17565b92915050565b5f60208284031215610ace575f5ffd5b5035919050565b5f5f5f5f5f5f60a08789031215610aea575f5ffd5b86359550602087013594506040870135935060608701359250608087013567ffffffffffffffff811115610b1c575f5ffd5b8701601f81018913610b2c575f5ffd5b803567ffffffffffffffff811115610b42575f5ffd5b8960208260051b8401011115610b56575f5ffd5b60208201935080925050509295509295509295565b5f5f60408385031215610b7c575f5ffd5b50508035926020909101359150565b6001600160a01b03811681146102cf575f5ffd5b5f5f5f60608486031215610bb1575f5ffd5b8335610bbc81610b8b565b9250602084013591506040840135610bd381610b8b565b809150509250925092565b610bf381875180518252602090810151910152565b5f60208701516001600160a01b0381511660408401526020810151606084015250604087015160808301528560a08301528460c083015261010060e0830152826101008301527f07ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff831115610c65575f5ffd5b8260051b808561012085013791909101610120019695505050505050565b5f60208284031215610c93575f5ffd5b815161042881610b8b565b5f60208284031215610cae575f5ffd5b5051919050565b5f5f60408385031215610cc6575f5ffd5b505080516020909101519092909150565b5f81518060208401855e5f93019283525090919050565b5f6104288284610cd7565b5f610d048285610cd7565b60ff199390931683525050601f01919050565b80516020808301519190811015610d37575f198160200360031b1b821691505b5091905056fea2646970667358221220dd1e19b731f05df9124314e4df94a83d4009d1ae0d929bb7f5857cb25ffde7d864736f6c634300081d0033

0x6080604052600436106100ce575f3560e01c8063b08938871161007c578063d0623e6d11610057578063d0623e6d146101f6578063d26b3e6e1461020a578063df37416514610229578063fb0e722b14610248575f5ffd5b8063b08938871461018b578063cb23bcb5146101a0578063ce11e6ab146101d7575f5ffd5b806395e2c676116100ac57806395e2c6761461012e578063ac0437101461014d578063ae5582fa14610162575f5ffd5b806327e74ca3146100d25780632f4eb62d146100e75780634bd1a1c61461010f575b5f5ffd5b6100e56100e0366004610abe565b610267565b005b3480156100f2575f5ffd5b506100fc60015481565b6040519081526020015b60405180910390f35b34801561011a575f5ffd5b506100e5610129366004610ad5565b6102d2565b348015610139575f5ffd5b506100fc610148366004610b6b565b6103f4565b348015610158575f5ffd5b506100fc60025481565b34801561016d575f5ffd5b5061017661042f565b60408051928352602083019190915201610106565b348015610196575f5ffd5b506100fc60065481565b3480156101ab575f5ffd5b506003546101bf906001600160a01b031681565b6040516001600160a01b039091168152602001610106565b3480156101e2575f5ffd5b506004546101bf906001600160a01b031681565b348015610201575f5ffd5b506100fc5f5481565b348015610215575f5ffd5b506100e5610224366004610b9f565b610577565b348015610234575f5ffd5b506007546101bf906001600160a01b031681565b348015610253575f5ffd5b506005546101bf906001600160a01b031681565b6007546001600160a01b031633146102c65760405162461bcd60e51b815260206004820152600e60248201527f4e6f74206769676142726964676500000000000000000000000000000000000060448201526064015b60405180910390fd5b6102cf816108fe565b50565b5f6102dd87876103f4565b6040805160a0810182525f54606082019081526006546080830152815281518083018352308152466020808301919091528201528082018390526004805492517f7fb3496700000000000000000000000000000000000000000000000000000000815293945090926001600160a01b0390921691637fb349679161036b9185918b918b918b918b9101610bde565b5f604051808303815f87803b158015610382575f5ffd5b505af1158015610394573d5f5f3e3d5ffd5b50506002548a9250891090506103e957807f475b5c7799f48003a7afb7bac86d23c4d2cfd499581b90657c981e4616318a2c896040516103d691815260200190565b60405180910390a2600181905560028890555b505050505050505050565b5f6104288383604051602001610414929190918252602082015260400190565b604051602081830303815290604052610a23565b9392505050565b5f5f5f600154116104ce5760405162461bcd60e51b815260206004820152605060248201527f416e204c3220726f6f74206861736e277420796574206265656e20627269646760448201527f656420746f207468697320636f6e74726163742e2072656672657368526f6f7460648201527f206d7573742062652063616c6c65642e00000000000000000000000000000000608482015260a4016102bd565b5f6002541161056b5760405162461bcd60e51b815260206004820152605060248201527f416e204c3220726f6f74206861736e277420796574206265656e20627269646760448201527f656420746f207468697320636f6e74726163742e2072656672657368526f6f7460648201527f206d7573742062652063616c6c65642e00000000000000000000000000000000608482015260a4016102bd565b50506001546002549091565b6008546001600160a01b031633146105d15760405162461bcd60e51b815260206004820152601060248201527f4e6f7420746865206465706c6f7965720000000000000000000000000000000060448201526064016102bd565b600854600160a01b900460ff161561062b5760405162461bcd60e51b815260206004820152601560248201527f63616e7420696e697469616c697a65207477696365000000000000000000000060448201526064016102bd565b600880547fffffffffffffffffffffff00ffffffffffffffffffffffffffffffffffffffff16600160a01b1790555f829055604080517f971b0e6b00000000000000000000000000000000000000000000000000000000815290516001600160a01b0385169163971b0e6b9160048083019260209291908290030181865afa1580156106b9573d5f5f3e3d5ffd5b505050506040513d601f19601f820116820180604052508101906106dd9190610c83565b6003805473ffffffffffffffffffffffffffffffffffffffff19166001600160a01b03929092169182179055604080517fa32fbb7b000000000000000000000000000000000000000000000000000000008152905163a32fbb7b916004808201926020929091908290030181865afa15801561075b573d5f5f3e3d5ffd5b505050506040513d601f19601f8201168201806040525081019061077f9190610c83565b6004805473ffffffffffffffffffffffffffffffffffffffff19166001600160a01b03928316178155600354604080517f368c093c0000000000000000000000000000000000000000000000000000000081529051919093169263368c093c92818101926020929091908290030181865afa158015610800573d5f5f3e3d5ffd5b505050506040513d601f19601f820116820180604052508101906108249190610c83565b6005805473ffffffffffffffffffffffffffffffffffffffff19166001600160a01b03928316179055600354604080517f0d8e6e2c00000000000000000000000000000000000000000000000000000000815290519190921691630d8e6e2c9160048083019260209291908290030181865afa1580156108a6573d5f5f3e3d5ffd5b505050506040513d601f19601f820116820180604052508101906108ca9190610c9e565b6006556007805473ffffffffffffffffffffffffffffffffffffffff19166001600160a01b03929092169190911790555050565b6040805180820182525f805482526006546020830190815260055493517f1f6d510b0000000000000000000000000000000000000000000000000000000081528351600482015290516024820152604481018590527e1dc7b0244cb71a4609d526300ba6771064bd046848666f7bfe577053d630c56064820181905292938593929182916001600160a01b031690631f6d510b9060840160408051808303815f875af11580156109b0573d5f5f3e3d5ffd5b505050506040513d601f19601f820116820180604052508101906109d49190610cb5565b91509150837f64986607a90a031414cac90eb78251d467a1219888fd4297669057a9718533458383604051610a13929190918252602082015260400190565b60405180910390a2505050505050565b6040805160018082528183019092525f9160208201818036833701905050600283604051610a519190610cee565b602060405180830381855afa158015610a6c573d5f5f3e3d5ffd5b5050506040513d601f19601f82011682018060405250810190610a8f9190610c9e565b604051602001610aa0929190610cf9565b604051602081830303815290604052610ab890610d17565b92915050565b5f60208284031215610ace575f5ffd5b5035919050565b5f5f5f5f5f5f60a08789031215610aea575f5ffd5b86359550602087013594506040870135935060608701359250608087013567ffffffffffffffff811115610b1c575f5ffd5b8701601f81018913610b2c575f5ffd5b803567ffffffffffffffff811115610b42575f5ffd5b8960208260051b8401011115610b56575f5ffd5b60208201935080925050509295509295509295565b5f5f60408385031215610b7c575f5ffd5b50508035926020909101359150565b6001600160a01b03811681146102cf575f5ffd5b5f5f5f60608486031215610bb1575f5ffd5b8335610bbc81610b8b565b9250602084013591506040840135610bd381610b8b565b809150509250925092565b610bf381875180518252602090810151910152565b5f60208701516001600160a01b0381511660408401526020810151606084015250604087015160808301528560a08301528460c083015261010060e0830152826101008301527f07ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff831115610c65575f5ffd5b8260051b808561012085013791909101610120019695505050505050565b5f60208284031215610c93575f5ffd5b815161042881610b8b565b5f60208284031215610cae575f5ffd5b5051919050565b5f5f60408385031215610cc6575f5ffd5b505080516020909101519092909150565b5f81518060208401855e5f93019283525090919050565b5f6104288284610cd7565b5f610d048285610cd7565b60ff199390931683525050601f01919050565b80516020808301519190811015610d37575f198160200360031b1b821691505b5091905056fea2646970667358221220dd1e19b731f05df9124314e4df94a83d4009d1ae0d929bb7f5857cb25ffde7d864736f6c634300081d0033