Unified Modeling Language (UML) sequence diagram generator for Ethereum transaction.
The below example transaction is a mStable swap from 5,100 USD Coin (USDC) to 5,096 Tether USD (USDT).
tx2uml 0xb2b0e7b286e83255928f81713ff416e6b8d0854706366b6a9ace46a88095f024
See a lot more examples here
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=productionTo upgrade run
npm install tx2uml -gTo see which version you are using
npm ls tx2umlUse 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 of transaction contract calls from an Ethereum archive node and Etherscan API.
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. Defaults to the transaction hash.
-u, --url <url> URL of the archive node with trace transaction support. Can also be set with the ARCHIVE_NODE_URL environment variable. (default: http://localhost:8545)
-n, --nodeType <value> geth (GoEthereum), tgeth (Turbo-Geth), openeth (OpenEthereum, previously Parity), nether (Nethermind), besu (Hyperledger Besu). Can also be set with the ARCHIVE_NODE_TYPE env var. (default: "geth")
-p, --noParams Hide function params and return values (default: false)
-g, --noGas Hide gas usages (default: false)
-e, --noEther Hide ether values (default: false)
-l, --noLogDetails Hide log details emitted from contract events. (default: false)
-t, --noTxDetails Hide transaction details like nonce, gas and tx fee (default: false)
-k, --etherscanKey Etherscan API key. Register your API key at https://etherscan.io/myapikey
-d, --depth <value> Limit the transaction call depth.
-v, --verbose run with debugging statements (default: false)
-h, --help output usage information
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.
There are five types of messages
- Call is a solid or dotted line with a filled arrow head at the
tocontract. - Return is a dotted line with a filled arrow head at the
fromcontract. - Delegate is a solid or dotted line with an open arrow head at the
tocontract. - 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-Destructlabel.
Call and delegate messages with a dotted line are proxy calls that uses the calling contract's fallback function.
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.
tx2uml needs an Ethereum archive node that supports the debug_traceTransaction or trace_replayTransaction JSON RPC APIs.
Known Ethereum node clients that support debug_traceTransaction are:
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
}'Known Ethereum node clients that support trace_replayTransaction are:
- OpenEthereum
- Nethermind
- Hyperledger Besu supports tracing with method is trace_transaction which has the same response.
You can test if your node supports trace_replayTransaction 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_replayTransaction",
"params":["0xb2b0e7b286e83255928f81713ff416e6b8d0854706366b6a9ace46a88095f024", ["trace"]],
"id":1
}'Most Ethereum API providers do not provide tracing or debugging APIs as they are resource intensive on the server side.
- ArchiveNode.io brings archive data on the Ethereum blockchain to small time developers who otherwise couldn't afford it. They offer both Nethermind and Turbo-Geth archive nodes. If you want to use one specifically, you can add either /nethermind or /turbogeth to the end of your endpoint.
Infura does not support tracing or debugging transactions.
Alchemy does support tracing transactions on their paid Growth plan but it was not reliable at the time of development.
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 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.26 is currently shipped in the lib folder.
See Recent changes for PlantUML's release notes.
PlantText is an online tool that generates diagrams from PlantUML.
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.
The following will generate png files for the above examples.
java -jar ./lib/plantuml.jar ./examples/syntax.puml ./examples/delegate.puml
Good online resources for learning UML
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 TURBO_GETH_URL=https://api.archivenode.io/<your api key>/turbogeth
npm run test
Note two of the tests are currently failing due to bugs TurboGeth and Nethermind bugs.
npm build and publish commands
npm run prettier:fix
npm run clean
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