🚀 First beta release of the new TON documentation is now live!
🗺 Jump ahead to beta-docs.ton.org or stay here to learn about the project's backstory, current achievements, and future plans.

For quite some time, developers shared the same feedback: TON documentation is too scattered, difficult to navigate, and has obvious gaps and inconsistencies.

We at TON Studio took that seriously and initiated the TON Docs Revamp project in late July. It is focused on the following four goals:

• To introduce a streamlined, discoverable structure that would be easy to navigate and search
• To make documentation welcoming to all developers, from newcomers to seasoned professionals
• To introduce and maintain stricter quality checks from humans and AIs to ensure proof-read, up-to-date, consistent, and clear content
• And, finally, to set up documentation release pipelines for major TON builders, while making community contributions straightforward and approachable

🏆 Today, with the help and suggestions from various developer teams, including Zengo, RSquad, TonTech, TON API team, and TON Core, the TON Studio is proud to present the first public version of this documentation. It already fulfills the first goal of comprehensive structure and rapidly moves towards achieving the third goal of content.

🦄 That said, this is a beta release: many pages await their contents, some pages require secondary reviews, while infrastructure, pipelines, and processes are only nourishing, not mature yet. All constructive feedback is appreciated.

So, what's in store already? We've got:

• Flat, easy-to-navigate structure
• Hands-on articles with real examples whenever we can provide them
• Visuals and diagrams, including various Mermaid diagrams
• Smart AI search and summaries
• Automatic CI spell checks and AI reviews based on the growing style guide
• ...and much, much more!

🏠 TON Docs Revamp features an engaging landing page that guides users through their TON journey, whether they're first exploring TON, building smart contracts, integrating wallets, or just want to access and navigate the documentation quickly.

📝 Re-written or brand new content includes pages for: mytonctrl, mylocalton, development setups with Sandbox and Blueprint (with major help from TonTech), IDEs and SDKs, gas estimation, analytics, oracles, bridges, TMAs, TON Connect, standard wallet contracts, Jettons, NFTs, TVM instructions (with proper search and discovery), TL-B, FunC and other TON-specific programming languages, web versions of whitepapers (with cross-links and solid AI summaries), and even a "Coming from Ethereum" guide!

📈 And this is just the beginning. Plans ahead and for the next month include:

- Release pipelines and assignments of relevant technical owners
- Docs, infrastructure, and processes for approachable community contributions
- More playgrounds, interactive components, and interactivity
- Much more content
- Stronger AI-based assistance as documentation grows

🎯 The main goals of this beta release are to show preliminary progress, willingness to make things right, and to collect feedback from the developer community before the full release, which is tentatively scheduled for November 17th.

We are nothing without the feedback from the community. If something is missing or confusing, let us know by filing a GitHub issue. Furthermore, help review new content whenever you or someone you know is deeply familiar with the topic. TON is vast, and there is always something to know or be aware of.

Prominent ecosystem projects are invited to host, co-own, and maintain their documentation with us. Keeping things in one place will enrich the user experience and AI responses.

💪 Let's make the best documentation for TON. Together.

→ Beta release URL: beta-docs.ton.org
→ GitHub repository: github.com/ton-org/docs
→ Future milestones: github.com/ton-org/docs/milestone/3

🫧 Tolk v1.2: rich bounced messages, cheap deployment, and a breaking change that you'll love

Tolk v1.2 is here, aligned with TVM 12 — bringing new assembler instructions that make contracts cheaper and cleaner.

This update introduces one breaking change, several powerful new capabilities, and a few quality-of-life improvements across the compiler.

✅ Notable changes in Tolk v1.2:

1. Breaking change: address is now "internal only"
2. Rich bounces: not 256 bits, but the full body on bounce
3. Cheap builder-to-slice, StateInit, and address composition
4. Improved compilation errors
5. Anonymous functions (lambdas)
6. Borrow checker to catch undefined behavior

PR on GitHub with detailed info.

✔ `address` is now "internal only"

Before:
* address meant internal/external/none

Now:
* address — internal only
* address? (nullable) — internal/none, exactly like "maybe address" in @ton/core
* any_address — internal/external/none

In 99% of contracts only internal addresses are used. External ones are rare, and "none" can be expressed as nullable.

struct Storage {
    // internal, checked automatically
    owner: address
}

With new TVM 12 instructions, addresses are validated automatically during (de)serialization without extra gas — no more manual isInternal() checks.

So yes, it's technically a breaking change, but it removes a ton of noise.

A short migration guide, as well as technical details, available here.

✔ Rich bounced messages

Historically, a bounced message only returned the first 256 bits of the original body.

Now TVM 12 supports rich bounces — which lets you obtain the entire body instead.

createMessage({
    bounce: BounceMode.RichBounce,
    ...
})

In onBouncedMessage, you get access to the original body, exit code, gas used, and more.

Old true/false bounce flags still work for backward compatibility.

Rich bounces simplify complex message flows and inter-contract communication — one of the most painful aspects of TON until now.

✔ Cheap builder-to-slice and address composition

Previously, converting a builder to a slice (endCell + beginParse) consumed a lot of gas because cells are expensive. Now there's a new instruction — BTOS (builder-to-slice) — without intermediate cell creation.

- b.endCell().beginParse() is now cheap: auto-optimized to BTOS
- "builder-to-address" is the same BTOS; hacks around "return a builder with a valid address" can be removed
- cheaper StateInit hashing and address calculations

Just update to Tolk v1.2 + TVM 12, and you'll immediately save gas.

✔ Anonymous functions (lambdas)

Can be used in general-purpose frameworks, perfectly integrated with the type system:

fun customRead(reader: (slice) -> int) { ... }

customRead(fun(s) {
    return s.loadUint(32)
})

✔ Low-level compiler enhancements

Also included: better diagnostics with precise ranges, new peephole optimizations, tuple ↔ object conversions, and multiple small fixes. A lightweight borrow checker prevents undefined behavior on concurrent mutations.

As always, all additions are carefully described in a PR.

🌳 We've also started improving TVM itself — new assembler instructions are designed specifically to fit the Tolk type system and optimizer. I have always said: the language is just the beginning. Perfect developer experience requires improving every layer of TON's stack. The road may be sharp and curvy — but we're definitely heading in the right direction.

📚 New TON Documentation is Live

We rebuilt the entire documentation from scratch based on community feedback.

What's new:

▪️ AI Assistant - Ask questions in plain language and get instant answers from the entire documentation

▪️ Easier Navigation - Flat structure rewritten by blockchain engineers

▪️ Comprehensive Guides - New content for blockchain foundations, TON Connect, mytonctrl, Sandbox, Blueprint, smart contracts, and more

▪️ Dr. Durov's Whitepapers - Now in web format with AI summaries and cross-links

Built with feedback from Zengo, RSquad, TonTech, TON API team, TON Core, and shaped and delivered by TON Studio.

Try it: docs.ton.org 

👉 Read more