documentation

Author: Jon-Becker

Cargo.toml

@@ -45,7 +45,7 @@ rust.missing_debug_implementations = "warn"
 rust.missing_docs = "warn"
 rust.unreachable_pub = "warn"
 rust.unused_must_use = "deny"
-rust.rust_2018_idioms = "deny"
+rust.rust_2018_idioms = { level = "deny", priority = -1 }
 rustdoc.all = "warn"
 
 [workspace.lints.clippy]

crates/common/src/ether/bytecode.rs

@@ -42,11 +42,11 @@ pub fn remove_pushbytes_from_bytecode(bytecode: alloy::primitives::Bytes) -> Res
 
     let mut i = 0;
     while i < bytecode.len() {
+        pruned.push(bytecode[i]);
+
         if push_range.contains(&bytecode[i]) {
-            pruned.push(bytecode[i]);
             i += bytecode[i] as usize - 0x5f + 1;
         } else {
-            pruned.push(bytecode[i]);
             i += 1;
         }
     }

crates/common/src/ether/types.rs

@@ -75,10 +75,7 @@ fn extract_types_from_string(string: &str) -> Result<Vec<DynSolType>> {
                     let array_range = find_balanced_encapsulator(split, ('[', ']'))?;
 
                     let size = split[array_range].to_string();
-                    array_size = match size.parse::<usize>() {
-                        Ok(size) => Some(size),
-                        Err(_) => None,
-                    };
+                    array_size = size.parse::<usize>().ok();
                 }
             }
 
@@ -180,10 +177,7 @@ pub fn to_type(string: &str) -> DynSolType {
 
         let size = string[array_range].to_string();
 
-        array_size.push_back(match size.parse::<usize>() {
-            Ok(size) => Some(size),
-            Err(_) => None,
-        });
+        array_size.push_back(size.parse::<usize>().ok());
 
         string = string.replacen(&format!("[{}]", &size), "", 1);
     }

crates/common/src/lib.rs

@@ -1,4 +1,17 @@
+//! Common utilities, constants, and resources used across the Heimdall codebase.
+//!
+//! This crate provides shared functionality for the Heimdall toolkit, including
+//! Ethereum-related utilities, common resources, and general utility functions.
+
+/// Constants used throughout the Heimdall codebase.
 pub mod constants;
+
+/// Utilities for interacting with Ethereum, including bytecode, calldata,
+/// and RPC functionality.
 pub mod ether;
+
+/// External resources and API integrations, such as OpenAI and Transpose.
 pub mod resources;
+
+/// General utility functions and types for common tasks.
 pub mod utils;

crates/common/src/resources/mod.rs

@@ -1,2 +1,5 @@
+/// OpenAI API integration for AI-powered analysis.
 pub mod openai;
+
+/// Transpose API integration for blockchain data access.
 pub mod transpose;

crates/common/src/utils/env.rs

@@ -1,9 +1,24 @@
+/// Sets an environment variable if it's not already set.
+///
+/// # Arguments
+///
+/// * `key` - The environment variable name
+/// * `value` - The value to set
 pub fn set_env(key: &str, value: &str) {
     if std::env::var(key).is_err() {
         std::env::set_var(key, value);
     }
 }
 
+/// Gets the value of an environment variable.
+///
+/// # Arguments
+///
+/// * `key` - The environment variable name to retrieve
+///
+/// # Returns
+///
+/// * `Option<String>` - The environment variable value if it exists
 pub fn get_env(key: &str) -> Option<String> {
     std::env::var(key).ok()
 }

crates/common/src/utils/hex.rs

@@ -1,8 +1,13 @@
 use super::strings::encode_hex;
 use alloy::primitives::{Address, Bytes, FixedBytes, U256};
 
-/// A convenience function which encodes a given EVM type into a sized, lowercase hex string.
+/// A convenience trait which encodes a given EVM type into a sized, lowercase hex string.
 pub trait ToLowerHex {
+    /// Converts the value to a lowercase hexadecimal string representation.
+    ///
+    /// # Returns
+    ///
+    /// * `String` - The lowercase hexadecimal representation
     fn to_lower_hex(&self) -> String;
 }
 

crates/common/src/utils/integers.rs

@@ -1,4 +1,15 @@
+/// Trait for formatting numbers with locale-specific formatting.
+///
+/// This trait adds methods to format numbers in a more human-readable way,
+/// such as adding thousands separators.
 pub trait ToLocaleString {
+    /// Formats a number with locale-specific formatting.
+    ///
+    /// For numbers, this adds commas as thousand separators.
+    ///
+    /// # Returns
+    ///
+    /// * `String` - The formatted string
     fn to_locale_string(&self) -> String;
 }
 

crates/common/src/utils/io/logging.rs

@@ -6,29 +6,43 @@ use super::super::strings::replace_last;
 /// Has several helper functions to add different types of traces.
 #[derive(Clone, Debug)]
 pub struct TraceFactory {
+    /// The level of the trace. Higher numbers mean more verbose output.
     pub level: i8,
+    /// The collection of traces gathered during execution.
     pub traces: Vec<Trace>,
 }
 
 /// The trace category is used to determine how the trace is formatted.
 #[derive(Clone, Debug)]
 pub enum TraceCategory {
+    /// Standard log message.
     Log,
+    /// Log message with unknown source.
     LogUnknown,
+    /// General message.
     Message,
+    /// Function call trace.
     Call,
+    /// Contract creation trace.
     Create,
+    /// Empty trace (placeholder).
     Empty,
+    /// Contract self-destruct trace.
     Suicide,
 }
 
 /// Individual trace, which is added to the trace factory.
 #[derive(Clone, Debug)]
 pub struct Trace {
+    /// The category of the trace, determining its formatting and interpretation.
     pub category: TraceCategory,
+    /// The instruction number or identifier for this trace.
     pub instruction: u32,
+    /// The message content of the trace, potentially multiple lines.
     pub message: Vec<String>,
+    /// The parent trace identifier (if this is a child trace).
     pub parent: u32,
+    /// Child trace identifiers that are nested under this trace.
     pub children: Vec<u32>,
 }
 
@@ -246,6 +260,24 @@ impl TraceFactory {
         self.add("call", parent_index, instruction, vec![title, returns])
     }
 
+    /// Adds a function call trace with extra information.
+    ///
+    /// This method creates a trace entry for a function call and includes additional context
+    /// information.
+    ///
+    /// # Arguments
+    ///
+    /// * `parent_index` - The index of the parent trace
+    /// * `instruction` - The instruction identifier
+    /// * `origin` - The origin context (e.g., contract name)
+    /// * `function_name` - The name of the function being called
+    /// * `args` - The arguments passed to the function
+    /// * `returns` - The return value(s) of the function
+    /// * `extra` - Additional context information to display
+    ///
+    /// # Returns
+    ///
+    /// * `u32` - The index of the newly added trace
     #[allow(clippy::too_many_arguments)]
     pub fn add_call_with_extra(
         &mut self,

crates/common/src/utils/io/macros.rs

@@ -1,3 +1,12 @@
+/// Creates a spinner with an INFO-level style for progress indicators.
+///
+/// This macro generates a progress style with a timestamp, an "INFO" label,
+/// and a spinning animation character that can be used with the indicatif
+/// crate's ProgressBar to show ongoing operations.
+///
+/// # Returns
+///
+/// * `ProgressStyle` - A styled progress indicator for info-level messages
 #[macro_export]
 macro_rules! info_spinner {
     () => {
@@ -12,6 +21,15 @@ macro_rules! info_spinner {
     };
 }
 
+/// Creates a spinner with a DEBUG-level style for progress indicators.
+///
+/// This macro generates a progress style with a timestamp, a "DEBUG" label,
+/// and a spinning animation character that can be used with the indicatif
+/// crate's ProgressBar to show ongoing operations at debug level.
+///
+/// # Returns
+///
+/// * `ProgressStyle` - A styled progress indicator for debug-level messages
 #[macro_export]
 macro_rules! debug_spinner {
     () => {

crates/common/src/utils/io/mod.rs

@@ -1,4 +1,11 @@
+/// File system operations and utilities.
 pub mod file;
+
+/// Logging functionality and utilities.
 pub mod logging;
+
+/// Macros for input/output operations.
 pub mod macros;
+
+/// Types used for input/output operations.
 pub mod types;

crates/common/src/utils/io/types.rs

@@ -67,8 +67,23 @@ pub fn display(inputs: Vec<DynSolValue>, prefix: &str) -> Vec<String> {
     output
 }
 
+/// Trait for converting values to parameterized strings and type information.
+///
+/// This trait is used primarily for displaying and serializing function parameters
+/// in a readable format when presenting decoded contract data.
 pub trait Parameterize {
+    /// Converts the value to a parameterized string representation.
+    ///
+    /// # Returns
+    ///
+    /// * `String` - The string representation of the parameter value
     fn parameterize(&self) -> String;
+
+    /// Returns the type name of the parameter as a string.
+    ///
+    /// # Returns
+    ///
+    /// * `String` - The type name (e.g., "uint256", "address", etc.)
     fn to_type(&self) -> String;
 }
 

crates/common/src/utils/iter.rs

@@ -1,5 +1,25 @@
+/// Extension trait for byte slices that adds helpful operations.
 pub trait ByteSliceExt {
+    /// Splits a byte slice by a delimiter byte slice.
+    ///
+    /// # Arguments
+    ///
+    /// * `delimiter` - The byte sequence to split on
+    ///
+    /// # Returns
+    ///
+    /// * `Vec<&[u8]>` - The split parts
     fn split_by_slice(&self, delimiter: &[u8]) -> Vec<&[u8]>;
+
+    /// Checks if a byte slice contains another byte slice.
+    ///
+    /// # Arguments
+    ///
+    /// * `sequence` - The byte sequence to search for
+    ///
+    /// # Returns
+    ///
+    /// * `bool` - `true` if the sequence is found, `false` otherwise
     fn contains_slice(&self, sequence: &[u8]) -> bool;
 }
 
@@ -36,6 +56,19 @@ impl ByteSliceExt for [u8] {
     }
 }
 
+/// Removes elements at specified indices from a collection.
+///
+/// This function takes a collection and a sorted list of indices, and removes
+/// the elements at those indices from the collection.
+///
+/// # Arguments
+///
+/// * `v` - The collection to remove elements from
+/// * `indices` - A sorted list of indices to remove
+///
+/// # Returns
+///
+/// * `Vec<T>` - A new collection with the elements at the specified indices removed
 pub fn remove_sorted_indices<T>(
     v: impl IntoIterator<Item = T>,
     indices: impl IntoIterator<Item = usize>,

crates/common/src/utils/mod.rs

@@ -1,11 +1,32 @@
+/// Environment variable utilities.
 pub mod env;
+
+/// Hexadecimal encoding and decoding utilities.
 pub mod hex;
+
+/// HTTP request and response handling utilities.
 pub mod http;
+
+/// Integer manipulation and formatting utilities.
 pub mod integers;
+
+/// Input/output utilities for file manipulation and logging.
 pub mod io;
+
+/// Iterator and collection utilities.
 pub mod iter;
+
+/// String manipulation and formatting utilities.
 pub mod strings;
+
+/// Synchronization primitives and utilities.
 pub mod sync;
+
+/// Threading and multi-threading utilities.
 pub mod threading;
+
+/// Time manipulation and formatting utilities.
 pub mod time;
+
+/// Version handling and management utilities.
 pub mod version;

crates/common/src/utils/strings.rs

@@ -271,7 +271,17 @@ pub fn extract_condition(s: &str, keyword: &str) -> Option<String> {
     None
 }
 
+/// Extension trait for strings that adds helpful operations.
 pub trait StringExt {
+    /// Truncates a string to a maximum length, adding an ellipsis if necessary.
+    ///
+    /// # Arguments
+    ///
+    /// * `max_length` - The maximum length of the returned string
+    ///
+    /// # Returns
+    ///
+    /// * `String` - The truncated string with ellipsis if needed
     fn truncate(&self, max_length: usize) -> String;
 }
 
@@ -365,11 +375,17 @@ pub fn tokenize(s: &str) -> Vec<String> {
 }
 
 #[derive(Debug, PartialEq, Eq)]
+/// Classification for tokens in code analysis.
 pub enum TokenType {
+    /// Control flow related tokens (if, while, for, etc).
     Control,
+    /// Operators (+, -, *, /, etc).
     Operator,
+    /// Constant values (numbers, string literals, etc).
     Constant,
+    /// Variable identifiers.
     Variable,
+    /// Function identifiers.
     Function,
 }
 

crates/common/src/utils/sync.rs

@@ -7,4 +7,8 @@ where
     tokio::task::block_in_place(f)
 }
 
+/// A boxed future with a static lifetime.
+///
+/// This type alias is a convenience for returning a boxed future from a function.
+/// The future is pinned and can be awaited.
 pub type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + 'a>>;