ton-source-map

TON Source Map

TypeScript type definitions and utilities for the TON Source Map format used by Tolk and FunC compilers.

What is TON Source Map?

TON Source Map provides debugging capabilities for smart contracts compiled to TVM (TON Virtual Machine). It enables source-level debugging by mapping between:

• High-level source code (Tolk/FunC) and TVM bitcode (Cells)
• Debug locations with variable state information
• Source files and their compiled representations

Architecture

The source map consists of two main components:

High-Level Mapping

Maps DEBUGMARK IDs (debug sections) to high-level language constructs:

• Source code locations (file, line, column)
• Variable states at each debug point
• Function context and inlining information
• AST node types and execution context

Assembly Mapping

Maps TVM Cells to assembly instructions:

• Cell hash to instruction sequences
• Instruction locations and debug sections
• Offset-based navigation in bitcode

How Mappings Work Together

The two mappings form a complete debugging bridge between TVM bitcode and source code through debug sections:

1. High-level → Debug Sections: Each HighLevelSourceMapEntry has an idx field that represents a debug section number. This connects source locations to logical code blocks.

2. Assembly → Debug Sections: Each InstructionInfo contains a debugSections array that links TVM instructions to the same debug section numbers.

3. Complete Mapping: When TVM executes an instruction, you can:

   • Find the instruction in assembly mapping by (cell hash + offset)
   • Get debug section numbers from that instruction
   • Look up corresponding source locations in high-level mapping

Example flow:

TVM Execution Data (hash + offset)
    ↓ findInstructionInfo()
Assembly Mapping → InstructionInfo.debugSections[]
    ↓ findHighlevelLocationBySection()
High-Level Mapping → HighLevelSourceMapEntry.loc (file, line, column)

This architecture enables bidirectional debugging: from bitcode to source code and vice versa.

Usage

import {SourceMap, findHighlevelLocations} from "ton-source-map"

// Find source location from TVM execution data
const locations = findHighlevelLocations(sourceMap, cellHash, offset)

Development

This project uses Corepack to manage Yarn version. Make sure to enable it first:

# Enable corepack (one time setup)
corepack enable

# Run tests
yarn test

# Run linter check
yarn fmt:check

# Run full pre-commit checks
yarn precommit

License

MIT