github.com/onflow/flow-go@v0.35.7-crescendo-preview.23-atree-inlining/fvm/evm/types/handler.go (about)

     1  package types
     2  
     3  import (
     4  	"github.com/onflow/cadence/runtime/common"
     5  	gethCommon "github.com/onflow/go-ethereum/common"
     6  )
     7  
     8  // EVM is an account inside FVM with special access to the underlying infrastructure
     9  // which allows to run a virtual EVM-based blockchain inside FVM.
    10  //
    11  // There are two ways to interact with this environment:
    12  //
    13  // First, passing a signed transaction (EOA account) to the `EVM.run` Cadence function
    14  // creates a new block, updates the internal merkle tree, and emits a new root hash.
    15  //
    16  // The Second way is through a new form of account called cadence-owned-accounts (COAs),
    17  // which is represented and controlled through a resource, owned by a Flow account.
    18  // The owner of the COA resource can interact with the evm environment on behalf of the address stored on the resource.
    19  //
    20  // The evm environment shares the same native token as Flow, there are no new tokens minted.
    21  // Other ERC-20 fungible tokens can be bridged between COA resources and Flow accounts.
    22  
    23  // ContractHandler handles operations on the evm environment
    24  type ContractHandler interface {
    25  	// DeployCOA deploys a Cadence owned account and return the address
    26  	DeployCOA(uuid uint64) Address
    27  
    28  	// AccountByAddress returns an account by address
    29  	// if isAuthorized is set, it allows for functionality like `call`, `deploy`
    30  	// should only be set for the cadence owned accounts only.
    31  	AccountByAddress(address Address, isAuthorized bool) Account
    32  
    33  	// LastExecutedBlock returns information about the last executed block
    34  	LastExecutedBlock() *Block
    35  
    36  	// Run runs a transaction in the evm environment,
    37  	// collects the gas fees, and transfers the gas fees to the given coinbase account.
    38  	Run(tx []byte, coinbase Address) *ResultSummary
    39  
    40  	// DryRun simulates execution of the provided RLP-encoded and unsigned transaction.
    41  	// Because the transaction is unsigned the from address is required, since
    42  	// from address is normally derived from the transaction signature.
    43  	// The function should not have any persisted changes made to the state.
    44  	DryRun(tx []byte, from Address) *ResultSummary
    45  
    46  	// BatchRun runs transaction batch in the evm environment,
    47  	// collect all the gas fees and transfers the gas fees to the given coinbase account.
    48  	BatchRun(txs [][]byte, coinbase Address) []*ResultSummary
    49  
    50  	// FlowTokenAddress returns the address where FLOW token is deployed
    51  	FlowTokenAddress() common.Address
    52  
    53  	// EVMContractAddress returns the address where EVM is deployed
    54  	EVMContractAddress() common.Address
    55  
    56  	// GenerateResourceUUID generates a new UUID for a resource
    57  	GenerateResourceUUID() uint64
    58  }
    59  
    60  // AddressAllocator allocates addresses, used by the handler
    61  type AddressAllocator interface {
    62  	// AllocateAddress allocates an address to be used by a COA resource
    63  	AllocateCOAAddress(uuid uint64) Address
    64  
    65  	// COAFactoryAddress returns the address for the COA factory
    66  	COAFactoryAddress() Address
    67  
    68  	// NativeTokenBridgeAddress returns the address for the native token bridge
    69  	// used for deposit and withdraw calls
    70  	NativeTokenBridgeAddress() Address
    71  
    72  	// AllocateAddress allocates an address by index to be used by a precompile contract
    73  	AllocatePrecompileAddress(index uint64) Address
    74  }
    75  
    76  // BlockStore stores the chain of blocks
    77  type BlockStore interface {
    78  	// LatestBlock returns the latest appended block
    79  	LatestBlock() (*Block, error)
    80  
    81  	// BlockHash returns the hash of the block at the given height
    82  	BlockHash(height uint64) (gethCommon.Hash, error)
    83  
    84  	// BlockProposal returns the block proposal
    85  	BlockProposal() (*Block, error)
    86  
    87  	// CommitBlockProposal commits the block proposal and update the chain of blocks
    88  	CommitBlockProposal() error
    89  
    90  	// ResetBlockProposal resets the block proposal
    91  	ResetBlockProposal() error
    92  }