@lazy-sol/access-control 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+v1.1.2: do not enable full privileges to zero address on construction
+
+v1.1.1: Role-based Access Control (RBAC) Inspector
+- Introduced the Role-based Access Control (RBAC) Inspector UI capable of evaluating features and roles
+  for already deployed contracts; supports all EVM-based networks (mainnet, sepolia, etc.)
+- Optimized npm imports moving all prod dependencies into dev dependencies
+
 v1.1.0: Contact Size Optimizations
 
 - __Breaking Change:__ Solidity 0.8.4 is now required to compile the contracts

package/README.md

@@ -65,7 +65,7 @@ features and roles. Usually, smart contracts use different values for all the fe
 next section).
 
 Access manager may revoke its own permissions, including the bit 255. Eventually that allows an access manager to let
-the smart contract “float freely” and be controlled only by the community (via DAO) or by no one at all.
+the smart contract “float freely” and be controlled only by the community (via the DAO) or by no one at all.
 
 ## Comparing with OpenZeppelin
 
@@ -73,7 +73,7 @@ Both our and OpenZeppelin Access Control implementations feature a similar API t
 thing".
 
 Zeppelin implementation is more flexible:
-* it allows setting unlimited number of roles, while current is limited to 256 different roles
+* it allows setting an unlimited number of roles, while current is limited to 256 different roles
 * it allows setting an admin for each role, while current allows having only one global admin
 
 Our implementation is more lightweight:
@@ -93,11 +93,11 @@ npm i -D @lazy-sol/access-control
 Restricted function is a function with a `public` Solidity modifier access to which is restricted
 so that only a pre-configured set of accounts can execute it.
 
-1. Enable role-based access control (RBAC) in a new smart contract
-   by inheriting the RBAC contract from the [AccessControl](./contracts/AccessControl.sol) contract:
+1.  Enable role-based access control (RBAC) in a new smart contract
+    by inheriting the RBAC contract from the [AccessControlCore](./contracts/AccessControlCore.sol) contract:
     ```solidity
     import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
-    import "@lazy-sol/access-control/contracts/AccessControl.sol";
+    import "@lazy-sol/access-control/contracts/AccessControlCore.sol";
     
     /**
      * @title Simple ERC20 Implementation
@@ -106,29 +106,29 @@ so that only a pre-configured set of accounts can execute it.
      *
      * @author Lazy So[u]l
      */
-    contract MyERC20Token is ERC20, AccessControl {
+    contract MyERC20Token is ERC20, AccessControlCore {
         
         ...
         
     }
     ```
 
-2. Define an access control role with the unique integer value:
+2.  Define an access control role with the unique integer value:
     ```solidity
         ...
         
         /**
          * @notice Token creator is responsible for creating (minting)
-         tokens to an arbitrary address
+         *      tokens to an arbitrary address
          * @dev Role ROLE_TOKEN_CREATOR allows minting tokens
-         (calling `mint` function)
+         *      (calling `mint` function)
          */
         uint32 public constant ROLE_TOKEN_CREATOR = 0x0001_0000;
         
         ...
     ```
 
-3. Add the `require(isSenderInRole(ROLE_TOKEN_CREATOR), "access denied")"` check into the function body:
+3.  Add the `_requireSenderInRole(ROLE_TOKEN_CREATOR)` check into the function body:
     ```solidity
         ...
         
@@ -137,7 +137,7 @@ so that only a pre-configured set of accounts can execute it.
          */
         function _mint(address _to, uint256 _value) internal virtual override {
             // check if caller has sufficient permissions to mint tokens
-            require(isSenderInRole(ROLE_TOKEN_CREATOR), "access denied");
+            _requireSenderInRole(ROLE_TOKEN_CREATOR);
 
             // delegate to super implementation
             super._mint(_to, _value);
@@ -146,8 +146,8 @@ so that only a pre-configured set of accounts can execute it.
         ...
     ```
 
-   Note: you could also use the `restrictedTo` modifier in the function declaration instead of the `require`
-   in the function body if you don't need a custom error message:
+    Note: it is also possible to use the `restrictedTo` modifier in the function declaration instead of the `require`
+    in the function body if this better suits the coding style:
     ```solidity
         ...
         
@@ -162,6 +162,31 @@ so that only a pre-configured set of accounts can execute it.
         ...
     ```
 
+### Customizing the Error Message
+
+Modifier `restrictedTo()`, internal functions `_requireSenderInRole()` and `_requireAccessCondition()` throw the
+`AccessDenied` denied error when access check fails.
+
+It is also possible to use your own custom errors or string messages if needed by leveraging a lower level boolean
+functions `_isSenderInRole()` and `_isOperatorInRole()`:
+
+```solidity
+    ...
+    
+    /**
+     * @inheritdoc ERC20
+     */
+    function _mint(address _to, uint256 _value) internal virtual override {
+        // check if caller has sufficient permissions to mint tokens
+        require(_isSenderInRole(ROLE_TOKEN_CREATOR), "access denied");
+
+        // delegate to super implementation
+        super._mint(_to, _value);
+    }
+    
+    ...
+```
+
 Examples:
 [ERC20Impl](https://raw.githubusercontent.com/vgorin/solidity-template/master/contracts/token/ERC20Impl.sol),
 [ERC721Impl](https://raw.githubusercontent.com/vgorin/solidity-template/master/contracts/token/ERC721Impl.sol).
@@ -177,32 +202,32 @@ Many deployed contracts are using this model, and when the time comes to switch
 
 Prerequisite: deployed OZ Ownable contract (target contract) address (target_address)
 
-1. Deploy the AccessControl Adapter bound to the already deployed OZ Ownable contract
-   (specify the target OZ Ownable contract address in the constructor upon the deployment)
+1.  Deploy the AccessControl Adapter bound to the already deployed OZ Ownable contract
+    (specify the target OZ Ownable contract address in the constructor upon the deployment)
     ```javascript
     const adapter = await (artifacts.require("OwnableToAccessControlAdapter")).new(target_address);
     ```
 
-2. Define what Ownable-restricted public functions on the target contract you'd like to be able
-   to provide access to through the adapter contract
+2.  Define what Ownable-restricted public functions on the target contract you'd like to be able
+    to provide access to through the adapter contract
 
-3. Map every such function with the role required to execute it using `updateAccessRole()` function  
-   For example, to be able to provide an access to the transferOwnership(address) function, you could do
+3.  Map every such function with the role required to execute it using `updateAccessRole()` function  
+    For example, to be able to provide an access to the transferOwnership(address) function, you could do
     ```javascript
     const ROLE_TRANSFER_OWNERSHIP_MANAGER = 0x00010000;
     await adapter.updateAccessRole("transferOwnership(address)", ROLE_TRANSFER_OWNERSHIP_MANAGER);
-   ```
+    ```
 
-4. Provide the roles to the corresponding operators as you would usually do with AccessControl  
-   For example, if you wish an address 0x00000000000000000000000000000000000Ff1CE to grant an access to the
-   transferOwnership(address) function on the target, you could do
+4.  Provide the roles to the corresponding operators as you would usually do with AccessControl  
+    For example, if you wish an address 0x00000000000000000000000000000000000Ff1CE to grant an access to the
+    transferOwnership(address) function on the target, you could do
     ```javascript
     const operator = "0x00000000000000000000000000000000000Ff1CE";
     await adapter.updateRole(operator, ROLE_TRANSFER_OWNERSHIP_MANAGER);
     ```
 
-5. Transfer the ownership of the target contract to the deployed AccessControl Adapter contract  
-   Note that you can also do steps 2-4 after the step 5
+5.  Transfer the ownership of the target contract to the deployed AccessControl Adapter contract  
+    Note that you can also do steps 2-4 after the step 5
 
 #### Usage Flow
 
@@ -210,16 +235,16 @@ Prerequisite: installed AccessControl Adapter with the access to at least one re
 function configured
 
 To execute the restricted access function on the target contract via the AccessControl Adapter
-1. Use target contract ABI to construct a low-level function call calldata  
-   For example, to construct the transferOwnership() function calldata to transfer the ownership to the
-   0x00000000000000000000000000000000DEAdc0De address, you could do
+1.  Use target contract ABI to construct a low-level function call calldata  
+    For example, to construct the transferOwnership() function calldata to transfer the ownership to the
+    0x00000000000000000000000000000000DEAdc0De address, you could do
     ```javascript
     const to = "0x00000000000000000000000000000000DEAdc0De";
     const calldata = target.contract.methods.transferOwnership(to).encodeABI();
     ```
 
-2. Execute a low-level function call on the AccessControl Adapter contract using the constructed calldata  
-   For example, to execute the transferOwnership() function (prepared in step 1), you could do
+2.  Execute a low-level function call on the AccessControl Adapter contract using the constructed calldata  
+    For example, to execute the transferOwnership() function (prepared in step 1), you could do
     ```javascript
       await web3.eth.sendTransaction({
           from: operator,
@@ -228,9 +253,20 @@ To execute the restricted access function on the target contract via the AccessC
       }
     ```
 
-3. It is also ok to add an ether to the transaction by adding a value field to the `sendTransaction` call,
-   as well as sending plain ether transfer transaction, as long as target contract has payable functions,
-   and/or has a default payable receiver
+3.  It is also ok to add an ether to the transaction by adding a value field to the `sendTransaction` call,
+    as well as sending plain ether transfer transaction, as long as target contract has payable functions,
+    and/or has a default payable receiver
+
+## Evaluating Currently Enabled Features and Roles on the Deployed Contract
+
+1.  To evaluate currently enabled features use
+    * `features()` function, or
+    * `getRole(this)` function, replacing `this` with the deployed contract address
+2.  To evaluate currently enabled permissions for a **particular** address use
+    * `getRole(address)` function
+3.  To find **all** the addresses having any permissions, track the `RoleUpdated()` event and evaluate the history
+    of `assiged` roles for every `operator` address
+    * Alternatively, use the [tool](ui.html) which automates the process
 
 ## Contributing
 Please see the [Contribution Guide](./CONTRIBUTING.md) document to get understanding on how to report issues,

package/artifacts/contracts/OwnableToAccessControlAdapter.sol/OwnableToAccessControlAdapter.json

@@ -278,8 +278,8 @@
       "type": "receive"
     }
   ],
-  "bytecode": "0x608060405234801561001057600080fd5b50604051610a23380380610a2383398101604081905261002f9161012f565b80600061003f82600019806100bb565b61004a3082806100bb565b50506001600160a01b0382166100955760405162461bcd60e51b815260206004820152600c60248201526b7a65726f206164647265737360a01b604482015260640160405180910390fd5b50600180546001600160a01b0319166001600160a01b0392909216919091179055610162565b6001600160a01b0383166000818152602081815260409182902084905581518581529081018490527fe9be537308880e0f56b7d7cfd7abf85f14c4934486d138f848b92a0cbaf659b4910160405180910390a2505050565b80516001600160a01b038116811461012a57600080fd5b919050565b6000806040838503121561014257600080fd5b61014b83610113565b915061015960208401610113565b90509250929050565b6108b2806101716000396000f3fe6080604052600436106100a05760003560e01c8063491d261111610064578063491d2611146101d35780635defb40d146101f3578063ae5b102e14610213578063ae682e2e14610233578063d4b839921461024b578063d5bb7f6714610283576100bf565b806309c5eabe146100ff5780630e82fe25146101285780632b5214161461016357806334e48c9e14610185578063442767331461019d576100bf565b366100bf576100bd604051806020016040528060008152506102a3565b005b6100bd6000368080601f0160208091040260200160405190810160405280939291908181526020018383808284376000920191909152506102a392505050565b61011261010d36600461064c565b6102a3565b60405161011f91906106ed565b60405180910390f35b34801561013457600080fd5b5061015561014336600461071d565b60026020526000908152604090205481565b60405190815260200161011f565b34801561016f57600080fd5b5030600090815260208190526040902054610155565b34801561019157600080fd5b50610155600160fd1b81565b3480156101a957600080fd5b506101556101b836600461074f565b6001600160a01b031660009081526020819052604090205490565b3480156101df57600080fd5b506100bd6101ee36600461076a565b610411565b3480156101ff57600080fd5b506100bd61020e366004610794565b610477565b34801561021f57600080fd5b506100bd61022e3660046107ed565b61048c565b34801561023f57600080fd5b50610155600160ff1b81565b34801561025757600080fd5b5060015461026b906001600160a01b031681565b6040516001600160a01b03909116815260200161011f565b34801561028f57600080fd5b506100bd61029e366004610809565b6104f5565b602081015181516060919015610323576001600160e01b03198116600090815260026020526040812054908190036103185760405162461bcd60e51b81526020600482015260136024820152721858d8d95cdcc81c9bdb19481b9bdd081cd95d606a1b60448201526064015b60405180910390fd5b61032181610502565b505b60015460405160009182916001600160a01b03909116903490610347908890610822565b60006040518083038185875af1925050503d8060008114610384576040519150601f19603f3d011682016040523d82523d6000602084013e610389565b606091505b5091509150816103ce5760405162461bcd60e51b815260206004820152601060248201526f195e1958dd5d1a5bdb8819985a5b195960821b604482015260640161030f565b7f57a62eca76fc623c92f161d2a4b851851ece707135ce2af1eec256d660571b6d8386836040516104019392919061083e565b60405180910390a1949350505050565b61041e600160fd1b610502565b6001600160e01b03198216600081815260026020908152604091829020849055815192835282018390527fdb8ed917742b49e83acd1322bcaa8f18b1e5f78a70784c43ea14db7ab50e628d910160405180910390a15050565b610488828051906020012082610411565b5050565b610499600160ff1b610502565b61048882826104f0336104c1876001600160a01b031660009081526020819052604090205490565b6001600160a01b0391909116600090815260208190526040902054600019808818821618908716919091171690565b610513565b6104ff308261048c565b50565b6104ff61050e8261056b565b61057d565b6001600160a01b0383166000818152602081815260409182902084905581518581529081018490527fe9be537308880e0f56b7d7cfd7abf85f14c4934486d138f848b92a0cbaf659b4910160405180910390a2505050565b6000610577338361059b565b92915050565b806104ff57604051634ca8886760e01b815260040160405180910390fd5b6001600160a01b038216600090815260208190526040812054821682145b9392505050565b634e487b7160e01b600052604160045260246000fd5b600067ffffffffffffffff808411156105f1576105f16105c0565b604051601f8501601f19908116603f01168101908282118183101715610619576106196105c0565b8160405280935085815286868601111561063257600080fd5b858560208301376000602087830101525050509392505050565b60006020828403121561065e57600080fd5b813567ffffffffffffffff81111561067557600080fd5b8201601f8101841361068657600080fd5b610695848235602084016105d6565b949350505050565b60005b838110156106b85781810151838201526020016106a0565b50506000910152565b600081518084526106d981602086016020860161069d565b601f01601f19169290920160200192915050565b6020815260006105b960208301846106c1565b80356001600160e01b03198116811461071857600080fd5b919050565b60006020828403121561072f57600080fd5b6105b982610700565b80356001600160a01b038116811461071857600080fd5b60006020828403121561076157600080fd5b6105b982610738565b6000806040838503121561077d57600080fd5b61078683610700565b946020939093013593505050565b600080604083850312156107a757600080fd5b823567ffffffffffffffff8111156107be57600080fd5b8301601f810185136107cf57600080fd5b6107de858235602084016105d6565b95602094909401359450505050565b6000806040838503121561080057600080fd5b61078683610738565b60006020828403121561081b57600080fd5b5035919050565b6000825161083481846020870161069d565b9190910192915050565b63ffffffff60e01b8416815260606020820152600061086060608301856106c1565b828103604084015261087281856106c1565b969550505050505056fea2646970667358221220e3c74e6e9d12e9f897ad014f9a9508e19f07aa6158ea118e7b0f262e5ef3629764736f6c63430008150033",
-  "deployedBytecode": "0x6080604052600436106100a05760003560e01c8063491d261111610064578063491d2611146101d35780635defb40d146101f3578063ae5b102e14610213578063ae682e2e14610233578063d4b839921461024b578063d5bb7f6714610283576100bf565b806309c5eabe146100ff5780630e82fe25146101285780632b5214161461016357806334e48c9e14610185578063442767331461019d576100bf565b366100bf576100bd604051806020016040528060008152506102a3565b005b6100bd6000368080601f0160208091040260200160405190810160405280939291908181526020018383808284376000920191909152506102a392505050565b61011261010d36600461064c565b6102a3565b60405161011f91906106ed565b60405180910390f35b34801561013457600080fd5b5061015561014336600461071d565b60026020526000908152604090205481565b60405190815260200161011f565b34801561016f57600080fd5b5030600090815260208190526040902054610155565b34801561019157600080fd5b50610155600160fd1b81565b3480156101a957600080fd5b506101556101b836600461074f565b6001600160a01b031660009081526020819052604090205490565b3480156101df57600080fd5b506100bd6101ee36600461076a565b610411565b3480156101ff57600080fd5b506100bd61020e366004610794565b610477565b34801561021f57600080fd5b506100bd61022e3660046107ed565b61048c565b34801561023f57600080fd5b50610155600160ff1b81565b34801561025757600080fd5b5060015461026b906001600160a01b031681565b6040516001600160a01b03909116815260200161011f565b34801561028f57600080fd5b506100bd61029e366004610809565b6104f5565b602081015181516060919015610323576001600160e01b03198116600090815260026020526040812054908190036103185760405162461bcd60e51b81526020600482015260136024820152721858d8d95cdcc81c9bdb19481b9bdd081cd95d606a1b60448201526064015b60405180910390fd5b61032181610502565b505b60015460405160009182916001600160a01b03909116903490610347908890610822565b60006040518083038185875af1925050503d8060008114610384576040519150601f19603f3d011682016040523d82523d6000602084013e610389565b606091505b5091509150816103ce5760405162461bcd60e51b815260206004820152601060248201526f195e1958dd5d1a5bdb8819985a5b195960821b604482015260640161030f565b7f57a62eca76fc623c92f161d2a4b851851ece707135ce2af1eec256d660571b6d8386836040516104019392919061083e565b60405180910390a1949350505050565b61041e600160fd1b610502565b6001600160e01b03198216600081815260026020908152604091829020849055815192835282018390527fdb8ed917742b49e83acd1322bcaa8f18b1e5f78a70784c43ea14db7ab50e628d910160405180910390a15050565b610488828051906020012082610411565b5050565b610499600160ff1b610502565b61048882826104f0336104c1876001600160a01b031660009081526020819052604090205490565b6001600160a01b0391909116600090815260208190526040902054600019808818821618908716919091171690565b610513565b6104ff308261048c565b50565b6104ff61050e8261056b565b61057d565b6001600160a01b0383166000818152602081815260409182902084905581518581529081018490527fe9be537308880e0f56b7d7cfd7abf85f14c4934486d138f848b92a0cbaf659b4910160405180910390a2505050565b6000610577338361059b565b92915050565b806104ff57604051634ca8886760e01b815260040160405180910390fd5b6001600160a01b038216600090815260208190526040812054821682145b9392505050565b634e487b7160e01b600052604160045260246000fd5b600067ffffffffffffffff808411156105f1576105f16105c0565b604051601f8501601f19908116603f01168101908282118183101715610619576106196105c0565b8160405280935085815286868601111561063257600080fd5b858560208301376000602087830101525050509392505050565b60006020828403121561065e57600080fd5b813567ffffffffffffffff81111561067557600080fd5b8201601f8101841361068657600080fd5b610695848235602084016105d6565b949350505050565b60005b838110156106b85781810151838201526020016106a0565b50506000910152565b600081518084526106d981602086016020860161069d565b601f01601f19169290920160200192915050565b6020815260006105b960208301846106c1565b80356001600160e01b03198116811461071857600080fd5b919050565b60006020828403121561072f57600080fd5b6105b982610700565b80356001600160a01b038116811461071857600080fd5b60006020828403121561076157600080fd5b6105b982610738565b6000806040838503121561077d57600080fd5b61078683610700565b946020939093013593505050565b600080604083850312156107a757600080fd5b823567ffffffffffffffff8111156107be57600080fd5b8301601f810185136107cf57600080fd5b6107de858235602084016105d6565b95602094909401359450505050565b6000806040838503121561080057600080fd5b61078683610738565b60006020828403121561081b57600080fd5b5035919050565b6000825161083481846020870161069d565b9190910192915050565b63ffffffff60e01b8416815260606020820152600061086060608301856106c1565b828103604084015261087281856106c1565b969550505050505056fea2646970667358221220e3c74e6e9d12e9f897ad014f9a9508e19f07aa6158ea118e7b0f262e5ef3629764736f6c63430008150033",
+  "bytecode": "0x608060405234801561001057600080fd5b50604051610a32380380610a3283398101604081905261002f9161013e565b8060006001600160a01b0382161561004e5761004e82600019806100ca565b6100593082806100ca565b50506001600160a01b0382166100a45760405162461bcd60e51b815260206004820152600c60248201526b7a65726f206164647265737360a01b604482015260640160405180910390fd5b50600180546001600160a01b0319166001600160a01b0392909216919091179055610171565b6001600160a01b0383166000818152602081815260409182902084905581518581529081018490527fe9be537308880e0f56b7d7cfd7abf85f14c4934486d138f848b92a0cbaf659b4910160405180910390a2505050565b80516001600160a01b038116811461013957600080fd5b919050565b6000806040838503121561015157600080fd5b61015a83610122565b915061016860208401610122565b90509250929050565b6108b2806101806000396000f3fe6080604052600436106100a05760003560e01c8063491d261111610064578063491d2611146101d35780635defb40d146101f3578063ae5b102e14610213578063ae682e2e14610233578063d4b839921461024b578063d5bb7f6714610283576100bf565b806309c5eabe146100ff5780630e82fe25146101285780632b5214161461016357806334e48c9e14610185578063442767331461019d576100bf565b366100bf576100bd604051806020016040528060008152506102a3565b005b6100bd6000368080601f0160208091040260200160405190810160405280939291908181526020018383808284376000920191909152506102a392505050565b61011261010d36600461064c565b6102a3565b60405161011f91906106ed565b60405180910390f35b34801561013457600080fd5b5061015561014336600461071d565b60026020526000908152604090205481565b60405190815260200161011f565b34801561016f57600080fd5b5030600090815260208190526040902054610155565b34801561019157600080fd5b50610155600160fd1b81565b3480156101a957600080fd5b506101556101b836600461074f565b6001600160a01b031660009081526020819052604090205490565b3480156101df57600080fd5b506100bd6101ee36600461076a565b610411565b3480156101ff57600080fd5b506100bd61020e366004610794565b610477565b34801561021f57600080fd5b506100bd61022e3660046107ed565b61048c565b34801561023f57600080fd5b50610155600160ff1b81565b34801561025757600080fd5b5060015461026b906001600160a01b031681565b6040516001600160a01b03909116815260200161011f565b34801561028f57600080fd5b506100bd61029e366004610809565b6104f5565b602081015181516060919015610323576001600160e01b03198116600090815260026020526040812054908190036103185760405162461bcd60e51b81526020600482015260136024820152721858d8d95cdcc81c9bdb19481b9bdd081cd95d606a1b60448201526064015b60405180910390fd5b61032181610502565b505b60015460405160009182916001600160a01b03909116903490610347908890610822565b60006040518083038185875af1925050503d8060008114610384576040519150601f19603f3d011682016040523d82523d6000602084013e610389565b606091505b5091509150816103ce5760405162461bcd60e51b815260206004820152601060248201526f195e1958dd5d1a5bdb8819985a5b195960821b604482015260640161030f565b7f57a62eca76fc623c92f161d2a4b851851ece707135ce2af1eec256d660571b6d8386836040516104019392919061083e565b60405180910390a1949350505050565b61041e600160fd1b610502565b6001600160e01b03198216600081815260026020908152604091829020849055815192835282018390527fdb8ed917742b49e83acd1322bcaa8f18b1e5f78a70784c43ea14db7ab50e628d910160405180910390a15050565b610488828051906020012082610411565b5050565b610499600160ff1b610502565b61048882826104f0336104c1876001600160a01b031660009081526020819052604090205490565b6001600160a01b0391909116600090815260208190526040902054600019808818821618908716919091171690565b610513565b6104ff308261048c565b50565b6104ff61050e8261056b565b61057d565b6001600160a01b0383166000818152602081815260409182902084905581518581529081018490527fe9be537308880e0f56b7d7cfd7abf85f14c4934486d138f848b92a0cbaf659b4910160405180910390a2505050565b6000610577338361059b565b92915050565b806104ff57604051634ca8886760e01b815260040160405180910390fd5b6001600160a01b038216600090815260208190526040812054821682145b9392505050565b634e487b7160e01b600052604160045260246000fd5b600067ffffffffffffffff808411156105f1576105f16105c0565b604051601f8501601f19908116603f01168101908282118183101715610619576106196105c0565b8160405280935085815286868601111561063257600080fd5b858560208301376000602087830101525050509392505050565b60006020828403121561065e57600080fd5b813567ffffffffffffffff81111561067557600080fd5b8201601f8101841361068657600080fd5b610695848235602084016105d6565b949350505050565b60005b838110156106b85781810151838201526020016106a0565b50506000910152565b600081518084526106d981602086016020860161069d565b601f01601f19169290920160200192915050565b6020815260006105b960208301846106c1565b80356001600160e01b03198116811461071857600080fd5b919050565b60006020828403121561072f57600080fd5b6105b982610700565b80356001600160a01b038116811461071857600080fd5b60006020828403121561076157600080fd5b6105b982610738565b6000806040838503121561077d57600080fd5b61078683610700565b946020939093013593505050565b600080604083850312156107a757600080fd5b823567ffffffffffffffff8111156107be57600080fd5b8301601f810185136107cf57600080fd5b6107de858235602084016105d6565b95602094909401359450505050565b6000806040838503121561080057600080fd5b61078683610738565b60006020828403121561081b57600080fd5b5035919050565b6000825161083481846020870161069d565b9190910192915050565b63ffffffff60e01b8416815260606020820152600061086060608301856106c1565b828103604084015261087281856106c1565b969550505050505056fea26469706673582212209161ccf77ca651079cf7ca63ab02af76c981b46d82708b27350727dd4292764464736f6c63430008150033",
+  "deployedBytecode": "0x6080604052600436106100a05760003560e01c8063491d261111610064578063491d2611146101d35780635defb40d146101f3578063ae5b102e14610213578063ae682e2e14610233578063d4b839921461024b578063d5bb7f6714610283576100bf565b806309c5eabe146100ff5780630e82fe25146101285780632b5214161461016357806334e48c9e14610185578063442767331461019d576100bf565b366100bf576100bd604051806020016040528060008152506102a3565b005b6100bd6000368080601f0160208091040260200160405190810160405280939291908181526020018383808284376000920191909152506102a392505050565b61011261010d36600461064c565b6102a3565b60405161011f91906106ed565b60405180910390f35b34801561013457600080fd5b5061015561014336600461071d565b60026020526000908152604090205481565b60405190815260200161011f565b34801561016f57600080fd5b5030600090815260208190526040902054610155565b34801561019157600080fd5b50610155600160fd1b81565b3480156101a957600080fd5b506101556101b836600461074f565b6001600160a01b031660009081526020819052604090205490565b3480156101df57600080fd5b506100bd6101ee36600461076a565b610411565b3480156101ff57600080fd5b506100bd61020e366004610794565b610477565b34801561021f57600080fd5b506100bd61022e3660046107ed565b61048c565b34801561023f57600080fd5b50610155600160ff1b81565b34801561025757600080fd5b5060015461026b906001600160a01b031681565b6040516001600160a01b03909116815260200161011f565b34801561028f57600080fd5b506100bd61029e366004610809565b6104f5565b602081015181516060919015610323576001600160e01b03198116600090815260026020526040812054908190036103185760405162461bcd60e51b81526020600482015260136024820152721858d8d95cdcc81c9bdb19481b9bdd081cd95d606a1b60448201526064015b60405180910390fd5b61032181610502565b505b60015460405160009182916001600160a01b03909116903490610347908890610822565b60006040518083038185875af1925050503d8060008114610384576040519150601f19603f3d011682016040523d82523d6000602084013e610389565b606091505b5091509150816103ce5760405162461bcd60e51b815260206004820152601060248201526f195e1958dd5d1a5bdb8819985a5b195960821b604482015260640161030f565b7f57a62eca76fc623c92f161d2a4b851851ece707135ce2af1eec256d660571b6d8386836040516104019392919061083e565b60405180910390a1949350505050565b61041e600160fd1b610502565b6001600160e01b03198216600081815260026020908152604091829020849055815192835282018390527fdb8ed917742b49e83acd1322bcaa8f18b1e5f78a70784c43ea14db7ab50e628d910160405180910390a15050565b610488828051906020012082610411565b5050565b610499600160ff1b610502565b61048882826104f0336104c1876001600160a01b031660009081526020819052604090205490565b6001600160a01b0391909116600090815260208190526040902054600019808818821618908716919091171690565b610513565b6104ff308261048c565b50565b6104ff61050e8261056b565b61057d565b6001600160a01b0383166000818152602081815260409182902084905581518581529081018490527fe9be537308880e0f56b7d7cfd7abf85f14c4934486d138f848b92a0cbaf659b4910160405180910390a2505050565b6000610577338361059b565b92915050565b806104ff57604051634ca8886760e01b815260040160405180910390fd5b6001600160a01b038216600090815260208190526040812054821682145b9392505050565b634e487b7160e01b600052604160045260246000fd5b600067ffffffffffffffff808411156105f1576105f16105c0565b604051601f8501601f19908116603f01168101908282118183101715610619576106196105c0565b8160405280935085815286868601111561063257600080fd5b858560208301376000602087830101525050509392505050565b60006020828403121561065e57600080fd5b813567ffffffffffffffff81111561067557600080fd5b8201601f8101841361068657600080fd5b610695848235602084016105d6565b949350505050565b60005b838110156106b85781810151838201526020016106a0565b50506000910152565b600081518084526106d981602086016020860161069d565b601f01601f19169290920160200192915050565b6020815260006105b960208301846106c1565b80356001600160e01b03198116811461071857600080fd5b919050565b60006020828403121561072f57600080fd5b6105b982610700565b80356001600160a01b038116811461071857600080fd5b60006020828403121561076157600080fd5b6105b982610738565b6000806040838503121561077d57600080fd5b61078683610700565b946020939093013593505050565b600080604083850312156107a757600080fd5b823567ffffffffffffffff8111156107be57600080fd5b8301601f810185136107cf57600080fd5b6107de858235602084016105d6565b95602094909401359450505050565b6000806040838503121561080057600080fd5b61078683610738565b60006020828403121561081b57600080fd5b5035919050565b6000825161083481846020870161069d565b9190910192915050565b63ffffffff60e01b8416815260606020820152600061086060608301856106c1565b828103604084015261087281856106c1565b969550505050505056fea26469706673582212209161ccf77ca651079cf7ca63ab02af76c981b46d82708b27350727dd4292764464736f6c63430008150033",
   "linkReferences": {},
   "deployedLinkReferences": {}
 }

package/contracts/AccessControl.sol

@@ -5,7 +5,7 @@
 // hardhat (0.4.11)
 pragma solidity >=0.8.4;
 
-import {AccessControlCore} from "./AccessControlCore.sol";
+import "./AccessControlCore.sol";
 
 /**
  * @title Role-based Access Control (RBAC)
@@ -56,7 +56,7 @@ import {AccessControlCore} from "./AccessControlCore.sol";
  *
  * @author Basil Gorin
  */
-contract AccessControl is AccessControlCore {
+abstract contract AccessControl is AccessControlCore {
 	/**
 	 * @notice Creates an access control instance, setting the contract owner to have full privileges
 	 *

package/contracts/AccessControlCore.sol

@@ -135,8 +135,11 @@ abstract contract AccessControlCore {
 	 * @param _features initial features mask of the contract, can be zero
 	 */
 	constructor(address _owner, uint256 _features) { // visibility modifier is required to be compilable with 0.6.x
-		// grant owner full privileges
-		__setRole(_owner, FULL_PRIVILEGES_MASK, FULL_PRIVILEGES_MASK);
+		// if there is a request to set owner (zero address owner means no owner)
+		if(_owner != address(0)) {
+			// grant owner full privileges
+			__setRole(_owner, FULL_PRIVILEGES_MASK, FULL_PRIVILEGES_MASK);
+		}
 		// update initial features bitmask
 		__setRole(address(this), _features, _features);
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazy-sol/access-control",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Enable the modular plug and play (PnP) architecture for your dapp by incorporating the role-based access control (RBAC) into the smart contracts",
   "main": "index.js",
   "scripts": {
@@ -21,14 +21,12 @@
   ],
   "author": "Basil Gorin",
   "license": "MIT",
-  "dependencies": {
-    "@lazy-sol/a-missing-gem": "^1.0.9",
-    "@nomiclabs/hardhat-truffle5": "^2.0.7",
-    "hardhat": "^2.22.9",
-    "hardhat-deploy": "^0.11.45"
-  },
   "devDependencies": {
+    "@lazy-sol/a-missing-gem": "^1.0.11",
     "@lazy-sol/zeppelin-test-helpers": "^1.0.5",
+    "@nomiclabs/hardhat-truffle5": "^2.0.7",
+    "hardhat": "^2.22.13",
+    "hardhat-deploy": "^0.11.45",
     "hardhat-gas-reporter": "^1.0.10",
     "solidity-coverage": "^0.8.13"
   },

package/test/include/deployment_routines.js

@@ -3,23 +3,14 @@
  * (doesn't return any value on successful operation)
  *
  * @param a0 smart contract owner
- * @param H0 initial token holder address
  * @returns USDT ERC20 instance
  */
-async function deploy_usdt(a0, H0 = a0) {
+async function deploy_usdt(a0) {
 	// smart contracts required
 	const USDTContract = artifacts.require("TetherToken");
 
-	// deploy the token
-	const token = await USDTContract.new(0, "Tether USD", "USDT", 6, {from: a0});
-
-	// move the initial supply if required
-	if(H0 !== a0) {
-		await token.transfer(H0, S0, {from: a0});
-	}
-
-	// return the reference
-	return token;
+	// deploy the token and return the reference
+	return await USDTContract.new(0, "Tether USD", "USDT", 6, {from: a0});
 }
 
 /**

package/test/include/rbac.behaviour.js

@@ -59,13 +59,15 @@ function behavesLikeRBAC(deployment_fn, a0, a1, a2) {
 			beforeEach(async function() {
 				access_control = await deployment_fn.call(this, a0, owner, features);
 			});
-			it('"RoleUpdated(owner)" event is emitted correctly', async function() {
-				await expectEvent.inConstruction(access_control, "RoleUpdated", {
-					operator: owner,
-					requested: FULL_PRIVILEGES_MASK,
-					assigned: FULL_PRIVILEGES_MASK,
+			if(owner !== ZERO_ADDRESS) {
+				it('"RoleUpdated(owner)" event is emitted correctly', async function() {
+					await expectEvent.inConstruction(access_control, "RoleUpdated", {
+						operator: owner,
+						requested: FULL_PRIVILEGES_MASK,
+						assigned: FULL_PRIVILEGES_MASK,
+					});
 				});
-			});
+			}
 			it('"RoleUpdated(this)" event is emitted correctly', async function() {
 				await expectEvent.inConstruction(access_control, "RoleUpdated", {
 					operator: access_control.address,
@@ -73,9 +75,16 @@ function behavesLikeRBAC(deployment_fn, a0, a1, a2) {
 					assigned: features,
 				});
 			});
-			it("owners' role is set correctly", async function() {
-				expect(await access_control.getRole(owner)).to.be.bignumber.that.equals(FULL_PRIVILEGES_MASK);
-			});
+			if(owner !== ZERO_ADDRESS) {
+				it("owners' role is set correctly", async function() {
+					expect(await access_control.getRole(owner)).to.be.bignumber.that.equals(FULL_PRIVILEGES_MASK);
+				});
+			}
+			else {
+				it("owners' role is not set", async function() {
+					expect(await access_control.getRole(owner)).to.be.bignumber.that.equals("0");
+				});
+			}
 			it("features are set correctly", async function() {
 				expect(await access_control.features()).to.be.bignumber.that.equals(features);
 			});

package/ui.html

@@ -0,0 +1,506 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="UTF-8">
+	<title>Role-based Access Control (RBAC) Inspector</title>
+	<!-- Include Web3.js from a CDN -->
+	<script src="https://cdn.jsdelivr.net/npm/web3@latest/dist/web3.min.js"></script>
+	<style>
+		table#roles_list {
+			width: 100%;
+			border-collapse: collapse;
+		}
+		table#roles_list th, table#roles_list td {
+			border: 1px solid grey;
+		}
+		table#roles_list tr td {
+			font-family: monospace;
+		}
+	</style>
+</head>
+<body>
+<fieldset id="root_container" style="display: none;"><legend id="connection_state" style="text-align: right;"></legend>
+<div id="main_app" style="display: none;">
+	<fieldset><legend>Role-based Access Control (RBAC) Features and Roles Inspector</legend>
+		<form onsubmit="inspect_features_roles(event)">
+			<table>
+				<tr>
+					<td><label for="contract_address">Contract Address:</label></td>
+					<td><input id="contract_address" type="text" required size="42" style="font-family: monospace;" value="0xA9f50518f9119d5F7A324EC76481c5246970dEa6"/></td>
+				</tr>
+				<tr><td></td><td><input type="submit" value="Inspect"/></td></tr>
+			</table>
+		</form>
+	</fieldset>
+	<div id="features_roles_container" style="display: none;">
+		<fieldset>
+			<legend id="features_title">RBAC Features</legend>
+			<div id="features_hex">Loading...</div>
+		</fieldset>
+		<fieldset>
+			<legend id="roles_list_title">RBAC Operators and Roles</legend>
+			<table id="roles_list"><tr><td>Loading...</td></tr></table>
+		</fieldset>
+	</div>
+</div>
+</fieldset>
+<div style="position: fixed; left: 0; bottom: 0; margin: 0.1em 0.2em;">&copy; 2024 <a href="https://github.com/lazy-sol/">Lazy So[u]l</a></div>
+<div style="position: fixed; right: 0; bottom: 0; margin: 0.1em 0.2em; font-family: monospace;">
+	[<a href="https://lazy-sol.github.io/advanced-erc20/ui.html">Advanced ERC20</a>]
+	[<a href="https://lazy-sol.github.io/tiny-erc721/ui.html">Tiny ERC721</a>]
+	[RBAC Inspector]
+</div>
+</body>
+<script type="text/javascript">
+// verify if MetaMask is installed
+if(!window.ethereum) {
+	if(window.confirm("MetaMask is not installed. You will be redirected to the MetaMask installation page.")) {
+		window.setTimeout(function() {
+			window.location.href = "https://metamask.io/download/";
+		}, 0);
+	}
+	window.stop();
+}
+</script>
+
+<script type="text/javascript">
+// static HTML page anchors
+const root_container = document.getElementById("root_container");
+const connection_state = document.getElementById("connection_state");
+const main_app = document.getElementById("main_app");
+const contract_address = document.getElementById("contract_address");
+const features_roles_container = document.getElementById("features_roles_container");
+const features_title = document.getElementById("features_title");
+const features_hex = document.getElementById("features_hex");
+const roles_list_title = document.getElementById("roles_list_title");
+const roles_list = document.getElementById("roles_list");
+</script>
+
+<script type="text/javascript">
+// auxiliary pure functions
+
+// auxiliary function to log and display non-fatal error, doesn't stop execution
+function non_fatal_error(message, error) {
+	console.error("%s: %o", message, error);
+	window.alert(message + (error? ": " + json_stringify(error): ""));
+}
+
+// auxiliary function to log and display fatal error and stop execution
+function fatal_error(message, error) {
+	non_fatal_error("FATAL: " + message, error);
+	window.stop();
+	throw error? error: "error";
+}
+
+// save JSON.stringify works properly with BigInt
+function json_stringify(input) {
+	return JSON.stringify(input, (key, value) =>
+		typeof value === 'bigint' ? value.toString() : value
+	);
+}
+</script>
+
+<script type="text/javascript">
+// config and app state
+
+// config stores settings which don't change
+const CONF = {
+	// supported networks, where our contracts are known to be deployed
+	chains: {
+		1: {
+			name: "Mainnet",
+			block_explorer: {
+				tx: "https://etherscan.io/tx/",
+				address: "https://etherscan.io/address/",
+				token: "https://etherscan.io/token/",
+			},
+		},
+		11155111: {
+			name: "Sepolia",
+			block_explorer: {
+				tx: "https://sepolia.etherscan.io/tx/",
+				address: "https://sepolia.etherscan.io/address/",
+				token: "https://sepolia.etherscan.io/token/",
+			},
+		},
+		8453: {
+			name: "Base",
+			block_explorer: {
+				tx: "https://basescan.org/tx/",
+				address: "https://basescan.org/address/",
+				token: "https://basescan.org/token/",
+			},
+		},
+		84532: {
+			name: "Base Sepolia",
+			block_explorer: {
+				tx: "https://sepolia.basescan.org//tx/",
+				address: "https://sepolia.basescan.org/address/",
+				token: "https://sepolia.basescan.org/token/",
+			},
+		},
+	},
+};
+
+// state stores settings which may change due to user actions,
+// due to the async nature of the app, many incoming events, it makes sense to follow
+// the state of the app by listening to all the events and updating the state
+const STATE = {
+	// currently connected network (recognized decimal Chain ID)
+	chain_id: undefined,
+	// currently connected account (accounts[0])
+	A0: undefined,
+	// currently connected chain config
+	chain: function() {
+		return this.chain_id? CONF.chains[this.chain_id]: undefined;
+	},
+	// function to display the chain we're connected to
+	update_chain_id: function(chain_id) {
+		this.chain_id = chain_id? parseInt(chain_id): undefined;
+	},
+	// function to update currently connected account
+	update_A0: function(accounts) {
+		// MetaMask is locked or not connected
+		if(!accounts || !accounts.length) {
+			this.A0 = undefined;
+		}
+		else {
+			[this.A0] = accounts;
+		}
+	},
+	// function to refresh the connection state UI
+	refresh_ui: function() {
+		if(CONF.chains[this.chain_id]) {
+			if(this.A0) {
+				connection_state.innerHTML = `Connected <span style="font-family: monospace;">${this.A0}</span>`;
+			}
+			else {
+				connection_state.innerHTML = `
+					MetaMask is not connected.
+					<input type="button" onclick="metamask_connect()" value="Connect"/>
+				`;
+			}
+		}
+		else if(this.chain_id) {
+			connection_state.innerHTML = `
+				Unsupported Chain ID: ${this.chain_id}
+				<input type="button" onclick="add_sepolia_network()" value="Switch to Sepolia"/>
+			`;
+		}
+		else {
+			connection_state.innerHTML = `
+				MetaMask disconnected.
+				<input type="button" onclick="metamask_connect()" value="Connect"/>
+			`;
+		}
+		root_container.style["display"] = "block";
+	},
+	// function to check if we're connected to supported network
+	connected: function() {
+		return this.chain() && this.A0;
+	},
+}
+</script>
+
+<script type="text/javascript">
+// main app section
+
+// define window.ethereum shortcut
+const ethereum = window.ethereum;
+// MetaMask is installed, create a new Web3 instance
+const web3 = new Web3(window.ethereum);
+
+// function to connect to MetaMask
+function metamask_connect() {
+	ethereum.request({ method: 'eth_requestAccounts' }).then(function(accounts) {
+		STATE.update_A0(accounts);
+		STATE.refresh_ui();
+		reload_main_app();
+	}).catch(function(e) {
+		non_fatal_error("Error connecting MetaMask", e);
+	});
+}
+
+// check if MetaMask is connected
+ethereum.request({ method: 'eth_accounts' }).then(function(accounts) {
+	// check current connected network
+	ethereum.request({ method: 'eth_chainId' }).then(function(chain_id) {
+		STATE.update_chain_id(chain_id);
+		STATE.update_A0(accounts);
+		STATE.refresh_ui();
+		reload_main_app();
+	}).catch(function(e) {
+		fatal_error("Error getting Chain ID", e);
+	});
+}).catch(function(e) {
+	fatal_error("Error connecting to MetaMask", e);
+});
+
+// Handle the case when MetaMask connects another account
+ethereum.on('accountsChanged', function(accounts) {
+	console.log("account has been switched", accounts)
+	STATE.update_A0(accounts);
+	STATE.refresh_ui();
+	reload_main_app();
+});
+
+// Handle the case when MetaMask is connected
+ethereum.on('connect', function(connect_info) {
+	console.log('MetaMask has been connected', connect_info);
+	STATE.update_chain_id(connect_info.chainId);
+	STATE.refresh_ui();
+	reload_main_app();
+});
+
+// MetaMask disconnect listener
+ethereum.on('disconnect', function(error) {
+	console.warn('MetaMask has been disconnected', error);
+	STATE.update_A0();
+	STATE.update_chain_id();
+	STATE.refresh_ui();
+	reload_main_app();
+});
+
+// network switch listener
+ethereum.on('chainChanged', function(chain_id) {
+	console.log('network has been changed', chain_id)
+	STATE.update_chain_id(chain_id);
+	STATE.refresh_ui();
+	reload_main_app();
+});
+
+// define an async routine to switch the network to Sepolia
+async function add_sepolia_network() {
+	const sepolia_chain_id = '0xaa36a7'; // Hexadecimal chain ID for Sepolia
+
+	try {
+		// Check if Sepolia is already added
+		await ethereum.request({
+			method: 'wallet_switchEthereumChain',
+			params: [{ chainId: sepolia_chain_id }],
+		});
+	}
+	catch(e) {
+		// Error code 4902 indicates that the chain has not been added to MetaMask
+		if(e.code !== 4902) {
+			// Handle errors when switching the network
+			fatal_error("Error switching network to Sepolia", e)
+		}
+
+		try {
+			// Add the Sepolia network
+			await ethereum.request({
+				method: 'wallet_addEthereumChain',
+				params: [{
+					chainId: sepolia_chain_id,
+					rpcUrl: 'https://sepolia.infura.io/v3/',
+					chainName: 'Sepolia Test Network',
+					nativeCurrency: {
+						name: 'SepoliaETH',
+						symbol: 'SepoliaETH',
+						decimals: 18,
+					},
+					blockExplorerUrls: ['https://sepolia.etherscan.io/'],
+				}],
+			});
+		}
+		catch (e) {
+			// Handle errors when adding the network
+			fatal_error("Error adding Sepolia network", e);
+		}
+	}
+}
+
+// writes the entire roles_list table
+function features_roles_update({features, roles, assignments}) {
+	if(!Array.isArray(roles)) {
+		roles = Object.entries(roles).map(([operator, role]) => Object.assign({}, {operator, role}));
+	}
+
+	if(assignments && assignments.length) {
+		features_hex.innerHTML = features?
+			`Features enabled: <span style="font-family: monospace">0x${features.toString(16).toUpperCase()}</span>`:
+			"No features enabled.";
+
+		if(roles && roles.length) {
+			const table_body = roles.map(render_role_row).join("\n");
+			roles_list.innerHTML = `<tr><th>Operator Address</th><th>Assigned Role</th></tr>\n${table_body}`;
+		}
+		else {
+			roles_list.innerHTML = "No roles assigned.";
+		}
+	}
+	else {
+		features_hex.innerHTML = "No features enabled or not an RBAC contract.";
+		roles_list.innerHTML = "No roles assigned or not an RBAC contract.";
+	}
+	features_roles_container.style["display"] = "block";
+}
+
+// renders an HTML of the role list table row
+function render_role_row({operator, role}) {
+	return `<tr><td>${operator}</td><td>0x${role.toString(16).toUpperCase()}</td></tr>`;
+}
+
+// reloads the entire app, used when network or accounts have been changed
+function reload_main_app() {
+	if(!STATE.connected()) {
+		main_app.style["display"] = "none";
+		return;
+	}
+
+	features_roles_container.style.display = "none";
+	features_title.innerHTML = "RBAC Features";
+	features_hex.innerHTML = "Loading features...";
+	roles_list_title.innerHTML = "RBAC Operators and Roles";
+	roles_list.innerHTML = "Loading operators and roles...";
+
+	main_app.style["display"] = "block";
+}
+
+// function to extract RBAC roles from the target contract
+async function extract_rbac_features_roles(target_address) {
+	// the earliest versions of the AccessControl emitted both FeaturesUpdated and RoleUpdated;
+	// the features were assigned to a zero address
+	// TODO: the earliest versions didn't emit an event on deployment
+	// later versions of the AccessControl emitted only RoleUpdated event;
+	// the features were assigned to a zero address, and later to the contract address (self-role)
+	// the most recent versions of the AccessControl emit only RoleUpdated event;
+	// the features are assigned to the contract address, argument naming is improved and made clearer
+	const v0_abi = [{
+		// the earliest versions only
+		"name": "FeaturesUpdated",
+		"type": "event",
+		"anonymous": false,
+		"inputs": [
+			{"indexed": true, "internalType": "address", "name": "_by", "type": "address"},
+			{"indexed": false, "internalType": "uint256", "name": "_requested", "type": "uint256"},
+			{"indexed": false, "internalType": "uint256", "name": "_actual", "type": "uint256"}
+		],
+	}, {
+		// both the earliest and later versions
+		"name": "RoleUpdated",
+		"type": "event",
+		"anonymous": false,
+		"inputs": [
+			{"indexed": true, "internalType": "address", "name": "_by", "type": "address"},
+			{"indexed": true, "internalType": "address", "name": "_to", "type": "address"},
+			{"indexed": false, "internalType": "uint256", "name": "_requested", "type": "uint256"},
+			{"indexed": false, "internalType": "uint256", "name": "_actual", "type": "uint256"}
+		],
+	}, {
+		// both the earliest and later versions
+		"name": "userRoles",
+		"type": "function",
+		"inputs": [{"internalType": "address", "name": "", "type": "address"}],
+		"outputs": [{"internalType": "uint256", "name": "", "type": "uint256"}],
+		"stateMutability": "view",
+	}];
+	const v1_abi = [{
+		// the latest versions only
+		"name": "RoleUpdated",
+		"type": "event",
+		"anonymous": false,
+		"inputs": [
+			{"indexed": true, "internalType": "address", "name": "operator", "type": "address"},
+			{"indexed": false, "internalType": "uint256", "name": "requested", "type": "uint256"},
+			{"indexed": false, "internalType": "uint256", "name": "assigned", "type": "uint256"}
+		],
+	}, {
+		// the latest versions only
+		"name": "getRole",
+		"type": "function",
+		"inputs": [{"internalType": "address", "name": "operator", "type": "address"}],
+		"outputs": [{"internalType": "uint256", "name": "", "type": "uint256"}],
+		"stateMutability": "view",
+	}];
+
+	const v0_contract = new web3.eth.Contract(v0_abi, target_address);
+	const v1_contract = new web3.eth.Contract(v1_abi, target_address);
+
+	const features_v0 = await v0_contract.getPastEvents("FeaturesUpdated", {
+		fromBlock: "earliest",
+	});
+	console.log("v0.getPastEvents(FeaturesUpdated)", features_v0);
+	const role_v0 = await v0_contract.getPastEvents("RoleUpdated", {
+		fromBlock: "earliest",
+	});
+	console.log("v0.getPastEvents(RoleUpdated)", role_v0);
+	const role_v1 = await v1_contract.getPastEvents("RoleUpdated", {
+		fromBlock: "earliest",
+	});
+	console.log("v1.getPastEvents(RoleUpdated)", role_v1);
+	const assignments = features_v0.map(function(event) {
+		const {_actual: assigned} = event.returnValues;
+		// fix to the most recent format: feature is self-role
+		return {operator: target_address, assigned};
+	}).concat(role_v0.map(function(event) {
+		let {_to: operator, _actual: assigned} = event.returnValues;
+		if(operator === "0x0000000000000000000000000000000000000000") {
+			// fix to the most recent format: feature is self-role
+			operator = target_address;
+		}
+		return {operator, assigned};
+	})).concat(role_v1.map(function(event) {
+		const {operator, assigned} = event.returnValues;
+		return {operator, assigned};
+	}));
+
+	let features = 0;
+	v0_contract.methods["userRoles"]();
+
+	const roles = {};
+	assignments.forEach(function({operator, assigned}) {
+		if(operator === target_address) {
+			features = assigned;
+		}
+		else if(!BigInt(assigned)) {
+			delete roles[operator];
+		}
+		else {
+			roles[operator] = assigned;
+		}
+	});
+	console.log("extracted RBAC features and roles", features, roles);
+	
+	return {features, roles, assignments};
+}
+
+// loads and parses features and roles on the RBAC contract,
+// always returns false since is used as a form submit listener
+function inspect_features_roles(e) {
+	if(e && e.preventDefault) {
+		e.preventDefault();
+	}
+
+	if(!contract_address.value) {
+		alert("Contract Address is required");
+		return false;
+	}
+	if(!STATE.connected()) {
+		alert("Not connected to the network. Please reload the page if the problem persists.")
+		return false;
+	}
+
+	web3.eth.getCode(contract_address.value).then(function(code) {
+		if(code.length < 4) {
+			alert("no code at " + contract_address.value);
+		}
+	}).catch(function(e) {
+		non_fatal_error("can't load contract at " + contract_address.value, e);
+	});
+
+	extract_rbac_features_roles(contract_address.value).then(features_roles_update).catch(function(e) {
+		console.warn("failed to load RBAC features and roles list", e);
+		features_hex.innerHTML = "Failed to load RBAC features: " + e;
+		roles_list.innerHTML = "Failed to load RBAC roles list: " + e;
+		features_roles_container.style["display"] = "block";
+	}).finally(function() {
+		features_title.innerHTML = "RBAC Features for " + contract_address.value;
+		roles_list_title.innerHTML = "RBAC Operators and Roles for " + contract_address.value;
+	});
+
+	return false;
+}
+</script>
+</html>