vapcore-clique

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.