Smart Contract Diagramming for Security: A Visual Approach | Sm4rty

6 min readSep 10, 2023

Hi there, I’m Samrat Gupta, a.k.a. Sm4rty, an independent smart contract auditor and part-time bug bounty hunter. In recent months, I’ve seen a growing trend of people sharing diagrams of protocol codebases during audits.
In this blog post, I’ll explore the importance of diagrams in the context of smart contract auditing and how we can create similar diagrams for our next audit.

Let’s start:

Why Draw Diagrams?

To improve code comprehension: Diagrams can help auditors gain a deeper understanding of the codebase and its inner workings.
It helps discover critical issues: As wisely noted by gPersoon, “Interesting issues often emerge only after gaining a comprehensive understanding of the protocol.” Diagrams, particularly beneficial for visually inclined individuals, aid in uncovering these crucial issues.
It facilitates effective communication: Diagrams are a powerful tool for understanding complex systems. They can help audit teams and protocol developers to better understand the system, identify potential vulnerabilities, and communicate their findings to each other.
It provides extra value to the protocol: Diagrams can add significant value during security engagements by providing clear architectural representations. This benefits not only the auditing team but also the protocol developers, by expanding their documentation resources.

Tools for Creating Diagrams:

There are basically some automated tools to create diagrams.

Automated Tools: Automated tools can generate diagrams quickly and easily, but they may not always be accurate or complete. Some popular automated tools include:

Solidity Metrics
Surya

Manual Tools: Manual tools require more effort, but they can be more accurate and complete. Some popular manual tools include:

Miro
PowerPoint
Draw.io
Any other online UML / whiteboard tools.
Physical Pen & Paper or Whiteboard.

Automated tools vs. Drawing Manually?

Automated tools can be a good option for creating quick and basic diagrams. It can be faster and easier to use, but they may not always be as accurate or complete as manually created diagrams.
Manual tools can be a better option for creating accurate and complete diagrams, especially for complex systems. Manually creating diagrams requires more effort, but it can help auditors to better understand the system and identify deeper issues.

Types of Diagrams:

State Diagrams:
State diagrams show the current state of a smart contract and the transitions between different states when interacting with the contract. Think it of “Going from one state to another” when interacting with a contract
They can be helpful for visualizing how contracts move from one state to another during different interactions.
Contract Diagrams:
Contract diagrams provide an overview of the individual contracts within an ecosystem, outlining their functions and relationships. They can also show function calls, which can help visualize how different functions within different smart contracts interact and work together.

Creating Contract Diagrams

A contract diagram is a visual representation of the relationships between the different smart contracts in a project.
In this demo, we will draw a contract diagram for the Beam Auction Contest at Sherlock using miro. To follow along, it is recommended to give a quick skim of the codebase.

Understand the project overview: Read the documents like specifications and design materials and understand the relationships between all the components of the smart contract. This will give you a basic understanding of the project and how the contracts interlink.
Map the contracts: Review all contracts in the project. For each contract, draw a rectangle on your diagram. This will create a visual representation of all the contracts in the project.

3. Add functions to the diagram: Next, In each contract box, we will draw a small box for each external and internal function. This will show the different functions that are available in each contract.

4. Draw the relationships between the contracts and functions: Draw an arrow from each function to all contracts/functions it calls. This will show how the different contracts and functions are related to each other.

5. Optimize for clarity: After initially creating the connections, take a step back to assess the diagram’s overall clarity. It may be necessary to rearrange elements to minimize crossing lines and enhance the diagram’s readability.

How to Create State Machine Diagrams?

A state machine diagram is a graphical representation of the different states that a system can be in and the transitions between those states.
In this demo, we will draw a contract diagram for the Beam Auction Contest at Sherlock using Miro. To follow along, it is recommended to give a quick skim of the codebase.

Identify State-Changing Operations: Begin by identifying the events that can cause transitions between states. In this example, the operation we’re considering is the “minting of an NFT.”
Identify States: Recognize the different states in which the system can exist. In this example, the different states are:

Initial state: The auction is set but not yet started.
Auction started: The auction has started and users can mint NFTs.
Auction ended: The auction has ended.

3. Map State Transitions: Map out the transitions between states based on the identified actions. In this example, a few transitions are:

Initial state → Auction started when the auction is started.
Auction started → Auction ended when the auction ends.
MINT CAP Reached→ When the mint cap is reached.

4. Determine Initial and Final States: Identify the system’s initial state and any final states representing the termination or completion of the system. In this example, the initial state is the state when the auction has been set but not yet started and the final state is the auction-ended state.

5. Handle Decision Points: Represent decision points where the next state depends on certain conditions or choices. In this example, the decision point is whether the auction has started yet or not. If the auction has not started yet, the next state is the auction started state. If the auction has started, the next state depends on whether the mint cap or the cap per address has been reached.

6. Optimize for Clarity: Review and refine the state diagram for accuracy, clarity, and completeness. Ensure that the transitions make sense and in our example, we checked that it accurately represents the behavior of the Merit Dutch Auction Contract during NFT minting.

After completing all the steps, we successfully drew a state machine diagram for minting an NFT in an auction. We tracked a few changes in the state variables like MINT_CAP, MINT_CAP_PER_ADDRESS, totalRaised, etc.