Package com.exonum.binding.core.blockchain

Class Blockchain

java.lang.Object
com.exonum.binding.core.blockchain.Blockchain
public final class Blockchain
extends java.lang.Object
Provides read-only access to the subset of blockchain::Schema features in the Core API: blocks, transaction messages, execution results.

Proofs

Blockchain allows creating cryptographic proofs that some data is indeed stored in the database. Exonum supports the following types of proofs:

  • Block Proof
  • Transaction Execution Proof
  • Call Result Proof
  • Service Data Proof

Block Proof

A block proof proves correctness of a blockchain block. It can be created with createBlockProof(long) for any committed block. See also BlockProof.

Transaction Execution Proof

A transaction execution proof proves that a transaction with a given message hash was executed in a block at a certain height at a certain location. It consists of a block proof, and a list proof from getBlockTransactions(long). It may be extended to a call result proof — read the next section.

Call Result Proof

A call result proof proves that a given service call completed with a particular result in a block at a certain height. It consists of a block proof and a map proof from the call errors registry, which index hash is recorded in the block header as Block.getErrorHash().

To construct such a proof, access the call records for a particular block with getCallRecords(long); and use CallRecords.getProof(CallInBlock).

Service Data Proof

A service data proof proves that some service index contains certain data as of the last committed block. It includes:

  • An index proof: a block proof + a proof from the aggregating collection.
  • A proof from the service index.

An index proof is created with createIndexProof(String).

Example

Consider a simple timestamping service that keeps timestamps for event ids, and supports proofs of their authenticity.

First, create a message definition for a proof: 

   message TimestampProof {
     MapProof timestamp = 1;
     IndexProof indexProof = 2;
   }

Then create the two components: timestamp proof from a service index and index proof for that index from the blockchain: 

   TimestampProof createTimestampProof(Snapshot s,
                                       String eventId) {
     // 1. Create a timestamp proof
     // The literal is for illustrative purposes —
     // usually the service name is prepended elsewhere
     var fullIndexName = "timestamping.timestamp";
     var timestamps = ProofMapIndexProxy.newInstance(fullIndexName, s,
         string(), timestamp());
     var tsProof = timestamps.getProof(eventId);

     // 2. Create an index proof
     var blockchain = Blockchain.newInstance(s);
     var indexProof = blockchain.createIndexProof(fullIndexName);

     // 3. Create a complete service data proof
     return TimestampProof.newBuilder()
       .setTimestamp(tsProof.getAsMessage())
       .setIndexProof(indexProof.getAsMessage())
       .build();
   }

Finally, serialize the proof and send it to the client.

All method arguments are non-null by default.

  • Method Details

    • newInstance

      public static Blockchain newInstance​(Access access)
      Constructs a new blockchain instance for the given database access.

      Expects a non-prefixed access. Use BlockchainData.getBlockchain() in service code.

    • createBlockProof

      public BlockProof createBlockProof​(long blockHeight)
      Creates a proof for the block at the given height.

      It allows creating genesis block proofs, but they make little sense, as a genesis block is supposed to be a "root of trust", hence, well-known to the clients verifying any subsequent proofs coming from the blockchain.

      If you need to create a proof for a service index, use createIndexProof(String).

      Parameters:
      blockHeight - a height of the block for which to create a proof
      Throws:
      java.lang.IndexOutOfBoundsException - if the height is not valid
      See Also:
      createIndexProof(String)

    • createIndexProof

      public IndexProof createIndexProof​(java.lang.String fullIndexName)
      Creates a proof for a single index in the database. It is usually a part of a Service Data Proof.
      Parameters:
      fullIndexName - the full index name for which to create a proof
      Throws:
      java.lang.IllegalStateException - if the access is not a snapshot, because a state of a service index can be proved only for the latest committed block, not for any intermediate state during transaction processing
      java.lang.IllegalArgumentException - if the index with the given name does not exist; or is not Merkelized. An index does not exist until it is initialized — created for the first time with a Fork. Depending on the service logic, an index may remain uninitialized indefinitely. Therefore, if proofs for an empty index need to be created, it must be initialized early in the service lifecycle (e.g., in Service.initialize(ExecutionContext, Configuration).

    • containsBlock

      public boolean containsBlock​(Block block)
      Returns true if the blockchain contains exactly the same block as the passed value; false if it does not contain such block. Please note that all block fields are compared, not only its hash.
      Parameters:
      block - a value to check for presence in the blockchain

    • getHeight

      public long getHeight()
      Returns the blockchain height which is the height of the latest committed block in the blockchain. The block height is a distance between the last block and the "genesis", or initial, block. Therefore, the blockchain height is equal to the number of blocks plus one.

      For example, the "genesis" block has height h = 0. The latest committed block has height h = getBlockHashes().size() - 1.

      Throws:
      java.lang.RuntimeException - if the "genesis block" was not created yet; consider using getNextHeight() in service methods that might be invoked before the genesis block commit

    • getNextHeight

      public long getNextHeight()
      Returns the blockchain height of the next block to be committed.
      See Also:
      getHeight()

    • getBlockHashes

      public ListIndex<HashCode> getBlockHashes()
      Returns a list of all block hashes, indexed by the block height. For example, the "genesis block" will be at index 0, the block at height h = 10 — at index 10. The last committed block will be at height h = getBlockHashes().size() - 1.

    • getBlockTransactions

      public ProofListIndexProxy<HashCode> getBlockTransactions​(long height)
      Returns a proof list of transaction hashes committed in the block at the given height.

      The index hash of this index is recorded in the block header as Block.getTxRootHash(). That allows constructing proofs that a transaction with a certain message hash was executed at a certain location: (block_height, tx_index_in_block) pair.

      Parameters:
      height - block height starting from 0
      Throws:
      java.lang.IllegalArgumentException - if the height is invalid: negative or exceeding the blockchain height

    • getBlockTransactions

      public ProofListIndexProxy<HashCode> getBlockTransactions​(HashCode blockId)
      Returns a proof list of transaction hashes committed in the block with the given id.
      Parameters:
      blockId - id of the block
      Throws:
      java.lang.IllegalArgumentException - if there is no block with given id
      See Also:
      getBlockTransactions(long)

    • getBlockTransactions

      public ProofListIndexProxy<HashCode> getBlockTransactions​(Block block)
      Returns a proof list of transaction hashes committed in the given block. The given block must match exactly the block that is stored in the database.
      Parameters:
      block - block of which list of transaction hashes should be returned
      Throws:
      java.lang.IllegalArgumentException - if there is no such block in the blockchain
      See Also:
      getBlockTransactions(long)

    • getTxMessages

      public MapIndex<HashCode,​TransactionMessage> getTxMessages()
      Returns a map of transaction messages identified by their SHA-256 hashes. Both committed and in-pool (not yet processed) transactions are returned.

    • getCallRecords

      public CallRecords getCallRecords​(long blockHeight)
      Returns the call records, containing the execution errors that occurred in the block at the given height.
      Parameters:
      blockHeight - the height of the block
      Throws:
      java.lang.IllegalArgumentException - if the height is invalid: negative or exceeding the blockchain height

    • getTxResult

      public java.util.Optional<Errors.ExecutionStatus> getTxResult​(HashCode messageHash)
      Returns a transaction execution result for the given message hash.
      Returns:
      a transaction execution result, or Optional.empty() if this transaction is unknown or was not yet executed

    • getTxLocations

      public MapIndex<HashCode,​TransactionLocation> getTxLocations()
      Returns a map that keeps the transaction position inside the blockchain for every transaction hash.

    • getTxLocation

      public java.util.Optional<TransactionLocation> getTxLocation​(HashCode messageHash)
      Returns transaction position inside the blockchain for given message hash.
      Returns:
      a transaction execution result, or Optional.empty() if this transaction is unknown or was not yet executed

    • getBlocks

      public MapIndex<HashCode,​Block> getBlocks()
      Returns a map that stores a block object for every block hash.

    • getBlock

      public Block getBlock​(long height)
      Returns the block at the given height.
      Parameters:
      height - the height of the block; must be non-negative and less than or equal to the current blockchain height
      Returns:
      a block at the height
      Throws:
      java.lang.IndexOutOfBoundsException - if the height is not valid

    • findBlock

      public java.util.Optional<Block> findBlock​(HashCode blockHash)
      Returns a block object for given block hash.
      Returns:
      a corresponding block, or Optional.empty() if there is no block with given block hash

    • getLastBlock

      public Block getLastBlock()
      Returns the latest committed block.
      Throws:
      java.lang.IllegalStateException - if the "genesis block" was not created

    • getConsensusConfiguration

      public Blockchain.Config getConsensusConfiguration()
      Returns the current consensus configuration of the network.
      Throws:
      java.lang.IllegalStateException - if the "genesis block" was not created
      See Also:
      Exonum configuration for consensus configuration information.

    • getTransactionPool

      public KeySetIndexProxy<HashCode> getTransactionPool()
      Returns a set of uncommitted (in-pool) transaction hashes; empty in case of no transactions. Note that this pool represents the state as of the current snapshot, and its state is volatile even between block commits.
      See Also:
      Pool of Unconfirmed Transactions

    • getNumTransactions

      public long getNumTransactions()
      Returns the total number of transactions committed to the blockchain.