# 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*](https://docs.everos.dev/ever-sdk/reference/mod_abi#abi) – Contract ABI for decoding output messages
* `skip_transaction_check`?: *boolean* – Skip transaction check flag
* `boc_cache`?: [*BocCacheType*](https://docs.everos.dev/ever-sdk/reference/mod_boc#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*](https://docs.everos.dev/ever-sdk/reference/mod_processing#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*](https://docs.everos.dev/ever-sdk/reference/mod_abi#abi) – Contract ABI for decoding output messages
* `boc_cache`?: [*BocCacheType*](https://docs.everos.dev/ever-sdk/reference/mod_boc#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*](https://docs.everos.dev/ever-sdk/reference/mod_processing#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*](https://docs.everos.dev/ever-sdk/reference/mod_abi#abi) – Contract ABI for decoding output messages
* `skip_transaction_check`?: *boolean* – Skip transaction check flag
* `boc_cache`?: [*BocCacheType*](https://docs.everos.dev/ever-sdk/reference/mod_boc#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*](https://docs.everos.dev/ever-sdk/reference/mod_processing#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*](https://docs.everos.dev/ever-sdk/reference/mod_abi#abi) – Contract ABI for decoding output messages
* `boc_cache`?: [*BocCacheType*](https://docs.everos.dev/ever-sdk/reference/mod_boc#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*](https://docs.everos.dev/ever-sdk/reference/mod_processing#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