chore: add storage trie #415

shane-moore · 2025-04-07T19:48:36Z

Changes

updated the EL data structures page to include overview of the Transaction Trie 🌳

shane-moore · 2025-04-07T20:08:30Z

@taxmeifyoucan @raxhvl, this PR is ready for review whenever you get a chance⚡

Copilot

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

Comments suppressed due to low confidence (1)

docs/wiki/EL/data-structures.md:193

Insert a space after 'insertion.' to correct the sentence spacing; it should be 'before insertion. This prevents attackers…'

…each slot index is hashed with keccak-256 before insertion.This prevents attackers…

raxhvl

This is coming up nicely @shane-moore

raxhvl · 2025-04-08T04:58:09Z

docs/wiki/EL/evm.md

-Again, it’s important to note that storage is not part of the EVM itself, rather the currently executing contract account.  More specifically, the contract account contains a **storage root*** that points to a separate Merkle Patricia Trie for that contract's storage.
+Again, it’s important to note that storage is not part of the EVM itself, rather the currently executing contract account.  More specifically, the contract account contains a **storage root** that points to a separate Merkle Patricia Trie for that contract's storage.
+
+The example above shows only a small section of the account's storage. Like memory, all the values in storage are well-defined as zero. Also, when a contract executes an `SSTORE` opcode that sets a storage slot’s value from non-zero back to zero, the operation becomes eligible for a gas refund (the gas is not returned immediately, but is credited to the transaction’s refund counter).  This refund is applied at the end of the transaction to offset some of the gas cost, effectively rewarding the freeing of storage space. 


Suggested change

The example above shows only a small section of the account's storage. Like memory, all the values in storage are well-defined as zero. Also, when a contract executes an `SSTORE` opcode that sets a storage slot’s value from non-zero back to zero, the operation becomes eligible for a gas refund (the gas is not returned immediately, but is credited to the transaction’s refund counter). This refund is applied at the end of the transaction to offset some of the gas cost, effectively rewarding the freeing of storage space.

The example above shows only a small section of the account's storage. Like memory, all the values in storage are well-defined as zero. Also, when a contract executes an `SSTORE` opcode that sets a storage slot’s value from non-zero back to zero, the operation becomes eligible for a gas refund (the gas is not returned immediately, but is credited to the transaction’s refund counter). This refund for freeing up valuable storage space from state trie is applied at the end of the transaction to offset some of the gas cost, effectively rewarding the freeing of storage space.

Added rationale behind storage. Feel free to reframe better.

@raxhvl, I got you. Updated in latest commit 489614e

raxhvl · 2025-04-08T05:01:14Z

docs/wiki/EL/data-structures.md

+
+In the previous section, we described how each account leaf in the **World State Trie** contains a `storageRoot`, which is the keccak-256 hash of the root node of a separate Merkle Patricia Trie, the **Storage Trie**. This trie is not embedded in the **World State Trie** but referenced via the `storageRoot`, enabling storage to be updated and proven independently while still contributing to the global state root.
+
+The **Storage Trie** represents a contract’s persistent state as a mapping of 256-bit storage slots indices (keys) to 256-bit RLP-encoded values. Like the World State Trie, it uses a secure key scheme where each slot index is hashed with keccak-256 before insertion.This prevents attackers from crafting keys that cause long traversal paths or highly unbalanced trie structures, which could otherwise be exploited for DOS attacks by inducing excessive computation during trie lookups or updates.


Suggestion: Indicate the mapping of index -> value is sometimes called a storage slot. You have used the "storage slot" in the note below, so maybe define it here.

raxhvl · 2025-04-08T05:04:35Z

docs/wiki/EL/data-structures.md

+
+The **Storage Trie** represents a contract’s persistent state as a mapping of 256-bit storage slots indices (keys) to 256-bit RLP-encoded values. Like the World State Trie, it uses a secure key scheme where each slot index is hashed with keccak-256 before insertion.This prevents attackers from crafting keys that cause long traversal paths or highly unbalanced trie structures, which could otherwise be exploited for DOS attacks by inducing excessive computation during trie lookups or updates.
+
+> While high-level languages (e.g., Solidity) define how contract variables are laid out across storage slots, this layout is abstracted at the execution layer. The trie treats all slots as uniform key-value entries.


The storage layout abstraction exists in solidity and not in the execution layer. Execution layer implements the abstraction.

taxmeifyoucan

Thanks Shane, great continuation!

github-actions · 2025-04-13T16:05:08Z

Hi @shane-moore,

⚠️ Potential typos found in your pull request:

📄 ./docs/eps/intro.md (line(s) 102):
1. ❌ Karim

ℹ️ How to fix this error:

If these are actual typos:
- Open the files at the specified line numbers and fix them
If these are names or one-off nouns:
- Wrap them in <name> tags
- Example: <name>Alex Pereira</name>
- Use this for people's names or unique terms that appear rarely
If these are valid terms:
- Add them to wordlist.txt (one word per line)
- Terms must be plain text without spaces/special chars
- The list is case-insensitive
If these are code terms:
- Wrap them in backticks (`) in your markdown

ℹ️ Checking for typos locally

Install aspell for your platform
Navigate to project root and run:

for f in **/*.md ; do echo $f ; aspell --lang=en_US --mode=markdown --home-dir=. --personal=wordlist.txt --ignore-case=true --camel-case --add-sgml-skip nospellcheck list < $f | sort | uniq -c ; done

Learn more about wordlist format

github-actions · 2025-04-13T16:05:54Z

Hi @shane-moore,

⚠️ Potential typos found in your pull request:

📄 ./docs/eps/intro.md (line(s) 102):
1. ❌ Karim

ℹ️ How to fix this error:

If these are actual typos:
- Open the files at the specified line numbers and fix them
If these are names or one-off nouns:
- Wrap them in <name> tags
- Example: <name>Alex Pereira</name>
- Use this for people's names or unique terms that appear rarely
If these are valid terms:
- Add them to wordlist.txt (one word per line)
- Terms must be plain text without spaces/special chars
- The list is case-insensitive
If these are code terms:
- Wrap them in backticks (`) in your markdown

ℹ️ Checking for typos locally

Install aspell for your platform
Navigate to project root and run:

for f in **/*.md ; do echo $f ; aspell --lang=en_US --mode=markdown --home-dir=. --personal=wordlist.txt --ignore-case=true --camel-case --add-sgml-skip nospellcheck list < $f | sort | uniq -c ; done

Learn more about wordlist format

github-actions · 2025-04-13T16:08:21Z

Hi @shane-moore,

⚠️ Potential typos found in your pull request:

📄 ./docs/eps/intro.md (line(s) 102):
1. ❌ Karim

ℹ️ How to fix this error:

If these are actual typos:
- Open the files at the specified line numbers and fix them
If these are names or one-off nouns:
- Wrap them in <name> tags
- Example: <name>Alex Pereira</name>
- Use this for people's names or unique terms that appear rarely
If these are valid terms:
- Add them to wordlist.txt (one word per line)
- Terms must be plain text without spaces/special chars
- The list is case-insensitive
If these are code terms:
- Wrap them in backticks (`) in your markdown

ℹ️ Checking for typos locally

Install aspell for your platform
Navigate to project root and run:

for f in **/*.md ; do echo $f ; aspell --lang=en_US --mode=markdown --home-dir=. --personal=wordlist.txt --ignore-case=true --camel-case --add-sgml-skip nospellcheck list < $f | sort | uniq -c ; done

Learn more about wordlist format

shane-moore · 2025-04-13T16:11:05Z

hi @raxhvl, just implemented your legit suggestions in latest commit 489614e. Feel free to take a look when you have a minute.

cc @taxmeifyoucan

raxhvl

Thanks @shane-moore

shane-moore force-pushed the chore/storage-trie branch from b5e49c4 to 0502ac3 Compare April 7, 2025 20:07

raxhvl requested a review from Copilot April 8, 2025 04:53

Copilot AI reviewed Apr 8, 2025

View reviewed changes

raxhvl self-assigned this Apr 8, 2025

raxhvl reviewed Apr 8, 2025

View reviewed changes

taxmeifyoucan approved these changes Apr 11, 2025

View reviewed changes

chore: add storage trie

df00c75

shane-moore force-pushed the chore/storage-trie branch from 0502ac3 to df00c75 Compare April 13, 2025 16:04

chore: updates per pr review

489614e

shane-moore force-pushed the chore/storage-trie branch from 8941121 to 489614e Compare April 13, 2025 16:07

raxhvl self-requested a review April 14, 2025 05:47

raxhvl approved these changes Apr 14, 2025

View reviewed changes

raxhvl merged commit fa266cb into eth-protocol-fellows:main Apr 14, 2025
1 of 2 checks passed


		In the previous section, we described how each account leaf in the World State Trie contains a `storageRoot`, which is the keccak-256 hash of the root node of a separate Merkle Patricia Trie, the Storage Trie. This trie is not embedded in the World State Trie but referenced via the `storageRoot`, enabling storage to be updated and proven independently while still contributing to the global state root.

		The Storage Trie represents a contract’s persistent state as a mapping of 256-bit storage slots indices (keys) to 256-bit RLP-encoded values. Like the World State Trie, it uses a secure key scheme where each slot index is hashed with keccak-256 before insertion.This prevents attackers from crafting keys that cause long traversal paths or highly unbalanced trie structures, which could otherwise be exploited for DOS attacks by inducing excessive computation during trie lookups or updates.


		The Storage Trie represents a contract’s persistent state as a mapping of 256-bit storage slots indices (keys) to 256-bit RLP-encoded values. Like the World State Trie, it uses a secure key scheme where each slot index is hashed with keccak-256 before insertion.This prevents attackers from crafting keys that cause long traversal paths or highly unbalanced trie structures, which could otherwise be exploited for DOS attacks by inducing excessive computation during trie lookups or updates.

		> While high-level languages (e.g., Solidity) define how contract variables are laid out across storage slots, this layout is abstracted at the execution layer. The trie treats all slots as uniform key-value entries.

chore: add storage trie #415

chore: add storage trie #415

Uh oh!

Conversation

shane-moore commented Apr 7, 2025

Changes

Uh oh!

shane-moore commented Apr 7, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

raxhvl left a comment

Choose a reason for hiding this comment

Uh oh!

raxhvl Apr 8, 2025

Choose a reason for hiding this comment

Uh oh!

shane-moore Apr 13, 2025

Choose a reason for hiding this comment

Uh oh!

raxhvl Apr 8, 2025

Choose a reason for hiding this comment

Uh oh!

raxhvl Apr 8, 2025

Choose a reason for hiding this comment

Uh oh!

taxmeifyoucan left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Apr 13, 2025

ℹ️ How to fix this error:

ℹ️ Checking for typos locally

Uh oh!

github-actions bot commented Apr 13, 2025

ℹ️ How to fix this error:

ℹ️ Checking for typos locally

Uh oh!

github-actions bot commented Apr 13, 2025

ℹ️ How to fix this error:

ℹ️ Checking for typos locally

Uh oh!

shane-moore commented Apr 13, 2025

Uh oh!

raxhvl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants