Categorygithub.com/ava-labs/subnet-evmcore
package
0.6.10
Repository: https://github.com/ava-labs/subnet-evm.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
60
Dependents
29
Files
7.1k SLOC

# README

Core Package

The core package maintains the backend for the blockchain, transaction pool, and maintains the required indexes for blocks, transactions, logs, and transaction receipts.

Blockchain

The BlockChain struct handles the insertion of blocks into the maintained chain. It maintains a "canonical chain", which is essentially the preferred chain (the chain that ends with the block preferred by the AvalancheGo consensus engine).

When the consensus engine verifies blocks as they are ready to be issued into consensus, it calls Verify() on the ChainVM Block interface implemented here. This calls InsertBlockManual on the BlockChain struct implemented in this package, which is the first entrypoint of a block into the blockchain.

InsertBlockManual verifies the block, inserts it into the state manager to track the merkle trie for the block, and adds it to the canonical chain if it extends the currently preferred chain.

Subnet-EVM adds functions for Accept and Reject, which take care of marking a block as finalized and performing garbage collection where possible.

The consensus engine can also call SetPreference on a VM to tell the VM that a specific block is preferred by the consensus engine to be accepted. This triggers a call to reorg the blockchain and set the newly preferred block as the preferred chain.

Transaction Pool

The transaction pool maintains the set of transactions that need to be issued into a new block. The VM exposes APIs that allow clients to issue transactions into the transaction pool and also performs gossip across the network in order to send and receive pending transactions that need to be issued into a new block. The transaction pool asynchronously follows the preferred block of the BlockChain struct by subscribing to new head events and updating its state accordingly. When the transaction pool updates, it ensures that any transactions it contains are still valid to be issued on top of the new preferred block.

State Manager

The State Manager manages the TrieDB. The TrieDB tracks a merkle forest of all of the merkle tries for the last accepted block and processing blocks. When a block is processed, the state transition results in a new merkle trie added to the merkle forest. The State Manager can operate in either archival or pruning mode.

Archival Mode

In archival mode, every merkle trie is written to disk so that the node maintains a complete history of all the blocks that it has processed.

Pruning Mode

In pruning mode, the State Manager keeps a reference to merkle tries of processing blocks. When a block gets accepted, it stays in memory. When a block gets rejected, the state manager can dereference and clean up the no longer needed merkle trie. The State Manager does not immediately write the merkle trie to disk of a block when it gets accepted. Instead, at a regular interval (~4096 blocks) it writes the merkle trie to disk, so that it does not add the overhead of storing every accepted block's merkle trie to disk.

# Packages

Package bloombits implements bloom filtering on batches of data.
Package rawdb contains a collection of low level database accessors.
Package state provides a caching layer atop the Ethereum state trie.
No description provided by the author
Package types contains data types related to Ethereum consensus.
Package vm implements the Ethereum Virtual Machine.

# Functions

ApplyMessage computes the new state by applying the given message against the old state within the environment.
ApplyPrecompileActivations checks if any of the precompiles specified by the chain config are enabled or disabled by the block transition from [parentTimestamp] to the timestamp set in [blockContext].
ApplyTransaction attempts to apply a transaction to the given state database and uses the input parameters for its environment.
ApplyUpgrades checks if any of the precompile or state upgrades specified by the chain config are activated by the block transition from [parentTimestamp] to the timestamp set in [header].
CalcGasLimit computes the gas limit of the next block after parent.
CanTransfer checks whether there are enough funds in the address' account to make a transfer.
CheckPredicates verifies the predicates of [tx] and returns the result.
CheckTxIndices checks that the transaction indices are correctly stored in the database ([tail, head]).
DefaultCacheConfigWithScheme returns a deep copied default cache config with a provided trie node scheme.
GenerateChain creates a chain of n blocks.
GenerateChainWithGenesis is a wrapper of GenerateChain which will initialize genesis block to database first according to the provided genesis specification then generate chain on top.
GenesisBlockForTesting creates and writes a block in which addr has the given wei balance.
GetHashFn returns a GetHashFunc which retrieves header hashes by number.
IntrinsicGas computes the 'intrinsic gas' for a message with the given data.
NewBlockChain returns a fully initialised block chain using information available in the database.
NewBlockValidator returns a new block validator which is safe for re-use.
NewBloomIndexer returns a chain indexer that generates bloom bits data for the canonical chain for fast logs filtering.
NewBoundedBuffer creates a new [BoundedBuffer].
NewChainIndexer creates a new chain indexer to do background processing on chain segments of a given size after certain number of confirmations passed.
NewEVMBlockContext creates a new context for use in the EVM.
NewEVMBlockContextWithPredicateResults creates a new context for use in the EVM with an override for the predicate results that is not present in header.Extra.
NewEVMTxContext creates a new transaction context for a single transaction.
NewFIFOCache creates a new First-In-First-Out cache of size [limit].
NewHeaderChain creates a new HeaderChain structure.
NewStateProcessor initialises a new StateProcessor.
NewStateTransition initialises and returns a new state transition object.
No description provided by the author
NewTxSenderCacher creates a new transaction sender background cacher and starts as many processing goroutines as allowed by the GOMAXPROCS on construction.
ProcessBeaconBlockRoot applies the EIP-4788 system call to the beacon block root contract.
ReadBlockByHash reads the block with the given hash from the database.
The argument [genesis] must be specified and must contain a valid chain config.
Insert two different chains that result in the identical state root.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
Insert two different chains that result in the identical state root.
No description provided by the author
TestStatefulPrecompiles provides a testing framework to ensure that processing transactions interacting with the stateful precompiles work as expected.
TotalFees computes total consumed fees in wei.
TotalFees computes total consumed fees in ether.
TransactionToMessage converts a transaction into a Message.
Transfer subtracts amount from sender and adds amount to recipient using the given Db.

# Constants

BlockChainVersion ensures that an incompatible database forces a resync from scratch.

# Variables

DefaultCacheConfig are the default caching values if none are specified by the user (also used during testing).
ErrBlobFeeCapTooLow is returned if the transaction fee cap is less than the blob gas fee of the block.
ErrBlobTxCreate is returned if a blob transaction has no explicit to field.
ErrFeeCapTooLow is returned if the transaction fee cap is less than the base fee of the block.
ErrFeeCapVeryHigh is a sanity error to avoid extremely big numbers specified in the fee cap field.
ErrGasLimitReached is returned by the gas pool if the amount of gas required by a transaction is higher than what's left in the block.
ErrGasUintOverflow is returned when calculating gas usage.
ErrInsufficientFunds is returned if the total cost of executing a transaction is higher than the balance of the user's account.
ErrInsufficientFundsForTransfer is returned if the transaction sender doesn't have enough funds for transfer(topmost call only).
ErrIntrinsicGas is returned if the transaction is specified to use less gas than required to start the invocation.
ErrKnownBlock is returned when a block to import is already known locally.
ErrMaxInitCodeSizeExceeded is returned if creation transaction provides the init code bigger than init code size limit.
ErrMissingBlobHashes is returned if a blob transaction has no blob hashes.
No description provided by the author
ErrNoGenesis is returned when there is no Genesis Block.
ErrNonceMax is returned if the nonce of a transaction sender account has maximum allowed value and would become invalid if incremented.
ErrNonceTooHigh is returned if the nonce of a transaction is higher than the next one expected based on the local chain.
ErrNonceTooLow is returned if the nonce of a transaction is lower than the one present in the local chain.
No description provided by the author
ErrSenderNoEOA is returned if the sender of a transaction is a contract.
ErrTipAboveFeeCap is a sanity error to ensure no one is able to specify a transaction with a tip higher than the total fee cap.
ErrTipVeryHigh is a sanity error to avoid extremely big numbers specified in the tip field.
ErrTxTypeNotSupported is returned if a transaction is not supported in the current network configuration.

# Structs

No description provided by the author
No description provided by the author
BlockChain represents the canonical chain given a database with a genesis block.
BlockGen creates blocks for testing.
BlockValidator is responsible for validating block headers, uncles and processed state.
BloomIndexer implements a core.ChainIndexer, building up a rotated bloom bits index for the Ethereum header bloom filters, permitting blazing fast filtering.
BoundedBuffer keeps [size] entries of type [K] in a buffer and calls [callback] on any item that is overwritten.
No description provided by the author
CacheConfig contains the configuration values for the trie database and state snapshot these are resident in a blockchain.
No description provided by the author
No description provided by the author
ChainIndexer does a post-processing job for equally sized sections of the canonical chain (like BlooomBits and CHT structures).
No description provided by the author
No description provided by the author
ExecutionResult includes all output after executing given evm message no matter the execution itself is successful or not.
Genesis specifies the header fields, state of a genesis block.
GenesisMismatchError is raised when trying to overwrite an existing genesis block with an incompatible one.
HeaderChain implements the basic block header chain logic that is shared by core.BlockChain and light.LightChain.
A Message contains the data derived from a single transaction that is relevant to state processing.
NewTxPoolHeadEvent is posted when the pool receives a request to update its head to [Block].
NewTxPoolReorgEvent is posted when the pool head is updated.
NewTxsEvent is posted when a batch of transactions enter the transaction pool.
No description provided by the author
RemovedLogsEvent is posted when a reorg happens.
StateProcessor is a basic Processor, which takes care of transitioning state from one point to another.
StateTransition represents a state transition.
TxIndexProgress is the struct describing the progress for transaction indexing.
TxSenderCacher is a helper structure to concurrently ecrecover transaction senders from digital signatures on background threads.

# Interfaces

ChainContext supports retrieving headers and consensus parameters from the current blockchain to be used during transaction processing.
ChainIndexerBackend defines the methods needed to process chain segments in the background and write the segment results into the database.
ChainIndexerChain interface is used for connecting the indexer to a blockchain.
FIFOCache evicts the oldest element added to it after [limit] items are added.
Processor is an interface for processing blocks using a given initial state.
No description provided by the author
No description provided by the author
Validator is an interface which defines the standard for block validation.

# Type aliases

GasPool tracks the amount of gas available during execution of the transactions in a block.
Deprecated: use types.GenesisAccount instead.
Deprecated: use types.GenesisAlloc instead.