Перейти к основному содержимому

Фарминг-протокол: прослойка над DEX-пулами и Aave v3

Метаданные​

ПараметрЗначение
Дата создания2026-09-20
Дата последнего изменения2026-09-20
Статус апрува✅ Одобрено
Дата апрува2026-09-20

Пользователям Magnet нужен способ зарабатывать на внешних доходных протоколах, не покидая платформу и не отдавая средства в кастодиальное управление. MagnetFarming решает это: пользователь выбирает рынок, деньги уходят напрямую в пул Uniswap / PancakeSwap или в Aave v3, прибыль и тело доступны к выводу в любой момент. Платформа зарабатывает на комиссии, которая удерживается исключительно с прибыли и распределяется по партнёрской программе и фиксированному списку кошельков.

Существующий MagnetLiquidity эту задачу не закрывает: там другая модель — NFT-продукт с токеном оплаты, свопами внутри контракта, арендой и матрицей земель. Фарминг-протокол делается отдельным модулем и MagnetLiquidity не затрагивает.

2.1. Пользовательские сценарии​

  1. Вклад в пул ликвидности. Пользователь выбирает рынок (например, WPOL/USDC), указывает суммы обоих токенов и ценовой диапазон, подтверждает два approve и депозит. Контракт открывает позицию Uniswap V3; в BSC дополнительно стейкает её в MasterChefV3. Неизрасходованный остаток возвращается сразу.
  2. Вклад в Aave. Пользователь выбирает рынок (например, USDC), указывает сумму, подтверждает approve и депозит.
  3. Клейм прибыли. В любой момент. Для пула это торговые комиссии в обоих токенах плюс CAKE, для Aave — накопленные проценты плюс награды ликвидити-майнинга. С каждого токена прибыли удерживается комиссия.
  4. Вывод тела. В любой момент, полностью или частично, без комиссии. Прибыль клеймится автоматически в той же транзакции.
  5. Получение партнёрских выплат. В Polygon партнёр получает свою долю мгновенно, в момент клейма даунлайна. В остальных сетях доля резервируется и приходит после того, как кипер разнесёт резерв.

2.2. Бизнес-логика​

Комиссия берётся только с прибыли. Депозит и вывод тела не облагаются. Проценты считаются от полной суммы прибыли, а не друг от друга:

прибыль 100 → казна 10% = 10
            → партнёрские линии 3% + 2% + 1% = 6
            → пользователю 84

Суммарная комиссия ограничена ончейн-потолком 50% и настраивается администратором.

Комиссия удерживается отдельно с каждого токена прибыли. На пуле это token0, token1 и CAKE; на Aave — базовый актив и каждый токен наград.

Партнёрка работает в двух режимах, выбор — по сети.

  • Polygon: цепочка читается ончейн из MagnetDiamond, доли уходят партнёрам мгновенно.
  • Остальные сети: Diamond там нет, поэтому доли раскладываются по 15 линиям и резервируются на контракте. Позже кошелёк-кипер с ролью KEEPER_ROLE присылает массив кошельков, и контракт платит по нему. Проценты настроены ончейн, кипер их не передаёт и подменить не может — он указывает только адресата.

Ключевое следствие такой фиксации: суммы фиксируются в момент клейма по действовавшим тогда процентам. Администратор может менять проценты когда угодно, и это не переписывает задним числом то, что партнёры уже заработали.

Доля, которой некому уйти, идёт в fallbackTreasury. Это касается пустых партнёрских линий, сломанных адресов получателей и случая, когда пользователь не зарегистрирован в Diamond. Клейм при этом не падает — иначе пользователь вне Diamond вообще не смог бы забрать свою прибыль.

Докладывать в существующую позицию нельзя. Повторный депозит создаёт новую позицию. Это сознательное упрощение: increaseLiquidity с его крайними случаями не нужен, а у пользователя может быть сколько угодно позиций в одном рынке.

2.3. UI/UX требования​

Экран каталога строится на marketsCount и getMarket. Экран позиции — на getUserPositions, getPosition, pendingProfit и positionBody. pendingProfit возвращает и полную прибыль, и сумму после комиссии, поэтому отдельно считать удержание на фронте не нужно.

Что важно учесть фронту:

  • Депозит в пул требует двух approve и обоих токенов от пользователя. Свопов внутри контракта нет, поэтому «войти одним USDT» без внешнего свопа не получится.
  • tickLower/tickUpper считает фронт и обязан выровнять по tickSpacing пула, иначе mint ревертит.
  • Вывод тела сам клеймит прибыль — отдельную кнопку «сначала заклеймить» показывать не нужно.

3.1. Архитектура​

Ядро MagnetFarming.sol (UUPS, AccessControl, Pausable, ReentrancyGuard) держит реестр рынков, позиции и логику комиссий. Интеграции вынесены во внешние библиотеки UniswapV3FarmLib и AaveV3FarmLib, которые линкуются при деплое: без этого имплементация не помещается в лимит EIP-170.

пользователь → MagnetFarming → UniswapV3FarmLib → NonfungiblePositionManager → пул
                             → UniswapV3FarmLib → MasterChefV3 (BSC)
                             → AaveV3FarmLib    → Aave v3 Pool
                             → IPartnerProvider → MagnetDiamond (Polygon)
                             → резерв + кипер   (остальные сети)

3.2. Описание технической реализации​

Подробное описание — в engineering/Контракты/MagnetFarming.md: раскладка хранилища, алгоритм разделения тела и процентов Aave через scaled-баланс, накопитель наград, полный ABI, инструкция для бэкенда и параметры деплоя.

4. Проблемы и компромиссы​

4.1. Известные ограничения​

  1. Запас байткода 759 байт из 24 576

    • Имплементация занимает 23 817 байт даже с вынесенными библиотеками.
    • Любое заметное расширение ядра потребует выноса ещё одного куска логики. Страж — ContractSize.test.ts.

  2. Пыль округления Aave

    • aToken ребейзится, и при полном выходе позиция не может запросить ровно свою долю: округления расходятся на единицу.
    • Решение: оценка покрытия округляется вниз, списание доли — вверх, всегда в пользу контракта. Остаточная пыль остаётся на контракте и забирается админским rescueTokens.

  3. Ребалансировка диапазона не поддерживается

    • Вышедшая из диапазона позиция перестаёт зарабатывать, пока пользователь не закроет её и не откроет заново.

  4. Ликвидити-майнинг Aave сейчас нулевой

    • На 2026-09-20 награды настроены только на два мёртвых рынка Polygon и ни на одном рынке BSC.
    • Код написан и протестирован, но в проде включается флагом рынка: rewardsController = address(0) выключает весь путь.

4.2. Технический долг​

  • Вынести удержание комиссии в отдельную библиотеку, когда запас байткода станет критичным.
  • Добавить ребалансировку диапазона V3, если продукт этого потребует.

4.3. Риски​

  1. Закрытие фарма PancakeSwap. Если у пула пропадёт pid, MasterChefV3 перестанет принимать NFT и депозит в этот рынок сломается. Митигация: рынок переводится на masterChef = address(0) одним апдейтом конфигурации; форк-тест явно проверяет v3PoolAddressPid != 0 и падает с внятной причиной.
  2. Компрометация кипера. Кипер не контролирует суммы, только адресатов, поэтому максимальный ущерб — увод уже зарезервированной партнёрки. Митигация: отдельная роль, отзываемая администратором.
  3. Ошибка администратора в процентах. Митигация: ончейн-потолок 50%, отдельные сеттеры с валидацией.

5. Вопросы на дополнительное обсуждение​

  • Размер комиссии и раскладка по линиям. В контракте настраивается ончейн, значения на прод нужно утвердить.

    • Кому адресовано: продукт

  • Список рынков на запуск. Сейчас в деплой-скрипте по одному рынку на сеть (WPOL/USDC и USDC в Polygon, USDT/WBNB и USDT в BSC).

    • Кому адресовано: продукт

6. План реализации​

6.1. Этапы разработки​

  • Этап 1: Дизайн и спецификация
  • Этап 2: Контракт, библиотеки, юнит-тесты
  • Этап 3: Форк-тесты на мейннете Polygon и BSC
  • Этап 4: Деплой-скрипт и документация
  • Этап 5: Интеграция фронта и бэкенда (кипер)
  • Этап 6: Аудит и деплой в прод

6.2. Критические зависимости​

  • MagnetDiamond в Polygon — источник партнёрских цепочек.
  • Бэкенд-сервис кипера для сетей без Diamond.

8. Документация​

  • Технический документ engineering/Контракты/MagnetFarming.md
  • Это ТЗ
  • Инструкция для фронтенда по расчёту tickLower/tickUpper

9. Ссылки​

  • Дизайн-документ: docs/superpowers/specs/2026-09-20-farming-protocol-design.md
  • План реализации: docs/superpowers/plans/2026-09-20-magnet-farming.md
  • Технический документ: engineering/Контракты/MagnetFarming.md
  • Смежные контракты: engineering/Контракты/FeeRouter.md, engineering/Контракты/PartnerChainBridge.md