chore: docs

Author: Jon-Becker

crates/cache/src/lib.rs

@@ -225,8 +225,7 @@ pub fn delete_cache(key: &str) -> Result<(), Error> {
 #[allow(deprecated)]
 pub fn read_cache<T>(key: &str) -> Result<Option<T>, Error>
 where
-    T: 'static + DeserializeOwned,
-{
+    T: 'static + DeserializeOwned, {
     let home = home_dir().ok_or(Error::Generic(
         "failed to get home directory. does your os support `std::env::home_dir()`?".to_string(),
     ))?;
@@ -249,8 +248,8 @@ where
         .map_err(|e| Error::Generic(format!("failed to deserialize cache object: {:?}", e)))?;
 
     // check if the cache has expired, if so, delete it and return None
-    if cache.expiry
-        < std::time::SystemTime::now()
+    if cache.expiry <
+        std::time::SystemTime::now()
             .duration_since(std::time::UNIX_EPOCH)
             .map_err(|e| Error::Generic(format!("failed to get current time: {:?}", e)))?
             .as_secs()
@@ -277,8 +276,7 @@ where
 #[allow(deprecated)]
 pub fn store_cache<T>(key: &str, value: T, expiry: Option<u64>) -> Result<(), Error>
 where
-    T: Serialize,
-{
+    T: Serialize, {
     let home = home_dir().ok_or(Error::Generic(
         "failed to get home directory. does your os support `std::env::home_dir()`?".to_string(),
     ))?;
@@ -290,8 +288,8 @@ where
         std::time::SystemTime::now()
             .duration_since(std::time::UNIX_EPOCH)
             .map_err(|e| Error::Generic(format!("failed to get current time: {:?}", e)))?
-            .as_secs()
-            + 60 * 60 * 24 * 90,
+            .as_secs() +
+            60 * 60 * 24 * 90,
     );
 
     let cache = Cache { value, expiry };
@@ -316,8 +314,7 @@ pub async fn with_cache<T, F, Fut>(key: &str, func: F) -> eyre::Result<T>
 where
     T: 'static + Serialize + DeserializeOwned + Send + Sync,
     F: FnOnce() -> Fut + Send,
-    Fut: std::future::Future<Output = Result<T, eyre::Report>> + Send,
-{
+    Fut: std::future::Future<Output = Result<T, eyre::Report>> + Send, {
     // Try to read from cache
     match read_cache::<T>(key) {
         Ok(Some(cached_value)) => {

crates/cfg/src/core/graph.rs

@@ -60,8 +60,8 @@ pub(crate) fn build_cfg(
                 .first()
                 .ok_or_eyre("failed to get first operation")?
                 .last_instruction
-                .opcode
-                == JUMPDEST,
+                .opcode ==
+                JUMPDEST,
         )?;
     }
 

crates/cli/src/args.rs

@@ -20,7 +20,7 @@ use tracing::{level_filters::LevelFilter, Level};
 
 #[derive(Debug, Parser)]
 #[clap(name = "heimdall", author = "Jonathan Becker <[email protected]>", version)]
-pub struct Arguments {
+pub(crate) struct Arguments {
     #[clap(subcommand)]
     pub sub: Subcommands,
 
@@ -34,7 +34,7 @@ pub struct Arguments {
     after_help = "For more information, read the wiki: https://jbecker.dev/r/heimdall-rs/wiki"
 )]
 #[allow(clippy::large_enum_variant)]
-pub enum Subcommands {
+pub(crate) enum Subcommands {
     #[clap(name = "disassemble", about = "Disassemble EVM bytecode to assembly")]
     Disassemble(DisassemblerArgs),
 
@@ -66,7 +66,7 @@ pub enum Subcommands {
 /// The log configuration.
 #[derive(Debug, Args)]
 #[clap(next_help_heading = "LOGGING")]
-pub struct LogArgs {
+pub(crate) struct LogArgs {
     /// The format to use for logs written to stdout.
     #[clap(long = "log.stdout.format", value_name = "FORMAT", global = true, default_value_t = LogFormat::Terminal)]
     pub log_stdout_format: LogFormat,
@@ -115,7 +115,7 @@ impl LogArgs {
     }
 
     /// Initializes tracing with the configured options from cli args.
-    pub fn init_tracing(&self) -> eyre::Result<Option<FileWorkerGuard>> {
+    pub(crate) fn init_tracing(&self) -> eyre::Result<Option<FileWorkerGuard>> {
         let mut tracer = HeimdallTracer::new();
 
         let stdout = self.layer(self.log_stdout_format, self.log_stdout_filter.clone(), true);
@@ -132,7 +132,7 @@ impl LogArgs {
 
 /// The color mode for the cli.
 #[derive(Debug, Copy, Clone, ValueEnum, Eq, PartialEq)]
-pub enum ColorMode {
+pub(crate) enum ColorMode {
     /// Colors on
     Always,
     /// Colors on
@@ -167,7 +167,7 @@ impl FromStr for ColorMode {
 /// The verbosity settings for the cli.
 #[derive(Debug, Copy, Clone, Args)]
 #[clap(next_help_heading = "DISPLAY")]
-pub struct Verbosity {
+pub(crate) struct Verbosity {
     /// Set the minimum log level.
     ///
     /// -v     Warnings & Errors
@@ -185,7 +185,7 @@ pub struct Verbosity {
 impl Verbosity {
     /// Get the corresponding [Directive] for the given verbosity, or none if the verbosity
     /// corresponds to silent.
-    pub fn directive(&self) -> Directive {
+    pub(crate) fn directive(&self) -> Directive {
         if self.quiet {
             LevelFilter::OFF.into()
         } else {

crates/cli/src/main.rs

@@ -1,3 +1,5 @@
+//! The Heimdall CLI is a command line interface for interacting with Heimdall modules.
+
 pub(crate) mod args;
 pub(crate) mod output;
 

crates/cli/src/output.rs

@@ -10,7 +10,7 @@ use heimdall_common::ether::rpc;
 ///   - if `target` is a contract_address, return `/output/{chain_id}/{target}/{filename}`
 ///   - if `target` is a file or raw bytes, return `/output/local/{filename}`
 /// - if `output` is specified, return `/{output}/{filename}`
-pub async fn build_output_path(
+pub(crate) async fn build_output_path(
     output: &str,
     target: &str,
     rpc_url: &str,
@@ -38,7 +38,7 @@ pub async fn build_output_path(
 }
 
 /// pass the input to the `less` command
-pub async fn print_with_less(input: &str) -> Result<()> {
+pub(crate) async fn print_with_less(input: &str) -> Result<()> {
     let mut child =
         std::process::Command::new("less").stdin(std::process::Stdio::piped()).spawn()?;
 

crates/common/src/ether/bytecode.rs

@@ -1,3 +1,5 @@
+//! Functions for working with Ethereum bytecode.
+
 use crate::utils::strings::decode_hex;
 
 use super::rpc::get_code;

crates/common/src/ether/calldata.rs

@@ -1,3 +1,5 @@
+//! Module for fetching calldata from a target.
+
 use super::rpc::get_transaction;
 use crate::utils::strings::decode_hex;
 use alloy::primitives::TxHash;

crates/common/src/ether/compiler.rs

@@ -1,13 +1,20 @@
+//! Module for compiler detection.
+
 use std::fmt::Display;
 
 use crate::{ether::bytecode::remove_pushbytes_from_bytecode, utils::iter::ByteSliceExt};
 use tracing::{debug, trace, warn};
 
-#[derive(Debug, PartialEq, Clone)]
+/// Compiler enum to represent the compiler used to compile the contract.
+#[derive(Debug, PartialEq, Eq, Clone)]
 pub enum Compiler {
+    /// Indicates that the contract was compiled using the Solidity compiler.
     Solc,
+    /// Indicates that the contract was compiled using the Vyper compiler.
     Vyper,
+    /// Indicates that the contract is a minimal proxy.
     Proxy,
+    /// Indicates that the compiler could not be detected.
     Unknown,
 }
 

crates/common/src/ether/provider.rs

@@ -18,15 +18,19 @@ use std::{fmt::Debug, str::FromStr};
 /// supported by the [`Provider`].
 #[derive(Clone, Debug)]
 pub enum MultiTransportProvider {
+    /// WebSocket transport
     Ws(RootProvider<PubSubFrontend, Ethereum>),
+    /// IPC transport
     Ipc(RootProvider<PubSubFrontend, Ethereum>),
+    /// HTTP transport
     Http(RootProvider<Http<Client>, Ethereum>),
 }
 
 // We implement a convenience "constructor" method, to easily initialize the transport.
 // This will connect to [`Http`] if the rpc_url contains 'http', to [`Ws`] if it contains 'ws',
 // otherwise it'll default to [`Ipc`].
 impl MultiTransportProvider {
+    /// Connect to a provider using the given rpc_url.
     pub async fn connect(rpc_url: &str) -> Result<Self> {
         if rpc_url.is_empty() {
             return Err(eyre::eyre!("No RPC URL provided"));
@@ -45,6 +49,7 @@ impl MultiTransportProvider {
         Ok(this)
     }
 
+    /// Get the chain id.
     pub async fn get_chainid(&self) -> Result<u64> {
         Ok(match self {
             Self::Ws(provider) => provider.get_chain_id().await?,
@@ -53,6 +58,7 @@ impl MultiTransportProvider {
         })
     }
 
+    /// Get the latest block number.
     pub async fn get_block_number(&self) -> Result<u64> {
         Ok(match self {
             Self::Ws(provider) => provider.get_block_number().await?,
@@ -61,6 +67,7 @@ impl MultiTransportProvider {
         })
     }
 
+    /// Get the bytecode at the given address.
     pub async fn get_code_at(&self, address: Address) -> Result<Vec<u8>> {
         Ok(match self {
             Self::Ws(provider) => provider.get_code_at(address).await?,
@@ -70,6 +77,7 @@ impl MultiTransportProvider {
         .to_vec())
     }
 
+    /// Get the transaction by hash.
     pub async fn get_transaction_by_hash(&self, tx_hash: TxHash) -> Result<Option<Transaction>> {
         Ok(match self {
             Self::Ws(provider) => provider.get_transaction_by_hash(tx_hash).await?,
@@ -78,6 +86,8 @@ impl MultiTransportProvider {
         })
     }
 
+    /// Replays the transaction at the given hash.
+    /// The `trace_type` parameter is a list of the types of traces to return.
     pub async fn trace_replay_transaction(
         &self,
         tx_hash: &str,
@@ -92,6 +102,8 @@ impl MultiTransportProvider {
         })
     }
 
+    /// Replays the block at the given number.
+    /// The `trace_type` parameter is a list of the types of traces to return.
     pub async fn trace_replay_block_transactions(
         &self,
         block_number: u64,
@@ -112,6 +124,7 @@ impl MultiTransportProvider {
         })
     }
 
+    /// Get the logs that match the given filter.
     pub async fn get_logs(&self, filter: &Filter) -> Result<Vec<Log>> {
         Ok(match self {
             Self::Ws(provider) => provider.get_logs(filter).await?,

crates/common/src/ether/rpc.rs

@@ -1,3 +1,5 @@
+//! RPC utilities for interacting with Ethereum nodes
+
 use crate::ether::provider::MultiTransportProvider;
 use alloy::{
     eips::BlockNumberOrTag,

crates/common/src/ether/signatures.rs

@@ -1,3 +1,6 @@
+//! This module contains the logic for resolving signatures from
+//! 4-byte function selector or a 32-byte event selector.
+
 use std::path::PathBuf;
 
 use alloy_dyn_abi::{DynSolType, DynSolValue};
@@ -19,16 +22,23 @@ use tracing::{debug, trace};
 
 use super::types::DynSolValueExt;
 
+/// A resolved function signature. May contain decoded inputs.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 pub struct ResolvedFunction {
+    /// The name of the function. For example, `transfer`.
     pub name: String,
+    /// The function signature. For example, `transfer(address,uint256)`.
     pub signature: String,
+    /// The inputs of the function. For example, `["address", "uint256"]`.
     pub inputs: Vec<String>,
+    /// The decoded inputs of the function. For example, `[DynSolValue::Address("0x1234"),
+    /// DynSolValue::Uint(123)]`.
     #[serde(skip)]
     pub decoded_inputs: Option<Vec<DynSolValue>>,
 }
 
 impl ResolvedFunction {
+    /// Returns the inputs of the function as a vector of [`DynSolType`]s.
     pub fn inputs(&self) -> Vec<DynSolType> {
         parse_function_parameters(&self.signature).expect("invalid signature")
     }
@@ -59,34 +69,45 @@ impl ResolvedFunction {
     }
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+/// A resolved error signature.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub struct ResolvedError {
+    /// The name of the error. For example, `revert`.
     pub name: String,
+    /// The error signature. For example, `revert(string)`.
     pub signature: String,
+    /// The inputs of the error. For example, `["string"]`.
     pub inputs: Vec<String>,
 }
 
 impl ResolvedError {
+    /// Returns the inputs of the error as a vector of [`DynSolType`]s.
     pub fn inputs(&self) -> Vec<DynSolType> {
         parse_function_parameters(&self.signature).expect("invalid signature")
     }
 }
-
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+/// A resolved log signature.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub struct ResolvedLog {
+    /// The name of the log. For example, `Transfer`.
     pub name: String,
+    /// The log signature. For example, `Transfer(address,address,uint256)`.
     pub signature: String,
+    /// The inputs of the log. For example, `["address", "address", "uint256"]`.
     pub inputs: Vec<String>,
 }
 
 impl ResolvedLog {
+    /// Returns the inputs of the log as a vector of [`DynSolType`]s.
     pub fn inputs(&self) -> Vec<DynSolType> {
         parse_function_parameters(&self.signature).expect("invalid signature")
     }
 }
-
+/// A trait for resolving a selector into a vector of [`ResolvedFunction`]s, [`ResolvedError`]s, or
 #[async_trait]
 pub trait ResolveSelector {
+    /// Resolves a selector into a vector of [`ResolvedFunction`]s, [`ResolvedError`]s, or
+    /// [`ResolvedLog`]s.
     async fn resolve(selector: &str) -> Result<Option<Vec<Self>>>
     where
         Self: Sized;
@@ -356,6 +377,7 @@ pub fn cache_signatures_from_abi(path: PathBuf) -> Result<()> {
     Ok(())
 }
 
+/// Heuristic to score a function signature based on its spamminess.
 pub fn score_signature(signature: &str, num_words: Option<usize>) -> u32 {
     // the score starts at 1000
     let mut score = 1000;