superfluid

Superfluid Protocol スキル

Rich ABI YAML リファレンスによる Superfluid Protocol スマートコントラクトの完全なインターフェースドキュメントです。プロトコルのアーキテクチャ全体については、references/guides/architecture.md をお読みください。このファイルでは、ユースケースに適したリファレンスを示します。

開発者向けトラック

まずトラックを特定し、以下のユースケースマップに従ってください。

スマートコントラクト開発者： SuperTokenV1Library、CFASuperAppBase、BlindMacroForwarder/ClearMacroForwarder、Host 経由の生のアグリーメント。ABI ソース：@superfluid-finance/ethereum-contracts。アドレス：@superfluid-finance/metadata + tokenlist。データ：オンチェーン呼び出し。主なリファレンス：.abi.yaml ファイル、super-apps.md、macro-forwarders.md、clear-macro.md。

アプリ（フロントエンド／バックエンド）開発者： @sfpro/sdk（ABI、wagmi フック、アドレス）、サブグラフ、API サービス。ABI ソース：@sfpro/sdk。アドレス：@superfluid-finance/metadata + tokenlist。データ：サブグラフ + API サービス。主なリファレンス：sdks.md、api-services.md、サブグラフガイド。

調査（単発）： スクリプト（tokenlist.mjs、metadata.mjs、balance.mjs、cast call）。ABI ソース：scripts/abi.mjs。アドレス：scripts/metadata.mjs + tokenlist.mjs。データ：cast call + scripts/balance.mjs。主なリファレンス：scripts.md。

SDK のインポートパス、ABI テーブル、非推奨パッケージに関する警告については、references/guides/sdks.md をご覧ください。 スクリプトのコマンド構文と例については、references/guides/scripts.md をご覧ください。

アーキテクチャの概要

Host（Superfluid.sol）— 中央ルーターです。アグリーメントの呼び出しは Host.callAgreement() または Host.batchCall() を経由します。アプリレジストリ、 ガバナンス、SuperTokenFactory を管理します。

アグリーメント — トークン上にデータを保存する、ステートレスな金融プリミティブです： CFA（1 対 1 のストリーム）、GDA（プールを介した多対多）、IDA（非推奨、GDA に置き換え）。

Super Token — リアルタイム残高に対応した ERC-20/ERC-777/ERC-2612 です。3 つの バリアントがあります：Wrapper（ERC-20 担保）、Native Asset/SETH（ETH 担保）、Pure （事前発行）。

フォワーダー（CFAv1Forwarder、GDAv1Forwarder）— 便利なラッパーです。各 呼び出しは、ウォレットに読みやすい説明が表示される独立したトランザクションです。バッチ処理はできません。アトミック性が必要な場合は、生のアグリーメント呼び出しを使って Host.batchCall を使用してください。

BlindMacroForwarder（旧称 MacroForwarder；SDK：blindMacroForwarderAbi、アドレス 0xFD0268E33111565dE546af2675351A4b1587F89F）— 拡張可能なバッチ実行機能です。開発者は カスタムマクロコントラクト（IUserDefinedMacro）をデプロイし、runMacro() を呼び出して、複数の手順を含む複雑な 操作をアトミックに実行します。呼び出し元は署名者である必要があります。レガシー — 新しい統合では ClearMacroForwarder に置き換えられています：セルフリレーのみ対応し、呼び出し元は読み取り不可能な生の calldata を ウォレットでブロードキャストします。references/guides/macro-forwarders.md をご覧ください。

ClearMacroForwarder（SDK：clearMacroForwarderAbi、アドレス 0xC1EaB73855155D4e021f7EB4f866996Bac2fe25e、 約 16 のネットワークにデプロイ済み）— 推奨されるデフォルトであり、BlindMacroForwarder に置き換わるものです。 EIP-712 署名方式のマクロ実行機能で、人間が読めるクリア署名、 第三者によるリレー、オプションの Permit2 トークンアップグレードを 1 つの署名で実行できます。2 つのモードがあります：セルフ送信（security.provider = "self"）とプロバイダーリレー（リレイヤーが Host SimpleACL ロールを保持）。references/guides/clear-macro.md および references/contracts/ClearMacroForwarder.abi.yaml をご覧ください。

自動化（Vesting Scheduler、FlowScheduler、Auto-Wrap）— オンチェーンの意図をスケジュールし、実行のトリガーにはオフチェーンのキーパーが必要です。

ユースケース → リファレンスマップ

タスクに必要なファイルのみをお読みください。Rich ABI YAML には、各コントラクトのすべての 公開関数、イベント、エラーに加え、シグネチャだけではわかりにくい動作、エッジケース、よくあるミスを示す notes: フィールドが記載されています。

ストリーミング送金（CFA）

• ストリームの作成／更新／削除（シンプル） → references/contracts/CFAv1Forwarder.abi.yaml
• ACL、オペレーター権限、フローメタデータ → references/contracts/ConstantFlowAgreementV1.abi.yaml も参照
• 他の操作と合わせてストリームをアトミックにバッチ処理 → references/contracts/Superfluid.abi.yaml も参照（Host バッチ呼び出し）

多数の受取人への分配（GDA）

• プールの作成、分配、プールへのストリーム配信 → references/contracts/GDAv1Forwarder.abi.yaml
• プールメンバーの管理、ユニット、請求 → references/contracts/SuperfluidPool.abi.yaml も参照
• Agreement の低レベルな詳細 → references/contracts/GeneralDistributionAgreementV1.abi.yaml も参照
• GDA がどのように O(1) のスケーラビリティを実現するか（数学的な詳細解説） → references/deep-researches/gda-scalability.md も参照

トークン操作

• ラップ／アンラップ、残高、ERC-20/777、permit → references/contracts/SuperToken.abi.yaml
• 新しい Super Token のデプロイ → references/contracts/SuperTokenFactory.abi.yaml

自動化

• クリフとストリームを使った権利確定 → references/contracts/VestingSchedulerV3.abi.yaml
• 将来のストリーム開始／停止のスケジュール設定 → references/contracts/FlowScheduler.abi.yaml
• Super Token の残高が少なくなったときに自動ラップ → references/contracts/AutoWrapManager.abi.yaml と references/contracts/AutoWrapStrategy.abi.yaml

Solidity 統合の作成（SuperTokenV1Library）

• トークン中心の Solidity API（using SuperTokenV1Library for ISuperToken） → references/contracts/SuperTokenV1Library.abi.yaml

このライブラリは CFA および GDA の Agreement 呼び出しを、token.flow(receiver, flowRate) のような使いやすいメソッドにラップします。Superfluid と連携するあらゆる Solidity コントラクト（Super App、自動化コントラクト、DeFi 統合）で使用してください。Agreement を抽象化した関数（flowX、transferX）も含まれており、CFA または GDA に自動で振り分けられます。また、Super App コールバック用の WithCtx バリアントも含まれています。Foundry のテストで注意すべき点については、YAML ヘッダーと用語集を参照してください。

Super Apps の構築

• アプリクレジット、コールバックのライフサイクル、ジェイル、アプリレベル → references/guides/super-apps.md
• CFA コールバックフック（簡易ベース） → references/contracts/CFASuperAppBase.abi.yaml
• コールバックロジック向けのトークン中心 API → references/contracts/SuperTokenV1Library.abi.yaml（WithCtx バリアントを使用）
• アプリ登録、Host コンテキスト、バッチ呼び出し → references/contracts/Superfluid.abi.yaml
• スマートコントラクトのパターン（GDA プール、コールバック、カスタムトークン、自動化、プロキシ） → references/guides/smart-contract-patterns.md

受信ストリームを中継する Super App は、残高がゼロでも動作できるようにする一時的なデポジット許容量であるアプリクレジットを使用します。1:1 の中継（入出力が各 1 つで、レートが同じ）は、トークンがなくても常に機能します。ファンアウト（1:N）には、追加のデポジット用にアプリがトークンを保有している必要があります。送信者のロックされた資金は、およそ 2 倍になります。これは、送信ストリームのデポジットが、送信者に課される負債として担保されるためです。アプリクレジットは CFA のみが対象です。GDA にはアプリクレジットのルールはありません。詳しくは、以下の「よくある注意点」を参照してください。詳細なガイドは references/guides/super-apps.md を参照してください。

マクロフォワーダー（組み合わせ可能なバッチ操作）

• 複雑なバッチ操作用のマクロを作成 → references/guides/macro-forwarders.md
• BlindMacroForwarder（旧 MacroForwarder）のコントラクトアドレスとインターフェイス → references/guides/macro-forwarders.md；ClearMacroForwarder が blind の後継となる理由 → references/guides/macro-forwarders.md
• バッチ操作の種類とエンコード規則 → references/contracts/Superfluid.abi.yaml（batch_operation_types）も参照
• EIP-712 署名付きマクロのパターン → references/guides/macro-forwarders-eip712-example.md
• ClearMacroForwarder — SDK に同梱（clearMacroForwarderAbi、clearMacroForwarderAddress、メタデータキー contractsV1.clearMacroForwarderV1WithPermit2）。約 16 のネットワークに 0xC1EaB73855155D4e021f7EB4f866996Bac2fe25e としてデプロイされています。人が読めるウォレットプロンプト、サードパーティープロバイダーによるリレー、1 つの署名による任意の Permit2 トークンアップグレードに対応する EIP-712 クリア署名を提供します。2 つのモードがあります。セルフ送信（security.provider = "self"、トランザクション実行者 = 署名者）と、プロバイダーリレー（リレー担当者が Host SimpleACL ロールを持ち、署名者のガス代負担なしで実行できるフローを実現）です。 → references/guides/clear-macro.md、references/contracts/ClearMacroForwarder.abi.yaml、references/contracts/ClearMacroBase.abi.yaml

センチネルと清算

• 重要なフローの一括清算 → references/contracts/BatchLiquidator.abi.yaml
• PIC オークション、ボンド管理、退出レート → references/contracts/TOGA.abi.yaml

SUP トークン／リザーブシステム

コントラクト内部では「FLUID」と「Locker」を使用していますが、一般向けの名称は「SUP」と「Reserve」です。

• SUP のロック、ステーク、ステーク解除、LP の提供、ロック解除 → references/contracts/FluidLocker.abi.yaml
• ユーザー用の Reserve（Locker）を作成 → references/contracts/FluidLockerFactory.abi.yaml
• エミッションプログラムから請求（署名済みメッセージ） → references/contracts/FluidLocker.abi.yaml および references/contracts/FluidEPProgramManager.abi.yaml
• エミッションプログラムの作成／資金提供／停止 → references/contracts/FluidEPProgramManager.abi.yaml
• ステーカーと LP への税の分配を把握 → references/contracts/StakingRewardController.abi.yaml
• 時間遅延付きストリーム（Fontaine）を介して SUP のロックを解除 → references/contracts/FluidLocker.abi.yaml および references/contracts/Fontaine.abi.yaml

ERC-8004 エージェントプール

• ERC-8004 標準、Identity／Reputation／Validation レジストリ、AgentPoolDistributor の統合 → references/deep-researches/erc8004-agent-pools.md
• GDA プールの仕組み（ユニット、請求、接続） → references/contracts/GDAv1Forwarder.abi.yaml および references/contracts/SuperfluidPool.abi.yaml

インデックス化されたデータのクエリ（サブグラフ）

• The Graph によるクエリスキーマの生成方法と、複数領域にまたがる注意点を把握 → references/subgraphs/_query-patterns.md
• ストリーム、プール、トークン、アカウント（エンティティ）をクエリ → references/subgraphs/protocol-v1-guide.md および protocol-v1-entities.graphql も参照
• プロトコルイベント（フローの更新、清算、分配）をクエリ → references/subgraphs/protocol-v1-guide.md および protocol-v1-events.graphql も参照
• ベスティングスケジュールと実行履歴をクエリ → references/subgraphs/vesting-scheduler-guide.md および vesting-scheduler.graphql も参照
• スケジュール済みフローと自動化タスクをクエリ → references/subgraphs/flow-scheduler-guide.md および flow-scheduler.graphql も参照
• 自動ラップのスケジュールと実行履歴をクエリ → references/subgraphs/auto-wrap-guide.md および auto-wrap.graphql も参照
• SUP ロッカー、ステーキング、エミッションプログラム、ロック解除履歴をクエリ → references/subgraphs/sup-subgraph-guide.md および sup-subgraph.graphql も参照

レガシー

• 旧 IDA（即時分配、非推奨） → references/contracts/InstantDistributionAgreementV1.abi.yaml

エコシステムとツール

• SDK のインポートパス、ABI テーブル、パッケージの選択 → references/guides/sdks.md
• スクリプトコマンドの構文と例 → references/guides/scripts.md
• API エンドポイントの詳細、Swagger リンク、注意点 → references/guides/api-services.md
• SUP トークン、ガバナンス、DAO、分配 → references/guides/sup-and-dao.md
• トークン価格、フィルタリング済みトークン一覧、CoinGecko ID → 下記の API Services（CMS）を参照
• ストリームの会計処理、日ごとの分割 → 下記の API Services（Accounting）を参照（CFA + ERC-20 のみ、GDA は対象外）
• 包括的な残高／特定時点の（過去の）残高／バッファー + 接続済み + 切断済みの内訳／CSV エクスポート（CFA + GDA + IDA） → 下記の API Services（Balance API）を参照
• 会計／税務レポートの生成またはディープリンク → https://reporter.superfluid.org; パラメーター仕様：https://reporter.superfluid.org/llms.txt
• ENS／Farcaster／Lens のハンドルを解決 → 下記の API Services（Whois）を参照
• GraphQL でプロトコルデータをクエリ → 下記の Subgraphs を参照
• センチネル／清算ボットを実行 → 下記の Sentinels を参照
• Super Token をリストに掲載 → https://tokens.superfluid.org/listing （GitHub 経由で申請）— 下記の Processes も参照

流動残高の表示（フロントエンド）

• リアルタイムのストリーミング残高カウンターをアニメーション表示する → references/guides/flowing-balances.md まずガイドを読んでください — 本番環境ですぐに使える実装（React、vanilla JS、Vue、Svelte、Solid）が掲載されています。流動残高のコードをゼロから生成しないでください。
• 流動残高表示のレイアウトシフト／揺れを修正する → references/guides/flowing-balances.md も参照してください
• wei の金額、フローレート、トークン価格をフォーマットする → references/guides/flowing-balances.md も参照してください

エコシステムの詳細調査

• プロトコルの歴史、創設、エクスプロイト、SUP のローンチ → references/deep-researches/superfluid-history.md
• Semantic Money の正式仕様（イエローペーパー、Haskell のリファレンス実装、BasicParticle、アグリーメントの階層） → references/deep-researches/semantic-money-yellowpaper.md
• GDA のスケーラビリティ（PDPool の計算、O(1) の分配、丸めのモデル、書き込み時の決済） → references/deep-researches/gda-scalability.md
• GoodDollar（Celo 上の G$ Pure Super Token、UBI、ストリーミング） → references/deep-researches/gooddollar.md
• Flow State（ストリーミング二次ファンディング、協同組合） → references/deep-researches/flowstate.md
• ERC-8004 Agent Pools（Base 上の AI エージェントの ID と GDA による分配） → references/deep-researches/erc8004-agent-pools.md
• Planet IX（GameFi、CFA、カスタム Super Tokens、SuperApp コールバック） → references/deep-researches/planet-ix.md
• Nerite（USND ステーブルコイン、Custom Pure Super Token、CFA+GDA） → references/deep-researches/nerite.md
• SuperBoring（DCA、CFA→GDA TOREX パターン、Superfluid Labs） → references/deep-researches/superboring.md
• TOREX（TWAP Oracle Exchange — ストリーミング DEX、割引モデル、LME 間の追徴／返金、流動性の移動、Twin TOREX） → references/deep-researches/torex.md
• Giveth（手数料無料の寄付、CFA による定期ストリーム） → references/deep-researches/giveth.md
• Streme.fun（トークンローンチャー、Pure Super Tokens、GDA ステーキング） → references/deep-researches/streme.md

Superfluid チームのブランドとデザイン

• カラーパレット、タイポグラフィ、ビジュアルアイデンティティ → references/guides/brand-design.md Superfluid チームのプロダクトデザインを扱っており、プロトコルエコシステム全体は対象としていません。

正式仕様とプロトコル理論

• イエローペーパーの基礎（決済プリミティブ、価値の保存、アグリーメントのフレームワーク） → references/deep-researches/semantic-money-yellowpaper.md
• GDA が無制限の受取人への O(1) ストリーミングを実現する仕組み → references/deep-researches/gda-scalability.md
• BasicParticle とリアルタイム残高の計算式 → references/deep-researches/semantic-money-yellowpaper.md も参照してください

リバートのデバッグ

エラープレフィックスはコントラクトに対応しています。

• CFA_* → ConstantFlowAgreementV1
• CFA_FWD_* → CFAv1Forwarder
• GDA_* → GeneralDistributionAgreementV1
• SUPERFLUID_POOL_* → SuperfluidPool
• SF_TOKEN_* → SuperfluidToken（SuperToken の基底）
• SUPER_TOKEN_* → SuperToken
• SUPER_TOKEN_FACTORY_* → SuperTokenFactory
• HOST_* → Superfluid（Host）
• IDA_* → InstantDistributionAgreementV1
• APP_RULE → Superfluid（Host）— Super App のコールバック違反
• 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 に同梱。複数ネットワークに対応）

各 YAML の errors: セクションには、そのコントラクトのエラー一覧がすべて説明付きで記載されています。関数ごとの errors: フィールドには、特定の関数がスローする可能性のあるエラーが示されています。16 進数のセレクター（関数、イベント、またはエラー）を調べるには、対応する .selectors.yaml ファイルを参照してください。すべての Foo.abi.yaml には、完全なシグネチャと計算済みハッシュを含む Foo.selectors.yaml が同じ場所にあります。

よくある注意点（クイックリファレンス）

一見わかりにくい挙動を抜粋しています。正式な情報源は、.abi.yaml ファイル内の各関数にある notes: フィールドです。全体像を把握するため、必ずそちらをお読みください。このセクションでは、特によくある注意点のみを取り上げます。

Super Token の小数桁数は常に 18 — upgrade() と downgrade() の数量は、基盤となるトークンの小数桁数にかかわらず、常に小数桁数 18 の SuperToken 単位です。スケーリングはコントラクトが内部で処理します。基盤となるトークンの小数桁数が関係するのは、ERC-20 の approve() 呼び出しのみです。例：100 USDC をラップするには、USDC で 100e6 を承認してから、upgrade(100e18) を呼び出します。

GDA のプール接続とメンバーシップ — プールのメンバーシップに上限はなく、アカウントは任意の数のプールでユニットを保有できます。ただし、1 つのトークンにつき、アカウントあたり接続できるプールは 256 個までです。接続されている場合、残高はメンバーの SuperToken 残高に自動的に反映されます。未接続のメンバーは、トークンを受け取るために claimAll() を呼び出す必要があります。balanceOf / realtimeBalanceOf のガス使用量は、接続されたプールの数に比例して増加します。

GDA の分配時の端数処理 — distributeFlow：ユニットあたりのレートは requestedFlowRate / totalUnits です（整数除算のため、切り捨てられます）。端数はプール管理者への調整フローになります。requestedFlowRate < totalUnits の場合、ユニットあたりのレートは 0 に切り捨てられ、フロー全体が管理者に渡されます。distribute（即時）の場合、端数は単にディストリビューターから引き落とされず、実際の分配額は要求額を下回ります。プールは残高を保有せず、トークンはメンバーへ直接流れます。align2 と調整フローの計算を含む端数処理モデルの全容については、references/deep-researches/gda-scalability.md を参照してください。

SuperTokenV1Library の address(this) — 便利な関数（flow、flowX、distribute、distributeFlow、createPool、claimAll）は、暗黙の送信元として msg.sender ではなく address(this) を使用します。Foundry のテストでは、vm.prank を使ってもこの挙動は変わりません。代わりに、送信元／from パラメーターを明示的に指定できる CFA/GDA 固有のオーバーロード関数を使用してください。

CFASuperAppBase の APP_LEVEL_FINAL — CFASuperAppBase は APP_LEVEL_FINAL にハードコードされているため、コールバックから下流の他の Super App を呼び出せません。下流の Super App と組み合わせるには、APP_LEVEL_SECOND を使用したカスタムベースを作成し、host.allowCompositeApp(targetApp) を呼び出してください。チェーンの最大深度は 2 アプリ（SECOND → FINAL）です。

GDA プールはネスト不可 — プールを別のプールのメンバーにすることはできません。メンバーアドレスがプールの場合、updateMemberUnits は SUPERFLUID_POOL_NO_POOL_MEMBERS でリバートします。プールアドレスをプール管理者にすることもできず、その場合は GDA_ADMIN_CANNOT_BE_POOL になります。

FluidLocker の即時アンロックペナルティ — unlockPeriod=0 にすると即時アンロックが発生し、80% のペナルティが課されます。すぐに移転されるのは 20% のみで、残りの 80% はステーカーと LP に再分配されます。即時アンロックを含むすべてのアンロックには、0.0001 ETH の msg.value が必要です（UNLOCKING_FEE。DAO のトレジャリーに送られます）。期間が 7～365 日の場合、アンロック期間中にトークンをストリーミングし、比例課税を適用する Fontaine ビーコンプロキシがデプロイされます。

GDA にはアプリクレジットがない — CFA とは異なり、GDA はアプリクレジットの仕組みをサポートしていません。CFA の流入を受け取り、GDA 経由で分配する Super App は、デポジットバッファを借りることができません。GDA ストリームのバッファデポジットは、独自の残高から資金を拠出するか、ユーザーから ERC-20 の transferFrom で受け取る必要があります。CFA から GDA へのストリーム分割コントラクトが失敗する最もよくある原因です。回避策については、references/guides/smart-contract-patterns.md の § A を参照してください。

balanceOf は 0 に補正される — ERC-20 との互換性のため、balanceOf は max(0, availableBalance) を返します。送信中のストリームがあるアカウントの残高はマイナスになる（重大な状態になる）ことがありますが、balanceOf は 0 を表示します。マイナス残高を検出するには realtimeBalanceOfNow を使用してください。availableBalance がマイナスの場合、そのアカウントは重大な状態にあり、清算を待っています。清算されると、残高は 0 にリセットされます。

Rich ABI YAML の読み方

YAML ファイルを解析する際の基本的な規約：

• 予約済みのルートキー： meta、events、errors — それ以外のすべてのルートキーは関数です。
• ctx: bytes パラメーター = 関数は Host 経由（callAgreement / batchCall）で呼び出され、直接呼び出されることはありません。
• notes: フィールド — 正確性にとって最も重要なフィールドです。関数に記述されるほか、コントラクトレベルでは meta.notes: として記述されます。自明ではない動作、エッジケース、よくある間違いが含まれます。予期しない動作についてユーザーから質問された場合、答えはほぼ必ず notes: フィールドにあります。必ず確認してください。
• access ラベル： anyone、host、self、admin、governance、sender、receiver、operator、manager、pic など。| と組み合わせてください。
• emits と errors の順序は実行フローに一致します（アルファベット順ではありません）。最初に記載されたエラーほど、発生する可能性が高いものです。
• フィールドの順序： 説明コメント、notes、mutability、access、inputs、outputs、emits、errors。

形式の完全な仕様と例（関数エントリー、イベント、エラーの各セクション）については、references/contracts/_rich-abi-yaml-format.md を参照してください。

ランタイムデータ（スクリプト）

スクリプトは、単発の検索に必要なランタイムデータ（アドレス、残高、ABI）を提供します。 bunx -p <pkg> bun <script> で実行します。構文の詳細については、references/guides/scripts.md を参照してください。アプリケーションコードを記述する場合は、代わりに npm パッケージを直接使用してください （上記の開発者トラックを参照）。

• scripts/abi.mjs — JSON ABI の検索と関数シグネチャの確認に使用します。アプリプロジェクト外で ABI を調べる必要がある場合に使用してください。
• scripts/tokenlist.mjs — Super Token のアドレス、シンボル、タイプを確認できます。トークンアドレスを探す場合や、そのタイプを確認する場合に使用してください。
• scripts/balance.mjs — リアルタイムの残高とフローレートを確認できます。アカウントの現在の残高またはネットフローが必要な場合に使用してください。
• scripts/metadata.mjs — コントラクトアドレス、サブグラフのエンドポイント、ネットワーク情報を確認できます。特定のチェーンのアドレスが必要な場合に使用してください。
• cast call — オンチェーンの読み取りを直接行います。スクリプトでは取得できない、コントラクトの最新状態が必要な場合に使用してください。

コマンド構文、引数、例については、references/guides/scripts.md を参照してください。

よく使うコントラクトアドレス

アドレスをハードコードしたり、でっち上げたりしないでください。@sfpro/sdk のアドレス エクスポート（references/guides/sdks.md を参照）または bunx -p @superfluid-finance/metadata bun scripts/metadata.mjs contracts <chain> から取得してください。

Forwarder アドレスは例外で、ほとんどのネットワークで共通です：

• CFAv1Forwarder：0xcfA132E353cB4E398080B9700609bb008eceB125
• GDAv1Forwarder：0x6DA13Bde224A05a288748d857b9e7DDEffd1dE08
• ClearMacroForwarder：0xC1EaB73855155D4e021f7EB4f866996Bac2fe25e（SDK：clearMacroForwarderAddress）
• BlindMacroForwarder（レガシーの MacroForwarder）：0xFD0268E33111565dE546af2675351A4b1587F89F（SDK：blindMacroForwarderAddress）

Host と agreement のアドレスはネットワークごとに異なります。

エコシステム

SDK とパッケージ

有効 — 新規プロジェクトに推奨：

• @sfpro/sdk — フロントエンド／バックエンド用 SDK：ABI、wagmi フック、アクション
• @superfluid-finance/ethereum-contracts — Solidity のビルド時 ABI ソース
• @superfluid-finance/metadata — コントラクトアドレス、ネットワーク情報（依存関係なし）
• @superfluid-finance/tokenlist — リスト掲載済みの Super Token と基盤トークン

使い分け：

• @sfpro/sdk — wagmi／viem を使用するフロントエンド／バックエンド向け
• ethereum-contracts — Solidity との統合向け（ビルド時のみ。ランタイムでは使用しません）
• metadata — ランタイムでのアドレス／ネットワーク解決向け
• tokenlist — トークンアドレスの検索向け

非推奨 — 新規プロジェクトでは推奨しないでください：

• @superfluid-finance/sdk-core → @sfpro/sdk に置き換えられました
• @superfluid-finance/sdk-redux → wagmi と @sfpro/sdk に置き換えられました
• @superfluid-finance/js-sdk → @sfpro/sdk に置き換えられました
• @superfluid-finance/widget → 置き換え先はありません

ABI のインポート表、アドレスエクスポート、SDK の詳細なガイダンス、非推奨 パッケージの詳細については、references/guides/sdks.md を参照してください。

API サービス

• Super API https://superapi.kazpi.com — オンチェーンの Super Token 残高をリアルタイムで取得（現在の残高のみ）
• Balance API https://balances.superfluid.dev — イベントソーシング方式のインデクサー：指定時点・過去の CFA+GDA+IDA 残高（バッファー／接続中／切断中）、スナップショット、レポート、移動を取得できます。読み取り専用で、認証は不要です
• CMS https://cms.superfluid.pro — トークン価格、価格履歴、フィルター付きトークンリスト
• Points https://cms.superfluid.pro/points — SUP ポイントキャンペーン
• Accounting https://accounting.superfluid.dev/v1 — 日ごとの分割に対応したストリーム会計
• Allowlist https://allowlist.superfluid.dev — 自動化の許可リスト登録状況を確認
• Whois https://whois.superfluid.finance — プロフィールを解決（ENS、Farcaster、Lens、AF）
• Token Prices https://token-prices-api.superfluid.dev/v1/{network}/{token} — Super Token の価格（CoinGecko 提供）
• Claim Programs https://claim.superfluid.org/api/programs — SUP 報酬プログラム：シーズン、割り当て、プールアドレス、フローレート

API ごとのエンドポイント、クエリパターン、Swagger／OpenAPI リンク、注意点については、 references/guides/api-services.md を参照してください。

サブグラフ

現在の状態を取得する場合は、サブグラフより RPC を優先してください。 サブグラフは トランザクション時にのみ更新されますが、ストリームは毎秒流れます。リアルタイムの読み取りには、 cast call または scripts/balance.mjs を使用してください。サブグラフは、過去の クエリ、イベントのインデックス作成、エンティティの一覧表示やフィルタリングに最適です。

エンドポイントのパターン：https://subgraph-endpoints.superfluid.dev/{network-name}/{subgraph}

• プロトコル protocol-v1 — プロトコルの主要データ（ストリーム、トークン、アカウント）
• Vesting Scheduler vesting-scheduler — v1、v2、v3 の全バージョン
• Flow Scheduler flow-scheduler
• Auto-Wrap auto-wrap
• SUP（Locker／Reserve）— Goldsky がホスト（Base のみ）。ステーキング、ロック解除、排出プログラム、LP ポジション。

ネットワーク名には、Superfluid の正式名称（optimism-mainnet、 base-mainnet など）を使用します。特定のチェーンの 解決済み URL を取得するには、bunx -p @superfluid-finance/metadata bun metadata.mjs subgraph <chain> を使用してください。

アプリ

• Super Tokens https://tokens.superfluid.org — Super Tokens の公式サイト：ERC20x の概要、Clear Macro、Super App フック、トークン一覧（Clear Macro のデモ：https://tokens.superfluid.org/clear/demo）
• Dashboard https://app.superfluid.org — エンドユーザー向けのストリーム管理
• Explorer https://explorer.superfluid.org — Superfluid Protocol のブロックエクスプローラー
• Claim https://claim.superfluid.org — SUP トークン、SUP ポイント、リザーブ／ロッカー
• TOGA https://toga.superfluid.finance — トークンごとの最近の清算を表示
• Dune https://dune.com/superfluid_hq/superfluid-overview — プロトコルの公式分析ダッシュボード
• Campaigns https://campaigns.superfluid.org — Superfluid を利用した限定 NFT のミントと、SUP 報酬キャンペーン
• x402 https://x402.superfluid.org — HTTP 402 と Superfluid ストリームを利用した、インターネットネイティブなサブスクリプションのオープン標準。一度限りの EIP-712 署名で、ガス代不要、リアルタイムの支払い検証、プロトコル手数料無料。人間のユーザーと AI エージェントの両方に対応します。
• 8004 Agent Pool https://8004-demo.superfluid.org/ — ERC-8004 の ID と Superfluid GDA を利用した AI エージェントプール。エージェントは登録してプールに参加し、比例配分された SUP を獲得できます。
• Reporter https://reporter.superfluid.org — Balance API を使用した会計／税務用 CSV レポート。クエリパラメーター（account、chain、tokens、startDate/endDate、period、export params）によるディープリンクに対応します。パラメーターの仕様：https://reporter.superfluid.org/llms.txt

リポジトリ： Dashboard · Explorer · TOGA · 8004 Demo

コミュニティとソーシャル

• Twitter/X https://x.com/Superfluid_HQ
• Farcaster https://warpcast.com/superfluid
• Discord https://discord.gg/EFAUmTnPd9

センチネル

センチネルはストリームを監視し、Super Token の残高がゼロに達した送信者を清算することで、プロトコルの支払い能力を維持します。誰でも実行できます。

• Graphinator — 軽量なサブグラフベースのセンチネル
• Superfluid Sentinel — 旧式の RPC ベースのセンチネル

Foundation、DAO、SUP トークン

SUP — Base 上の SuperToken（0xa69f80524381275a7ffdb3ae01c54150644c8792）です。 総供給量は10億です。Snapshotを通じて Superfluid DAO がガバナンスを行います。Locker / Reserve はオンチェーンのステーキングメカニズムです（ロック期間が長いほど、ボーナスが大きくなります）。

配布の内訳、Foundation と DAO の役割、ガバナンスの詳細、およびリンクについては、references/guides/sup-and-dao.mdを参照してください。

プロセス

トークンのリスティング — Super Token はオンチェーンの Resolver に登録され、サブグラフがそれを取得して（isListedを設定します）。リスティングされると、基盤となるトークン（存在する場合）とともに Superfluid のトークンリストに表示されます。

• 申請：リスティングフォーム → superfluid-org/assetsにイシューが作成されます

自動化の許可リストへの登録 — 自動化（権利確定、フローのスケジュール設定、自動ラップ）を Dashboard の UI に表示し、Superfluid のオフチェーンキーパーが自動化コントラクトをトリガーするには、この登録が必要です。許可リストに登録されていない場合、自動化は時間どおりに実行されず、実質的に役に立ちません。

• 申請：許可リスト登録フォーム
• ステータスの確認：GET https://allowlist.superfluid.dev/api/allowlist/{account}/{chainId}