tezos-protocol-016-PtMumbai 20.1

Parameters

module Context : P

Signature

include Sc_rollup_PVM_sig.S
  with type context = Context.Tree.t
  with type state = Context.tree
  with type proof = Context.proof

type state = Context.tree

The state of the PVM denotes a state of the rollup.

The life cycle of the PVM is as follows. It starts its execution from an initial_state. The initial state is specialized at origination with a boot_sector, using the install_boot_sector function. The resulting state is call the “genesis” of the rollup.

Afterwards, we classify states into two categories: "internal states" do not require any external information to be executed while "input states" are waiting for some information from the inbox to be executable.

type context = Context.Tree.t

A context represents the executable environment needed by the state to exist. Typically, the rollup node storage can be part of this context to allow the PVM state to be persistent.

type hash = Sc_rollup_repr.State_hash.t

A hash characterizes the contents of a state.

type proof = Context.proof

During interactive refutation games, a player may need to provide a proof that a given execution step is valid. The PVM implementation is responsible for ensuring that this proof type has the correct semantics.

A proof p has four parameters:

start_hash := proof_start_state p
stop_hash := proof_stop_state p
input_requested := proof_input_requested p
input_given := proof_input_given p

The following predicate must hold of a valid proof:

exists start_state, stop_state. (state_hash start_state == start_hash) AND (Option.map state_hash stop_state == stop_hash) AND (is_input_state start_state == input_requested) AND (match (input_given, input_requested) with | (None, No_input_required) -> eval start_state == stop_state | (None, Initial) -> stop_state == None | (None, First_after (l, n)) -> stop_state == None | (Some input, No_input_required) -> true | (Some input, Initial) -> set_input input_given start_state == stop_state | (Some input, First_after (l, n)) -> set_input input_given start_state == stop_state)

In natural language---the two hash parameters start_hash and stop_hash must have actual state values (or possibly None in the case of stop_hash) of which they are the hashes. The input_requested parameter must be the correct request from the start_hash, given according to is_input_state. Finally there are four possibilities of input_requested and input_given.

if no input is required, or given, the proof is a simple eval step ;
if input was required but not given, the stop_hash must be None (the machine is blocked) ;
if no input was required but some was given, this makes no sense and it doesn't matter if the proof is valid or invalid (this case will be ruled out by the inbox proof anyway) ;
finally, if input was required and given, the proof is a set_input step.

val proof_encoding : 
  proof Tezos_protocol_environment_016_PtMumbai.Data_encoding.t

proofs are embedded in L1 refutation game operations using proof_encoding. Given that the size of L1 operations are limited, it is of *critical* importance to make sure that no execution step of the PVM can generate proofs that do not fit in L1 operations when encoded. If such a proof existed, the rollup could get stuck.

val proof_start_state : proof -> hash

proof_start_state proof returns the initial state hash of the proof execution step.

val proof_stop_state : proof -> hash

proof_stop_state proof returns the final state hash of the proof execution step.

val state_hash : state -> hash Tezos_protocol_environment_016_PtMumbai.Lwt.t

state_hash state returns a compressed representation of state.

val initial_state : 
  empty:state ->
  state Tezos_protocol_environment_016_PtMumbai.Lwt.t

initial_state ~empty is the initial state of the PVM, before its specialization with a given boot_sector. The initial state is built on the empty state which must be provided.

val install_boot_sector : 
  state ->
  string ->
  state Tezos_protocol_environment_016_PtMumbai.Lwt.t

install_boot_sector state boot_sector specializes the initial state of a PVM using a dedicated boot_sector, submitted at the origination of the rollup.

val is_input_state : 
  state ->
  Sc_rollup_PVM_sig.input_request Tezos_protocol_environment_016_PtMumbai.Lwt.t

is_input_state state returns the input expectations of the state---does it need input, and if so, how far through the inbox has it read so far?

val set_input : 
  Sc_rollup_PVM_sig.input ->
  state ->
  state Tezos_protocol_environment_016_PtMumbai.Lwt.t

set_input input state sets input in state as the next input to be processed. This must answer the input_request from is_input_state state.

val eval : state -> state Tezos_protocol_environment_016_PtMumbai.Lwt.t

eval s0 returns a state s1 resulting from the execution of an atomic step of the rollup at state s0.

val verify_proof : 
  Sc_rollup_PVM_sig.input option ->
  proof ->
  Sc_rollup_PVM_sig.input_request
    Tezos_protocol_environment_016_PtMumbai.Error_monad.tzresult
    Tezos_protocol_environment_016_PtMumbai.Lwt.t

verify_proof input p checks the proof p with input input and returns the input_request before the evaluation of the proof. See the doc-string for the proof type.

verify_proof input p fails when the proof is invalid in regards to the given input.

val produce_proof : 
  context ->
  Sc_rollup_PVM_sig.input option ->
  state ->
  proof Tezos_protocol_environment_016_PtMumbai.Error_monad.tzresult
    Tezos_protocol_environment_016_PtMumbai.Lwt.t

produce_proof ctxt input_given state should return a proof for the PVM step starting from state, if possible. This may fail for a few reasons:

the input_given doesn't match the expectations of state ;
the context for this instance of the PVM doesn't have access to enough of the state to build the proof.

val verify_origination_proof : 
  proof ->
  string ->
  bool Tezos_protocol_environment_016_PtMumbai.Lwt.t

verify_origination_proof proof boot_sector verifies a proof supposedly generated by produce_origination_proof.

val produce_origination_proof : 
  context ->
  string ->
  proof Tezos_protocol_environment_016_PtMumbai.Error_monad.tzresult
    Tezos_protocol_environment_016_PtMumbai.Lwt.t

produce_origination_proof context boot_sector produces a proof p covering the specialization of a PVM, from the initial_state up to the genesis state wherein the boot_sector has been installed.

type output_proof

The following type is inhabited by the proofs that a given output is part of the outbox of a given state.

val output_proof_encoding : 
  output_proof Tezos_protocol_environment_016_PtMumbai.Data_encoding.t

output_proof_encoding encoding value for output_proofs.

val output_of_output_proof : output_proof -> Sc_rollup_PVM_sig.output

output_of_output_proof proof returns the output that is referred to in proof's statement.

val state_of_output_proof : output_proof -> hash

state_of_output_proof proof returns the state hash that is referred to in proof's statement.

val verify_output_proof : 
  output_proof ->
  bool Tezos_protocol_environment_016_PtMumbai.Lwt.t

verify_output_proof output_proof returns true iff proof is a valid witness that its output is part of its state's outbox.

val produce_output_proof : 
  context ->
  state ->
  Sc_rollup_PVM_sig.output ->
  (output_proof, Tezos_protocol_environment_016_PtMumbai.Error_monad.error)
    Tezos_protocol_environment_016_PtMumbai.Pervasives.result
    Tezos_protocol_environment_016_PtMumbai.Lwt.t

produce_output_proof ctxt state output returns a proof that witnesses the fact that output is part of state's outbox.

val check_dissection : 
  default_number_of_sections:int ->
  start_chunk:Sc_rollup_dissection_chunk_repr.t ->
  stop_chunk:Sc_rollup_dissection_chunk_repr.t ->
  Sc_rollup_dissection_chunk_repr.t list ->
  unit Tezos_protocol_environment_016_PtMumbai.Error_monad.tzresult

check_dissection ~default_number_of_sections ~start_chunk ~stop_chunk chunks fails if the dissection encoded by the list [start_chunk] @ chunks @ [stop_chunk] does not satisfy the properties expected by the PVM.

val get_current_level : 
  state ->
  Raw_level_repr.t option Tezos_protocol_environment_016_PtMumbai.Lwt.t

get_current_level state returns the current level of the state, returns None if it is not possible to compute the level.

module Internal_for_tests : sig ... end

val parse_boot_sector : string -> string option

parse_boot_sector s builds a boot sector from its human writable description.

val pp_boot_sector : 
  Tezos_protocol_environment_016_PtMumbai.Format.formatter ->
  string ->
  unit

pp_boot_sector fmt s prints a human readable representation of a boot sector.

val pp : 
  state ->
  (Tezos_protocol_environment_016_PtMumbai.Format.formatter ->
    unit ->
    unit)
    Tezos_protocol_environment_016_PtMumbai.Lwt.t

pp state returns a pretty-printer valid for state.

val get_tick : 
  state ->
  Sc_rollup_tick_repr.t Tezos_protocol_environment_016_PtMumbai.Lwt.t

get_tick state returns the current tick of state.

type status =

| Halted
| Waiting_for_input_message
| Waiting_for_reveal
| Waiting_for_metadata
| Parsing
| Evaluating

The machine has five possible statuses:

val get_status : state -> status Tezos_protocol_environment_016_PtMumbai.Lwt.t

get_status state returns the machine status in state.

val get_outbox : 
  Raw_level_repr.t ->
  state ->
  Sc_rollup_PVM_sig.output list Tezos_protocol_environment_016_PtMumbai.Lwt.t

get_outbox outbox_level state returns the outbox in state for a given outbox_level.

type instruction =

| IPush : int -> instruction
| IAdd : instruction
| IStore : string -> instruction

The machine has only three instructions.

val equal_instruction : instruction -> instruction -> bool

equal_instruction i1 i2 is true iff i1 equals i2.

val pp_instruction : 
  Tezos_protocol_environment_016_PtMumbai.Format.formatter ->
  instruction ->
  unit

pp_instruction fmt i shows a human readable representation of i.

val get_parsing_result : 
  state ->
  bool option Tezos_protocol_environment_016_PtMumbai.Lwt.t

get_parsing_result state is Some true if the current message is syntactically correct, Some false when it contains a syntax error, and None when the machine is not in parsing state.

val get_code : 
  state ->
  instruction list Tezos_protocol_environment_016_PtMumbai.Lwt.t

get_code state returns the current code obtained by parsing the current input message.

val get_stack : state -> int list Tezos_protocol_environment_016_PtMumbai.Lwt.t

get_stack state returns the current stack.

val get_var : 
  state ->
  string ->
  int option Tezos_protocol_environment_016_PtMumbai.Lwt.t

get_var state x returns the current value of variable x. Returns None if x does not exist.

val get_evaluation_result : 
  state ->
  bool option Tezos_protocol_environment_016_PtMumbai.Lwt.t

get_evaluation_result state returns Some true if the current message evaluation succeeds, Some false if it failed, and None if the evaluation has not been done yet.

val get_is_stuck : 
  state ->
  string option Tezos_protocol_environment_016_PtMumbai.Lwt.t

get_is_stuck state returns Some err if some internal error made the machine fail during the last evaluation step. None if no internal error occurred. When a machine is stuck, it reboots, waiting for the next message to process.

package tezos-protocol-016-PtMumbai

Parameters

Signature