TON SDK integration: where the frontend breaks and what to do about it
Integrating the TON SDK into a user interface seems simple until the first failure: the wallet is connected, the address is received, the transaction goes out.
The problems start on the way back — the user closes the tab between signing and confirmation, and the interface keeps waiting for a wallet event that will never arrive.
The most frequent complaint after launch is "the transfer went through, but the status is stuck." The reason is that the frontend relies on wallet events rather than on network state: a minimized app, a network switch or a device change leaves the operation pending forever.
Polling for confirmations from an independent source eliminates this entire class of stuck transactions.
Then comes status divergence. The local cache, the database record and the actual account state update at different rates, and within a few minutes the picture drifts apart — the balance is correct, the history is empty.
Every such case is handled by a manual reconciliation against the log, which means engineer and operator time.
A separate group is wallet integration errors on entry: a return without a session, a mismatched signature, a different order of events across wallets.
If these branches are not covered, the user repeats the transfer and pays the fee twice — now at their own expense, and that does not restore trust in the product.
Next, we break down how this is closed: a single source of state instead of a set of local copies, deferred confirmation checks and idempotent operations on the server side, so that a repeated request does not create a second transaction.
What a predictable build delivers: speed, failures, support
A predictable build is a single path of change from the developer's branch to the user, with no manual edits in the console.
Contract addresses, network parameters and the list of supported wallets are injected from the environment, so shipping an interface fix takes minutes and does not depend on who is on call today.
The main source of incidents in TON integration is desynchronization between the network state and what the user sees.
The wallet connection session expired, the recipient address did not match, the message was assembled with the wrong structure — and the transaction goes to the wrong place or does not go out at all.
This class of failure is not caught by eye on a staging environment, but it is reliably filtered out by a build that verifies data before sending.
Testnet checks run the message structure, the signature, the address binding and the timeouts on every change. The reliability of operations rests not on the developer's attentiveness, but on the fact that there are simply no manual steps in the process.
Downtime is costly not in engineering hours: while the interface is unavailable, people's operations hang mid-scenario, and manual triage of each case stretches over days.
With a reproducible build, rolling back to the previous version is a single action, and the downtime window is measured in minutes.
Frontend support stops depending on one person who "remembers everything": the diagrams, environment configurations and release regulations live in the repository, a local run mirrors the production one, and a new engineer gets onboarded within a day.
Integration formats: side module, embedded, hybrid
The connection format is chosen along two axes: where the keys are stored and who is responsible for message schema compatibility across updates.
All options talk to the same network and use a common wallet connection standard, so moving between them is a question of code ownership and release cycle, not of rewriting the logic.
| Option | When it fits | Limitations |
|---|---|---|
| Side module | Fast launch, a storefront, one-off payment scenarios, someone else's frontend | Limited access to page state, third-party update policy, conflicts with styles and routing |
| Embedded into the product | Your own product with frequent releases, complex transaction logic, need for control over cell serialization | Requires its own release cycle and ongoing maintenance of the codebase |
| External signing service | Keys must not reach the browser: corporate perimeter, custodial scenario | Dependency on provider availability, an extra network round trip, a limited set of supported message types |
| Hybrid scheme | A mature product: fast scenarios go to the module, critical operations to the embedded integration | Two security surfaces, harder to test and reproduce errors |
Limitations almost always surface at the seams: a change in the message schema version breaks transaction parsing, and a signing provider update changes the response format.
That is why we freeze the cell serialization contract and cover it with checks before the option goes into the product's main branch.
Stages of work: from audit to handover to the team
We start not with code but with an inventory: we look at how the application talks to the network, who signs transactions, where the wallet state is stored and how send errors are handled.
This sets the boundaries of the implementation stages — from there the work proceeds according to the actual state of the project, not according to assumptions.
- Code audit. We break down the current integration: connection via TonConnect, subscription to balance changes, parsing of network responses. The output is a list of bottlenecks with risk assessment and priorities.
- Data flow diagram. We fix the path from a user action to a confirmed transaction: where the message is formed, where it is assembled into a Cell, what waits for a network response and what waits for a server-side status.
- Designing the integration layer. We describe wrappers over the TON SDK, unified types and a retry strategy, and delineate responsibility between frontend and server.
- Build. We implement wallet connection, operation sending and state reading, keeping the interface consistent when it desynchronizes from the network.
- Operation testing. We run scenarios on the testnet: rejected signature, repeated login, account switch, connection drop, stuck transaction. We verify the idempotency of retries.
- Project handover. We hand over configuration documentation, diagrams, deployment instructions and access, hold a call with the team and stay in touch during the support period.
Each stage ends with an artifact — a diagram, a document or a working scenario — so stepping back one stage is possible without rebuilding the entire project.
Diagrams, configuration and update regulations
TON integration does not end the moment the wallet connects to the interface and the transaction goes out to the network. After that the project lives without us: libraries get updated, contract addresses change, new engineers come in.
That is why we hand over not only code but also a package of artifacts that the client's team uses to run the project independently.
- State diagram: initialization, wallet connection, confirmation, user rejection, connection drop and retry — indicating what the user sees in each state.
- Environment configuration: testnet and mainnet, contract addresses, node parameters, keys and variables moved out of the code, so changing the network does not require logic edits.
- Cell model breakdown: how data is packed into cells, where the boundary between frontend and contract lies, which fields are read for display.
- Update regulations: who tracks new SDK and TonConnect branches, in what order compatibility is checked and how a rollback to the previous working build is performed.
- Access rules: roles, who is granted access to keys and dashboards, the rotation procedure, the operations log and what happens when an engineer leaves.
- Project documentation: architecture diagram, module descriptions, the list of external dependencies and extension points.
- Pre-release checklist: connection, signature, rejection, insufficient funds, network error.
Such a package removes dependence on the contractor: library updates and onboarding a new developer follow the described steps rather than individual people's memory.
Case study: how we eliminated stuck confirmations for users
What it was like
The project was payment acceptance in a wallet on TON. The user sent a transfer, the interface showed "processing," and for some people that state never changed: the confirmation arrived, but the status in the dashboard stayed the same.
Support opened a manual investigation — up to 27% of operations in a week required reconciliation against the node log.
The cause was found while analyzing the logs. The client polled the network on a timer and lost events when the wallet reconnected: if the user closed the tab or switched between networks, the chain of updates had to be reassembled from scratch.
The status handler was also not idempotent — a repeated event pushed the state backwards, and the operation "hung" in the accounting.
What it became
We rewrote the confirmation layer: subscription to state changes instead of timer polling, an idempotency key based on the operation hash, a retry queue with increasing delay.
Statuses were separated explicitly — sent, included in a block, confirmed, rejected — instead of a single "processing." On startup the application rebuilds state from the log and catches up on missed events.
The share of operations requiring manual reconciliation dropped from 27% to 0.4%: only disputed cases where the address was entered incorrectly remained. Time to an honest status shrank from tens of minutes to a few seconds.
A connection drop, a tab restart or node unavailability no longer breaks the chain — after recovery the service reaches the current state on its own and loses not a single operation.
How the Cell model differs from the usual requests to a server
In TON there is no familiar "request — response" pair: contract state does not live in a database on a server but in the network itself. The Cell model makes a cell the minimal data carrier — a stretch of a bit string with references to child cells. Any structure is assembled from such cells and addressed by the hash of its content.
The difference from an API shows up at the level of the call. An ordinary method is a name and parameters that the server maps to table columns. On the network, a call is a message: the contract receives it as a cell and decides for itself what to do with it.
There are no fields or columns in the network's data structure — there are bits that the contract code interprets.
Message serialization works the same way: instead of a JSON schema there is a bit order. The first bits hold the opcode, then come the arguments, and heavy data goes into separate cells by reference.
A shift by one bit changes the opcode, and the transaction fails before the logic even runs. That is why the SDK here is not a wrapper over a network request but an assembler and parser of cells.
Working with state is different too. State is not read with a separate request: it is extracted from the data cell — by running a method locally or from the body of the response transaction.
Its relevance is as of the moment of the run: between reading and writing the state may change. Writing happens only via a message, and confirmation arrives asynchronously when the transaction gets into a block.
Limitations and technical doubts before the start
Connecting a wallet looks like a single button, but it is an asynchronous process with intermediate states: a transaction in TON does not return a synchronous result — the client sends a message, receives a hash and waits for confirmation from network events.
An interface that does not distinguish "sent" from "executed" shows false success and multiplies support requests. We design the waiting, re-polling and clear-rejection screens before development begins.
The second group of doubts is the data format: state is stored as a tree of cells with a limit on the size of a single cell, so long lists and nested structures are cut into parts and reassembled according to serialization rules.
A markup error does not surface immediately but on a specific read scenario, so we cover assembly and parsing with checks. Signing happens on the user's device: the private key never leaves the wallet, and the server side works only with public data and operation hashes.
Do we need our own node?
For most tasks, public access points with request balancing are enough. Your own is justified when you need predictable response latency and independence from third-party limits.
What if the user rejected the signature or closed the wallet?
The operation does not go out to the network, and the interface state returns to the initial one. Retrying is safe: duplicates are filtered out by the operation identifier, so a double tap does not create a second transaction.
What are the compatibility and migration risks?
The set of supported methods differs across wallets, so we build the entry point with a fallback scenario and test on several wallets before release. We plan contract updates so that access to already recorded data is preserved.
Let's discuss the task: what we need from you and what we do
You do not need a finished technical document for an estimate and a work plan — describing the task in words is enough: what the product is, which assets and networks are involved, who the user is and what is already implemented in the code.
If the frontend is partly written, send the repository and the current state of the wallet connection — that is enough to see the integration's bottlenecks.
What we need from you:
- the product's purpose and the scenarios in which the user signs a transaction;
- the assets involved and whether withdrawal to external networks is needed;
- the current frontend code and the point to which the integration has been taken.
What we take on:
- auditing the current integration and choosing the wallet connection scheme;
- work with the Cell model: assembling, parsing and validating messages;
- setting up TonConnect and handling the return from the wallet and signature rejections;
- automated tests for key scenarios and a testnet run;
- integration documentation and handover to your team;
- support during launch and incident triage.
We fix the scope of responsibility before the project starts: product decisions remain on your side, while we cover the technical part and the predictability of the launch.
Describe the task in free form — we will come back with an estimate, a work plan and the questions that were missing for precision.