Merge pull request #106 from PracticalParticle/work

Work

Author: JaCoderX

CONTRIBUTING.md

@@ -273,11 +273,14 @@ npm run test:coverage
 
 ## Documentation
 
+**Source of truth:** Solidity contracts are the source of truth for protocol API and behavior. The `docs/` directory is generated from contract NatSpec; do not edit those generated files by hand. For the full documentation map, updating process, and audit checklist, see **[CODEBASE_DOCUMENTATION.md](CODEBASE_DOCUMENTATION.md)**.
+
 ### Contract Documentation
 - **NatSpec comments** for all public functions
 - **Security annotations** for sensitive operations
 - **Usage examples** in comments
 - **Parameter descriptions** for all inputs/outputs
+- **Regenerate API docs** after contract changes: `npm run docgen` (see [docgen/README.md](docgen/README.md))
 
 ### SDK Documentation
 - **JSDoc comments** for all public methods

README.md

@@ -111,16 +111,16 @@ Addresses are written to **`deployed-addresses.json`**.
 
 | Contract | Address |
 |----------|---------|
-| EngineBlox | [`0xd0db4bcfac215e86371c55ba9d91030082fe7adb`](https://sepolia.etherscan.io/address/0xd0db4bcfac215e86371c55ba9d91030082fe7adb) |
-| SecureOwnableDefinitions | [`0xd21e88564377cbbed7885416cf0462b1a7e424aa`](https://sepolia.etherscan.io/address/0xd21e88564377cbbed7885416cf0462b1a7e424aa) |
-| RuntimeRBACDefinitions | [`0x03156b0dcbd104c397aa3463705964b933ed4d3f`](https://sepolia.etherscan.io/address/0x03156b0dcbd104c397aa3463705964b933ed4d3f) |
-| GuardControllerDefinitions | [`0x4b828c8575fcb375158d0926fd2ca01e5f41ca1f`](https://sepolia.etherscan.io/address/0x4b828c8575fcb375158d0926fd2ca01e5f41ca1f) |
+| EngineBlox | [`0xb2cb295d62b1296d426344bcaea7f13e6415db33`](https://sepolia.etherscan.io/address/0xb2cb295d62b1296d426344bcaea7f13e6415db33) |
+| SecureOwnableDefinitions | [`0x58a6f5cb9b5bbbc4700b26dca21a07b5d628a329`](https://sepolia.etherscan.io/address/0x58a6f5cb9b5bbbc4700b26dca21a07b5d628a329) |
+| RuntimeRBACDefinitions | [`0xc897e8cc3d33f22153edee9bc82bf62d62dd7c94`](https://sepolia.etherscan.io/address/0xc897e8cc3d33f22153edee9bc82bf62d62dd7c94) |
+| GuardControllerDefinitions | [`0x922454de0599640a7cd223e2f955d45025f3cfda`](https://sepolia.etherscan.io/address/0x922454de0599640a7cd223e2f955d45025f3cfda) |
 
 #### Account
 
 | Contract | Address |
 |----------|---------|
-| AccountBlox | [`0x5886d5760551fae5f826ebb71d5b8a125da57a15`](https://sepolia.etherscan.io/address/0x5886d5760551fae5f826ebb71d5b8a125da57a15) |
+| AccountBlox | [`0xb73f8e5f08e30a9326d7127aaffe897a26c49f70`](https://sepolia.etherscan.io/address/0xb73f8e5f08e30a9326d7127aaffe897a26c49f70) |
 
 #### Examples
 
@@ -175,7 +175,9 @@ npm run docgen && npm run format    # docs & format
 
 ## 📚 Documentation
 
+- **[Codebase documentation process & audit checklist](CODEBASE_DOCUMENTATION.md)** – Source of truth, how to update docs, audit-ready checklist
 - [Protocol Architecture](./sdk/typescript/docs/bloxchain-architecture.md) · [State Machine](./sdk/typescript/docs/state-machine-engine.md) · [Getting Started](./sdk/typescript/docs/getting-started.md) · [API Reference](./sdk/typescript/docs/api-reference.md) · [SecureOwnable](./sdk/typescript/docs/secure-ownable.md) · [RuntimeRBAC](./sdk/typescript/docs/dynamic-rbac.md) · [Best Practices](./sdk/typescript/docs/best-practices.md) · [Examples](./sdk/typescript/docs/examples-basic.md)
+- **Contract API (generated):** [docs/](docs/) – generated from Solidity NatSpec via `npm run docgen`
 
 ## 🛡️ Security Features
 

contracts/core/access/RuntimeRBAC.sol

@@ -71,7 +71,7 @@ abstract contract RuntimeRBAC is BaseStateMachine, IRuntimeRBAC {
     /**
      * @dev Requests and approves a RBAC configuration batch using a meta-transaction
      * @param metaTx The meta-transaction
-     * @return The transaction record
+     * @return The transaction ID of the applied batch
      * @notice OWNER signs, BROADCASTER executes according to RuntimeRBACDefinitions
      */
     function roleConfigBatchRequestAndApprove(

contracts/core/access/interface/IRuntimeRBAC.sol

@@ -12,7 +12,7 @@ import "../../lib/EngineBlox.sol";
  * 
  * Key Features:
  * - Batch-based role configuration (atomic operations)
- * - Runtime function schema registration
+ * - Role and permission management (function schema registration is handled by GuardController)
  * - Integration with EngineBlox for secure operations
  * - Query functions for role and permission inspection
  * 
@@ -47,7 +47,7 @@ interface IRuntimeRBAC {
     /**
      * @dev Requests and approves a RBAC configuration batch using a meta-transaction
      * @param metaTx The meta-transaction
-     * @return The transaction record
+     * @return The transaction ID of the applied batch
      */
     function roleConfigBatchRequestAndApprove(
         EngineBlox.MetaTransaction memory metaTx

contracts/core/base/BaseStateMachine.sol

@@ -520,6 +520,7 @@ abstract contract BaseStateMachine is Initializable, ERC165Upgradeable, Reentran
      * @dev Gets function schema information
      * @param functionSelector The function selector to get information for
      * @return The full FunctionSchema struct (functionSignature, functionSelector, operationType, operationName, supportedActionsBitmap, enforceHandlerRelations, isProtected, handlerForSelectors)
+     * @notice Reverts with ResourceNotFound if the schema does not exist
      */
     function getFunctionSchema(bytes4 functionSelector) external view returns (EngineBlox.FunctionSchema memory) {
         _validateAnyRole();

contracts/core/execution/GuardController.sol

@@ -32,7 +32,7 @@ import "./interface/IGuardController.sol";
  * 
  * Usage Flow:
  * 1. Deploy GuardController (or combine with RuntimeRBAC/SecureOwnable for role management)
- * 2. Function schemas should be registered via definitions or RuntimeRBAC if combined
+ * 2. Function schemas are registered via definitions at init or via GuardController guard config batch (REGISTER_FUNCTION)
  * 3. Create roles and assign function permissions with action bitmaps (via RuntimeRBAC if combined)
  * 4. Assign wallets to roles (via RuntimeRBAC if combined)
      * 5. Configure target whitelists per function selector (REQUIRED for execution)
@@ -173,7 +173,7 @@ abstract contract GuardController is BaseStateMachine {
     /**
      * @dev Approves and executes a time-locked transaction
      * @param txId The transaction ID
-     * @return result The execution result
+     * @return txId The transaction ID
      * @notice Requires STANDARD execution type and EXECUTE_TIME_DELAY_APPROVE permission for the execution function
      */
     function approveTimeLockExecution(
@@ -191,7 +191,7 @@ abstract contract GuardController is BaseStateMachine {
     /**
      * @dev Cancels a time-locked transaction
      * @param txId The transaction ID
-     * @return The updated transaction record
+     * @return The transaction ID
      * @notice Requires STANDARD execution type and EXECUTE_TIME_DELAY_CANCEL permission for the execution function
      */
     function cancelTimeLockExecution(
@@ -209,7 +209,7 @@ abstract contract GuardController is BaseStateMachine {
     /**
      * @dev Approves a time-locked transaction using a meta-transaction
      * @param metaTx The meta-transaction containing the transaction record and signature
-     * @return The updated transaction record
+     * @return The transaction ID
      * @notice Requires STANDARD execution type and EXECUTE_META_APPROVE permission for the execution function
      */
     function approveTimeLockExecutionWithMetaTx(
@@ -226,7 +226,7 @@ abstract contract GuardController is BaseStateMachine {
     /**
      * @dev Cancels a time-locked transaction using a meta-transaction
      * @param metaTx The meta-transaction containing the transaction record and signature
-     * @return The updated transaction record
+     * @return The transaction ID
      * @notice Requires STANDARD execution type and EXECUTE_META_CANCEL permission for the execution function
      */
     function cancelTimeLockExecutionWithMetaTx(
@@ -243,7 +243,7 @@ abstract contract GuardController is BaseStateMachine {
     /**
      * @dev Requests and approves a transaction in one step using a meta-transaction
      * @param metaTx The meta-transaction containing the transaction record and signature
-     * @return The transaction record after request and approval
+     * @return The transaction ID
      * @notice Requires STANDARD execution type
      * @notice Validates function schema and permissions for the execution function (same as executeWithTimeLock)
      * @notice Requires EXECUTE_META_REQUEST_AND_APPROVE permission for the execution function selector
@@ -304,7 +304,7 @@ abstract contract GuardController is BaseStateMachine {
     /**
      * @dev Requests and approves a Guard configuration batch using a meta-transaction
      * @param metaTx The meta-transaction
-     * @return The transaction record
+     * @return The transaction ID
      * @notice OWNER signs, BROADCASTER executes according to GuardControllerDefinitions
      */
     function guardConfigBatchRequestAndApprove(

contracts/core/execution/interface/IGuardController.sol

@@ -5,10 +5,10 @@ import "../../lib/EngineBlox.sol";
 
 /**
  * @title IGuardController
- * @dev Interface for GuardController contract that GuardianSafeV3 and other contracts delegate to
+ * @dev Interface for GuardController contract that AccountBlox and other contracts delegate to
  * @notice This interface defines only GuardController-specific methods
- * @notice Functions from BaseStateMachine (createMetaTxParams, generateUnsignedMetaTransaction*, getTransaction, functionSchemaExists, getFunctionSchema, owner, getBroadcaster, getRecovery) should be accessed via IBaseStateMachine
- * @notice Functions from RuntimeRBAC (registerFunction, unregisterFunction, createNewRole, addWalletToRole, revokeWallet) should be accessed via IRuntimeRBAC
+ * @notice Functions from BaseStateMachine (createMetaTxParams, generateUnsignedMetaTransaction*, getTransaction, getFunctionSchema, owner, getBroadcasters, getRecovery) should be accessed via IBaseStateMachine
+ * @notice Functions from RuntimeRBAC (role management: createNewRole, addWalletToRole, revokeWallet, etc.) should be accessed via IRuntimeRBAC. Function schema registration is performed via GuardController (guard config batch), not RuntimeRBAC.
  * @custom:security-contact security@particlecrypto.com
  */
 interface IGuardController {

docgen/README.md

@@ -25,6 +25,7 @@ This directory contains a separate npm workspace for generating documentation us
 
 ## Configuration
 
-- Hardhat config: `hardhat.config.cjs`
+- Hardhat config: `hardhat.config.cjs` (script uses `--config hardhat.config.cjs` so the parent’s `hardhat.config.ts` is not loaded).
 - Templates: `templates/contract.hbs`
 - Output: `../docs/` (parent directory)
+- Requires `ts-node` as a devDependency (Hardhat 2.x detects TypeScript from the repo and expects it).

docgen/hardhat.config.cjs

@@ -15,7 +15,7 @@ module.exports = {
     }
   },
   paths: {
-    // Reference parent directory's contracts, artifacts, and cache
+    // Root at parent so contracts are "inside" the project; use --config hardhat.config.cjs so this CJS file is loaded
     root: path.resolve(__dirname, ".."),
     sources: path.resolve(__dirname, "../contracts"),
     tests: path.resolve(__dirname, "../test"),

docgen/package.json

@@ -3,12 +3,14 @@
   "version": "1.0.0",
   "description": "Documentation generation workspace for Bloxchain protocol (isolated Hardhat 2.x dependencies)",
   "private": true,
+  "type": "commonjs",
   "scripts": {
-    "docgen": "hardhat docgen",
+    "docgen": "hardhat docgen --config hardhat.config.cjs",
     "install-deps": "npm install"
   },
   "devDependencies": {
     "hardhat": "^2.28.3",
-    "solidity-docgen": "^0.6.0-beta.36"
+    "solidity-docgen": "^0.6.0-beta.36",
+    "ts-node": "^10.9.2"
   }
 }