Интеграция с Superfluid (потоковые платежи)

Интеграция с Superfluid (потоковые платежи)

Традиционный подход к периодическим платежам в Web3 — approve + transferFrom по расписанию, либо предоплата на несколько периодов. Оба варианта требуют или активного участия пользователя, или доверия к контракту держать большие суммы наперёд. Superfluid решает это иначе: деньги текут посекундно, баланс обновляется в реальном времени без отдельных транзакций. Для подписочных dApp, salary streaming или grant distribution — это значимая разница в UX.

Как работает Superfluid под капотом

Super Tokens и реальное время

Superfluid не работает с обычными ERC-20. Нужен Super Token — оверлей над ERC-20 через upgrade() функцию. Пользователь вносит 100 USDC → получает 100 USDCx (Super Token). USDCx — это ERC-20, который умеет в потоки.

balanceOf(address account) у Super Token возвращает реальное значение с учётом всех активных потоков: staticBalance + netFlowRate * (block.timestamp - lastUpdated). Это view функция, которая смотрит в будущее и прошлое одновременно. Никаких on-chain записей каждую секунду — только обновление при открытии/закрытии/изменении потока.

Практическое следствие: баланс меняется с каждой секундой без транзакций. Это означает, что transfer(recipient, amount) с суммой «весь баланс» — опасная операция: между вашим вычислением суммы и исполнением транзакции прошло время, реальный баланс уменьшился.

CFAv1 (Constant Flow Agreement)

Основной инструмент — IConstantFlowAgreementV1. Открыть поток:

ISuperfluid(host).callAgreement(
    cfa,
    abi.encodeWithSelector(
        cfa.createFlow.selector,
        token,        // USDCx
        receiver,     // адрес получателя
        flowRate,     // wei per second (int96)
        new bytes(0)  // userData
    ),
    "0x"
);

flowRate — это int96, не uint256. Отрицательное значение означает входящий поток. Для расчёта flowRate: monthlyAmount * 1e18 / (30 * 24 * 3600) — количество wei USDCx в секунду.

Важный нюанс: int96 ограничен ~39.6 * 10^27 wei/sec. Для большинства use case — с запасом, но при работе с токенами с нестандартным количеством decimals нужно проверять overflow.

Liquidation и solvency buffer

Superfluid защищает получателей от ситуации, когда у отправителя закончились средства, через механизм liquidation. При открытии потока отправитель депонирует solvency buffer — обычно 4-часовой поток. Если баланс упал до нуля, но поток не закрыт — любой может вызвать ликвидацию через deleteFlow, получив часть буфера как reward.

Это меняет UX требования: при интеграции в dApp нужно предупреждать пользователя о минимальном необходимом балансе. Если у пользователя USDCx на 3 часа потока — он не может открыть новый поток (буфер = 4 часа). Это распространённая причина confusing INSUFFICIENT_BALANCE ошибок.

Практическая интеграция

Superfluid SDK

import { Framework } from "@superfluid-finance/sdk-core";
import { ethers } from "ethers";

const sf = await Framework.create({
  chainId: 137, // Polygon
  provider,
});

const usdcx = await sf.loadSuperToken("USDCx");
const createFlowOperation = usdcx.createFlow({
  sender: userAddress,
  receiver: recipientAddress,
  flowRate: "385802469135802", // ~1000 USDC/month
});

const tx = await createFlowOperation.exec(signer);

SDK абстрагирует callAgreement вызовы. Для производственного кода — используем batchCall для объединения нескольких операций в одну транзакцию: upgrade + createFlow за один газ.

Обработка событий протокола

Ключевые события для мониторинга:

• FlowCreated(token, sender, receiver, flowRate, totalSenderFlowRate, totalReceiverFlowRate) — новый поток
• FlowUpdated(...) — изменение ставки
• FlowDeleted(...) — закрытие потока (включая ликвидации)

Для frontend real-time обновлений: WebSocket подписка через wagmi watchContractEvent или The Graph subscription (если развёрнут Superfluid subgraph для вашей сети). Superfluid имеет официальный subgraph на mainnet, Polygon, Optimism, Arbitrum, BNB Chain.

Реальный кейс: подписочный dApp без мониторинга FlowDeleted от ликвидаций — пользователи продолжали получать контент после окончания подписки, потому что фронтенд не знал, что поток был ликвидирован. Решение: event listener + статус проверка через cfa.getFlow().

Работа с userData

createFlow принимает bytes userData — произвольные данные, которые эмитируются в событие. Используем для:

• Привязки потока к subscription ID
• Передачи referral кода
• Идентификатора тарифного плана

bytes memory userData = abi.encode(subscriptionId, planId);

На стороне обработчика событий — decode:

const [subscriptionId, planId] = ethers.utils.defaultAbiCoder.decode(
  ["uint256", "uint256"],
  event.userData
);

ACL (Access Control List) для автоматизации

Если нужно, чтобы смарт-контракт мог управлять потоками от имени пользователя (например, автоматическое обновление flowRate при смене тарифа), используем Superfluid ACL:

// Пользователь даёт разрешение контракту
cfa.authorizeFlowOperatorWithFullControl(token, operatorContract, "0x");

Это аналог ERC-20 approve, но для управления потоками. Operator может создавать, изменять, закрывать потоки от имени пользователя в рамках выданных прав.

Поддерживаемые сети и токены

Для кастомных токенов: деплой Pure Super Token (без wrapper, нативный super token) через SuperTokenFactory. Используется для in-app валют, где не нужен underlying ERC-20.

Процесс работы

Аналитика (0.5-1 день). Определяем use case: подписки, salary, grants, rewards streaming. Выбираем сеть. Нужен ли ACL для автоматического управления потоками.

Разработка (2-4 дня). Смарт-контракт (если нужна кастомная логика) + SDK интеграция на фронтенде + event обработчики + мониторинг ликвидаций.

Тестирование. Superfluid имеет testnet деплои на Polygon Mumbai (deprecated) и Sepolia. Форк-тесты с mainnet состоянием через Foundry для сложной бизнес-логики.

Ориентиры по срокам

Базовая интеграция (создание/управление потоками в frontend) без кастомного смарт-контракта — 2-3 дня. Полноценная подписочная система с кастомным контрактом, ACL и мониторингом ликвидаций — 4-7 дней.

Стоимость рассчитывается индивидуально после анализа бизнес-логики.