Merge pull request #268 from CMTA/dev

CMTAT v2.5.0

CHANGELOG.md

@@ -2,15 +2,36 @@
 
 Please follow <https://changelog.md/> conventions.
 
-## 2.4.0
+## 2.5.0 - 20240910
+
+- Change Solidity version to 0.8.27 (latest)
+- Some slight improvements to the documentation
+
+## 2.5.0-rc.0 - 20240809
+
+**Features**
+
+- Add ERC-1643 (part of ERC-1400) for document management through an optional external contract called DocumentEngine (not yet available) [Add ERC-1643 support #267](https://github.com/CMTA/CMTAT/issues/267)
+- Externalize the Debt and CreditEvent module to an optional external contract called DebtEngine (not yet available) [Add DebtEngine #271](https://github.com/CMTA/CMTAT/issues/271)
+- CMTAT version compatible with UUPS proxy : more gas efficient than Transparent Proxy + no need of a proxy admin contract. See Upgradable Smart Contracts | What is a Smart Contract Proxy Pattern? [Add UUPS proxy support #270](https://github.com/CMTA/CMTAT/issues/270)
+- Remove [flag](https://github.com/CMTA/CMTAT/blob/master/contracts/modules/wrapper/core/BaseModule.sol#L29) attribute, present since v2.3.0, which was not really used. [ #266](https://github.com/CMTA/CMTAT/issues/266)
+
+**Technical**
+
+- Change Solidity version to 0.8.26 (latest)
+- Change EVM version to Cancun
+- Remove truffle from dependencies, replaced by Hardhat. See [Consensys Announces the Sunset of Truffle and Ganache and New Hardhat Partnership](https://consensys.io/blog/consensys-announces-the-sunset-of-truffle-and-ganache-and-new-hardhat)
+- Proxy Factory
+  - use create2 with the library [Create2](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/utils/Create2.sol) from OpenZeppelin:
+- Implement [ERC-7201](https://eips.ethereum.org/EIPS/eip-7201) to manage memory to reduce memory collision when upgrading a proxy to a new implementation. [Use erc-7201 for namespace #272](https://github.com/CMTA/CMTAT/issues/272)
+
+## 2.4.0 - 20240503
 
 The modifications between the version v2.3.0 and this version are not audited !!!
 
 - Improve tests & update the code
 - `ERC20SnapshotInternal` inherits from `ICMTATSnapshot`
 
-
-
 ## 2.4.0-rc.1 - 20240319
 
 The modifications between the version v2.3.0 and this version are not audited !!!

CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing Guidelines
+
+There are many ways to contribute to CMTAT Contracts.
+
+## Opening an issue
+
+You can [open an issue] to suggest a feature, a difficulty you have or report a minor bug. For serious bugs in an audited version please do not open an issue, instead refer to our [security policy] for appropriate steps. See [SECURITY.md](./SECURITY.MD).
+
+Before opening an issue, be sure to search through the existing open and closed issues, and consider posting a comment in one of those instead.
+
+When requesting a new feature, include as many details as you can, especially around the use cases that motivate it. 
+
+## Submitting a pull request
+
+If you would like to contribute code or documentation you may do so by forking the repository and submitting a pull request.
+
+Run linter and tests to make sure your pull request is good before submitting it.
+
+
+
+## Reference
+
+Based on the version made by [OpenZeppelin](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/CONTRIBUTING.md)

FAQ.md

@@ -3,36 +3,60 @@
 This FAQ is intended to developers familiar with smart contracts
 development.
 
+## Cross-chain bridge support
+
+> With which bridge can the CMTAT be used?
+
+We will analyze the three main bridges: [CCIP](https://chain.link/cross-chain) by Chainlink, [LayerZero](https://layerzero.network) and [AxelarNetwork](https://www.axelar.network)
+
+Generally, in term of implementation, it depends of the model to handle cross-chain token transfer. There are three main models: Burn & Mint, Lock & Mint, Lock & Unlock
+
+To use one of these models, you must implement in the token the functions required and used by the bridge (typically burn and mint). The model "lock and lock" is a little different from the first two models because it does not in principle require any particular implementation.
+
+For example the interface for CCIP is available here: [github.com/smartcontractkit/ccip - ERC20/IBurnMintERC20.sol](https://github.com/smartcontractkit/ccip/blob/948882675ad1c6604d4b911071fc3881148abe66/contracts/src/v0.8/shared/token/ERC20/IBurnMintERC20.sol)
+
+Axelar Network has also a similar behavior and requirement to create what they call a custom interchain token: https://docs.axelar.dev/dev/send-tokens/interchain-tokens/create-token#create-a-custom-interchain-token
+
+We haven't done any testing but in principle the functions `burnFrom`and `mint` are available and compatible with the last CMTAT version, see [github.com/CMTA/CMTAT/blob/master/contracts/interfaces/ICCIPToken.sol](https://github.com/CMTA/CMTAT/blob/master/contracts/interfaces/ICCIPToken.sol).
+
+For the public burn function, unfortunately, we currently have a reason argument in the function which is not compatible with bridges because their burn function only have two arguments (account and value): [github.com/CMTA/CMTAT - wrapper/core/ERC20BurnModule.sol#L32](https://github.com/CMTA/CMTAT/blob/master/contracts/modules/wrapper/core/ERC20BurnModule.sol#L32)
+
+### Chainlink CCIP
+
+For chainlink, the difficulty is that for the moment only tokens whitelisted by chainlink (e.g USDC) can use the bridge, which is not the case for Axelar Network.
+
+The ERC-20 interface for CCIP is available here: [github.com/smartcontractkit/ccip - ERC20/IBurnMintERC20.sol](https://github.com/smartcontractkit/ccip/blob/948882675ad1c6604d4b911071fc3881148abe66/contracts/src/v0.8/shared/token/ERC20/IBurnMintERC20.sol)
+
+### LayerZero
+
+There are two possibilities to use LayerZero with a CMTAT:
+
+The first one is to add a module inside CMTAT to include the Omnichain Fungible Token (OFT) Standard; see  [github.com/LayerZero-Labs - OFT.sol](https://github.com/LayerZero-Labs/LayerZero-v2/blob/main/packages/layerzero-v2/evm/oapp/contracts/oft/OFT.sol)
+
+The second possibility is to deploy an OFT Adapter to act as an intermediary lockbox for the token.
+
+More information in LayerZero documentation: [docs.layerzero.network/v2/developers/evm/oft/quickstart](
+
 ## 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.
+Since the sunset of Truffle by Consensys, we use 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.
+- All our tests are written in Javascript and migrating them to Foundry will require a lot of work
+- 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
 
 
 >  Do you plan to fully support Foundry in the near future? 
 
-For the foreseeable future, we plan to keep Hardhat/Truffle as the main
+For the foreseeable future, we plan to keep Hardhat  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?
 
@@ -45,60 +69,39 @@ You can only run the tests with `Hardhat`.
 
 > 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. 
+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`.
+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*. 
+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.
+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).
+[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.
+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 list of automatic tests in
-[test.pdf](https://github.com/CMTA/CMTAT/blob/master/doc/general/test/test.pdf).