{"id":33278853,"url":"https://github.com/ton-blockchain/tvm-specification","last_synced_at":"2025-11-17T10:05:01.446Z","repository":{"id":310819836,"uuid":"1038803064","full_name":"ton-blockchain/tvm-specification","owner":"ton-blockchain","description":"TON Virtual Machine instructions specification","archived":false,"fork":false,"pushed_at":"2025-10-15T20:26:53.000Z","size":1746,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-10-15T20:53:54.773Z","etag":null,"topics":["specifications","ton","tvm","vm"],"latest_commit_sha":null,"homepage":"https://txtracer.ton.org/spec/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ton-blockchain.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-15T21:05:02.000Z","updated_at":"2025-10-15T20:26:57.000Z","dependencies_parsed_at":"2025-08-20T13:12:12.156Z","dependency_job_id":"506dc418-44ee-441a-93bc-919c79f9e357","html_url":"https://github.com/ton-blockchain/tvm-specification","commit_stats":null,"previous_names":["i582/tvm-specification","ton-blockchain/tvm-specification"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ton-blockchain/tvm-specification","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ton-blockchain%2Ftvm-specification","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ton-blockchain%2Ftvm-specification/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ton-blockchain%2Ftvm-specification/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ton-blockchain%2Ftvm-specification/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ton-blockchain","download_url":"https://codeload.github.com/ton-blockchain/tvm-specification/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ton-blockchain%2Ftvm-specification/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":284861040,"owners_count":27075156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-17T02:00:06.431Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["specifications","ton","tvm","vm"],"created_at":"2025-11-17T10:05:00.338Z","updated_at":"2025-11-17T10:05:01.438Z","avatar_url":"https://github.com/ton-blockchain.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TON Virtual Machine Instructions Specification\n\nSpecification of 900+ instruction of TVM.\n\nFull specification as a JSON file can be found in [`gen/tvm-specification.json`](gen/tvm-specification.json).\n\nTypeScript wrappers can be found in [`types/`](src/types) and used via `tvm-specification` package.\n\nJSON Schema of specifications is available in [`gen/schema.json`](gen/schema.json).\nGenerators such as [quicktype.io](https://app.quicktype.io/) can be used to generate wrappers for a specific programming\nlanguage.\n\n## Current state\n\n- Instructions count: **918**\n- With exit code description: **169**\n- With examples: **33**\n- With other implementations description: **102**\n- With TLB representation: **918**\n- Without any text description: **0**, including arithmetic: **0**\n- With unverified empty stack signature: **0**\n- Fift instructions count: **116**\n- With C++ implementations: **918**\n\n## Validity\n\nThis repository contains scripts that check the validity of instruction descriptions:\n\n- [input-instr-signature.ts](validity/input-instr-signature.ts) — checks the validity of instruction signatures and\n  operands (currently 825 instructions are automatically checked (90%))\n- [examples-validation.ts](validity/examples-validation.ts) — checks the validity of instruction examples by executing\n  them and verifying that the resulting stack matches the expected output\n- [other-implementations-validation.ts](validity/other-implementations-validation.ts) — checks that the instructions\n  listed in `other_implementations` is compilable\n- [tlb-validation.ts](validity/tlb-validation.ts) — checks the validity of TLB representations by parsing them and\n  generating TypeScript wrapper code\n- [docs-links-validation.ts](validity/docs-links-validation.ts) — checks that documentation links in `docs_links` are\n  reachable\n- JSON Schema validation — validates the JSON schema itself and checks that the generated specification conforms to it\n\n## Projects that use this specification\n\n- [TxTracer](https://txtracer.ton.org/) — Web app for tracing and analyzing transactions\n- [Playground](https://txtracer.ton.org/play/) — TVM Assembly and FunC playground\n- [TON VS Code Extension](https://github.com/ton-blockchain/ton-language-server) — VS Code extension for TON developers\n- [TVM Specification page](https://txtracer.ton.org/spec/) — Visual representation of this specification\n- [TASM](https://github.com/ton-blockchain/tasm) — Assembler and disassembler implementation for TVM bitcode in pure\n  TypeScript tested on 100k real contracts from blockchain\n\n## Examples\n\nThis repository includes practical examples demonstrating how to use this specification:\n\n- [Simple TVM Disassembler (Go)](examples/golang/tasm-go/) — Minimal implementation (200 lines of core deserialization\n  logic) showing how to create a TVM bytecode disassembler using the specification.\n\n## Use cases\n\nCurrently, the specification is mainly used in two ways:\n\n- Using human-readable instruction descriptions in interfaces (TxTracer on hover) or for\n  autocompletion (Playground).\n- Using machine-readable instruction descriptions for tools such as TASM.\n\nLet's briefly describe the main fields for each way of using the specification. If you want to read full documentation\nabout each field, check out the [specification schema](src/types/specification-schema.ts).\n\n### As Documentation\n\nIf you want to use this specification as documentation, the main source of information is the\n`description` field that exists for each instruction.\n\n#### Required fields:\n\n- `short` — brief mostly one-line description of the instruction. If non-empty, describes the short description of the\n  instruction\n- `long` — detailed description of the instruction's functionality\n- `operands` — list of operand names for the instruction, their types and possible values are located in the root\n  `layout` field\n\n#### Optional fields:\n\n- `tags` — list of tags for categorizing and searching instructions\n- `exit_codes` — list of possible exit codes and their trigger conditions\n- `other_implementations` — list of alternative implementations for this instruction using other instructions\n- `related_instructions` — list of instructions that are related or similar to this one\n- `examples` — list of examples showing how to use this instruction with stack state\n- `gas` — list of gas consumption entries with descriptions and formulas\n- `docs_links` — list of documentation links related to this instruction\n\nIf you also want to display the stack signature, use the root `signature` field and the `stack_string`\nfield from it. This field contains a human-readable description of the input and output types on the stack.\n\n#### Fift instructions\n\nThis specification also describes instructions that are only available in Fift and are aliases for existing\ninstructions.\n\n### For Tool Developers\n\nWhen building tools that work with TVM bytecode (disassemblers, analyzers, debuggers, etc.), you need to decode\ncomplete instructions from the bytecode stream. The specification provides all the necessary information in the\n`layout` field of each instruction to implement this process.\n\nCheck out [examples/golang/tasm-go/tasm/decompile.go](examples/golang/tasm-go/tasm/decompile.go) for a minimal\nimplementation of a TVM bytecode disassembler using the specification.\n\n## Development\n\n[`data/`](data) directory contains a set of files with description for all instructions. This description doesn't\ninclude information that can be obtained from [`src/instructions/instructions.ts`](src/instructions/instructions.ts)\nfile which contains bit-level specification for each instruction.\n\n### Generation\n\nTo generate C++ implementations for each instruction, we need to clone the TON repository. Before the full specification\ngeneration run the following command to clone TON repository and generate `implementations.json` file.\n\n```\nyarn find-implementations\n```\n\nTo generate the full specification, run:\n\n```\nyarn generate\n```\n\nBefore the commit run:\n\n```\nyarn precommit\n```\n\nTo format, build and validate changes.\n\n# License\n\nMIT © TON Core\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fton-blockchain%2Ftvm-specification","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fton-blockchain%2Ftvm-specification","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fton-blockchain%2Ftvm-specification/lists"}