@bloxchain/contracts 1.0.0-alpha.2 → 1.0.0-alpha.20

package/core/security/interface/ISecureOwnable.sol

@@ -1,104 +1,105 @@
-// SPDX-License-Identifier: MPL-2.0
-pragma solidity 0.8.33;
-
-// Contracts imports
-import "../../lib/EngineBlox.sol";
-
-/**
- * @title ISecureOwnable
- * @dev Interface for SecureOwnable functionality
- * @notice This interface defines SecureOwnable-specific operations
- * @notice Note: owner(), getBroadcasters(), and getRecovery() are available through BaseStateMachine
- */
-interface ISecureOwnable {
-    // ============ OWNERSHIP MANAGEMENT ============
-
-    /**
-     * @dev Requests a transfer of ownership
-     * @return The transaction record
-     */
-    function transferOwnershipRequest() external returns (EngineBlox.TxRecord memory);
-
-    /**
-     * @dev Approves a pending ownership transfer transaction after the release time
-     * @param txId The transaction ID
-     * @return The updated transaction record
-     */
-    function transferOwnershipDelayedApproval(uint256 txId) external returns (EngineBlox.TxRecord memory);
-
-    /**
-     * @dev Approves a pending ownership transfer transaction using a meta-transaction
-     * @param metaTx The meta-transaction
-     * @return The updated transaction record
-     */
-    function transferOwnershipApprovalWithMetaTx(EngineBlox.MetaTransaction memory metaTx) external returns (EngineBlox.TxRecord memory);
-
-    /**
-     * @dev Cancels a pending ownership transfer transaction
-     * @param txId The transaction ID
-     * @return The updated transaction record
-     */
-    function transferOwnershipCancellation(uint256 txId) external returns (EngineBlox.TxRecord memory);
-
-    /**
-     * @dev Cancels a pending ownership transfer transaction using a meta-transaction
-     * @param metaTx The meta-transaction
-     * @return The updated transaction record
-     */
-    function transferOwnershipCancellationWithMetaTx(EngineBlox.MetaTransaction memory metaTx) external returns (EngineBlox.TxRecord memory);
-
-    // ============ BROADCASTER MANAGEMENT ============
-
-    /**
-     * @dev Updates the broadcaster address
-     * @param newBroadcaster The new broadcaster address
-     * @return The transaction record
-     */
-    function updateBroadcasterRequest(address newBroadcaster) external returns (EngineBlox.TxRecord memory);
-
-    /**
-     * @dev Approves a pending broadcaster update transaction after the release time
-     * @param txId The transaction ID
-     * @return The updated transaction record
-     */
-    function updateBroadcasterDelayedApproval(uint256 txId) external returns (EngineBlox.TxRecord memory);
-
-    /**
-     * @dev Approves a pending broadcaster update transaction using a meta-transaction
-     * @param metaTx The meta-transaction
-     * @return The updated transaction record
-     */
-    function updateBroadcasterApprovalWithMetaTx(EngineBlox.MetaTransaction memory metaTx) external returns (EngineBlox.TxRecord memory);
-
-    /**
-     * @dev Cancels a pending broadcaster update transaction
-     * @param txId The transaction ID
-     * @return The updated transaction record
-     */
-    function updateBroadcasterCancellation(uint256 txId) external returns (EngineBlox.TxRecord memory);
-
-    /**
-     * @dev Cancels a pending broadcaster update transaction using a meta-transaction
-     * @param metaTx The meta-transaction
-     * @return The updated transaction record
-     */
-    function updateBroadcasterCancellationWithMetaTx(EngineBlox.MetaTransaction memory metaTx) external returns (EngineBlox.TxRecord memory);
-
-    // ============ RECOVERY MANAGEMENT ============
-
-    /**
-     * @dev Requests and approves a recovery address update using a meta-transaction
-     * @param metaTx The meta-transaction
-     * @return The transaction record
-     */
-    function updateRecoveryRequestAndApprove(EngineBlox.MetaTransaction memory metaTx) external returns (EngineBlox.TxRecord memory);
-
-    // ============ TIMELOCK MANAGEMENT ============
-
-    /**
-     * @dev Requests and approves a time lock period update using a meta-transaction
-     * @param metaTx The meta-transaction
-     * @return The transaction record
-     */
-    function updateTimeLockRequestAndApprove(EngineBlox.MetaTransaction memory metaTx) external returns (EngineBlox.TxRecord memory);
-}
+// SPDX-License-Identifier: MPL-2.0
+pragma solidity 0.8.34;
+
+// Contracts imports
+import "../../lib/EngineBlox.sol";
+
+/**
+ * @title ISecureOwnable
+ * @dev Interface for SecureOwnable functionality
+ * @notice This interface defines SecureOwnable-specific operations
+ * @notice Note: owner(), getBroadcasters(), and getRecovery() are available through BaseStateMachine
+ */
+interface ISecureOwnable {
+    // ============ OWNERSHIP MANAGEMENT ============
+
+    /**
+     * @dev Requests a transfer of ownership
+     * @return txId The transaction ID (use getTransaction(txId) for full record)
+     */
+    function transferOwnershipRequest() external returns (uint256 txId);
+
+    /**
+     * @dev Approves a pending ownership transfer transaction after the release time
+     * @param txId The transaction ID
+     * @return The transaction ID (use getTransaction(txId) for full record)
+     */
+    function transferOwnershipDelayedApproval(uint256 txId) external returns (uint256);
+
+    /**
+     * @dev Approves a pending ownership transfer transaction using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The transaction ID (use getTransaction(txId) for full record)
+     */
+    function transferOwnershipApprovalWithMetaTx(EngineBlox.MetaTransaction memory metaTx) external returns (uint256);
+
+    /**
+     * @dev Cancels a pending ownership transfer transaction
+     * @param txId The transaction ID
+     * @return The transaction ID (use getTransaction(txId) for full record)
+     */
+    function transferOwnershipCancellation(uint256 txId) external returns (uint256);
+
+    /**
+     * @dev Cancels a pending ownership transfer transaction using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The transaction ID (use getTransaction(txId) for full record)
+     */
+    function transferOwnershipCancellationWithMetaTx(EngineBlox.MetaTransaction memory metaTx) external returns (uint256);
+
+    // ============ BROADCASTER MANAGEMENT ============
+
+    /**
+     * @dev Requests an update to the broadcaster at a specific location (index).
+     * @param newBroadcaster The new broadcaster address (zero address to revoke at location)
+     * @param location The index in the broadcaster role's authorized wallets set
+     * @return txId The transaction ID (use getTransaction(txId) for full record)
+     */
+    function updateBroadcasterRequest(address newBroadcaster, uint256 location) external returns (uint256 txId);
+
+    /**
+     * @dev Approves a pending broadcaster update transaction after the release time
+     * @param txId The transaction ID
+     * @return The transaction ID (use getTransaction(txId) for full record)
+     */
+    function updateBroadcasterDelayedApproval(uint256 txId) external returns (uint256);
+
+    /**
+     * @dev Approves a pending broadcaster update transaction using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The transaction ID (use getTransaction(txId) for full record)
+     */
+    function updateBroadcasterApprovalWithMetaTx(EngineBlox.MetaTransaction memory metaTx) external returns (uint256);
+
+    /**
+     * @dev Cancels a pending broadcaster update transaction
+     * @param txId The transaction ID
+     * @return The transaction ID (use getTransaction(txId) for full record)
+     */
+    function updateBroadcasterCancellation(uint256 txId) external returns (uint256);
+
+    /**
+     * @dev Cancels a pending broadcaster update transaction using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The transaction ID (use getTransaction(txId) for full record)
+     */
+    function updateBroadcasterCancellationWithMetaTx(EngineBlox.MetaTransaction memory metaTx) external returns (uint256);
+
+    // ============ RECOVERY MANAGEMENT ============
+
+    /**
+     * @dev Requests and approves a recovery address update using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The transaction ID (use getTransaction(txId) for full record)
+     */
+    function updateRecoveryRequestAndApprove(EngineBlox.MetaTransaction memory metaTx) external returns (uint256);
+
+    // ============ TIMELOCK MANAGEMENT ============
+
+    /**
+     * @dev Requests and approves a time lock period update using a meta-transaction
+     * @param metaTx The meta-transaction
+     * @return The transaction ID (use getTransaction(txId) for full record)
+     */
+    function updateTimeLockRequestAndApprove(EngineBlox.MetaTransaction memory metaTx) external returns (uint256);
+}

package/core/security/lib/definitions/SecureOwnableDefinitions.sol

@@ -1,9 +1,9 @@
 // SPDX-License-Identifier: MPL-2.0
-pragma solidity 0.8.33;
+pragma solidity 0.8.34;
 
 import "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 import "../../../lib/EngineBlox.sol";
-import "../../../../interfaces/IDefinition.sol";
+import "../../../lib/interfaces/IDefinition.sol";
 
 /**
  * @title SecureOwnableDefinitions
@@ -32,7 +32,7 @@ library SecureOwnableDefinitions {
     
     // Function Selector Constants
     bytes4 public constant TRANSFER_OWNERSHIP_SELECTOR = bytes4(keccak256("executeTransferOwnership(address)"));
-    bytes4 public constant UPDATE_BROADCASTER_SELECTOR = bytes4(keccak256("executeBroadcasterUpdate(address)"));
+    bytes4 public constant UPDATE_BROADCASTER_SELECTOR = bytes4(keccak256("executeBroadcasterUpdate(address,uint256)"));
     bytes4 public constant UPDATE_RECOVERY_SELECTOR = bytes4(keccak256("executeRecoveryUpdate(address)"));
     bytes4 public constant UPDATE_TIMELOCK_SELECTOR = bytes4(keccak256("executeTimeLockUpdate(uint256)"));
     
@@ -40,7 +40,7 @@ library SecureOwnableDefinitions {
     bytes4 public constant TRANSFER_OWNERSHIP_REQUEST_SELECTOR = bytes4(keccak256("transferOwnershipRequest()"));
     bytes4 public constant TRANSFER_OWNERSHIP_DELAYED_APPROVAL_SELECTOR = bytes4(keccak256("transferOwnershipDelayedApproval(uint256)"));
     bytes4 public constant TRANSFER_OWNERSHIP_CANCELLATION_SELECTOR = bytes4(keccak256("transferOwnershipCancellation(uint256)"));
-    bytes4 public constant UPDATE_BROADCASTER_REQUEST_SELECTOR = bytes4(keccak256("updateBroadcasterRequest(address)"));
+    bytes4 public constant UPDATE_BROADCASTER_REQUEST_SELECTOR = bytes4(keccak256("updateBroadcasterRequest(address,uint256)"));
     bytes4 public constant UPDATE_BROADCASTER_DELAYED_APPROVAL_SELECTOR = bytes4(keccak256("updateBroadcasterDelayedApproval(uint256)"));
     bytes4 public constant UPDATE_BROADCASTER_CANCELLATION_SELECTOR = bytes4(keccak256("updateBroadcasterCancellation(uint256)"));
     
@@ -128,6 +128,7 @@ library SecureOwnableDefinitions {
             operationType: OWNERSHIP_TRANSFER,
             operationName: "OWNERSHIP_TRANSFER",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(metaApproveActions),
+            enforceHandlerRelations: true,
             isProtected: true,
             handlerForSelectors: transferOwnershipHandlerForSelectors
         });
@@ -138,6 +139,7 @@ library SecureOwnableDefinitions {
             operationType: OWNERSHIP_TRANSFER,
             operationName: "OWNERSHIP_TRANSFER",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(metaCancelActions),
+            enforceHandlerRelations: true,
             isProtected: true,
             handlerForSelectors: transferOwnershipHandlerForSelectors
         });
@@ -148,6 +150,7 @@ library SecureOwnableDefinitions {
             operationType: BROADCASTER_UPDATE,
             operationName: "BROADCASTER_UPDATE",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(metaApproveActions),
+            enforceHandlerRelations: true,
             isProtected: true,
             handlerForSelectors: broadcasterHandlerForSelectors
         });
@@ -158,6 +161,7 @@ library SecureOwnableDefinitions {
             operationType: BROADCASTER_UPDATE,
             operationName: "BROADCASTER_UPDATE",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(metaCancelActions),
+            enforceHandlerRelations: true,
             isProtected: true,
             handlerForSelectors: broadcasterHandlerForSelectors
         });
@@ -168,6 +172,7 @@ library SecureOwnableDefinitions {
             operationType: RECOVERY_UPDATE,
             operationName: "RECOVERY_UPDATE",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(metaRequestApproveActions),
+            enforceHandlerRelations: true,
             isProtected: true,
             handlerForSelectors: recoveryHandlerForSelectors
         });
@@ -178,6 +183,7 @@ library SecureOwnableDefinitions {
             operationType: TIMELOCK_UPDATE,
             operationName: "TIMELOCK_UPDATE",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(metaRequestApproveActions),
+            enforceHandlerRelations: true,
             isProtected: true,
             handlerForSelectors: timelockHandlerForSelectors
         });
@@ -189,6 +195,7 @@ library SecureOwnableDefinitions {
             operationType: OWNERSHIP_TRANSFER,
             operationName: "OWNERSHIP_TRANSFER",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(timeDelayRequestActions),
+            enforceHandlerRelations: true,
             isProtected: true,
             handlerForSelectors: transferOwnershipHandlerForSelectors
         });
@@ -199,6 +206,7 @@ library SecureOwnableDefinitions {
             operationType: OWNERSHIP_TRANSFER,
             operationName: "OWNERSHIP_TRANSFER",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(timeDelayApproveActions),
+            enforceHandlerRelations: true,
             isProtected: true,
             handlerForSelectors: transferOwnershipHandlerForSelectors
         });
@@ -209,16 +217,18 @@ library SecureOwnableDefinitions {
             operationType: OWNERSHIP_TRANSFER,
             operationName: "OWNERSHIP_TRANSFER",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(timeDelayCancelActions),
+            enforceHandlerRelations: true,
             isProtected: true,
             handlerForSelectors: transferOwnershipHandlerForSelectors
         });
         
         schemas[9] = EngineBlox.FunctionSchema({
-            functionSignature: "updateBroadcasterRequest(address)",
+            functionSignature: "updateBroadcasterRequest(address,uint256)",
             functionSelector: UPDATE_BROADCASTER_REQUEST_SELECTOR,
             operationType: BROADCASTER_UPDATE,
             operationName: "BROADCASTER_UPDATE",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(timeDelayRequestActions),
+            enforceHandlerRelations: true,
             isProtected: true,
             handlerForSelectors: broadcasterHandlerForSelectors
         });
@@ -229,6 +239,7 @@ library SecureOwnableDefinitions {
             operationType: BROADCASTER_UPDATE,
             operationName: "BROADCASTER_UPDATE",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(timeDelayApproveActions),
+            enforceHandlerRelations: true,
             isProtected: true,
             handlerForSelectors: broadcasterHandlerForSelectors
         });
@@ -239,6 +250,7 @@ library SecureOwnableDefinitions {
             operationType: BROADCASTER_UPDATE,
             operationName: "BROADCASTER_UPDATE",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(timeDelayCancelActions),
+            enforceHandlerRelations: true,
             isProtected: true,
             handlerForSelectors: broadcasterHandlerForSelectors
         });
@@ -251,16 +263,18 @@ library SecureOwnableDefinitions {
             operationType: OWNERSHIP_TRANSFER,
             operationName: "OWNERSHIP_TRANSFER",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(executionApproveCancelActions),
+            enforceHandlerRelations: true,
             isProtected: true,
             handlerForSelectors: transferOwnershipExecutionHandlerForSelectors
         });
         
         schemas[13] = EngineBlox.FunctionSchema({
-            functionSignature: "executeBroadcasterUpdate(address)",
+            functionSignature: "executeBroadcasterUpdate(address,uint256)",
             functionSelector: UPDATE_BROADCASTER_SELECTOR,
             operationType: BROADCASTER_UPDATE,
             operationName: "BROADCASTER_UPDATE",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(executionApproveCancelActions),
+            enforceHandlerRelations: true,
             isProtected: true,
             handlerForSelectors: broadcasterExecutionHandlerForSelectors
         });
@@ -271,6 +285,7 @@ library SecureOwnableDefinitions {
             operationType: RECOVERY_UPDATE,
             operationName: "RECOVERY_UPDATE",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(executionMetaRequestApproveActions),
+            enforceHandlerRelations: true,
             isProtected: true,
             handlerForSelectors: recoveryExecutionHandlerForSelectors
         });
@@ -281,6 +296,7 @@ library SecureOwnableDefinitions {
             operationType: TIMELOCK_UPDATE,
             operationName: "TIMELOCK_UPDATE",
             supportedActionsBitmap: EngineBlox.createBitmapFromActions(executionMetaRequestApproveActions),
+            enforceHandlerRelations: true,
             isProtected: true,
             handlerForSelectors: timelockExecutionHandlerForSelectors
         });

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@bloxchain/contracts",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.20",
   "description": "Library engine for building enterprise grade decentralized permissioned applications",
   "files": [
     "core",
-    "utils",
-    "interfaces",
     "abi",
+    "standards",
+    "components",
     "README.md"
   ],
   "scripts": {
@@ -40,8 +40,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@openzeppelin/contracts": "^5.4.0",
-    "@openzeppelin/contracts-upgradeable": "^5.4.0"
+    "@openzeppelin/contracts": "^5.6.1",
+    "@openzeppelin/contracts-upgradeable": "^5.6.1"
   },
   "engines": {
     "node": ">=18.0.0"

package/standards/README.md

@@ -0,0 +1,12 @@
+# Bloxchain Standards
+
+Protocol-level **interfaces** that define optional behaviors and extension points for Blox contracts. These live outside `core/` so the engine stays minimal and stable.
+
+## Structure
+
+- **behavior/** – Optional behavior interfaces (e.g. cloneable blox). Implementations live in `components/` or `examples/`.
+- **hooks/** – Hook and trigger interfaces used by the system to call into external contracts (e.g. post-action hooks).
+
+## Usage
+
+Contracts in `core/`, `components/`, and `examples/` may depend on these interfaces. New standards should be proposed and reviewed before addition.

package/standards/behavior/ICopyable.sol

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MPL-2.0
+pragma solidity 0.8.34;
+
+/**
+ * @title ICopyable
+ * @dev Interface for blox contracts that support generic cloning with custom init data.
+ *
+ * Bloxes implementing this interface can be cloned by factory patterns (e.g. CopyBlox,
+ * FactoryBlox) and initialized in one call with owner/broadcaster/recovery/timelock/
+ * eventForwarder plus arbitrary init data, or have clone-specific data set
+ *
+ * Use cases:
+ * - Clone and init in one step: factory calls initializeWithData(..., initData).
+ * - Clone with standard init then set clone data: factory calls initializeWithData(...)
+ */
+interface ICopyable {
+    /**
+     * @dev Full initialization with standard blox params and custom init data.
+     * @param initialOwner The initial owner address
+     * @param broadcaster The broadcaster address
+     * @param recovery The recovery address
+     * @param timeLockPeriodSec The timelock period in seconds
+     * @param eventForwarder The event forwarder address (optional, use address(0) to skip)
+     * @param initData Custom initialization data (e.g. ABI-encoded config) for this clone
+     */
+    function initializeWithData(
+        address initialOwner,
+        address broadcaster,
+        address recovery,
+        uint256 timeLockPeriodSec,
+        address eventForwarder,
+        bytes calldata initData
+    ) external;
+}

package/standards/hooks/IOnActionHook.sol

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: MPL-2.0
+pragma solidity 0.8.34;
+
+import "../../core/lib/EngineBlox.sol";
+
+/**
+ * @title IOnActionHook
+ * @dev Minimal interface for external hook contracts attached to state machine actions.
+ *
+ * @notice This interface is intentionally small to keep overall contract size low.
+ * @notice The state machine calls this single hook after any transaction operation that
+ *         produces a TxRecord, providing a centralized post-action entry point.
+ */
+interface IOnActionHook {
+    /**
+     * @dev Called after any transaction operation that produces a TxRecord.
+     *      This includes request, approve, cancel and meta-tx flows.
+     * @param txRecord The transaction record produced by the operation
+     */
+    function onAction(EngineBlox.TxRecord memory txRecord) external;
+}