# soroban-decompiler-cli
Command-line tool for decompiling Soroban smart contracts from compiled WASM binaries back to readable Rust source code.
This crate provides the `soroban-decompile` binary, which wraps the `soroban-decompiler` library. It supports full decompilation, signature-only extraction, contract spec inspection, host import resolution, WASM analysis, and low-level stack debugging. All output goes to stdout by default so it can be piped into other tools.
## Installation
Build from the workspace root:
```
cargo build --release
```
The binary is at `target/release/soroban-decompile`. You can also run it directly through cargo:
```
cargo run --release -p soroban-decompiler-cli -- <command> [options]
```
## Commands
### decompile
The primary command. Reads a `.wasm` file and outputs reconstructed Rust source code including type definitions, contract struct, and function bodies with storage operations, authentication calls, and cross-contract invocations.
```
soroban-decompile decompile -i contract.wasm
```
Write the output to a file instead of stdout:
```
soroban-decompile decompile -i contract.wasm -o decompiled.rs
```
Extract only type definitions and function signatures, skipping bytecode analysis. This is useful when you need just the contract interface and want it fast.
```
soroban-decompile decompile --signatures-only -i contract.wasm
```
### inspect
Prints the contract specification as formatted JSON. This includes all functions with their parameter names and types, struct definitions, enum variants, error codes, and event schemas. The data comes from the `contractspecv0` WASM custom section that the Soroban SDK embeds during compilation.
```
soroban-decompile inspect -i contract.wasm
```
### imports
Resolves every entry in the WASM import table against the Soroban host function database and prints the results as JSON. Each import is shown with its raw WASM module/field name alongside the resolved semantic name (like `get_contract_data` or `require_auth_for_args`), argument types, and return type.
```
soroban-decompile imports -i contract.wasm
```
### analyze
Traces the Soroban dispatcher chain for each exported function and reports the host function calls found in each implementation, along with metadata about the function's complexity: whether it contains branches, loops, local calls, and how many instructions it has.
```
soroban-decompile analyze -i contract.wasm
```
### debug-stack
A diagnostic command for examining the decompiler's internal analysis of a specific function. It dumps the full stack simulation results: the traced host calls with their resolved arguments, the return expression, the control flow block tree (if/else, loops), and the memory state showing callee writes propagated to the caller. Useful for understanding why a particular function's output has unresolved values.
```
soroban-decompile debug-stack -i contract.wasm -f increment
```
## Examples
The repository includes pre-compiled WASM files in `examples/contracts/` taken from https://github.com/stellar/soroban-examples for quick testing without setting up the Soroban build toolchain.
Decompile the hello_world contract:
```
soroban-decompile decompile -i examples/contracts/soroban_hello_world_contract.wasm
```
Decompile increment and write to a file:
```
soroban-decompile decompile \
-i examples/contracts/soroban_increment_contract.wasm \
-o increment.rs
```
Inspect the auth contract's spec:
```
soroban-decompile inspect -i examples/contracts/soroban_auth_contract.wasm
```
Debug the increment function's stack analysis in the custom_types contract:
```
soroban-decompile debug-stack \
-i examples/contracts/soroban_custom_types_contract.wasm \
-f increment
```
Decompile all example contracts:
```
for f in examples/contracts/*.wasm; do
echo "=== $(basename $f) ==="
soroban-decompile decompile -i "$f"
echo
done
```
To decompile your own contracts, compile them with `soroban contract build` and point the tool at the `.wasm` file in `target/wasm32v1-none/release/`.
## License
Apache-2.0