Skip to content

Commit

Permalink
feat: expand canopy depth docs
Browse files Browse the repository at this point in the history
  • Loading branch information
aspnxdd committed Nov 4, 2024
1 parent 3b8e28d commit f3acd9d
Show file tree
Hide file tree
Showing 2 changed files with 15 additions and 3 deletions.
18 changes: 15 additions & 3 deletions docs/advanced/state-compression.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,14 +193,14 @@ sized and set at tree creation via this `maxBufferSize` value.

### Canopy depth

The "canopy depth", sometimes called the canopy size, is the number of proof
nodes that are cached/stored on-chain for any given proof path.
The "canopy depth," also known as the canopy size, refers to the number of proof
node levels that are cached or stored onchain for a given proof path.

When performing an update action on a `leaf`, like transferring ownership (e.g.
selling a compressed NFT), the **complete** proof path must be used to verify
original ownership of the leaf and therefore allow for the update action. This
verification is performed using the **complete** proof path to correctly compute
the current `root hash` (or any cached `root hash` via the on-chain "concurrent
the current `root hash` (or any cached `root hash` via the onchain "concurrent
buffer").

The larger a tree's max depth is, the more proof nodes are required to perform
Expand All @@ -222,6 +222,18 @@ For example, a tree with a max depth of `14` would require `14` total proof
nodes. With a canopy of `10`, only `4` proof nodes are required to be submitted
per update transaction.

![Canopy depth of 1 for a Concurrent Merkle Tree of max depth of 3](/assets/docs/compression/canopy-depth-1.png)

Consider another example, this time with a tree of max depth `3`. If we want to
apply an action to one of the tree’s leaves—such as updating `R4`—we need to
provide proofs for `L4` and `R2`. However, we can omit `R1` since it is already
cached/stored onchain due to our canopy depth of `1`, which ensures that all
nodes at level 1 (`L1` and `R1`) are stored onchain. This results in a total of
2 required proofs.

Therefore, the number of proofs required to update a leaf is equal to the max
depth minus the canopy depth. In this example, `3 - 1 = 2`.

#### The larger the canopy depth value, the higher the cost

The `canopyDepth` value is also a primary factor of cost when creating a tree
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit f3acd9d

Please sign in to comment.