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 (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.

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)

Distributing to many recipients (GDA)

Token operations

Automation

Writing Solidity integrations (SuperTokenV1Library)

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

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.

Sentinels and liquidation

Legacy

Ecosystem & tooling

Debugging Reverts

Error prefixes map to contracts:

Each YAML's errors: section is the complete error index for that contract, with selector hashes and descriptions. Per-function errors: 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: meta, events, errors. Every other root-level key is a function.

Function entries

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, mutability, access, inputs, outputs, emits, errors. All are omitted when not applicable.

Key conventions

• •ctx: bytes parameter = function is called through the Host (callAgreement / batchCall), never directly.
• •access labels: anyone, host, self, admin, governance, sender, receiver, operator, manager, pic, agreement, trusted-forwarder, factory, super-app. Combine with |. Conditional: anyone(if-critical-or-jailed).
• •emits and errors ordering carries meaning: matches execution flow, not alphabetical. First errors in the list are the most likely causes.
• •# GOTCHA: prefix flags non-obvious behavior, common mistakes, or edge cases. Pay close attention to these.
• •meta.source is an array of raw GitHub URLs to the Solidity source files (implementation, interface, base — filenames are self-documenting).
• •meta.deployments has per-network addresses split into mainnet and testnet subgroups.

Events section

events:
  FlowUpdated:
    indexed:              # log topics (filterable)
      - token: address
      - sender: address
    data:                 # log payload
      - flowRate: int96

Errors section

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 — @sfpro/sdk package + scripts/abi.mjs

The @sfpro/sdk package provides typed JSON ABIs for use with viem / wagmi / ethers. ABIs are split across sub-paths:

The SDK also exports chain-indexed address objects alongside each ABI:

Each export is an object keyed by chain ID:

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 @sfpro/sdk — do NOT hand-craft ABI fragments (risk of phantom parameters) or hardcode contract addresses (they vary per network). Use scripts/abi.mjs 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 (CFAv1Forwarder) and short aliases (cfa, host, pool, token, vesting, etc.).

Token list — scripts/tokenlist.mjs

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 superTokenInfo.type field determines which ABI patterns apply:

• •Wrapper → upgrade/downgrade work; underlyingTokenAddress is provided. Underlying ERC-20 approval uses underlying's native decimals; Super Token functions always use 18 decimals.
• •Native Asset → use upgradeByETH/downgradeToETH instead.
• •Pure → upgrade/downgrade revert; no wrapping.

Super Token balance — scripts/balance.mjs

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 — scripts/metadata.mjs

Source: @superfluid-finance/metadata npm package. Resolves contract addresses, subgraph endpoints, and network info for any Superfluid-supported chain. Use when meta.deployments 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: host, cfaV1, cfaV1Forwarder, gdaV1, gdaV1Forwarder, superTokenFactory, toga, vestingSchedulerV3, flowScheduler, autowrap, batchLiquidator, etc.

On-chain reads — cast call

cast performs read-only eth_call queries against any contract. If cast is not installed locally, use bunx @foundry-rs/cast instead.

Never use cast send 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. optimism-mainnet, base-mainnet, eth-mainnet).

Examples:

# 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 abi.mjs to look up exact function signatures and metadata.mjs / tokenlist.mjs 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 @sfpro/sdk. 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 scripts/metadata.mjs. Repo
• •Finding token addresses — @superfluid-finance/tokenlist based on @uniswap/token-lists, wrapped by scripts/tokenlist.mjs. Repo

Deprecated — do not recommend for new projects:

API Services

• •Super API — wrapped by scripts/balance.mjs. 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, resolve takes an address and reverse-resolve takes a name.

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 cast call or scripts/balance.mjs for real-time reads. The subgraph is best for historical queries, event indexing, and listing/filtering entities.

Endpoint pattern: https://subgraph-endpoints.superfluid.dev/{network-name}/{subgraph}

Network names are canonical Superfluid names (optimism-mainnet, base-mainnet, etc.). Use node metadata.mjs subgraph <chain> to get the resolved URL for a specific chain.

Apps

Repos: Dashboard · Explorer · TOGA

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 (superfluid.eth). 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).

Links: Website · Blog · Forum · Claim app · Token launch announcement

Processes

Token Listing — a Super Token gets listed on the on-chain Resolver, which the subgraph picks up (marks isListed). Once listed, it appears in the Superfluid token list along with its underlying token (if any).

• •Request: listing form → opens issue in superfluid-org/assets

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}