package tezos-shell

  1. Overview
  2. Docs

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
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

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_crypto.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 : 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 db : chain_db -> db

Return the peer id of the node

Sending messages

module Request : sig ... end
module Advertise : sig ... end

Block index

module Block_header : sig ... end

Index of block headers.

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

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

val commit_invalid_block : chain_db -> Tezos_crypto.Block_hash.t -> Block_header.t -> Tezos_error_monad.TzCore.error list -> (unit, Tezos_error_monad.TzCore.error list) Stdlib.result Lwt.t

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

Operations index

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

val inject_prechecked_block : chain_db -> Tezos_crypto.Block_hash.t -> Block_header.t -> Tezos_base.Operation.t list list -> (unit, Tezos_error_monad.TzCore.error list) Stdlib.result 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.

Index of operations (for the mempool).

Protocol index

module Protocol : sig ... end

Index of protocol sources.

val commit_protocol : db -> Tezos_crypto.Protocol_hash.t -> Protocol.t -> (bool, Tezos_error_monad.TzCore.error list) Stdlib.result Lwt.t

Store on disk protocol sources.

OCaml

Innovation. Community. Security.