Інтеграція з Superfluid (потокові платежі)

Інтеграція з Superfluid (потокові платежі)

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

Як працює Superfluid під капотом

Super Tokens і real-time

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 в секунду (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/місяць
});

const tx = await createFlowOperation.exec(signer);

SDK абстрагує callAgreement вызови. Для production коду використовуємо 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 інтеграція на фронтенді + обробчики событій + мониторинг ліквідацій.

Тестування. Superfluid має testnet деплои на Polygon Mumbai (deprecated) та Sepolia. Fork-тести з mainnet станом через Foundry для складної бізнес-логіки.

Орієнтири по термінам

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

Вартість рахується індивідуально після аналізу бізнес-логіки.