Feat/##1369 withdraw from beacon chain part 1 - pi circuit (#1634)

### Description

1st part of #1369, mainly on pi circuit integration


### Issue Link

#1369 

### Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] This change requires a documentation update

### Contents

- `Withdrawal` struct definition and `WdTable` implementation
- adding `withdrawals` and `withdrawal_root` in block struct
- `wd_table` assignment in pi circuit

Author: KimiWu123

bus-mapping/src/circuit_input_builder.rs

@@ -9,6 +9,7 @@ mod input_state_ref;
 #[cfg(test)]
 mod tracer_tests;
 mod transaction;
+mod withdrawal;
 
 use self::access::gen_state_access_trace;
 use crate::{
@@ -36,6 +37,7 @@ use itertools::Itertools;
 use log::warn;
 use std::{collections::HashMap, ops::Deref};
 pub use transaction::{Transaction, TransactionContext};
+pub use withdrawal::{Withdrawal, WithdrawalContext};
 
 /// Circuit Setup Parameters
 #[derive(Debug, Clone, Copy)]
@@ -47,6 +49,8 @@ pub struct FixedCParams {
     // TODO: evm_rows: Maximum number of rows in the EVM Circuit
     /// Maximum number of txs in the Tx Circuit
     pub max_txs: usize,
+    /// Maximum number of withdrawals in the Withdrawal Circuit
+    pub max_withdrawals: usize,
     /// Maximum number of bytes from all txs calldata in the Tx Circuit
     pub max_calldata: usize,
     /// Max ammount of rows that the CopyCircuit can have.
@@ -89,6 +93,7 @@ impl Default for FixedCParams {
         FixedCParams {
             max_rws: 1000,
             max_txs: 1,
+            max_withdrawals: 1,
             max_calldata: 256,
             // TODO: Check whether this value is correct or we should increase/decrease based on
             // this lib tests
@@ -370,6 +375,7 @@ impl CircuitInputBuilder<DynamicCParams> {
         // Compute subcircuits parameters
         let c_params = {
             let max_txs = eth_block.transactions.len();
+            let max_withdrawals = eth_block.withdrawals.as_ref().unwrap().len();
             let max_bytecode = self.code_db.num_rows_required_for_bytecode_table();
 
             let max_calldata = eth_block
@@ -411,6 +417,7 @@ impl CircuitInputBuilder<DynamicCParams> {
             FixedCParams {
                 max_rws: max_rws_after_padding,
                 max_txs,
+                max_withdrawals,
                 max_calldata,
                 max_copy_rows,
                 max_exp_steps,

bus-mapping/src/circuit_input_builder/block.rs

@@ -1,11 +1,14 @@
 //! Block-related utility module
 
-use super::{execution::ExecState, transaction::Transaction, CopyEvent, ExecStep, ExpEvent};
+use super::{
+    execution::ExecState, transaction::Transaction, CopyEvent, ExecStep, ExpEvent, Withdrawal,
+};
 use crate::{
     operation::{OperationContainer, RWCounter},
     Error,
 };
-use eth_types::{evm_unimplemented, Address, Word};
+use eth_types::{evm_unimplemented, Address, Word, H256};
+use itertools::Itertools;
 use std::collections::HashMap;
 
 /// Context of a [`Block`] which can mutate in a [`Transaction`].
@@ -148,6 +151,30 @@ impl Block {
         &mut self.txs
     }
 
+    /// Return the list of withdrawals of this block.
+    pub fn withdrawals(&self) -> Vec<Withdrawal> {
+        let eth_withdrawals = self.eth_block.withdrawals.clone().unwrap();
+        eth_withdrawals
+            .iter()
+            .map({
+                |w| {
+                    Withdrawal::new(
+                        w.index.as_u64(),
+                        w.validator_index.as_u64(),
+                        w.address,
+                        w.amount.as_u64(),
+                    )
+                    .unwrap()
+                }
+            })
+            .collect_vec()
+    }
+
+    /// Return root of withdrawals of this block
+    pub fn withdrawals_root(&self) -> H256 {
+        self.eth_block.withdrawals_root.unwrap_or_default()
+    }
+
     /// Push a copy event to the block.
     pub fn add_copy_event(&mut self, event: CopyEvent) {
         self.copy_events.push(event);

bus-mapping/src/circuit_input_builder/tracer_tests.rs

@@ -22,7 +22,7 @@ use mock::{
 use pretty_assertions::assert_eq;
 use std::collections::HashSet;
 
-// Helper struct that contains a CircuitInputBuilder, a particuar tx and a
+// Helper struct that contains a CircuitInputBuilder, a particular tx and a
 // particular execution step so that we can easily get a
 // CircuitInputStateRef to have a context in order to get the error at a
 // given step.

bus-mapping/src/circuit_input_builder/withdrawal.rs

@@ -0,0 +1,57 @@
+//! Withdrawal & WithdrawalContext utility module.
+
+use eth_types::Address;
+
+use crate::Error;
+
+/// Context of a [`Withdrawal`].
+#[derive(Debug, Default)]
+pub struct WithdrawalContext {
+    /// Unique identifier of a withdrawal. This value starts from 0 and then increases
+    /// monotonically.
+    id: u64,
+}
+
+impl WithdrawalContext {
+    /// Return id of this withdrawal.
+    pub fn id(&self) -> u64 {
+        self.id
+    }
+}
+
+/// Result of the parsing of an Ethereum Withdrawal.
+#[derive(Debug, Copy, Clone, Default)]
+pub struct Withdrawal {
+    /// Unique identifier of a withdrawal in the whole history of withdrawals.
+    pub id: u64,
+    /// Unique identifier of a validator.
+    pub validator_id: u64,
+    /// Address to be withdrawn to.
+    pub address: Address,
+    /// Withdrawal amount in Gwei.
+    pub amount: u64,
+}
+
+impl Withdrawal {
+    /// Create a new Self
+    pub fn new(id: u64, validator_id: u64, address: Address, amount: u64) -> Result<Self, Error> {
+        Ok(Self {
+            id,
+            validator_id,
+            address,
+            amount,
+        })
+    }
+    /// Return the amount in this withdrawal
+    pub fn amount_in_wei(&self) -> u64 {
+        self.amount * (10 ^ 9)
+    }
+
+    /// Constructor for padding withdrawal in withdrawal circuit
+    pub fn padding_withdrawal(id: usize) -> Self {
+        Self {
+            id: id as u64,
+            ..Default::default()
+        }
+    }
+}

circuit-benchmarks/src/pi_circuit.rs

@@ -34,6 +34,7 @@ mod tests {
         const BENCHMARK_ID: &str = "Pi Circuit";
 
         const MAX_TXS: usize = 10;
+        const MAX_WITHDRAWALS: usize = 10;
         const MAX_CALLDATA: usize = 128;
 
         let degree: u32 = var("DEGREE")
@@ -42,7 +43,7 @@ mod tests {
             .expect("Cannot parse DEGREE env var as u32");
 
         let public_data = generate_publicdata(MAX_TXS);
-        let circuit = PiCircuit::<Fr>::new(MAX_TXS, MAX_CALLDATA, public_data);
+        let circuit = PiCircuit::<Fr>::new(MAX_TXS, MAX_WITHDRAWALS, MAX_CALLDATA, public_data);
         let public_inputs = circuit.instance();
         let instance: Vec<&[Fr]> = public_inputs.iter().map(|input| &input[..]).collect();
         let instances = &[&instance[..]];

circuit-benchmarks/src/super_circuit.rs

@@ -81,6 +81,7 @@ mod tests {
 
         let circuits_params = FixedCParams {
             max_txs: 1,
+            max_withdrawals: 1,
             max_calldata: 32,
             max_rws: 256,
             max_copy_rows: 256,

eth-types/src/geth_types.rs

@@ -134,6 +134,20 @@ impl BlockConstants {
     }
 }
 
+/// Definition of all of the constants related to an Ethereum withdrawal.
+#[derive(Debug, Default, Clone, Serialize)]
+pub struct Withdrawal {
+    /// Unique identifier of a withdrawal. This value starts from 0 and then increases
+    /// monotonically.
+    pub id: u64,
+    /// Unique identifier of a validator.
+    pub validator_id: u64,
+    /// Address to be withdrawn to.
+    pub address: Address,
+    /// Withdrawal amount in Gwei.
+    pub amount: u64,
+}
+
 /// Definition of all of the constants related to an Ethereum transaction.
 #[derive(Debug, Default, Clone, Serialize)]
 pub struct Transaction {
@@ -322,7 +336,7 @@ pub struct GethData {
     /// chain id
     pub chain_id: Word,
     /// history hashes contains most recent 256 block hashes in history, where
-    /// the lastest one is at history_hashes[history_hashes.len() - 1].
+    /// the latest one is at history_hashes[history_hashes.len() - 1].
     pub history_hashes: Vec<Word>,
     /// Block from geth
     pub eth_block: Block<crate::Transaction>,

external-tracer/src/lib.rs

@@ -1,26 +1,28 @@
 //! This module generates traces by connecting to an external tracer
 
 use eth_types::{
-    geth_types::{Account, BlockConstants, Transaction},
+    geth_types::{Account, BlockConstants, Transaction, Withdrawal},
     Address, Error, GethExecTrace, Word,
 };
 use serde::Serialize;
 use std::collections::HashMap;
 
-/// Configuration structure for `geth_utlis::trace`
+/// Configuration structure for `geth_utils::trace`
 #[derive(Debug, Default, Clone, Serialize)]
 pub struct TraceConfig {
     /// chain id
     pub chain_id: Word,
     /// history hashes contains most recent 256 block hashes in history, where
-    /// the lastest one is at history_hashes[history_hashes.len() - 1].
+    /// the latest one is at history_hashes[history_hashes.len() - 1].
     pub history_hashes: Vec<Word>,
     /// block constants
     pub block_constants: BlockConstants,
     /// accounts
     pub accounts: HashMap<Address, Account>,
     /// transaction
     pub transactions: Vec<Transaction>,
+    /// withdrawal
+    pub withdrawals: Vec<Withdrawal>,
     /// logger
     pub logger_config: LoggerConfig,
 }

integration-tests/src/integration_test_circuits.rs

@@ -50,6 +50,8 @@ const TEST_MOCK_RANDOMNESS: u64 = 0x100;
 
 /// MAX_TXS
 const MAX_TXS: usize = 4;
+/// MAX_WITHDRAWALS
+const MAX_WITHDRAWALS: usize = 4;
 /// MAX_CALLDATA
 const MAX_CALLDATA: usize = 512;
 /// MAX_RWS
@@ -68,6 +70,7 @@ const MAX_KECCAK_ROWS: usize = 38000;
 const CIRCUITS_PARAMS: FixedCParams = FixedCParams {
     max_rws: MAX_RWS,
     max_txs: MAX_TXS,
+    max_withdrawals: MAX_WITHDRAWALS,
     max_calldata: MAX_CALLDATA,
     max_bytecode: MAX_BYTECODE,
     max_copy_rows: MAX_COPY_ROWS,

integration-tests/tests/circuit_input_builder.rs

@@ -18,6 +18,7 @@ async fn test_circuit_input_builder_block(block_num: u64) {
         FixedCParams {
             max_rws: 16384,
             max_txs: 1,
+            max_withdrawals: 1,
             max_calldata: 4000,
             max_bytecode: 4000,
             max_copy_rows: 16384,

mock/src/block.rs

@@ -1,6 +1,9 @@
 //! Mock Block definition and builder related methods.
 
-use crate::{MockTransaction, MOCK_BASEFEE, MOCK_CHAIN_ID, MOCK_DIFFICULTY, MOCK_GASLIMIT};
+use crate::{
+    withdrawal::MockWithdrawal, MockTransaction, MOCK_BASEFEE, MOCK_CHAIN_ID, MOCK_DIFFICULTY,
+    MOCK_GASLIMIT,
+};
 use eth_types::{Address, Block, Bytes, Hash, Transaction, Word, H64, U64};
 use ethers_core::{
     types::{Bloom, OtherFields},
@@ -37,6 +40,7 @@ pub struct MockBlock {
     seal_fields: Vec<Bytes>,
     uncles: Vec<Hash>,
     pub(crate) transactions: Vec<MockTransaction>,
+    pub(crate) withdrawals: Vec<MockWithdrawal>,
     size: Word,
     // This field is handled here as we assume that all block txs have the same ChainId.
     // Also, the field is stored in the block_table since we don't have a chain_config
@@ -71,6 +75,7 @@ impl Default for MockBlock {
             seal_fields: Vec::new(),
             uncles: Vec::new(),
             transactions: Vec::new(),
+            withdrawals: Vec::new(),
             size: Word::zero(),
             chain_id: *MOCK_CHAIN_ID,
         }
@@ -109,8 +114,13 @@ impl From<MockBlock> for Block<Transaction> {
                 .collect::<Vec<Transaction>>(),
             size: Some(mock.size),
             other: OtherFields::default(),
-            withdrawals_root: None,
-            withdrawals: None,
+            withdrawals_root: mock.withdrawal_hash,
+            withdrawals: Some(
+                mock.withdrawals
+                    .iter_mut()
+                    .map(|mock_wd| mock_wd.to_owned().into())
+                    .collect(),
+            ),
         }
     }
 }
@@ -143,8 +153,13 @@ impl From<MockBlock> for Block<()> {
             transactions: vec![],
             size: Some(mock.size),
             other: OtherFields::default(),
-            withdrawals_root: None,
-            withdrawals: None,
+            withdrawals_root: mock.withdrawal_hash,
+            withdrawals: Some(
+                mock.withdrawals
+                    .iter()
+                    .map(|mock_wd| mock_wd.to_owned().into())
+                    .collect(),
+            ),
         }
     }
 }

mock/src/lib.rs

@@ -9,12 +9,15 @@ mod account;
 mod block;
 mod sha3;
 pub mod test_ctx;
+pub mod test_ctx2;
 mod transaction;
+mod withdrawal;
 
 pub(crate) use account::MockAccount;
 pub(crate) use block::MockBlock;
 pub use sha3::Sha3CodeGen;
 pub use test_ctx::TestContext;
+pub use test_ctx2::TestContext2;
 pub use transaction::{AddrOrWallet, MockTransaction, CORRECT_MOCK_TXS};
 
 /// Mock block gas limit