Glossary of Terms

Exonum documentation uses some specific terms to describe key Exonum concepts. Here, these terms are condensed to a single page.

Note

All terms here are defined with Exonum in mind. For example, Transaction describes how transactions work in Exonum. Generally speaking, transaction may have many other meanings, but they are not covered in this document.

Artifact

Aka service artifact

Factory for service instantiation. Artifacts are similar to classes in object-oriented programming while services are similar to objects. A single artifact may be used to instantiate zero or more services.

An artifact is identified by a name and a semantic version. Like services, artifacts are attached to a runtime, and their lifecycle events are controlled via the supervisor.

Auditor

Aka auditing node

A full node in the blockchain network that does not participate in creating new blocks, but rather performs continuous audit of all transactions in the network. Auditors are identified by a public key within the blockchain network. Unlike validators, adding auditors does not create an overhead in transaction latency and throughput, so there can be hundreds of auditors in the same blockchain network.

Example

Consider an Exonum blockchain that implements public registry in a particular country. In this case, auditing nodes may belong to non-government agencies which are interested in monitoring the operation of the registry.

Authenticated Consensus

The type of consensus, in which the participants are known in advance and are authenticated, usually with the help of public-key cryptography (such as digital signatures). Exonum uses authenticated consensus algorithm slightly similar to PBFT, in order to keep the system decentralized and withstand attacks by Byzantine validators.

Binary Serialization

Serialization of data stored in the blockchain and messages into a platform-independent sequence of bytes using the Protobuf serialization format. Binary serialization is used in Exonum for cryptographic operations, such as computing hashes and digital signing.

Tip

See Serialization for more details.

Block

Aka normal block

An ordered list of transactions in a blockchain, together with the authentication by at least 2/3 of the validators set, and some additional information (such as the hash of the previous block and the hash of the blockchain state after applying the transactions in the block). The compact block form, in which transactions are replaced by the root of their Merkle tree, is used for communication with light clients.

Besides transactions, applying a block to the blockchain state comprises executing hooks for the currently active services.

Block Skip

An outcome of the consensus algorithm alternative to approving a block. Like normal blocks, block skips are stored together with authenticating info, but they are removed from the storage as soon as a newer skip or a normal block is approved.

Applying a block skip to the blockchain state is trivial: no calls to services are executed, so the blockchain state remains the same.

Tip

See Consensus article for reasoning behind block skips.

Blockchain

A distributed ledger, which uses hash linking to achieve immutability of the transactions log, and other cryptographic tools to improve accountability. Transactions in a blockchain are grouped in blocks to improve auditing by light clients.

Whereas the design goal of a distributed ledger is decentralized data management, one of the design goals of a blockchain is achieving accountability of the blockchain maintainers and auditability of the system by third parties (e.g., internal and external auditors, regulators and end users of the system).

Blockchain Explorer

Aka explorer, explorer service

A service that provides REST API and Websockets for monitoring blocks and transactions in Exonum blockchain. The explorer service allows obtaining the following information and executing the following actions via its endpoints:

  • information on a specified range of blocks
  • information on a block at a specific height
  • information on a transaction specified by a hash
  • sending a transaction into the pool of uncommitted transactions and broadcasting it to other nodes
  • subscribing to block and / or transaction commit events.

Tip

See Other Services for more details.

Blockchain State

The persistent state maintained by each full node in the blockchain network, to which transactions are applied. The consensus algorithm ensures that the blockchain state (not only the transactions log) is identical for all full nodes.

In Exonum, the blockchain state is implemented as a key-value storage. It is persisted using RocksDB. The parts of the storage correspond to tables used by the core and services.

Built-in Service

Service that is active at the blockchain initialization (that is, when the genesis block is created).

One example of built-in services is the supervisor. Indeed, if a supervisor service is not instantiated on the genesis block, service lifecycle cannot be controlled in the future.

Byzantine Node

A node in a distributed network that acts outside of behavior prescribed by the consensus algorithm in the network. Byzantine behavior may be caused by a malicious intent, malfunctioning software/hardware, or network connectivity problems.

Consensus algorithms that are able to withstand Byzantine behavior are called Byzantine fault-tolerant (BFT). Exonum uses BFT consensus inspired by PBFT. Exonum is able to tolerate up to 1/3 of validators acting Byzantine, which is the best possible number under the security model that Exonum uses.

Configuration

A set of configurable parameters that determine the behavior of a full node. Configuration consists of 2 parts: global configuration and local configuration. Certain configuration parameters are defined by the core, e.g., the maximum number of transactions in a block. Services can define and manage additional configuration parameters too.

Tip

See Configuration for more details.

Consensus

Aka consensus algorithm

A mechanism of reaching agreement among nodes in a network. In the blockchain context, consensus is required to withstand faults: nodes being non-responsive and/or outright trying to compromise the operation of the blockchain.

There are 2 main types of consensus:

  • Authenticated consensus, in which the participating nodes are known in advance. This is the type of consensus implemented in Exonum;
  • Anonymous consensus, in which the consensus participants are not known in advance. This type of consensus is commonly used in cryptocurrencies (e.g., Bitcoin).

Consensus Message

A message generated by a full node as prescribed by the consensus algorithm. Validators exchange consensus messages to commit transactions to the blockchain by creating new blocks.

Consensus messages include:

  • Propose, Prevote and Precommit messages that correspond to 3 phases of the consensus algorithm used in Exonum;
  • Request messages used by full nodes to request missing data from peers;
  • Block message used to transmit an entire block of transactions to a lagging full node;
  • Auxiliary messages, such as Status and Connect.

Tip

See Consensus and Requests for more details.

Core

In Exonum: the functionality present in any Exonum blockchain, regardless of the deployed services, encapsulated in the exonum repository.

For example, the core includes a collection of system tables (such as a set of all transactions ever committed to the blockchain).

Data Migration

Preparing the data of an Exonum service for use with an updated version of the service business logic. Fulfil the same role as migrations in traditional database management systems.

Migrations are defined in service artifacts, managed by the core and controlled by the supervisor. From the point of a service developer, migrations are represented by migration scripts.

Data Schema

Structured presentation of a portion of the blockchain state. Similar to object-relational mapping. Data schemas may be used by services to access and modify their data. A schema can also be made public, allowing other services on the same blockchain to safely read service data, and for light clients to check Merkle proofs returned by the service.

Decentralization

Absence of a single point of failure in the system. For example, absence of a single administrator having privileges to perform arbitrary actions.

Digital Signature

Aka signature

A public-key digital signature in the Ed25519 elliptic curve cryptosystem. The signature over a message proves that the signer knows a specific private key corresponding to a publicly known public key. A signature can be verified against this public key and the signed message, thus providing message authenticity (i.e., the message comes from a specific source) and integrity (the message is not modified after being signed). Ed25519 signatures are universally verifiable, meaning that a verifier does not need to know any additional information to verify a signature.

Implementation details

Ed25519 digital signatures occupy 64 bytes in the binary form. Exonum uses the sodiumoxide Rust crate (a libsodium binding for Rust) to create and verify digital signatures on full nodes, and TweetNaCl.js to perform similar operations on light clients.

Distributed Ledger

A distributed system that maintains a full transactions log for all operations in the system, so that any piece of data in the system has a verifiable audit trail. All transactions are authenticated, usually via public key cryptography used together with some form of timestamping to provide non-repudiation.

Note

In a generic distributed ledger, the audit trail may be dispersed across the system participants. Thus, it may be difficult to argue about consistency of the whole system.

Blockchains are a particular kind of distributed ledgers with a focus on auditability and accountability of the system maintainers.

Epoch

Aka consensus epoch

A single iteration of the Exonum consensus algorithm, which results in accepting a block or a block skip. Also, an non-negative, auto-incrementing counter enumerating these iterations.

Full Node

Aka peer

A node in the blockchain network that replicates all transactions in the blockchain and thus has a local copy of the entire blockchain state. There are 2 categories of full nodes in Exonum: validators and auditors.

Genesis Block

The very first block in the blockchain. The genesis block does not link to the hash of the previous block in the blockchain; instead, this link is filled with a placeholder (32 bytes of zeros). The genesis block contains an initial global configuration and no other transactions.

Global Configuration

Part of the configuration common for all full nodes. The global configuration is a part of the blockchain state. The core defines several global configuration parameters, which are mostly related to consensus and networking (e.g., a set of validators public keys).

Hash

Aka cryptographic hash

SHA-256 cryptographic hash digest of certain data. Exonum uses hashes as unique identifiers for transactions. Hashes are also used to create Merkle trees and their variants.

Implementation details

SHA-256 hashes occupy 32 bytes in the binary form. Exonum uses sodiumoxide to calculate hashes on full nodes and sha.js to do the same on light clients.

Interface

Aka service interface

Collection of transaction types that a service is capable of handling. Fulfil the same role as interfaces in programming languages (e.g., interface in Java or trait in Rust): a service can declare that it implements one or more interfaces, thus allowing other services and light clients to interact with the service through these interfaces.

Warning

Interfaces are an unstable feature of the Exonum framework; their specification may change in future releases.

Internal Call

Call from one service instance to another during transaction processing or other top-level calls in a block. Internal calls allow service to interact with each other and implement stateful call authorization (e.g., multi-signatures).

Tip

See Service Interaction for more details.

Warning

Internal calls are an unstable feature of the Exonum framework; their specification may change in future releases.

Java Service

Exonum service implemented within the Java runtime. Java services implement read requests as REST APIs with the help of the vert.x Web framework.

Unlike Rust services, execution of Java services is isolated within JVM, and their artifacts can be deployed on nodes at any time. This comes with the performance trade-off.

JSON Serialization

Serialization of data stored in the blockchain and messages into JSON. JSON serialization is used in Exonum for service endpoints. It is implemented both in the core and in the light client library.

Light Client

Aka lightweight client, thin client

A node in the blockchain network that does not replicate all transactions in the blockchain, but rather only a small subset that the client is interested in and/or has access to. Light clients can communicate with full nodes to retrieve information from the blockchain and initiate transactions. The proofs mechanism allows minimizing the trust factor during this communication and protecting the client against a range of attacks.

Local Configuration

A part of configuration local to every full node. The local configuration is not a part of the blockchain state; instead, it is maintained as a local TOML file, which is read during the node startup. The core defines several local configuration parameters, such as the private key used to sign consensus and network messages created by the node.

Maintainer

An entity participating in creating blocks and setting the rules in a blockchain.

In permissioned blockchains, maintainers have known real-world identities, which are reflected in the blockchain protocol. The maintainers set up and administer validator nodes in the network, and agree on the changes in the transaction processing rules.

Example

Consider an Exonum blockchain that implements a public registry in a particular country. In this case, the maintainer of the blockchain is a government agency or agencies, which are tasked with maintaining public registries by law.

In contrast, in permissionless blockchains (e.g., Bitcoin), maintainers are not reflected within the blockchain protocol. Validators in such networks are usually pseudonymous.

Merkle Proof

A cryptographic proof that certain data is a part of the cryptographic commitment based on Merkle trees or their variants. A Merkle proof allows compactly proving that certain data is stored at the specified key in the blockchain state. At the same time, the proof does not reveal other information about the state and does not require replication of all transactions in the blockchain network.

Merkle proofs are used in Exonum in the responses to read requests by light clients. Using proofs, a client can verify the authenticity of a response without needing to communicate with multiple full nodes or replicating all transactions in the blockchain.

Merkle Tree

Aka hash tree

A data structure based on a binary tree that allows calculating an aggregate hash from a list of elements in such a way that any particular element of the list is tied to the overall hash via a short link. (This link is called a Merkle path or Merkle proof.)

Exonum uses Merkle trees and a similar data structure for maps (Merkle Patricia tree) to collect the entire blockchain state into a single state hash recorded in blocks, and to provide proofs to light clients.

Note

In cryptographic terms, a Merkle tree applies a commitment scheme to the list of elements in such a way that the size of any opening of the commitment is logarithmic with respect to the number of elements in the list.

Message

A digitally signed piece of data transmitted through an Exonum network. There are 2 major kinds of messages:

Migration Script

Encapsulation of data migration in a service artifact. Defines logic to transform data of the old version of the service to a specific newer version. The output of a migration script is atomically applied to the database on every node in the network, provided that it is the same for all nodes. (This check is ensured by the supervisor.)

Tip

See MerkleDB for more details.

Permissioned Blockchain

A blockchain in which maintainers are a limited set of entities with established real-world identities. Accordingly, validator nodes in a permissioned blockchain are few in number and are authenticated with the help of public-key cryptography.

Permissioned blockchains usually use variations of authenticated consensus.

Private API

An endpoint of a Rust service that is hosted on a private web server. Can be used to administer a local instance of the service. As an example, private API can be used to change the local configuration of a service.

Private Key

Private key as per the Ed25519 specification. Each private key corresponds to a specific public key. The knowledge of a private key is necessary to create digital signatures over messages, which could be later verified against the message and the corresponding public key.

Implementation details

As per libsodium, private keys occupy 64 bytes in the binary form: 32 bytes for the cryptographic seed used to generate the key, and 32 bytes for the pre-calculated corresponding public key. The latter 32 bytes are redundant, but help speed up computations.

Public Key

A public key as per the Ed25519 specification. Public keys are used to verify digital signatures over messages. A public key can be linked with a real-world identity. For example, public keys used in consensus are tied to specific validators, as only a specific validator is assumed to know the corresponding private key.

Implementation details

As per libsodium, public keys occupy 32 bytes in the binary form.

Read Request

A service endpoint that can be used to retrieve data from the blockchain state. The data is usually returned with a proof that the data is indeed a part of the blockchain state and has been authorized by a supermajority of validators.

The implementation of read requests is runtime-specific. For example, read requests can be implemented via HTTP GET.

Runtime

Container for services and artifacts, providing a single interface for the core to interact with. A runtime provides to the core service logic by executing it in a certain environment, such as a virtual machine.

Exonum currently supports Rust and Java runtimes, but a runtime can be implemented for any environment provided that it can interact with the Rust interface provided by the core.

Rust Service

Exonum service implemented within the Rust runtime. Rust services implement read requests and private endpoints as REST APIs with the help of the actix Web framework.

Rust services have high performance, but are executed in the same context as the core, which may lead to security risks. Another peculiarity is that new Rust artifacts may only be deployed via node recompilation.

Serialization

A process of converting Exonum data structures to a language-independent representation. Exonum defines (de)serialization rules for stored datatypes and messages. Each of these can be converted from/to 2 representations: binary and JSON.

Service

The main extension point of the Exonum framework, similar in its design to a web service. Services define all transaction processing logic in any Exonum blockchain.

Externally, a service is essentially a collection of endpoints that allow manipulating data in the blockchain state and retrieving it, possibly with proofs. Internally, a service may define various entities, including table schema, configurable parameters, etc.

Currently, services can be implemented in Rust or Java.

Tip

See Services for more details.

Service Endpoint

A point of communication with a service. There are several kinds of endpoints:

  • Transactions allow modifying the service state.
  • Service schemas allow to read service information from the database, which can be used by other services
  • Read requests allow reading data from the blockchain state, usually together with a proof.
  • Private APIs allow configuring the service locally.

External entities such as light clients can access endpoints via runtime-specific interfaces. The primary interface currently is REST-ful HTTP.

Service Hook

Event that a service may react to by changing the blockchain state. The core defines the following hooks:

  • service initialization
  • service being resumed
  • before any transactions in every block are executed
  • after all transactions in every block are executed

Together with transactions, before transactions / after transactions hooks constitute top-level calls performed within each block.

Tip

See Services for more details.

Service Lifecycle

Lifecycle for artifacts and services defined in the Exonum core. It defines artifact / service states and allowed transitions among these states, together with the preconditions that must apply for the transition to occur.

For example, services may be instantiated, stopped, frozen, resumed, with zero or more data migrations occurring between stopping / freezing and resuming.

Tip

See Service Lifecycle for more details.

Stored Datatype

A datatype capable of being stored as a value in the Exonum key-value storage. Stored datatypes use binary serialization logic to convert data to a platform-independent representation.

Tip

See Storage for more details.

Supervisor

Exonum service controlling the service lifecycle. Supervisor is responsible for authorizing lifecycle events and thus reflects the will of system maintainers.

Tip

See Supervisor for more details.

Table

Aka index

A structured collection of data (e.g., a map, set or a list) that provides a high-level abstraction on top of the blockchain state. Tables are used by services to simplify data management. Additionally, some types of tables allow computing Merkle proofs efficiently for table items.

Transaction

An atomic patch to the blockchain state satisfying ACID criteria. Transactions are authenticated with the help of public-key digital signatures; i.e., the authorship of each transaction is known and cannot be easily repudiated. Transactions may be generated by various entities in the blockchain network, such as light clients.

Transactions are ordered and grouped into blocks in the course of the consensus algorithm. Thus, transactions are applied in the same order on all full nodes in the blockchain network.

All transactions are templated and defined within services, acting similarly to stored procedures in database management systems.

Transaction verification rules, such as the validity of a digital signature in the transaction, are specified in the Exonum core. If the rules do not hold for a particular transaction, it does not change the blockchain state, but may still be recorded in the transaction log.

Tip

See Transactions for more details.

Validator

A full node in the blockchain network with the right to participate in the consensus algorithm to create blocks. In Exonum, validators are identified with the help of the global configuration, which contains public keys of all validators in the network. The set of validators can be changed by changing the global configuration. Usually, the set of validators is reasonably small, consisting of 4–16 nodes.