precompile

Documentation

Index

• Constants
• Variables
• func CalculateFunctionSelector(functionSignature string) []byte
• func CheckConfigure(parentTimestamp *big.Int, currentTimestamp *big.Int, ...)
• func PackModifyAllowList(address common.Address, role AllowListRole) ([]byte, error)
• func PackReadAllowList(address common.Address) []byte
• func SetAllowListRole(stateDB StateDB, address common.Address, role AllowListRole)
• type AllowListConfig
  • func (c *AllowListConfig) Address() common.Address
  • func (c *AllowListConfig) Configure(state StateDB)
  • func (c *AllowListConfig) Contract() StatefulPrecompiledContract
  • func (c *AllowListConfig) Timestamp() *big.Int
• type AllowListRole
  • func GetAllowListStatus(state StateDB, address common.Address) AllowListRole
  • func (s AllowListRole) IsAdmin() bool
  • func (s AllowListRole) IsEnabled() bool
  • func (s AllowListRole) Valid() bool
• type PrecompileAccessibleState
• type RunStatefulPrecompileFunc
• type StateDB
• type StatefulPrecompileConfig
• type StatefulPrecompiledContract

Constants

const (
	ModifyAllowListGasCost = 20_000
	ReadAllowListGasCost   = 5_000
)

Gas costs for stateful precompiles

Variables

var (
	AllowListAddress = common.HexToAddress("0x0200000000000000000000000000000000000000")

	UsedAddresses = []common.Address{
		AllowListAddress,
	}
)

Designated addresses of stateful precompiles Note: it is important that none of these addresses conflict with each other or any other precompiles in core/vm/contracts.go. We start at 0x0200000000000000000000000000000000000000 and will increment by 1 from here to reduce the risk of conflicts. For forks of subnet-evm, users should start at 0x0300000000000000000000000000000000000000 to ensure that their own modifications do not conflict with stateful precompiles that may be added to subnet-evm in the future.

Functions

func CalculateFunctionSelector

func CalculateFunctionSelector(functionSignature string) []byte

CalculateFunctionSelector returns the 4 byte function selector that results from [functionSignature] Ex. the function setBalance(addr address, balance uint256) should be passed in as the string: "setBalance(address,uint256)"

func CheckConfigure

func CheckConfigure(parentTimestamp *big.Int, currentTimestamp *big.Int, config StatefulPrecompileConfig, state StateDB)

CheckConfigure checks if [config] is activated by the transition from block at [parentTimestamp] to [currentTimestamp]. If it does, then it calls Configure on [config] to make the necessary state update to enable the StatefulPrecompile. Note: this function is called within genesis to configure the starting state if it [config] specifies that it should be configured at genesis, or happens during block processing to update the state before processing the given block. TODO: add ability to call Configure at different timestamps, so that developers can easily re-configure by updating the stateful precompile config. Assumes that [config] is non-nil.

func PackModifyAllowList

func PackModifyAllowList(address common.Address, role AllowListRole) ([]byte, error)

PackModifyAllowList packs [address] and [role] into the appropriate arguments for modifying the allow list. Note: [role] is not packed in the input value returned, but is instead used as a selector for the function selector that should be encoded in the input.

func PackReadAllowList

func PackReadAllowList(address common.Address) []byte

PackReadAllowList packs [address] into the input data to the read allow list function

func SetAllowListRole

func SetAllowListRole(stateDB StateDB, address common.Address, role AllowListRole)

SetAllowListRole sets the permissions of [address] to [role] assumes [role] has already been verified as valid.

Types

type AllowListConfig

type AllowListConfig struct {
	BlockTimestamp *big.Int `json:"blockTimestamp"`

	AllowListAdmins []common.Address `json:"adminAddresses"`
}

AllowListConfig specifies the configuration of the allow list. Specifies the block timestamp at which it goes into effect as well as the initial set of allow list admins.

func (*AllowListConfig) Address

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

Address returns the address where the stateful precompile is accessible.

func (*AllowListConfig) Configure

func (c *AllowListConfig) Configure(state StateDB)

Configure initializes the address space of [ModifyAllowListAddress] by initializing the role of each of the addresses in [AllowListAdmins].

func (*AllowListConfig) Contract

func (c *AllowListConfig) Contract() StatefulPrecompiledContract

Contract returns the singleton stateful precompiled contract to be used for the allow list.

func (*AllowListConfig) Timestamp

func (c *AllowListConfig) Timestamp() *big.Int

Timestamp returns the timestamp at which the allow list should be enabled

type AllowListRole

type AllowListRole common.Hash

Enum constants for valid AllowListRole

var (
	AllowListNoRole  AllowListRole = AllowListRole(common.BigToHash(big.NewInt(0))) // No role assigned - this is equivalent to common.Hash{} and deletes the key from the DB when set
	AllowListEnabled AllowListRole = AllowListRole(common.BigToHash(big.NewInt(1))) // Deployers are allowed to create new contracts
	AllowListAdmin   AllowListRole = AllowListRole(common.BigToHash(big.NewInt(2))) // Admin - allowed to modify both the admin and deployer list as well as deploy contracts

	// Error returned when an invalid write is attempted
	ErrReadOnlyModifyAllowList = errors.New("cannot modify allow list in read only")
	ErrCannotModifyAllowList   = errors.New("non-admin cannot modify allow list")
)

func GetAllowListStatus

func GetAllowListStatus(state StateDB, address common.Address) AllowListRole

GetAllowListStatus returns the allow list role of [address].

func (AllowListRole) IsAdmin

func (s AllowListRole) IsAdmin() bool

IsAdmin returns true if [s] indicates the permission to modify the allow list.

func (AllowListRole) IsEnabled

func (s AllowListRole) IsEnabled() bool

IsEnabled returns true if [s] indicates that it has permission to access the resource.

func (AllowListRole) Valid

func (s AllowListRole) Valid() bool

Valid returns true iff [s] represents a valid role.

type PrecompileAccessibleState

type PrecompileAccessibleState interface {
	GetStateDB() StateDB
}

PrecompileAccessibleState defines the interface exposed to stateful precompile contracts

type RunStatefulPrecompileFunc

type RunStatefulPrecompileFunc func(accessibleState PrecompileAccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error)

type StateDB

type StateDB interface {
	GetState(common.Address, common.Hash) common.Hash
	SetState(common.Address, common.Hash, common.Hash)
	SetNonce(common.Address, uint64)
}

StateDB is the interface for accessing EVM state

type StatefulPrecompileConfig

type StatefulPrecompileConfig interface {
	// Address returns the address where the stateful precompile is accessible.
	Address() common.Address
	// Timestamp returns the timestamp at which this stateful precompile should be enabled.
	// 1) 0 indicates that the precompile should be enabled from genesis.
	// 2) n indicates that the precompile should be enabled in the first block with timestamp >= [n].
	// 3) nil indicates that the precompile is never enabled.
	Timestamp() *big.Int
	// Configure is called on the first block where the stateful precompile should be enabled.
	// This allows the stateful precompile to configure its own state via [StateDB] as necessary.
	// This function must be deterministic since it will impact the EVM state. If a change to the
	// config causes a change to the state modifications made in Configure, then it cannot be safely
	// made to the config after the network upgrade has gone into effect.
	//
	// Configure is called on the first block where the stateful precompile should be enabled. This
	// provides the config the ability to set its initial state and should only modify the state within
	// its own address space.
	Configure(StateDB)
	// Contract returns a thread-safe singleton that can be used as the StatefulPrecompiledContract when
	// this config is enabled.
	Contract() StatefulPrecompiledContract
}

StatefulPrecompileConfig defines the interface for a stateful precompile to

type StatefulPrecompiledContract

type StatefulPrecompiledContract interface {
	// Run executes the precompiled contract. Assumes that [suppliedGas] exceeds the amount
	// returned by RequiredGas.
	Run(accessibleState PrecompileAccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error)
	// RequiredGas returns the amount of gas required to execute this precompile on [input].
	RequiredGas(input []byte) uint64
}

StatefulPrecompiledContract is the interface for executing a precompiled contract

var (
	// Singleton StatefulPrecompiledContract for W/R access to the contract deployer allow list.
	AllowListPrecompile StatefulPrecompiledContract = createAllowListPrecompile()
)