https://github.com/tact-lang/tasm
Assembler and disassembler implementation for TVM bitcode in pure TypeScript
https://github.com/tact-lang/tasm
assembler bitcode bytecode disassembler ton tvm
Last synced: 3 months ago
JSON representation
Assembler and disassembler implementation for TVM bitcode in pure TypeScript
- Host: GitHub
- URL: https://github.com/tact-lang/tasm
- Owner: tact-lang
- License: mit
- Created: 2025-06-04T08:32:53.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-06-23T11:10:00.000Z (4 months ago)
- Last Synced: 2025-06-23T12:24:15.737Z (4 months ago)
- Topics: assembler, bitcode, bytecode, disassembler, ton, tvm
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@tact-lang/ton-assembly
- Size: 669 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# TON Assembly
This repository contains an assembler and disassembler implementation for TVM bitcode.
This implementation provides a complete cycle
`Text -> Internal representation -> Cells -> BoC -> Cells -> Internal representation -> Text`, this means that the same
text assembly can be obtained from a text assembly, going through all the compilation and decompilation steps.
The assembler correctly handles cases where the code does not fit into a single cell and automatically
creates a separate reference for the remaining code.
Current implementation optimizes cases where the reference can be folded into more efficient instructions
(e.g. `IF` into `IFREF`), thereby optimizing gas consumption.
During compilation, the assembler collects additional mappings that can be used to convert the TVM log into a full trace
that will refer to specific instructions in the decompiled version of the contract.
This mapping looks like this:
```
cell-hash + offset -> instruction
```
This implementation is able to generate a coverage report for the contract by BoC and logs
from [Sandbox](https://github.com/ton-org/sandbox).
The proof of concept can be found in the [`./src/coverage`](./src/coverage) folder.
`instructionNameForOpcode()` function can be used to get the name of the instruction for a given opcode, which is useful
for runtime debugging with TVM since TVM itself provides only integer opcodes.
## CLI Tools
This package includes two command-line utilities for working with TON Assembly:
### Assembler
Compile TVM Assembly files to BOC format:
```bash
# Install globally
npm install -g ton-assembly
# Use the assembler
tasm contract.tasm -o contract.boc
# Or via yarn scripts
yarn assembler contract.tasm -o contract.boc
```
### Disassembler
Disassemble BOC files back to TVM Assembly:
```bash
# Use the disassembler
tdisasm contract.boc -o contract.tasm
# Or via yarn scripts
yarn disassembler contract.boc -o contract.tasm
```
Both tools support multiple output formats (binary, hex, base64) and provide verbose output options.
#### Example Usage
```bash
# Compile assembly to BOC
tasm contract.tasm -o contract.boc --verbose
# Disassemble BOC back to assembly
tdisasm contract.boc -o decompiled.tasm --verbose
# Full round-trip test
tasm decompiled.tasm -o recompiled.boc
# contract.boc and recompiled.boc should be identical!
# Work with different formats
tasm contract.tasm -f hex > contract.hex
tdisasm contract.hex -f hex -o contract.tasm
# Assemble from string directly
tasm -s "PUSHINT_4 1" -f hex
# Disassemble from hex/base64 strings directly
tdisasm -s "b5ee9c72410102010027000114ff008e83f4a413ed43d901002fa64ce73b5134348034c7f487f4fffd0115501b05485b1460ec17065c" -f hex -o contract.tasm
tdisasm -s "te6cckEBAgEAJwABFP8AjoP0pBPtQ9kBAC+mTOc7UTQ0gDTH9If0//0BFVAbBUhbFGDsFwZc" -f base64
```
See [CLI documentation](./src/cli/README.md) for detailed usage instructions.
## Library Usage
In addition to the CLI tools, this package can be used as a library for programmatic compilation, decompilation, and log
tracing.
For detailed information, see the [**API Documentation**](API.md).
## Validity
The assembler was tested on 106k contracts from the blockchain
where it successfully decompiled and compiled all contracts into equivalent **Cells**.
## License
This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
MIT © [TON Studio](https://tonstudio.io).