Tools to create documentation for Solidity Smart Contracts
- Solidity-docgen [OpenZeppelin]
- Surya [ConsenSys]
- Sol2uml [naddison36]
- Solc Documentation output
- Auditor tool
This article presents some very interesting tools to perform an analyze of a smart contract written in Solidity and generate the documentation.
Here a summary:
- Solidity-docgen: extract the documentation
- Surya : generate graph, inheritance, markdown report, …
- Solgraph: generates a DOT graph that visualizes function control flow of a Solidity contract and highlights potential security vulnerabilities.
- Sol2uml: generate an UML/Class diagram
- Auditor tool
- vscode-solidity-auditor: Visual Studio Code extension contributing security centric syntax and semantic highlighting, a detailed class outline, specialized views, advanced Solidity code insights and augmentation to Visual Studio Code.
- Slither to perform a static analysis on the smart contract and generate a vulnerability report.
- Mythril which uses symbolic execution, SMT solving and taint analysis to detect a variety of security vulnerabilities.
Why use these tools ?
- A good documentation allows other developers and users to better understand the code.
- it helps to find bugs and security issues inside the smart contract
- When a security audit is performed, it helps the auditor to understand the code.
[TOC]
Solidity-docgen [OpenZeppelin]
solidity-docgen is a program that extracts documentation for a Solidity project.
Installation
npm install solidity-docgen
You can use it as a standalone library or as a hardhat plugin
Surya [ConsenSys]
Surya is an utility tool for smart contract systems. It provides a number of visual outputs and information about the contracts’ structure. Also supports querying the function call graph in multiple ways to aid in the manual inspection of contracts.
Installation:
npm install -g surya
Surya is also available with the VS Code extension: vscode-solidity-auditor https://github.com/ConsenSys/vscode-solidity-auditor
Graph
The graph command outputs a DOT-formatted graph of the control flow.
ftrace
The ftrace command outputs a treefied function call trace stemming from the defined “CONTRACT::FUNCTION” and traversing “all/internal/external” types of calls.
flatten
The flatten command outputs a flattened version of the source code, with all import statements replaced by the corresponding source code. “
describe
The describe command shows a summary of the contracts and methods in the files provided.
Inheritance
The inheritance command outputs a DOT-formatted graph of the inheritance tree.
Dependencies
The dependencies command outputs the c3-linearization of a given contract’s inheritance graph.
Parse
The parse command outputs a treefied AST object coming from the parser.
mdreport
The mdreport command creates a Markdown description report with tables comprising information about the system’s files, contracts and their functions.
Solgraph
An alternative to Surya to create a CFG graph is Solgraph.
Generates a DOT graph that visualizes function control flow of a Solidity contract and highlights potential security vulnerabilities.
npx solgraph contracts/YOUR_CONTRACT.sol > YOUR_CONTRACT.dot
Convert the dot file in PNG
dot -Tpng YOUR_CONTRACT.dot -o YOUR_CONTRACT.png
Sol2uml [naddison36]
A visualisation tool for Solidity contracts
It features:
-
Unified Modeling Language (UML) class diagram generator for Solidity contracts.
-
Contract storage layout diagrams.
Example:
Alternative (plantuml)
-
Run a Plantuml server on your local machine, see github.com/plantuml/plantuml-server
-
Use plantuml inside VScode to generate an uml
This feature is directly available if you install the vscode extension Solidity Visual Developer
Solc Documentation output
Generate NatSpec documentation
Solidity contracts can use a special form of comments to provide rich documentation for functions, return variables and more. This special form is named the Ethereum Natural Language Specification Format (NatSpec).
See docs - natspec-format for more information
When parsed by the compiler, documentation such as the one from the above example will produce two different JSON files.
- user doc: this doc is meant to be consumed by the end user as a notice when a function is executed
solc --userdoc ex1.sol
- dev doc: this doc is meant to be consumed by the developer.
solc --devdoc ex1.sol
-
User doc
-
All
solc --devdoc ex1.sol
- With Foundry,
solccan generate the following error:Source "OZ/access/IAccessControl.sol" not found: File not found. Searched the following locations: "".
To resolve this, you can pass the content of remappings.txtin the command:
solc OZ/=lib/openzeppelin-contracts/contracts/ --userdoc src/ex1.sol
Auditor tool
Aderyn [Cyfrin]
Solidity static analyzer
Aderyn is an open-source public good developer tool. It is a Rust-based solidity smart contract static analyzer designed to help protocol engineers and security researchers find vulnerabilities in Solidity code bases.
aderyn --output aderyn-report.md
See Cyfrin/aderyn
Mythril [ConsenSys]
Mythril is a security analysis tool for EVM bytecode.
It uses symbolic execution, SMT solving and taint analysis to detect a variety of security vulnerabilities.
Usage
myth analyze <solidity-file>
Since its used solc to compile the files, it is sometimes necessary to create a json file to map the libraries. Example for a project build with Foundry
{
"remappings": [
"OZ/=lib/openzeppelin-contracts/contracts/"
], "optimizer":{
"enabled": true,
"runs": 200
}
}
The command is then:
myth analyze <your contract> --solc-json solc_setting.json
Slither [crytic]
Slither is a very good tool to perform a static analysis on the smart contract and generate a vulnerability report.
Slither is a Solidity static analysis framework written in Python3. It runs a suite of vulnerability detectors, prints visual information about contract details, and provides an API to easily write custom analyses.
You can filter the libraries and test files to prevent them from also being analyzed by slither.
Example for a project build with Foundry
slither . --checklist --filter-paths "openzeppelin-contracts|test|forge-std" > slither-report.md
vscode-solidity-auditor [ConsenSys]
Solidity language support and visual security auditor for Visual Studio Code
VScode solidity auditor is a swiss-knife which includes a varietiy of tools to analyze a contract and generate the documentation
It offers the following option: generate report, graph, inheritance, function signature, uml,…
It includes the tool Surya too.