acton disasm

Description

Disassemble compiled TVM bytecode from a file, a literal BoC string, or a live contract address.

This command is useful for debugging compiler output, inspecting deployed code, following library references, and correlating bytecode with Tolk source via source maps.

Options

Disassembly Options

<boc-file>

Binary, hex, or base64 BoC file to disassemble.

Use --string to pass the code directly instead of reading a file.

-s,--string<string>

BoC value in hex or base64 format.

-o,--output<path>

Write plain disassembly text to a file.

Without --json, this replaces standard output. With --json, Acton still prints the JSON envelope to stdout and writes only the assembly field to the file.

If the parent directory does not exist, Acton creates it automatically. Existing files are overwritten.

--show-hashes

Show cell hashes alongside code blocks.

--show-offsets

Show instruction bit offsets in the left column.

--json

Print machine-readable disassembly JSON to stdout.

Successful output includes success, the plain disassembly in assembly, and blocks derived from --source-map. Without --source-map, blocks is empty.

--source-map<path>

Use a source map to show original Tolk source locations together with disassembly output.

--address<address>

Fetch contract code from the blockchain by address and disassemble it.

--net<network>

Network to use for --address and library lookups.

Supported values: mainnet, testnet, localnet, custom:<name>.

localnet and custom:<name> resolve through the project network configuration in Acton.toml.

If omitted:

Acton tries mainnet first and then falls back to testnet.

--follow-libraries

If the input disassembles to exactly one top-level exotic library-reference cell, fetch and disassemble the actual library code instead of showing only the library hash reference.

This is not a general recursive library-follow mode.

Display Options

--color<when>

Control when to use colored output.

Possible values:

auto, always, never

Project Options

--manifest-path<path>

Path to the Acton.toml file to use for this invocation.

Use this when running the command outside the project directory or when the manifest lives at a non-default location.

--project-root<path>

Path to the project root to use for configuration discovery and relative defaults.

This conflicts with --manifest-path.

Blockchain Lookups

When --address is used, Acton fetches code from the selected network.

--net accepts mainnet, testnet, localnet, and custom:<name>
localnet and custom:<name> use URLs from Acton.toml
Without --net, Acton tries mainnet first and then testnet
with --address, --follow-libraries reuses the network that returned the contract code

When --follow-libraries is used with a local file or --string, Acton uses the explicit --net if provided; otherwise library fetches default to testnet.

TonCenter API Keys

Built-in mainnet/testnet requests read TONCENTER_MAINNET_API_KEY or TONCENTER_TESTNET_API_KEY, depending on the selected network.

For custom:<name>, Acton reads <NORMALIZED_NAME>_API_KEY. Custom network names are uppercased and non-alphanumeric characters are replaced with _, so custom:mock-remote becomes MOCK_REMOTE_API_KEY.

Acton loads .env automatically, so the simplest setup during project work is usually to keep these keys there and use shell environment variables only for one-off overrides or CI.

Input Precedence

BOC_FILE and --string are mutually exclusive
--address is used only when neither a file nor --string is provided
--follow-libraries only replaces the input when the initial disassembly is exactly one top-level exotic library-reference cell and the lookup succeeds
ordinary code, mixed instruction streams, or nested library references are a no-op for --follow-libraries
if library lookup fails, Acton warns and disassembles the original code instead; this still exits successfully

Source Maps

If you compiled a contract with acton compile --source-map, you can pass that source map JSON here to annotate the disassembly with original Tolk locations.

--source-map only affects annotations in the output. It does not change which BoC is disassembled.

JSON Output

With --json, Acton prints pretty-printed JSON to stdout.

success: true for successful disassembly
assembly: plain disassembly text without inline source-map comments
blocks: source-to-assembly mappings derived from --source-map

Each item in blocks contains a source location and assembly_ranges. assembly_ranges stores inclusive zero-based start_line/end_line pairs into the assembly string.

If --source-map is not provided, blocks is empty.

If --output is also provided, the output file contains the same plain assembly text while stdout remains JSON.

Exit Status

0: Disassembly completed successfully, including runs with unresolved library references that were left as warnings.
1: BoC input was invalid, a blockchain fetch failed, source-map loading failed, or the output file could not be written.

Examples

Disassemble a local BoC file:
```
acton disasm contract.boc
```

Disassemble a literal BoC string:

acton disasm --string "b5ee9c72010104...0840f01c700f2f4"

Disassemble code from a blockchain address:

acton disasm --address UQA_ftKIJsHEAE_UgtFOUK15hPzycZooFuUr8duyY9T3kwwM --net testnet

Show hashes, offsets, and source locations:

acton disasm contract.boc --show-hashes --show-offsets --source-map contract.json

Inspect deployed code together with hashes:

acton disasm --address UQA_ftKIJsHEAE_UgtFOUK15hPzycZooFuUr8duyY9T3kwwM --show-hashes --net testnet

Write disassembly to a nested output path:

acton disasm contract.boc --output build/disasm/contract.tasm

Resolve a top-level library-reference cell using a configured custom network:
```
acton disasm library-ref.boc --follow-libraries --net custom:staging
```

Print machine-readable JSON with source-map ranges:

acton disasm contract.boc --source-map contract.json --json