Module tvm

Module tvm

Functions

run_executor – Emulates all the phases of contract execution locally

run_tvm – Executes get-methods of ABI-compatible contracts

run_get – Executes a get-method of FIFT contract

Types

TvmErrorCode

ExecutionOptions

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 – Emulate uninitialized account to run deploy message

AccountForExecutorAccountVariant – Account state to run message

AccountForExecutor

TransactionFees

ParamsOfRunExecutor

ResultOfRunExecutor

ParamsOfRunTvm

ResultOfRunTvm

ParamsOfRunGet

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.

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 – Account to run on executor
• execution_options?: ExecutionOptions – Execution options.
• abi?: Abi – Contract ABI for decoding output messages
• skip_transaction_check?: boolean – Skip transaction check flag

• boc_cache?: 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 – Optional decoded message bodies according to the optional abi parameter.
• account: string – Updated account state BOC. Encoded as base64

• fees: 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.

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 – Execution options.
• abi?: Abi – Contract ABI for decoding output messages
• boc_cache?: 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 – 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

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 – 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

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

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

type AccountForExecutorNoneVariant = {

}

AccountForExecutorUninitVariant

Emulate uninitialized account to run deploy message

type AccountForExecutorUninitVariant = {

}

AccountForExecutorAccountVariant

Account state to run message

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

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:

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

TransactionFees

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

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 – Account to run on executor
• execution_options?: ExecutionOptions – Execution options.
• abi?: Abi – Contract ABI for decoding output messages
• skip_transaction_check?: boolean – Skip transaction check flag

• boc_cache?: 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

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 – Optional decoded message bodies according to the optional abi parameter.
• account: string – Updated account state BOC. Encoded as base64

• fees: TransactionFees – Transaction fees

ParamsOfRunTvm

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 – Execution options.
• abi?: Abi – Contract ABI for decoding output messages
• boc_cache?: 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

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

• out_messages: string[] – List of output messages' BOCs. Encoded as base64

• decoded?: 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

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 – 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

type ResultOfRunGet = {
    output: any
}

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