Simulator LiteAPI support

Available since: Acton 1.2

The simulator exposes a liteserver-compatible binary endpoint for tools that talk to TON nodes through LiteAPI instead of TON Center HTTP APIs. The endpoint supports local indexing, application binary interface (ABI) discovery, and get-method execution against simulated state. It returns TON-compatible block cells for the local basechain and masterchain streams.

Endpoint

LiteAPI is disabled by default. Enable it with --liteapi:

acton simulator start --liteapi

When the simulator runs on HTTP port 5411, LiteAPI listens on TCP port 5412 by default. Set another port explicitly with --liteapi-port:

acton simulator start --liteapi --liteapi-port 15000

Replace <PUBLIC_KEY> with the base64 Ed25519 public key printed by acton simulator start. The following JSON is a partial TON global configuration. It encodes 127.0.0.1 as the integer 2130706433.

{
  "liteservers": [
    {
      "ip": 2130706433,
      "port": 5412,
      "id": {
        "@type": "pub.ed25519",
        "key": "<PUBLIC_KEY>"
      }
    }
  ]
}

Advertised capabilities

liteServer.getVersion and liteServer.getMasterchainInfoExt report:

Field	Value	Meaning
`version`	`0x101`	Liteserver protocol version `1.1`.
`capabilities`	`6`	`+2` for `masterchainInfoExt`, `+4` for `runSmcMethod`.

The simulator does not advertise capability +1 because general block proof-chain construction between distinct masterchain blocks is not implemented.

Supported methods

Method	Status	Notes
`liteServer.getMasterchainInfo`	Supported	Returns the latest simulator block ID and zero-state ID.
`liteServer.getMasterchainInfoExt`	Supported	Reports simulator version, capabilities, latest block, and time metadata.
`liteServer.getTime`	Supported	Returns current wall-clock Unix time.
`liteServer.getVersion`	Supported	Reports version `0x101` and capabilities `6`.
`liteServer.getBlock`	Supported	Returns the stored block bag of cells (BoC) for the requested masterchain or basechain block.
`liteServer.getBlockHeader`	Supported	Returns block ID and a Merkle proof of the stored block root; tonlib extracts header fields from the proof.
`liteServer.sendMessage`	Supported	Accepts an external-in message BoC and queues it for simulator execution.
`liteServer.getAccountState`	Supported	Returns account state with local block/state proofs accepted by tonlib account-state validation.
`liteServer.getAccountStatePrunned`	Supported	Same simulator behavior as `getAccountState`.
`liteServer.runSmcMethod`	Limited	Supports mode `0` and result bit `4`; proof, `init_c7`, and library-extra modes are rejected.
`liteServer.getBlockProof`	Limited	Supports only the degenerate proof where `known_block` and `target_block` are the same block.
`liteServer.getShardInfo`	Limited	Returns the local single-shard descriptor; shard proof validation is not implemented.
`liteServer.getAllShardsInfo`	Limited	Returns local all-shards data; tonlib shard-list proof validation is not implemented.
`liteServer.getOneTransaction`	Limited	Returns transaction data by account and logical time; transaction proof validation is not implemented.
`liteServer.getTransactions`	Supported	Returns account transactions as a multi-root BoC plus containing block IDs.
`liteServer.lookupBlock`	Supported	Resolves by seqno, logical time, or Unix time in the single simulator shard.
`liteServer.lookupBlockWithProof`	Supported	Resolves masterchain and basechain blocks with local Merkle proofs for tonlib lookup validation.
`liteServer.listBlockTransactions`	Limited	Supports `count`, `after`, and `want_proof`; `reverse_order` is not implemented.
`liteServer.listBlockTransactionsExt`	Limited	Supports `count`, `after`, and `want_proof`; returns transaction cells as a multi-root BoC; `reverse_order` is not implemented.
`liteServer.getConfigAll`	Limited	Returns local config data with masterchain state/config proofs; `param_list` filtering is not applied.
`liteServer.getConfigParams`	Limited	Returns local config data with masterchain state/config proofs; `param_list` filtering is not applied.
`liteServer.getLibraries`	Limited	Returns locally known public libraries for raw LiteAPI clients; tonlib proof-validated library lookup is not implemented.
`liteServer.getLibrariesWithProof`	Limited	Returns library data; state/data proof validation is not implemented.
`liteServer.getShardBlockProof`	Limited	Returns the local shard-block link shape; shard-block proof validation is not implemented.
`liteServer.waitMasterchainSeqno` wrapper	Supported	Waits until simulator reaches the requested seqno or the request timeout expires.

runSmcMethod uses the same execution path as simulator runGetMethod: it reads code, data, balance, libraries, previous block info, and virtual time from the requested simulator block. Missing or non-runnable accounts are reported with liteserver-style exit code -256.

Unsupported methods

Unsupported methods return liteServer.error.

Method	Status	Reason
`liteServer.getState`	Not supported	Full block-state BoC export is not implemented.
`liteServer.getValidatorStats`	Not supported	The simulator does not emulate validator statistics.
`liteServer.getOutMsgQueueSizes`	Not supported	Out-message queue size snapshots are not modeled.
`liteServer.getBlockOutMsgQueueSize`	Not supported	Block queue proof/data is not modeled.
`liteServer.getDispatchQueueInfo`	Not supported	Dispatch queue state is not modeled.
`liteServer.getDispatchQueueMessages`	Not supported	Dispatch queue messages are not modeled.
`liteServer.nonfinal.getValidatorGroups`	Not supported	Non-final validator group API is outside the simulator model.
`liteServer.nonfinal.getCandidate`	Not supported	Non-final candidate API is outside the simulator model.
`liteServer.nonfinal.getPendingShardBlocks`	Not supported	Pending shard-block candidate API is outside the simulator model.

Limitations

The simulator mines 1 executable basechain shard block in workchain 0 and 1 matching masterchain block in workchain -1 per seqno. Masterchain blocks carry shard, configuration, and history metadata; their transaction lists are empty. Use basechain blocks to enumerate executed transactions.

Generated BoCs are TON Block cells with transaction data and a state_update. They omit validator signatures, key-block proof chains, shard split/merge history, and the artifacts listed under unsupported methods. Method-specific restrictions appear in the coverage tables; transaction listing also omits metadata proof expansion.

Proof policy

Header, lookup, configuration, account-state, and transaction-list proofs use the simulator's stored block and state roots. Account-state proof and shard_proof fields are 2-root BoCs containing exotic Merkle proof cells for tonlib validation. These local proofs provide no validator-backed trust guarantees.

Use no-proof or unsafe proof mode only with the local simulator for methods lacking proof validation. These modes do not authenticate public-network state. Retain proof validation when connecting to testnet or mainnet.