types

package
v0.33.36-update-commit Latest Latest
Warning

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

 Go to latest Published: Jun 18, 2024 License: AGPL-3.0 Imports: 16 Imported by: 10

Documentation

Index

Constants

View Source 
const (
	// tx type 255 is used for direct calls from bridged accounts
	DirectCallTxType = byte(255)

	UnknownCallSubType  = byte(0)
	DepositCallSubType  = byte(1)
	WithdrawCallSubType = byte(2)
	TransferCallSubType = byte(3)
	DeployCallSubType   = byte(4)
	ContractCallSubType = byte(5)

	TransferGasUsage = 21_000
)
View Source 
const (
	EventTypeBlockExecuted       flow.EventType = "evm.BlockExecuted"
	EventTypeTransactionExecuted flow.EventType = "evm.TransactionExecuted"
)
View Source 
const AddressLength = gethCommon.AddressLength

AddressLength holds the number of bytes used for each EVM address

Variables

View Source 
var (
	SmallestAcceptableBalanceValueInAttoFlow = new(big.Int).SetInt64(1e10)
	OneFlowInAttoFlow                        = new(big.Int).SetInt64(1e18)
)
View Source 
var (
	DefaultDirectCallBaseGasUsage = uint64(21_000)
	DefaultDirectCallGasPrice     = uint64(0)

	// anything block number above 0 works here
	BlockNumberForEVMRules = big.NewInt(1)
)
View Source 
var (
	// ErrAccountDoesNotExist is returned when evm account doesn't exist
	ErrAccountDoesNotExist = errors.New("account does not exist")

	// ErrInsufficientBalance is returned when evm account doesn't have enough balance
	ErrInsufficientBalance = errors.New("insufficient balance")

	// ErrInsufficientComputation is returned when not enough computation is
	// left in the context of flow transaction to execute the evm operation.
	ErrInsufficientComputation = errors.New("insufficient computation")

	// ErrUnAuthroizedMethodCall method call, usually emited when calls are called on EOA accounts
	ErrUnAuthroizedMethodCall = errors.New("unauthroized method call")

	// ErrInsufficientTotalSupply is returned when flow token
	// is withdraw request is there but not enough balance is on EVM vault
	// this should never happen but its a saftey measure to protect Flow against EVM issues.
	// TODO: we might consider this fatal
	ErrInsufficientTotalSupply = errors.New("insufficient total supply")

	// ErrBalanceConversion is returned conversion of balance has failed, usually
	// is returned when the balance presented in attoflow has values that could
	// be marginally lost on the conversion.
	ErrBalanceConversion = errors.New("balance converion error")

	// ErrNotImplemented is a fatal error when something is called that is not implemented
	ErrNotImplemented = NewFatalError(errors.New("a functionality is called that is not implemented"))
)
View Source 
var EmptyAddress = Address(gethCommon.Address{})

EmptyAddress is an empty evm address

View Source 
var GenesisBlock = &Block{
	ParentBlockHash: gethCommon.Hash{},
	Height:          uint64(0),
	ReceiptRoot:     gethTypes.EmptyRootHash,
}

GenesisBlock is the genesis block in the EVM environment

Functions

func IsAFatalError 

func IsAFatalError(err error) bool

IsAFatalError returns true if the error or underlying error is of fatal type.

func IsAInsufficientTotalSupplyError 

func IsAInsufficientTotalSupplyError(err error) bool

IsAInsufficientTotalSupplyError returns true if the error type is InsufficientTotalSupplyError

func IsAStateError 

func IsAStateError(err error) bool

IsAStateError returns true if the error or any underlying errors is of the type EVM validation error

func IsAUnAuthroizedMethodCallError 

func IsAUnAuthroizedMethodCallError(err error) bool

IsAUnAuthroizedMethodCallError returns true if the error type is UnAuthroizedMethodCallError

func IsEVMExecutionError 

func IsEVMExecutionError(err error) bool

IsEVMValidationError returns true if the error or any underlying errors is of the type EVM execution error

func IsEVMValidationError 

func IsEVMValidationError(err error) bool

IsEVMValidationError returns true if the error or any underlying errors is of the type EVM validation error

Types

type Account 

type Account interface {
	// Returns the address of this account
	Address() Address

	// Returns balance of this account
	Balance() Balance

	// Deposit deposits the token from the given vault into this account
	Deposit(*FLOWTokenVault)

	// Withdraw withdraws the balance from account and
	// return it as a FlowTokenVault
	// works only for bridged accounts
	Withdraw(Balance) *FLOWTokenVault

	// Transfer is a utility method on top of call for transfering tokens to another account
	Transfer(to Address, balance Balance)

	// Deploy deploys a contract to the environment
	// the new deployed contract would be at the returned address and
	// the contract data is not controlled by the bridge account
	// works only for bridged accounts
	Deploy(Code, GasLimit, Balance) Address

	// Call calls a smart contract function with the given data.
	// The gas usage is limited by the given gas limit,
	// and the Flow transaction's computation limit.
	// The fees are deducted from the bridged account
	// and are transferred to the target address.
	// if no data is provided it would behave as transfering tokens to the
	// target address
	// works only for bridged accounts
	Call(Address, Data, GasLimit, Balance) Data
}

Account is an EVM account, currently three types of accounts are supported on Flow EVM, externally owned accounts (EOAs), smart contract accounts and bridged accounts BridgedAccount is a new type of account in the environment, that instead of being managed by public key, it is managed by a resource owned by a Flow account.

In other words, the FVM account who owns the FOA resource can bridge native tokens to and from the account associated with the bridged account, deploy contracts to the environment, or call methods on contracts without the need to sign a transaction.

type Address 

type Address gethCommon.Address

Address is an EVM-compatible address

func NewAddress 

func NewAddress(addr gethCommon.Address) Address

NewAddress constructs a new Address

func NewAddressFromBytes 

func NewAddressFromBytes(inp []byte) Address

NewAddressFromBytes constructs a new address from bytes

func NewAddressFromString 

func NewAddressFromString(str string) Address

NewAddressFromString constructs a new address from an string

func (Address) Bytes 

func (fa Address) Bytes() []byte

Bytes returns a byte slice for the address

func (Address) ToCommon 

func (fa Address) ToCommon() gethCommon.Address

ToCommon returns the geth address

type AddressAllocator 

type AddressAllocator interface {
	// AllocateAddress allocates an address to be used by a bridged account resource
	AllocateAddress() (Address, error)
}

AddressAllocator allocates addresses, used by the handler

type Backend 

type Backend interface {
	environment.ValueStore
	environment.Meter
	environment.EventEmitter
}

Backend passes the FVM functionality needed inside the handler

type Balance 

type Balance cadence.UFix64

Balance represents the balance of an address in the evm environment, balances are kept in attoflow (1e10^-18 flow), the smallest denomination of FLOW token (similar to how Wei is used to store Eth) But on the FLOW Vaults, we use Cadence.UFix64 to store values in Flow. this could result in accidental conversion mistakes, the balance object here would do the conversions and does appropriate checks.

For example the smallest unit of Flow token that a FlowVault could store is 1e10^-8, so transfering smaller values (or values with smalls fractions) could result in loss in conversion. The balance object checks it to prevent invalid balance. This means that values smaller than 1e10^-8 flow could not be bridged between FVM and Flow EVM.

func DecodeBalance 

func DecodeBalance(encoded []byte) (Balance, error)

DecodeBalance decodes a balance from an encoded byte slice

func NewBalanceFromAttoFlow 

func NewBalanceFromAttoFlow(inp *big.Int) (Balance, error)

NewBalanceFromAttoFlow constructs a new balance from atto flow value

func (Balance) Add 

func (b Balance) Add(other Balance) Balance

Add adds the other balance from this balance

func (Balance) Encode 

func (b Balance) Encode() []byte

Encode encodes the balance into byte slice

func (Balance) Sub 

func (b Balance) Sub(other Balance) Balance

Sub subtract the other balance from this balance

func (Balance) ToAttoFlow 

func (b Balance) ToAttoFlow() *big.Int

ToAttoFlow converts the balance into AttoFlow

type BaseView 

type BaseView interface {
	ReadOnlyView

	// Creates a new account
	CreateAccount(
		addr gethCommon.Address,
		balance *big.Int,
		nonce uint64,
		code []byte,
		codeHash gethCommon.Hash,
	) error

	// UpdateAccount updates a account
	UpdateAccount(
		addr gethCommon.Address,
		balance *big.Int,
		nonce uint64,
		code []byte,
		codeHash gethCommon.Hash,
	) error

	// DeleteAccount deletes an account
	DeleteAccount(addr gethCommon.Address) error

	// UpdateSlot updates the value for the given slot in the main storage
	UpdateSlot(
		slot SlotAddress,
		value gethCommon.Hash,
	) error

	// Commit commits the changes
	Commit() error
}

BaseView is a low-level mutable view of the state baseview is usually updated at the commit calls to the higher level view

type Block 

type Block struct {
	// the hash of the parent block
	ParentBlockHash gethCommon.Hash

	// Height returns the height of this block
	Height uint64

	// holds the total amount of the native token deposited in the evm side.
	TotalSupply uint64

	// ReceiptRoot returns the root hash of the receipts emitted in this block
	ReceiptRoot gethCommon.Hash

	// transaction hashes
	TransactionHashes []gethCommon.Hash
}

Block represents a evm block. It captures block info such as height and state

func NewBlock 

func NewBlock(height, uuidIndex, totalSupply uint64,
	stateRoot, receiptRoot gethCommon.Hash,
	txHashes []gethCommon.Hash,
) *Block

NewBlock constructs a new block

func NewBlockFromBytes 

func NewBlockFromBytes(encoded []byte) (*Block, error)

NewBlockFromBytes constructs a new block from encoded data

func (*Block) AppendTxHash 

func (b *Block) AppendTxHash(txHash gethCommon.Hash)

AppendTxHash appends a transaction hash to the list of transaction hashes of the block

func (*Block) Hash 

func (b *Block) Hash() (gethCommon.Hash, error)

Hash returns the hash of the block

func (*Block) ToBytes 

func (b *Block) ToBytes() ([]byte, error)

ToBytes encodes the block into bytes

type BlockContext 

type BlockContext struct {
	BlockNumber            uint64
	DirectCallBaseGasUsage uint64
	DirectCallGasPrice     uint64
	GasFeeCollector        Address
}

BlockContext holds the context needed for the emulator operations

func NewDefaultBlockContext 

func NewDefaultBlockContext(BlockNumber uint64) BlockContext

NewDefaultBlockContext returns a new default block context

type BlockExecutedEventPayload 

type BlockExecutedEventPayload struct {
	Block *Block
}

func (*BlockExecutedEventPayload) CadenceEvent 

func (p *BlockExecutedEventPayload) CadenceEvent() (cadence.Event, error)

type BlockStore 

type BlockStore interface {
	// LatestBlock returns the latest appended block
	LatestBlock() (*Block, error)

	// BlockHash returns the hash of the block at the given height
	BlockHash(height int) (gethCommon.Hash, error)

	// BlockProposal returns the block proposal
	BlockProposal() (*Block, error)

	// CommitBlockProposal commits the block proposal and update the chain of blocks
	CommitBlockProposal() error

	// ResetBlockProposal resets the block proposal
	ResetBlockProposal() error
}

BlockStore stores the chain of blocks

type BlockView 

type BlockView interface {
	// executes a direct call
	DirectCall(call *DirectCall) (*Result, error)

	// RunTransaction executes an evm transaction
	RunTransaction(tx *gethTypes.Transaction) (*Result, error)
}

BlockView facilitates execution of a transaction or a direct evm call in the context of a block Errors returned by the methods are one of the followings: - Fatal error - Database error (non-fatal) - EVM validation error - EVM execution error

type Code 

type Code []byte

type ContractHandler 

type ContractHandler interface {
	// AllocateAddress allocates an address to be used by a bridged account resource
	AllocateAddress() Address

	// AccountByAddress returns an account by address
	// if isAuthorized is set, it allows for functionality like `call`, `deploy`
	// should only be set for bridged accounts only.
	AccountByAddress(address Address, isAuthorized bool) Account

	// LastExecutedBlock returns information about the last executed block
	LastExecutedBlock() *Block

	// Run runs a transaction in the evm environment,
	// collects the gas fees, and transfers the gas fees to the given coinbase account.
	Run(tx []byte, coinbase Address)

	FlowTokenAddress() common.Address
}

ContractHandler handles operations on the evm environment

type Data 

type Data []byte

func (Data) AsBigInt 

func (d Data) AsBigInt() *big.Int

AsBigInt process the data and return it as a big integer

type DirectCall 

type DirectCall struct {
	Type     byte
	SubType  byte
	From     Address
	To       Address
	Data     []byte
	Value    *big.Int
	GasLimit uint64
}

DirectCall captures all the data related to a direct call to evm direct calls are similar to transactions but they don't have signatures and don't need sequence number checks

func NewContractCall 

func NewContractCall(caller Address, to Address, data Data, gasLimit uint64, value *big.Int) *DirectCall

func NewDeployCall 

func NewDeployCall(caller Address, code Code, gasLimit uint64, value *big.Int) *DirectCall

func NewDepositCall 

func NewDepositCall(address Address, amount *big.Int) *DirectCall

func NewTransferCall 

func NewTransferCall(from Address, to Address, amount *big.Int) *DirectCall

func NewWithdrawCall 

func NewWithdrawCall(address Address, amount *big.Int) *DirectCall

func (*DirectCall) Encode 

func (dc *DirectCall) Encode() ([]byte, error)

Encode encodes the direct call it also adds the type as the very first byte, similar to how evm encodes types.

func (*DirectCall) Hash 

func (dc *DirectCall) Hash() (gethCommon.Hash, error)

Hash computes the hash of a direct call

func (*DirectCall) Message 

func (dc *DirectCall) Message() *gethCore.Message

Message constructs a core.Message from the direct call

type EVMExecutionError 

type EVMExecutionError struct {
	// contains filtered or unexported fields
}

EVMExecutionError is a non-fatal error, returned when execution of an evm transaction or direct call has failed.

func NewEVMExecutionError 

func NewEVMExecutionError(rootCause error) EVMExecutionError

NewEVMExecutionError returns a new EVMExecutionError

func (EVMExecutionError) Error 

func (err EVMExecutionError) Error() string

func (EVMExecutionError) Unwrap 

func (err EVMExecutionError) Unwrap() error

Unwrap unwraps the underlying evm error

type EVMValidationError 

type EVMValidationError struct {
	// contains filtered or unexported fields
}

EVMValidationError is a non-fatal error, returned when validation steps of an EVM transaction or direct call has failed.

func NewEVMValidationError 

func NewEVMValidationError(rootCause error) EVMValidationError

NewEVMValidationError returns a new EVMValidationError

func (EVMValidationError) Error 

func (err EVMValidationError) Error() string

func (EVMValidationError) Unwrap 

func (err EVMValidationError) Unwrap() error

Unwrap unwraps the underlying evm error

type Emulator 

type Emulator interface {
	// constructs a new block view
	NewReadOnlyBlockView(ctx BlockContext) (ReadOnlyBlockView, error)

	// constructs a new block
	NewBlockView(ctx BlockContext) (BlockView, error)
}

Emulator emulates an evm-compatible chain

type Event 

type Event struct {
	Etype   flow.EventType
	Payload EventPayload
}

func NewBlockExecutedEvent 

func NewBlockExecutedEvent(block *Block) *Event

func NewTransactionExecutedEvent 

func NewTransactionExecutedEvent(
	height uint64,
	txEncoded []byte,
	txHash gethCommon.Hash,
	result *Result,
) *Event

type EventPayload 

type EventPayload interface {
	// CadenceEvent creates a Cadence event type
	CadenceEvent() (cadence.Event, error)
}

type FLOWTokenVault 

type FLOWTokenVault struct {
	// contains filtered or unexported fields
}

FLOWTokenVault holds a balance of flow token

func NewFlowTokenVault 

func NewFlowTokenVault(balance Balance) *FLOWTokenVault

func (*FLOWTokenVault) Balance 

func (t *FLOWTokenVault) Balance() Balance

func (*FLOWTokenVault) Deposit 

func (t *FLOWTokenVault) Deposit(inp *FLOWTokenVault)

func (*FLOWTokenVault) Withdraw 

func (t *FLOWTokenVault) Withdraw(b Balance) *FLOWTokenVault

type FatalError 

type FatalError struct {
	// contains filtered or unexported fields
}

FatalError is used for any error that is not user related and something unusual has happend. Usually we stop the node when this happens given it might have a non-deterministic root.

func NewFatalError 

func NewFatalError(rootCause error) FatalError

NewFatalError returns a new FatalError

func (FatalError) Error 

func (err FatalError) Error() string

func (FatalError) Unwrap 

func (err FatalError) Unwrap() error

Unwrap unwraps the underlying fatal error

type GasLimit 

type GasLimit uint64

type HotView 

type HotView interface {
	ReadOnlyView

	// CreateAccount creates a new account
	CreateAccount(gethCommon.Address) error
	// SelfDestruct set the flag for destruction of the account after execution
	SelfDestruct(gethCommon.Address) error

	// SubBalance subtracts the amount from the balance the given address
	SubBalance(gethCommon.Address, *big.Int) error
	// AddBalance adds the amount to the balance of the given address
	AddBalance(gethCommon.Address, *big.Int) error
	// SetNonce sets the nonce for the given address
	SetNonce(gethCommon.Address, uint64) error
	// SetCode sets the code for the given address
	SetCode(gethCommon.Address, []byte) error

	// SetState sets a value for the given slot in the main storage
	SetState(SlotAddress, gethCommon.Hash) error
	// SetTransientState sets a value for the given slot in the transient storage
	SetTransientState(SlotAddress, gethCommon.Hash)

	// AddRefund adds the amount to the total (gas) refund
	AddRefund(uint64) error
	// SubRefund subtracts the amount from the total (gas) refund
	SubRefund(uint64) error

	// AddAddressToAccessList adds an address to the per-transaction access list
	AddAddressToAccessList(addr gethCommon.Address) (addressAdded bool)
	// AddSlotToAccessList adds a slot to the per-transaction access list
	AddSlotToAccessList(SlotAddress) (addressAdded, slotAdded bool)

	// AddLog append a log to the log collection
	AddLog(*gethTypes.Log)
	// AddPreimage adds a preimage to the list of preimages (input -> hash mapping)
	AddPreimage(gethCommon.Hash, []byte)
}

HotView captures a high-level mutable view of the state

type ReadOnlyBlockView 

type ReadOnlyBlockView interface {
	// BalanceOf returns the balance of this address
	BalanceOf(address Address) (*big.Int, error)
	// NonceOf returns the nonce of this address
	NonceOf(address Address) (uint64, error)
	// CodeOf returns the code for this address (if smart contract is deployed at this address)
	CodeOf(address Address) (Code, error)
}

ReadOnlyBlockView provides a read only view of a block

type ReadOnlyView 

type ReadOnlyView interface {
	// Exist returns true if the address exist in the state
	Exist(gethCommon.Address) (bool, error)
	// IsCreated returns true if address has been created in this tx
	IsCreated(gethCommon.Address) bool
	// HasSelfDestructed returns true if an address has self destructed
	// it also returns the balance of address before selfdestruction call
	HasSelfDestructed(gethCommon.Address) (bool, *big.Int)
	// GetBalance returns the balance of an address
	GetBalance(gethCommon.Address) (*big.Int, error)
	// GetNonce returns the nonce of an address
	GetNonce(gethCommon.Address) (uint64, error)
	// GetCode returns the code of an address
	GetCode(gethCommon.Address) ([]byte, error)
	// GetCodeHash returns the code hash of an address
	GetCodeHash(gethCommon.Address) (gethCommon.Hash, error)
	// GetCodeSize returns the code size of an address
	GetCodeSize(gethCommon.Address) (int, error)
	// GetState returns values for an slot in the main storage
	GetState(SlotAddress) (gethCommon.Hash, error)
	// GetTransientState returns values for an slot transient storage
	GetTransientState(SlotAddress) gethCommon.Hash
	// GetRefund returns the total amount of (gas) refund
	GetRefund() uint64
	// AddressInAccessList checks if an address is in the access list
	AddressInAccessList(gethCommon.Address) bool
	// SlotInAccessList checks if a slot is in the access list
	SlotInAccessList(SlotAddress) (addressOk bool, slotOk bool)
}

ReadOnlyView provides a readonly view of the state

type Result 

type Result struct {
	// a boolean that is set to false if the execution has failed (non-fatal)
	Failed bool
	// type of transaction defined by the evm package
	// see DirectCallTxType as extra type we added type for direct calls.
	TxType uint8
	// total gas consumed during an opeartion
	GasConsumed uint64
	// the address where the contract is deployed (if any)
	DeployedContractAddress Address
	// returned value from a function call
	ReturnedValue []byte
	// EVM logs (events that are emited by evm)
	Logs []*gethTypes.Log
}

Result captures the result of an interaction to the emulator it could be the out put of a direct call or output of running an evm transaction. Its more comprehensive than typical evm receipt, usually the receipt generation requires some extra calculation (e.g. Deployed contract address) but we take a different apporach here and include more data so that it requires less work for anyone who tracks and consume results.

func (*Result) Receipt 

func (res *Result) Receipt() *gethTypes.ReceiptForStorage

Receipt constructs an EVM-style receipt can be used by json-rpc and other integration to be returned.

type SlotAddress 

type SlotAddress struct {
	Address gethCommon.Address
	Key     gethCommon.Hash
}

SlotAddress captures an address to a storage slot

type StateDB 

type StateDB interface {
	gethVM.StateDB

	// Commit commits the changes
	Commit() error

	// Logs collects and prepares logs
	Logs(
		blockHash gethCommon.Hash,
		blockNumber uint64,
		txHash gethCommon.Hash,
		txIndex uint,
	) []*gethTypes.Log

	// returns a map of preimages
	Preimages() map[gethCommon.Hash][]byte
}

StateDB acts as the main interface to the EVM runtime

type StateError 

type StateError struct {
	// contains filtered or unexported fields
}

StateError is a non-fatal error, returned when a state operation has failed (e.g. reaching storage interaction limit)

func NewStateError 

func NewStateError(rootCause error) StateError

NewStateError returns a new StateError

func (StateError) Error 

func (err StateError) Error() string

func (StateError) Unwrap 

func (err StateError) Unwrap() error

Unwrap unwraps the underlying evm error

type TransactionExecutedPayload 

type TransactionExecutedPayload struct {
	BlockHeight uint64
	TxEncoded   []byte
	TxHash      gethCommon.Hash
	Result      *Result
}

we might break this event into two (tx included /tx executed) if size becomes an issue

func (*TransactionExecutedPayload) CadenceEvent 

func (p *TransactionExecutedPayload) CadenceEvent() (cadence.Event, error)

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.