Working with IR

Wake IR (intermediate representation) model builds on top of the AST (abstract syntax tree) produced by the Solidity compiler. It is a tree representation of the source code holding additional information.

The IR tree nodes can be divided into a few categories:

• Declarations - nodes that represent declarations of variables, functions, structs, etc.,
• Statements - nodes that control the execution flow (if, for, while, etc.) and nodes that represent a single operation ending with a semicolon (assignment, function call, etc.),
• Expressions - nodes that typically have a value (literals, identifiers, function calls, etc.),
• Type names - nodes that represent a name of a type (uint, address, etc.), usually used in a VariableDeclaration,
• Meta - nodes typically used as helpers that do not belong to any of the above categories.

All expressions, type names and a VariableDeclaration have a type information attached to them. See wake.ir.types API reference for more information.

Nodes structure

The IR tree can have a very complex structure. However, there are a few rules that make it easier to understand:

• SourceUnit is the root node of the IR tree,
• FunctionDefinitions and ModifierDefinitions hold statements,
• statements may hold other statements and expressions,
• there are only a few cases when expressions may be used without a parental statement (i.e. outside of a function/modifier body):
  • in an InheritanceSpecifier argument list,
    • e.g. contract A is B(1, 2) {},
  • in a ModifierInvocation argument list,
    • e.g. function foo() public onlyOwner(1, 2) {},
  • in a VariableDeclaration initial value,
    • e.g. uint a = 1;,
  • in an ArrayTypeName fixed length value,
    • e.g. uint[2] a;,
• only a few nodes may reference other nodes (declarations specifically):
  • Identifier as a simple name reference,
    • e.g. owner referencing a variable declaration,
  • MemberAccess as a member access reference,
    • e.g. owner.balance referencing a global symbol ADDRESS_BALANCE,
  • IdentifierPathPart a helper structure used in IdentifierPath to describe a part of a path separated by dots,
    • e.g. Utils.IERC20 in contract A is Utils.IERC20 {},
  • UserDefinedTypeName as a reference to a user defined type,
    • e.g. MyContract in new MyContract(),
  • ExternalReference a helper structure describing a YulIdentifier referencing a Solidity VariableDeclaration,
    • e.g. assembly { mstore(0, owner) }.

The following example shows the whole IR tree for a simple Solidity code snippet:

pragma solidity ^0.8;

library Math{
    function fib(uint n) public pure returns (uint) {
        if (n < 2)
            return n;
        return fib(n - 1) + fib(n - 2);
    }
}

Nodes of the same category are colored the same. Both nodes and labels of edges are clickable and lead to the corresponding API documentation. Dash edges represent a reference to another node.

Tip

Since all IR nodes are iterable, it is very easy to create a simple printer to explore what parts of the source code correspond to which nodes.

from __future__ import annotations

import networkx as nx
import rich_click as click
import wake.ir as ir
import wake.ir.types as types
from rich import print
from wake.printers import Printer, printer


class StructurePrinter(Printer):
    def print(self) -> None:
        pass

    def visit_source_unit(self, node: ir.SourceUnit):
        for n in node:
            print(f"{n}\n{n.source}\n====================")

    @printer.command(name="structure")
    def cli(self) -> None:
        pass