package tezos-protocol-014-PtKathma

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

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.

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.

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.

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

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

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

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

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

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.

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.

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.

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

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.