Change:
the nodes in the UpdatePath form a parent-hash chain from the committer's leaf to the root. <del> For example, nodes the tree in full-tree might have been populated by full Commits from A, E, F, G, and B (in that order).  These Commits would create the following parent-hash validity relationship (where the value for a node is reset each time it is listed): Commit from A: A - U - X Commit from E: E - Y - Z - X Commit from F: F - Y - Z - X Commit from G: G - Z - X Commit from B: B - U - X After these commits, the tree will have the following parent-hash chains: A B - U - X E F - Y G - Z Since these chains collectively cover all non-blank parent nodes in the tree, the tree is parent-hash valid. Note that this tree, though valid, contains invalid parent-hash links.  If a client were checking parent hashes top-down from X, for example, they would find that Z has an invalid parent hash relative to X, but that U has valid parent hash.  Likewise, if the client were checking bottom-up, they would find that the chain from F ends in an invalid link from Y to Z.  These invalid links are the natural result of multiple clients having committed. </del> 8.9. As described in commit, each Commit message may optionally contain an

Discussion:
Depends on Conflicts with The diff here is messy because it includes . The biggest change is the extended example, for which you can just scroll to the bottom.
Regarding the Tree Hash Including the parentnode in the tree hash which is supposed to be computed from the leaves, makes the definition appear circular to a new reader. Since the situation when you have blank nodes in the middle of a tree but not at the root is a rather complicated, the situation when you could calculate a tree hash using the parentnode is non-obvious. In the description of Tree Hash the document says that the ParentNode object is optional "depending on whether the node is blank or not." This isn't clear specification language. Saying the parentnode object is present if the node is blank or present if the node is not blank would be clear. What if the parent node is also blank? What if the root is blank? I think an example with and without blank nodes would be appropriate. Explaining the reason why the parentnode is included will help the reader establish a better mental model. Regarding the Parent Hash I still find this section super confusing. A few points Using a tree hash (siblingtreehash) inside the parent hash is non-obvious. There should be some explanation about what property this is providing and that it is a tree hash and not a parent hash. (Honestly it was the third time I read the section that I realized that it was really the tree hash and not the parent hash of the sibling.) Using P, V, and S for Parent, target node, and sibling node is introduced here and never used anywhere else in the document. P for parent and S for sibling make sense. I can't tell what V is supposed to stand for, and it unfortunately could cause people to confuse the vector notation used throughout, but shortly after introducing V for the target node. I propose using "N" for node or "X" instead. There is one reference to the filtered direct path of U. Perhaps this is V, or a child of V? The calculations are sufficiently complicated that I think this warrants a complete, non-trivial, worked example (possibly in an appendix). At some point we should consider providing test vectors in a future document, and this would be an ideal candidate.

Regarding the Tree Hash To be clear, the that is included in the tree hash is the node whose subtree is being hashed. The tree hash doesn't include only the leaves, it includes all the nodes in the tree. If you mean , then yes, I agree the connection is a little subtle. I've tried to explain this a little better. Updated this to be clear that the ParentNode is omitted if and only if the node is blank. Not clear what situation you mean here. I think the specific computations are pretty clearly specified for these cases. Something like this was added in : URL I extended the example and put it in an appendix. Assuming you mean here, hopefully this is addressed by the above notes. Added a note to clarify that this is the tree hash and why. Changed to "D" for "direct path", and explained the semantics. Actually it's the leaf, which is now called "L". I think the example linked above does a pretty good job. Feedback obviously welcome. Agreed that a test vectors document will be a useful follow-on.
This is a huge improvement. While I still prefer "path hash" to "parent hash", the new language in this PR is clear and I think will be straightforward for new implementers to read.