solidity

Documentation

Overview

Package solidity provides a source map to determine original code locations from op codes in EVM traces. This package doesn't typically need to be used directly, and can be automatically supported by adding the source-map flag to `ethier gen`.

See https://docs.soliditylang.org/en/v0.8.14/internals/source_mappings.html for more information.

Index

• Constants
• type JumpType
• type Location
• type Source
• type SourceMap
  • func NewSourceMap(sources []*Source, contracts map[string]*compiler.Contract, ...) (*SourceMap, error)
  • func (sm *SourceMap) CoverageCollector() (vm.EVMLogger, func() []byte)
  • func (sm *SourceMap) Source(contract common.Address, pc uint64) (*Location, bool)
  • func (sm *SourceMap) SourceByName(contract string, pc uint64) (*Location, bool)

Constants

const (
	FunctionIn  = JumpType(`i`)
	FunctionOut = JumpType(`o`)
	RegularJump = JumpType(`-`)
)

Possible JumpType values.

Types

type JumpType

type JumpType string

A JumpType describes the action of a JUMP instruction.

type Location

type Location struct {
	Start, Length int

	// FileIdx refers to the index of the source file in the inputs to solc, as
	// passed to NewSourceMap(), but can generally be ignored in favour of the
	// Source, which is determined from the NewSourceMap() input.
	FileIdx int
	Source  string

	// Line and Col are both 1-indexed as this is typical behaviour of IDEs and
	// coverage reports.
	Line, Col int
	// EndLine and EndCol are Length bytes after Line and Col, also 1-indexed.
	EndLine, EndCol int

	Jump          JumpType
	ModifierDepth int
}

A Location is an offset-based location in a Solidity file. Using notation described in https://docs.soliditylang.org/en/v0.8.14/internals/source_mappings.html, s = Start, l = Length, f = FileIdx, j = Jump, and m = ModifierDepth.

type Source

type Source struct {
	File, Code string
}

A Source is a source file used by solc when compiling contracts. The File is the string output from solc's source list in the combined JSON, and Code is the contents of File.

type SourceMap

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

A SourceMap maps a program counter from an EVM trace to the original position in the Solidity source code.

func NewSourceMap

func NewSourceMap(sources []*Source, contracts map[string]*compiler.Contract, deployed map[common.Address]string) (*SourceMap, error)

NewSourceMap returns a SourceMap based on solc --combined-json output, coupled with deployment addresses of the contracts. The sources are the sourceList array from the combined JSON, and the order must not be changed The key of the contracts map must match the value of the deployed map to allow the SourceMap to find the correct mapping when only an address is available.

func (*SourceMap) CoverageCollector

func (sm *SourceMap) CoverageCollector() (vm.EVMLogger, func() []byte)

CoverageCollector returns an EVMLogger that can be used to trace EVM operations for code coverage. The returned function returns an LCOV trace file at any time coverage is not being actively collected (i.e. it is not thread safe with respect to VM computation).

func (*SourceMap) Source

func (sm *SourceMap) Source(contract common.Address, pc uint64) (*Location, bool)

Source returns the code location that was compiled into the instruction at the specific program counter in the deployed contract.

func (*SourceMap) SourceByName

func (sm *SourceMap) SourceByName(contract string, pc uint64) (*Location, bool)

SourceByName functions identically to Source but doesn't require that the contract has been deployed. NOTE that there isn't a one-to-one mapping between runtime byte code (i.e. program counter) and instruction number because the PUSH* instructions require additional bytes; see https://docs.soliditylang.org/en/v0.8.14/internals/source_mappings.html.