Crate trace_decoder

An Ethereum Node executes transactions in blocks.

Execution mutates two key data structures:

• The state, which tracks, e.g the account balance.
• The storage, which is a huge array of integers, per-account.

Ethereum nodes expose information about the transactions over RPC, e.g:

• The specific changes to the storage tries.
• Changes to account balance in the state trie.

The state execution correctness is then asserted by the zkEVM prover in evm_arithmetization, relying on starky and plonky2.

Prover perfomance is a high priority.

The aformentioned data structures are represented as tries, which may have subtries hashed out. That is, any node (and its children!) may be replaced by its hash, while maintaining provability of its contents:

    A               A
   / \             / \
  B   C     ->    H   C
 / \   \               \
D   E   F               F

(where H is the hash of the D/B\E subtrie).

The principle concern of this module is to step through the transactions, and reproduce the intermediate tries, while hashing out all possible subtries to minimise prover load (since prover performance is sensitive to the size of the trie). The prover can therefore prove each batch of transactions independently.

Non-goals

• Performance - this will never be the bottleneck in any proving stack.
• Robustness - this library depends on other libraries that are not robust, so may panic at any time.

Modules

observer

Implementation of the observer for the trace decoder.

Structs

BlockLevelData

Data that is specific to a block and is constant for all txns in a given block.

BlockTrace

Core payload needed to generate proof for a block. Additional data retrievable from the blockchain node (using standard ETH RPC API) may be needed for proof generation.

CombinedPreImages

A trie pre-image where both state & storage are combined into one payload.

OtherBlockData

Other data that is needed for proof gen.

SeparateTriePreImages

State/Storage trie pre-images that are separate.

TxnInfo

Info specific to txns in the block.

TxnMeta

Structure holding metadata for one transaction.

TxnTrace

A “trace” specific to an account for a txn.

Enums

BlockTraceTriePreImages

Minimal hashed out tries needed by all txns in the block.

ContractCodeUsage

Contract code access type. Used by txn traces.

SeparateStorageTriesPreImage

A trie pre-image where state and storage are separate.

SeparateTriePreImage

A trie pre-image where state & storage are separate.

WireDisposition

Expected trie type when parsing from binary in a BlockTrace.

Functions

entrypoint

TODO(0xaatif): document this after https://github.com/0xPolygonZero/zk_evm/issues/275