dummy

README

Consensus

Disclaimer: the consensus package in coreth is a complete misnomer.

The consensus package in go-ethereum handles block validation and specifically handles validating the PoW portion of consensus - thus the name.

Since AvalancheGo handles consensus for Coreth, Coreth is just the VM, but we keep the consensus package in place to handle part of the block verification process.

Block Verification

The dummy consensus engine is responsible for performing verification on the header of a block. The engine verifies that all of the fields of the header are correct.

Dynamic Fees

As of Apricot Phase 3, the C-Chain includes a dynamic fee algorithm based off of (EIP-1559)[https://eips.ethereum.org/EIPS/eip-1559]. This introduces a field to the block type called BaseFee. The Base Fee sets a minimum gas price for any transaction to be included in the block. For example, a transaction with a gas price of 49 gwei, will be invalid to include in a block with a base fee of 50 gwei.

The dynamic fee algorithm aims to adjust the base fee to handle network congestion. Coreth sets a target utilization on the network, and the dynamic fee algorithm adjusts the base fee accordingly. If the network operates above the target utilization, the dynamic fee algorithm will increase the base fee to make utilizing the network more expensive and bring overall utilization down. If the network operates below the target utilization, the dynamic fee algorithm will decrease the base fee to make it cheaper to use the network.

• EIP-1559 is intended for Ethereum where a block is produced roughly every 10s
• C-Chain typically produces blocks every 2 seconds, but the dynamic fee algorithm needs to handle the case that the network quiesces and there are no blocks for a long period of time
• Since C-Chain produces blocks at a different cadence, it adapts EIP-1559 to sum the amount of gas consumed within a 10 second interval instead of using only the amount of gas consumed in the parent block

Consensus Engine Callbacks

The consensus engine is called while blocks are being both built and processed and Coreth adds callback functions into the dummy consensus engine to insert its own logic into these stages.

FinalizeAndAssemble

The FinalizeAndAssemble callback is used as the final step in building a block within the miner package. Coreth adds a callback function within FinalizeAndAssemble in order to process atomic transactions.

Finalize

Finalize is called as the final step in processing a block here. Finalize adds a callback function in order to process atomic transactions as well. Since either Finalize or FinalizeAndAssemble are called, but not both, when building or verifying/processing a block they need to perform the exact same processing/verification step to ensure that a block produced by the miner where FinalizeAndAssemble is called will be processed and verified in the same way when Finalize gets called.

Documentation

Index

• Variables
• func CalcBaseFee(config *params.ChainConfig, parent *types.Header, timestamp uint64) ([]byte, *big.Int, error)
• func EstimateNextBaseFee(config *params.ChainConfig, parent *types.Header, timestamp uint64) ([]byte, *big.Int, error)
• func MinRequiredTip(config *params.ChainConfig, header *types.Header) (*big.Int, error)
• type ConsensusCallbacks
• type DummyEngine
  • func NewCoinbaseFaker() *DummyEngine
  • func NewETHFaker() *DummyEngine
  • func NewFaker() *DummyEngine
  • func NewFakerWithCallbacks(cb ConsensusCallbacks) *DummyEngine
  • func NewFakerWithClock(cb ConsensusCallbacks, clock *mockable.Clock) *DummyEngine
  • func NewFakerWithMode(cb ConsensusCallbacks, mode Mode) *DummyEngine
  • func NewFullFaker() *DummyEngine
  • func (self *DummyEngine) Author(header *types.Header) (common.Address, error)
  • func (self *DummyEngine) CalcDifficulty(chain consensus.ChainHeaderReader, time uint64, parent *types.Header) *big.Int
  • func (self *DummyEngine) Close() error
  • func (self *DummyEngine) Finalize(chain consensus.ChainHeaderReader, block *types.Block, parent *types.Header, ...) error
  • func (self *DummyEngine) FinalizeAndAssemble(chain consensus.ChainHeaderReader, header *types.Header, parent *types.Header, ...) (*types.Block, error)
  • func (self *DummyEngine) Prepare(chain consensus.ChainHeaderReader, header *types.Header) error
  • func (self *DummyEngine) VerifyHeader(chain consensus.ChainHeaderReader, header *types.Header) error
  • func (self *DummyEngine) VerifyUncles(chain consensus.ChainReader, block *types.Block) error
• type Mode
• type OnExtraStateChangeType
• type OnFinalizeAndAssembleCallbackType

Variables

var (
	ApricotPhase3MinBaseFee     = big.NewInt(params.ApricotPhase3MinBaseFee)
	ApricotPhase3MaxBaseFee     = big.NewInt(params.ApricotPhase3MaxBaseFee)
	ApricotPhase4MinBaseFee     = big.NewInt(params.ApricotPhase4MinBaseFee)
	ApricotPhase4MaxBaseFee     = big.NewInt(params.ApricotPhase4MaxBaseFee)
	ApricotPhase3InitialBaseFee = big.NewInt(params.ApricotPhase3InitialBaseFee)
	EUpgradeMinBaseFee          = big.NewInt(params.EUpgradeMinBaseFee)

	ApricotPhase4BaseFeeChangeDenominator = new(big.Int).SetUint64(params.ApricotPhase4BaseFeeChangeDenominator)
	ApricotPhase5BaseFeeChangeDenominator = new(big.Int).SetUint64(params.ApricotPhase5BaseFeeChangeDenominator)

	ApricotPhase3BlockGasFee      uint64 = 1_000_000
	ApricotPhase4MinBlockGasCost         = new(big.Int).Set(common.Big0)
	ApricotPhase4MaxBlockGasCost         = big.NewInt(1_000_000)
	ApricotPhase4BlockGasCostStep        = big.NewInt(50_000)
	ApricotPhase4TargetBlockRate  uint64 = 2 // in seconds
	ApricotPhase5BlockGasCostStep        = big.NewInt(200_000)
)

Functions

func CalcBaseFee

func CalcBaseFee(config *params.ChainConfig, parent *types.Header, timestamp uint64) ([]byte, *big.Int, error)

CalcBaseFee takes the previous header and the timestamp of its child block and calculates the expected base fee as well as the encoding of the past pricing information for the child block. CalcBaseFee should only be called if [timestamp] >= [config.ApricotPhase3Timestamp]

func EstimateNextBaseFee

func EstimateNextBaseFee(config *params.ChainConfig, parent *types.Header, timestamp uint64) ([]byte, *big.Int, error)

EstimateNextBaseFee attempts to estimate the next base fee based on a block with [parent] being built at [timestamp]. If [timestamp] is less than the timestamp of [parent], then it uses the same timestamp as parent. Warning: This function should only be used in estimation and should not be used when calculating the canonical base fee for a subsequent block.

func MinRequiredTip

func MinRequiredTip(config *params.ChainConfig, header *types.Header) (*big.Int, error)

MinRequiredTip is the estimated minimum tip a transaction would have needed to pay to be included in a given block (assuming it paid a tip proportional to its gas usage). In reality, there is no minimum tip that is enforced by the consensus engine and high tip paying transactions can subsidize the inclusion of low tip paying transactions. The only correctness check performed is that the sum of all tips is >= the required block fee.

This function will return nil for all return values prior to Apricot Phase 4.

Types

type ConsensusCallbacks

type ConsensusCallbacks struct {
	OnFinalizeAndAssemble OnFinalizeAndAssembleCallbackType
	OnExtraStateChange    OnExtraStateChangeType
}

type DummyEngine

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

func NewCoinbaseFaker

func NewCoinbaseFaker() *DummyEngine

func NewETHFaker

func NewETHFaker() *DummyEngine

func NewFaker

func NewFaker() *DummyEngine

func NewFakerWithCallbacks

func NewFakerWithCallbacks(cb ConsensusCallbacks) *DummyEngine

func NewFakerWithClock

func NewFakerWithClock(cb ConsensusCallbacks, clock *mockable.Clock) *DummyEngine

func NewFakerWithMode

func NewFakerWithMode(cb ConsensusCallbacks, mode Mode) *DummyEngine

func NewFullFaker

func NewFullFaker() *DummyEngine

func (*DummyEngine) Author

func (self *DummyEngine) Author(header *types.Header) (common.Address, error)

func (*DummyEngine) CalcDifficulty

func (self *DummyEngine) CalcDifficulty(chain consensus.ChainHeaderReader, time uint64, parent *types.Header) *big.Int

func (*DummyEngine) Close

func (self *DummyEngine) Close() error

func (*DummyEngine) Finalize

func (self *DummyEngine) Finalize(chain consensus.ChainHeaderReader, block *types.Block, parent *types.Header, state *state.StateDB, receipts []*types.Receipt) error

func (*DummyEngine) FinalizeAndAssemble

func (self *DummyEngine) FinalizeAndAssemble(chain consensus.ChainHeaderReader, header *types.Header, parent *types.Header, state *state.StateDB, txs []*types.Transaction,
	uncles []*types.Header, receipts []*types.Receipt,
) (*types.Block, error)

func (*DummyEngine) Prepare

func (self *DummyEngine) Prepare(chain consensus.ChainHeaderReader, header *types.Header) error

func (*DummyEngine) VerifyHeader

func (self *DummyEngine) VerifyHeader(chain consensus.ChainHeaderReader, header *types.Header) error

func (*DummyEngine) VerifyUncles

func (self *DummyEngine) VerifyUncles(chain consensus.ChainReader, block *types.Block) error

type Mode

type Mode struct {
	ModeSkipHeader   bool
	ModeSkipBlockFee bool
	ModeSkipCoinbase bool
}

type OnExtraStateChangeType

type OnExtraStateChangeType = func(block *types.Block, statedb *state.StateDB) (blockFeeContribution *big.Int, extDataGasUsed *big.Int, err error)

type OnFinalizeAndAssembleCallbackType

type OnFinalizeAndAssembleCallbackType = func(header *types.Header, state *state.StateDB, txs []*types.Transaction) (extraData []byte, blockFeeContribution *big.Int, extDataGasUsed *big.Int, err error)