# Heimdall-rs for EVM Bytecode Analysis and Decompilation

> Heimdall-rs is a Rust toolkit for inspecting unverified EVM smart contracts, disassembling bytecode, generating control flow graphs, decoding transactions, and recovering higher-level code. Its main trade-off is specialization for EVM analysis rather than a general-purpose smart contract development workflow.

**Jon-Becker/heimdall-rs** — Heimdall is an advanced EVM smart contract toolkit specializing in bytecode analysis and extracting information from unverified contracts.

- Repository: https://github.com/Jon-Becker/heimdall-rs
- Website: http://heimdall.rs
- Stars: 1,639 · Forks: 180
- Language: Rust
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/jon-becker-heimdall-rs

## What Heimdall-rs Does With Unverified EVM Code

Heimdall-rs addresses a specific problem in Ethereum development: a deployed contract may expose bytecode without publishing the Solidity source that produced it. That makes ordinary source-oriented inspection incomplete. The toolkit is aimed at researchers, security analysts, contract investigators, and developers who need information from EVM bytecode directly.

The repository lists bytecode disassembly, control flow graph generation, decompilation, storage dumping, raw calldata decoding, and raw transaction trace decoding as its supported operations. These are related but distinct forms of analysis. Disassembly focuses on the instruction-level representation. A control flow graph adds branching and control-transfer structure. Decompilation attempts to turn bytecode into a higher-level representation. Storage and transaction analysis address state and calldata rather than only contract code.

That scope makes Heimdall-rs more specialized than a normal Rust library or a generic bytecode viewer. The project is written in Rust and organized as a Cargo workspace with separate crates for disassembly, decompilation, tracing, inspection, decoding, configuration, caching, core logic, storage dumping, CLI functionality, control flow graphs, and VM support. The README does not provide a complete command reference, so users still need the wiki or the repository examples to determine the exact operation and input format for a particular investigation.

## The Cargo Workspace and Analysis Pipeline

The repository layout shows that Heimdall-rs is designed as a collection of cooperating crates rather than one monolithic program. `crates/disassemble`, `crates/cfg`, and `crates/decompile` correspond directly to the low-level, graph, and higher-level analysis paths. Other crates handle concerns such as `crates/decode`, `crates/tracing`, `crates/dump`, `crates/inspect`, and the `crates/cli` entry point.

The workspace structure suggests a staged data flow. EVM bytecode can first be interpreted as instructions, then represented with control flow relationships, and then processed by decompilation. Other paths accept transaction calldata or traces, while the dump operation works with contract storage. Shared concerns are separated into `common`, `core`, `config`, `cache`, and `vm` crates. That separation is useful for code organization and makes each analysis capability available as a distinct unit.

The `examples/` directory includes folders for `disassemble`, `cfg`, `decompile`, `dump`, `decode`, `decode_offline`, `inspect`, and language bindings under `python` and `typescript`. Based on those directory names, the repository is intended to demonstrate both command-line workflows and programmatic or offline decoding paths. The README does not explain the internal representations, intermediate formats, cache keys, or VM behavior in enough detail to claim that outputs from one operation can be fed automatically into every other operation. Engineers integrating Heimdall-rs should inspect the relevant crate and example rather than assume a shared pipeline.

## Installation Through bifrost and Rust Tooling

The documented installation path depends on Rust, Cargo, and Heimdall's update and installation manager, `bifrost`. The README first instructs users to install Rust and Cargo with the Rustup shell script. It then provides an HTTP installer for `bifrost`. Running `bifrost` from a new terminal is the documented way to install Heimdall. After compilation, the `heimdall` command becomes available from a new terminal.

The first command installs the Rust toolchain. It changes the user's machine rather than the Heimdall project, so the README says to ensure Rust and Cargo are installed before continuing:

```bash
curl https://sh.rustup.rs -sSf | sh
```

The next command installs `bifrost` through the project-provided installer. The README does not describe the contents or verification mechanism of that script, so production environments should review the download path before piping it into a shell:

```bash
curl -L http://get.heimdall.rs | bash
```

With `bifrost` available, invoke it without arguments. The README says to run this from a new terminal after installation:

```bash
bifrost
```

The README also offers a manual route through the latest release in the `bifrost/bifrost` directory. Its advanced options are delegated to the bifrost documentation, rather than documented in the project overview. The repository also contains a `Dockerfile`, but the README does not give a Docker installation tutorial. It therefore should not be treated as a documented deployment path without checking the image behavior and build requirements separately.

## A First Real Use of the heimdall Command

The repository confirms the executable name as `heimdall`, but the README does not document a concrete analysis command, input flag, output format, or example invocation. Consequently, there is not enough information here to invent a first disassembly or decompilation command. The safest first documented action is to invoke the installed executable and consult its own output or the linked wiki for the required subcommand.

Use the following command to start Heimdall without assuming an undocumented option:

```bash
heimdall
```

What the reader should see is the behavior of the installed Heimdall executable, which may present usage information or an error about required input. The README does not state which of those outcomes applies, so it would be inaccurate to promise a particular menu, prompt, or success message.

For source-oriented exploration, the repository's `examples/` directories are the better documented starting point. They include `disassemble`, `cfg`, `decompile`, `dump`, `decode`, `decode_offline`, and `inspect` examples, plus Python and TypeScript directories. Their exact invocations must be read from the files themselves. A practical adoption check is therefore to locate the example matching the target bytecode or transaction data, use that input format, and record whether the output preserves the control flow and storage information required for the investigation. The README does not document rollback, network access requirements, or supported EVM forks, so those points must be checked before relying on an analysis result.

## Operational Limits for Decompilation and Transaction Analysis

The central limitation is the boundary between recovering useful information and proving what a contract means. Decompilation can expose recognizable structure, but the repository description does not claim that Heimdall-rs reconstructs the original Solidity source, variable names, comments, compiler version, or source-level intent. Unverified bytecode may also contain compiler optimizations, generated dispatch logic, packed data, or obfuscation that makes interpretation less direct.

The toolkit's other operations also need precise inputs. Raw calldata decoding is useful only when the transaction data and ABI context are interpreted correctly. Raw trace decoding is tied to trace structure. Storage dumping requires access to the state or RPC data that the operation expects, although the README does not specify the provider configuration. Control flow graph generation can make branching visible, but a graph does not by itself establish whether a path is reachable under current state or whether a vulnerability exists.

Heimdall-rs is therefore the wrong tool when the requirement is to prove behavior from verified source, replace formal verification, or guarantee that every contract vulnerability will be found. A source-aware Solidity compiler and audit workflow is a different approach because it starts from source code and compilation artifacts rather than treating deployed bytecode as the primary input. The README does not provide benchmark data, false-positive rates, or a formal accuracy specification, so adoption should be based on representative contract samples and verification of specific outputs.

## Rust Versioning, Build Cost, and MIT Licensing

The workspace declares Rust `1.91` as its `rust-version`, edition `2021`, and MIT licensing. The `rust-toolchain.toml` file is also present, so a Rust-based installation may rely on a pinned toolchain setup rather than whichever compiler happens to be active. The release profile uses fat link-time optimization, one codegen unit, and disabled incremental compilation. Those settings favor release size and optimization over quick rebuilds, which can increase build time for the workspace.

The `Makefile` exposes separate debug and release builds, checks, formatting, Clippy linting, tests, documentation tests, coverage targets, benchmarks, and installation of the Heimdall CLI. The documented build commands are ordinary Cargo operations. For example, the repository's `build` target runs the workspace build, while `check` includes all targets and features. The Makefile also relies on `cargo nextest` for its `test` target and nightly Rust for formatting, so contributors need additional tooling for those workflows.

The MIT license permits use, modification, distribution, and sublicensing under the license's stated conditions, but this is not legal advice. Applications that redistribute Heimdall-rs or incorporate its crates should preserve the required license and notice information. The repository's release history includes versions `0.9.1`, `0.9.2`, and `0.9.3`, and the workspace metadata currently shows version `0.9.2`. The last push was on 2026-10-11, so there is no archive indicator, but the README does not define a compatibility policy for upgrades. Before changing versions, inspect the relevant release and test the selected analysis against known fixtures.

## Conclusion

Adopt Heimdall-rs when you need a focused command-line toolkit for EVM bytecode inspection or unverified contract investigation. Do not treat its decompilation output as verified source or as a complete security assessment. Check first that your target uses supported EVM bytecode, that the selected operation is available in your installation, and that the MIT license fits your distribution and review requirements.

## FAQ

### How do I install Heimdall-rs?

The README instructs users to install Rust and Cargo, install `bifrost`, and then run `bifrost` from a new terminal. It also provides a manual route through the latest release in the `bifrost/bifrost` directory.

### What can Heimdall-rs analyze?

The project lists EVM bytecode disassembly, smart-contract control flow graph generation, decompilation, storage dumping, raw calldata decoding, and raw transaction trace decoding.

### Does Heimdall-rs recover verified Solidity source?

The README describes Heimdall-rs as a toolkit for analyzing and extracting information from unverified contracts. It does not claim that decompilation reconstructs verified source or guarantees source-level accuracy.

## Sources

- [Jon-Becker/heimdall-rs on GitHub](https://github.com/Jon-Becker/heimdall-rs)
- [License: MIT](https://github.com/Jon-Becker/heimdall-rs/blob/main/LICENSE)
- [Project website](http://heimdall.rs)
- [README](https://github.com/Jon-Becker/heimdall-rs/blob/main/README.md)
- [Releases](https://github.com/Jon-Becker/heimdall-rs/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jon-becker-heimdall-rs