Module tvm
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 abortedEmulates 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.message: string – Input message BOC. Must be encoded as base64.skip_transaction_check?: boolean – Skip transaction check flagboc_cache?: BocCacheType – Cache type to put the result. The BOC itself returned if no cache type providedreturn_updated_account?: boolean – Return updated account flag. Empty string is returned if the flag isfalse
transaction: any – Parsed transaction. In addition to the regular transaction fields there is abocfield encoded withbase64which contains source transaction BOC.out_messages: string[] – List of output messages' BOCs. Encoded asbase64account: string – Updated account state BOC. Encoded asbase64
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.message: string – Input message BOC. Must be encoded as base64.account: string – Account BOC. Must be encoded as base64.boc_cache?: BocCacheType – Cache type to put the result. The BOC itself returned if no cache type providedreturn_updated_account?: boolean – Return updated account flag. Empty string is returned if the flag isfalse
out_messages: string[] – List of output messages' BOCs. Encoded asbase64account: string – Updated account state BOC. Encoded asbase64. Attention! Onlyaccount_state.storage.state.datapart of the BOC is updated.
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.account: string – Account BOC inbase64function_name: string – Function nameinput?: any – Input parameterstuple_list_as_array?: boolean – Convert lists based on nested tuples in the result into plain arrays. Default isfalse. 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
output: any – Values returned by get-method on stack
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 = 401CanNotReadBlockchainConfig = 402TransactionAborted = 403InternalError = 404ActionPhaseFailed = 405AccountCodeMissing = 406LowBalance = 407AccountFrozenOrDeleted = 408AccountMissing = 409UnknownExecutionError = 410InvalidInputStack = 411InvalidAccountBoc = 412InvalidMessageType = 413ContractExecutionError = 414AccountIsSuspended = 415
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 configblock_time?: number – time that is used as transaction timeblock_lt?: bigint – block logical timetransaction_lt?: bigint – transaction logical timechksig_always_succeed?: boolean – Overrides standard TVM behaviour. If set totruethen CHKSIG always will returntrue.signature_id?: number – Signature ID to be used in signature verifying instructions when CapSignatureWithId capability is enabled
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 abortedtype AccountForExecutorNoneVariant = {
}
Emulate uninitialized account to run deploy message
type AccountForExecutorUninitVariant = {
}
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
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 abortedWhen 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;
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 fieldstorage_fee: bigint – Fee for account storagegas_fee: bigint – Fee for processingout_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 fieldtotal_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 forwardingaccount_fees: bigint – Total account fees for the transaction execution. Compounds of storage_fee + gas_fee + ext_in_msg_fee + total_fwd_fees
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.skip_transaction_check?: boolean – Skip transaction check flagboc_cache?: BocCacheType – Cache type to put the result. The BOC itself returned if no cache type providedreturn_updated_account?: boolean – Return updated account flag. Empty string is returned if the flag isfalse
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 abocfield encoded withbase64which contains source transaction BOC.out_messages: string[] – List of output messages' BOCs. Encoded asbase64account: string – Updated account state BOC. Encoded asbase64
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.boc_cache?: BocCacheType – Cache type to put the result. The BOC itself returned if no cache type providedreturn_updated_account?: boolean – Return updated account flag. Empty string is returned if the flag isfalse
type ResultOfRunTvm = {
out_messages: string[],
decoded?: DecodedOutput,
account: string
}
out_messages: string[] – List of output messages' BOCs. Encoded asbase64account: string – Updated account state BOC. Encoded asbase64. Attention! Onlyaccount_state.storage.state.datapart of the BOC is updated.
type ParamsOfRunGet = {
account: string,
function_name: string,
input?: any,
execution_options?: ExecutionOptions,
tuple_list_as_array?: boolean
}
account: string – Account BOC inbase64function_name: string – Function nameinput?: any – Input parameterstuple_list_as_array?: boolean – Convert lists based on nested tuples in the result into plain arrays. Default isfalse. 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
type ResultOfRunGet = {
output: any
}
output: any – Values returned by get-method on stack
Last modified 1mo ago