Consensus Protocol

The Dusk Network utilizes a consensus protocol called Succinct Attestation (SA). SA is a permissionless proof-of-stake (PoS) consensus mechanism that provides statistical finality guarantees¹. SA belongs to the committee-based PoS category² because it uses committees to finalize blocks for a given round.

SA is permissionless, meaning that any eligible participant in the Dusk Network protocol can join and participate in the consensus process. To be eligible, a participant must meet the following requirements:

• Have a pre-configured amount of DUSK locked as a stake (referred to as a Provisioner)
• Have a stake with a maturity of at least two epochs (referred to as an Eligible Provisioner)

Other terms used in the context of SA:

• Round: A single SA execution.
• Round iteration: The execution of all three phases (Selection, 1st Reduction, and 2nd Reduction) in a row.
• Committee: A subset of Eligible Provisioners, selected through a process called "Deterministic Sortition."

Repository structure

Example Node

The minimalistic and stateless version of the dusk-blockchain node allows for testing and diagnosing compatibility issues using the Consensus protocol in conjunction with Kadcast³. It enables the node to join and participate in the dusk-blockchain/test-harness. Once the dusk-blockchain is fully migrated, this executable will no longer be needed and can be deprecated.

Example Testbed

A multi-instance setup running 10 SA instances provisioned with 10 eligible participants. The setup is configured to run for up to 1000 rounds. Useful for any kind of testing (issues, stress and performance testing).

Consensus crate

A full implementation of SA mechanism.

Implementation details

The implementation of SA consists of two main tokio-rs tasks, the Main_Loop and Agreement_Loop, which communicate with external components through message queues/channels. The protocol parameters for SA are located in src/config.rs.

• The Main_Loop is responsible for executing contract storage calls using the Operations trait and storing and retrieving candidate blocks using the Database trait. It performs the selection, first reduction, and second reduction steps⁴ in sequence and ultimately produces and broadcasts an Agreement Message. The inbound queue for the Main_Loop can contain either NewBlock or Reduction type messages.

• The Agreement_Loop retrieves a candidate block using the Database trait when a winner hash is selected. It is responsible for verifying and accumulating Agreement messages from different consensus iterations and processing the Aggregated Agreement message. The inbound queue for the Agreement_Loop can contain either Agreement or Aggregated Agreement type messages. The messages are concurrently verified and accumulated by a pool of worker tasks in tokio-rs.

How to use (example code)

let mut consensus = Consensus::new(
	// Inbound messages for Main Loop
	inbound_msgs,
	// Outbound messages for Main Loop
	outbound_msgs,
	// Inbound messages for Agreement Loop
	agr_inbound_queue,
	// Outbound messages for Agreement Loop
	agr_outbound_queue,
	// Implements Operations trait
	Arc::new(Mutex::new(crate::mocks::Executor {})),
	// Implements Database trait
	Arc::new(Mutex::new(crate::mocks::SimpleDB::default())),
);

let mut most_recent_block = Block::default();

loop {
	/// Provisioners list is retrieved from contract storage state.
	let provisioners = rusk::get_provisioners();

	// Round update is the input data for any consensus round execution.
	// Round update includes mostly data from most recent block. 
	let round_update = from(most_recent_block);

	/// Consensus::Spin call initializes a consensus round
	/// and spawns main consensus tokio::tasks.
	let ret = consensus.spin(
			round_update
			provisioners,
			cancel_rx,
		)
		.await;

	/// Consensus spin output/ret can be a winner block or an error. 
	match ret {
		Ok(winner_block) => { 
			println!("new block produced");
		}
		Err(_) => {
			// Cancelled from outside by cancel_rx chan.
			// Max Step Reached - happens only if no consensus is reached for up to 213 steps/71 iterations.
		}
	}
	most_recent_block = winner;

	/// Internally, consensus instance may accept future messages for next round. 
	/// They will be drained on running the round, that's why same consensus instance is used for all round executions.
}

Tokio runtime

The implementation is fully based on Tokio-rs/Runtime. That said the recommended way of setting up the runtime is shown below.

 tokio::runtime::Builder::new_multi_thread()
   		// A thread per an accumulator worker so that CPU-bound operations 
   		// (the agreement verification) does not impact negatively main tokio tasks. 
           .worker_threads(2 + consensus::config::ACCUMULATOR_WORKERS_AMOUNT)
   		// Enable the time driver so we can use timeout feature in all steps execution.
           .enable_time()
           .build()
           .unwrap()
           .block_on(async { ... } )

Build, Run and Test

# Run unit tests
cargo test

# Build consensus
cargo b --release

# Build and Run in-process testbed example
cargo run --release --example testbed

# Build example node
cargo b --release --example node

# Run example node
export DUSK_WALLET_DIR="TBD"
export DUSK_CONSENSUS_KEYS_PASS="TBD"

USAGE:
    node --bootstrap <bootstrap>... --address <public_address>  --preloaded-num <preloaded-num> --provisioner-unique-id <prov-id>  --log-level <LOG>