Архитектура Trustless моста (TVM ↔ TVM)

Документация по архитектуре Trustless кроссчейн моста для передачи токенов между TVM сетями.

Принципиальная схема

Глоссарий

Native и Alien токены

Термин	Описание
Native токен	Токен, который изначально был создан и существует в данной сети. При трансфере в другую сеть — блокируется (lock) в Proxy-контракте.
Alien токен	Обёрнутое (wrapped) представление токена из другой сети. Создаётся (mint) в сети назначения при входящем трансфере. При обратном трансфере — сжигается (burn).

Пример:

• USDT в сети TON — это Native токен для TON
• При трансфере USDT из TON в Tycho:
  • В TON: USDT блокируется в NativeProxy (остаётся Native)
  • В Tycho: минтится wUSDT (Alien токен)

Структура трансфера

Важно понимать

Каждый кросс-чейн трансфер состоит из двух частей:

1. Часть в сети отправления — блокировка/сжигание токенов и эмиссия события
2. Часть в сети назначения — верификация и минтинг/разблокировка токенов

Event-контракт

Для каждого трансфера в сети назначения деплоится отдельный Event-контракт. Он выполняет две ключевые функции:

1. Защита от double-spending — контракт с уникальным адресом (derived от данных транзакции) гарантирует, что одна транзакция может быть обработана только один раз
2. Участие в логике Merge — Event-контракт определяет, какой токен получит пользователь (derive или canon) на основе настроек MergePool

Компоненты системы

On-chain компоненты (Смарт-контракты)

LiteClient

Контракт легкого клиента, хранящий информацию о ключевых блоках другой сети.

Хранимые данные:

• current_seq_no — номер последовательности текущего ключевого блока
• current_epoch_since/until — временные метки начала/окончания эпохи валидаторов
• current_cutoff_weight — минимальный вес подписей (2/3 + 1 от общего веса валидаторов)
• current_validators_set — набор валидаторов с публичными ключами и весами

Операции:

• new_key_block — обработка нового ключевого блока, верификация подписей, обновление набора валидаторов
• check_block — проверка подписей блока против текущего набора валидаторов

TransactionChecker

Контракт для верификации транзакций из другой сети через Merkle proofs.

Операции:

• check_transaction — проверка транзакции:
  1. Извлекает Merkle proof транзакции и блока
  2. Проверяет, что транзакция существует в блоке
  3. Отправляет запрос в LiteClient для верификации подписей блока
  4. При успешной верификации отправляет response::transaction_checked

ProxyMultiVaultNative (NativeProxy)

Proxy-контракт для работы с native токенами (jettons).

Основные функции:

• Принимает native токены (lock) при исходящих трансферах
• Отправляет native токены (unlock) при входящих трансферах
• Эмитит события для трансферов в другие сети
• Управляет комиссиями и дневными лимитами

Ключевые методы:

• transferNotification — callback при получении jetton-токенов, инициирует исходящий трансфер
• onTvmEventConfirmedExtended — обработка подтвержденного события (завершение входящего трансфера)

ProxyMultiVaultAlien (AlienProxy)

Proxy-контракт для работы с alien токенами.

Основные функции:

• Минтит alien токены при входящих трансферах
• Обрабатывает callback после сжигания alien токенов и инициирует исходящий трансфер
• Управляет деплоем новых alien токенов
• Работает с MergePool/MergeRouter для объединения токенов

Ключевые методы:

• onTvmEventConfirmedExtended — минтинг alien токенов при входящем трансфере
• onAcceptTokensBurn — callback от jetton-контракта после сжигания токенов
• deployTvmAlienToken — деплой нового alien токена

EventConfiguration (TvmTvmEventConfiguration)

Контракт конфигурации событий, управляющий деплоем event-контрактов.

Хранимые данные:

• Адрес TransactionChecker
• Код event-контракта
• Адрес proxy-контракта
• Параметры конфигурации

Ключевые методы:

• deployEvent — деплой нового event-контракта для обработки входящего трансфера

MultiVaultTvmTvmEvent (Alien / Native)

Event-контракты для обработки конкретных трансферов.

Жизненный цикл (enum Status):

Код	Статус	Описание
0	Initializing	Начальное состояние
1	Pending	Ожидание верификации через TransactionChecker
2	Confirmed	Трансфер подтверждён, proxy вызван, токены доставлены
3	Rejected	Трансфер отклонён
4	Cancelled	Трансфер отменён пользователем
5	LimitReached	Превышен дневной лимит, ожидает одобрения
6	LiquidityRequested	Запрошена ликвидность
7	LiquidityProvided	Ликвидность предоставлена
8	Verified	Транзакция верифицирована (trustless)

Ключевые методы:

• processProof — обработка proof транзакции, вызов TransactionChecker
• onTrustlessVerify — callback от TransactionChecker при успешной верификации
• _onConfirm — вызов proxy для завершения трансфера

MergePool / MergeRouter

Контракты для объединения alien токенов из разных сетей в единое представление (canon token).

MergeRouter:

• Роутинг к соответствующему MergePool для токена

MergePool:

• Хранит маппинг derive-токенов к canon-токену
• Конвертация между decimals разных представлений

Off-chain компоненты (Backend)

Sync Service

Фоновый сервис синхронизации ключевых блоков между сетями.

Важно

Sync Service работает в фоновом режиме и синхронизирует ключевые блоки периодически, а не для каждого трансфера. Это необходимо для поддержания актуального набора валидаторов в LiteClient.

Функции:

• Отслеживает ключевые блоки в сети отправления
• Загружает актуальную информацию о validator set в контракт LiteClient сети назначения
• Вызывает new_key_block на LiteClient для обновления набора валидаторов

Proof API

Легкая нода, синхронизирующая блоки и предоставляющая API для построения proof chain.

Функции:

• Формирует Merkle tree proof для транзакции
• Формирует proof блока
• Endpoint: GET /v1/proof_chain/{address}/{lt} — возвращает BOC с proof chain

Bridge API

Индексатор событий для конкретной TVM сети.

Функции:

• Индексация событий из proxy-контрактов
• Отслеживание статусов трансферов
• Предоставление данных для деплоя event-контрактов

Bridge Aggregator API

Агрегатор над всеми API для работы с трансферами.

Функции:

• Подготовка payload для трансферов
• Объединение истории трансферов из всех сетей
• Отслеживание статусов трансферов независимо от сетей

---

Потоки трансферов

Lock Native → Mint Alien

Этот поток описывает перевод native токена из сети отправления в сеть назначения, где он становится alien токеном.

Пошаговое описание

Шаг 1-2: Инициация и блокировка

Пользователь отправляет jetton-токены на NativeProxy. В payload указывается адрес получателя и целевая сеть. Proxy блокирует токены и эмитит событие TvmTvmNative.

Шаг 3: Деплой Event-контракта

Proof API генерирует Merkle proof транзакции. EventConfiguration деплоит event-контракт с данными proof в сети назначения.

Шаг 4-5: Верификация

Event-контракт вызывает TransactionChecker для верификации транзакции. TransactionChecker проверяет Merkle proof и запрашивает LiteClient для верификации подписей блока.

Шаг 6-7: Подтверждение

При успешной верификации TransactionChecker вызывает onTrustlessVerify(true) на Event-контракте. Статус меняется на Verified. Затем Event-контракт вызывает _onConfirm(), который:

• Меняет статус на Confirmed
• Отправляет onTvmEventConfirmedExtended в AlienProxy

Шаг 8-9: Минтинг

AlienProxy получает подтверждение, проверяет лимиты, взимает комиссию и минтит alien-токены получателю.

---

Burn Alien → Unlock Native

Обратный поток: возврат alien токена в исходную сеть, где разблокируются native токены.

Пошаговое описание

Шаг 1-2: Пользователь сжигает alien токены через AlienProxy. Proxy эмитит событие TvmTvmAlien.

Шаг 3-5: Деплой Event-контракта и верификация аналогично предыдущему потоку.

Шаг 6-7: Event-контракт получает подтверждение, статус меняется Verified → Confirmed.

Шаг 8-9: NativeProxy получает подтверждение и разблокирует (unlock) native токены получателю.

---

Lock Native → Unlock Native

Поток для трансфера native токена между сетями, где в обеих сетях токен является native.

Особенность реализации

Трансфер технически выполняется через Alien-поток, но на AlienProxy происходит проверка: если для токена настроен native-native сценарий (есть запись в predeployedTokens), то AlienProxy не минтит токен, а проксирует вызов на NativeProxy.

Пошаговое описание

Шаг 1-2: Пользователь отправляет native токены на NativeProxy в сети отправления. Токены блокируются, эмитится событие TvmTvmNative.

Шаг 3-5: В сети назначения деплоится MultiVaultTvmTvmEventAlien (не Native!) через AlienEventConfiguration. Происходит верификация через TransactionChecker.

Шаг 6-7: Event-контракт вызывает receivePredeployedToken на AlienProxy. Если токен зарегистрирован в predeployedTokens, возвращается PredeployedTokenData с адресом nativeProxyTokenWallet.

Шаг 8-9: После верификации Event-контракт вызывает onTvmEventConfirmedExtended на AlienProxy, передавая nativeProxyTokenWallet в метаданных.

Шаг 10: AlienProxy проверяет nativeProxyTokenWallet.hasValue(). Если true — не минтит, а проксирует вызов на NativeProxy через proxyMultiVaultNative.onTvmEventConfirmedExtended().

Шаг 11: NativeProxy получает вызов (принимает от AlienProxy или напрямую от EventConfig), разблокирует native токены и отправляет получателю.

Когда используется этот поток?

Lock Native → Unlock Native используется когда токен настроен как native в обеих сетях через predeployedTokens в AlienProxy. Это возможно для:

• Wrapped native токенов (например, wTON)
• Токенов, специально настроенных администратором

Настройка происходит через регистрацию PredeployedTokenData в маппинге tvmConfiguration.predeployedTokens.