DeFi

A DeFi project.

Install

Preferred: Use The Devcontainer

Prefer working inside the provided devcontainer instead of installing toolchains and running commands directly on your host machine.

This is important for security: a devcontainer is not bulletproof, and Docker is not a true sandbox, but isolating dependencies and execution from your main OS environment can still reduce the attack surface and lower the impact of a compromised dependency, script, or tool.

Available configurations:

• .devcontainer/mounted/devcontainer.json: mounts the local repository into the container workspace
• .devcontainer/unmounted/devcontainer.json: copies the workspace into a Docker volume instead of mounting it from the host

The unmounted option is generally the safer default because it reduces direct host filesystem exposure. The mounted option is more convenient when you explicitly want a live bind mount from the host.

In VS Code:

1. Install the Dev Containers extension if it is not already installed.
2. Run Dev Containers: Open Folder in Container....
3. Choose either .devcontainer/unmounted/devcontainer.json or .devcontainer/mounted/devcontainer.json.
4. After the container starts, run dependency installation and project commands inside the container terminal.

If you only need one recommendation, prefer .devcontainer/unmounted/devcontainer.json over local installation and local execution.

Local Installation

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

• Run without fuzz testing, use forge test -vvv

Generate Coverage Report

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

Coverage Screenshot

TBD

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/Vault.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/vault \
baolean/manticore:latest

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

3. Select Solidity version

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

4. Run manticore:

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

SuMo

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

Note: there are issues when forge needs to compile with --ffi

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

Deployed Addresses

TBD

Git Release Flow

beta-* is forked off dev and merged into rc-* (once integratoin issues fixed). rc-* is merged into main (once audit fixes are done).

• beta-* branches contain fixes found during frontend/backend integrations, updated ABIs & new testnet addresses
• rc-* branches contain audit fixes, audit report and mainnet addresses
• main branch freeze latest rc-*