precompile

Documentation

Index

• Variables
• func DefaultRequiredGas(gasConfig store.GasConfig, methodType MethodType, methodInputArgs []byte) uint64
• func LoadAbiFile(fs embed.FS, path string) (abi.ABI, error)
• func ValidateMethodInputsCount(inputs MethodInputs, expectedCount int) error
• type Contract
  • func NewContract(abi abi.ABI, address common.Address, bytecode string) *Contract
  • func (c *Contract) Address() common.Address
  • func (c *Contract) Bytecode() string
  • func (c *Contract) RegisterMethods(methods ...Method) *Contract
  • func (c *Contract) RequiredGas(input []byte) uint64
  • func (c *Contract) Run(evm *vm.EVM, contract *vm.Contract, readOnlyMode bool) (methodOutputArgs []byte, runErr error)
• type Event
• type EventArgument
• type EventEmitter
  • func NewEventEmitter(sdkCtx sdk.Context, abi abi.ABI, address common.Address, ...) *EventEmitter
  • func (ee *EventEmitter) Emit(event Event) error
• type Method
• type MethodInputs
• type MethodOutputs
• type MethodType
• type RunContext
  • func NewRunContext(sdkCtx sdk.Context, evm *vm.EVM, contract *vm.Contract, ...) *RunContext
  • func (rc *RunContext) EventEmitter() *EventEmitter
  • func (rc *RunContext) IsMsgValue() bool
  • func (rc *RunContext) MsgSender() common.Address
  • func (rc *RunContext) MsgValue() *big.Int
  • func (rc *RunContext) SdkCtx() sdk.Context
  • func (rc *RunContext) TxOrigin() common.Address
• type VersionMap
  • func NewMultiVersionMap(contracts []*Contract, rules func(height int64) int) *VersionMap
  • func NewSingleVersionMap(contract *Contract) *VersionMap
  • func (v *VersionMap) Address() common.Address
  • func (v *VersionMap) GetByHeight(height int64) *Contract
  • func (v *VersionMap) GetByVersion(version int) *Contract
  • func (v *VersionMap) GetLatest() *Contract

Variables

var TypesConverter = struct {
	// Address provides functions to convert between EVM and Cosmos SDK addresses.
	Address addressConverter
	// BigInt provides functions to convert between EVM and Cosmos SDK big integers.
	BigInt bigIntConverter
}{
	Address: addressConverter{},
	BigInt:  bigIntConverter{},
}

TypesConverter is a singleton that provides functions to convert types between EVM and Cosmos SDK.

Functions

func DefaultRequiredGas

func DefaultRequiredGas(
	gasConfig store.GasConfig,
	methodType MethodType,
	methodInputArgs []byte,
) uint64

DefaultRequiredGas calculates the default amount of gas required to execute a contract call with the given method type and input arguments. The default gas calculation algorithm implies a flat cost plus additional cost based on the input size: cost = costFlat + (costPerByte * len(methodInputArgs)) The costFlat and costPerByte values are taken from the provided gas config.

func LoadAbiFile

func LoadAbiFile(fs embed.FS, path string) (abi.ABI, error)

LoadAbiFile loads the ABI file from the given file system and path. The ABI file is expected to be in JSON format. If the file cannot be loaded or parsed, an error is returned.

func ValidateMethodInputsCount

func ValidateMethodInputsCount(inputs MethodInputs, expectedCount int) error

ValidateMethodInputsCount validates the count of the given method inputs against the expected value. If the counts don't match, an error is returned.

Types

type Contract

type Contract struct {
	Abi abi.ABI
	// contains filtered or unexported fields
}

Contract represents a precompiled contract that can be executed by the EVM.

func NewContract

func NewContract(abi abi.ABI, address common.Address, bytecode string) *Contract

NewContract creates a new precompiled contract with the given ABI and address.

func (*Contract) Address

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

Address returns the EVM address of the contract.

func (*Contract) Bytecode

func (c *Contract) Bytecode() string

Bytecode returns the EVM bytecode of the contract.

func (*Contract) RegisterMethods

func (c *Contract) RegisterMethods(methods ...Method) *Contract

RegisterMethods registers the given methods in the contract. If a method with the same name already exists, it will be overwritten. This function does not check whether the registered method name exists in the ABI - if not, the method will not be available for callers.

func (*Contract) RequiredGas

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

RequiredGas returns the amount of gas required to execute the contract call with the given input. If the target method does not determine the required gas by itself, the required gas is calculated based on the default algorithm that implies a flat cost plus additional cost based on the input size.

func (*Contract) Run

func (c *Contract) Run(
	evm *vm.EVM,
	contract *vm.Contract,
	readOnlyMode bool,
) (methodOutputArgs []byte, runErr error)

Run executes a contract call with the given input. The call is executed in the context of the given EVM and contract instances. The right precompiled method is determined based on the call input and the contract's ABI. The execution can be performed in read-only mode, which means that only Read methods can be executed. The call can also transfer value but the target method must be of type Write and support payable calls. Output arguments of the called method are returned as a byte slice.

type Event

type Event interface {
	// EventName returns the name of the event.
	EventName() string
	// Arguments returns the arguments of the event. The order of the arguments
	// must match the order of the event's arguments in the ABI.
	Arguments() []*EventArgument
}

Event represents an EVM event that can be emitted by a precompiled contract.

type EventArgument

type EventArgument struct {
	// Indexed indicates whether the argument is indexed. Indexed arguments are
	// used to filter events in the logs.
	Indexed bool
	// Value is the value of the argument.
	Value interface{}
}

EventArgument represents an argument of an event.

type EventEmitter

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

EventEmitter is a component that can be used to emit EVM events from a precompiled contract.

func NewEventEmitter

func NewEventEmitter(
	sdkCtx sdk.Context,
	abi abi.ABI,
	address common.Address,
	stateDB *statedb.StateDB,
) *EventEmitter

NewEventEmitter creates a new event emitter instance.

func (*EventEmitter) Emit

func (ee *EventEmitter) Emit(event Event) error

Emit emits the given EVM event. The event is appended to the state DB as a log.

type Method

type Method interface {
	// MethodName returns the name of the method.
	MethodName() string
	// MethodType returns the type of the method.
	MethodType() MethodType
	// RequiredGas returns the amount of gas required to execute the method.
	// The method may not implement its own gas calculation and return false
	// in the second return value to use the default gas calculation algorithm
	// provided by the precompiled contract.
	RequiredGas(methodInputArgs []byte) (uint64, bool)
	// Payable returns true if the method is payable and can accept a native
	// transfer of tokens. This is applicable only to method whose MethodType
	// is Write.
	Payable() bool
	// Run executes the method with the given inputs and returns the outputs.
	// The method is executed in the context of the given RunContext.
	Run(
		context *RunContext,
		inputs MethodInputs,
	) (MethodOutputs, error)
}

Method represents a precompiled contract method.

type MethodInputs

type MethodInputs []interface{}

MethodInputs is a convenience type representing an array of method inputs.

type MethodOutputs

type MethodOutputs []interface{}

MethodOutputs is a convenience type representing an array of method outputs.

type MethodType

type MethodType int

MethodType represents the type of the method.

const (
	// Read represents a read method that does not modify the state.
	Read MethodType = iota
	// Write represents a write method that modifies the state
	// (i.e. an EVM transaction).
	Write
)

type RunContext

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

RunContext represents the context in which a precompiled contract method is executed. It provides access to the EVM, the contract, and the event emitter.

func NewRunContext

func NewRunContext(
	sdkCtx sdk.Context,
	evm *vm.EVM,
	contract *vm.Contract,
	eventEmitter *EventEmitter,
) *RunContext

NewRunContext creates a new run context with the given EVM, contract, and event emitter instances.

func (*RunContext) EventEmitter

func (rc *RunContext) EventEmitter() *EventEmitter

EventEmitter returns the event emitter instance associated with the run context. The event emitter can be used to emit EVM events from the precompiled contract.

func (*RunContext) IsMsgValue

func (rc *RunContext) IsMsgValue() bool

IsMsgValue returns true if the message value is greater than zero.

func (*RunContext) MsgSender

func (rc *RunContext) MsgSender() common.Address

MsgSender returns the address of the message sender. This corresponds to the msg.sender in Solidity.

func (*RunContext) MsgValue

func (rc *RunContext) MsgValue() *big.Int

MsgValue returns the value sent with the message. This corresponds to the msg.value in Solidity.

func (*RunContext) SdkCtx

func (rc *RunContext) SdkCtx() sdk.Context

SdkCtx returns the Cosmos SDK context associated with the run context.

func (*RunContext) TxOrigin

func (rc *RunContext) TxOrigin() common.Address

TxOrigin returns the address of the transaction originator. This corresponds to the tx.origin in Solidity.

type VersionMap

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

VersionMap is a map of precompile versions.

func NewMultiVersionMap

func NewMultiVersionMap(
	contracts []*Contract,
	rules func(height int64) int,
) *VersionMap

NewMultiVersionMap creates a new VersionMap with multiple contracts. Order of the passed contracts is important. The first contract is version 1, the second contract is version 2, and so on. The rules function should return the version number based on the height.

BEWARE: Use this only when you know what you are doing. The typical use cases is ensuring backwards compatibility when breaking changes are introduced to the precompile. Double-check if you are not introducing a consensus-level regression by the way.

func NewSingleVersionMap

func NewSingleVersionMap(contract *Contract) *VersionMap

NewSingleVersionMap creates a new VersionMap with a single contract. This should be the default for most cases.

func (*VersionMap) Address

func (v *VersionMap) Address() common.Address

Address returns the address of the precompile. All versions share the same address so the latest version's address is returned.

func (*VersionMap) GetByHeight

func (v *VersionMap) GetByHeight(height int64) *Contract

GetByHeight returns the precompile version based on the chain height.

func (*VersionMap) GetByVersion

func (v *VersionMap) GetByVersion(version int) *Contract

GetByVersion returns the precompile version based on the version number.

func (*VersionMap) GetLatest

func (v *VersionMap) GetLatest() *Contract

GetLatest returns the latest precompile version.