candidate

README

Candidate Generator

Abstract

For more information on block generation, please refer to the generation package readme.

Values

Candidate (Block)

Field	Type
Version	uint8
Height	uint64
Timestamp	int64
Previous block hash	uint256
Block seed	BLS Signature
Merkle root	[]byte (32 bytes)
Certificate	Certificate*
Block hash	[]byte (32 bytes)
Transactions	[]Transaction* (variable size)

* For schemas of these items, please refer to the dusk-wallet repo.

Architecture

The candidate generator component is triggered by the score generator, through the ScoreEvent message. After receiving this message, the candidate generator will start constructing a candidate block. First off, it requests all verified transactions from the mempool. It prepends a coinbase transaction to this set, which rewards him with the agreed-upon reward amount. It then constructs the block header, and calculates the block merkle root, and the hash. Finally, it wraps the ScoreEvent into a Score message, and the newly created block into a Candidate message, before propagating both of these messages to the rest of the network.

Documentation

Index

• Constants
• func ConstructCoinbaseTx(rewardReceiver *key.PublicKey, proof []byte, score []byte) (*transactions.Coinbase, error)
• func GenerateGenesisBlock(generatorPubKey *key.PublicKey) (string, error)
• type Factory
  • func NewFactory(broker eventbus.Broker, rpcBus *rpcbus.RPCBus, walletPubKey *key.PublicKey) *Factory
  • func (f *Factory) Instantiate() consensus.Component
• type Generator
  • func NewComponent(publisher eventbus.Publisher, genPubKey *key.PublicKey, rpcBus *rpcbus.RPCBus) *Generator
  • func (bg *Generator) Collect(e consensus.Event) error
  • func (bg *Generator) ConstructBlockTxs(proof, score []byte) ([]transactions.Transaction, error)
  • func (bg *Generator) Finalize()
  • func (bg *Generator) Generate(sev score.Event) (*block.Block, error)
  • func (bg *Generator) GenerateBlock(round uint64, seed, proof, score, prevBlockHash []byte) (*block.Block, error)
  • func (bg *Generator) ID() uint32
  • func (bg *Generator) Initialize(eventPlayer consensus.EventPlayer, signer consensus.Signer, ...) []consensus.TopicListener
• type Helper
  • func NewHelper(t *testing.T, eb *eventbus.EventBus, rpcBus *rpcbus.RPCBus, ...) *Helper
  • func (h *Helper) Initialize(ru consensus.RoundUpdate)
  • func (h *Helper) ProvideTransactions(t *testing.T)
  • func (h *Helper) TriggerBlockGeneration()

Constants

const MaxTxSetSize = 150000

TBD along with block size and processing.MaxFrameSize

Functions

func ConstructCoinbaseTx

func ConstructCoinbaseTx(rewardReceiver *key.PublicKey, proof []byte, score []byte) (*transactions.Coinbase, error)

ConstructCoinbaseTx forges the transaction to reward the block generator.

func GenerateGenesisBlock

func GenerateGenesisBlock(generatorPubKey *key.PublicKey) (string, error)

GenerateGenesisBlock is a developer utility for regenerating the genesis block as they would be different per network type. Once a genesis block is approved, its hex blob should be copied into config.TestNetGenesisBlob

Types

type Factory

type Factory struct {
	Bus  eventbus.Broker
	RBus *rpcbus.RPCBus
	// contains filtered or unexported fields
}

Factory creates a candidate.Generator.

func NewFactory

func NewFactory(broker eventbus.Broker, rpcBus *rpcbus.RPCBus, walletPubKey *key.PublicKey) *Factory

NewFactory instantiates a Factory.

func (*Factory) Instantiate

func (f *Factory) Instantiate() consensus.Component

Instantiate a candidate Generator. Implements consensus.ComponentFactory.

type Generator

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

Generator is responsible for generating candidate blocks, and propagating them alongside received Scores. It is triggered by the ScoreEvent, sent by the score generator.

func NewComponent

func NewComponent(publisher eventbus.Publisher, genPubKey *key.PublicKey, rpcBus *rpcbus.RPCBus) *Generator

NewComponent returns an uninitialized candidate generator.

func (*Generator) Collect

func (bg *Generator) Collect(e consensus.Event) error

Collect a ScoreEvent, which triggers generation of a candidate block. The Generator will propagate both the Score and Candidate messages at the end of this function call.

func (*Generator) ConstructBlockTxs

func (bg *Generator) ConstructBlockTxs(proof, score []byte) ([]transactions.Transaction, error)

ConstructBlockTxs will fetch all valid transactions from the mempool, prepend a coinbase transaction, and return them all.

func (*Generator) Finalize

func (bg *Generator) Finalize()

Finalize implements consensus.Component

func (*Generator) Generate

func (bg *Generator) Generate(sev score.Event) (*block.Block, error)

func (*Generator) GenerateBlock

func (bg *Generator) GenerateBlock(round uint64, seed, proof, score, prevBlockHash []byte) (*block.Block, error)

GenerateBlock generates a candidate block, by constructing the header and filling it with transactions from the mempool.

func (*Generator) ID

func (bg *Generator) ID() uint32

ID returns the listener ID of the Generator. Implements consensus.Component.

func (*Generator) Initialize

func (bg *Generator) Initialize(eventPlayer consensus.EventPlayer, signer consensus.Signer, ru consensus.RoundUpdate) []consensus.TopicListener

Initialize the Generator, by populating the fields needed to generate candidate blocks, and returns a Listener for ScoreEvents. Implements consensus.Component.

type Helper

type Helper struct {
	Bus  *eventbus.EventBus
	RBus *rpcbus.RPCBus
	*Factory
	Generator *Generator
	*consensus.SimplePlayer

	ScoreChan, CandidateChan chan bytes.Buffer
	// contains filtered or unexported fields
}

Helper for reducing generation test boilerplate

func NewHelper

func NewHelper(t *testing.T, eb *eventbus.EventBus, rpcBus *rpcbus.RPCBus, txBatchCount uint16) *Helper

NewHelper creates a Helper

func (*Helper) Initialize

func (h *Helper) Initialize(ru consensus.RoundUpdate)

Initialize the generator with the given round update.

func (*Helper) ProvideTransactions

func (h *Helper) ProvideTransactions(t *testing.T)

ProvideTransactions sends a set of transactions upon the request of the blockgenerator, standing in place of the mempool.

func (*Helper) TriggerBlockGeneration

func (h *Helper) TriggerBlockGeneration()

TriggerBlockGeneration creates a random ScoreEvent and triggers block generation