All-In-One IGO

Contract to use for normal & VPR IGO but also any other extra cases where a project wants to allow people to buy tokens at a set price.

More details on Confluence

Install

yarn install && forge install

Each time a new dependency is added in lib/ run forge install.

Architecture

Follow's Solidstate architecture (diamond pattern based).

folder	layer	description	example
-	internal - interface	contains custom error, enum, struct& event	IRandomnessWritableInternal.sol, IRandomnessReadableInternal.sol
-	external - interface	common interfaces which define external and public function's prototypes	IRandomnessFallback.sol, IRandomnessReadble.sol, IRandomnessWritable.sol
readable	external	set of functions which only read the storage	RandomnessReadable.sol
writable	external & internal	set of functions which update storage; internal function always declares in xyzWritableInternal.sol & contains modifier	RandomnessInternalWritable.sol, RandomnessWritable.sol
./	storage	library for to map, access and modify storage	RandomnessStorage.sol

Tests

Since Permit 2 has been integrated --via-ir compilation is compulsory to solve stak too deep issue.

• Run without fuzz testing, use forge test -vvv --nmc Differential --via-ir
• Run with fuzz testing, use forge test -vvv --ffi --via-ir (takes more time as it produced random data)

Generate Coverage Report

If lcov is not installed, run brew install lcov. Then run: forge coverage --report lcov --ffi --nmc Differential && genhtml lcov.info --branch-coverage --output-dir coverage

Coverage Screenshot

Run GitHub Actions Locally

1. Install act
2. Load env var source .env
3. Run a job: act -j foundry -s SEED (hit ENTER when asked Provide value for 'SEED':)

Run Advanced Tests

Slither

slither .

Note: Slither has been added to GitHub actions, so it will run automatically on every push and pull requests.

Mythril

myth a src/IGO.sol --solc-json mythril.config.json (you can use both myth a and mythril analyze)

Manticore

1. Run Docker container:

docker run --rm -it --platform linux/amd64 \
-v $(pwd):/home/igo \
baolean/manticore:latest

2. Go to mounted volume location: cd /home/igo

3. Select Solidity version

solc-select install 0.8.17 && solc-select use 0.8.17

4. Run manticore:

manticore src/IGO.sol --contract IGO --solc-remaps="openzeppelin-contracts/=lib/openzeppelin-contracts/contracts/ permit2/=lib/permit2/src/"

SuMo

After install yarn dependencies, run yarn sumo test to run mutation testing.

Note: there issues as we can specificy --ffi parameter when compiling with forge

Gambit

1. Install it locally, see GitHub

2. Run: gambit mutate --json gambit-conf.json

Note: gambit does not take into account specified remappings

Best Practices to Follow

Generics

• Code formatter & linter: prettier, solhint, husky, lint-staged & husky
• Foundry

Security

• Solidity Patterns
• Solcurity Codes
• Secureum posts (101 & 101: Security Pitfalls & Best Practice)
• Smart Contract Security Verification Standard
• SWC

Be Prepared For Audits

Must Do Checklist:

• Unit (TDD) & integration (BDD) tests (green)
• Well refactored & commented code
  • Use where needed: NatSpec comment, PlantUML, Sol2UML (UML for Solidity)
• Internal Audit - Tool Suite
  • Secureum articles
    • Audit Techniques & Tools 101
    • Audit Findings 101
    • Audit Findings 201
  • Built in Foundry:
    • fuzz testing: generate (semi-)random inputs
      • There is also echidna which can be used
    • differential testing
    • invariant testing
  • Static analysers: mythril, slither (GitHub actions), securify, smartcheck, oyente
    • Note: solidity smt checker can be used on top for formal verification testing
  • Symbolic execution: manticore
  • Mutation testing: SuMo, Gambit, universalmutator
  • Audit report generator: MythX

Note: For more complex contract Paper code review should be considered to check for conception & logic errors.

Other tools for a deeper analysis:

• static binary EVM analysis: rattle
• control flow graph: surya (integrated into VSCode extension), evm_cfg_builder
• disassemble EVM code: ethersplay, pyevmasm
• runtime verification: scribble (also done by: mythril, harvey, mythx)
• JSON RPC multiplexer, analysis tool wrapper & test integration tool: etheno (Ethereum testing Swiss Army knife)
  • eliminates the complexity of tools like Echidna on large, multi-contract projects