chain

package
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 28, 2024 License: AGPL-3.0 Imports: 31 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ConsoleLogContractAddress = common.HexToAddress("0x000000000000000000636F6e736F6c652e6c6f67")

ConsoleLogContractAddress is the address for the console.log precompile contract

View Source 
var StandardCheatcodeContractAddress = common.HexToAddress("0x7109709ECfa91a80626fF3989D68f67F5b1DD12D")

StandardCheatcodeContractAddress is the address for the standard cheatcode contract

View Source 
var _, MaxUint64 = utils.GetIntegerConstraints(false, 64)

MaxUint64 holds the max value an uint64 can take

Functions

This section is empty.

Types

type BlocksRemovedEvent 

type BlocksRemovedEvent struct {
	// Chain refers to the TestChain which emitted the event.
	Chain *TestChain

	// Blocks refers to the block(s) that was removed from the Chain.
	Blocks []*types.Block
}

BlocksRemovedEvent describes an event where a block(s) is removed from the TestChain. This only considers internally committed blocks, not ones spoofed in between block number jumps.

type CheatCodeContract 

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

CheatCodeContract defines a struct which represents a pre-compiled contract with various methods that is meant to act as a contract.

func (*CheatCodeContract) Abi 

func (c *CheatCodeContract) Abi() *abi.ABI

Abi provides the cheat code contract interface.

func (*CheatCodeContract) Address 

func (c *CheatCodeContract) Address() common.Address

Address represents the address the cheat code contract is deployed at.

func (*CheatCodeContract) Name 

func (c *CheatCodeContract) Name() string

Name represents the name of the cheat code contract.

func (*CheatCodeContract) RequiredGas 

func (c *CheatCodeContract) RequiredGas(input []byte) uint64

RequiredGas determines the amount of gas necessary to execute the pre-compile with the given input data. Returns the gas cost.

func (*CheatCodeContract) Run 

func (c *CheatCodeContract) Run(input []byte) ([]byte, error)

Run executes the given pre-compile with the provided input data. Returns the output data from execution, or an error if one occurred.

type ContractDeploymentsAddedEvent 

type ContractDeploymentsAddedEvent struct {
	// Chain refers to the TestChain which emitted the event.
	Chain *TestChain

	// Contract defines information for the contract which was deployed to the Chain.
	Contract *types.DeployedContractBytecode

	// DynamicDeployment describes whether this contract deployment was dynamic (e.g. `c = new MyContract()`) or was
	// because of a traditional transaction
	DynamicDeployment bool
}

ContractDeploymentsAddedEvent describes an event where a contract has become available on the TestChain, either due to contract creation, or a self-destruct operation being reverted.

type ContractDeploymentsRemovedEvent 

type ContractDeploymentsRemovedEvent struct {
	// Chain refers to the TestChain which emitted the event.
	Chain *TestChain

	// Contract defines information for the contract which was deployed to the Chain.
	Contract *types.DeployedContractBytecode
}

ContractDeploymentsRemovedEvent describes an event where a contract has become unavailable on the TestChain, either due to the reverting of a contract creation, or a self-destruct operation.

type PendingBlockAddedTxEvent 

type PendingBlockAddedTxEvent struct {
	// Chain refers to the TestChain which emitted the event.
	Chain *TestChain

	// Block refers to the pending block which the transaction was added to.
	Block *types.Block

	// TransactionIndex describes the index of the transaction in the pending block.
	TransactionIndex int
}

PendingBlockAddedTxEvent describes an event where a pending block had a transaction added to it.

type PendingBlockCommittedEvent 

type PendingBlockCommittedEvent struct {
	// Chain refers to the TestChain which emitted the event.
	Chain *TestChain

	// Block refers to the pending block that was committed to the Chain as the new head.
	Block *types.Block
}

PendingBlockCommittedEvent describes an event where a pending block is committed to the chain as the new head.

type PendingBlockCreatedEvent 

type PendingBlockCreatedEvent struct {
	// Chain refers to the TestChain which emitted the event.
	Chain *TestChain

	// Block refers to the Chain's pending block which was just created.
	Block *types.Block
}

PendingBlockCreatedEvent describes an event where a new pending block was created, prior to any transactions being added to it.

type PendingBlockDiscardedEvent 

type PendingBlockDiscardedEvent struct {
	// Chain refers to the TestChain which emitted the event.
	Chain *TestChain

	// Block refers to the pending block that was discarded before being committed to the Chain.
	Block *types.Block
}

PendingBlockDiscardedEvent describes an event where a pending block is discarded from the chain before being committed.

type TestChain 

type TestChain struct {

	// BlockGasLimit defines the maximum amount of gas that can be consumed by transactions in a block.
	// Transactions which push the block gas usage beyond this limit will not be added to a block without error.
	BlockGasLimit uint64

	// Events defines the event system for the TestChain.
	Events TestChainEvents
	// contains filtered or unexported fields
}

TestChain represents a simulated Ethereum chain used for testing. It maintains blocks in-memory and strips away typical consensus/chain objects to allow for more specialized testing closer to the EVM.

func NewTestChain 

func NewTestChain(genesisAlloc core.GenesisAlloc, testChainConfig *config.TestChainConfig) (*TestChain, error)

NewTestChain creates a simulated Ethereum backend used for testing, or returns an error if one occurred. This creates a test chain with a test chain configuration and the provided genesis allocation and config. If a nil config is provided, a default one is used.

func (*TestChain) AddTracer 

func (t *TestChain) AddTracer(tracer vm.EVMLogger, txs bool, calls bool)

AddTracer adds a given vm.EVMLogger or TestChainTracer to the TestChain. If directed, the tracer will be attached for transactions and/or non-state changing calls made via CallContract.

func (*TestChain) BlockFromNumber 

func (t *TestChain) BlockFromNumber(blockNumber uint64) (*chainTypes.Block, error)

BlockFromNumber obtains the block with the provided block number from the current chain. If blocks committed to the TestChain skip block numbers, this method will simulate the existence of well-formed intermediate blocks to ensure chain validity throughout. Thus, this is a "simulated" chain API method. Returns the block, or an error if one occurs.

func (*TestChain) BlockHashFromNumber 

func (t *TestChain) BlockHashFromNumber(blockNumber uint64) (common.Hash, error)

BlockHashFromNumber returns a block hash for a given block number. If the index is out of bounds, it returns an error.

func (*TestChain) CallContract 

func (t *TestChain) CallContract(msg *core.Message, state *state.StateDB, additionalTracers ...vm.EVMLogger) (*core.ExecutionResult, error)

CallContract performs a message call over the current test chain state and obtains a core.ExecutionResult. This is similar to the CallContract method provided by Ethereum for use in calling pure/view functions, as it executed a transaction without committing any changes, instead discarding them. It takes an optional state argument, which is the state to execute the message over. If not provided, the current pending state (or committed state if none is pending) will be used instead. The state executed over may be a pending block state.

func (*TestChain) CheatCodeContracts 

func (t *TestChain) CheatCodeContracts() map[common.Address]*CheatCodeContract

CheatCodeContracts returns all cheat code contracts which are installed in the chain.

func (*TestChain) Clone 

func (t *TestChain) Clone(onCreateFunc func(chain *TestChain) error) (*TestChain, error)

Clone recreates the current TestChain state into a new instance. This simply reconstructs the block/chain state but does not perform any other API-related changes such as adding additional tracers the original had. Additionally, this does not clone pending blocks. The provided method, if non-nil, is used as callback to provide an intermediate step between chain creation, and copying of all blocks, allowing for tracers to be added. Returns the new chain, or an error if one occurred.

func (*TestChain) Close added in v0.1.3 

func (t *TestChain) Close()

Close will release any objects from the TestChain that must be _explicitly_ released. Currently, the one object that must be explicitly released is the stateDB trie's underlying cache. This cache, if not released, prevents the TestChain object from being freed by the garbage collector and causes a severe memory leak.

func (*TestChain) CommittedBlocks 

func (t *TestChain) CommittedBlocks() []*chainTypes.Block

CommittedBlocks returns the real blocks which were committed to the chain, where methods such as BlockFromNumber return the simulated chain state with intermediate blocks injected for block number jumps, etc.

func (*TestChain) GenesisDefinition 

func (t *TestChain) GenesisDefinition() *core.Genesis

GenesisDefinition returns the core.Genesis definition used to initialize the chain.

func (*TestChain) Head 

func (t *TestChain) Head() *chainTypes.Block

Head returns the head of the chain (the latest block).

func (*TestChain) HeadBlockNumber 

func (t *TestChain) HeadBlockNumber() uint64

HeadBlockNumber returns the test chain head's block number, where zero is the genesis block.

func (*TestChain) PendingBlock 

func (t *TestChain) PendingBlock() *chainTypes.Block

PendingBlock describes the current pending block which is being constructed and awaiting commitment to the chain. This may be nil if no pending block was created.

func (*TestChain) PendingBlockAddTx 

func (t *TestChain) PendingBlockAddTx(message *core.Message) error

PendingBlockAddTx takes a message (internal txs) and adds it to the current pending block, updating the header with relevant execution information. If a pending block was not created, an error is returned. Returns the constructed block, or an error if one occurred.

func (*TestChain) PendingBlockCommit 

func (t *TestChain) PendingBlockCommit() error

PendingBlockCommit commits a pending block to the chain, so it is set as the new head. The pending block is set to nil after doing so. If there is no pending block when calling this function, an error is returned.

func (*TestChain) PendingBlockCreate 

func (t *TestChain) PendingBlockCreate() (*chainTypes.Block, error)

PendingBlockCreate constructs an empty block which is pending addition to the chain. The block produces by this method will have a block number and timestamp that is greater by the current chain head by 1. Returns the constructed block, or an error if one occurred.

func (*TestChain) PendingBlockCreateWithParameters 

func (t *TestChain) PendingBlockCreateWithParameters(blockNumber uint64, blockTime uint64, blockGasLimit *uint64) (*chainTypes.Block, error)

PendingBlockCreateWithParameters constructs an empty block which is pending addition to the chain, using the block properties provided. Values should be sensibly chosen (e.g., block number and timestamps should be greater than the previous block). Providing a block number that is greater than the previous block number plus one will simulate empty blocks between. Returns the constructed block, or an error if one occurred.

func (*TestChain) PendingBlockDiscard 

func (t *TestChain) PendingBlockDiscard() error

PendingBlockDiscard discards a pending block, allowing a different one to be created.

func (*TestChain) RevertToBlockNumber 

func (t *TestChain) RevertToBlockNumber(blockNumber uint64) error

RevertToBlockNumber sets the head of the chain to the block specified by the provided block number and reloads the state from the underlying database.

func (*TestChain) State 

func (t *TestChain) State() *state.StateDB

State returns the current state.StateDB of the chain.

func (*TestChain) StateAfterBlockNumber 

func (t *TestChain) StateAfterBlockNumber(blockNumber uint64) (*state.StateDB, error)

StateAfterBlockNumber obtains the Ethereum world state after processing all transactions in the provided block number. Returns the state, or an error if one occurs.

func (*TestChain) StateFromRoot 

func (t *TestChain) StateFromRoot(root common.Hash) (*state.StateDB, error)

StateFromRoot obtains a state from a given state root hash. Returns the state, or an error if one occurred.

func (*TestChain) StateRootAfterBlockNumber 

func (t *TestChain) StateRootAfterBlockNumber(blockNumber uint64) (common.Hash, error)

StateRootAfterBlockNumber obtains the Ethereum world state root hash after processing all transactions in the provided block number. Returns the state, or an error if one occurs.

type TestChainEvents 

type TestChainEvents struct {
	// PendingBlockCreated emits events indicating a pending block was created on the chain.
	PendingBlockCreated events.EventEmitter[PendingBlockCreatedEvent]

	// PendingBlockAddedTx emits events indicating a pending block had a transaction added to it.
	PendingBlockAddedTx events.EventEmitter[PendingBlockAddedTxEvent]

	// PendingBlockCommitted emits events indicating a pending block was committed to the chain.
	PendingBlockCommitted events.EventEmitter[PendingBlockCommittedEvent]

	// PendingBlockDiscarded emits events indicating a pending block was discarded before being committed to the chain.
	PendingBlockDiscarded events.EventEmitter[PendingBlockDiscardedEvent]

	// BlocksRemoved emits events indicating a block(s) was removed from the chain.
	BlocksRemoved events.EventEmitter[BlocksRemovedEvent]

	// ContractDeploymentAddedEventEmitter emits events indicating a new contract was created on chain. This is called
	// alongside ContractDeploymentRemovedEventEmitter when contract deployment changes are detected. e.g. If a
	// contract is deployed and immediately destroyed within the same transaction, a ContractDeploymentsAddedEvent
	// will be fired, followed immediately by a ContractDeploymentsRemovedEvent.
	ContractDeploymentAddedEventEmitter events.EventEmitter[ContractDeploymentsAddedEvent]

	// ContractDeploymentAddedEventEmitter emits events indicating a previously deployed contract was removed
	// from the chain. This is called alongside ContractDeploymentAddedEventEmitter when contract deployment changes
	// are detected. e.g. If a contract is deployed and immediately destroyed within the same transaction, a
	// ContractDeploymentsAddedEvent will be fired, followed immediately by a ContractDeploymentsRemovedEvent.
	ContractDeploymentRemovedEventEmitter events.EventEmitter[ContractDeploymentsRemovedEvent]
}

TestChainEvents defines event emitters for a TestChain.

type TestChainTracer 

type TestChainTracer interface {
	// EVMLogger is extended by this logger.
	vm.EVMLogger

	// CaptureTxEndSetAdditionalResults can be used to set additional results captured from execution tracing. If this
	// tracer is used during transaction execution (block creation), the results can later be queried from the block.
	// This method will only be called on the added tracer if it implements the extended TestChainTracer interface.
	CaptureTxEndSetAdditionalResults(results *types.MessageResults)
}

TestChainTracer is an extended vm.EVMLogger which can be used with a TestChain to store any captured information within call results, recorded in each block produced.

type TestChainTracerRouter 

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

TestChainTracerRouter acts as a vm.EVMLogger or TestChainTracer splitter, allowing multiple tracers to be used in place of one. When this tracer receives callback, it calls upon its underlying tracers.

func NewTestChainTracerRouter 

func NewTestChainTracerRouter() *TestChainTracerRouter

NewTestChainTracerRouter returns a new TestChainTracerRouter instance with no registered tracers.

func (*TestChainTracerRouter) AddTracer 

func (t *TestChainTracerRouter) AddTracer(tracer vm.EVMLogger)

AddTracer adds a vm.EVMLogger or TestChainTracer to the TestChainTracerRouter, so all vm.EVMLogger relates calls are forwarded to it.

func (*TestChainTracerRouter) AddTracers 

func (t *TestChainTracerRouter) AddTracers(tracers ...vm.EVMLogger)

AddTracers adds vm.EVMLogger implementations to the TestChainTracerRouter so all other method calls are forwarded to them.

func (*TestChainTracerRouter) CaptureEnd 

func (t *TestChainTracerRouter) CaptureEnd(output []byte, gasUsed uint64, err error)

CaptureEnd is called after a call to finalize tracing completes for the top of a call frame, as defined by vm.EVMLogger.

func (*TestChainTracerRouter) CaptureEnter 

func (t *TestChainTracerRouter) CaptureEnter(typ vm.OpCode, from common.Address, to common.Address, input []byte, gas uint64, value *big.Int)

CaptureEnter is called upon entering of the call frame, as defined by vm.EVMLogger.

func (*TestChainTracerRouter) CaptureExit 

func (t *TestChainTracerRouter) CaptureExit(output []byte, gasUsed uint64, err error)

CaptureExit is called upon exiting of the call frame, as defined by vm.EVMLogger.

func (*TestChainTracerRouter) CaptureFault 

func (t *TestChainTracerRouter) CaptureFault(pc uint64, op vm.OpCode, gas, cost uint64, scope *vm.ScopeContext, depth int, err error)

CaptureFault records an execution fault, as defined by vm.EVMLogger.

func (*TestChainTracerRouter) CaptureStart 

func (t *TestChainTracerRouter) CaptureStart(env *vm.EVM, from common.Address, to common.Address, create bool, input []byte, gas uint64, value *big.Int)

CaptureStart initializes the tracing operation for the top of a call frame, as defined by vm.EVMLogger.

func (*TestChainTracerRouter) CaptureState 

func (t *TestChainTracerRouter) CaptureState(pc uint64, op vm.OpCode, gas, cost uint64, scope *vm.ScopeContext, rData []byte, depth int, vmErr error)

CaptureState records data from an EVM state update, as defined by vm.EVMLogger.

func (*TestChainTracerRouter) CaptureTxEnd 

func (t *TestChainTracerRouter) CaptureTxEnd(restGas uint64)

CaptureTxEnd is called upon the end of transaction execution, as defined by vm.EVMLogger.

func (*TestChainTracerRouter) CaptureTxEndSetAdditionalResults 

func (t *TestChainTracerRouter) CaptureTxEndSetAdditionalResults(results *types.MessageResults)

CaptureTxEndSetAdditionalResults can be used to set additional results captured from execution tracing. If this tracer is used during transaction execution (block creation), the results can later be queried from the block. This method will only be called on the added tracer if it implements the extended TestChainTracer interface.

func (*TestChainTracerRouter) CaptureTxStart 

func (t *TestChainTracerRouter) CaptureTxStart(gasLimit uint64)

CaptureTxStart is called upon the start of transaction execution, as defined by vm.EVMLogger.

func (*TestChainTracerRouter) Tracers 

func (t *TestChainTracerRouter) Tracers() []vm.EVMLogger

Tracers returns the vm.EVMLogger instances added to the TestChainTracerRouter.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.