Unified Modeling Language (UML) class diagram generator for Solidity contracts.
Open Zeppelin's ERC20 token contracts generated from version 4.1.2
See examples for more diagrams.
The following installation assumes Node.js has already been installed which comes with Node Package Manager (NPM).
To install globally so you can run sol2uml
from anywhere
npm link sol2uml --only=production
To upgrade run
npm upgrade sol2uml -g
To see which version you are using
npm ls sol2uml
To see the usage options
$ sol2uml -h
Usage: sol2uml <fileFolderAddress> [options]
Generates UML diagrams from Solidity source code.
If no file, folder or address is passes as the first argument, the working folder is used.
When a folder is used, all *.sol files are found in that folder and all sub folders.
If an Ethereum address with a 0x prefix is passed, the verified source code from Etherscan will be used.
Options:
-b, --baseContractNames <value> only output contracts connected to these comma separated base contract names
-f, --outputFormat <value> output file format: svg, png, dot or all (default: "svg")
-o, --outputFileName <value> output file name
-d, --depthLimit <depth> number of sub folders that will be recursively searched for Solidity files. Default -1 is unlimited (default: -1)
-n, --network <network> mainnet, ropsten, kovan, rinkeby or goerli (default: "mainnet")
-k, --etherscanApiKey <key> Etherscan API Key
-c, --clusterFolders cluster contracts into source folders
-v, --verbose run with debugging statements
-h, --help output usage information
To generate a diagram of all contracts under the contracts folder and its sub folders
sol2uml ./contracts
To generate a diagram of EtherDelta's contract from the verified source code on Etherscan. The output wil be a svg file 0xB8c77482e45F1F44dE1745F52C74426C631bDD52.svg
in the working folder.
sol2uml 0xB8c77482e45F1F44dE1745F52C74426C631bDD52
To generate a diagram of EtherDelta's contract from the verified source code on Etherscan Ropsten. The output wil be a svg file 0xB8c77482e45F1F44dE1745F52C74426C631bDD52.svg
in the working folder.
sol2uml 0xB8c77482e45F1F44dE1745F52C74426C631bDD52 -n ropsten
To generate all Solidity files under some root folder and output the svg file to a specific location
sol2uml path/to/contracts/root/folder -o ./outputFile.svg
To generate a diagram of all contracts in a single Solidity file, the output file in png format to output file ./someFile.png
sol2uml path/to/contracts/root/folder/solidity/file.sol -f png -o ./someFile.png
To generate diagrams of all Solidity files under some root folder. The output will be contracts.svg
and contracts.png
files in the working folder.
sol2uml ./contracts -f all -v
The main function that parses Solidity source code from files or files in folders is parseUmlClassesFromFiles. This returns an array of UML class objects.
EtherscanParser is a class that parses Etherscan's verified Solidity source code for a contract. For example
import { convertUmlClassesToSvg, EtherscanParser } from 'sol2uml'
async function generateSvg() {
const etherscanParser = new EtherscanParser()
// get the verified source code from Etherscan for the contract address and
// parse Solidity into UML class objects
const umlClasses = await etherscanParser.getUmlClasses('0xB8c77482e45F1F44dE1745F52C74426C631bDD52')
// Convert UML classes to a svg string
const svg = await convertUmlClassesToSvg(umlClasses)
}
generateFilesFromUmlClasses is used to write the dot, svg and png files from an array of UML class objects.
Good online resources for learning UML
A Solidity variable becomes an attribute in UML and a Solidity function becomes an operation in UML.
- Interface
- Abstract - if any of the contract's functions are abstract, the class will have an Abstract stereotype. Child contracts of abstract contracts that do not implement all the abstract functions are currently not marked as Abstract.
- Library
- event
- modifier
- abstract - is there is no function body on a contract, the operator is marked as abstract. Operators on an Interface do not have an abstract stereotype as all operators are abstract.
- fallback - abstract fallback functions will just have an abstract stereotype.
- payable - payable fallback functions will just have a fallback stereotype.
Lines:
- Solid lines are used to link the contract types of storage (state) variables. This can be linked to contracts, interfaces or libraries.
- Solid lines are also used for generalisations of contracts and abstract contracts.
- Solid lines are also used for aggregated structs and enums
- Dashed lines are used or generalisations of interfaces.
- Dash lines are also used for types of memory variables.
Heads/Tails:
- An empty triangle head is used for generalisations of contracts, interfaces and abstract contracts.
- An open arrow head is used for storage or memory variable dependencies
- A diamond tail is used for aggregations of structs and enums
This is a rewrite of the Ruzyysmartt solidity-diagram-gen tool which no longer works as it uses solidity-parser which cannot handle newer Solidity syntax like constructor
.
This version uses ruzyysmartt (GitHub @ruzyysmartt) solidity-parser-antlr Solidity parser which is built on top of [json grammar](https://github.com/solidity js). The logic to generate the dot syntax has been rewritten and different UML syntax is now used to Richard Ramos's original implementation.
The diagrams are generated using viz.js which uses Graphviz to render a Scalable Vector Graphics (SVG) file. Graphviz Online allows dot files to be edited and rendered into a SVG dynamically.