Merge pull request #233 from CMTA/docv2-v2.3.1

Docv v2.3.1

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

@@ -5,30 +5,27 @@ development.
 
 ## Toolkit support
 
-> Why do you continue using Truffle instead of migrating to HardHat or Foundry?
+> Which is the main development tool you use ?
 
-Regarding [Hardhat](https://hardhat.org/):
+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.
 
-- Our tests are not working with Hardhat so to migrate to hardhat, we will have to update our tests which will require a lot of works.
-- Moreover, we do not see a use case where hardhat will be better than Truffle.
-- Hardhat has a lot of plugins, but for example, for the coverage, we can run the coverage without be fully compatible with Hardhat.
+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
-- Performance wise, we observed that Foundry is superior to Truffle, notably to test the Snapshot module
 - 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 Truffle as the main
+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 suite to
+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.
 
@@ -37,9 +34,11 @@ documented in its
 [README](https://github.com/CMTA/CMTAT-Foundry/blob/main/README.md#cmtat---using-the-foundry-suite).
 
 
->  Can Hardhat be used to run tests?
+>  Can Truffle be used to run tests?
 
-No, please use Truffle to run the 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
@@ -84,7 +83,7 @@ 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
-behaviour when addressing an issue reported by a security audit.
+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).

README.md

@@ -31,7 +31,7 @@ order to support:
 This reference implementation allows the issuance and management of tokens representing equity securities.
 It can however also be used for other forms of financial instruments such as debt securities.
 
-You may modify the token code by adding, removing, or modifying features. However, the mandatory modules must remain in place for compliance with Swiss law.
+You may modify the token code by adding, removing, or modifying features. However, the core modules must remain in place for compliance with Swiss law.
 
 ### Deployment model 
 
@@ -63,46 +63,63 @@ Please see the OpenGSN [documentation](https://docs.opengsn.org/contracts/#recei
 ### Kill switch
 
 CMTAT initially supported a `kill()` function relying on the SELFDESTRUCT opcode (which effectively destroyed the contract's storage and code).
-However, Ethereum's [Cancun update](https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/cancun.md) (rolled out in the second half of
-2023) will remove support for SELFDESTRUCT (see
+However, Ethereum's [Cancun update](https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/cancun.md) (rolled out in the second half of 2023)  will remove support for SELFDESTRUCT (see
 [EIP-6780](https://eips.ethereum.org/EIPS/eip-6780)).
 
-The `kill()` function will therefore not behave as it used to once Cancun is deployed.  As an alternative, the token contract can be paused indefinitely, and a new contract deployed (and the proxy modified accordingly).
+The `kill()` function will therefore not behave as it used to once Cancun is deployed.  
+
+The alternative function is the function `deactivateContract`, introduced in the version v2.3.1 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.
+
 
 
 ## Modules
 
 Here the list of the differents modules with the links towards the documentation and the main file.
 
-### Mandatory
+### Controller
+
+| Name             | Documentation                                                | Main File                                                    |
+| ---------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
+| ValidationModule | [validation.md](doc/modules/presentation/controllers/validation.md) | [ValidationModule.sol](./contracts/modules/wrapper/controllers/ValidationModule.sol) |
+
+### Core
+
+Generally, these modules are required to be compliant with the CMTA specification.
 
 | Name              | Documentation                                                | Main File                                                    |
 | ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| BaseModule        | [base.md](doc/modules/presentation/mandatory/base.md)        | [BaseModule.sol](./contracts/modules/wrapper/mandatory/BaseModule.sol) |
-| BurnModule        | [burn.md](doc/modules/presentation/mandatory/burn.md)        | [BurnModule.sol](./contracts/modules/wrapper/mandatory/BurnModule.sol) |
-| EnforcementModule | [enforcement.md](doc/modules/presentation/mandatory/enforcement.md) | [EnforcementModule.sol](./contracts/modules/wrapper/mandatory/EnforcementModule.sol) |
-| ERC20BaseModule   | [erc20base.md](doc/modules/presentation/mandatory/erc20base.md) | [ERC20BaseModule.sol](./contracts/modules/wrapper/mandatory/ERC20BaseModule.sol) |
-| MintModule        | [mint.md](doc/modules/presentation/mandatory/mint.md)        | [MintModule.sol](./contracts/modules/wrapper/mandatory/MintModule.sol) |
-| PauseModule       | [pause.md](doc/modules/presentation/mandatory/pause.md)      | [PauseModule.sol](./contracts/modules/wrapper/mandatory/PauseModule.sol) |
+| BaseModule        | [base.md](doc/modules/presentation/core/base.md)             | [BaseModule.sol](./contracts/modules/wrapper/core/BaseModule.sol) |
+| BurnModule        | [ERC20Burn.md](doc/modules/presentation/core/ERC20Burn.md)   | [ERC20BurnModule.sol](./contracts/modules/wrapper/core/ERC20BurnModule.sol) |
+| EnforcementModule | [enforcement.md](doc/modules/presentation/core/enforcement.md) | [EnforcementModule.sol](./contracts/modules/wrapper/core/EnforcementModule.sol) |
+| ERC20BaseModule   | [erc20base.md](doc/modules/presentation/core/erc20base.md)   | [ERC20BaseModule.sol](./contracts/modules/wrapper/core/ERC20BaseModule.sol) |
+| MintModule        | [ERC20Mint.md](doc/modules/presentation/core/ERC20Mint.md)   | [ERC20MintModule.sol](./contracts/modules/wrapper/core/ERC20MintModule.sol) |
+| PauseModule       | [pause.md](doc/modules/presentation/core/pause.md)           | [PauseModule.sol](./contracts/modules/wrapper/core/PauseModule.sol) |
 
-### Optional
+### Extensions
+
+Generally, these modules are not required to be compliant with the CMTA specification.
 
 | Name              | Documentation                                                | Main File                                                    |
 | ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| MetaTxModule      | [metatx.md](doc/modules/presentation/optional/metatx.md)     | [MetaTxModule.sol](./contracts/modules/wrapper/optional/MetaTxModule.sol) |
-| SnapshotModule*   | [snapshot.md](doc/modules/presentation/optional/snapshot.md) | [SnapshotModule.sol](./contracts/modules/wrapper/optional/SnapshotModule.sol) |
-| ValidationModule  | [validation.md](doc/modules/presentation/optional/validation.md) | [ValidationModule.sol](./contracts/modules/wrapper/optional/SnapshotModule.sol) |
-| creditEventModule | [creditEvents.md](doc/modules/presentation/optional/Debt/creditEvents.md) | [CreditEventsModule.sol](./contracts/modules/wrapper/optional/DebtModule/CreditEventsModule.sol) |
-| DebtBaseModule    | [debtBase.md](doc/modules/presentation/optional/Debt/debtBase.md) | [DebtBaseModule.sol](./contracts/modules/wrapper/optional/DebtModule/DebtBaseModule.sol) |
+| MetaTxModule      | [metatx.md](doc/modules/presentation/extensions/metatx.md)   | [MetaTxModule.sol](./contracts/modules/wrapper/extensions/MetaTxModule.sol) |
+| SnapshotModule*   | [snapshot.md](doc/modules/presentation/extensions/snapshot.md) | [SnapshotModule.sol](./contracts/modules/wrapper/extensions/SnapshotModule.sol) |
+| creditEventModule | [creditEvents.md](doc/modules/presentation/extensions/Debt/creditEvents.md) | [CreditEventsModule.sol](./contracts/modules/wrapper/extensions/DebtModule/CreditEventsModule.sol) |
+| DebtBaseModule    | [debtBase.md](doc/modules/presentation/extensions/Debt/debtBase.md) | [DebtBaseModule.sol](./contracts/modules/wrapper/extensions/DebtModule/DebtBaseModule.sol) |
 
 *not imported by default
 
 ### Security
 
-| Name                   | Documentation                                                | Main File                                                    |
-| ---------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| AuthorizationModule    | [authorization.md](./doc/modules/presentation/security/authorization.md) | [AuthorizationModule.sol](./contracts/modules/security/AuthorizationModule.sol) |
-| OnlyDelegateCallModule | [onlyDelegateCallModule.md](./doc/modules/presentation/security/onlyDelegateCallModule.md) | [OnlyDelegateCallModule.sol](./contracts/modules/security/OnlyDelegateCallModule.sol) |
+| Name                | Documentation                                                | Main File                                                    |
+| ------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
+| AuthorizationModule | [authorization.md](./doc/modules/presentation/security/authorization.md) | [AuthorizationModule.sol](./contracts/modules/security/AuthorizationModule.sol) |
 
 
 
@@ -128,32 +145,37 @@ See the code in [modules/security](./contracts/modules/security).
 
 Access control is managed thanks to the module `AuthorizationModule`.
 
-The module `OnlyDelegateCallModule` is a special module to insure that
-some functions (e.g., such as `delegatecall()` and `selfdestruct`) can only be triggered through proxies when the contract is deployed with a proxy.
-
 ### Audit
 
 The contracts have been audited by [ABDKConsulting](https://www.abdk.consulting/), a globally recognized firm specialized in smart contracts security.
 
-
 #### First audit - September 2021
 
+Fixed version : [1.0](https://github.com/CMTA/CMTAT/releases/tag/1.0)
+
 Fixes of security issues discovered by the initial audit were reviewed by ABDK and confirmed to be effective, as certified by the [report released](doc/audits/ABDK-CMTAT-audit-20210910.pdf) on September 10, 2021, covering [version c3afd7b](https://github.com/CMTA/CMTAT/tree/c3afd7b4a2ade160c9b581adb7a44896bfc7aaea) of the contracts.
 Version [1.0](https://github.com/CMTA/CMTAT/releases/tag/1.0) includes additional fixes of minor issues, compared to the version retested.
 
 A summary of all fixes and decisions taken is available in the file [CMTAT-Audit-20210910-summary.pdf](doc/audits/CMTAT-Audit-20210910-summary.pdf) 
 
 #### Second audit - March 2023
 
+Fixed version : [v2.3.0](https://github.com/CMTA/CMTAT/releases/tag/v2.3.0)
+
 The second audit covered version [2.2](https://github.com/CMTA/CMTAT/releases/tag/2.2).
 
-Version 2.3 contains the different fixes and improvements related to this audit.
+Version v2.3.0 contains the different fixes and improvements related to this audit.
 
 The report is available in [ABDK_CMTA_CMTATRuleEngine_v_1_0.pdf](doc/audits/ABDK_CMTA_CMTATRuleEngine_v_1_0/ABDK_CMTA_CMTATRuleEngine_v_1_0.pdf). 
 
 ### Tools
 
-You will find the report produced by [Slither](https://github.com/crytic/slither) in [slither-report.md](doc/audits/tools/slither-report.md). 
+You will find the report produced by [Slither](https://github.com/crytic/slither) in 
+
+| Version | File                                                         |
+| ------- | ------------------------------------------------------------ |
+| v2.3.0  | [v2.3.0-slither-report.md](doc/audits/tools/v2.3.0-slither-report.md) |
+| v2.3.1  | [v2.3.1-slither-report.md](doc/audits/tools/v2.3.1-slither-report.md) |
 
 
 ### Test
@@ -178,7 +200,7 @@ Here a summary of the main documents:
 | Documentation of the modules API. | [doc/modules](doc/modules)                                 |
 | Documentation on the toolchain    | [doc/TOOLCHAIN.md](doc/TOOLCHAIN.md)                       |
 | How to use the project            | [doc/USAGE.md](doc/USAGE.md)                               |
-| Project architecture              | [doc/general/architecture.md](doc/general/architecture.md) |
+| Project architecture              | [doc/general/ARCHITECTURE.md](doc/general/ARCHITECTURE.md) |
 
 CMTA providers further documentation describing the CMTAT framework in a platform-agnostic way, and covering legal aspects, see
 

contracts/CMTAT_PROXY.sol

@@ -13,8 +13,6 @@ contract CMTAT_PROXY is CMTAT_BASE {
     constructor(
         address forwarderIrrevocable
     ) MetaTxModule(forwarderIrrevocable) {
-        // Initialize the variable for the implementation
-        deployedWithProxy = true;
         // Disable the possibility to initialize the implementation
         _disableInitializers();
     }

contracts/modules/CMTAT_BASE.sol

@@ -17,7 +17,7 @@ SnapshotModule:
 Add this import in case you add the SnapshotModule
 import "./wrapper/optional/SnapshotModule.sol";
 */
-import "./wrapper/controller/ValidationModule.sol";
+import "./wrapper/controllers/ValidationModule.sol";
 import "./wrapper/extensions/MetaTxModule.sol";
 import "./wrapper/extensions/DebtModule/DebtBaseModule.sol";
 import "./wrapper/extensions/DebtModule/CreditEventsModule.sol";