From 22b96972f2ef806b2551eca34b4d509c2737c04b Mon Sep 17 00:00:00 2001 From: Hai Nguyen Van Date: Fri, 28 Jan 2022 14:46:51 +0100 Subject: [PATCH] Protocol: Document datatypes and interfaces --- src/proto_alpha/lib_protocol/amendment.mli | 32 +++++++-- .../lib_protocol/contract_storage.mli | 5 ++ src/proto_alpha/lib_protocol/main.mli | 6 +- .../lib_protocol/operation_repr.mli | 71 +++++++++++++++++++ src/proto_alpha/lib_protocol/raw_context.mli | 19 +++++ .../lib_protocol/stake_storage.mli | 3 + .../lib_protocol/storage_functors.mli | 3 + .../lib_protocol/voting_period_repr.mli | 2 +- .../lib_protocol/voting_period_storage.mli | 3 + 9 files changed, 137 insertions(+), 7 deletions(-) diff --git a/src/proto_alpha/lib_protocol/amendment.mli b/src/proto_alpha/lib_protocol/amendment.mli index 2bfc0326cc31..d13065f8522f 100644 --- a/src/proto_alpha/lib_protocol/amendment.mli +++ b/src/proto_alpha/lib_protocol/amendment.mli @@ -23,7 +23,10 @@ (* *) (*****************************************************************************) -(** Only delegates with at least one roll take part in the amendment +(** + Amendments and proposals. + + Only delegates with at least one roll take part in the amendment procedure. It works as follows: - Proposal period: delegates can submit protocol amendment @@ -39,9 +42,12 @@ period. Otherwise we go back to a proposal period. In any case, if there is enough participation the quorum is updated. - - Cooldown period: Nothing happens, this period is only a time gap - between exploration and promotion periods. At the end of a cooldown - period we move to a promotion period. + - Cooldown period: business as usual for the main chain. This + period is only a time gap between exploration and promotion + periods intended to provide the community with extra time to + continue testing the new protocol proposal, and start adapting + their infrastructure in advance. At the end of the Cooldown + period we move to the Promotion period. - Promotion period: delegates can cast votes to promote or not the proposal using the ballot operation. At the end of a promotion @@ -51,7 +57,16 @@ participation the quorum is updated. - Adoption period: At the end of an adoption period, the proposal - is activated as the new protocol. *) + is activated as the new protocol. + + The current protocol parameters are documented in + src/proto_alpha/lib_parameters/default_parameters.ml + + In practice, the real constants used are defined in the + migration code. In src/proto_alpha/lib_protocol/init_storage.ml, + function [prepare_first_block] introduces new constants and + redefines the existing ones. +*) open Alpha_context @@ -71,6 +86,13 @@ type error += | Unauthorized_ballot | Duplicate_ballot +(** Records a vote for a delegate if the current voting period is + Exploration or Promotion. + @raise Invalid_proposal if [proposal] ≠ [current_proposal]. + @raise Duplicate_ballot if delegate already voted. + @raise Unauthorized_ballot if delegate is not listed to vote, + or if current period differs from Exploration or Promotion. +*) val record_ballot : context -> public_key_hash -> diff --git a/src/proto_alpha/lib_protocol/contract_storage.mli b/src/proto_alpha/lib_protocol/contract_storage.mli index ed8a89f02d09..3b095669014d 100644 --- a/src/proto_alpha/lib_protocol/contract_storage.mli +++ b/src/proto_alpha/lib_protocol/contract_storage.mli @@ -23,6 +23,9 @@ (* *) (*****************************************************************************) +(** Low-level handlers of raw contexts for base operations on + contracts. *) + type error += | (* `Branch *) Counter_in_the_future of Contract_repr.contract * Z.t * Z.t @@ -65,6 +68,8 @@ val check_counter_increment : val increment_counter : Raw_context.t -> Signature.Public_key_hash.t -> Raw_context.t tzresult Lwt.t +(** [get_balance c contract] returns the balance of [contract] given raw + context [c]. *) val get_balance : Raw_context.t -> Contract_repr.t -> Tez_repr.t tzresult Lwt.t val get_balance_carbonated : diff --git a/src/proto_alpha/lib_protocol/main.mli b/src/proto_alpha/lib_protocol/main.mli index d90b5c1675c8..9ae17e0b2baf 100644 --- a/src/proto_alpha/lib_protocol/main.mli +++ b/src/proto_alpha/lib_protocol/main.mli @@ -41,7 +41,11 @@ *) (** [validation_mode] permits to differenciate [!type:validation_state] - values. *) + values. + + TODO: #2536 + Add some documentation for the different modes. +*) type validation_mode = | Application of { block_header : Alpha_context.Block_header.t; diff --git a/src/proto_alpha/lib_protocol/operation_repr.mli b/src/proto_alpha/lib_protocol/operation_repr.mli index 5e59b9adf81b..ffb6d5c19aec 100644 --- a/src/proto_alpha/lib_protocol/operation_repr.mli +++ b/src/proto_alpha/lib_protocol/operation_repr.mli @@ -155,56 +155,90 @@ type raw = Operation.t = {shell : Operation.shell_header; proto : bytes} val raw_encoding : raw Data_encoding.t +(** An [operation] contains the operation header information in [shell] + and all data related to the operation itself in [protocol_data]. *) type 'kind operation = { shell : Operation.shell_header; protocol_data : 'kind protocol_data; } +(** A [protocol_data] wraps together a signature for the operation and + the contents of the operation itself. *) and 'kind protocol_data = { contents : 'kind contents_list; signature : Signature.t option; } +(** A [contents_list] is a list of contents, the GADT guarantees two + invariants: + - the list is not empty, and + - if the list has several elements then it only contains manager + operations. *) and _ contents_list = | Single : 'kind contents -> 'kind contents_list | Cons : 'kind Kind.manager contents * 'rest Kind.manager contents_list -> ('kind * 'rest) Kind.manager contents_list +(** A value of type [contents] an operation related to whether + consensus, governance or contract management. *) and _ contents = + (* Preendorsement: About consensus, preendorsement of a block held by a + validator (specific to Tenderbake). *) | Preendorsement : consensus_content -> Kind.preendorsement contents + (* Endorsement: About consensus, endorsement of a block held by a + validator. *) | Endorsement : consensus_content -> Kind.endorsement contents + (* Seed_nonce_revelation: Nonces are created by bakers and are + combined to create pseudo-random seeds. Bakers are urged to reveal their + nonces after a given number of cycles to keep their block rewards + from being forfeited. *) | Seed_nonce_revelation : { level : Raw_level_repr.t; nonce : Seed_repr.nonce; } -> Kind.seed_nonce_revelation contents + (* Double_preendorsement_evidence: Double-preendorsement is a + kind of malicious attack where a byzantine attempts to fork + the chain by preendorsing blocks with different + contents (at the same level and same round) + twice. This behavior may be reported and the byzantine will have + its security deposit forfeited. *) | Double_preendorsement_evidence : { op1 : Kind.preendorsement operation; op2 : Kind.preendorsement operation; } -> Kind.double_preendorsement_evidence contents + (* Double_endorsement_evidence: Similar to double-preendorsement but + for endorsements. *) | Double_endorsement_evidence : { op1 : Kind.endorsement operation; op2 : Kind.endorsement operation; } -> Kind.double_endorsement_evidence contents + (* Double_baking_evidence: Similarly to double-endorsement but the + byzantine attempts to fork by signing two different blocks at the + same level. *) | Double_baking_evidence : { bh1 : Block_header_repr.t; bh2 : Block_header_repr.t; } -> Kind.double_baking_evidence contents + (* Activate_account: Account activation allows to register a public + key hash on the blockchain. *) | Activate_account : { id : Ed25519.Public_key_hash.t; activation_code : Blinded_public_key_hash.activation_code; } -> Kind.activate_account contents + (* Proposals: A candidate protocol can be proposed for voting. *) | Proposals : { source : Signature.Public_key_hash.t; period : int32; proposals : Protocol_hash.t list; } -> Kind.proposals contents + (* Ballot: The validators of the chain will then vote on proposals. *) | Ballot : { source : Signature.Public_key_hash.t; period : int32; @@ -212,7 +246,14 @@ and _ contents = ballot : Vote_repr.ballot; } -> Kind.ballot contents + (* Failing_noop: An operation never considered by the state machine + and which will always fail at [apply]. This allows end-users to + sign arbitrary messages which have no computational semantics. *) | Failing_noop : string -> Kind.failing_noop contents + (* Manager_operation: Operations, emitted and signed by + a (revealed) implicit account, that describe management and + interactions between contracts (whether implicit or + smart). *) | Manager_operation : { source : Signature.Public_key_hash.t; fee : Tez_repr.tez; @@ -223,8 +264,15 @@ and _ contents = } -> 'kind Kind.manager contents +(** A [manager_operation] describes management and interactions + between contracts (whether implicit or smart). *) and _ manager_operation = + (* [Reveal] for the revelation of a public key, a one-time + prerequisite to any signed operation, in order to be able to + check the sender’s signature. *) | Reveal : Signature.Public_key.t -> Kind.reveal manager_operation + (* [Transaction] of some amount to some destination contract. It can + also be used to execute/call smart-contracts. *) | Transaction : { amount : Tez_repr.tez; parameters : Script_repr.lazy_expr; @@ -232,6 +280,8 @@ and _ manager_operation = destination : Destination_repr.t; } -> Kind.transaction manager_operation + (* [Origination] of a contract using a smart-contract [script] and + initially credited with the amount [credit]. *) | Origination : { delegate : Signature.Public_key_hash.t option; script : Script_repr.t; @@ -239,16 +289,27 @@ and _ manager_operation = preorigination : Contract_repr.t option; } -> Kind.origination manager_operation + (* [Delegation] to some staking contract (designated by its public + key hash). When this value is None, delegation is reverted as it + is set to nobody. *) | Delegation : Signature.Public_key_hash.t option -> Kind.delegation manager_operation + (* [Register_global_constant] allows registration and substitution + of a global constant available from any contract and registered in + the context. *) | Register_global_constant : { value : Script_repr.lazy_expr; } -> Kind.register_global_constant manager_operation + (* [Set_deposits_limit] sets an optional limit for frozen deposits + of a contract at a lower value than the maximum limit. When None, + the limit in unset back to the default maximum limit. *) | Set_deposits_limit : Tez_repr.t option -> Kind.set_deposits_limit manager_operation + (* [Tx_rollup_origination] allows an implicit contract to originate + a new transactional rollup. *) | Tx_rollup_origination : Kind.tx_rollup_origination manager_operation | Tx_rollup_submit_batch : { tx_rollup : Tx_rollup_repr.t; @@ -261,17 +322,27 @@ and _ manager_operation = commitment : Tx_rollup_commitment_repr.t; } -> Kind.tx_rollup_commit manager_operation + (* [Sc_rollup_originate] allows an implicit account to originate a new + smart contract rollup (initialized with a given boot + sector). *) | Sc_rollup_originate : { kind : Sc_rollup_repr.Kind.t; boot_sector : Sc_rollup_repr.PVM.boot_sector; } -> Kind.sc_rollup_originate manager_operation + (* [Sc_rollup_add_messages] adds messages to a given rollup's + inbox. *) | Sc_rollup_add_messages : { rollup : Sc_rollup_repr.t; messages : string list; } -> Kind.sc_rollup_add_messages manager_operation +(** Counters are used as anti-replay protection mechanism in + manager operations: each manager account stores a counter and + each manager operation declares a value for the counter. When + a manager operation is applied, the value of the counter of + its manager is checked and incremented. *) and counter = Z.t type 'kind internal_operation = { diff --git a/src/proto_alpha/lib_protocol/raw_context.mli b/src/proto_alpha/lib_protocol/raw_context.mli index 8b454158dc14..605a786ebe85 100644 --- a/src/proto_alpha/lib_protocol/raw_context.mli +++ b/src/proto_alpha/lib_protocol/raw_context.mli @@ -23,6 +23,25 @@ (* *) (*****************************************************************************) +(** State of the validation. + + Two parts: + + 1. Context.t: what is stored between blocks, this includes an + Irmin tree typically stored on disk and the cache (stored in + RAM). + + 2. Additional information needed during the validation of a + block but not persisted across blocks, always stored in + RAM. The gas counter is here. + + [Alpha_context.t] is actually implemented as [Raw_context.t]. + The difference is that Alpha_context.mli does not expose this + so functions manipulating an Alpha_context.t are guaranteed + to only access the context through the storage modules + exposed in Alpha_context.mli. These modules are in charge of + maintaining invariants over the structure of the context. *) + (** {1 Errors} *) type error += Too_many_internal_operations (* `Permanent *) diff --git a/src/proto_alpha/lib_protocol/stake_storage.mli b/src/proto_alpha/lib_protocol/stake_storage.mli index f97220b7198d..3274261317d4 100644 --- a/src/proto_alpha/lib_protocol/stake_storage.mli +++ b/src/proto_alpha/lib_protocol/stake_storage.mli @@ -23,6 +23,9 @@ (* *) (*****************************************************************************) +(** This library provides basic operations (accessors and setters) on + staking tokens. *) + module Delegate_sampler_state : sig val init : Raw_context.t -> diff --git a/src/proto_alpha/lib_protocol/storage_functors.mli b/src/proto_alpha/lib_protocol/storage_functors.mli index 5b78bc8a1f7f..3161d01ed7bd 100644 --- a/src/proto_alpha/lib_protocol/storage_functors.mli +++ b/src/proto_alpha/lib_protocol/storage_functors.mli @@ -26,6 +26,9 @@ (** Tezos Protocol Implementation - Typed storage builders. + Contains functors used by [Storage] to create the structure on + disk. + @see [Make_subcontext] *) diff --git a/src/proto_alpha/lib_protocol/voting_period_repr.mli b/src/proto_alpha/lib_protocol/voting_period_repr.mli index 028281ec567e..92e87bf1236c 100644 --- a/src/proto_alpha/lib_protocol/voting_period_repr.mli +++ b/src/proto_alpha/lib_protocol/voting_period_repr.mli @@ -24,7 +24,7 @@ (*****************************************************************************) (** The voting period kinds are ordered as follows: - Proposal -> Testing_vote -> Testing -> Promotion -> Adoption. + Proposal -> Exploration -> Cooldown -> Promotion -> Adoption. This order is the one used be the function [succ] below. *) type kind = diff --git a/src/proto_alpha/lib_protocol/voting_period_storage.mli b/src/proto_alpha/lib_protocol/voting_period_storage.mli index 8800819131ca..15cf417bb1db 100644 --- a/src/proto_alpha/lib_protocol/voting_period_storage.mli +++ b/src/proto_alpha/lib_protocol/voting_period_storage.mli @@ -23,6 +23,7 @@ (* *) (*****************************************************************************) +(** Initializes the current context with voting period information. *) val init : Raw_context.t -> Voting_period_repr.t -> Raw_context.t tzresult Lwt.t (** Sets the initial period to [{voting_period = root; kind = Proposal; @@ -36,8 +37,10 @@ val reset : Raw_context.t -> Raw_context.t tzresult Lwt.t (** Increment the index by one and set the kind to its successor. *) val succ : Raw_context.t -> Raw_context.t tzresult Lwt.t +(** Returns information about the current voting period. *) val get_current : Raw_context.t -> Voting_period_repr.t tzresult Lwt.t +(** Returns the current voting period kind. *) val get_current_kind : Raw_context.t -> Voting_period_repr.kind tzresult Lwt.t (** Returns true if the context level is the last of current voting period. *) -- GitLab