Liquidity Request

Что такое Liquidity Request

Проблема

При кросс-чейн трансфере Native токенов может возникнуть ситуация, когда на Native Proxy в сети назначения недостаточно токенов для завершения трансфера.

Пример: Пользователь хочет перевести 1000 USDT из сети A в сеть B. В сети B это Native токен, который должен быть разблокирован из Proxy. Но в Proxy только 500 USDT — трансфер не может завершиться.

Решение

Liquidity Request (LR) — механизм, который позволяет:

1. Приостановить трансфер до получения недостающей ликвидности
2. Установить награду (bounty) — получатель может предложить часть суммы как вознаграждение
3. Привлечь Liquidity Provider — стороннего участника, который предоставит недостающие токены

Как это работает

1. Отправка токенов — пользователь инициирует кросс-чейн трансфер из сети A в сеть B
2. Верификация proof — Event контракт в сети B получает и верифицирует Merkle proof транзакции
3. Попытка разблокировки — Event контракт вызывает Native Proxy для разблокировки токенов
4. Недостаток ликвидности — Proxy обнаруживает, что баланс меньше требуемой суммы, и вызывает notEnoughLiquidity() на Event контракте
5. Создание LR — Event контракт переходит в статус LiquidityRequested и эмитит событие

Три варианта разрешения LR:

Вариант	Действие	Результат
LP предоставляет ликвидность	LP отправляет amount - bounty токенов на Event контракт	Получатель получает токены, LP получает обратный трансфер на полную сумму в исходной сети
Пользователь отменяет	Sender или recipient вызывает cancel()	Токены возвращаются отправителю в исходную сеть
Retry при появлении ликвидности	Кто-либо вызывает retry() после пополнения Proxy	Трансфер завершается штатно

Ключевые участники

Участник	Роль
Отправитель (sender)	Инициирует трансфер, может отменить LR
Получатель (recipient)	Получает токены, может установить bounty, может отменить LR
Liquidity Provider (LP)	Предоставляет недостающую ликвидность за вознаграждение
Native Proxy	Контракт, хранящий ликвидность в сети назначения

Когда создаётся LR

Типы трансферов

Тип трансфера	Описание	Требует LR?
Native → Alien	Native токены блокируются, Alien минтятся	Нет — минт не требует ликвидности
Alien → Native	Alien сжигаются, Native разблокируются	Да — требуется ликвидность в Proxy
Native → Native	Native через hub-сеть	Да — требуется ликвидность

Условия создания LR

LR создаётся автоматически, когда:

1. Трансфер верифицирован и подтверждён (статус Confirmed) — proof транзакции прошёл криптографическую верификацию
2. Proxy пытается отправить токены получателю
3. Баланс Proxy меньше требуемой суммы
4. Proxy вызывает notEnoughLiquidity() на Event контракте

После этого Event контракт переходит в статус LiquidityRequested и эмитит событие LiquidityRequested(bounty).

Данные LR

Поле	Описание
token	Адрес токена
amount	Полная сумма трансфера
recipient	Адрес получателя
sender	Адрес отправителя
bounty	Награда для LP (устанавливается получателем)
status	Текущий статус LR

Жизненный цикл LR

Диаграмма состояний

Описание статусов

Статус	Что происходит	Что можно сделать
Initializing	Event контракт создан	Ожидание proof
Pending	Proof отправлен на верификацию	Ожидание подтверждения
Verified	Верификация пройдена	Ожидание конфигурации
Confirmed	Трансфер подтверждён, выполняется	—
LiquidityRequested	Ожидание LP	Установить bounty, отменить, retry
LimitReached	Достигнут дневной лимит	Approve, reject, отменить
LiquidityProvided	LP предоставил ликвидность	Финальный статус
Cancelled	Трансфер отменён	Финальный статус
Rejected	Трансфер отклонён	Финальный статус

События контракта

Событие	Когда эмитится
LiquidityRequested(bounty)	При создании LR или изменении bounty
LiquidityProvided(tokenSender)	При успешном предоставлении ликвидности
Cancelled()	При отмене трансфера
LimitReached(approver)	При достижении дневного лимита
Rejected()	При отклонении трансфера

Управление LR

Предоставление ликвидности (Approve)

Liquidity Provider (LP) может предоставить недостающую ликвидность:

1. LP отправляет amount - bounty токенов на Event контракт
2. Получатель получает токены
3. LP получает обратный трансфер на полную сумму в исходной сети

Отмена (Cancel)

Отправитель или получатель может отменить LR:

• Статус меняется на Cancelled
• Создаётся обратный трансфер на указанный адрес
• Токены возвращаются в исходную сеть (минус комиссии)

Кто может отменить:

• Отправитель (sender)
• Получатель (recipient)
• Limit approver (если статус LimitReached)

Установка награды (Bounty)

Получатель или отправитель может изменить bounty для привлечения LP:

• Bounty может быть от 0 до полной суммы трансфера
• Чем выше bounty, тем привлекательнее LR для LP
• При изменении bounty эмитится событие LiquidityRequested(newBounty)

Retry (повторная попытка)

Если ликвидность появилась в Proxy, можно повторить попытку:

• Вызывается функция retry()
• Трансфер повторно пытается выполниться через Proxy

Кто может вызвать retry:

• Отправитель
• Получатель
• Initializer

Кто такой Initializer

Initializer — это адрес, который отправил транзакцию с proof в сеть назначения и инициализировал Event контракт. Обычно это:

• Сам пользователь (через UI бриджа)
• Автоматический сервис бриджа
• Любой третий участник, который хочет ускорить трансфер

Initializer имеет право вызывать retry(), так как он уже потратил газ на инициализацию Event контракта.

Таймауты

В контрактах нет явного таймаута для LR. Liquidity Request может находиться в статусе LiquidityRequested неограниченное время.

Ошибки и Edge Cases

Таблица ошибок (ErrorCodes)

Код	Описание
2324	Неверный статус для операции
2326	takeWalletAddress вызван не из token root
2331	notEnoughLiquidity вызван не из Proxy
2332	cancel/setBounty вызван не получателем/отправителем
2333	Bounty > amount
2334	transferNotification вызван не из token wallet
2335	approveLimit/rejectLimit вызван не approver'ом

Edge Cases

Конкуренция LP

Если несколько LP видят один LR и отправляют токены одновременно:

• Первый transferNotification с корректной суммой будет принят
• Статус атомарно меняется на LiquidityProvided
• Все последующие транзакции вернут токены отправителям

Частичное выполнение

Нельзя отправить меньше токенов, чем amount - bounty. Любая сумма меньше требуемой будет отклонена и возвращена.

LR без активности

LR может висеть в статусе LiquidityRequested неограниченно долго. Решения:

1. Увеличить bounty для привлечения LP
2. Отменить через cancel()
3. Дождаться пополнения Proxy и вызвать retry()

Bounty = 0

При нулевом bounty LP должен отправить полную сумму. Это непривлекательно (profit = 0), поэтому такие LR обычно не обрабатываются.