Documentation
¶
Index ¶
- Constants
- Variables
- func CalculateFunctionSelector(functionSignature string) []byte
- func CheckConfigure(parentTimestamp *big.Int, currentTimestamp *big.Int, ...)
- func PackMintInput(address common.Address, amount *big.Int) ([]byte, error)
- func PackModifyAllowList(address common.Address, role AllowListRole) ([]byte, error)
- func PackReadAllowList(address common.Address) []byte
- func SetContractDeployerAllowListStatus(stateDB StateDB, address common.Address, role AllowListRole)
- func SetContractNativeMinterStatus(stateDB StateDB, address common.Address, role AllowListRole)
- func SetTxAllowListStatus(stateDB StateDB, address common.Address, role AllowListRole)
- func UnpackMintInput(input []byte) (common.Address, *big.Int, error)
- type AllowListConfig
- type AllowListRole
- type ContractDeployerAllowListConfig
- type ContractNativeMinterConfig
- type PrecompileAccessibleState
- type RunStatefulPrecompileFunc
- type StateDB
- type StatefulPrecompileConfig
- type StatefulPrecompiledContract
- type TxAllowListConfig
Constants ¶
const ( ModifyAllowListGasCost = 20_000 ReadAllowListGasCost = 5_000 MintGasCost = 30_000 )
Gas costs for stateful precompiles
Variables ¶
var ( ContractDeployerAllowListAddress = common.HexToAddress("0x0200000000000000000000000000000000000000") ContractNativeMinterAddress = common.HexToAddress("0x0200000000000000000000000000000000000001") TxAllowListAddress = common.HexToAddress("0x0200000000000000000000000000000000000002") UsedAddresses = []common.Address{ ContractDeployerAllowListAddress, ContractNativeMinterAddress, TxAllowListAddress, } )
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 ¶
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 PackMintInput ¶ added in v0.2.0
PackMintInput packs [address] and [amount] into the appropriate arguments for minting operation.
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 ¶
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.
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 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.
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 ¶
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 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 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 ContractNativeMinterConfig ¶ added in v0.2.0
type ContractNativeMinterConfig struct {
AllowListConfig
}
ContractNativeMinterConfig wraps AllowListConfig and uses it to implement the StatefulPrecompileConfig interface while adding in the contract deployer specific precompile address.
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(state StateDB)
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.
type PrecompileAccessibleState ¶
type PrecompileAccessibleState interface {
GetStateDB() StateDB
}
PrecompileAccessibleState defines the interface exposed to stateful precompile contracts
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 }
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. 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 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
}
TxAllowListConfig wraps AllowListConfig and uses it to implement the StatefulPrecompileConfig interface while adding in the contract deployer specific precompile address.
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(state StateDB)
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.