Clean up simple-payment-and-state-verification#7697
Clean up simple-payment-and-state-verification#7697ryoqun wants to merge 1 commit intosolana-labs:masterfrom
Conversation
| It contains the following: | ||
|
|
||
| * State -> Bank-Merkle | ||
| * Transaction -> Entry-Merkle -> Block-Merkle -> Bank-Merkle (for Payment Merkle Path) |
There was a problem hiding this comment.
Swap the order to align with the order of corresponding sections above.
| ``` | ||
|
|
||
| The light entries are reconstructed from Entries and simply show the entry Merkle Root that was mixed in to the PoH hash, instead of the full transaction set. | ||
| The light entries are reconstructed from Entries and simply show the Entry-Merkle Root that was mixed in to the PoH hash, instead of the full transaction set. |
There was a problem hiding this comment.
Consistent capitalization.
There was a problem hiding this comment.
"Entry-Merkle" is used here to discern from "Block-Merkle". These correspond to diagrams in art/
There was a problem hiding this comment.
Regarding capitalization, the original content went its own way, and that should be corrected first. There's no precedent for uppercasing and hyphenating new terms. Merkle is a proper noun, so should be capitalized on its own, but when using it to imply "Merkle hash" in new terms, you should lowercase it. So: "Block-Merkle" should be "block-merkle".
| ### Verification | ||
|
|
||
| A light client that is aware of the supermajority set validators can verify a receipt by following the Merkle Path to the PoH chain. The Bank-Merkle is the Merkle Root and will appear in votes included in an Entry. The light client can simulate [fork selection](../implemented-proposals/tower-bft.md) for the consecutive votes and verify that the receipt is confirmed at the desired lockout threshold. | ||
| A light client that is aware of the supermajority set validators can verify a receipt by following the Merkle Path to the PoH chain. The Bank-Merkle is the Merkle Root that will appear in votes. The light client can simulate [fork selection](../implemented-proposals/tower-bft.md) for the consecutive votes and verify that the receipt is confirmed at the desired lockout threshold. |
There was a problem hiding this comment.
I know votes are themselves transactions, which ultimately go into an entry. But this piece of information isn't relevant in this prose, I think.
| ### Chain of Components in Merkle Path | ||
|
|
||
| A receipt has a PoH link from the payment or state Merkle Path root to a list of consecutive validation votes. | ||
| A receipt has a PoH link from the Payment or State Merkle Path Root to a list of consecutive validation votes. |
There was a problem hiding this comment.
Consistent capitalization.
There was a problem hiding this comment.
I'm confused on what capitalization means here. I'd think "Path" could be "path" and that only Merkle (a proper noun) needs to be capitalized. If those things you're capitalizing are data structures in the codebase, they capitalizing them makes sense, but should also be surrounded with backticks.
| Leaders should coalesce the validator votes by stake weight into a single entry. This will reduce the number of entries necessary to create a receipt. | ||
|
|
||
| ### Chain of Entries | ||
| ### Chain of Components in Merkle Path |
There was a problem hiding this comment.
Entries here is referring to the comprising parts of Merkle Path, not the Entry. Confusing at best, use different word. I picked component, no particular preference. segment could work too.
There was a problem hiding this comment.
Here Entries would be referring to the "vector of PoH entries" below. The next few lines are intended to describe how we get from a TX or account state up to the Bank-Merkle, which consequently links to votes.
This whole section could use a rewrite. It comes from a time before concepts like "rooted bank" and "confidence" were solidified and is admittedly hand wavy as a result.
| A 'light client' is a cluster participant that does not itself run a validator. This light client would provide a level of security greater than trusting a remote validator, without requiring the light client to spend a lot of resources verifying the ledger. | ||
|
|
||
| Rather than providing transaction signatures directly to a light client, the validator instead generates a Merkle Proof from the transaction of interest to the root of a Merkle Tree of all transactions in the including block. This Merkle Root is stored in a ledger entry which is voted on by validators, providing it consensus legitimacy. The additional level of security for a light client depends on an initial canonical set of validators the light client considers to be the stakeholders of the cluster. As that set is changed, the client can update its internal set of known validators with [receipts](simple-payment-and-state-verification.md#receipts). This may become challenging with a large number of delegated stakes. | ||
| Rather than naively providing all the transaction signatures in a block to a light client, the validator instead generates a Merkle Proof from the transaction of interest to the root of a Merkle Tree of all transactions in the including block. This Merkle Root is stored in a ledger entry which is voted on by validators, providing it consensus legitimacy. The additional level of security for a light client depends on an initial canonical set of validators the light client considers to be the stakeholders of the cluster. As that set is changed, the client can update its internal set of known validators with [receipts](simple-payment-and-state-verification.md#receipts). This may become challenging with a large number of delegated stakes. |
There was a problem hiding this comment.
Wow, github's inline word-diff got turned off...
Be explicit about what are the transaction signatures here.
For the lazy:
Rather than {+naively+} providing {+all the+} transaction signatures [-directly-]{+in a block+} to a light client, the validator instead generates a Merkle Proof from the transaction of interest to the root of a Merkle Tree of all transactions in the including block. This Merkle Root is stored in a ledger entry which is voted on by validators, providing it consensus legitimacy. The additional level of security for a light client depends on an initial canonical set of validators the light client considers to be the stakeholders of the cluster. As that set is changed, the client can update its internal set of known validators with receipts. This may become challenging with a large number of delegated stakes.
There was a problem hiding this comment.
Also, I'd think "Merkle" is the only word that needs to be capitalized here.
There was a problem hiding this comment.
Also, I'd think "Merkle" is the only word that needs to be capitalized here.
I'd capitalized "Merkle Tree/Root/Proof" as they are all fairly well-defined distinct entities. Tree being the data structure, Root being the top of the Tree (in typically poor CS naming) and Proof(/Path) being the chain of siblings proving a node exists in the Tree
There was a problem hiding this comment.
Wow, github's inline word-diff got turned off...
Gitbook's line-unwrapping FTW!
|  | ||
|
|
||
| A Block-Merkle is a Merkle root of all the Entry-Merkles sequenced in the block. Transaction status is necessary for the receipt because the state receipt is constructed for the block. Two transactions over the same state can appear in the block, and therefore, there is no way to infer from just the state whether a transaction that is committed to the ledger has succeeded or failed in modifying the intended state. It may not be necessary to encode the full status code, but a single status bit to indicate the transaction's success. | ||
| A Block-Merkle is a Merkle Root of all the Entry-Merkles sequenced in the block. Transaction status is necessary for the receipt because the state receipt is constructed for the block. Two transactions over the same state can appear in the block, and therefore, there is no way to infer from just the state whether a transaction that is committed to the ledger has succeeded or failed in modifying the intended state. It may not be necessary to encode the full status code, but a single status bit to indicate the transaction's success. |
There was a problem hiding this comment.
Consistent capitalization.
|
This document is too poorly written for these minor edits. Please consider a complete rewrite. |
I tend to agree. Especially in light of many of the prereq features that did not exist then, existing now. |
|
@ryoqun, Trent's changes were quite substantial. Starting from scratch looks easier than rebasing. |
|
This pull request has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. |
stale
Bot
added
the
stale
|
This stale pull request has been automatically closed. Thank you for your contributions. |
3 participants
problem
simple-payment-and-state-verification.mdis written in inconsistent writing style. Also, there is some confusing or difficult to read parts here and there.solution
A fresh joiner can smooth the doc out for better, hopefully. :)
background
In the reviewing process of #7622 and #7652, I've also checked this doc and found some low-hanging clean-ups.