consensus

Documentation

Index

• Constants
• Variables
• func MineTestingBlock(parent types.BlockID, timestamp types.Timestamp, ...) (b types.Block)
• type ConsensusSetSubscriber
• type ConsensusTester
  • func NewConsensusTester(t *testing.T, s *State) (ct *ConsensusTester)
  • func NewTestingEnvironment(name string, t *testing.T) (ct *ConsensusTester)
  • func (ct *ConsensusTester) AddSiacoinInputToTransaction(inputT types.Transaction, sci types.SiacoinInput) (t types.Transaction)
  • func (ct *ConsensusTester) ConsistencyChecks()
  • func (ct *ConsensusTester) CurrencyCheck()
  • func (ct *ConsensusTester) CurrentPathCheck()
  • func (ct *ConsensusTester) FileContractTransaction(start types.BlockHeight, expiration types.BlockHeight) (txn types.Transaction, file []byte)
  • func (ct *ConsensusTester) FindSpendableSiacoinInput() (sci types.SiacoinInput, value types.Currency)
  • func (ct *ConsensusTester) MineAndApplyValidBlock() (block types.Block)
  • func (ct *ConsensusTester) MineAndSubmitCurrentBlock(txns []types.Transaction)
  • func (ct *ConsensusTester) MineCurrentBlock(txns []types.Transaction) (b types.Block)
  • func (ct *ConsensusTester) Payouts(height types.BlockHeight, txns []types.Transaction) (payouts []types.SiacoinOutput)
  • func (ct *ConsensusTester) RewindABlock()
  • func (ct *ConsensusTester) RewindApplyCheck()
  • func (ct *ConsensusTester) SiacoinOutputTransaction() (txn types.Transaction)
• type State
  • func New(gateway modules.Gateway, saveDir string) (*State, error)
  • func (s *State) AcceptBlock(b types.Block) error
  • func (s *State) Block(bid types.BlockID) (b types.Block, exists bool)
  • func (s *State) BlockAtHeight(height types.BlockHeight) (b types.Block, exists bool)
  • func (s *State) BlockDiffs(bid types.BlockID) (scods []modules.SiacoinOutputDiff, fcds []modules.FileContractDiff, ...)
  • func (s *State) BlockOutputDiffs(id types.BlockID) (scods []modules.SiacoinOutputDiff, err error)
  • func (s *State) ChildTarget(bid types.BlockID) (target types.Target, exists bool)
  • func (s *State) Close() error
  • func (s *State) ConsensusSetNotify() <-chan struct{}
  • func (s *State) ConsensusSetSubscribe(subscriber ConsensusSetSubscriber)
  • func (s *State) CurrentBlock() types.Block
  • func (s *State) CurrentTarget() types.Target
  • func (s *State) EarliestChildTimestamp(bid types.BlockID) (timestamp types.Timestamp, exists bool)
  • func (s *State) EarliestTimestamp() types.Timestamp
  • func (s *State) Height() types.BlockHeight
  • func (s *State) HeightOfBlock(bid types.BlockID) (height types.BlockHeight, exists bool)
  • func (s *State) RelayBlock(conn modules.PeerConn) error
  • func (s *State) StateHash() crypto.Hash
  • func (s *State) StorageProofSegment(fcid types.FileContractID) (index uint64, err error)
  • func (s *State) Synchronize(peer modules.NetAddress) error
  • func (s *State) ValidStorageProofs(t types.Transaction) (err error)
• type StateInfo

Constants

const (
	MaxCatchUpBlocks = 50
)

Variables

var (
	ErrBadBlock        = errors.New("block is known to be invalid")
	ErrBlockKnown      = errors.New("block exists in block map")
	ErrEarlyTimestamp  = errors.New("block timestamp is too early")
	ErrFutureTimestamp = errors.New("block timestamp too far in future")
	ErrOrphan          = errors.New("block has no known parent")
	ErrLargeBlock      = errors.New("block is too large to be accepted")
	ErrMinerPayout     = errors.New("miner payout sum does not equal block subsidy")
	ErrMissedTarget    = errors.New("block does not meet target")
)

var (
	ErrMissingSiacoinOutput = errors.New("transaction spends a nonexisting siacoin output")
	ErrMissingFileContract  = errors.New("transaction terminates a nonexisting file contract")
	ErrMissingSiafundOutput = errors.New("transaction spends a nonexisting siafund output")
)

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.

Functions

func MineTestingBlock

func MineTestingBlock(parent types.BlockID, timestamp types.Timestamp, minerPayouts []types.SiacoinOutput, txns []types.Transaction, target types.Target) (b types.Block)

MineTestingBlock accepts a bunch of parameters for a block and then grinds blocks until a block with the appropriate target is found.

Types

type ConsensusSetSubscriber

type ConsensusSetSubscriber interface {
	// ReceiveConsensusSetUpdate sends a consensus update to a module through a
	// function call. Updates will always be sent in the correct order.
	// Usually, the function receiving the updates will also process the
	// changes. If the function blocks indefinitely, the state will still
	// function.
	ReceiveConsensusSetUpdate(revertedBlocks []types.Block, appliedBlocks []types.Block)
}

A ConsensusSetSubscriber is an object that receives updates to the consensus set every time there is a change in consensus.

type ConsensusTester

type ConsensusTester struct {
	*State
	*testing.T

	UnlockConditions types.UnlockConditions
	UnlockHash       types.UnlockHash
	SecretKey        crypto.SecretKey
	// contains filtered or unexported fields
}

A ConsensusTester holds a state and a testing object as well as some minimal and simplistic features for performing actions such as mining and building transactions.

func NewConsensusTester

func NewConsensusTester(t *testing.T, s *State) (ct *ConsensusTester)

NewConsensusTester returns an assistant that's ready to help with testing.

func NewTestingEnvironment

func NewTestingEnvironment(name string, t *testing.T) (ct *ConsensusTester)

NewTestingEnvironment creates a state and an assistant that wraps around the state, then mines enough blocks that the assistant has outputs ready to spend.

func (*ConsensusTester) AddSiacoinInputToTransaction

func (ct *ConsensusTester) AddSiacoinInputToTransaction(inputT types.Transaction, sci types.SiacoinInput) (t types.Transaction)

AddSiacoinInputToTransaction takes a transaction and adds an input that the assistant knows how to spend, returning the transaction and the value of the input that got added.

func (*ConsensusTester) ConsistencyChecks

func (ct *ConsensusTester) ConsistencyChecks()

consistencyChecks calls all of the consistency functions on each of the states.

func (*ConsensusTester) CurrencyCheck

func (ct *ConsensusTester) CurrencyCheck()

currencyCheck uses the height to determine the total amount of currency that should be in the system, and then tallys up the outputs to see if that is the case.

func (*ConsensusTester) CurrentPathCheck

func (ct *ConsensusTester) CurrentPathCheck()

CurrentPathCheck looks at every block listed in currentPath and verifies that every block from current to genesis matches the block listed in currentPath.

func (*ConsensusTester) FileContractTransaction

func (ct *ConsensusTester) FileContractTransaction(start types.BlockHeight, expiration types.BlockHeight) (txn types.Transaction, file []byte)

FileContractTransaction creates and funds a transaction that has a file contract, and returns that transaction.

func (*ConsensusTester) FindSpendableSiacoinInput

func (ct *ConsensusTester) FindSpendableSiacoinInput() (sci types.SiacoinInput, value types.Currency)

FindSpendableSiacoinInput returns a SiacoinInput that the ConsensusTester is able to spend, as well as the value of the input. There is no guarantee on the value, it could be anything.

func (*ConsensusTester) MineAndApplyValidBlock

func (ct *ConsensusTester) MineAndApplyValidBlock() (block types.Block)

MineAndApplyValidBlock mines a block and sets a handful of payouts to addresses that the assistant can spend, which will give the assistant a good volume of outputs to draw on for testing.

func (*ConsensusTester) MineAndSubmitCurrentBlock

func (ct *ConsensusTester) MineAndSubmitCurrentBlock(txns []types.Transaction)

MineAndSubmitCurrentBlock is a shortcut function that calls MineCurrentBlock and then submits it to the state.

func (*ConsensusTester) MineCurrentBlock

func (ct *ConsensusTester) MineCurrentBlock(txns []types.Transaction) (b types.Block)

MineCurrentBlock is a shortcut function that calls MineTestingBlock using variables that satisfy the current state.

func (*ConsensusTester) Payouts

func (ct *ConsensusTester) Payouts(height types.BlockHeight, txns []types.Transaction) (payouts []types.SiacoinOutput)

Payouts returns a block with 12 payouts worth 1e6 and a final payout that makes the total payout amount add up correctly. This produces a large set of outputs that can be used for testing.

func (*ConsensusTester) RewindABlock

func (ct *ConsensusTester) RewindABlock()

RewindABlock removes the most recent block from the consensus set.

func (*ConsensusTester) RewindApplyCheck

func (ct *ConsensusTester) RewindApplyCheck()

rewindApplyCheck grabs the state hash and then rewinds to the genesis block. Then the state moves forwards to the initial starting place and verifies that the state hash is the same.

func (*ConsensusTester) SiacoinOutputTransaction

func (ct *ConsensusTester) SiacoinOutputTransaction() (txn types.Transaction)

SiacoinOutputTransaction creates and funds a transaction that has a siacoin output, and returns that transaction.

type State

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

The State 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, saveDir string) (*State, error)

New returns a new State, containing at least the genesis block. If there is an existing block database present in saveDir, it will be loaded. Otherwise, a new database will be created.

func (*State) AcceptBlock

func (s *State) AcceptBlock(b types.Block) error

AcceptBlock will add a block to the state, forking the blockchain if it is on a fork that is heavier than the current fork. If the block is accepted, it will be relayed to connected peers.

func (*State) Block

func (s *State) Block(bid types.BlockID) (b types.Block, exists bool)

Block returns the block associated with the given id.

func (*State) BlockAtHeight

func (s *State) BlockAtHeight(height types.BlockHeight) (b types.Block, exists bool)

BlockAtHeight returns the block on the current path with the given height.

func (*State) BlockDiffs

func (s *State) BlockDiffs(bid types.BlockID) (scods []modules.SiacoinOutputDiff, fcds []modules.FileContractDiff, sfods []modules.SiafundOutputDiff, sfpd modules.SiafundPoolDiff, err error)

BlockDiffs returns the diffs created by the input block.

func (*State) BlockOutputDiffs

func (s *State) BlockOutputDiffs(id types.BlockID) (scods []modules.SiacoinOutputDiff, err error)

BlockOutputDiffs returns the SiacoinOutputDiffs for a given block.

func (*State) ChildTarget

func (s *State) ChildTarget(bid types.BlockID) (target types.Target, exists bool)

func (*State) Close

func (s *State) Close() error

Close safely closes the block database.

func (*State) ConsensusSetNotify

func (s *State) ConsensusSetNotify() <-chan struct{}

ConsensusSetNotify returns a channel that will be sent an empty struct every time the consensus set changes.

func (*State) ConsensusSetSubscribe

func (s *State) ConsensusSetSubscribe(subscriber ConsensusSetSubscriber)

ConsensusSetSubscribe accepts a new subscriber who will receive a call to ReceiveConsensusSetUpdate every time there is a change in the consensus set.

func (*State) CurrentBlock

func (s *State) CurrentBlock() types.Block

CurrentBlock returns the highest block on the tallest fork.

func (*State) CurrentTarget

func (s *State) CurrentTarget() types.Target

CurrentTarget returns the target of the next block that needs to be submitted to the state.

func (*State) EarliestChildTimestamp

func (s *State) EarliestChildTimestamp(bid types.BlockID) (timestamp types.Timestamp, exists bool)

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

func (*State) EarliestTimestamp

func (s *State) EarliestTimestamp() types.Timestamp

func (*State) Height

func (s *State) Height() types.BlockHeight

Height returns the height of the current blockchain (the longest fork).

func (*State) HeightOfBlock

func (s *State) HeightOfBlock(bid types.BlockID) (height types.BlockHeight, exists bool)

HeightOfBlock returns the height of the block with the given ID.

func (*State) RelayBlock

func (s *State) RelayBlock(conn modules.PeerConn) error

RelayBlock is an RPC that accepts a block from a peer.

func (*State) StateHash

func (s *State) StateHash() crypto.Hash

StateHash returns the markle root of the current state of consensus.

func (*State) StorageProofSegment

func (s *State) StorageProofSegment(fcid types.FileContractID) (index uint64, err error)

StorageProofSegment returns the segment to be used in the storage proof for a given file contract.

func (*State) Synchronize

func (s *State) Synchronize(peer modules.NetAddress) error

Synchronize synchronizes the local consensus set (i.e. the blockchain) with the network consensus set. The process is as follows: synchronize asks a peer for new blocks. The requester sends 32 block IDs, starting with the 12 most recent and then progressing exponentially backwards to the genesis block. The receiver uses these blocks to find the most recent block seen by both peers. From this starting height, it transmits blocks sequentially. The requester then integrates these blocks into its consensus set. Multiple such transmissions may be required to fully synchronize.

TODO: don't run two Synchronize threads at the same time

func (*State) ValidStorageProofs

func (s *State) ValidStorageProofs(t types.Transaction) (err error)

ValidStorageProofs checks that the storage proofs are valid in the context of the consensus set.

type StateInfo

type StateInfo struct {
	CurrentBlock types.BlockID
	Height       types.BlockHeight
	Target       types.Target
}

StateInfo contains basic information about the State.