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

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

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'

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

PreviousModule proofs NextModule utils

Last updated 1 year ago