57b59b4e26
This completely reworks the way block index and processing works to use
headers-first semantics and support out of order processing of the
associated block data.
This will ultimately provide a wide variety of benefits as it means the
entire shape of the block tree can be determined from the headers alone
which in turn will allow much more informed decisions to be made,
provides better information regarding sync status and warning
conditions, and allows future work to add invalidation and
reconsideration of arbitrary blocks.
It must be noted that this is a major change to the way the block index
and block handling is done and is deeply integrated with the consensus
rules, so it will need a significant amount of testing and extremely
careful review.
Also of note is that there are a lot of assumptions made in the calling
code in regards to expected error attribution and the state the chain
has at the moment notifications are processed, so all of those semantics
have intentionally been retained, even though they might seem a bit out
of place now, in order to limit the amount of changes introduced at a
time and thus better ensures correctness.
For example, in the future it would probably make more sense to make the
notifications entirely asynchronous and for validation failures to be
reported via those asynchronous notifications. However, before that can
happen, all callers would first need to be updated to ensure they do not
rely on the chain being in the same state it was at the moment the
notification was generated.
In addition to all of the existing full block tests, this introduces
a comprehensive set of processing order tests which exercise all of the
new logic.
High level overview of the changes:
- Introduce tracking for whether a block is fully linked, meaning it
builds on a branch that has block data for all of its ancestors
- Add received order tracking to ensure miners are not able to gain an
advantage in terms of chain selection by only advertising a header
- Add several new pieces of information to the block index:
- Header with the most cumulative work that is not known to be invalid
- Header with the most cumulative work that is known to be invalid
- Map of best chain candidates to aid in efficient selection
- Map of unlinked children for more efficient linking
- Prunable cached chain tips to significantly reduce potential search
space during invalidation
- Introduce a compare function which determines which of two nodes
should be considered better for the purposes of best chain selection
- Add chain tip iteration capabilities with potential filtering
- Mark all descendants invalid due to known invalid ancestor when a
block is marked invalid
- Add ability to determine if a block can currently be validated
- Rework the chain reorganization func to work with an arbitrary target
- Modify the overall chain reorg func to reorg to the block with the
most cumulative work that is valid in the case it is not possible to
reorg to the target block
- Add a new MultiError type for keeping track of multiple errors in the
same call
- Add a new ErrNoBlockData error kind
- Update all cases that only require all of the ancestor block data to
be available to check for that condition instead of the more strict
condition of already being fully validated
- Introduce a new processing lock separate from the overall chain lock
- Add new method and ability to independently accept block headers
- Rework the block processing func to accept blocks out of order so long
as their header is already known valid
- Keep a cache of blocks that recently passed contextual validation
checks
- Cleanup and correct various comments to match reality
- Add comprehensive tests to exercise the new processing logic and best
header tracking (for both invalid and not known invalid)
78 lines
2.9 KiB
Go
78 lines
2.9 KiB
Go
// Copyright (c) 2014-2016 The btcsuite developers
|
|
// Copyright (c) 2015-2020 The Decred developers
|
|
// Use of this source code is governed by an ISC
|
|
// license that can be found in the LICENSE file.
|
|
|
|
package blockchain_test
|
|
|
|
import (
|
|
"context"
|
|
"fmt"
|
|
"os"
|
|
"path/filepath"
|
|
|
|
"github.com/decred/dcrd/blockchain/v4"
|
|
"github.com/decred/dcrd/chaincfg/v3"
|
|
"github.com/decred/dcrd/database/v2"
|
|
_ "github.com/decred/dcrd/database/v2/ffldb"
|
|
"github.com/decred/dcrd/dcrutil/v4"
|
|
)
|
|
|
|
// This example demonstrates how to create a new chain instance and use
|
|
// ProcessBlock to attempt to add a block to the chain. As the package
|
|
// overview documentation describes, this includes all of the Decred consensus
|
|
// rules. This example intentionally attempts to insert a duplicate genesis
|
|
// block to illustrate how an invalid block is handled.
|
|
func ExampleBlockChain_ProcessBlock() {
|
|
// Create a new database to store the accepted blocks into. Typically
|
|
// this would be opening an existing database and would not be deleting
|
|
// and creating a new database like this, but it is done here so this is
|
|
// a complete working example and does not leave temporary files laying
|
|
// around.
|
|
mainNetParams := chaincfg.MainNetParams()
|
|
dbPath := filepath.Join(os.TempDir(), "exampleprocessblock")
|
|
_ = os.RemoveAll(dbPath)
|
|
db, err := database.Create("ffldb", dbPath, mainNetParams.Net)
|
|
if err != nil {
|
|
fmt.Printf("Failed to create database: %v\n", err)
|
|
return
|
|
}
|
|
defer os.RemoveAll(dbPath)
|
|
defer db.Close()
|
|
|
|
// Create a new BlockChain instance using the underlying database for
|
|
// the main bitcoin network. This example does not demonstrate some
|
|
// of the other available configuration options such as specifying a
|
|
// notification callback and signature cache. Also, the caller would
|
|
// ordinarily keep a reference to the median time source and add time
|
|
// values obtained from other peers on the network so the local time is
|
|
// adjusted to be in agreement with other peers.
|
|
chain, err := blockchain.New(context.Background(),
|
|
&blockchain.Config{
|
|
DB: db,
|
|
ChainParams: mainNetParams,
|
|
TimeSource: blockchain.NewMedianTime(),
|
|
})
|
|
if err != nil {
|
|
fmt.Printf("Failed to create chain instance: %v\n", err)
|
|
return
|
|
}
|
|
|
|
// Process a block. For this example, intentionally cause an error by
|
|
// trying to process the genesis block which already exists.
|
|
genesisBlock := dcrutil.NewBlock(mainNetParams.GenesisBlock)
|
|
forkLen, err := chain.ProcessBlock(genesisBlock,
|
|
blockchain.BFNone)
|
|
if err != nil {
|
|
fmt.Printf("Failed to create chain instance: %v\n", err)
|
|
return
|
|
}
|
|
isMainChain := forkLen == 0
|
|
fmt.Printf("Block accepted. Is it on the main chain?: %v", isMainChain)
|
|
|
|
// This output is dependent on the genesis block, and needs to be
|
|
// updated if the mainnet genesis block is updated.
|
|
// Output:
|
|
// Failed to process block: already have block 267a53b5ee86c24a48ec37aee4f4e7c0c4004892b7259e695e9f5b321f1ab9d2
|
|
}
|