Superfluid Protocol Skill
Complete interface documentation for Superfluid Protocol smart contracts via
Rich ABI YAML references. Read
references/architecture.md
for the full
protocol architecture. This file maps use-cases to the right references and
explains how to read them.
Architecture Summary
Host (
) — central router. Agreement calls go through
or
. 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
with raw agreement calls for atomicity.
MacroForwarder — extensible batch executor. Developers deploy custom
macro contracts (
) 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.
Streaming money (CFA)
| Intent | Read |
|---|
| 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)
| Intent | Read |
|---|
| 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
|
Token operations
| Intent | Read |
|---|
| Wrap/unwrap, balances, ERC-20/777, permit | references/contracts/SuperToken.abi.yaml
|
| Deploy a new Super Token | references/contracts/SuperTokenFactory.abi.yaml
|
Automation
| Intent | Read |
|---|
| 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)
| Intent | Read |
|---|
Token-centric Solidity API (using SuperTokenV1Library for ISuperToken
) | references/libraries/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 (
,
)
that auto-route to CFA or GDA, plus
variants for Super App
callbacks. See the YAML header and glossary for Foundry testing gotchas.
Building Super Apps
| Intent | Read |
|---|
| CFA callback hooks (simplified base) | references/bases/CFASuperAppBase.abi.yaml
|
| Token-centric API for callback logic | also references/libraries/SuperTokenV1Library.abi.yaml
(use variants) |
| App registration, Host context, batch calls | references/contracts/Superfluid.abi.yaml
|
Super Apps that relay incoming flows via app credit cause the
sender's deposit
to roughly double (or more for fan-out patterns), because outgoing stream
deposits are backed by the sender as owed deposit. See "App Credit & Deposit
Mechanics" in
references/architecture.md
for the full explanation.
Macro forwarders (composable batch operations)
| Intent | Read |
|---|
| 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
|
Sentinels and liquidation
| Intent | Read |
|---|
| Batch liquidation of critical flows | references/contracts/BatchLiquidator.abi.yaml
|
| PIC auction, bond management, exit rates | references/contracts/TOGA.abi.yaml
|
Querying indexed data (Subgraphs)
| Intent | Read |
|---|
| Understand how The Graph generates query schemas from entity definitions | references/subgraphs/query-patterns.md
|
| Query streams, pools, tokens, accounts, events | also references/subgraphs/protocol-v1.graphql
|
| Query vesting schedules and execution history | also references/subgraphs/vesting-scheduler.graphql
|
| Query scheduled flows and automation tasks | also references/subgraphs/flow-scheduler.graphql
|
| Query auto-wrap schedules and execution history | also references/subgraphs/auto-wrap.graphql
|
Legacy
| Intent | Read |
|---|
| Old IDA (instant distribution, deprecated) | references/contracts/InstantDistributionAgreementV1.abi.yaml
|
Ecosystem & tooling
| Intent | Read |
|---|
| Which SDK or package for a project | See Ecosystem → SDKs & Packages below |
| Token prices, filtered token list, CoinGecko IDs | See Ecosystem → API Services (CMS) below |
| Stream accounting, per-day chunking | See Ecosystem → API Services (Accounting) below |
| Resolve ENS / Farcaster / Lens handles | See Ecosystem → API Services (Whois) below |
| Query protocol data via GraphQL | See Ecosystem → Subgraphs below |
| SUP token, governance, DAO | See Ecosystem → Foundation, DAO & SUP Token below |
| Token prices for Super Tokens (simple API) | See Ecosystem → API Services (Token Prices) below |
| Run a sentinel / liquidation bot | See Ecosystem → Sentinels below |
| Get a Super Token listed / enable automations | See Ecosystem → Processes below |
Debugging Reverts
Error prefixes map to contracts:
| Prefix | Contract |
|---|
| ConstantFlowAgreementV1 |
| CFAv1Forwarder |
| GeneralDistributionAgreementV1 |
| SuperfluidPool |
| SuperfluidToken (base of SuperToken) |
| SuperToken |
| SuperTokenFactory |
| Superfluid (Host) |
| InstantDistributionAgreementV1 |
| Superfluid (Host) — Super App callback violation |
Each YAML's
section is the complete error index for that contract,
with selector hashes and descriptions. Per-function
fields show
which errors a specific function can throw.
Reading the Rich ABI YAMLs
Each YAML is a self-contained contract reference. Here's how to parse them.
Root structure
# Header comment — contract name, description, key notes
meta: # name, version, source, implements, inherits, deployments
# == Section == # Grouped functions (these are the core content)
events: # All events the contract emits
errors: # Complete error index
Three root keys are reserved:
,
,
. Every other
root-level key is a
function.
Function entries
yaml
createFlow:
# Description of what the function does.
# GOTCHA: Non-obvious behavior or edge cases.
mutability: nonpayable # view | pure | nonpayable | payable
access: sender | operator # who can call (omitted for view/pure)
inputs:
- token: address
- receiver: address
- flowRate: int96 # inline comments for non-obvious params
- ctx: bytes
outputs:
- newCtx: bytes
emits: [FlowUpdated, FlowUpdatedExtension] # ordered by emission sequence
errors: [CFA_FLOW_ALREADY_EXISTS, CFA_INVALID_FLOW_RATE] # ordered by check sequence
Fields appear in this order: description comment,
,
,
,
,
,
. All are omitted when not applicable.
Key conventions
- parameter = function is called through the Host
( / ), never directly.
- labels: , , , , ,
, , , , , ,
, , . Combine with . Conditional:
anyone(if-critical-or-jailed)
.
- and ordering carries meaning: matches execution flow,
not alphabetical. First errors in the list are the most likely causes.
- prefix flags non-obvious behavior, common mistakes, or edge
cases. Pay close attention to these.
- is an array of raw GitHub URLs to the Solidity source files
(implementation, interface, base — filenames are self-documenting).
- has per-network addresses split into and
subgroups.
Events section
yaml
events:
FlowUpdated:
indexed: # log topics (filterable)
- token: address
- sender: address
data: # log payload
- flowRate: int96
Errors section
yaml
errors:
# -- Category --
- SIMPLE_ERROR # 0xabcd1234 — description
- PARAMETERIZED_ERROR: # errors with diagnostic data
inputs:
- value: uint256
Runtime Data (Scripts)
The Rich ABIs document interfaces (what to call and how). Scripts provide
runtime data (what to call it on) by wrapping canonical npm packages with
local caching for offline use. No npm install required — the scripts fetch
from CDN equivalents of the packages.
ABI JSON — package +
The
package provides typed JSON ABIs
for use with viem / wagmi / ethers. ABIs are split across sub-paths:
| Contract (YAML name) | Import path | Export name |
|---|
| CFAv1Forwarder | | |
| GDAv1Forwarder | | |
| SuperfluidPool | | |
| SuperToken | | |
| Superfluid (Host) | | |
| ConstantFlowAgreementV1 | | |
| GeneralDistributionAgreementV1 | | |
| InstantDistributionAgreementV1 | | |
| SuperTokenFactory | | |
| BatchLiquidator | | |
| TOGA | | |
| AutoWrapManager | @sfpro/sdk/abi/automation
| |
| AutoWrapStrategy | @sfpro/sdk/abi/automation
| |
| FlowScheduler | @sfpro/sdk/abi/automation
| |
| VestingSchedulerV3 | @sfpro/sdk/abi/automation
| |
The SDK also exports chain-indexed address objects alongside each ABI:
| Import path | Address exports |
|---|
| , |
| , , , , , , |
@sfpro/sdk/abi/automation
| , , , vestingSchedulerV3Address
|
Each export is an object keyed by chain ID:
js
import { hostAbi, hostAddress } from "@sfpro/sdk/abi/core";
const host = hostAddress[8453]; // Base Mainnet
CFASuperAppBase and SuperTokenV1Library are not in the SDK (abstract base /
Solidity library).
When writing application code, ALWAYS import ABIs and addresses from
— do NOT hand-craft ABI fragments (risk of phantom parameters)
or hardcode contract addresses (they vary per network). Use
to inspect or inline ABIs when the SDK is not a dependency:
node abi.mjs <contract> Full JSON ABI
node abi.mjs <contract> <function> Single fragment by name
node abi.mjs list All contracts with SDK import info
Accepts YAML names (
) and short aliases (
,
,
,
,
, etc.).
Token list —
Source:
@superfluid-finance/tokenlist
npm package.
Resolves Super Token addresses, symbols, and types. Use when you need to find
a specific token address or determine a Super Token's type.
node tokenlist.mjs super-token <chain-id> <symbol-or-address>
node tokenlist.mjs by-chain <chain-id> --super
node tokenlist.mjs by-symbol <symbol> [--chain-id <id>]
node tokenlist.mjs by-address <address>
node tokenlist.mjs stats
The
field determines which ABI patterns apply:
- Wrapper → / work; is
provided. Underlying ERC-20 approval uses underlying's native decimals;
Super Token functions always use 18 decimals.
- Native Asset → use / instead.
- Pure → / revert; no wrapping.
Super Token balance —
Source:
Super API (real-time on-chain query).
Retrieves the current Super Token balance, net flow rate, and underlying token
balance for any account. No caching — balances are fetched live.
node balance.mjs balance <chain-id> <token-symbol-or-address> <account>
The output includes:
- connected/unconnected balance — wei and human-readable formatted values.
Connected = streaming balance; unconnected = pending pool distributions.
- netFlow — aggregate flow rate in wei/sec and tokens/month (30-day month).
- maybeCriticalAt — estimated time when connected balance hits zero.
- underlyingToken — the wrapped ERC-20 balance (for Wrapper Super Tokens).
Network metadata —
Source:
@superfluid-finance/metadata
npm package.
Resolves contract addresses, subgraph endpoints, and network info for any
Superfluid-supported chain. Use when
in a YAML doesn't
cover the target chain, or when you need automation/subgraph endpoints.
node metadata.mjs contracts <chain-id-or-name>
node metadata.mjs contract <chain-id-or-name> <key>
node metadata.mjs automation <chain-id-or-name>
node metadata.mjs subgraph <chain-id-or-name>
node metadata.mjs networks [--mainnets|--testnets]
Contract keys match the field names in the metadata:
,
,
,
,
,
,
,
,
,
,
, etc.
On-chain reads —
performs read-only
queries against
any contract. If
is not installed locally, use
instead.
Never use or any write/transaction command — read calls only.
cast call <address> "functionName(inputTypes)(returnTypes)" [args] --rpc-url <url>
The return types in the second set of parentheses tell cast how to decode the
output. Without them you get raw hex.
RPC endpoint: https://rpc-endpoints.superfluid.dev/{network-name}
— network
names are the canonical Superfluid names from
node metadata.mjs networks
(e.g.
,
,
).
Examples:
bash
# Total supply of USDCx on Optimism
cast call 0x35adeb0638eb192755b6e52544650603fe65a006 \
"totalSupply()(uint256)" \
--rpc-url https://rpc-endpoints.superfluid.dev/optimism-mainnet
# Flow rate via CFAv1Forwarder (address from Common Contract Addresses below)
cast call 0xcfA132E353cB4E398080B9700609bb008eceB125 \
"getAccountFlowrate(address,address)(int96)" \
<superTokenAddress> <account> \
--rpc-url https://rpc-endpoints.superfluid.dev/optimism-mainnet
Use
to look up exact function signatures and
/
for contract and token addresses.
Common Contract Addresses
Do NOT hardcode or fabricate addresses. Get them from the SDK address exports
(see ABI section above) or from
node scripts/metadata.mjs contracts <chain>
.
Forwarder addresses are the exception — uniform across most networks:
- CFAv1Forwarder:
0xcfA132E353cB4E398080B9700609bb008eceB125
- GDAv1Forwarder:
0x6DA13Bde224A05a288748d857b9e7DDEffd1dE08
Host and agreement addresses vary per network.
Ecosystem
SDKs & Packages
Active — recommended for new projects:
When to use what:
- Frontend with wagmi/viem — install . Enhanced ABIs include
downstream errors for type-safe error handling. Import paths documented in
the ABI section above.
Docs ·
Repo
- Solidity integrations — import ABIs from
@superfluid-finance/ethereum-contracts
at build time. Do NOT use as a
runtime dependency — it pulls in heavy deps not suitable for client bundles.
Repo
- Resolving addresses/networks at runtime —
@superfluid-finance/metadata
has zero dependencies, wrapped by
.
Repo
- Finding token addresses —
@superfluid-finance/tokenlist
based on
, wrapped by .
Repo
Deprecated — do not recommend for new projects:
API Services
| API | Base URL | Purpose |
|---|
| Super API | https://superapi.kazpi.com
| Real-time on-chain Super Token balances |
| CMS | https://cms.superfluid.pro
| Token prices, price history, filtered token list |
| Points | https://cms.superfluid.pro/points
| SUP points campaigns |
| Accounting | https://accounting.superfluid.dev/v1
| Stream accounting with per-day chunking |
| Allowlist | https://allowlist.superfluid.dev
| Check automation allowlist status |
| Whois | https://whois.superfluid.finance
| Resolve profiles (ENS, Farcaster, Lens, AF) |
| Token Prices | https://token-prices-api.superfluid.dev/v1/{network}/{token}
| Super Token prices (CoinGecko-backed) |
- Super API — wrapped by . Use the script instead of
calling the API directly.
- CMS — can return unlisted Super Tokens (not just those in the
tokenlist). Can get CoinGecko IDs for price lookups.
Swagger ·
OpenAPI ·
Repo
- Points — SUP points campaigns (Stack.so replacement). Same repo as CMS.
API docs ·
OpenAPI
- Accounting — splits per-second streams into chunked granularity (e.g.
streamed per day). Handles CFA and ERC-20 transfers only — no GDA
support.
Swagger ·
Repo
- Allowlist —
GET /api/allowlist/{account}/{chainId}
. Check if an
account is allowlisted for automations (vesting, flow scheduling, auto-wrap).
- Whois — Resolves across ENS, AF, Farcaster, Lens, etc.
GET /api/resolve/{address}
— address → profile/name
GET /api/reverse-resolve/{handle}
— name/handle → address
GOTCHA: despite the names, takes an address and
takes a name.
- Token Prices — simpler alternative to CMS for price lookups. Provides
prices for all listed SuperTokens where the token (or underlying) is known to
CoinGecko. Endpoint:
GET /v1/{canonical-network-name}/{token-address}
.
Repo
Subgraphs
Prefer RPC over subgraph for current state. The subgraph only updates on
transactions, but Superfluid state changes continuously (streams flow every
second). Balances, flow rates, and distribution states on the subgraph are
always behind. This is especially true for GDA and IDA — their 1-to-many and
N-to-many primitives are built for scalability: a distribution to millions of
pool members updates only the Pool entity on-chain (one event), so individual
PoolMember records on the subgraph won't reflect the new state until each
member transacts. Use
or
for real-time
reads. The subgraph is best for historical queries, event indexing, and
listing/filtering entities.
For entity schemas and query construction patterns, see the
"Querying indexed data" use-case section above.
Endpoint pattern:
https://subgraph-endpoints.superfluid.dev/{network-name}/{subgraph}
| Subgraph | Path | Notes |
|---|
| Protocol | | Main protocol data (streams, tokens, accounts) |
| Vesting Scheduler | | All versions: v1, v2, v3 |
| Flow Scheduler | | |
| Auto-Wrap | | |
Network names are canonical Superfluid names (
,
, etc.). Use
node metadata.mjs subgraph <chain>
to get the
resolved URL for a specific chain.
Apps
Sentinels
Sentinels monitor streams and liquidate senders whose Super Token balance
reaches zero, keeping the protocol solvent. Anyone can run one.
| Tool | Purpose |
|---|
| Graphinator | Lightweight subgraph-based sentinel |
Foundation, DAO & SUP Token
Superfluid Foundation — independent entity overseeing long-term protocol
stewardship. Provides governance facilitation, administrative, and legal
support.
Superfluid DAO — community-driven governance. Includes a Security Council
that handles routine protocol upgrades. Proposals discussed on the
forum, voted on via
Snapshot (
).
Delegate SUP at
claim.superfluid.org/governance.
SUP token — a SuperToken on Base. Address:
0xa69f80524381275a7ffdb3ae01c54150644c8792
. Total supply: 1,000,000,000.
Future inflation at DAO discretion.
CoinGecko
Distribution:
- 60% community — distributed via Streaming Programmatic Rewards (SPR)
over at least 2 years in quarterly seasons. SPR streams token rewards
continuously (alternative to one-off airdrops). Sub-split between DAO
treasury and foundation funds.
- 25% development team — 3-year lockup stream with 1-year cliff.
- 15% early backers — same 3-year lockup with 1-year cliff.
Locker / Reserve system — on-chain staking mechanism (FluidLocker
contract). Holders lock SUP and choose unlock duration — longer lockup = bigger
bonus, early unlock incurs a tax. Terminology: "Locker" in contracts, "Reserve"
in the UI and marketing (e.g. the Claim app).
Processes
Token Listing — a Super Token gets listed on the on-chain Resolver, which
the subgraph picks up (marks
). Once listed, it appears in the
Superfluid token list along with its underlying token (if any).
Automation Allowlisting — required for automations (vesting, flow
scheduling, auto-wrap) to appear in the Dashboard UI and for Superfluid
off-chain keepers to trigger the automation contracts. Without allowlisting,
automations won't be executed on time and are effectively useless.
- Request: allowlisting form
- Check status:
GET https://allowlist.superfluid.dev/api/allowlist/{account}/{chainId}