Обработка жетонов
Эта страница переведена сообществом на русский язык, но нуждается в улучшениях. Если вы хотите принять участие в переводе свяжитесь с @alexgton.
Лучшие практики обработки жетонов
Жетоны - это токены в блокчейне TON - их можно рассматривать аналогично токенам ERC-20 в сети Ethereum.
Транзакции в TON становятся необратимыми уже после одного подтверждения. Для лучшего пользовательского опыта (UX/UI) рекомендуется избегать дополнительного ожидания.
Вывод средств
Highload Wallet v3 - это новейшее решение блокчейна TON, которое является золотым стандартом для вывода жетонов. Он позволяет вам воспользоваться преимуществами пакетной отправки средств.
Пакетное снятие средств - означает, что несколько переводов отправляются пакетами, что обеспечивает быстрый и дешевый вывод средств.
Зачисления
Рекомендуется настроить несколько кошельков пополнения MEMO для улучшения производительности.
Пополнения с Memo - позволяет вам иметь один кошелек пополнения, и пользователи добавляют Memo, чтобы быть идентифицированными вашей системой. Это означает, что вам не нужно сканировать весь блокчейн, но это немного менее удобно для пользователей.
Пополнения без Memo - Это решение также существует, но его интеграция более сложна. Однако мы можем помочь вам с этим, если вы предпочтете выбрать этот путь. Пожалуйста, уведомите нас до того, как решите реализовать этот подход.
Дополнительная информация
Ожидается, что каждый сервис в Экосистеме установит forward_ton_amount
равный 0,000000001 TON (1 нанотон), когда будет производиться вывод жетонов, чтобы отправить Jetton Notify при успешном переводе, иначе перевод не будет соответствовать стандарту и не сможет быть обработан другими CEX и сервисами.
-
Пожалуйста, найдите пример JS lib - tonweb - это официальная JS библиотека от TON Foundation.
-
Если Вы хотите использовать Java, Вы можете заглянуть в ton4j.
-
Для Go следует рассмотреть tonutils-go. На данный момент мы рекомендуем JS lib.
Оглавление
В следующих документах представлены подробные сведения об архитектуре жетонов в целом, а также основные концепции TON, которые могут отличаться от EVM-подобных и других блокчейнов. Это крайне важно, чтобы получить хорошее понимание TON, и оно значительно поможет вам.
В этом документе описано следующее по порядку:
- Общие сведения
- Архитектура
- Контракт Jetton Master (Выпуск токенов)
- Контракт Jetton Wallet (кошелек пользователя)
- Макеты сообщений
- Обработка жетонов (off-chain)
- Обработка жетонов (on-chain)
- Обработка кошелька
- Лучшие практики
Общие сведения
Транзакции TON необратимы после одного подтверждения. Для ясного понимания читатель должен быть знаком с основными принципами обработки активов, описанными в этом разделе нашей документации. В частности, важно знать контракты, кошельки, сообщения и процесс развертывания.
Для лучшего пользовательского опыта рекомендуется избегать ожидания дополнительных блоков после того, как транзакции будут завершены в блокчейне TON. Подробнее можно прочитать в Catchain.pdf.
Быстрый переход к основному описанию обработки Jetton:
Централизованная обработка
On-Chain обработка
Блокчейн TON и лежащая в его основе экосистема классифицируют взаимозаменяемые токены (FT) как жетоны. Поскольку в блокчейне применяется шардинг, наша реализация взаимозаменяемых токенов уникальна по сравнению с аналогичными моделями блокчейнов.
В этом анализе мы более подробно рассмотрим формальные стандарты, описывающи поведение и метаданные жетонов. Менее формальный обзор архитектуры жетонов, ориентированный на шардинг, можно найти в нашем блоге "anatomy of jettons".
Мы также предоставили конкретные подробности, обсуждая наш процессор платежей TON с открытым исходным кодом (bicycle), который позволяет пользователям вносить и выводить как Toncoin, так и жетоны, используя отдельный адрес депозита без использования текстового п оля memo.
Архитектура Jetton
Стандартизированные токены в TON реализованы с использованием набора смарт-контрактов, включая:
- Смарт-контракт Jetton master
- Смарт-контракт Jetton wallet


Смарт-контракт Jetton master
Смарт-контракт jetton master хранит общую информацию о жетоне (включая общее предложение, ссылку на метаданные или сами метаданные).
Jetton с symbol
==TON
или те, которые содержат системные уведомления, такие как: ERROR, SYSTEM и другие. Обязательно проверьте, отображаются ли жетоны в вашем интерфейсе таким образом, чтобы их нельзя было смешивать с переводами TON, системными уведомлениями и т. д. Иногда даже symbol
, name
и image
созданы таким образом, чтобы выглядеть почти одинаково с оригиналом с целью обмана пользователей.
Чтобы исключить возможность мошенничества для пользователей TON, пожалуйста, найдите оригинальный адрес жетона (Смарт-контракт Jetton master) для определенных типов жетонов или перейдите на официальный канал или веб-сайт проекта в социальных сетях для получения правильной информации. Проверяйте активы, чтобы исключить возможность мошенничества с помощью списка Tonkeeper ton-assets.
Получение данных о жетоне
Для извлечения более конкретных данных жетона используйте get метод контракта get_jetton_data()
.
Этот метод возвращает следующие данные:
Имя | Тип | Описание |
---|---|---|
total_supply | int | общее количество выпущенных жетонов, измеренное в неделимых единицах. |
mintable | int | информация о возможности чеканки новых жетонов. Это значение равно -1 (можно чеканить) или 0 (нельзя чеканить). |
admin_address | slice | |
jetton_content | cell | данные в соответствии с TEP-64, см. страницу анализа метаданных жетона для получения дополнительной информации. |
jetton_wallet_code | cell |
Также можно использовать метод /jetton/masters
из Toncenter API для получения уже декодированных данных и метаданных жетона. Мы также разработали методы для (js) tonweb и (js) ton-core/ton, (go) tongo и (go) tonutils-go, (python) pytonlib и многих других SDK.
Пример использования Tonweb для запуска метода get и получения url для метаданных off-chain:
import TonWeb from "tonweb";
const tonweb = new TonWeb();
const jettonMinter = new TonWeb.token.jetton.JettonMinter(tonweb.provider, {address: "<JETTON_MASTER_ADDRESS>"});
const data = await jettonMinter.getJettonData();
console.log('Total supply:', data.totalSupply.toString());
console.log('URI to off-chain metadata:', data.jettonContentUri);
Jetton minter
Как упоминалось ранее, жетоны могут быть либо выпускаемыми mintable
, либо не выпускаемыми non-mintable
.
Если они не выпускаемые, логика становится простой — нет способа чеканить дополнительные токены. Чтобы чеканить жетоны в первый раз, обратитесь к странице выпуск своего первого жетона.
Если жетоны выпускаемые, в minter contract есть специальная функция для чеканки дополнительных жетонов. Эту функцию можно вызвать, отправив внутреннее сообщение со специальным opcode с адреса администратора.
Если администратор жетона хочет ограничить их выпуск, есть три способа сделать это:
- Если вы не можете или не хотит е обновлять код контракта, администратор должен передать право собственности с текущего администратора на нулевой адрес. Это оставит контракт без действующего администратора, таким образом, не давая никому возможности чеканить жетоны. Однако это также предотвратит любые изменения метаданных жетона.
- Если у вас есть доступ к исходному коду и вы можете его изменить, вы можете создать метод в контракте, который устанавливает флаг для прерывания любого процесса чеканки после его вызова, и добавит инструкцию для проверки этого флага в функции выпуска.
- Если вы можете обновлять код контракта, вы можете добавить ограничения, обновив код уже развернутого контракта.
Смарт-контракт Jetton wallet
Контракты Jetton wallet
используются для отправки, получения и сжигания жетонов. Каждый контракт jetton wallet хранит информацию о балансе кошелька для определенных пользователей.
В некоторых случаях jetton wallet используются отдельно для каждого владельца жетона для каждого его типа.
Jetton wallets
не следует путать с кошельками, предназначенными для взаимодействия с блокчейном и хранящих только актива Toncoin (например, кошельки v3R2, highload кошельки и т.д.), которые отвечают за поддержку и управление только определенным типом жетонов.
Развертывание Jetton Wallet
При передаче жетонов
между кошельками транзакции (сообщения) требуют определенного количества TON в качестве оплаты сетевых комиссий за газ и выполнения действий согласно коду контракта Jetton wallet.
Это означает, что получателю не нужно развертывать Jetton wallet перед получением жетонов. Jetton wallet получателя будет развернут автоматически, если отправитель имеет достаточно TON в кошельке для оплаты необходимых комиссий за газ.
Получение адреса Jetton wallet для конкретного пользователя
Для получения jetton wallet
address
с помощью owner address
(адрес кошелька TON), Jetton master contract
предоставляет get метод get_wallet_address(slice owner_address)
.
- API
- js
Запустите
get_wallet_address(slice owner_address)
через метод/runGetMethod
из Toncenter API. В реальных случаях (не в тестовых) важно всегда проверять, что кошелек действительно принадлежит нужному Jetton Master. Подроднее смотрите пример кода.
import TonWeb from 'tonweb';
const tonweb = new TonWeb();
const jettonMinter = new TonWeb.token.jetton.JettonMinter(tonweb.provider, { address: '<JETTON_MASTER_ADDRESS>' });
const jettonWalletAddress = await jettonMinter.getJettonWalletAddress(new TonWeb.utils.Address('<OWNER_WALLET_ADDRESS>'));
// It is important to always check that wallet indeed is attributed to desired Jetton Master:
const jettonWallet = new TonWeb.token.jetton.JettonWallet(tonweb.provider, {
address: jettonWalletAddress
});
const jettonData = await jettonWallet.getData();
if (jettonData.jettonMinterAddress.toString(false) !== jettonMinter.address.toString(false)) {
throw new Error('jetton minter address from jetton wallet doesnt match config');
}
console.log('Jetton wallet address:', jettonWalletAddress.toString(true, true, true));
Дополнительные примеры можно найти в TON Cookbook.
Получение данных для определенного Jetton wallet
Чтобы получить баланс кошелька, данные об владельце и другую информацию, связанную с конкретным контрактом jetton wallet, используйте get метод get_wallet_data()
в контракте jetton wallet.
Этот метод возвращает следующие данные:
Имя | Тип |
---|---|
balance | int |
owner | slice |
jetton | slice |
jetton_wallet_code | cell |
- API
- js
Используйте get метод
/jetton/wallets
из API Toncenter для получения ранее декодированных данных jetton wallet.
import TonWeb from "tonweb";
const tonweb = new TonWeb();
const walletAddress = "EQBYc3DSi36qur7-DLDYd-AmRRb4-zk6VkzX0etv5Pa-Bq4Y";
const jettonWallet = new TonWeb.token.jetton.JettonWallet(tonweb.provider,{address: walletAddress});
const data = await jettonWallet.getData();
console.log('Jetton balance:', data.balance.toString());
console.log('Jetton owner address:', data.ownerAddress.toString(true, true, true));
// It is important to always check that Jetton Master indeed recognize wallet
const jettonMinter = new TonWeb.token.jetton.JettonMinter(tonweb.provider, {address: data.jettonMinterAddress.toString(false)});
const expectedJettonWalletAddress = await jettonMinter.getJettonWalletAddress(data.ownerAddress.toString(false));
if (expectedJettonWalletAddress.toString(false) !== new TonWeb.utils.Address(walletAddress).toString(false)) {
throw new Error('jetton minter does not recognize the wallet');
}
console.log('Jetton master address:', data.jettonMinterAddress.toString(true, true, true));
Макеты сообщений
Подробнее о сообщениях читайте здесь.
Обмен между Jetton wallet и кошельками TON происходит через следующую последовательность сообщений:


Сообщение 0
Sender -> sender's jetton wallet
. Сообщение о передаче содержит следующие данные:
Имя | Тип | Описание |
---|---|---|
query_id | uint64 | Позволяет приложениям связывать три типа сообщений Transfer , Transfer notification и Excesses друг с другом. Для корректного выполнения этого процесса рекомендуется всегда использовать уникальный query id запроса. |
amount | coins | Общая сумма ton coin , которая будет отправлена с сообщением. |
destination | address | Адрес нового владельца жетона |
response_destination | address | Адрес кошелька, используемый для возврата оставшихся ton coin с сообщением об излишках. |
custom_payload | maybe cell | Размер всегда >= 1 бит. Пользовательские данные (которые используются как отправителем, так и получателем jetton wallet для внутренней логики). |
forward_ton_amount | coins | Должно быть > 0, если вы хотите отправить transfer notification с forward payload . Это часть значения amount и должно быть меньше чем amount |
forward_payload | maybe cell | Размер всегда >= 1 бит. Если первые 32 бита = 0x0, это простое сообщение. |
Сообщение 2'
payee's jetton wallet -> payee
. Сообщение с уведомлением о переводе. Отправляется только если forward_ton_amount
не равен нулю. Содержит следующие данные:
Имя | Тип |
---|---|
query_id | uint64 |
amount | coins |
sender | address |
forward_payload | cell |
З десь адрес sender
- это адрес Jetton wallet
Алисы.
Сообщение 2''
payee's jetton wallet -> Sender
. Тело сообщения. Отправляется только в том случае, если после уплаты комиссий остались какие-либо монеты ton. Содержит следующие данные:
Имя | Тип |
---|---|
query_id | uint64 |
Подробное описание полей контракта jetton wallet можно найти в интерфейсе описании стандарта жетона
TEP-74.