seedhammer/dcrd
seedhammer/dcrd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

blockchain: Update README.md and doc.go.

Browse Source 
This modifies the README.md and doc.go files to match the latest code.
This commit is contained in:
Dave Collins 2020-12-23 15:44:36 -06:00
parent f3890ca2cc
commit 12e132e680
No known key found for this signature in database
GPG Key ID: B8904D9D9C93D1F2
2 changed files with 75 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
blockchain/README.md
View File

@ -6,23 +6,24 @@ blockchain
[![Doc](https://img.shields.io/badge/doc-reference-blue.svg)](https://pkg.go.dev/github.com/decred/dcrd/blockchain/v3)
Package blockchain implements Decred block handling and chain selection rules.
The test coverage is currently only around 60%, but will be increasing over
time. See `test_coverage.txt` for the gocov coverage report. Alternatively, if
you are running a POSIX OS, you can run the `cov_report.sh` script for a
real-time report. Package blockchain is licensed under the liberal ISC license.
There is an associated blog post about the release of this package
[here](https://blog.conformal.com/btcchain-the-bitcoin-chain-package-from-bctd/).
The Decred block handling and chain selection rules are an integral, and quite
likely the most important, part of Decred. At its core, Decred is a distributed
consensus of which blocks are valid and which ones will comprise the main block
chain (public ledger) that ultimately determines accepted transactions, so it is
extremely important that fully validating nodes agree on all rules.
This package has intentionally been designed so it can be used as a standalone
package for any projects needing to handle processing of blocks into the decred
block chain.
At a high level, this package provides support for inserting new blocks into the
block chain according to the aforementioned rules. It includes functionality
such as rejecting duplicate blocks, ensuring blocks and transactions follow all
rules, and best chain selection along with reorganization.
## Installation and Updating
Since this package does not deal with other Decred specifics such as network
communication or wallets, it provides a notification system which gives the
caller a high level of flexibility in how they want to react to certain events
such as newly connected main chain blocks which might result in wallet updates.
```bash
$ go get -u github.com/decred/dcrd/blockchain
```
A comprehensive suite of tests is provided to ensure proper functionality.
## Decred Chain Processing Overview
@ -55,6 +56,35 @@ is by no means exhaustive:
coins
- Insert the block into the block database
## Processing Order
This package supports headers-first semantics such that block data can be
processed out of order so long as the associated header is already known.
The headers themselves, however, must be processed in the correct order since
headers that do not properly connect are rejected. In other words, orphan
headers are not allowed.
The processing code always maintains the best chain as the branch tip that has
the most cumulative proof of work, so it is important to keep that in mind when
considering errors returned from processing blocks.
Notably, due to the ability to process blocks out of order, and the fact blocks
can only be fully validated once all of their ancestors have the block data
available, it is to be expected that no error is returned immediately for blocks
that are valid enough to make it to the point they require the remaining
ancestor block data to be fully validated even though they might ultimately end
up failing validation. Similarly, because the data for a block becoming
available makes any of its direct descendants that already have their data
available eligible for validation, an error being returned does not necessarily
mean the block being processed is the one that failed validation.
## Installation and Updating
```bash
$ go get -u github.com/decred/dcrd/blockchain
```
## Examples
* [ProcessBlock Example](https://pkg.go.dev/github.com/decred/dcrd/blockchain/v3#example-BlockChain.ProcessBlock)

39
blockchain/doc.go
View File

@ -7,7 +7,7 @@
Package blockchain implements Decred block handling and chain selection rules.
The Decred block handling and chain selection rules are an integral, and quite
likely the most important, part of decred. At its core, Decred is a distributed
likely the most important, part of Decred. At its core, Decred is a distributed
consensus of which blocks are valid and which ones will comprise the main block
chain (public ledger) that ultimately determines accepted transactions, so it is
extremely important that fully validating nodes agree on all rules.
@ -53,13 +53,38 @@ is by no means exhaustive:
coins
- Insert the block into the block database
Processing Order
This package supports headers-first semantics such that block data can be
processed out of order so long as the associated header is already known.
The headers themselves, however, must be processed in the correct order since
headers that do not properly connect are rejected. In other words, orphan
headers are not allowed.
The processing code always maintains the best chain as the branch tip that has
the most cumulative proof of work, so it is important to keep that in mind when
considering errors returned from processing blocks.
Notably, due to the ability to process blocks out of order, and the fact blocks
can only be fully validated once all of their ancestors have the block data
available, it is to be expected that no error is returned immediately for blocks
that are valid enough to make it to the point they require the remaining
ancestor block data to be fully validated even though they might ultimately end
up failing validation. Similarly, because the data for a block becoming
available makes any of its direct descendants that already have their data
available eligible for validation, an error being returned does not necessarily
mean the block being processed is the one that failed validation.
Errors
Errors returned by this package are either the raw errors provided by underlying
calls or of type blockchain.RuleError. This allows the caller to differentiate
between unexpected errors, such as database errors, versus errors due to rule
violations through type assertions. In addition, callers can programmatically
determine the specific rule violation by examining the Errorkind field of the
type asserted blockchain.RuleError.
Errors returned by this package have full support for the standard library
errors.Is and errors.As methods and are either the raw errors provided by
underlying calls or of type blockchain.RuleError, possibly wrapped in a
blockchain.MultiError. This allows the caller to differentiate between
unexpected errors, such as database errors, versus errors due to rule violations
through errors.As. In addition, callers can programmatically determine the
specific rule violation by making use of errors.Is with any of the wrapped error
kinds.
*/
package blockchain