Cryo Explorer Ethereum Mainnet

// SPDX-License-Identifier: BUSL-1.1
pragma solidity ^0.8.28;

import {Toll} from "chronicle-std@v2/toll/Toll.sol";

import {UScribe} from "uscribe@v1/UScribe.sol";

import {IChronicleVAO_Superstate_USTB_Reader as IReader} from "./IReader.sol";

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

// The poke struct is the single struct that is being poked.
struct PokeData {
    uint48 age;
    uint128 val;
}

/**
 * @title ChronicleVAO_Superstate_USTB_Consumer_2
 * @custom:uscribe-version 1.3.0
 *
 * @author Chronicle Labs, Inc
 * @custom:security-contact [email protected]
 */
contract ChronicleVAO_Superstate_USTB_Consumer_2 is
    UScribe,
    TollWithImmutableRouter,
    IReader
{

    /// @notice Thrown if attempted to poke a stale message.
    error StaleMessage();

    /// @notice Thrown if attempted to poke a future message.
    error FutureMessage();

    /// @notice Emitted when a poke is received.
    /// @param caller The caller's address.
    /// @param val The value poked.
    /// @param age The age of the value poked.
    event Poked(address indexed caller, uint128 val, uint48 age);

    //--------------------------------------------------------------------------
    // Storage

    uint128 internal _val;

    //--------------------------------------------------------------------------
    // Constructor

    constructor(address initialAuthed, address router)
        UScribe(initialAuthed, "VAO::Superstate_USTB")
        TollWithImmutableRouter(router)
    {}

    /// @dev Defines authorization for IToll's authenticated functions.
    function toll_auth() internal override(TollWithImmutableRouter) auth {}

    //--------------------------------------------------------------------------
    // Poke Functionality

    /// @dev Function to handle state update.
    ///
    ///      This function is being called by the upstream uScribe
    ///      implementation iff the poke's signature verification succeeded.
    ///
    ///      Therefore, this function MUST only verify the payload contains
    ///      correctly encoded, non-stale and non-future data before committing a state update.
    ///
    /// @dev Reverts if:
    ///      - Decoding payload to expected format fails
    ///
    /// @dev Returns error if:
    ///      - Payload is stale
    ///      - Payload is signed at a future date to block timestamp
    ///
    /// @dev The payload is expected to be encoded using the PokeData struct
    ///      containing the fields:
    ///
    ///      - age: uint48
    ///      - val: uint128
    ///
    ///  @dev The age stored after a poke is equal to the current block time,
    ///       not the age sent in the poke.
    function _poke(bytes calldata payload)
        internal
        override(UScribe)
        returns (bytes4)
    {
        PokeData memory pokeData = abi.decode(payload, (PokeData));

        // Fail if payload stale.
        if (pokeData.age <= latestPoke()) {
            return StaleMessage.selector;
        }

        // Fail if payload from the future.
        if (pokeData.age > block.timestamp) {
            return FutureMessage.selector;
        }

        // Store the poke's val.
        _val = pokeData.val;

        emit Poked(msg.sender, pokeData.val, pokeData.age);

        return _NO_ERR;
    }

    //--------------------------------------------------------------------------
    // IReader Functionality
    //
    // Note that read functions differ from Scribe with regards to `val = 0` not
    // being a failure code. Read functions only revert/fail if
    // `latestPoke() = 0`, implying no valid poke occured yet.
    //
    // Side effect of this is that the read functions cannot be disabled.

    //// @inheritdoc IVAOReader
    function read() public view toll returns (uint val) {
        bool ok;
        (ok, val,) = _tryReadWithAge();
        require(ok);
    }

    //// @inheritdoc IVAOReader
    function tryRead() public view toll returns (bool ok, uint val) {
        (ok, val,) = _tryReadWithAge();
        // assert(ok || val == 0);
    }

    //// @inheritdoc IVAOReader
    function readWithAge() public view toll returns (uint val, uint age) {
        bool ok;
        (ok, val, age) = _tryReadWithAge();
        require(ok);
    }

    //// @inheritdoc IVAOReader
    function tryReadWithAge()
        public
        view
        toll
        returns (bool ok, uint val, uint age)
    {
        (ok, val, age) = _tryReadWithAge();
    }

    function _tryReadWithAge()
        internal
        view
        returns (bool ok, uint val, uint age)
    {
        age = latestPoke();
        val = _val;
        ok = age != 0;
        // assert(ok || val == 0);
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.16;

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

/**
 * @title Toll Module
 *
 * @notice "Toll paid, we kiss - but dissension looms, maybe diss?"
 *
 * @dev The `Toll` contract module provides a basic access control mechanism,
 *      where a set of addresses are granted access to protected functions.
 *      These addresses are said the be _tolled_.
 *
 *      Initially, no address is tolled. Through the `kiss(address)` and
 *      `diss(address)` functions, auth'ed callers are able to toll/de-toll
 *      addresses. Authentication for these functions is defined via the
 *      downstream implemented `toll_auth()` function.
 *
 *      This module is used through inheritance. It will make available the
 *      modifier `toll`, which can be applied to functions to restrict their
 *      use to only tolled callers.
 */
abstract contract Toll is IToll {
    /// @dev Mapping storing whether address is tolled.
    /// @custom:invariant Image of mapping is {0, 1}.
    ///                     ∀x ∊ Address: _buds[x] ∊ {0, 1}
    /// @custom:invariant Only functions `kiss` and `diss` may mutate the mapping's state.
    ///                     ∀x ∊ Address: preTx(_buds[x]) != postTx(_buds[x])
    ///                                     → (msg.sig == "kiss" ∨ msg.sig == "diss")
    /// @custom:invariant Mapping's state may only be mutated by authenticated caller.
    ///                     ∀x ∊ Address: preTx(_buds[x]) != postTx(_buds[x])
    ///                                     → toll_auth()
    mapping(address => uint) private _buds;

    /// @dev List of addresses possibly being tolled.
    /// @dev May contain duplicates.
    /// @dev May contain addresses not being tolled anymore.
    /// @custom:invariant Every address being tolled once is element of the list.
    ///                     ∀x ∊ Address: tolled(x) → x ∊ _budsTouched
    address[] private _budsTouched;

    /// @dev Ensures caller is tolled.
    modifier toll() {
        assembly ("memory-safe") {
            // Compute slot of _buds[msg.sender].
            mstore(0x00, caller())
            mstore(0x20, _buds.slot)
            let slot := keccak256(0x00, 0x40)

            // Revert if caller not tolled.
            let isTolled := sload(slot)
            if iszero(isTolled) {
                // Store selector of `NotTolled(address)`.
                mstore(0x00, 0xd957b595)
                // Store msg.sender.
                mstore(0x20, caller())
                // Revert with (offset, size).
                revert(0x1c, 0x24)
            }
        }
        _;
    }

    /// @dev Reverts if caller not allowed to access protected function.
    /// @dev Must be implemented in downstream contract.
    function toll_auth() internal virtual;

    /// @inheritdoc IToll
    function kiss(address who) external {
        toll_auth();

        if (_buds[who] == 1) return;

        _buds[who] = 1;
        _budsTouched.push(who);
        emit TollGranted(msg.sender, who);
    }

    /// @inheritdoc IToll
    function diss(address who) external {
        toll_auth();

        if (_buds[who] == 0) return;

        _buds[who] = 0;
        emit TollRenounced(msg.sender, who);
    }

    /// @inheritdoc IToll
    function tolled(address who) public view returns (bool) {
        return _buds[who] == 1;
    }

    /// @inheritdoc IToll
    /// @custom:invariant Only contains tolled addresses.
    ///                     ∀x ∊ tolled(): _tolled[x]
    /// @custom:invariant Contains all tolled addresses.
    ///                     ∀x ∊ Address: _tolled[x] == 1 → x ∊ tolled()
    function tolled() public view returns (address[] memory) {
        // Initiate array with upper limit length.
        address[] memory budsList = new address[](_budsTouched.length);

        // Iterate through all possible tolled addresses.
        uint ctr;
        for (uint i; i < budsList.length; i++) {
            // Add address only if still tolled.
            if (_buds[_budsTouched[i]] == 1) {
                budsList[ctr++] = _budsTouched[i];
            }
        }

        // Set length of array to number of tolled addresses actually included.
        assembly ("memory-safe") {
            mstore(budsList, ctr)
        }

        return budsList;
    }

    /// @inheritdoc IToll
    function bud(address who) public view returns (uint) {
        return _buds[who];
    }
}

// SPDX-License-Identifier: BUSL-1.1
pragma solidity ^0.8.24;

import {Auth} from "chronicle-std@v2/auth/Auth.sol";

import {IUScribe} from "./IUScribe.sol";
import {UPokeData, SchnorrData, ECDSAData} from "./Types.sol";

import {LibSchnorr} from "./libs/LibSchnorr.sol";
import {LibSecp256k1} from "./libs/LibSecp256k1.sol";

/**
 * @title UScribe
 * @custom:version 1.2.0
 *
 * @notice A universal Oracle
 *
 * @author Chronicle Labs, Inc
 * @custom:security-contact [email protected]
 */
abstract contract UScribe is IUScribe, Auth {
    using LibSchnorr for LibSecp256k1.Point;
    using LibSecp256k1 for LibSecp256k1.Point;
    using LibSecp256k1 for LibSecp256k1.JacobianPoint;

    //--------------------------------------------------------------------------
    // Constants and Immutables

    bytes4 internal constant _NO_ERR = bytes4(0);

    /// @inheritdoc IUScribe
    bytes32 public immutable wat;

    // Note that strings cannot be marked as immutable.
    // @custom:invariant Is immutable.
    string private _name;

    //--------------------------------------------------------------------------
    // Storage

    uint48 private _latestPoke;

    struct SchnorrStorage {
        LibSecp256k1.Point[256] pubKeys;
        uint8 bar;
    }

    SchnorrStorage private __schnorrStorage;

    struct ECDSAStorage {
        address[256] validators;
        uint8 bar;
    }

    ECDSAStorage private __ecdsaStorage;

    //--------------------------------------------------------------------------
    // Constructor

    constructor(address initialAuthed, string memory name_)
        Auth(initialAuthed)
    {
        require(bytes(name_).length != 0);

        _name = name_;
        wat = keccak256(bytes(name_));

        // Note to not have bars of zero.
        __schnorrStorage.bar = type(uint8).max;
        __ecdsaStorage.bar = type(uint8).max;
    }

    /// @inheritdoc IUScribe
    function name() external view returns (string memory) {
        return _name;
    }

    //--------------------------------------------------------------------------
    // Consumer Implemented Functionality

    /// @dev Function implemented in downstream consumer contract to handle
    ///      application specific state update.
    ///
    /// @dev The implementation MUST deserialize the payload and perform
    ///      necessary sanity checks.
    ///
    ///      It SHOULD NOT revert but instead return the error types' selector
    ///      whenever possible. This allows uScribe to wrap the application
    ///      specific error into a `PokeError_ConsumerRejectedPayload()` error.
    ///
    ///      To indicate a successful poke, the function MUST return the
    ///      `_NO_ERR = bytes4(0)` constant.
    ///
    /// @dev Note that this function is vulnerable to replay attacks.
    ///
    ///      Consumers MUST implement application specific logic to prevent
    ///      replayability issues. uScribe only verifies that the respective
    ///      validators attested to the payload at some point in time, ie
    ///      uScribe performs a stateless signature verification.
    ///
    ///      Note that this requires the payload to contain sufficient data for
    ///      the consumer logic to protect against replayability issues.
    ///
    ///      Protections against replayability issues MAY be including a nonce
    ///      in the payload or only accepting payloads with strictly
    ///      monotonically increasing timestamps. The `latestPoke()(uint)`
    ///      function can be used by consumers to access the timestamp of the
    ///      last poke.
    ///
    ///      To protect against cross-chain replayability issues the payload
    ///      MAY be expected to include the chain's id.
    ///
    /// @param payload The verified payload blob.
    /// @return bytes4 `_NO_ERR` if poke successful, application's error type
    ///                selector otherwise.
    function _poke(bytes calldata payload) internal virtual returns (bytes4);

    //--------------------------------------------------------------------------
    // Poke Functionality

    /// @inheritdoc IUScribe
    function poke(UPokeData calldata uPokeData, SchnorrData calldata schnorr)
        external
    {
        bytes4 err;
        bytes32 message;

        // Construct Schnorr Chronicle Signed Message of uPokeData.
        message = constructChronicleSignedMessage({
            scheme: bytes32("SCHNORR"),
            uPokeData: uPokeData
        });

        // Verify Schnorr signature.
        err = __verifySchnorrSignature(message, schnorr);
        if (err != _NO_ERR) {
            revert PokeError_VerificationFailed(err);
        }

        // Poke's security verified.
        emit UPoked(msg.sender, uPokeData.proofURI);

        // Forward payload to consumer.
        err = _poke(uPokeData.payload);
        if (err != _NO_ERR) {
            revert PokeError_ConsumerRejectedPayload(err);
        }

        // Update latest poke timestamp once poke accepted by consumer.
        _latestPoke = uint48(block.timestamp);
    }

    /// @inheritdoc IUScribe
    function poke(UPokeData calldata uPokeData, ECDSAData[] calldata ecdsas)
        external
    {
        bytes4 err;
        bytes32 message;

        // Construct ECDSA Chronicle Signed Message of uPokeData.
        message = constructChronicleSignedMessage({
            scheme: bytes32("ECDSA"),
            uPokeData: uPokeData
        });

        // Verify ECDSA signatures.
        err = __verifyECDSASignatures(message, ecdsas);
        if (err != _NO_ERR) {
            revert PokeError_VerificationFailed(err);
        }

        // Poke's security verified.
        emit UPoked(msg.sender, uPokeData.proofURI);

        // Forward payload to consumer.
        err = _poke(uPokeData.payload);
        if (err != _NO_ERR) {
            revert PokeError_ConsumerRejectedPayload(err);
        }

        // Update latest poke timestamp once poke accepted by consumer.
        _latestPoke = uint48(block.timestamp);
    }

    //--------------------------------------------------------------------------
    // Chronicle Signed Message Functionality

    /// @inheritdoc IUScribe
    function constructChronicleSignedMessage(
        bytes32 scheme,
        UPokeData calldata uPokeData
    ) public view returns (bytes32) {
        return keccak256(
            abi.encodePacked(
                "\x19Chronicle Signed Message:\n32",
                keccak256(
                    abi.encodePacked(
                        scheme,
                        wat,
                        keccak256(abi.encodePacked(uPokeData.payload)),
                        keccak256(abi.encodePacked(uPokeData.proofURI))
                    )
                )
            )
        );
    }

    //--------------------------------------------------------------------------
    // Signature Verification Functionality

    /// @custom:invariant Reverts iff out of gas.
    /// @custom:invariant Runtime is O(__schnorrStorage.bar).
    function __verifySchnorrSignature(
        bytes32 message,
        SchnorrData calldata schnorr
    ) private view returns (bytes4) {
        // Let pubKey be the currently processed validator's public key.
        LibSecp256k1.Point memory pubKey;
        // Let id be the currently processed validator's id.
        uint8 id;
        // Let aggPubKey be the sum of processed validator public keys.
        // Note that Jacobian coordinates are used.
        LibSecp256k1.JacobianPoint memory aggPubKey;
        // Let bloom be a bloom filter to guarantee signer uniqueness.
        uint bloom;

        // Fail if number of validators unequal to bar.
        //
        // Note that requiring equality constrains the verification's runtime
        // from Ω(bar) to Θ(bar).
        uint bar = __schnorrStorage.bar;
        if (schnorr.validatorIds.length != bar) {
            return VerificationError_BarNotReached.selector;
        }

        // Initiate validator variables.
        id = uint8(schnorr.validatorIds[0]);
        pubKey = __schnorrStorage.pubKeys[id];
        if (pubKey.isZeroPoint()) {
            return VerificationError_ValidatorInvalid.selector;
        }

        // Initiate bloom filter and aggPubKey.
        bloom = 1 << id;
        aggPubKey = pubKey.toJacobian();

        // Aggregation loop.
        for (uint i = 1; i < bar; i++) {
            // Update validator variables.
            id = uint8(schnorr.validatorIds[i]);
            pubKey = __schnorrStorage.pubKeys[id];
            if (pubKey.isZeroPoint()) {
                return VerificationError_ValidatorInvalid.selector;
            }

            // Fail if double signing attempted.
            if (bloom & (1 << id) != 0) {
                return VerificationError_DoubleSigningAttempted.selector;
            }

            // Update bloom filter.
            bloom |= 1 << id;

            // Add pubKey to aggPubKey.
            aggPubKey.addAffinePoint(pubKey);
        }

        // Perform signature verification.
        bool ok = aggPubKey.toAffine().verifySignature(
            message, schnorr.signature, schnorr.commitment
        );
        if (!ok) {
            return VerificationError_SignatureInvalid.selector;
        }

        return _NO_ERR;
    }

    /// @custom:invariant Reverts iff out of gas.
    /// @custom:invariant Runtime is O(__ecdsaStorage.bar).
    function __verifyECDSASignatures(
        bytes32 message,
        ECDSAData[] calldata ecdsas
    ) private view returns (bytes4) {
        // Let ecdsa be the currently processed ECDSA signature.
        ECDSAData memory ecdsa;
        // Let signer be the currently processed ECDSA signature's signer.
        address signer;
        // Let id the the currently processed ECDSA signature's signer id.
        uint id;
        // Let bloom be a bloom filter to guarantee signer uniqueness.
        uint bloom;

        // Fail if number of validators unequal to bar.
        //
        // Note that requiring equality constrains the verification's runtime
        // from Ω(bar) to Θ(bar).
        uint bar = __ecdsaStorage.bar;
        if (ecdsas.length != bar) {
            return VerificationError_BarNotReached.selector;
        }

        for (uint i; i < bar; i++) {
            // Update ECDSA variables.
            ecdsa = ecdsas[i];
            signer = ecrecover(message, ecdsa.v, ecdsa.r, ecdsa.s);
            id = uint160(signer) >> 152;

            // Fail if signature invalid or signer not a validator.
            // forgefmt: disable-next-item
            if (signer == address(0) || __ecdsaStorage.validators[id] != signer) {
                return VerificationError_SignatureInvalid.selector;
            }

            // Fail if double signing attempted.
            if (bloom & (1 << id) != 0) {
                return VerificationError_DoubleSigningAttempted.selector;
            }

            // Update bloom filter.
            bloom |= 1 << id;
        }

        return _NO_ERR;
    }

    //--------------------------------------------------------------------------
    // Auth'ed Functionality

    //----------------------------------
    // SchnorrStorage

    /// @inheritdoc IUScribe
    function liftSchnorr(LibSecp256k1.Point[] calldata pubKeys) external auth {
        for (uint i; i < pubKeys.length; i++) {
            LibSecp256k1.Point memory pubKey = pubKeys[i];
            require(!pubKey.isZeroPoint());
            // assert(pubKey.toAddress() != address(0));

            address validator = pubKey.toAddress();
            uint id = uint160(validator) >> 152;

            LibSecp256k1.Point memory sPubKey = __schnorrStorage.pubKeys[id];
            if (sPubKey.isZeroPoint()) {
                __schnorrStorage.pubKeys[id] = pubKey;
                emit ValidatorLiftedSchnorr(msg.sender, validator);
            } else {
                require(validator == sPubKey.toAddress());
            }
        }
    }

    /// @inheritdoc IUScribe
    function dropSchnorr(uint8[] calldata ids) external auth {
        for (uint i; i < ids.length; i++) {
            uint8 id = ids[i];

            LibSecp256k1.Point memory pubKey = __schnorrStorage.pubKeys[id];
            if (!pubKey.isZeroPoint()) {
                delete __schnorrStorage.pubKeys[id];
                emit ValidatorDroppedSchnorr(msg.sender, pubKey.toAddress());
            }
        }
    }

    /// @inheritdoc IUScribe
    function setBarSchnorr(uint8 bar) external auth {
        require(bar != 0);

        if (__schnorrStorage.bar != bar) {
            emit BarUpdatedSchnorr(msg.sender, __schnorrStorage.bar, bar);
            __schnorrStorage.bar = bar;
        }
    }

    //----------------------------------
    // ECDSAStorage

    /// @inheritdoc IUScribe
    function liftECDSA(address[] calldata validators) external auth {
        for (uint i; i < validators.length; i++) {
            address validator = validators[i];
            require(validator != address(0));

            uint id = uint160(validator) >> 152;

            if (__ecdsaStorage.validators[id] == address(0)) {
                __ecdsaStorage.validators[id] = validator;
                emit ValidatorLiftedECDSA(msg.sender, validator);
            } else {
                require(__ecdsaStorage.validators[id] == validator);
            }
        }
    }

    /// @inheritdoc IUScribe
    function dropECDSA(uint8[] calldata ids) external auth {
        for (uint i; i < ids.length; i++) {
            uint8 id = ids[i];
            address validator = __ecdsaStorage.validators[id];

            if (validator != address(0)) {
                // assert(uint160(validator) >> 152 == id);
                delete __ecdsaStorage.validators[id];
                emit ValidatorDroppedECDSA(msg.sender, validator);
            }
        }
    }

    /// @inheritdoc IUScribe
    function setBarECDSA(uint8 bar) external auth {
        require(bar != 0);

        if (__ecdsaStorage.bar != bar) {
            emit BarUpdatedECDSA(msg.sender, __ecdsaStorage.bar, bar);
            __ecdsaStorage.bar = bar;
        }
    }

    //--------------------------------------------------------------------------
    // Public View Functions

    /// @inheritdoc IUScribe
    ///
    /// @dev Note that function is public to grant read-only access to
    ///      downstream consumer.
    function latestPoke() public view returns (uint) {
        return _latestPoke;
    }

    //----------------------------------
    // SchnorrStorage

    /// @inheritdoc IUScribe
    function validatorsSchnorr(address who) external view returns (bool) {
        uint id = uint160(who) >> 152;
        LibSecp256k1.Point memory pubKey = __schnorrStorage.pubKeys[id];

        return !pubKey.isZeroPoint() && pubKey.toAddress() == who;
    }

    /// @inheritdoc IUScribe
    function validatorsSchnorr(uint8 id)
        external
        view
        returns (bool, address)
    {
        LibSecp256k1.Point memory pubKey = __schnorrStorage.pubKeys[id];

        return !pubKey.isZeroPoint()
            ? (true, pubKey.toAddress())
            : (false, address(0));
    }

    /// @inheritdoc IUScribe
    function validatorsSchnorr() external view returns (address[] memory) {
        address[] memory validators = new address[](256);

        LibSecp256k1.Point memory pubKey;
        uint ctr;
        for (uint i; i < 256; i++) {
            pubKey = __schnorrStorage.pubKeys[i];

            if (!pubKey.isZeroPoint()) {
                validators[ctr++] = pubKey.toAddress();
            }
        }

        assembly ("memory-safe") {
            mstore(validators, ctr)
        }

        return validators;
    }

    /// @inheritdoc IUScribe
    function barSchnorr() external view returns (uint8) {
        return __schnorrStorage.bar;
    }

    //----------------------------------
    // ECDSAStorage

    /// @inheritdoc IUScribe
    function validatorsECDSA(address who) external view returns (bool) {
        uint id = uint160(who) >> 152;

        return who != address(0) && __ecdsaStorage.validators[id] == who;
    }

    /// @inheritdoc IUScribe
    function validatorsECDSA(uint id) external view returns (bool, address) {
        address validator = __ecdsaStorage.validators[id];

        return validator != address(0) ? (true, validator) : (false, address(0));
    }

    /// @inheritdoc IUScribe
    function validatorsECDSA() external view returns (address[] memory) {
        address[] memory validators = new address[](256);

        address validator;
        uint ctr;
        for (uint i; i < 256; i++) {
            validator = __ecdsaStorage.validators[i];

            if (validator != address(0)) {
                validators[ctr++] = validator;
            }
        }

        assembly ("memory-safe") {
            mstore(validators, ctr)
        }

        return validators;
    }

    /// @inheritdoc IUScribe
    function barECDSA() external view returns (uint8) {
        return __ecdsaStorage.bar;
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

interface IChronicleVAO_Superstate_USTB_Reader {
    /// @notice Returns the oracle's current value.
    /// @dev Reverts if:
    ///      - Not yet poked
    /// @return val The oracle's current value.
    function read() external view returns (uint val);

    /// @notice Returns the oracle's current value.
    /// @return ok True if previously poked, false otherwise.
    /// @return val The oracle's current value if it exists, zero otherwise.
    function tryRead() external view returns (bool ok, uint val);

    /// @notice Returns the oracle's current value and its age.
    /// @dev Reverts if:
    ///      - Not yet poked
    /// @return val The oracle's current value.
    /// @return age The value's age.
    function readWithAge() external view returns (uint val, uint age);

    /// @notice Returns the oracle's current value and its age.
    /// @return ok True if previously poked, false otherwise.
    /// @return val The oracle's current value if it exists, zero otherwise.
    /// @return age The value's age if value exists, zero otherwise.
    function tryReadWithAge()
        external
        view
        returns (bool ok, uint val, uint age);
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

import {IToll} from "chronicle-std@v2/toll/IToll.sol";

/**
 * @title TollWithImmutableRouter
 *
 * @notice "Toll paid, we kiss - but dissension looms, maybe diss?"
 *
 * @dev The `TollWithImmutableRouter` contract module provides a basic access
 *      control mechanism, where a set of addresses are granted access to
 *      protected functions.
 *      These addresses are said the be _tolled_.
 *
 *      Note that this module differs from chronicle-std/Toll in that a router
 *      address given at construction is immutably tolled.
 *
 *      This path reduces gas costs for customers connecting to the router
 *      instead of directly reading from the uscribe consumer.
 *
 *      Initially, only the router is tolled. Through the `kiss(address)` and
 *      `diss(address)` functions, auth'ed callers are able to toll/de-toll
 *      addresses. Authentication for these functions is defined via the
 *      downstream implemented `toll_auth()` function.
 *
 *      This module is used through inheritance. It will make available the
 *      modifier `toll`, which can be applied to functions to restrict their
 *      use to only tolled callers.
 */
abstract contract TollWithImmutableRouter is IToll {
    /// @dev Address of the immutably tolled router.
    address private immutable _router;

    /// @dev Mapping storing whether address is tolled.
    /// @custom:invariant Image of mapping is {0, 1}.
    ///                     ∀x ∊ Address: _buds[x] ∊ {0, 1}
    /// @custom:invariant Only functions `kiss`, `diss` or constructor may
    ///                   mutate the mapping's state.
    ///                     ∀x ∊ Address: preTx(_buds[x]) != postTx(_buds[x])
    ///                                     → (msg.sig == "kiss" ∨ msg.sig == "diss" ∨ msg.sig == "")
    /// @custom:invariant Mapping's state may only be mutated by authenticated
    ///                   caller or during construction.
    ///                     ∀x ∊ Address: preTx(_buds[x]) != postTx(_buds[x])
    ///                                     → (toll_auth() ∨ msg.sig == "")
    mapping(address => uint) private _buds;

    /// @dev List of addresses possibly being tolled.
    /// @dev May contain duplicates.
    /// @dev May contain addresses not being tolled anymore.
    /// @custom:invariant Every address being tolled once is element of the list.
    ///                     ∀x ∊ Address: tolled(x) → x ∊ _budsTouched
    address[] private _budsTouched;

    constructor(address router) {
        _router = router;

        _buds[router] = 1;
        _budsTouched.push(router);
        emit TollGranted(msg.sender, router);
    }

    /// @dev Ensures caller is tolled.
    modifier toll() {
        if (msg.sender != _router) {
            assembly ("memory-safe") {
                // Compute slot of _buds[msg.sender].
                mstore(0x00, caller())
                mstore(0x20, _buds.slot)
                let slot := keccak256(0x00, 0x40)

                // Revert if caller not tolled.
                let isTolled := sload(slot)
                if iszero(isTolled) {
                    // Store selector of `NotTolled(address)`.
                    mstore(0x00, 0xd957b595)
                    // Store msg.sender.
                    mstore(0x20, caller())
                    // Revert with (offset, size).
                    revert(0x1c, 0x24)
                }
            }
        }
        _;
    }

    /// @dev Reverts if caller not allowed to access protected function.
    /// @dev Must be implemented in downstream contract.
    function toll_auth() internal virtual;

    /// @inheritdoc IToll
    function kiss(address who) external {
        toll_auth();

        if (_buds[who] == 1) return;

        _buds[who] = 1;
        _budsTouched.push(who);
        emit TollGranted(msg.sender, who);
    }

    /// @inheritdoc IToll
    function diss(address who) external {
        toll_auth();

        require(who != _router, "TollWithImmutableRouter: cannot diss router");

        if (_buds[who] == 0) return;

        _buds[who] = 0;
        emit TollRenounced(msg.sender, who);
    }

    /// @inheritdoc IToll
    function tolled(address who) public view returns (bool) {
        return _buds[who] == 1;
    }

    /// @inheritdoc IToll
    /// @custom:invariant Only contains tolled addresses.
    ///                     ∀x ∊ tolled(): _buds[x] == 1
    /// @custom:invariant Contains all tolled addresses.
    ///                     ∀x ∊ Address: _buds[x] == 1 → x ∊ tolled()
    function tolled() public view returns (address[] memory) {
        // Initiate array with upper limit length.
        address[] memory budsList = new address[](_budsTouched.length);

        // Iterate through all possible tolled addresses.
        uint ctr;
        for (uint i; i < budsList.length; i++) {
            // Add address only if still tolled.
            if (_buds[_budsTouched[i]] == 1) {
                budsList[ctr++] = _budsTouched[i];
            }
        }

        // Set length of array to number of tolled addresses actually included.
        assembly ("memory-safe") {
            mstore(budsList, ctr)
        }

        return budsList;
    }

    /// @inheritdoc IToll
    function bud(address who) public view returns (uint) {
        return _buds[who];
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.16;

interface IToll {
    /// @notice Thrown by protected function if caller not tolled.
    /// @param caller The caller's address.
    error NotTolled(address caller);

    /// @notice Emitted when toll granted to address.
    /// @param caller The caller's address.
    /// @param who The address toll got granted to.
    event TollGranted(address indexed caller, address indexed who);

    /// @notice Emitted when toll renounced from address.
    /// @param caller The caller's address.
    /// @param who The address toll got renounced from.
    event TollRenounced(address indexed caller, address indexed who);

    /// @notice Grants address `who` toll.
    /// @dev Only callable by auth'ed address.
    /// @param who The address to grant toll.
    function kiss(address who) external;

    /// @notice Renounces address `who`'s toll.
    /// @dev Only callable by auth'ed address.
    /// @param who The address to renounce toll.
    function diss(address who) external;

    /// @notice Returns whether address `who` is tolled.
    /// @param who The address to check.
    /// @return True if `who` is tolled, false otherwise.
    function tolled(address who) external view returns (bool);

    /// @notice Returns full list of addresses tolled.
    /// @dev May contain duplicates.
    /// @return List of addresses tolled.
    function tolled() external view returns (address[] memory);

    /// @notice Returns whether address `who` is tolled.
    /// @custom:deprecated Use `tolled(address)(bool)` instead.
    /// @param who The address to check.
    /// @return 1 if `who` is tolled, 0 otherwise.
    function bud(address who) external view returns (uint);
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.16;

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

/**
 * @title Auth Module
 *
 * @dev The `Auth` contract module provides a basic access control mechanism,
 *      where a set of addresses are granted access to protected functions.
 *      These addresses are said to be _auth'ed_.
 *
 *      Initially, the address given as constructor argument is the only address
 *      auth'ed. Through the `rely(address)` and `deny(address)` functions,
 *      auth'ed callers are able to grant/renounce auth to/from addresses.
 *
 *      This module is used through inheritance. It will make available the
 *      modifier `auth`, which can be applied to functions to restrict their
 *      use to only auth'ed callers.
 */
abstract contract Auth is IAuth {
    /// @dev Mapping storing whether address is auth'ed.
    /// @custom:invariant Image of mapping is {0, 1}.
    ///                     ∀x ∊ Address: _wards[x] ∊ {0, 1}
    /// @custom:invariant Only address given as constructor argument is authenticated after deployment.
    ///                     deploy(initialAuthed) → (∀x ∊ Address: _wards[x] == 1 → x == initialAuthed)
    /// @custom:invariant Only functions `rely` and `deny` may mutate the mapping's state.
    ///                     ∀x ∊ Address: preTx(_wards[x]) != postTx(_wards[x])
    ///                                     → (msg.sig == "rely" ∨ msg.sig == "deny")
    /// @custom:invariant Mapping's state may only be mutated by authenticated caller.
    ///                     ∀x ∊ Address: preTx(_wards[x]) != postTx(_wards[x]) → _wards[msg.sender] = 1
    mapping(address => uint) private _wards;

    /// @dev List of addresses possibly being auth'ed.
    /// @dev May contain duplicates.
    /// @dev May contain addresses not being auth'ed anymore.
    /// @custom:invariant Every address being auth'ed once is element of the list.
    ///                     ∀x ∊ Address: authed(x) -> x ∊ _wardsTouched
    address[] private _wardsTouched;

    /// @dev Ensures caller is auth'ed.
    modifier auth() {
        assembly ("memory-safe") {
            // Compute slot of _wards[msg.sender].
            mstore(0x00, caller())
            mstore(0x20, _wards.slot)
            let slot := keccak256(0x00, 0x40)

            // Revert if caller not auth'ed.
            let isAuthed := sload(slot)
            if iszero(isAuthed) {
                // Store selector of `NotAuthorized(address)`.
                mstore(0x00, 0x4a0bfec1)
                // Store msg.sender.
                mstore(0x20, caller())
                // Revert with (offset, size).
                revert(0x1c, 0x24)
            }
        }
        _;
    }

    constructor(address initialAuthed) {
        _wards[initialAuthed] = 1;
        _wardsTouched.push(initialAuthed);

        // Note to use address(0) as caller to indicate address was auth'ed
        // during deployment.
        emit AuthGranted(address(0), initialAuthed);
    }

    /// @inheritdoc IAuth
    function rely(address who) external auth {
        if (_wards[who] == 1) return;

        _wards[who] = 1;
        _wardsTouched.push(who);
        emit AuthGranted(msg.sender, who);
    }

    /// @inheritdoc IAuth
    function deny(address who) external auth {
        if (_wards[who] == 0) return;

        _wards[who] = 0;
        emit AuthRenounced(msg.sender, who);
    }

    /// @inheritdoc IAuth
    function authed(address who) public view returns (bool) {
        return _wards[who] == 1;
    }

    /// @inheritdoc IAuth
    /// @custom:invariant Only contains auth'ed addresses.
    ///                     ∀x ∊ authed(): _wards[x] == 1
    /// @custom:invariant Contains all auth'ed addresses.
    ///                     ∀x ∊ Address: _wards[x] == 1 → x ∊ authed()
    function authed() public view returns (address[] memory) {
        // Initiate array with upper limit length.
        address[] memory wardsList = new address[](_wardsTouched.length);

        // Iterate through all possible auth'ed addresses.
        uint ctr;
        for (uint i; i < wardsList.length; i++) {
            // Add address only if still auth'ed.
            if (_wards[_wardsTouched[i]] == 1) {
                wardsList[ctr++] = _wardsTouched[i];
            }
        }

        // Set length of array to number of auth'ed addresses actually included.
        assembly ("memory-safe") {
            mstore(wardsList, ctr)
        }

        return wardsList;
    }

    /// @inheritdoc IAuth
    function wards(address who) public view returns (uint) {
        return _wards[who];
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {UPokeData, SchnorrData, ECDSAData} from "./Types.sol";
import {LibSecp256k1} from "./libs/LibSecp256k1.sol";

interface IUScribe {
    //--------------------------------------------------------------------------
    // Errors

    /// @notice Thrown if poke verification failed.
    /// @param err The verification error.
    error PokeError_VerificationFailed(bytes4 err);

    /// @notice Thrown if poke rejected by consumer.
    /// @param err The consumer error.
    error PokeError_ConsumerRejectedPayload(bytes4 err);

    //----------------------------------
    // Verification Errors

    /// @notice Verification error thrown via `PokeError_VerificationFailed` if
    ///         poke did not reach bar threshold.
    error VerificationError_BarNotReached();

    /// @notice Verification error thrown via `PokeError_VerificationFailed` if
    ///         poke attempted double signing.
    error VerificationError_DoubleSigningAttempted();

    /// @notice Verification error thrown via `PokeError_VerificationFailed` if
    ///         poke included invalid validator.
    error VerificationError_ValidatorInvalid();

    /// @notice Verification error thrown via `PokeError_VerificationFailed` if
    ///         poke included invalid signature.
    error VerificationError_SignatureInvalid();

    //--------------------------------------------------------------------------
    // Events

    /// @notice Emitted when oracle was successfully poked.
    /// @param caller The caller's address.
    /// @param proofURI Optional URI to validity proof.
    event UPoked(address indexed caller, string proofURI);

    /// @notice Emitted when new validator lifted for Schnorr verification.
    /// @param caller The caller's address.
    /// @param validator The validator address lifted.
    event ValidatorLiftedSchnorr(
        address indexed caller, address indexed validator
    );

    /// @notice Emitted when validator dropped from Schnorr verification.
    /// @param caller The caller's address.
    /// @param validator The validator address dropped.
    event ValidatorDroppedSchnorr(
        address indexed caller, address indexed validator
    );

    /// @notice Emitted when bar for Schnorr verification updated.
    /// @param caller The caller's address.
    /// @param oldBar The old bar's value.
    /// @param newBar The new bar's value.
    event BarUpdatedSchnorr(address indexed caller, uint8 oldBar, uint8 newBar);

    /// @notice Emitted when new validator lifted for ECDSA verification.
    /// @param caller The caller's address.
    /// @param validator The validator address lifted.
    event ValidatorLiftedECDSA(
        address indexed caller, address indexed validator
    );

    /// @notice Emitted when validator dropped from ECDSA verification.
    /// @param caller The caller's address.
    /// @param validator The validator address dropped.
    event ValidatorDroppedECDSA(
        address indexed caller, address indexed validator
    );

    /// @notice Emitted when bar for ECDSA verification updated.
    /// @param caller The caller's address.
    /// @param oldBar The old bar's value.
    /// @param newBar The new bar's value.
    event BarUpdatedECDSA(address indexed caller, uint8 oldBar, uint8 newBar);

    //--------------------------------------------------------------------------
    // Poke Functionality

    /// @notice Pokes the oracle using Schnorr verification.
    /// @param uPokeData The UPokeData being poked.
    /// @param schnorrData The SchnorrData proving the `uPokeData`'s integrity.
    function poke(
        UPokeData calldata uPokeData,
        SchnorrData calldata schnorrData
    ) external;

    /// @notice Pokes the oracle using ECDSA verification.
    /// @param uPokeData The UPokeData being poked.
    /// @param ecdsaDatas The list of ECDSAData proving the `uPokeData`'s
    ///                   integrity.
    function poke(UPokeData calldata uPokeData, ECDSAData[] calldata ecdsaDatas)
        external;

    /// @notice Construct a Chronicle Signed Message.
    /// @param scheme The scheme to construct the message for.
    /// @param uPokeData The UPokeData to inlcude in the message.
    function constructChronicleSignedMessage(
        bytes32 scheme,
        UPokeData calldata uPokeData
    ) external view returns (bytes32);

    //--------------------------------------------------------------------------
    // Auth'ed Functionality

    /// @notice Lifts list of public keys `pubKeys` for Schnorr verification.
    /// @dev Only callable by auth'ed address.
    /// @param pubKeys The list of public keys to lift.
    function liftSchnorr(LibSecp256k1.Point[] calldata pubKeys) external;

    /// @notice Drops list of validator ids `ids` from Schnorr verification.
    /// @dev Only callable by auth'ed address.
    /// @param ids The list of validator ids to drop.
    function dropSchnorr(uint8[] calldata ids) external;

    /// @notice Updates the bar security parameter for Schnorr verification.
    /// @dev Only callable by auth'ed address.
    /// @param bar The value to update bar to.
    function setBarSchnorr(uint8 bar) external;

    /// @notice Lifts list of addresses `validators` for ECDSA verification.
    /// @dev Only callable by auth'ed address.
    /// @param validators The list of addresses to lift.
    function liftECDSA(address[] calldata validators) external;

    /// @notice Drops list of validator ids `ids` from ECDSA verification.
    /// @dev Only callable by auth'ed address.
    /// @param ids The list of validator ids to drop.
    function dropECDSA(uint8[] calldata ids) external;

    /// @notice Updates the bar security parameter for ECDSA verification.
    /// @dev Only callable by auth'ed address.
    /// @param bar The value to update bar to.
    function setBarECDSA(uint8 bar) external;

    //--------------------------------------------------------------------------
    // Public View Functions

    /// @notice Returns the oracle's identifier.
    /// @dev The wat is derived from `name()`:
    ///
    ///      ```solidity
    ///      assert(wat() = keccak256(bytes(name())));
    ///      ```
    /// @return bytes32 The oracle's identifier.
    function wat() external view returns (bytes32);

    /// @notice Returns the oracle's name.
    /// @return string The oracle's name.
    function name() external view returns (string memory);

    /// @notice Returns the timestamp of the latest poke.
    /// @dev This timestamp is updated on every poke and allows uniform
    ///      staleness monitoring accross uscribe instances.
    /// @return uint The timestamp of the latest poke.
    function latestPoke() external view returns (uint);

    /// @notice Returns whether address `who` is a validator for Schnorr
    ///         verification.
    /// @param who The address to check.
    /// @return bool True if `who` is a validator for Schnorr verification,
    ///              false otherwise.
    function validatorsSchnorr(address who) external view returns (bool);

    /// @notice Returns whether validator id `id` is a validator for Schnorr
    ///         verification and, if so, the validator's address.
    /// @param id The validator id to check.
    /// @return bool True if `who` is a validator for Schnorr verification,
    ///              false otherwise.
    /// @return address Address of the validator if `id` is a validator for
    ///                 Schnorr verification, zero address otherwise.
    function validatorsSchnorr(uint8 id)
        external
        view
        returns (bool, address);

    /// @notice Returns the lift of validator addresses for Schnorr
    ///         verification.
    /// @return address[] The lift of validator addresses for Schnorr
    ///                   verification.
    function validatorsSchnorr() external view returns (address[] memory);

    /// @notice Returns the bar security parameter for Schnorr verification.
    /// @return uint8 The bar security parameter for Schnorr verification.
    function barSchnorr() external view returns (uint8);

    /// @notice Returns whether address `who` is a validator for ECDSA
    ///         verification.
    /// @param who The address to check.
    /// @return bool True if `who` is a validator for ECDSA verification, false
    ///              otherwise.
    function validatorsECDSA(address who) external view returns (bool);

    /// @notice Returns whether validator id `id` is a validator for ECDSA
    ///         verification and, if so, the validator's address.
    /// @param id The validator id to check.
    /// @return bool True if `who` is a validator for ECDSA verification,
    ///              false otherwise.
    /// @return address Address of the validator if `id` is a validator for
    ///                 ECDSA verification, zero address otherwise.
    function validatorsECDSA(uint id) external view returns (bool, address);

    /// @notice Returns the lift of validator addresses for ECDSA verification.
    /// @return address[] The lift of validator addresses for ECDSA
    ///                   verification.
    function validatorsECDSA() external view returns (address[] memory);

    /// @notice Returns the bar security parameter for ECDSA verification.
    /// @return uint8 The bar security parameter for ECDSA verification.
    function barECDSA() external view returns (uint8);
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

struct UPokeData {
    bytes payload;
    string proofURI;
}

struct SchnorrData {
    bytes32 signature;
    address commitment;
    bytes validatorIds;
}

struct ECDSAData {
    uint8 v;
    bytes32 r;
    bytes32 s;
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.16;

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

///////////////////////////////////////////////////////////////////////////////
//
// Library copied from [email protected]
//
// Reference: https://github.com/chronicleprotocol/scribe/blob/7d2106a265a8d82f259b506c4c8fec42002546ef/src/libs/LibSchnorr.sol
//
///////////////////////////////////////////////////////////////////////////////

/**
 * @title LibSchnorr
 *
 * @notice Custom-purpose library for Schnorr signature verification on the
 *         secp256k1 curve
 */
library LibSchnorr {
    using LibSecp256k1 for LibSecp256k1.Point;

    /// @dev Returns whether `signature` and `commitment` sign via `pubKey`
    ///      message `message`.
    ///
    /// @custom:invariant Reverts iff out of gas.
    /// @custom:invariant Uses constant amount of gas.
    function verifySignature(
        LibSecp256k1.Point memory pubKey,
        bytes32 message,
        bytes32 signature,
        address commitment
    ) internal pure returns (bool) {
        // Return false if signature or commitment is zero.
        if (signature == 0 || commitment == address(0)) {
            return false;
        }

        // Note to enforce pubKey is valid secp256k1 point.
        //
        // While the Scribe contract ensures to only verify signatures for valid
        // public keys, this check is enabled as an additional defense
        // mechanism.
        if (!pubKey.isOnCurve()) {
            return false;
        }

        // Note to enforce signature is less than Q to prevent signature
        // malleability.
        //
        // While the Scribe contract only accepts messages with strictly
        // monotonically increasing timestamps, circumventing replay attack
        // vectors and therefore also signature malleability issues at a higher
        // level, this check is enabled as an additional defense mechanism.
        if (uint(signature) >= LibSecp256k1.Q()) {
            return false;
        }

        // Construct challenge = H(Pₓ ‖ Pₚ ‖ m ‖ Rₑ) mod Q
        uint challenge = uint(
            keccak256(
                abi.encodePacked(
                    pubKey.x, uint8(pubKey.yParity()), message, commitment
                )
            )
        ) % LibSecp256k1.Q();

        // Compute msgHash = -sig * Pₓ      (mod Q)
        //                 = Q - (sig * Pₓ) (mod Q)
        //
        // Unchecked because the only protected operation performed is the
        // subtraction from Q where the subtrahend is the result of a (mod Q)
        // computation, i.e. the subtrahend is guaranteed to be less than Q.
        uint msgHash;
        unchecked {
            msgHash = LibSecp256k1.Q()
                - mulmod(uint(signature), pubKey.x, LibSecp256k1.Q());
        }

        // Compute v = Pₚ + 27
        //
        // Unchecked because pubKey.yParity() ∊ {0, 1} which cannot overflow
        // by adding 27.
        uint v;
        unchecked {
            v = pubKey.yParity() + 27;
        }

        // Set r = Pₓ
        uint r = pubKey.x;

        // Compute s = Q - (e * Pₓ) (mod Q)
        //
        // Unchecked because the only protected operation performed is the
        // subtraction from Q where the subtrahend is the result of a (mod Q)
        // computation, i.e. the subtrahend is guaranteed to be less than Q.
        uint s;
        unchecked {
            s = LibSecp256k1.Q() - mulmod(challenge, pubKey.x, LibSecp256k1.Q());
        }

        // Compute ([s]G - [e]P)ₑ via ecrecover.
        address recovered =
            ecrecover(bytes32(msgHash), uint8(v), bytes32(r), bytes32(s));

        // Verification succeeds iff ([s]G - [e]P)ₑ = Rₑ.
        //
        // Note that commitment is guaranteed to not be zero.
        return commitment == recovered;
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.16;

///////////////////////////////////////////////////////////////////////////////
//
// Library copied from [email protected]
//
// Reference: https://github.com/chronicleprotocol/scribe/blob/7d2106a265a8d82f259b506c4c8fec42002546ef/src/libs/LibSecp256k1.sol
//
///////////////////////////////////////////////////////////////////////////////

/**
 * @title LibSecp256k1
 *
 * @notice Library for secp256k1 elliptic curve computations
 *
 * @dev This library was developed to efficiently compute aggregated public
 *      keys for Schnorr signatures based on secp256k1, i.e. it is _not_ a
 *      general purpose elliptic curve library!
 *
 *      References to the Ethereum Yellow Paper are based on the following
 *      version: "BERLIN VERSION beacfbd – 2022-10-24".
 */
library LibSecp256k1 {
    using LibSecp256k1 for LibSecp256k1.Point;
    using LibSecp256k1 for LibSecp256k1.JacobianPoint;

    uint private constant ADDRESS_MASK =
        0x000000000000000000000000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF;

    // -- Secp256k1 Constants --
    //
    // Taken from https://www.secg.org/sec2-v2.pdf.
    // See section 2.4.1 "Recommended Parameters secp256k1".

    uint private constant _A = 0;
    uint private constant _B = 7;
    uint private constant _P =
        0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F;

    /// @dev Returns the order of the group.
    function Q() internal pure returns (uint) {
        return
            0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141;
    }

    /// @dev Returns the generator G.
    ///      Note that the generator is also called base point.
    function G() internal pure returns (Point memory) {
        return Point({
            x: 0x79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798,
            y: 0x483ada7726a3c4655da4fbfc0e1108a8fd17b448a68554199c47d08ffb10d4b8
        });
    }

    /// @dev Returns the zero point.
    function ZERO_POINT() internal pure returns (Point memory) {
        return Point({x: 0, y: 0});
    }

    // -- (Affine) Point --

    /// @dev Point encapsulates a secp256k1 point in Affine coordinates.
    struct Point {
        uint x;
        uint y;
    }

    /// @dev Returns the Ethereum address of `self`.
    ///
    /// @dev An Ethereum address is defined as the rightmost 160 bits of the
    ///      keccak256 hash of the concatenation of the hex-encoded x and y
    ///      coordinates of the corresponding ECDSA public key.
    ///      See "Appendix F: Signing Transactions" §134 in the Yellow Paper.
    function toAddress(Point memory self) internal pure returns (address) {
        address addr;
        // Functionally equivalent Solidity code:
        // addr = address(uint160(uint(keccak256(abi.encode(self.x, self.y)))));
        assembly ("memory-safe") {
            addr := and(keccak256(self, 0x40), ADDRESS_MASK)
        }
        return addr;
    }

    /// @dev Returns Affine point `self` in Jacobian coordinates.
    function toJacobian(Point memory self)
        internal
        pure
        returns (JacobianPoint memory)
    {
        return JacobianPoint({x: self.x, y: self.y, z: 1});
    }

    /// @dev Returns whether `self` is the zero point.
    function isZeroPoint(Point memory self) internal pure returns (bool) {
        return (self.x | self.y) == 0;
    }

    /// @dev Returns whether `self` is a point on the curve.
    ///
    /// @dev The secp256k1 curve is specified as y² ≡ x³ + ax + b (mod P)
    ///      where:
    ///         a = 0
    ///         b = 7
    function isOnCurve(Point memory self) internal pure returns (bool) {
        uint left = mulmod(self.y, self.y, _P);
        // Note that adding a * x can be waived as ∀x: a * x = 0.
        uint right =
            addmod(mulmod(self.x, mulmod(self.x, self.x, _P), _P), _B, _P);

        return left == right;
    }

    /// @dev Returns the parity of `self`'s y coordinate.
    ///
    /// @dev The value 0 represents an even y value and 1 represents an odd y
    ///      value.
    ///      See "Appendix F: Signing Transactions" in the Yellow Paper.
    function yParity(Point memory self) internal pure returns (uint) {
        return self.y & 1;
    }

    // -- Jacobian Point --

    /// @dev JacobianPoint encapsulates a secp256k1 point in Jacobian
    ///      coordinates.
    struct JacobianPoint {
        uint x;
        uint y;
        uint z;
    }

    /// @dev Returns Jacobian point `self` in Affine coordinates.
    ///
    /// @custom:invariant Reverts iff out of gas.
    /// @custom:invariant Does not run into an infinite loop.
    function toAffine(JacobianPoint memory self)
        internal
        pure
        returns (Point memory)
    {
        Point memory result;

        // Compute z⁻¹, i.e. the modular inverse of self.z.
        uint zInv = _invMod(self.z);

        // Compute (z⁻¹)² (mod P)
        uint zInv_2 = mulmod(zInv, zInv, _P);

        // Compute self.x * (z⁻¹)² (mod P), i.e. the x coordinate of given
        // Jacobian point in Affine representation.
        result.x = mulmod(self.x, zInv_2, _P);

        // Compute self.y * (z⁻¹)³ (mod P), i.e. the y coordinate of given
        // Jacobian point in Affine representation.
        result.y = mulmod(self.y, mulmod(zInv, zInv_2, _P), _P);

        return result;
    }

    /// @dev Adds Affine point `p` to Jacobian point `self`.
    ///
    ///      It is the caller's responsibility to ensure given points are on the
    ///      curve!
    ///
    ///      Computation based on: https://www.hyperelliptic.org/EFD/g1p/auto-shortw-jacobian.html#addition-madd-2007-bl.
    ///
    ///      Note that the formula assumes z2 = 1, which always holds if z2's
    ///      point is given in Affine coordinates.
    ///
    ///      Note that eventhough the function is marked as pure, to be
    ///      understood as only being dependent on the input arguments, it
    ///      nevertheless has side effects by writing the result into the
    ///      `self` memory variable.
    ///
    /// @custom:invariant Only mutates `self` memory variable.
    /// @custom:invariant Reverts iff out of gas.
    /// @custom:invariant Uses constant amount of gas.
    function addAffinePoint(JacobianPoint memory self, Point memory p)
        internal
        pure
    {
        // Addition formula:
        //      x = r² - j - (2 * v)             (mod P)
        //      y = (r * (v - x)) - (2 * y1 * j) (mod P)
        //      z = (z1 + h)² - z1² - h²         (mod P)
        //
        // where:
        //      r = 2 * (s - y1) (mod P)
        //      j = h * i        (mod P)
        //      v = x1 * i       (mod P)
        //      h = u - x1       (mod P)
        //      s = y2 * z1³     (mod P)       Called s2 in reference
        //      i = 4 * h²       (mod P)
        //      u = x2 * z1²     (mod P)       Called u2 in reference
        //
        // and:
        //      x1 = self.x
        //      y1 = self.y
        //      z1 = self.z
        //      x2 = p.x
        //      y2 = p.y
        //
        // Note that in order to save memory allocations the result is stored
        // in the self variable, i.e. the following holds true after the
        // functions execution:
        //      x = self.x
        //      y = self.y
        //      z = self.z

        // Cache self's coordinates on stack.
        uint x1 = self.x;
        uint y1 = self.y;
        uint z1 = self.z;

        // Compute z1_2 = z1²     (mod P)
        //              = z1 * z1 (mod P)
        uint z1_2 = mulmod(z1, z1, _P);

        // Compute h = u        - x1       (mod P)
        //           = u        + (P - x1) (mod P)
        //           = x2 * z1² + (P - x1) (mod P)
        //
        // Unchecked because the only protected operation performed is P - x1
        // where x1 is guaranteed by the caller to be an x coordinate belonging
        // to a point on the curve, i.e. being less than P.
        uint h;
        unchecked {
            h = addmod(mulmod(p.x, z1_2, _P), _P - x1, _P);
        }

        // Compute h_2 = h²    (mod P)
        //             = h * h (mod P)
        uint h_2 = mulmod(h, h, _P);

        // Compute i = 4 * h² (mod P)
        uint i = mulmod(4, h_2, _P);

        // Compute z = (z1 + h)² - z1²       - h²       (mod P)
        //           = (z1 + h)² - z1²       + (P - h²) (mod P)
        //           = (z1 + h)² + (P - z1²) + (P - h²) (mod P)
        //             ╰───────╯   ╰───────╯   ╰──────╯
        //               left         mid       right
        //
        // Unchecked because the only protected operations performed are
        // subtractions from P where the subtrahend is the result of a (mod P)
        // computation, i.e. the subtrahend being guaranteed to be less than P.
        unchecked {
            uint left = mulmod(addmod(z1, h, _P), addmod(z1, h, _P), _P);
            uint mid = _P - z1_2;
            uint right = _P - h_2;

            self.z = addmod(left, addmod(mid, right, _P), _P);
        }

        // Compute v = x1 * i (mod P)
        uint v = mulmod(x1, i, _P);

        // Compute j = h * i (mod P)
        uint j = mulmod(h, i, _P);

        // Compute r = 2 * (s               - y1)       (mod P)
        //           = 2 * (s               + (P - y1)) (mod P)
        //           = 2 * ((y2 * z1³)      + (P - y1)) (mod P)
        //           = 2 * ((y2 * z1² * z1) + (P - y1)) (mod P)
        //
        // Unchecked because the only protected operation performed is P - y1
        // where y1 is guaranteed by the caller to be an y coordinate belonging
        // to a point on the curve, i.e. being less than P.
        uint r;
        unchecked {
            r = mulmod(
                2,
                addmod(mulmod(p.y, mulmod(z1_2, z1, _P), _P), _P - y1, _P),
                _P
            );
        }

        // Compute x = r² - j - (2 * v)             (mod P)
        //           = r² - j + (P - (2 * v))       (mod P)
        //           = r² + (P - j) + (P - (2 * v)) (mod P)
        //                  ╰─────╯   ╰───────────╯
        //                    mid         right
        //
        // Unchecked because the only protected operations performed are
        // subtractions from P where the subtrahend is the result of a (mod P)
        // computation, i.e. the subtrahend being guaranteed to be less than P.
        unchecked {
            uint r_2 = mulmod(r, r, _P);
            uint mid = _P - j;
            uint right = _P - mulmod(2, v, _P);

            self.x = addmod(r_2, addmod(mid, right, _P), _P);
        }

        // Compute y = (r * (v - x))       - (2 * y1 * j)       (mod P)
        //           = (r * (v - x))       + (P - (2 * y1 * j)) (mod P)
        //           = (r * (v + (P - x))) + (P - (2 * y1 * j)) (mod P)
        //             ╰─────────────────╯   ╰────────────────╯
        //                    left                 right
        //
        // Unchecked because the only protected operations performed are
        // subtractions from P where the subtrahend is the result of a (mod P)
        // computation, i.e. the subtrahend being guaranteed to be less than P.
        unchecked {
            uint left = mulmod(r, addmod(v, _P - self.x, _P), _P);
            uint right = _P - mulmod(2, mulmod(y1, j, _P), _P);

            self.y = addmod(left, right, _P);
        }
    }

    // -- Private Helpers --

    /// @dev Returns the modular inverse of `x` for modulo `_P`.
    ///
    ///      It is the caller's responsibility to ensure `x` is less than `_P`!
    ///
    ///      The modular inverse of `x` is x⁻¹ such that x * x⁻¹ ≡ 1 (mod P).
    ///
    /// @dev Modified from Jordi Baylina's [ecsol](https://github.com/jbaylina/ecsol/blob/c2256afad126b7500e6f879a9369b100e47d435d/ec.sol#L51-L67).
    ///
    /// @custom:invariant Reverts iff out of gas.
    /// @custom:invariant Does not run into an infinite loop.
    function _invMod(uint x) private pure returns (uint) {
        uint t;
        uint q;
        uint newT = 1;
        uint r = _P;

        assembly ("memory-safe") {
            // Implemented in assembly to circumvent division-by-zero
            // and over-/underflow protection.
            //
            // Functionally equivalent Solidity code:
            //      while (x != 0) {
            //          q = r / x;
            //          (t, newT) = (newT, addmod(t, (_P - mulmod(q, newT, _P)), _P));
            //          (r, x) = (x, r - (q * x));
            //      }
            //
            // For the division r / x, x is guaranteed to not be zero via the
            // loop condition.
            //
            // The subtraction of form P - mulmod(_, _, P) is guaranteed to not
            // underflow due to the subtrahend being a (mod P) result,
            // i.e. the subtrahend being guaranteed to be less than P.
            //
            // The subterm q * x is guaranteed to not overflow because
            // q * x ≤ r due to q = ⎣r / x⎦.
            //
            // The term r - (q * x) is guaranteed to not underflow because
            // q * x ≤ r and therefore r - (q * x) ≥ 0.
            for {} x {} {
                q := div(r, x)

                let tmp := t
                t := newT
                newT := addmod(tmp, sub(_P, mulmod(q, newT, _P)), _P)

                tmp := r
                r := x
                x := sub(tmp, mul(q, x))
            }
        }

        return t;
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.16;

interface IAuth {
    /// @notice Thrown by protected function if caller not auth'ed.
    /// @param caller The caller's address.
    error NotAuthorized(address caller);

    /// @notice Emitted when auth granted to address.
    /// @param caller The caller's address.
    /// @param who The address auth got granted to.
    event AuthGranted(address indexed caller, address indexed who);

    /// @notice Emitted when auth renounced from address.
    /// @param caller The caller's address.
    /// @param who The address auth got renounced from.
    event AuthRenounced(address indexed caller, address indexed who);

    /// @notice Grants address `who` auth.
    /// @dev Only callable by auth'ed address.
    /// @param who The address to grant auth.
    function rely(address who) external;

    /// @notice Renounces address `who`'s auth.
    /// @dev Only callable by auth'ed address.
    /// @param who The address to renounce auth.
    function deny(address who) external;

    /// @notice Returns whether address `who` is auth'ed.
    /// @param who The address to check.
    /// @return True if `who` is auth'ed, false otherwise.
    function authed(address who) external view returns (bool);

    /// @notice Returns full list of addresses granted auth.
    /// @dev May contain duplicates.
    /// @return List of addresses granted auth.
    function authed() external view returns (address[] memory);

    /// @notice Returns whether address `who` is auth'ed.
    /// @custom:deprecated Use `authed(address)(bool)` instead.
    /// @param who The address to check.
    /// @return 1 if `who` is auth'ed, 0 otherwise.
    function wards(address who) external view returns (uint);
}