Crate exonum_configuration [−] [src]

Introduction

This crate implements the standalone configuration service of Exonum blockchain, which, upon being plugged in, allows modifying Exonum blockchain configuration by means of propose config and vote for proposed config transactions, signed by validators - actual blockchain participants.

It also contains http api implementation for public queries (get actual/following configuration, etc.) and private queries, intended for use only by validator nodes' maintainers (post configuration propose, post vote for a configuration propose).

Exonum blockchain configuration is composed of:

  • consensus algorithm parameters
  • list of validators' public keys - list of identities of consensus participants
  • list of services public keys
  • configuration of all services, plugged in for a specific blockchain instance.

It also contains auxiliary fields:

  • actual_from - blockchain height, upon reaching which current config is to become actual.
  • previous_cfg_hash - hash of previous configuration, which validators' set is allowed to cast votes for current config.

See StoredConfiguration in exonum.

While using the service's transactions and/or api, it's important to understand, how hash of a configuration is calculated. It's calculated as a hash of normalized String bytes, containing configuration json representation. When a new propose is put via TxConfigPropose:

  1. bytes of a String, containing configuration json ->
  2. String ->
  3. StoredConfiguration ->
  4. unique normalized String for a unique configuration ->
  5. bytes ->
  6. hash(bytes)

The same hash of a configuration is referenced in TxConfigVote in cfg_hash.

Examples

Run Exonum blockchain testnet with single configuration service turned on for it in a single process (2 threads per node: 1 - for exonum node and 1 - for http api listener)

extern crate exonum;
extern crate exonum_configuration;

use exonum::helpers::fabric::NodeBuilder;

use exonum_configuration::ConfigurationService;

fn main() {
    exonum::helpers::init_logger().unwrap();
    NodeBuilder::new()
        .with_service::<ConfigurationService>()
        .run();
}

Modules

config_api

Configuration service http api.

Structs

ConfigurationSchema

ConfigurationService database schema: tables and logically atomic mutation methods.
ConfigurationService

Struct, implementing Service trait template. Most of the actual business logic of modifying Exonum blockchain configuration is inside of TxConfigPropose and TxConfigVote.
StorageValueConfigProposeData
TxConfigPropose
TxConfigVote
ZEROVOTE

Specific TxConfigVote with all bytes in message set to 0. It is used as placeholder in database for votes of validators, which didn't cast votes.

Constants

CONFIG_PROPOSE_MESSAGE_ID

Value of message_type of TxConfigPropose
CONFIG_SERVICE

Value of service_id of ConfigurationService
CONFIG_VOTE_MESSAGE_ID

Value of message_type of TxConfigVote