recover-eco-funds

レガシー Eco 資金の回収

概要

レガシーな Circle CLI Eco 入金から、意図データ、返金先、トランザクションの状態を推測せずに資金を回収します。このワークフローは証拠を優先し、デフォルトでは読み取り専用の確認を行います。

レガシーのみの回収： このスキルで実行する回収フェーズは、公開済みのインテントで reward.creator が Circle SCA の API 検証済み eoaOwnerAddress に固定されている入金を対象とします。現在の Gateway v2／Circle CLI の入金では、refundRecipient が SCA に設定され、そこへ直接返金されるはずです。現在の入金については、以下の読み取り専用のステータス確認を行い、SCA と Gateway の残高を照合してください。必要に応じて通常のサポート窓口に問い合わせてください。レガシーのバッキング EOA からのスイープは実行しないでください。

入金の古さやエンドポイントのバージョンだけで、レガシーと判定しないでください。IntentPublished イベントをデコードし、固定された reward.creator を SCA およびその API 検証済み eoaOwnerAddress と比較します。

• reward.creator == eoaOwnerAddress：すべての読み取り専用確認が済んだ後であれば、レガシー回収を適用できる可能性があります。
• reward.creator == SCA：現在の SCA への直接返金動作です。実行可能なレガシーフェーズに進む前に停止してください。
• いずれでもない：選択した Circle ウォレットは固定された返金先を所有していないため、停止してください。

Eco 入金がなく、USDC が Agent Wallet のバッキング EOA に単に送られた場合（CLI がそのアドレスに対して「Wallet not found」と報告する場合）は、フェーズ 1 と 2 を省略し、フェーズ 3 に進んでください。

Circle CLI がインストールされていない、Terms の確認が未完了、またはエージェントセッションが無効な場合は、まず use-circle-cli と use-agent-wallet のスキルを使用してください。ログイン要求を複数回送信しないでください。新しい要求を送信するたびに、以前の OTP は無効になります。

2 つの回収手順を理解する

レガシー Eco 入金では、次の 2 つの操作が別々に必要になる場合があります。

1. Eco の自己返金： 報酬期限の経過後、ボールト／返金チェーンで Portal.refund(destination, routeHash, reward) を呼び出します。Portal はインテントを検証し、決定論的なボールトに指示して、資金を reward.creator に返します。この呼び出しは誰でも中継できますが、返金先は元のインテントで固定されています。
2. バッキング EOA からのスイープ： reward.creator が SCA のバッキング EOA だった場合、ERC-3009 を使用して、その EOA からリンクされた SCA へ USDC を移動することを承認します。SCA がトークン呼び出しを中継してガス代を支払うため、バッキング EOA にネイティブトークンのガス代は必要ありません。

現在の Gateway v2／Circle CLI Eco 入金では、SCA が返金先に設定されます。このスキルの実行対象外です。ステータスと残高を照合し、バッキング EOA からのスイープは実行しないでください。

安全境界

• イベント／作成チェーン、Vault／返金チェーン、インテントの宛先値、Gateway の宛先チェーン、SCA、バックアップ EOA、作成チェーンの Portal、返金チェーンの Portal、Vault、トークン、金額、ルートハッシュ、インテントハッシュ、期限はそれぞれ異なるフィールドとして扱ってください。互いに置き換えてはいけません。合成された Eco フローでは、あるチェーンにイベントを公開しつつ、返金可能な Vault を別のチェーンに残すことができます。また、Portal のデプロイアドレスはチェーン間で一致するとは限りません。
• バックアップ EOA は Circle ウォレット API の eoaOwnerAddress から導出してください。ユーザーが指定したオーナーを、このフィールドと照合せずに受け入れてはいけません。
• 旧式のセルフ返金をブロードキャストする前に、reward.creator が選択した Circle ウォレットの API で検証済みの eoaOwnerAddress と一致することを必須にしてください。SCA と一致する場合は、現在の SCA への直接送金フローとして分類し、実行可能な復旧処理の前に停止してください。refund(...) はパーミッションレスですが、無関係なウォレットへの返金にユーザーのガス代を使ってはいけません。
• 返金タプルは、ソースチェーンの IntentPublished イベントから再構成してください。Eco ステータス API は参考情報として有用ですが、calldata の構築に使うには十分な権威がありません。
• 再構成したインテントハッシュが、イベントのインデックス付きインテントハッシュと一致することを検証してください。
• オンチェーンの期限前、またはリワードのステータスがすでに Withdrawn か Refunded の場合は、返金を拒否してください。
• ブロードキャスト前に、正確な SCA から正確な calldata をシミュレーションしてください。
• 資金を移動する各操作の直前に、明示的な承認を求めてください。チェーン、トークン、生の金額と小数表記の金額、送信元、送信先、コントラクト、インテント／nonce、推定ガス代を提示してください。
• 実行予定のブロードキャストごとに、永続化された冪等性キーを1つ使用してください。応答が不明瞭な場合は、何か新しい操作を試みる前にオンチェーンの状態を照合してください。
• ユーザートークン、セッションシークレット、OTP、秘密鍵、生の EIP-712 署名をログに記録してはいけません。代わりに署名ハッシュを記録してください。
• CIRCLE_PROXY_URL で Circle のデフォルトが上書きされている場合は、正確なオリジンを確認し、エージェントのセッショントークンを経由して送信する前に、ユーザーから明示的な信頼を得てください。Phase 2 のヘルパーでは、上書きがある場合に --allow-proxy-origin <scheme://host> が必要です。Phase 3 のスクリプトは Circle の本番環境のみと通信し、上書きが設定されている間は実行を拒否します。
• 近道として refundTo(...) を使ってはいけません。これは受取人を変更でき、現在の Eco コントラクトでは実行者が制限されています。パーミッションレスの refund(...) パスで十分です。

証拠ディレクトリを作成する

診断を始める前に、たとえば次のような専用ディレクトリを作成してください。

mkdir -p ./eco-recovery-evidence

コマンドの実行時刻、CLI のバージョン、Circle のチェーンコード、RPC URL のホスト名、公開アドレス、インテントとトランザクションのハッシュ、サニタイズ済みの stdout／stderr、終了コード、処理前後の残高、シミュレーション結果、冪等性キー、最終的なエクスプローラーリンクを記録してください。公開アドレスやアカウント間の関係も機密情報となる場合があるため、ディレクトリは非公開にしてください。

生の署名や認証情報をこのディレクトリに保存してはいけません。

Phase 1：状態を変更せずに診断する

記憶しているフラグに頼る前に、最新のヘルプを実行してください。

circle --version
circle wallet status --output json
circle gateway deposit --help
circle wallet execute --help
circle contract query --help

SCA を特定し、作成チェーン、返金候補の Vault チェーン、Gateway の宛先を確認してください。

circle wallet list --chain <SOURCE_CHAIN> --type agent --output json
circle wallet balance --address <SCA> --chain <SOURCE_CHAIN> --output json
circle gateway balance --address <SCA> --chain <GATEWAY_DESTINATION_CHAIN> --output json

少なくとも1つのインテント識別子を収集してください。

• Eco インテントハッシュ、または
• インテントを公開した作成チェーンのトランザクションハッシュ、または
• Eco 入金アドレスと、そのアドレスに到達した入金トランザクション。

Circle SCA の現在の Eco インテントステータスを確認する

Eco には SCA ごとのインテント一覧を取得するエンドポイントがありません。SCA を入金用に作成された単一用途の Eco ボールトに対応付けてから、そのボールトとインテントを照会します。

1. 送金元チェーンの SCA を特定します。

   circle wallet list --chain <SOURCE_CHAIN> --type agent --output json
   

2. 元の circle gateway deposit --output json の結果または保存済みの証跡から <VAULT_ADDRESS> を取得します。vaultAddress、sourceAddress、sourceBlockchain、transferTxHash、deadline の各フィールドで入金を特定できます。この出力を保存していない場合は、SCA の確定済み送金先行取引を一覧表示し、該当する USDC の入金トランザクションを特定します。その destinationAddress が Eco ボールトです。

   circle transaction list \
     --address <SCA> \
     --chain <SOURCE_CHAIN> \
     --operation transfer \
     --tx-type outbound \
     --state confirmed \
     --output json
   

   金額、時刻、USDC トークン、トランザクションハッシュが想定どおりであることを照合します。複数の入金がある場合、アドレスだけを見てボールトを選択しないでください。

3. 現在の Gateway 入金ボールトレコードを照会します。ボールトへの入金に使ったチェーンの EVM チェーン ID を使用してください（Base mainnet は 8453、Base Sepolia は 84532 です。現在の CLI サポート状況は circle gateway deposit --help で確認してください）。

   curl -fsS \
     "https://api.eco.com/circle-gateway/v2/depositAddresses/<VAULT_ADDRESS>?sourceChainId=<SOURCE_CHAIN_EVM_ID>"
   

   state、vaultAddress、amount、deadline、sourceChainId、intentHash を記録します。PENDING や FUNDING_DETECTED などの状態はまだ処理中です。PUBLISHED はインテントが公開済みであることを示します。一方、FAILED、REFUNDED_BY_USER、RECOVERY_PUBLISHED の場合は、次の操作を行う前に状況を照合する必要があります。

4. ボールトレコードに intentHash がある場合は、インテントのライフサイクルを照会します。

   curl -fsS \
     --request POST \
     --url https://quotes.eco.com/api/v3/intents/intentStatus \
     --header "Content-Type: application/json" \
     --data '{"intentHash":"<INTENT_HASH>"}'
   

   作成トランザクションのハッシュしかない場合は、代わりに次の使用可能な識別子を使います。

   curl -fsS \
     --request POST \
     --url https://quotes.eco.com/api/v3/intents/intentStatus \
     --header "Content-Type: application/json" \
     --data '{"intentCreatedHash":"<CREATION_TRANSACTION_HASH>"}'
   

   data.status、data.intentCreated、data.fulfillment、data.refund を記録し、含まれているすべてのトランザクションハッシュとエクスプローラー URL も記録します。

これらの API は補助的な証跡です。応答に WaitingForRefund と表示される場合は、オンチェーンでの再構築を続行してください。API のステータスだけを根拠に返金用 calldata を作成したり、ブロードキャストしたりしないでください。

状態を分類します。

確認された状態	対応
インテントの期限前	待機またはエスカレーションします。返金は行いません
インテントが履行済み／完了済み	Gateway または送金先の資金を照合します。返金は行いません
レガシーインテントで、期限を過ぎており、未履行かつボールトに資金がある	Eco のセルフ返金処理を実行します
固定された返金先が SCA である	現行フローでは、照合またはエスカレーションを行います。レガシーの復旧処理は実行しません
報酬ステータスがすでに Refunded	返金先の残高を特定します。返金を再度呼び出さないでください
USDC が SCA にある	復旧完了です
USDC が確認済みのバックアップ EOA にある	バックアップ EOA のスイープ処理を実行します
ボールトと両方のウォレット残高がゼロ	停止して送金イベントを追跡します。推測で判断しないでください

ヘルパーの前提条件

Phase 2 ヘルパー（eco-self-refund.mjs）を使うには、依存関係をインストール済みの、信頼できる circle-cli の開発用チェックアウトが必要です。現在の公開コマンドでは、コントラクトの raw calldata 送信ができないためです。このヘルパーは Circle CLI の既存のセキュアセッションとチャレンジコードを再利用します。キーチェーンのシークレットを直接読み取ったり、表示したりすることはありません。

Phase 3 ヘルパー（sign-eoa-authorization.mjs）に必要なのは、Node.js 20.18.2 以降と、circle wallet login でログインした公開版 @circle-fin/cli 1.1.4 以降のみです。チェックアウトは不要です。

両方のパスを明示的に解決します。

<SKILL_DIR>       directory containing this SKILL.md
<CIRCLE_CLI_REPO> trusted circle-cli checkout containing apps/cli and node_modules

インストール済みの新しい CLI の --help に、ネイティブの復旧、raw calldata、またはバックアップオーナー用コマンドがある場合は、それらのコマンドを優先し、同じ事前確認、承認、証跡の要件を維持してください。

フェーズ 2：Eco の返金を自分で実行する

オンチェーンイベントによって、デポジットがレガシーであること、または固定の受取先が選択したウォレットに所有され、この手動手順が必要であることが確認されるまで、このフェーズに進まないでください。reward.creator が SCA の場合は停止し、現行フローの照合手順を使用してください。

実行前に references/self-refund.md を読んでください。正確なイベントフィールド、タプル、オンチェーンでの確認項目、raw-calldata のフォールバックが定義されています。

インストール済みの CLI の --help にネイティブの Circle CLI リカバリーコマンドがある場合は、そちらを優先してください。それ以外の場合は、信頼できる circle-cli チェックアウトに含まれるヘルパーを使用してください。

<CIRCLE_CLI_REPO>/node_modules/.bin/tsx \
  <SKILL_DIR>/scripts/eco-self-refund.mjs \
  --circle-cli-repo <CIRCLE_CLI_REPO> \
  --chain <REFUND_CHAIN> \
  --event-chain-id <CREATION_CHAIN_EVM_ID> \
  --refund-chain-id <REFUND_CHAIN_EVM_ID> \
  --event-rpc-url <CREATION_CHAIN_RPC_URL> \
  --refund-rpc-url <REFUND_CHAIN_RPC_URL> \
  --sca <SCA> \
  --event-portal <CREATION_CHAIN_ECO_PORTAL> \
  --portal <REFUND_CHAIN_ECO_PORTAL> \
  --creation-tx <SOURCE_TX_HASH> \
  --intent-hash <INTENT_HASH> \
  --evidence-dir <EVIDENCE_DIR> \
  --estimate-fee

この呼び出しは読み取り専用です。明示的に選択した作成チェーンの Portal から IntentPublished をデコードしてインテントハッシュを検証した後、別途選択した返金チェーンの Portal から報酬ステータスとボールト残高を読み取り、正確な refund(...) calldata を構築して、SCA から eth_call を実行します。--estimate-fee を指定すると、Circle セッションも読み込み、固定の受取先が選択した SCA または API が報告したそのバックアップ EOA であることを検証し、承認前確認に手数料の見積もりを含めます。セッションを使わない診断の場合に限り、このフラグを省略してください。その場合の出力は承認には不十分です。選択したチェーンに資金のあるボールトがない場合は停止し、合成された Eco ルートが示す他のチェーンを確認してください。イベントのチェーンがボールトを保持している、あるいは両方の Portal アドレスが同一であると仮定しないでください。

recipientOwnership.checked: true と estimatedFee を含む承認前確認を提示し、ユーザーから明示的な承認を得た後、次の両方を指定して再実行してください。

--submit --confirm-intent <INTENT_HASH>

確認値によって、承認の対象は際限のない返金操作ではなく、単一のインテントに限定されます。

CIRCLE_PROXY_URL が設定されている場合、ヘルパーはセッショントークンを送信する前に停止します。報告されたオリジンを確認し、ユーザーにそのオリジンを正確に信頼するか確認したうえで、--allow-proxy-origin <scheme://host> を追加してください。

確認後、次の項目を検証してください。

• Circle のトランザクション状態が確定済みで、トランザクションハッシュがあること。
• Portal の報酬ステータスが Refunded であること。
• 各報酬トークンのボールト残高がゼロであるか、返金額分だけ減少していること。
• 固定の返金先の残高が増加していること。
• レシートに、想定したインテントと受取先に対する IntentRefunded が含まれていること。

任意の通常の circle wallet execute によるタプル形式の見積もりは、動的なタプル引数を厳密に限定できないため、このスキルの allowed-tools では事前承認されていません。この見積もりは、ホストの通常の対話型コマンド承認を通してのみ実行してください。直接 RPC シミュレーションが成功しても見積もりに失敗する場合は、事前承認済みヘルパーの raw calldata パスを使用してください。ホスト側パーサーに受け入れさせるために、タプルの値を変更しないでください。

フェーズ 3：裏付けEOAのUSDCをリンク済みSCAに移動する

返金がすでにSCAに届いている場合は、このフェーズをスキップします。

実行前にreferences/eoa-to-sca.mdを読んでください。これは、裏付けEOAが承認し、リンク済みSCAが中継する標準的なUSDC ERC-3009送金です。

裏付けEOAの残高を確認してから、チェーン、USDCコントラクト、裏付けEOA、SCA、未加工および小数表記の金額を提示し、署名する前にユーザーから明示的な承認を得てください。

circle contract query "balanceOf(address)" <BACKING_EOA> --contract <USDC_CONTRACT> --chain <SOURCE_CHAIN>

node <SKILL_DIR>/scripts/sign-eoa-authorization.mjs \
  --chain <SOURCE_CHAIN> \
  --sca <SCA> \
  --eoa <BACKING_EOA> \
  --usdc <USDC_CONTRACT> \
  --amount-atomic <RAW_USDC_AMOUNT>

このヘルパーは次の処理を行います。

1. --scaがログイン中のアカウントのAgent Walletsのいずれかであり、そのAPI報告値であるeoaOwnerAddressが--eoaと一致することを必須とします。
2. from=backing EOA、to=linked SCA、正確な未加工金額、新しい32バイトのnonce、有効期限1時間を指定したTransferWithAuthorizationを、稼働中のUSDC name()／version()をEIP-712ドメインに使って構築します。
3. walletAddress=<backing EOA>およびblockchain=<SOURCE_CHAIN>を指定して、typed-dataの署名を要求します。SCAのウォレットIDで署名するのは誤りです。USDCが期待する未加工のEOA署名の代わりに、EIP-1271のリプレイセーフなSCAラッパーが生成される可能性があるためです。
4. 署名者をローカルで復元し、裏付けEOAと一致することを必須とします。
5. 送信はせずに、authorizationStateの確認、circle wallet execute ... --estimateによる手数料の見積もり、固定の冪等性キーを使用する単一の送信コマンド、および検証クエリを表示します。

このスクリプトはCircleの本番環境（https://agentic-wallet.circle.com）とのみ通信します。CIRCLE_PROXY_URLが設定されている場合は、セッションを読み取る前に停止します。この変数の設定を解除し、circle wallet loginを再実行してから、スクリプトを再実行してください。表示されるcircle wallet executeコマンドも、オーバーライドなしで実行する必要があります。

認証の有効期限が切れる前に、表示されたコマンドを順番に実行してください。--estimateの結果を提示し、送信コマンドを実行する前に、送金とネットワーク手数料について明示的な承認を得てください。送信コマンドには未加工の署名が含まれます。これを証跡ディレクトリに保存せず、代わりに署名ハッシュを記録してください。

確認後、次の項目を検証してください。

• 裏付けEOAのUSDC残高が正確な金額分減少していること。
• SCAのUSDC残高が正確な金額分増加していること。
• authorizationState(backing EOA, nonce)がtrueであること。
• レシートに想定されるUSDCの送金が記録されていること。

曖昧な送信または失敗した送信

クライアントがタイムアウトしたという理由だけで、新しい認証または冪等性キーを作成しないでください。

Ecoの返金が不明確な場合は、報酬ステータス、Vault残高、受取人残高、トランザクション一覧、およびIntentRefundedログを確認してください。いずれかで成功が確認できた場合は、結果を記録して停止してください。

ERC-3009の送信が不明確な場合は、authorizationState、両方のUSDC残高、トランザクション一覧、および送金ログを確認してください。nonceが消費済みであること、または残高の移動が完了していることは、認証が使用された証拠です。最初の送金を照合するまで、2回目の送金に署名しないでください。

署名済みの認証が未送信の場合、オンチェーンの状態からnonceが未使用であることが確認でき、かつ元の署名が意図しない第三者によってリプレイされる可能性がない場合を除き、同じ金額で新たな認証を作成する前にvalidBeforeの期限切れを待ってください。

完了レポート

次の項目を報告してください。

• 初期診断と選択した分岐。
• 作成／イベント、Vault／返金、インテント宛先、およびGateway宛先のチェーン名とID。
• SCA、検証済みの裏付けEOA、作成チェーンのPortal、返金チェーンのPortal、Vault、トークン、および固定の返金先。
• インテントハッシュ、ルートハッシュ、期限、実行前後の報酬ステータス。
• アトミック単位およびUSDCでの金額。
• シミュレーション結果とガス見積もり。
• CircleのトランザクションID、オンチェーンのトランザクションハッシュ、およびエクスプローラーへのリンク。
• 実行前後の残高とERC-3009認証の状態。
• 証跡ディレクトリのパス、およびシークレット／署名を除外した旨の注記。

参考リンク

• Eco Portal コントラクト：https://docs.eco.com/routes/architecture/portal
• Eco Vault：https://docs.eco.com/routes/architecture/vault
• Eco intent ステータス API：https://docs.eco.com/api-reference/quotes-v3/get-intent-status
• Eco コントラクト：https://github.com/eco/eco-routes
• EIP-3009：https://eips.ethereum.org/EIPS/eip-3009
• Circle USDC コントラクト：https://developers.circle.com/stablecoins/usdc-contract-addresses
• Circle Agent Wallet セットアップスキル：use-agent-wallet

---

免責事項：このスキルは「現状有姿」で提供され、保証はありません。また、Circle Developer Termsが適用されます。生成された出力には誤りが含まれる場合があります。トランザクションをブロードキャストする前に、すべてのアドレス、金額、期限、コントラクト、シミュレーション、手数料、承認内容を確認してください。