Does Acton Support Off-Chain Computations for TON? A Complete Technical Guide

Yes, Acton provides built-in support for off-chain computations on TON through the ton-executor crate, enabling local execution of smart-contract get-methods without broadcasting transactions to the blockchain.

Acton, the Rust-based testing and scripting framework for The Open Network (TON), ships with dedicated off-chain execution capabilities via its ton-executor crate. This functionality allows developers to run read-only get-methods against contract state locally, making it ideal for testing, debugging, and predicate evaluation without incurring gas costs or network latency.

How Acton Enables Off-Chain TON Computations

The ton-executor crate serves as the foundation for off-chain operations in Acton. According to the source code in crates/ton-executor/src/lib.rs, this crate exposes a public API specifically designed to emulate TON Virtual Machine (TVM) execution locally.

All off-chain computations operate on Base64-encoded Bag of Cells (BoC) data structures. These executors accept a BoC describing the contract's current state and method arguments, invoke the native TVM emulator through FFI bindings, and return the decoded result without ever touching the live blockchain.

The Two Core Executor Types

Acton implements two complementary executors for different off-chain use cases:

• GetExecutor – A high-level executor defined in crates/ton-executor/src/get/mod.rs that runs contract get-methods and returns fully decoded results. It serializes native FFI calls per instance, making it thread-safe for reuse across concurrent operations.
• StepGetExecutor – A granular, step-by-step executor located in crates/ton-executor/src/get/step.rs designed for debugging and CLI inspection. This executor allows you to inspect the VM state after each individual instruction.

Architecture and Key Source Files

The off-chain computation system spans multiple modules within the Acton repository:

• crates/ton-executor/src/lib.rs – Crate root describing high-level off-chain get-method support.
• crates/ton-executor/src/get/mod.rs – Implementation of GetExecutor and RunGetMethodArgs.
• crates/ton-executor/src/get/step.rs – Implementation of StepGetExecutor for instruction-by-instruction debugging.
• src/ffi/emulation.rs – FFI layer that instantiates GetExecutor for predicate evaluation.
• src/commands/script/mod.rs – CLI command integration allowing scripts to invoke off-chain methods.
• src/commands/test/mod.rs – Test harness utilizing both executor types for contract verification.

Practical Implementation Examples

Basic Off-Chain Get-Method Calls

To execute a simple off-chain read of a TON contract's state, initialize a GetExecutor with the contract's BoC parameters and invoke the desired method:

use ton_executor::get::{GetExecutor, RunGetMethodArgs};

// `params` is a Base64-encoded BoC containing the contract address and arguments.
let exec = GetExecutor::new(&params)?;
let args = RunGetMethodArgs::new("getBalance", vec![]);
let result = exec.run_get_method(&args)?;
println!("Balance: {}", result);

Source: crates/ton-executor/src/get/mod.rs (constructor) and src/ffi/emulation.rs (usage).

Step-by-Step Debugging

For debugging complex contract logic, StepGetExecutor provides granular visibility into the TVM execution state:

use ton_executor::get::step::StepGetExecutor;

// `stack_b64` is the BoC with the contract's current state.
// `params` contains the get-method name and arguments.
let mut step_exec = StepGetExecutor::new(&stack_b64, &params, None)?;
while let Some(step) = step_exec.next_step()? {
    println!("PC: {}, Stack top: {:?}", step.pc, step.stack_top);
}

Source: crates/ton-executor/src/get/step.rs.

Integration in Acton Scripts

Acton scripts leverage GetExecutor directly within command implementations to perform off-chain reads as part of automated workflows:

// Inside an Acton script (src/commands/script/mod.rs)
let mut exec = GetExecutor::new(&params)?;
let result = exec.run_get_method(&RunGetMethodArgs::new("getOwner", vec![]))?;
// The script can now use `result` as a regular value.

Summary

• Acton supports off-chain computations through the ton-executor crate, specifically for TON smart-contract get-methods.
• GetExecutor provides thread-safe, high-level execution of read-only methods using Base64-encoded BoC inputs.
• StepGetExecutor enables step-by-step debugging of VM execution for deep contract inspection.
• The system operates entirely locally without broadcasting transactions, making it suitable for testing and CI/CD pipelines.
• Key implementations reside in crates/ton-executor/src/get/mod.rs and crates/ton-executor/src/get/step.rs, with FFI bridges in src/ffi/emulation.rs.

Frequently Asked Questions

Can Acton perform off-chain computations for TON state changes?

No, Acton's off-chain capabilities via GetExecutor and StepGetExecutor are limited to read-only get-methods. These executors cannot modify contract state or send messages to the blockchain; they only simulate the TVM locally to return current state values as implemented in crates/ton-executor/src/get/mod.rs.

What data format does Acton use for off-chain contract calls?

Acton uses Base64-encoded Bag of Cells (BoC) to represent contract state and arguments. The GetExecutor accepts this BoC format as input parameters, deserializing it internally before passing to the native TVM emulator.

Is the GetExecutor thread-safe for concurrent off-chain calls?

Yes, according to the source in crates/ton-executor/src/get/mod.rs, GetExecutor serializes native FFI calls per instance, making it safe to reuse across threads. This design allows multiple simultaneous off-chain computations without race conditions.

How does Acton's step-by-step debugging work for TON contracts?

The StepGetExecutor in crates/ton-executor/src/get/step.rs provides a programmatic debugger interface. It executes the TVM one instruction at a time, yielding the program counter and stack state after each step, which the CLI commands in src/commands/test/mod.rs utilize for detailed execution tracing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}