TON Assembly (TASM)

The ton-assembly ↗️ NPM package provides a set of utilities for converting between the BoC-serialized TVM bitcode, Fift assembly sources, and a Fift-like pseudocode format called TON Assembly (TASM).

Available tools:

• tasm — an assembler from TASM assembly to TVM bitcode (BoC-serialized).
• tdisasm — a disassembler from TVM bitcode (BoC-serialized) to TASM assembly.
• tfift — a compiler of Fift assembly smart contract source files to TVM bitcode (BoC-serialized).

Installation

The package requires Node.js LTS 18 or later.

Run the following command to install the TASM tool suite globally:

npm install -g ton-assembly

Command-line usage

Disassembler, tdisasm

Run tdisasm to decompile (disassemble) BoC files into TASM:

tdisasm contract.boc -o decompiled.tasm --verbose

Assembler, tasm

Run tasm to compile (assemble) TASM files into BoC-serialized TVM bitcode:

tasm contract.tasm -o compiled.boc --verbose

Fift assembly compiler, tfift

Run tfift to compile Fift assembly files into BoC-serialized TVM bitcode:

tfift contract.fif -o contract.boc

tfift accepts the subset of Fift assembly emitted by Tolk and does not support arbitrary Fift programs or constructions such as <b b> s>.

BoC input-output format options

Use -f to change the input-output format:

• Supported formats are: binary (default), hex, base64.
• tasm and tfift use -f to select the BoC output format.
• tdisasm uses -f to select the BoC input format and always emits TASM text.

# Binary output (default)
tasm contract.tasm -f binary -o contract.boc

# Hex output
tasm contract.tasm -f hex -o compiled.hex

# Base64 output
tasm contract.tasm -f base64 -o compiled.base64

Use -s to read input from a string argument instead of a file:

• tasm and tfift take the source text, TASM or Fift assembly, respectively.
• tdisasm takes a hex-or Base64-encoded BoC data, and -f must specify its encoding.

# TASM source input and hex-encoded BoC output
tasm -s "PUSHINT_4 1" -f hex -o compiled.hex

Library usage

Install the package as a project dependency:

npm install ton-assembly

The package exports 4 modules:

• text parses TASM string into an abstract syntax tree (AST) represented by Instr[] or pretty-prints the AST as a TASM string.
• runtime compiles and decompiles between Instr[] (AST representation), TVM binary Cell values, and BoC Buffer values.
• logs parses TVM emulator execution logs.
• trace correlates executed instructions with TASM source locations by using mappings produced during compilation.

import {
  // Parsing and printing module
  text,
  // (De)compilation module
  runtime,
  // TVM logs parsing module
  logs,
} from "ton-assembly";

// Module: text
const code = "PUSH s0";
//                        filepath, assembly
const parseResult = text.parse("<code>", code);
if (parseResult.$ === "ParseFailure") {
  throw parseResult.error;
} // "ParseSuccess"
const instructions = parseResult.instructions;
// Pretty-printed an array of `Instr` objects as a formatted assembly code string.
console.log(text.print(instructions));

// Module: runtime
const boc = runtime.compile(instructions);
const decompiledInstructions = runtime.decompile(boc);
// Assembled to a BoC buffer, then disassembled it.
console.log(text.print(decompiledInstructions));

// Module: logs
const executionLog = `
  code cell hash:6DB0B8EFEF2B59D53B896E2A6EBCBBEF72BE9A1F8CD2DA1D0E8EA8F57C4F8AE0 offset:2608
  stack: [98 100 0 101]
  execute PUSHINT 0
  gas remaining: 999999998
  changing gas limit to 100
  handling exception code 2: stack underflow
  default exception handler, terminating vm with exit code 2
  final c5:C{00000000}
`;
const parsedLog = logs.parse(executionLog);
for (const line of parsedLog) {
  if (line.$ === "VmStack") {
    console.log("Stack contents:", line.stack);
  }
  if (line.$ === "VmExecute") {
    console.log("Executing:", line.instr);
  }
}

For the examples of the trace module, see the full API documentation of ton-assembly ↗️.