@lazy-sol/access-control 1.0.3

package/docs/style_guides.md

@@ -0,0 +1,240 @@
+# Style Guides
+
+A programming style guide is an opinionated guide of programming conventions, style, and best practices for a
+team or project.
+
+This section breaks into several subsections depending on the programming, scripting, and markup languages used.
+When new language is added to the project, one should also add a corresponding style guide subsection to this section.
+
+For each language we use, a style guide is based on one or more widely used style guides. When several reference
+guides are used, we assume that the first one is a basic one, and next ones supplement it (contradicting rules
+in the next ones are ignored).
+
+There are always controversial rules leading to endless debates, these rules are more a matter of taste, than a
+rational thing. One of the examples is a famous endless "tabs vs spaces debate".
+For each style guide we maintain the list of these controversial rules together with overridden rules.
+
+This is yet another element for encouraging people to lead a project.
+You get a chance to demonstrate in practice how the rules you've chosen help the development, readability, maintainability, etc.
+
+## JavaScript
+
+JavaScript is a non-class based object oriented programming language that is one of the core technologies of the
+World Wide Web.
+JavaScript was developed in September 1995 by a Netscape programmer Brandan Eich.
+It was originally named Mocha, but quickly became known as LiveScript and, later, JavaScript.
+
+JavaScript's syntax and naming conventions are similar to Java, for example both languages use camelCase to name
+functions and variables, PascalCase for class names, UPPER_CASE for constants.
+JavaScript, however, is not so strict: programs using snake_case instead of camelCase can also be seen widely.
+
+We use [Airbnb Javascript Style Guide](https://github.com/airbnb/javascript) as a base.
+Following rules are considered contentious (to be extended) and/or are overridden:
+
+- [Whitespace](https://github.com/airbnb/javascript#whitespace)
+    - use of soft tabs (space character) set to 2 spaces (eslint: indent)
+    - **no** spaces inside curly braces (eslint: object-curly-spacing: **"never"**)  
+        **reason:** monospace fonts have already enough spare space in braces, commas, dots, etc.
+        to make these symbols clearly distinguishable from the literals' symbols
+    - characters per line limit (eslint: max-len): **120**
+        **reason:**: most of the screens allow to easily see 120 characters in one line
+- [Blocks](https://github.com/airbnb/javascript#blocks)
+    - `else` statements in an `if-else` construct, as well as `catch` and `finally`,
+    must be **on its own line** after the preceding closing brace (eslint: brace-style: **"stroustrup"**)
+        **reason:** this makes `if-else` blocks better distinguishable when statements inside are very short
+- [Naming Conventions](https://github.com/airbnb/javascript#naming-conventions)
+    - camelCase naming for objects, functions, and instances (eslint: camelcase)
+
+## TypeScript
+
+TypeScript is a strongly typed programming language that builds on JavaScript, developed by Microsoft, published
+in 2012.
+
+TypeScript style guide inherits from [JavaScript](#javascript) and is enriched with
+[Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html), which is used basically
+to cover areas not covered in [Airbnb Javascript Style Guide](https://github.com/airbnb/javascript).
+
+## Solidity
+
+Solidity is an object-oriented programming language for implementing smart contracts.
+Solidity was proposed in August 2014 by Dr. Gavin Wood.
+As specified by Dr. Gavin Wood, Solidity is designed around the JavaScript syntax to make it familiar for existing web
+developers.
+
+Solidity inherits its syntax and naming conventions from JavaScript. Both languages use camelCase naming for
+functions and variables, PascalCase for class names, UPPER_CASE for constants.
+
+We use [Official Solidity Style Guide](https://docs.soliditylang.org/en/v0.8.16/style-guide.html) as a base,
+enriched with [Official Java Code Conventions](https://www.oracle.com/technetwork/java/codeconventions-150003.pdf)
+(for example, Official Solidity Guide misses ideas on interface naming).
+Following rules are considered contentious and/or are overridden:
+
+- Tabs or Spaces: spaces are the preferred indentation method
+- `else` statements in an `if-else` construct must be **on its own line** after the preceding closing brace
+
+Prefer `Interface` naming to Zeppelin's `IInterface` one.
+Name the interface by answering the question "what it is?", based on functional requirements. A `Truck`.
+Name the implementation contract by answering the question "how it works?", or "what it looks like?",
+based on non-functional requirements. A `RedTruck`.
+ERC standards like ERC20, ERC721, and others are effectively interfaces already and do not require an "I" prefix.
+
+Bad:
+
+```
+interface IPriceOracle {
+...
+}
+contract PriceOracle is IPriceOracle {
+...
+}
+```
+
+Good:
+
+```
+interface PriceOracle {
+...
+}
+contract PriceOracleV1 is PriceOracle {
+...
+}
+```
+
+Bad:
+
+```
+interface IERC20 {
+...
+}
+contract Token is IERC20 {
+...
+}
+```
+
+Good:
+
+```
+interface ERC20 {
+...
+}
+contract Token is ERC20 {
+...
+}
+```
+
+## Markdown
+
+Markdown is a lightweight markup language created by John Gruber and Aaron Swartz in 2004 with the goal to be
+appealing to human readers in its source code form. Markdown was standardized in 2012-2016.
+
+We use [Google Markdown Style Guide](https://google.github.io/styleguide/docguide/style.html) as a base,
+enriched with [Matt Cone Markdown Style Guide](https://www.markdownguide.org/basic-syntax/).
+Following rules are considered contentious and/or are overridden:
+
+- [Trailing whitespace](https://google.github.io/styleguide/docguide/style.html#trailing-whitespace)
+    / [Line Breaks Best Practices](https://www.markdownguide.org/basic-syntax/#line-break-best-practices):
+    don't use the trailing backslash, use trailing whitespace and ensure .editorconfig has
+    `trim_trailing_whitespace = false` for `*.md` files
+
+## Automating Formatting Standards
+
+The above standards can be more easily met by automating their implementation.
+Many repositories will have a `.editorconfig` file, which tells editors how to interpret inputs, such as tab.
+The EditorConfig file is read automatically by many IDEs, including WebStorm, IntellijIDEA and Visual Studio,
+but is **not** picked up automatically by many even related tools including PHPStorm, Sublime, Eclipse,
+and Visual Studio Code: a [supporting plugin](https://editorconfig.org/) should be used.
+You should ensure your IDE setup supports these editor expectations.
+
+Optionally you may additionally use Prettier or a similar formatter.
+Prettier is an opinionated code formatter, which uses sensible defaults that can often (but not always)
+be overridden in a `.prettierrc` file.
+Prettier will also inspect `.editorconfig` files and use those settings as its defaults.
+Note that Visual Studio Code includes Prettier formatter by default, and its Format command triggers it.
+It can also be configured to trigger on-save.
+
+Prettier should **not** be used on existing projects that already have an established standard.
+
+Finally, a _linter_ such as eslint or solhint may be a good option to be used.
+Linters dynamically inspect code and point out potential issues.
+This can include style issues as above but also code quality issues like unused variables,
+deprecated functions, unreachable code, etc.
+Installing the solidity plugin for Visual Studio Code automatically installs a linter.
+
+Note that the above tools can all be used together. EditorConfig works as you type, ensuring you meet standards,
+Prettier formats your code after you write it, while linters highlight, but do not fix, potential quality issues.
+
+## Testing Standards and Style Guidelines
+
+Testing smart contracts is of critical importance. Tests are used to validate security requirements,
+and to confirm behaviour to be as expected and intended.
+Proper testing of any software is a difficult skill that takes a long time to learn. Here are some important guides.
+
+**Unit testing** is intended to test a single, specific behaviour, such as a function.
+In the context of smart contracts this typically means to execute a function and then check the resulting state
+and events emitted.
+
+Unit testing forms the vast majority of test cases and requires large numbers of simple tests,
+with each test verifying a single aspect of behaviour.
+It should be possible for any failed test to immediately identify the error.
+
+Unit tests are often built in a way phrased as _arrange-act-assert_.
+Arrange is the process to set up the contract to a suitable initial state.
+Act is executing the desired function.
+Assert is verifying the state changes occurred and events emitted.
+
+Arrange steps **do not belong to the test function** and should be implemented as part of a `beforeEach` or similar
+hook which sets up the state for all the tests.
+Use `describe` blocks to separate test functionality that has different state setup.
+
+It is vitally important that tests are not an afterthought, but a key part of the development deliverable.
+This means that the test should cover not just "the behaviour", but edge cases, error handling, permission checking,
+bounds-checking and other similar difficulties. "Happy path" testing is of minimal value.
+
+Some important points on unit tests:
+
+- Only test one thing at a time - do not run compound tests
+- Each test must be independent
+- Consider making utility functions for things like state setup to ensure simplicity and consistency
+- Separate contracts by a file and only test one contract per file
+- Separate functionality areas with `describe` blocks, and note you can nest these blocks for sub-functionality
+- Tests should be as small as possible, ideally only one line, or a few lines
+- You can append `.only` to a test case while implementing it, to isolate that one test (not to run the whole suite
+    during the test development), though keep in mind that the entire suite must also work
+- Do not add suite setup to `beforeEach`, as this will run before every test.
+    For example, getting all the accounts from the provider can be implemented either as global function, or if
+    using async mode - can be run in the `before` hook, which runs one single time.
+- Ensure the test checks function execution constraints (contract state, function input params, access control), smart
+    contract state change(s), event emission(s)
+- Favour constants (or TypeScript enums) for testing values, as they can convey meaning and be reused as the
+    assertion value
+
+Many areas of functionality may also implement an end-to-end test, where multiple steps are undertaken in order
+to ensure a cohesive and correct workflow.
+These typically act as a "sanity check" to verify complex behaviours work as intended.
+Such tests supplement, but do not replace, comprehensive unit tests.
+
+Code Coverage reports can be generated with `npm run coverage`.
+Reports show the coverage as a percentage of lines covered with tests.
+It is important to ensure this is not reduced by your modifications.
+It is also important the testing is not done **solely** to increase the test coverage percentage.
+Instead, the code coverage outputs are used to highlight areas where tests are lacking.
+The coverage reports generate output artifacts that show line-by-line where code is untested,
+as well as summaries by files overall.
+
+When beginning a new block of work you should ensure that you run the coverage report prior to starting
+to ensure your changes do not lower the code coverage.
+
+See also: [Gitlab Testing Standards](https://docs.gitlab.com/ee/development/testing_guide/)
+
+## References
+1. Srđan Popić, Gordana Velikić at al.
+    The Benefits of the Coding Standards Enforcement and it's Influence on the
+    Developers' Coding Behaviour: A Case Study on Two Small Projects
+2. [Coding standards: what are they, and why do you need
+    them](https://blog.codacy.com/coding-standards-what-are-they-and-why-do-you-need-them/)
+
+## About
+
+Prepared by Basil Gorin
+
+(c) 2017–2024 Basil Gorin

package/hardhat.config.js

@@ -0,0 +1,359 @@
+/**
+ * default Hardhat configuration which uses account mnemonic to derive accounts
+ * script expects following environment variables to be set:
+ *   - P_KEY1 – mainnet private key, should start with 0x
+ *     or
+ *   - MNEMONIC1 – mainnet mnemonic, 12 words
+ *
+ *   - P_KEY3 – ropsten private key, should start with 0x
+ *     or
+ *   - MNEMONIC3 – ropsten mnemonic, 12 words
+ *
+ *   - P_KEY4 – rinkeby private key, should start with 0x
+ *     or
+ *   - MNEMONIC4 – rinkeby mnemonic, 12 words
+ *
+ *   - P_KEY41 – kovan private key, should start with 0x
+ *     or
+ *   - MNEMONIC41 – kovan mnemonic, 12 words
+ *
+ *   - P_KEY5 – goerli private key, should start with 0x
+ *     or
+ *   - MNEMONIC5 – goerli mnemonic, 12 words
+ *
+ *   - P_KEY137 – polygon/matic private key, should start with 0x
+ *     or
+ *   - MNEMONIC137 – polygon/matic mnemonic, 12 words
+ *
+ *   - P_KEY80001 – mumbai (polygon testnet) private key, should start with 0x
+ *     or
+ *   - MNEMONIC80001 – mumbai (polygon testnet) mnemonic, 12 words
+ *
+ *   - P_KEY56 – Binance Smart Chain (BSC) mainnet private key, should start with 0x
+ *     or
+ *   - MNEMONIC56 – Binance Smart Chain (BSC) mainnet mnemonic, 12 words
+ *
+ *   - P_KEY97 – Binance Smart Chain (BSC) testnet private key, should start with 0x
+ *     or
+ *   - MNEMONIC97 – Binance Smart Chain (BSC) testnet mnemonic, 12 words
+ *
+ *   - ALCHEMY_KEY – Alchemy API key
+ *     or
+ *   - INFURA_KEY – Infura API key (Project ID)
+ *
+ *   - ETHERSCAN_KEY – Etherscan API key
+ *
+ *   - POLYSCAN_KEY – polygonscan API key
+ *
+ *   - BSCSCAN_KEY – BscScan API key
+ *
+ *   - REPORT_GAS - optional, set it to true to print gas usage info
+ */
+
+// Enable Truffle 5 plugin for tests
+// https://hardhat.org/guides/truffle-testing.html
+require("@nomiclabs/hardhat-truffle5");
+
+// enable Solidity-coverage
+// https://hardhat.org/plugins/solidity-coverage.html
+require("solidity-coverage");
+
+// enable hardhat-gas-reporter
+// https://github.com/cgewecke/hardhat-gas-reporter
+require("hardhat-gas-reporter");
+
+// adds a mechanism to deploy contracts to any network,
+// keeping track of them and replicating the same environment for testing
+// https://www.npmjs.com/package/hardhat-deploy
+require("hardhat-deploy");
+
+// 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) {
+	console.warn("neither MNEMONIC1 nor P_KEY1 is not set. Mainnet deployments won't be available");
+	process.env.MNEMONIC1 = FAKE_MNEMONIC;
+}
+else if(process.env.P_KEY1 && !process.env.P_KEY1.startsWith("0x")) {
+	console.warn("P_KEY1 doesn't start with 0x. Appended 0x");
+	process.env.P_KEY1 = "0x" + process.env.P_KEY1;
+}
+if(!process.env.MNEMONIC3 && !process.env.P_KEY3) {
+	console.warn("neither MNEMONIC3 nor P_KEY3 is not set. Ropsten deployments won't be available");
+	process.env.MNEMONIC3 = FAKE_MNEMONIC;
+}
+else if(process.env.P_KEY3 && !process.env.P_KEY3.startsWith("0x")) {
+	console.warn("P_KEY3 doesn't start with 0x. Appended 0x");
+	process.env.P_KEY3 = "0x" + process.env.P_KEY3;
+}
+if(!process.env.MNEMONIC4 && !process.env.P_KEY4) {
+	console.warn("neither MNEMONIC4 nor P_KEY4 is not set. Rinkeby deployments won't be available");
+	process.env.MNEMONIC4 = FAKE_MNEMONIC;
+}
+else if(process.env.P_KEY4 && !process.env.P_KEY4.startsWith("0x")) {
+	console.warn("P_KEY4 doesn't start with 0x. Appended 0x");
+	process.env.P_KEY4 = "0x" + process.env.P_KEY4;
+}
+if(!process.env.MNEMONIC42 && !process.env.P_KEY42) {
+	console.warn("neither MNEMONIC42 nor P_KEY42 is not set. Kovan deployments won't be available");
+	process.env.MNEMONIC42 = FAKE_MNEMONIC;
+}
+else if(process.env.P_KEY42 && !process.env.P_KEY42.startsWith("0x")) {
+	console.warn("P_KEY42 doesn't start with 0x. Appended 0x");
+	process.env.P_KEY42 = "0x" + process.env.P_KEY42;
+}
+if(!process.env.MNEMONIC5 && !process.env.P_KEY5) {
+	console.warn("neither MNEMONIC5 nor P_KEY5 is not set. Goerli deployments won't be available");
+	process.env.MNEMONIC5 = FAKE_MNEMONIC;
+}
+else if(process.env.P_KEY5 && !process.env.P_KEY5.startsWith("0x")) {
+	console.warn("P_KEY5 doesn't start with 0x. Appended 0x");
+	process.env.P_KEY5 = "0x" + process.env.P_KEY5;
+}
+if(!process.env.MNEMONIC137 && !process.env.P_KEY137) {
+	console.warn("neither MNEMONIC137 nor P_KEY137 is not set. Polygon mainnet deployments won't be available");
+	process.env.MNEMONIC137 = FAKE_MNEMONIC;
+}
+else if(process.env.P_KEY137 && !process.env.P_KEY137.startsWith("0x")) {
+	console.warn("P_KEY137 doesn't start with 0x. Appended 0x");
+	process.env.P_KEY137 = "0x" + process.env.P_KEY137;
+}
+if(!process.env.MNEMONIC80001 && !process.env.P_KEY80001) {
+	console.warn("neither MNEMONIC80001 nor P_KEY80001 is not set. Mumbai (matic/polygon L2 testnet) deployments won't be available");
+	process.env.MNEMONIC80001 = FAKE_MNEMONIC;
+}
+else if(process.env.P_KEY80001 && !process.env.P_KEY80001.startsWith("0x")) {
+	console.warn("P_KEY80001 doesn't start with 0x. Appended 0x");
+	process.env.P_KEY80001 = "0x" + process.env.P_KEY80001;
+}
+if(!process.env.MNEMONIC56 && !process.env.P_KEY56) {
+	console.warn("neither MNEMONIC56 nor P_KEY56 is not set. Binance Smart Chain (BSC) mainnet deployments won't be available");
+	process.env.MNEMONIC56 = FAKE_MNEMONIC;
+}
+else if(process.env.P_KEY56 && !process.env.P_KEY56.startsWith("0x")) {
+	console.warn("P_KEY56 doesn't start with 0x. Appended 0x");
+	process.env.P_KEY56 = "0x" + process.env.P_KEY56;
+}
+if(!process.env.MNEMONIC97 && !process.env.P_KEY97) {
+	console.warn("neither MNEMONIC97 nor P_KEY97 is not set. Binance Smart Chain (BSC) testnet deployments won't be available");
+	process.env.MNEMONIC97 = FAKE_MNEMONIC;
+}
+else if(process.env.P_KEY97 && !process.env.P_KEY97.startsWith("0x")) {
+	console.warn("P_KEY97 doesn't start with 0x. Appended 0x");
+	process.env.P_KEY97 = "0x" + process.env.P_KEY97;
+}
+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");
+	process.env.ETHERSCAN_KEY = "";
+}
+if(!process.env.POLYSCAN_KEY) {
+	console.warn("POLYSCAN_KEY is not set. Deployed smart contract code verification won't be available on polyscan");
+	process.env.POLYSCAN_KEY = "";
+}
+if(!process.env.BSCSCAN_KEY) {
+	console.warn("BSCSCAN_KEY is not set. Deployed smart contract code verification won't be available on BscScan");
+	process.env.BSCSCAN_KEY = "";
+}
+
+/**
+ * @type import('hardhat/config').HardhatUserConfig
+ */
+module.exports = {
+	defaultNetwork: "hardhat",
+	networks: {
+		// https://hardhat.org/hardhat-network/
+		hardhat: {
+			// set networkId to 0xeeeb04de as for all local networks
+			chainId: 0xeeeb04de,
+			// set the gas price to one for convenient tx costs calculations in tests
+			// gasPrice: 1,
+			// London hard fork fix: impossible to set gas price lower than baseFeePerGas (875,000,000)
+			initialBaseFeePerGas: 0,
+			accounts: {
+				count: 35,
+			},
+/*
+			forking: {
+				url: "https://mainnet.infura.io/v3/" + process.env.INFURA_KEY, // create a key: https://infura.io/
+				enabled: !!(process.env.HARDHAT_FORK),
+			},
+*/
+		},
+		// https://etherscan.io/
+		mainnet: {
+			url: get_endpoint_url("mainnet"),
+			accounts: get_accounts(process.env.P_KEY1, process.env.MNEMONIC1),
+		},
+		// https://ropsten.etherscan.io/
+		ropsten: {
+			url: get_endpoint_url("ropsten"),
+			accounts: get_accounts(process.env.P_KEY3, process.env.MNEMONIC3),
+		},
+		// https://rinkeby.etherscan.io/
+		rinkeby: {
+			url: get_endpoint_url("rinkeby"),
+			accounts: get_accounts(process.env.P_KEY4, process.env.MNEMONIC4),
+		},
+		// https://kovan.etherscan.io/
+		kovan: {
+			url: get_endpoint_url("kovan"),
+			accounts: get_accounts(process.env.P_KEY42, process.env.MNEMONIC42),
+		},
+		// https://goerli.etherscan.io/
+		goerli: {
+			url: get_endpoint_url("goerli"),
+			accounts: get_accounts(process.env.P_KEY5, process.env.MNEMONIC5),
+		},
+		// matic/polygon L2 mainnet
+		// https://polygonscan.com/
+		polygon: {
+			url: "https://polygon-rpc.com/",
+			accounts: get_accounts(process.env.P_KEY137, process.env.MNEMONIC137),
+		},
+		// matic/polygon L1 testnet – Mumbai
+		// https://mumbai.polygonscan.com/
+		mumbai: {
+			url: "https://rpc-mumbai.maticvigil.com",
+			accounts: get_accounts(process.env.P_KEY80001, process.env.MNEMONIC80001),
+		},
+		// Binance Smart Chain (BSC) L2 mainnet
+		binance: {
+			url: "https://bsc-dataseed1.binance.org/",
+			accounts: get_accounts(process.env.P_KEY56, process.env.MNEMONIC56),
+		},
+		// Binance Smart Chain (BSC) L2 testnet
+		binance_testnet: {
+			url: "https://data-seed-prebsc-1-s3.binance.org:8545/",
+			accounts: get_accounts(process.env.P_KEY97, process.env.MNEMONIC97),
+		},
+	},
+
+	// Configure Solidity compiler
+	solidity: {
+		// https://hardhat.org/guides/compile-contracts.html
+		compilers: [
+			{
+				version: "0.8.21",
+				settings: {
+					optimizer: {
+						enabled: true,
+						runs: 200
+					}
+				}
+			},
+			{
+				version: "0.6.2",
+				settings: {
+					optimizer: {
+						enabled: true,
+						runs: 200
+					}
+				}
+			},
+			{
+				version: "0.4.22",
+				settings: {
+					optimizer: {
+						enabled: true,
+						runs: 200
+					}
+				}
+			},
+			{
+				version: "0.4.11",
+				settings: {
+					optimizer: {
+						enabled: true,
+						runs: 200
+					}
+				}
+			},
+		]
+	},
+
+	// Set default mocha options here, use special reporters etc.
+	mocha: {
+		// timeout: 100000,
+
+		// disable mocha timeouts:
+		// https://mochajs.org/api/mocha#enableTimeouts
+		enableTimeouts: false,
+		// https://github.com/mochajs/mocha/issues/3813
+		timeout: false,
+	},
+
+	// hardhat-gas-reporter will be disabled by default, use REPORT_GAS environment variable to enable it
+	// https://hardhat.org/plugins/hardhat-gas-reporter.html
+	gasReporter: {
+		enabled: !!(process.env.REPORT_GAS)
+	},
+}
+
+/**
+ * Determines a JSON-RPC endpoint to use to connect to the node
+ * based on the requested network name and environment variables set
+ *
+ * Tries to use custom RPC URL first (MAINNET_RPC_URL/ROPSTEN_RPC_URL/RINKEBY_RPC_URL/KOVAN_RPC_URL)
+ * Tries to use alchemy RPC URL next (if ALCHEMY_KEY is set)
+ * Fallbacks to infura RPC URL
+ *
+ * @param network_name one of mainnet/ropsten/rinkeby/kovan
+ * @return JSON-RPC endpoint URL
+ */
+function get_endpoint_url(network_name) {
+	// try custom RPC endpoint first (private node, quicknode, etc.)
+	// create a quicknode key: https://www.quicknode.com/
+	if(process.env.MAINNET_RPC_URL && network_name === "mainnet") {
+		return process.env.MAINNET_RPC_URL;
+	}
+	if(process.env.ROPSTEN_RPC_URL && network_name === "ropsten") {
+		return process.env.ROPSTEN_RPC_URL;
+	}
+	if(process.env.RINKEBY_RPC_URL && network_name === "rinkeby") {
+		return process.env.RINKEBY_RPC_URL;
+	}
+	if(process.env.KOVAN_RPC_URL && network_name === "kovan") {
+		return process.env.KOVAN_RPC_URL;
+	}
+	if(process.env.GOERLI_RPC_URL && network_name === "goerli") {
+		return process.env.GOERLI_RPC_URL;
+	}
+
+	// try the alchemy next
+	// create a key: https://www.alchemy.com/
+	if(process.env.ALCHEMY_KEY) {
+		switch(network_name) {
+			case "mainnet": return "https://eth-mainnet.alchemyapi.io/v2/" + process.env.ALCHEMY_KEY;
+			case "ropsten": return "https://eth-ropsten.alchemyapi.io/v2/" + process.env.ALCHEMY_KEY;
+			case "rinkeby": return "https://eth-rinkeby.alchemyapi.io/v2/" + process.env.ALCHEMY_KEY;
+			case "kovan": return "https://eth-kovan.alchemyapi.io/v2/" + process.env.ALCHEMY_KEY;
+			case "goerli": return "https://eth-goerli.alchemyapi.io/v2/" + process.env.ALCHEMY_KEY;
+		}
+	}
+
+	// fallback to infura
+	// create a key: https://infura.io/
+	switch(network_name) {
+		case "mainnet": return "https://mainnet.infura.io/v3/" + process.env.INFURA_KEY;
+		case "ropsten": return "https://ropsten.infura.io/v3/" + process.env.INFURA_KEY;
+		case "rinkeby": return "https://rinkeby.infura.io/v3/" + process.env.INFURA_KEY;
+		case "kovan": return "https://kovan.infura.io/v3/" + process.env.INFURA_KEY;
+		case "goerli": return "https://goerli.infura.io/v3/" + process.env.INFURA_KEY;
+	}
+}
+
+/**
+ * Depending on which of the inputs are available (private key or mnemonic),
+ * constructs an account object for use in the hardhat config
+ *
+ * @param p_key account private key, export private key from mnemonic: https://metamask.io/
+ * @param mnemonic 12 words mnemonic, create 12 words: https://metamask.io/
+ * @return either [p_key] if p_key is defined, or {mnemonic} if mnemonic is defined
+ */
+function get_accounts(p_key, mnemonic) {
+	return p_key? [p_key]: mnemonic? {mnemonic, initialIndex: 0}: undefined;
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@lazy-sol/access-control",
+  "version": "1.0.3",
+  "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": {
+    "clean": "hardhat clean",
+    "compile": "hardhat compile",
+    "test": "hardhat test",
+    "coverage": "hardhat coverage",
+    "deploy": "hardhat deploy"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "keywords": [
+    "RBAC",
+    "Solidity",
+    "access control",
+    "modular architecture"
+  ],
+  "author": "Basil Gorin",
+  "license": "MIT",
+  "dependencies": {
+    "@lazy-sol/a-missing-gem": "^1.0.0",
+    "@nomiclabs/hardhat-truffle5": "^2.0.7",
+    "hardhat": "^2.16.0",
+    "hardhat-deploy": "^0.11.45"
+  },
+  "devDependencies": {
+    "@lazy-sol/zeppelin-test-helpers": "^1.0.0",
+    "hardhat-gas-reporter": "^1.0.10",
+    "solidity-coverage": "^0.8.10"
+  },
+  "overrides": {
+    "tough-cookie": "^4.1.3",
+    "yargs-parser": "^5.0.1"
+  }
+}

package/test/adapter_factory.js

@@ -0,0 +1,54 @@
+// AdapterFactory tests
+
+// Zeppelin test helpers
+const {
+	BN,
+	constants,
+	expectEvent,
+	expectRevert,
+} = require("@openzeppelin/test-helpers");
+const {
+	assert,
+	expect,
+} = require("chai");
+const {
+	ZERO_ADDRESS,
+	ZERO_BYTES32,
+	MAX_UINT256,
+} = constants;
+
+// deployment routines in use
+const {
+	deploy_usdt,
+	deploy_adapter_factory,
+	factory_deploy_ownable_to_ac_adapter,
+} = require("./include/deployment_routines");
+
+// run AdapterFactory tests
+contract("AdapterFactory tests", function(accounts) {
+	// extract accounts to be used:
+	// A0 – special default zero account accounts[0] used by Truffle, reserved
+	// a0 – deployment account having all the permissions, reserved
+	// H0 – initial token holder account
+	// a1, a2,... – working accounts to perform tests on
+	const [A0, a0, H0, a1, a2, a3] = accounts;
+
+	let usdt, factory;
+	beforeEach(async function() {
+		usdt = await deploy_usdt(a1);
+		factory = await deploy_adapter_factory();
+	});
+
+	it("adapter deployment fails if executed not by the ownable owner", async function() {
+		await expectRevert(factory_deploy_ownable_to_ac_adapter(a2, factory, usdt), "not an owner");
+	});
+	describe("adapter deployment succeeds if executed by the ownable owner", async function() {
+		let adapter;
+		beforeEach(async function() {
+			({adapter} = await factory_deploy_ownable_to_ac_adapter(a1, factory, usdt));
+		});
+		it("adapter's target is set correctly", async function() {
+			expect(await adapter.target()).to.be.equal(usdt.address);
+		});
+	});
+});