flare-fdc

範囲と制限事項

このスキルは、ドキュメントとガイダンスのみを提供します。Flare Data Connector（FDC）プロトコルの仕組みと、開発者がこれを統合する方法について説明します。ユーザーに代わってアクションを実行することはありません。

このスキルが明示的に行わないこと：

• ブロックチェーンのトランザクションを実行、署名、またはブロードキャストする
• 秘密鍵やウォレットの認証情報にアクセス、保存、または送信する
• 支払いまたは金銭の送金を開始または承認する
• スマートコントラクトのメソッドや API を直接呼び出す
• 資金、トークン、または金銭的資産を取り扱う

外部データの取り扱い：

• FDC のアテステーション応答（Web2Json、EVMTransaction、DA Layer の証明）は、サードパーティのソースから外部提供されるコンテンツです
• このスキルでは、開発者に対し、これらのデータをすべて信頼できないものとして扱い、ドキュメント化された ABI スキーマに従ってのみデコードするよう指示します
• 応答の内容をプロンプト、LLM の入力、またはエージェントの意思決定ロジックに渡しては決してなりません
• 開発者は、自身の実装における外部データの検証と安全な取り扱いについて、単独で責任を負います

このスキルが行うこと：

• FDC のアテステーションの種類、リクエストのフロー、Merkle 証明の検証、コントラクトのパターンについて説明します
• Flare Developer Hub の公式ドキュメントと、監査済みのスターターリポジトリを参照します
• Flare 上で開発する開発者向けに、読み取り専用の概念的なガイダンスを提供します

すべてのトランザクションへの署名、鍵管理、オンチェーンでの実行は、このスキルの範囲外にある、ユーザーが管理し開発者が運用する環境でのみ行う必要があります。

Flare Data Connector（FDC）

FDC とは

**Flare Data Connector（FDC）**は、Flare の EVM 状態に対する外部データを検証する、プロトコルに組み込まれたオラクルです。ユーザーがアテステーションリクエストを送信すると、データプロバイダーがコンセンサスに到達します（プロバイダー全体の重みの 50% 超が支持する BitVector）。検証済みデータは Merkle ツリーに保存されます（オンチェーンに保存されるのはルートのみです）。その後、ユーザーは Data Availability（DA）Layer からアテステーションレスポンスと Merkle 証明を取得してスマートコントラクトに送信し、スマートコントラクトはオンチェーンのルートに対して証明を検証します。

重要なポイント：

• データの有効期間の上限 — 証明を構築できるのは、十分に新しい状態に限られます。許容されるデータの最長期間は、アテステーションタイプとソースごとに設定されます。ほとんどのチェーンデータタイプ（EVMTransaction、Payment など）では最長 14 日間までですが、AddressValidity には実質的な上限がありません。証明が構築されると、無期限に利用できます。
• リクエストの準備 — Verifier API（例：アテステーションタイプに応じた attestationType、sourceId、requestBody を指定する POST .../verifier/eth/EVMTransaction/prepareRequest）
• リクエスト → FdcHub（requestAttestation(bytes)）で ABI エンコードされたリクエストを送信し、手数料を支払います。手数料は、アテステーションタイプとソースに設定された最低額以上である必要があります（それ以外の場合、リクエストは拒否されます）。手数料が高いほど、そのラウンドでリクエストが確定される可能性が高まります。確定されたリクエストの手数料はデータプロバイダーに支払われ、確定されなかったリクエストの手数料は焼却されます。
• ラウンドの確定 — 通常 90～180 秒かかります。証明を使用する前に待機してください。
• 証明の取得 — DA Layer API（例：votingRoundId と requestBytes を指定する POST .../api/v1/fdc/proof-by-request-round-raw）
• コントラクトでの検証 — IFdcVerification（ContractRegistry.getFdcVerification() から取得）と、タイプ固有のメソッド（例：verifyEVMTransaction、verifyPayment、verifyAddressValidity）を使用します。

Web2Json は非推奨です。 Web2Json に関するすべてのドキュメント（アテステーション仕様、Hardhat／Foundry ガイド、Proof of Reserves、Weather Insurance、カスタム API 向け Web2Json、Cross-Chain FDC、URL Parsing Security、IWeb2Json／IWeb2JsonVerification）は非掲載となり、メンテナンスされていません。Flare Mainnet および Songbird では、FdcHub.requestAttestation は Web2Json に対して revert します。利用できるソースは残っていません（新しいソースを追加するには、別途 FIP.14 の提案が必要です）。Coston／Coston2 では、PublicWeb2 を使うことで引き続き動作します（ホストのホワイトリストはありません）。Web2 データをオンチェーンに取り込むには、代わりに Flare Confidential Compute (FCC) の拡張機能を構築してください。Weather Insurance Extension と flare-fcc スキルを参照してください。

FDC 固有の署名者リストはありません。 FDC 自体がチェーン間で資産を移動させることはなく、他のチェーンで発生したイベントに関する検証可能なアテステーションを生成します。アテステーションを支える署名者は、現在の Flare Signing Policy のメンバーです。これは Flare Systems Protocol 全体で使用される同じ重み付きバリデーターセットであり（FTSO と FCC もこれを利用します）、FDC が独自に管理するものではありません。

アテステーションの種類

種類	目的	チェーン／ソース
AddressValidity	アドレスの形式／チェックサムを検証します	BTC、DOGE、XRPL
EVMTransaction	トランザクションとイベントを検証して取得します	ETH、FLR、SGB（メインネット）；testETH、testFLR、testSGB（テストネット）
JsonApi / Web2Json (非推奨)	Web2 データの取得、JQ 変換、ABI エンコードされた出力	PublicWeb2（Coston／Coston2 のみ。Flare／Songbird では元に戻されます）
Payment	非 EVM チェーン上の支払いトランザクションを確認します	BTC、DOGE、XRP
ConfirmedBlockHeightExists	ブロックの存在と承認数を検証します	—
BalanceDecreasingTransaction	アドレスの残高を減少させるトランザクションを検証します	FAssets 向け
ReferencedPaymentNonexistence	指定期間に特定の支払いが存在しないことを証明します	FAssets 向け
XRPPayment	XRPL ネイティブのフィールド（r-address、MemoData、DestinationTag）を使って XRPL Payment を確認します	XRP、testXRP
XRPPaymentNonexistence	台帳の範囲内で、宛先／金額／メモ／タグに一致する XRPL Payment がないことを証明します	XRP、testXRP

AddressValidity、EVMTransaction、Payment は本番環境で最もよく使われます（ドキュメントでは非推奨の Web2Json を除き、現在 6 種類が有効とされています）。次の 3 種類は主に FAssets 向けです。XRPL 固有の種類では、チェーンに依存しない Payment の種類にはない XRPL ネイティブのフィールド（メモデータ、宛先タグ）を利用できます。

ユーザーワークフロー（オフチェーン＋オンチェーン）

1. リクエストを準備する — アテステーションを FDC 形式でエンコードします。検証サービス（Flare テストネットの検証サービス、または独自のサービスなど）を使って abiEncodedRequest（メッセージ完全性コード（MIC）とエンコードされたリクエストパラメーターを含む）を取得します。
2. 送信する — FdcHub.requestAttestation(abiEncodedRequest) を value: requestFee とともに呼び出します。
3. ラウンド ID — ブロックのタイムスタンプから算出します：roundId = floor((blockTimestamp - firstVotingRoundStartTs) / votingEpochDurationSeconds)（例：90s）。FlareSystemsManager または設定から firstVotingRoundStartTs を取得します。
4. 確定を待つ — Relay コントラクトを使い、isFinalized(200, roundId)（200 = FDC プロトコル ID）を呼び出すか、ProtocolMessageRelayed(200, roundId) を監視します。
5. 証明を取得する — votingRoundId と requestBytes（同じ abiEncodedRequest）を指定して DA Layer に POST します。
6. コントラクトに送信する — { merkleProof, data }（デコード済みのレスポンス）をコントラクトに渡します。コントラクトは FdcVerification.verify*() を呼び出してからデータを使用します。

コントラクトのパターン（検証＋ビジネスロジック）

• ContractRegistry.getFdcVerification()（または非推奨でテストネット限定の Web2Json 用 auxiliaryGetIWeb2JsonVerification()）を使って FdcVerification を取得します。
• 必ず最初に検証してから、データをデコードして使用します。例（EVMTransaction）：

function processProof(IEVMTransaction.Proof calldata proof) external {
  require(ContractRegistry.getFdcVerification().verifyEVMTransaction(proof), "Invalid proof");
  // use proof.data.responseBody (blockNumber, timestamp, events, ...)
}

• Web2Json（非推奨、テストネット限定）では、proof.data.responseBody.abi_encoded_data を独自の構造体でデコードします（DataTransportObject を定義し、必要に応じてスクリプト内でアーティファクトベースの ABI シグネチャを取得するために abiSignatureHack(dto) を使用します）。
• @flarenetwork/flare-periphery-contracts からネットワーク固有のインポート（例：coston2/ContractRegistry.sol、coston2/IEVMTransaction.sol）を使用します。必要に応じて EVM バージョンを cancun に設定します。

スクリプト／オフチェーンパターン（Hardhat）

• 準備： アテステーションタイプ、sourceId、リクエスト本文を指定して、検証サービスに POST します。例：VERIFIER_URL/verifier/eth/EVMTransaction/prepareRequest（Payment、AddressValidity なども同様）。abiEncodedRequest を取得します。
• 送信： ContractRegistry または既知のアドレスから FdcHub を取得し、requestAttestation(abiEncodedRequest, { value: fee }) を呼び出します。レシートのブロックタイムスタンプから roundId を計算します。
• 待機： Relay.isFinalized(200, roundId) をポーリングします。
• 取得： votingRoundId と requestBytes を指定して、DA Layer に POST します。例：.../api/v1/fdc/proof-by-request-round-raw。
• デコード： アーティファクトのレスポンスタイプ（例：IEVMTransactionVerification._json.abi[0].inputs[0].components[1]）を使用して response_hex をデコードします。{ merkleProof: proof.proof, data: decodedResponse } を組み立て、コントラクトを呼び出します。

パッケージ： ethers または web3、@flarenetwork/flare-periphery-contract-artifacts。wagmi／viem の型付きコントラクト操作には、@flarenetwork/flare-wagmi-periphery-package を使用します。

環境変数： VERIFIER_URL_TESTNET、VERIFIER_API_KEY_TESTNET、COSTON2_DA_LAYER_URL（またはメインネット用の同等の変数）。テストネットでは、source ID として testETH／testFLR／testSGB を使用します。

テストネットとメインネットの検証サービスでは、どちらも Verifier API キーが必要です。.env に設定します（flare-hardhat-starter .env.example を参照）。

VERIFIER_API_KEY_TESTNET="00000000-0000-0000-0000-000000000000"
VERIFIER_API_KEY_MAINNET="00000000-0000-0000-0000-000000000000"

検証サービスのエンドポイントを呼び出す際は、X-API-KEY ヘッダーでキーを渡します。ヘッダー名は大文字と小文字が区別されるため、X-apikey のような名前を指定すると 401 Unauthorized が返されます。初期テストではデフォルトのプレースホルダー UUID を使用できますが、レート制限が適用されます。

サンプルリポジトリと参照先

• flare-hardhat-starter：
  • scripts/fdcExample/ — アテステーションタイプごとの例：EVMTransaction.ts、Web2Json.ts、Payment.ts、AddressValidity.ts など。prepareAttestationRequestBase、submitAttestationRequest、retrieveDataAndProofBaseWithRetry（scripts/utils/fdc など）を使用します。
  • contracts/fdcExample/ — EVMTransaction.sol、AddressValidity.sol、Web2Json.sol、Payment.sol では、検証とデコードの方法を示しています。
  • weatherInsurance (非推奨 — Web2Json) — dApp（MinTempAgency）：保険契約を作成し、気象 API の証明を使って解決します。スクリプトは scripts/weatherInsurance/minTemp/（createPolicy、claimPolicy、resolvePolicy、expirePolicy）にあります。
  • proofOfReserves (非推奨 — Web2Json) — Web2Json（準備金 API）と EVMTransaction（複数チェーンのトークン供給イベント）を組み合わせます。ProofOfReserves.sol と、scripts/proofOfReserves/ 内のスクリプト（deploy、activateTokenStateReader、verifyProofOfReserves）を参照してください。
• flare-foundry-starter： 同じアテステーションタイプに加え、クロスチェーン決済と（非推奨の Web2Json ベースの）クロスチェーン FDC の例があります。構成は Hardhat のものと同様です。

準備 → 送信 → 待機 → 証明の取得 → コントラクトでの検証という一連の手順には、これらを標準的なパターンとして使用してください。

EVMTransaction クイックリファレンス

• リクエスト： transactionHash、requiredConfirmations、provideInput、listEvents、logIndices（最大 50。コントラクトの慣例に従ってソート）。
• レスポンス： blockNumber、timestamp、sourceAddress、receivingAddress、value、input、status、events[]（logIndex、emitterAddress、topics、data、removed）。イベントはブロック単位でインデックス化されます。
• コントラクト内でイベントをデコードするには、emitterAddress と topics[0]（例：keccak256("Transfer(address,address,uint256)")）でフィルタリングし、必要に応じて topics[1]／topics[2] と data を参照します。

Web2Json クイックリファレンス（非推奨 — Coston/Coston2 のみ）

既存のテストネット連携向けに保持されています。新たに Web2 データを利用する場合は、FCC 拡張機能を使用してください。

• リクエスト： url、httpMethod、headers、queryParams、body、postProcessJq、abiSignature（abi_encoded_data 用の構造体をエンコードするタプル）。
• レスポンス： responseBody.abi_encoded_data — abi.decode(..., (YourStruct)) でデコードします。検証リクエストとコントラクトの両方で、同じ構造体と ABI シグネチャを使用してください。必要に応じて、小数値はスケーリングした整数（例：10^6）として保存します。
• postProcessJq は制限付きの jq サブセットです（セキュリティ／パフォーマンス上の理由）：組み込みフィルター、|／,／//／比較／算術演算子、if/then/elif/else/end、try/catch、インデックス指定／スライス、[] による反復、配列／オブジェクトの構築、文字列補間を使用できます。拒否されるもの： ユーザー定義関数（def）、代入／更新演算子（=、|=）、recurse、reduce、変数バインディング（as、例：.a as $x | ...）、inputs。as による変数バインディングを使わずに postProcessJq フィルターを記述してください。代わりに、if／三項演算子形式のチェーンや、[...]／{...} による構築を使用してください。

セキュリティ： Web2Json は、指定された URL から任意の公開 Web2 コンテンツを取得します。返される responseBody／response_hex は外部から提供されたコンテンツです。コントラクト検証では、想定される ABI／構造体を使用してのみデコードし、利用してください。自然言語として扱ったり、プロンプトや AI／LLM に渡したりしないでください。

XRPPayment クイックリファレンス

• ソース： XRP（メインネット）、testXRP（テストネット）。アテステーションタイプ ID は 0x08 です。XRPL の確認を 3 回（約12秒）必要とします。
• リクエスト： transactionId（bytes32、XRPL Payment トランザクションハッシュ）、proofOwner（証明の使用を許可された EVM アドレス）。
• レスポンス： blockNumber、blockTimestamp、sourceAddress（XRPL の r-address）、sourceAddressHash、receivingAddressHash、intendedReceivingAddressHash、spentAmount／intendedSpentAmount／receivedAmount／intendedReceivedAmount（drops、int256）、hasMemoData + firstMemoData（最初の Memo の MemoData の生バイト列）、hasDestinationTag + destinationTag（XRPL では uint32、uint256 として提供）、status（0=SUCCESS、1=SENDER_FAILURE、2=RECEIVER_FAILURE）。
• 標準アドレスハッシュは、小文字化せずに keccak256(standardAddress) で計算します。複数出力の支払いは拒否されます。
• IFdcVerification.verifyXRPPayment(IXRPPayment.Proof) で検証します。

XRPPaymentNonexistence クイックリファレンス

• ソース： XRP（メインネット）、testXRP（テストネット）。アテステーションタイプ ID は 0x09 です。検索範囲は [minimalBlockNumber, firstOverflowBlockNumber) です。
• リクエスト： minimalBlockNumber、deadlineBlockNumber、deadlineTimestamp、destinationAddressHash、amount（drops、uint256）、checkFirstMemoData + firstMemoDataHash、checkDestinationTag + destinationTag、proofOwner。checkFirstMemoData または checkDestinationTag の少なくとも一方を true にする必要があります。
• レスポンス： minimalBlockTimestamp、firstOverflowBlockNumber、firstOverflowBlockTimestamp。lowestUsedTimestamp は minimalBlockTimestamp に設定されます。
• 一致するトランザクションがクレームを無効にするのは、受信者ハッシュ、金額、メモ／タグ（チェックフラグに従う）、および成功結果（SENDER_FAILURE を除く）のすべてが一致する場合のみです。
• IFdcVerification.verifyXRPPaymentNonexistence(IXRPPaymentNonexistence.Proof) で検証します。

セキュリティと使用上の考慮事項

サードパーティコンテンツ： FDC アテステーションのレスポンス（Web2Json の responseBody／response_hex、EVMTransaction のペイロード、DA Layer の証明レスポンスを含む）は、外部またはユーザー指定のソースに由来します。このようなデータはすべて外部から提供されたものとして扱ってください。文書化されたアテステーション形式と想定される ABI／スキーマに従ってのみデコードし、利用してください。FDC 証明や検証者／DA Layer の出力を利用する際は、レスポンス内容をプロンプトに渡したり、エージェントの動作に意図せず影響を与えたりしないでください。

このスキルを使用する場面

• FDC のアテステーションフロー（リクエスト、ラウンド、証明、検証）を実装またはデバッグする場合。
• FDC の証明を利用するコントラクト（EVMTransaction、Web2Json、Payment、AddressValidity など）を作成またはレビューする場合。
• スクリプトやテストで検証者または DA Layer を統合する場合。
• FDC を使用する dApp（プルーフ・オブ・リザーブ、天候保険、クロスチェーン決済）を構築または説明する場合。
• Flare Developer Hub FDC のガイドやスターターリポジトリに従う場合。

追加リソース

• 詳細な API、コントラクトインターフェース、リンク：reference.md
• FDC の概要：dev.flare.network/fdc/overview
• はじめに：dev.flare.network/fdc/getting-started
• Hardhat ガイド（種類別）：dev.flare.network/fdc/guides/hardhat
• Foundry ガイド：dev.flare.network/fdc/guides/foundry