Інтеграція Superfluid: впровадження потокових платежів у dApp

Уявіть: ваш dApp приймає підписки, і щосекунди баланс користувача змінюється без зайвих транзакцій. Superfluid робить це можливим, відкриваючи новий рівень UX для DeFi-сервісів, грантів та зарплатних потоків. Ми професійно інтегруємо потокові платежі у ваш додаток — від простої воронки до складної системи з ACL та моніторингом ліквідацій. Розберемо, як це працює під капотом, і чому Superfluid знижує кількість транзакцій у 1000 разів порівняно з традиційними підписками. У нашій практиці були проєкти, де інтеграція зменшила газові витрати на 40% порівняно з розкладом транзакцій.

Чому потокові платежі вигідніші за традиційний підхід?

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

Superfluid знижує кількість транзакцій у 1000 разів порівняно з традиційними підписками, а газові витрати — у 3–5 разів на одиницю часу.

Як 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 помилок.

Які ризики виникають при інтеграції потокових платежів?

Основні ризики — неправильний розрахунок буфера, неврахування ліквідацій та відсутність моніторингу подій. Наприклад, підписний dApp без моніторингу FlowDeleted від ліквідацій — користувачі продовжували отримувати контент після закінчення підписки, тому що фронтенд не знав, що потік був ліквідований. Рішення: event listener + статус перевірка через cfa.getFlow(). Також ризик — помилка при обчисленні flowRate через відмінності в decimals: USDC має 6, USDCx — 18. Ми завжди тестуємо контракти на форку mainnet перед деплоєм.

Як забезпечити стабільність роботи Superfluid?

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.

Що входить в роботу

Ми надаємо повний цикл інтеграції:

• Аналіз use case та вибір мережі
• Розробка смарт-контракту (при необхідності)
• Інтеграція Superfluid SDK на фронтенді
• Налаштування обробників подій та моніторингу ліквідацій
• Тестування на testnet та форк-тести (Foundry)
• Документація API для frontend та інструкції з деплою
• Передача вихідного коду та доступів
• Гарантія стабільної роботи протягом 30 днів після здачі

Процес роботи

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

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

Тестування. Superfluid має тестові мережі: Sepolia, Mumbai (застаріла). Форк-тести з mainnet станом через Foundry для складної бізнес-логіки.

Орієнтири за термінами

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

Вартість розраховується індивідуально після аналізу бізнес-логіки. Ми оцінимо ваш проєкт за 1 робочий день — зв'яжіться з нами для консультації. Наші інженери мають 5+ років досвіду у веб-розробці та реалізували 30+ Web3-проєктів.

Superfluid SDK