Node (u.2cec5eb6caa25952b31ad8eff0d4dbf9.tezt-tezos.18.1.doc.tezt-tezos.Tezt

Convention: in this module, some functions implement node commands; those functions are named after those commands. For instance, Node.config_init corresponds to octez-node config init, and Node.run corresponds to octez-node run.

The arguments of those functions are also named after the actual arguments. For instance, ?network is named after --network, to make Node.config_init ~network:"carthagenet" look as close as possible to octez-node config init --network carthagenet.

Most options have default values which are not necessarily the default values of octez-node. Indeed, the latter are tailored for Mainnet, but here we use defaults which are tailored for the sandbox. In particular, the default value for ?network is "sandbox". However, if you specify an option such as ~network or ~history_mode, they are passed to the node unchanged, to reduce surprises.

These conventions are also followed in the Client module.

History modes for the node.

Sourcetype history_mode =

| Archive
| Full of int option
| Rolling of int option

The parameter for Full And Rolling mode is called additional_cycles.

For the Full (resp. Rolling) mode it controls the number of contexts (resp. blocks) we preserved behind the checkpoint (aka the no fork point). Default in sandbox mode is 2 and 5 for mainnet parameters (see preserved_cycles in the protocol parameters).

Sourcetype media_type =

| Json
| Binary
| Any

Values that can be passed to the node's --media-type argument

Sourcetype argument =

| Network of string
(*
--network
*)
| History_mode of history_mode
(*
--history-mode
*)
| Expected_pow of int
(*
--expected-pow
*)
| Singleprocess
(*
--singleprocess
*)
| Bootstrap_threshold of int
(*
--bootstrap-threshold (deprecated)
*)
| Synchronisation_threshold of int
(*
--synchronisation-threshold
*)
| Sync_latency of int
(*
--sync-latency
*)
| Connections of int
(*
--connections
*)
| Private_mode
(*
--private-mode
*)
| Disable_p2p_maintenance
(*
--disable-p2p-maintenance
*)
| Disable_p2p_swap
(*
--disable-p2p-swap
*)
| Peer of string
(*
--peer
*)
| No_bootstrap_peers
(*
--no-bootstrap-peers
*)
| Disable_operations_precheck
(*
--disable-mempool-precheck
*)
| Media_type of media_type
(*
--media-type
*)
| Metadata_size_limit of int option
(*
--metadata-size-limit
*)
| Metrics_addr of string
(*
--metrics-addr
*)
| Cors_origin of string
(*
--cors-origin
*)
| Disable_mempool
(*
--disable-mempool
*)
| Version
(*
--version
*)

Tezos node command-line arguments.

Not all arguments are available here. Some are simply not implemented, and some are handled separately because they need special care. The latter are implemented as optional labeled arguments (e.g. ?net_port and ?data_dir).

Sourcetype tls_config = {

certificate_path : string;
key_path : string;

}

A TLS configuration for the node: paths to a .crt and a .key file.

Passed to run like commands through the --rpc-tls argument.

Sourcetype t

Tezos node states.

Source

val create : 
  ?runner:Tezt.Runner.t ->
  ?path:string ->
  ?name:string ->
  ?color:Tezt.Log.Color.t ->
  ?data_dir:string ->
  ?event_pipe:string ->
  ?net_addr:string ->
  ?net_port:int ->
  ?advertised_net_port:int ->
  ?rpc_host:string ->
  ?rpc_port:int ->
  ?rpc_tls:tls_config ->
  ?allow_all_rpc:bool ->
  argument list ->
  t

Create a node.

This function just creates the t value, it does not call identity_generate nor config_init nor run.

The standard output and standard error output of the node will be logged with prefix name and color color.

Default data_dir is a temporary directory which is always the same for each name.

Default event_pipe is a temporary file whose name is derived from name. It will be created as a named pipe so that node events can be received.

Default value for net_addr is either 127.0.0.1 if no runner is provided, or a value allowing the local Tezt program to connect to it if it is.

Default values for net_port or rpc_port are chosen automatically with values starting from 16384 (configurable with `--starting-port`). They are used by config_init and by functions from the Client module. They are not used by run, so if you do not call config_init or generate the configuration file through some other means, your node will not listen.

Default value for allow_all_rpc is true.

The argument list is a list of configuration options that the node should run with. It is passed to the first run of octez-node config init. It is also passed to all runs of octez-node run that occur before octez-node config init. If Expected_pow is given, it is also used as the default value for identity_generate.

If runner is specified, the node will be spawned on this runner using SSH.

Sourceval add_argument : t -> argument -> unit

Add an argument to a node as if it was passed to create.

The argument is passed to the next run of octez-node config init. It is also passed to all runs of octez-node run that occur before the next octez-node config init.

Sourceval add_peer : t -> t -> unit

Add a --peer argument to a node.

Usage: add_peer node peer

Same as add_argument node (Peer "127.0.0.1:<PORT>") where <PORT> is the P2P port of peer.

Sourceval get_peers : t -> string list

Returns the list of address of all Peer <addr> arguments.

Sourceval add_peer_with_id : t -> t -> unit Lwt.t

Add a --peer argument to a node.

Usage: add_peer node peer

Same as add_argument node (Peer "127.0.0.1:<PORT>#<ID>") where <PORT> is the P2P port and <ID> is the identity of peer.

Sourceval remove_peers_json_file : t -> unit

Removes the file peers.json that is at the root of data-dir. This file contains the list of peers known by the node.

Sourceval point_and_id : ?from:t -> t -> string Lwt.t

Get the P2P point and id for a node.

Return "<ADDRESS>:<PORT>#<ID>" where <PORT> is the P2P port and <ID> is the identity of the node.

<ADDRESS> is obtained using Runner.address runner with ?from being the runner of from and runner is the runner of the node. In other words it is the address where from can contact node.

Sourceval point : ?from:t -> t -> string * int

Get the P2P point of a node.

Return (<ADDRESS>,<PORT>) where <PORT> is the P2P port and <ADDRESS> is the reachable address of the node.

<ADDRESS> is obtained using Runner.address runner with ?from being the runner of from and runner is the runner of the node. In other words it is the address where from can contact node.

Sourceval point_str : ?from:t -> t -> string

Same as point but returns a string representation of the point "<ADDRESS>:<PORT>".

Sourceval name : t -> string

See Daemon.Make.name

Sourceval net_port : t -> int

Get the network port given as --net-addr to a node.

Sourceval advertised_net_port : t -> int option

Get the network port given as --advertised-net-port to a node.

Sourceval rpc_scheme : t -> string

Get the RPC scheme of a node.

Returns https if node is started with --rpc-tls, otherwise http

Sourceval rpc_host : t -> string

Get the RPC host given as --rpc-addr to a node.

Sourceval rpc_port : t -> int

Get the RPC port given as --rpc-port to a node.

Sourceval rpc_endpoint : t -> string

Get the node's RPC endpoint URI.

These are composed of the node's --rpc-tls, --rpc-addr and --rpc-port arguments.

Sourceval data_dir : t -> string

Get the data-dir of a node.

Sourceval runner : t -> Tezt.Runner.t option

Get the runner associated to a node.

Return None if the node runs on the local machine.

Sourceval check_error : ?exit_code:int -> ?msg:Tezt.Base.rex -> t -> unit Lwt.t

Wait until a node terminates and check its status.

If the node is not running, or if the process returns an exit code which is not exit_code, or if msg does not match the stderr output, fail the test.

If exit_code is not specified, any non-zero code is accepted. If no msg is given, the stderr is ignored.

Sourceval wait : t -> Unix.process_status Lwt.t

Wait until a node terminates and return its status. If the node is not running, make the test fail.

Sourceval terminate : ?timeout:float -> t -> unit Lwt.t

Send SIGTERM and wait for the process to terminate.

Default timeout is 30 seconds, after which SIGKILL is sent.

Sourceval kill : t -> unit Lwt.t

Send SIGKILL and wait for the process to terminate.

Commands

Sourceval identity_generate : ?expected_pow:int -> t -> unit Lwt.t

Run octez-node identity generate.

Sourceval spawn_identity_generate : ?expected_pow:int -> t -> Tezt.Process.t

Same as identity_generate, but do not wait for the process to exit.

Sourceval show_history_mode : history_mode -> string

Convert an history mode into a string.

The result is suitable to be passed to the node on the command-line.

Sourceval config_init : t -> argument list -> unit Lwt.t

Run octez-node config init.

Sourceval config_update : t -> argument list -> unit Lwt.t

Run tezos-node config update.

Sourceval config_reset : t -> argument list -> unit Lwt.t

Run tezos-node config reset.

Sourceval config_show : t -> Tezt.JSON.t Lwt.t

Run octez-node config show. Returns the node configuration.

Sourcemodule Config_file : sig ... end

Node configuration files.

Sourceval spawn_config_init : t -> argument list -> Tezt.Process.t

Same as config_init, but do not wait for the process to exit.

Sourceval spawn_config_update : t -> argument list -> Tezt.Process.t

Same as config_update, but do not wait for the process to exit.

Sourceval spawn_config_reset : t -> argument list -> Tezt.Process.t

Same as config_reset, but do not wait for the process to exit.

Sourcetype snapshot_history_mode =

| Rolling_history
| Full_history

A snapshot history mode for exports

Sourcetype export_format =

| Tar
| Raw

A snapshot file format for exports

Source

val snapshot_export : 
  ?history_mode:snapshot_history_mode ->
  ?export_level:int ->
  ?export_format:export_format ->
  t ->
  string ->
  unit Lwt.t

Run octez-node snapshot export.

Source

val spawn_snapshot_export : 
  ?history_mode:snapshot_history_mode ->
  ?export_level:int ->
  ?export_format:export_format ->
  t ->
  string ->
  Tezt.Process.t

Same as snapshot_export, but do not wait for the process to exit.

Sourceval snapshot_info : ?json:bool -> t -> string -> unit Lwt.t

Run octez-node snapshot info.

Sourceval spawn_snapshot_info : ?json:bool -> t -> string -> Tezt.Process.t

Same as snapshot_info, but do not wait for the process to exit.

Source

val snapshot_import : 
  ?no_check:bool ->
  ?reconstruct:bool ->
  t ->
  string ->
  unit Lwt.t

Run octez-node snapshot import.

Source

val spawn_snapshot_import : 
  ?no_check:bool ->
  ?reconstruct:bool ->
  t ->
  string ->
  Tezt.Process.t

Same as snapshot_import, but do not wait for the process to exit.

Sourceval reconstruct : t -> unit Lwt.t

Run octez-node reconstruct.

Sourceval spawn_reconstruct : t -> Tezt.Process.t

Same as reconstruct, but do not wait for the process to exit.

Source

val run : 
  ?patch_config:(Tezt.JSON.t -> Tezt.JSON.t) ->
  ?on_terminate:(Unix.process_status -> unit) ->
  ?event_level:Daemon.Level.default_level ->
  ?event_sections_levels:(string * Daemon.Level.level) list ->
  t ->
  argument list ->
  unit Lwt.t

Spawn octez-node run.

The resulting promise is fulfilled as soon as the node has been spawned. It continues running in the background.

event_level specifies the verbosity of the file descriptor sink. This must be at least `Notice, which is the level of event "node_is_ready.v0", needed for wait_for_ready. The default value is `Info which is also the default event level of the node.

event_sections_levels specifies the verbosity for events in sections whose prefix is in the list. For instance ~event_sections_levels:[("prevalidator", `Debug); ("validator.block", `Debug)] will activate the logs at debug level for events whose section starts with "prevalidator" or "validator.block". See Tezos_stdlib_unix.File_descriptor_sink and the logging documentation for a more precise semantic.

Source

val replay : 
  ?on_terminate:(Unix.process_status -> unit) ->
  ?event_level:Daemon.Level.default_level ->
  ?event_sections_levels:(string * Daemon.Level.level) list ->
  ?strict:bool ->
  ?blocks:string list ->
  t ->
  argument list ->
  unit Lwt.t

Spawn octez-node replay.

Same as run but for the replay command. In particular it also supports events. One key difference is that the node will eventually stop.

See run for a description of the arguments.

Events

Sourceexception Terminated_before_event of {

daemon : string;
event : string;
where : string option;

}

Sourceval wait_for_ready : t -> unit Lwt.t

Wait until the node is ready.

More precisely, wait until a node_is_ready event occurs. If such an event already occurred, return immediately.

Sourceval wait_for_level : t -> int -> int Lwt.t

Wait for a given chain level.

More precisely, wait until a head_increment or branch_switch with a level greater or equal to the requested level occurs. If such an event already occurred, return immediately.

Sourceval get_level : t -> int

Get the current known level of a node.

Returns 0 if the node is not running or if no head_increment or branch_switch event was received yet. This makes this function equivalent to wait_for_level node 0 except that it does not actually wait for the level to be known.

Note that, as the node's status is updated only on head increments, this value is wrong just after a snapshot import.

Sourceval wait_for_identity : t -> string Lwt.t

Wait for the node to read its identity.

More precisely, wait until a read_identity event occurs. If such an event already occurred, return immediately.

Return the identity.

Source

val wait_for_request : 
  request:[< `Flush | `Inject | `Notify | `Arrived ] ->
  t ->
  unit Lwt.t

wait_for_request ?level ~request node waits for request event on the node.

Source

val wait_for_full : 
  ?where:string ->
  t ->
  string ->
  (Tezt.JSON.t -> 'a option) ->
  'a Lwt.t

See Daemon.Make.wait_for_full.

Source

val wait_for : 
  ?where:string ->
  t ->
  string ->
  (Tezt.JSON.t -> 'a option) ->
  'a Lwt.t

See Daemon.Make.wait_for.

Sourceval wait_for_connections : t -> int -> unit Lwt.t

Wait for a node to receive a given number of connections.

wait_for_connections node n waits until node receives n "connection" Chain validator events.

Sourceval wait_for_disconnections : t -> int -> unit Lwt.t

Wait for a node to receive a given number of disconnections.

wait_for_disconnections node n waits until node receives n "disconnection" Chain validator events.

Sourcetype event = {

name : string;
value : Tezt.JSON.t;
timestamp : float;

}

Raw events.

Sourceval on_event : t -> (event -> unit) -> unit

See Daemon.Make.on_event.

Sourceval log_events : t -> unit

See Daemon.Make.log_events.

Sourcetype observe_memory_consumption =

| Observe of unit -> int option Lwt.t

Sourceval memory_consumption : t -> observe_memory_consumption Lwt.t

See Daemon.Make.memory_consumption.

High-Level Functions

Source

val init : 
  ?runner:Tezt.Runner.t ->
  ?path:string ->
  ?name:string ->
  ?color:Tezt.Log.Color.t ->
  ?data_dir:string ->
  ?event_pipe:string ->
  ?net_port:int ->
  ?advertised_net_port:int ->
  ?rpc_host:string ->
  ?rpc_port:int ->
  ?rpc_tls:tls_config ->
  ?event_level:Daemon.Level.default_level ->
  ?event_sections_levels:(string * Daemon.Level.level) list ->
  ?patch_config:(Tezt.JSON.t -> Tezt.JSON.t) ->
  ?snapshot:(string * bool) ->
  argument list ->
  t Lwt.t

Initialize a node.

This creates a node, runs identity_generate, config_init and run, then waits for the node to be ready, and finally returns the node.

Arguments are passed to config_init. If you specified Expected_pow, it is also passed to identity_generate. Arguments are not passed to run. If you do not wish the arguments to be stored in the configuration file (which will affect future runs too), do not use init.

When patch_config is provided, the function is used to patch the configuration file generated by config_init before the call to run. This argument should only be used to test configuration options that cannot be set with command-line arguments.

To import a snapshot before calling run, specify ~snapshot:(file, do_reconstruct), where file is the path to the snapshot. If reconstruct is true, then --reconstruct is passed to the import command.

Sourceval send_raw_data : t -> data:string -> unit Lwt.t

send_raw_data node ~data writes ~data using an IP socket on the net port of node.

Sourceval upgrade_storage : t -> unit Lwt.t

upgrade_storage node upprades the given node storage.

Sourceval get_version : t -> string Lwt.t

Run octez-node --version and return the node's version.