TON Contract Executor  

This library allows you to run TON Virtual Machine locally and execute contract.
That allows you to write & debug & fully test your contracts before launching them to the network.

Features

TON Contract executor allows you to:

- execute smart contracts from existing code and data Cells
- get TVM execution logs
- debug your contracts via debug primitives
- seamlessly handle internal state changes of contract data and code
- call so-called get methods of smart contracts
- send and debug internal and external messages
- debug messages sent by smart contract
- manipulate the C7 register of the smart contract (including time, random seed, network config, etc.)
- make some gas optimizations

Basically you can develop, debug, and fully cover your contract with unit-tests fully locally without deploying it to the network

Installation

``bash
yarn add ton-contract-executor
`

How it works


Creating SmartContract from FunC source code (here the @ton-community/func-js package is used for compilation):
`typescript
import { compileFunc } from "@ton-community/func-js";
import { SmartContract } from "ton-contract-executor";
import { Cell } from "@ton/core";

async function main() {
const source =
() main() {
;; noop
}

int sum(int a, int b) method_id {
return a + b;
}

const compileResult = await compileFunc({
sources: {
'contract.fc': source,
},
entryPoints: ['contract.fc'],
})

if (compileResult.status === 'error') throw new Error('compilation failed')

const contract = await SmartContract.fromCell(
Cell.fromBoc(Buffer.from(compileResult.codeBoc, 'base64'))[0],
new Cell(),
)
}
`

In some cases it's useful to create SmartContract from existing precompiled code Cell & data Cell.
For example if you need to debug some existing contract from network.

Here is an example of creating a local copy of existing wallet smart contract from the network deployed at EQD4FPq-PRDieyQKkizFTRtSDyucUIqrj0v_zXJmqaDp6_0t address and getting its seq:

`typescript
import {Address, Cell, TonClient} from "@ton/core";
import {SmartContract} from "ton-contract-executor";

const contractAddress = Address.parse('EQD4FPq-PRDieyQKkizFTRtSDyucUIqrj0v_zXJmqaDp6_0t')

let client = new TonClient({
endpoint: 'https://toncenter.com/api/v2/jsonRPC'
})

async function main() {
let state = await client.getContractState(contractAddress)

let code = Cell.fromBoc(state.code!)[0]
let data = Cell.fromBoc(state.data!)[0]

let wallet = await SmartContract.fromCell(code, data)

let res = await wallet.invokeGetMethod('seqno', [])
console.log('Wallet seq is: ', res.result[0])
}

`

Interacting with contract

Once you have created instance of SmartContract you can start interacting with it.

$3

You can invoke any get method on contract using `invokeGetMethod` function:

`typescript
import { SmartContract, stackInt } from "ton-contract-executor";
import { Cell } from "@ton/core";

async function main() {
const source =
() main() {
;; noop
}

int sum(int a, int b) method_id {
return a + b;
}

const compileResult = await compileFunc({
sources: {
'contract.fc': source,
},
entryPoints: ['contract.fc'],
})

if (compileResult.status === 'error') throw new Error('compilation failed')

const contract = await SmartContract.fromCell(
Cell.fromBoc(Buffer.from(compileResult.codeBoc, 'base64'))[0],
new Cell(),
)

const res = await contract.invokeGetMethod('sum', [
// argument a
stackInt(1),
// argument b
stackInt(2),
])

console.log('1 + 2 = ', res.result[0])
}
`

You can create arguments of other types for get methods using exported functions stackInt, stackCell, stackSlice, stackTuple and stackNull.

$3

You can send both external and internal messages to your contract by calling sendMessage:
`typescript
import { SmartContract, internal } from "ton-contract-executor";
import { Cell } from "@ton/core";

async function main() {
const contract = await SmartContract.fromCell(
Cell.fromBoc(Buffer.from(compileResult.codeBoc, 'base64'))[0],
new Cell(),
)

const msgBody = new Cell()

const res = await this.contract.sendInternalMessage(internal({
dest: contractAddress,
value: 1n, // 1 nanoton
bounce: false,
body: msgBody,
}))
}
`

ton-contract-executor exports two helpers, internal and externalIn to help you create the necessary Message objects.

There are two aliases for sendMessage - sendInternalMessage and sendExternalMessage, but they only check that the type of the provided Message is internal or external-in respectively, otherwise their behavior is the same as sendMessage.

$3

invokeGetMethod, sendMessage, sendInternalMessage, sendExternalMessage all support last optional opts?: { gasLimits?: GasLimits; } argument for setting gas limits.
As an example, the following code

`typescript
import { compileFunc } from "@ton-community/func-js";
import { SmartContract, stackInt } from "ton-contract-executor";
import { Cell } from "@ton/core";

async function main() {
const source =
() main() {
;; noop
}

int sum(int a, int b) method_id {
return a + b;
}

const compileResult = await compileFunc({
sources: {
'contract.fc': source,
},
entryPoints: ['contract.fc'],
})

if (compileResult.status === 'error') throw new Error('compilation failed')

let contract = await SmartContract.fromCell(
Cell.fromBoc(Buffer.from(compileResult.codeBoc, 'base64'))[0],
new Cell(),
)

console.log(await contract.invokeGetMethod('sum', [
stackInt(1),
stackInt(2),
], {
gasLimits: {
limit: 308,
},
}))
}
`
will output a failed execution result to console, because such a call requires 309 gas.

$3

As the result of calling `sendMessage`, `sendInternalMessage`, `sendExternalMessage` or `invokeGetMethod`, an ExecutionResult object is returned.

ExecutionResult could be either successful or failed:

`typescript
declare type FailedExecutionResult = {
type: 'failed';
exit_code: number;
gas_consumed: number;
result: NormalizedStackEntry[];
actionList: OutAction[];
action_list_cell?: Cell;
logs: string;
};
declare type SuccessfulExecutionResult = {
type: 'success';
exit_code: number;
gas_consumed: number;
result: NormalizedStackEntry[];
actionList: OutAction[];
action_list_cell?: Cell;
logs: string;
};
declare type ExecutionResult = FailedExecutionResult | SuccessfulExecutionResult;
`

What is what:

- exit_code: exit code of TVM
- result: resulting stack (basically the result of function in case of get methods)
- gas_consumed: consumed gas amount
- actionList (list of output actions of smart contract, such as messages )
- action_list_cell: raw cell with serialized action list
- logs: logs of TVM

$3

You also can configure some parameters of your smart contract:

`fromCell` accepts configuration object as third parameter:

`typescript
type SmartContractConfig = {
getMethodsMutate: boolean; // this allows you to use set_code in get methods (useful for debugging)
debug: boolean; // enables or disables TVM logs (it's useful to disable logs if you rely on performance)
runner: TvmRunner;
};
`

TvmRunner allows you to select TVM executor for specific contract, by default all contracts use `TvmRunnerAsynchronous` which runs thread pool of WASM TVM (it uses worker_threads on node and web workers when bundled for web).

$3

By default, for each call to TVM current unixtime is set to C7 register, but you can change it by calling `setUnixTime` on SmartContract instance.

$3

C7 register is used to access some external information in contract:

`typescript
export declare type C7Config = {
unixtime?: number;
balance?: bigint;
myself?: Address;
randSeed?: bigint;
actions?: number;
messagesSent?: number;
blockLt?: number;
transLt?: number;
globalConfig?: Cell;
};
`

We prefill it by default, but you can change it by calling `setC7Config` or `setC7`.

$3

In order for your tests to terminate successfully, you need to terminate the spawned worker threads, which can be done as follows:

`typescript
import {TvmRunnerAsynchronous} from "ton-contract-executor";

await TvmRunnerAsynchronous.getShared().cleanup()
`

$3

ton-contract-executor can be bundled using webpack, but a polyfill for Buffer is required.

This can be done by installing the buffer package and adding the following to your webpack configuration:

`js
resolve: {
fallback: {
"buffer": require.resolve("buffer/")
}
}
`

However, if you are using @ton-community/func-js for compilation, you also need polyfills for crypto and stream (crypto-browserify and stream-browserify respectively), and add the following to your webpack configuration:

`js
resolve: {
fallback: {
"fs": false,
"path": false,
"crypto": require.resolve("crypto-browserify"),
"stream": require.resolve("stream-browserify"),
"buffer": require.resolve("buffer/")
}
}
``

$3

If you need to build the WASM part of this package, you can use this repo

License

MIT