Superfluid Protocol

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

# 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 Signing** — 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 → `