From 13c2a52b36fb0873c31af6400e52481d33bc0d4c Mon Sep 17 00:00:00 2001 From: EclesioMeloJunior Date: Tue, 3 Dec 2024 08:40:54 -0400 Subject: [PATCH] chore: address comments --- .../parachain-protocol/fragment-chain.md | 18 +++++++++--------- .../prospective-parachains.md | 4 ++-- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/docs/design/parachain-protocol/fragment-chain.md b/docs/docs/design/parachain-protocol/fragment-chain.md index 0a822f6ed8..cfab69d446 100644 --- a/docs/docs/design/parachain-protocol/fragment-chain.md +++ b/docs/docs/design/parachain-protocol/fragment-chain.md @@ -1,14 +1,14 @@ # Fragment Chain -### Candidate Storage +### [Candidate Storage](https://github.com/paritytech/polkadot-sdk/blob/3d8da815ecd12b8f04daf87d6ffba5ec4a181806/polkadot/node/core/prospective-parachains/src/fragment_chain/mod.rs#L189) -This structure does not care if candidates form a chain, it only stores candidates and holds "links" to a `CandidateEntry`, those links are +This structure does not care if candidates form a chain, it only stores candidates and holds "links" to a [`CandidateEntry`](https://github.com/paritytech/polkadot-sdk/blob/3d8da815ecd12b8f04daf87d6ffba5ec4a181806/polkadot/node/core/prospective-parachains/src/fragment_chain/mod.rs#L346), those links are `Parent Head Data Hash` to `Set` `Output Head Data Hash` to `Set` -The parent head data hash is simply the parent block of that candidate, the output head data hash is the hash of the resultant `HeadData` after an execution, you can think of the output head data as the raw head of the parachain block that we get after validating the inputs against the parachain runtime. +The parent head data hash is simply the parent block of that candidate, the output head data hash is the hash of the resultant [`HeadData`](https://github.com/paritytech/polkadot-sdk/blob/8f1606e9f9bd6269a4c2631a161dcc73e969a302/polkadot/parachain/src/primitives.rs#L51) after an execution, you can think of the output head data as the raw head of the parachain block that we get after validating the inputs against the parachain runtime. `input -> execution -> head data (parachain block head)`, it is called head data because it is a `Vec`, what this head data contains is not for the validator, what we care is the *hash* of it. @@ -18,7 +18,7 @@ Scope is the context of a fragment chain, it contains constraints and ancestors ### Fragment Node -This is a node that is part of a `BackedChain`. When we create a new fragment we should make sure that the candidate is valid under the operating constraints. We use the constraints to build an expected persisted validation data and compare with the one we got from the candidate. A fragment node is always backed and it is generated from a `CandidateEntry`. +This is a node that is part of a [`BackedChain`](https://github.com/paritytech/polkadot-sdk/blob/3d8da815ecd12b8f04daf87d6ffba5ec4a181806/polkadot/node/core/prospective-parachains/src/fragment_chain/mod.rs#L596). When we create a new fragment we should make sure that the candidate is valid under the operating constraints. We use the constraints to build an expected persisted validation data and compare with the one we got from the candidate. A fragment node is always backed and it is generated from a [`CandidateEntry`](https://github.com/paritytech/polkadot-sdk/blob/3d8da815ecd12b8f04daf87d6ffba5ec4a181806/polkadot/node/core/prospective-parachains/src/fragment_chain/mod.rs#L346). ### BackedChain @@ -28,7 +28,7 @@ It holds a chain of backed nodes (fragments), in rust they store the fragments. This is a method where given a chain of fragments we need to remove all the fragments that descend a certain parent head data hash (this is the hash of the parachain block that is parent of another parachain block). -Let's say that we have the following `BackedChain` +Let's say that we have the following [`BackedChain`](https://github.com/paritytech/polkadot-sdk/blob/3d8da815ecd12b8f04daf87d6ffba5ec4a181806/polkadot/node/core/prospective-parachains/src/fragment_chain/mod.rs#L596) ``` {Parent Head Hash (0) | Output Head Data Hash (1)} @@ -49,13 +49,13 @@ V If we want to revert to `ParentHeadDataHash (3)` we search for a node that outputs such head data hash, in this case is the node at position 2, knowing the index we should remove its children (nodes at position 3 and 4) and clear their informations from the tables `byParentHead`, `byOutputHead` and `Candidates`, and we return the removed nodes. -### Fragment Chain +### [Fragment Chain](https://github.com/paritytech/polkadot-sdk/blob/3d8da815ecd12b8f04daf87d6ffba5ec4a181806/polkadot/node/core/prospective-parachains/src/fragment_chain/mod.rs#L663) The fragment chain is a struct that an active leaf holds, also it should avoid cycles or paths in the three. ##### Populate Chain -This is a method from `FragmentChain` where given a scope and a Candidate Storage it will try to build a `BackedChain` with the candidates that follow the conditions: +This is a method from [`FragmentChain`](https://github.com/paritytech/polkadot-sdk/blob/3d8da815ecd12b8f04daf87d6ffba5ec4a181806/polkadot/node/core/prospective-parachains/src/fragment_chain/mod.rs#L663) where given a scope and a Candidate Storage it will try to build a [`BackedChain`](https://github.com/paritytech/polkadot-sdk/blob/3d8da815ecd12b8f04daf87d6ffba5ec4a181806/polkadot/node/core/prospective-parachains/src/fragment_chain/mod.rs#L596) with the candidates that follow the conditions: - Does not introduce a cycle: That means, its output head data hash is not the parent head data hash of another candidate in the BackedChain. - Its parent hash is correct: matches the previous output hash, forming a coherent chain @@ -63,14 +63,14 @@ This is a method from `FragmentChain` where given a scope and a Candidate Storag - All non-pending-availability has a parent in the current scope. - Candidates outputs fullfils the constraint. -If those conditions follows for 1 or more candidates we consider them possible backed/backable, however since the `BackedChain` does not allow forks we need to resolve that if there is more than one candidates, and the fork selection rule is: compare the hashes and the lowest hash will be chosen and pushed into the `BackedChain` and removed from the Candidate Storage +If those conditions follows for 1 or more candidates we consider them possible backed/backable, however since the [`BackedChain`](https://github.com/paritytech/polkadot-sdk/blob/3d8da815ecd12b8f04daf87d6ffba5ec4a181806/polkadot/node/core/prospective-parachains/src/fragment_chain/mod.rs#L596) does not allow forks we need to resolve that if there is more than one candidates, and the fork selection rule is: compare the hashes and the lowest hash will be chosen and pushed into the [`BackedChain`](https://github.com/paritytech/polkadot-sdk/blob/3d8da815ecd12b8f04daf87d6ffba5ec4a181806/polkadot/node/core/prospective-parachains/src/fragment_chain/mod.rs#L596) and removed from the Candidate Storage ##### Trim Unelegible Forks What is does is a deapth breadth-first search looking for candidates in the Candidate Storage that has no potential that is children of valid backed candidates. -Consider the following chain, the green letters forms the `BackedChain` while the red letters are candidates placed in the `Unconnected` candidate storage, drawing them (without all the maps and hashes here and there) we can have something similar to the image bellow. +Consider the following chain, the green letters forms the [`BackedChain`](https://github.com/paritytech/polkadot-sdk/blob/3d8da815ecd12b8f04daf87d6ffba5ec4a181806/polkadot/node/core/prospective-parachains/src/fragment_chain/mod.rs#L596) while the red letters are candidates placed in the `Unconnected` candidate storage, drawing them (without all the maps and hashes here and there) we can have something similar to the image bellow. ![IMG_944F8C1D62F0-1](https://hackmd.io/_uploads/SJ3KA0m7kg.jpg) diff --git a/docs/docs/design/parachain-protocol/prospective-parachains.md b/docs/docs/design/parachain-protocol/prospective-parachains.md index 70e3c61d3b..2960ca1a10 100644 --- a/docs/docs/design/parachain-protocol/prospective-parachains.md +++ b/docs/docs/design/parachain-protocol/prospective-parachains.md @@ -23,7 +23,7 @@ Inform the prospective parachains subsystem that a previously introduced candida 3. [`prospectiveparachains.GetBackableCandidates`](https://github.com/paritytech/polkadot-sdk/blob/2ef2723126584dfcd6d2a9272282ee78375dbcd3/polkadot/node/subsystem-types/src/messages.rs#L1391C2-L1391C23) -Try getting N backable candidate hashes along with their relay parents for the given parachain, under the given relay-parent hash, which is a descendant of the given ancestors. Timed out ancestors should not be included in the collection. N should represent the number of scheduled cores of this `ParaId`. A timed out ancestor frees the cores of all of its descendants, so if there's a hole in the supplied ancestor path, we'll get candidates that backfill those timed out slots first. It may also return less/no candidates, if there aren't enough backable candidates recorded. +Try getting N backable candidate hashes along with their relay parents for the given parachain, under the given relay-parent hash, which is a descendant of the given ancestors. Timed out ancestors should not be included in the collection. N should represent the number of scheduled cores of this `ParaID`. A timed out ancestor frees the cores of all of its descendants, so if there's a hole in the supplied ancestor path, we'll get candidates that backfill those timed out slots first. It may also return less/no candidates, if there aren't enough backable candidates recorded. 4. [`prospectiveparachains.GetHypotheticalMembership`](https://github.com/paritytech/polkadot-sdk/blob/2ef2723126584dfcd6d2a9272282ee78375dbcd3/polkadot/node/subsystem-types/src/messages.rs#L1411) @@ -31,7 +31,7 @@ Get the hypothetical or actual membership of candidates with the given propertie 5. [`prospectiveparachains.GetMinimumRelayParents`](https://github.com/paritytech/polkadot-sdk/blob/2ef2723126584dfcd6d2a9272282ee78375dbcd3/polkadot/node/subsystem-types/src/messages.rs#L1428C2-L1428C24) -Get the minimum accepted relay-parent number for each para in the fragment chain for the given relay-chain block hash. That is, if the block hash is known and is an active leaf, this returns the minimum relay-parent block number in the same branch of the relay chain which is accepted in the fragment chain for each para-id. If the block hash is not an active leaf, this will return an empty vector. Para-IDs which are omitted from this list can be assumed to have no valid candidate relay-parents under the given relay-chain block hash. Para-IDs are returned in no particular order. +Get the minimum accepted relay-parent number for each para in the fragment chain for the given relay-chain block hash. That is, if the block hash is known and is an active leaf, this returns the minimum relay-parent block number in the same branch of the relay chain which is accepted in the fragment chain for each ParaID. If the block hash is not an active leaf, this will return an empty vector. ParaIDs which are omitted from this list can be assumed to have no valid candidate relay-parents under the given relay-chain block hash. ParaIDs are returned in no particular order. 6. [`prospectiveparachains.GetProspectiveValidationData`](https://github.com/paritytech/polkadot-sdk/blob/2ef2723126584dfcd6d2a9272282ee78375dbcd3/polkadot/node/subsystem-types/src/messages.rs#L1434C2-L1434C30)