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.

There's also call diagram examples in the Evolution of Uniswap examples.

Value Transfer Diagrams

More value transfer diagram examples can be found here.

There's also value transfer diagram examples in the Evolution of Uniswap examples.

Install

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

tx2uml needs Java installed to generate the diagrams using PlantUML.

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 shortened tx hashes joined together with a 'v' prefix for value transfer diagrams.
  -u, --url <url>               URL of the archive node with trace transaction support (default: "http://localhost:8545", env: ARCHIVE_NODE_URL)
  -c, --chain <value>           Name or chain id of the blockchain explorer to get contract source code from. `none` will not get any source code. `custom` will use the `explorerUrl` option. A name like `ethereum` or `base` will map to a chain id, eg 1 or 8453. Alternatively, use an integer of the chain id. Supported names: ethereum, custom, none, sepolia, holesky, hoodi, arbitrum, optimisim, polygon, avalanche, base, bsc, crono, fantom, sonic, gnosis, moonbeam, celo, scroll, linea, blast, berachain, zksync (default: "ethereum", env: ETH_NETWORK)
  -e, --explorerUrl <url>       required if a `custom` chain is used. eg a testnet like Polygon Mumbai https://api-testnet.polygonscan.com/api (env: EXPLORER_URL)
  -k, --etherscanKey <value>    Etherscan like block explorer API key (env: EXPLORER_API_KEY)
  -cf, --configFile <value>     name of the json configuration file that can override contract details like name and ABI (default: "tx.config.json")
  -af, --abiFile <value>        name of the json abi file that can override contract details like ABI (default: "tx.abi.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.
  --title <value>               Diagram title at the top (default: tx hash)
  -hf, --hideFooter             Hides the boxes at the bottom of the contract lifelines. (default: false)
  -hc, --hideCaption            Hides the network, block number and timestamp at the bottom of the diagram. (default: false)
  -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 [options] <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", "reth", default: "geth", env:
                               ARCHIVE_NODE_TYPE)
  -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 parameter names and values (default: false)
  -pv, --noParamValues         only hide function parameter values, not the names. Will display "?" if the name is not specified in the ABI (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)
  --mapSource <mapped-source>  Maps contracts to similar verified contracts on Etherscan. Useful for factory deployed contracts.
                               Left of the colon ":" is a comma-separated list of addresses that don't have verified source code.
                               In them middle is colon ":" that separates the two lists.
                               Right of the colon ":" is a comma-separated list of addresses that have verified source code.
                               For example: --mapSource 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640:0x8f8EF111B67C04Eb1641f5ff19EE54Cda062f163
  -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)
  --mapSource <mapped-source>  Maps contracts to similar verified contracts on Etherscan. Useful for factory deployed contracts.
                               Left of the colon ":" is a comma-separated list of addresses that don't have verified source code.
                               In them middle is colon ":" that separates the two lists.
                               Right of the colon ":" is a comma-separated list of addresses that have verified source code.
                               For example: --mapSource 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640:0x8f8EF111B67C04Eb1641f5ff19EE54Cda062f163
  -hb, --hideBalances          Hides the changes in ether and token balances at the bottom. (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.sc