precompile

package
v0.4.1-rc.0 Latest Latest
Warning

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

 Go to latest Published: Oct 20, 2022 License: GPL-3.0, LGPL-3.0 Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	SetAdminFuncKey      = "setAdmin"
	SetEnabledFuncKey    = "setEnabled"
	SetNoneFuncKey       = "setNone"
	ReadAllowListFuncKey = "readAllowList"

	ModifyAllowListGasCost = writeGasCostPerSlot
	ReadAllowListGasCost   = readGasCostPerSlot
)
View Source 
const (
	SetFeeConfigGasCost     = writeGasCostPerSlot * (numFeeConfigField + 1) // plus one for setting last changed at
	GetFeeConfigGasCost     = readGasCostPerSlot * numFeeConfigField
	GetLastChangedAtGasCost = readGasCostPerSlot
)
View Source 
const (
	MintGasCost = 30_000
)

Variables

View Source 
var (
	ContractDeployerAllowListAddress = common.HexToAddress("0x0200000000000000000000000000000000000000")
	ContractNativeMinterAddress      = common.HexToAddress("0x0200000000000000000000000000000000000001")
	TxAllowListAddress               = common.HexToAddress("0x0200000000000000000000000000000000000002")
	FeeConfigManagerAddress          = common.HexToAddress("0x0200000000000000000000000000000000000003")

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

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. The first stateful precompiles were added in coreth to support nativeAssetCall and nativeAssetBalance. New stateful precompiles originating in coreth will continue at this prefix, so we reserve this range in subnet-evm so that they can be migrated into subnet-evm without issue. These start at the address: 0x0100000000000000000000000000000000000000 and will increment by 1. Optional precompiles implemented in subnet-evm 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 Configure added in v0.2.8 

func Configure(chainConfig ChainConfig, blockContext BlockContext, precompileConfig StatefulPrecompileConfig, state StateDB)

Configure sets the nonce and code to non-empty values then calls Configure on [precompileConfig] to make the necessary state update to enable the StatefulPrecompile. Assumes that [precompileConfig] is non-nil.

func GetFeeConfigLastChangedAt added in v0.2.5 

func GetFeeConfigLastChangedAt(stateDB StateDB) *big.Int

func GetStoredFeeConfig added in v0.2.5 

func GetStoredFeeConfig(stateDB StateDB) commontype.FeeConfig

GetStoredFeeConfig returns fee config from contract storage in given state

func PackFeeConfig added in v0.2.5 

func PackFeeConfig(feeConfig commontype.FeeConfig) ([]byte, error)

PackFeeConfig packs [feeConfig] without the selector into the appropriate arguments for fee config operations.

func PackGetFeeConfigInput added in v0.2.5 

func PackGetFeeConfigInput() []byte

PackGetFeeConfigInput packs the getFeeConfig signature

func PackGetLastChangedAtInput added in v0.2.5 

func PackGetLastChangedAtInput() []byte

PackGetLastChangedAtInput packs the getFeeConfigLastChangedAt signature

func PackMintInput added in v0.2.0 

func PackMintInput(address common.Address, amount *big.Int) ([]byte, error)

PackMintInput packs [address] and [amount] into the appropriate arguments for minting operation. Assumes that [amount] can be represented by 32 bytes.

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 PackSetFeeConfig added in v0.2.5 

func PackSetFeeConfig(feeConfig commontype.FeeConfig) ([]byte, error)

PackSetFeeConfig packs [feeConfig] with the selector into the appropriate arguments for setting fee config operations.

func ReservedAddress added in v0.2.8 

func ReservedAddress(addr common.Address) bool

UsedAddress returns true if [addr] is in a reserved range for custom precompiles

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.

func SetContractNativeMinterStatus added in v0.2.0 

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

SetContractNativeMinterStatus sets the permissions of [address] to [role] for the minter list. assumes [role] has already been verified as valid.

func SetFeeConfigManagerStatus added in v0.2.5 

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

SetFeeConfigManagerStatus sets the permissions of [address] to [role] for the fee config manager list. assumes [role] has already been verified as valid.

func SetTxAllowListStatus added in v0.2.2 

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

SetTxAllowListStatus sets the permissions of [address] to [role] for the tx allow list. assumes [role] has already been verified as valid.

func StoreFeeConfig added in v0.2.5 

func StoreFeeConfig(stateDB StateDB, feeConfig commontype.FeeConfig, blockContext BlockContext) error

StoreFeeConfig stores given [feeConfig] and block number in the [blockContext] to the [stateDB]. A validation on [feeConfig] is done before storing.

func UnpackFeeConfigInput added in v0.2.5 

func UnpackFeeConfigInput(input []byte) (commontype.FeeConfig, error)

UnpackFeeConfigInput attempts to unpack [input] into the arguments to the fee config precompile assumes that [input] does not include selector (omits first 4 bytes in PackSetFeeConfigInput)

func UnpackMintInput added in v0.2.0 

func UnpackMintInput(input []byte) (common.Address, *big.Int, error)

UnpackMintInput attempts to unpack [input] into the arguments to the mint precompile assumes that [input] does not include selector (omits first 4 bytes in PackMintInput)

Types

type AddressRange added in v0.2.8 

type AddressRange struct {
	Start common.Address
	End   common.Address
}

AddressRange represents a continuous range of addresses

func (*AddressRange) Contains added in v0.2.8 

func (a *AddressRange) Contains(addr common.Address) bool

Contains returns true iff [addr] is contained within the (inclusive)

type AllowListConfig 

type AllowListConfig struct {
	AllowListAdmins  []common.Address `json:"adminAddresses"`
	EnabledAddresses []common.Address `json:"enabledAddresses"` // initial enabled addresses
}

AllowListConfig specifies 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) Equal added in v0.2.8 

func (c *AllowListConfig) Equal(other *AllowListConfig) bool

Equal returns true iff [other] has the same admins in the same order in its allow list.

func (*AllowListConfig) Verify added in v0.4.0 

func (c *AllowListConfig) Verify() error

Verify returns an error if there is an overlapping address between admin and enabled roles

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
	ErrCannotModifyAllowList = errors.New("non-admin cannot modify allow list")
)

func GetContractDeployerAllowListStatus 

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

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

func GetContractNativeMinterStatus added in v0.2.0 

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

GetContractNativeMinterStatus returns the role of [address] for the minter list.

func GetFeeConfigManagerStatus added in v0.2.5 

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

GetFeeConfigManagerStatus returns the role of [address] for the fee config manager list.

func GetTxAllowListStatus added in v0.2.2 

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

GetTxAllowListStatus 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) IsNoRole added in v0.2.0 

func (s AllowListRole) IsNoRole() bool

IsNoRole returns true if [s] indicates no specific role.

func (AllowListRole) Valid 

func (s AllowListRole) Valid() bool

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

type BlockContext added in v0.2.5 

type BlockContext interface {
	Number() *big.Int
	Timestamp() *big.Int
}

BlockContext defines an interface that provides information to a stateful precompile about the block that activates the upgrade. The precompile can access this information to initialize its state.

type ChainConfig added in v0.2.5 

type ChainConfig interface {
	// GetFeeConfig returns the original FeeConfig that was set in the genesis.
	GetFeeConfig() commontype.FeeConfig
}

ChainContext defines an interface that provides information to a stateful precompile about the chain configuration. The precompile can access this information to initialize its state.

type ContractDeployerAllowListConfig 

type ContractDeployerAllowListConfig struct {
	AllowListConfig
	UpgradeableConfig
}

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

func NewContractDeployerAllowListConfig added in v0.2.8 

func NewContractDeployerAllowListConfig(blockTimestamp *big.Int, admins []common.Address, enableds []common.Address) *ContractDeployerAllowListConfig

NewContractDeployerAllowListConfig returns a config for a network upgrade at [blockTimestamp] that enables ContractDeployerAllowList with [admins] and [enableds] as members of the allowlist.

func NewDisableContractDeployerAllowListConfig added in v0.2.8 

func NewDisableContractDeployerAllowListConfig(blockTimestamp *big.Int) *ContractDeployerAllowListConfig

NewDisableContractDeployerAllowListConfig returns config for a network upgrade at [blockTimestamp] that disables ContractDeployerAllowList.

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(_ ChainConfig, state StateDB, _ BlockContext)

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.

func (*ContractDeployerAllowListConfig) Equal added in v0.2.8 

func (c *ContractDeployerAllowListConfig) Equal(s StatefulPrecompileConfig) bool

Equal returns true if [s] is a *ContractDeployerAllowListConfig and it has been configured identical to [c].

type ContractNativeMinterConfig added in v0.2.0 

type ContractNativeMinterConfig struct {
	AllowListConfig
	UpgradeableConfig
	InitialMint map[common.Address]*math.HexOrDecimal256 `json:"initialMint,omitempty"` // initial mint config to be immediately minted
}

ContractNativeMinterConfig wraps AllowListConfig and uses it to implement the StatefulPrecompileConfig interface while adding in the ContractNativeMinter specific precompile address.

func NewContractNativeMinterConfig added in v0.2.8 

func NewContractNativeMinterConfig(blockTimestamp *big.Int, admins []common.Address, enableds []common.Address, initialMint map[common.Address]*math.HexOrDecimal256) *ContractNativeMinterConfig

NewContractNativeMinterConfig returns a config for a network upgrade at [blockTimestamp] that enables ContractNativeMinter with the given [admins] and [enableds] as members of the allowlist. Also mints balances according to [initialMint] when the upgrade activates.

func NewDisableContractNativeMinterConfig added in v0.2.8 

func NewDisableContractNativeMinterConfig(blockTimestamp *big.Int) *ContractNativeMinterConfig

NewDisableContractNativeMinterConfig returns config for a network upgrade at [blockTimestamp] that disables ContractNativeMinter.

func (*ContractNativeMinterConfig) Address added in v0.2.0 

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

Address returns the address of the native minter contract.

func (*ContractNativeMinterConfig) Configure added in v0.2.0 

func (c *ContractNativeMinterConfig) Configure(_ ChainConfig, state StateDB, _ BlockContext)

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

func (*ContractNativeMinterConfig) Contract added in v0.2.0 

func (c *ContractNativeMinterConfig) Contract() StatefulPrecompiledContract

Contract returns the singleton stateful precompiled contract to be used for the native minter.

func (*ContractNativeMinterConfig) Equal added in v0.2.8 

func (c *ContractNativeMinterConfig) Equal(s StatefulPrecompileConfig) bool

Equal returns true if [s] is a *ContractNativeMinterConfig and it has been configured identical to [c].

func (*ContractNativeMinterConfig) Verify added in v0.4.0 

func (c *ContractNativeMinterConfig) Verify() error

type FeeConfigManagerConfig added in v0.2.5 

type FeeConfigManagerConfig struct {
	AllowListConfig // Config for the fee config manager allow list
	UpgradeableConfig
	InitialFeeConfig *commontype.FeeConfig `json:"initialFeeConfig,omitempty"` // initial fee config to be immediately activated
}

FeeConfigManagerConfig wraps AllowListConfig and uses it to implement the StatefulPrecompileConfig interface while adding in the FeeConfigManager specific precompile address.

func NewDisableFeeManagerConfig added in v0.2.8 

func NewDisableFeeManagerConfig(blockTimestamp *big.Int) *FeeConfigManagerConfig

NewDisableFeeManagerConfig returns config for a network upgrade at [blockTimestamp] that disables FeeConfigManager.

func NewFeeManagerConfig added in v0.2.8 

func NewFeeManagerConfig(blockTimestamp *big.Int, admins []common.Address, enableds []common.Address, initialConfig *commontype.FeeConfig) *FeeConfigManagerConfig

NewFeeManagerConfig returns a config for a network upgrade at [blockTimestamp] that enables FeeConfigManager with the given [admins] and [enableds] as members of the allowlist with [initialConfig] as initial fee config if specified.

func (*FeeConfigManagerConfig) Address added in v0.2.5 

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

Address returns the address of the fee config manager contract.

func (*FeeConfigManagerConfig) Configure added in v0.2.5 

func (c *FeeConfigManagerConfig) Configure(chainConfig ChainConfig, state StateDB, blockContext BlockContext)

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

func (*FeeConfigManagerConfig) Contract added in v0.2.5 

func (c *FeeConfigManagerConfig) Contract() StatefulPrecompiledContract

Contract returns the singleton stateful precompiled contract to be used for the fee manager.

func (*FeeConfigManagerConfig) Equal added in v0.2.8 

func (c *FeeConfigManagerConfig) Equal(s StatefulPrecompileConfig) bool

Equal returns true if [s] is a *FeeConfigManagerConfig and it has been configured identical to [c].

func (*FeeConfigManagerConfig) Verify added in v0.4.0 

func (c *FeeConfigManagerConfig) Verify() error

type PrecompileAccessibleState 

type PrecompileAccessibleState interface {
	GetStateDB() StateDB
	GetBlockContext() BlockContext
}

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)

	SetCode(common.Address, []byte)

	SetNonce(common.Address, uint64)
	GetNonce(common.Address) uint64

	GetBalance(common.Address) *big.Int
	AddBalance(common.Address, *big.Int)
	SubBalance(common.Address, *big.Int)

	CreateAccount(common.Address)
	Exist(common.Address) bool

	Suicide(common.Address) bool
	Finalise(deleteEmptyObjects bool)
}

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
	// IsDisabled returns true if this network upgrade should disable the precompile.
	IsDisabled() bool
	// Equal returns true if the provided argument configures the same precompile with the same parameters.
	Equal(StatefulPrecompileConfig) bool
	// 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] and [BlockContext] 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(ChainConfig, StateDB, BlockContext)
	// Contract returns a thread-safe singleton that can be used as the StatefulPrecompiledContract when
	// this config is enabled.
	Contract() StatefulPrecompiledContract
	// Verify is called on startup and an error is treated as fatal. Configure can assume the Config has passed verification.
	Verify() error
}

StatefulPrecompileConfig defines the interface for a stateful precompile to

type StatefulPrecompiledContract 

type StatefulPrecompiledContract interface {
	// Run executes the precompiled contract.
	Run(accessibleState PrecompileAccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error)
}

StatefulPrecompiledContract is the interface for executing a precompiled contract 

var (

	// Singleton StatefulPrecompiledContract for minting native assets by permissioned callers.
	ContractNativeMinterPrecompile StatefulPrecompiledContract = createNativeMinterPrecompile(ContractNativeMinterAddress)

	ErrCannotMint = errors.New("non-enabled cannot mint")
)
var (

	// Singleton StatefulPrecompiledContract for setting fee configs by permissioned callers.
	FeeConfigManagerPrecompile StatefulPrecompiledContract = createFeeConfigManagerPrecompile(FeeConfigManagerAddress)

	ErrCannotChangeFee = errors.New("non-enabled cannot change fee config")
)
var (

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

	ErrSenderAddressNotAllowListed = errors.New("cannot issue transaction from non-allow listed address")
)
var (

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

type TxAllowListConfig added in v0.2.2 

type TxAllowListConfig struct {
	AllowListConfig
	UpgradeableConfig
}

TxAllowListConfig wraps AllowListConfig and uses it to implement the StatefulPrecompileConfig interface while adding in the TxAllowList specific precompile address.

func NewDisableTxAllowListConfig added in v0.2.8 

func NewDisableTxAllowListConfig(blockTimestamp *big.Int) *TxAllowListConfig

NewDisableTxAllowListConfig returns config for a network upgrade at [blockTimestamp] that disables TxAllowList.

func NewTxAllowListConfig added in v0.2.8 

func NewTxAllowListConfig(blockTimestamp *big.Int, admins []common.Address, enableds []common.Address) *TxAllowListConfig

NewTxAllowListConfig returns a config for a network upgrade at [blockTimestamp] that enables TxAllowList with the given [admins] and [enableds] as members of the allowlist.

func (*TxAllowListConfig) Address added in v0.2.2 

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

Address returns the address of the contract deployer allow list.

func (*TxAllowListConfig) Configure added in v0.2.2 

func (c *TxAllowListConfig) Configure(_ ChainConfig, state StateDB, _ BlockContext)

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

func (*TxAllowListConfig) Contract added in v0.2.2 

func (c *TxAllowListConfig) Contract() StatefulPrecompiledContract

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

func (*TxAllowListConfig) Equal added in v0.2.8 

func (c *TxAllowListConfig) Equal(s StatefulPrecompileConfig) bool

Equal returns true if [s] is a *TxAllowListConfig and it has been configured identical to [c].

type UpgradeableConfig added in v0.2.8 

type UpgradeableConfig struct {
	BlockTimestamp *big.Int `json:"blockTimestamp"`
	Disable        bool     `json:"disable,omitempty"`
}

UpgradeableConfig contains the timestamp for the upgrade along with a boolean [Disable]. If [Disable] is set, the upgrade deactivates the precompile and resets its storage.

func (*UpgradeableConfig) Equal added in v0.2.8 

func (c *UpgradeableConfig) Equal(other *UpgradeableConfig) bool

Equal returns true iff [other] has the same blockTimestamp and has the same on value for the Disable flag.

func (*UpgradeableConfig) IsDisabled added in v0.2.8 

func (c *UpgradeableConfig) IsDisabled() bool

IsDisabled returns true if the network upgrade deactivates the precompile.

func (*UpgradeableConfig) Timestamp added in v0.2.8 

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

Timestamp returns the timestamp this network upgrade goes into effect.

Source Files

View all Source files

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.