Superfluid Protocol

---

name: superfluid description: > Knowledge base for the Superfluid Protocol and its ecosystem. Use BEFORE searching the web for Superfluid information. Keywords: Superfluid, CFA, GDA, Super App, Super Token, stream, flow rate, real-time balance, pool (member/distributor), IDA, sentinels, liquidation, TOGA, @sfpro/sdk, semantic money, yellowpaper, whitepaper metadata: version: 1.1.2

---

Superfluid Protocol Skill

Complete interface documentation for Superfluid Protocol smart contracts via Rich ABI YAML references. Read references/guides/architecture.md for the full protocol architecture. This file maps use-cases to the right references.

Developer Tracks

Determine the track first, then follow the Use-Case Map below.

Smart Contract dev: SuperTokenV1Library, CFASuperAppBase, MacroForwarder, raw agreements via Host. ABI source: @superfluid-finance/ethereum-contracts. Addresses: @superfluid-finance/metadata + tokenlist. Data: on-chain calls. Key refs: .abi.yaml files, super-apps.md, macro-forwarders.md.

App (frontend/backend) dev: @sfpro/sdk (ABIs, wagmi hooks, addresses), subgraphs, API services. ABI source: @sfpro/sdk. Addresses: @superfluid-finance/metadata + tokenlist. Data: subgraphs + API services. Key refs: sdks.md, api-services.md, subgraph guides.

Investigating (one-off): Scripts (tokenlist.mjs, metadata.mjs, balance.mjs, cast call). ABI source: scripts/abi.mjs. Addresses: scripts/metadata.mjs + tokenlist.mjs. Data: cast call + scripts/balance.mjs. Key refs: scripts.md.

For SDK import paths, ABI tables, and deprecated package warnings, see references/guides/sdks.md. For script command syntax and examples, see references/guides/scripts.md.

Architecture Summary

Host (Superfluid.sol) — central router. Agreement calls go through Host.callAgreement() or Host.batchCall(). Manages the app registry, governance, and SuperTokenFactory.

Agreements — stateless financial primitives that store data on the token: CFA (1:1 streams), GDA (many-to-many via pools), IDA (deprecated, replaced by GDA).

Super Token — ERC-20/ERC-777/ERC-2612 with real-time balance. Three variants: Wrapper (ERC-20 backed), Native Asset/SETH (ETH backed), Pure (pre-minted).

Forwarders (CFAv1Forwarder, GDAv1Forwarder) — convenience wrappers. Each call is a standalone transaction with readable wallet descriptions. Cannot be batched — use Host.batchCall with raw agreement calls for atomicity.

MacroForwarder — extensible batch executor. Developers deploy custom macro contracts (IUserDefinedMacro) and call MacroForwarder.runMacro() to execute complex multi-step operations atomically. See references/guides/macro-forwarders.md.

Automation (Vesting Scheduler, FlowScheduler, Auto-Wrap) — schedule on-chain intent, require off-chain keepers to trigger execution.

Use-Case → Reference Map

Read only the files needed for the task. Each Rich ABI YAML documents every public function, event, and error for one contract — plus notes: fields that flag non-obvious behavior, edge cases, and common mistakes not apparent from signatures alone.

Streaming money (CFA)

Create/update/delete a stream (simple) → references/contracts/CFAv1Forwarder.abi.yaml

ACL, operator permissions, flow metadata → also references/contracts/ConstantFlowAgreementV1.abi.yaml

Batch streams with other ops atomically → also references/contracts/Superfluid.abi.yaml (Host batch call)

Distributing to many recipients (GDA)

Create pools, distribute, stream to pool → references/contracts/GDAv1Forwarder.abi.yaml

Pool member management, units, claims → also references/contracts/SuperfluidPool.abi.yaml

Low-level agreement details → also references/contracts/GeneralDistributionAgreementV1.abi.yaml

How GDA achieves O(1) scalability (formal math deep-dive) → also references/deep-researches/gda-scalability.md

Token operations

Wrap/unwrap, balances, ERC-20/777, permit → references/contracts/SuperToken.abi.yaml

Deploy a new Super Token → references/contracts/SuperTokenFactory.abi.yaml

Automation

Vesting with cliffs and streams → references/contracts/VestingSchedulerV3.abi.yaml

Schedule future stream start/stop → references/contracts/FlowScheduler.abi.yaml

Auto-wrap when Super Token balance is low → references/contracts/AutoWrapManager.abi.yaml and references/contracts/AutoWrapStrategy.abi.yaml

Writing Solidity integrations (SuperTokenV1Library)

Token-centric Solidity API (using SuperTokenV1Library for ISuperToken) → references/contracts/SuperTokenV1Library.abi.yaml

The library wraps CFA and GDA agreement calls into ergonomic methods like token.flow(receiver, flowRate). Use it for any Solidity contract that interacts with Superfluid — Super Apps, automation contracts, DeFi integrations. Includes agreement-abstracted functions (flowX, transferX) that auto-route to CFA or GDA, plus WithCtx variants for Super App callbacks. See the YAML header and glossary for Foundry testing gotchas.

Building Super Apps

App credit, callback lifecycle, jailing, app levels → references/guides/super-apps.md

CFA callback hooks (simplified base) → references/contracts/CFASuperAppBase.abi.yaml

Token-centric API for callback logic → references/contracts/SuperTokenV1Library.abi.yaml (use WithCtx variants)

App registration, Host context, batch calls → references/contracts/Superfluid.abi.yaml

Smart contract patterns (GDA pools, callbacks, custom tokens, automation, proxies) → references/guides/smart-contract-patterns.md

Super Apps that relay incoming flows use app credit — a temporary deposit allowance enabling zero-balance operation. A 1:1 relay (one in, one out at the same rate) always works without tokens. Fan-out (1:N) requires the app to hold tokens for extra deposits. The sender's locked capital roughly doubles because outgoing stream deposits are backed as owed deposit on the sender. App credit is CFA-only — GDA has no app credit rule. See Common Gotchas below. See references/guides/super-apps.md for the full guide.

Macro forwarders (composable batch operations)

Write a macro for complex batched operations → references/guides/macro-forwarders.md

MacroForwarder contract address and interface → also references/guides/macro-forwarders.md

Batch operation types and encoding rules → also references/contracts/Superfluid.abi.yaml (batch_operation_types)

EIP-712 signed macro patterns → references/guides/macro-forwarders-eip712-example.md

Clear Macro — supersedes MacroForwarder with native EIP-712 clear signing for Super Token operations. Human-readable transaction display (multilingual), third-party relaying (not limited to msg.sender), gasless transactions (fees paid in the Super Token), and custom fee schemes. https://tokens.superfluid.org/clear

Sentinels and liquidation

Batch liquidation of critical flows → references/contracts/BatchLiquidator.abi.yaml

PIC auction, bond management, exit rates → references/contracts/TOGA.abi.yaml

SUP Token / Reserve System

Contracts use "FLUID" and "Locker" internally — public-facing names are "SUP" and "Reserve".

Lock, stake, unstake SUP; provide LP; unlock → references/contracts/FluidLocker.abi.yaml

Create a Reserve (Locker) for a user → references/contracts/FluidLockerFactory.abi.yaml

Claim from emission programs (signed messages) → references/contracts/FluidLocker.abi.yaml and references/contracts/FluidEPProgramManager.abi.yaml

Create / fund / stop emission programs → references/contracts/FluidEPProgramManager.abi.yaml

Understand tax distribution to stakers and LPs → references/contracts/StakingRewardController.abi.yaml

Unlock SUP via time-delayed stream (Fontaine) → references/contracts/FluidLocker.abi.yaml and references/contracts/Fontaine.abi.yaml

ERC-8004 Agent Pools

ERC-8004 standard, Identity/Reputation/Validation registries, AgentPoolDistributor integration → references/deep-researches/erc8004-agent-pools.md

GDA pool mechanics (units, claims, connections) → references/contracts/GDAv1Forwarder.abi.yaml and references/contracts/SuperfluidPool.abi.yaml

Querying indexed data (Subgraphs)

Understand how The Graph generates query schemas, plus cross-cutting gotchas → references/subgraphs/_query-patterns.md

Query streams, pools, tokens, accounts (entities) → also references/subgraphs/protocol-v1-guide.md and protocol-v1-entities.graphql

Query protocol events (flow updates, liquidations, distributions) → also references/subgraphs/protocol-v1-guide.md and protocol-v1-events.graphql

Query vesting schedules and execution history → also references/subgraphs/vesting-scheduler-guide.md and vesting-scheduler.graphql

Query scheduled flows and automation tasks → also references/subgraphs/flow-scheduler-guide.md and flow-scheduler.graphql

Query auto-wrap schedules and execution history → also references/subgraphs/auto-wrap-guide.md and auto-wrap.graphql

Query SUP lockers, staking, emission programs, unlock history → also references/subgraphs/sup-subgraph-guide.md and sup-subgraph.graphql

Legacy

Old IDA (instant distribution, deprecated) → references/contracts/InstantDistributionAgreementV1.abi.yaml

Ecosystem & tooling

SDK import paths, ABI tables, package choice → references/guides/sdks.md

Script command syntax and examples → references/guides/scripts.md

API endpoint details, Swagger links, gotchas → references/guides/api-services.md

SUP token, governance, DAO, distribution → references/guides/sup-and-dao.md

Token prices, filtered token list, CoinGecko IDs → See API Services (CMS) below

Stream accounting, per-day chunking → See API Services (Accounting) below

Resolve ENS / Farcaster / Lens handles → See API Services (Whois) below

Query protocol data via GraphQL → See Subgraphs below

Run a sentinel / liquidation bot → See Sentinels below

Get a Super Token listed → https://tokens.superfluid.org/listing (submit via GitHub) — See also Processes below

Displaying flowing balances (frontend)

Animate a real-time streaming balance counter → references/guides/flowing-balances.md

Read the guide first — it has production-ready implementations (React, vanilla JS, Vue, Svelte, Solid). Do not generate flowing balance code from scratch.

Fix layout shift / jumping in a flowing balance display → also references/guides/flowing-balances.md

Format wei amounts, flow rates, token prices → also references/guides/flowing-balances.md

Ecosystem deep-dives

Protocol history, founding, exploit, SUP launch → references/deep-researches/superfluid-history.md

Semantic Money formal spec (yellowpaper, Haskell reference, BasicParticle, agreement hierarchy) → references/deep-researches/semantic-money-yellowpaper.md

GDA scalability (PDPool math, O(1) distributions, rounding model, settle-on-write) → references/deep-researches/gda-scalability.md

GoodDollar (G$ Pure Super Token on Celo, UBI, streaming) → references/deep-researches/gooddollar.md

Flow State (Streaming Quadratic Funding, cooperative) → references/deep-researches/flowstate.md

ERC-8004 Agent Pools (AI agent identity + GDA distribution on Base) → references/deep-researches/erc8004-agent-pools.md

Planet IX (GameFi, CFA, custom Super Tokens, SuperApp callbacks) → references/deep-researches/planet-ix.md

Nerite (USND stablecoin, Custom Pure Super Token, CFA+GDA) → references/deep-researches/nerite.md

SuperBoring (DCA, CFA→GDA TOREX pattern, Superfluid Labs) → references/deep-researches/superboring.md

TOREX (TWAP Oracle Exchange — streaming DEX, discount model, back charge/refund between LMEs, liquidity movers, Twin TOREX) → references/deep-researches/torex.md

Giveth (zero-fee donations, CFA recurring streams) → references/deep-researches/giveth.md

Streme.fun (token launcher, Pure Super Tokens, GDA staking) → references/deep-researches/streme.md

Superfluid team brand & design

Color palette, typography, visual identity → references/guides/brand-design.md

Covers the Superfluid team's product design, not the broader protocol ecosystem.

Formal specification and protocol theory

Yellowpaper foundations (payment primitives, conservation of value, agreement framework) → references/deep-researches/semantic-money-yellowpaper.md

How GDA achieves O(1) streaming to unlimited receivers → references/deep-researches/gda-scalability.md

BasicParticle and the real-time balance formula → also references/deep-researches/semantic-money-yellowpaper.md

Debugging Reverts

Error prefixes map to contracts:

CFA_* → ConstantFlowAgreementV1

CFA_FWD_* → CFAv1Forwarder

GDA_* → GeneralDistributionAgreementV1

SUPERFLUID_POOL_* → SuperfluidPool

SF_TOKEN_* → SuperfluidToken (base of SuperToken)

SUPER_TOKEN_* → SuperToken

SUPER_TOKEN_FACTORY_* → SuperTokenFactory

HOST_* → Superfluid (Host)

IDA_* → InstantDistributionAgreementV1

APP_RULE → Superfluid (Host) — Super App callback violation

NOT_LOCKER_OWNER, FORBIDDEN, INSUFFICIENT_*, STAKING_*, LP_*, TTE_* → FluidLocker

LOCKER_CREATION_PAUSED, NOT_GOVERNOR → FluidLockerFactory

PROGRAM_*, INVALID_SIGNATURE, NOT_PROGRAM_ADMIN → FluidEPProgramManager

NOT_APPROVED_LOCKER, NOT_LOCKER_FACTORY, NOT_PROGRAM_MANAGER → StakingRewardController

NOT_CONNECTED_LOCKER, NO_ACTIVE_UNLOCK, TOO_EARLY_TO_TERMINATE_UNLOCK → Fontaine

NotAgentOwner, AlreadyJoined, AgentNotRegistered, InsufficientFee, FeeTransferFailed → AgentPoolDistributor

Each YAML's errors: section is the complete error index for that contract, with descriptions. Per-function errors: fields show which errors a specific function can throw. To look up a hex selector (function, event, or error), read the companion .selectors.yaml file — every Foo.abi.yaml has a Foo.selectors.yaml alongside it with full signatures and computed hashes.

Common Gotchas (Quick Reference)

Subset of non-obvious behaviors. The authoritative source is the notes: field on each function in the .abi.yaml files — always read those for the complete picture. This section covers only the most common ones.

Super Token decimals always 18 — upgrade() and downgrade() amounts are always in 18-decimal SuperToken units, regardless of underlying token decimals. The contract handles scaling internally. The only place underlying decimals matter is the ERC-20 approve() call. Example: to wrap 100 USDC, approve 100e6 on USDC, then call upgrade(100e18).

GDA pool connections vs. membership — Pool membership is unlimited (an account can hold units in any number of pools). However, only 256 pools can be connected per account per token — connected means the balance auto-reflects in the member's SuperToken balance. Unconnected members must call claimAll() to receive their tokens. Gas for balanceOf / realtimeBalanceOf scales linearly with connected pools.

GDA distribution rounding — distributeFlow: per-unit rate = requestedFlowRate / totalUnits (integer division, rounds down). The rounding remainder becomes an adjustment flow to the pool admin. If requestedFlowRate < totalUnits, per-unit rate truncates to 0 and the entire flow goes to admin. distribute (instant): the remainder simply isn't taken from the distributor — actual distributed amount < requested. Pools hold no balance; tokens flow through directly to members. See references/deep-researches/gda-scalability.md for the full rounding model with align2 and adjustment flow math.

SuperTokenV1Library address(this) — Convenience functions (flow, flowX, distribute, distributeFlow, createPool, claimAll) use address(this) as the implicit sender, not msg.sender. In Foundry tests, vm.prank does not override this. Use CFA/GDA-specific function overloads with an explicit sender/from parameter instead.

CFASuperAppBase APP_LEVEL_FINAL — CFASuperAppBase is hardcoded to APP_LEVEL_FINAL, which prevents calling other Super Apps downstream from its callbacks. To compose with downstream Super Apps, build a custom base using APP_LEVEL_SECOND and call host.allowCompositeApp(targetApp). Max chain depth: 2 apps (SECOND → FINAL).

GDA pools cannot nest — A pool cannot be a member of another pool. updateMemberUnits reverts with SUPERFLUID_POOL_NO_POOL_MEMBERS if the member address is a pool. Pool addresses also cannot be pool admins (GDA_ADMIN_CANNOT_BE_POOL).

FluidLocker instant unlock penalty — unlockPeriod=0 triggers an instant unlock with 80% penalty — only 20% is transferred immediately, 80% is redistributed to stakers and LPs. All unlocks (including instant) require msg.value of 0.0001 ETH (UNLOCKING_FEE, sent to DAO treasury). Periods of 7–365 days deploy a Fontaine beacon proxy that streams tokens over the unlock period with a proportional tax.

GDA has no app credit — Unlike CFA, GDA does not support the app credit mechanism. A Super App that receives CFA inflows and distributes via GDA cannot borrow the deposit buffer — it must fund the GDA stream's buffer deposit from its own balance or via ERC-20 transferFrom from the user. This is the most common reason CFA→GDA stream-splitting contracts fail. See references/guides/smart-contract-patterns.md § A for the workaround.

balanceOf clamps to zero — balanceOf returns max(0, availableBalance) for ERC-20 compatibility. Accounts with active outgoing streams can go negative (critical), but balanceOf will still show 0. Use realtimeBalanceOfNow to detect negative balances — a negative availableBalance means the account is critical and awaiting liquidation. Once liquidated, the balance resets to zero.

Reading the Rich ABI YAMLs

Essential conventions for parsing the YAML files:

Reserved root keys: meta, events, errors — every other root key is a function.

ctx: bytes parameter = function is called through the Host (callAgreement / batchCall), never directly.

notes: field — the most important field for correctness. Present on functions (and as meta.notes: at contract level). Contains non-obvious behavior, edge cases, and common mistakes. If a user asks about unexpected behavior, the answer is almost always in a notes: field. Always read these.

access labels: anyone, host, self, admin, governance, sender, receiver, operator, manager, pic, etc. Combine with |.

emits and errors ordering matches execution flow (not alphabetical). First errors = most likely.

Field order: description comment, notes, mutability, access, inputs, outputs, emits, errors.

For the full format spec with examples (function entries, events, errors sections), see references/contracts/_rich-abi-yaml-format.md.

Runtime Data (Scripts)

Scripts provide runtime data (addresses, balances, ABIs) for one-off lookups. Run with bunx -p bun