Cryo Explorer Ethereum Mainnet

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

import {ITypeAndVersion} from "../shared/interfaces/ITypeAndVersion.sol";

import {Ownable2StepMsgSender} from "../shared/access/Ownable2StepMsgSender.sol";

import {Strings} from "../vendor/openzeppelin-solidity/v5.0.2/contracts/utils/Strings.sol";
import {EnumerableSet} from "../vendor/openzeppelin-solidity/v5.0.2/contracts/utils/structs/EnumerableSet.sol";

contract WorkflowRegistry is Ownable2StepMsgSender, ITypeAndVersion {
  using EnumerableSet for EnumerableSet.Bytes32Set;
  using EnumerableSet for EnumerableSet.AddressSet;
  using EnumerableSet for EnumerableSet.UintSet;

  string public constant override typeAndVersion = "WorkflowRegistry 1.0.0";
  uint8 private constant MAX_WORKFLOW_NAME_LENGTH = 64;
  uint8 private constant MAX_URL_LENGTH = 200;
  uint8 private constant MAX_PAGINATION_LIMIT = 100;

  enum WorkflowStatus {
    ACTIVE,
    PAUSED
  }

  struct WorkflowMetadata {
    bytes32 workflowID; //     Unique identifier from hash of owner address, WASM binary content, config content and secrets URL.
    address owner; // ─────────╮ Workflow owner.
    uint32 donID; //           │ Unique identifier for the Workflow DON.
    WorkflowStatus status; // ─╯ Current status of the workflow (active, paused).
    string workflowName; //    Human readable string capped at 64 characters length.
    string binaryURL; //       URL to the WASM binary.
    string configURL; //       URL to the config.
    string secretsURL; //      URL to the encrypted secrets. Workflow DON applies a default refresh period (e.g. daily).
  }

  /// @dev Maps an owner address to a set of their workflow (name + owner) hashess.
  mapping(address owner => EnumerableSet.Bytes32Set workflowKeys) private s_ownerWorkflowKeys;
  /// @dev Maps a DON ID to a set of workflow IDs.
  mapping(uint32 donID => EnumerableSet.Bytes32Set workflowKeys) private s_donWorkflowKeys;
  /// @dev Maps a workflow (name + owner) hash to its corresponding workflow metadata.
  mapping(bytes32 workflowKey => WorkflowMetadata workflowMetadata) private s_workflows;
  /// @dev Mapping to track workflows by secretsURL hash (owner + secretsURL).
  /// This is used to find all workflows that have the same secretsURL when a force secrets update event is requested.
  mapping(bytes32 secretsURLHash => EnumerableSet.Bytes32Set workflowKeys) private s_secretsHashToWorkflows;
  /// @dev Keep track of all workflowIDs to ensure uniqueness.
  mapping(bytes32 workflowID => bool inUse) private s_workflowIDs;

  /// @dev List of all authorized EOAs/contracts allowed to access this contract's state functions. All view functions are open access.
  EnumerableSet.AddressSet private s_authorizedAddresses;
  /// @dev List of all authorized DON IDs.
  EnumerableSet.UintSet private s_allowedDONs;

  bool private s_registryLocked = false;

  event AllowedDONsUpdatedV1(uint32[] donIDs, bool allowed);
  event AuthorizedAddressesUpdatedV1(address[] addresses, bool allowed);
  event WorkflowRegisteredV1(
    bytes32 indexed workflowID,
    address indexed workflowOwner,
    uint32 indexed donID,
    WorkflowStatus status,
    string workflowName,
    string binaryURL,
    string configURL,
    string secretsURL
  );
  event WorkflowUpdatedV1(
    bytes32 indexed oldWorkflowID,
    address indexed workflowOwner,
    uint32 indexed donID,
    bytes32 newWorkflowID,
    string workflowName,
    string binaryURL,
    string configURL,
    string secretsURL
  );
  event WorkflowPausedV1(
    bytes32 indexed workflowID, address indexed workflowOwner, uint32 indexed donID, string workflowName
  );
  event WorkflowActivatedV1(
    bytes32 indexed workflowID, address indexed workflowOwner, uint32 indexed donID, string workflowName
  );
  event WorkflowDeletedV1(
    bytes32 indexed workflowID, address indexed workflowOwner, uint32 indexed donID, string workflowName
  );
  event WorkflowForceUpdateSecretsRequestedV1(address indexed owner, bytes32 secretsURLHash, string workflowName);
  event RegistryLockedV1(address lockedBy);
  event RegistryUnlockedV1(address unlockedBy);

  error AddressNotAuthorized(address caller);
  error BinaryURLRequired();
  error CallerIsNotWorkflowOwner(address caller);
  error DONNotAllowed(uint32 donID);
  error InvalidWorkflowID();
  error RegistryLocked();
  error URLTooLong(uint256 providedLength, uint8 maxAllowedLength);
  error WorkflowAlreadyInDesiredStatus();
  error WorkflowAlreadyRegistered();
  error WorkflowContentNotUpdated();
  error WorkflowDoesNotExist();
  error WorkflowIDAlreadyExists();
  error WorkflowNameRequired();
  error WorkflowNameTooLong(uint256 providedLength, uint8 maxAllowedLength);

  modifier registryNotLocked() {
    if (s_registryLocked) revert RegistryLocked();
    _;
  }

  // ================================================================
  // |                            Admin                             |
  // ================================================================

  /// @notice Updates the list of allowed DON IDs.
  /// @dev If a DON ID with associated workflows is removed from the allowed DONs list, the only allowed actions on
  /// workflows for that DON are to pause or delete them. It will no longer be possible to update, activate, or register
  /// new workflows for a removed DON.
  /// @param donIDs The list of unique identifiers for Workflow DONs.
  /// @param allowed True if they should be added to the allowlist, false to remove them.
  function updateAllowedDONs(uint32[] calldata donIDs, bool allowed) external onlyOwner registryNotLocked {
    uint256 length = donIDs.length;
    if (allowed) {
      for (uint256 i = 0; i < length; ++i) {
        s_allowedDONs.add(donIDs[i]);
      }
    } else {
      for (uint256 i = 0; i < length; ++i) {
        s_allowedDONs.remove(donIDs[i]);
      }
    }

    emit AllowedDONsUpdatedV1(donIDs, allowed);
  }

  /// @notice Updates a list of authorized addresses that can register workflows.
  /// @dev We don't check if an existing authorized address will be set to false, please take extra caution.
  /// @param addresses The list of addresses.
  /// @param allowed True if they should be added to whitelist, false to remove them.
  function updateAuthorizedAddresses(address[] calldata addresses, bool allowed) external onlyOwner registryNotLocked {
    uint256 length = addresses.length;
    if (allowed) {
      for (uint256 i = 0; i < length; ++i) {
        s_authorizedAddresses.add(addresses[i]);
      }
    } else {
      for (uint256 i = 0; i < length; ++i) {
        s_authorizedAddresses.remove(addresses[i]);
      }
    }

    emit AuthorizedAddressesUpdatedV1(addresses, allowed);
  }

  /// @notice Locks the registry, preventing any further modifications.
  /// @dev This function can only be called by the owner of the contract. Once locked, the registry cannot be modified
  /// until it is unlocked by calling `unlockRegistry`. Emits a `RegistryLockedV1` event.
  function lockRegistry() external onlyOwner {
    s_registryLocked = true;
    emit RegistryLockedV1(msg.sender);
  }

  /// @notice Unlocks the registry, allowing modifications to be made.
  /// @dev This function can only be called by the owner of the contract. Once unlocked, the registry can be modified
  /// again. Emits a `RegistryUnlockedV1` event.
  function unlockRegistry() external onlyOwner {
    s_registryLocked = false;
    emit RegistryUnlockedV1(msg.sender);
  }

  // ================================================================
  // |                       Workflow Management                    |
  // ================================================================

  /// @notice Registers a new workflow.
  /// @dev Registers a new workflow after validating the caller, DON ID, workflow name, and workflow metadata.
  /// This function performs the following steps:
  /// - Validates the caller is authorized and the DON ID is allowed.
  /// - Validates the workflow metadata (workflowID, binaryURL, configURL, secretsURL) lengths.
  /// - Checks if the workflow with the given name already exists for the owner.
  /// - Stores the workflow metadata in the appropriate mappings for the owner and DON.
  /// - Adds the secretsURL to the hash mapping if present.
  ///
  /// Requirements:
  /// - Caller must be an authorized address.
  /// - The provided DON ID must be allowed.
  /// - The workflow name must not exceed `MAX_WORKFLOW_NAME_LENGTH`.
  /// - Workflow metadata must be valid and adhere to set requirements.
  /// - Workflow with the given name must not already exist for the owner.
  ///
  /// Emits:
  /// - `WorkflowRegisteredV1` event upon successful registration.
  ///
  /// @param workflowName The human-readable name for the workflow. Must not exceed 64 characters.
  /// @param workflowID The unique identifier for the workflow based on the WASM binary content, config content and
  /// secrets URL.
  /// @param donID The unique identifier of the Workflow DON that this workflow is associated with.
  /// @param status Initial status for this workflow after registration (e.g., Active or Paused).
  /// @param binaryURL The URL pointing to the WASM binary for the workflow.
  /// @param configURL The URL pointing to the configuration file for the workflow.
  /// @param secretsURL The URL pointing to the secrets file for the workflow. Can be empty if there are no secrets.
  function registerWorkflow(
    string calldata workflowName,
    bytes32 workflowID,
    uint32 donID,
    WorkflowStatus status,
    string calldata binaryURL,
    string calldata configURL,
    string calldata secretsURL
  ) external registryNotLocked {
    _validatePermissions(donID, msg.sender);
    _validateWorkflowName(bytes(workflowName).length);
    _validateWorkflowURLs(bytes(binaryURL).length, bytes(configURL).length, bytes(secretsURL).length);

    bytes32 workflowKey = computeHashKey(msg.sender, workflowName);
    if (s_workflows[workflowKey].owner != address(0)) {
      revert WorkflowAlreadyRegistered();
    }

    _requireUniqueWorkflowID(workflowID);

    // Create new workflow entry
    s_workflows[workflowKey] = WorkflowMetadata({
      workflowID: workflowID,
      owner: msg.sender,
      donID: donID,
      status: status,
      workflowName: workflowName,
      binaryURL: binaryURL,
      configURL: configURL,
      secretsURL: secretsURL
    });

    s_ownerWorkflowKeys[msg.sender].add(workflowKey);
    s_donWorkflowKeys[donID].add(workflowKey);

    // Hash the secretsURL and add the workflow to the secrets hash mapping
    if (bytes(secretsURL).length > 0) {
      bytes32 secretsHash = computeHashKey(msg.sender, secretsURL);
      s_secretsHashToWorkflows[secretsHash].add(workflowKey);
    }

    emit WorkflowRegisteredV1(workflowID, msg.sender, donID, status, workflowName, binaryURL, configURL, secretsURL);
  }

  /// @notice Updates the workflow metadata for a given workflow.
  /// @dev Updates the workflow metadata based on the provided parameters.
  /// - If a field needs to be updated, the new value should be provided.
  /// - If the value should remain unchanged, provide the same value as before.
  /// - To remove an optional field (such as `configURL` or `secretsURL`), pass an empty string ("").
  /// - To get the workflowKey, use `computeHashKey` with the workflow owner's address and the workflow name, or
  ///   perform an offchain equivalent of keccak256(abi.encodePacked(owner, workflowName)).
  ///
  /// This function performs the following steps:
  /// - Validates the provided workflow metadata.
  /// - Retrieves the workflow by the caller's address and `workflowName`.
  /// - Updates only the fields that have changed.
  /// - Ensures that the workflow ID (`newWorkflowID`) must change and at least one of the URLs must also change.
  /// - Updates the `secretsURL` hash mappings if the `secretsURL` changes.
  ///
  /// Requirements:
  /// - `binaryURL` must always be provided, as it is required.
  /// - If only one field is being updated, the other fields must be provided with their current values to keep them unchanged, otherwise
  ///   they will be treated as empty strings.
  /// - The DON ID must be in the allowed list to perform updates.
  /// - The caller must be an authorized address. This means that even if the caller is the owner of the workflow, if they were later
  ///   removed from the authorized addresses list, they will not be able to perform updates.
  ///
  /// Emits:
  /// - `WorkflowUpdatedV1` event indicating the workflow has been successfully updated.
  ///
  /// @param workflowKey The unique identifier for the workflow.
  /// @param newWorkflowID The rehashed unique identifier for the workflow.
  /// @param binaryURL The URL pointing to the WASM binary. Must always be provided.
  /// @param configURL The URL pointing to the configuration file. Provide an empty string ("") to remove it.
  /// @param secretsURL The URL pointing to the secrets file. Provide an empty string ("") to remove it.
  function updateWorkflow(
    bytes32 workflowKey,
    bytes32 newWorkflowID,
    string calldata binaryURL,
    string calldata configURL,
    string calldata secretsURL
  ) external registryNotLocked {
    _validateWorkflowURLs(bytes(binaryURL).length, bytes(configURL).length, bytes(secretsURL).length);

    WorkflowMetadata storage workflow = _getWorkflowFromStorage(msg.sender, workflowKey);

    uint32 donID = workflow.donID;
    _validatePermissions(donID, msg.sender);

    // Store the old workflowID for event emission.
    bytes32 currentWorkflowID = workflow.workflowID;

    // Determine which URLs have changed
    bool sameBinaryURL = Strings.equal(workflow.binaryURL, binaryURL);
    bool sameConfigURL = Strings.equal(workflow.configURL, configURL);
    bool sameSecretsURL = Strings.equal(workflow.secretsURL, secretsURL);
    if (sameBinaryURL && sameConfigURL && sameSecretsURL) {
      revert WorkflowContentNotUpdated();
    }

    // Ensure the new workflowID is unique
    _requireUniqueWorkflowID(newWorkflowID);

    // Free the old workflowID
    s_workflowIDs[currentWorkflowID] = false;

    // Update all fields that have changed and the relevant sets
    workflow.workflowID = newWorkflowID;
    if (!sameBinaryURL) {
      workflow.binaryURL = binaryURL;
    }
    if (!sameConfigURL) {
      workflow.configURL = configURL;
    }
    if (!sameSecretsURL) {
      // Remove the old secrets hash if secretsURL is not empty
      if (bytes(workflow.secretsURL).length > 0) {
        // Using keccak256 instead of computeHashKey as currentSecretsURL is memory
        bytes32 oldSecretsHash = keccak256(abi.encodePacked(msg.sender, workflow.secretsURL));
        s_secretsHashToWorkflows[oldSecretsHash].remove(workflowKey);
      }

      workflow.secretsURL = secretsURL;

      // Add the new secrets hash if secretsURL is not empty
      if (bytes(secretsURL).length > 0) {
        bytes32 newSecretsHash = computeHashKey(msg.sender, secretsURL);
        s_secretsHashToWorkflows[newSecretsHash].add(workflowKey);
      }
    }

    // Emit an event after updating the workflow
    emit WorkflowUpdatedV1(
      currentWorkflowID, msg.sender, donID, newWorkflowID, workflow.workflowName, binaryURL, configURL, secretsURL
    );
  }

  /// @notice Pauses an existing workflow.
  /// @dev Workflows with any DON ID can be paused. If a caller was later removed from the authorized addresses list,
  /// they will still be able to pause the workflow.
  ///
  /// To get the workflowKey, use `computeHashKey` with the workflow owner's address and the workflow name, or perform
  /// an offchain equivalent of `keccak256(abi.encodePacked(owner, workflowName))`.
  /// @param workflowKey The unique identifier for the workflow.
  function pauseWorkflow(
    bytes32 workflowKey
  ) external registryNotLocked {
    _updateWorkflowStatus(workflowKey, WorkflowStatus.PAUSED);
  }

  /// @notice Activates an existing workflow.
  /// @dev The DON ID for the workflow must be in the allowed list to perform this action. The caller must also be an
  /// authorized address. This means that even if the caller is the owner of the workflow, if they were later removed
  /// from the authorized addresses list, they will not be able to activate the workflow.
  ///
  /// To get the workflowKey, use `computeHashKey` with the workflow owner's address and the workflow name, or perform
  /// an offchain equivalent of `keccak256(abi.encodePacked(owner, workflowName))`.
  /// @param workflowKey The unique identifier for the workflow.
  function activateWorkflow(
    bytes32 workflowKey
  ) external registryNotLocked {
    _updateWorkflowStatus(workflowKey, WorkflowStatus.ACTIVE);
  }

  /// @notice Deletes an existing workflow, removing it from the contract storage.
  /// @dev This function permanently removes a workflow associated with the caller's address.
  /// - Workflows with any DON ID can be deleted.
  /// - The caller must also be an authorized address. This means that even if the caller is the owner of the workflow,
  ///   if they were later removed from the authorized addresses list, they will not be able to delete the workflow.
  /// - To get the workflowKey, use `computeHashKey` with the workflow owner's address and the workflow name, or
  ///   perform an offchain equivalent of `keccak256(abi.encodePacked(owner, workflowName))`.
  ///
  /// The function performs the following operations:
  /// - Retrieves the workflow metadata using the workflow name and owner address.
  /// - Ensures that only the owner of the workflow can perform this operation.
  /// - Deletes the workflow from the `s_workflows` mapping.
  /// - Removes the workflow from associated sets (`s_ownerWorkflowKeys`, `s_donWorkflowKeys`, and
  ///   `s_secretsHashToWorkflows`).
  ///
  /// Requirements:
  /// - The caller must be the owner of the workflow and an authorized address.
  ///
  /// Emits:
  /// - `WorkflowDeletedV1` event indicating that the workflow has been deleted successfully.
  ///
  /// @param workflowKey The unique identifier for the workflow.
  function deleteWorkflow(
    bytes32 workflowKey
  ) external registryNotLocked {
    // Retrieve workflow metadata from storage
    WorkflowMetadata storage workflow = _getWorkflowFromStorage(msg.sender, workflowKey);

    // Only checking access for the caller instead of using _validatePermissions so that even if the DON was removed from the
    // allowed list, the workflow can still be deleted.
    if (!s_authorizedAddresses.contains(msg.sender)) {
      revert AddressNotAuthorized(msg.sender);
    }

    // Release the workflowID for reuse
    s_workflowIDs[workflow.workflowID] = false;

    // Remove the workflow from the owner and DON mappings
    s_ownerWorkflowKeys[msg.sender].remove(workflowKey);
    s_donWorkflowKeys[workflow.donID].remove(workflowKey);

    // Remove the workflow from the secrets hash set if secretsURL is not empty
    if (bytes(workflow.secretsURL).length > 0) {
      // Using keccak256 instead of computeHashKey as secretsURL is storage ref
      bytes32 secretsHash = keccak256(abi.encodePacked(msg.sender, workflow.secretsURL));
      s_secretsHashToWorkflows[secretsHash].remove(workflowKey);
    }

    // Emit an event indicating the workflow has been deleted. We need to do this before deleting the workflow from storage.
    emit WorkflowDeletedV1(workflow.workflowID, msg.sender, workflow.donID, workflow.workflowName);

    // Delete the workflow metadata from storage
    delete s_workflows[workflowKey];
  }

  /// @notice Requests a force update for workflows that share the same secrets URL.
  /// @dev This function allows an owner to request a force update for all workflows that share a given `secretsURL`.
  /// The `secretsURL` can be shared between multiple workflows, but they must all belong to the same owner. This
  /// function ensures that the caller owns all workflows associated with the given `secretsURL`.
  /// If you need to compare the `secretsHash` outside the contract, use `computeHashKey` with the owner's address and
  /// the `secretsURL` string passed into this function.
  ///
  /// The function performs the following steps:
  /// - Hashes the provided `secretsURL` and `msg.sender` to generate a unique mapping key.
  /// - Retrieves all workflows associated with the given secrets hash.
  /// - Collects the names of all matching workflows and emits an event indicating a force update request.
  ///
  /// Requirements:
  /// - The caller must be the owner of all workflows that share the given `secretsURL`.
  ///
  /// Emits:
  /// - `WorkflowForceUpdateSecretsRequestedV1` event indicating that a force update for workflows using this
  /// `secretsURL` has been requested.
  /// @param secretsURL The URL pointing to the updated secrets file. This can be shared among multiple workflows.
  function requestForceUpdateSecrets(
    string calldata secretsURL
  ) external registryNotLocked {
    // Use secretsURL and sender hash key to get the mapping key
    bytes32 secretsHash = computeHashKey(msg.sender, secretsURL);

    // Retrieve all workflow keys associated with the given secrets hash
    EnumerableSet.Bytes32Set storage workflowKeys = s_secretsHashToWorkflows[secretsHash];
    uint256 matchCount = workflowKeys.length();

    // No workflows found with the provided secretsURL
    if (matchCount == 0) {
      revert WorkflowDoesNotExist();
    }

    // Iterate through matched workflows and emit events for accessible ones
    for (uint256 i = 0; i < matchCount; ++i) {
      bytes32 workflowKey = workflowKeys.at(i);
      WorkflowMetadata storage workflow = s_workflows[workflowKey];

      if (s_allowedDONs.contains(workflow.donID) && s_authorizedAddresses.contains(msg.sender)) {
        emit WorkflowForceUpdateSecretsRequestedV1(msg.sender, secretsHash, workflow.workflowName);
      }
    }
  }

  /// @dev Internal function to update the workflow status.
  ///
  /// This function is used to change the status of an existing workflow, either to "Paused" or "Active".
  ///
  /// The function performs the following operations:
  /// - Retrieves the workflow metadata from storage based on the workflow name.
  /// - Only the owner of the workflow can update the status.
  /// - Checks if the workflow is already in the desired status, and reverts if no change is necessary to avoid
  ///   unnecessary storage writes.
  /// - Updates the status of the workflow and emits the appropriate event (`WorkflowPausedV1` or
  ///   `WorkflowActivatedV1`).
  ///
  /// Emits:
  /// - `WorkflowPausedV1` or `WorkflowActivatedV1` event indicating that the relevant workflow status has been updated.
  /// @param workflowKey The unique identifier for the workflow.
  /// @param newStatus The new status to set for the workflow (either `Paused` or `Active`).
  function _updateWorkflowStatus(bytes32 workflowKey, WorkflowStatus newStatus) internal {
    // Retrieve workflow metadata once
    WorkflowMetadata storage workflow = _getWorkflowFromStorage(msg.sender, workflowKey);
    uint32 donID = workflow.donID;

    // Avoid unnecessary storage writes if already in the desired status
    if (workflow.status == newStatus) {
      revert WorkflowAlreadyInDesiredStatus();
    }

    // Emit the appropriate event based on newStatus
    if (newStatus == WorkflowStatus.ACTIVE) {
      _validatePermissions(donID, msg.sender);
      emit WorkflowActivatedV1(workflow.workflowID, msg.sender, donID, workflow.workflowName);
    } else if (newStatus == WorkflowStatus.PAUSED) {
      emit WorkflowPausedV1(workflow.workflowID, msg.sender, donID, workflow.workflowName);
    }

    // Update the workflow status
    workflow.status = newStatus;
  }

  /// @dev Internal function to retrieve a workflow from storage.
  /// @param sender The address of the caller. Must be the owner of the workflow.
  /// @param workflowKey The unique identifier for the workflow.
  /// @return workflow The workflow metadata.
  function _getWorkflowFromStorage(
    address sender,
    bytes32 workflowKey
  ) internal view returns (WorkflowMetadata storage workflow) {
    workflow = s_workflows[workflowKey];

    if (workflow.owner == address(0)) revert WorkflowDoesNotExist();
    if (workflow.owner != sender) revert CallerIsNotWorkflowOwner(sender);

    return workflow;
  }

  /// @notice Ensures the given workflowID is unique and marks it as used.
  /// @param workflowID The workflowID to validate and consume.
  function _requireUniqueWorkflowID(
    bytes32 workflowID
  ) internal {
    if (workflowID == bytes32(0)) revert InvalidWorkflowID();

    if (s_workflowIDs[workflowID]) {
      revert WorkflowIDAlreadyExists();
    }

    s_workflowIDs[workflowID] = true;
  }

  // ================================================================
  // |                       Workflow Queries                       |
  // ================================================================

  /// @notice Returns workflow metadata.
  /// @param workflowOwner Address that owns this workflow.
  /// @param workflowName The human-readable name for the workflow.
  /// @return WorkflowMetadata The metadata of the workflow.
  function getWorkflowMetadata(
    address workflowOwner,
    string calldata workflowName
  ) external view returns (WorkflowMetadata memory) {
    bytes32 workflowKey = computeHashKey(workflowOwner, workflowName);
    WorkflowMetadata storage workflow = s_workflows[workflowKey];

    if (workflow.owner == address(0)) revert WorkflowDoesNotExist();

    return workflow;
  }

  /// @notice Retrieves a list of workflow metadata for a specific owner.
  /// @dev This function allows paginated retrieval of workflows owned by a particular address. If the `limit` is set
  /// to 0 or exceeds the `MAX_PAGINATION_LIMIT`, the `MAX_PAGINATION_LIMIT` will be used instead in both cases.
  /// @param workflowOwner The address of the workflow owner for whom the workflow metadata is being retrieved.
  /// @param start The index at which to start retrieving workflows (zero-based index). If the start index is greater
  /// than or equal to the total number of workflows, an empty array is returned.
  /// @param limit The maximum number of workflow metadata entries to retrieve. If the limit exceeds the available
  /// number of workflows from the start index, only the available entries are returned.
  /// @return workflowMetadataList An array of `WorkflowMetadata` structs containing metadata of workflows owned by
  /// the specified owner.
  function getWorkflowMetadataListByOwner(
    address workflowOwner,
    uint256 start,
    uint256 limit
  ) external view returns (WorkflowMetadata[] memory workflowMetadataList) {
    uint256 totalWorkflows = s_ownerWorkflowKeys[workflowOwner].length();
    if (start >= totalWorkflows) {
      return new WorkflowMetadata[](0);
    }

    if (limit > MAX_PAGINATION_LIMIT || limit == 0) {
      limit = MAX_PAGINATION_LIMIT;
    }

    uint256 end = (start + limit > totalWorkflows) ? totalWorkflows : start + limit;

    uint256 resultLength = end - start;
    workflowMetadataList = new WorkflowMetadata[](resultLength);

    for (uint256 i = 0; i < resultLength; ++i) {
      bytes32 workflowKey = s_ownerWorkflowKeys[workflowOwner].at(start + i);
      workflowMetadataList[i] = s_workflows[workflowKey];
    }

    return workflowMetadataList;
  }

  /// @notice Retrieves a list of workflow metadata for a specific DON ID.
  /// @dev This function allows paginated retrieval of workflows associated with a particular DON. If the `limit` is
  /// set to 0 or exceeds the `MAX_PAGINATION_LIMIT`, the `MAX_PAGINATION_LIMIT` will be used instead in both cases.
  /// @param donID The unique identifier of the DON whose associated workflows are being retrieved.
  /// @param start The index at which to start retrieving workflows (zero-based index). If the start index is greater
  /// than or equal to the total number of workflows, an empty array is returned.
  /// @param limit The maximum number of workflow metadata entries to retrieve. If the limit exceeds the available
  /// number of workflows from the start index, only the available entries are returned.
  /// @return workflowMetadataList An array of `WorkflowMetadata` structs containing metadata of workflows associated
  /// with the specified DON ID.
  function getWorkflowMetadataListByDON(
    uint32 donID,
    uint256 start,
    uint256 limit
  ) external view returns (WorkflowMetadata[] memory workflowMetadataList) {
    uint256 totalWorkflows = s_donWorkflowKeys[donID].length();
    if (start >= totalWorkflows) {
      return new WorkflowMetadata[](0);
    }

    if (limit > MAX_PAGINATION_LIMIT || limit == 0) {
      limit = MAX_PAGINATION_LIMIT;
    }

    uint256 end = (start + limit > totalWorkflows) ? totalWorkflows : start + limit;

    uint256 resultLength = end - start;
    workflowMetadataList = new WorkflowMetadata[](resultLength);

    for (uint256 i = 0; i < resultLength; ++i) {
      bytes32 workflowKey = s_donWorkflowKeys[donID].at(start + i);
      workflowMetadataList[i] = s_workflows[workflowKey];
    }

    return workflowMetadataList;
  }

  /// @notice Fetch all allowed DON IDs
  /// @return allowedDONs List of all allowed DON IDs
  function getAllAllowedDONs() external view returns (uint32[] memory allowedDONs) {
    uint256 len = s_allowedDONs.length();
    allowedDONs = new uint32[](len);
    for (uint256 i = 0; i < len; ++i) {
      allowedDONs[i] = uint32(s_allowedDONs.at(i));
    }

    return allowedDONs;
  }

  /// @notice Fetch all authorized addresses
  /// @return authorizedAddresses List of all authorized addresses
  function getAllAuthorizedAddresses() external view returns (address[] memory authorizedAddresses) {
    uint256 len = s_authorizedAddresses.length();
    authorizedAddresses = new address[](len);
    for (uint256 i = 0; i < len; ++i) {
      authorizedAddresses[i] = s_authorizedAddresses.at(i);
    }

    return authorizedAddresses;
  }

  /// @notice Returns whether the registry is currently locked
  /// @return True if the registry is locked, false otherwise
  function isRegistryLocked() external view returns (bool) {
    return s_registryLocked;
  }

  // ================================================================
  // |                          Validation                          |
  // ================================================================

  /// @dev Internal function to validate the urls for a workflow.
  function _validateWorkflowURLs(
    uint256 binaryURLLength,
    uint256 configURLLength,
    uint256 secretsURLLength
  ) internal pure {
    if (binaryURLLength == 0) {
      revert BinaryURLRequired();
    }

    if (binaryURLLength > MAX_URL_LENGTH) {
      revert URLTooLong(binaryURLLength, MAX_URL_LENGTH);
    }

    if (configURLLength > MAX_URL_LENGTH) {
      revert URLTooLong(configURLLength, MAX_URL_LENGTH);
    }

    if (secretsURLLength > MAX_URL_LENGTH) {
      revert URLTooLong(secretsURLLength, MAX_URL_LENGTH);
    }
  }

  /// @dev Internal function to validate the length of a workflow name.
  /// @param workflowNameLength The workflow name to validate.
  /// @custom:throws WorkflowNameTooLong if the workflow name exceeds MAX_WORKFLOW_NAME_LENGTH (64 characters).
  function _validateWorkflowName(
    uint256 workflowNameLength
  ) internal pure {
    if (workflowNameLength == 0) {
      revert WorkflowNameRequired();
    }

    if (workflowNameLength > MAX_WORKFLOW_NAME_LENGTH) {
      revert WorkflowNameTooLong(workflowNameLength, MAX_WORKFLOW_NAME_LENGTH);
    }
  }

  /// @notice Validates access permissions for a given DON and caller.
  /// @dev Reverts with DONNotAllowed if the DON is not allowed or AddressNotAuthorized if the caller is not authorized.
  /// @param donID The ID of the DON to check.
  /// @param caller The address attempting to access the DON
  function _validatePermissions(uint32 donID, address caller) internal view {
    if (!s_allowedDONs.contains(donID)) {
      // First, ensure the DON is in the allowed list. This is separate from the permission check below because a DON
      // can be removed from the allowed list without removing the permissioned addresses associated with the DON.
      revert DONNotAllowed(donID);
    }

    // Then, ensure the specific address is also authorized.
    if (!s_authorizedAddresses.contains(caller)) revert AddressNotAuthorized(caller);
  }

  /// @notice Generates a unique `workflowKey` by combining the owner's address with a specific field.
  /// This is essential for managing workflows within the registry. The following functions use this as an input:
  /// - updateRegistry
  /// - pauseWorkflow
  /// - activateWorkflow
  /// - deleteWorkflow
  /// If you do not have the `workflowKey` for these functions, you can compute it using this function
  /// with the owner's address and the workflow name.
  /// @dev This function ensures uniqueness for operations like workflow management or secrets
  /// handling by hashing the owner's address together with a distinguishing field such as
  /// the workflow name or secrets URL.
  /// @param owner The address of the owner. Typically used to uniquely associate the field with the owner.
  /// @param field A string field, such as the workflow name or secrets URL, that is used to generate the unique hash.
  /// @return A unique `bytes32` hash computed from the combination of the owner's address and the given field.
  function computeHashKey(address owner, string calldata field) public pure returns (bytes32) {
    return keccak256(abi.encodePacked(owner, field));
  }
}

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

interface ITypeAndVersion {
  function typeAndVersion() external pure returns (string memory);
}

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

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

/// @notice Sets the msg.sender to be the owner of the contract and does not set a pending owner.
contract Ownable2StepMsgSender is Ownable2Step {
  constructor() Ownable2Step(msg.sender, address(0)) {}
}

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

pragma solidity ^0.8.20;

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

/**
 * @dev String operations.
 */
library Strings {
    bytes16 private constant HEX_DIGITS = "0123456789abcdef";
    uint8 private constant ADDRESS_LENGTH = 20;

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

    /**
     * @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;
            /// @solidity memory-safe-assembly
            assembly {
                ptr := add(buffer, add(32, length))
            }
            while (true) {
                ptr--;
                /// @solidity memory-safe-assembly
                assembly {
                    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 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));
    }
}

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

pragma solidity ^0.8.20;

/**
 * @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.
 *
 * ```solidity
 * contract Example {
 *     // Add the library methods
 *     using EnumerableSet for EnumerableSet.AddressSet;
 *
 *     // Declare a set state variable
 *     EnumerableSet.AddressSet private mySet;
 * }
 * ```
 *
 * As of v3.3.0, sets of type `bytes32` (`Bytes32Set`), `address` (`AddressSet`)
 * and `uint256` (`UintSet`) are supported.
 *
 * [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 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;
    }

    // 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 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;

        /// @solidity memory-safe-assembly
        assembly {
            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 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;

        /// @solidity memory-safe-assembly
        assembly {
            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 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;

        /// @solidity memory-safe-assembly
        assembly {
            result := store
        }

        return result;
    }
}

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

import {IOwnable} from "../interfaces/IOwnable.sol";

/// @notice A minimal contract that implements 2-step ownership transfer and nothing more. It's made to be minimal
/// to reduce the impact of the bytecode size on any contract that inherits from it.
contract Ownable2Step is IOwnable {
  /// @notice The pending owner is the address to which ownership may be transferred.
  address private s_pendingOwner;
  /// @notice The owner is the current owner of the contract.
  /// @dev The owner is the second storage variable so any implementing contract could pack other state with it
  /// instead of the much less used s_pendingOwner.
  address private s_owner;

  error OwnerCannotBeZero();
  error MustBeProposedOwner();
  error CannotTransferToSelf();
  error OnlyCallableByOwner();

  event OwnershipTransferRequested(address indexed from, address indexed to);
  event OwnershipTransferred(address indexed from, address indexed to);

  constructor(address newOwner, address pendingOwner) {
    if (newOwner == address(0)) {
      revert OwnerCannotBeZero();
    }

    s_owner = newOwner;
    if (pendingOwner != address(0)) {
      _transferOwnership(pendingOwner);
    }
  }

  /// @notice Get the current owner
  function owner() public view override returns (address) {
    return s_owner;
  }

  /// @notice Allows an owner to begin transferring ownership to a new address. The new owner needs to call
  /// `acceptOwnership` to accept the transfer before any permissions are changed.
  /// @param to The address to which ownership will be transferred.
  function transferOwnership(address to) public override onlyOwner {
    _transferOwnership(to);
  }

  /// @notice validate, transfer ownership, and emit relevant events
  /// @param to The address to which ownership will be transferred.
  function _transferOwnership(address to) private {
    if (to == msg.sender) {
      revert CannotTransferToSelf();
    }

    s_pendingOwner = to;

    emit OwnershipTransferRequested(s_owner, to);
  }

  /// @notice Allows an ownership transfer to be completed by the recipient.
  function acceptOwnership() external override {
    if (msg.sender != s_pendingOwner) {
      revert MustBeProposedOwner();
    }

    address oldOwner = s_owner;
    s_owner = msg.sender;
    s_pendingOwner = address(0);

    emit OwnershipTransferred(oldOwner, msg.sender);
  }

  /// @notice validate access
  function _validateOwnership() internal view {
    if (msg.sender != s_owner) {
      revert OnlyCallableByOwner();
    }
  }

  /// @notice Reverts if called by anyone other than the contract owner.
  modifier onlyOwner() {
    _validateOwnership();
    _;
  }
}

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

pragma solidity ^0.8.20;

/**
 * @dev Standard math utilities missing in the Solidity language.
 */
library Math {
    /**
     * @dev Muldiv operation overflow.
     */
    error MathOverflowedMulDiv();

    enum Rounding {
        Floor, // Toward negative infinity
        Ceil, // Toward positive infinity
        Trunc, // Toward zero
        Expand // Away from zero
    }

    /**
     * @dev Returns the addition of two unsigned integers, with an overflow flag.
     */
    function tryAdd(uint256 a, uint256 b) internal pure returns (bool, uint256) {
        unchecked {
            uint256 c = a + b;
            if (c < a) return (false, 0);
            return (true, c);
        }
    }

    /**
     * @dev Returns the subtraction of two unsigned integers, with an overflow flag.
     */
    function trySub(uint256 a, uint256 b) internal pure returns (bool, uint256) {
        unchecked {
            if (b > a) return (false, 0);
            return (true, a - b);
        }
    }

    /**
     * @dev Returns the multiplication of two unsigned integers, with an overflow flag.
     */
    function tryMul(uint256 a, uint256 b) internal pure returns (bool, uint256) {
        unchecked {
            // Gas optimization: this is cheaper than requiring 'a' not being zero, but the
            // benefit is lost if 'b' is also tested.
            // See: https://github.com/OpenZeppelin/openzeppelin-contracts/pull/522
            if (a == 0) return (true, 0);
            uint256 c = a * b;
            if (c / a != b) return (false, 0);
            return (true, c);
        }
    }

    /**
     * @dev Returns the division of two unsigned integers, with a division by zero flag.
     */
    function tryDiv(uint256 a, uint256 b) internal pure returns (bool, uint256) {
        unchecked {
            if (b == 0) return (false, 0);
            return (true, a / b);
        }
    }

    /**
     * @dev Returns the remainder of dividing two unsigned integers, with a division by zero flag.
     */
    function tryMod(uint256 a, uint256 b) internal pure returns (bool, uint256) {
        unchecked {
            if (b == 0) return (false, 0);
            return (true, a % b);
        }
    }

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

    /**
     * @dev Returns the smallest of two numbers.
     */
    function min(uint256 a, uint256 b) internal pure returns (uint256) {
        return 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.
            return a / b;
        }

        // (a + b - 1) / b can overflow on addition, so we distribute.
        return a == 0 ? 0 : (a - 1) / b + 1;
    }

    /**
     * @notice Calculates floor(x * y / denominator) with full precision. Throws if result overflows a uint256 or
     * denominator == 0.
     * @dev 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 {
            // 512-bit multiply [prod1 prod0] = x * y. Compute the product mod 2^256 and mod 2^256 - 1, then use
            // use the Chinese Remainder Theorem to reconstruct the 512 bit result. The result is stored in two 256
            // variables such that product = prod1 * 2^256 + prod0.
            uint256 prod0 = x * y; // Least significant 256 bits of the product
            uint256 prod1; // Most significant 256 bits of the product
            assembly {
                let mm := mulmod(x, y, not(0))
                prod1 := sub(sub(mm, prod0), lt(mm, prod0))
            }

            // Handle non-overflow cases, 256 by 256 division.
            if (prod1 == 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 prod0 / denominator;
            }

            // Make sure the result is less than 2^256. Also prevents denominator == 0.
            if (denominator <= prod1) {
                revert MathOverflowedMulDiv();
            }

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

            // Make division exact by subtracting the remainder from [prod1 prod0].
            uint256 remainder;
            assembly {
                // Compute remainder using mulmod.
                remainder := mulmod(x, y, denominator)

                // Subtract 256 bit number from 512 bit number.
                prod1 := sub(prod1, gt(remainder, prod0))
                prod0 := sub(prod0, 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 {
                // Divide denominator by twos.
                denominator := div(denominator, twos)

                // Divide [prod1 prod0] by twos.
                prod0 := div(prod0, twos)

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

            // Shift in bits from prod1 into prod0.
            prod0 |= prod1 * twos;

            // Invert denominator mod 2^256. Now that denominator is an odd number, it has an inverse modulo 2^256 such
            // that denominator * inv = 1 mod 2^256. Compute the inverse by starting with a seed that is correct for
            // four bits. That is, denominator * inv = 1 mod 2^4.
            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^8
            inverse *= 2 - denominator * inverse; // inverse mod 2^16
            inverse *= 2 - denominator * inverse; // inverse mod 2^32
            inverse *= 2 - denominator * inverse; // inverse mod 2^64
            inverse *= 2 - denominator * inverse; // inverse mod 2^128
            inverse *= 2 - denominator * inverse; // inverse mod 2^256

            // 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^256. Since the preconditions guarantee that the outcome is
            // less than 2^256, this is the final result. We don't need to compute the high bits of the result and prod1
            // is no longer required.
            result = prod0 * inverse;
            return result;
        }
    }

    /**
     * @notice 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) {
        uint256 result = mulDiv(x, y, denominator);
        if (unsignedRoundsUp(rounding) && mulmod(x, y, denominator) > 0) {
            result += 1;
        }
        return result;
    }

    /**
     * @dev Returns the square root of a number. If the number is not a perfect square, the value is rounded
     * towards zero.
     *
     * Inspired by Henry S. Warren, Jr.'s "Hacker's Delight" (Chapter 11).
     */
    function sqrt(uint256 a) internal pure returns (uint256) {
        if (a == 0) {
            return 0;
        }

        // For our first guess, we get the biggest power of 2 which is smaller than the square root of the target.
        //
        // We know that the "msb" (most significant bit) of our target number `a` is a power of 2 such that we have
        // `msb(a) <= a < 2*msb(a)`. This value can be written `msb(a)=2**k` with `k=log2(a)`.
        //
        // This can be rewritten `2**log2(a) <= a < 2**(log2(a) + 1)`
        // → `sqrt(2**k) <= sqrt(a) < sqrt(2**(k+1))`
        // → `2**(k/2) <= sqrt(a) < 2**((k+1)/2) <= 2**(k/2 + 1)`
        //
        // Consequently, `2**(log2(a) / 2)` is a good first approximation of `sqrt(a)` with at least 1 correct bit.
        uint256 result = 1 << (log2(a) >> 1);

        // At this point `result` is an estimation with one bit of precision. We know the true value is a uint128,
        // since it is the square root of a uint256. Newton's method converges quadratically (precision doubles at
        // every iteration). We thus need at most 7 iteration to turn our partial result with one bit of precision
        // into the expected uint128 result.
        unchecked {
            result = (result + a / result) >> 1;
            result = (result + a / result) >> 1;
            result = (result + a / result) >> 1;
            result = (result + a / result) >> 1;
            result = (result + a / result) >> 1;
            result = (result + a / result) >> 1;
            result = (result + a / result) >> 1;
            return min(result, a / result);
        }
    }

    /**
     * @notice 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 + (unsignedRoundsUp(rounding) && result * result < a ? 1 : 0);
        }
    }

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

    /**
     * @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 + (unsignedRoundsUp(rounding) && 1 << result < value ? 1 : 0);
        }
    }

    /**
     * @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 + (unsignedRoundsUp(rounding) && 10 ** result < value ? 1 : 0);
        }
    }

    /**
     * @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 value) internal pure returns (uint256) {
        uint256 result = 0;
        unchecked {
            if (value >> 128 > 0) {
                value >>= 128;
                result += 16;
            }
            if (value >> 64 > 0) {
                value >>= 64;
                result += 8;
            }
            if (value >> 32 > 0) {
                value >>= 32;
                result += 4;
            }
            if (value >> 16 > 0) {
                value >>= 16;
                result += 2;
            }
            if (value >> 8 > 0) {
                result += 1;
            }
        }
        return result;
    }

    /**
     * @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 + (unsignedRoundsUp(rounding) && 1 << (result << 3) < value ? 1 : 0);
        }
    }

    /**
     * @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.0.0) (utils/math/SignedMath.sol)

pragma solidity ^0.8.20;

/**
 * @dev Standard signed math utilities missing in the Solidity language.
 */
library SignedMath {
    /**
     * @dev Returns the largest of two signed numbers.
     */
    function max(int256 a, int256 b) internal pure returns (int256) {
        return a > b ? a : b;
    }

    /**
     * @dev Returns the smallest of two signed numbers.
     */
    function min(int256 a, int256 b) internal pure returns (int256) {
        return 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 {
            // must be unchecked in order to support `n = type(int256).min`
            return uint256(n >= 0 ? n : -n);
        }
    }
}

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

interface IOwnable {
  function owner() external returns (address);

  function transferOwnership(address recipient) external;

  function acceptOwnership() external;
}