1 of 29

Documenting Solidity using diagrams

Nick Addison, Origin Protocol

naddison

​

​

2 of 29

sol2uml

Repo https://github.com/naddison36/sol2uml

NPM sol2uml

Install npm link sol2uml --only=production

Usage sol2uml [command] [options]

License MIT

​

3 of 29

sol2uml commands

class UML class diagram

storage Display contract's storage slots

diff Compare Etherscan source files

flatten Merge Etherscan source files into a local file

​

4 of 29

Class command

sol2uml class [options] <filesFoldersAddress>

class is default command so can be dropped

filesFoldersAddress comma-separated file names, folders or contract address

​

​

5 of 29

Class - Etherscan

sol2uml 0xC02a…6Cc2

​

Generate a WETH9.svg file

​

​

6 of 29

Class - Local file

sol2uml ./contracts/token/OETH.sol

​

​

​

​

7 of 29

Class - Local folder

sol2uml ./node_modules/@openzeppelin/contracts

​

​

8 of 29

Three diagrams to document a contract

​

  • Hierarchy high level inheritance
  • Squashed collapses all inherited properties
  • Storage layout of storage slots

​

9 of 29

Class - Origin Vault Hierarchy

10 of 29

Class - contract hierarchy

sol2uml . -b VaultCore,VaultAdmin -hv -hf -he -hs -hl -hi

-b, --baseContractNames

-hv, --hideVariables

-hf, --hideFunctions

-he, --hideEnums

-hs, --hideStructs

-hl, --hideLibraries

-hi, --hideInterfaces

11 of 29

Class - OETH Oracle Hierarchy

sol2uml . \

-hv -hf -he -hs -hl -hi \

-b OETHOracle,OETHOracleUpdater

​

​

​

12 of 29

Class squashed

sol2uml . -s -d 0 \

-b OETHOracle

​

options

-s, --squash

-d, --depth <value>

-b, --baseContractNames

13 of 29

Class - squashed, depth = 1

14 of 29

Class - squashed public

sol2uml . -s -d 0 -b OETHOracle \

-hp -hm -ht -hsc

​

options

-hp, --hidePrivates

-hm, --hideModifiers

-ht, --hideEvents

-hsc, --hideSourceContract

15 of 29

Storage command

sol2uml storage [options] <filesFoldersAddress>

filesFoldersAddress comma-separated file names, folders or contract address

​

​

16 of 29

Storage - USDC

sol2uml storage 0xa232..bdcf -s 0xa0b..eb48

​

options

-s, --storage <address>

17 of 29

Storage - USDC data

18 of 29

Storage - USDC data

sol2uml storage 0xa232..bdcf -s 0xa0b..eb48 -d

​

Options

-d, --data

-s, --storage <address>

-u, --url <url> default: "http://localhost:8545", env: NODE_URL

​

19 of 29

Storage - USDC data at block

sol2uml storage \

0xa232..bdcf \

-s 0xa0b..eb48 -d \

-hv -bn 18500000

​

options

-hv, --hideValues

-bn, --block <number>

20 of 29

Storage - Matic on Polygon

sol2uml storage 0x00..01010 \

-n polygon -hv

​

options

-n, --network <network>

21 of 29

Storage - OETHOracle

sol2uml storage . -c OETHOracle

​

options

-c, --contract <name>

22 of 29

Storage - OETH Dripper

sol2uml storage 0x2fdfbb2b905484f1445e23a97c97f65fe0e43dec \

--data --storage 0xc0f42f73b8f01849a2dd99753524d4ba14317eb3 \

--slotNames OUSD.governor,OUSD.pending.governor,OUSD.reentry.status,0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc \

--slotTypes address,address,bool,address \

--hideValues

​

​

23 of 29

Storage - OETH Dripper

24 of 29

Generation script

25 of 29

README in contract folder

26 of 29

diff command

sol2uml diff [options] <addressA> <addressB or folders>

​

​

​

27 of 29

Diff - Etherscan to local

sol2uml diff 0xB06d..2A20 .,node_modules

​

28 of 29

Diff - Upgraded OETH Vault

sol2uml diff 0x1091..89F3 0xEA24..645c

29 of 29

Diff - Upgraded OETH Vault

sol2uml diff 0x1091..89F3 0xEA24..645c