engine

Documentation

Index

• Variables
• type Engine
• type HashEngine
  • func (e *HashEngine) Difficulty() uint64
  • func (e *HashEngine) Finalize(ctx context.Context, chain chain.Reader, header *pb.Header, _ state.Reader, ...) (*pb.Block, error)
  • func (e *HashEngine) Prepare(chain chain.Reader, header *pb.Header) error
  • func (e *HashEngine) Reward() uint64
  • func (e *HashEngine) VerifyHeader(chain chain.Reader, header *pb.Header) error
• type PoW
  • func NewHashEngine(minerID peer.ID, difficulty, reward uint64) PoW
• type ProofOfWait

Variables

var (
	// ErrInvalidPreviousBlock is the error returned by VerifyHeader
	// when the previous block referenced can't be found.
	ErrInvalidPreviousBlock = errors.New("invalid header: previous block could not be found")

	// ErrInvalidBlockNumber is the error returned  by VerifyHeader
	// when the block number is invalid.
	ErrInvalidBlockNumber = errors.New("invalid header: block number is invalid")

	// ErrDifficultyNotMet is the error returned  by VerifyHeader
	// when the block's difficulty has not been met (for PoW).
	ErrDifficultyNotMet = errors.New("invalid header: difficulty not met")

	// ErrInvalidChain is the error returned when the input chain
	// returns invalid or unactionable results.
	ErrInvalidChain = errors.New("invalid chain")
)

Types

type Engine

type Engine interface {
	// VerifyHeader checks whether a header conforms to the consensus
	// rules of a given engine.
	VerifyHeader(chain chain.Reader, header *pb.Header) error

	// Prepare initializes the consensus fields of a block header according to the
	// rules of a particular engine. The changes are executed inline.
	Prepare(chain chain.Reader, header *pb.Header) error

	// Finalize assumes that transactions have already been validated and don't
	// violate state rules.
	// It assembles the transactions in a final block, potentially adding more
	// transactions than those from the input (for example, block rewards).
	// The block header might be updated (including a merkle root of the
	// transactions, or computing a valid nonce for a proof-of-work algorithm
	// for example).
	Finalize(ctx context.Context, chain chain.Reader, header *pb.Header, state state.Reader, txs []*pb.Transaction) (*pb.Block, error)
}

Engine is an algorithm agnostic consensus engine. It verifies that headers are valid and properly assembles blocks according to the consensus rules. It doesn't change any state, it's the responsibility of the caller to process the blocks assembled by the engine.

type HashEngine

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

HashEngine is an engine that uses hashes of the block as a proof-of-work. It tries to find a Nonce so that the hash of the whole block starts with a given number of 0.

func (*HashEngine) Difficulty

func (e *HashEngine) Difficulty() uint64

Difficulty returns the number of leading 0 we expect from the header hash.

func (*HashEngine) Finalize

func (e *HashEngine) Finalize(ctx context.Context, chain chain.Reader, header *pb.Header, _ state.Reader, txs []*pb.Transaction) (*pb.Block, error)

Finalize verifies the header, creates a reward for the miner, finds a nonce that meets the PoW difficulty and assembles the finalized block. You can abort Finalize by cancelling the context (if for example a new block arrives and you want to stop mining on an outdated block).

func (*HashEngine) Prepare

func (e *HashEngine) Prepare(chain chain.Reader, header *pb.Header) error

Prepare initializes the fields of the given header to respect consensus rules.

func (*HashEngine) Reward

func (e *HashEngine) Reward() uint64

Reward returns the reward a miner will receive when producing a new valid block.

func (*HashEngine) VerifyHeader

func (e *HashEngine) VerifyHeader(chain chain.Reader, header *pb.Header) error

VerifyHeader verifies that the header met the PoW difficulty and correctly chains to a previous block.

type PoW

type PoW interface {
	Engine

	// Difficulty returns the difficulty of the proof-of-work.
	// Blocks that don't conform to the current difficulty will be rejected.
	Difficulty() uint64

	// Reward returns the reward that the miner will receive in a reward
	// transaction when producing a new valid block.
	Reward() uint64
}

PoW is a consensus engine based on a proof-of-work algorithm.

func NewHashEngine

func NewHashEngine(minerID peer.ID, difficulty, reward uint64) PoW

NewHashEngine creates a PoW engine with an initial difficulty. The miner should specify its public key to receive block rewards.

type ProofOfWait

type ProofOfWait interface {
	Engine

	// Interval returns the minimum and maximum number of
	// milliseconds necessary to produce a block.
	Interval() (int, int)
}

ProofOfWait is a consensus engine based on the powerful proof-of-wait © algorithm. It is only meant to be used as a PoC and in tests.