feat: verifiable-api (#505)

* feat: init verifiable-api crate

* handle empty account or storage value in proof verification

* fixup

* impl get_filter_logs handler

* impl more methods

* impl get_logs, lots of refactor

* single account endpoint

* remove redundant Get from response types

* divide into server, client, types crates

* new common crate to avoid cyclic deps

* verifiable_api in config and usage

* impl create_access_list

* add wasm binding for eth_getStorageAt

* fix getAccount storage, getLogs

* make it work with opstack

* fix receipt proof logic

* replace MAX_SUPPORTED_LOGS_NUMBER with MAX_SUPPORTED_BLOCKS_TO_PROVE_FOR_LOGS

* fix clippy warns

* some cleanup & add usage in README

* update cli args & README.md

* move logic from handlers to ApiService

* impl all used methods in verifiable api

* make new traits wasm compat

* add get_block and make code optional

* use camelCase in paths for consistency

* handle error in VerifiableApiClient

* refactor with ExecutionInner & dyn dispatch

* address review comments

* refactor with new ExecutionSpec trait

* tests for ApiService & ExecutionInnerClient

* refactor into VerifiableApiServer struct

* also test verifiable-api in rpc_equivalance tests

* fix clippy, update README

* support transaction_detail_flag in get_block

* fix code_hash verification

* impl create_access_list in Evm

* expose eth_createAccessList, block param in eth_estimateGas

* expose eth_getProof in RPC

* address review comments

* doc-strings, openapi.yaml and handler for same

* fix err handling in Evm.create_access_list

* validateTx flag in createExtendedAccessList

Author: eshaan7

Cargo.lock

@@ -8,11 +8,16 @@ exclude = ["benches"]
 [workspace]
 members = [
     "cli",
+    "common",
     "core",
     "ethereum",
     "ethereum/consensus-core",
     "opstack",
     "helios-ts",
+    "tests/test-utils",        # ToDo(@eshaan7): find a better way to include this
+    "verifiable-api/client",
+    "verifiable-api/server",
+    "verifiable-api/types",
 ]
 
 default-members = ["cli"]
@@ -83,14 +88,18 @@ typenum = "1.17.0"
 ######################################
 
 [dependencies]
+helios-common = { path = "./common" }
 helios-core = { path = "./core" }
 helios-ethereum = { path = "./ethereum" }
 helios-opstack = { path = "./opstack" }
 
 [dev-dependencies]
-tokio = { version = "1", features = ["full"] }
+tokio.workspace = true
+futures.workspace = true
+url.workspace = true
+serde.workspace = true
 dotenv = "0.15.0"
-serde = { version = "1.0.154", features = ["derive"] }
+helios-verifiable-api-server = { path = "verifiable-api/server" }
 
 [target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies]
 alloy = { version = "0.9.1", features = ["full"] }

Cargo.toml

@@ -1,7 +1,9 @@
+use std::str::FromStr;
+
 use alloy::primitives::Address;
 use criterion::{criterion_group, criterion_main, Criterion};
-use helios_core::types::BlockTag;
-use std::str::FromStr;
+
+use helios_common::types::BlockTag;
 
 mod harness;
 

benches/get_balance.rs

@@ -1,7 +1,9 @@
+use std::str::FromStr;
+
 use alloy::primitives::Address;
 use criterion::{criterion_group, criterion_main, Criterion};
-use helios_core::types::BlockTag;
-use std::str::FromStr;
+
+use helios_common::types::BlockTag;
 
 mod harness;
 

benches/get_code.rs

@@ -1,12 +1,14 @@
 #![allow(dead_code)]
+use std::{path::PathBuf, str::FromStr};
+
 use alloy::primitives::{Address, B256, U256};
-use helios_core::types::BlockTag;
+
+use helios_common::types::BlockTag;
 use helios_ethereum::{
     config::{checkpoints, networks},
     database::FileDB,
     EthereumClient, EthereumClientBuilder,
 };
-use std::{path::PathBuf, str::FromStr};
 
 /// Fetches the latest mainnet checkpoint from the fallback service.
 ///

benches/harness.rs

@@ -1,6 +1,7 @@
 use alloy::primitives::Address;
 use criterion::{criterion_group, criterion_main, Criterion};
-use helios_core::types::BlockTag;
+
+use helios_common::types::BlockTag;
 
 mod harness;
 

benches/sync.rs

@@ -21,6 +21,8 @@ dirs = "5.0.1"
 ctrlc = "3.2.3"
 url = "2.5.0"
 
+# self crates
+helios-common = { path = "../common" }
 helios-core = { path = "../core" }
 helios-ethereum = { path = "../ethereum" }
 helios-opstack = { path = "../opstack" }

cli/Cargo.toml

@@ -15,17 +15,18 @@ use eyre::Result;
 use figment::providers::Serialized;
 use figment::value::Value;
 use futures::executor::block_on;
+use tracing::{error, info};
+use tracing_subscriber::filter::{EnvFilter, LevelFilter};
+use tracing_subscriber::FmtSubscriber;
+use url::Url;
+
+use helios_common::network_spec::NetworkSpec;
 use helios_core::client::Client;
 use helios_core::consensus::Consensus;
-use helios_core::network_spec::NetworkSpec;
 use helios_ethereum::config::{cli::CliConfig, Config as EthereumConfig};
 use helios_ethereum::database::FileDB;
 use helios_ethereum::{EthereumClient, EthereumClientBuilder};
 use helios_opstack::{config::Config as OpStackConfig, OpStackClient, OpStackClientBuilder};
-use tracing::{error, info};
-use tracing_subscriber::filter::{EnvFilter, LevelFilter};
-use tracing_subscriber::FmtSubscriber;
-use url::Url;
 
 #[tokio::main]
 async fn main() -> Result<()> {
@@ -128,6 +129,8 @@ struct EthereumArgs {
     checkpoint: Option<B256>,
     #[clap(short, long, env, value_parser = parse_url)]
     execution_rpc: Option<Url>,
+    #[clap(long, env, value_parser = parse_url)]
+    execution_verifiable_api: Option<Url>,
     #[clap(short, long, env, value_parser = parse_url)]
     consensus_rpc: Option<Url>,
     #[clap(short, long, env)]
@@ -162,6 +165,7 @@ impl EthereumArgs {
         CliConfig {
             checkpoint: self.checkpoint,
             execution_rpc: self.execution_rpc.clone(),
+            execution_verifiable_api: self.execution_verifiable_api.clone(),
             consensus_rpc: self.consensus_rpc.clone(),
             data_dir: self
                 .data_dir
@@ -186,6 +190,8 @@ struct OpStackArgs {
     rpc_port: Option<u16>,
     #[clap(short, long, env, value_parser = parse_url)]
     execution_rpc: Option<Url>,
+    #[clap(long, env, value_parser = parse_url)]
+    execution_verifiable_api: Option<Url>,
     #[clap(short, long, env, value_parser = parse_url)]
     consensus_rpc: Option<Url>,
     #[clap(
@@ -226,6 +232,10 @@ impl OpStackArgs {
             user_dict.insert("execution_rpc", Value::from(rpc.to_string()));
         }
 
+        if let Some(api) = &self.execution_verifiable_api {
+            user_dict.insert("execution_verifiable_api", Value::from(api.to_string()));
+        }
+
         if let Some(rpc) = &self.consensus_rpc {
             user_dict.insert("consensus_rpc", Value::from(rpc.to_string()));
         }

cli/src/main.rs

@@ -0,0 +1,11 @@
+[package]
+name = "helios-common"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+alloy.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+revm.workspace = true
+eyre.workspace = true

common/Cargo.toml

@@ -0,0 +1,16 @@
+#[derive(Clone)]
+pub enum ExecutionMode {
+    Rpc(String),
+    VerifiableApi(String),
+}
+
+impl ExecutionMode {
+    pub fn from_urls(rpc: Option<String>, verifiable_api: Option<String>) -> Self {
+        match (rpc, verifiable_api) {
+            // we prioritize verifiable_api over rpc
+            (_, Some(verifiable_api)) => Self::VerifiableApi(verifiable_api),
+            (Some(rpc), None) => Self::Rpc(rpc),
+            (None, None) => panic!("Must specify either execution_rpc or execution_verifiable_api"),
+        }
+    }
+}