README
¶
Chain component
The Chain is a component which is fully responsible for building the blockchain. It judges the validity of incoming blocks, appends them to the database, and disseminates newly approved blocks both internally (through the event bus) and externally (over the gossip network). Additionally, it is aware of the node's state in the network at all times, and controls the execution of the consensus by responding to perceived state changes.
Structure
To the rest of the system, the Chain appears as quite a monolithic component. However, it is composed by a few different, more granular components, which all fulfill their own responsibilities.
Loader
The Loader is responsible for initializing the Chain with the correct initial data, as well as checking for data integrity on startup. It abstracts over the DB, and is implemented by the loader.
Verifier
The Verifier abstracts over block verification mechanisms, and uses the verifiers package under the hood, in an attempt to simplify the API (as checks are supposed to be kept atomic from a function perspective, but always are called together). It is implemented by the loader.
Synchronizer
The Synchronizer is a stand-alone component which is fully responsible for processing blocks that come in from the network. Through the Ledger interface, it can direct the Chain into the right decisions based on the perceived state of the node against the network. More information can be found in the synchronizer documentation.
Below follows a visual workflow of how the chain and synchronizer take decisions on incoming blocks, which should help clarify the control flow.
Loop
The Loop allows the Chain to take control of consensus execution, by allowing it to easily start and stop the work being done.
Proxy
The Proxy is used to contact the RUSK server. The Chain outsources certain operations to RUSK since the current codebase can not execute VM transactions, and this is needed for transaction validity checks and state transitions.
Documentation
¶
Index ¶
- Constants
- func ReconstructCommittee(p *user.Provisioners, b *block.Block) error
- type Chain
- func (c *Chain) AcceptBlock(blk block.Block) error
- func (c *Chain) AcceptSuccessiveBlock(blk block.Block) error
- func (c *Chain) CalculateSyncProgress() float64
- func (c *Chain) GetSyncProgress(_ context.Context, e *node.EmptyRequest) (*node.SyncProgressResponse, error)
- func (c *Chain) ProcessBlockFromNetwork(srcPeerID string, m message.Message) ([]bytes.Buffer, error)
- func (c *Chain) ProcessSyncTimerExpired(strPeerAddr string) error
- func (c *Chain) ProduceBlock() error
- func (c *Chain) RebuildChain(_ context.Context, e *node.EmptyRequest) (*node.GenericResponse, error)
- func (c *Chain) StopBlockProduction()
- func (c *Chain) TryNextConsecutiveBlockInSync(blk block.Block) error
- func (c *Chain) TryNextConsecutiveBlockOutSync(blk block.Block) error
- func (c *Chain) VerifyCandidateBlock(blk block.Block) error
- type DBLoader
- func (l *DBLoader) Append(blk *block.Block) error
- func (l *DBLoader) BlockAt(searchingHeight uint64) (block.Block, error)
- func (l *DBLoader) Clear() error
- func (l *DBLoader) Close(driver string) error
- func (l *DBLoader) Height() (uint64, error)
- func (l *DBLoader) LoadTip() (*block.Block, error)
- func (l *DBLoader) PerformSanityCheck(startAt, firstBlocksAmount, lastBlocksAmount uint64) error
- func (l *DBLoader) SanityCheckBlock(prevBlock block.Block, blk block.Block) error
- type Ledger
- type Loader
- type MockLoader
- func (m *MockLoader) Append(blk *block.Block) error
- func (m *MockLoader) BlockAt(index uint64) (block.Block, error)
- func (m *MockLoader) Clear() error
- func (m *MockLoader) Close(driver string) error
- func (m *MockLoader) Height() (uint64, error)
- func (m *MockLoader) LoadTip() (*block.Block, error)
- func (m *MockLoader) PerformSanityCheck(uint64, uint64, uint64) error
- type MockVerifier
- type Verifier
Constants ¶
const ( // SanityCheckHeight is the suggested amount of blocks to check when // calling Loader.PerformSanityCheck. SanityCheckHeight uint64 = 10 )
Variables ¶
This section is empty.
Functions ¶
func ReconstructCommittee ¶ added in v0.4.0
func ReconstructCommittee(p *user.Provisioners, b *block.Block) error
ReconstructCommittee will fill in the committee members that are present from genesis. nolint
Types ¶
type Chain ¶
type Chain struct {
// contains filtered or unexported fields
}
Chain represents the nodes blockchain. This struct will be aware of the current state of the node.
func New ¶
func New(ctx context.Context, db database.DB, eventBus *eventbus.EventBus, loader Loader, verifier Verifier, srv *grpc.Server, proxy transactions.Proxy, loop *loop.Consensus) (*Chain, error)
New returns a new chain object. It accepts the EventBus (for messages coming from (remote) consensus components.
func (*Chain) AcceptBlock ¶
AcceptBlock will accept a block if 1. We have not seen it before 2. All stateless and stateful checks are true Returns nil, if checks passed and block was successfully saved.
func (*Chain) AcceptSuccessiveBlock ¶ added in v0.4.0
AcceptSuccessiveBlock will accept a block which directly follows the chain tip, and advertises it to the node's peers.
func (*Chain) CalculateSyncProgress ¶ added in v0.4.0
CalculateSyncProgress of the node.
func (*Chain) GetSyncProgress ¶ added in v0.4.0
func (c *Chain) GetSyncProgress(_ context.Context, e *node.EmptyRequest) (*node.SyncProgressResponse, error)
GetSyncProgress returns how close the node is to being synced to the tip, as a percentage value.
func (*Chain) ProcessBlockFromNetwork ¶ added in v0.4.0
func (c *Chain) ProcessBlockFromNetwork(srcPeerID string, m message.Message) ([]bytes.Buffer, error)
ProcessBlockFromNetwork will handle blocks incoming from the network. It will allow the chain to enter sync mode if it detects that we are behind, which will cancel the running consensus loop and attempt to reach the new chain tip. Satisfies the peer.ProcessorFunc interface.
func (*Chain) ProcessSyncTimerExpired ¶ added in v0.4.0
ProcessSyncTimerExpired called by outsync timer when a peer does not provide GetData response. It implements transition back to inSync state. strPeerAddr is the address of the peer initiated the syncing but failed to deliver.
func (*Chain) ProduceBlock ¶ added in v0.4.0
ProduceBlock will start the consensus loop. It can be halted at any point by sending a signal through the `stopConsensus` channel (`StopBlockProduction` as exposed by the `Ledger` interface).
func (*Chain) RebuildChain ¶ added in v0.4.0
func (c *Chain) RebuildChain(_ context.Context, e *node.EmptyRequest) (*node.GenericResponse, error)
RebuildChain will delete all blocks except for the genesis block, to allow for a full re-sync. NOTE: This function no longer does anything, but is still here to conform to the ChainServer interface, for GRPC communications.
func (*Chain) StopBlockProduction ¶ added in v0.4.0
func (c *Chain) StopBlockProduction()
StopBlockProduction will send a non-blocking signal to `stopConsensusChan` to kill the consensus goroutine.
func (*Chain) TryNextConsecutiveBlockInSync ¶ added in v0.4.0
TryNextConsecutiveBlockInSync is the processing path for accepting a block from the network during in-sync state.
func (*Chain) TryNextConsecutiveBlockOutSync ¶ added in v0.4.0
TryNextConsecutiveBlockOutSync is the processing path for accepting a block from the network during out-of-sync state.
type DBLoader ¶ added in v0.3.0
type DBLoader struct {
// contains filtered or unexported fields
}
DBLoader performs database prefetching and sanityChecks at node startup.
func NewDBLoader ¶ added in v0.3.0
NewDBLoader returns a Loader which gets the Chain Tip from the DB.
func (*DBLoader) Height ¶ added in v0.3.0
Height returns the height of the blockchain stored in the DB.
func (*DBLoader) PerformSanityCheck ¶ added in v0.3.0
PerformSanityCheck checks the head and the tail of the blockchain to avoid inconsistencies and a faulty bootstrap.
func (*DBLoader) SanityCheckBlock ¶ added in v0.4.0
SanityCheckBlock will verify whether we have not seed the block before (duplicate), perform a check on the block header and verifies the coinbase transactions. It leaves the bulk of transaction verification to the executor Return nil if the sanity check passes.
type Ledger ¶ added in v0.4.0
type Ledger interface {
TryNextConsecutiveBlockInSync(block.Block) error
TryNextConsecutiveBlockOutSync(block.Block) error
ProduceBlock() error
StopBlockProduction()
ProcessSyncTimerExpired(strPeerAddr string) error
}
Ledger is the Chain interface used in tests.
type Loader ¶ added in v0.3.0
type Loader interface {
// LoadTip of the chain.
LoadTip() (*block.Block, error)
// Clear removes everything from the DB.
Clear() error
// Close the Loader and finalizes any pending connection.
Close(driver string) error
// Height returns the current height as stored in the loader.
Height() (uint64, error)
// BlockAt returns the block at a given height.
BlockAt(uint64) (block.Block, error)
// Append a block on the storage.
Append(*block.Block) error
}
Loader is an interface which abstracts away the storage used by the Chain to store the blockchain.
func NewMockLoader ¶ added in v0.3.0
func NewMockLoader() Loader
NewMockLoader creates a Mockup of the Loader interface.
type MockLoader ¶ added in v0.3.0
type MockLoader struct {
// contains filtered or unexported fields
}
MockLoader is the mock of the DB loader to help testing the chain.
func (*MockLoader) Append ¶ added in v0.3.0
func (m *MockLoader) Append(blk *block.Block) error
Append the block to the internal blockchain representation.
func (*MockLoader) BlockAt ¶ added in v0.3.0
func (m *MockLoader) BlockAt(index uint64) (block.Block, error)
BlockAt the block to the internal blockchain representation.
func (*MockLoader) Close ¶ added in v0.3.0
func (m *MockLoader) Close(driver string) error
Close the mock.
func (*MockLoader) Height ¶ added in v0.3.0
func (m *MockLoader) Height() (uint64, error)
Height returns the height currently known by the Loader.
func (*MockLoader) LoadTip ¶ added in v0.3.0
func (m *MockLoader) LoadTip() (*block.Block, error)
LoadTip of the chain.
func (*MockLoader) PerformSanityCheck ¶ added in v0.3.0
func (m *MockLoader) PerformSanityCheck(uint64, uint64, uint64) error
PerformSanityCheck on first N blocks and M last blocks.
type MockVerifier ¶ added in v0.3.0
type MockVerifier struct{}
MockVerifier is a mock for the chain.Verifier interface.
func (*MockVerifier) PerformSanityCheck ¶ added in v0.3.0
func (v *MockVerifier) PerformSanityCheck(uint64, uint64, uint64) error
PerformSanityCheck on first N blocks and M last blocks.
func (*MockVerifier) SanityCheckBlock ¶ added in v0.4.0
SanityCheckBlock will verify whether a block is valid according to the rules of the consensus.
type Verifier ¶ added in v0.3.0
type Verifier interface {
// PerformSanityCheck on first N blocks and M last blocks.
PerformSanityCheck(startAt uint64, firstBlocksAmount uint64, lastBlockAmount uint64) error
// SanityCheckBlock will verify whether a block is valid according to the rules of the consensus.
SanityCheckBlock(prevBlock block.Block, blk block.Block) error
}
Verifier performs checks on the blockchain and potentially new incoming block.
Source Files