package octez-crawler

  1. Overview
  2. Docs

This module allow to follow the layer 1 chain by subscribing to the head monitoring RPC offered by the Tezos node, reconnecting, etc.

type Tezos_base.TzPervasives.error +=
  1. | Cannot_find_predecessor of Tezos_base.TzPervasives.Block_hash.t
  2. | Http_connection_error of Cohttp.Code.status_code * string
type t

The type of layer 1 followers.

Monitoring the Layer 1 chain

val start : name:string -> reconnection_delay:float -> ?protocols:Tezos_base.TzPervasives.Protocol_hash.t list -> Tezos_client_base.Client_context.full -> t Lwt.t

start ~name ~reconnection_delay ?protocols cctxt connects to a Tezos node and starts monitoring new heads. One can iterate on the heads by calling iter_heads on its result. reconnection_delay gives an initial delay for the reconnection which is used in an exponential backoff. The name is used to differentiate events. If protocols is provided, only heads of these protocols will be monitored.

val create : name:string -> reconnection_delay:float -> ?protocols:Tezos_base.TzPervasives.Protocol_hash.t list -> Tezos_client_base.Client_context.full -> t

create ~name ~reconnection_delay ?protocols cctxt creates a Layer 1 context without connecting to a Tezos node. Use connect to connect to start monitoring heads. If protocols is provided, only heads of these protocols will be monitored.

val shutdown : t -> unit Lwt.t

shutdown t properly shuts the layer 1 down. This function is to be used on exit.

iter_heads ?name t f calls f on all new heads appearing in the layer 1 chain. In case of a disconnection with the layer 1 node, it reconnects automatically. If f returns an error (other than a disconnection), iter_heads terminates and returns the error. A name can be provided to differentiate iterations on the same connection.

wait_first t waits for the first head to appear in the stream and returns it.

get_latest_head t returns the latest L1 head if at least one was seen by t. The head is the one sent by the heads monitoring RPC of the L1 node, independently of how they were processed by the current process.

Helper functions for the Layer 1 chain

val get_predecessor_opt : ?max_read:int -> t -> (Tezos_base.TzPervasives.Block_hash.t * int32) -> (Tezos_base.TzPervasives.Block_hash.t * int32) option Tezos_base.TzPervasives.tzresult Lwt.t

get_predecessor_opt ?max_read state head returns the predecessor of block head, when head is not the genesis block. max_read (by default 8) is used to cache a number of predecessors (including head) to avoid some RPC calls when one need to access multiple predecessors.

get_predecessor ?max_read state head returns the predecessor block of head.

val nth_predecessor : get_predecessor:('a -> 'a Tezos_base.TzPervasives.tzresult Lwt.t) -> int -> 'a -> ('a * 'a Tezos_base.TzPervasives.trace) Tezos_base.TzPervasives.tzresult Lwt.t

nth_predecessor ~get_predecessor n head returns block, history where block is the nth predecessor of head and history is the list of blocks between block (excluded) and head (included) on the chain. It uses the function get_predecessor to retrieve the predecessor of one block.

get_tezos_reorg_for_new_head l1_ctxt ?get_old_predecessor old_head new_head returns the reorganization of L1 blocks between old_head and new_head. If old_head is `Level l, then it returns the reorganization between new_head and level l on the same chain. get_old_predecessor can be provided to use a different function (than by default get_predecessor) to retrieve the predecessors of the old head. This is necessary when the old head is not in the L1 chain anymore and forgotten by the L1 node.

client_context_with_timeout ctxt timeout creates a client context where RPCs will be made with timeout timeout seconds. Calls that timeout will resolve with an error RPC_timeout which will trigger a reconnection in iter_heads.

OCaml

Innovation. Community. Security.