# ton-source-map

> TypeScript type definitions and functions for TON Source Map format used by Tolk and FunC compilers

Latest version **0.2.2** (published 2025-09-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install ton-source-map
pnpm add ton-source-map
yarn add ton-source-map
bun add ton-source-map
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.2 |
| Published | 2025-09-23 |
| First published | 2025-09-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.0.0 |
| Dependencies | 0 |
| Unpacked size | 33.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | TON Core |
| Maintainers | petr_makhnev |
| Keywords | ton, tolk, func, tvm, source-map |

## Links

- npm: https://www.npmjs.com/package/ton-source-map
- Repository: https://github.com/i582/ton-source-map
- Homepage: https://github.com/i582/ton-source-map#readme
- Issues: https://github.com/i582/ton-source-map/issues
- npm.io page: https://npm.io/package/ton-source-map

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 0.2.2 (latest) — 2025-09-23
- 0.2.1 — 2025-09-23
- 0.2.0 — 2025-09-23
- 0.1.0 — 2025-09-23

## README

# TON Source Map

[![CI](https://github.com/i582/ton-source-map/workflows/CI/badge.svg)](https://github.com/i582/ton-source-map/actions)

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

```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](https://nodejs.org/api/corepack.html) 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

---
_Source: https://npm.io/package/ton-source-map · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._