# Module tvm

## Module tvm

### Functions

[run\_executor](#run_executor) – Emulates all the phases of contract execution locally

[run\_tvm](#run_tvm) – Executes get-methods of ABI-compatible contracts

[run\_get](#run_get) – Executes a get-method of FIFT contract

### Types

[TvmErrorCode](#tvmerrorcode)

[ExecutionOptions](#executionoptions)

[AccountForExecutorNoneVariant](#accountforexecutornonevariant) – Non-existing account to run a creation internal message. Should be used with `skip_transaction_check = true` if the message has no deploy data since transactions on the uninitialized account are always aborted

[AccountForExecutorUninitVariant](#accountforexecutoruninitvariant) – Emulate uninitialized account to run deploy message

[AccountForExecutorAccountVariant](#accountforexecutoraccountvariant) – Account state to run message

[AccountForExecutor](#accountforexecutor)

[TransactionFees](#transactionfees)

[ParamsOfRunExecutor](#paramsofrunexecutor)

[ResultOfRunExecutor](#resultofrunexecutor)

[ParamsOfRunTvm](#paramsofruntvm)

[ResultOfRunTvm](#resultofruntvm)

[ParamsOfRunGet](#paramsofrunget)

[ResultOfRunGet](#resultofrunget)

## Functions

### run\_executor

Emulates all the phases of contract execution locally

Performs all the phases of contract execution on Transaction Executor - the same component that is used on Validator Nodes.

Can be used for contract debugging, to find out the reason why a message was not delivered successfully. Validators throw away the failed external inbound messages (if they failed before `ACCEPT`) in the real network. This is why these messages are impossible to debug in the real network. With the help of run\_executor you can do that. In fact, `process_message` function performs local check with `run_executor` if there was no transaction as a result of processing and returns the error, if there is one.

Another use case to use `run_executor` is to estimate fees for message execution. Set `AccountForExecutor::Account.unlimited_balance` to `true` so that emulation will not depend on the actual balance. This may be needed to calculate deploy fees for an account that does not exist yet. JSON with fees is in `fees` field of the result.

One more use case - you can produce the sequence of operations, thus emulating the sequential contract calls locally. And so on.

Transaction executor requires account BOC (bag of cells) as a parameter. To get the account BOC - use `net.query` method to download it from GraphQL API (field `boc` of `account`) or generate it with `abi.encode_account` method.

Also it requires message BOC. To get the message BOC - use `abi.encode_message` or `abi.encode_internal_message`.

If you need this emulation to be as precise as possible (for instance - emulate transaction with particular lt in particular block or use particular blockchain config, downloaded from a particular key block - then specify `execution_options` parameter.

If you need to see the aborted transaction as a result, not as an error, set `skip_transaction_check` to `true`.

```ts
type ParamsOfRunExecutor = {
    message: string,
    account: AccountForExecutor,
    execution_options?: ExecutionOptions,
    abi?: Abi,
    skip_transaction_check?: boolean,
    boc_cache?: BocCacheType,
    return_updated_account?: boolean
}

type ResultOfRunExecutor = {
    transaction: any,
    out_messages: string[],
    decoded?: DecodedOutput,
    account: string,
    fees: TransactionFees
}

function run_executor(
    params: ParamsOfRunExecutor,
): Promise<ResultOfRunExecutor>;

function run_executor_sync(
    params: ParamsOfRunExecutor,
): ResultOfRunExecutor;
```

NOTE: Sync version is available only for `lib-node` binding.

#### Parameters

* `message`: *string* – Input message BOC.\
  Must be encoded as base64.
* `account`: [*AccountForExecutor*](#accountforexecutor) – Account to run on executor
* `execution_options`?: [*ExecutionOptions*](#executionoptions) – Execution options.
* `abi`?: [*Abi*](/ever-sdk/reference/types-and-methods/mod_abi.md#abi) – Contract ABI for decoding output messages
* `skip_transaction_check`?: *boolean* – Skip transaction check flag
* `boc_cache`?: [*BocCacheType*](/ever-sdk/reference/types-and-methods/mod_boc.md#boccachetype) – Cache type to put the result.\
  The BOC itself returned if no cache type provided
* `return_updated_account`?: *boolean* – Return updated account flag.\
  Empty string is returned if the flag is `false`

#### Result

* `transaction`: *any* – Parsed transaction.\
  In addition to the regular transaction fields there is a\
  `boc` field encoded with `base64` which contains source\
  transaction BOC.
* `out_messages`: *string\[]* – List of output messages' BOCs.\
  Encoded as `base64`
* `decoded`?: [*DecodedOutput*](/ever-sdk/reference/types-and-methods/mod_processing.md#decodedoutput) – Optional decoded message bodies according to the optional `abi` parameter.
* `account`: *string* – Updated account state BOC.\
  Encoded as `base64`
* `fees`: [*TransactionFees*](#transactionfees) – Transaction fees

### run\_tvm

Executes get-methods of ABI-compatible contracts

Performs only a part of compute phase of transaction execution that is used to run get-methods of ABI-compatible contracts.

If you try to run get-methods with `run_executor` you will get an error, because it checks ACCEPT and exits if there is none, which is actually true for get-methods.

To get the account BOC (bag of cells) - use `net.query` method to download it from GraphQL API (field `boc` of `account`) or generate it with `abi.encode_account method`. To get the message BOC - use `abi.encode_message` or prepare it any other way, for instance, with FIFT script.

Attention! Updated account state is produces as well, but only `account_state.storage.state.data` part of the BOC is updated.

```ts
type ParamsOfRunTvm = {
    message: string,
    account: string,
    execution_options?: ExecutionOptions,
    abi?: Abi,
    boc_cache?: BocCacheType,
    return_updated_account?: boolean
}

type ResultOfRunTvm = {
    out_messages: string[],
    decoded?: DecodedOutput,
    account: string
}

function run_tvm(
    params: ParamsOfRunTvm,
): Promise<ResultOfRunTvm>;

function run_tvm_sync(
    params: ParamsOfRunTvm,
): ResultOfRunTvm;
```

NOTE: Sync version is available only for `lib-node` binding.

#### Parameters

* `message`: *string* – Input message BOC.\
  Must be encoded as base64.
* `account`: *string* – Account BOC.\
  Must be encoded as base64.
* `execution_options`?: [*ExecutionOptions*](#executionoptions) – Execution options.
* `abi`?: [*Abi*](/ever-sdk/reference/types-and-methods/mod_abi.md#abi) – Contract ABI for decoding output messages
* `boc_cache`?: [*BocCacheType*](/ever-sdk/reference/types-and-methods/mod_boc.md#boccachetype) – Cache type to put the result.\
  The BOC itself returned if no cache type provided
* `return_updated_account`?: *boolean* – Return updated account flag.\
  Empty string is returned if the flag is `false`

#### Result

* `out_messages`: *string\[]* – List of output messages' BOCs.\
  Encoded as `base64`
* `decoded`?: [*DecodedOutput*](/ever-sdk/reference/types-and-methods/mod_processing.md#decodedoutput) – Optional decoded message bodies according to the optional `abi` parameter.
* `account`: *string* – Updated account state BOC.\
  Encoded as `base64`. Attention! Only `account_state.storage.state.data` part of the BOC is updated.

### run\_get

Executes a get-method of FIFT contract

Executes a get-method of FIFT contract that fulfills the smc-guidelines <https://test.ton.org/smc-guidelines.txt> and returns the result data from TVM's stack

```ts
type ParamsOfRunGet = {
    account: string,
    function_name: string,
    input?: any,
    execution_options?: ExecutionOptions,
    tuple_list_as_array?: boolean
}

type ResultOfRunGet = {
    output: any
}

function run_get(
    params: ParamsOfRunGet,
): Promise<ResultOfRunGet>;

function run_get_sync(
    params: ParamsOfRunGet,
): ResultOfRunGet;
```

NOTE: Sync version is available only for `lib-node` binding.

#### Parameters

* `account`: *string* – Account BOC in `base64`
* `function_name`: *string* – Function name
* `input`?: *any* – Input parameters
* `execution_options`?: [*ExecutionOptions*](#executionoptions) – Execution options
* `tuple_list_as_array`?: *boolean* – Convert lists based on nested tuples in the **result** into plain arrays.\
  Default is `false`. Input parameters may use any of lists representations\
  If you receive this error on Web: "Runtime error. Unreachable code should not be executed...",\
  set this flag to true.\
  This may happen, for example, when elector contract contains too many participants

#### Result

* `output`: *any* – Values returned by get-method on stack

## Types

### TvmErrorCode

```ts
enum TvmErrorCode {
    CanNotReadTransaction = 401,
    CanNotReadBlockchainConfig = 402,
    TransactionAborted = 403,
    InternalError = 404,
    ActionPhaseFailed = 405,
    AccountCodeMissing = 406,
    LowBalance = 407,
    AccountFrozenOrDeleted = 408,
    AccountMissing = 409,
    UnknownExecutionError = 410,
    InvalidInputStack = 411,
    InvalidAccountBoc = 412,
    InvalidMessageType = 413,
    ContractExecutionError = 414,
    AccountIsSuspended = 415
}
```

One of the following value:

* `CanNotReadTransaction = 401`
* `CanNotReadBlockchainConfig = 402`
* `TransactionAborted = 403`
* `InternalError = 404`
* `ActionPhaseFailed = 405`
* `AccountCodeMissing = 406`
* `LowBalance = 407`
* `AccountFrozenOrDeleted = 408`
* `AccountMissing = 409`
* `UnknownExecutionError = 410`
* `InvalidInputStack = 411`
* `InvalidAccountBoc = 412`
* `InvalidMessageType = 413`
* `ContractExecutionError = 414`
* `AccountIsSuspended = 415`

### ExecutionOptions

```ts
type ExecutionOptions = {
    blockchain_config?: string,
    block_time?: number,
    block_lt?: bigint,
    transaction_lt?: bigint,
    chksig_always_succeed?: boolean,
    signature_id?: number
}
```

* `blockchain_config`?: *string* – boc with config
* `block_time`?: *number* – time that is used as transaction time
* `block_lt`?: *bigint* – block logical time
* `transaction_lt`?: *bigint* – transaction logical time
* `chksig_always_succeed`?: *boolean* – Overrides standard TVM behaviour. If set to `true` then CHKSIG always will return `true`.
* `signature_id`?: *number* – Signature ID to be used in signature verifying instructions when CapSignatureWithId capability is enabled

### AccountForExecutorNoneVariant

Non-existing account to run a creation internal message. Should be used with `skip_transaction_check = true` if the message has no deploy data since transactions on the uninitialized account are always aborted

```ts
type AccountForExecutorNoneVariant = {

}
```

### AccountForExecutorUninitVariant

Emulate uninitialized account to run deploy message

```ts
type AccountForExecutorUninitVariant = {

}
```

### AccountForExecutorAccountVariant

Account state to run message

```ts
type AccountForExecutorAccountVariant = {
    boc: string,
    unlimited_balance?: boolean
}
```

* `boc`: *string* – Account BOC.\
  Encoded as base64.
* `unlimited_balance`?: *boolean* – Flag for running account with the unlimited balance.\
  Can be used to calculate transaction fees without balance check

### AccountForExecutor

```ts
type AccountForExecutor = ({
    type: 'None'
} & AccountForExecutorNoneVariant) | ({
    type: 'Uninit'
} & AccountForExecutorUninitVariant) | ({
    type: 'Account'
} & AccountForExecutorAccountVariant)
```

Depends on value of the `type` field.

When *type* is *'None'*

Non-existing account to run a creation internal message. Should be used with `skip_transaction_check = true` if the message has no deploy data since transactions on the uninitialized account are always aborted

When *type* is *'Uninit'*

Emulate uninitialized account to run deploy message

When *type* is *'Account'*

Account state to run message

* `boc`: *string* – Account BOC.\
  Encoded as base64.
* `unlimited_balance`?: *boolean* – Flag for running account with the unlimited balance.\
  Can be used to calculate transaction fees without balance check

Variant constructors:

```ts
function accountForExecutorNone(): AccountForExecutor;
function accountForExecutorUninit(): AccountForExecutor;
function accountForExecutorAccount(boc: string, unlimited_balance?: boolean): AccountForExecutor;
```

### TransactionFees

```ts
type TransactionFees = {
    in_msg_fwd_fee: bigint,
    storage_fee: bigint,
    gas_fee: bigint,
    out_msgs_fwd_fee: bigint,
    total_account_fees: bigint,
    total_output: bigint,
    ext_in_msg_fee: bigint,
    total_fwd_fees: bigint,
    account_fees: bigint
}
```

* `in_msg_fwd_fee`: *bigint* – Deprecated.\
  Contains the same data as ext\_in\_msg\_fee field
* `storage_fee`: *bigint* – Fee for account storage
* `gas_fee`: *bigint* – Fee for processing
* `out_msgs_fwd_fee`: *bigint* – Deprecated.\
  Contains the same data as total\_fwd\_fees field. Deprecated because of its confusing name, that is not the same with GraphQL API Transaction type's field.
* `total_account_fees`: *bigint* – Deprecated.\
  Contains the same data as account\_fees field
* `total_output`: *bigint* – Deprecated because it means total value sent in the transaction, which does not relate to any fees.
* `ext_in_msg_fee`: *bigint* – Fee for inbound external message import.
* `total_fwd_fees`: *bigint* – Total fees the account pays for message forwarding
* `account_fees`: *bigint* – Total account fees for the transaction execution. Compounds of storage\_fee + gas\_fee + ext\_in\_msg\_fee + total\_fwd\_fees

### ParamsOfRunExecutor

```ts
type ParamsOfRunExecutor = {
    message: string,
    account: AccountForExecutor,
    execution_options?: ExecutionOptions,
    abi?: Abi,
    skip_transaction_check?: boolean,
    boc_cache?: BocCacheType,
    return_updated_account?: boolean
}
```

* `message`: *string* – Input message BOC.\
  Must be encoded as base64.
* `account`: [*AccountForExecutor*](#accountforexecutor) – Account to run on executor
* `execution_options`?: [*ExecutionOptions*](#executionoptions) – Execution options.
* `abi`?: [*Abi*](/ever-sdk/reference/types-and-methods/mod_abi.md#abi) – Contract ABI for decoding output messages
* `skip_transaction_check`?: *boolean* – Skip transaction check flag
* `boc_cache`?: [*BocCacheType*](/ever-sdk/reference/types-and-methods/mod_boc.md#boccachetype) – Cache type to put the result.\
  The BOC itself returned if no cache type provided
* `return_updated_account`?: *boolean* – Return updated account flag.\
  Empty string is returned if the flag is `false`

### ResultOfRunExecutor

```ts
type ResultOfRunExecutor = {
    transaction: any,
    out_messages: string[],
    decoded?: DecodedOutput,
    account: string,
    fees: TransactionFees
}
```

* `transaction`: *any* – Parsed transaction.\
  In addition to the regular transaction fields there is a\
  `boc` field encoded with `base64` which contains source\
  transaction BOC.
* `out_messages`: *string\[]* – List of output messages' BOCs.\
  Encoded as `base64`
* `decoded`?: [*DecodedOutput*](/ever-sdk/reference/types-and-methods/mod_processing.md#decodedoutput) – Optional decoded message bodies according to the optional `abi` parameter.
* `account`: *string* – Updated account state BOC.\
  Encoded as `base64`
* `fees`: [*TransactionFees*](#transactionfees) – Transaction fees

### ParamsOfRunTvm

```ts
type ParamsOfRunTvm = {
    message: string,
    account: string,
    execution_options?: ExecutionOptions,
    abi?: Abi,
    boc_cache?: BocCacheType,
    return_updated_account?: boolean
}
```

* `message`: *string* – Input message BOC.\
  Must be encoded as base64.
* `account`: *string* – Account BOC.\
  Must be encoded as base64.
* `execution_options`?: [*ExecutionOptions*](#executionoptions) – Execution options.
* `abi`?: [*Abi*](/ever-sdk/reference/types-and-methods/mod_abi.md#abi) – Contract ABI for decoding output messages
* `boc_cache`?: [*BocCacheType*](/ever-sdk/reference/types-and-methods/mod_boc.md#boccachetype) – Cache type to put the result.\
  The BOC itself returned if no cache type provided
* `return_updated_account`?: *boolean* – Return updated account flag.\
  Empty string is returned if the flag is `false`

### ResultOfRunTvm

```ts
type ResultOfRunTvm = {
    out_messages: string[],
    decoded?: DecodedOutput,
    account: string
}
```

* `out_messages`: *string\[]* – List of output messages' BOCs.\
  Encoded as `base64`
* `decoded`?: [*DecodedOutput*](/ever-sdk/reference/types-and-methods/mod_processing.md#decodedoutput) – Optional decoded message bodies according to the optional `abi` parameter.
* `account`: *string* – Updated account state BOC.\
  Encoded as `base64`. Attention! Only `account_state.storage.state.data` part of the BOC is updated.

### ParamsOfRunGet

```ts
type ParamsOfRunGet = {
    account: string,
    function_name: string,
    input?: any,
    execution_options?: ExecutionOptions,
    tuple_list_as_array?: boolean
}
```

* `account`: *string* – Account BOC in `base64`
* `function_name`: *string* – Function name
* `input`?: *any* – Input parameters
* `execution_options`?: [*ExecutionOptions*](#executionoptions) – Execution options
* `tuple_list_as_array`?: *boolean* – Convert lists based on nested tuples in the **result** into plain arrays.\
  Default is `false`. Input parameters may use any of lists representations\
  If you receive this error on Web: "Runtime error. Unreachable code should not be executed...",\
  set this flag to true.\
  This may happen, for example, when elector contract contains too many participants

### ResultOfRunGet

```ts
type ResultOfRunGet = {
    output: any
}
```

* `output`: *any* – Values returned by get-method on stack


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.everos.dev/ever-sdk/reference/types-and-methods/mod_tvm.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.