acton simulator

Synopsis

acton simulator [options] command

Description

Acton simulator is a fast, deterministic TON development environment for local execution, forked-state development, and faucet-based funding. It produces TON-compatible blocks and provides LiteAPI, TON Center v2/v3, Streaming API, and Emulate API surfaces used by many contract and dApp workflows.

It is Acton's custom simplified implementation, not a real TON network or validator cluster. It does not model validators, consensus, shard elections, or the full production node and indexer stack.

Subcommands

acton simulator start

Start Acton's simplified TON development environment.

Synopsis

acton simulator start [options]

Options

acton simulator airdrop

Send GRAM from the local faucet to an address.

Synopsis

acton simulator airdrop [options] address

Options

acton simulator mine

Mine simulator blocks manually. Empty blocks are skipped unless --mine-empty-blocks was enabled at startup or the mining mode was changed through POST /acton_setMiningMode.

Synopsis

acton simulator mine [options] [n]

Options

acton simulator increase-time

Increase the simulator virtual clock.

Synopsis

acton simulator increase-time [options] seconds

Options

acton simulator set-time

Set the simulator virtual clock.

Synopsis

acton simulator set-time [options] timestamp

Options

acton simulator set-next-block-timestamp

Set a one-shot timestamp for the next simulator block.

Synopsis

acton simulator set-next-block-timestamp [options] timestamp

Options

acton simulator status

Inspect the current simulator status.

Synopsis

acton simulator status [options]

Options

acton simulator snapshot

Save and restore persistent JSON snapshots of a simulator.

Synopsis

acton simulator snapshot [options] command

Subcommands

• create [name] saves the current network state
• list prints saved snapshots with IDs, names, block seqnos, and file sizes
• restore <id> restores the saved network state
• delete <id> deletes one saved snapshot
• export <id> --out <path> downloads a saved snapshot; --force replaces an existing file
• import <path> [--name <name>] validates and saves a JSON snapshot under a new ID without restoring it

Snapshots survive node restarts. Creation and restoration run in the node's mutation queue without stopping its process. A snapshot includes accounts, block and transaction history, registered metadata, pending messages, and virtual time. Restoration also updates SQLite when persistence is enabled.

Relative file paths resolve from the Acton project root. These commands call the running simulator control API. Pass --port or --auth-token when needed, and --json for structured output. Use the returned ID for restore, delete, and export.

Configuration

You can store defaults in Acton.toml:

[localnet]
port = 5411
db-path = ".acton/localnet.sqlite"
fork-net = "testnet"
fork-block-number = 55000000
accounts = ["deployer", "user"]
rate-limit = 1
response-delay-ms = 300
block-time-ms = 500
no-mining = false
mine-empty-blocks = false

CLI flags override config values for the current invocation. In particular, --db-path overrides [localnet].db-path. A relative path in Acton.toml resolves from the project root, while a relative --db-path resolves from the current working directory.

TON Center API Keys

When simulator forks from the built-in mainnet/testnet backends, authenticated requests read TONCENTER_MAINNET_API_KEY or TONCENTER_TESTNET_API_KEY.

When simulator forks from 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.

Simulator API auth

acton simulator start --require-auth protects every simulator HTTP route under /api/*, /acton_*, /api/emulate/*, and /api/streaming/*. Static UI files remain public, but the bundled UI does not receive the token from the server. When a protected API request returns 401, the bundled UI shows a token overlay; paste the printed token there before using protected API views. The key button in the sidebar footer reopens the same overlay.

When auth is enabled, the server prints a simulator API token. Pass it as either:

Authorization: Bearer <TOKEN>
X-API-Key: <TOKEN>

Authorization: Bearer is the preferred form. X-API-Key is accepted for TON Center-compatible clients. Browser WebSocket clients can pass token=<TOKEN> only on /api/streaming/v2/ws.

For CLI subcommands that call simulator control routes, pass --auth-token or set ACTON_LOCALNET_AUTH_TOKEN. If ACTON_LOCALNET_AUTH_TOKEN is set when starting with --require-auth, simulator uses that value; otherwise it generates and prints a fresh token.

Runtime Model

• fork mode allows local development against remote chain state
• acton simulator start runs in the foreground until the process is stopped
• Acton starts an HTTP server on 127.0.0.1:<port> for simulator API, control endpoints, and the bundled simulator UI
• the server keeps running until the process is stopped, for example with Ctrl+C
• the simulator UI is available on the root path, for example http://127.0.0.1:<port>/
• the node checks for pending messages every --block-time-ms milliseconds, defaulting to 500 ms; --mine-empty-blocks also creates blocks when no messages are queued
• --no-mining or [localnet].no-mining = true disables automatic block production; use acton simulator mine [N] or POST /acton_mine to create blocks manually
• Simulator has a virtual clock for block and transaction time; use acton simulator increase-time, acton simulator set-time, or acton simulator set-next-block-timestamp to move it without waiting for real time
• messages accepted through send_boc, acton_sendInternalMessage, or the faucet are queued and included on a later automatic or manually mined block
• a block can include multiple transactions; locally generated internal messages are processed in the same block when possible
• the bundled UI is a single-page explorer app, so routes like /explorer, /tokens, /nfts, and per-address or per-transaction pages are served from the same frontend shell
• the UI reads chain data from /api/v2 and /api/v3, and uses acton_* control endpoints for local address aliases, registered compiler ABIs, status and saved snapshots
• --require-auth protects read and write API routes, including read-only streaming endpoints
• when --port and [localnet].port are both absent, the current runtime fallback is 5411
• --rate-limit applies to /api/* endpoints, not admin endpoints
• --response-delay-ms applies only to /api/v2, /api/v3, and /api/emulate/v1 endpoints; streaming, control, and UI routes are not delayed
• POST /acton_setNetworkConditions can change the response delay while the server is running, and GET /acton_nodeInfo reports the current value

Control Endpoints

The simulator server exposes acton_* control routes for local development tooling:

• GET /acton_nodeInfo returns uptime, latest block seqno, and the active state source
• POST /acton_createSnapshot with {"name":"before-upgrade"} saves a JSON snapshot
• GET /acton_listSnapshots lists saved snapshots
• POST /acton_restoreSnapshot with {"id":"<SNAPSHOT_ID>"} restores the saved network state
• POST /acton_deleteSnapshot with {"id":"<SNAPSHOT_ID>"} deletes one saved file
• GET /acton_exportSnapshot?id=<SNAPSHOT_ID> downloads the saved JSON file
• POST /acton_importSnapshot?name=bug validates JSON bytes and saves them under a new ID without changing the running state
• POST /acton_setConfig with {"config":"<BASE64_BOC>"} validates and replaces the full blockchain config dictionary, then commits it in a config-only block
• POST /acton_setConfigParam with {"index":2,"boc":"<BASE64_BOC>","expectedHash":"<CURRENT_CELL_HASH>"} replaces one config parameter and commits a config-only block, even when automatic mining is disabled. expectedHash is the current parameter's lowercase hexadecimal representation hash; use null to add a missing parameter. A stale hash returns HTTP 409. Parameter 0 cannot be changed
• POST /acton_setShardAccount with {"address":"<ADDR>","shard_account":"<BASE64_BOC>"} replaces the selected account state with a base64-encoded ShardAccount BOC
• POST /acton_sendInternalMessage with {"boc":"<BASE64_BOC>"} sends a base64-encoded internal message BOC through the local internal queue
• POST /acton_mine with optional {"blocks":N} mines queued and/or empty blocks manually; N defaults to 1, and empty blocks follow the mining mode
• POST /acton_setMiningMode with {"skip_empty_blocks":false} enables empty blocks for automatic and manual mining; use true to skip them
• POST /acton_increaseTime with {"seconds":3600} adds seconds to the virtual simulator clock
• POST /acton_setTime with {"timestamp":1710000000} sets the current virtual Unix time
• POST /acton_setNextBlockTimestamp with {"timestamp":1710000600} sets a one-shot timestamp for the next mined block
• POST /acton_setNetworkConditions with {"response_delay_ms":300} updates simulated network latency; use 0 to disable response delay

Acton Studio exposes the same parameter editor under Config in the Network section for simulator environments. Changes preserve all other parameters and historical configs.

TON Center-compatible message endpoints such as /api/v2/sendBoc and /api/v3/message accept external-in messages only. Use /acton_sendInternalMessage when local tooling needs to inject a raw internal message.

Control endpoints are unauthenticated by default for local development. Use --require-auth when another local process, browser page, or test harness should not be able to read or mutate the running simulator without the token. Do not expose the simulator server publicly.

Persistence

• --db-path or [localnet].db-path enables persistent SQLite-backed node state across runs
• snapshot create saves a persistent restore point as JSON
• --snapshots-dir sets the directory used for saved snapshots
• blockchain configs changed through /acton_setConfig or /acton_setConfigParam are stored in block history and survive restarts when --db-path is configured
• without a database, live state is ephemeral; saved snapshots remain available in the snapshot directory

Exit Status

• 0: The selected simulator subcommand completed successfully. For acton simulator status, this also includes the selected port not running; use --json and inspect running for automation.
• 1: Startup failed because port binding, database setup, remote fork initialization, faucet handling, or a status/control query failed.

Display Options

Project Options

Examples

1. Start with defaults:

   acton simulator start

2. Fork from testnet at a historical block:

   acton simulator start --fork-net testnet --fork-block-number 55000000

3. Use a dedicated snapshot directory:

   acton simulator start --snapshots-dir snapshots

4. Airdrop local funds:

   acton simulator airdrop UQA_ftKIJsHEAE_UgtFOUK15hPzycZooFuUr8duyY9T3kwwM --amount 25

5. Start a local integration node with pre-funded accounts:

   acton simulator start --accounts deployer,user --db-path build/localnet.db

6. Inspect a running simulator:

   acton simulator status --json

7. Save and share a snapshot:

   acton simulator snapshot create before-upgrade
   acton simulator snapshot list --json
   acton simulator snapshot restore <SNAPSHOT_ID>
   acton simulator snapshot export <SNAPSHOT_ID> --out snapshots/before-upgrade.json
   acton simulator snapshot import snapshots/before-upgrade.json

See Also

• acton help wallet
• Simulator guide