Merge pull request #210 from CMTA/dev

CMTAT release v2.3.1

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: Truffle CI
+name: Hardhat CI
 
 on:
   push:
@@ -27,5 +27,5 @@ jobs:
       - name: Install Project Dependencies
         run: npm install
 
-      - name: Run Truffle Test
-        run: npx truffle test
+      - name: Run Hardhat Test
+        run: npx hardhat test

.gitignore

@@ -2,6 +2,7 @@ node_modules
 build
 coverage
 coverage.json
+bin/*
 #exception
 !doc/general/test/coverage
 /.openzeppelin
@@ -15,3 +16,5 @@ artifacts
 cache
 #manticore
 mcore_*
+#secrets
+.env

CHANGELOG.md

@@ -2,6 +2,57 @@
 
 Please follow <https://changelog.md/> conventions.
 
+## 2.3.1-rc.0 - 20230925
+
+### Summary
+**Architecture**
+- The directory `mandatory` is renamed in `core` ([#222](https://github.com/CMTA/CMTAT/pull/222))
+- The directory `optional` is renamed in `extensions` ([#222](https://github.com/CMTA/CMTAT/pull/222))
+- Creation of a directory `controllers` which for the moment contains only the ValidationModule ([#222](https://github.com/CMTA/CMTAT/pull/222))
+- Rename contract and init function for `ERC20BurnModule`, `ERC20MintModule`, `ERC20SnapshotModule` to clearly indicate the inheritance from ERC20 interface ([#226](https://github.com/CMTA/CMTAT/pull/226))
+
+**Gas optimization**
+
+- Add a batch version for the burn, mint and transfer functions (see [#51](https://github.com/CMTA/CMTAT/pull/51))
+- Use custom error instead of string error message ([#217](https://github.com/CMTA/CMTAT/pull/217))
+
+See [Defining Industry Standards for Custom Error Messages](https://blog.openzeppelin.com/defining-industry-standards-for-custom-error-messages-to-improve-the-web3-developer-experience)
+
+**Other**
+
+- Add ERC20 decimals as an argument of the initialize function ([#213](https://github.com/CMTA/CMTAT/pull/213))
+  Until now, the number of decimal was set inside the code to the value 0
+  This release changes this behavior to use instead a parameter supplied by the deployer inside the function initialize.
+- Add a constant VERSION to indicate the current version of the token ([#229](https://github.com/CMTA/CMTAT/pull/229))
+- Implement an alternative to the kill function ([#221](https://github.com/CMTA/CMTAT/pull/221))
+
+The alternative function is the function `deactivateContract` inside the PauseModule, to deactivate the contract. This function set a boolean state variable `isDeactivated` to true and puts the contract in the pause state. The function `unpause`is updated to revert if the previous variable is set to true, thus the contract is in the pause state "forever".
+
+The consequences are the following:
+
+In standalone mode, this operation is irreversible, it is not possible to rollback.
+
+With a proxy, it is still possible to rollback by deploying a new implementation.
+
+**Tools**
+
+- Update the Solidity version to 0.8.20, which is a requirement for the new OpenZeppelin version (5.0.0)
+- Run tests with Hardhat instead of Truffle since Truffle does not support custom errors ([#217](https://github.com/CMTA/CMTAT/pull/51))
+- Update OpenZeppelin to the version [v5.0.0-rc.0](https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable/releases/tag/v5.0.0-rc.0)
+
+**Security**
+- Add new control on the DEFAULT_ADMIN_ROLE by inheriting `AccessControlDefaultAdminRules` ([#220](https://github.com/CMTA/CMTAT/pull/220))
+This contract implements the following risk mitigations on top of [AccessControl](https://docs.openzeppelin.com/contracts/4.x/api/access#AccessControl):
+
+Only one account holds the DEFAULT_ADMIN_ROLE since deployment until it’s potentially renounced.
+
+Enforces a 2-step process to transfer the DEFAULT_ADMIN_ROLE to another account.
+
+Enforces a configurable delay between the two steps, with the ability to cancel before the transfer is accepted.
+
+- Add a function `transferadminshipDirectly` ([#226](https://github.com/CMTA/CMTAT/pull/226))
+- Remove the module `OnlyDelegateCallModule` since it was used to protect the function `kill`, which has been removed in this version ([#221](https://github.com/CMTA/CMTAT/pull/221)).
+
 ## 2.3.0 - 20230609
 
 - Add Truffle CI workflow (Contributor: [diego-G](https://github.com/diego-G) / [21.co](https://github.com/amun))

FAQ.md

@@ -0,0 +1,104 @@
+# FAQ
+
+This FAQ is intended to developers familiar with smart contracts
+development.
+
+## Toolkit support
+
+> Which is the main development tool you use ?
+
+Until the version v.2.3.1, we used `Truffle` with `web3js` as our main development tool and testing library. Since this version, we use *custom errors* to generate errors inside our smart contracts and this type of errors are not supported by `Truffle` for testing.
+
+Therefore, we use `Hardhat` with `web3js` to run our tests, but you can compile the contracts with Truffle or Hardhat.
+
+Regarding [Foundry](https://book.getfoundry.sh/):
+
+-  The plugin "upgrades plugin" by OpenZeppelin is not available with Foundry and it is a very good tool to check the proxy implementation and perform automatic tests. See [https://docs.openzeppelin.com/upgrades-plugins/1.x/](https://docs.openzeppelin.com/upgrades-plugins/1.x/)
+-  The tests for the gasless module (MetaTx) would be difficult to write
+   in Solidity, as Foundry requires, see [https://github.com/CMTA/CMTAT/blob/master/test/common/MetaTxModuleCommon.js](https://github.com/CMTA/CMTAT/blob/master/test/common/MetaTxModuleCommon.js)
+- The OpenZeppelin libraries that we use have their tests mainly written in JavaScript, which provides a good basis for our tests
+- We have a repository [CMTA/CMTAT-Foundry](https://github.com/CMTA/CMTAT-foundry) that provides experimental support for Foundry, but it does not provide complete support and testing for the latest CMTAT version.
+
+
+>  Do you plan to fully support Foundry in the near future? 
+
+For the foreseeable future, we plan to keep Hardhat/Truffle as the main
+development and testing suite.
+
+We have not planned to export all the tests from the Truffle/Hardhat suite to
+their Solidity version equivalent suitable to Foundry, though some tests
+are already available.
+
+The CMTAT-Foundry repository uses CMTAT as a submodule, whose version is
+documented in its
+[README](https://github.com/CMTA/CMTAT-Foundry/blob/main/README.md#cmtat---using-the-foundry-suite).
+
+
+>  Can Truffle be used to run tests?
+
+No. Since the version v.2.31 and the use of `custom errors`, the tests no longer work with Truffle.
+
+You can only run the tests with `Hardhat`.
+
+
+## Modules
+
+> What is the reason the Snapshot module wasn't audited in version v2.3.0?
+
+This module was left out of scope because it is not used yet (and not
+included in a default deployment) and will be
+subject to changes soon. 
+
+> What is the status of [ERC1404](https://erc1404) compatibility?
+
+We have not planned to be fully compatible with ERC1404 (which, in fact,
+is only an EIP at the time of writing). 
+CMTAT includes the two functions defind by ERC1404, namely
+`detectTransferRestriction` and `messageForTransferRestriction`.
+Thus CMTAT can provide the same functionality as ERC1404.
+
+However, from a pure technical perspective, CMTAT is not fully compliant
+with the ERC1404 specification, due the way it inherits the ERC20
+interface. 
+
+> What is the purpose of the flag parameter in the Base module?
+
+It is just a variable to include some additional information under the form of bit fields.
+It is not used inside the code because it is destined to provide more
+information on the tokens to the "outside", for example for the token
+owners.
+
+
+> Is the Validation module optional? 
+
+Generally, for a CMTAT token, the Validation functionality is optional
+from the legal perspective (please contact admin@cmta.ch for detailed
+information).
+
+However, in order to use the functions from the Pause and Enforcement
+modules, our CMTAT implementation requires the Validation module
+Therefore, the Validation module is effectively required *in this
+implementation*. 
+
+If you remove the Validation module and want to use the Pause or the
+Enforcement module, you have to call the functions of modules inside the
+main contracts. It was initially the case but we have changed this
+behavior when addressing an issue reported by a security audit.
+Here is an old version:
+[https://github.com/CMTA/CMTAT/blob/ed23bfc69cfacc932945da751485c6472705c975/contracts/CMTAT.sol#L205](https://github.com/CMTA/CMTAT/blob/ed23bfc69cfacc932945da751485c6472705c975/contracts/CMTAT.sol#L205),
+and the relevant Pull [Request](https://github.com/CMTA/CMTAT/pull/153).
+
+
+## Documentation
+
+> What is the code coverage of the test suite?
+
+A [code coverage report](https://github.com/CMTA/CMTAT/blob/master/doc/general/test/coverage/index.html)
+is available.
+
+Normally, you can run the test suite and generate a code coverage report with `npx hardhat coverage`.
+
+Please clone the repository and open the file inside your browser.
+
+You will find a summary of all automatic tests in
+[test.pdf](https://github.com/CMTA/CMTAT/blob/master/doc/general/test/test.pdf).