unwrap

name

unwrap

description

Unwrap WETH into ETH or the equivalent wrapped-native token into the chain's native gas token on a single EVM chain. Use when Codex needs to convert WETH to ETH, unwrap WPOL to POL, handle `withdraw(uint256)` on wrapped-native contracts, load ETH_PRIVATE_KEY plus ADDRESS from the repo-root dotenvx `.env`, resolve chain metadata through `$evm-chains`, and send the transaction with cast. The user must specify the source chain and an amount or `all`.

Unwrap

Overview

Unwrap one wrapped-native balance on one EVM chain into the chain's native gas token. The happy path is WETH -> ETH, but keep the same workflow for wrapped-native equivalents such as WPOL -> POL.

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 when you need the Bungee token endpoint to resolve the exact wrapped-native token address for the selected chain.

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.

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 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 unwrap pair

Resolve these inputs for the selected chain:

• source chain name and chain id
• source-chain RPC_URL
• native currency symbol
• wrapped-native token address
• wrapped-native token symbol
• wrapped-native token decimals
• current wrapped-native balance
• current native balance for gas checks

Resolve the wrapped-native token address from a trusted exact-chain source after resolving the chain through $evm-chains. Prefer the Bungee token endpoint for the chain, filtered to the wrapped-native symbol that matches the chain-native asset family, such as WETH for ETH chains or WPOL for Polygon.

3. Determine the unwrap amount

The user must supply either:

• an exact human amount, such as 0.25
• all

For an exact amount:

• scale the human amount by the wrapped-native token decimals
• reject zero or negative amounts
• reject amounts greater than the current wrapped-native balance

For all:

• use the full wrapped-native balance

If the computed unwrap amount is zero, stop and report that there is nothing to unwrap on that chain.

4. Verify gas runway

Do not spend wrapped-native inventory to fund gas. The wallet must already have enough native balance to submit the unwrap transaction.

Before broadcasting:

• estimate the unwrap transaction or inspect a recent comparable unwrap on that chain
• compare the current native balance against that estimate plus a small safety margin

If the account lacks enough native gas to submit the unwrap transaction, stop and report the chain as blocked.

5. Broadcast the unwrap transaction

Use the wrapped-native contract's withdraw(uint256) entrypoint with the computed amount.

Example:

cast send "$WRAPPED_NATIVE" "withdraw(uint256)" "$UNWRAP_AMOUNT" \
  --rpc-url "$RPC_URL" \
  --private-key "$ETH_PRIVATE_KEY"

6. Verify completion

• Use cast receipt to confirm the source-chain transaction succeeded.
• Re-read the wrapped-native and native balances if the user asks for a post-state check.

Guardrails

• Do not unwrap non-native wrappers or arbitrary ERC-20s.
• Do not infer chain IDs, native symbols, RouteMesh support, or RPC URLs locally. Resolve them through $evm-chains.
• Do not assume wrapped-native token addresses. Resolve them from the exact-chain token source after resolving the chain through $evm-chains.
• Do not interpret all as an approval to bridge, swap, or transfer funds anywhere else.
• Do not broadcast if the wallet lacks enough native gas for the unwrap transaction.

Minimum Inputs

Before executing, make sure you have:

• one source chain
• chain metadata from $evm-chains
• one unwrap amount or all
• the exact-chain wrapped-native token address