diff --git a/FAQ.md b/FAQ.md index bf292d24..f80ef5d2 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,81 +1,105 @@ # FAQ -## IDE (Truffle, Hardhat, ...) +This FAQ is intended to developers familiar with smart contracts +development. + +## Toolkit support > Why do you continue using Truffle instead of migrating to HardHat or Foundry? -**Hardhat VS Truffle** +Regarding [Hardhat](https://hardhat.org/): - 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. -**Truffle VS Foundry** +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) will be difficult to write in Solidity, see [https://github.com/CMTA/CMTAT/blob/master/test/common/MetaTxModuleCommon.js](https://github.com/CMTA/CMTAT/blob/master/test/common/MetaTxModuleCommon.js) -- OpenZeppelin, the main libraries we use, have their tests mainly written in JavaScript, so it provides good examples for our tests -- But for performance, we have seen indeed that Foundry is better than Truffle, notably to test the Snapshot Module +- 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 support Foundry in the near Future? I see a CMTAT-Foundry repo. Is it reliable? +> Do you plan to fully support Foundry in the near future? -No, it is currently not reliable. +For the foreseeable future, we plan to keep Truffle as the main +development and testing suite. -We have not planned to export all the tests in their Solidity version, but some tests are available +We have not planned to export all the tests from the Truffle suite to +their Solidity version equivalent suitable to Foundry, though some tests +are already available. -The repo CMTAT-Foundry will have the latest CMTAT version +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). -Please, note that we provide only a minimal support for the foundry repository as well as Hardhat. -We use Truffle to maintain the project. +> Can Hardhat be used to run tests? -> Hardhat tests: are they really working in v2.3.0? +No, please use Truffle to run the tests. -No, please use Truffle to run the tests ## Modules -> Why the Snapshot module is not audited in the version v2.3.0? +> What is the reason the Snapshot module wasn't audited in version v2.3.0? -It was out of scope because it’s not really used yet and will likely 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. -At deployment, this module is not included by default +> What is the status of [ERC1404](https://erc1404) compatibility? -> What is the status for 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. -We have not planned to be fully compatible since this ERC is not an ERC, it is only an EIP. +However, from a pure technical perspective, CMTAT is not fully compliant +with the ERC1404 specification, due the way it inherits the ERC20 +interface. -To be fully compatible, we have to inherit of ERC20 inside the interface and it will break our architecture. +> What is the purpose of the flag parameter in the Base module? -See [https://erc1404.org/](https://erc1404.org/) +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. -> What is exactly the purpose of the flag parameter in BaseModule? -> I see that it’s a variable (uint256) to include some information, but I don’t see any use case in the code. -It is just a variable to include some additional information under the form of bit flags. -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*. -> Question regarding the ValidationModule optional module. -> -> Why is it optional? The module is required by Pauser and Enforcer mandatory modules +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. +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). -- ValidationModule is optional from the legal perspective, but you can ask admin@cmta.ch to have a better/clearer information on that. -- It is the opposite: PauseModule and EnforcementModule are required to use the ValidationModule (but indeed, you actually need the ValidationModule for the functions to be called) -- If you remove the ValidationModule and want to use the Pause and 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 by fixing the CVF-1 -Here 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) -The PR: [https://github.com/CMTA/CMTAT/pull/153](https://github.com/CMTA/CMTAT/pull/153) -We could probably move the ValidationModule inside the mandatory modules and think about a better architecture (but probably not for the next release) ## Documentation -> What is the code coverage? +> What is the code coverage of the test suite? -A code coverage is available here: [https://github.com/CMTA/CMTAT/blob/master/doc/general/test/coverage/index.html](https://github.com/CMTA/CMTAT/blob/master/doc/general/test/coverage/index.html) +A [code coverage report](https://github.com/CMTA/CMTAT/blob/master/doc/general/test/coverage/index.html) +is available. -Normally, you can run the code coverage with `npx hardhat coverage` +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 navigator +Please clone the repository and open the file inside your browser. -You will find a summary of all automatic tests in the file [test.pdf](https://github.com/CMTA/CMTAT/blob/master/doc/general/test/test.pdf) \ No newline at end of file +You will find a summary of all automatic tests in +[test.pdf](https://github.com/CMTA/CMTAT/blob/master/doc/general/test/test.pdf). diff --git a/contracts/modules/wrapper/mandatory/BurnModule.sol b/contracts/modules/wrapper/mandatory/BurnModule.sol index d1d540b8..b95e02af 100644 --- a/contracts/modules/wrapper/mandatory/BurnModule.sol +++ b/contracts/modules/wrapper/mandatory/BurnModule.sol @@ -7,7 +7,10 @@ import "../../../../openzeppelin-contracts-upgradeable/contracts/proxy/utils/Ini import "../../security/AuthorizationModule.sol"; abstract contract BurnModule is ERC20Upgradeable, AuthorizationModule { - event Burn(address indexed owner, uint256 amount, string reason); + /** + * @notice Emitted when the specified `value` amount of tokens owned by `owner`are destroyed with the given `reason` + */ + event Burn(address indexed owner, uint256 value, string reason); function __BurnModule_init( string memory name_, @@ -35,51 +38,56 @@ abstract contract BurnModule is ERC20Upgradeable, AuthorizationModule { } /** - * @dev Destroys `amount` tokens from `account` - * + * @notice Destroys a `value` amount of tokens from `account`, by transferring it to address(0). + * @dev * See {ERC20-_burn} * Emits a {Burn} event + * Emits a {Transfer} event with `to` set to the zero address (emits inside _burn). + * Requirements: + * - the caller must have the `BURNER_ROLE`. */ function forceBurn( address account, - uint256 amount, + uint256 value, string memory reason ) public onlyRole(BURNER_ROLE) { - _burn(account, amount); - emit Burn(account, amount, reason); + _burn(account, value); + emit Burn(account, value, reason); } /** * - * @dev batch version of {forceBurn}. - * + * @notice batch version of {forceBurn}. + * @dev * See {ERC20-_burn} and {OpenZeppelin ERC1155_burnBatch}. * - * Emits a {Burn} event by burn action. - * + * For each burn action: + * -Emits a {Burn} event + * -Emits a {Transfer} event with `to` set to the zero address (emits inside _burn). + * The burn `reason`is the same for all `accounts` which tokens are burnt. * Requirements: - * - `tos` and `amounts` must have the same length + * - `accounts` and `values` must have the same length * - the caller must have the `BURNER_ROLE`. */ function forceBurnBatch( address[] calldata accounts, - uint256[] calldata amounts, + uint256[] calldata values, string memory reason ) public onlyRole(BURNER_ROLE) { require( accounts.length > 0, - "CMTAT: tos is empty" + "CMTAT: accounts is empty" ); - // We do not check that amounts is not empty since + // We do not check that values is not empty since // this require will throw an error in this case. require( - accounts.length == amounts.length, - "CMTAT: accounts and amounts length mismatch" + accounts.length == values.length, + "CMTAT: accounts and values length mismatch" ); for (uint256 i = 0; i < accounts.length; ) { - _burn(accounts[i], amounts[i]); - emit Burn(accounts[i], amounts[i], reason); + _burn(accounts[i], values[i]); + emit Burn(accounts[i], values[i], reason); unchecked { ++i; } diff --git a/contracts/modules/wrapper/mandatory/ERC20BaseModule.sol b/contracts/modules/wrapper/mandatory/ERC20BaseModule.sol index 11a60c9e..be7ace73 100644 --- a/contracts/modules/wrapper/mandatory/ERC20BaseModule.sol +++ b/contracts/modules/wrapper/mandatory/ERC20BaseModule.sol @@ -6,19 +6,23 @@ pragma solidity ^0.8.17; import "../../../../openzeppelin-contracts-upgradeable/contracts/proxy/utils/Initializable.sol"; import "../../../../openzeppelin-contracts-upgradeable/contracts/token/ERC20/ERC20Upgradeable.sol"; + abstract contract ERC20BaseModule is ERC20Upgradeable { /* Events */ - event Spend(address indexed owner, address indexed spender, uint256 amount); + /** + @notice Emitted when the specified `spender` spends the specified `value` tokens owned by the specified `owner` reducing the corresponding allowance. + */ + event Spend(address indexed owner, address indexed spender, uint256 value); /* Variables */ uint8 private _decimals; /* Initializers */ /** - * @dev Sets the values for {name} and {symbol}. + * @dev Sets the values for {name}, {symbol} and decimals. * - * All two of these values are immutable: they can only be set once during - * construction. + * These values are immutable: they can only be set once during + * construction/initialization. */ function __ERC20Module_init( string memory name_, @@ -41,50 +45,14 @@ abstract contract ERC20BaseModule is ERC20Upgradeable { /* Methods */ /** - * @notice Returns the number of decimals used to get its user representation. - * @dev - * For example, if `decimals` equals `2`, a balance of `505` tokens should - * be displayed to a user as `5,05` (`505 / 10 ** 2`). * - * Tokens usually opt for a value of 18, imitating the relationship between - * Ether and Wei. This is the value {ERC20} uses, unless this function is - * overridden; - * - * NOTE: This information is only used for _display_ purposes: it in - * no way affects any of the arithmetic of the contract, including - * {IERC20-balanceOf} and {IERC20-transfer}. + * @notice Returns the number of decimals used to get its user representation. + * @inheritdoc ERC20Upgradeable */ function decimals() public view virtual override returns (uint8) { return _decimals; } - /** - * @dev See {IERC20-transferFrom}. - * - * Emits an {Approval} event indicating the updated allowance. This is not - * required by the EIP. See the note at the beginning of {ERC20}. - * - * Requirements: - * - * - `sender` and `recipient` cannot be the zero address. - * - `sender` must have a balance of at least `amount`. - * - the caller must have allowance for ``sender``'s tokens of at least - * `amount`. - */ - function transferFrom( - address sender, - address recipient, - uint256 amount - ) public virtual override returns (bool) { - bool result = super.transferFrom(sender, recipient, amount); - // The result will be normally always true because OpenZeppelin uses require to check all the conditions. - if (result) { - emit Spend(sender, _msgSender(), amount); - } - - return result; - } - /** * @notice batch version of transfer * @param tos can not be empty, must have the same length as values @@ -94,13 +62,13 @@ abstract contract ERC20BaseModule is ERC20Upgradeable { * * Requirements: * - `tos` and `values` must have the same length - * - `tos`cannot contain a zero address + * - `tos`cannot contain a zero address (check made by transfer) * - the caller must have a balance cooresponding to the total values */ function transferBatch( address[] calldata tos, uint256[] calldata values - ) public { + ) public returns (bool) { require( tos.length > 0, "CMTAT: tos is empty" @@ -111,35 +79,58 @@ abstract contract ERC20BaseModule is ERC20Upgradeable { tos.length == values.length, "CMTAT: tos and values length mismatch" ); - bool result; for (uint256 i = 0; i < tos.length; ) { - result = ERC20Upgradeable.transfer(tos[i], values[i]); - require(result, "CMTAT: transfer failed"); + // We call directly the internal function transfer + // The reason is that the public function adds only the owner address recovery + ERC20Upgradeable._transfer(_msgSender(), tos[i], values[i]); unchecked { ++i; } } + // not really useful + // Here only to keep the same behaviour as transfer + return true; } /** - * @dev See {IERC20-approve}. - * - * Requirements: - * - * - `spender` cannot be the zero address. + * @notice Transfers `value` amount of tokens from address `from` to address `to` + * @inheritdoc ERC20Upgradeable + * @custom:dev-cmtat + * Emits a {Spend} event indicating the spended allowance. + */ + function transferFrom( + address from, + address to, + uint256 value + ) public virtual override returns (bool) { + bool result = ERC20Upgradeable.transferFrom(from, to, value); + // The result will be normally always true because OpenZeppelin will revert in case of an error + if (result) { + emit Spend(from, _msgSender(), value); + } + + return result; + } + + /** + * @notice Allows `spender` to withdraw from your account multiple times, up to the `value` amount + * @dev see {OpenZeppelin ERC20 - approve} */ function approve( address spender, - uint256 amount, + uint256 value, uint256 currentAllowance ) public virtual returns (bool) { + address owner = _msgSender(); require( - allowance(_msgSender(), spender) == currentAllowance, + allowance(owner, spender) == currentAllowance, "CMTAT: current allowance is not right" ); - super.approve(spender, amount); + // We call directly the internal function _approve + // The reason is that the public function adds only the owner address recovery + ERC20Upgradeable._approve(owner, spender, value); return true; } uint256[50] private __gap; -} \ No newline at end of file +} diff --git a/contracts/modules/wrapper/mandatory/MintModule.sol b/contracts/modules/wrapper/mandatory/MintModule.sol index c50f191b..82bdf847 100644 --- a/contracts/modules/wrapper/mandatory/MintModule.sol +++ b/contracts/modules/wrapper/mandatory/MintModule.sol @@ -7,7 +7,11 @@ import "../../../../openzeppelin-contracts-upgradeable/contracts/proxy/utils/Ini import "../../security/AuthorizationModule.sol"; abstract contract MintModule is ERC20Upgradeable, AuthorizationModule { - event Mint(address indexed beneficiary, uint256 amount); + /** + * @notice Emitted when the specified `value` amount of new tokens are created and + * allocated to the specified `account`. + */ + event Mint(address indexed account, uint256 value); function __MintModule_init( string memory name_, @@ -35,49 +39,54 @@ abstract contract MintModule is ERC20Upgradeable, AuthorizationModule { } /** - * @dev Creates `amount` new tokens for `to`. - * - * See {ERC20-_mint}. + * @notice Creates a `value` amount of tokens and assigns them to `account`, by transferring it from address(0) + * @dev + * See {OpenZeppelin ERC20-_mint}. + * Emits a {Mint} event. + * Emits a {Transfer} event with `from` set to the zero address (emits inside _mint). * * Requirements: - * - * - the caller must have the `MINTER_ROLE`. + * - `account` cannot be the zero address (check made by _mint). + * - The caller must have the `MINTER_ROLE`. */ - function mint(address to, uint256 amount) public onlyRole(MINTER_ROLE) { - _mint(to, amount); - emit Mint(to, amount); + function mint(address account, uint256 value) public onlyRole(MINTER_ROLE) { + _mint(account, value); + emit Mint(account, value); } /** * - * @dev batch version of {mint}. - * - * See {ERC20-_mint} and {OpenZeppelin ERC1155_mintBatch}. + * @notice batch version of {mint} + * @dev + * See {OpenZeppelin ERC20-_mint} and {OpenZeppelin ERC1155_mintBatch}. * - * Emits a {Mint} event. + * For each mint action: + * - Emits a {Mint} event. + * - Emits a {Transfer} event with `from` set to the zero address (emits inside _mint). * * Requirements: - * - `tos` and `amounts` must have the same length + * - `accounts` and `values` must have the same length + * - `accounts` cannot contain a zero address (check made by _mint). * - the caller must have the `MINTER_ROLE`. */ function mintBatch( - address[] calldata tos, - uint256[] calldata amounts + address[] calldata accounts, + uint256[] calldata values ) public onlyRole(MINTER_ROLE) { require( - tos.length > 0, - "CMTAT: tos is empty" + accounts.length > 0, + "CMTAT: accounts is empty" ); - // We do not check that amounts is not empty since + // We do not check that values is not empty since // this require will throw an error in this case. require( - tos.length == amounts.length, - "CMTAT: tos and amounts length mismatch" + accounts.length == values.length, + "CMTAT: accounts and values length mismatch" ); - for (uint256 i = 0; i < tos.length; ) { - _mint(tos[i], amounts[i]); - emit Mint(tos[i], amounts[i]); + for (uint256 i = 0; i < accounts.length; ) { + _mint(accounts[i], values[i]); + emit Mint(accounts[i], values[i]); unchecked { ++i; } diff --git a/doc/modules/presentation/mandatory/burn.md b/doc/modules/presentation/mandatory/burn.md index 67ff7cc5..5043d426 100644 --- a/doc/modules/presentation/mandatory/burn.md +++ b/doc/modules/presentation/mandatory/burn.md @@ -51,8 +51,11 @@ public onlyRole(BURNER_ROLE) ##### Description -Redeem the given `amount` of tokens from the given `account`. -Only authorized users are allowed to call this function. +Destroys a `value` amount of tokens from `account`, by transferring it to address(0). + +##### Requirements + +Only authorized users (*BURNER_ROLE*) are allowed to call this function. #### `forceBurnBatch(address[],uint256[],string) ` @@ -65,11 +68,16 @@ public onlyRole(BURNER_ROLE) ##### Description -For each account in `accounts`, redeem the corresponding amount of tokens given by `amounts`. -Only authorized users are allowed to call this function. +For each account in `accounts`, destroys a `value` amount of tokens from `account`, by transferring it to address(0). The burn `reason`is the same for all `accounts` which tokens are burnt. +##### Requirements + +- `accounts` and `values` must have the same length + +- The caller must have the `BURNER_ROLE`. + ### Events #### `Burn(address,uint,string)` @@ -82,4 +90,6 @@ event Burn(address indexed owner, uint256 amount, string reason) ##### Description -Emitted when the specified `amount` of tokens was burnt from the specified `account`. +Emitted when the specified `value` amount of tokens owned by `owner`are destroyed with the given `reason` + +​ diff --git a/doc/modules/presentation/mandatory/erc20base.md b/doc/modules/presentation/mandatory/erc20base.md index 8b72035d..26c59790 100644 --- a/doc/modules/presentation/mandatory/erc20base.md +++ b/doc/modules/presentation/mandatory/erc20base.md @@ -22,7 +22,7 @@ The ERC20Base Module sets forth the ERC20 basic functionalities a token must hav ### Graph -![surya_graph_ERC20BaseModule.sol](../..//schema/surya_graph/surya_graph_ERC20BaseModule.sol.png) +![surya_graph_ERC20BaseModule.sol](/home/ryan/Downloads/no_backup/CM/cmtat-2.3/CMTAT/out/surya_graph/surya_graph_ERC20BaseModule.sol.png) ## Sūrya's Description Report @@ -33,7 +33,6 @@ The ERC20Base Module sets forth the ERC20 basic functionalities a token must hav | ----------------------------------------------- | ---------------------------------------- | | ./modules/wrapper/mandatory/ERC20BaseModule.sol | fdaf8d8a710a4ae6166fb0e491018c559acb4e89 | - ### Contracts Description Table @@ -45,10 +44,10 @@ The ERC20Base Module sets forth the ERC20 basic functionalities a token must hav | └ | __ERC20Module_init | Internal 🔒 | 🛑 | onlyInitializing | | └ | __ERC20Module_init_unchained | Internal 🔒 | 🛑 | onlyInitializing | | └ | decimals | Public ❗️ | | NO❗️ | +| └ | transferBatch | Public ❗️ | 🛑 | NO❗️ | | └ | transferFrom | Public ❗️ | 🛑 | NO❗️ | | └ | approve | Public ❗️ | 🛑 | NO❗️ | - ### Legend | Symbol | Meaning | @@ -62,101 +61,113 @@ Base Module API for Ethereum blockchain extends the [ERC-20](https://github.com/ ### Functions -#### `totalSupply()` +#### OpenZeppelin + +##### `totalSupply()` Origin: OpenZeppelin (ERC20Upgradeable) -##### Definition: +###### Definition ```solidity -function totalSupply() -external view +function totalSupply() public view virtual returns (uint256) ``` -##### Description: +###### Description Return the total number of tokens currently in circulation. -#### `balanceOf(address)` +##### `balanceOf(address)` Origin: OpenZeppelin (ERC20Upgradeable) -##### Definition: +###### Definition ```solidity function balanceOf(address account) -external view +public view virtual returns (uint256) ``` -##### Description: +###### Description Return the number of tokens currently owned by the given `owner`. -#### `transfer(address,uint256)` +##### `transfer(address,uint256)` Origin: OpenZeppelin (ERC20Upgradeable) -##### Definition: +###### Definition ```solidity -function transfer(address to, uint256 amount) -external +function transfer(address to, uint256 value) +public virtual returns (bool) ``` -##### Description: +###### Description Transfer the given `amount` of tokens from the caller to the given `destination` address. The function returns `true` on success and reverts on error. -#### `approve(address,uint256)` +###### Requirements + + * `to` cannot be the zero address. + * the caller must have a balance of at least `value`. + +##### `approve(address,uint256)` Origin: OpenZeppelin (ERC20Upgradeable) -##### Definition: +###### Definition ```solidity -function approve(address spender, uint256 amount) -external +function approve(address spender, uint256 value) +public virtual returns (bool) ``` -##### Description: +###### Description Allow the given `spender` to transfer at most the given `amount` of tokens from the caller. The function returns `true` on success and reverts of error. -#### `allowance(address,address)` +###### Requirement + +`spender` cannot be the zero address. + +##### `allowance(address,address)` Origin: OpenZeppelin (ERC20Upgradeable) -##### Definition: +###### Definition ```solidity function allowance(address owner, address spender) -external view +public view virtual returns (uint256) ``` -##### Description: +###### Description Return the number of tokens the given `spender` is currently allowed to transfer from the given `owner`. -#### `approve(address,uint256,uint256)` +#### CMTAT -##### Definition: +##### `approve(address,uint256,uint256)` + +###### Definition ```solidity -function approve(address spender,uint256 amount,uint256 currentAllowance) +function approve(address spender,uint256 value,uint256 currentAllowance) public virtual returns (bool) ``` -##### Description: +###### Description -Allow the given `spender` to transfer at most the given `amount` of tokens from the caller. +Allows `spender` to withdraw from your account multiple times, up to the `value` amount The function may be successfully executed only when the given `currentAllowance` values equals to the amount of token the spender is currently allowed to transfer from the caller. The function returns `true` on success and reverts of error. @@ -174,62 +185,79 @@ So, Bob got 210 tokens in total, while Alice never means to allow him to transfe In order to mitigate this kind of attack, Alice at step 3 calls `approve (bob, 110, 100)`. Such call could only succeed if the allowance is still 100, i.e. Bob's attempt to front run the transaction will make Alice's transaction to fail. -#### `transferFrom(address,address,uint256)` +###### Requirement -##### Definition: +- The given `currentAllowance` value has to be equal to the amount of token the spender is currently allowed to transfer from the caller. +- `spender`and the sender cannot be the zero address (check made by `OpenZeppelin-_approve`). + +##### `transferFrom(address,address,uint256)` + +This function overrides the function `transferFrom`from OpenZeppelin + +###### Definition ```solidity -function transferFrom(address sender,address recipient,uint256 amount) +function transferFrom(address from,address to,uint256 value) public virtual override -returns (bool) +returns (bool) ``` -##### Description: +###### Description -Transfer the given `amount` of tokens from the given `owner` to the given `destination` address. -`sender` and `recipient` cannot be the zero address. -The function returns `true` on success and reverts of error. +Transfers `value` amount of tokens from address `from` to address `to` + +The function returns `true` on success, nothing if the parent function return false. The behavior of the parent function in case of an error is to revert rather than returned false. + +###### Requirement + +`from` and `to` cannot be the zero address. ### Events -#### `Transfer(address,address,uint256)` +#### OpenZeppelin + +##### `Transfer(address,address,uint256)` Origin: OpenZeppelin (ERC20Upgradeable) -##### Definition: +###### Definition ```solidity event Transfer(address indexed from, address indexed to, uint256 value) ``` -##### Description: +###### Description -Emitted when the specified `amount` of tokens was transferred from the specified `origin` address to the specified `destination` address. +Emitted when `value` tokens are moved from one account (`from`) to another (`to`). -#### `Approval(address,address,uint256)` +Note that `value` may be zero. + +##### `Approval(address,address,uint256)` Origin: OpenZeppelin (ERC20Upgradeable) -##### Definition: +###### Definition ```solidity event Approval(address indexed owner, address indexed spender, uint256 value) ``` -##### Description: +###### Description + +Emitted when the allowance of a `spender` for an `owner` is set by a call to {approve}. `value` is the new allowance. -Emitted when the specified `owner` allowed the specified `spender` to transfer the specified `amount` of tokens. +#### CMTAT -#### `Spend(address,address,uint256)` +##### `Spend(address,address,uint256)` -##### Definition: +###### Definition ```solidity -event Spend (address indexed owner, address indexed spender, uint256 amount) +event Spend (address indexed owner, address indexed spender, uint256 value) ``` -##### Description: +###### Description -Emitted when the specified `spender` spends the specified `amount` of the tokens owned by the specified `owner` reducing the corresponding allowance. +Emitted when the specified `spender` spends the specified `value` tokens owned by the specified `owner` reducing the corresponding allowance. This event is not defined by ERC-20 and is needed to track allowance changes. diff --git a/doc/modules/presentation/mandatory/mint.md b/doc/modules/presentation/mandatory/mint.md index 7a011814..af3f3474 100644 --- a/doc/modules/presentation/mandatory/mint.md +++ b/doc/modules/presentation/mandatory/mint.md @@ -33,7 +33,7 @@ This document defines Mint Module for the CMTA Token specification. | File Name | SHA-1 Hash | | ------------------------------------------ | ---------------------------------------- | -| ./modules/wrapper/mandatory/MintModule.sol | 59896c200ba366d171fc377d8b78d757aefbc69d | +| ./modules/wrapper/mandatory/MintModule.sol | 3d6fa6f2890f85f4f426aee39ea2ee31203f2109 | ### Contracts Description Table @@ -50,6 +50,8 @@ This document defines Mint Module for the CMTA Token specification. | └ | mintBatch | Public ❗️ | 🛑 | onlyRole | + + ### Legend | Symbol | Meaning | @@ -70,28 +72,40 @@ This section describes the Ethereum API of Issue Module. ##### Definition ```solidity -function mint(address to, uint256 amount) +function mint(address account, uint256 value) public onlyRole(MINTER_ROLE) ``` ##### Description -Create the given `amount` of tokens and allocate them to the given address`to`. -Only authorized users are allowed to call this function. + Creates a `value` amount of tokens and assigns them to `account`, by transferring it from address(0) + + +##### Requirements + +- Only authorized users (`MINTER_ROLE`) are allowed to call this function. +- `account` cannot be the zero address (check made by _mint). #### `mintBatch(address[],uint256[]) ` ##### Definition ```solidity -function mintBatch(address[] calldata to,uint256[] calldata amounts) +function mintBatch(address[] calldata accounts,uint256[] calldata values) public onlyRole(MINTER_ROLE) ``` ##### Description -For each address in `to`, create the corresponding amount of tokens given by `amounts` and allocate them to the given address`to`. -Only authorized users are allowed to call this function. +For each address in `accounts`, create the corresponding amount of tokens given by `amounts` and allocate them to the given address`to`. + +##### Requirements + +Only authorized users (`MINTER_ROLE`) are allowed to call this function + +`accounts` and `values` must have the same length + +`accounts` cannot contain a zero address (check made by _mint). ### Events @@ -101,11 +115,11 @@ Only authorized users are allowed to call this function. ```solidity -event Mint (address indexed beneficiary,uint256 amount) +event Mint(address indexed account, uint256 value) ``` ##### Description -Emitted when the specified `amount` of new tokens was created and -allocated to the specified `beneficiary`. +Emitted when the specified `value` amount of new tokens are created and +allocated to the specified `account`. diff --git a/doc/modules/schema/sol2uml/mandatory/BurnModule.svg b/doc/modules/schema/sol2uml/mandatory/BurnModule.svg index 08a35b36..59a74bc0 100644 --- a/doc/modules/schema/sol2uml/mandatory/BurnModule.svg +++ b/doc/modules/schema/sol2uml/mandatory/BurnModule.svg @@ -59,9 +59,9 @@    __BurnModule_init(name_: string, symbol_: string, admin: address) <<onlyInitializing>>    __BurnModule_init_unchained() <<onlyInitializing>> Public: -    <<event>> Burn(owner: address, amount: uint256, reason: string) -    forceBurn(account: address, amount: uint256, reason: string) <<onlyRole>> -    forceBurnBatch(accounts: address[], amounts: uint256[], reason: string) <<onlyRole>> +    <<event>> Burn(owner: address, value: uint256, reason: string) +    forceBurn(account: address, value: uint256, reason: string) <<onlyRole>> +    forceBurnBatch(accounts: address[], values: uint256[], reason: string) <<onlyRole>> diff --git a/doc/modules/schema/sol2uml/mandatory/ERC20BaseModule.svg b/doc/modules/schema/sol2uml/mandatory/ERC20BaseModule.svg index bcf5742a..71f5fcd9 100644 --- a/doc/modules/schema/sol2uml/mandatory/ERC20BaseModule.svg +++ b/doc/modules/schema/sol2uml/mandatory/ERC20BaseModule.svg @@ -4,36 +4,37 @@ - - + + UmlClassDiagram - + cluster_0 - + contracts/modules/wrapper/mandatory - + -25 - -<<Abstract>> -ERC20BaseModule -contracts/modules/wrapper/mandatory/ERC20BaseModule.sol - -Private: -   _decimals: uint8 -   __gap: uint256[50] - -Internal: -    __ERC20Module_init(name_: string, symbol_: string, decimals_: uint8) <<onlyInitializing>> -    __ERC20Module_init_unchained(decimals_: uint8) <<onlyInitializing>> -Public: -    <<event>> Spend(owner: address, spender: address, amount: uint256) -    decimals(): uint8 -    transferFrom(sender: address, recipient: address, amount: uint256): bool -    approve(spender: address, amount: uint256, currentAllowance: uint256): bool +28 + +<<Abstract>> +ERC20BaseModule +contracts/modules/wrapper/mandatory/ERC20BaseModule.sol + +Private: +   _decimals: uint8 +   __gap: uint256[50] + +Internal: +    __ERC20Module_init(name_: string, symbol_: string, decimals_: uint8) <<onlyInitializing>> +    __ERC20Module_init_unchained(decimals_: uint8) <<onlyInitializing>> +Public: +    <<event>> Spend(owner: address, spender: address, value: uint256) +    decimals(): uint8 +    transferBatch(tos: address[], values: uint256[]): bool +    transferFrom(from: address, to: address, value: uint256): bool +    approve(spender: address, value: uint256, currentAllowance: uint256): bool diff --git a/doc/modules/schema/sol2uml/mandatory/MintModule.svg b/doc/modules/schema/sol2uml/mandatory/MintModule.svg index 74239d2c..1deb5ab8 100644 --- a/doc/modules/schema/sol2uml/mandatory/MintModule.svg +++ b/doc/modules/schema/sol2uml/mandatory/MintModule.svg @@ -59,9 +59,9 @@    __MintModule_init(name_: string, symbol_: string, admin: address) <<onlyInitializing>>    __MintModule_init_unchained() <<onlyInitializing>> Public: -    <<event>> Mint(beneficiary: address, amount: uint256) -    mint(to: address, amount: uint256) <<onlyRole>> -    mintBatch(to: address[], amounts: uint256[]) <<onlyRole>> +    <<event>> Mint(account: address, value: uint256) +    mint(account: address, value: uint256) <<onlyRole>> +    mintBatch(accounts: address[], values: uint256[]) <<onlyRole>> diff --git a/doc/modules/schema/surya_graph/surya_graph_ERC20BaseModule.sol.png b/doc/modules/schema/surya_graph/surya_graph_ERC20BaseModule.sol.png index 63f732c1..dfd36bb1 100644 Binary files a/doc/modules/schema/surya_graph/surya_graph_ERC20BaseModule.sol.png and b/doc/modules/schema/surya_graph/surya_graph_ERC20BaseModule.sol.png differ diff --git a/test/common/BurnModuleCommon.js b/test/common/BurnModuleCommon.js index c460a8ca..4a36dc74 100644 --- a/test/common/BurnModuleCommon.js +++ b/test/common/BurnModuleCommon.js @@ -30,7 +30,7 @@ function BurnModuleCommon (admin, address1, address2) { // Emits a Burn event expectEvent.inLogs(this.logs1, 'Burn', { owner: address1, - amount: VALUE1, + value: VALUE1, reason: REASON }); // Check balances and total supply @@ -52,7 +52,7 @@ function BurnModuleCommon (admin, address1, address2) { // Emits a Burn event expectEvent.inLogs(this.logs2, 'Burn', { owner: address1, - amount: DIFFERENCE, + value: DIFFERENCE, reason: REASON }); // Check balances and total supply @@ -78,7 +78,7 @@ function BurnModuleCommon (admin, address1, address2) { // Emits a Burn event expectEvent.inLogs(this.logs, 'Burn', { owner: address1, - amount: VALUE1, + value: VALUE1, reason: REASON }) }) @@ -145,7 +145,7 @@ function BurnModuleCommon (admin, address1, address2) { // emits a Mint event expectEvent.inLogs(this.logs1, 'Burn', { owner: TOKEN_HOLDER[i], - amount: TOKEN_BY_HOLDERS_TO_BURN[i], + value: TOKEN_BY_HOLDERS_TO_BURN[i], reason: REASON }) } @@ -158,7 +158,7 @@ function BurnModuleCommon (admin, address1, address2) { (await this.cmtat.totalSupply()).should.be.bignumber.equal(TOTAL_SUPPLY_AFTER_BURN) }) - it('testCanBeBurntByBurnerRole', async function () { + it('testCanBeBurntBatchByBurnerRole', async function () { // Arrange await this.cmtat.grantRole(BURNER_ROLE, address2, { from: admin }); @@ -184,7 +184,7 @@ function BurnModuleCommon (admin, address1, address2) { // emits a Mint event expectEvent.inLogs(this.logs1, 'Burn', { owner: TOKEN_HOLDER[i], - amount: TOKEN_BY_HOLDERS_TO_BURN[i] + value: TOKEN_BY_HOLDERS_TO_BURN[i] }) } // Check balances and total supply @@ -220,15 +220,15 @@ function BurnModuleCommon (admin, address1, address2) { const TOKEN_HOLDER_INVALID = [admin, address1] await expectRevert( this.cmtat.forceBurnBatch(TOKEN_HOLDER_INVALID, TOKEN_BY_HOLDERS_TO_BURN, REASON, { from: admin }), - 'CMTAT: accounts and amounts length mismatch' + 'CMTAT: accounts and values length mismatch' ) }) it('testCannotBurnBatchIfAccountsIsEmpty', async function () { const TOKEN_ADDRESS_TOS_INVALID = [] await expectRevert( - this.cmtat.transferBatch(TOKEN_ADDRESS_TOS_INVALID, TOKEN_BY_HOLDERS_TO_BURN, { from: admin }), - 'CMTAT: tos is empty' + this.cmtat.forceBurnBatch(TOKEN_ADDRESS_TOS_INVALID, TOKEN_BY_HOLDERS_TO_BURN, REASON, { from: admin }), + 'CMTAT: accounts is empty' ) }) }) diff --git a/test/common/ERC20BaseModuleCommon.js b/test/common/ERC20BaseModuleCommon.js index fa3d15dd..cad3b12e 100644 --- a/test/common/ERC20BaseModuleCommon.js +++ b/test/common/ERC20BaseModuleCommon.js @@ -238,7 +238,7 @@ function BaseModuleCommon (admin, address1, address2, address3, proxyTest) { expectEvent.inLogs(this.logs, 'Spend', { owner: address1, spender: address3, - amount: '11' + value: '11' }) }) diff --git a/test/common/MintModuleCommon.js b/test/common/MintModuleCommon.js index 1152beba..61bd19ca 100644 --- a/test/common/MintModuleCommon.js +++ b/test/common/MintModuleCommon.js @@ -35,8 +35,8 @@ function MintModuleCommon (admin, address1, address2) { }) // emits a Mint event expectEvent.inLogs(this.logs1, 'Mint', { - beneficiary: address1, - amount: VALUE1 + account: address1, + value: VALUE1 }); // Act @@ -58,8 +58,8 @@ function MintModuleCommon (admin, address1, address2) { }) // emits a Mint event expectEvent.inLogs(this.logs2, 'Mint', { - beneficiary: address2, - amount: VALUE2 + account: address2, + value: VALUE2 }) }) @@ -89,8 +89,8 @@ function MintModuleCommon (admin, address1, address2) { }) // emits a Mint event expectEvent.inLogs(this.logs1, 'Mint', { - beneficiary: address1, - amount: VALUE1 + account: address1, + value: VALUE1 }) }) @@ -147,8 +147,8 @@ function MintModuleCommon (admin, address1, address2) { for (let i = 0; i < TOKEN_HOLDER.length; ++i) { // emits a Mint event expectEvent.inLogs(this.logs1, 'Mint', { - beneficiary: TOKEN_HOLDER[i], - amount: TOKEN_SUPPLY_BY_HOLDERS[i] + account: TOKEN_HOLDER[i], + value: TOKEN_SUPPLY_BY_HOLDERS[i] }) } }) @@ -191,8 +191,8 @@ function MintModuleCommon (admin, address1, address2) { // emits a Mint event for (let i = 0; i < TOKEN_HOLDER.length; ++i) { expectEvent.inLogs(this.logs1, 'Mint', { - beneficiary: TOKEN_HOLDER[i], - amount: TOKEN_SUPPLY_BY_HOLDERS[i] + account: TOKEN_HOLDER[i], + value: TOKEN_SUPPLY_BY_HOLDERS[i] }) } }) @@ -214,7 +214,7 @@ function MintModuleCommon (admin, address1, address2) { const TOKEN_SUPPLY_BY_HOLDERS = [BN(10), BN(100), BN(1000)] await expectRevert( this.cmtat.mintBatch(TOKEN_HOLDER_INVALID, TOKEN_SUPPLY_BY_HOLDERS, { from: admin }), - 'CMTAT: tos and amounts length mismatch' + 'CMTAT: accounts and values length mismatch' ) }) @@ -223,7 +223,7 @@ function MintModuleCommon (admin, address1, address2) { const TOKEN_SUPPLY_BY_HOLDERS = [] await expectRevert( this.cmtat.mintBatch(TOKEN_HOLDER_INVALID, TOKEN_SUPPLY_BY_HOLDERS, { from: admin }), - 'CMTAT: tos is empty' + 'CMTAT: accounts is empty' ) }) })