Superfluid Protocol スキル

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

開発者トラック

まずトラックを決定してから、以下のユースケースマップを参照してください。

スマートコントラクト開発: SuperTokenV1Library、CFASuperAppBase、MacroForwarder、Host を経由した生の Agreement。ABI ソース: @superfluid-finance/ethereum-contracts。アドレス: @superfluid-finance/metadata + tokenlist。データ: オンチェーン呼び出し。主要なリファレンス: .abi.yaml ファイル、super-apps.md、macro-forwarders.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）— 中央ルーター。Agreement 呼び出しは Host.callAgreement() または Host.batchCall() を通じて行われます。アプリレジストリ、ガバナンス、SuperTokenFactory を管理します。

Agreement — トークンにデータを保存するステートレスな金融プリミティブ: CFA（1:1 ストリーム）、GDA（プール経由の多対多）、IDA（非推奨、GDA に置き換え）。

Super Token — ERC-20/ERC-777/ERC-2612 リアルタイムバランス機能付き。3 つのバリアント: Wrapper（ERC-20 支援）、Native Asset/SETH（ETH 支援）、Pure（事前に鋳造）。

Forwarder（CFAv1Forwarder、GDAv1Forwarder）— 便利なラッパー。各呼び出しは、読み取り可能なウォレット説明を備えたスタンドアロントランザクションです。バッチ化できません — 原子性のために Host.batchCall と生の Agreement 呼び出しを使用します。

MacroForwarder — 拡張可能なバッチエグゼキューター。開発者はカスタムマクロコントラクト（IUserDefinedMacro）をデプロイし、MacroForwarder.runMacro() を呼び出して複雑なマルチステップ操作を原子的に実行します。references/guides/macro-forwarders.md を参照してください。

オートメーション（Vesting Scheduler、FlowScheduler、Auto-Wrap）— オンチェーンの意図をスケジュールし、オフチェーンキーパーが実行をトリガーすることを必要とします。

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

タスクに必要なファイルのみを読んでください。各 Rich ABI YAML は 1 つのコントラクトのすべてのパブリック関数、イベント、エラーをドキュメント化しており、シグネチャからは明らかでない非明白な動作、エッジケース、および一般的な間違いにフラグを立てる 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 Apps、オートメーションコントラクト、DeFi インテグレーション）で使用します。Agreement に抽象化された関数（flowX、transferX）を含み、これらは CFA または GDA に自動ルーティングされ、Super App コールバック用の WithCtx バリアントも含まれます。YAML ヘッダーと用語集を参照して Foundry テストの落とし穴を確認してください。

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 Apps は アプリクレジット を使用します — ゼロバランス操作を可能にする一時的な預金許可。1:1 リレー（1 入力、1 出力、同じレート）は常にトークンなしで機能します。ファンアウト（1:N）では、アプリが追加の預金用のトークンを保持する必要があります。送信者のロック済みキャピタルはおおよそ 2 倍になります（これは発信ストリーム預金が送信者の保有する負債として補われるためです）。アプリクレジットは CFA のみです — GDA にはアプリクレジットルールがありません。下記の一般的な落とし穴を参照してください。 完全なガイドについては references/guides/super-apps.md を参照してください。

マクロフォワーダー（構成可能なバッチ操作）

• 複雑なバッチ操作用のマクロを記述 → references/guides/macro-forwarders.md
• MacroForwarder コントラクトアドレスとインターフェース → また references/guides/macro-forwarders.md
• バッチ操作タイプとエンコードルール → また references/contracts/Superfluid.abi.yaml（batch_operation_types）
• EIP-712 署名されたマクロパターン → references/guides/macro-forwarders-eip712-example.md
• Clear Signing — MacroForwarder をネイティブ EIP-712 クリアサイニング（Super Token 操作用）で置き換えます。人間が読める取引表示（多言語）、第三者リレー（msg.sender に限定されない）、ガスレストランザクション（手数料は Super Token で支払い）、およびカスタム手数料スキーム。https://tokens.superfluid.org/clear

センチネルと清算

• クリティカルフローのバッチ清算 → references/contracts/BatchLiquidator.abi.yaml
• PIC オークション、ボンド管理、終了レート → references/contracts/TOGA.abi.yaml

SUP トークン / Reserve システム

コントラクトは内部的に「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
• 時間遅延ストリーム経由で SUP をアンロック（Fontaine） → 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 サービス（CMS）を参照
• ストリーム会計、1 日単位のチャンキング → API サービス（Accounting）を参照
• ENS / Farcaster / Lens ハンドルを解決 → API サービス（Whois）を参照
• GraphQL 経由でプロトコルデータをクエリ → サブグラフを参照
• センチネル / 清算ボットを実行 → センチネルを参照
• Super Token をリストに取得 → https://tokens.superfluid.org/listing（GitHub 経由で提出） — プロセスも参照

ストリーミングバランスの表示（フロントエンド）

• リアルタイムストリーミングバランスカウンターをアニメーション化 → references/guides/flowing-balances.md ガイドを最初に読んでください — 本番対応の実装（React、バニラ JS、Vue、Svelte、Solid）があります。ストリーミングバランスコードをゼロから生成しないでください。
• ストリーミングバランス表示のレイアウトシフト / ジャンピングを修正 → また references/guides/flowing-balances.md
• Wei 金額、フロー率、トークン価格をフォーマット → また references/guides/flowing-balances.md

エコシステムの深い掘り下げ

• プロトコル履歴、設立、エクスプロイト、SUP ローンチ → references/deep-researches/superfluid-history.md
• Semantic Money 正式仕様（yellowpaper、Haskell リファレンス、BasicParticle、Agreement 階層） → references/deep-researches/semantic-money-yellowpaper.md
• GDA スケーラビリティ（PDPool 数学、O(1) 配信、丸めモデル、settle-on-write） → references/deep-researches/gda-scalability.md
• GoodDollar（G$ Pure Super Token on Celo、UBI、ストリーミング） → references/deep-researches/gooddollar.md
• Flow State（Streaming Quadratic Funding、協調型） → references/deep-researches/flowstate.md
• ERC-8004 エージェントプール（AI エージェント ID + Base 上の GDA 配信） → references/deep-researches/erc8004-agent-pools.md
• Planet IX（GameFi、CFA、カスタム Super Token、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 Token、GDA ステーキング） → references/deep-researches/streme.md

Superfluid チームブランド & デザイン

• カラーパレット、タイポグラフィ、ビジュアルアイデンティティ → references/guides/brand-design.md Superfluid チームの製品デザインをカバーしており、より広いプロトコルエコシステムではありません。

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

• Yellowpaper の基礎（支払いプリミティブ、価値の保存、Agreement フレームワーク） → 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

各 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 プール接続 vs メンバーシップ — プールメンバーシップは無制限です（アカウントは任意の数のプールにユニットを保持できます）。ただし、アカウントあたりトークンあたり 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 Apps を呼び出すことを防ぎます。下流の Super Apps で合成するには、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 に再配布されます。すべてのアンロック（即座を含む）には msg.value の 0.0001 ETH（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 にクランプされます — balanceOf は ERC-20 互換性のため max(0, availableBalance) を返します。アクティブな発信ストリームを持つアカウントはネガティブ（クリティカル）になることができますが、balanceOf は依然 0 を表示します。ネガティブバランスを検出するには realtimeBalanceOfNow を使用してください — ネガティブな availableBalance はアカウントがクリティカルで清算を待っていることを意味します。清算されると、バランスは 0 にリセットされます。

Rich ABI YAML の読み方

YAML ファイルを解析するための重要な規則:

• 予約されたルートキー: meta、events、errors — その他のすべてのルートキーは 関数 です。
• ctx: bytes パラメータ = 関数は Host（callAgreement / batchCall）を通じて呼び出され、直接呼び出されることはありません。
• notes: フィールド — 正確性にとって最も重要なフィールド。関数に存在し、コントラクトレベルでは meta.notes: として存在します。非明白な動作、エッジケース、一