Skip to content

USAGE.md

Latest commit

 

History

History
304 lines (180 loc) · 9.48 KB

USAGE.md

File metadata and controls

304 lines (180 loc) · 9.48 KB

Usage instructions

The instructions below have been tested on Ubuntu 22.04.5 LTS.

[TOC]

Main Dependencies

The toolchain includes the following components, where the versions are the latest ones that we tested:

Smart contract

  • hardhat.config.js

    • Solidity 0.8.34 (via solc-js)
    • EVM version: Prague (Pectra upgrade)

  • Package.json

    • OpenZeppelin Contracts (Node.js module): v5.5.0
    • OpenZeppelin Contracts Upgradeable (Node.js module): v5.5.0

Tools

Submodule

Use inside Javascript tests

OpenZeppelin Contracts Upgradeable (submodule) v5.2.0 Upgradeable variant of OpenZeppelin Contracts, meant for use in upgradeable contracts. The version of the library used is available in the file USAGE.md

Warning:

  • Submodules are not automatically updated when the host repository is updated.
  • Only update the module to a specific version, not an intermediary commit.

Installation

  • Clone the repository

Clone the git repository, with the option --recurse-submodules to fetch the submodules:

git clone git@github.com:CMTA/CMTAT.git --recurse-submodules

  • Node.js version

We recommend to install the Node Version Manager nvm to manage multiple versions of Node.js on your machine. You can then, for example, install the version 20.5.0 of Node.js with the following command: nvm install 20.5.0

The file .nvmrc at the root of the project set the Node.js version. nvm usewill automatically use this version if no version is supplied on the command line.

  • node modules

To install the node modules required by CMTAT, run the following command at the root of the project:

npm install

Hardhat

Since the sunset of Truffle by Consensys ,Hardhat is our main development tool and replace Truffle.

To use Hardhat, the recommended way is to use the version installed as part of the node modules, via the npx command:

npx hardhat

Alternatively, you can install Hardhat globally:

npm install -g hardhat

See Hardhat's official documentation for more information.

Truffle [depreciated]

Truffle is no longer supported since it has been sunset by Consensys, see Consensys Announces the Sunset of Truffle and Ganache and New Hardhat Partnership

Contract size

You can get the size of the contract by running the following commands.

  • Compile the contracts:
npx hardhat compile
  • Run the script:
npm run-script size

The script calls the plugin hardhat-contract-sizer with Hardhat.

Testing

Tests are written in JavaScript by using web3js and run only with Hardhat as follows:

npx hardhat test

To use the global hardhat install, use instead hardhat test.

Please see the Hardhat documentation for more information about the writing and running of Hardhat.

Code style guidelines

We use linters to ensure consistent coding style. If you contribute code, please run this following command:

Prettier

npm run-script lint:all:prettier

For JavaScript:

npm run-script lint:js 
npm run-script lint:js:fix

For Solidity:

npm run-script lint:sol  
npm run-script lint:sol:fix

NodeJS toolchain

eslint JavaScript static analyzer, and the following plugins:

Ethlint Solidity static analyzer.

Compilation with solc

solc JavaScript bindings for the Solidity compiler.

solc --base-path . --include-path ./node_modules/ contracts/deployment/CMTAT_STANDALONE.sol

Generate documentation

NodeJS toolchain

sol2uml

Generate UML for smart contracts

solidity-coverage

Code coverage for Solidity smart-contracts

Surya

Utility tool for smart contract systems.

sol2uml

Generate UML for smart contracts

You can generate UML for smart contracts by running the following command:

npm run-script uml

Warning:

From the version v2.3.0, this command is not working and generates the following error

RangeError: Maximum call stack size exceeded

Surya

To generate documentation with surya, you can call the three bash scripts in doc/script

Task Script Command example
Generate graph script_surya_graph.sh npx surya graph -i contracts/**/*.sol
npx surya graph contracts/modules/CMTAT_BASE.sol
Generate inheritance script_surya_inheritance.sh npx surya inheritance contracts/modules/CMTAT_BASE.sol -i
npx surya inheritance contracts/modules/CMTAT_BASE.sol
Generate report script_surya_report.sh npx surya mdreport -i surya_report.md contracts/modules/CMTAT_BASE.sol
npx surya mdreport surya_report.md contracts/modules/CMTAT_BASE.sol

In the report, the path for the different files are indicated in absolute. You have to remove the part which correspond to your local filesystem.

Coverage

Code coverage for Solidity smart-contracts, installed as a hardhat plugin

npm run-script coverage

Slither

Slither is a Solidity static analysis framework written in Python3

slither .  --checklist --filter-paths "mocks|openzeppelin-contracts-upgradeable|openzeppelin-contracts|@openzeppelin|test" > slither-report.md

Mythril

It seems that Mythril version v.0.24.8 does not support custom error or maybe it is an error related to solc.

Solc experienced a fatal error.

TypeError: No matching declaration found after argument-dependent lookup.
  --> contracts/modules/internal/ERC20BurnModuleInternal.sol:27:9:
   |
27 |         require(accounts.length != 0, CMTAT_BurnModule_EmptyAccounts());
   |         ^^^^^^^
Note: Candidate: function require(bool)
Note: Candidate: function require(bool, string memory)
  • Standalone
myth analyze contracts/deployment/CMTATStandalone.sol --solc-json solc_setting.json > myth_standalone_report.md
  • With proxy
myth analyze contracts/deployment/CMTATUpgradeable.sol --solc-json solc_setting.json > myth_proxy_report.md

File path for solc is configured in solc_setting.json

Aderyn

See Cyfrin/aderyn

aderyn . -x mocks

Others NodeJS tools

This part describe the list of libraries present in the file package.json.

This package adds functions to your Hardhat scripts so you can deploy and upgrade proxies for your contracts.

Deployment script

Two scripts example deploy-cmtat-standalone.js and deploy-cmtat-standalone-light.js are available in the Hardhat scripts directory.

To run it locally with Hardhat:

npx hardhat run scripts/deploy-cmtat-standalone.js
npx hardhat run scripts/deploy-cmtat-standalone-light.js

Claude

This project contains a directory .claude and a CLAUDE.md file to help using Claude on CMTAT codebase

See code.claude.com