Skip to content

Documentation for Tolk written from scratch #1421

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

Open
wants to merge 11 commits into
base: main
Choose a base branch
from
+10,285 −5,188
Open

Documentation for Tolk written from scratch #1421

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
4d86562
Fix some typos in existing Tolk docs
tolk-vm Nov 10, 2025
df0525a
[Tolk] Created page structure for the future Tolk documentation
tolk-vm Nov 10, 2025
610b1e8
[Tolk] New docs: type system
tolk-vm Nov 13, 2025
08c2887
[Tolk] New docs: syntax details
tolk-vm Nov 17, 2025
35ada07
[Tolk] New docs: language features
tolk-vm Nov 20, 2025
50b60c0
[Tolk] New docs: migration from FunC
tolk-vm Nov 21, 2025
4854fdf
[Tolk] New docs: idioms and conventions
tolk-vm Nov 23, 2025
4c42120
[Tolk] New docs: additions to changelog
tolk-vm Nov 23, 2025
420b832
[Tolk] New docs: overview page (landing)
tolk-vm Nov 23, 2025
f34329f
[Tolk] Syntax highlighting via Prism.js
tolk-vm Nov 23, 2025
8a3ead6
[Tolk] Modify cspell for a spellchecker to succeed
tolk-vm Nov 24, 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
21 changes: 21 additions & 0 deletions .cspell.jsonc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,26 @@
"!2lw-deny-list", // turns off the dictionary
]
},
{
"filename": "languages/tolk/features/message-sending.mdx",
"ignoreWords": [
"StateInit",
Copy link
Collaborator

@verytactical verytactical Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

StateInit is the name of the type, not a word. We have specifically created a spellchecker rule to convert it into code.

Copy link
Collaborator Author

@tolk-vm tolk-vm Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this article, StateInit is not the name of the type, it's a word.

For example, it occurs in a header:

<h2>Deployment, StateInit, and workchains</h2>

Another example, it's used as a word:

It's incorrect to say that "StateInit is code+data"

The type is ContractState, it's quoted in backticks.

Copy link
Collaborator

@verytactical verytactical Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which language has a word "StateInit"?

Copy link
Collaborator Author

@tolk-vm tolk-vm Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And which language has a word "masterchain"?

Copy link
Collaborator

@verytactical verytactical Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

English admits joining words, but neither capitalizes them in the process, or abbreviates "initialization" to "init", or has the same word defined as a type in block.tlb.

We're pushing for consistent use of the words in documentation, and StateInit was intentionally put in the list, so that we can at the very least replace all the uses with a single regex in case we decide to.

]
},
{
"filename": "languages/tolk/features/compiler-optimizations.mdx",
"ignoreWords": [
"fifting",
]
},
{
"filename": "languages/tolk/from-func/tolk-vs-func.mdx",
"ignoreWords": [
"transpiles",
"Hindley",
"Milner",
]
},
{
"filename": "**/api/**/*.{json,yml,yaml}",
"ignoreWords": [
Expand Down Expand Up @@ -110,6 +130,7 @@
"foundations/whitepapers/ton.mdx",
"foundations/whitepapers/tvm.mdx",
"languages/fift/whitepaper.mdx",
"languages/tolk/features/standard-library.mdx",
// Generated files
"tvm/instructions.mdx",
// Binaries
Expand Down
16 changes: 8 additions & 8 deletions contract-dev/first-smart-contract.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ First, we need a way to store the counter value. Tolk makes this simple with <To

```tolk title="./contracts/first_contract.tolk"
struct Storage {
counter: uint64; // the current counter value
counter: uint64 // the current counter value
}
// load contract data from persistent storage
Expand Down Expand Up @@ -153,17 +153,17 @@ Tolk structures are also useful for defining message bodies. In our case, we’l
Each structure has a unique prefix (`0x7e8764ef` and `0x3a752f06`), widely called opcodes, that lets the contract distinguish between them.

```tolk title="./contracts/first_contract.tolk"
struct(0x7e8764ef) IncreaseCounter {
struct (0x7e8764ef) IncreaseCounter {
increaseBy: uint32
}
struct(0x3a752f06) ResetCounter {}
struct (0x3a752f06) ResetCounter {}
```

To group them together, we'll use a union. Unions allow multiple types to be bundled into a single type that can be serialized and deserialized automatically:

```tolk title="./contracts/first_contract.tolk"
type AllowedMessage = IncreaseCounter | ResetCounter;
type AllowedMessage = IncreaseCounter | ResetCounter
```

Now we can write our message handler:
Expand Down Expand Up @@ -227,7 +227,7 @@ Here’s the full source code of `contracts/first_contract.tolk`:

```tolk title="./contracts/first_contract.tolk" expandable
struct Storage {
counter: uint64;
counter: uint64
}
fun Storage.load() {
Expand All @@ -238,13 +238,13 @@ fun Storage.save(self) {
contract.setData(self.toCell());
}
struct(0x7e8764ef) IncreaseCounter {
struct (0x7e8764ef) IncreaseCounter {
increaseBy: uint32
}
struct(0x3a752f06) ResetCounter {}
struct (0x3a752f06) ResetCounter {}
type AllowedMessage = IncreaseCounter | ResetCounter;
type AllowedMessage = IncreaseCounter | ResetCounter
fun onInternalMessage(in: InMessage) {
val msg = lazy AllowedMessage.fromSlice(in.body);
Expand Down
142 changes: 121 additions & 21 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -395,21 +395,71 @@
"tag": "recommended",
"pages": [
"languages/tolk/overview",
"languages/tolk/basic-syntax",
"languages/tolk/idioms-conventions",
{
"group": "From FunC",
"group": "Type system",
"pages": [
"languages/tolk/from-func/in-short",
"languages/tolk/from-func/in-detail",
"languages/tolk/from-func/mutability",
"languages/tolk/from-func/stdlib",
"languages/tolk/from-func/create-message",
"languages/tolk/from-func/lazy-loading",
"languages/tolk/from-func/pack"
"languages/tolk/types/list-of-types",
"languages/tolk/types/numbers",
"languages/tolk/types/booleans",
"languages/tolk/types/address",
"languages/tolk/types/cells",
"languages/tolk/types/strings",
"languages/tolk/types/structures",
"languages/tolk/types/aliases",
"languages/tolk/types/generics",
"languages/tolk/types/enums",
"languages/tolk/types/nullable",
"languages/tolk/types/unions",
"languages/tolk/types/tensors",
"languages/tolk/types/tuples",
"languages/tolk/types/maps",
"languages/tolk/types/callables",
"languages/tolk/types/void-never",
"languages/tolk/types/type-checks-and-casts",
"languages/tolk/types/overall-tvm-stack",
"languages/tolk/types/overall-serialization"
]
},
{
"group": "Syntax details",
"pages": [
"languages/tolk/syntax/variables",
"languages/tolk/syntax/conditions-loops",
"languages/tolk/syntax/exceptions",
"languages/tolk/syntax/functions-methods",
"languages/tolk/syntax/structures-fields",
"languages/tolk/syntax/pattern-matching",
"languages/tolk/syntax/mutability",
"languages/tolk/syntax/operators",
"languages/tolk/syntax/imports"
]
},
{
"group": "Language features",
"pages": [
"languages/tolk/features/message-handling",
"languages/tolk/features/contract-storage",
"languages/tolk/features/contract-getters",
"languages/tolk/features/message-sending",
"languages/tolk/features/auto-serialization",
"languages/tolk/features/lazy-loading",
"languages/tolk/features/jetton-payload",
"languages/tolk/features/standard-library",
"languages/tolk/features/asm-functions",
"languages/tolk/features/compiler-optimizations"
]
},
{
"group": "Migrating from FunC",
"pages": [
"languages/tolk/from-func/tolk-vs-func",
"languages/tolk/from-func/tolk-vs-tlb",
"languages/tolk/from-func/stdlib-fc",
"languages/tolk/from-func/converter"
]
},
"languages/tolk/environment-setup",
"languages/tolk/counter-smart-contract",
"languages/tolk/language-guide",
"languages/tolk/changelog"
]
},
Expand Down Expand Up @@ -916,52 +966,52 @@
},
{
"source": "/v3/documentation/smart-contracts/tolk/environment-setup",
"destination": "/languages/tolk/environment-setup",
"destination": "contract-dev/first-smart-contract",
"permanent": true
},
{
"source": "/v3/documentation/smart-contracts/tolk/counter-smart-contract",
"destination": "languages/tolk/counter-smart-contract",
"destination": "contract-dev/first-smart-contract",
"permanent": true
},
{
"source": "/v3/documentation/smart-contracts/tolk/language-guide",
"destination": "languages/tolk/language-guide",
"destination": "languages/tolk/basic-syntax",
"permanent": true
},
{
"source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-short",
"destination": "/languages/tolk/from-func/in-short",
"destination": "/languages/tolk/from-func/tolk-vs-func",
"permanent": true
},
{
"source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-detail",
"destination": "/languages/tolk/from-func/in-detail",
"destination": "/languages/tolk/from-func/tolk-vs-func",
"permanent": true
},
{
"source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/mutability",
"destination": "/languages/tolk/from-func/mutability",
"destination": "/languages/tolk/syntax/mutability",
"permanent": true
},
{
"source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/stdlib",
"destination": "/languages/tolk/from-func/stdlib",
"destination": "/languages/tolk/from-func/stdlib-fc",
"permanent": true
},
{
"source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/pack-to-from-cells",
"destination": "languages/tolk/from-func/pack",
"destination": "languages/tolk/features/auto-serialization",
"permanent": true
},
{
"source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/create-message",
"destination": "languages/tolk/from-func/create-message",
"destination": "languages/tolk/features/message-sending",
"permanent": true
},
{
"source": "/v3/documentation/smart-contracts/tolk/tolk-vs-func/lazy-loading",
"destination": "languages/tolk/from-func/lazy-loading",
"destination": "languages/tolk/features/lazy-loading",
"permanent": true
},
{
Expand Down Expand Up @@ -3193,6 +3243,56 @@
"source": "/participate/run-nodes/full-node",
"destination": "/v3/guidelines/nodes/running-nodes/full-node",
"permanent": true
},
{
"source": "/languages/tolk/from-func/in-short",
"destination": "/languages/tolk/from-func/tolk-vs-func",
"permanent": true
},
{
"source": "/languages/tolk/from-func/in-detail",
"destination": "/languages/tolk/from-func/tolk-vs-func",
"permanent": true
},
{
"source": "/languages/tolk/from-func/mutability",
"destination": "/languages/tolk/syntax/mutability",
"permanent": true
},
{
"source": "/languages/tolk/from-func/stdlib",
"destination": "/languages/tolk/from-func/stdlib-fc",
"permanent": true
},
{
"source": "/languages/tolk/from-func/create-message",
"destination": "/languages/tolk/features/message-sending",
"permanent": true
},
{
"source": "/languages/tolk/from-func/lazy-loading",
"destination": "/languages/tolk/features/lazy-loading",
"permanent": true
},
{
"source": "/languages/tolk/from-func/pack",
"destination": "/languages/tolk/features/auto-serialization",
"permanent": true
},
{
"source": "/languages/tolk/environment-setup",
"destination": "/languages/tolk/overview",
"permanent": true
},
{
"source": "/languages/tolk/counter-smart-contract",
"destination": "/languages/tolk/overview",
"permanent": true
},
{
"source": "/languages/tolk/language-guide",
"destination": "/languages/tolk/overview",
"permanent": true
}
]
}
53 changes: 53 additions & 0 deletions extra.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,3 +75,56 @@ table {
div[data-component-part="callout-content"]>.code-block:last-child {
margin-bottom: 0;
}

/*
A temporary solution syntax highlighting of Tolk snippets: invoke Prism.js on a client-side.
See `snippets/tolk-highlight.jsx`.
@link https://github.com/ton-org/docs/issues/1473
*/

:root {
--tolk-token-comment: #808080;
--tolk-token-type-hint: #D500EC;
--tolk-token-keyword: #0000FF;
--tolk-token-struct: #007EA2;
--tolk-token-variable: #444444;
--tolk-token-attr-name: #808000;
--tolk-token-function: #A82D2D;
--tolk-token-number: #0B9000;
--tolk-token-string: #008000;
--tolk-token-string-bg: #FAF9EF;
--tolk-token-operator: #A0A000;
--tolk-token-punctuation: #808000;
--tolk-token-three-dots: #999999;
}

.token.comment { color: var(--tolk-token-comment); font-style: italic; }
.token.type-hint { color: var(--tolk-token-type-hint); }
.token.boolean { color: var(--tolk-token-keyword); }
.token.keyword { color: var(--tolk-token-keyword); }
.token.self { color: var(--tolk-token-variable); font-weight: bold; }
.token.attr-name { color: var(--tolk-token-attr-name); }
.token.function { color: var(--tolk-token-function); }
.token.number { color: var(--tolk-token-number); }
.token.string { color: var(--tolk-token-string); background-color: var(--tolk-token-string-bg); }
.token.operator { color: var(--tolk-token-operator); }
.token.punctuation { color: var(--tolk-token-punctuation); }
.token.three-dots { color: var(--tolk-token-three-dots); }
.token.struct { color: var(--tolk-token-struct); }
.token.variable { color: var(--tolk-token-variable); }

html.dark {
--tolk-token-comment: #808080;
--tolk-token-type-hint: #DF90F8;
--tolk-token-keyword: #D75F02;
--tolk-token-struct: #56C1FF;
--tolk-token-variable: #C5D2E0;
--tolk-token-attr-name: #808000;
--tolk-token-function: #F9B900;
--tolk-token-number: #33A033;
--tolk-token-string: #33A033;
--tolk-token-string-bg: #1B1C1E;
--tolk-token-operator: #A0A000;
--tolk-token-punctuation: #85B2A0;
--tolk-token-three-dots: #777777;
}
2 changes: 1 addition & 1 deletion foundations/addresses/derive.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ fun main() {

The `b5ee9c724101010100020000004cacb9cd` in the `getCode` function is a placeholder for a hardcoded code cell in [BoC](/foundations/serialization/boc) format known at compile-time. The `getData` function is a placeholder for building a data cell, and the actual implementation depends on the storage layout of the target smart contract. Usually, data is composed in a parametrized way, but this does not alter the rest of the logic — only the `getData` function.

The `calculateAddress` function uses the [`AutoDeployAddress`](/languages/tolk/from-func/create-message#stateinit-and-workchains) built-in that handles all the underlying `StateInit` and address composing logic. In the [Tolk stdlib](/languages/tolk/from-func/stdlib), the code and data pair is represented by [`ContractState`](/languages/tolk/from-func/create-message#dont-confuse-stateinit-and-codedata-they-are-different). The `buildAddress` method returns a builder containing the resulting address, which can be cheaply stored in another builder — the most common use case.
The `calculateAddress` function uses the [`AutoDeployAddress`](/languages/tolk/features/message-sending) built-in that handles all the underlying `StateInit` and address composing logic. In the Tolk stdlib, the code and data pair is represented by `ContractState`. The `buildAddress` method returns a builder containing the resulting address, which can be cheaply stored in another builder — the most common use case.

### On-chain — contract sharding

Expand Down
2 changes: 1 addition & 1 deletion languages/func/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ noindex: "true"
import { Aside } from '/snippets/aside.jsx';

<Aside>
TON Blockchain uses Tolk as the official language. Other languages are still available, and legacy codebases exist, but Tolk is the only actively supported language. The FunC compiler, for instance, is no longer maintained.
TON Blockchain uses [Tolk](/languages/tolk) as the official language. Other languages are still available, and legacy codebases exist, but Tolk is the only actively supported language. The FunC compiler, for instance, is no longer maintained.
</Aside>

FunC is a domain-specific, statically typed language with C-like syntax designed to write smart contracts on TON. It can be characterized as an intermediate-level language sitting on top of the [Fift](/languages/fift) assembly language.
Expand Down
Loading