cfg

Documentation

Overview

Package cfg provides structures and functions for building and manipulating control flow graphs (CFGs) of Solidity contracts.

Index

• type Builder
  • func NewBuilder(ctx context.Context, builder *ir.Builder) (*Builder, error)
  • func (b *Builder) Build() error
  • func (b *Builder) GetGraph() *Graph
  • func (b *Builder) GetOrderedStateVariables() ([]*Variable, error)
  • func (b *Builder) GetStorageStateVariables() ([]*Variable, error)
  • func (b *Builder) Print(contractName string)
  • func (b *Builder) ToJSON(contractName string) ([]byte, error)
  • func (b *Builder) ToMermaid() string
• type Graph
  • func NewGraph() *Graph
  • func (g *Graph) AddDependency(from string, to *ir.Import)
  • func (g *Graph) AddInheritance(from string, to *ast.BaseContract)
  • func (g *Graph) AddNode(name string, contract *ir.Contract, isEntryContract bool)
  • func (g *Graph) CountNodes() int
  • func (g *Graph) GetNode(name string) *Node
  • func (g *Graph) GetNodes() map[string]*Node
  • func (g *Graph) NodeExists(name string) bool
• type Node
  • func (n *Node) GetContract() *ir.Contract
  • func (n *Node) GetImportNames() []string
  • func (n *Node) GetImports() []*ir.Import
  • func (n *Node) GetInheritedContractNames() []string
  • func (n *Node) GetInherits() []*ast.BaseContract
  • func (n *Node) GetName() string
  • func (n *Node) IsEntryContract() bool
  • func (n *Node) ToString() string
• type Variable
  • func (v *Variable) GetContract() *ir.Contract
  • func (v *Variable) GetNode() *Node
  • func (v *Variable) GetVariable() *ir.StateVariable
  • func (v *Variable) IsEntryContract() bool
  • func (v *Variable) String() string

Types

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

Builder is responsible for constructing the control flow graph (CFG) of Solidity contracts. It utilizes the Intermediate Representation (IR) provided by solgo and Graphviz for graph operations.

func NewBuilder

func NewBuilder(ctx context.Context, builder *ir.Builder) (*Builder, error)

NewBuilder initializes a new CFG builder with the given context and IR builder. Returns an error if the provided IR builder is nil or if it does not have a root contract set.

func (*Builder) Build

func (b *Builder) Build() error

Build processes the Solidity contracts using the IR builder to construct the CFG. It identifies the entry contract and explores all dependencies and inherited contracts. Returns an error if the root node or entry contract is not set in the IR builder.

func (*Builder) GetGraph

func (b *Builder) GetGraph() *Graph

GetGraph returns the internal Graph instance of the CFG.

func (*Builder) GetOrderedStateVariables

func (b *Builder) GetOrderedStateVariables() ([]*Variable, error)

GetOrderedStateVariables returns a slice of state variables in the order of their declaration. It fetches variables from the entry contract and follows the inheritance chain. Returns an error if the graph is not initialized or the entry contract is not found.

func (*Builder) GetStorageStateVariables

func (b *Builder) GetStorageStateVariables() ([]*Variable, error)

GetStorageStateVariables returns a slice of state variables relevant to storage. It follows the inheritance chain and collects variables from base contracts before the derived ones. Returns an error if the graph is not initialized or the entry contract is not found.

func (*Builder) Print

func (b *Builder) Print(contractName string)

Print displays information about a specific contract or the entry contract in the graph. If the contractName is provided, it prints details of the specified contract. If the contractName is empty, it finds and prints details of the entry contract in the graph.

The function prints the contract's name, its status as an entry contract, and recursively prints information about its imports and inherited contracts, if any.

func (*Builder) ToJSON

func (b *Builder) ToJSON(contractName string) ([]byte, error)

ToJSON converts a specified contract or the entire graph to a JSON representation. This method is part of the Builder type which presumably builds or manages the CFG.

If a contractName is provided, the method attempts to find and convert only the specified contract node within the graph to JSON. If the specified contract is not found, it returns an error.

If no contractName is provided (i.e., an empty string), the method converts the entire graph to JSON, representing all nodes within the graph.

func (*Builder) ToMermaid

func (b *Builder) ToMermaid() string

ToMermaid generates a string representation of the control flow graph (CFG) in Mermaid syntax. Mermaid is a tool that generates diagrams and flowcharts from text in a similar manner as markdown.

The function iterates through each node in the graph and constructs the Mermaid syntax accordingly. It represents each contract in the graph as a node in the Mermaid graph. Entry contracts are distinguished with a special notation. The function also visualizes dependencies and inheritance relationships between contracts using arrows in the Mermaid syntax.

If the graph is nil or contains no nodes, the function returns a default string indicating that no contracts are found.

type Graph

type Graph struct {
	Nodes map[string]*Node
}

Graph represents a directed graph of Nodes, with each node representing a Solidity contract. The graph captures the relationships and dependencies among contracts within a project.

func NewGraph

func NewGraph() *Graph

NewGraph creates and returns a new instance of a Graph.

func (*Graph) AddDependency

func (g *Graph) AddDependency(from string, to *ir.Import)

AddDependency creates a dependency edge from one node to another by adding an import. The dependency is defined from 'from' node to 'to' import.

func (*Graph) AddInheritance

func (g *Graph) AddInheritance(from string, to *ast.BaseContract)

AddInheritance adds an inheritance relationship from one node to a base contract. The relationship is added to the 'from' node's Inherits slice.

func (*Graph) AddNode

func (g *Graph) AddNode(name string, contract *ir.Contract, isEntryContract bool)

AddNode adds a new Node to the Graph. It takes the contract name, its IR representation, and a boolean indicating if it is an entry contract. If the node already exists, it does nothing.

func (*Graph) CountNodes

func (g *Graph) CountNodes() int

CountNodes returns the total number of nodes in the Graph.

func (*Graph) GetNode

func (g *Graph) GetNode(name string) *Node

GetNode retrieves a node by name from the Graph. It returns nil if the node does not exist.

func (*Graph) GetNodes

func (g *Graph) GetNodes() map[string]*Node

GetNodes returns all nodes present in the Graph.

func (*Graph) NodeExists

func (g *Graph) NodeExists(name string) bool

NodeExists checks if a node with the given name exists in the Graph.

type Node

type Node struct {
	Name          string              `json:"name"`
	Contract      *ir.Contract        `json:"-"`
	Imports       []*ir.Import        `json:"imports"`
	Inherits      []*ast.BaseContract `json:"inherits"`
	EntryContract bool                `json:"entry_contract"`
}

Node represents a node in the graph, encapsulating information about a Solidity contract. It includes the contract's name, IR representation, import dependencies, inherited contracts, and a flag indicating if it's the entry contract.

func (*Node) GetContract

func (n *Node) GetContract() *ir.Contract

GetContract returns the IR representation of the Solidity contract encapsulated by the node.

func (*Node) GetImportNames

func (n *Node) GetImportNames() []string

GetImportNames returns a slice of the absolute paths of all import dependencies of the contract.

func (*Node) GetImports

func (n *Node) GetImports() []*ir.Import

GetImports returns a slice of all the import dependencies of the contract.

func (*Node) GetInheritedContractNames

func (n *Node) GetInheritedContractNames() []string

GetInheritedContractNames returns a slice of names of all contracts inherited by the contract.

func (*Node) GetInherits

func (n *Node) GetInherits() []*ast.BaseContract

GetInherits returns a slice of all the contracts inherited by the contract.

func (*Node) GetName

func (n *Node) GetName() string

GetName returns the name of the Solidity contract.

func (*Node) IsEntryContract

func (n *Node) IsEntryContract() bool

IsEntryContract returns true if the node represents an entry contract in the graph.

func (*Node) ToString

func (n *Node) ToString() string

ToString provides a string representation of the Node, including its name, entry contract status, imports, and inherited contracts. This is useful for debugging and logging purposes.

type Variable

type Variable struct {
	Node          *Node             // Node is the contract where the state variable is defined.
	StateVariable *ir.StateVariable // StateVariable is the IR representation of the state variable.
	IsEntry       bool              // IsEntry indicates if this variable is from the entry contract.
}

Variable represents a state variable within a smart contract. It encapsulates information about the state variable and its relationship to the contract it belongs to.

func (*Variable) GetContract

func (v *Variable) GetContract() *ir.Contract

GetContract returns the IR representation of the contract to which this variable belongs.

func (*Variable) GetNode

func (v *Variable) GetNode() *Node

GetNode returns the contract node associated with this state variable.

func (*Variable) GetVariable

func (v *Variable) GetVariable() *ir.StateVariable

GetVariable returns the internal IR representation of the state variable.

func (*Variable) IsEntryContract

func (v *Variable) IsEntryContract() bool

IsEntryContract checks if this variable is from the entry contract.

func (*Variable) String

func (v *Variable) String() string

String returns the name of the state variable.