bridge

name

bridge

description

Bridge a single-chain USDC balance or native gas token balance to Ethereum mainnet with Bungee Manual routes. Use when Codex needs to bridge ETH or the source chain's native asset family, bridge USDC to Ethereum mainnet, keep the final transaction submission in cast, load ETH_PRIVATE_KEY plus ADDRESS from the repo-root dotenvx `.env`, resolve chain metadata through `$evm-chains`, and build manual Bungee transactions. The user must specify the source chain, the asset to bridge, and an amount or `all`.

Bridge

Overview

Bridge one asset from one source chain to Ethereum mainnet. Scope is intentionally narrow:

• native gas token for the selected source chain
• canonical USDC on the selected source chain

Accept ETH as shorthand for the native asset family. On non-ETH-native chains, normalize that request to the source chain's actual native symbol after resolving the chain through $evm-chains.

Use $evm-chains to resolve chain name, chain ID, native currency symbol, default public RPC, and RouteMesh support before any onchain step. RouteMesh routing and ROUTEMESH_API_KEY sourcing are delegated to the globally installed $evm-chains skill; if that skill is unavailable, tell the user to install it with npx skills add evm-chains before proceeding. Use cli-cast only for the cast commands. Read ../../references/bungee.md before calling Bungee endpoints.

Workflow

1. Load the signing environment

Load ETH_PRIVATE_KEY, ADDRESS, and any other repo-local secrets from the repo-root dotenvx .env before any signing step. Run secret-dependent commands through a dotenvx-run subshell, such as dotenvx run --quiet -- sh -c '...'; do not source .env directly because it is encrypted. Use ADDRESS as the wallet identity and destination address on Ethereum mainnet.

If ADDRESS is missing, empty, or otherwise unusable, derive it from ETH_PRIVATE_KEY with cast wallet address and continue. Treat ETH_PRIVATE_KEY as the signing source of truth.

Require ETH_PRIVATE_KEY before any signing step. Resolve the selected source chain and Ethereum mainnet through $evm-chains before any RPC call. Use the RPC URL returned by $evm-chains; that skill is responsible for using RouteMesh when the chain supports it and its global ROUTEMESH_API_KEY is available, otherwise it falls back to public RPCs.

2. Resolve the bridge context

Resolve these values before quoting:

• source chain name and chain id
• source-chain RPC_URL
• Ethereum mainnet chain id and RPC_URL
• source-chain native currency symbol
• destination address on Ethereum mainnet
• canonical USDC token address on the source chain
• current balance for the selected asset

Resolve the exact-chain USDC token address from the Bungee token endpoint after resolving the source chain through $evm-chains.

3. Normalize the requested asset and amount

Allowed asset inputs:

• USDC
• the native asset family for the selected source chain
• ETH as shorthand for that native asset family

Reject everything else.

The user must supply either:

• an exact human amount
• all

For USDC:

• scale exact human amounts by token decimals
• reject amounts greater than the current USDC balance
• interpret all as the full USDC balance

For native:

• scale exact human amounts against the native unit
• reject amounts greater than the sweepable native balance
• interpret all as the maximum sweepable native amount after reserving gas and route fees

If the selected source chain is Ethereum mainnet, refuse the request. This skill does not perform same-chain bridge operations into mainnet.

4. Quote a manual Bungee route

Use Bungee Manual, not Auto, so the final onchain transaction is still submitted with cast.

Request the quote from GET /api/v1/bungee/quote with:

• fromChainId=<SOURCE_CHAIN_ID>
• toChainId=1
• fromTokenAddress=<USDC_ADDRESS or native sentinel>
• toTokenAddress=<ETH mainnet USDC address or native sentinel>
• amount=<RAW_AMOUNT>
• receiverAddress=<ADDRESS>
• enableManual=true
• disableSwapping=true

Native token sentinel:

0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE

Choose a manual route that preserves the asset on Ethereum mainnet when available. For native bridging, never quote the literal full balance. Keep a reserve for:

• the source-chain bridge transaction itself
• route-specific fees returned by Bungee
• one additional debugging or recovery transaction if the route stalls

5. Build the bridge transaction

Build the selected route with GET /api/v1/bungee/build-tx?quoteId=....

If the build response includes approvalData:

• check current allowance first
• only submit the approval if the current allowance is insufficient

Approval example:

cast send "$USDC" "approve(address,uint256)" "$SPENDER" "$AMOUNT" \
  --rpc-url "$RPC_URL" \
  --private-key "$ETH_PRIVATE_KEY"

Built transaction example:

cast send "$TX_TO" \
  --data "$TX_DATA" \
  --value "$TX_VALUE" \
  --rpc-url "$RPC_URL" \
  --private-key "$ETH_PRIVATE_KEY"

6. Ask for confirmation before broadcast

Before any approval or bridge send:

• show the chain
• show the bridged asset and amount
• show the chosen route id or quote id
• show whether an approval is needed
• show the bridge transaction target, calldata size, and value

Ask once for explicit confirmation. Do not broadcast approvals or bridge transactions before the user confirms.

7. Broadcast and track the route

After confirmation:

1. submit the approval transaction if needed
2. confirm the approval receipt with cast receipt
3. submit the built bridge transaction with cast send
4. confirm the source-chain receipt with cast receipt
5. poll GET /api/v1/bungee/status with the submitted source-chain transaction hash until terminal success or failure

Treat Bungee status codes 3 and 4 as success. Treat 5, 6, and 7 as terminal failure.

Guardrails

• Do not bridge tokens outside the allowed asset set.
• Do not infer chain IDs, native symbols, RouteMesh support, or RPC URLs locally. Resolve them through $evm-chains.
• Do not assume token addresses. Resolve them from the Bungee token endpoints for the exact chain after resolving that chain through $evm-chains.
• Do not spend the last unit of native gas.
• Do not attempt same-chain bridge operations on Ethereum mainnet.
• Do not enable swapping in the Bungee quote flow for this skill.
• Do not broadcast approvals or bridge transactions before explicit user confirmation.

Minimum Inputs

Before executing, make sure you have:

• one source chain
• chain metadata from $evm-chains for the source chain and Ethereum mainnet
• one allowed asset selection
• one bridge amount or all
• the exact-chain canonical USDC token address if bridging USDC