package octez-smart-rollup-node-lib

  1. Overview
  2. Docs
package octez-smart-rollup-node-lib
Legend:
Library
Module
Module type
Parameter
Class
Class type

This module describes the execution context of the node.

type genesis_info = Metadata.genesis_info = {
  1. level : int32;
  2. commitment_hash : Octez_smart_rollup.Commitment.Hash.t;
}
type 'a store constraint 'a = [< `Read | `Write Read ]

Abstract type for store to force access through this module.

module Node_store : sig ... end

Exposed functions to manipulate Node_context store outside of this module

type debug_logger = string -> unit Lwt.t
type current_protocol = {
  1. hash : Tezos_base.TzPervasives.Protocol_hash.t;
    (*

    Hash of the current protocol.

    *)
  2. proto_level : int;
    (*

    Protocol supported by this rollup node (represented as a protocol level).

    *)
  3. constants : Octez_smart_rollup.Rollup_constants.protocol_constants;
    (*

    Protocol constants retrieved from the Tezos node.

    *)
}
type last_whitelist_update = {
  1. message_index : int;
  2. outbox_level : Int32.t;
}
type private_info = {
  1. last_whitelist_update : last_whitelist_update;
  2. last_outbox_level_searched : int32;
    (*

    If the rollup is private then the last search outbox level when looking at whitelist update to execute. This is to reduce the folding call at each cementation. If the rollup is public then it's None.

    *)
}
type sync_info = {
  1. on_synchronized : unit Lwt_condition.t;
  2. mutable processed_level : int32;
  3. sync_level_input : int32 Lwt_watcher.input;
}
type 'a t = {
  1. config : Configuration.t;
    (*

    Inlined configuration for the rollup node.

    *)
  2. cctxt : Tezos_client_base.Client_context.full;
    (*

    Client context used by the rollup node.

    *)
  3. dal_cctxt : Tezos_dal_node_lib.Dal_node_client.cctxt option;
    (*

    DAL client context to query the dal node, if the rollup node supports the DAL.

    *)
  4. dac_client : Tezos_dac_client_lib.Dac_observer_client.t option;
    (*

    DAC observer client to optionally pull in preimages

    *)
  5. data_dir : string;
    (*

    Node data dir.

    *)
  6. l1_ctxt : Layer1.t;
    (*

    Layer 1 context to fetch blocks and monitor heads, etc.

    *)
  7. genesis_info : genesis_info;
    (*

    Origination information of the smart rollup.

    *)
  8. injector_retention_period : int;
    (*

    Number of blocks the injector will keep information about included operations.

    *)
  9. block_finality_time : int;
    (*

    Deterministic block finality time for the layer 1 protocol.

    *)
  10. kind : Octez_smart_rollup.Kind.t;
    (*

    Kind of the smart rollup.

    *)
  11. unsafe_patches : Pvm_patches.t;
    (*

    Patches to apply to the PVM.

    *)
  12. lockfile : Lwt_unix.file_descr;
    (*

    A lock file acquired when the node starts.

    *)
  13. store : 'a store;
    (*

    The store for the persistent storage.

    *)
  14. context : 'a Tezos_layer2_store.Context.t;
    (*

    The persistent context for the rollup node.

    *)
  15. lcc : ('a, lcc) Reference.t;
    (*

    Last cemented commitment on L1 (independently of synchronized status of rollup node) and its level.

    *)
  16. lpc : ('a, Octez_smart_rollup.Commitment.t option) Reference.t;
    (*

    The last published commitment on L1, i.e. commitment that the operator is staked on (even if the rollup node is not synchronized).

    *)
  17. private_info : ('a, private_info option) Reference.t;
    (*

    contains information for the rollup when it's private.

    *)
  18. kernel_debug_logger : debug_logger;
    (*

    Logger used for writing kernel_debug messages

    *)
  19. finaliser : unit -> unit Lwt.t;
    (*

    Aggregation of finalisers to run when the node context closes

    *)
  20. current_protocol : current_protocol Reference.rw;
    (*

    Information about the current protocol. This value is changed in place on protocol upgrades.

    *)
  21. global_block_watcher : Octez_smart_rollup.Sc_rollup_block.t Lwt_watcher.input;
    (*

    Watcher for the L2 chain, which enables RPC services to access a stream of L2 blocks.

    *)
  22. sync : sync_info;
    (*

    Synchronization status with respect to the L1 node.

    *)
}
type rw = [ `Read | `Write ] t

Read/write node context t.

type ro = [ `Read ] t

Read only node context t.

val get_operator : _ t -> 'a Purpose.t -> 'a Purpose.operator option

get_operator cctxt purpose returns the public key hash for the operator who has purpose purpose, if any.

val is_operator : _ t -> Tezos_crypto.Signature.Public_key_hash.t -> bool

is_operator cctxt pkh returns true if the public key hash pkh is an operator for the node (for any purpose).

val is_accuser : _ t -> bool

is_accuser node_ctxt returns true if the rollup node runs in accuser mode.

val is_bailout : _ t -> bool

is_bailout node_ctxt returns true if the rollup node runs in bailout mode.

val is_loser : _ t -> bool

is_loser node_ctxt returns true if the rollup node runs has some failures planned.

val can_inject : _ t -> Octez_smart_rollup.Operation_kind.t -> bool

can_inject config op_kind determines if a given operation kind can be injected based on the configuration settings.

val check_op_in_whitelist_or_bailout_mode : _ t -> Tezos_crypto.Signature.Public_key_hash.t list -> unit Tezos_base.TzPervasives.tzresult

check_op_in_whitelist_or_bailout_mode node_ctxt whitelist Checks when the rollup node is operating to determine if the operator is in the whitelist or if the rollup node is in bailout mode. Bailout mode does not publish any commitments but still defends previously committed one.

get_fee_parameter cctxt purpose returns the fee parameter to inject an operation for a given purpose. If no specific fee parameters were configured for this purpose, returns the default fee parameter for this purpose.

val global_lockfile_path : data_dir:string -> string

The path for the lockfile used when starting and running the node.

val processing_lockfile_path : data_dir:string -> string

The path for the lockfile used in block processing.

val gc_lockfile_path : data_dir:string -> string

The path for the lockfile used in garbage collection.

checkout_context node_ctxt block_hash returns the context at block block_hash.

val dal_supported : _ t -> bool

Returns true if the rollup node supports the DAL and if DAL is enabled for the current protocol.

val readonly : _ t -> ro

readonly node_ctxt returns a read only version of the node context node_ctxt.

type 'a delayed_write = ('a, rw) Tezos_layer2_store.Delayed_write_monad.t

Monad for values with delayed write effects in the node context.

Abstraction over store

get_history_mode t returns the current history mode for the rollup node.

Layer 2 blocks

is_processed store hash returns true if the block with hash has already been processed by the daemon.

get_l2_block t hash returns the Layer 2 block known by the rollup node for Layer 1 block hash.

Same as get_l2_block but returns None when the Layer 2 block is not available.

Same as get_l2_block but retrieves the Layer 2 block by its level.

val find_l2_block_by_level : _ t -> int32 -> Octez_smart_rollup.Sc_rollup_block.t option Tezos_base.TzPervasives.tzresult Lwt.t

Same as get_l2_block_by_level but returns None when the Layer 2 block is not available.

get_full_l2_block node_ctxt hash returns the full L2 block for L1 block hash hash. The result contains the L2 block and its content (inbox, messages, commitment).

save_level t head registers the correspondences head.level |-> head.hash in the store.

save_l2_block t l2_block remembers that the l2_block is processed. The system should not have to come back to it.

set_l2_head t l2_block sets l2_block as the new head of the L2 chain.

last_processed_head_opt store returns the last processed head if it exists.

val mark_finalized_level : rw -> int32 -> unit Tezos_base.TzPervasives.tzresult Lwt.t

mark_finalized_head store head remembers that the head is finalized. By construction, every block whose level is smaller than head's is also finalized.

val get_finalized_level : _ t -> int32 Tezos_base.TzPervasives.tzresult Lwt.t

get_finalized_level t returns the last finalized level.

get_finalized_head_opt store returns the last finalized head if it exists.

hash_of_level node_ctxt level returns the current block hash for a given level.

hash_of_level_opt is like hash_of_level but returns None if the level is not known.

level_of_hash node_ctxt hash returns the level for Tezos block hash hash if it is known by the Tezos Layer 1 node.

Returns the block header for a given hash using the L1 node.

val get_predecessor_opt : _ t -> Layer1.head -> Layer1.head option Tezos_base.TzPervasives.tzresult Lwt.t

get_predecessor_opt state head returns the predecessor of block head, when head is not the genesis block.

get_predecessor state head returns the predecessor block of head.

val get_predecessor_header_opt : _ t -> Layer1.header -> Layer1.header option Tezos_base.TzPervasives.tzresult Lwt.t

Same as get_predecessor_opt with headers.

Same as get_predecessor with headers.

val get_tezos_reorg_for_new_head : _ t -> [ `Head of Layer1.head | `Level of int32 ] -> Layer1.head -> Layer1.head Octez_crawler.Reorg.t Tezos_base.TzPervasives.tzresult Lwt.t

get_tezos_reorg_for_new_head node_ctxt old_head new_head returns the L1 reorganization between old_head and new_head.

val block_with_tick : _ t -> ?min_level:int32 -> max_level:int32 -> Z.t -> Octez_smart_rollup.Sc_rollup_block.t option Tezos_base.TzPervasives.tzresult Lwt.t

block_with_tick store ?min_level ~max_level tick returns Some b where b is the last layer 2 block which contains the tick before max_level. If no such block exists (the tick happened after max_level, or we are too late), the function returns None. Fails if the tick happened before min_level.

val tick_offset_of_commitment_period : _ t -> Octez_smart_rollup.Commitment.t -> Z.t Tezos_base.TzPervasives.tzresult Lwt.t

tick_offset_of_commitment_period node_ctxt commtient returns the global initial tick (since genesis) of the PVM for the state at the beginning of the commitment period that commitment concludes.

Commitments

get_commitment t hash returns the commitment with hash stored by the rollup node.

Same as get_commitment but returns None if this commitment hash is not known by the rollup node.

commitment_exists t hash returns true if the commitment with hash is known (i.e. stored) by the rollup node.

save_commitment t commitment saves a commitment in the store an returns is hash.

commitment_published_at_level t hash returns the levels at which the commitment was first published and the one at which it was included by in a Layer 1 block. It returns None if the commitment is not known by the rollup node or if it was never published by the rollup node (and included on L1).

save_commitment_published_at_level t hash levels saves the publication/inclusion information for a commitment with hash.

type commitment_source =
  1. | Anyone
  2. | Us

commitment_was_published t hash returns true if the commitment is known as being already published on L1. The source indicates if we want to know the publication status for commitments we published ourselves `Us or that `Anyone published.

val set_lcc : rw -> lcc -> unit Tezos_base.TzPervasives.tzresult Lwt.t

set_lcc t lcc saves the LCC both on disk and in the node context. It's written in the context iff lcc is is younger than its current value.

val register_published_commitment : rw -> Octez_smart_rollup.Commitment.t -> first_published_at_level:int32 -> level:int32 -> published_by_us:bool -> unit Tezos_base.TzPervasives.tzresult Lwt.t

register_published_commitment t c ~first_published_at_level ~level ~published_by_us saves the publishing information for commitment c both on disk and in the node context. We remember the first publication level and the level the commitment was published by us.

Inboxes

get_inbox t inbox_hash retrieves the inbox whose hash is inbox_hash from the rollup node's storage.

Same as get_inbox but returns None if this inbox is not known.

save_inbox t inbox remembers the inbox in the storage. It is associated to its hash which is returned.

inbox_of_head node_ctxt block returns the latest inbox at the given block. This function always returns inbox for all levels at and after the rollup genesis. NOTE: It requires the L2 block for block.hash to have been saved.

Same as get_inbox but uses the Layer 1 block hash for this inbox instead.

Returns messages as they are stored in the store, unsafe to use because all messages may not be present. Use Messages.get instead.

get_num_messages t witness_hash retrieves the number of messages for the inbox witness witness_hash stored by the rollup node.

save_messages t payloads_hash ~predecessor messages associates the list of messages to the payloads_hash. The payload hash must be computed by calling, e.g. Sc_rollup.Inbox.add_all_messages.

type proto_info = {
  1. proto_level : int;
    (*

    Protocol level for operations of block (can be different from L1 header value in the case of a migration block).

    *)
  2. first_level_of_protocol : bool;
    (*

    true if the level is the first of the protocol.

    *)
  3. protocol : Tezos_base.TzPervasives.Protocol_hash.t;
    (*

    Hash of the current protocol for this level.

    *)
}

Return values for protocol_of_level.

val protocol_of_level_with_store : _ Store.t -> int32 -> proto_info Tezos_base.TzPervasives.tzresult Lwt.t

protocol_of_level_with_store store level returns the protocol of block level level.

val protocol_of_level : _ t -> int32 -> proto_info Tezos_base.TzPervasives.tzresult Lwt.t

protocol_of_level t level returns the protocol of block level level.

Returns the last protocol seen by the rollup node.

Returns the activation level of a protocol or fails if the protocol was never seen by the rollup node.

val save_protocol_info : rw -> Layer1.header -> predecessor:Layer1.header -> unit Tezos_base.TzPervasives.tzresult Lwt.t

save_protocol_info t block ~predecessor saves to disk the protocol information associated to the block, if there is a protocol change between block and predecessor.

DAL

get_slot_header t ~published_in_block_hash slot_index returns the slot header for the slot_index that was published in the provided block hash on Layer 1.

get_all_slot_headers t ~published_in_block_hash returns the slot headers for all the slots that were published in the provided block hash on Layer 1.

get_slot_indexes t ~published_in_block_hash returns the slot indexes whose headers were published in the provided block hash on Layer 1.

save_slot_header t ~published_in_block_hash header saves the header as being published for its index in the provided block hash on Layer 1.

val find_slot_status : _ t -> confirmed_in_block_hash:Tezos_base.TzPervasives.Block_hash.t -> Octez_smart_rollup.Dal.Slot_index.t -> [ `Unconfirmed | `Confirmed ] option Tezos_base.TzPervasives.tzresult Lwt.t

find_slot_status t ~confirmed_in_block_hash index returns None if the slot's block is not processed yet, Some `Unconfirmed if the slot was not confirmed and Some `Confirmed if the slot is confirmed and the associated pages are available.

val list_slots_statuses : _ t -> confirmed_in_block_hash:Tezos_base.TzPervasives.Block_hash.t -> (Octez_smart_rollup.Dal.Slot_index.t * [ `Confirmed | `Unconfirmed ]) list Tezos_base.TzPervasives.tzresult Lwt.t

list_slots_statuses t ~confirmed_in_block_hash lists the list of slots indices with their respective statuses that are saved for the given confirmed_in_block_hash

val save_slot_status : rw -> Tezos_base.TzPervasives.Block_hash.t -> Octez_smart_rollup.Dal.Slot_index.t -> [ `Confirmed | `Unconfirmed ] -> unit Tezos_base.TzPervasives.tzresult Lwt.t

save_slot_status node_ctxt hash slot_index status saves in node_ctxt.store that slot_index has status status in the block with hash in node_ctxt.store.

val gc : [> `Write ] t -> level:int32 -> unit Tezos_base.TzPervasives.tzresult Lwt.t

gc node_ctxt level triggers garbage collection for the node in accordance with node_ctxt.config.gc_parameters. Upon completion, all data for L2 levels lower than level will be removed.

get_gc_levels node_ctxt returns information about the garbage collected levels.

val check_level_available : _ t -> int32 -> unit Tezos_base.TzPervasives.tzresult Lwt.t

check_level_available node_ctxt level resolves with an error if the level is before the first non garbage collected level.

val get_last_context_split_level : _ t -> int32 option Tezos_base.TzPervasives.tzresult Lwt.t
val save_context_split_level : rw -> int32 -> unit Tezos_base.TzPervasives.tzresult Lwt.t

Helpers

val make_kernel_logger : (string -> unit Lwt.t) -> ?log_kernel_debug_file:string -> string -> ((string -> unit Lwt.t) * (unit -> unit Lwt.t)) Lwt.t

make_kernel_logger event ?log_kernel_debug_file logs_dir returns two functions kernel_debug_logger and finaliser, to be used in the node context. kernel_debug_logger writes kernel logs to logs_dir/log_kernel_debug_file and emits them with the event.

Synchronization tracking

val is_synchronized : _ t -> bool

is_synchronized node_ctxt returns true iff the rollup node has processed the latest available L1 head.

val wait_synchronized : _ t -> unit Lwt.t

wait_synchronized node_ctxt is a promise that resolves when the rollup node whose state is node_ctxt is synchronized with L1. If the node is already synchronized, it resolves immediately.

module Internal_for_tests : sig ... end
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct