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

$3

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

$3

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.

$3

`typescript
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:

`bash


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