paulrberg/agent-skills/cli-cast

Foundry Cast CLI

This skill is coordination-exempt: skip the ai-coord gate for its declared work.

Separate read, preparation, simulation, signing, and broadcast. Do not hide state-changing actions inside command construction.

For EIP-7702 authorization or delegation revocation, read references/eip7702.md before preparation. It defines signer selection, authority versus transaction sender, and conditional staged approval. It also defines authorization verification in addition to the transaction receipt.

Resolve Chain and Provider

Invoke $evm-atlas before every network operation. It owns chain resolution, discrete reads, and bounded live subscriptions. Pass the explicit chain name or ID, JSON-RPC method, exact parameters or call object, and block selector or checkpoint requirement. State why you need the result. Require its read packet containing the resolved chain name and ID, provider route, result, observed block or checkpoint, and coverage gaps.

If the chain is absent from evm-atlas, stop RPC-dependent work. Do not accept an arbitrary RPC URL to bypass that restriction. When the chain is ambiguous, never infer Ethereum.

Use an RPC URL in this skill only for a trace, fork, or send flow you cannot express as bounded discrete reads. For RouteMesh-backed continuous transport, first require evm-atlas to confirm current RouteMesh coverage. Then, if the explicit Foundry alias is configured, use it:

ROUTEMESH_CHAIN_ID="$CHAIN_ID" cast COMMAND --rpc-url routemesh

The alias can interpolate an environment variable, such as ROUTEMESH_API_KEY. The routemesh CLI keeps its own key. Thus, successful atlas reads do not prove that the alias resolves. Before you sign a transaction for alias broadcast, or use the alias in another way, run ROUTEMESH_CHAIN_ID="$CHAIN_ID" cast chain-id --rpc-url routemesh 2>/dev/null. Require the expected chain ID. If the check fails, load the missing variable from the user's environment setup without printing it. If you cannot load it, treat the alias as not configured.

Otherwise, use the nonsecret public RPC that evm-atlas verified. Never construct, inspect, or print a RouteMesh URL. Treat Cast stderr as secret-bearing because Foundry may reveal a resolved alias URL on transport failure. Never repeat that output in chat, logs, or external reports.

Resolve every RPC value from evm-atlas's current read packet or the RouteMesh alias above. A hard-coded public RPC URL in a prepare, simulate, or verify command violates this delegation even when the chain matches. This includes a literal https:// endpoint from memory or a prior response.

When a local cast command against that provider returns a --json hex quantity, decode it. Use cast to-dec <hex> or a field-select form such as cast receipt <hash> <field> or cast tx <hash> <field>. Do not pipe --json output through jq tonumber. It fails on hex strings and on null.

Authority Phases

An instruction to execute a contract call authorizes preparation, simulation, signing, broadcast, and necessary wallet confirmations within the requested scope. Present the review. Then proceed without a separate chat approval or manual wallet click from the user. Apply existing authorization across phases. A read-only, prepare-only, or simulation-only request does not authorize execution.

Explicit user instructions take precedence over skill defaults. Honor user-imposed approval gates and host restrictions. Ask only when execution needs authority or a material decision the user has not supplied. Message/typed-data signatures and EIP-7702 authorizations retain their separate payload and use approvals below.

Read

Local ABI encoding/decoding and selector derivation may run without transaction approval. Delegate chain, block, fee, nonce, eth_call, eth_estimateGas, transaction, receipt, log, balance, code, storage, proof, and ENS reads to $evm-atlas, including reads needed to prepare or verify a transaction. Do not ask evm-atlas to hand a read back to this skill merely because later work may change state.

Use env -i PATH="$PATH" cast <command> --help for exact local syntax. Cast help can print inherited environment values, including API keys. Do not load credentials or decrypted dotenv for capability checks. Typical local operations:

cast calldata 'transfer(address,uint256)' "$TO" "$AMOUNT"
cast decode-calldata 'transfer(address,uint256)' "$CALLDATA"

Prepare

Without signing, resolve chain ID, sender, target, function signature, arguments, calldata, native value, nonce, and fee assumptions. Without signing, validate those fields and assumptions. Obtain every on-chain fact through evm-atlas. Do not request or load key material during preparation. Before simulation or helper construction, select a supported signer under Sign and Broadcast. Before either activity, check that signer's command capabilities.

Request both the confirmed nonce at the numeric checkpoint block and the pending nonce. When they differ, or a wallet reports replacement transaction underpriced, a queued transaction occupies the lowest unconfirmed nonce. Later nonces stay stuck behind that transaction. Target that nonce instead of queueing another transaction behind it. Use fees that clear the node's replacement bump, usually 10-20% on both the fee cap and the tip.

For Ethereum mainnet, references/ethereum-gas.md defines the default gas policy. Under that policy, fetch a fresh Rabby slow quote before simulation. Bind its EIP-1559 fee pair before simulation.

The user or a consuming skill may explicitly choose a different gas policy. Their choice may include a fixed legacy gas price for an exact-zero sweep. Honor that choice. It does not require a separate policy-exception approval. Record its source, transaction type, fee values, and any constraints in the transaction review.

Apply the selected policy to every signer. Do not silently substitute a different tier or transaction type. Do not reuse Ethereum fee values on another chain.

On other chains without a selected policy, set an EIP-1559 max fee with headroom over the latest base fee. Use a value such as 2 * baseFee + priorityFee instead of passing eth_gasPrice as the cap. The charge stays base fee plus tip. An exact cap can fall below the base fee before signing and force a revised review.

Chain-specific gas accounting

Resolve the chain's active fee model before choosing a transaction type or subtracting fees from a balance. Use current official protocol documentation for semantics and $evm-atlas for the target chain's parameters, fee-oracle calls, estimates, and receipts. EVM compatibility, a native symbol of ETH, and support for legacy transactions do not establish Ethereum fee semantics. A chain absent from atlas remains unsupported.

For the exact transaction, retain a public fee record with:

• chain/checkpoint, active fork, and sources,
• transaction type, gas estimate and limit, and price/caps,
• expected total fee,
• upfront fee reserve with each component and margin,
• refund behavior.

Identify which charges estimated gas includes and which charges cause additional native debits. Use arbitrary-precision integer arithmetic. Round reserves up. Never count a component twice or subtract an anticipated refund from the upfront funding requirement. When value, calldata, nonce, type, gas, or fees change, re-estimate. Serialization can change the L1 charge even for an empty-calldata transfer.

• Ethereum-style accounting: establish that gas covers all fees for this transaction. Reserve gasLimit * gasPrice

for legacy, or gasLimit * maxFeePerGas for EIP-1559. Actual cost uses receipt gasUsed and effectiveGasPrice. Exact-zero native sweeps require evidence of a fixed charged price, fixed gas used, and no additional charges or credits. A plain undelegated EOA transfer on Ethereum with empty calldata and legacy pricing can use exactly 21000 gas. Do not apply that constant to other fee models.

• Arbitrum Nitro: use the complete eth_estimateGas result, or NodeInterface.gasEstimateComponents() through

atlas. It includes the parent-chain posting charge converted into child-chain gas. Budget the full gas limit at the reviewed price cap. Do not add a second L1 fee.

Arbitrum Nitro supports legacy transactions, but their charged price depends on the active ArbOS version and tip-collection setting. Verify that behavior through atlas and the current fee processor. Newer versions make tip collection configurable. When tips are disabled, prefer EIP-1559 with zero priority fee. Under that condition, legacy bids and equal caps still charge the inclusion base fee. When tips are collected, apply the active effective-price rules.

A fixed charged price alone does not fix the variable posting-gas component or prove an exact-zero sweep. Reconcile unused gas/price headroom against the reviewed residual policy. Use receipt gasUsed * effectiveGasPrice for total cost. gasUsedForL1 is an included gas component, not an extra wei charge. See gas and fees and estimation.

• OP Stack: reserve execution gas plus the L1 data fee and any enabled operator fee. Through atlas, query the

verified GasPriceOracle for getL1Fee(bytes) using the serialized unsigned transaction. Where supported, query it through atlas for getL1FeeUpperBound(uint256) using the transaction's unsigned byte length. These interfaces account for signature overhead. Do not add it twice. The latter is a practical size bound at the current oracle prices, not a cap on fees at inclusion.

Query getOperatorFee(gasLimit) for upfront budgeting. Reconstruct the included operator charge using the inclusion fork's parameters, gas use, and exact client rounding/refund semantics. Before Isthmus, the operator charge is absent. Isthmus and Jovian use different scalar formulas. Establish absence from fork/configuration evidence, not a failed call or a missing provider field. Receipt total is execution cost plus l1Fee plus operator cost, each once.

See transaction fees, Fjord oracle, Isthmus operator accounting, and Jovian changes.

• Other models, including ZKsync: obtain the current chain-native estimator and receipt semantics through atlas and

official docs. Establish coverage of pubdata, resource overhead, custom debits, and refunds for the actual transaction type. Use an ordinary type 0/2 transfer only if the chain and browser transport support it with complete fee coverage. Do not substitute a deprecated estimator or add custom transaction fields without a supported signing path.

ZKsync's fee structure includes pubdata/overhead and refunds. Neither 21000 gas nor exact-zero accounting follows from EVM compatibility. Stop with the missing component when complete accounting cannot be established.

On chains with fees outside transaction caps, label the total as an estimated reserve. For those chains, disclose the uncovered price movement. Immediately before signing on those chains, recheck affordability. A margin is not a protocol-enforced maximum. Require value + upfront fee reserve <= balance. Ordinary gas estimation or a successful eth_call alone does not prove this.