@bloxchain/contracts 1.0.0-alpha → 1.0.0-alpha.10

package/core/research/FactoryBlox/FactoryBloxDefinitions.sol

@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2025 Particle Crypto Security
+pragma solidity 0.8.33;
+
+import "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+import "../../lib/EngineBlox.sol";
+import "../../lib/interfaces/IDefinition.sol";
+
+/**
+ * @title FactoryBloxDefinitions
+ * @dev Library containing definitions for FactoryBlox cloneBlox, whitelist, pricing, and macro registration.
+ *
+ * Registers cloneBlox, whitelist (addToWhitelist, removeFromWhitelist), and pricing (setClonePrice)
+ * function schemas. OWNER_ROLE gets EXECUTE_TIME_DELAY_REQUEST so requests go via the controller.
+ * All four are macro selectors so the controller can target address(this).
+ */
+library FactoryBloxDefinitions {
+    bytes32 public constant CLONE_OPERATION = keccak256("CLONE_OPERATION");
+    bytes32 public constant WHITELIST_OPERATION = keccak256("WHITELIST_OPERATION");
+    bytes32 public constant CLONE_PRICE_OPERATION = keccak256("CLONE_PRICE_OPERATION");
+
+    /// @dev Macro selectors (allowed to target address(this) for GuardController execution)
+    bytes4 public constant CLONE_BLOX_SELECTOR =
+        bytes4(keccak256("cloneBlox(address,address,address,address,uint256,bytes)"));
+    // addToWhitelist(address,(address,uint256,address,uint256))
+    bytes4 public constant ADD_TO_WHITELIST_SELECTOR =
+        bytes4(keccak256("addToWhitelist(address,(address,uint256,address,uint256))"));
+    bytes4 public constant REMOVE_FROM_WHITELIST_SELECTOR = bytes4(keccak256("removeFromWhitelist(address)"));
+    // setClonePrice(address,(address,uint256,address,uint256))
+    bytes4 public constant SET_CLONE_PRICE_SELECTOR =
+        bytes4(keccak256("setClonePrice(address,(address,uint256,address,uint256))"));
+
+    function getFunctionSchemas() public pure returns (EngineBlox.FunctionSchema[] memory) {
+        EngineBlox.FunctionSchema[] memory schemas = new EngineBlox.FunctionSchema[](4);
+
+        EngineBlox.TxAction[] memory timeDelayRequestActions = new EngineBlox.TxAction[](1);
+        timeDelayRequestActions[0] = EngineBlox.TxAction.EXECUTE_TIME_DELAY_REQUEST;
+
+        bytes4[] memory cloneHandlers = new bytes4[](1);
+        cloneHandlers[0] = CLONE_BLOX_SELECTOR;
+        schemas[0] = EngineBlox.FunctionSchema({
+            functionSignature: "cloneBlox(address,address,address,address,uint256,bytes)",
+            functionSelector: CLONE_BLOX_SELECTOR,
+            operationType: CLONE_OPERATION,
+            operationName: "CLONE_OPERATION",
+            supportedActionsBitmap: EngineBlox.createBitmapFromActions(timeDelayRequestActions),
+            isProtected: true,
+            handlerForSelectors: cloneHandlers
+        });
+
+        bytes4[] memory addWhitelistHandlers = new bytes4[](1);
+        addWhitelistHandlers[0] = ADD_TO_WHITELIST_SELECTOR;
+        schemas[1] = EngineBlox.FunctionSchema({
+            functionSignature: "addToWhitelist(address,(address,uint256,address,uint256))",
+            functionSelector: ADD_TO_WHITELIST_SELECTOR,
+            operationType: WHITELIST_OPERATION,
+            operationName: "WHITELIST_OPERATION",
+            supportedActionsBitmap: EngineBlox.createBitmapFromActions(timeDelayRequestActions),
+            isProtected: true,
+            handlerForSelectors: addWhitelistHandlers
+        });
+
+        bytes4[] memory removeWhitelistHandlers = new bytes4[](1);
+        removeWhitelistHandlers[0] = REMOVE_FROM_WHITELIST_SELECTOR;
+        schemas[2] = EngineBlox.FunctionSchema({
+            functionSignature: "removeFromWhitelist(address)",
+            functionSelector: REMOVE_FROM_WHITELIST_SELECTOR,
+            operationType: WHITELIST_OPERATION,
+            operationName: "WHITELIST_OPERATION",
+            supportedActionsBitmap: EngineBlox.createBitmapFromActions(timeDelayRequestActions),
+            isProtected: true,
+            handlerForSelectors: removeWhitelistHandlers
+        });
+
+        // Schema 3: setClonePrice (per-implementation pricing configuration for cloneBlox)
+        bytes4[] memory setClonePriceHandlers = new bytes4[](1);
+        setClonePriceHandlers[0] = SET_CLONE_PRICE_SELECTOR;
+        schemas[3] = EngineBlox.FunctionSchema({
+            functionSignature: "setClonePrice(address,(address,uint256,address,uint256))",
+            functionSelector: SET_CLONE_PRICE_SELECTOR,
+            operationType: CLONE_PRICE_OPERATION,
+            operationName: "CLONE_PRICE_OPERATION",
+            supportedActionsBitmap: EngineBlox.createBitmapFromActions(timeDelayRequestActions),
+            isProtected: true,
+            handlerForSelectors: setClonePriceHandlers
+        });
+
+        return schemas;
+    }
+
+    function getRolePermissions() public pure returns (IDefinition.RolePermission memory) {
+        bytes32[] memory roleHashes = new bytes32[](4);
+        EngineBlox.FunctionPermission[] memory functionPermissions = new EngineBlox.FunctionPermission[](4);
+
+        EngineBlox.TxAction[] memory ownerRequestActions = new EngineBlox.TxAction[](1);
+        ownerRequestActions[0] = EngineBlox.TxAction.EXECUTE_TIME_DELAY_REQUEST;
+
+        roleHashes[0] = EngineBlox.OWNER_ROLE;
+        bytes4[] memory cloneHandlers = new bytes4[](1);
+        cloneHandlers[0] = CLONE_BLOX_SELECTOR;
+        functionPermissions[0] = EngineBlox.FunctionPermission({
+            functionSelector: CLONE_BLOX_SELECTOR,
+            grantedActionsBitmap: EngineBlox.createBitmapFromActions(ownerRequestActions),
+            handlerForSelectors: cloneHandlers
+        });
+
+        roleHashes[1] = EngineBlox.OWNER_ROLE;
+        bytes4[] memory addWhitelistHandlers = new bytes4[](1);
+        addWhitelistHandlers[0] = ADD_TO_WHITELIST_SELECTOR;
+        functionPermissions[1] = EngineBlox.FunctionPermission({
+            functionSelector: ADD_TO_WHITELIST_SELECTOR,
+            grantedActionsBitmap: EngineBlox.createBitmapFromActions(ownerRequestActions),
+            handlerForSelectors: addWhitelistHandlers
+        });
+
+        roleHashes[2] = EngineBlox.OWNER_ROLE;
+        bytes4[] memory removeWhitelistHandlers = new bytes4[](1);
+        removeWhitelistHandlers[0] = REMOVE_FROM_WHITELIST_SELECTOR;
+        functionPermissions[2] = EngineBlox.FunctionPermission({
+            functionSelector: REMOVE_FROM_WHITELIST_SELECTOR,
+            grantedActionsBitmap: EngineBlox.createBitmapFromActions(ownerRequestActions),
+            handlerForSelectors: removeWhitelistHandlers
+        });
+
+        // Owner: setClonePrice
+        roleHashes[3] = EngineBlox.OWNER_ROLE;
+        bytes4[] memory setClonePriceHandlers = new bytes4[](1);
+        setClonePriceHandlers[0] = SET_CLONE_PRICE_SELECTOR;
+        functionPermissions[3] = EngineBlox.FunctionPermission({
+            functionSelector: SET_CLONE_PRICE_SELECTOR,
+            grantedActionsBitmap: EngineBlox.createBitmapFromActions(ownerRequestActions),
+            handlerForSelectors: setClonePriceHandlers
+        });
+
+        return IDefinition.RolePermission({
+            roleHashes: roleHashes,
+            functionPermissions: functionPermissions
+        });
+    }
+
+    function supportsInterface(bytes4 interfaceId) external pure returns (bool) {
+        return interfaceId == type(IERC165).interfaceId || interfaceId == type(IDefinition).interfaceId;
+    }
+}

package/core/research/erc1155-blox/ERC1155Blox.sol

@@ -0,0 +1,170 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2025 Particle Crypto Security
+pragma solidity 0.8.33;
+
+// OpenZeppelin
+import "@openzeppelin/contracts-upgradeable/token/ERC1155/ERC1155Upgradeable.sol";
+import "@openzeppelin/contracts-upgradeable/token/ERC1155/extensions/ERC1155BurnableUpgradeable.sol";
+import "@openzeppelin/contracts/token/ERC1155/IERC1155.sol";
+import "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+
+// Core
+import "../../security/SecureOwnable.sol";
+import "../../access/RuntimeRBAC.sol";
+import "../../execution/GuardController.sol";
+import "../../base/BaseStateMachine.sol";
+import "../../lib/interfaces/IDefinition.sol";
+import "./lib/definitions/ERC1155BloxDefinitions.sol";
+
+/**
+ * @title ERC1155Blox
+ * @dev ERC1155 multi-token (IERC1155) with SecureOwnable, RuntimeRBAC, and GuardController.
+ * Exposes safeTransferFrom, safeBatchTransferFrom (callable only via GuardController), mint/mintBatch (via controller), and burn/burnBatch (via controller).
+ * @custom:security-contact security@particlecrypto.com
+ */
+contract ERC1155Blox is
+    IERC1155,
+    ERC1155Upgradeable,
+    ERC1155BurnableUpgradeable,
+    SecureOwnable,
+    RuntimeRBAC,
+    GuardController
+{
+    /// @custom:oz-upgrades-unsafe-allow constructor
+    constructor() {
+        _disableInitializers();
+    }
+
+    /**
+     * @dev Override to resolve diamond: SecureOwnable, RuntimeRBAC, GuardController all define initialize(5 params).
+     * Call this first, then initializeToken(uri) to set ERC1155 base URI.
+     */
+    function initialize(
+        address initialOwner,
+        address broadcaster,
+        address recovery,
+        uint256 timeLockPeriodSec,
+        address eventForwarder
+    ) public virtual override(GuardController, RuntimeRBAC, SecureOwnable) initializer {
+        GuardController.initialize(initialOwner, broadcaster, recovery, timeLockPeriodSec, eventForwarder);
+        RuntimeRBAC.initialize(initialOwner, broadcaster, recovery, timeLockPeriodSec, eventForwarder);
+        SecureOwnable.initialize(initialOwner, broadcaster, recovery, timeLockPeriodSec, eventForwarder);
+
+        IDefinition.RolePermission memory erc1155Permissions = ERC1155BloxDefinitions.getRolePermissions();
+        _loadDefinitions(
+            ERC1155BloxDefinitions.getFunctionSchemas(),
+            erc1155Permissions.roleHashes,
+            erc1155Permissions.functionPermissions,
+            true
+        );
+
+        _addMacroSelector(ERC1155BloxDefinitions.SAFE_TRANSFER_FROM_SELECTOR);
+        _addMacroSelector(ERC1155BloxDefinitions.SAFE_BATCH_TRANSFER_FROM_SELECTOR);
+        _addMacroSelector(ERC1155BloxDefinitions.MINT_SELECTOR);
+        _addMacroSelector(ERC1155BloxDefinitions.MINT_BATCH_SELECTOR);
+        _addMacroSelector(ERC1155BloxDefinitions.BURN_SELECTOR);
+        _addMacroSelector(ERC1155BloxDefinitions.BURN_BATCH_SELECTOR);
+    }
+
+    /**
+     * @notice Initialize the ERC1155 base URI. Call after initialize(5 params).
+     * @param uri_ Base URI for token metadata (e.g. https://example.com/{id}.json)
+     */
+    function initializeToken(string memory uri_) public reinitializer(2) {
+        __ERC1155_init(uri_);
+    }
+
+    /**
+     * @notice Safe transfer of token; callable only by this contract via GuardController
+     * @param from Sender address
+     * @param to Recipient address
+     * @param id Token type ID
+     * @param value Amount to transfer
+     * @param data Additional data for recipient hook
+     */
+    function safeTransferFrom(address from, address to, uint256 id, uint256 value, bytes memory data)
+        public
+        virtual
+        override(ERC1155Upgradeable, IERC1155)
+    {
+        _validateExecuteBySelf();
+        super.safeTransferFrom(from, to, id, value, data);
+    }
+
+    /**
+     * @notice Safe batch transfer; callable only by this contract via GuardController
+     * @param from Sender address
+     * @param to Recipient address
+     * @param ids Token type IDs
+     * @param values Amounts to transfer
+     * @param data Additional data for recipient hook
+     */
+    function safeBatchTransferFrom(address from, address to, uint256[] memory ids, uint256[] memory values, bytes memory data)
+        public
+        virtual
+        override(ERC1155Upgradeable, IERC1155)
+    {
+        _validateExecuteBySelf();
+        super.safeBatchTransferFrom(from, to, ids, values, data);
+    }
+
+    /**
+     * @notice Mint tokens to an account (callable only by this contract via GuardController)
+     * @param to Recipient address
+     * @param id Token type ID
+     * @param value Amount to mint
+     * @param data Additional data for recipient hook
+     */
+    function mint(address to, uint256 id, uint256 value, bytes memory data) external virtual {
+        _validateExecuteBySelf();
+        _mint(to, id, value, data);
+    }
+
+    /**
+     * @notice Mint batch of tokens (callable only by this contract via GuardController)
+     * @param to Recipient address
+     * @param ids Token type IDs
+     * @param values Amounts to mint
+     * @param data Additional data for recipient hook
+     */
+    function mintBatch(address to, uint256[] memory ids, uint256[] memory values, bytes memory data) external virtual {
+        _validateExecuteBySelf();
+        _mintBatch(to, ids, values, data);
+    }
+
+    /**
+     * @notice Burn tokens from an account (callable only by this contract via GuardController)
+     * @param account Account to burn from
+     * @param id Token type ID
+     * @param value Amount to burn
+     */
+    function burn(address account, uint256 id, uint256 value) public virtual override(ERC1155BurnableUpgradeable) {
+        _validateExecuteBySelf();
+        super.burn(account, id, value);
+    }
+
+    /**
+     * @notice Burn batch of tokens (callable only by this contract via GuardController)
+     * @param account Account to burn from
+     * @param ids Token type IDs
+     * @param values Amounts to burn
+     */
+    function burnBatch(address account, uint256[] memory ids, uint256[] memory values)
+        public
+        virtual
+        override(ERC1155BurnableUpgradeable)
+    {
+        _validateExecuteBySelf();
+        super.burnBatch(account, ids, values);
+    }
+
+    function supportsInterface(bytes4 interfaceId)
+        public
+        view
+        virtual
+        override(ERC1155Upgradeable, SecureOwnable, RuntimeRBAC, GuardController, IERC165)
+        returns (bool)
+    {
+        return interfaceId == type(IERC1155).interfaceId || super.supportsInterface(interfaceId) || GuardController.supportsInterface(interfaceId);
+    }
+}

package/core/research/erc1155-blox/lib/definitions/ERC1155BloxDefinitions.sol

@@ -0,0 +1,203 @@
+// SPDX-License-Identifier: MPL-2.0
+pragma solidity 0.8.33;
+
+import "../../../../lib/EngineBlox.sol";
+import "../../../../lib/interfaces/IDefinition.sol";
+
+/**
+ * @title ERC1155BloxDefinitions
+ * @dev Definition library for ERC1155Blox execution selectors (safeTransferFrom, safeBatchTransferFrom, mint, mintBatch, burn, burnBatch).
+ * Registers function schemas and role permissions so the GuardController can execute these functions
+ * via time-lock and meta-transaction workflows.
+ * @custom:security-contact security@particlecrypto.com
+ */
+library ERC1155BloxDefinitions {
+
+    // System macro selectors (allowed to target address(this) for GuardController execution)
+    bytes4 public constant SAFE_TRANSFER_FROM_SELECTOR = bytes4(keccak256("safeTransferFrom(address,address,uint256,uint256,bytes)"));
+    bytes4 public constant SAFE_BATCH_TRANSFER_FROM_SELECTOR = bytes4(keccak256("safeBatchTransferFrom(address,address,uint256[],uint256[],bytes)"));
+    bytes4 public constant MINT_SELECTOR = bytes4(keccak256("mint(address,uint256,uint256,bytes)"));
+    bytes4 public constant MINT_BATCH_SELECTOR = bytes4(keccak256("mintBatch(address,uint256[],uint256[],bytes)"));
+    bytes4 public constant BURN_SELECTOR = bytes4(keccak256("burn(address,uint256,uint256)"));
+    bytes4 public constant BURN_BATCH_SELECTOR = bytes4(keccak256("burnBatch(address,uint256[],uint256[])"));
+
+    bytes32 public constant ERC1155_OPERATION = keccak256("ERC1155_OPERATION");
+
+    /**
+     * @dev Returns function schemas for ERC1155Blox execution selectors (used by controller).
+     */
+    function getFunctionSchemas() public pure returns (EngineBlox.FunctionSchema[] memory) {
+        EngineBlox.FunctionSchema[] memory schemas = new EngineBlox.FunctionSchema[](6);
+
+        EngineBlox.TxAction[] memory timeDelayRequestActions = new EngineBlox.TxAction[](1);
+        timeDelayRequestActions[0] = EngineBlox.TxAction.EXECUTE_TIME_DELAY_REQUEST;
+        EngineBlox.TxAction[] memory timeDelayApproveActions = new EngineBlox.TxAction[](1);
+        timeDelayApproveActions[0] = EngineBlox.TxAction.EXECUTE_TIME_DELAY_APPROVE;
+        EngineBlox.TxAction[] memory timeDelayCancelActions = new EngineBlox.TxAction[](1);
+        timeDelayCancelActions[0] = EngineBlox.TxAction.EXECUTE_TIME_DELAY_CANCEL;
+        EngineBlox.TxAction[] memory metaTxRequestApproveActions = new EngineBlox.TxAction[](2);
+        metaTxRequestApproveActions[0] = EngineBlox.TxAction.SIGN_META_REQUEST_AND_APPROVE;
+        metaTxRequestApproveActions[1] = EngineBlox.TxAction.EXECUTE_META_REQUEST_AND_APPROVE;
+        EngineBlox.TxAction[] memory metaTxApproveActions = new EngineBlox.TxAction[](2);
+        metaTxApproveActions[0] = EngineBlox.TxAction.SIGN_META_APPROVE;
+        metaTxApproveActions[1] = EngineBlox.TxAction.EXECUTE_META_APPROVE;
+        EngineBlox.TxAction[] memory metaTxCancelActions = new EngineBlox.TxAction[](2);
+        metaTxCancelActions[0] = EngineBlox.TxAction.SIGN_META_CANCEL;
+        metaTxCancelActions[1] = EngineBlox.TxAction.EXECUTE_META_CANCEL;
+
+        uint16 actionsBitmap = EngineBlox.createBitmapFromActions(timeDelayRequestActions)
+            | EngineBlox.createBitmapFromActions(timeDelayApproveActions)
+            | EngineBlox.createBitmapFromActions(timeDelayCancelActions)
+            | EngineBlox.createBitmapFromActions(metaTxRequestApproveActions)
+            | EngineBlox.createBitmapFromActions(metaTxApproveActions)
+            | EngineBlox.createBitmapFromActions(metaTxCancelActions);
+
+        bytes4[] memory safeTransferFromHandlers = new bytes4[](1);
+        safeTransferFromHandlers[0] = SAFE_TRANSFER_FROM_SELECTOR;
+        bytes4[] memory safeBatchTransferFromHandlers = new bytes4[](1);
+        safeBatchTransferFromHandlers[0] = SAFE_BATCH_TRANSFER_FROM_SELECTOR;
+        bytes4[] memory mintHandlers = new bytes4[](1);
+        mintHandlers[0] = MINT_SELECTOR;
+        bytes4[] memory mintBatchHandlers = new bytes4[](1);
+        mintBatchHandlers[0] = MINT_BATCH_SELECTOR;
+        bytes4[] memory burnHandlers = new bytes4[](1);
+        burnHandlers[0] = BURN_SELECTOR;
+        bytes4[] memory burnBatchHandlers = new bytes4[](1);
+        burnBatchHandlers[0] = BURN_BATCH_SELECTOR;
+
+        schemas[0] = EngineBlox.FunctionSchema({
+            functionSignature: "safeTransferFrom(address,address,uint256,uint256,bytes)",
+            functionSelector: SAFE_TRANSFER_FROM_SELECTOR,
+            operationType: ERC1155_OPERATION,
+            operationName: "ERC1155_SAFE_TRANSFER_FROM",
+            supportedActionsBitmap: actionsBitmap,
+            isProtected: true,
+            handlerForSelectors: safeTransferFromHandlers
+        });
+        schemas[1] = EngineBlox.FunctionSchema({
+            functionSignature: "safeBatchTransferFrom(address,address,uint256[],uint256[],bytes)",
+            functionSelector: SAFE_BATCH_TRANSFER_FROM_SELECTOR,
+            operationType: ERC1155_OPERATION,
+            operationName: "ERC1155_SAFE_BATCH_TRANSFER_FROM",
+            supportedActionsBitmap: actionsBitmap,
+            isProtected: true,
+            handlerForSelectors: safeBatchTransferFromHandlers
+        });
+        schemas[2] = EngineBlox.FunctionSchema({
+            functionSignature: "mint(address,uint256,uint256,bytes)",
+            functionSelector: MINT_SELECTOR,
+            operationType: ERC1155_OPERATION,
+            operationName: "ERC1155_MINT",
+            supportedActionsBitmap: actionsBitmap,
+            isProtected: true,
+            handlerForSelectors: mintHandlers
+        });
+        schemas[3] = EngineBlox.FunctionSchema({
+            functionSignature: "mintBatch(address,uint256[],uint256[],bytes)",
+            functionSelector: MINT_BATCH_SELECTOR,
+            operationType: ERC1155_OPERATION,
+            operationName: "ERC1155_MINT_BATCH",
+            supportedActionsBitmap: actionsBitmap,
+            isProtected: true,
+            handlerForSelectors: mintBatchHandlers
+        });
+        schemas[4] = EngineBlox.FunctionSchema({
+            functionSignature: "burn(address,uint256,uint256)",
+            functionSelector: BURN_SELECTOR,
+            operationType: ERC1155_OPERATION,
+            operationName: "ERC1155_BURN",
+            supportedActionsBitmap: actionsBitmap,
+            isProtected: true,
+            handlerForSelectors: burnHandlers
+        });
+        schemas[5] = EngineBlox.FunctionSchema({
+            functionSignature: "burnBatch(address,uint256[],uint256[])",
+            functionSelector: BURN_BATCH_SELECTOR,
+            operationType: ERC1155_OPERATION,
+            operationName: "ERC1155_BURN_BATCH",
+            supportedActionsBitmap: actionsBitmap,
+            isProtected: true,
+            handlerForSelectors: burnBatchHandlers
+        });
+
+        return schemas;
+    }
+
+    /**
+     * @dev Returns role permissions for ERC1155Blox execution selectors (OWNER and BROADCASTER).
+     */
+    function getRolePermissions() public pure returns (IDefinition.RolePermission memory) {
+        bytes32[] memory roleHashes = new bytes32[](12);
+        EngineBlox.FunctionPermission[] memory functionPermissions = new EngineBlox.FunctionPermission[](12);
+
+        EngineBlox.TxAction[] memory ownerTimeLockRequest = new EngineBlox.TxAction[](1);
+        ownerTimeLockRequest[0] = EngineBlox.TxAction.EXECUTE_TIME_DELAY_REQUEST;
+        EngineBlox.TxAction[] memory ownerTimeLockApprove = new EngineBlox.TxAction[](1);
+        ownerTimeLockApprove[0] = EngineBlox.TxAction.EXECUTE_TIME_DELAY_APPROVE;
+        EngineBlox.TxAction[] memory ownerTimeLockCancel = new EngineBlox.TxAction[](1);
+        ownerTimeLockCancel[0] = EngineBlox.TxAction.EXECUTE_TIME_DELAY_CANCEL;
+        EngineBlox.TxAction[] memory ownerMetaSign = new EngineBlox.TxAction[](1);
+        ownerMetaSign[0] = EngineBlox.TxAction.SIGN_META_REQUEST_AND_APPROVE;
+        EngineBlox.TxAction[] memory ownerMetaApprove = new EngineBlox.TxAction[](1);
+        ownerMetaApprove[0] = EngineBlox.TxAction.SIGN_META_APPROVE;
+        EngineBlox.TxAction[] memory ownerMetaCancel = new EngineBlox.TxAction[](1);
+        ownerMetaCancel[0] = EngineBlox.TxAction.SIGN_META_CANCEL;
+        EngineBlox.TxAction[] memory broadcasterMetaExec = new EngineBlox.TxAction[](1);
+        broadcasterMetaExec[0] = EngineBlox.TxAction.EXECUTE_META_REQUEST_AND_APPROVE;
+        EngineBlox.TxAction[] memory broadcasterMetaApprove = new EngineBlox.TxAction[](1);
+        broadcasterMetaApprove[0] = EngineBlox.TxAction.EXECUTE_META_APPROVE;
+        EngineBlox.TxAction[] memory broadcasterMetaCancel = new EngineBlox.TxAction[](1);
+        broadcasterMetaCancel[0] = EngineBlox.TxAction.EXECUTE_META_CANCEL;
+
+        uint16 ownerBitmap = EngineBlox.createBitmapFromActions(ownerTimeLockRequest)
+            | EngineBlox.createBitmapFromActions(ownerTimeLockApprove)
+            | EngineBlox.createBitmapFromActions(ownerTimeLockCancel)
+            | EngineBlox.createBitmapFromActions(ownerMetaSign)
+            | EngineBlox.createBitmapFromActions(ownerMetaApprove)
+            | EngineBlox.createBitmapFromActions(ownerMetaCancel);
+        uint16 broadcasterBitmap = EngineBlox.createBitmapFromActions(broadcasterMetaExec)
+            | EngineBlox.createBitmapFromActions(broadcasterMetaApprove)
+            | EngineBlox.createBitmapFromActions(broadcasterMetaCancel);
+
+        bytes4[6] memory selectors = [
+            SAFE_TRANSFER_FROM_SELECTOR,
+            SAFE_BATCH_TRANSFER_FROM_SELECTOR,
+            MINT_SELECTOR,
+            MINT_BATCH_SELECTOR,
+            BURN_SELECTOR,
+            BURN_BATCH_SELECTOR
+        ];
+        for (uint256 i = 0; i < 6; i++) {
+            bytes4[] memory selfRef = new bytes4[](1);
+            selfRef[0] = selectors[i];
+            roleHashes[i] = EngineBlox.OWNER_ROLE;
+            functionPermissions[i] = EngineBlox.FunctionPermission({
+                functionSelector: selectors[i],
+                grantedActionsBitmap: ownerBitmap,
+                handlerForSelectors: selfRef
+            });
+        }
+        for (uint256 i = 0; i < 6; i++) {
+            bytes4[] memory selfRef = new bytes4[](1);
+            selfRef[0] = selectors[i];
+            roleHashes[6 + i] = EngineBlox.BROADCASTER_ROLE;
+            functionPermissions[6 + i] = EngineBlox.FunctionPermission({
+                functionSelector: selectors[i],
+                grantedActionsBitmap: broadcasterBitmap,
+                handlerForSelectors: selfRef
+            });
+        }
+
+        return IDefinition.RolePermission({
+            roleHashes: roleHashes,
+            functionPermissions: functionPermissions
+        });
+    }
+
+    /**
+     * @dev ERC165: report support for IDefinition when this library is used at an address
+     */
+    function supportsInterface(bytes4 interfaceId) external pure returns (bool) {
+        return interfaceId == type(IDefinition).interfaceId;
+    }
+}

package/core/research/erc20-blox/ERC20Blox.sol

@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2025 Particle Crypto Security
+pragma solidity 0.8.33;
+
+// OpenZeppelin
+import "@openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol";
+import "@openzeppelin/contracts-upgradeable/token/ERC20/extensions/ERC20BurnableUpgradeable.sol";
+import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+
+// Core
+import "../../pattern/Account.sol";
+import "../../lib/interfaces/IDefinition.sol";
+import "../../lib/utils/SharedValidation.sol";
+import "./lib/definitions/ERC20BloxDefinitions.sol";
+
+// Standards
+import "../../../standards/behavior/ICopyable.sol";
+
+/**
+ * @title ERC20Blox
+ * @dev ERC20 token (IERC20) with Account pattern and ICopyable for cloning.
+ * Exposes transfer (ERC20), mint (owner-only), and burn (ERC20Burnable).
+ * @custom:security-contact security@particlecrypto.com
+ */
+contract ERC20Blox is
+    IERC20,
+    ICopyable,
+    ERC20Upgradeable,
+    ERC20BurnableUpgradeable,
+    Account
+{
+    /// @custom:oz-upgrades-unsafe-allow constructor
+    constructor() {
+        _disableInitializers();
+    }
+
+    /**
+     * @dev ICopyable: full init with custom data. initData must be abi.encode(name, symbol).
+     * Runs Account init, ERC20Blox definitions, and ERC20 name/symbol in one step.
+     */
+    function initializeWithData(
+        address initialOwner,
+        address broadcaster,
+        address recovery,
+        uint256 timeLockPeriodSec,
+        address eventForwarder,
+        bytes calldata initData
+    ) external virtual initializer {
+        super.initialize(initialOwner, broadcaster, recovery, timeLockPeriodSec, eventForwarder);
+        
+        IDefinition.RolePermission memory erc20Permissions = ERC20BloxDefinitions.getRolePermissions();
+        _loadDefinitions(
+            ERC20BloxDefinitions.getFunctionSchemas(),
+            erc20Permissions.roleHashes,
+            erc20Permissions.functionPermissions,
+            true
+        );
+        
+        // Add macro selectors for the ERC20Blox definitions
+        _addMacroSelector(ERC20BloxDefinitions.TRANSFER_SELECTOR);
+        _addMacroSelector(ERC20BloxDefinitions.TRANSFER_FROM_SELECTOR);
+        _addMacroSelector(ERC20BloxDefinitions.MINT_SELECTOR);
+        _addMacroSelector(ERC20BloxDefinitions.BURN_SELECTOR);
+        _addMacroSelector(ERC20BloxDefinitions.BURN_FROM_SELECTOR);
+        (string memory name, string memory symbol) = abi.decode(initData, (string, string));
+        __ERC20_init(name, symbol);
+    }
+
+    /**
+     * @notice Transfer tokens to an account (callable only by this contract via GuardController)
+     * @param to Recipient address
+     * @param value Amount to transfer
+     */
+    function transfer(address to, uint256 value) public virtual override(ERC20Upgradeable, IERC20) returns (bool) {
+        _validateExecuteBySelf();
+        return super.transfer(to, value);
+    }
+
+    /**
+     * @notice Transfer tokens from one account to another (with allowance); callable only by this contract via GuardController
+     * @param from Sender address
+     * @param to Recipient address
+     * @param value Amount to transfer
+     */
+    function transferFrom(address from, address to, uint256 value) public virtual override(ERC20Upgradeable, IERC20) returns (bool) {
+        _validateExecuteBySelf();
+        return super.transferFrom(from, to, value);
+    }
+
+    /**
+     * @notice Mint tokens to an account (callable only by this contract via GuardController)
+     * @param to Recipient address
+     * @param amount Amount to mint
+     */
+    function mint(address to, uint256 amount) external virtual {
+        _validateExecuteBySelf();
+        _mint(to, amount);
+    }
+
+    /**
+     * @notice Burn tokens from caller (callable only by this contract via GuardController)
+     * @param value Amount to burn
+     */
+    function burn(uint256 value) public virtual override(ERC20BurnableUpgradeable) {
+        _validateExecuteBySelf();
+        super.burn(value);
+    }
+
+    /**
+     * @notice Burn tokens from an account (with allowance); callable only by this contract via GuardController
+     * @param account Account to burn from
+     * @param value Amount to burn
+     */
+    function burnFrom(address account, uint256 value) public virtual override(ERC20BurnableUpgradeable) {
+        _validateExecuteBySelf();
+        super.burnFrom(account, value);
+    }
+
+    function supportsInterface(bytes4 interfaceId) public view virtual override(Account) returns (bool) {
+        return interfaceId == type(IERC20).interfaceId || interfaceId == type(ICopyable).interfaceId || super.supportsInterface(interfaceId);
+    }
+
+    /**
+     * @dev Base initialization (5 params only) is disallowed; use initializeWithData(..., initData) with abi.encode(name, symbol).
+     */
+    function initialize(
+        address initialOwner,
+        address broadcaster,
+        address recovery,
+        uint256 timeLockPeriodSec,
+        address eventForwarder
+    ) public virtual override(Account) initializer {
+        revert SharedValidation.NotSupported();
+    }
+}