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 SetContractDeployerAllowListStatus(stateDB StateDB, address common.Address, role AllowListRole)
• type AllowListConfig
  • func (c *AllowListConfig) Configure(state StateDB, precompileAddr common.Address)
  • func (c *AllowListConfig) Timestamp() *big.Int
• type AllowListRole
  • func GetContractDeployerAllowListStatus(stateDB StateDB, address common.Address) AllowListRole
  • func (s AllowListRole) IsAdmin() bool
  • func (s AllowListRole) IsEnabled() bool
  • func (s AllowListRole) Valid() bool
• type ContractDeployerAllowListConfig
  • func (c *ContractDeployerAllowListConfig) Address() common.Address
  • func (c *ContractDeployerAllowListConfig) Configure(state StateDB)
  • func (c *ContractDeployerAllowListConfig) Contract() StatefulPrecompiledContract
• 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 (
	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")
	ErrExceedsGasAllowance     = errors.New("running allow list exceeds gas allowance")
)

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

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

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 SetContractDeployerAllowListStatus

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

SetContractDeployerAllowListStatus sets the permissions of [address] to [role] for the contract deployer allow list. 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) Configure

func (c *AllowListConfig) Configure(state StateDB, precompileAddr common.Address)

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

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

func GetContractDeployerAllowListStatus

func GetContractDeployerAllowListStatus(stateDB StateDB, address common.Address) AllowListRole

GetContractDeployerAllowListStatus returns the role of [address] for the contract deployer allow list.

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 ContractDeployerAllowListConfig

type ContractDeployerAllowListConfig struct {
	AllowListConfig
}

ContractDeployerAllowListConfig wraps AllowListConfig and uses it to implement the StatefulPrecompileConfig interface while adding in the contract deployer specific precompile address.

func (*ContractDeployerAllowListConfig) Address

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

Address returns the address of the contract deployer allow list.

func (*ContractDeployerAllowListConfig) Configure

func (c *ContractDeployerAllowListConfig) Configure(state StateDB)

Configure configures [state] with the desired admins based on [c].

func (*ContractDeployerAllowListConfig) Contract

func (c *ContractDeployerAllowListConfig) Contract() StatefulPrecompiledContract

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

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.
	ContractDeployerAllowListPrecompile StatefulPrecompiledContract = createAllowListPrecompile(ContractDeployerAllowListAddress)
)