consensus

Documentation

Index

• Constants
• Variables
• type ConsensusSet
  • func New(gateway modules.Gateway, bootstrap bool, persistDir string, ...) (*ConsensusSet, error)
  • func (cs *ConsensusSet) AcceptBlock(b types.Block) error
  • func (cs *ConsensusSet) BlockAtHeight(height types.BlockHeight) (block types.Block, exists bool)
  • func (cs *ConsensusSet) BlockHeightOfBlock(block types.Block) (height types.BlockHeight, exists bool)
  • func (cs *ConsensusSet) CalculateStakeModifier(height types.BlockHeight, block types.Block, delay types.BlockHeight) *big.Int
  • func (cs *ConsensusSet) ChildTarget(id types.BlockID) (target types.Target, exists bool)
  • func (cs *ConsensusSet) Close() error
  • func (cs *ConsensusSet) ConsensusSetSubscribe(subscriber modules.ConsensusSetSubscriber, start modules.ConsensusChangeID) error
  • func (cs *ConsensusSet) CurrentBlock() (block types.Block)
  • func (cs *ConsensusSet) FindParentBlock(b types.Block, depth types.BlockHeight) (block types.Block, exists bool)
  • func (cs *ConsensusSet) Flush() error
  • func (cs *ConsensusSet) Height() (height types.BlockHeight)
  • func (cs *ConsensusSet) InCurrentPath(id types.BlockID) (inPath bool)
  • func (cs *ConsensusSet) MinimumValidChildTimestamp(id types.BlockID) (timestamp types.Timestamp, exists bool)
  • func (cs *ConsensusSet) Synced() bool
  • func (cs *ConsensusSet) TransactionAtID(id types.TransactionID) (types.Transaction, types.TransactionShortID, bool)
  • func (cs *ConsensusSet) TransactionAtShortID(shortID types.TransactionShortID) (types.Transaction, bool)
  • func (cs *ConsensusSet) TryTransactionSet(txns []types.Transaction) (modules.ConsensusChange, error)
  • func (cs *ConsensusSet) Unsubscribe(subscriber modules.ConsensusSetSubscriber)

Constants

const (
	// DatabaseFilename contains the filename of the database that will be used
	// when managing consensus.
	DatabaseFilename = modules.ConsensusDir + ".db"
)

Variables

var (
	// ChangeLog contains a list of atomic changes that have happened to the
	// consensus set so that subscribers can subscribe from the most recent
	// change they have seen.
	ChangeLog = []byte("ChangeLog")

	// ChangeLogTailID is a key that points to the id of the current changelog
	// tail.
	ChangeLogTailID = []byte("ChangeLogTailID")
)

var (

	// BlockHeight is a bucket that stores the current block height.
	//
	// Generally we would just look at BlockPath.Stats(), but there is an error
	// in boltdb that prevents the bucket stats from updating until a tx is
	// committed. Wasn't a problem until we started doing the entire block as
	// one tx.
	//
	// DEPRECATED - block.Stats() should be sufficient to determine the block
	// height, but currently stats are only computed after committing a
	// transaction, therefore cannot be assumed reliable.
	BlockHeight = []byte("BlockHeight")

	// BlockMap is a database bucket containing all of the processed blocks,
	// keyed by their id. This includes blocks that are not currently in the
	// consensus set, and blocks that may not have been fully validated yet.
	BlockMap = []byte("BlockMap")

	// BlockPath is a database bucket containing a mapping from the height of a
	// block to the id of the block at that height. BlockPath only includes
	// blocks in the current path.
	BlockPath = []byte("BlockPath")

	// Consistency is a database bucket with a flag indicating whether
	// inconsistencies within the database have been detected.
	Consistency = []byte("Consistency")

	// CoinOutputs is a database bucket that contains all of the unspent
	// coin outputs.
	CoinOutputs = []byte("CoinOutputs")

	// BlockStakeOutputs is a database bucket that contains all of the unspent
	// blockstake outputs.
	BlockStakeOutputs = []byte("BlockStakeOutputs")

	// TransactionIDMap is a database bucket that containsall of the present
	// transaction IDs linked to their short ID
	TransactionIDMap = []byte("TransactionIDMap")
)

var (
	// MaxCatchUpBlocks is the maxiumum number of blocks that can be given to
	// the consensus set in a single iteration during the initial blockchain
	// download.
	MaxCatchUpBlocks = func() types.BlockHeight {
		switch build.Release {
		case "dev":
			return 50
		case "standard":
			return 10
		case "testing":
			return 3
		default:
			panic("unrecognized build.Release")
		}
	}()
)

var SurpassThreshold = big.NewRat(20, 100)

SurpassThreshold is a percentage that dictates how much heavier a competing chain has to be before the node will switch to mining on that chain. This is not a consensus rule. This percentage is only applied to the most recent block, not the entire chain; see blockNode.heavierThan.

If no threshold were in place, it would be possible to manipulate a block's timestamp to produce a sufficiently heavier block.

Types

type ConsensusSet

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

The ConsensusSet is the object responsible for tracking the current status of the blockchain. Broadly speaking, it is responsible for maintaining consensus. It accepts blocks and constructs a blockchain, forking when necessary.

func New

func New(gateway modules.Gateway, bootstrap bool, persistDir string, bcInfo types.BlockchainInfo, chainCts types.ChainConstants) (*ConsensusSet, error)

New returns a new ConsensusSet, containing at least the genesis block. If there is an existing block database present in the persist directory, it will be loaded.

func (*ConsensusSet) AcceptBlock

func (cs *ConsensusSet) AcceptBlock(b types.Block) error

AcceptBlock will try to add a block to the consensus set. If the block does not extend the longest currently known chain, an error is returned but the block is still kept in memory. If the block extends a fork such that the fork becomes the longest currently known chain, the consensus set will reorganize itself to recognize the new longest fork. If a block is accepted without error, it will be relayed to all connected peers. This function should only be called for new blocks.

func (*ConsensusSet) BlockAtHeight

func (cs *ConsensusSet) BlockAtHeight(height types.BlockHeight) (block types.Block, exists bool)

BlockAtHeight returns the block at a given height.

func (*ConsensusSet) BlockHeightOfBlock

func (cs *ConsensusSet) BlockHeightOfBlock(block types.Block) (height types.BlockHeight, exists bool)

BlockHeightOfBlock returns the blockheight given a block.

func (*ConsensusSet) CalculateStakeModifier

func (cs *ConsensusSet) CalculateStakeModifier(height types.BlockHeight, block types.Block, delay types.BlockHeight) *big.Int

CalculateStakeModifier calculates the stakemodifier from the blockchain. Height is the height for which to calculate the stakemodifier. This is needed in case height - StakeModifierDelay goes

sub-genesis

Block is a block on the correct fork, so we can roll back from it. Delay is the amount of blocks we roll back from `block`. Block and delay must be chosen so that rolling back `delay` blocks from `block` reaches first block with which to calculate the stakemodifier.

func (*ConsensusSet) ChildTarget

func (cs *ConsensusSet) ChildTarget(id types.BlockID) (target types.Target, exists bool)

ChildTarget returns the target for the child of a block.

func (*ConsensusSet) Close

func (cs *ConsensusSet) Close() error

Close safely closes the block database.

func (*ConsensusSet) ConsensusSetSubscribe

func (cs *ConsensusSet) ConsensusSetSubscribe(subscriber modules.ConsensusSetSubscriber, start modules.ConsensusChangeID) error

ConsensusSetSubscribe adds a subscriber to the list of subscribers, and gives them every consensus change that has occurred since the change with the provided id.

As a special case, using an empty id as the start will have all the changes sent to the modules starting with the genesis block.

func (*ConsensusSet) CurrentBlock

func (cs *ConsensusSet) CurrentBlock() (block types.Block)

CurrentBlock returns the latest block in the heaviest known blockchain.

func (*ConsensusSet) FindParentBlock

func (cs *ConsensusSet) FindParentBlock(b types.Block, depth types.BlockHeight) (block types.Block, exists bool)

FindParentBlock finds the parent of a block at the given depth. While this function is expensive, it guarantees that the correct parent block is found, even if the block is not on the longest fork. If it is known up front that a lookup is done within the current fork, "BlockAtHeight" should be used.

func (*ConsensusSet) Flush

func (cs *ConsensusSet) Flush() error

Flush will block until the consensus set has finished all in-progress routines.

func (*ConsensusSet) Height

func (cs *ConsensusSet) Height() (height types.BlockHeight)

Height returns the height of the consensus set.

func (*ConsensusSet) InCurrentPath

func (cs *ConsensusSet) InCurrentPath(id types.BlockID) (inPath bool)

InCurrentPath returns true if the block presented is in the current path, false otherwise.

func (*ConsensusSet) MinimumValidChildTimestamp

func (cs *ConsensusSet) MinimumValidChildTimestamp(id types.BlockID) (timestamp types.Timestamp, exists bool)

MinimumValidChildTimestamp returns the earliest timestamp that the next block can have in order for it to be considered valid.

func (*ConsensusSet) Synced

func (cs *ConsensusSet) Synced() bool

Synced returns true if the consensus set is synced with the network.

func (*ConsensusSet) TransactionAtID

func (cs *ConsensusSet) TransactionAtID(id types.TransactionID) (types.Transaction, types.TransactionShortID, bool)

TransactionAtID allows you to fetch a transaction from a block within the blockchain, using a given transaction ID. If that transaction does not exist, false is returned

func (*ConsensusSet) TransactionAtShortID

func (cs *ConsensusSet) TransactionAtShortID(shortID types.TransactionShortID) (types.Transaction, bool)

TransactionAtShortID allows you fetch a transaction from a block within the blockchain, using a given shortID. If that transaction does not exist, false is returned.

func (*ConsensusSet) TryTransactionSet

func (cs *ConsensusSet) TryTransactionSet(txns []types.Transaction) (modules.ConsensusChange, error)

TryTransactionSet applies the input transactions to the consensus set to determine if they are valid. An error is returned IFF they are not a valid set in the current consensus set. The size of the transactions and the set is not checked. After the transactions have been validated, a consensus change is returned detailing the diffs that the transaction set would have.

func (*ConsensusSet) Unsubscribe

func (cs *ConsensusSet) Unsubscribe(subscriber modules.ConsensusSetSubscriber)

Unsubscribe removes a subscriber from the list of subscribers, allowing for garbage collection and rescanning. If the subscriber is not found in the subscriber database, no action is taken.