The Open Network (TON) is rapidly emerging as a powerful, scalable blockchain platform designed for high-performance decentralized applications (dApps) and smart contracts. As developers dive into building on TON, understanding its unique architecture and programming model becomes crucial. Unlike more traditional blockchains, TON introduces distinct paradigms in execution flow, message handling, and contract design that require careful attention.
This guide outlines essential considerations for developers working with TON’s Func language and the broader ecosystem. Whether you're new to TON or refining your development process, these insights will help you avoid common pitfalls and build robust, secure applications.
1. Be Aware of Name Collisions in Func
Func, TON’s primary smart contract language, allows for highly flexible naming conventions. Variables and functions can include special characters like var++, ~bits, or even foo-bar+baz. While this flexibility enhances expressiveness, it increases the risk of name collisions—especially when integrating third-party libraries or reusing code.
To mitigate this, always use a linter during development. A linter helps detect syntactic ambiguities and naming conflicts early, improving code reliability. Integrating linter plugins into your IDE ensures real-time feedback and consistent coding standards across your project.
👉 Discover tools that streamline smart contract development on high-performance blockchains.
2. Handle Exit Codes Carefully
The TON Virtual Machine (TVM) terminates execution with exit codes—typically 0 for success and 1 for failure. However, unlike some systems where exceptions provide detailed error messages, TON only returns numeric exit codes. Crucially, using throw(0) or throw(1) directly can unexpectedly halt execution because these values match normal termination codes.
Instead of relying on these low-level throws, design your error-handling logic around custom exit codes (e.g., throw(5) for invalid input). Documenting expected exit paths helps improve debugging and enhances contract transparency.
3. Respect Strict Typing and Data Integrity
Func is a strictly typed language, meaning every variable must hold data of the declared type. The compiler enforces this rigorously—there are no runtime warnings for type mismatches. If you attempt to read an unexpected value (e.g., treating a string as an integer), execution fails immediately with errors like code 5 (integer out of bounds).
Always validate data transformations and ensure return types match expectations. Since the compiler only evaluates initial states, runtime changes must be explicitly managed. This makes thorough testing and static analysis essential components of your workflow.
4. Understand Message Modes and Fees
Messages in TON operate under specific modes that dictate how they're processed, especially regarding fees and storage costs. Failing to account for message modes can lead to unexpected failures—such as a contract running out of TON due to unanticipated storage fees.
For example, sending a message without reserving enough value for gas may result in rejection during the action phase. Review message mode documentation to ensure your contracts handle value transfers correctly under all conditions.
5. Leverage Code Upgradability via Actor Model
TON fully implements the actor model, allowing smart contracts to change their own code at runtime. This is achieved through the SETCODE instruction or by modifying the TVM code registry within a transaction.
While this enables powerful features like contract upgrades and bug fixes without redeployment, it also introduces security risks. Ensure proper access controls are in place before allowing code modifications—otherwise, malicious actors could exploit upgradability to take over a contract.
6. Know the Transaction Phases: Compute, Action, and Bounce
TON transactions proceed through three distinct phases:
- Compute phase: Executes contract logic.
- Action phase: Sends messages, updates data, or modifies code.
- Bounce phase: Handles failed external messages.
Critically, exit codes from failed actions are not visible during the compute phase—they occur later. This differs from Ethereum-style blockchains where reverts happen immediately. Developers must anticipate failures in the action phase and design fallback mechanisms accordingly.
7. Contracts Are Autonomous and Asynchronous
In TON’s sharded architecture, contracts reside in different shards and are processed by separate validators. This means synchronous cross-contract calls are impossible—all communication happens asynchronously via messages.
As a result, your dApp logic must account for delayed responses and potential message reordering. Use acknowledgment patterns and timeouts to manage state transitions safely.
👉 Explore how modern blockchain platforms support asynchronous dApp interactions.
8. No Rollback Data—Only Exit Codes
Unlike blockchains that provide revert reasons (e.g., Ethereum’s "revert reason strings"), TON does not store detailed rollback information. Only the exit code indicates why a transaction failed.
Therefore, planning and documenting your contract’s exit code strategy is vital. Assign meaningful codes to different error scenarios (e.g., 10 for unauthorized access, 11 for insufficient balance) so users and frontends can interpret failures accurately.
9. Use Method IDs Correctly
Functions in Func annotated with method_id have a unique identifier used for external invocation. These IDs can be set explicitly (e.g., method_id(5)) or generated automatically by the compiler.
Two methods are predefined:
recv_internal: Handles internal blockchain messages.recv_external: Processes external inbound messages.
Ensure your entry points align with these conventions to maintain compatibility with wallets and dApp connectors like TON Connect.
10. Addresses May Be Empty or Uninitialized
TON addresses are deterministic and can be precomputed—even before deployment. However, an address may not contain any code or tokens initially. Sending a message with certain flags to such an address can cause it to become frozen or uninitialized, losing storage rights and funds.
Always verify contract state before interacting. Use tools like TON Explorer or SDKs to check if an address is active and properly deployed.
11. Recognize the Three Address Formats
TON supports three address representations:
- Raw format:
workchain:hash, used internally. - User-friendly format: Includes metadata like bounceability and workchain ID.
- Base64-encoded format: Most commonly used in wallets and UIs.
Understanding these formats prevents errors when parsing or generating addresses in your app.
12. Debugging Requires Proactive Tracking
Due to Func’s strict typing and lack of runtime visibility, tracking execution flow manually is essential. Unlike Solidity, where function visibility (public/private) offers some protection, Func relies on conditional logic (if statements) and explicit error handling.
Use logging patterns (via debug messages or event-like structures) and unit tests to simulate various execution paths.
13. Account for Gas When Sending Bounced Messages
When processing bounced messages (e.g., refunds), ensure you subtract the required gas fee from the returned amount. Failing to do so may result in underpayment or failed transactions.
Always calculate net returns based on actual consumed resources—not just the original transfer value.
14. Monitor Callbacks and Handle Failures Gracefully
Because TON is asynchronous, message delivery order isn't guaranteed. A failure notification might arrive before the original request is confirmed.
Implement idempotent operations and use request identifiers to track pending actions. This ensures your system remains consistent even if messages arrive out of sequence.
15. Check Bounce Flags on Internal Message Receipt
When receiving internal messages, always inspect the bounce flag. It determines whether a message should be returned to the sender if processing fails.
Improper handling can lead to lost funds or unintended behavior. Follow best practices for standard response message handling.
16. Implement Replay Protection for External Messages
External messages (e.g., from wallets) are vulnerable to replay attacks unless protected. Two common solutions exist:
- Seqno-based wallets: Track a sequence number (
seqno) to reject duplicate messages. - High-load wallets: Store process IDs with expiration timestamps for scalability under heavy traffic.
Choose the appropriate method based on your application’s throughput needs and security requirements.
Frequently Asked Questions (FAQ)
Q: Can I upgrade my TON smart contract after deployment?
A: Yes. TON supports runtime code upgrades using the SETCODE instruction, enabling non-disruptive updates as long as your contract logic allows it.
Q: Why did my transaction fail without a clear error message?
A: TON only returns numeric exit codes, not descriptive errors. Check common codes like 5 (integer overflow) or custom ones defined in your contract.
Q: How do I prevent replay attacks on my dApp?
A: Use sequence numbers (seqno) or timestamped request IDs in external message handlers to ensure each action is processed only once.
Q: Are TON addresses compatible across all wallets?
A: Yes, but ensure you're using the correct format—user-friendly addresses are standard in most modern wallets.
Q: Is asynchronous messaging hard to debug?
A: It requires a shift in mindset. Use message IDs, logs, and simulation tools to trace flows across time and shards.
Q: Where can I test my TON contracts safely?
A: Use the TON testnet along with local emulators like tonos-cli or sandbox environments provided by developer toolkits.
👉 Start building on a next-gen blockchain platform with robust developer support.