documentation

Author: Jon-Becker

crates/core/src/error.rs

@@ -1,19 +1,27 @@
 // TODO: after all errors are fixed, remove most instances of Generic for
 // specific errors (e.g. ParseError, FilesystemError, etc.)
+/// Error type for the Core module
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
+    /// Error when serializing or deserializing JSON data
     #[error("Json error: {0}")]
     SerdeError(#[from] serde_json::Error),
+    /// Error when accessing data out of bounds
     #[error("BoundsError")]
     BoundsError,
+    /// Error when decoding data
     #[error("DecodeError")]
     DecodeError,
+    /// Error when interacting with an RPC endpoint
     #[error("RPCError: {0}")]
     RpcError(String),
+    /// Generic error with a message
     #[error("Error: {0}")]
     Generic(String),
+    /// Error when transforming data structures
     #[error("TransposeError: {0}")]
     TransposeError(String),
+    /// Error when parsing data
     #[error("Parse error: {0}")]
     ParseError(String),
 }

crates/core/src/lib.rs

@@ -1,5 +1,13 @@
+//! The Core module serves as the central integration point for all Heimdall's
+//! functionality, providing access to various analysis tools for Ethereum smart contracts.
+//!
+//! This module re-exports the public interfaces of all the tool-specific crates,
+//! making it easier to use Heimdall's capabilities in other projects.
+
+/// Error types for the core module
 pub mod error;
 
+// Re-export all tool-specific modules
 pub use heimdall_cfg;
 pub use heimdall_decoder;
 pub use heimdall_decompiler;

crates/decode/src/core/mod.rs

@@ -23,17 +23,37 @@ use crate::{
 };
 
 #[derive(Debug, Clone)]
+/// Result of a successful decode operation
+///
+/// Contains the decoded function signature and parameters, as well as
+/// a trace factory for displaying the result in a formatted way.
 pub struct DecodeResult {
+    /// The resolved function with its decoded inputs
     pub decoded: ResolvedFunction,
     _trace: TraceFactory,
 }
 
 impl DecodeResult {
+    /// Displays the decoded function signature and parameters in a formatted way
     pub fn display(&self) {
         self._trace.display();
     }
 }
 
+/// Decodes EVM calldata into human-readable function signatures and parameters
+///
+/// This function attempts to identify the function being called based on the function
+/// selector in the calldata, and then decodes the remaining data according to the
+/// function's parameter types. If no matching function is found, it will attempt
+/// to infer the parameter types from the raw calldata.
+///
+/// # Arguments
+///
+/// * `args` - Configuration parameters for the decode operation
+///
+/// # Returns
+///
+/// A DecodeResult containing the resolved function and its decoded parameters
 pub async fn decode(mut args: DecodeArgs) -> Result<DecodeResult, Error> {
     let start_time = Instant::now();
 

crates/decode/src/error.rs

@@ -1,9 +1,13 @@
+/// Error type for the Decoder module
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
+    /// Error when fetching data from external sources
     #[error("Fetch error: {0}")]
     FetchError(String),
+    /// Generic internal error
     #[error("Internal error: {0}")]
     Eyre(#[from] eyre::Report),
+    /// Error when accessing data out of bounds
     #[error("Bounds error")]
     BoundsError,
 }

crates/decode/src/interfaces/args.rs

@@ -10,6 +10,10 @@ use heimdall_config::parse_url_arg;
     after_help = "For more information, read the wiki: https://jbecker.dev/r/heimdall-rs/wiki",
     override_usage = "heimdall decode <TARGET> [OPTIONS]"
 )]
+/// Arguments for the decode operation
+///
+/// This struct contains all the configuration parameters needed to decode
+/// calldata into human-readable function signatures and parameters.
 pub struct DecodeArgs {
     /// The target to decode, either a transaction hash or string of bytes.
     #[clap(required = true)]
@@ -59,12 +63,20 @@ pub struct DecodeArgs {
 }
 
 impl DecodeArgs {
+    /// Retrieves the calldata from the specified target
+    ///
+    /// This method fetches the calldata from a transaction hash, raw hex string,
+    /// or directly from the provided target, depending on the configuration options.
+    ///
+    /// # Returns
+    /// The raw calldata as a vector of bytes
     pub async fn get_calldata(&self) -> Result<Vec<u8>> {
         get_calldata_from_target(&self.target, self.raw, &self.rpc_url).await
     }
 }
 
 impl DecodeArgsBuilder {
+    /// Creates a new DecodeArgsBuilder with default values
     pub fn new() -> Self {
         Self {
             target: Some(String::new()),

crates/decode/src/lib.rs

@@ -1,3 +1,10 @@
+//! The Decode module provides functionality to decode EVM calldata into
+//! human-readable function signatures and parameters.
+//!
+//! This module enables the analysis of raw transaction data by identifying the
+//! function being called and properly parsing its parameters.
+
+/// Error types for the decoder module
 pub mod error;
 
 mod core;

crates/decompile/src/core/mod.rs

@@ -39,11 +39,30 @@ use crate::{
 use tracing::{debug, info, warn};
 
 #[derive(Debug, Clone)]
+/// Result of a successful decompile operation
+///
+/// Contains the decompiled source code (if requested) and the reconstructed ABI
+/// of the contract.
 pub struct DecompileResult {
+    /// The decompiled source code in Solidity or Yul format (if requested)
     pub source: Option<String>,
+    /// The reconstructed JSON ABI of the contract
     pub abi: JsonAbi,
 }
 
+/// Decompiles EVM bytecode into higher-level Solidity-like code
+///
+/// This function analyzes the bytecode of a contract through symbolic execution
+/// and attempts to reconstruct the original source code or a functionally equivalent
+/// representation. It also generates an ABI for the contract.
+///
+/// # Arguments
+///
+/// * `args` - Configuration parameters for the decompile operation
+///
+/// # Returns
+///
+/// A DecompileResult containing the decompiled source (if requested) and the ABI
 pub async fn decompile(args: DecompilerArgs) -> Result<DecompileResult, Error> {
     // init
     let start_time = Instant::now();

crates/decompile/src/error.rs

@@ -1,9 +1,13 @@
+/// Error type for the Decompiler module
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
+    /// Error when fetching data from external sources
     #[error("Fetch error: {0}")]
     FetchError(String),
+    /// Error during the disassembly process
     #[error("Disassembly error: {0}")]
     DisassemblyError(#[from] heimdall_disassembler::Error),
+    /// Generic internal error
     #[error("Internal error: {0}")]
     Eyre(#[from] eyre::Report),
 }

crates/decompile/src/interfaces/args.rs

@@ -10,6 +10,10 @@ use heimdall_config::parse_url_arg;
     after_help = "For more information, read the wiki: https://jbecker.dev/r/heimdall-rs/wiki",
     override_usage = "heimdall decompile <TARGET> [OPTIONS]"
 )]
+/// Arguments for the decompile operation
+///
+/// This struct contains all the configuration parameters needed to decompile
+/// bytecode into human-readable source code and ABI.
 pub struct DecompilerArgs {
     /// The target to decompile, either a file, bytecode, contract address, or ENS name.
     #[clap(required = true)]
@@ -62,12 +66,20 @@ pub struct DecompilerArgs {
 }
 
 impl DecompilerArgs {
+    /// Retrieves the bytecode for the specified target
+    ///
+    /// This method fetches the bytecode from a file, address, or directly from a hex string,
+    /// depending on the target type provided in the arguments.
+    ///
+    /// # Returns
+    /// The raw bytecode as a vector of bytes
     pub async fn get_bytecode(&self) -> Result<Vec<u8>> {
         get_bytecode_from_target(&self.target, &self.rpc_url).await
     }
 }
 
 impl DecompilerArgsBuilder {
+    /// Creates a new DecompilerArgsBuilder with default values
     pub fn new() -> Self {
         Self {
             target: Some(String::new()),

crates/decompile/src/lib.rs

@@ -1,3 +1,11 @@
+//! The Decompile module provides functionality to convert EVM bytecode
+//! into higher-level Solidity-like code.
+//!
+//! This module enables the analysis of compiled smart contracts by reconstructing
+//! the original source code structure, making bytecode more human-readable and
+//! understandable.
+
+/// Error types for the decompiler module
 mod error;
 
 mod core;

crates/disassemble/src/core/mod.rs

@@ -6,6 +6,19 @@ use heimdall_common::utils::strings::encode_hex;
 use heimdall_vm::core::opcodes::opcode_name;
 use tracing::{debug, info};
 
+/// Disassembles EVM bytecode into readable assembly instructions
+///
+/// This function takes the bytecode of a contract and converts it into a string
+/// representation of the equivalent EVM assembly code. It handles special cases
+/// like PUSH operations which consume additional bytes as data.
+///
+/// # Arguments
+///
+/// * `args` - Arguments specifying the target and disassembly options
+///
+/// # Returns
+///
+/// A string containing the disassembled bytecode in assembly format
 pub async fn disassemble(args: DisassemblerArgs) -> Result<String, Error> {
     // init
     let start_time = Instant::now();

crates/disassemble/src/error.rs

@@ -1,5 +1,7 @@
+/// Error type for the Disassembler module
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
+    /// Generic internal error that may occur during disassembly
     #[error("Internal error: {0}")]
     Eyre(#[from] eyre::Report),
 }

crates/disassemble/src/interfaces/args.rs

@@ -9,6 +9,10 @@ use heimdall_config::parse_url_arg;
     after_help = "For more information, read the wiki: https://jbecker.dev/r/heimdall-rs/wiki",
     override_usage = "heimdall disassemble <TARGET> [OPTIONS]"
 )]
+/// Arguments for the disassembly operation
+///
+/// This struct contains all the configuration parameters needed to disassemble
+/// a contract's bytecode into human-readable assembly.
 pub struct DisassemblerArgs {
     /// The target to disassemble, either a file, bytecode, contract address, or ENS name.
     #[clap(required = true)]
@@ -33,6 +37,10 @@ pub struct DisassemblerArgs {
 }
 
 #[derive(Debug, Clone)]
+/// Builder for DisassemblerArgs
+///
+/// This struct provides a builder pattern for creating DisassemblerArgs instances
+/// with a fluent API.
 pub struct DisassemblerArgsBuilder {
     /// The target to disassemble, either a file, bytecode, contract address, or ENS name.
     target: Option<String>,
@@ -51,6 +59,13 @@ pub struct DisassemblerArgsBuilder {
 }
 
 impl DisassemblerArgs {
+    /// Retrieves the bytecode for the specified target
+    ///
+    /// This method fetches the bytecode from a file, address, or directly from a hex string,
+    /// depending on the target type provided in the arguments.
+    ///
+    /// # Returns
+    /// The raw bytecode as a vector of bytes
     pub async fn get_bytecode(&self) -> Result<Vec<u8>> {
         get_bytecode_from_target(&self.target, &self.rpc_url).await
     }
@@ -63,6 +78,7 @@ impl Default for DisassemblerArgsBuilder {
 }
 
 impl DisassemblerArgsBuilder {
+    /// Creates a new DisassemblerArgsBuilder with default values
     pub fn new() -> Self {
         Self {
             target: Some(String::new()),
@@ -73,31 +89,40 @@ impl DisassemblerArgsBuilder {
         }
     }
 
+    /// Sets the target for disassembly (address, file, or bytecode)
     pub fn target(&mut self, target: String) -> &mut Self {
         self.target = Some(target);
         self
     }
 
+    /// Sets the RPC URL for fetching bytecode if the target is an address
     pub fn rpc_url(&mut self, rpc_url: String) -> &mut Self {
         self.rpc_url = Some(rpc_url);
         self
     }
 
+    /// Sets whether to use decimal (true) or hexadecimal (false) for program counter
     pub fn decimal_counter(&mut self, decimal_counter: bool) -> &mut Self {
         self.decimal_counter = Some(decimal_counter);
         self
     }
 
+    /// Sets the name for the output file
     pub fn name(&mut self, name: String) -> &mut Self {
         self.name = Some(name);
         self
     }
 
+    /// Sets the output directory or 'print' to print to console
     pub fn output(&mut self, output: String) -> &mut Self {
         self.output = Some(output);
         self
     }
 
+    /// Builds the DisassemblerArgs from the builder
+    ///
+    /// # Returns
+    /// A Result containing the built DisassemblerArgs or an error if required fields are missing
     pub fn build(&self) -> eyre::Result<DisassemblerArgs> {
         Ok(DisassemblerArgs {
             target: self.target.clone().ok_or_else(|| eyre::eyre!("target is required"))?,

crates/disassemble/src/lib.rs

@@ -1,4 +1,11 @@
-mod error;
+//! The Disassembler module provides functionality to convert EVM bytecode
+//! into human-readable assembly instructions.
+//!
+//! This module enables the translation of raw bytecode into meaningful operations,
+//! which is a critical step for understanding and analyzing smart contracts.
+
+/// Error types for the disassembler module
+pub mod error;
 
 mod core;
 mod interfaces;

crates/dump/src/core/mod.rs

@@ -16,6 +16,18 @@ use tracing::{debug, info};
 
 use crate::{error::Error, interfaces::DumpArgs};
 
+/// Dumps the storage slots for a contract
+///
+/// This function retrieves storage slots from a contract by analyzing state differences
+/// across multiple blocks. It uses parallel processing to efficiently handle large block ranges.
+///
+/// # Arguments
+///
+/// * `args` - Configuration parameters for the dump operation
+///
+/// # Returns
+///
+/// A HashMap containing the storage slots (keys) and their values
 pub async fn dump(args: DumpArgs) -> Result<HashMap<FixedBytes<32>, FixedBytes<32>>, Error> {
     let start_time = Instant::now();
     let storage = Arc::new(Mutex::new(HashMap::new()));

crates/dump/src/error.rs

@@ -1,7 +1,9 @@
 // TODO: after all errors are fixed, remove most instances of Generic for
 // specific errors (e.g. ParseError, FilesystemError, etc.)
+/// Generic error type for the Dump Module
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
+    /// Generic internal error
     #[error("Internal error: {0}")]
     Eyre(#[from] eyre::Report),
 }

crates/dump/src/interfaces/args.rs

@@ -8,6 +8,10 @@ use heimdall_config::parse_url_arg;
     after_help = "For more information, read the wiki: https://jbecker.dev/r/heimdall-rs/wiki",
     override_usage = "heimdall dump <TARGET> [OPTIONS]"
 )]
+/// Arguments for the dump operation
+///
+/// This struct contains all the configuration parameters needed to perform
+/// a storage slot dump for a target contract.
 pub struct DumpArgs {
     /// The target to find and dump the storage slots of.
     #[clap(required = true)]
@@ -40,6 +44,7 @@ pub struct DumpArgs {
 }
 
 impl DumpArgsBuilder {
+    /// Creates a new DumpArgsBuilder with default values
     pub fn new() -> Self {
         Self {
             target: Some(String::new()),