# 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.

## LiteAPI Relation

`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.
