acton retrace

Synopsis

acton retrace [options] hash

Description

Download a transaction by hash and replay it locally in the TON sandbox.

acton retrace is useful for debugging failures, inspecting outgoing actions, reviewing VM and executor logs, and comparing local replay results with the original on-chain execution.

When --contract is provided, Acton also prepares a source-level retrace for the named project contract by recompiling it with debug info and source maps. When --debug is added, the prepared replay is exposed as a local Debug Adapter Protocol (DAP) server for editor integration.

Options

Retrace Options

Source-Level Debugging Options

Display Options

Project Options

Network And API Behavior

• Without --net, Acton tries mainnet and then testnet
• localnet and custom:<name> are not supported by the retrace backend

TonCenter API Keys

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

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.

If no matching key is configured, Acton throttles requests to reduce rate-limit failures.

For library fallback lookups, retrace also supports DTON_API_KEY from the environment.

Source-Level Retrace

When --contract is set:

• the contract must exist in the resolved Acton.toml
• the selected source must be a .tolk contract
• Acton refreshes the bundled stdlib under .acton/ before preparing the source-level retrace
• Acton recompiles the contract for the current invocation with debug info and source maps
• no prior acton build --debug step is required, but the current local sources and import mappings must compile cleanly
• the recompilation must return both source maps and debug marks; missing either is a hard error
• the compiled local code hash must match the code hash used by the retraced transaction

If you run the command outside the project directory, use --manifest-path or --project-root so Acton can resolve the contract configuration and import mappings.

Debug Mode

When --debug is used together with --contract:

• Acton starts a local DAP server on 127.0.0.1:<port>
• the normal retrace summary is still printed before the debug server starts
• the command stays attached to that debug session until the client disconnects

This mode is intended for editor integrations that speak the Debug Adapter Protocol.

--debug-port follows the same convention as other Acton debug commands: without --debug it does not start a debug server.

Current replay-debug limits:

• the retrace adapter exposes one DAP thread only
• replay sessions do not expose the live Registers scope available in local debug sessions
• the supported request set is intentionally narrow: source breakpoints, continue/step, stack/scopes/variables, exception info, evaluate, and disconnect
• unsupported client-specific extension requests are ignored rather than emulated

VS Code Setup

Typical setup:

1. Install or load the TON VS Code extension.

2. Make sure VS Code can find your acton binary.

   If needed, point the extension at a specific binary with an environment variable such as ACTON_BIN, or start VS Code from a shell where acton is already on PATH.

3. Open the project workspace that contains the target contract in Acton.toml.

4. Start a retrace debug session either through the extension command or through a manual launch.json entry.

For a manual setup, create .vscode/launch.json like this:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "tolk",
      "request": "launch",
      "name": "Attach to Acton Retrace",
      "debugServer": 4711
    }
  ]
}

Then start retrace in a terminal from the project root:

acton retrace <HASH> --contract <NAME> --debug --debug-port 4711

After the DAP server is listening, launch the matching VS Code debug configuration. Breakpoints should be set in the same .tolk sources that belong to the selected contract from Acton.toml.

Output

The command prints:

• network selection and state-hash check status
• transaction metadata and fee summary
• compute and action phase summaries
• decoded outgoing actions
• additional full VM and executor logs when --logs-dir is used
• source-level debug preparation errors when --contract is used
• DAP startup status when --debug is used

When --logs-dir is set, Acton creates the target directory and writes vm.log plus executor.log there.

Exit Status

• 0: The transaction was fetched and replayed successfully.
• 1: The transaction could not be found, network lookup failed, replay data was incomplete, local contract validation or compilation failed, the local code hash did not match the retraced account code, the DAP server could not start, or local log files could not be written.

Examples

1. Retrace with automatic network fallback:

   acton retrace 3c1b02a33390e596d83b306eab57b3f7271bc90e2e527ea4cafccfde25139d41

2. Force mainnet and use an API key from the environment:

   TONCENTER_MAINNET_API_KEY=your-key acton retrace 3c1b02a33390e596d83b306eab57b3f7271bc90e2e527ea4cafccfde25139d41 --net mainnet

3. Save logs and show full outgoing cell bodies:

   acton retrace 3c1b02a33390e596d83b306eab57b3f7271bc90e2e527ea4cafccfde25139d41 --verbose --logs-dir build/retrace

4. Prepare a source-level retrace for a project contract:

   acton retrace 3c1b02a33390e596d83b306eab57b3f7271bc90e2e527ea4cafccfde25139d41 --contract JettonMinter

5. Start a local DAP server for editor debugging:

   acton retrace 3c1b02a33390e596d83b306eab57b3f7271bc90e2e527ea4cafccfde25139d41 --contract JettonMinter --debug --debug-port 4711

See Also

• acton help disasm
• Retrace command guide