Dal_attestations_repr (tezos-protocol-alpha.Tezos_raw_protocol_alpha.Dal_attestations

Overview

This module extends Dal_attestation_repr to handle multiple DAL attestations at different lags. A lag represents the difference between the attested level of a slot and its published level.

The structure stores a fixed number of attestations, determined by number_of_lags. Each attestation is indexed by lag_index (0-based) and is a bitset encoding which slots are attested at a particular level. The slots' (published) level is implicit (it is obtained as "attested level" minus the lag corresponding to the given lag index), and is not relevant for this module.

Encoding

The encoding uses a compact bitset representation that minimizes space when small slot indices are attested:

Bitset structure

The bitset is stored as an integer, with bit positions starting at 0 (LSB). The structure is:

Prefix (number_of_lags bits at positions 0 to number_of_lags-1): Indicates which attestations are non-empty. Bit i corresponds to lag index i. If bit i = 1, the attestation at lag index i is non-empty. We call this a "prefix" because it logically comes first in the structure, even though it occupies the lowest bit positions.

Data section (starting at bit position number_of_lags): For each non-empty attestation (in order from lag index 0 to number_of_lags-1), a sequence of 8-bit chunks is stored:
bit 0 of each chunk is an is_last flag (1 iff this is the last chunk for the current lag).
bits 1..7 encode slots, with the first chunk covering slots 0..6, the next chunk slots 7..13, etc. Empty attestations are not stored in the data section.

Empty case: An empty bitset (value 0) represents the case where all attestations are empty.

Example

For number_of_lags = 4 and number_of_slots = 160:

Attestation at lag index 0: empty
Attestation at lag index 1: slots 1 and 5 attested
Attestation at lag index 2: empty
Attestation at lag index 3: slots 0 and 11 attested

The prefix has bits 1 and 3 set. The data section contains:

Lag 1: one chunk (is_last=1) with slot bits for 0..6, where 1 and 5 are set.
Lag 3: two chunks with slot bits for 0..6 and 7..13 respectively, where 0 and 11 are set.

00100001 00000010 01000101    1010
<- lag 3 data --> <-lag 1>    <-->
  (16 bits)       (8 bits)    prefix
  slots 0, 11     slots 1, 5  lags 1, 3

The order of the bits is:

[slot13]...[slot7][is_last] [slot6]...[slot0][is_last] [slot6]...[slot0][is_last] [lag3]...[lag0]
<-------------- lag 3 data (2 chunks) ---------------> <---- lag 1 (1 chunk) ---> <-- prefix --->

type t = private Tezos_protocol_environment_alpha.Bitset.t

val encoding : t Tezos_protocol_environment_alpha.Data_encoding.t

The size of the encoding is not bounded. However, the size of a DAL attestations bitset is checked during validation of an attestation; and there is a bound on the size of a generic operation.

val rpc_arg : t Tezos_protocol_environment_alpha.RPC_arg.t

RPC path argument for parsing a DAL attestation bitset from a decimal integer string in URL paths.

val empty : t

empty returns an empty attestation structure where all slots at all lags are marked as unavailable.

val is_empty : t -> bool

is_empty t returns true if all attestations at all lags are empty.

val is_empty_at_lag_index : t -> lag_index:int -> bool

is_empty_at_lag_index t returns true if the attestation at lag_index is empty.

val is_attested : 
  t ->
  number_of_slots:int ->
  number_of_lags:int ->
  lag_index:int ->
  Dal_slot_index_repr.t ->
  bool

is_attested t ~number_of_slots ~number_of_lags ~lag_index slot_index returns true if the attestation at lag_index commits that the slot at slot_index is available. lag_index must satisfy 0 <= lag_index < number_of_lags, and slot_index must satisfy 0 <= slot_index < number_of_slots.

type unfolded_lag_attestation = {

lag_index : int;
slot_indices : int list;

}

The decoded representation of the slots attested for a given lag_index.

val unfolded_lag_attestation_encoding : 
  unfolded_lag_attestation Tezos_protocol_environment_alpha.Data_encoding.t

val decode : 
  t ->
  number_of_slots:int ->
  number_of_lags:int ->
  unfolded_lag_attestation list
    Tezos_protocol_environment_alpha.Error_monad.tzresult

decode t ~number_of_slots ~number_of_lags decodes the attestation bitset t into an explicit representation. Returns a list of unfolded_lag_attestation, one entry per non-empty lag, in increasing lag order. slot_indices contains the attested slot indices for that lag, in increasing order. Empty lags are omitted from the result. Fails with Dal_invalid_attestation_bitset if t is malformed.

val commit : 
  t ->
  number_of_slots:int ->
  number_of_lags:int ->
  lag_index:int ->
  Dal_slot_index_repr.t ->
  t

commit t ~number_of_slots ~number_of_lags ~lag_index slot_index commits into the attestation at lag_index that the slot slot_index is available. lag_index must satisfy 0 <= lag_index < number_of_lags, and slot_index must satisfy 0 <= slot_index < number_of_slots.

val occupied_size_in_bits : t -> int

occupied_size_in_bits v returns the size in bits of v.

val expected_max_size_in_bits : 
  number_of_slots:int ->
  number_of_lags:int ->
  int

expected_max_size_in_bits ~number_of_slots ~number_of_lags returns the maximum size (in bits) of a t value.

val weight : t -> int

type attestation = t

Type alias for use in submodules.

module Slot_availability : sig ... end

Slot availability represents the protocol's attestation result for a block.

module Accountability : sig ... end

This module is used to record the shard attestations.

module Dal_dependent_signing : sig ... end

t-dependent combination of public keys or signatures.

module Internal_for_tests : sig ... end