From d7cf6ddff827e7c3d86bc4fb257f5855d722a763 Mon Sep 17 00:00:00 2001 From: AlexG <39581753+reveloper@users.noreply.github.com> Date: Thu, 20 Mar 2025 11:24:35 +0900 Subject: [PATCH 1/7] Update changelog.md Minor proofread. --- .../smart-contracts/tolk/changelog.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/v3/documentation/smart-contracts/tolk/changelog.md b/docs/v3/documentation/smart-contracts/tolk/changelog.md index 5cc2dc8643e..36c3f0c9696 100644 --- a/docs/v3/documentation/smart-contracts/tolk/changelog.md +++ b/docs/v3/documentation/smart-contracts/tolk/changelog.md @@ -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 @@ -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). @@ -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**. From 9f3130a0f7a5c48057857ea990f5ad529575426f Mon Sep 17 00:00:00 2001 From: AlexG <39581753+reveloper@users.noreply.github.com> Date: Thu, 20 Mar 2025 12:07:25 +0900 Subject: [PATCH 2/7] Update in-detail.mdx Minor proofread. --- .../tolk/tolk-vs-func/in-detail.mdx | 114 +++++++++--------- 1 file changed, 57 insertions(+), 57 deletions(-) diff --git a/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-detail.mdx b/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-detail.mdx index 4b2197f44b3..e5bb09cf0b5 100644 --- a/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-detail.mdx +++ b/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-detail.mdx @@ -1,6 +1,6 @@ # Tolk vs FunC: in detail -A very huge list below. Will anyone have enough patience to read it up to the end?.. +A huge list is below. Will anyone have enough patience to read it up to the end?.. :::tip There is a compact version Here: [Tolk vs FunC: in short](/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-short) @@ -35,7 +35,7 @@ Here: [Tolk vs FunC: in short](/v3/documentation/smart-contracts/tolk/tolk-vs-fu ✅ `2+2` is 4, not an identifier. Identifiers can only be alpha-numeric -In FunC, almost any character can be a part of identifier. +In FunC, almost any character can be a part of the identifier. For example, `2+2` (without a space) is an identifier. You can even declare a variable with such a name. @@ -57,11 +57,11 @@ In Tolk, spaces are not mandatory. `2+2` is 4, as expected. `3+~x` is `3 + (~ x) More precisely, an identifier can start from {'[a-zA-Z$_]'} -and be continued with {'[a-zA-Z0-9$_]'}. Note, that `?`, `:`, and others are not valid symbols, `found?` and `op::increase` are not valid identifiers. +and be continued with {'[a-zA-Z0-9$_]'}. Note that `?`, `:`, and others are not valid symbols, and `found?` and `op::increase` are invalid identifiers. Note, that `cell`, `slice`, etc. are valid identifiers: `var cell = ...` or even `var cell: cell = ...` is okay. (like in TypeScript, `number` is a valid identifier) -You can use backticks to surround an identifier, and then it can contain any symbols (similar to Kotlin and some other langs). Its potential usage is to allow keywords be used as identifiers, in case of code generation by a scheme, for example. +You can use backticks to surround an identifier, and then it can contain any symbols (similar to Kotlin and some other languages). This potential usage is to allow keywords to be used as identifiers in case of code generation by a scheme, for example. @@ -87,11 +87,11 @@ You can use backticks to surround an identifier, and then it can contain any sym ✅ Impure by default, compiler won't drop user function calls -FunC has an `impure` function specifier. When absent, a function is treated as pure. If its result is unused, its call was deleted by the compiler. +FunC has an `impure` function specifier. When absent, a function is treated as pure. If its result is unused, its call is deleted by the compiler. Though this behavior is documented, it is very unexpected to newcomers. -For instance, various functions that don't return anything (throw an exception on mismatch, for example), -are silently deleted. This situation is spoilt by the fact that FunC doesn't check and validate function body, +For instance, various functions that don't return anything (throw an exception on mismatch, for example) +are silently deleted. This situation is spoilt by FunC not checking and validating the function body, allowing impure operations inside pure functions. In Tolk, all functions are impure by default. You can mark a function pure with annotation, @@ -214,7 +214,7 @@ There is also a `@deprecated` attribute, not affecting compilation, but for a hu ✅ `get` instead of `method_id` -In FunC, `method_id` (without arguments) actually declared a get method. In Tolk, you use a straightforward syntax: +In FunC, `method_id` (without arguments) declared a get method. In Tolk, you use a straightforward syntax:
@@ -262,7 +262,7 @@ fun do_smth(c, n) fun do_smth(c: cell, n: int) ``` -If parameter types are mandatory, return type is not (it's often obvious of verbose). If omitted, it's auto inferred: +If parameter types are mandatory, the return type is not (it's often obvious or verbose). If omitted, it's auto-inferred: ```tolk fun x() { ... } // auto infer from return statements ``` @@ -316,7 +316,7 @@ fun send(msg: cell) { ✅ String postfixes removed, compile-time functions introduced -Tolk removes the old FunC-style string postfixes (`"..."c`, etc.) in favor of a **clearer and more flexible approach**. +Tolk removes the old FunC-style string postfixes (`"..."c`, etc.) in favor of a **more transparent and more flexible approach**.
@@ -372,8 +372,8 @@ fun minihashDemo() { } ``` -The naming highlights, that these functions have "arrived" from string postfixes and operate on string values. -Remember, that at runtime, there are no strings, only slices. +The naming highlights that these functions have arrived from string postfixes and operate on string values. +Remember that at runtime, there are no strings, only slices.

@@ -394,12 +394,12 @@ var items = ( ); ``` -Note, that `(5)` is not a tensor, it's just integer `5` in parentheses. +Note that `(5)` is not a tensor. It's just the integer `5` in parentheses. With a trailing comma `(5,)` it's still `(5)`.

- ✅ Function `ton("...")` for human-readable amounts of toncoins + ✅ Function `ton("...")` for human-readable amounts of Toncoins

@@ -421,7 +421,7 @@ With a trailing comma `(5,)` it's still `(5)`.
-Function `ton()` only accepts constant values (e.g., `ton(some_var)` is invalid). +The function `ton()` only accepts constant values (e.g., `ton(some_var)` is invalid). Its type is `coins` (not `int`!), although it's still a regular `int` from the TVM point of view. Arithmetic over `coins` degrade to `int` (for example, `cost << 1` is valid, `cost + ton("0.02")` also). @@ -555,7 +555,7 @@ fun replaceLast(mutate self: tuple, value: T) { ``` Having called `replaceLast` and `replaceList` will result in TWO generated asm (fift) functions. -Actually, they mostly remind "template" functions. At each unique invocation, function's body is fully cloned under a new name. +They mostly remind template functions. The function's body is fully cloned under a new name at each unique invocation. There may be multiple generic parameters: ```tolk @@ -588,7 +588,7 @@ fun callAnyFn2(f: TCallback, arg: TObj) { } ``` -Note, that while generic `T` are mostly detected from arguments, there are not so obvious corner cases, when `T` does not depend from arguments: +Note that while generic `T` is mostly detected from arguments, there are no such obvious corner cases when `T` does not depend on arguments: ```tolk fun tupleLast(self: tuple): T asm "LAST"; @@ -606,7 +606,7 @@ someF(t.tupleLast()); // ok, T=(paremeter's declared type) return t.tupleLast(); // ok if function specifies return type ``` -Also note, that `T` for asm functions must occupy 1 stack slot (otherwise, asm body is unable to handle it properly), whereas for a user-defined function, `T` could be of any shape. +Also note that `T` for asm functions must occupy one stack slot, whereas for a user-defined function, `T` could be of any shape. Otherwise, asm body is unable to handle it properly. In the future, when structures and generic structures are implemented, all the power of generic functions will come into play. @@ -645,11 +645,11 @@ All parameter types and their order rename the same, only naming is changed. `fu -In Tolk, you can not used a symbol from `a.tolk` without importing this file. In other words, "import what you use". +In Tolk, you can not use a symbol from `a.tolk` without importing this file. In other words, "import what you use". -All stdlib functions are available out of the box, downloading stdlib and `#include "stdlib.fc"` is not needed. See below about embedded stdlib. +All stdlib functions are available out of the box. Downloading stdlib and `#include "stdlib.fc" is unnecessary. See below about embedded stdlib. -There is still a global scope of naming. If `f` is declared in two different files, it's an error. We "import" a whole file, no per-file visibility and `export` keyword is now supported, but probably will be in the future. +There is still a global scope of naming. If `f` is declared in two different files, it's an error. We "import" a whole file with no per-file visibility, and the `export` keyword is now supported but probably will be in the future.

@@ -662,7 +662,7 @@ In Tolk, all pragmas were removed. `allow-post-modification` and `compute-asm-lt As for now, there is one experimental option introduced — `remove-unused-functions`, which doesn't include unused symbols to Fift output. -`#pragma version xxx` was replaced by `tolk xxx` (no >=, just a strict version). It's good practice to annotate compiler version you are using. If it doesn't match, Tolk will show a warning. +`#pragma version xxx` was replaced by `tolk xxx` (no >=, just a strict version). It's good practice to annotate the compiler version you are using. If it doesn't match, Tolk will show a warning. ```tolk tolk 0.6 ``` @@ -672,17 +672,17 @@ tolk 0.6 ✅ Late symbols resolving. AST representation

-In FunC (like in С) you can not access a function declared below: +In FunC, like in С, you can not access a function declared below: ```func int b() { a(); } ;; error int a() { ... } ;; since it's declared below ``` -To avoid an error, a programmer should create a forward declaration at first. The reason is that symbols resolving is performed right at the time of parsing. +To avoid an error, a programmer should first create a forward declaration. The reason is that symbol resolution is performed right during parsing. -Tolk compiler separates these two steps. At first it does parsing, and then it does symbol resolving. Hence, a snippet above would not be erroneous. +Tolk compiler separates these two steps. At first, it does parsing, and then it does symbol resolving. Hence, a snippet above would not be erroneous. -Sounds simple, but internally, it's a very huge job. To make this available, I've introduced an intermediate AST representation, completely missed in FunC. That's an essential point of future modifications and performing semantic code analisys. +It sounds simple, but internally, it's a very huge job. To make this available, I've introduced an intermediate AST representation, which was completely missed in FunC. That's an essential point for future modifications and performing semantic code analysis.

@@ -723,7 +723,7 @@ Creating null values and checking variables on null looks very pretty now. ✅ `throw` and `assert` keywords

-Tolk greatly simplifies working with exceptions. +Tolk dramatically simplifies working with exceptions. If FunC has `throw()`, `throw_if()`, `throw_arg_if()`, and the same for unless, Tolk has only two primitives: `throw` and `assert`. @@ -759,7 +759,7 @@ Note, that `!condition` is possible since logical NOT is available, see below. There is a long (verbose) syntax of `assert(condition, excNo)`: ```tolk assert(condition) throw excNo; -// with possibility to include arg to throw +// with a possibility to include arg to throw ``` Also, Tolk swaps `catch` arguments: it's `catch (excNo, arg)`, both optional (since arg is most likely empty). @@ -818,11 +818,11 @@ Note, that `!condition` is possible since logical NOT is available, see below. ✅ Operator precedence became identical to C++ / JavaScript -In FunC, such code `if (slices_equal() & status == 1)` is parsed as `if( (slices_equal()&status) == 1 )`. This is a reason of various errors in real-world contracts. +In FunC, such code `if (slices_equal() & status == 1)` is parsed as `if( (slices_equal()&status) == 1 )`. This approach is a reason for various errors in real-world contracts. -In Tolk, `&` has lower priority, identical to C++ and JavaScript. +In Tolk, `&` has a lower priority, which is identical to C++ and JavaScript. -Moreover, Tolk fires errors on potentially wrong operators usage to completely eliminate such errors: +Moreover, Tolk fires errors on potentially wrong operators' usage to eliminate such errors: ```tolk if (flags & 0xFF != 0) ``` @@ -832,7 +832,7 @@ will lead to a compilation error (similar to gcc/clang): & has lower precedence than ==, probably this code won't work as you expected. Use parenthesis: either (... & ...) to evaluate it first, or (... == ...) to suppress this error. ``` -Hence, the code should be rewritten: +Hence, you should rewrite the code: ```tolk // either to evaluate it first (our case) if ((flags & 0xFF) != 0) @@ -889,7 +889,7 @@ In Tolk, a function can declare `mutate` parameters. It's a generalization of Fu ✅ Deprecated command-line options removed -Command-line flags `-A`, `-P`, and others, were removed. Default behavior +Command-line flags `-A`, `-P`, and others were removed. Default behavior ``` /path/to/tolk {inputFile} ``` @@ -902,7 +902,7 @@ Only one input file can be passed, others should be `import`'ed. ✅ stdlib functions renamed to ~~verbose~~ clear names, camelCase style -All naming in standard library was reconsidered. Now, functions are named using longer, but clear names. +All names in the standard library were reconsidered. Now, functions are called using longer but clear names. @@ -1087,9 +1087,9 @@ Tolk supports logical operators. They behave exactly as you get used to (right c
-Keywords `ifnot` and `elseifnot` were removed, since now we have logical not (for optimization, Tolk compiler generates `IFNOTJMP`, btw). Keyword `elseif` was replaced by traditional `else if`. +Keywords `ifnot` and `elseifnot` were removed, since now we have logical not (for optimization, Tolk compiler generates `IFNOTJMP`, btw). The `elseif` keyword was replaced by the traditional `else if`. -Remember, that a boolean `true`, transformed `as int`, is -1, not 1. It's a TVM representation. +Remember that a boolean `true`, transformed `as int`, is -1, not 1. It's a TVM representation.

@@ -1149,7 +1149,7 @@ Tolk has nullable types: `int?`, `cell?`, and `T?` in general (even for tensors) Non-nullable types, such as `int` and `cell`, can never hold null values. The compiler enforces **null safety**: you cannot use nullable types without first checking for null. -Fortunately, thanks to smart casts, these checks integrate smoothly and organically into the code. +Fortunately, these checks integrate smoothly and organically into the code thanks to smart casts. Smart casts are purely a compile-time feature — they do not consume gas or extra stack space. ```tolk @@ -1164,14 +1164,14 @@ if (value != null) { } ``` -Remember, that when a variable's type is not specified, it's auto inferred from assignment and never changes: +Remember that when a variable's type is not specified, it's auto-inferred from the assignment and never changes: ```tolk var i = 0; i = null; // error, can't assign `null` to `int` i = maybeInt; // error, can't assign `int?` to `int` ``` -Such a code will not work, you must **explicitly declare the variable as nullable**:: +Such a code will not work. You must **explicitly declare the variable as nullable**:: ```tolk // incorrect var i = null; @@ -1185,7 +1185,7 @@ var i: int? = null; var i = null as int?; ``` -Smart casts (similar to TypeScript and Kotlin) make it easier dealing with nullable types, allowing code like this: +Smart casts (similar to TypeScript and Kotlin) make it easier to deal with nullable types, allowing code like this: ```tolk if (lastCell != null) { // here lastCell is `cell`, not `cell?` @@ -1219,10 +1219,10 @@ if (t.0 != null) { } ``` -Note, that smart casts don't work for globals, only for local vars. +Note that smart casts don't work for globals; they only work for local vars. Tolk has the `!` operator (non-null assertion, compile-time only), like `!` in TypeScript and `!!` in Kotlin. -If you are "absolutely certain" that a variable is not null, +If you are certain that a variable is not null, this operator allows you to skip the compiler's check. ```tolk fun doSmth(c: cell); @@ -1235,7 +1235,7 @@ fun analyzeStorage(nCells: int, lastCell: cell?) { ``` In practice, you'll use this operator working with low-level dicts API. -In the future, Tolk will have a high-level `map`. +Tolk will have a high-level `map` in the future. For now, working with dicts will require the `!` operator. ```tolk // it returns either (slice, true) or (null, false) @@ -1276,11 +1276,11 @@ if (v == null) { // v is `int` again ``` -If you face `never` in compilation errors, most likely there is a warning in preceding code. +If you encounter `never` in compilation errors, there is most likely a warning in the preceding code. -Non-atomic nullables are also allowed: `(int, int)?`, `(int?, int?)?`, or even `()?`. Then, -**a special "value presence" stack slot** is implicitly added. -It holds 0 if value is null, and not 0 (currently, -1) if not null: +Non-atomic nullable are also allowed: `(int, int)?`, `(int?, int?)?`, or even `()?`. Then, +a special *value presence* stack slot is implicitly added. +It holds `0` if a value is null, and not 0 (currently, -1) if not null: ```tolk // t: (int, int)? t = (1, 2); // 1 2 -1 @@ -1292,7 +1292,7 @@ t = (); // -1 t = null; // 0 ``` -All in all, nullability is a major step forward for type safety and reliability. +All in all, nullability is a significant step forward for type safety and reliability. Nullable types eliminate runtime errors, enforcing correct handling of optional values. @@ -1308,8 +1308,8 @@ This change is so huge that it's described on a separate page: [Tolk mutability]

Tolk vs FunC gas consumption

:::caution TLDR -Tolk gas consumption could be a bit higher, because it fixes unexpected arguments shuffling in FunC. It's negligible in practice. -In the future, Tolk compiler will become smart enough to reorder arguments targeting less stack manipulations, +Tolk gas consumption could be higher because it fixes unexpected argument shuffling in FunC, but it's negligible in practice. +In the future, the Tolk compiler will become smart enough to reorder arguments targeting fewer stack manipulations, but still avoiding a shuffling problem. ::: @@ -1319,15 +1319,15 @@ some_asm_function(f1(), f2()); ``` Sometimes, `f2()` could be called before `f1()`, and it's unexpected. -To fix this behavior, one could specify `#pragma compute-asm-ltr`, forcing arguments to be always evaluated in ltr-order. -This was experimental, and therefore turned off by default. +One could specify `#pragma compute-asm-ltr` to fix this behavior, forcing arguments to be evaluated constantly in ltr-order. +This specifier was experimental and, therefore, turned off by default. -This pragma reorders arguments on a stack, often leading to more stack manipulations than without it. -In other words, in fixes unexpected behavior, but increases gas consumption. +This pragma reorders arguments on a stack, often leading to more stack manipulations than without. +In other words, it fixes unexpected behavior but increases gas consumption. -Tolk puts arguments onto a stack exactly the same as if this pragma turned on. -So, its gas consumption is sometimes higher than in FunC if you didn't use this pragma. +Tolk puts arguments onto a stack exactly as if this pragma is turned on. +So, its gas consumption is sometimes higher than FunC's if you don't use this pragma. Of course, there is no shuffling problem in Tolk. -In the future, Tolk compiler will become smart enough to reorder arguments targeting less stack manipulations, +In the future, the Tolk compiler will become smart enough to reorder arguments targeting fewer stack manipulations, but still avoiding a shuffling problem. From 834b1f09a8a1d05835e4369a8216b1b278d8c879 Mon Sep 17 00:00:00 2001 From: AlexG <39581753+reveloper@users.noreply.github.com> Date: Tue, 25 Mar 2025 13:51:10 +0900 Subject: [PATCH 3/7] Update overview.mdx Proofread and rework --- .../smart-contracts/tolk/overview.mdx | 57 ++++++++++--------- 1 file changed, 31 insertions(+), 26 deletions(-) diff --git a/docs/v3/documentation/smart-contracts/tolk/overview.mdx b/docs/v3/documentation/smart-contracts/tolk/overview.mdx index e9b428bd999..776c3e1dcde 100644 --- a/docs/v3/documentation/smart-contracts/tolk/overview.mdx +++ b/docs/v3/documentation/smart-contracts/tolk/overview.mdx @@ -6,9 +6,9 @@ import Button from '@site/src/components/button' # 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" @@ -63,7 +63,7 @@ int currentCounter() method_id { Try a FunC → Tolk converter
@@ -71,8 +71,8 @@ int currentCounter() method_id { ## 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. @@ -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. @@ -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: @@ -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) From 51ea28d361aed4639da31583ee4e5108049e6970 Mon Sep 17 00:00:00 2001 From: AlexG <39581753+reveloper@users.noreply.github.com> Date: Tue, 25 Mar 2025 13:51:40 +0900 Subject: [PATCH 4/7] Update overview.mdx --- docs/v3/documentation/smart-contracts/tolk/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v3/documentation/smart-contracts/tolk/overview.mdx b/docs/v3/documentation/smart-contracts/tolk/overview.mdx index 776c3e1dcde..731372807a9 100644 --- a/docs/v3/documentation/smart-contracts/tolk/overview.mdx +++ b/docs/v3/documentation/smart-contracts/tolk/overview.mdx @@ -4,7 +4,7 @@ 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. Tolk compiler is a fork of FunC compiler, introducing familiar syntax similar to TypeScript From ef366bd7418e4bd1aaf1718ffb02e08787767295 Mon Sep 17 00:00:00 2001 From: AlexG <39581753+reveloper@users.noreply.github.com> Date: Tue, 25 Mar 2025 16:20:11 +0900 Subject: [PATCH 5/7] Update in-short.md Proofread and rework --- .../smart-contracts/tolk/tolk-vs-func/in-short.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-short.md b/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-short.md index 598406581ba..7817a123c9e 100644 --- a/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-short.md +++ b/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-short.md @@ -1,9 +1,9 @@ # Tolk vs FunC: in short -Tolk is much more similar to TypeScript and Kotlin than to C and Lisp. -But it still gives you full control over TVM assembler, since it has a FunC kernel inside. +Tolk is much more similar to TypeScript and Kotlin than C and Lisp. +But it still gives you complete control over the TVM assembler since it has a FunC kernel inside. -1. Functions are declared via `fun`, get methods via `get`, variables via `var` (and `val` for immutable), putting types on the right; parameter types are mandatory; return type can be omitted (auto inferred), as well as for locals; specifiers `inline` and others are `@` attributes +1. Functions are declared via `fun`, get methods via `get`, variables via `var`, immutable variables via `val`, putting types on the right; parameter types are mandatory; return type can be omitted (auto inferred), as well as for locals; specifiers `inline` and others are `@` attributes ```tolk global storedV: int; @@ -20,7 +20,7 @@ fun sum(a: int, b: int) { // auto inferred int get currentCounter(): int { ... } ``` -2. No `impure`, it's by default, compiler won't drop user function calls +2. No `impure`, it's by default, the Tolk compiler won't drop user function calls 3. Not `recv_internal` and `recv_external`, but `onInternalMessage` and `onExternalMessage` 4. `2+2` is 4, not an identifier; identifiers are alpha-numeric; use naming `const OP_INCREASE` instead of `const op::increase`; `cell` and `slice` are valid identifiers (not keywords) 5. Logical operators AND `&&`, OR `||`, NOT `!` are supported @@ -44,7 +44,7 @@ get currentCounter(): int { ... } - `"..."c` → `stringCrc32("...")` (and other postfixes also) 7. A function can be called even if declared below; forward declarations not needed; the compiler at first does parsing, and then it does symbol resolving; there is now an AST representation of source code 8. stdlib functions renamed to ~~verbose~~ clear names, camelCase style; it's now embedded, not downloaded from GitHub; it's split into several files; common functions available always, more specific available with `import "@stdlib/tvm-dicts"`, IDE will suggest you; here is [a mapping](/v3/documentation/smart-contracts/tolk/tolk-vs-func/stdlib) -9. No `~` tilda methods; `cs.loadInt(32)` modifies a slice and returns an integer; `b.storeInt(x, 32)` modifies a builder; `b = b.storeInt()` also works, since it not only modifies, but returns; chained methods work identically to JS, they return `self`; everything works exactly as expected, similar to JS; no runtime overhead, exactly same Fift instructions; custom methods are created with ease; tilda `~` does not exist in Tolk at all; [more details here](/v3/documentation/smart-contracts/tolk/tolk-vs-func/mutability) +9. No `~` tilda methods; `cs.loadInt(32)` modifies a slice and returns an integer; `b.storeInt(x, 32)` modifies a builder; `b = b.storeInt()` also works since it is not only modifies but returns; chained methods work identically to JS, they return `self`; everything works exactly as expected, similar to JS; no runtime overhead, exactly same Fift instructions; custom methods are created with ease; tilda `~` does not exist in Tolk at all; [more details here](/v3/documentation/smart-contracts/tolk/tolk-vs-func/mutability) 10. Clear and readable error messages on type mismatch 11. `bool` type support 12. Indexed access `tensorVar.0` and `tupleVar.0` support @@ -57,6 +57,6 @@ get currentCounter(): int { ... } - WASM wrapper for blueprint [exists](https://github.com/ton-blockchain/tolk-js) - And even a converter from FunC to Tolk [exists](https://github.com/ton-blockchain/convert-func-to-tolk) -#### Where to go next +## See also -[Tolk vs FunC: in detail](/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-detail) +- [Tolk vs FunC: in detail](/v3/documentation/smart-contracts/tolk/tolk-vs-func/in-detail) From cdf32c3e8244fa3e43e83d17c5e95090f8d201bc Mon Sep 17 00:00:00 2001 From: AlexG <39581753+reveloper@users.noreply.github.com> Date: Tue, 25 Mar 2025 16:52:18 +0900 Subject: [PATCH 6/7] Update mutability.mdx Proofread and rework --- .../tolk/tolk-vs-func/mutability.mdx | 52 ++++++++++--------- 1 file changed, 27 insertions(+), 25 deletions(-) diff --git a/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/mutability.mdx b/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/mutability.mdx index 06bfc9aba8c..9ed25c2dfd0 100644 --- a/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/mutability.mdx +++ b/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/mutability.mdx @@ -8,15 +8,15 @@ title: "Tolk vs FunC: mutability" - no `~` tilda methods - `cs.loadInt(32)` modifies a slice and returns an integer - `b.storeInt(x, 32)` modifies a builder -- `b = b.storeInt()` also works, since it not only modifies, but returns -- chained methods work identically to JS, they return `self` +- `b = b.storeInt()` also works since it not only modifies but returns +- chained methods work identically to JS; they return `self` - everything works exactly as expected, similar to JS -- no runtime overhead, exactly same Fift instructions +- no runtime overhead, the same Fift instructions - custom methods are created with ease - tilda `~` does not exist in Tolk at all ::: -This is a drastic change. If FunC has `.methods()` and `~methods()`, Tolk has only dot, one and only way to call a `.method()`. A method may *mutate* an object, or may not. Unlike the list "in short", it's a behavioral and semantic difference from FunC. +This is a drastic change. If FunC has `.methods()` and `~methods()`, Tolk has only a dot, and the only way to call a method is `.method()`. The method may or may not *mutate* an object. Also, there is a behavioral and semantic difference between FunC and the list. The goal is to have calls identical to JS and other languages: @@ -63,7 +63,7 @@ The goal is to have calls identical to JS and other languages: -In order to make this available, Tolk offers a mutability conception, which is a generalization of what a tilda means in FunC. +Tolk offers a mutability conception to make this available, a generalization of what a `~` tilda means in FunC.

By default, all arguments are copied by value (identical to FunC) @@ -80,7 +80,7 @@ someFn(10); // ok, just int origX.someFn(); // still allowed (but not recommended), origX remains 0 ``` -Same goes for cells, slices, whatever: +The same goes for cells, slices, whatever: ```tolk fun readFlags(cs: slice) { return cs.loadInt(32); @@ -90,13 +90,13 @@ var flags = readFlags(msgBody); // msgBody is not modified // msgBody.loadInt(32) will read the same flags ``` -It means, that when you call a function, you are sure that original data is not modified. +This means that when you call a function, you are sure that the original data has not been modified.

`mutate` keyword and mutating functions

-But if you add `mutate` keyword to a parameter, a passed argument will be mutated. To avoid unexpected mutations, you must specify `mutate` when calling it, also: +But if you add the `mutate` keyword to a parameter, it will make a passed argument mutable. To avoid unexpected mutations, you must specify `mutate` when calling it, also: ```tolk fun increment(mutate x: int) { x += 1; @@ -111,7 +111,7 @@ increment(origX); // error, unexpected mutation increment(10); // error, not lvalue origX.increment(); // error, not a method, unexpected mutation val constX = getSome(); -increment(mutate constX); // error, it's immutable, since `val` +increment(mutate constX); // error, it's immutable since `val` ``` Same for slices and any other types: @@ -134,13 +134,13 @@ fun incrementXY(mutate x: int, mutate y: int, byValue: int) { incrementXY(mutate origX, mutate origY, 10); // both += 10 ``` -*You may ask — is it just passing by reference? It effectively is, but since "ref" is an overloaded term in TON (cells and slices have refs), a keyword `mutate` was chosen.* +*You may ask — is it just passing by reference? It effectively is, but since "ref" is an overloaded term in TON (cells and slices have refs), the keyword `mutate` was chosen.*

`self` parameter turning a function into a method

-When a first parameter is named `self`, it emphasizes that a function (still a global one) is a method and should be called via dot. +When you name the first parameter `self`, it emphasizes that the function, though still global, is a method and should be called via a dot. ```tolk fun assertNotEq(self: int, throwIfEq: int) { if (self == throwIfEq) { @@ -153,7 +153,7 @@ someN.assertNotEq(10); assertNotEq(someN, 10); // still allowed (but not recommended) ``` -`self`, without `mutate`, is **immutable** (unlike all other parameters). Think of it like "read-only method". +`self`, without `mutate`, is **immutable** (unlike all other parameters). Think of it like a **read-only method**. ```tolk fun readFlags(self: slice) { return self.loadInt(32); // error, modifying immutable variable @@ -195,7 +195,7 @@ fun incrementWithY(mutate self: int, mutate y: int, byValue: int) { origX.incrementWithY(mutate origY, 10); // both += 10 ``` -If you take a look into stdlib, you'll notice, that lots of functions are actually `mutate self`, meaning they are methods, modifying an object. Tuples, dictionaries, and so on. In FunC, they were usually called via tilda. +If you look into stdlib, you'll notice that many functions are actually **mutate self**, meaning they are methods of modifying an object. Tuples, dictionaries, and so on. In FunC, they were usually called via tilda. ```tolk @pure fun tuplePush(mutate self: tuple, value: X): void @@ -208,7 +208,7 @@ t.tuplePush(1); `return self` makes a method chainable

-Exactly like `return self` in Python or `return this` in JavaScript. That's what makes methods like `storeInt()` and others chainable. +It is precisely like `return self` in Python or `return this` in JavaScript. That makes methods like `storeInt()` and others chainable. ```tolk fun storeInt32(mutate self: builder, x: int): self { self.storeInt(x, 32); @@ -223,13 +223,13 @@ b.storeInt32(4); // works without assignment, since mutates b b = b.storeInt32(5); // and works with assignment, since also returns ``` -Pay attention to the return type, it's `self`. Currently, you should specify it. Being left empty, compilation will fail. Probably, in the future it would be correct. +Pay attention to the return type, it's `self`. You should specify it; otherwise, the compilation will fail if left empty. Probably, in the future, it will be correct.

`mutate self` and asm functions

-While it's obvious for user-defined functions, one could be interested, how to make an `asm` function with such behavior? To answer this question, we should look under the hood, how mutation works inside the compiler. +While it's evident for user-defined functions, one could be interested in how to make an `asm` function with such behavior. To answer this question, we should look under the hood at how mutation works inside the compiler. When a function has `mutate` parameters, it actually implicitly returns them, and they are implicitly assigned to arguments. It's better by example: ```tolk @@ -245,7 +245,7 @@ fun f2(mutate x: int, mutate y: int): (slice, cell) { ... } // actually does: (x', y', r) = f2(x, y); x = x'; y = y'; someF(r) someF(f2(mutate x, mutate y)); -// when `self`, it's exactly the same +// when `self`, it's the same // actually does: (cs', r) = loadInt(cs, 32); cs = cs'; flags = r flags = cs.loadInt(32); ``` @@ -265,7 +265,7 @@ fun loadMessageFlags(mutate self: slice): int asm(-> 1 0) "4 LDU"; ``` -Note, that to return self, you don't have to do anything special, just specify a return type. Compiler will do the rest. +Note, that to return self, you don't have to do anything special, just specify a return type. The compiler will do the rest. ```tolk // "STU" pops (int, builder) and pushes (builder') // with asm(op self), we put arguments to correct order @@ -275,9 +275,9 @@ fun storeMessageOp(mutate self: builder, op: int): self asm(op self) "32 STU"; ``` -It's very unlikely you'll have to do such tricks. Most likely, you'll just write wrappers around existing functions: +It's doubtful you'll have to do such tricks. Most likely, you'll write wrappers around existing functions: ```tolk -// just do like this, without asm, it's the same effective +// just do it like this, without asm; it's the same effective @inline fun myLoadMessageFlags(mutate self: slice): int { @@ -294,15 +294,17 @@ fun myStoreMessageOp(mutate self: builder, flags: int): self { Do I need `@inline` for simple functions/methods? -For now, better do it, yes. In most examples above, `@inline` was omitted for clarity. Currently, without `@inline`, it will be a separate TVM continuation with jumps in/out. With `@inline`, a function will be generated, but inlined by Fift (like `inline` specifer in FunC). +For now, better do it, yes. In most examples above, `@inline` was omitted for clarity. Without `@inline`, it will be a separate TVM continuation with jumps in/out. With `@inline`, a function will be generated, but inlined by Fift, like the `inline` specifier in FunC. -In the future, Tolk will automatically detect simple functions and perform a true inlining by itself, on AST level. Such functions won't be even codegenerated to Fift. The compiler would decide, better than a human, whether to inline, to make a ref, etc. But it will take some time for Tolk to become so smart :) For now, please specify the `@inline` attribute. +In the future, Tolk will automatically detect simple functions and perform true inlining on the AST level. Such functions won't be even codegenerated to Fift. The compiler would decide, better than a human, whether to inline, to make a ref, etc. But it will take some time for Tolk to become so smart :) + +For now, please specify the `@inline` attribute.

- But `self` is not a method, it's still a function! I feel like I've been cheated + But `self` is not a method. It's still a function! I feel like I've been cheated

-Absolutely. Like FunC, Tolk has only global functions (as of v0.6). There are no classes / structures with methods. There are no methods `hash()` for `slice` and `hash()` for `cell`. Instead, there are functions `sliceHash()` and `cellHash()`, which can be called either like functions or by dot (preferred): +Absolutely. Like FunC, Tolk has only global functions (as of v0.6). There are no classes or structures with methods. There are no methods `hash()` for `slice` and `hash()` for `cell`. Instead, there are functions `sliceHash()` and `cellHash()`, which can be called either like functions or by dot (preferred): ```tolk fun f(s: slice, c: cell) { // not like this @@ -317,5 +319,5 @@ fun f(s: slice, c: cell) { } ``` -In the future, after a giant work on the type system, having fully refactored FunC kernel inside, Tolk might have an ability of declaring structures with real methods, generalized enough for covering built-in types. But it will take a long journey to follow. +In the future, Tolk might be able to declare structures with actual methods that are generalized enough to cover built-in types. But it will take a long journey to follow and will be delivered at least after a giant amount of work on the type system, having fully refactored the FunC kernel inside. From 651569ba98ba6e4c8e216674365969fbd175b715 Mon Sep 17 00:00:00 2001 From: AlexG <39581753+reveloper@users.noreply.github.com> Date: Tue, 25 Mar 2025 18:29:11 +0900 Subject: [PATCH 7/7] Update stdlib.md Proofread and rework. --- .../tolk/tolk-vs-func/stdlib.md | 42 +++++++++---------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/stdlib.md b/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/stdlib.md index a46c00725f3..ac08aa9ba69 100644 --- a/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/stdlib.md +++ b/docs/v3/documentation/smart-contracts/tolk/tolk-vs-func/stdlib.md @@ -1,26 +1,26 @@ # Tolk vs FunC: standard library FunC has a rich [standard library](/v3/documentation/smart-contracts/func/docs/stdlib), -known as *"stdlib.fc"* file. It's quite low-level and contains lots of `asm` functions -named very closely to TVM commands. +known as *"stdlib.fc"* file. It's quite low-level and contains many `asm` functions +closely related to [TVM instructions](/v3/documentation/tvm/instructions/). Tolk also has a standard library based on a FunC one. Three main differences: -1. It's split in multiple files: `common.tolk`, `tvm-dicts.tolk`, and others. Functions from `common.tolk` are available always. Functions from other files are available after import: +1. It's split into multiple files: `common.tolk`, `tvm-dicts.tolk`, and others. Functions from `common.tolk` are always available. Functions from other files are available after import: ```tolk import "@stdlib/tvm-dicts" beginCell() // available always createEmptyDict() // available due to import ``` -2. You don't need to download it from GitHub, it's a part of Tolk distribution. -3. Almost all FunC functions were renamed to ~~verbose~~ clear names. So that when you write contracts or read example, you better understand what's going on. +2. You don't need to download it from GitHub; it's a part of Tolk distribution. +3. Almost all FunC functions were renamed to ~~verbose~~ clear names. So that when you write contracts or read examples, you better understand what's going on. ## A list of renamed functions -If "Required import" column is empty, a function is available without any imports. +If the **Required import** column is empty, a function is available without imports. -Note, that some of the functions were deleted, because they either can be expressed syntactically, +Note that some of the functions were deleted because they either can be expressed syntactically, or they were very uncommon in practice. | FunC name | Tolk name | Required import | @@ -210,16 +210,16 @@ or they were very uncommon in practice. ## A list of added functions -Tolk standard library has some functions that were missing in FunC, but are quite common for everyday tasks. +Tolk standard library has some functions missing in FunC but is pretty typical for everyday tasks. -Since Tolk is actively developed, and its standard library changes, better consider `tolk-stdlib/` folder +Since Tolk is actively developed, and its standard library changes, it better considers the `tolk-stdlib/` folder in sources [here](https://github.com/ton-blockchain/ton/tree/master/crypto/smartcont/tolk-stdlib). Besides functions, there some constants were added: `SEND_MODE_*`, `RESERVE_MODE_*`, etc. -When FunC becomes deprecated, the documentation about Tolk stdlib will be completely rewritten, anyway. +When FunC becomes deprecated, the documentation about Tolk stdlib will be rewritten entirely, anyway. -And remember, that all the functions above are actually wrappers over TVM assembler. If something is missing, -you can easily wrap any TVM instruction yourself. +Remember that all the functions above are wrappers over the TVM assembler. If something is missing, +you can quickly wrap any TVM instruction yourself. ## Some functions became mutating, not returning a copy @@ -247,10 +247,10 @@ you can easily wrap any TVM instruction yourself. -Most FunC functions, that were used with `~` tilda in practice, now mutate the object, see examples above. +Most FunC functions used with `~` tilda in practice now mutate the object; see examples above. For example, if you used `dict~udict_set(…)`, just use `dict.uDictSet(…)`, and everything is fine. -But if you used `dict.udict_set(…)` to obtain a copy, you'll need to express it some other way. +But if you used `dict.udict_set(…)` to obtain a copy, you'll need to express it another way. [Read about mutability](/v3/documentation/smart-contracts/tolk/tolk-vs-func/mutability). @@ -258,17 +258,17 @@ But if you used `dict.udict_set(…)` to obtain a copy, you'll need to express i ## How does embedded stdlib work under the hood As told above, all standard functions are available out of the box. -Yeah, for you need `import` for non-common functions (it's intentionally), but still, no external downloads. +You need `import` for non-common functions (it's intentional), but still, no external downloads. It works the following way. -The first thing Tolk compiler does on start is locating stdlib folder by searching in predefined paths relative to an executable binary. -For example, if you launch Tolk compiler from a package installed (e.g. `/usr/bin/tolk`), locate stdlib in `/usr/share/ton/smartcont`. -If you have non-standard installation, you may pass `TOLK_STDLIB` env variable. It's standard practice for compilers. +The first thing the Tolk compiler does at the start is locate the stdlib folder by searching predefined paths relative to an executable binary. +For example, if you launch the Tolk compiler from a package installed (e.g. `/usr/bin/tolk`), locate stdlib in `/usr/share/ton/smartcont`. +You may pass the `TOLK_STDLIB` env variable if you have a non-standard installation. It's standard practice for compilers. A WASM wrapper [tolk-js](https://github.com/ton-blockchain/tolk-js) also contains stdlib. So, when you take tolk-js or blueprint, all stdlib functions are still available out of the box. -IDE plugins (both JetBrains and VS Code) also auto-locate stdlib to provide auto-completion. -If you use blueprint, it automatically installs tolk-js, and therefore, folder `node_modules/@ton/tolk-js/` exists in your project file structure. -Inside, there are `common.tolk`, `tvm-dicts.tolk`, and others. +JetBrains and VS Code IDE plugins also auto-locate stdlib to provide auto-completion. +If you use blueprint, it automatically installs tolk-js; therefore, folder `node_modules/@ton/tolk-js/` exists in your project file structure. +Inside are `common.tolk`, `tvm-dicts.tolk`, and others.