octez-shell-libs 20.1 · OCaml Package

Tezos Shell - High-level API for the Gossip network and local storage.

It provides functions to query *static* resources such as blocks headers, operations, and functions to access dynamic resources such as heads and chains.

Several chains (mainchain, testchain, ...) can be managed independently. First a chain is activated using activate, which provides a chain_db from which it is possible to access resources. Eventually the chain is deactivated using deactivate.

Static resources are accessible via "Requester" modules (Block_header, Operation, Operations, Protocol). These modules act as read-through caches in front of the local storage State and the p2p layer. They centralize concurrent requests, and cache results in memory. They don't update State directly.

For instance, from a block_header hash, one can fetch the actual block header using Block_header.fetch, then the block operations with Operations.fetch.

module Message = Distributed_db_message

type t

type db = t

type p2p =
  (Message.t,
    Tezos_p2p_services.Peer_metadata.t,
    Tezos_p2p_services.Connection_metadata.t)
    Tezos_p2p.P2p.net

val create : Tezos_store.Store.t -> p2p -> t

val store : db -> Tezos_store.Store.t

val shutdown : t -> unit Lwt.t

Network database

type chain_db

An instance of the distributed DB for a given chain

val activate : 
  t ->
  Tezos_store.Store.Chain.t ->
  P2p_reader.callback ->
  chain_db

The first call to activate t chain callbacks activates chain, creates a chain_db and sends a Get_current_branch chain_id message to all neighbors, where chain_id is the identifier of chain. This informs the neighbors that this node expects notifications for new heads/mempools. The given callbacks are given to the P2p_reader for each peer:

notify_branch peer locator is called when the P2p_reader receives the message Current_branch (chain, locator) from peer peer.

notify_head peer head is called when the P2p_reader receives the message Current_head (chain, head, mempool) from peer peer.

Disconnection peer is called when the P2p_reader receives the message Deactivate chain from peer peer or when the P2p_reader associated to peer is shutdown.

Subsequent calls simply return the existing chain_db.

val get_chain : t -> Tezos_base.TzPervasives.Chain_id.t -> chain_db option

Look for the database of an active chain.

val deactivate : chain_db -> unit Lwt.t

deactivate chain_db sends a Deactivate chain_id message to all active neighbors for this chain. This notifies them that this node isn't interested in messages for this chain

val disconnect : 
  reason:string ->
  chain_db ->
  Tezos_base.P2p_peer.Id.t ->
  unit Lwt.t

Kick a given peer.

val greylist : chain_db -> Tezos_base.P2p_peer.Id.t -> unit Lwt.t

Greylist a given peer.

Various accessors.

val chain_store : chain_db -> Tezos_store.Store.chain_store

val db : chain_db -> db

val information : 
  chain_db ->
  Tezos_shell_services.Chain_validator_worker_state.Distributed_db_state.view

val my_peer_id : chain_db -> Tezos_base.P2p_peer.Id.t

Return the peer id of the node

val get_peer_metadata : 
  chain_db ->
  Tezos_base.P2p_peer.Id.t ->
  Tezos_p2p_services.Peer_metadata.t

Sending messages

module Request : sig ... end

module Advertise : sig ... end

Block index

module Block_header : sig ... end

Index of block headers.

module Operations : 
  Tezos_requester.Requester.REQUESTER
    with type t := chain_db
     and type key = Tezos_base.TzPervasives.Block_hash.t * int
     and type value = Tezos_base.Operation.t list
     and type param := Tezos_base.TzPervasives.Operation_list_list_hash.t

Index of all the operations of a given block (per validation pass).

val commit_block : 
  chain_db ->
  Tezos_base.TzPervasives.Block_hash.t ->
  Block_header.t ->
  Tezos_base.Operation.t list list ->
  Tezos_validation.Block_validation.result ->
  Tezos_store.Store.Block.t option Tezos_base.TzPervasives.tzresult Lwt.t

Store on disk all the data associated to a valid block.

val commit_invalid_block : 
  chain_db ->
  Tezos_base.TzPervasives.Block_hash.t ->
  Block_header.t ->
  Tezos_base.TzPervasives.Error_monad.error list ->
  unit Tezos_base.TzPervasives.tzresult Lwt.t

Store on disk all the data associated to an invalid block.

Operations index

val inject_operation : 
  chain_db ->
  Tezos_base.TzPervasives.Operation_hash.t ->
  Tezos_base.Operation.t ->
  bool Lwt.t

Inject a new operation in the local index (memory only).

val inject_prechecked_block : 
  chain_db ->
  Tezos_base.TzPervasives.Block_hash.t ->
  Block_header.t ->
  Tezos_base.Operation.t Tezos_base.TzPervasives.trace
    Tezos_base.TzPervasives.trace ->
  unit Tezos_base.TzPervasives.tzresult Lwt.t

Inject a prechecked block in the precheck_blocks memory table. This is to ensure the data availability of the operations once the block has been prechecked and advertised to our peers.

No need to remove the data explicitely of the precheck_blocks memory table. The table is handled as an LRU cache.

module Operation : 
  Tezos_requester.Requester.REQUESTER
    with type t := chain_db
     and type key := Tezos_base.TzPervasives.Operation_hash.t
     and type value := Tezos_base.Operation.t
     and type param := unit

Index of operations (for the mempool).

Protocol index

module Protocol : sig ... end

Index of protocol sources.

val commit_protocol : 
  db ->
  Tezos_base.TzPervasives.Protocol_hash.t ->
  Protocol.t ->
  bool Tezos_base.TzPervasives.tzresult Lwt.t

Store on disk protocol sources.

package octez-shell-libs

Network database

Sending messages

Block index

Operations index

Protocol index