From 6ab3173017eb63542471f7da180df69f5818a669 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 6 Oct 2023 14:37:08 +0200 Subject: [PATCH 1/4] doc: fix glossary entries Mempool & Metadata --- docs/alpha/glossary.rst | 5 +++++ docs/nairobi/glossary.rst | 6 ++++++ docs/oxford/glossary.rst | 5 +++++ 3 files changed, 16 insertions(+) diff --git a/docs/alpha/glossary.rst b/docs/alpha/glossary.rst index c015b4951f7a..8d9ed8f81f1b 100644 --- a/docs/alpha/glossary.rst +++ b/docs/alpha/glossary.rst @@ -49,6 +49,11 @@ _`Level` (a.k.a. block height) since the genesis block, where the genesis block is at level 0. _`Mempool` + A pool (set) of operation_\ s maintained by a node_ and not yet included in a block_. + +.. _def_metadata_alpha: + +_`Metadata` A (block or operation) metadata is a piece of data computed as a result of the application of the block or operation on an associated context_. The metadata diff --git a/docs/nairobi/glossary.rst b/docs/nairobi/glossary.rst index 47579b785445..8ddb3015d828 100644 --- a/docs/nairobi/glossary.rst +++ b/docs/nairobi/glossary.rst @@ -51,6 +51,12 @@ _`Level` (a.k.a. block height) since the genesis block, where the genesis block is at level 0. _`Mempool` + A pool (set) of operation_\ s maintained by a node_ and not yet included in a block_. + +.. _def_metadata: +.. _def_metadata_nairobi: + +_`Metadata` A (block or operation) metadata is a piece of data computed as a result of the application of the block or operation on an associated context_. The metadata diff --git a/docs/oxford/glossary.rst b/docs/oxford/glossary.rst index a64921fe6653..d48e48ea99c7 100644 --- a/docs/oxford/glossary.rst +++ b/docs/oxford/glossary.rst @@ -49,6 +49,11 @@ _`Level` (a.k.a. block height) since the genesis block, where the genesis block is at level 0. _`Mempool` + A pool (set) of operation_\ s maintained by a node_ and not yet included in a block_. + +.. _def_metadata_oxford: + +_`Metadata` A (block or operation) metadata is a piece of data computed as a result of the application of the block or operation on an associated context_. The metadata -- GitLab From 7c8ec19da9de337ce29bedf5fef215aa7697ae19 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 6 Oct 2023 14:37:44 +0200 Subject: [PATCH 2/4] doc: improve description of metadata & context data in storage.rst --- docs/shell/storage.rst | 21 +++++++++++---------- docs/user/history_modes.rst | 2 ++ 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/docs/shell/storage.rst b/docs/shell/storage.rst index 90f582c3dad6..aa53fe736dba 100644 --- a/docs/shell/storage.rst +++ b/docs/shell/storage.rst @@ -4,8 +4,7 @@ The storage layer This document explains the inner workings of the storage layer of the Octez shell. The storage layer is responsible for aggregating blocks -(along with their respective ledger state) and operations within -blocks (along with their associated metadata). It is composed of two +(along with their respective ledger state and :ref:`metadata `) and operations within blocks. It is composed of two main components: a :ref:`store component ` providing storage abstractions for blockchain data such as blocks and operations; and the :ref:`context component ` providing storage abstractions for ledger states (also called contexts). @@ -26,7 +25,11 @@ on disk. This is done by the :doc:`validation toolchain `. The store is initialized using a :doc:`history mode<../user/history_modes>` that can be either *Archive*, *Full* or -*Rolling*. Depending on the chosen history mode, some data will be +*Rolling*. + +In Archive mode, the storage keeps the complete history of all the blocks, up to the genesis block. The history of each block includes the block itself, the context (ledger state) in which the block was applied, and metadata such as the changes resulting of the block application. + +Depending on the chosen history mode, some data will be pruned while the chain is growing. In *Full* mode, all blocks that are part of the chain are kept but their associated metadata below a certain threshold are discarded. In *Rolling* mode, blocks under a @@ -77,14 +80,12 @@ For the operational details of pruning, see :ref:`first_pruning`. Other features ************** -Note that after pruning metadata of some blocks, the store has the capability to reconstruct it +It is possible to export a canonical representation of the chain for a given block, also known as a :doc:`snapshot <../user/snapshots>`, if that block is stored as a non-pruned one (that is a block from which we can read its header, metadata and associated context). + +Another notable feature is that after pruning the metadata and context of some blocks, the store has the capability to reconstruct them by replaying every block and operation present and repopulating the context. Hence, it is possible to transform a ``Full`` store into an ``Archive`` one (see also :ref:`Switch_mode_restrictions`). -It is also possible to retrieve a canonical representation of the -store and context for a given block (provided that its metadata are -present) as a :doc:`snapshot<../user/snapshots>`. - The store also writes on disk the sources of protocols no longer active. This allows to recompile them or even share them on the network if needed. @@ -95,12 +96,12 @@ The store maintains two specific variables related to the pruned data, whose val history mode: - The *caboose*, which represents the oldest block known by the - store. The latter block may or may not have its metadata in + store. The latter block may or may not have its metadata and context in the store. In *Archive* and *Full* mode, this would always be the genesis block. - The *savepoint* which indicates the lowest block known by the store - that possesses metadata. + that possesses metadata and context. The *checkpoint* is another variable maintained by the store, that indicates one block that must be part of the chain. This special block may be in the future. diff --git a/docs/user/history_modes.rst b/docs/user/history_modes.rst index af20bde53790..211b74745759 100644 --- a/docs/user/history_modes.rst +++ b/docs/user/history_modes.rst @@ -96,6 +96,8 @@ of the storage: - *savepoint*: the last known block which contains metadata, - *caboose*: the last known block. +For more details about what data are stored in each mode, refer to :doc:`../shell/storage`. + .. _Set_up_a_full_node: Setting up a node in full mode -- GitLab From 3aadeb8f9e4fcd131ac14e6d85cb7e0145c4844d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Germ=C3=A1n=20Andr=C3=A9s=20Delbianco?= Date: Wed, 11 Oct 2023 17:45:20 +0200 Subject: [PATCH 3/4] doc/alpha: make small fixes in Private Rollups subsection --- docs/alpha/smart_rollups.rst | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/docs/alpha/smart_rollups.rst b/docs/alpha/smart_rollups.rst index c016c16983d7..a300c8d873f8 100644 --- a/docs/alpha/smart_rollups.rst +++ b/docs/alpha/smart_rollups.rst @@ -14,7 +14,7 @@ rollups, allowing to increase the throughput of the Tezos blockchain, (almost) arbitrarily. The purpose of this documentation is to provide an overview of the terminology and basic principles of smart rollups. -In the :doc:`../shell/smart_rollup_node`, we provide a complete tour +In the :doc:`../shell/smart_rollup_node`, we provide a complete tour of smart rollups related workflows and reference documentation for the development of a WASM kernel. The integration of these rollups in the Tezos protocol is @@ -173,7 +173,7 @@ A smart rollup is characterized by: - the Michelson type of the entrypoint used by Layer 1 smart contracts to send internal messages to it, and - an optional list of addresses used as a white-list of allowed -stakers (see :ref:`private_rollup_alpha`). +stakers (see :ref:`private_rollups_alpha`). All these characteristics are provided when originating a new smart rollup. @@ -258,7 +258,7 @@ to avoid type confusion: namely, a kernel transferring a tuple that the Layer 1 interprets as a ticket. Lastly, the outbox message can contain a white-list update. This message can only be executed for a rollup that is private since its origination (see -:ref:`private_rollup_alpha`). +:ref:`private_rollups_alpha`). Refutation ^^^^^^^^^^ @@ -308,26 +308,27 @@ published a concurrent commitment. However, assuming the existence of an honest participant *H*, then *H* will start the refutation game with all concurrent stakers to avoid the rollup getting stuck. -.. _private_rollup_alpha: +.. _private_rollups_alpha: -Private rollup -^^^^^^^^^^^^^^ +Private rollups +^^^^^^^^^^^^^^^ -A **private** smart rollup guarantees that private data can't be +A **private** Smart Rollup guarantees that private data cannot be leaked by any means, whereas in a public rollup, one can force a rollup to leak part of the data by starting a refutation game. This is -achieved by restricting the set of allowed stakers with a -white-list. With that restriction only addresses on the white-list can -publish commitments and therefore participate in a refutation game. +achieved by restricting the set of allowed stakers using a +*whitelist*. With that restriction, only addresses on the whitelist +can publish commitments and therefore participate in a refutation +game. -The white-list is optionally defined at origination. The rollup is +The whitelist is optionally defined at origination. The rollup is considered public if no white-list is defined, private otherwise. The -white-list can be updated with a specific outbox message. This message +whitelist can be updated with a specific outbox message. This message contains an optional list, the new list completely replaces the stored -white-list in layer 1. If the message contains no list, then the +whitelist in layer 1. If the message contains no list, then the rollup becomes public. In turn, it is forbidden to make a public rollup private by sending an outbox message with a non-empty -white-list. +whitelist. It is the responsibility of the kernel to maintain the white-list by submitting outbox messages. Kernels must therefore implement their -- GitLab From 127cc6ebf479483dd9aab3942de0cb54a3c2c77f Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 13 Oct 2023 19:01:49 +0200 Subject: [PATCH 4/4] doc: fix redirected link to git merge/rebase tutorial --- docs/developer/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index 46b0d71933c3..e50f5f0b98da 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -109,7 +109,7 @@ Then use ``push -f`` in your branch to rewrite the history. Being proficient with interactive rebases is mandatory to avoid mistakes and wasting time. -This Git strategy is a variant of the `git rebase workflow `_. +This Git strategy is a variant of the `git rebase workflow `_. .. _mr_workflow: -- GitLab