ERC721SoulboundToken

{{
  "language": "Solidity",
  "sources": {
    "src/common/access-control/AccessControl.sol": {
      "content": "// SPDX-License-Identifier: BUSL-1.1

pragma solidity 0.8.30;

import {IAccessControl} from "./interfaces/IAccessControl.sol";
import {Strings} from "../libraries/Strings.sol";

/**
 * @dev Contract module that allows children to implement role-based access
 * control mechanisms. This is a lightweight version that doesn't allow enumerating role
 * members except through off-chain means by accessing the contract event logs. Some
 * applications may benefit from on-chain enumerability, for those cases see
 * {AccessControlEnumerable}.
 *
 * Roles are referred to by their `bytes32` identifier. These should be exposed
 * in the external API and be unique. The best way to achieve this is by
 * using `public constant` hash digests:
 *
 * ```
 * bytes32 public constant MY_ROLE = keccak256("MY_ROLE");
 * ```
 *
 * Roles can be used to represent a set of permissions. To restrict access to a
 * function call, use {hasRole}:
 *
 * ```
 * function foo() public {
 *     require(hasRole(MY_ROLE, msg.sender));
 *     ...
 * }
 * ```
 *
 * Roles can be granted and revoked dynamically via the {grantRole} and
 * {revokeRole} functions. Each role has an associated admin role, and only
 * accounts that have a role's admin role can call {grantRole} and {revokeRole}.
 *
 * By default, the admin role for all roles is `DEFAULT_ADMIN_ROLE`, which means
 * that only accounts with this role will be able to grant or revoke other
 * roles. More complex role relationships can be created by using
 * {_setRoleAdmin}.
 *
 * This version includes an admin cap for the `DEFAULT_ADMIN_ROLE`
 * to ensure secure role management and avoid excessive administrative power.
 * @custom:security-contact security@wisdomtree.com
 */
abstract contract AccessControl is IAccessControl {

    /// @notice The struct for the role data.
    struct RoleDataC20 {
        mapping(address => bool) members;
        bytes32 adminRole;
    }

    /// @notice The struct for the delegate data.
    struct Delegate {
        address from;
        address[] delegates;
    }

    /// @notice The mapping for the role data.
    mapping(bytes32 => RoleDataC20) internal _rolesC20;

    /// @notice Maximum number of accounts that can hold the `DEFAULT_ADMIN_ROLE`
    uint256 public constant MAX_ADMINS = 3;

    /// @notice Current number of accounts that hold the `DEFAULT_ADMIN_ROLE`
    uint256 private _adminCount = 0;

    /// @notice Maximum number of delegates that can be assigned the `DELEGATED_ADMIN_ROLE`
    uint256 public constant MAX_DELEGATES = 12;

    /// @notice Mapping that stores the delegation tree structure
    mapping(address => Delegate) public delegatedAdmins;

    /// @notice Cursor to track the number of delegates assigned
    uint256 public lastDelegatedAdmin = 0;

    /// @notice Predefined roles within the system
    bytes32 public constant DEFAULT_ADMIN_ROLE = 0x00;
    bytes32 public constant ISSUER_ROLE = keccak256("ISSUER_ROLE");
    bytes32 public constant REGISTRAR_ROLE = keccak256("REGISTRAR_ROLE");
    bytes32 public constant DELEGATED_ADMIN_ROLE = keccak256("DELEGATED_ADMIN_ROLE");

    /**
     * @dev Modifier that checks that an account has a specific role. Reverts
     * with a standardized custom error including the required role.
     * @param role The role to check.
     */
    modifier onlyRole(bytes32 role) {
        _checkRole(role);
        _;
    }

    /**
     * @dev Modifier that checks that a given role is not 'DEFAULT_ADMIN_ROLE'
     * @param role The role to check.
     */
    modifier notDefaultAdminRole(bytes32 role) {
        if (role == DEFAULT_ADMIN_ROLE) {
            revert AccessControlDefaultAdminNotAcceptable();
        }
        _;
    }

    /**
     * @dev Modifier that checks that a given role is not 'DELEGATED_ADMIN_ROLE'
     * @param role The role to check.
     */
    modifier notDelegatedAdminRole(bytes32 role) {
        if (role == DELEGATED_ADMIN_ROLE) {
            revert AccessControlDelegatedAdminNotAcceptable();
        }
        _;
    }

    /**
     * @dev Grants `role` to `account`.
     *
     * If `account` had not been already granted `role`, emits a {RoleGranted} event.
     *
     * Requirements:
     * - The caller must have the admin role associated with `role`.
     * - The role must not be `DEFAULT_ADMIN_ROLE` or `DELEGATED_ADMIN_ROLE`.
     * @param role The role to grant.
     * @param account The account to grant the role to.
     *
     * May emit a {RoleGranted} event.
     */
    function grantRole(bytes32 role, address account)
        external
        virtual
        override
        onlyRole(getRoleAdmin(role))
        notDefaultAdminRole(role)
        notDelegatedAdminRole(role)
    {
        _grantRole(role, account);
    }

    /**
     * @dev Grants `DEFAULT_ADMIN_ROLE` to `account`.
     *
     * Requirements:
     * - The caller must have `DEFAULT_ADMIN_ROLE`.
     * - The admin cap must not have been reached.
     * - The account must not have `DELEGATED_ADMIN_ROLE`.
     * - The account must not have `DEFAULT_ADMIN_ROLE`.
     *
     * @param account The account to grant the role to.
     * May emit a {RoleGranted} event.
     */
    function grantDefaultAdminRole(address account) external virtual override {
        if (!hasRole(DEFAULT_ADMIN_ROLE, msg.sender)) {
            revert AccessControlUnauthorizedAccount(msg.sender, DEFAULT_ADMIN_ROLE);
        }
        if (hasRole(DELEGATED_ADMIN_ROLE, account)) {
            revert AccessControlDefaultAdminToDelegatedAdmin(account);
        }
        if (hasRole(DEFAULT_ADMIN_ROLE, account)) {
            revert AccessControlRoleAlreadyAssigned(account, DEFAULT_ADMIN_ROLE);
        }
        if (_adminCount >= MAX_ADMINS) {
            revert AccessControlAdminCapReached();
        }

        _grantRole(DEFAULT_ADMIN_ROLE, account);
    }

    /**
     * @dev Batch grants `DELEGATED_ADMIN_ROLE` to each address in `accounts` array.
     *
     * Requirements:
     * - The caller must have `DEFAULT_ADMIN_ROLE`.
     * - The total number of delegates must not exceed `MAX_DELEGATES`.
     * @param accounts The array of accounts to grant the role to.
     *
     * May emit a {RoleGranted} event.
     */
    function batchGrantDelegateAdminRole(address[] memory accounts) external virtual override {
        if (!hasRole(DEFAULT_ADMIN_ROLE, msg.sender)) {
            revert AccessControlNotDefaultAdmin(msg.sender);
        }

        uint256 _len = accounts.length;
        if (lastDelegatedAdmin + _len > MAX_DELEGATES) {
            revert AccessControlDelegateCapReached();
        }

        for (uint256 i; i < _len; ++i) {
            grantDelegateAdminRole(accounts[i]);
        }
    }

    /**
     * @dev Revokes `DELEGATED_ADMIN_ROLE` from `account`.
     *
     * Requirements:
     * - The caller must have either the `DEFAULT_ADMIN_ROLE` or be the direct delegator.
     * @param account The account to revoke the role from.
     *
     * May emit a {RoleRevoked} event.
     */
    function revokeDelegateAdminRole(address account) external virtual override {
        if (!hasRole(DELEGATED_ADMIN_ROLE, account)) {
            revert AccessControlRoleNotAssigned(account, DELEGATED_ADMIN_ROLE);
        }
        bool _isDefaultAdmin = hasRole(DEFAULT_ADMIN_ROLE, msg.sender);
        if (delegatedAdmins[account].from != msg.sender && !_isDefaultAdmin) {
            revert AccessControlNoRightsToRevoke(msg.sender, account);
        }

        _recursiveRemoveDelegate(account, _isDefaultAdmin);
    }

    /**
     * @dev Revokes `DEFAULT_ADMIN_ROLE` from `account`.
     *
     * Requirements:
     * - The caller must have the `DEFAULT_ADMIN_ROLE`.
     * - At least one admin must remain after the revocation.
     * @param account The account to revoke the role from.
     *
     * May emit a {RoleRevoked} event.
     */
    function revokeDefaultAdminRole(address account) external virtual override {
        if (!hasRole(DEFAULT_ADMIN_ROLE, msg.sender)) {
            revert AccessControlUnauthorizedAccount(msg.sender, DEFAULT_ADMIN_ROLE);
        }
        if (!hasRole(DEFAULT_ADMIN_ROLE, account)) {
            revert AccessControlRoleNotAssigned(account, DEFAULT_ADMIN_ROLE);
        }
        if (_adminCount <= 1) {
            revert AccessControlMinimumAdminCount();
        }

        // Revoke all delegates of this admin
        Delegate memory delegateInfo = delegatedAdmins[account];
        uint256 delegatesLength = delegateInfo.delegates.length;

        for (uint256 i = 0; i < delegatesLength; ++i) {
            _removeDelegate(delegateInfo.delegates[i]);
        }

        delete delegatedAdmins[account];

        _revokeRole(DEFAULT_ADMIN_ROLE, account);     
        _adminCount--;
    }

    /**
     * @dev Revokes `role` from `account`.
     *
     * If `account` had been granted `role`, emits a {RoleRevoked} event.
     *
     * Requirements:
     * - The caller must have the admin role associated with `role`.
     * - The role must not be `DEFAULT_ADMIN_ROLE` or `DELEGATED_ADMIN_ROLE`.
     * @param role The role to revoke.
     * @param account The account to revoke the role from.
     *
     * May emit a {RoleRevoked} event.
     */
    function revokeRole(bytes32 role, address account)
        external
        virtual
        override
        onlyRole(getRoleAdmin(role))
        notDefaultAdminRole(role)
        notDelegatedAdminRole(role)
    {
        _revokeRole(role, account);
    }

    /**
     * @dev Revokes `role` from the calling account.
     *
     * Roles are often managed via {grantRole} and {revokeRole}: this function's
     * purpose is to provide a mechanism for accounts to lose their privileges
     * if they are compromised (such as when a trusted device is misplaced).
     *
     * Requirements:
     * - The caller must be `account`.
     * - The role must not be `DEFAULT_ADMIN_ROLE` or `DELEGATED_ADMIN_ROLE`.
     *
     * @param role The role to revoke.
     * May emit a {RoleRevoked} event.
     */
    function renounceRole(bytes32 role) external virtual override notDefaultAdminRole(role) notDelegatedAdminRole(role) {
        _revokeRole(role, msg.sender);
    }

    /**
     * @dev Grants `DELEGATED_ADMIN_ROLE` to `account`.
     *
     * Requirements:
     * - The caller must have `DEFAULT_ADMIN_ROLE` or `DELEGATED_ADMIN_ROLE`.
     * - The total number of delegates must not exceed `MAX_DELEGATES`.
     * - The account must not have `DELEGATED_ADMIN_ROLE`.
     * - The account must not have `DEFAULT_ADMIN_ROLE`.
     * @param account The account to grant the role to.
     *
     * May emit a {RoleGranted} event.
     */
    function grantDelegateAdminRole(address account) public virtual override {
        if (!hasRole(DEFAULT_ADMIN_ROLE, msg.sender) && !hasRole(DELEGATED_ADMIN_ROLE, msg.sender)) {
            revert AccessControlNotDefaultOrDelegatedAdmin(msg.sender);
        }
        if (hasRole(DELEGATED_ADMIN_ROLE, account)) {
            revert AccessControlRoleAlreadyAssigned(account, DELEGATED_ADMIN_ROLE);
        }
        if (hasRole(DEFAULT_ADMIN_ROLE, account)) {
            revert AccessControlDelegatedAdminToDefaultAdmin(account);
        }
        if (account == address(0)) {
            revert AccessControlInvalidAddress();
        }
        if (lastDelegatedAdmin >= MAX_DELEGATES) {
            revert AccessControlDelegateCapReached();
        }

        delegatedAdmins[msg.sender].delegates.push(account);
        delegatedAdmins[account].from = msg.sender;

        _grantRole(DELEGATED_ADMIN_ROLE, account);
        lastDelegatedAdmin++;
    }

    /**
     * @dev Returns `true` if `account` has been granted `role`.
     * @param role The role to check.
     * @param account The account to check.
     * @return bool True if the account has the role, false otherwise.
     */
    function hasRole(bytes32 role, address account) public view virtual override returns (bool) {
        return _rolesC20[role].members[account];
    }

    /**
     * @dev Returns the admin role that controls `role`. See {grantRole} and
     * {revokeRole}.
     * @param role The role to check.
     * @return bytes32 The admin role.
     */
    function getRoleAdmin(bytes32 role) public view virtual override returns (bytes32) {
        return _rolesC20[role].adminRole;
    }

    /**
     * @dev Sets `adminRole` as ``role``'s admin role.
     *
     * Emits a {RoleAdminChanged} event.
     * @param role The role to change.
     * @param adminRole The new admin role.
     */
    function _setRoleAdmin(bytes32 role, bytes32 adminRole) internal virtual {
        bytes32 previousAdminRole = getRoleAdmin(role);
        _rolesC20[role].adminRole = adminRole;
        emit RoleAdminChanged(role, previousAdminRole, adminRole);
    }

    /**
     * @dev Grants `role` to `account`.
     *
     * Internal function without access restriction.
     * @param role The role to grant.
     * @param account The account to grant the role to.
     *
     * May emit a {RoleGranted} event.
     */
    function _grantRole(bytes32 role, address account) internal virtual {
        if (account == address(0)) {
            revert AccessControlInvalidAddress();
        }

        if (role == DEFAULT_ADMIN_ROLE) {
            if (hasRole(DEFAULT_ADMIN_ROLE, account)) {
                revert AccessControlRoleAlreadyAssigned(account, DEFAULT_ADMIN_ROLE);
            }
            _adminCount++;
        }

        if (!hasRole(role, account)) {
            _rolesC20[role].members[account] = true;
            emit RoleGranted(role, account, msg.sender);
        }
    }

    /**
     * @dev Revokes `role` from `account`.
     * @param role The role to revoke.
     * @param account The account to revoke the role from.
     */
    function _revokeRole(bytes32 role, address account) internal virtual {
        if (account == address(0)) {
            revert AccessControlInvalidAddress();
        }
        if (hasRole(role, account)) {
            _rolesC20[role].members[account] = false;
            emit RoleRevoked(role, account, msg.sender);
        }
    }

    /**
     * @dev Recursively removes delegate roles from an account.
     * @param account The account to remove delegate roles from.
     * @param _isDefaultAdmin Boolean indicating if the caller is a default admin.
     */
    function _recursiveRemoveDelegate(address account, bool _isDefaultAdmin) internal virtual {
        if (account == address(0)) {
            revert AccessControlInvalidAddress();
        }

        address parent = delegatedAdmins[account].from;
        if (parent != msg.sender && !_isDefaultAdmin) {
            revert AccessControlNoRightsToRevoke(msg.sender, account);
        }

        if (parent != address(0)) {
            Delegate storage parentInfo = delegatedAdmins[parent];
            uint256 delegatesLength = parentInfo.delegates.length;
            for (uint256 i = 0; i < delegatesLength; ++i) {
                if (parentInfo.delegates[i] == account) {
                    parentInfo.delegates[i] = parentInfo.delegates[delegatesLength - 1];
                    parentInfo.delegates.pop();
                    break;
                }
            }
        }

        _removeDelegate(account);
    }

    /**
     * @dev Removes a delegate role from an account.
     * @param account The account to remove the delegate role from.
     */
    function _removeDelegate(address account) internal virtual {
        Delegate memory delegateInfo = delegatedAdmins[account];
        uint256 delegatesLength = delegateInfo.delegates.length;

        for (uint256 i = 0; i < delegatesLength; ++i) {
            _removeDelegate(delegateInfo.delegates[i]);
        }

        delete delegatedAdmins[account];
        _revokeRole(DELEGATED_ADMIN_ROLE, account);
        lastDelegatedAdmin--;
    }

    /**
     * @dev Revert with a standard custom error if `msg.sender` is missing `role`.
     * Overriding this function changes the behavior of the {onlyRole} modifier.
     *
     * Format of the revert message is described in {_checkRole}.
     *
     * _Available since v4.6._
     * @param role The role to check.
     */
    function _checkRole(bytes32 role) internal view virtual {
        _checkRole(role, msg.sender);
    }

    /**
     * @dev Revert with a standard custom error if `account` is missing `role`.
     * @param role The role to check.
     * @param account The account to check.
     */
    function _checkRole(bytes32 role, address account) internal view virtual {
        if (!hasRole(role, account) && !hasRole(DEFAULT_ADMIN_ROLE, account)) {
            revert AccessControlUnauthorizedAccount(account, role);
        }
    }
}
"
    },
    "src/common/access-control/interfaces/IAccessControl.sol": {
      "content": "// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts v4.4.1 (access/IAccessControl.sol)

pragma solidity 0.8.30;

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

/**
 * @dev External interface of AccessControl declared to support ERC165 detection.
 */
interface IAccessControl is IAccessControlErrors {
    /**
     * @dev Emitted when `newAdminRole` is set as ``role``'s admin role, replacing `previousAdminRole`.
     *
     * `DEFAULT_ADMIN_ROLE` is the starting admin for all roles, despite
     * {RoleAdminChanged} not being emitted signaling this.
     *
     * _Available since v3.1._
     */
    event RoleAdminChanged(bytes32 indexed role, bytes32 indexed previousAdminRole, bytes32 indexed newAdminRole);

    /**
     * @dev Emitted when `account` is granted `role`.
     *
     * `sender` is the account that originated the contract call, an admin role.
     * @param role The role that was granted.
     * @param account The account that was granted the role.
     * @param sender The sender of the role grant.
     */
    event RoleGranted(bytes32 indexed role, address indexed account, address indexed sender);

    /**
     * @dev Emitted when `account` is revoked `role`.
     *
     * `sender` is the account that originated the contract call:
     *   - if using `revokeRole`, it is the admin role bearer
     *   - if using `renounceRole`, it is the role bearer (i.e. `account`).
     * @param role The role that was revoked.
     * @param account The account that was revoked the role.
     * @param sender The sender of the role revocation.
     */
    event RoleRevoked(bytes32 indexed role, address indexed account, address indexed sender);

    /**
     * @dev Grants `role` to `account`.
     *
     * If `account` had not been already granted `role`, emits a {RoleGranted}
     * event.
     *
     * Requirements:
     *
     * - The caller must have ``role``'s admin role.
     * @param role The role to grant.
     * @param account The account to grant the role to.
     */
    function grantRole(bytes32 role, address account) external;

    /**
     * @dev Grants `DEFAULT_ADMIN_ROLE` to `account`.
     *
     * If `account` had not been already granted `DEFAULT_ADMIN_ROLE`, emits a {RoleGranted}
     * event.
     *
     * Requirements:
     *
     * - The caller must have `DEFAULT_ADMIN_ROLE`.
     * - It will only be granted if the admin cap has not been reached.
     *
     * May emit a {RoleGranted} event.
     * @param account The account to grant the role to.
     */
    function grantDefaultAdminRole(address account) external;

    /**
     * @dev Grants `DELEGATED_ADMIN_ROLE` to `account`.
     *
     * If `account` had not been already granted `DELEGATED_ADMIN_ROLE`, emits a {RoleGranted}
     * event.
     *
     * Requirements:
     *
     * - The caller must have `DEFAULT_ADMIN_ROLE` or `DELEGATED_ADMIN_ROLE`.
     * - The total number of delegates must not exceed the `MAX_DELEGATES`.
     *
     * May emit a {RoleGranted} event.
     * @param account The account to grant the role to.
     */
    function grantDelegateAdminRole(address account) external;

    /**
     * @dev Batch grants `DELEGATED_ADMIN_ROLE` to each address in `accounts` array.
     *
     * If each `account` had not been already granted `DELEGATED_ADMIN_ROLE`, emits a {RoleGranted}
     * event for each.
     *
     * Requirements:
     *
     * - The caller must have `DEFAULT_ADMIN_ROLE`.
     * - The total number of delegates must not exceed `MAX_DELEGATES`.
     *
     * May emit a {RoleGranted} event.
     * @param accounts The accounts to grant the role to.
     */
    function batchGrantDelegateAdminRole(address[] memory accounts) external;

    /**
     * @dev Revokes `DELEGATED_ADMIN_ROLE` from `account`.
     *
     * If `account` had been granted `DELEGATED_ADMIN_ROLE`, emits a {RoleRevoked}
     * event.
     *
     * Requirements:
     *
     * - The caller must have `DEFAULT_ADMIN_ROLE` or be the direct delegator of the role.
     *
     * May emit a {RoleRevoked} event.
     * @param account The account to revoke the role from.
     */
    function revokeDelegateAdminRole(address account) external;

    /**
     * @dev Revokes `DEFAULT_ADMIN_ROLE` from `account`.
     *
     * If `account` had been granted `DEFAULT_ADMIN_ROLE`, emits a {RoleRevoked}
     * event.
     *
     * Requirements:
     *
     * - The caller must have `DEFAULT_ADMIN_ROLE`.
     * - At least one admin must remain after the revocation.
     *
     * May emit a {RoleRevoked} event.
     * @param account The account to revoke the role from.
     */
    function revokeDefaultAdminRole(address account) external;

    /**
     * @dev Revokes `role` from `account`.
     *
     * If `account` had been granted `role`, emits a {RoleRevoked} event.
     *
     * Requirements:
     *
     * - The caller must have ``role``'s admin role.
     * @param role The role to revoke.
     * @param account The account to revoke the role from.
     */
    function revokeRole(bytes32 role, address account) external;

    /**
     * @dev Revokes `role` from the calling account.
     *
     * Roles are often managed via {grantRole} and {revokeRole}: this function's
     * purpose is to provide a mechanism for accounts to lose their privileges
     * if they are compromised (such as when a trusted device is misplaced).
     *
     * If the calling account had been granted `role`, emits a {RoleRevoked}
     * event.
     *
     * Requirements:
     *
     * - The caller must be `account`.
     * @param role The role to revoke.
     */
    function renounceRole(bytes32 role) external;

    /**
     * @dev Returns `true` if `account` has been granted `role`.
     * @param role The role to check.
     * @param account The account to check.
     * @return bool True if the account has the role, false otherwise.
     */
    function hasRole(bytes32 role, address account) external view returns (bool);

    /**
     * @dev Returns the admin role that controls `role`. See {grantRole} and
     * {revokeRole}.
     *
     * To change a role's admin, use {AccessControl-_setRoleAdmin}.
     * @param role The role to get the admin for.
     * @return bytes32 The admin role.
     */
    function getRoleAdmin(bytes32 role) external view returns (bytes32);
}
"
    },
    "src/common/access-control/interfaces/IAccessControlErrors.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity 0.8.30;

/**
 * @title IAccessControlErrors
 * @dev Interface for AccessControl custom errors
 */
interface IAccessControlErrors {
    /**
     * @dev Indicates that the caller is not authorized to perform an operation.
     * @param account The address attempting the operation.
     * @param role The required role.
     */
    error AccessControlUnauthorizedAccount(address account, bytes32 role);

    /**
     * @dev Indicates that the admin cap has been reached.
     */
    error AccessControlAdminCapReached();

    /**
     * @dev Indicates that the delegate cap has been reached.
     */
    error AccessControlDelegateCapReached();

    /**
     * @dev Indicates that the account already has the role.
     * @param account The address that already has the role.
     * @param role The role in question.
     */
    error AccessControlRoleAlreadyAssigned(address account, bytes32 role);

    /**
     * @dev Indicates that the account does not have the role.
     * @param account The address that doesn't have the role.
     * @param role The role in question.
     */
    error AccessControlRoleNotAssigned(address account, bytes32 role);

    /**
     * @dev Indicates that the zero address was provided.
     */
    error AccessControlInvalidAddress();

    /**
     * @dev Indicates that the DEFAULT_ADMIN_ROLE cannot be directly granted.
     */
    error AccessControlDefaultAdminNotAcceptable();

    /**
     * @dev Indicates that the DELEGATED_ADMIN_ROLE cannot be edited using this function.
     */
    error AccessControlDelegatedAdminNotAcceptable();

    /**
     * @dev Indicates that the DEFAULT_ADMIN_ROLE cannot be assigned to a DELEGATED_ADMIN_ROLE account.
     * @param account The address that has DELEGATED_ADMIN_ROLE.
     */
    error AccessControlDefaultAdminToDelegatedAdmin(address account);

    /**
     * @dev Indicates that the DELEGATED_ADMIN_ROLE cannot be assigned to a DEFAULT_ADMIN_ROLE account.
     * @param account The address that has DEFAULT_ADMIN_ROLE.
     */
    error AccessControlDelegatedAdminToDefaultAdmin(address account);

    /**
     * @dev Indicates that there must be at least one admin.
     */
    error AccessControlMinimumAdminCount();

    /**
     * @dev Indicates that the caller has no rights to revoke the role.
     * @param caller The address attempting to revoke.
     * @param account The address from which the role would be revoked.
     */
    error AccessControlNoRightsToRevoke(address caller, address account);

    /**
     * @dev Indicates that the caller is not a default or delegated admin.
     * @param caller The address attempting the operation.
     */
    error AccessControlNotDefaultOrDelegatedAdmin(address caller);

    /**
     * @dev Indicates that the caller is not a default admin.
     * @param caller The address attempting the operation.
     */
    error AccessControlNotDefaultAdmin(address caller);
} "
    },
    "src/common/interfaces/IBeacon.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity 0.8.30;

import {ContractType} from "../types/ContractType.sol";

/**
 * @dev Interface for Beacon contract
 */
interface IBeacon {
    /**
     * @dev Returns the implementation address of the Beacon contract
     * @return The implementation address
     */
    function implementation() external view returns (address);

    /**
     * @dev Returns the beacon name
     * @return The beacon name identifying this beacon/logic pair
     */
    function name() external view returns (string memory);

    /**
     * @dev Returns the contract type of this beacon
     * @return contractType The contract type as ContractType enum: NONE (invalid), ERC20Token, ERC721Token, ERC721SoulboundToken, WhitelistComplianceOracle
     */
    function contractType() external view returns (ContractType);
}
"
    },
    "src/common/interfaces/IBeaconUpgradeErrors.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity 0.8.30;

/**
 * @title IBeaconUpgradeErrors
 * @author WisdomTree Development Team
 * @dev Standardized error interface for beacon upgrade operations across all contract types.
 * This interface ensures consistent error reporting for upgradeBeaconToAndCall functionality
 * across ERC20, ERC721, Oracle, and any other contracts that implement beacon upgrades.
 * @custom:security-contact security@wisdomtree.com
 */
interface IBeaconUpgradeErrors {
    /**
     * @dev Thrown when attempting to upgrade to a zero address beacon.
     * @param providedBeacon The invalid beacon address that was provided (should be address(0))
     */
    error BeaconUpgradeZeroAddress(address providedBeacon);

    /**
     * @dev Thrown when the new beacon does not support the required IBeacon interface.
     * @param beacon The beacon address that does not support the IBeacon interface
     */
    error BeaconUpgradeInvalidInterface(address beacon);

    /**
     * @dev Thrown when the new beacon returns a zero address as its implementation.
     * @param beacon The beacon address that has an invalid implementation
     */
    error BeaconUpgradeInvalidImplementation(address beacon);

    /**
     * @dev Thrown when attempting to upgrade to the same beacon that is currently active.
     * @param currentBeacon The beacon address that is already active
     */
    error BeaconUpgradeSameBeacon(address currentBeacon);

    /**
     * @dev Thrown when the new beacon does not support the contractType() function.
     * @param beacon The beacon address that does not support contractType functionality
     */
    error BeaconUpgradeNoContractType(address beacon);

    /**
     * @dev Thrown when the new beacon's contract type does not match the current beacon's type.
     * @param beacon The beacon address with mismatched contract type
     * @param expectedType The expected contract type
     * @param actualType The actual contract type returned by the new beacon
     */
    error BeaconUpgradeTypeMismatch(address beacon, uint8 expectedType, uint8 actualType);

    /**
     * @dev Thrown when the call to the new implementation fails during upgrade.
     * @param beacon The beacon address that was being upgraded to
     * @param callData The call data that failed
     */
    error BeaconUpgradeCallFailed(address beacon, bytes callData);
}"
    },
    "src/common/interfaces/IERC165.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity 0.8.30;

interface IERC165 {
    /**
     * @dev Returns true if this contract implements the interface defined by
     * `interfaceID`. See the corresponding
     * https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[EIP section]
     * to learn more about how these ids are created.
     *
     * This function call must use less than 30 000 gas.
     * @param interfaceID The interface ID to check.
     * @return bool True if the contract implements the interface, false otherwise.
     */
    function supportsInterface(bytes4 interfaceID) external view returns (bool);
}
"
    },
    "src/common/libraries/Math.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity 0.8.30;

/**
 * @dev Standard math utilities missing in the Solidity language.
 */
library Math {
    /**
     * @dev The rounding direction.
     */
    enum Rounding {
        Down, // Toward negative infinity
        Up, // Toward infinity
        Zero // Toward zero
    }

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

    /**
     * @dev Returns the smallest of two numbers.
     *
     * @param a The first number.
     * @param b The second number.
     * @return The smallest of the 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.
     *
     * @param a The first number.
     * @param b The second number.
     * @return The average of the two numbers.
     */
    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 up instead
     * of rounding down.
     *
     * @param a The first number.
     * @param b The second number.
     * @return The ceiling of the division of the two numbers.
     */
    function ceilDiv(uint256 a, uint256 b) internal pure returns (uint256) {
        // (a + b - 1) / b can overflow on addition, so we distribute.
        return a == 0 ? 0 : (a - 1) / b + 1;
    }

    /**
     * @dev Return the log in base 2, rounded down, of a positive value.
     * Returns 0 if given 0.
     *
     * @param value The value to compute the log2 of.
     * @return The log in base 2 of the value.
     */
    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.
     *
     * @param value The value to compute the log2 of.
     * @param rounding The rounding direction.
     * @return The log in base 2 of the value.
     */
    function log2(uint256 value, Rounding rounding) internal pure returns (uint256) {
        unchecked {
            uint256 result = log2(value);
            return result + (rounding == Rounding.Up && 1 << result < value ? 1 : 0);
        }
    }

    /**
     * @dev Return the log in base 10, rounded down, of a positive value.
     * Returns 0 if given 0.
     *
     * @param value The value to compute the log10 of.
     * @return The log in base 10 of the value.
     */
    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 256, rounded down, of a positive value.
     * 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.
     *
     * @param value The value to compute the log256 of.
     * @return The log in base 256 of the value.
     */
    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 10, following the selected rounding direction, of a positive value.
     * Returns 0 if given 0.
     *
     * @param value The value to compute the log10 of.
     * @param rounding The rounding direction.
     * @return The log in base 10 of the value.
     */
    function log256(uint256 value, Rounding rounding) internal pure returns (uint256) {
        unchecked {
            uint256 result = log256(value);
            return result + (rounding == Rounding.Up && 1 << (result << 3) < value ? 1 : 0);
        }
    }
}
"
    },
    "src/common/libraries/StorageSlot.sol": {
      "content": "// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.0.0) (utils/StorageSlot.sol)
// This file was procedurally generated from scripts/generate/templates/StorageSlot.js.

pragma solidity 0.8.30;

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

    /// @notice The slot for boolean.
    struct BooleanSlot {
        bool value;
    }

    /// @notice The slot for bytes32.
    struct Bytes32Slot {
        bytes32 value;
    }

    /// @notice The slot for uint256.
    struct Uint256Slot {
        uint256 value;
    }

    /// @notice The slot for string.
    struct StringSlot {
        string value;
    }

    /// @notice The slot for bytes.
    struct BytesSlot {
        bytes value;
    }

    /// @notice The slot for uint8.
    struct Uint8Slot {
        uint8 value;
    }

    /// @notice The slot for bytes array.
    struct BytesArraySlot {
        bytes[] value;
    }

    /// @notice The slot for uint256 array.
    struct Uint256ArraySlot {
        uint256[] value;
    }

    /// @notice The slot for uint256 mapping.
    struct Uint256MappingSlot {
        mapping(uint256 => uint256) value;
    }

    /// @notice The slot for uint256 string mapping.
    struct Uint256StringMappingSlot {
        mapping(uint256 => string) value;
    }

    /// @notice The slot for uint256 address mapping.
    struct Uint256AddressMappingSlot {
        mapping(uint256 => address) value;
    }

    /// @notice The slot for address uint256 mapping.
    struct AddressUint256MappingSlot {
        mapping(address => uint256) value;
    }

    /// @notice The slot for address mapping address boolean mapping.
    struct AddressMappingAddressBooleanMappingSlot {
        mapping(address => mapping(address => bool)) value;
    }

    /// @notice The slot for address mapping uint256 mapping.
    struct AddressMappingUint256MappingSlot {
        mapping(address => mapping(uint256 => uint256)) value;
    }

    /// @notice The slot for bytes address mapping.
    struct BytesAddressMappingSlot {
        mapping(bytes => address) value;
    }

    /// @notice The slot for bytes uint8 mapping.
    struct BytesUint8MappingSlot {
        mapping(bytes => uint8) value;
    }

    /// @notice The slot for bytes uint256 mapping.
    struct BytesUintMappingSlot {
        mapping(bytes => uint256) value;
    }

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

    /**
     * @dev Returns an `BooleanSlot` with member `value` located at `slot`.
     * @param slot The slot to read from.
     * @return r The slot value.
     */
    function getBooleanSlot(bytes32 slot) internal pure returns (BooleanSlot storage r) {
        /// @solidity memory-safe-assembly
        assembly {
            r.slot := slot
        }
    }

    /**
     * @dev Returns an `Bytes32Slot` with member `value` located at `slot`.
     * @param slot The slot to read from.
     * @return r The slot value.
     */
    function getBytes32Slot(bytes32 slot) internal pure returns (Bytes32Slot storage r) {
        /// @solidity memory-safe-assembly
        assembly {
            r.slot := slot
        }
    }

    /**
     * @dev Returns an `Uint256Slot` with member `value` located at `slot`.
     * @param slot The slot to read from.
     * @return r The slot value.
     */
    function getUint256Slot(bytes32 slot) internal pure returns (Uint256Slot storage r) {
        /// @solidity memory-safe-assembly
        assembly {
            r.slot := slot
        }
    }

    /**
     * @dev Returns a `Uint8Slot` with member `value` located at `slot`.
     * @param slot The slot to read from.
     * @return r The slot value.
     */
    function getUint8Slot(bytes32 slot) internal pure returns (Uint8Slot storage r) {
        /// @solidity memory-safe-assembly
        assembly {
            r.slot := slot
        }
    }

    /**
     * @dev Returns an `StringSlot` with member `value` located at `slot`.
     * @param slot The slot to read from.
     * @return r The slot value.
     */
    function getStringSlot(bytes32 slot) internal pure returns (StringSlot storage r) {
        /// @solidity memory-safe-assembly
        assembly {
            r.slot := slot
        }
    }

    /**
     * @dev Returns an `StringSlot` representation of the string storage pointer `store`.
     * @param store The storage pointer to read from.
     * @return r The slot value.
     */
    function getStringSlot(string storage store) internal pure returns (StringSlot storage r) {
        /// @solidity memory-safe-assembly
        assembly {
            r.slot := store.slot
        }
    }

    /**
     * @dev Returns an `BytesSlot` with member `value` located at `slot`.
     * @param slot The slot to read from.
     * @return r The slot value.
     */
    function getBytesSlot(bytes32 slot) internal pure returns (BytesSlot storage r) {
        /// @solidity memory-safe-assembly
        assembly {
            r.slot := slot
        }
    }

    /**
     * @dev Returns an `BytesSlot` representation of the bytes storage pointer `store`.
     * @param store The storage pointer to read from.
     * @return r The slot value.
     */
    function getBytesSlot(bytes storage store) internal pure returns (BytesSlot storage r) {
        /// @solidity memory-safe-assembly
        assembly {
            r.slot := store.slot
        }
    }

    /**
     * @dev Returns an `BytesArraySlot` with member `value` located at `slot`.
     * @param slot The slot to read from.
     * @return r The slot value.
     */
    function getBytesArraySlot(bytes32 slot) internal pure returns (BytesArraySlot storage r) {
        assembly {
            r.slot := slot
        }
    }

    /**
     * @dev Returns an `Uint256ArraySlot` with member `value` located at `slot`.
     * @param slot The slot to read from.
     * @return r The slot value.
     */
    function getUint256ArraySlot(bytes32 slot) internal pure returns (Uint256ArraySlot storage r) {
        assembly {
            r.slot := slot
        }
    }

    /**
     * @dev Returns an `Uint256MappingSlot` with member `value` located at `slot`.
     * @param slot The slot to read from.
     * @return r The slot value.
     */
    function getUint256MappingSlot(bytes32 slot) internal pure returns (Uint256MappingSlot storage r) {
        assembly {
            r.slot := slot
        }
    }

    /**
     * @dev Returns an `Uint256StringMappingSlot` with member `value` located at `slot`.
     * @param slot The slot to read from.
     * @return r The slot value.
     */
    function getUint256StringMappingSlot(bytes32 slot) internal pure returns (Uint256StringMappingSlot storage r) {
        assembly {
            r.slot := slot
        }
    }

    /**
     * @dev Returns an `Uint256AddressMappingSlot` with member `value` located at `slot`.
     * @param slot The slot to read from.
     * @return r The slot value.
     */
    function getUint256AddressMappingSlot(bytes32 slot) internal pure returns (Uint256AddressMappingSlot storage r) {
        assembly {
            r.slot := slot
        }
    }

    /**
     * @dev Returns an `AddressUint256MappingSlot` with member `value` located at `slot`.
     * @param slot The slot to read from.
     * @return r The slot value.
     */
    function getAddressUint256MappingSlot(bytes32 slot) internal pure returns (AddressUint256MappingSlot storage r) {
        assembly {
            r.slot := slot
        }
    }

    /**
     * @dev Returns an `AddressMappingAddressBooleanMappingSlot` with member `value` located at `slot`.
     * @param slot The slot to read from.
     * @return r The slot value.
     */
    function getAddressMappingAddressBooleanMappingSlot(bytes32 slot) internal pure returns (AddressMappingAddressBooleanMappingSlot storage r) {
        assembly {
            r.slot := slot
        }
    }

    /**
     * @dev Returns an `AddressMappingUint256MappingSlot` with member `value` located at `slot`.
     * @param slot The slot to read from.
     * @return r The slot value.
     */
    function getAddressMappingUint256MappingSlot(bytes32 slot) internal pure returns (AddressMappingUint256MappingSlot storage r) {
        assembly {
            r.slot := slot
        }
    }

    /**
     * @dev Returns a `BytesAddressMappingSlot` with member `value` located at `slot`.
     * @param slot The slot to read from.
     * @return r The slot value.
     */
    function getBytesAddressMappingSlot(bytes32 slot) internal pure returns (BytesAddressMappingSlot storage r) {
        assembly {
            r.slot := slot
        }
    }

    /**
     * @dev Returns a `BytesUint8MappingSlot` with member `value` located at `slot`.
     * @param slot The slot to read from.
     * @return r The slot value.
     */
    function getBytesUint8MappingSlot(bytes32 slot) internal pure returns (BytesUint8MappingSlot storage r) {
        assembly {
            r.slot := slot
        }
    }

    /**
     * @dev Returns a `BytesUintMappingSlot` with member `value` located at `slot`.
     * @param slot The slot to read from.
     * @return r The slot value.
     */
    function getBytesUintMappingSlot(bytes32 slot) internal pure returns (BytesUintMappingSlot storage r) {
        assembly {
            r.slot := slot
        }
    }
}
"
    },
    "src/common/libraries/Strings.sol": {
      "content": "// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v4.8.0) (utils/Strings.sol)

pragma solidity 0.8.30;

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

/**
 * @dev String operations.
 */
library Strings {
    /**
     * @dev The symbols for the hexadecimal representation.
     */
    bytes16 private constant _SYMBOLS = "0123456789abcdef";
    /**
     * @dev The length of an address.
     */
    uint8 private constant _ADDRESS_LENGTH = 20;

    /**
     * @dev Converts a `uint256` to its ASCII `string` decimal representation.
     *
     * @param value The value to convert.
     * @return buffer The 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), _SYMBOLS))
                }
                value /= 10;
                if (value == 0) break;
            }
            return buffer;
        }
    }

    /**
     * @dev Converts a `uint256` to its ASCII `string` hexadecimal representation.
     *
     * @param value The value to convert.
     * @return buffer The 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.
     *
     * @param value The value to convert.
     * @param length The length of the hexadecimal representation.
     * @return buffer The ASCII `string` hexadecimal representation.
     */
    function toHexString(uint256 value, uint256 length) internal pure returns (string memory) {
        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] = _SYMBOLS[value & 0xf];
            value >>= 4;
        }
        require(value == 0, "Strings: hex length insufficient");
        return string(buffer);
    }

    /**
     * @dev Converts an `address` with fixed length of 20 bytes to its not checksummed ASCII `string` hexadecimal representation.
     *
     * @param addr The address to convert.
     * @return buffer The ASCII `string` hexadecimal representation.
     */
    function toHexString(address addr) internal pure returns (string memory) {
        return toHexString(uint256(uint160(addr)), _ADDRESS_LENGTH);
    }
}"
    },
    "src/common/types/ContractType.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity 0.8.30;

/**
 * @dev Contract type enumeration for implementation upgrade validation.
 * @dev This is used to validate that the implementation address supports the correct interface for the contract type.
 * @dev NONE is an explicit placeholder to prevent uninitialized variables from defaulting to a valid contract type.
 */
enum ContractType { 
    NONE,                       // 0 - Explicit placeholder for uninitialized variables
    ERC20Token,                 // 1
    ERC721Token,                // 2
    ERC721SoulboundToken,       // 3
    WhitelistComplianceOracle   // 4
} "
    },
    "src/tokens/ERC721/ERC721SoulboundToken.sol": {
      "content": "// SPDX-License-Identifier: BUSL-1.1
pragma solidity 0.8.30;

import {IERC721SoulboundToken} from "../interfaces/erc721Soulbound/IERC721SoulboundToken.sol";
import {AccessControl} from "../../common/access-control/AccessControl.sol";
import {StorageSlot} from "../../common/libraries/StorageSlot.sol";
import {IBeacon} from "../../common/interfaces/IBeacon.sol";
import {ContractType} from "../../common/types/ContractType.sol";
import {IERC165} from "../../common/interfaces/IERC165.sol";
import {Strings} from "../../common/libraries/Strings.sol";
import {IERC721Soulbound} from "../interfaces/erc721Soulbound/IERC721Soulbound.sol";
import {IERC721SoulboundTokenInit} from "../interfaces/erc721Soulbound/IERC721SoulboundTokenInit.sol";
import {IERC721SoulboundBeaconUpgrade} from "../interfaces/erc721Soulbound/IERC721SoulboundBeaconUpgrade.sol";
import {IERC721SoulboundEvents} from "../interfaces/erc721Soulbound/IERC721SoulboundEvents.sol";
import {IERC721SoulboundErrors} from "../interfaces/erc721Soulbound/IERC721SoulboundErrors.sol";
import {IERC721SoulboundMetadata} from "../interfaces/erc721Soulbound/IERC721SoulboundMetadata.sol";
import {IERC721SoulboundEnumerable} from "../interfaces/erc721Soulbound/IERC721SoulboundEnumerable.sol";
import {IERC721SoulboundBurnable} from "../interfaces/erc721Soulbound/IERC721SoulboundBurnable.sol";
import {IERC721SoulboundMintable} from "../interfaces/erc721Soulbound/IERC721SoulboundMintable.sol";
import {IERC721SoulboundReceiver} from "../interfaces/erc721Soulbound/IERC721SoulboundReceiver.sol";
import {IAccessControl} from "../../common/access-control/interfaces/IAccessControl.sol";
import {IBeaconUpgradeErrors} from "../../common/interfaces/IBeaconUpgradeErrors.sol";

/**
 * @title ERC721SoulboundToken
 * @author Mohammad Salim, WisdomTree Digital Assets
 * @dev Implementation of the ERC721SoulboundToken interface.
 * @custom:security-contact security@wisdomtree.com
 */
contract ERC721SoulboundToken is
    IERC165,
    IERC721SoulboundEvents,
    IERC721SoulboundErrors,
    IERC721Soulbound,
    IERC721SoulboundTokenInit,
    IERC721SoulboundBeaconUpgrade,
    IERC721SoulboundMetadata,
    IERC721SoulboundEnumerable,
    IERC721SoulboundMintable,
    IERC721SoulboundBurnable,
    IBeaconUpgradeErrors,
    AccessControl
{
    using StorageSlot for StorageSlot.AddressSlot;
    using StorageSlot for StorageSlot.Uint256Slot;
    using StorageSlot for StorageSlot.BooleanSlot;
    using StorageSlot for StorageSlot.Uint8Slot;
    using StorageSlot for StorageSlot.StringSlot;
    using StorageSlot for StorageSlot.Uint256ArraySlot;
    using StorageSlot for StorageSlot.Uint256MappingSlot;
    using StorageSlot for StorageSlot.AddressMappingUint256MappingSlot;
    using StorageSlot for StorageSlot.Uint256StringMappingSlot;
    using StorageSlot for StorageSlot.Uint256AddressMappingSlot;
    using StorageSlot for StorageSlot.AddressMappingAddressBooleanMappingSlot;

    /// @notice The slot for the Beacon address.
    bytes32 internal constant _BEACON_SLOT = keccak256("proxy.beacon");

    /// @notice The slot for the initialization owner address.
    bytes32 internal constant _INIT_OWNER_SLOT = keccak256("proxy.initializationOwnerAddress");

    /// @notice The slot for the contract initialization status.
    bytes32 internal constant _IS_INITIALIZED_SLOT = keccak256("proxy.isInitialized");

    /// @notice The slot for the token name.
    bytes32 internal constant _NAME_SLOT = keccak256("proxy.name");

    /// @notice The slot for the token symbol.
    bytes32 internal constant _SYMBOL_SLOT = keccak256("proxy.symbol");

    /// @notice The slot for the next token to mints Id - 1.
    bytes32 internal constant _NEXT_TOKEN_ID_SLOT = keccak256("proxy.nextTokenId");

    /// @notice The slot for the mapping from owner address to their owned tokens.
    bytes32 internal constant _OWNED_TOKENS_SLOT = keccak256("proxy.ownedTokens");

    /// @notice The slot for the mapping from token ID to its index in the list of owner's tokens.
    bytes32 internal constant _OWNED_TOKENS_INDEX_SLOT = keccak256("proxy.ownedTokensIndex");

    /// @notice The slot for the array containing all token IDs.
    bytes32 internal constant _ALL_TOKENS_SLOT = keccak256("proxy.allTokens");

    /// @notice The slot for the mapping from token ID to its index in the list of all tokens.
    bytes32 internal constant _ALL_TOKENS_INDEX_SLOT = keccak256("proxy.allTokensIndex");

    /// @notice The slot for the mapping from token ID to owner address.
    bytes32 internal constant _OWNERS_SLOT = keccak256("proxy.owners");

    /// @notice The slot for the mapping from owner address to their token balances.
    bytes32 internal constant _BALANCES_SLOT = keccak256("proxy.balances");

    /// @notice The slot for the mapping from token ID to token URI.
    bytes32 internal constant _TOKEN_URIS_SLOT = keccak256("proxy.tokenURIs");

    /// @notice The slot for the base URI.
    bytes32 internal constant _BASE_URI_SLOT = keccak256("proxy.baseURI");

    /**
     * @dev Emitted when the Beacon address is changed.
     * @param previousBeacon The address of the previous Beacon.
     * @param newBeacon The address of the new Beacon.
     */
    event BeaconChanged(address indexed previousBeacon, address indexed newBeacon);

    /**
     * @notice Ensure that only the initialization owner can call certain functions.
     */
    modifier onlyInitializationOwner() {
        if (msg.sender != StorageSlot.getAddressSlot(_INIT_OWNER_SLOT).value) {
            revert ERC721UnauthorizedInitializer(msg.sender);
        }
        _;
    }

    /**
     * @notice Constructor that disables initialization on the implementation contract.
     * @dev This prevents the implementation contract from being initialized by malicious actors.
     * When deployed through a proxy, the initialization will happen via the proxy's constructor
     * calling initializeWithRoles through delegatecall.
     */
    constructor() {
        // Disable initialization on the implementation contract to prevent malicious initialization
        StorageSlot.getBooleanSlot(_IS_INITIALIZED_SLOT).value = true;
    }

    /**
     * @notice Initialize the contract with the given initialization owner address and roles.
     * Requirements:
     * - The caller must be the initialization owner.
     * - The `name_` cannot be empty.
     * - The `symbol_` cannot be empty.
     * - The `symbol_` cannot be longer than 12 characters.
     * - The `owner` address cannot be the zero address.
     * - The `issuer` address cannot be the zero address.
     * - The `registrar` address cannot be the zero address.
     * @param name_ The name of the token
     * @param symbol_ The symbol of the token
     * @param owner The address assigned the DEFAULT_ADMIN_ROLE
     * @param issuer The address assigned the ISSUER_ROLE (placeholder role for future functionality)
     * @param registrar The address assigned the REGISTRAR_ROLE (handles minting, burning, and other operations)
     */
    function initializeWithRoles(
        string calldata name_,
        string calldata symbol_,
        address owner,
        address issuer,
        address registrar
    ) external override onlyInitializationOwner {
        if (owner == address(0x00)) {
            revert ERC721InvalidOwner(owner);
        }
        if (registrar == address(0x00)) {
            revert ERC721InvalidRegistrar(registrar);
        }
        if (issuer == address(0x00)) {
            revert ERC721InvalidIssuer(issuer);
        }
        if (StorageSlot.getBooleanSlot(_IS_INITIALIZED_SLOT).value) {
            revert ERC721AlreadyInitialized();
        }

        if (bytes(symbol_).length == 0 || bytes(symbol_).length >= 13) {
            revert ERC721InvalidSymbolLength(bytes(symbol_).length);
        }

        if (bytes(name_).length == 0) {
            revert ERC721EmptyTokenName();
        }

        StorageSlot.getStringSlot(_NAME_SLOT).value = name_;
        StorageSlot.getStringSlot(_SYMBOL_SLOT).value = symbol_;

        _grantRole(DEFAULT_ADMIN_ROLE, owner);
        _grantRole(ISSUER_ROLE, issuer);
        _grantRole(REGISTRAR_ROLE, registrar);
        _setRoleAdmin(ISSUER_ROLE, DELEGATED_ADMIN_ROLE);
        _setRoleAdmin(REGISTRAR_ROLE, DELEGATED_ADMIN_ROLE);

        StorageSlot.getBooleanSlot(_IS_INITIALIZED_SLOT).value = true;
    }

    /**
     * @notice Allows the DEFAULT_ADMIN_ROLE to upgrade the Beacon and execute an optional function.
     * @param newBeacon The address of the new Beacon contract.
     * @param callData The data to be passed to the delegate call on the new implementation.
     *
     * Emits a {BeaconChanged} event.
     *
     * Requirements:
     * - The caller must have the `DEFAULT_ADMIN_ROLE`.
     * - `newBeacon` cannot be the zero address.
     * - The new beacon must support the IBeacon interface.
     * - The new beacon must have a valid implementation address.
     * - The new beacon contract type must match the current beacon contract type.
     */
    function upgradeBeaconToAndCall(
        address newBeacon,
        bytes calldata callData
    ) 
        external
        override
        onlyRole(DEFAULT_ADMIN_ROLE) 
    {
        if (newBeacon == address(0)) revert BeaconUpgradeZeroAddress(newBeacon);
        
        // 1. Validate beacon implements IBeacon interface
        if (!IERC165(newBeacon).supportsInterface(type(IBeacon).interfaceId)) {
            revert BeaconUpgradeInvalidInterface(newBeacon);
        }
        
        // 2. Validate beacon can return implementation
        address impl = IBeacon(newBeacon).implementation();
        if (impl == address(0)) {
            revert BeaconUpgradeInvalidImplementation(newBeacon);
        }
        
        // 3. Validate contract type consistency (mandatory for proper beacon functionality)
        address currentBeacon = StorageSlot.getAddressSlot(_BEACON_SLOT).value;
        
        // 4. Check if beacon is actually changing to prevent unnecessary event emission
        if (newBeacon == currentBeacon) {
            revert BeaconUpgradeSameBeacon(currentBeacon);
        }
        
        // New beacon must support contractType function - this is mandatory
        ContractType newType;
        try IBeacon(newBeacon).contractType() returns (ContractType _newType) {
            newType = _newType;
        } catch {
            revert BeaconUpgradeNoContractType(newBeacon);
        }
        
        // If current beacon exists, validate type consistency
        if (currentBeacon != address(0)) {
            ContractType currentType;
            try IBeacon(currentBeacon).contractType() returns (ContractType _currentType) {
                currentType = _currentType;
            } catch {
                revert BeaconUpgradeNoContractType(currentBeacon);
            }
            
            if (newType != currentType) {
                revert BeaconUpgradeTypeMismatch(newBeacon, uint8(currentType), uint8(newType));
            }
        }
        
        address previousBeacon = StorageSlot.getAddressSlot(_BEACON_SLOT).value;
        _setBeacon(newBeacon);
        emit BeaconChanged(previousBeacon, newBeacon);
        
        if (callData.length > 0) {
            address implementationAddress = IBeacon(newBeacon).implementation();
            (bool success, ) = implementationAddress.delegatecall(callData);
            if (!success) {
                revert BeaconUpgradeCallFailed(newBeacon, callData);
            }
        }
    }

    /**
     * @dev Mints a new token and safely transfers it to the specified address.
     * If the target address is a contract, it must implement the `ERC721Receiver`
     * interface to receive the token. If the token is transferred to a non-contract
     * address that does not implement the `ERC721Receiver` interface, this function
     * will revert.
     *
     * Requires the sender to have the `REGISTRAR_ROLE` role.
     *
     * Emits a {Transfer} event.
     *
     * @param to The address to which the token will be transferred.
     */
    function safeMint(address to) external override onlyRole(REGISTRAR_ROLE) {
        uint256 tokenId = StorageSlot.getUint256Slot(_NEXT_TOKEN_ID_SLOT).value++;
        _safeMint(to, tokenId);
    }

    /**