@lazy-sol/access-control 1.0.5 → 1.0.6

package/README.md

@@ -4,6 +4,98 @@ A shortcut to a modular and easily pluggable dapp architecture.
 Enable the modular plug and play (PnP) architecture for your dapp by incorporating the role-based access control (RBAC)
 into the smart contracts.
 
+## Technical Overview
+
+Role-based Access Control (RBAC), or simply Access Control, is the base parent contract to be inherited by other smart
+contracts wishing to enable the RBAC feature. It provides an API to check if a specific operation is permitted globally
+and/or if a particular user has a permission to execute it.
+
+It deals with two main entities: features and roles. Features are designed to be used to enable/disable public functions
+of the smart contract (used by a wide audience). User roles are designed to control the access to restricted functions
+of the smart contract (used by a limited set of maintainers).
+
+When designing the RBAC-enabled contract, the best practice is to make all public mutative functions controlled with
+their corresponding feature flags, which can be enabled/disabled during smart contact deployment, setup process, and,
+optionally, during contract operation.
+
+Restricted access functions must be controlled by their corresponding user roles/permissions and usually can be executed
+by the deployer during smart contract deployment and setup process.
+
+After deployment is complete and smart contract setup is verified the deployer should enable the feature flags and
+revoke own permissions to control these flags, as well as permissions to execute restricted access functions.
+
+It is possible that smart contract functionalities are enabled in phases, but the intention is that eventually it is
+also possible to set the smart contract to be uncontrolled by anyone and be fully decentralized.
+
+It is also possible that the deployer shares its admin permissions with other addresses during the deployment and setup
+process, but eventually all these permissions can be revoked from all the addresses involved.
+
+Following diagram summarizes stated below:
+
+![Role-based Access Control (RBAC) Lifecycle](Role-based%20Access%20Control%20%28RBAC%29%20Lifecycle.png)  
+Diagram 1. RBAC-enabled smart contract deployment and setup phases. Contract evolves from the fully controlled in the
+initial phases of the setup process to the fully decentralized and uncontrolled in the end.
+
+It is important to note that it is not necessary, and not recommended to wait until the last “Setup Complete” phase is
+executed to consider the protocol fully operational in the mainnet. In fact, the best practice is to do the launch after
+the deployer permissions are revoked, but there are admin multisig accounts with the full permissions to control the
+protocol. This kind of approach allows reacting to the security issues, which are more likely to happen in the beginning
+of the protocol operation.
+
+## Special Permissions Mapping
+
+Special permissions mapping, `userRoles`, stores special permissions of the smart contract administrators and helpers.
+The mapping is a part of AccessControl and is inherited by the smart contracts using it.
+
+The value stored in the mapping is a 256 bits unsigned integer, each bit of that integer represents a particular
+permission. We call a set of permissions a role. Usually, roles are defined as 32 bits unsigned integer constants, but
+extension to 255 bits is possible.
+
+Permission with the bit 255 set is a special one. It corresponds to the access manager role `ROLE_ACCESS_MANAGER`
+defined on the Access Control smart contract and allows accounts having that bit set to grant/revoke their permissions
+to other addresses and to enable/disable corresponding features of the smart contract (to update self address “this”
+role – see below).
+
+Self address “this” mapping is a special one. It represents the deployed smart contract itself and defines features
+enabled on it. Features control what public functions are enabled and how they behave. Usually, features are defined as
+32 bits unsigned integer constants, but extension to 255 bits is possible.
+
+Access Control is a shared parent for other smart contracts which are free to use any strategy to introduce their
+features and roles. Usually, smart contracts use different values for all the features and roles (see the table in the
+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.
+
+## Comparing with OpenZeppelin
+
+Both our and OpenZeppelin Access Control implementations feature a similar API to check/know "who is allowed to do this
+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 admin for each role, while current allows having only one global admin
+
+Our implementation is more lightweight:
+* it uses only 1 bit per role, while Zeppelin uses 256 bits
+* it allows setting up to 256 roles at once, in a single transaction, while Zeppelin allows setting only one role in a
+  single transaction
+
+## Upgradeability
+
+[Upgradeable Access Control](https://github.com/lazy-sol/access-control-upgradeable) is a Role-based Access Control
+extension supporting the OpenZeppelin UUPS Proxy upgrades. Smart contracts inheriting from the
+`UpgradeableAccessControl` can be deployed behind the ERC1967 proxy and will get the upgradeability mechanism setup.
+
+Upgradeable Access Control introduces another “special” permission bit 254 which is reserved for an upgrade manager role
+`ROLE_UPGRADE_MANAGER` which is allowed to and is responsible for implementation upgrades of the ERC1967 Proxy.
+
+Being controlled by the upgrade manager, the upgradeability is also a revocable feature of the smart contract: the
+`upgradeTo` restricted function access can be revoked from all the admin accounts.
+
+The best practice is to disable contract upgradeability when the protocol is mature enough and has already proven its
+security and stability.
+
 ## Installation
 ```
 npm i -D @lazy-sol/access-control

package/hardhat.config.js

@@ -1,6 +1,6 @@
 /**
  * default Hardhat configuration which uses account mnemonic to derive accounts
- * script expects following environment variables to be set:
+ * script supports the following environment variables set:
  *   - P_KEY1 – mainnet private key, should start with 0x
  *     or
  *   - MNEMONIC1 – mainnet mnemonic, 12 words
@@ -53,6 +53,10 @@
  *     or
  *   - MNEMONIC84532 – Base Sepolia (testnet) Optimistic Rollup (L2) mnemonic, 12 words
  *
+ *   - P_KEY – Custom network (defined by its JSON-RPC) private key, should start with 0x
+ *     or
+ *   - MNEMONIC – Custom network (defined by its JSON-RPC) mnemonic, 12 words
+ *
  *   - ALCHEMY_KEY – Alchemy API key
  *     or
  *   - INFURA_KEY – Infura API key (Project ID)
@@ -85,6 +89,13 @@ require("hardhat-gas-reporter");
 // https://www.npmjs.com/package/hardhat-deploy
 require("hardhat-deploy");
 
+// automatically generate TypeScript bindings for smart contracts while using Hardhat
+// TypeScript bindings help IDEs to properly recognize compiled contracts' ABIs
+// https://github.com/dethcrypto/TypeChain/tree/master/packages/hardhat
+// npm install -D typechain @typechain/hardhat @typechain/truffle-v5
+// run: npx hardhat typechain
+// require("@typechain/hardhat");
+
 // verify environment setup, display warning if required, replace missing values with fakes
 const FAKE_MNEMONIC = "test test test test test test test test test test test junk";
 if(!process.env.MNEMONIC1 && !process.env.P_KEY1) {
@@ -185,19 +196,26 @@ else if(process.env.P_KEY84531 && !process.env.P_KEY84531.startsWith("0x")) {
 }
 if(!process.env.MNEMONIC84532 && !process.env.P_KEY84532) {
 	console.warn("neither MNEMONIC84532 nor P_KEY84532 is not set. Base Sepolia (testnet) deployments won't be available");
-	process.env.MNEMONIC84531 = FAKE_MNEMONIC;
+	process.env.MNEMONIC84532 = FAKE_MNEMONIC;
 }
 else if(process.env.P_KEY84532 && !process.env.P_KEY84532.startsWith("0x")) {
 	console.warn("P_KEY84532 doesn't start with 0x. Appended 0x");
 	process.env.P_KEY84532 = "0x" + process.env.P_KEY84532;
 }
+if(!process.env.MNEMONIC && !process.env.P_KEY) {
+	process.env.MNEMONIC = FAKE_MNEMONIC;
+}
+else if(process.env.P_KEY && !process.env.P_KEY.startsWith("0x")) {
+	console.warn("P_KEY doesn't start with 0x. Appended 0x");
+	process.env.P_KEY = "0x" + process.env.P_KEY;
+}
 if(!process.env.INFURA_KEY && !process.env.ALCHEMY_KEY) {
 	console.warn("neither INFURA_KEY nor ALCHEMY_KEY is not set. Deployments may not be available");
 	process.env.INFURA_KEY = "";
 	process.env.ALCHEMY_KEY = "";
 }
 if(!process.env.ETHERSCAN_KEY) {
-	console.warn("ETHERSCAN_KEY is not set. Deployed smart contract code verification won't be available");
+	console.warn("ETHERSCAN_KEY is not set. Deployed smart contract code verification won't be available on etherscan");
 	process.env.ETHERSCAN_KEY = "";
 }
 if(!process.env.POLYSCAN_KEY) {
@@ -210,6 +228,7 @@ if(!process.env.BSCSCAN_KEY) {
 }
 if(!process.env.BASESCAN_KEY) {
 	console.warn("BASESCAN_KEY is not set. Deployed smart contract code verification won't be available on BaseScan");
+	process.env.BASESCAN_KEY = "";
 }
 
 /**
@@ -303,6 +322,10 @@ module.exports = {
 			url: get_endpoint_url("base_sepolia"),
 			accounts: get_accounts(process.env.P_KEY84532, process.env.MNEMONIC84532),
 		},
+		custom: {
+			url: get_endpoint_url(),
+			accounts: get_accounts(process.env.P_KEY, process.env.MNEMONIC),
+		},
 	},
 
 	// Configure Solidity compiler
@@ -348,6 +371,12 @@ module.exports = {
 		]
 	},
 
+	// configure typechain to generate Truffle v5 bindings
+	typechain: {
+		outDir: "typechain",
+		target: "truffle-v5",
+	},
+
 	// Set default mocha options here, use special reporters etc.
 	mocha: {
 		// timeout: 100000,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazy-sol/access-control",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "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": {
@@ -22,13 +22,13 @@
   "author": "Basil Gorin",
   "license": "MIT",
   "dependencies": {
-    "@lazy-sol/a-missing-gem": "^1.0.4",
+    "@lazy-sol/a-missing-gem": "^1.0.9",
     "@nomiclabs/hardhat-truffle5": "^2.0.7",
-    "hardhat": "^2.22.4",
+    "hardhat": "^2.22.6",
     "hardhat-deploy": "^0.11.45"
   },
   "devDependencies": {
-    "@lazy-sol/zeppelin-test-helpers": "^1.0.0",
+    "@lazy-sol/zeppelin-test-helpers": "^1.0.1",
     "hardhat-gas-reporter": "^1.0.10",
     "solidity-coverage": "^0.8.12"
   },