UML for Ethereum Transactions

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

The following contract call and value transfer diagrams are for the Uniswap V1 transaction 0xe5e35ee13bb6326df4da89f17504a81923299d4986de06a019ca7856cbe76bca that removes MKR liquidity from the Uniswap V1 MKR pool.

Contract Call Diagram

See a lot more call diagram examples with different options here.

Value Transfer Diagrams

More value transfer diagram examples can be found 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

Usage

Command Line Interface (CLI)

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

Usage: tx2uml [command] <options>

Ethereum transaction visualizer that generates UML sequence diagrams from an Ethereum archive node and Etherscan like
block explorer

Options:
  -f, --outputFormat <value>    output file format (choices: "png", "svg", "eps", "puml", default: "svg")
  -o, --outputFileName <value>  output file name. Defaults to the transaction hash
  -u, --url <url>               URL of the archive node with trace transaction support (default: "http://localhost:8545", env: ARCHIVE_NODE_URL)
  -c, --chain <value>           blockchain explorer network to get source code from (choices: "mainnet", "goerli", "sepolia", "arbitrum", "optimisim", "polygon", "avalanche", "bsc", "crono", "fantom", "gnosis",
                                "moonbeam", default: "mainnet", env: ETH_NETWORK)
  -cf, --configFile <value>     name of the json configuration file that can override contract details like name and ABI (default: "tx.config.json")
  -m, --memory <gigabytes>      max Java memory of PlantUML process in gigabytes. Java default is 1/4 of physical memory. Large txs in png format will need up to 12g. svg format is much better for large transactions.
  -v, --verbose                 run with debugging statements (default: false)
  -V, --version                 output the version number
  -h, --help                    display help for command

Commands:
  call [options] <txHash(s)>    Generates a UML sequence diagram of transaction contract calls between contracts (default).
  value <txHash(s)>             Generates a UML sequence diagram of token and ether value transfers between accounts and contracts. This requires an archive node that supports debug_traceTransaction with custom EVM tracers which are Geth, Erigon or Anvil.
  copy [options] <txHash(s)>    Copies one or more transactions from one chain to another. This is either relayed with the original signature or impersonated with a different signer.
  help [command]                display help for command

Call command

Usage: tx2uml call <txhash(s)> [options]

Generates a UML sequence diagram of transaction contract calls between contracts (default).

Arguments:
  txHash(s)                   transaction hash or an array of hashes in hexadecimal format with a 0x prefix. If running for multiple transactions, the comma-separated list of transaction hashes must not have white spaces

Options:
  -n, --nodeType <value>      type of Ethereum node the provider url is pointing to. This determines which trace API is used (choices: "geth", "erigon", "nether", "openeth", "tgeth", "besu", "anvil", default: "geth", env: ARCHIVE_NODE_TYPE)
  -k, --etherscanKey <value>  Etherscan like block explorer API key
  -a, --noAddresses <value>   hide calls to contracts in a list of comma-separated addresses with a 0x prefix
  -d, --depth <value>         limit the transaction call depth
  -e, --noEther               hide ether values (default: false)
  -g, --noGas                 hide gas usages (default: false)
  -l, --noLogDetails          hide log details emitted from contract events (default: false)
  -p, --noParams              hide function params and return values (default: false)
  -t, --noTxDetails           hide transaction details like nonce, gas and tx fee (default: false)
  -x, --noDelegates           hide delegate calls from proxy contracts to their implementations and calls to deployed libraries (default: false)
  -h, --help                  display help for command

Value command

Usage: tx2uml value <txhash(s)> [options]

Generates a UML sequence diagram of token and ether value transfers between accounts and contracts. This requires an archive node that supports debug_traceTransaction with custom EVM tracers which are Geth, Erigon or Anvil.

Arguments:
  txHash(s)   transaction hash or an array of hashes in hexadecimal format with a 0x prefix. If running for multiple transactions, the comma-separated list of transaction hashes must not have white spaces

Options:
  -e, --onlyToken  get transfers only from token events. No ETH transfers will be included. Use when provider does not
                   support debug_traceTransaction with custom tracer. (default: false)
  -h, --help       display help for command

Copy command

Usage: tx2uml copy <txhash(s)> [options]

Copies one or more transactions from one chain to another. This is either relayed with the original signature or
impersonated with a different signer.

Arguments:
  txHash(s)                    transaction hash or an array of hashes in hexadecimal format with a 0x prefix. If
                               running for multiple transactions, the comma-separated list of transaction hashes must
                               not have white spaces

Options:
  -du, --destUrl <url>         url of the node provider the transaction is being copied to (default:
                               "http://localhost:8545", env: DEST_NODE_URL)
  -i, --impersonate <address>  Address of the account that is to be impersonated. This only works for development nodes
                               like Hardhat and Anvil. The default is the transaction is relayed so is from the
                               original signer.
  -h, --help                   display help for command

Configuration file

You can use a config file to set contract properties that are not available on chain or on Etherscan. For example, the contract's name and protocol. The config file can also be used to supply contract ABIs if a contract has not been verified on Etherscan. This is particularly useful if you are testing on a local fork of mainnet and some of the contracts in the transaction are yet to be deployed on mainnet.

The config file is in json format and has json schema config.schema.json. The config file is an object with an address property for each contract.

The default file is tx.config.json in the current working folder, but you can set the location and name of the config file with the -cf, --configFile <value> option.

An example config file

{
  "0xd6ed651CfDf7778794649FfA87557EF091DfFE81": {
    "protocolName": "mStable",
    "contractName": "Convex3CrvVault",
    "tokenSymbol": "mv3CRV",
    "tokenName": "Convex 3Crv Vault",
    "abi": [
      ...
    ]
  },
  "0xaF94d5585CCCb04afcf98cA49E60F09f96f6444d": {
    "protocolName": "mStable",
    "contractName": "CurveMetapoolCalculatorLibrary"
  }
}

Call Sequence 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.

Messages

There are five types of messages

• Call is a solid or dotted line with a filled arrow head at the to contract.
• Return is a dotted line with a filled arrow head at the from contract.
• Delegate is a solid or dotted line with an open arrow head at the to contract.
• Create is a filled line with a filled arrow head and a circle at the contract being created.
• Selfdestruct is a solid line with a half filled arrow head looping back on itself with a Self-Destruct label.

Call and delegate messages with a dotted line are proxy calls that uses the calling contract's fallback function.

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. Examples of delegate calls are proxy contracts calling their implementations or calls to library contracts.

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.

The -x or --noDelegates option can be used to hide all delegate calls.

Data Source

Archive node that supports tracing transactions

tx2uml needs an Ethereum archive node that supports the debug_traceTransaction or trace_transaction JSON RPC APIs.

The ethereum node url can be set with the -u or --url options or by exporting the ARCHIVE_NODE_URL environment variable. For example

export ARCHIVE_NODE_URL=https://api.archivenode.io/<your API key>/turbogeth 

Known Ethereum node clients that support debug_traceTransaction with a tracer parameter are:

• Go-Ethereum (Geth)
• Erigon (fka Turbo-Geth)

tx2uml will use --nodeType geth as it's default option.

You can test if your node supports debug_traceTransaction with the following curl command

curl --location --request POST 'https://your.node.url/yourApiKey' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc":"2.0",
    "method":"debug_traceTransaction",
    "params":["0xe5e35ee13bb6326df4da89f17504a81923299d4986de06a019ca7856cbe76bca", {"tracer": "callTracer"}],
    "id":1
}'

Anvil, Hardhat and Genache all support debug_traceTransaction but without the tracer parameter so will not work with tx2uml.

Known Ethereum node clients that support trace_transaction are:

• OpenEthereum
• Nethermind
• Hyperledger Besu
• Anvil

You can test if your node supports trace_transaction with the following curl command

curl --location --request POST 'https://your.node.url/yourApiKey' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc":"2.0",
    "method":"trace_transaction",
    "params":["0xb2b0e7b286e83255928f81713ff416e6b8d0854706366b6a9ace46a88095f024"],
    "id":1
}'

Ethereum client trace support

Ethereum API provider trace support

Most Ethereum API providers do not provide tracing or debugging APIs as they are resource intensive on the server side.

• ArchiveNode.io supports trace_transaction with Nethereum and full debug_traceTransaction support with Erigon.

• Alchemy supports both trace_transaction and debug_traceTransaction on their paid Growth plan. Only the in-built call and prestate tracers are supported. Custom tracers is not supported.

• QuickNode supports both trace_transaction and debug_traceTransaction on their paid plan. The in-built call and prestate tracers are supported. Custom tracers can be requested via support and approved if within resourcing limits.

• Chainstack supports both trace_transaction and debug_traceTransaction on their Growth plan when a dedicated Geth or Erigon archive node is deployed. For Erigon, this includes built-in and custom tracer support.

• GetBlock supports trace_transaction but not debug_traceTransaction.

• WatchData supports trace_transaction and is available on their free plan.

• Infura does not support either trace_transaction or debug_traceTransaction.

Etherscan

Etherscan is used to get the Application Binary Interfaces (ABIs) for the contracts used in a transaction. Etherscan's get contract ABI API is used with module contract and action getsourcecode. For example https://api.etherscan.io/api?module=contract&action=getsourcecode&address=0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413

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.2023.1 under MIT license is currently 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.

Generate png files form puml

The following will generate png files for the above examples.

java -jar ./lib/plantuml.jar ./examples/syntax.puml ./examples/delegate.puml

UML Syntax

Good online resources for learning UML

• PlantUML Sequence diagrams
• Ashley's PlantUML Doc
• UML 2 Sequence Diagramming Guidelines

Similar Visualisation Tools

• Transaction Tracer
• Tenderly
• EthTx info
• Bloxy
• Etherscan

Development

Testing

If you want to run all the tests, you'll need to export the following environment variables which are used by the tests to connect to different archive nodes. If you are using Archive Node, you need to replace with the API key provided to you.

export ARCHIVE_NODE_URL=https://api.archivenode.io/<your api key>/nethermind
export NETHERMIND_URL=https://api.archivenode.io/<your api key>/nethermind
export ERIGON_GETH_URL=https://api.archivenode.io/<your api key>/erigon
npm run test

Note two of the tests are currently failing due to bugs TurboGeth and Nethermind bugs.

Publishing

npm build and publish commands

npm run prettier:fix
npm run clean
npm run package-lock
npm run build
# make tx2uml globally available for local testing
npm link
# check all the files are included in the npm package
npm pack --dry-run
npm publish