Jetton token development on TON: from idea to deployment

Failures During Issuance: Where a Jetton Token Breaks

Issuing a jetton token looks like a single transaction: contract deployed, response successful, asset exists.

Problems start later — balance does not appear in the wallet, transfers are debited from the sender and do not reach the recipient, and the team cannot issue additional volumes. We analyze the engineering causes behind this and where they are laid down at the design stage.

The most common point of failure is contract metadata. The name, symbol, and number of decimal places must be declared according to the accepted scheme, and the external description file must reside at a stable address and be served with the correct content type.

If even one condition is violated, indexers and client applications silently skip the asset: transactions exist on the network, the token is absent in the interface, and the user believes issuance failed.

The second class of failures is smart contract errors in transfer logic and balance accounting.

Incorrect handling of incoming messages, lack of refund on failed execution, wrong operation code, or insufficient gas for a service message leads to the debit occurring but the credit not.

Such a failure does not reproduce on a single test wallet — it manifests under a flow of operations when some execution paths are not covered by checks.

The third is issuance administration.

If the issuance right is assigned to a single key without a handover plan, and the rights to issue, freeze, and change metadata are not separated, the asset quickly loses manageability: changing parameters or minting additional volume becomes impossible, while obligations to holders remain. A reliable scheme is an admin contract with multisig confirmation and separate roles.

All four points are checked before publishing the contract to mainnet — on test scenarios with multiple wallets and by running failure paths. We explain how this is structured in practice.

What Managed Asset Issuance Gives: Effect in Metrics

Managed issuance begins with separation of rights: the master contract receives the admin role, which issues and burns the asset, while holders operate only through their wallets.

A separate role is for stopping operations, another for changing metadata: if the operator makes a mistake, excess permissions do not have to be revoked from the entire set.

In TON, this maps to the native Jetton standard, so wallets and platforms see the asset without modifications on their side.

We consolidate asset metadata into a single source: name, symbol, number of decimal places, and description reside in the contract, not in correspondence with a contractor.

Wallets and explorers pull them automatically — an edit in one place removes an entire class of discrepancies between interfaces.

What changes in metrics after contract rework. Issuing a batch ceases to be manual assembly: the admin calls one operation, and roles and checks do the rest.

The share of transfer failures falls from double-digit to fractions of a percent — the contract itself rejects sending to an inactive address and verifies decimals.

The volume of manual operations decreases by multiples: balance reconciliation, transferring tokens between wallets, and metadata edits move into the contract.

The class of failures due to insufficient funds for the fee and an incorrect recipient address also goes away — such transfers are filtered before sending, not after.

Issuance Options: When You Need Your Own Jetton Token

Jetton is not one contract but a bundle: a master with metadata and emission plus wallets created for each holder. The choice comes down to one thing: how much logic we put on top of the standard jetton interface and how much we leave unchanged.

Wallets, exchanges, and swap services read the standard interface — deviations from it break detection and balance accounting.

Contract options come down to three: a standard template without modifications, a template with extensions, or a custom architecture. The difference shows not at launch but when freeze, transfer fee, or wallet limits are needed — where standard behavior is no longer enough.

Contract extensibility is built before deploy: master code on TON is immutable after publication, so an upgrade is the publication of a new master and transfer of state.

Holder wallet addresses change, and this is accounted for in integrations in advance — otherwise, after the update, balance accounting in a service or exchange will diverge.

Work Stages: From Emission Scheme to Handover of the Setup

Development stages are arranged so that by launch the contract matches the emission scheme rather than being assembled piecemeal. Each step closes with a verifiable artifact: role scheme, check report, address of the published contract.

1. Requirements analysis. We fix the issuance volume, who receives tokens and by what rule, whether additional minting and burning are needed, and whether transfer freeze is required.
2. Designing the emission scheme and roles. We determine which wallets manage issuance and metadata updates; critical roles are covered by multisig.
3. Contract development per the Jetton standard. We implement transfers, issuance and burning, metadata, access restrictions, and correct error handling.
4. Testing on an isolated network. We run scenarios for issuance, transfer, burning, and access denial, including boundary amounts and repeated calls.
5. Contract publication. We deploy to mainnet, pin metadata, verify addresses, and check the first issuance.
6. Rights handover. We transfer ownership to the customer's wallets and describe the admin change procedure and actions on loss of access.
7. Handover of the setup and support. We provide documentation and schemes, monitor the first operations, and answer your team's questions.

What We Hand Over: Configurations, Schemes, Procedures

We hand over not only a working token but everything that allows it to be supported without us. The package is assembled so that your engineer can build the contracts from source, verify behavior with an explorer, and perform any operation with the asset without looking for us.

• Contract source code and build file with pinned dependencies — deployment is reproduced on your side step by step, without hidden edits.
• Role scheme with the ownership tree: who issues, who manages, who can pause operations, and which actions require multiple signatures.
• Access policies — emission limits, management transfer procedure, rules for adding and revoking admins.
• Asset documentation: metadata, decimals, procedure for checking the contract address and verifying source code on the explorer side.
• Test scenarios — tests for main and boundary paths: repeated issuance, attempt to operate without rights, management transfer, behavior on error.
• Support procedure — what the owner does independently, in what order to act during an incident, and via which channel to contact us.

Acceptance is based on facts: we deploy on testnet, run scenarios, verify behavior against the description, and only then record the package as yours. After that, you manage the asset yourself — support connects per procedure, not by default.

Case: How We Removed Load from the Master Contract

The project came to us with an already issued Jetton: the token lived and traded, but all administration went through one master contract and one owner wallet.

Batch issuance, distribution, address freezing — each operation was performed manually from this wallet, and the next transaction waited until the previous one was confirmed.

What Was the Bottleneck

One address — one sequence counter: two transactions sent in succession competed with each other, and the second one failed. Distribution to several hundred addresses stretched to 40–60 minutes of manual work, and about 7% of operations had to be restarted. The master contract key was in one place: its compromise meant loss of control over issuance.

What We Reworked and What Resulted

We left the master contract only for issuance and token parameters, and moved distribution logic into separate wallet contracts with predefined limits. Access was split into roles in TON: issuance — under multisig, routine transfers — under an operator key with a daily cap. Address lists are prepared as a batch, so operations no longer queue one after another.

• Batch issuance to several hundred addresses: 40–60 minutes manually → 2–3 minutes in one operation.
• Failed and restarted operations: about 7% → none during a month of observation.
• Keys with issuance right: one → three signatures, two of three required.

The eliminated failure class — conflict over one address and error on repeated sending. Rollback became one transaction, and the operation log remained in the contract — incidents can now be analyzed by history, not chat correspondence.

What to Do If the Asset Is Already Issued on Another Standard?

If the asset already circulates on another standard, its contract cannot be rewritten: code on the network is immutable. There remain three paths — asset wrapper, migration by registry snapshot, and exchange via a separate contract.

The choice hinges on one thing: whether the issuer has admin keys granting issuance and stop rights.

The wrapper works like this: the original asset is locked in a storage contract, and its one-to-one copy is issued on TON. Holders receive a compatible instrument without action on their side, and the original asset remains valid — rollback is possible.

The tradeoff is trust in the storage: without public reserve confirmation, the wrapper trades below the original.

Snapshot migration is used when the contract grants issuance and stop rights. At a fixed network state, a holder registry is assembled, the old contract is frozen, and the same volumes are issued in the new one — holder preservation is complete, and they need to do nothing.

The difficulty is registry accuracy: if the standard does not expose an address list, it is assembled from transfer events, and each missed entry becomes a dispute with the owner.

Standards compatibility is almost never complete: decimals, metadata model, and accounting method differ — balance inside the contract versus a separate registry. Discrepancies are cheaper to close at the new contract design stage than after issuance.

Without admin keys, a migration contract remains: the holder themselves deposits the old asset and receives the new one. There is no coercion, but the transition stretches, part of the holders remain in the old asset, and two prices appear for one asset.

In terms of owner rights, this is the weakest option: issuance management moves to the new contract, while obligations to the old holders remain.

Common Technical Questions Before Starting Work

Before deploying a Jetton token, the same engineering questions almost always surface: can the logic be changed later, where are the admin keys stored, is an audit needed, and what remains with the owner after handover. Their answers determine the architecture no less than the tokenomics itself.

Below are short breakdowns. These decisions fix whether the master contract will be upgradeable or immutable, who holds the issuance right, and what restrictions are hardcoded.

Where are admin keys stored?

Not in the repository, not in correspondence, and not on a work machine. The owner key is stored in a hardware wallet, and for issuance and parameter changes we use multisig with role separation: one signature does not give full control.

We describe key rotation and access recovery procedure in advance so that a change of responsible person does not block token management.

Is contract audit mandatory?

For a public launch — yes. We check issuance and burning, limits, fee math, owner rights, and reentrancy scenarios. Separately, we check that built-in "admin" functions cannot be called bypassing the declared rules. The outcome is a report with a list of findings and fixes before deploy.

What rights remain with the owner and what happens if a key is compromised?

After handover, nothing remains with us: issuance, pause, and parameter change rights are transferred to the customer's address. Then we deliberately limit the scope of rights — issuance limits, timelock on key parameter changes, a separate admin contract.

This reduces damage if the owner key is compromised: the attacker cannot issue arbitrary volume or withdraw liquidity in a single call.

Let's Discuss the Task and Come Back with an Estimate and Plan

Technical requirements for a Jetton token rarely fit in one line: roles for issuance and freezing, transfer rules, metadata, and integration with wallets and platforms are needed.

So that the work estimate is based on scope rather than intuition, we need input context — then fewer assumptions remain in the implementation plan, and disputed points are discussed before the first line of code.

What to send for review:

• token economics: total issuance, share distribution, mechanics of additional emission and burning;
• roles and rights: who issues, freezes, changes contract parameters, and how these rights are transferred;
• transfer scenarios: fees, amount and frequency limits, transaction tax, whitelists and blacklists;
• metadata requirements: name, symbol, number of decimal places, icon, and description for wallets;
• target platforms: exchanges, custody services, decentralized exchanges — their requirements for the contract;
• project constraints: timelines, need for external audit, integration with already operating services.

In response, we will return a contract scheme with responsibility areas, sequence of stages, scope of work, and an estimate with a list of assumptions it depends on.

If forks surface during the review — for example, fixed issuance versus managed issuance — we will show both options and their consequences for further development. Describe the task in free form and attach what already exists: we will come back with an estimate and plan.