types

Documentation

Index

• func GetSrcMapLength(src string) int
• func GetSrcMapSourceUnitID(src string) int
• func GetSrcMapStart(src string) int
• func ParseABIFromInterface(i any) (*abi.ABI, error)
• func RemoveContractMetadata(bytecode []byte) []byte
• type AST
  • func (a *AST) UnmarshalJSON(data []byte) error
• type Compilation
  • func NewCompilation() *Compilation
  • func (c *Compilation) CacheSourceCode() error
• type CompiledContract
  • func (c *CompiledContract) GetDeploymentMessageData(args []any) ([]byte, error)
  • func (c *CompiledContract) IsMatch(initBytecode []byte, runtimeBytecode []byte) bool
• type ContractDefinition
  • func (s ContractDefinition) GetNodeType() string
  • func (c *ContractDefinition) UnmarshalJSON(data []byte) error
• type ContractKind
• type ContractMetadata
  • func ExtractContractMetadata(bytecode []byte) *ContractMetadata
  • func (m ContractMetadata) ExtractBytecodeHash() []byte
• type FunctionDefinition
  • func (s FunctionDefinition) GetNodeType() string
• type Node
• type SourceArtifact
• type SourceMap
  • func ParseSourceMap(sourceMapStr string) (SourceMap, error)
  • func (s SourceMap) GetInstructionIndexToOffsetLookup(bytecode []byte) ([]int, error)
• type SourceMapElement
• type SourceMapJumpType

Functions

func GetSrcMapLength

func GetSrcMapLength(src string) int

GetSrcMapLength returns the length of the function definition in bytes

func GetSrcMapSourceUnitID

func GetSrcMapSourceUnitID(src string) int

GetSrcMapSourceUnitID returns the source unit ID based on the source of the AST

func GetSrcMapStart

func GetSrcMapStart(src string) int

GetSrcMapStart returns the byte offset where the function definition starts in the source file

func ParseABIFromInterface

func ParseABIFromInterface(i any) (*abi.ABI, error)

ParseABIFromInterface parses a generic object into an abi.ABI and returns it, or an error if one occurs.

func RemoveContractMetadata

func RemoveContractMetadata(bytecode []byte) []byte

RemoveContractMetadata takes bytecode and attempts to detect contract metadata within it, splitting it where the metadata is found. If contract metadata could be located, this method returns the bytecode solely (no contract metadata, and no constructor arguments, which tend to follow). Otherwise, this method returns the provided input as-is.

Types

type AST

type AST struct {
	// NodeType represents the node type (currently we only evaluate source unit node types)
	NodeType string `json:"nodeType"`
	// Nodes is a list of Nodes within the AST
	Nodes []Node `json:"nodes"`
	// Src is the source file for this AST
	Src string `json:"src"`
}

AST is the abstract syntax tree

func (*AST) UnmarshalJSON

func (a *AST) UnmarshalJSON(data []byte) error

type Compilation

type Compilation struct {
	// SourcePathToArtifact maps source file paths to their corresponding SourceArtifact.
	SourcePathToArtifact map[string]SourceArtifact

	// SourceIdToPath is a mapping of source unit IDs to source file paths.
	SourceIdToPath map[int]string

	// SourceCode is a lookup of a source file path from SourceList to source code. This is populated by
	// CacheSourceCode.
	SourceCode map[string][]byte
}

Compilation represents the artifacts of a smart contract compilation.

func NewCompilation

func NewCompilation() *Compilation

NewCompilation returns a new, empty Compilation object.

func (*Compilation) CacheSourceCode

func (c *Compilation) CacheSourceCode() error

CacheSourceCode caches source code for each CompiledSource in the compilation in the CompiledSource.SourceCode field. This method will attempt to populate each CompiledSource.SourceCode which has not yet been populated (is nil) before returning an error, if one occurs.

type CompiledContract

type CompiledContract struct {
	// Abi describes a contract's application binary interface, a structure used to describe information needed
	// to interact with the contract such as constructor and function definitions with input/output variable
	// information, event declarations, and fallback and receive methods.
	Abi abi.ABI

	// InitBytecode describes the bytecode used to deploy a contract.
	InitBytecode []byte

	// RuntimeBytecode represents the rudimentary bytecode to be expected once the contract has been successfully
	// deployed. This may differ at runtime based on constructor arguments, immutables, linked libraries, etc.
	RuntimeBytecode []byte

	// SrcMapsInit describes the source mappings to associate source file and bytecode segments in InitBytecode.
	SrcMapsInit string

	// SrcMapsRuntime describes the source mappings to associate source file and bytecode segments in RuntimeBytecode.
	SrcMapsRuntime string

	// Kind describes the kind of contract, i.e. contract, library, interface.
	Kind ContractKind
}

CompiledContract represents a single contract unit from a smart contract compilation.

func (*CompiledContract) GetDeploymentMessageData

func (c *CompiledContract) GetDeploymentMessageData(args []any) ([]byte, error)

GetDeploymentMessageData is a helper method used create contract deployment message data for the given contract. This data can be set in transaction/message structs "data" field to indicate the packed init bytecode and constructor argument data to use.

func (*CompiledContract) IsMatch

func (c *CompiledContract) IsMatch(initBytecode []byte, runtimeBytecode []byte) bool

IsMatch returns a boolean indicating whether provided contract bytecode is a match to this compiled contract definition.

type ContractDefinition

type ContractDefinition struct {
	// NodeType represents the node type (currently we only evaluate source unit node types)
	NodeType string `json:"nodeType"`
	// Nodes is a list of Nodes within the AST
	Nodes []Node `json:"nodes"`
	// Src is the source file for this AST
	Src string `json:"src"`
	// CanonicalName is the name of the contract definition
	CanonicalName string `json:"canonicalName,omitempty"`
	// Kind is a ContractKind that represents what type of contract definition this is (contract, interface, or library)
	Kind ContractKind `json:"contractKind,omitempty"`
}

ContractDefinition is the contract definition node

func (ContractDefinition) GetNodeType

func (s ContractDefinition) GetNodeType() string

func (*ContractDefinition) UnmarshalJSON

func (c *ContractDefinition) UnmarshalJSON(data []byte) error

type ContractKind

type ContractKind string

ContractKind represents the kind of contract definition represented by an AST node

const (
	// ContractKindContract represents a contract node
	ContractKindContract ContractKind = "contract"
	// ContractKindLibrary represents a library node
	ContractKindLibrary ContractKind = "library"
	// ContractKindInterface represents an interface node
	ContractKindInterface ContractKind = "interface"
)

type ContractMetadata

type ContractMetadata map[string]any

ContractMetadata is an CBOR-encoded structure describing contract information which is embedded within smart contract bytecode by the Solidity compiler (unless explicitly directed not to). Reference: https://docs.soliditylang.org/en/v0.8.16/metadata.html

func ExtractContractMetadata

func ExtractContractMetadata(bytecode []byte) *ContractMetadata

ExtractContractMetadata extracts contract metadata from provided byte code and returns it. If contract metadata could not be extracted, nil is returned.

func (ContractMetadata) ExtractBytecodeHash

func (m ContractMetadata) ExtractBytecodeHash() []byte

ExtractBytecodeHash extracts the bytecode hash from given contract metadata and returns the bytes representing the hash. If it could not be detected or extracted, nil is returned.

type FunctionDefinition

type FunctionDefinition struct {
	// NodeType represents the node type (currently we only evaluate source unit node types)
	NodeType string `json:"nodeType"`
	// Src is the source file for this AST
	Src  string `json:"src"`
	Name string `json:"name,omitempty"`
}

FunctionDefinition is the function definition node

func (FunctionDefinition) GetNodeType

func (s FunctionDefinition) GetNodeType() string

type Node

type Node interface {
	// GetNodeType returns solc's node type e.g. FunctionDefinition, ContractDefinition.
	GetNodeType() string
}

Node interface represents a generic AST node

type SourceArtifact

type SourceArtifact struct {
	// Ast describes the abstract syntax tree artifact of a source file compilation, providing tokenization of the
	// source file components.
	Ast any

	// Contracts describes a mapping of contract names to contract definition structures which are contained within
	// the source.
	Contracts map[string]CompiledContract

	// SourceUnitId refers to the identifier of the source unit within the compilation.
	SourceUnitId int
}

SourceArtifact represents a source descriptor for a smart contract compilation, including AST and contained CompiledContract instances.

type SourceMap

type SourceMap []SourceMapElement

SourceMap describes a list of elements which correspond to instruction indexes in compiled bytecode, describing which source files and the start/end range of the source code which the instruction maps to.

func ParseSourceMap

func ParseSourceMap(sourceMapStr string) (SourceMap, error)

ParseSourceMap takes a source mapping string returned by the compiler and parses it into an array of SourceMapElement objects. Returns the list of SourceMapElement objects.

func (SourceMap) GetInstructionIndexToOffsetLookup

func (s SourceMap) GetInstructionIndexToOffsetLookup(bytecode []byte) ([]int, error)

GetInstructionIndexToOffsetLookup obtains a slice where each index of the slice corresponds to an instruction index, and the element of the slice represents the instruction offset. Returns the slice lookup, or an error if one occurs.

type SourceMapElement

type SourceMapElement struct {
	// Index refers to the index of the SourceMapElement within its parent SourceMap. This is not actually a field
	// saved in the SourceMap, but is provided for convenience so the user may remove SourceMapElement objects during
	// analysis.
	Index int

	// Offset refers to the byte offset which marks the start of the source range the instruction maps to.
	Offset int

	// Length refers to the byte length of the source range the instruction maps to.
	Length int

	// SourceUnitID refers to an identifier for the CompiledSource file which houses the relevant source code.
	SourceUnitID int

	// JumpType refers to the SourceMapJumpType which provides information about any type of jump that occurred.
	JumpType SourceMapJumpType

	// ModifierDepth refers to the depth in which code has executed a modifier function. This is used to assist
	// debuggers, e.g. understanding if the same modifier is re-used multiple times in a call.
	ModifierDepth int
}

SourceMapElement describes an individual element of a source mapping output by the compiler. The index of each element in a source map corresponds to an instruction index (not to be mistaken with offset). It describes portion of a source file the instruction references.

type SourceMapJumpType

type SourceMapJumpType string

SourceMapJumpType describes the type of jump operation occurring within a SourceMapElement if the instruction is jumping.

const (
	// SourceMapJumpTypeNone indicates no jump occurred.
	SourceMapJumpTypeNone SourceMapJumpType = ""

	// SourceMapJumpTypeJumpIn indicates a jump into a function occurred.
	SourceMapJumpTypeJumpIn SourceMapJumpType = "i"

	// SourceMapJumpTypeJumpOut indicates a return from a function occurred.
	SourceMapJumpTypeJumpOut SourceMapJumpType = "o"

	// SourceMapJumpTypeJumpWithin indicates a jump occurred within the same function, e.g. for loops.
	SourceMapJumpTypeJumpWithin SourceMapJumpType = "-"
)