Skip to content

Rework and proofread Tolk section #1054

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Mar 25, 2025
Merged

Rework and proofread Tolk section #1054

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
d7cf6dd
Update changelog.md
reveloper Mar 20, 2025
9f3130a
Update in-detail.mdx
reveloper Mar 20, 2025
834b1f0
Update overview.mdx
reveloper Mar 25, 2025
51ea28d
Update overview.mdx
reveloper Mar 25, 2025
ef366bd
Update in-short.md
reveloper Mar 25, 2025
cdf32c3
Update mutability.mdx
reveloper Mar 25, 2025
651569b
Update stdlib.md
reveloper Mar 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions docs/v3/documentation/smart-contracts/tolk/changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ When new versions of Tolk are released, they will be mentioned here.
2. Standard library (asm definitions) updated to reflect nullability
3. Smart casts, like in TypeScript in Kotlin
4. Operator `!` (non-null assertion)
5. Code after `throw` is treated unreachable
5. Code after `throw` is treated as unreachable
6. The `never` type


Expand All @@ -46,15 +46,15 @@ The first public release. Here are some notes about its origin:
## How Tolk was born

In June 2024, I created a pull request [FunC v0.5.0](https://github.com/ton-blockchain/ton/pull/1026).
Besides this PR, I've written a roadmap — what can be enhanced in FunC, syntactically and semantically.
Besides this PR, I've written a roadmap for what can be enhanced in FunC, syntactically and semantically.

All in all, instead of merging v0.5.0 and continuing developing FunC, we decided to **fork** it.
To leave FunC untouched, as it is. As it always was. And to develop a new language, driven by a fresh and new name.
Instead of merging v0.5.0 and continuing to develop FunC, we decided to **fork** it.
To leave FunC untouched as it is. As it always was. And to develop a new language driven by a fresh and new name.

For several months, I have worked on Tolk privately. I have implemented a giant list of changes.
And it's not only about the syntax. For instance, Tolk has an internal AST representation, completely missed in FunC.
And it's not only about the syntax. For instance, Tolk has an internal AST representation that is completely missed in FunC.

On TON Gateway, on 1-2 November in Dubai, I had a speech presenting Tolk to the public, and we released it the same day.
On TON Gateway, from 1 to 2 November in Dubai, I gave a speech presenting Tolk to the public, and we released it the same day.
The video is available [on YouTube](https://www.youtube.com/watch?v=Frq-HUYGdbI).

Here is the very first pull request: ["Tolk Language: next-generation FunC"](https://github.com/ton-blockchain/ton/pull/1345).
Expand All @@ -64,11 +64,11 @@ The first version of the Tolk Language is v0.6, a metaphor of FunC v0.5 that mis

## Meaning of the name "Tolk"

"Tolk" is a very beautiful word.
**Tolk** is a wonderful word.

In English, it's consonant with *talk*. Because, generally, what do we need a language for? We need it *to talk* to computers.

In all slavic languages, the root *tolk* and the phrase *"to have tolk"* means "to make sense"; "to have deep internals".
In all Slavic languages, the root *tolk* and the phrase *"to have tolk"* means "to make sense"; "to have deep internals".

But actually, **TOLK** is an abbreviation.
You know, that TON is **The Open Network**.
Expand Down
59 changes: 32 additions & 27 deletions docs/v3/documentation/smart-contracts/tolk/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ title: Overview

import Button from '@site/src/components/button'

# Tolk Language: overview
# Tolk language: overview

**Tolk** is a new language for writing smart contracts in TON. Think of Tolk as the "**next‑generation FunC**".
Tolk compiler is literally a fork of FunC compiler, introducing familiar syntax similar to TypeScript,
but leaving all low-level optimizations untouched.
**Tolk** is a new language for writing smart contracts in TON.
Tolk compiler is a fork of FunC compiler, introducing familiar syntax similar to TypeScript
but leaving all low-level optimizations untouched. Think of Tolk as the next‑generation FunC.

```tolk
import "storage.tolk"
Expand Down Expand Up @@ -63,16 +63,16 @@ int currentCounter() method_id {
Try a FunC → Tolk converter
</Button>
<Button href="/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-short" colorType={'secondary'} sizeType={'sm'}>
Read "Tolk vs FunC differences"
Tolk vs FunC differences
</Button>
<div style={{height: '2em'}}></div>


## Motivation behind Tolk

FunC is awesome.
It is really low-level and encourages a programmer to think about compiler internals.
It gives full control over TVM assembler, allowing a programmer to make his contract as effective as possible.
It is low-level and encourages a programmer to think about compiler internals.
It gives complete control over TVM assembler, allowing a programmer to make his contract as effective as possible.
If you get used to it, you love it.

But there is a problem.
Expand All @@ -81,7 +81,7 @@ If you are keen on Lisp and Haskell, you'll be happy.
But if you are a JavaScript / Go / Kotlin developer, its syntax is peculiar for you, leading to occasional mistakes.
A struggle with syntax may decrease your motivation for digging into TON.

Imagine, what if there was a language, also smart, also low-level, but not functional and not like C?
Imagine what if there was a language that was smart and low-level but not functional and not like C?
Leaving all beauty and complexity inside, what if it would be more similar to popular languages at first glance?

That's what Tolk is about.
Expand All @@ -91,24 +91,24 @@ That's what Tolk is about.

If you know FunC and want to try a new syntax, your way is:
1. Read [Tolk vs FunC: in short](/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-short).
2. With blueprint, create a new Tolk contract (for example, a counter) and experiment around. Remember, that almost all stdlib functions are renamed to ~~verbose~~ clear names. Here is [a mapping](/v3/documentation/smart-contracts/tolk/tolk-vs-func/stdlib).
3. Try a [converter](https://github.com/ton-blockchain/convert-func-to-tolk) for your existing contracts or one from [FunC Contracts](/v3/documentation/smart-contracts/contracts-specs/examples). Keep in mind that contracts written in Tolk from scratch would definitely look nicer than being auto-converted. For instance, using logical operators instead of bitwise tremendously increases code readability.
2. With a blueprint, create a new Tolk contract (for example, a counter) and experiment around it. Remember that almost all stdlib functions are renamed to ~~verbose~~ clear names. Here is [a mapping](/v3/documentation/smart-contracts/tolk/tolk-vs-func/stdlib).
3. Try a [converter](https://github.com/ton-blockchain/convert-func-to-tolk) for your existing contracts or one from [FunC Contracts](/v3/documentation/smart-contracts/contracts-specs/examples). Remember that contracts written in Tolk from scratch look nicer than auto-converted ones. For instance, using logical operators instead of bitwise tremendously increases code readability.

## How to try Tolk if you don't know FunC

:::tip Currently, this documentation assumes that you know FunC
The documentation describes "Tolk vs FunC" differences.
Later it will be adapted to land newcomers. Moreover, FunC will eventually become deprecated,
and all code snippets throughout the whole documentation will be rewritten to Tolk.
This section describes the **Tolk vs FunC** differences.
Later, it will be adapted to land newcomers. Moreover, FunC will eventually become deprecated for onboarding,
and all code snippets throughout the documentation will be rewritten for Tolk.
:::

If you are new to TON, your way is:
1. Dig into [this documentation](/v3/documentation/smart-contracts/overview) to acquire basic on development in TON. No matter what language you'll use, you need to be aware of cells, slices, TON asynchronous nature after all.
2. Facing FunC snippets, you can still use FunC, or try to express the same in Tolk. If FunC syntax is peculiar for you, don't worry: the goal of Tolk is exactly to fix this issue.
3. Once you gain some understanding of what's going on, try using Tolk with [blueprint](https://github.com/ton-org/blueprint).
1. Dig into [this documentation](/v3/documentation/smart-contracts/overview) to acquire basic on development in TON. No matter your language, you must be aware of cells, slices, and TON asynchronous nature.
2. Facing FunC snippets, you can still use FunC or try to express the same in Tolk. If FunC syntax is peculiar to you, don't worry: the goal of Tolk is to fix this issue precisely.
3. Once you understand what's happening, try using Tolk with [blueprint](https://github.com/ton-org/blueprint).


## Tooling around Tolk Language
## Tooling around Tolk language

Sources of the Tolk compiler are a part of the `ton-blockchain` [repo](https://github.com/ton-blockchain/ton).
Besides the compiler, we have:
Expand All @@ -125,31 +125,36 @@ Besides the compiler, we have:
The Tolk compiler, a fork of the FunC compiler, is deemed production-ready, albeit somewhat experimental at the moment.

Undiscovered bugs may exist, potentially inherited from FunC or attributable to TVM characteristics.
Anyway, no matter what language you use, you should cover your contracts with tests to reach high reliability.
Anyway, no matter your language, you should cover your contracts with tests to reach high reliability.


## Roadmap

The first released version of Tolk is v0.6, emphasizing [missing](/v3/documentation/smart-contracts/tolk/changelog#how-tolk-was-born) FunC v0.5.

Here are some (yet not all and not ordered in any way) points to be investigated:
Here are some points to investigate:
- type system improvements
- structures and generics
- auto-pack structures to/from cells, probably integrated with message handlers
- methods for structures, generalized to cover built-in types
- easier messages sending
- better experience for common use-cases (jettons, nft, etc.)
- easier message sending
- better experience for everyday use cases: jettons, NFT, etc.
- gas and stack optimizations, AST inlining
- extending and maintaining stdlib
- some kind of ABI (how explorers "see" bytecode)
- some ABI (how explorers "see" bytecode)
- gas and fee management in general

The next strategic goal for **Tolk v1.0** is **structures with auto-serialization into cells**.
This will eliminate the need for manual manipulations with builders and slices, allowing data and messages to be described declaratively.
The following strategic milestone for **Tolk v1.0** is structures with auto-serialization into cells.

This milestone eliminates manual manipulations with builders and slices, allowing data and messages to be described declaratively.
Closely related to this is the **ABI (interface) of contracts**.
Well-designed structures actually make up the majority of an ABI.
Well-designed structures make up the majority of an ABI.


## Issues and contacts

If you face an issue, connect to developer society on [TON Dev Chats](https://t.me/addlist/1r5Vcb8eljk5Yzcy) or create GitHub issues.

## Issues and Contacts
## See also

If you face issue, connect to developer society on [TON Dev Chats](https://t.me/addlist/1r5Vcb8eljk5Yzcy) or create GitHub issues.
- [Tolk vs FunC: in short](/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-short)
Loading
Loading