package tezos-protocol-014-PtKathma

  1. Overview
  2. Docs
package tezos-protocol-014-PtKathma
Legend:
Library
Module
Module type
Parameter
Class
Class type
type t

The state of a transaction rollup is a set of variables whose values vary in time, as the rollup progresses.

val initial_state : pre_allocated_storage:Tezos_protocol_environment_014_PtKathma.Z.t -> t

initial_state pre_allocated_storage returns the initial state of a transaction rollup (after its origination) with pre_allocated_storage bytes of storage already paid for.

val update_burn_per_byte : t -> elapsed:int -> factor:int -> final_size:int -> hard_limit:int -> t

update_burn_per_byte state ~elapsed ~factor ~final_size ~hard_limit updates the cost per byte to be paid for each message submitted to the rollup. This is done by computing a moving average for factor snapshots. Each snapshot being the size of the total messages for the rollup. Hence each snapshot contributes to 1/(1 + factor) to the average.

It may happen that the rollup does not receive any message for some period of time. The parameter elapsed allows that to be taken into account. If elapsed=n with n>=1 it is similar as if update_burn_per_byte was called n times with final_size=0.

Once the exponential moving average ema is computed, we use the hard limit to know whether the cost per byte should be updated:

1. If ema <= 80 then the cost per byte is decreased

2. If 80 < ema <= 90 then the cost per byte is stable

3. If 90 < ema then the cost ber byte is increased

The rationale behind this mechanics is to adapt the cost of a transactional rollup depending on its activity. This can be used to prevent from some spamming attacks.

burn_cost ~limit state size computes the burn to be paid to submit size bytes in the inbox of the transactional rollup.

Returns Tx_rollup_submit_batch_burn_exceeded if the (computed) burn exceeds limit.

val has_valid_commitment_at : t -> Tx_rollup_level_repr.t -> bool

has_valid_commitment_at state level returns true iff there is a valid commitment for level in the layer-1 storage.

On the contrary, if there is not commitment for level in the layer-1 storage, or if there exists an orphan commitment (that is, a commitment which has been rejected, or with one of its ancestors that has been rejected) at level, this function returns false.

val uncommitted_inboxes_count : t -> int

uncommitted_inboxes_count state returns the number of inboxes the rollup current has in the storage which did not receive a commitment yet.

val commitments_count : t -> int

commitments_count t returns the number of commitment still in the layer-1 context.

val inboxes_count : t -> int

inboxes_count state returns the number of inboxes the rollup current has in the storage.

val next_commitment_to_finalize : t -> Tx_rollup_level_repr.t option

next_commitment_to_finalize state returns the rollup level of the next commitment to be finalized.

val next_commitment_to_remove : t -> Tx_rollup_level_repr.t option

next_commitment_to_remove state returns the rollup level of the next commitment to be removed from the layer-1 context.

val finalized_commitment_oldest_level : t -> Tx_rollup_level_repr.t option

finalized_commitment_oldest_level state returns the rollup level of the oldest finalized commitment.

next_commitment_level current_level state returns the expected level of the next valid commitment.

This function can return the error No_uncommitted_inbox if there is no inbox awaiting a commitment.

val next_commitment_predecessor : t -> Tx_rollup_commitment_repr.Hash.t option

next_commitment_predecessor state returns the expected predecessor hash of the next valid commitment.

record_inbox_creation state level updates the state of a rollup to take into account the creation of of a new inbox at the given Tezos level, and returns the rollup level to associate to this inbox and the number of bytes allocated for the inbox.

This function may return an Internal_error iff an inbox has already been created at a level greater (or equal) than level. It is the responsibility of the caller to avoid that.

record_inbox_deletion state level updates state to take into account the deletion of the inbox stored at Tezos level from the storage.

This function returns an Internal_error iff there is no inbox in the storage of the layer-1, or if level is not the oldest level of rollup.

record_commitment_creation state level updates state to take into account the creation of a commitment at a given Tezos level.

This function returns an Internal_error if level is not the successor level of the current commitment head, or if level is greater than the inbox head.

record_commitment_rejection state level pred_hash updates state to take into account the fact that the commitment for the inbox at level has been rejected.

The caller is expected to provide the predecessor hash the next valid commitment needs to use. It can be omitted under two circumstances: if level = root, or if the commitment identified by pred_hash is no longer in the layer-1 context.

record_commitment_deletion state level msg_hash commitment_hash updates state to take into account the deletion of a commitment at a given rollup level, and of given commitment_hash and whose last message commitment is msg_hash.

This function returns an Internal_error if level is not the commitment tail, that is the oldest finalized commitment.

val finalized_commitments_range : t -> (Tx_rollup_level_repr.t * Tx_rollup_level_repr.t) option

finalized_commitments_range state returns the window of finalized commitments that have not yet been cleaned out

This function returns an Internal_error if the state is inconsistent, which should not be possible.

check_level_can_be_rejected state level raises Cannot_reject_level iff there does not exist a commitment at level that is not yet finalized.

val last_removed_commitment_hashes : t -> (Tx_rollup_message_result_hash_repr.t * Tx_rollup_commitment_repr.Hash.t) option

last_removed_commitment_hashes state returns two hashes associated to the last removed commitment: the message result hash and the last commitment hash.

val head_levels : t -> (Tx_rollup_level_repr.t * Raw_level_repr.t) option

head_levels state returns the level of the last inbox which has been created in the layer-1 context, along with the Tezos level at which said inbox has been created.

adjust_storage_allocation state ~delta accounts for a change in delta number of bytes used storage space by a transaction rollup.

A positive delta indicates that the occupied storage of the rollup increased. A negative delta indicates that the occupied storage of the rollup decreased.

Along with an updated state, a diff of storage space is returned. The diff is max(0, allocated_storage - (occupied_storage + delta)). That is, 0 if no new storage was allocated, and the number of bytes allocated otherwise.

This function returns Tx_rollup_errors.Internal_error if submitted delta would make occupied_storage negative.

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