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, BlindMacroForwarder/ClearMacroForwarder, 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, clear-macro.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.

BlindMacroForwarder (legacy name MacroForwarder; SDK: blindMacroForwarderAbi, addr

0xFD0268E33111565dE546af2675351A4b1587F89F) — extensible batch executor. Developers deploy

custom macro contracts (IUserDefinedMacro) and call runMacro() to execute complex multi-step

operations atomically. The caller must be the signer. **Legacy — superseded by ClearMacroForwarder

for new integrations**: self-relay only, and the caller broadcasts raw (unreadable) calldata in the

wallet. See references/guides/macro-forwarders.md.

ClearMacroForwarder (SDK: clearMacroForwarderAbi, addr 0xC1EaB73855155D4e021f7EB4f866996Bac2fe25e,

deployed across ~16 networks) — recommended default; supersedes BlindMacroForwarder. EIP-712

signed macro executor with human-readable clear-signing,

third-party relaying, and optional Permit2 token upgrade in one signature. Two modes: self-submit

(security.provider = "self") and provider-relay (relayer holds a Host SimpleACL role). See

references/guides/clear-macro.md and references/contracts/ClearMacroForwarder.abi.yaml.

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
• BlindMacroForwarder (legacy MacroForwarder) contract address and interface → references/guides/macro-forwarders.md; why ClearMacroForwarder supersedes blind → 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
• ClearMacroForwarder — SDK-shipped (clearMacroForwarderAbi, clearMacroForwarderAddress,

metadata key contractsV1.clearMacroForwarderV1WithPermit2), deployed at

0xC1EaB73855155D4e021f7EB4f866996Bac2fe25e across ~16 networks. EIP-712 clear signing for

human-readable wallet prompts, third-party provider relaying, optional Permit2 token upgrade in

one signature. Two modes: self-submit (security.provider = "self", tx executor = signer) and

provider-relay (relayer holds a Host SimpleACL role, enabling gasless-for-signer flows).

→ references/guides/clear-macro.md, references/contracts/ClearMacroForwarder.abi.yaml,

references/contracts/ClearMacroBase.abi.yaml

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 (CFA + ERC-20 only, no GDA)
• Comprehensive balances / point-in-time (historical) balance / buffer+connected+disconnected breakdown / CSV exports (CFA + GDA + IDA) → See API Services (Balance API) below
• Generate or deep-link an accounting/tax report → https://reporter.superfluid.org; param spec: https://reporter.superfluid.org/llms.txt
• 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
• InvalidSignature, InvalidPayload, MacroContractMismatch, ProviderNotAuthorized, OutsideValidityWindow, InvalidNonce → ClearMacroForwarder (SDK-shipped, multi-network)

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