docs(client): clean up rust doc landing page

crates/firehose-client/README.md

@@ -1,4 +1,7 @@
-# Firehose Ethereum Rust Client
+# Firehose Rust Client
+
+Extract blocks from [StreamingFast Firehose](https://firehose.streamingfast.io/)
+programatically in Rust.
 
 ## gRPC Endpoints
 
@@ -7,9 +10,10 @@
 Use environment variables to provide Firehose Ethereum and Firehose
 Beacon providers of your choice.
 
-To do this, place a `.env` file in the root of `veemon`. See the
-`.env.example` file in the root of this repository for what you'll need,
-depending on your requirements.
+To do this, place a `.env` file in the root of the `veemon` repository. 
+See the `.env.example` file, also in the root of this repository, for what
+you'll need, depending on your requirements. You may have access to a
+Firehose provider and/or may need to use a provider.
 
 ## firehose-ethereum and firehose-beacon gRPC
 

crates/firehose-client/examples/fetch_beacon.rs

@@ -2,7 +2,7 @@
 //!
 //! Demonstrates how to fetch a single block from Beacon Firehose, using the `Fetch` API.
 
-use firehose_client::client::{Chain, FirehoseClient};
+use firehose_client::{Chain, FirehoseClient};
 use firehose_protos::EthBlock;
 use forrestrie::beacon_v1::{block::Body, Block as BeaconBlock};
 

crates/firehose-client/examples/fetch_ethereum.rs

@@ -2,7 +2,7 @@
 //!
 //! Demonstrates how to fetch a single block from Ethereum firehose.
 
-use firehose_client::client::{Chain, FirehoseClient};
+use firehose_client::{Chain, FirehoseClient};
 use firehose_protos::EthBlock as Block;
 
 #[tokio::main]

crates/firehose-client/examples/stream_beacon.rs

@@ -2,7 +2,7 @@
 //!
 //! Demonstrates how to stream a range of blocks from Firehose Beacon
 
-use firehose_client::client::{Chain, FirehoseClient};
+use firehose_client::{Chain, FirehoseClient};
 use forrestrie::beacon_v1::Block as FirehoseBeaconBlock;
 use futures::StreamExt;
 

crates/firehose-client/examples/stream_ethereum.rs

@@ -1,7 +1,7 @@
 //! # Example: Stream Ethereum Blocks
 //!
 //! This example demonstrates how to stream Ethereum blocks using the Firehose client.
-use firehose_client::client::{Chain, FirehoseClient};
+use firehose_client::{Chain, FirehoseClient};
 use firehose_protos::EthBlock as Block;
 use futures::StreamExt;
 
@@ -14,7 +14,7 @@ async fn main() {
 
     let mut client = FirehoseClient::new(Chain::Ethereum);
     let mut stream = client
-        .stream_ethereum_with_retry(START_BLOCK, TOTAL_BLOCKS)
+        .stream_blocks(START_BLOCK, TOTAL_BLOCKS)
         .await
         .unwrap();
 

crates/firehose-client/src/client.rs

@@ -13,6 +13,7 @@ use tonic::{
 };
 use tracing::{error, info, trace};
 
+/// Work with the fetch and streaming APIs supported by [StreamingFast Firehose](https://firehose.streamingfast.io/).
 pub struct FirehoseClient {
     chain: Chain,
     fetch_client: Option<FetchClient<Channel>>,
@@ -127,7 +128,7 @@ impl FirehoseClient {
         Ok(ReceiverStream::new(rx))
     }
 
-    pub async fn stream_ethereum_with_retry(
+    pub async fn stream_blocks(
         &mut self,
         start: u64,
         total: u64,
@@ -252,6 +253,7 @@ fn insert_api_key_if_provided<T>(request: &mut tonic::Request<T>, chain: Chain)
     }
 }
 
+/// Extract blocks with [`FirehoseClient`] from an extendable union of chain variants.
 #[derive(Clone, Copy, Debug)]
 pub enum Chain {
     Ethereum,

crates/firehose-client/src/lib.rs

@@ -1,3 +1,55 @@
-pub mod client;
-pub mod error;
-pub mod tls;
+//! # Rust Firehose Client
+//!
+//! Rust implementation of a client for the [StreamingFast Firehose](https://firehose.streamingfast.io/)
+//! gRPC Fetch `Block` and Stream `Block`s APIs.
+//!
+//! ## Example Fetching an Ethereum Block
+//!
+//! ```no_run
+//! # use firehose_client::{Chain, FirehoseClient};
+//! # use firehose_protos::EthBlock as Block;
+//! # #[tokio::main]
+//! # async fn main() -> Result<(), firehose_protos::ProtosError> {
+//! let mut client = FirehoseClient::new(Chain::Ethereum);
+//!
+//! if let Some(response) = client.fetch_block(20672593).await.unwrap().ok() {
+//!     let block = Block::try_from(response.into_inner())?;
+//!     assert_eq!(block.number, 20672593);
+//!     assert_eq!(
+//!         format!("0x{}", hex::encode(block.hash)).as_str(),
+//!         "0xea48ba1c8e38ea586239e9c5ec62949ddd79404c6006c099bb02a8b22ddd18e4"
+//!     );
+//! }
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! ## Example Streaming Ethereum Blocks
+//!
+//! ```no_run
+//! # use firehose_client::{Chain, FirehoseClient};
+//! # use futures::StreamExt;
+//! # #[tokio::main]
+//! # async fn main() -> Result<(), firehose_protos::ProtosError> {
+//! const TOTAL_BLOCKS: u64 = 8192;
+//! const START_BLOCK: u64 = 19581798;
+//!
+//! let mut client = FirehoseClient::new(Chain::Ethereum);
+//! let mut stream = client
+//!     .stream_blocks(START_BLOCK, TOTAL_BLOCKS)
+//!     .await
+//!     .unwrap();
+//!
+//! while let Some(block) = stream.next().await {
+//!     // Do Something with the extracted stream of blocks.
+//! }
+//! # Ok(())
+//! # }
+//! ```
+//!
+
+mod client;
+mod error;
+mod tls;
+
+pub use crate::client::{Chain, FirehoseClient};

crates/firehose-protos-examples/examples/receipt_root.rs

@@ -2,7 +2,7 @@
 //! compare it to the receipts root in the block header.
 //!
 use alloy_primitives::FixedBytes;
-use firehose_client::client::{Chain, FirehoseClient};
+use firehose_client::{Chain, FirehoseClient};
 use firehose_protos::EthBlock as Block;
 
 const BLOCK_NUMBER: u64 = 20672593;

crates/forrestrie-examples/examples/fetch_and_verify_block.rs

@@ -24,7 +24,7 @@
 //! assert_eq!(block_root, block_header_root);
 //! ```
 //!
-use firehose_client::client::{Chain, FirehoseClient};
+use firehose_client::{Chain, FirehoseClient};
 use forrestrie::beacon_v1::Block as FirehoseBeaconBlock;
 use tree_hash::TreeHash;
 use types::{BeaconBlock, MainnetEthSpec};

crates/forrestrie-examples/examples/match_ethereum_to_beacon.rs

@@ -29,7 +29,7 @@
 //! comparison until the correct Beacon slot is found.
 //!
 
-use firehose_client::client::{Chain, FirehoseClient};
+use firehose_client::{Chain, FirehoseClient};
 use forrestrie::{
     beacon_state::ETHEREUM_BEACON_DENEB_OFFSET,
     beacon_v1::{block, Block as FirehoseBeaconBlock},

crates/forrestrie-examples/examples/receipts_proof.rs

@@ -2,7 +2,7 @@
 //!
 //! This example shows how to generate an inclusion proof for a set of receipts of a EL block;
 
-use firehose_client::client::{Chain, FirehoseClient};
+use firehose_client::{Chain, FirehoseClient};
 use firehose_protos::{EthBlock as Block, FullReceipt};
 use forrestrie::execution_layer::{build_trie_with_proofs, TargetLeaves};
 use reth_primitives::ReceiptWithBloom;

crates/forrestrie-examples/examples/single_execution_block.rs

@@ -23,7 +23,7 @@
 //! for the era.
 //!
 use ethportal_api::Header;
-use firehose_client::client::{Chain, FirehoseClient};
+use firehose_client::{Chain, FirehoseClient};
 use firehose_protos::EthBlock;
 use forrestrie::{
     beacon_block::{

crates/forrestrie-examples/examples/verify_block_inclusion_proof.rs

@@ -24,7 +24,7 @@
 //! let proof = body.compute_merkle_proof(EXECUTION_PAYLOAD_INDEX).unwrap();
 //! ```
 //!
-use firehose_client::client::{Chain, FirehoseClient};
+use firehose_client::{Chain, FirehoseClient};
 use forrestrie::{
     beacon_block::{
         HistoricalDataProofs, BEACON_BLOCK_BODY_PROOF_DEPTH, EXECUTION_PAYLOAD_FIELD_INDEX,