Recover Eco Funds

Recover Legacy Eco Funds

Overview

Recover funds from a legacy Circle CLI Eco deposit without guessing intent data, refund recipients, or transaction state. The workflow is evidence-first and defaults to read-only inspection.

Legacy-only recovery: The executable recovery phases in this skill are for deposits whose already-published intent fixes reward.creator to the Circle SCA's API-verified eoaOwnerAddress. Current Gateway v2/Circle CLI deposits set refundRecipient to the SCA and should refund directly there. For a current deposit, use the read-only status checks below, reconcile the SCA and Gateway balances, and escalate through the normal support path if necessary; do not run the legacy backing-EOA sweep.

Do not classify a deposit as legacy from its age or endpoint version alone. Decode the IntentPublished event and compare the fixed reward.creator with both the SCA and its API-verified eoaOwnerAddress:

• reward.creator == eoaOwnerAddress: legacy recovery may apply after all read-only checks.
• reward.creator == SCA: current direct-to-SCA refund behavior; stop before the executable legacy phases.
• neither: stop because the selected Circle wallet does not own the fixed refund recipient.

If there is no Eco deposit and USDC was simply sent to an Agent Wallet's backing EOA (the CLI reports "Wallet not found" for that address), skip Phases 1 and 2 and go straight to Phase 3.

Use the use-circle-cli and use-agent-wallet skills first if the Circle CLI is not installed, the Terms gate is unresolved, or the agent session is invalid. Do not trigger multiple login requests: each fresh request invalidates the prior OTP.

Understand the two recovery legs

A legacy Eco deposit can require two separate operations:

1. Eco self-refund: call Portal.refund(destination, routeHash, reward) on the vault/refund chain after the reward deadline. The Portal validates the intent and instructs its deterministic vault to return funds to reward.creator. Anyone may relay this call, but the recipient is fixed by the original intent.
2. Backing EOA sweep: if reward.creator was the SCA's backing EOA, authorize USDC to move from that EOA to the linked SCA with ERC-3009. The SCA relays the token call and pays gas; the backing EOA does not need native gas.

Current Gateway v2/Circle CLI Eco deposits set the SCA as the refund recipient. They are outside the executable scope of this skill: use status and balance reconciliation, and do not run the backing-EOA sweep.

Safety boundary

• Treat event/creation chain, vault/refund chain, intent destination value, Gateway destination chain, SCA, backing EOA, creation-chain Portal, refund-chain Portal, vault, token, amount, route hash, intent hash, and deadline as different fields. Never substitute one for another. A composed Eco flow can publish the event on one chain while leaving the refundable vault on another, and Portal deployment addresses need not match across chains.
• Derive the backing EOA from the Circle wallet API's eoaOwnerAddress; do not accept a user-supplied owner without comparing it to that field.
• Before a legacy self-refund broadcast, require reward.creator to equal the selected Circle wallet's API-verified eoaOwnerAddress. If it equals the SCA, classify it as the current direct-to-SCA flow and stop before executable recovery. Although refund(...) is permissionless, never spend the user's gas to refund an unrelated wallet.
• Reconstruct the refund tuple from the source-chain IntentPublished event. The Eco status API is useful context but is not authoritative enough to build calldata.
• Verify the reconstructed intent hash equals the event's indexed intent hash.
• Refuse a refund before the onchain deadline or when reward status is already Withdrawn or Refunded.
• Simulate the exact calldata from the exact SCA before broadcasting.
• Ask for explicit approval immediately before each money-moving action. Present chain, token, raw and decimal amount, source, destination, contract, intent/nonce, and estimated gas.
• Use one persisted idempotency key per intended broadcast. On an ambiguous response, reconcile onchain state before attempting anything new.
• Never log user tokens, session secrets, OTPs, private keys, or raw EIP-712 signatures. Log a signature hash instead.
• If CIRCLE_PROXY_URL overrides Circle's default, inspect the exact origin and obtain explicit user trust before sending an agent session token through it. The Phase 2 helper requires --allow-proxy-origin <scheme://host> when an override is present. The Phase 3 script talks only to Circle production and refuses to run while an override is set.
• Never use refundTo(...) as a shortcut. It can change the recipient and is creator-restricted on current Eco contracts. The permissionless refund(...) path is sufficient.

Create an evidence directory

Create a dedicated directory before diagnosis, for example:

mkdir -p ./eco-recovery-evidence

Capture command time, CLI version, Circle chain code, RPC URL host, public addresses, intent and transaction hashes, sanitized stdout/stderr, exit code, pre/post balances, simulation result, idempotency key, and final explorer link. Keep the directory private because public addresses and account relationships may still be sensitive.

Do not place raw signatures or authentication material in this directory.

Phase 1: Diagnose without changing state

Run current help before relying on remembered flags:

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

Identify the SCA and inspect the creation chain, candidate vault/refund chains, and Gateway destination:

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

Collect at least one intent identifier:

• Eco intent hash, or
• creation-chain transaction hash that published the intent, or
• Eco deposit address plus the funding transaction that reached it.

Check the current Eco intent status for a Circle SCA

Eco does not provide a list-intents-by-SCA endpoint. Map the SCA to the single-use Eco vault created for the deposit, then query that vault and its intent:

1. Identify the source-chain SCA:

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

2. Get <VAULT_ADDRESS> from the original circle gateway deposit --output json result or the saved evidence. Its vaultAddress, sourceAddress, sourceBlockchain, transferTxHash, and deadline fields identify the deposit. If that output was not saved, list the SCA's confirmed outbound transfers and find the exact USDC funding transaction; its destinationAddress is the Eco vault:

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

   Match the intended amount, time, USDC token, and transaction hash. Do not select a vault from address alone when multiple deposits exist.

3. Query the current Gateway deposit-vault record. Use the EVM chain ID for the chain that funded the vault (8453 for Base mainnet or 84532 for Base Sepolia; verify current CLI support with circle gateway deposit --help):

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

   Record state, vaultAddress, amount, deadline, sourceChainId, and intentHash. States such as PENDING and FUNDING_DETECTED are still in progress; PUBLISHED means an intent was published, while FAILED, REFUNDED_BY_USER, and RECOVERY_PUBLISHED require reconciliation before another action.

4. When the vault record contains an intentHash, query the intent lifecycle:

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

   If only the creation transaction hash is available, use the alternate accepted identifier:

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

   Capture data.status, data.intentCreated, data.fulfillment, and data.refund, including every transaction hash and explorer URL present.

These APIs are supporting evidence. If the response says WaitingForRefund, continue with onchain reconstruction; never build refund calldata or broadcast from an API status alone.

Classify the state:

Helper prerequisites

The Phase 2 helper (eco-self-refund.mjs) requires a trusted circle-cli developer checkout with dependencies installed because the current public command surface does not expose raw contract calldata submission. It reuses Circle CLI's existing secure session and challenge code; it does not read or print keychain secrets directly.

The Phase 3 helper (sign-eoa-authorization.mjs) needs only Node.js 20.18.2+ and the public @circle-fin/cli 1.1.4 or newer, logged in with circle wallet login. No checkout is required.

Resolve both paths explicitly:

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

If a newer installed CLI exposes native recovery, raw-calldata, or backing-owner commands in --help, prefer those commands and retain the same preflight, approval, and evidence requirements.