To use the ruleEngine and the different rules, we recommend the latest audited version, from the Releases page. Currently, it is the version v1.0.2
This repository includes the RuleEngine contract for the CMTAT token.
The RuleEngine is an external contract used to apply transfer restrictions to another contract, initially the CMTAT. Acting as a controller, it can call different contract rules and apply these rules on each transfer.
The toolchain includes the following components, where the versions are the latest ones that we tested:
- Foundry
- Solidity 0.8.26 (via solc-js)
- OpenZeppelin Contracts (submodule) v5.0.2
While it has been designed for the CMTAT, the ruleEngine can be used with others contracts to apply restriction on transfer.
For that, the only thing to do is to import in your contract the interface IRuleEngine which declares the function operateOnTransfer
This interface can be found in CMTAT/contracts/interfaces/engine/IRuleEngine.sol
Before each transfer, your contract must call the function operateOnTransfer which is the entrypoint for the RuleEngine.
npm run-script uml
npm run-script uml:ruleEngine
The following rules are available:
| Rule | Type | Description | Doc |
|---|---|---|---|
| RuleWhitelist | RuleValidation | This rule can be used to restrict transfers from/to only addresses inside a whitelist. | RuleWhitelist.md surya-report |
| RuleWhitelistWrapper | RuleValidation | This rule can be used to restrict transfers from/to only addresses inside a group of whitelist rules managed by different operators. | RuleWhitelistWrapper.md surya-report |
| RuleBlacklist | RuleValidation | This rule can be used to forbid transfer from/to addresses in the blacklist | RuleBlacklist.md surya-report |
| RuleSanctionList | RuleValidation | The purpose of this contract is to use the oracle contract from Chainalysis to forbid transfer from/to an address included in a sanctions designation (US, EU, or UN). | RuleSanctionList.md surya-report |
| RuleConditionalTransfer | RuleOperation | This page describes a Conditional Transfer implementation. This rule requires that transfers have to be approved before being executed by the token holders. | RuleConditionalTransfer.md surya-report |
The Rule Engine and the other rules are not upgradeable. The reason is the following: If we need a new on, we just issue a new one, and set inside the CMTAT token (or the RuleEngine for the rules) to use the new.
- Pause
There are no functionalities to put in pause the contracts.
- Kill / Deactivate the contracts
There are no functionalities to kill/deactivate the contracts.
The gasless integration was not part of the audit performed by ABDK on the version 1.0.1
The RuleEngine contracts and the other rules support client-side gasless transactions using the Gas Station Network (GSN) pattern, the main open standard for transfering fee payment to another account than that of the transaction issuer. The contract uses the OpenZeppelin contract ERC2771Context, which allows a contract to get the original client with _msgSender() instead of the fee payer given by msg.sender .
At deployment, the parameter forwarder inside the contract constructor has to be set with the defined address of the forwarder. Please note that the forwarder can not be changed after deployment.
Please see the OpenGSN documentation for more details on what is done to support GSN in the contract.
The contracts have been audited by ABDKConsulting, a globally recognized firm specialized in smart contracts' security.
Fixed version : v1.0.2
The first audit was performed by ABDK on the version 1.0.1.
The release v1.0.2 contains the different fixes and improvements related to this audit.
The temporary report is available in Taurus. Audit 3.3.CollectedIssues.ods
The final report is available in ABDK_CMTA_CMTATRuleEngine_v_1_0.pdf.
You will find the report performed with Slither in
| Version | File |
|---|---|
| latest | slither-report.md |
| v1.0.2 | v1.0.2-slither-report.md |
| v1.0.3 | v1.0.3-slither-report.md |
Here a summary of the main documentation
| Document | Link/Files |
|---|---|
| Technical documentation | doc/technical/ |
| Toolchain | doc/TOOLCHAIN.md |
| Functionalities | doc/functionalities.pdf |
| Surya report | doc/surya |
See also Taurus - Token Transfer Management: How to Apply Restrictions with CMTAT and ERC-1404
Explain how it works.
The contracts are developed and tested with Foundry, a smart contract development toolchain.
To install the Foundry suite, please refer to the official instructions in the Foundry book.
You must first initialize the submodules, with
forge install
See also the command's documentation.
Later you can update all the submodules with:
forge update
See also the command's documentation.
The official documentation is available in the Foundry website
forge build --contracts src/RuleEngine.sol
forge build --contracts src/RuleWhiteList.sol
You can run the tests with
forge testTo run a specific test, use
forge test --match-contract <contract name> --match-test <function name>Generate gas report
forge test --gas-reportSee also the test framework's official documentation, and that of the test commands.
- Perform a code coverage
forge coverage
- Generate LCOV report
forge coverage --report lcov
- Generate
index.html
forge coverage --report lcov && genhtml lcov.info --branch-coverage --output-dir coverageSee Solidity Coverage in VS Code with Foundry & Foundry forge coverage
The official documentation is available in the Foundry website
This documentation has been written for the version v1.0.2
To run the script for deployment, you need to create a .env file. The value for CMTAT.ADDRESS is require only to use the script RuleEngine.s.sol Warning : put your private key in a .env file is not the best secure way.
- File .env
PRIVATE_KEY=<YOUR_PRIVATE_KEY>
CMTAT_ADDRESS=<CMTAT ADDDRESS
- Command
CMTAT with RuleEngine
forge script script/CMTATWithRuleEngineScript.s.sol:CMTATWithRuleEngineScript --rpc-url=$RPC_URL --broadcast --verify -vvvValue of YOUR_RPC_URL with a local instance of anvil : 127.0.0.1:8545
Only RuleEngine with a Whitelist contract
forge script script/RuleEngineScript.s.sol:RuleEngineScript --rpc-url=$RPC_URL --broadcast --verify -vvvThe code is copyright (c) Capital Market and Technology Association, 2018-2024, and is released under Mozilla Public License 2.0.