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

package/README.md

@@ -1,6 +1,19 @@
 # @bloxchain/contracts
 
-Bloxchain Protocol Smart Contracts - State Abstraction for Blockchain Security
+[![npm version](https://img.shields.io/npm/v/@bloxchain/contracts.svg)](https://www.npmjs.com/package/@bloxchain/contracts)
+[![License: MPL-2.0](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](https://opensource.org/licenses/MPL-2.0)
+[![Solidity](https://img.shields.io/badge/Solidity-0.8.33-blue.svg)](https://soliditylang.org/)
+
+Bloxchain Protocol smart contracts – state abstraction and core components for building on the Bloxchain Protocol.
+
+> **⚠️ EXPERIMENTAL SOFTWARE WARNING**  
+> This package contains experimental smart contract code. While the framework is feature-complete and tested, it is not yet audited for production use. Use at your own risk and do not deploy with real assets without proper security review.
+
+## Requirements
+
+- **Node.js**: >= 18.0.0 (for tooling; Solidity has no runtime dependency)
+- **Solidity**: 0.8.x (0.8.33 recommended)
+- **Compilers**: Foundry, Hardhat, or Truffle
 
 ## Installation
 
@@ -10,40 +23,64 @@ npm install @bloxchain/contracts
 
 ## Usage
 
-Import contracts in your Solidity files:
+Import contracts in your Solidity files. Paths are relative to the package root (`core/`, `utils/`, `interfaces/`):
 
 ```solidity
 import "@bloxchain/contracts/core/base/BaseStateMachine.sol";
 import "@bloxchain/contracts/core/security/SecureOwnable.sol";
 import "@bloxchain/contracts/core/access/RuntimeRBAC.sol";
 import "@bloxchain/contracts/core/execution/GuardController.sol";
+import "@bloxchain/contracts/utils/SharedValidation.sol";
+import "@bloxchain/contracts/interfaces/IDefinition.sol";
 ```
 
+**Foundry**: No remapping needed; the package exposes `core/`, `utils/`, and `interfaces/` at root.  
+**Hardhat / Truffle**: Resolve `@bloxchain/contracts` from `node_modules` as usual.
+
 ## Contracts
 
-### Core Contracts
-- `BaseStateMachine` - Foundation state machine contract
-- `SecureOwnable` - Multi-role security with time-locked operations
-- `RuntimeRBAC` - Dynamic role-based access control
-- `GuardController` - Execution workflows and time-locked transactions
+### Core contracts
+
+| Contract | Description |
+|----------|-------------|
+| `BaseStateMachine` | Foundation state machine for all blox contracts |
+| `SecureOwnable` | Multi-role security with time-locked operations |
+| `RuntimeRBAC` | Dynamic role-based access control |
+| `GuardController` | Execution workflows and time-locked transactions |
 
-### Template Contracts
-- `BareBlox` - Minimal base state machine
-- `SecureBlox` - Basic secure ownership
-- `RoleBlox` - Secure ownership + RBAC
-- `ControlBlox` - Complete execution workflows
-- `MachineBlox` - Full-featured with hooks
+### Templates and examples
 
-### Example Contracts
-- `SimpleVault` - Secure asset management
-- `SimpleRWA20` - Tokenized real-world assets
+Templates (e.g. BareBlox, SecureBlox, ControlBlox) and example applications (SimpleVault, SimpleRWA20) live in the main repository under `contracts/examples/`. They are not included in this npm package. See the [main repo](https://github.com/PracticalParticle/Bloxchain-Protocol) for full documentation and examples.
 
 ## Dependencies
 
-This package requires:
+This package declares:
+
 - `@openzeppelin/contracts`: ^5.4.0
 - `@openzeppelin/contracts-upgradeable`: ^5.4.0
 
+Install them in your project if your tooling does not resolve transitive dependencies.
+
+## Versioning and stability
+
+This package follows [Semantic Versioning](https://semver.org/). Current versions are **alpha** (`1.0.0-alpha.x`). Pre-1.0 releases may introduce breaking changes; we recommend pinning the exact version until the protocol is audited and stable.
+
+## Security
+
+- **Vulnerability reporting**: Do not open public GitHub issues for security vulnerabilities. See the [Security Policy](https://github.com/PracticalParticle/Bloxchain-Protocol/blob/main/SECURITY.md) for reporting instructions (e.g. security@particlecs.com).
+- **Audit status**: Not yet audited. Do not use with mainnet assets without an independent security review.
+
+## Support and links
+
+- **Documentation**: [Bloxchain Protocol README](https://github.com/PracticalParticle/Bloxchain-Protocol#readme)
+- **Issues and feature requests**: [GitHub Issues](https://github.com/PracticalParticle/Bloxchain-Protocol/issues)
+- **Homepage**: [bloxchain.app](https://bloxchain.app/)
+- **Author**: [Particle Crypto Security](https://particlecs.com/)
+
+## Repository
+
+Part of [Bloxchain Protocol](https://github.com/PracticalParticle/Bloxchain-Protocol). For full documentation, architecture, and examples, see the main repository.
+
 ## License
 
-MPL-2.0
+MPL-2.0 (Mozilla Public License 2.0). See the [LICENSE](https://github.com/PracticalParticle/Bloxchain-Protocol/blob/main/LICENSE) file in the main repository.

package/abi/BareBlox.abi.json

@@ -58,122 +58,46 @@
     "type": "error"
   },
   {
-    "anonymous": false,
-    "inputs": [
-      {
-        "indexed": false,
-        "internalType": "uint64",
-        "name": "version",
-        "type": "uint64"
-      }
-    ],
-    "name": "Initialized",
-    "type": "event"
-  },
-  {
-    "anonymous": false,
     "inputs": [
       {
-        "indexed": true,
-        "internalType": "uint256",
-        "name": "txId",
-        "type": "uint256"
-      },
-      {
-        "indexed": true,
         "internalType": "bytes32",
-        "name": "operationType",
+        "name": "resourceId",
         "type": "bytes32"
-      },
-      {
-        "indexed": true,
-        "internalType": "address",
-        "name": "approver",
-        "type": "address"
       }
     ],
-    "name": "TransactionApproved",
-    "type": "event"
-  },
-  {
-    "anonymous": false,
-    "inputs": [
-      {
-        "indexed": true,
-        "internalType": "uint256",
-        "name": "txId",
-        "type": "uint256"
-      },
-      {
-        "indexed": true,
-        "internalType": "bytes32",
-        "name": "operationType",
-        "type": "bytes32"
-      },
-      {
-        "indexed": true,
-        "internalType": "address",
-        "name": "canceller",
-        "type": "address"
-      }
-    ],
-    "name": "TransactionCancelled",
-    "type": "event"
+    "name": "ResourceNotFound",
+    "type": "error"
   },
   {
     "anonymous": false,
     "inputs": [
       {
         "indexed": true,
-        "internalType": "uint256",
-        "name": "txId",
-        "type": "uint256"
-      },
-      {
-        "indexed": true,
-        "internalType": "bytes32",
-        "name": "operationType",
-        "type": "bytes32"
+        "internalType": "bytes4",
+        "name": "functionSelector",
+        "type": "bytes4"
       },
       {
         "indexed": false,
-        "internalType": "bool",
-        "name": "success",
-        "type": "bool"
+        "internalType": "bytes",
+        "name": "data",
+        "type": "bytes"
       }
     ],
-    "name": "TransactionExecuted",
+    "name": "ComponentEvent",
     "type": "event"
   },
   {
     "anonymous": false,
     "inputs": [
-      {
-        "indexed": true,
-        "internalType": "uint256",
-        "name": "txId",
-        "type": "uint256"
-      },
-      {
-        "indexed": true,
-        "internalType": "address",
-        "name": "requester",
-        "type": "address"
-      },
-      {
-        "indexed": true,
-        "internalType": "bytes32",
-        "name": "operationType",
-        "type": "bytes32"
-      },
       {
         "indexed": false,
-        "internalType": "uint256",
-        "name": "releaseTime",
-        "type": "uint256"
+        "internalType": "uint64",
+        "name": "version",
+        "type": "uint64"
       }
     ],
-    "name": "TransactionRequested",
+    "name": "Initialized",
     "type": "event"
   },
   {
@@ -1212,6 +1136,25 @@
     "stateMutability": "view",
     "type": "function"
   },
+  {
+    "inputs": [
+      {
+        "internalType": "bytes32",
+        "name": "roleHash",
+        "type": "bytes32"
+      }
+    ],
+    "name": "getWalletsInRole",
+    "outputs": [
+      {
+        "internalType": "address[]",
+        "name": "",
+        "type": "address[]"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  },
   {
     "inputs": [
       {

package/abi/BaseStateMachine.abi.json

@@ -58,122 +58,46 @@
     "type": "error"
   },
   {
-    "anonymous": false,
-    "inputs": [
-      {
-        "indexed": false,
-        "internalType": "uint64",
-        "name": "version",
-        "type": "uint64"
-      }
-    ],
-    "name": "Initialized",
-    "type": "event"
-  },
-  {
-    "anonymous": false,
     "inputs": [
       {
-        "indexed": true,
-        "internalType": "uint256",
-        "name": "txId",
-        "type": "uint256"
-      },
-      {
-        "indexed": true,
         "internalType": "bytes32",
-        "name": "operationType",
+        "name": "resourceId",
         "type": "bytes32"
-      },
-      {
-        "indexed": true,
-        "internalType": "address",
-        "name": "approver",
-        "type": "address"
       }
     ],
-    "name": "TransactionApproved",
-    "type": "event"
-  },
-  {
-    "anonymous": false,
-    "inputs": [
-      {
-        "indexed": true,
-        "internalType": "uint256",
-        "name": "txId",
-        "type": "uint256"
-      },
-      {
-        "indexed": true,
-        "internalType": "bytes32",
-        "name": "operationType",
-        "type": "bytes32"
-      },
-      {
-        "indexed": true,
-        "internalType": "address",
-        "name": "canceller",
-        "type": "address"
-      }
-    ],
-    "name": "TransactionCancelled",
-    "type": "event"
+    "name": "ResourceNotFound",
+    "type": "error"
   },
   {
     "anonymous": false,
     "inputs": [
       {
         "indexed": true,
-        "internalType": "uint256",
-        "name": "txId",
-        "type": "uint256"
-      },
-      {
-        "indexed": true,
-        "internalType": "bytes32",
-        "name": "operationType",
-        "type": "bytes32"
+        "internalType": "bytes4",
+        "name": "functionSelector",
+        "type": "bytes4"
       },
       {
         "indexed": false,
-        "internalType": "bool",
-        "name": "success",
-        "type": "bool"
+        "internalType": "bytes",
+        "name": "data",
+        "type": "bytes"
       }
     ],
-    "name": "TransactionExecuted",
+    "name": "ComponentEvent",
     "type": "event"
   },
   {
     "anonymous": false,
     "inputs": [
-      {
-        "indexed": true,
-        "internalType": "uint256",
-        "name": "txId",
-        "type": "uint256"
-      },
-      {
-        "indexed": true,
-        "internalType": "address",
-        "name": "requester",
-        "type": "address"
-      },
-      {
-        "indexed": true,
-        "internalType": "bytes32",
-        "name": "operationType",
-        "type": "bytes32"
-      },
       {
         "indexed": false,
-        "internalType": "uint256",
-        "name": "releaseTime",
-        "type": "uint256"
+        "internalType": "uint64",
+        "name": "version",
+        "type": "uint64"
       }
     ],
-    "name": "TransactionRequested",
+    "name": "Initialized",
     "type": "event"
   },
   {
@@ -1142,6 +1066,25 @@
     "stateMutability": "view",
     "type": "function"
   },
+  {
+    "inputs": [
+      {
+        "internalType": "bytes32",
+        "name": "roleHash",
+        "type": "bytes32"
+      }
+    ],
+    "name": "getWalletsInRole",
+    "outputs": [
+      {
+        "internalType": "address[]",
+        "name": "",
+        "type": "address[]"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  },
   {
     "inputs": [
       {