Skip to content

Latest commit

 

History

History
418 lines (333 loc) · 13.3 KB

mod_tvm.md

File metadata and controls

418 lines (333 loc) · 13.3 KB
Raw

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

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 debugginh, to find out the reason why message was not delivered successfully

  • because Validators just throw away the failed external inbound messages, here you can catch them.

Another use case is to estimate fees for message execution. Set AccountForExecutor::Account.unlimited_balance to true so that emulation will not depend on the actual balance.

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

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.

If you need this emulation to be as precise as possible then specify ParamsOfRunExecutor 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>;

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

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

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
}

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

ExecutionOptions

type ExecutionOptions = {
    blockchain_config?: string,
    block_time?: number,
    block_lt?: bigint,
    transaction_lt?: bigint
}
  • 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

AccountForExecutor

type AccountForExecutor = {
    type: 'None'
} | {
    type: 'Uninit'
} | {
    type: 'Account'
    boc: string,
    unlimited_balance?: boolean
}

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

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
}
  • in_msg_fwd_fee: bigint
  • storage_fee: bigint
  • gas_fee: bigint
  • out_msgs_fwd_fee: bigint
  • total_account_fees: bigint
  • total_output: bigint

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