sol2uml

Solidity 2 UML

Unified Modeling Language (UML) class diagram generator for Solidity contracts.

Install

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

Usage

To see the usage options

$ sol2uml -h

Usage: sol2uml [options] <file or root folder>

Generates UML diagrams from Solidity source code

Options:
  -v, --verbose                 With debugging statements
  -f, --outputFormat [value]    Output file format: svg, png, dot or all (default: "svg")
  -n, --outputFileName [value]  Output file name
  -c, --clusterFolders          Cluster contracts into source folders
  -h, --help                    output usage information

To generate the test contracts in this repo

$ sol2uml.js ./src/contracts

To generate a SVG diagram of all Solidity files under some root folder and output the svg file to a specific location

$ sol2uml.js path/to/contracts/root/folder -n ./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.js path/to/contracts/root/folder/solidity/file.sol -f png -n ./someFile.png

To generate SVG and PNG diagrams of all Solidity files under some root folder. The output will be diagram.svg and diagram.png files in the working folder.

$ sol2uml.js ./contracts -f all -v

Example from Open Zeppelin

Open Zeppelin's ERC20 token contracts Generated from version 2.3.0

See examples for more diagrams.

UML Syntax

Good online resources for learning UML

• UML 2 Class Diagramming Guidelines
• Creating class diagrams with UML

Terminology differences

A Solidity variable becomes an attribute in UML and a Solidity function becomes an operation in UML.

Stereotypes

Class stereotypes

• Interface
• Abstract
• Library

Operator stereotypes

• 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.

UML Relationships

The most concise explanation of the What is the difference between association, aggregation and composition.

The following UML relationships are used in Solidity terms:

• Association contract A has a storage variable of contract or interface B. The variable will exist beyond the transaction in the smart contract.
• Dependency contract interface or library A has a memory variable of class B. This can be a function parameter, return parameter or function variable. The variable will no longer exist beyond the transaction.
• Generalisation contract or interface A inherits from contract, interface or abstract contract B
• Composition
• Aggregation

Note a class in the above can also be an Interface, Abstract class or Library.

About

This is a rewrite of the Richard Ramos's solidity-diagram-gen tool which no longer works as it uses solidity-parser which cannot handle newer Solidity syntax like constructor.

This version uses the solidity-parser-antlr Solidity parser which is built on top of ANTLR4 grammar. The logic to generate the dot syntax has been rewritten and different UML syntax is now used.

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 SVN dynamically.

TODO

• Document UML syntax
• Option to specify a list of contracts to generate along with their dependencies. This was not all contracts in dependent libraries like Open Zeppelin need to be generated.
• Portrait output mode
• Add indicator for state mutability. eg view and pure functions