cli-cast

Foundry Cast CLI

此技能不受协调门禁限制：对于其声明的工作，请跳过 ai-coord 门禁。

将读取、准备、模拟、签名和广播分开。不要在构造命令时隐藏会改变状态的操作。

对于 EIP-7702 授权或委托撤销，请在准备前阅读 references/eip7702.md。该文档定义了签名者的选择、权限方与交易发送方的区别，以及有条件的分阶段审批。它还定义了除交易收据之外的授权验证。

解析链和提供方

每次网络操作前都调用 $evm-atlas。它负责链解析、离散读取和有界实时订阅。传入明确的链名称或 ID、JSON-RPC 方法、精确参数或调用对象，以及区块选择器或检查点要求。说明需要该结果的原因。要求它提供读取数据包，其中包含解析出的链名称和 ID、提供方路由、结果、观察到的区块或检查点，以及覆盖范围缺口。

如果 evm-atlas 中没有该链，请停止依赖 RPC 的工作。不要接受任意 RPC URL 来绕过此限制。链不明确时，绝不要推断为 Ethereum。

只有在无法通过有界离散读取表达跟踪、分叉或发送流程时，才在此技能中使用 RPC URL。对于由 RouteMesh 支持的连续传输，首先要求 evm-atlas 确认当前的 RouteMesh 覆盖情况。然后，如果已配置明确的 Foundry 别名，请使用它：

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

别名可以插入环境变量，例如 ROUTEMESH_API_KEY。routemesh CLI 使用自己的密钥。因此，atlas 读取成功并不能证明别名可以解析。在通过别名广播交易前签名，或以其他方式使用别名之前，运行 ROUTEMESH_CHAIN_ID="$CHAIN_ID" cast chain-id --rpc-url routemesh 2>/dev/null。要求链 ID 与预期一致。如果检查失败，请从用户的环境设置中载入缺失的变量，但不要打印该变量。如果无法载入，则视为别名未配置。

否则，使用 evm-atlas 验证过的非机密公共 RPC。绝不要构造、检查或打印 RouteMesh URL。将 Cast 的 stderr 视为包含机密信息，因为 Foundry 可能会在传输失败时泄露已解析的别名 URL。绝不要在聊天、日志或外部报告中复述该输出。

每个 RPC 值都必须来自 evm-atlas 当前的读取数据包或上述 RouteMesh 别名。在准备、模拟或验证命令中硬编码公共 RPC URL 违反了此委派要求，即使链匹配也不例外。这包括凭记忆或先前响应写入的字面量 https:// 端点。

针对该提供方运行本地 cast 命令时，如果返回 --json 十六进制数量，请将其解码。使用 cast to-dec <hex>，或使用字段选择形式，例如 cast receipt <hash> <field> 或 cast tx <hash> <field>。不要将 --json 输出通过管道传给 jq tonumber。它无法处理十六进制字符串和 null。

授权阶段

执行合约调用的指令，即授权在请求范围内进行准备、模拟、签名、广播以及必要的钱包确认。展示审核信息。然后继续执行，无需另行征求聊天审批，也无需用户手动点击钱包。在各阶段沿用现有授权。只读、仅准备或仅模拟请求不授权执行。

用户的明确指令优先于技能默认设置。遵守用户设定的审批门槛和主机限制。只有当执行需要用户尚未提供的授权或重大决策时才提问。消息/类型化数据签名和 EIP-7702 授权仍须分别获得下文规定的载荷审批和用途审批。

读取

本地 ABI 编码/解码和选择器推导无需交易批准即可执行。将链、区块、费用、nonce、eth_call、eth_estimateGas、交易、收据、日志、余额、代码、存储、证明和 ENS 读取委托给 $evm-atlas，包括准备或验证交易所需的读取。不要仅仅因为后续操作可能改变状态，就要求 evm-atlas 将读取交回此技能。

使用 env -i PATH="$PATH" cast <command> --help 查看准确的本地语法。Cast 帮助信息可能会打印继承的环境值，包括 API 密钥。检查功能时不要加载凭据或已解密的 dotenv。常见的本地操作：

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

准备

不签名的情况下，确定链 ID、发送方、目标、函数签名、参数、调用数据、原生币金额、nonce 和费用假设。不签名的情况下，验证这些字段和假设。所有链上事实都必须通过 evm-atlas 获取。准备期间不要请求或加载密钥材料。在模拟或构造辅助内容之前，根据“签名与广播”选择受支持的签名者。在进行任一操作之前，检查该签名者的命令功能。

同时请求数值检查点区块处已确认的 nonce 和 pending nonce。当二者不同时，或钱包报告 replacement transaction underpriced 时，表示有一笔排队交易占用了最低的未确认 nonce。后续 nonce 都会被这笔交易阻塞。使用该 nonce，而不是在其后再排队一笔交易。设置足以满足节点替换加价要求的费用，通常将费用上限和小费都提高 10-20%。

对于 Ethereum 主网，references/ethereum-gas.md 定义了默认 Gas 策略。按照该策略，在模拟之前获取最新的 Rabby slow 报价。模拟前绑定其 EIP-1559 费用对。

用户或调用此技能的技能可以明确选择其他 Gas 策略。其选择可能包括用于精确清零转账的固定传统 Gas 价格。应遵循该选择，无需另行批准策略例外。请在交易审核中记录其来源、交易类型、费用值和任何限制。

对每个签名者应用所选策略。不要擅自替换为其他档位或交易类型。不要在其他链上复用 Ethereum 的费用值。

对于未选择策略的其他链，设置一个高于最新基础费用且留有余量的 EIP-1559 最高费用。使用诸如 2 * baseFee + priorityFee 的值，而不是将 eth_gasPrice 作为费用上限。实际收费仍为基础费用加小费。在签名之前，精确的费用上限可能会低于基础费用，从而需要重新审核。

特定链的 Gas 计费

选择交易类型或从余额中扣除费用之前，先确定该链当前启用的费用模型。语义应参考当前官方协议文档，目标链的参数、费用预言机调用、估算值和收据则应使用 $evm-atlas 获取。兼容 EVM、原生币符号为 ETH，以及支持传统交易，都不能证明该链采用 Ethereum 费用语义。atlas 中没有的链仍不受支持。

对于确切交易，保留一份公开费用记录，包含：

• 链/检查点、当前启用的分叉及来源，
• 交易类型、Gas 估算值和限额，以及价格/上限，
• 预期总费用，
• 预留的预付费用，以及各项组成部分和余量，
• 退款行为。

明确哪些费用已包含在预估 Gas 中，哪些费用会导致额外的原生币扣款。使用任意精度整数运算。预留费用时向上取整。绝不要重复计算某项费用，也不要从预付资金需求中扣除预期退款。当金额、调用数据、nonce、类型、Gas 或费用发生变化时，重新估算。即使是空调用数据转账，序列化也可能改变 L1 费用。

• **Ethereum 风格的记账：**确认 gas 足以支付这笔交易的所有费用。对于传统交易，预留 gasLimit * gasPrice；对于 EIP-1559，预留 gasLimit * maxFeePerGas。实际成本使用回执中的 gasUsed 和 effectiveGasPrice 计算。精确归零的原生资产清扫要求有证据证明收取价格固定、gas 使用量固定，且没有额外收费或入账。在 Ethereum 上，未委托的 EOA 使用空 calldata 和传统定价进行转账时，恰好可以使用 21000 gas。不要将这一常数用于其他费用模型。

• **Arbitrum Nitro：**使用完整的 eth_estimateGas 结果，或通过 atlas 调用 NodeInterface.gasEstimateComponents()。结果已包含转换为子链 gas 的父链发布费用。按审核过的价格上限预算完整 gas 限额。不要再加一笔 L1 费用。

  Arbitrum Nitro 支持传统交易，但其实际收取价格取决于当前 ArbOS 版本和小费收取设置。通过 atlas 和当前的 费用处理器验证这一行为。较新版本支持配置小费收取。禁用小费时，优先使用优先费为零的 EIP-1559。在此条件下，传统交易报价和相同的费用上限仍按纳入区块时的基础费计费。收取小费时，应用当前生效的价格规则。

  仅凭收取价格固定，无法固定可变的发布 gas 组件，也无法证明清扫后余额精确归零。根据审核过的余额残留策略核对未使用的 gas／价格余量。使用回执中的 gasUsed * effectiveGasPrice 计算总成本。gasUsedForL1 是已包含的 gas 组件，不是额外的 wei 费用。请参阅 gas 和费用及 估算。

• **OP Stack：**预留执行 gas、L1 数据费以及任何已启用的运营者费用。通过 atlas 查询已验证的 GasPriceOracle，使用序列化后的未签名交易调用 getL1Fee(bytes)。如果支持，则通过 atlas 使用交易未签名字节长度调用 getL1FeeUpperBound(uint256)。这些接口已计入签名开销，不要重复添加。后者是基于当前预言机价格的实用大小上限，并非纳入区块时的费用上限。

  查询 getOperatorFee(gasLimit) 以进行预先预算。根据纳入区块时所用分叉的参数、gas 使用量以及客户端确切的舍入／退款语义，还原实际纳入的运营者费用。在 Isthmus 之前，不存在运营者费用。Isthmus 和 Jovian 使用不同的标量公式。应依据分叉／配置证据确认费用不存在，而不要依据调用失败或缺少提供程序字段来判断。回执总费用为执行成本、l1Fee 和运营者费用之和，每项只计一次。

  请参阅交易费用、 Fjord 预言机、 Isthmus 运营者费用记账及 Jovian 变更。

• **其他模型，包括 ZKsync：**通过 atlas 和官方文档获取当前链原生估算器及回执语义。确认其涵盖实际交易类型的 pubdata、资源开销、自定义扣款和退款。只有在链和浏览器传输均支持普通的 type 0／2 转账且费用已完整覆盖时，才使用此类转账。不要替换为已弃用的估算器，也不要在没有受支持的签名路径时添加自定义交易字段。

  ZKsync 的费用结构包含 pubdata／开销和退款。EVM 兼容性并不意味着 gas 为 21000，也不意味着可以精确归零记账。无法确认完整记账时，应指出缺失的组件并停止。 对于费用不计入交易上限的链，将总额标为预估预留额。对于这些链，说明未覆盖的价格变动。在这些链上签名前，重新检查费用是否可负担。保证金不是由协议强制执行的上限。必须满足 value + upfront fee reserve <= balance。仅进行常规 Gas 估算或成功执行 eth_call，都不足以证明这一点。

如果允许在钱包最终修改费用，则根据修改后的值重新计算依赖于此的额外费用和可负担性。对于价值取决于预留额的清空操作，除下方固定费用例外外，必须保留所有已审核字段。

最终收取的费用和发送方余额通常已经反映已退还或未用完的 Gas。不要再次扣除。异步退款（例如 Arbitrum 可重试票据）应单独处理。预期到账的款项尚未到账前，绝不可将其用于支出。绝不可声称快照中的余额是永久不变的。

普通转账不会隐式发现无关的待处理退款。清空操作必须在审核中说明其剩余余额策略及任何已知的待处理入账。

模拟

模拟完全一致的已准备调用，保留发送方、目标地址、金额、调用数据、nonce、交易类型、Gas 限额和费用字段。然后估算 Gas。将有界的 eth_call 和 eth_estimateGas 证据交由 evm-atlas 处理。如果 RPC 错误与提供的 Gas 或已核验的余额相矛盾，应让 atlas 诊断确切的模拟路径。在将错误归因于交易无效或链级交易类型支持情况之前，先完成此步骤。

修改字段以使诊断调用通过，并不能验证已准备的交易。保留消耗型工作流的模拟要求和用户设定的审批关卡。仅当模拟需要持续连接的提供商时，才使用本地分叉、项目模拟或 Cast trace，并遵循 Resolve Chain and Provider。模拟成功可作为证据，但不代表已获准签名。

如果精确模拟 EIP-7702 需要已签名的授权，则先使用参考实现中获准的授权签名阶段。交易签名和广播仍须在模拟和交易审批之后进行。

审核

在签署或广播交易之前，提供一份具体的审核，包含：

• 链名称和 ID、RPC 来源，以及所用的最新区块，
• 发送方、目标、函数、解码后的参数、calldata 和原生代币金额，
• nonce、Gas 估算值／上限、费用假设、预期总成本、预留前置资金，以及任何协议强制执行的费用上限，
• 链特有的费用组成部分、这些上限之外的交易纳入价格不确定性，以及预期退款或剩余金额，
• 所选 Gas 策略及其来源，
• 对于 Rabby Slow，预言机 URL、档位、报价时间、预计纳入时间、每 Gas 的最高费用，以及每 Gas 的最高优先费用，
• 对于传统策略，固定 Gas 价格和交易类型，
• 预期的授权、转账或其他状态变更，
• 模拟命令和结果，
• 所选签名者，以及已隐去机密信息的确切签名／广播命令。

对于已获授权的合约调用，以 ### ⏳ Transaction review 开头。对于该调用，在同一轮中继续进行签名和广播。将重复字段放入精简表格。将确切命令放在围栏代码块中。对于其他交易或明确要求审批的情况，使用 ### ⚠️ Transaction approval required。在这些情况下，除非现有审批已经涵盖，否则需取得对具体审核的确认。

除下文所述的浏览器钱包例外情况外，如果已审核字段发生变化，请重新模拟。在这种情况下，提供修订后的审核。如果修订内容仍符合用户授权的意图和限制，则继续执行；否则，请求缺失的授权。EIP-7702 签名遵循参考文档中的分阶段审核流程。

仅对于浏览器签名，已审核的 Gas 上限和费用是初始值，除非使用该交易的工作流要求这些值保持固定。用户可以在钱包确认界面中主动更改 Gas 上限、Gas 价格、每 Gas 最高费用或每 Gas 最高优先费用。用户对最终钱包界面的批准即表示授权使用修改后的 Gas 设置。根据链特定的会计规则计算额外费用及其对可支付能力的影响。不得仅因这些值与准备时的值不同就停止、要求二次审批或重新模拟。

只有在链、发送方、目标、calldata、原生代币金额、nonce、授权列表（如有）和解码后的意图仍与已授权审核相符时，才继续执行。钱包对其中任何字段的更改都要求拒绝交易并提供修订后的审核。

Agent 确认钱包请求时，请保留已审核的 Gas 设置。用户修改值的例外不授权 Agent 接受钱包选择的费用变更。接受钱包选择的费用变更之前，请重新构建交易，并模拟这些变更。审核这些变更。

如果费用决定转账金额或其他已审核的不变量（例如保留恰好为零的原生代币余额），则不适用浏览器例外。请保留已审核的交易类型、Gas 上限和费用值。如果钱包更改了这些字段，请在签名前拒绝交易。在这种情况下，重新计算相关值，然后进行模拟。遵循上述修订审核授权规则。

签名与广播

请阅读 references/browser-signing.md，了解浏览器能力检查和发送方处理。 只有在完成审查且处于上述授权范围内时，才打开签名请求。除非用户或使用该技能的工具限制了签名方，否则优先顺序为：浏览器、加密密钥库、硬件钱包。如果浏览器签名不可用，仅限浏览器的工作流必须停止。在此类工作流中，绝不可替换为其他签名方。

如果代码仓库或使用该技能的工具提供了签名或广播助手，应在使用浏览器签名之前先使用该助手。用户对签名方的限制仍然适用。在模拟之前说明所选签名方。

仅在用户明确选择使用环境变量中的私钥，或没有更安全的方法可用时，才使用此类私钥。绝不可在聊天中索要密钥，也不可将其打印出来。

cast send 会在一条命令中完成签名和广播。获得执行授权后，在审查完成后运行它。Cast 1.8.3+ 的以下助手也会完成签名和广播：

• cast erc20-token transfer|approve|mint|burn，
• cast erc20-token permit --broadcast，
• cast erc4626 deposit|mint|withdraw|redeem，
• cast safe propose|sign|execute。

对这些助手同样执行 Prepare、Simulate 和 Review 阶段。Safe 提案或确认是一种签名凭据，需要单独审查其载荷。对于其他任何已安装帮助信息显示会签名或提交的子命令，例如 cast safe create、add-delegate 或 remove-delegate，也按相同方式处理。Cast 1.8.4+ 中的 Tempo 命令 cast tip20-token grant-role|revoke-role 和 cast tempo zone deposit|withdraw 也包括在内。签署消息或类型化数据（包括不带 --broadcast 的 cast erc20-token permit），也必须先审查确切载荷、域、链绑定和预期用途，之后才能批准。

明确传入所选费用。EIP-1559 使用 --gas-price 和 --priority-gas-price。固定的 legacy 策略使用 --legacy --gas-price，不使用 --priority-gas-price。在默认的 Ethereum 策略下，使用已审查的 Rabby Slow 组合。

打开签名器之前，重新检查当前链的 gas 和额外费用要求。打开签名器之前，重新检查已审查的上限或 legacy gas 价格是否在适用时足以覆盖当前基础费。如果签名前必须更改费用，请重新模拟。在这种情况下，提供修订后的审查内容。绝不可悄然更改所选策略。

钱包费用编辑遵循 Review 阶段，包括其固定费用例外。消息和类型化数据签名不消耗 gas。

广播后，记录交易哈希。让 evm-atlas 在已审查的链上验证收据。如果收据仍在待处理状态，evm-atlas 可以使用一次有界的 RouteMesh newHeads 订阅，等待下一个区块后再检查。仍然必须验证收据。仅凭待处理交易或日志通知不能确认交易。根据当前链的费用模型核算实际费用，包括额外收据组成部分和退款，且不得重复计算。

缺少费用证据意味着核算尚未完成，并不能证明费用为零。成功收据时，在 ### ✅ Transaction confirmed 下报告状态、区块、已用 gas、实际总费用或其确切证据缺口，以及区块浏览器链接；已挖出但失败的交易则报告在 ### ↩ Transaction reverted 下。结果不明确时，开头使用 ### ⛔ Broadcast unresolved — do not retry。对此类结果，说明仍需哪些证据。

在先检查交易是否存在之前，不要重试失败或结果不确定的广播。对于浏览器钱包签名，在认定没有发送任何内容之前，请阅读 references/browser-signing.md 中的 Timing 和 Recovering 部分。进程被终止或超时，并不能证明交易没有广播。钱包交互可能持续时间超过命令运行时间。钱包可能会通过自己的 RPC 提供商广播交易。

停止条件

如果签名者、发送方、链、目标或解码后的意图尚未确定，请在签名前停止。交易签名还要求已明确费用核算、支付能力和模拟结果。只有明确获批的 EIP-7702 授权阶段可以先于这些交易检查。必须已明确其授权载荷、签名者和预期用途。审查时必须区分强制执行的上限与预估预留费用。

浏览器批准已编辑的 gas 设置，意味着授权这些设置，但并不能证明未包含的链特定费用已得到覆盖。

如果广播结果不明确，请在重试前停止。只有出现以下任一结果，才算完成：

• 已验证的读取结果，
• 本地编码结果，
• 已批准的签名产物，
• evm-atlas 已验证的已挖出收据，且除用户批准的浏览器钱包 gas 设置外，与已审查的交易一致。

绝不要修饰或截断地址、calldata、签名、哈希、RPC URL、费用值、命令或安全措辞。完成撤销还要求通过 references/eip7702.md 中的授权和代码已清除检查。