Ethereum Smart Contracts Visualisation Tools: Surya, Solgraph, Slither, Piet, Sol2UML and Sol Function Profiler

02. Mai 2022
Von Yamila Levalle, Security Researcher at Dreamlab Technologies

Visualisation tools are a key part of the smart contract development and documentation process, as they display high-level information about the structure of smart contracts and enable them to be understood and visualised. These tools are also useful for manual contract inspection and are a crucial part of the smart contract auditing process. Essential security information such as contract summary, functions or calls summary, control flow graph, and inheritance graph is typically included in the output of these tools.

Sūrya: Utility tool for smart contract systems, offering a number of visual outputs and information about the structure of the contract. Also supports querying the function call graph and it's used by the extension Solidity Visual Auditor to generate and show graphs.
Solgraph: A tool to generate a DOT graph that visualises the function control flow of a Solidity contract and highlights potential security vulnerabilities.
Slither: An Solidity static analysis framework. Through its printers, it can map method visibility and modifiers, state variables that are read and written, identify calls, and print the inheritance graph of a smart contract.
Piet: A web application to clarify understanding of smart contract architectures. Offers graphical representation and inspection of smart contracts as well as a markdown documentation generator.
Sol-function-profiler: This tool is a Solidity contract function profiler.
Sol2UML: Sol2UML is a tool that creates UML diagrams from Solidity source code, it is used by Etherscan to generate the UML diagrams.

Smart Contracts to Analyse

KingOfTheEtherThrone: A chain-game contract that maintains a 'throne' which agents may pay to rule. The project is no longer active, however the original smart contract can be found here:

https://github.com/crytic/not-so-smart-contracts/blob/master/unchecked_external_call/KotET_source_code/KingOfTheEtherThrone.sol

This smart contract (renamed to KingOfEther.sol) will now be used with all the visualisation tools, then analysing the output and use cases for each of the tools.

1) Surya

Surya is an utility tool for smart contract systems. It aids auditors in understanding and visualising Solidity smart contracts by providing information about the structure of the contracts and generating call graphs and inheritance graphs. It also supports querying the function call graph in multiple ways to aid in the manual inspection of contracts. Surya features:

Integrated with Visual Auditor
Currently only supports Solidity
Commands: graph, ftrace, flatten, describe, inheritance, dependencies, parse, mdreport

Usage:

describe: The describe command shows a summary of the contracts and methods in the files provided.

surya describe KingOfEther.sol

graph: The graph command outputs a DOT-formatted graph of the control flow.

surya graph KingOfEther.sol | dot -Tpng > KingOfEther2.png

Contents of the file KingOfEther2.png:

ftrace: The ftrace command outputs a treefied function call trace that is derived from the defined "CONTRACT::FUNCTION" and traversing "all|internal|external" types of calls. External calls are marked in orange and internal calls are uncolored.

surya ftrace KingOfTheEtherThrone::sweepCommission all KingOfEther.sol

mdreport: The mdreport command creates a Markdown description report with tables comprising information about the system's files, contracts and their functions. It's similar to the describe command, except it outputs a nicely formatted Markdown file.

surya mdreport King.md KingOfEther.sol

Contents of the King.md file: Public functions are listed with a red exclamation point to remind developers to be especially careful of these methods. Red octagons mean that the function can change a state variable. Modifiers are listed last.

inheritance: The inheritance command outputs a DOT-formatted graph of the inheritance tree.

surya inheritance KingOfEther.sol | dot -Tpng > KingOfEtherInheritance.png

Surya also has other three useful commands:

flatten: The flatten command outputs a flattened version of the source code, with all import statements replaced by the corresponding source code.
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.

Solidity Visual Auditor is a Visual Studio Code extension customised for Solidity developers and auditors. This extension contributes security-centric syntax and semantic highlighting, a detailed class outline, specialised views, advanced Solidity code insights and augmentation to Visual Studio Code. For Graph and Reporting Features Solidity Visual Auditor uses Surya, so you can access Surya features from within VSCode. It can show interactive call graphs with call flow highlighting.

2) Solgraph

Solgraph generates a DOT graph that visualises the function control flow of a Solidity contract and highlights potential security vulnerabilities.

Legend:

Red: Send to external address
Blue: Constant function
Yellow: View
Green: Pure
Orange: Call
Purple: Transfer
Lilac: Payable

Usage:

solgraph KingOfEther.sol > KingOfEther3.dot

To visualise the graph:

dot -Tpng KingOfEther3.dot -o KingOfEther3.png

The contents of the KingOfEther3.png file:

In the disadvantages section, Solgraph can only display the control flow graph, it doesn't operate on later versions of Solidity since the parser has to be upgraded from solidity-parser-sc to solidity-parser-antlr, and it simply flags vulnerable functions as "UNTRUSTED" without further explanation.

3) Slither

Slither allows printing and visualising much of the smart contract information through its 18 printers. The most common ones are covered below.

Usage:

Contract Summary: Output a quick summary of the contract.

slither /share/KingOfEther.sol --print contract-summary

Human Summary: Print a human-readable summary of the contracts

slither /share/KingOfEther.sol --print human-summary

Function Summary: Output a summary of the contract showing for each function:

What are the visibility and the modifiers
What are the state variables read or written
What are the calls

slither /share/KingOfEther.sol --print function-summary

Variables Written and Authorisation: Print the variables written and the check on msg.sender of each function.

slither /share/KingOfEther.sol --print vars-and-auth

Call Graph: Export the call-graph of the contracts to a dot file.

slither /share/KingOfEther.sol --print call-graph

To visualise the graph:

dot -Tpng KingOfEther.sol.KingOfTheEtherThrone.call-graph.dot -o slithercallgraph.png

Inheritance Graph: Output a graph showing the inheritance interaction between the contracts.

slither /share/KingOfEther.sol --print inheritance-graph

dot -Tpng KingOfEther.sol.inheritance-graph.dot -o slitherinheritancegraph.png

4) Piet

Piet is a web application to help clarify understanding of smart contract architectures. This is achieved by generating a graphical representation of the architectures and allowing deployed instances of smart contracts to be queried.

The graphical representation shows the inheritance structure of solidity contracts, in addition the defined enumerations and structs are also shown. To provide understanding of one single solidity contract, Piet offers an inspector view showing all members of the contract including the inherited ones. The presentation of the contract and the contract members is enriched by documentation labels derived from Ethereum NatSpec tags.

Piet also provides an interactive mode, enabling the state of a smart contract to be read, sending transactions and browsing through the events. This is achieved by connecting to the deployed smart contracts through an injected web3 object.

In the drawbacks section, Piet interface is somewhat unintuitive, and the tool’s description states that it’s still in demo mode and may contain bugs.

5) Solidity Function Profiler

A command line tool that generates a human-consumable report listing a contract's functions. This is useful during manual code review to understand which functions are made public, the modifiers used, and so on.

Usage:

node index.js KingOfEther.sol

6) Sol2UML

Sol2UML is a tool that generates UML diagrams from Solidity source code, the output can be in svg, png or dot format. It can be used with a single solidity file, a folder or with the smart contract verified source code from Etherscan.

Usage:

sol2uml KingOfEther.sol

Contents of KingOfEther.sol.svg

Comparing the Output and Functionality of the Visualisation Tools

In conclusion, each tool has its own set of advantages, disadvantages, and use cases.

If a highly detailed result with plenty of information about the contracts to analyse is required, or for complex contract interactions, the ideal approach uses Surya or Slither Printers. These both provide several choices for displaying the call graph, control flow, function call trace, contract summary, function summary, and inheritance graph. Slither also allows written variables to be seen along with the authorisation checks that evaluate msg.sender of each function. Surya can create a very useful markdown description report with tables comprising information about the system's files, contracts and their functions. One particular advantage of Surya is that it can be used through Solidity Visual Auditor within Visual Studio code.
The Solidity Function Profiler is the ideal option to produce a human-readable report, detailing the functions of a contract, their visibility, return type, and modifiers.
Piet can be used to view the contract's inheritance graph in web format. It also features a useful interactive mode that allows you to read the status of a smart contract, send transactions, and browse through events.
For the control flow graph and possible security flaws Solgraph is an option. However, remember that it can't be used in newer contracts as the parser needs to be updated from solidity-parser-sc to solidity-parser-antlr, and it can't parse contracts from solidity 0.5 and up. As a result, this option is only applicable for older smart contracts.
Sol2UML is the tool to use for modelling Ethereum smart contract interactions using a modelling language like UML.

For general purposes, Surya is a good and very flexible option. For example, for high-level analysis in a smart contract audit process, Surya describe can be used to display a summary of the contracts and methods and Surya mdreport to output the report to a nicely formatted markdown file. Then, for further analysis in the manual code review phase, Surya graph can be used to generate a formatted control flow graph, Surya inheritance to review the inheritance interaction between contracts and Surya ftrace to analyse the most important functions of the smart contracts.

References and Useful Links:

Alle Blog-Posts