TVM Stack

TVM stack values are used for smart-contract get-method parameters and results.

Required Entry Types

null,
integer,
cell,
slice,
tuple,
list,
unsupported preserved value.

Integer Size

TVM integers are not limited to 64 bits. The current stack representation uses num_bigint::BigInt, and checked fixtures include a decimal value wider than i128 and u256.

Cells And Slices

Cells and slices should preserve:

data bits,
refs,
current slice offset where applicable,
BoC compatibility.

Tuples And Lists

Tuples and lists can nest. Implementation must avoid the four-reference direct-cell limit by using linked or referenced representation compatible with liteserver expectations.

liteServer.runSmcMethod sends params:bytes and receives result:mode.2?bytes. These bytes must match TON stack serialization, not an arbitrary SDK-local format. The root VmStack cell starts with depth:(## 24), followed by the stack list payload when depth is non-zero. Empty get-method calls therefore serialize to a BoC whose root cell contains exactly 24 zero bits and no references.

Checked offline fixtures in fixtures/tvm/stack.json record deterministic non-empty stack BoCs, root hashes, and decoded entry shapes generated by the local codec. They cover scalar non-empty stacks, linked stack chains with more than four logical entries, nested tuple/list values, huge integers, cell/slice entries, and unsupported raw bytes. The fixture test decodes each BoC, compares the expected entries and root hash, and verifies canonical reserialization to the exact checked bytes.

An ignored live smoke test, contracts::tests::live_non_empty_stack_run_get_method_smoke, can be run with TON_GLOBAL_CONFIG_JSON, TON_STACK_TEST_CONTRACT_ADDRESS, TON_STACK_TEST_METHOD defaulting to seqno, and TON_STACK_TEST_JSON. It confirms transport success for a real liteserver call using a non-empty stack. If the chosen method intentionally returns a non-zero exit code, set TON_STACK_TEST_ACCEPT_EXIT_CODE to that value. When the live call succeeds with exit_code == 0, the test prints a fixture JSON object containing source tool/version, network, endpoint, block id, account, method, input stack JSON, params BoC/root hash, result BoC/root hash, decoded result, and compatibility-reference notes. Non-zero accepted smoke tests do not print capture fixtures.

Current Crate Mapping

src/tvm/stack.rs
src/liteclient/client.rs get-method helpers

Missing Work

Fill checked captured_or_opt_in stack fixtures from successful live output.
Add cross_sdk_vectors with tonutils-go params BoC bytes when available; for tonlib, keep structural decoded-result comparisons unless raw params BoC bytes are obtainable.
Expand result stack decoding against checked live response fixtures.

tonutils-rs