Tolk 1.4 on TON: ABI, TypeScript wrappers, source maps

On May 11, 2026, the TON team shipped Tolk 1.4, with 1.4.1 patch following on May 23. This is the largest update to the language since its initial release: ABI export, TypeScript wrappers, source maps, debugger marks, plus a declarative contract block.

Here’s what it means for developers and why 1.4 isn’t “another minor upgrade” — it’s an infrastructure shift.

The headline idea: contract as a declaration

Previously, a Tolk file was a collection of functions — onInternalMessage, get methods, helpers — and the compiler inferred from signatures that this was a contract. From 1.4 there’s an explicit declarative block:

contract Counter {
    author: "Tolk Team"
    version: "0.1"
    description: "A small counter contract"

    storage: ContractStorage
    incomingMessages: Increment | Reset
}

// the rest of the code is unchanged:
// - types and declarations
// - onInternalMessage
// - get methods

The block does not change bytecode. Its job is to give tooling a machine-readable description of the contract. From it the compiler knows:

• Author and version (for UI and block explorers).
• The type used in storage.
• Which messages the contract can accept.

With this declaration a contract stops being “an opaque set of functions” — it becomes an object with metadata that tooling can understand.

ABI: automatic interface generation

The most practical consequence of the contract block is automatic ABI export. ABI (application binary interface) is a machine-readable description of contract inputs and outputs: which messages it accepts, in what format, which get methods return what.

Before 1.4 you wrote ABI on TON by hand — a separate JSON or YAML kept in sync with contract code. Any signature change required an ABI update, or the client side broke.

From 1.4 the Tolk compiler generates ABI itself from the contract declaration:

1. Changed storage — ABI updates automatically.
2. Added a new incoming message — ABI knows about it.
3. Created a new get method — ABI exports it.

What this gives you: block explorers can parse contract transactions with meaningful field names, dApp UIs can generate forms for specific messages, test tools know which methods to call.

TypeScript wrappers: client code almost for free

On top of ABI, 1.4 ships automatic TypeScript wrapper generation. This is a client-side shim for your contract that knows all its methods and messages, and offers them in your IDE with autocomplete and type checks.

Pre-1.4, the typical workflow for wiring a contract into a dApp:

1. Write the contract in Tolk/FunC.
2. Write TypeScript classes by hand for each incoming message and each get method.
3. Serialise by hand, parse responses by hand.
4. When the contract changes — synchronously update the TS code.

From 1.4, steps 2-4 are done by the compiler. You write the contract, run the build — you get a ready TS module that imports into your dApp and works immediately. Example call:

import { Counter } from './tolk-output/Counter';

const counter = Counter.fromAddress(address);
await counter.send(provider, sender, value, { op: 'Increment' });
const value = await counter.getValue(provider);

Without 1.4 you wrote all of this by hand; with 1.4 it’s generated.

Source maps and debugger marks: debugging in Tolk

A TON developer’s biggest pain for years has been the absence of proper debugging. Contract crashed on TVM instruction 7 — go figure out what that means in bytecode. With 1.4 that’s behind us.

Source maps. A mapping between TVM bytecode and Tolk source: the compiler records which TVM instruction corresponds to which line of your code, which variables sit where on the stack, how call frames are arranged. When a transaction fails on a specific TVM instruction, source maps let you see: “failed here, in this Tolk line, in this function”.

Debugger marks. Compiler-inserted markers in bytecode that let a debugger set breakpoints and step through even fully-optimised production contracts. Previously, to debug you had to build in debug mode (slow, unoptimised); now you can debug the production build directly.

In practice: a developer can take a production contract, replay a specific transaction in a local emulator with step-by-step execution — and see exactly where things went wrong. Before 1.4 this kind of tooling effectively didn’t exist on TON.

New import rules

The contract block brings two rules that change project structure:

Rule 1: all get methods live in the same file as contract. Previously Tolk allowed splitting get functions across files via imports. From 1.4, if you use contract MyContract, all entrypoints (onInternalMessage, onExternalMessage, get methods) must live in the same file as the declaration. This doesn’t work:

// file: separate-getter.tolk
get fun method1() { ... }

// file: MyContract.tolk
import "separate-getter"   // compile error

contract MyContract { ... }

Why: so the contract file shows the contract’s full interface in one place. This makes reading and understanding easier for other developers.

Rule 2: import "MyContract" does not pull its entrypoints. If a project has multiple contracts (JettonMinter + JettonWallet), you can now import one from another without onInternalMessage collision. Pre-1.4 you had to carefully extract shared types to separate files; from 1.4 the contract block “hides” internal entrypoints on import.

A useful side effect: you can write tests as get methods in separate files of the same project. They don’t conflict with the contract’s own get methods, and all imported types work inside:

import "Counter"

get fun `test increase does not overflow`() {
    val initial = Storage { value: 0 };
    // ... tests
}

PascalCase for filenames

Tolk 1.4 adopts a preferred convention: filename = contract name in PascalCase. So JettonMinter.tolk instead of jetton_minter.tolk. Not required (old names still work), but idiomatic — and improves readability in IDEs and imports.

What’s in 1.4.1

The 1.4.1 release on May 23, 2026 is described as “small fixes and minor updates” — a stabilising patch after 1.4.0. The team doesn’t publish a detailed fix list, but the patch arriving 12 days after 1.4.0 implies that 1.4.0 caught minor bugs that were promptly fixed. If you’re upgrading now — go straight to 1.4.1.

Who should update and when

If you maintain an active Tolk contract:

• Install 1.4.1 on a dev machine, run a project build.
• Add the contract declaration to your main files — you get ABI and TS wrappers for free.
• Add TS module generation to CI alongside the compiled contract.

If you’re starting a new project:

• Begin with the contract block. PascalCase filenames.
• Use auto-generated TypeScript wrappers — saves days on dApp integration.

If you’re still on FunC:

• 1.4 is a strong argument to look at Tolk. ABI and TS wrappers out of the box — FunC doesn’t have those and won’t get them. Intro to the language — in our Tolk overview.

If you’re just learning TON smart contracts:

• Tolk 1.4 + ABI + TypeScript wrappers — the lowest barrier to entry TON has ever had. Start with Tolk, not FunC.

What’s next

Per the Tolk 1.4 PR and team comments, ABI and source maps are “the final pieces of the original vision”. That means the fundamental Tolk feature set is now complete. Likely next steps:

• Further language enhancements (types, generics, patterns).
• Expanded IDE support (debug UI, TON Studio integration).
• ABI standardisation as an ecosystem format (so block explorers and UI frameworks parse the same ABI).

In parallel with Tolk, the TVM itself is moving — the upgrade to TVM v14 is coming in TON Core v2026.05-rc. See our TON Core release explainer for the changes Tolk 1.5+ will build on.

The full TON development ecosystem — in our SDK comparison. First-contract walkthrough if you haven’t yet — in our Acton hands-on piece.