vapcore-clique 0.1.0

Vapory style clique consensus engine
Documentation

vapcore-clique

Implementation of the Clique PoA Engine.

File structure:

  • mod.rs -> Provides the engine API implementation, with additional block state tracking
  • block_state.rs -> Records the Clique state for given block.
  • params.rs -> Contains the parameters for the Clique engine.
  • step_service.rs -> An event loop to trigger sealing.
  • util.rs -> Various standalone utility functions.
  • tests.rs -> Consensus tests as defined in EIP-225.

How syncing works:

  1. Client will call:
    • Clique::verify_block_basic()
    • Clique::verify_block_unordered()
    • Clique::verify_block_family()
  2. Using Clique::state() we try and retrieve the parent state. If this isn't found we need to back-fill it from the last known checkpoint.
  3. Once we have a good state, we can record it using CliqueBlockState::apply().

How sealing works:

  1. Set a signer using Engine::set_signer(). If a miner account was set up through a config file or CLI flag MinerService::set_author() will eventually set the signer
  2. We check that the engine is ready for sealing through Clique::sealing_state() Note: This is always SealingState::Ready for Clique
  3. Calling Clique::new() will spawn a StepService thread. This thread will call Engine::step() periodically. Internally, the Clique step() function calls Client::update_sealing(), which is what makes and seals a block.
  4. Clique::generate_seal() will then be called by miner. This will return a Seal which is either a Seal::None or Seal:Regular. The following shows how a Seal variant is chosen: a. We return Seal::None if no signer is available or the signer is not authorized. b. If period == 0 and block has transactions, we return Seal::Regular, otherwise return Seal::None. c. If we're INTURN, wait for at least period since last block before trying to seal. d. If we're not INTURN, we wait for a random amount of time using the algorithm specified in EIP-225 before trying to seal again.
  5. Miner will create new block, in process it will call several engine methods to do following: a. Clique::open_block_header_timestamp() must set timestamp correctly. b. Clique::populate_from_parent() must set difficulty to correct value. Note: Clique::populate_from_parent() is used in both the syncing and sealing code paths.
  6. We call Clique::on_seal_block() which will allow us to modify the block header during seal generation.
  7. Finally, Clique::verify_local_seal() is called. After this, the syncing code path will be followed in order to import the new block.