Building on Telegram and TON: Lessons Learned

Telegram, Much More Than Just Chats

Telegram, aside from being a messaging app, is a platform for building interactive, miniature applications that have the potential to reach hundreds of millions of users instantly. With the introduction of Mini Apps, Telegram offers developers a powerful channel to deploy lightweight web applications directly within the messaging interface. These Mini Apps are embedded in a constrained WebView environment, which resembles an iframe but comes with specialised integrations and security features unique to Telegram.

Key features of Telegram Mini Apps:

• Injected Data and Security: user and session data are injected directly into the app’s runtime. This includes authentication details, chat context, and theme preferences, which are accessible through the initData and initDataUnsafe objects (user ID, username, theme params). They always validate the HMAC hash server-side using your bot token to prevent tampering. This enables seamless authentication without extra logins. Handling this data properly is essential for ensuring that apps behave securely and predictably across different clients (iOS, Android, Desktop, Web).
• Platform-specific APIs: Telegram also provides platform-specific APIs to deliver native-like interactions. For example, haptic feedback can be triggered during in-app events, improving user engagement and making Mini Apps feel like an integrated part of Telegram rather than a generic web page.
• Hybrid Flows: Designing a Telegram Mini App requires understanding the difference between full in-app experiences and micro-enhancements to chat flows. Full Mini Apps behave like standalone applications with their own navigation, state management, and persistent storage, while micro-enhancements leverage inline buttons, quick replies, or message updates to augment the chat experience without breaking the flow. Choosing the right approach affects not only the user experience but also the architecture of your TON smart contracts that power the app.

The TON Blockchain

The Open Network, commonly known as TON, is a highly scalable and fast blockchain platform that originated from the ambitious vision of Telegram’s founders, Pavel and Nikolai Durov. Their goal was to create a blockchain that could handle large-scale adoption while remaining user-friendly, integrating smoothly with everyday tools like messaging and financial services. Even though Telegram stepped back from direct involvement due to regulatory considerations, the project has flourished under the guidance of the TON Foundation and the open-source community.

TON is designed with three core principles in mind. First, it achieves high throughput and low latency, enabling potentially millions of transactions per second with near-instant confirmations. Second, it keeps transaction costs minimal, supporting micro-transactions and in-app payments without burdening users with high fees. Third, it prioritises ease of use, allowing blockchain interactions to feel intuitive, particularly when combined with platforms like Telegram.

At a technical level, TON introduces two main concepts that are distinct from traditional blockchains:

1. Wallets in TON are smart contracts themselves, which means that a single keypair can manage multiple wallets, each with configurable logic and transaction rules.
2. Smart contracts communicate asynchronously through a message-driven architecture, where contracts send and receive messages instead of directly invoking each other. This enables parallel execution, high scalability, and flexible contract logic but also demands careful design to prevent silent failures or lost transactions.

From its earliest conception, TON was designed to be:

• Scalable through perpetual sharding
• Fast with near-instant finality
• Light on fees, enabling microtransactions
• User-friendly, plugging natively into Telegram

One of the most pleasant surprises when building on TON was how much attention has been paid to developer experience. While the ecosystem is still evolving, the core tooling already feels more deliberate and safer than what many developers are used to on other chains.

The most impactful tool in our workflow was Blueprint, TON’s official development framework. Blueprint plays a role similar to Hardhat or Foundry in the EVM ecosystem, but with a stronger emphasis on safety and wallet abstraction. Instead of requiring developers to manually expose private keys during deployment, Blueprint emulates wallets locally and manages signing internally. This design choice eliminates an entire class of operational risks that commonly affect early-stage smart contract projects.

“It’s worth mentioning that blueprint deploy supports hardware wallets for signing, which Hardhat/foundry still don’t do.” — Justin Taylor, Senior Software Engineer @ Labrys

Blueprint also standardises the compilation pipeline for Tact, FunC and Tolk, allowing contracts written in different languages to coexist within the same project. During one of our development cycles, this was particularly important because parts of the system were implemented in Tact while legacy components remained in FunC. Blueprint handled this seamlessly, enabling us to focus on contract logic rather than build tooling.

From a testing standpoint, Blueprint’s local blockchain simulation made it possible to test message flows, gas behaviour, and edge cases without repeatedly pushing broken contracts to testnet. This shortened our feedback loop dramatically and helped surface silent failures early, before they reached production.

Complementing Blueprint was TON’s unusually accessible testnet experience. Instead of signing up for faucets, bridging assets, or waiting for approvals, developers can obtain test TON instantly through a Telegram faucet bot that dispenses tokens every hour. This integration with Telegram removes friction from the development process and encourages experimentation, which is critical when working with a message-driven execution model like TON’s.

Wallets, Addresses & Gas: Where Developers Make Critical Mistakes

“Most of the serious issues we encountered were not related to business logic, but rather to misunderstandings around wallets, addresses, and gas. TON’s design is powerful, but it assumes developers understand its underlying mechanics.”

One of the first pitfalls is TON’s address system. Every wallet and contract address exists in two representations: bounceable and non-bounceable:

• Bounceable addresses, typically starting with EQ, are designed to safely return funds if the destination contract is uninitialized or fails to accept the message.
• Non-bounceable addresses, usually starting with UQ, do not offer this protection. Sending TON to a non-bounceable address before the contract is deployed results in permanent loss of funds.

This distinction is easy to overlook and costly to ignore. We encountered a scenario where funds were sent to a non-bounceable address during a deployment race condition. The funds were unrecoverable. From that point on, we enforced bounceable address usage throughout the system and only converted to non-bounceable formats when absolutely necessary.

Wallet versions introduce another layer of complexity. TON wallets have evolved through several iterations, from V1 to the current V5 standard. Earlier versions support basic transfers and limited transaction batching, while newer versions introduce advanced logic, better message handling, and, in the case of V5, gasless transactions and account abstraction–like features. For Telegram Mini Apps, wallet version selection matters. V5 wallets significantly simplify UX by allowing transactions to be sponsored or abstracted away from the end user, which is often essential for consumer-facing applications.

Gas management is where TON differs most sharply from EVM-based chains:

“On TON, contracts must explicitly specify how much gas they intend to consume, and unused gas must be refunded manually. If a contract underestimates its gas usage, execution can fail silently, without reverting the entire transaction or returning a clear error message to the caller.”

This behavior surfaced repeatedly:

• From the user’s perspective → the app appeared frozen.
• From the blockchain’s perspective → the message simply failed to execute.

The solution was not better UI feedback, but better gas modelling and defensive contract design. We began over-provisioning gas for critical paths and explicitly refunding excess funds at the end of execution to prevent balance accumulation inside contracts.

Other Miscellaneous Things to Consider

One of the most difficult challenges was managing a hybrid smart contract codebase written in both Tact and FunC. Ensuring ABI compatibility between the two languages required careful message schema design and extensive testing.

The asynchronous nature of TON transactions also introduced some complexity. Because transactions are not atomic, multi-step operations had to be designed defensively. Each step needed to account for partial failure, delayed execution, or unexpected message ordering. This forced us to rethink common patterns that are trivial on synchronous chains.

Storage limits presented another constraint. Large collections, particularly those resembling NFT-like data structures, could not be stored naively onchain. We had to implement compact encoding strategies and off-chain references to keep contracts within acceptable size limits.

Finally, what we mentioned before: silent failures taught us humility. TON does not hold your hand. If your gas is miscalculated or your message mode is incorrect, the chain will not warn you. It will simply move on. Understanding this behaviour and designing systems that anticipate it is essential for building production-grade applications.