Ethereum transaction to UML sequence diagram generator

Unified Modeling Language (UML) sequence diagram generator for Ethereum transaction.

The below example is of a Maker DAO CDP transaction with gas usages.

tx2uml 0x4d953a8c531624e8336df5060239b7c0462b3d4d0cc5dcbb61af679ba81d161a -v -g -o makerDao

See a lot more examples here

Install

The following installation assumes Node.js has already been installed which comes with Node Package Manager (NPM).

tx2uml needs Java installed as that's required by PlantUML to generate the diagrams.

To install globally so you can run tx2uml from anywhere

npm link tx2uml --only=production

To upgrade run

npm install tx2uml -g

To see which version you are using

npm ls tx2uml

Usage

Command Line Interface (CLI)

Use the -h option to see the tx2uml CLI usage options

$ tx2uml -h
Usage: tx2uml <transaction hash or comma separated list of hashes> [options]

Ethereum transaction visualizer that generates a UML sequence diagram from transaction contract calls.

The transaction hashes have to be in hexadecimal format with a 0x prefix. If running for multiple transactions, the comma separated list of transaction hashes must not have white spaces. eg spaces or tags.

Options:
  -f, --outputFormat <value>    output file format: png, svg or puml (default: "png")
  -o, --outputFileName <value>  output file name
  -n, --network <network>       mainnet, ropsten, kovan or rinkeby (default: "mainnet")
  -a, --alethioApiKey <key>     Alethio API Key
  -p, --params                  show function params and return values (default: false)
  -g, --gas                     show gas usages (default: false)
  -e, --ether                   show Ether value (default: false)
  -t, --transfers               only show ether and token transfers (default: false)
  -v, --verbose                 run with debugging statements (default: false)
  -h, --help                    output usage information

Syntax

Participants

The participant names are shortened contract addresses. Basically, the first and last 2 bytes in hexadecimal format with a 0x prefix.

Stereotypes are added for the contract and token name if they can be sourced. The contract name comes from Etherscan's verified contracts. The token name comes from Alethio.

Messages

There are five types of messages

Call an external contract call shown as a filled arrow head at the to contract.
Return of a call shown as a dotted line with the filled arrow head.
Value transfer of Ether shown as an open arrow head with the amount in Ethers
Create a new contract with
Selfdestruct shown as a dotted lined with a filled arrow head

Delegate Calls

A delegatecall allows code to be executed on a contract in the context of the calling contract. That is, the delegated code appears as if it is running on the caller's contract. This means it has access to the caller's storage, Ether and calls will appear to come from the caller.

In the sequence diagram, the lifeline of the delegated call will be in blue and calls will come from the calling contract. In the below example, the third call is the delegate call to the 0x3333..4444 contract. Although the code is executed on the 0x3333..4444 contract, the context is from 0x2222..3333 so the two calls to 0x4444..5555 are shown in blue and are from 0x2222..3333.

Data Source

Alethio

All the contract calls are sourced from Alethio. Specifically, the Contract Messages API which as already done the hard work of parsing the transaction trace to extract the contract call details.

The Alethio API is free for volumes less than 10,000 calls a month. After that you'll need an API key from https://developers.aleth.io/. In order to trace large transactions, over a dozen Alethio calls can be made for one transaction as contract messages are limited to 100 messages per API call.

PlantUML

PlantUML is a Java program that can convert Plant UML syntax into png, svg or eps images. tx2uml pipes the PlantUML to the spawned Java process which then pipes the image outputs to a file.

plantuml.jar version 1.2020.2 is currently used and it shipped in the lib folder.

See Recent changes for PlantUML's release notes.

PlantText

PlantText is an online tool that generates diagrams from PlantUML.

PlantUML extension for VS Code

Jebbs PlantUML extension for VS Code is used to authoring the PlantUML diagrams.

Alt-D on Windows, or Option-D on Mac, to stat PlantUML preview in VS Code.

UML Syntax

Good online resources for learning UML

Similar transaction visualisation tools

Development

npm test, build and publish commands

npm run test
npm run prettier:fix
npm run build
# make tx2uml globally available
npm link
npm publish

ashwinrz / tx2uml