Your neighborhood zk-ready ethereum node emits binary "witnesses"[^1].

But plonky2, your prover, wants GenerationInputs.

This library helps you get there.

[^1]: A witness is an attestation of the state of the world, which can be proven by a prover.

Non-Goals

• Performance - this won't be the bottleneck in any proving system.
• Robustness - malicious or malformed input may crash this library.

TODO(0xaatif): refactor all the docs below

It might not be obvious why we need traces for each txn in order to generate proofs. While it's true that we could just run all the txns of a block in an EVM to generate the traces ourselves, there are a few major downsides:

• The client is likely a full node and already has to run the txns in an EVM anyways.
• We want this protocol to be as agnostic as possible to the underlying chain that we're generating proofs for, and running our own EVM would likely cause us to loose this genericness.

While it's also true that we run our own zk-EVM (plonky2) to generate proofs, it's critical that we are able to generate txn proofs in parallel. Since generating proofs with plonky2 is very slow, this would force us to sequentialize the entire proof generation process. So in the end, it's ideal if we can get this information sent to us instead.

This library generates an Intermediary Representation (IR) of a block's transactions, given a [BlockTrace] and some additional data represented by [OtherBlockData].

It first preprocesses the [BlockTrace] to provide transaction, withdrawals and tries data that can be directly used to generate an IR. For each transaction, this library extracts the necessary data from the processed transaction information to return the IR.

The IR is used to generate root proofs, then aggregation proofs and finally block proofs. Because aggregation proofs require at least two entries, we pad the vector of IRs thanks to additional dummy payload intermediary representations whenever necessary.

Withdrawals and Padding

Withdrawals are all proven together in a dummy payload. A dummy payload corresponds to the IR of a proof with no transaction. They must, however, be proven last. The padding is therefore carried out as follows: If there are no transactions in the block, we add two dummy transactions. The withdrawals -- if any -- are added to the second dummy transaction. If there is only one transaction in the block, we add one dummy transaction. If there are withdrawals, the dummy transaction is at the end. Otherwise, it is added at the start. If there are two or more transactions:

• if there are no withdrawals, no dummy transactions are added
• if there are withdrawals, one dummy transaction is added at the end, with all the withdrawals in it.