Module Tezos_baking_alpha.Baking_state

Consensus key type and functions

type consensus_key = {
  1. alias : string option;
  2. public_key : Tezos_base.TzPervasives.Signature.public_key;
  3. public_key_hash : Tezos_base.TzPervasives.Signature.public_key_hash;
  4. secret_key_uri : Tezos_client_base.Client_keys.sk_uri;
}
val pp_consensus_key : Stdlib.Format.formatter -> consensus_key -> unit
val pp_consensus_key_and_delegate : Stdlib.Format.formatter -> consensus_key_and_delegate -> unit

Delegates slots type and functions

type delegate_slot = {
  1. consensus_key_and_delegate : consensus_key_and_delegate;
  2. first_slot : Tezos_protocol_alpha.Protocol.Alpha_context.Slot.t;
  3. attesting_power : int;
}

A delegate slot consists of the delegate's consensus key, its public key hash, its first slot, and its attesting power at some level.

val pp_delegate_slot : Stdlib.Format.formatter -> delegate_slot -> unit
module Delegate_slots : sig ... end
type delegate_slots = Delegate_slots.t
val pp_delegate_slots : Stdlib.Format.formatter -> delegate_slots -> unit

compute_delegate_slots cctxt ?block ~level ~chain delegates computes the delegate slots of the given delegates for the level

  • parameter block

    default to `Head 0

Consensus operations types functions

type consensus_vote_kind =
  1. | Attestation
  2. | Preattestation
val pp_consensus_vote_kind : Stdlib.Format.formatter -> consensus_vote_kind -> unit

An unsigned consensus vote consists of the consensus vote kind, either an attestation or a preattestation, the delegate keys and its protocol and dal content.

type batch_content = {
  1. level : Tezos_protocol_alpha.Protocol.Alpha_context.Raw_level.t;
  2. round : Tezos_protocol_alpha.Protocol.Alpha_context.Round.t;
  3. block_payload_hash : Tezos_protocol_alpha.Protocol.Block_payload_hash.t;
}

A batch content contains information common to all consensus operation in a batch of consensus votes.

type unsigned_consensus_vote_batch = private {
  1. batch_kind : consensus_vote_kind;
  2. batch_content : batch_content;
  3. batch_branch : Tezos_base.TzPervasives.Block_hash.t;
  4. unsigned_consensus_votes : unsigned_consensus_vote list;
}

An unsigned consensus batch consists of a batch kind: either preattestations or attestations, a batch content and a batch branch. These values should be common to each operations in the batch. This type also contains the list of unsigned consensus votes.

make_unsigned_consensus_vote_batch kind batch_content ~batch_branch delegates_and_slots maps the delegates_and_slots list to create a list of unsigned_consensus_vote that is then included in an unsigned_consensus_vote_batch with kind, batch_content and batch_branch. Note: dal_content of each operations is set to None, dal_content_map_p needs to be called to update the dal_content field.

val dal_content_map_p : (unsigned_consensus_vote -> Tezos_protocol_alpha.Protocol.Alpha_context.dal_content option Tezos_base.TzPervasives.tzresult Lwt.t) -> unsigned_consensus_vote_batch -> unsigned_consensus_vote_batch Lwt.t

dal_content_map_p f unsigned_consensus_vote_batch map each unsigned_consensus_vote in the batch with f.

type signed_consensus_vote = {
  1. unsigned_consensus_vote : unsigned_consensus_vote;
  2. signed_operation : Tezos_protocol_alpha.Protocol.Alpha_context.packed_operation;
}

A signed consensus vote consists of an unsigned consensus vote and its packed version signed.

type signed_consensus_vote_batch = private {
  1. batch_kind : consensus_vote_kind;
  2. batch_content : batch_content;
  3. batch_branch : Tezos_base.TzPervasives.Block_hash.t;
  4. signed_consensus_votes : signed_consensus_vote list;
}

Similar to unsigned_consensus_vote_batch type but the list of the operation are signed consensus votes.

make_signed_consensus_vote_batch batch_kind batch_content ~batch_branch signed_consensus_votes creates a signed_consensus_vote_batch. This function raises an error if the batch is ill-formed:

  • batch consensus vote has a different kind than batch_kind
  • batch consensus vote has a different level than the one in batch_content
  • batch consensus vote has a different round than the one in batch_content
  • batch consensus vote has a different block hash payload than the one in batch_content
  • kind is Preattestation and a batch consensus vote contains a dal_content.
val make_singleton_consensus_vote_batch : signed_consensus_vote -> signed_consensus_vote_batch

make_singleton_consensus_vote_batch signed_consensus_vote similar to make_signed_consensus_vote_batch but creates a batch with only one operation.

Block info types and functions

A prequorum consists of a level, a round, a block_payload_hash and the list of preattestations that has a total voting power higher than the protocol threshold.

val pp_block_info : Stdlib.Format.formatter -> block_info -> unit

Proposal type and functions

type proposal = {
  1. block : block_info;
  2. predecessor : block_info;
}

A proposal consists of information about the current block proposal and its predecessor.

val pp_proposal : Stdlib.Format.formatter -> proposal -> unit

Elected block type and functions

An elected block is a proposal where the quorum has been reached. The type consists of the proposal and the quorum proof ie. an attestation list where the total voting power of the operation is higher than the protocol threshold.

val pp_elected_block : Stdlib.Format.formatter -> elected_block -> unit
val is_first_block_in_protocol : proposal -> bool

Identify the first block of the protocol, ie. the block that activates the current protocol.

This block should be baked by the baker of the previous protocol (that's why this same block is also referred to as the last block of the previous protocol). It is always considered final and therefore is not attested.

Locked_round type and functions

A locked round is the last block attested by the baker.

val pp_locked_round : Stdlib.Format.formatter -> locked_round -> unit

Attestable_payload type and functions

type attestable_payload = {
  1. proposal : proposal;
  2. prequorum : prequorum;
}

An attestable payload is a proposal on which the prequorum has been reached.

val pp_attestable_payload : Stdlib.Format.formatter -> attestable_payload -> unit

Level_state type and functions

type level_state = {
  1. current_level : int32;
  2. latest_proposal : proposal;
    (*

    latest validated block by the node that the baker work on.

    *)
  3. is_latest_proposal_applied : bool;
    (*

    true when the proposal, validated by the block has also been applied.

    *)
  4. locked_round : locked_round option;
    (*

    Has value when the baker have attested the current proposal

    *)
  5. attestable_payload : attestable_payload option;
    (*

    Has value when a pqc has been reached on a previous or current round.

    *)
  6. elected_block : elected_block option;
    (*

    A quorum has been reached on an applied proposal.

    *)
  7. delegate_slots : delegate_slots;
    (*

    Delegate slots for the baker delegates at the current level

    *)
  8. next_level_delegate_slots : delegate_slots;
    (*

    Delegate slots for the baker delegates at the next level

    *)
  9. next_level_proposed_round : Tezos_protocol_alpha.Protocol.Alpha_context.Round.t option;
    (*

    Some if a proposal has been injected for the next level on the given round

    *)
  10. dal_attestable_slots : dal_attestable_slots;
    (*

    For each (own) delegate having a DAL slot at the current level, store a promise to obtain the attestable slots for that level.

    *)
  11. next_level_dal_attestable_slots : dal_attestable_slots;
    (*

    and similarly for the next level

    *)
}

A level state consists of all usefull information regarding the current level such as the latest proposal, its status, the delegate slots, etc.

val pp_level_state : Stdlib.Format.formatter -> level_state -> unit

Round_state type and functions

type phase =
  1. | Idle
  2. | Awaiting_preattestations
  3. | Awaiting_attestations
  4. | Awaiting_application
val pp_phase : Stdlib.Format.formatter -> phase -> unit
type round_state = {
  1. current_round : Tezos_protocol_alpha.Protocol.Alpha_context.Round.t;
  2. current_phase : phase;
  3. delayed_quorum : Tezos_protocol_alpha.Protocol.Alpha_context.Kind.attestation Tezos_protocol_alpha.Protocol.Alpha_context.operation list option;
    (*

    Has value when the Quorum has been reached but the current proposal has not yet been applied

    *)
  4. early_attestations : signed_consensus_vote list;
    (*

    Attestations ready for injection before the prequorum has been reached

    *)
  5. awaiting_unlocking_pqc : bool;
    (*

    Used to avoid preattesting reproposal if its round is lower than the one we are locked on

    *)
}

A round state consists of information related to the current round phase

val pp_round_state : Stdlib.Format.formatter -> round_state -> unit

Forge types and functions

type block_kind =
  1. | Fresh of Operation_pool.pool
    (*

    A Fresh proposal contains the list its operations.

    *)
  2. | Reproposal of {
    1. consensus_operations : Tezos_protocol_alpha.Protocol.Alpha_context.packed_operation list;
    2. payload_hash : Tezos_protocol_alpha.Protocol.Block_payload_hash.t;
    3. payload_round : Tezos_protocol_alpha.Protocol.Alpha_context.Round.t;
    4. payload : Operation_pool.payload;
    }
    (*

    A Reproposal contains the consensus_operations as a proof that the prequorum was reached for this proposal. It also contains information about the payload of the previous proposal.

    *)

A block kind is either a reproposal of a proposal that has reached a prequorum, or a fresh block.

type block_to_bake = {
  1. predecessor : block_info;
  2. round : Tezos_protocol_alpha.Protocol.Alpha_context.Round.t;
  3. delegate : consensus_key_and_delegate;
    (*

    Delegate that have the right to bake the block.

    *)
  4. kind : block_kind;
    (*

    Either a reproposal or a fresh proposal

    *)
  5. force_apply : bool;
    (*

    if true, while baking the block, try and apply the block and its operations instead of only validating them. This can be set using the --force-apply-from-round flag (see force_apply_from_round_arg in baking_commands.ml).

    *)
}
type forge_request =
  1. | Forge_and_sign_block of block_to_bake
  2. | Forge_and_sign_preattestations of {
    1. unsigned_preattestations : unsigned_consensus_vote_batch;
    }
  3. | Forge_and_sign_attestations of {
    1. unsigned_attestations : unsigned_consensus_vote_batch;
    }

forge_request type used to push a concurrent forging task in the forge worker.

prepared_block type returned by the forge worker and that contains all information useful for block injection.

val pp_prepared_block : Stdlib.Format.formatter -> prepared_block -> unit
type forge_event =
  1. | Block_ready of prepared_block
  2. | Preattestation_ready of signed_consensus_vote
  3. | Attestation_ready of signed_consensus_vote

forge_event type used to return the result of a task completion in the forge worker.

val pp_forge_event : Stdlib.Format.formatter -> forge_event -> unit
type forge_worker_hooks = {
  1. push_request : forge_request -> unit;
  2. get_forge_event_stream : unit -> forge_event Lwt_stream.t;
  3. cancel_all_pending_tasks : unit -> unit;
}

forge_worker_hooks type that allows interactions with the forge worker. Hooks are needed in order to break a circular dependency.

Global_state types and functions

type validation_mode =
  1. | Node
  2. | Local of Abstract_context_index.t

The validation mode specifies whether the baker (filters and) validates mempool operations via an RPC to the node, or if it does so "locally", by using the context.

val pp_validation_mode : Stdlib.Format.formatter -> validation_mode -> unit

Caches of timestamps

val create_cache : unit -> cache

A global state contains all information related to the chain and baker configuration.

val pp_global_state : Stdlib.Format.formatter -> global_state -> unit
type state = {
  1. global_state : global_state;
  2. level_state : level_state;
  3. round_state : round_state;
}
type t = state
val pp : Stdlib.Format.formatter -> t -> unit
val update_current_phase : t -> phase -> t

update_current_phase t new_phase updates the round state in t with the new_phase.

val round_proposer : state -> level:[ `Current | `Next ] -> Tezos_protocol_alpha.Protocol.Alpha_context.Round.t -> delegate_slot option

Returns, among our *own* delegates, the delegate (and its attesting slot) that has a proposer slot at the given round and the current or next level, if any.

Memoization wrapper for Round.timestamp_of_round.

From the current state, the function returns an optional association pair, which consists of the next round timestamp and its round.

Timeout type and functions

type timeout_kind =
  1. | End_of_round of {
    1. ending_round : Tezos_protocol_alpha.Protocol.Alpha_context.Round.t;
    }
  2. | Time_to_prepare_next_level_block of {
    1. at_round : Tezos_protocol_alpha.Protocol.Alpha_context.Round.t;
    }

timeout kind is either a timeout triggered at the end of a round or a timeout triggered when it is time to prepare the block at the next level.

val pp_timeout_kind : Stdlib.Format.formatter -> timeout_kind -> unit

State_data type and functions

val record_state : t -> unit Tezos_base.TzPervasives.tzresult Lwt.t

record_state t writes the current level, the locked round and the attestable payload to the disk.

val may_record_new_state : previous_state:t -> new_state:t -> unit Tezos_base.TzPervasives.tzresult Lwt.t

may_record_new_state ~previous_state ~new_state Does nothing if the baker configuration is set to Baking_configuration.state_recorder_config.Memory only. Otherwise, check that information from the new_state are consistent with previous_state and if the information has been updated, record the new_state to the disk.

type state_data = {
  1. level_data : int32;
  2. locked_round_data : locked_round option;
  3. attestable_payload_data : attestable_payload option;
}

type used for data recorded on disk.

load_attestable_data cctxt location tries to load the state_data from the cctxt at location, returns None if the file does not exists.

val may_load_attestable_data : t -> t Tezos_base.TzPervasives.tzresult Lwt.t

may_load_attestable_data t tries to load locked round and attestable payload from t if it is recorded, if not, return the state.

Event type and functions

Event type used in the baking_scheduling to trigger state transition.

val pp_event : Stdlib.Format.formatter -> event -> unit
val pp_short_event : Stdlib.Format.formatter -> event -> unit