Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add concept and specifications pages about Jettons #949

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add concept and specifications pages about Jettons #949

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions docs/v3/concepts/dive-into-ton/ton-blockchain/jettons.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Jettons
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both files should be placed in the left side menu. Please add pages in menu and check rendered documentation locally with

npm run start


## What is a Jetton?

**Jetton** is a fungible token standard on **The Open Network (TON)** blockchain, similar to **ERC-20 tokens** on Ethereum. It allows developers to create and manage custom tokens for various purposes, which can be used within decentralized applications and services on the TON blockchain, such as stablecoins, game tokens, governance tokens, and more. Unlike the native token **Toncoin (TON)** used for system operations, Jettons are custom tokens designed for specific use cases within the TON ecosystem.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We aim to focus our readers on the user's perspective, positioning the user as the central actor:

This technology enables users to…

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This explanation should be refined into a minimalistic and clear version. Let's avoid including any information that is not immediately useful to readers in this moment.

Example of structure:

  1. Provide a short easy to read definition using basic language that relates to everyday life rather than Web3 terms. 1-2 lines.
  2. Give a real-life use cases as well as examples from the TON Ecosystem. 1-2 lines.
  3. Give an example of tokens from Ethereum.


## How Do Jettons Work?

Jettons are implemented using **a smart contract-based architecture** that ensures their creation, management, and interaction within the TON blockchain. The core components of the Jetton architecture include:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's useful to set a landing stage to smart contract terms. We need to educate users—who will check their balance in explorers—from the very beginning, not just developers.

For example:

When you use jettons, like USDT, jetton smart contracts manage the transfers, balance updates and enforce the rules. These contracts ensure that every operation is safe and fair without needing a classic bank-side to oversee it.


- [Jetton Master Contract](https://github.com/ton-blockchain/token-contract/blob/main/ft/jetton-minter.fc)
- [Jetton Wallet Contract](https://github.com/ton-blockchain/token-contract/blob/main/ft/jetton-wallet.fc)
- [Jetton Minter Contract (optional)](https://github.com/ton-blockchain/token-contract/blob/main/ft/jetton-minter.fc)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is incorrect; in this context, the minter and master are the same entity.


These contracts create, manage, and transfer custom tokens (Jettons) within the TON ecosystem.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please provide a more detailed explanation to readers about the different types of Jetton Wallet contracts.

For clarity, let's refer to the Tonviewer explorer types available in the UI. The Tonviewer jetton wallet types are defined according to this parser.

  • 1 x jetton_master type
  • 4 x jetton_wallet contract types

Which defined as:

  • jetton_master corresponds to the standard TEP-64.

with any combination the jetton wallet contract:

1.jetton_wallet - standard contract according the TEP-74 - example: jUSDC
2. jetton_wallet_v1 - standard extension, example: CATI
3. jetton_wallet_v2 - standard extension, example: DOGS
4. jetton_wallet_governed - standard extension, example: USDT

These types offer different features and incur varying gas costs for transfers.

Every combination of [jetton_master + jetton_wallet_x] contracts may be minted according to the Mintless jetton standard.

Take in account this hint and do the following:

  1. Explain the basic concepts of jettons as additional contracts for users. (Remember, users ultimately operate with Wallet Contract addresses.) Use a recognizable example, such as the USDT jetton, to illustrate these concepts.
  2. Describe the differences among jetton types and provide examples to clarify each concept. Focus on the features they offer rather than on technical details.
  3. Explain the mintless jetton feature and how it works from the user's perspective.
  4. Combine theoretical explanations with practical examples and addresses.
  5. Avoid overwhelming the explanation with too many links or technical terms.


### 1. Jetton Master Contract

At the core of each jetton is the **Jetton Master Contract**. This contract serves as the blueprint and defines the rules for a specific type of jetton. The Jetton Master Contract holds key information such as:

- **[Metadata](https://github.com/ton-blockchain/TEPs/blob/master/text/0064-token-data-standard.md)**: The token’s name, symbol, decimals, and other standard details.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you add the example with real token here?

- **Minting Rules**: The logic to create (mint) new tokens and control the total supply.
- **Circulating Supply**: The amount of jettons in circulation, tracked by the master contract.

This contract is deployed once per jetton type and serves as the anchor for the specific token. It controls how the token [behaves](https://github.com/ton-blockchain/TEPs/blob/master/text/0074-jettons-standard.md) and ensures consistency in its use across the TON network.

### 2. Jetton Wallet Contract

Once a jetton has been created, users need a **Jetton Wallet Contract** to **store, send, and receive tokens**.

- **Wallets for Jetton Holders**: Each user who holds jettons will have a separate Jetton Wallet Contract that tracks their balance for that particular jetton type.
- **Sending and Receiving Jettons**: The Jetton Wallet contract allows users to send and receive tokens by transferring them to other wallets.
- **Burning Jettons**: In some cases, users may burn (destroy) their tokens via the wallet contract, reducing the total circulating supply.

Transactions between Jetton wallets require a certain amount of Toncoin (TON) to cover **gas fees** for the network to process the transaction.

- **Wallet Creation on Transfer**: If the recipient does not already have a wallet for the specific jetton, a new wallet is deployed automatically when they receive the tokens, as long as the sender has enough TON to cover the gas fees.

:::note Jetton Wallets should not be confused with general blockchain wallets for managing Toncoin or other assets. :::

### 3. Jetton Minter Contract (Optional)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minting operation is defined in the minter contract. Minter contract is not optional.


Sometimes, jettons may need to be minted (created) after the initial deployment. This is where the **Jetton Minter Contract** comes into play.

- **Minting New Tokens**: The Minter Contract allows the creation of new jettons and increases the total supply. However, this contract is optional — if minting is not permitted, the jetton becomes non-mintable, and the total supply is fixed.
- **Non-Mintable**: If a jetton does not have a Minter contract, the logic is simplified—once the initial supply is created, no additional tokens can be minted. To mint jettons for the first time, refer to the [Mint your first jetton](/v3/guidelines/dapps/tutorials/mint-your-first-token) page.

## See Also

- [Jetton Processing](/v3/guidelines/dapps/asset-processing/jettons)
- [Sharding TON Smart Contracts](https://blog.ton.org/how-to-shard-your-ton-smart-contract-and-why-studying-the-anatomy-of-tons-jettons)
Loading