Foundry unsafe-typecast 规则详解拦截 Solidity 窄化转型中的静默截断【免费下载链接】foundryFoundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.项目地址: https://gitcode.com/GitHub_Trending/fo/foundry本篇文章围绕 Foundry 内置 Solidity 静态检查器forge-lint的中等严重度规则unsafe-typecast展开讲解它如何识别uint256 → uint128、int256 → uint128这类可能丢失数据的窄化转型分析其源码级判定逻辑含掩码豁免、链式转型溯源等并通过测试用例与实际配置演示如何在项目中启用、排除或按行抑制该规则。读完本文你将能够准确判断哪些 Solidity 类型转换会被该规则告警、哪些写法是安全的并学会在生产代码中用SafeCast或位掩码消除静默截断风险。规则概览ID 与严重度unsafe-typecast是 Foundry linter位于 crates/lint在中等严重度Med下注册的一条静态分析规则其定义位于 crates/lint/src/sol/med/mod.rsunsafe_typecast: (UnsafeTypecast, late, (UNSAFE_TYPECAST));SeverityMedIDunsafe-typecast触发时机lateLateLintPass即语义分析完成后基于 HIR 类型信息检查表达式诊断信息typecast can truncate values在 crates/lint/README.md 的规则清单中它的定位是Typecasts that can truncate values should be checked可能导致截断的类型转换应当被检查。它检查什么规则会报告源值类型可能超出目标类型范围的强制类型转换典型场景包括uint256 → uint128无符号整数从 256 位窄化为 128 位int256 → uint128有符号整数转无符号整数既可能丢符号也可能丢位宽同时它做了两类豁免掩码豁免被掩码约束到目标位宽的表达式不会被标记例如uint8(value 0xff)。源码在 crates/lint/src/sol/med/unsafe_typecast.rs 中通过is_bounded_by_mask判断当转型目标是uintN且源表达式是x MASK掩码为字面量且mask.bit_len() N时认为值已被限制在目标范围内直接跳过检查。升级转型豁免向更宽类型转换天然安全如uint8 → uint256、bytes1 → bytes32不会告警。需要特别注意的是即使代码在转型前做了手动范围检查规则依然可能产生告警。因为它只分析表达式的静态类型不追踪 require 等前置约束。文档明确建议在抑制该 lint 之前先复核手动范围检查是否覆盖了所有执行路径。为什么这是隐患Solidity 对窄化转型不会 revert而是静默保留最低位截断高位。这意味着function setAmount(uint256 amount) external { smallAmount uint128(amount); // silent truncation if amount 2**128 }当amount 2**128时smallAmount被悄悄截断为低 128 位。这种静默截断可能引发严重的记账类漏洞例如金额溢出amount overflow用户传入大额但被截断成小额或反之手续费计算错误wrong fees不变量被破坏broken invariants余额、供应量等状态不再自洽由于交易本身不会失败这类问题很难通过常规测试发现却可能被恶意输入利用。因此文档建议当源值无法被证明有界时使用带检查的转型辅助函数例如 OpenZeppelin 的SafeCastfunction setAmount(uint256 amount) external { smallAmount SafeCast.toUint128(amount); }SafeCast.toUint128在amount type(uint128).max时会 revert把静默错误变成显式失败杜绝资金状态被意外破坏。正确的修复写法规则文档给出的完整修复示例function setAmount(uint256 amount) external { smallAmount SafeCast.toUint128(amount); } // A mask that bounds the value to the target width is also recognized. smallByte uint8(amount 0xff);方式一用SafeCast.toUint128(amount)做运行时检查越界即回滚方式二用位掩码amount 0xff显式把值限定到目标位宽此时规则将其识别为安全表达式不再告警。源码级判定逻辑规则的实现位于 crates/lint/src/sol/med/unsafe_typecast.rs核心分三步1. 识别转换表达式check_expr只处理ExprKind::Call(call, args, _)且cast_type(call)能解析出目标基本类型、参数个数为 1 的表达式随后调用is_bounded_by_mask排除掩码豁免场景见上文。2. 溯源源值类型source_types函数unsafe_typecast.rs会穿透转换链与一元运算符、并收集二元运算两侧来得到最底层的基本类型集合若内层仍是转型ExprKind::Call且cast_type命中则递归到其参数例如uint64(uint128(int128(uint128(a))))最终溯源到uint64 a十六进制字符串字面量视为bytes普通字符串字面量视为string一元运算如取负继续向内递归二元运算如、-同时收集左右两侧类型例如uint128(int128(uint128(a)) b)会把b的int128一并纳入判断其他情况通过gcx.type_of_expr查询 HIR 类型系统的表达式类型。这意味着规则对外层看着安全、内层参与运算后可能越界的写法同样敏感而不仅是单层转换。3. 不安全矩阵is_unsafe_elementary_typecastunsafe_typecast.rs定义了不安全的精确规则源类型目标类型判定uint从 N 位uint到 M 位N M不安全int从 N 位int到 M 位N M不安全int任意位uint任意位恒不安全丢符号uint从 N 位int到 M 位N M不安全bytesNbytesMN M不安全bytes/string动态bytesN定长恒不安全可能截断address160 位uint到 M 位M 160不安全addressint恒不安全其余组合安全对照测试用例 crates/lint/testdata/UnsafeTypecast.sol 可以印证这些分支upcastSafeUint/upcastSafeInt/upcastSafeBytes第 9-113 行逐级升级转型全部安全、无告警safeSizeUint/safeSizeInt第 115-183 行uintN(type(uintN).max)这类与类型本身同宽的写法不告警sameSizeAddressSafe第 185-192 行address → uint160、address → bytes20等 160 位同宽转换安全downcastUnsafeUint/downcastUnsafeInt/downcastUnsafeBytes第 194-297 行每一级窄化转型都用//~WARN: typecast can truncate values注释断言告警unsignedSignedUnsafe/signedUnsignedUnsafe第 299-431 行有符号/无符号互转含同宽度全部告警downcastDynamicUnsafe第 433-438 行bytes memory → bytes32、string → bytes32动态转定长同样告警。在Repros合约第 441-466 行中还覆盖了若干边界回归场景function downcastBoundedByMaskSafe(uint256 value, uint256 length) public pure { uint8(value 0xff); // 掩码豁免安全 uint8(0x7f value); // 掩码在左侧同样识别 uint8((0x80 length) 0xfe); // 复合表达式 掩码安全 uint16(value 0xffff); } function nestedCastsAreEvaluatedAtAllDepths(uint64 a, int128 b) internal pure returns (uint64) { uint64 aAloneIsSafe uint64(uint128(int128(uint128(a)))); // 内层同宽环回安全 uint128 aPlusB uint128(int128(uint128(a)) b); // 二元运算引入 int128 b告警 uint64 unsafe uint64(aPlusB); // 继续窄化告警 return uint64(uint128(int128(uint128(a)) b)); // 一次表达式两处告警 }nestedCastsAreEvaluatedAtAllDepths证明了穿透多层转型 收集二元运算两侧的必要性仅仅把a环回为uint128并不危险但与bint128相加后结果再窄化到uint64就存在截断风险。对应期望输出可查看 crates/lint/testdata/UnsafeTypecast.stderr。诊断输出与抑制方式规则触发时forge-lint输出的告警形如节选自 UnsafeTypecast.stderrwarning[unsafe-typecast]: typecast can truncate values LL │ uint248 b uint248(a); │ ━━━━━━━━━━ ├ note: consider disabling this lint if youre certain the cast is safe │ │ // casting to uint248 is safe because [explain why] │ // forge-lint: disable-next-line(unsafe-typecast)实现中通过ctx.emit_with_suggestion附带了一条建议注释模板见 unsafe_typecast.rs提示你在确信转换安全时用forge-lint: disable-next-line(unsafe-typecast)按行抑制并写明理由// casting to uint248 is safe because [explain why] // forge-lint: disable-next-line(unsafe-typecast) uint248 b uint248(a);抑制注释的解析逻辑位于forge lint命令行实现 crates/forge/src/cmd/lint.rs它还支持报告未被使用的冗余抑制注释避免抑制注释长期残留、失去约束力。测试用例 UnsafeTypecast.sol 顶部也演示了文件级禁用语法forge-lint: disable-start(mixed-case-variable)…forge-lint: disable-end(mixed-case-variable)。在项目中配置该规则unsafe-typecast属于Med严重度默认的forge lint配置会运行High、Med、Low三个严重度的规则见 crates/config/src/lint.rs因此无需任何配置即可生效。在foundry.toml的[lint]段可以进一步控制[lint] # 只运行 high/med/low 三类严重度规则默认值 severity [high, med, low] # 显式排除某条规则即使它属于已启用的严重度 exclude_lints [unsafe-typecast] # 是否在 forge build 时自动执行 lint默认 true lint_on_build true # 按 glob 忽略的文件 # ignore [lib/**, test/**]对应配置结构体定义在 crates/config/src/lint.rs其字段含义severity要运行的严重度集合默认[high, med, low]可选值见 Severity 枚举High/Med/Low/Info/Gas/CodeSizeexclude_lints按规则 ID 排除例如unsafe-typecastignoreglob 模式列表用于跳过目录/文件lint_on_buildforge build时是否自动执行 lint。另外 crates/lint/README.md 说明配置的 test 与 script 目录下的文件默认对所有规则豁免unsafe-cheatcode、environment-read-across-mutation两条除外生产源码始终会被检查——unsafe-typecast覆盖范围即生产源码中的显式转型表达式。实践建议小结默认开启无需额外配置Med严重度在默认severity [high, med, low]中已启用。遇到告警先看类型矩阵同宽uint160 ↔ address、升级转型、uintN(value mask)掩码形式都是安全的int → uint、动态bytes/string → bytesN、任何位宽缩小的转型都应警惕。优先修复而非抑制用SafeCast.toUint128等带检查的辅助函数确实安全时再用forge-lint: disable-next-line(unsafe-typecast)按行抑制并注明理由避免误伤因为手动 require 检查不一定被规则识别。警惕链式与运算场景规则会穿透多层转型并收集二元运算两侧类型uint64(uint128(x) y)这类复合表达式即使外层位宽一致也可能被标记。延伸阅读规则完整文档crates/lint/docs/unsafe-typecast.md规则源码实现crates/lint/src/sol/med/unsafe_typecast.rs规则注册位置crates/lint/src/sol/med/mod.rs测试用例crates/lint/testdata/UnsafeTypecast.sol 与 crates/lint/testdata/UnsafeTypecast.stderrlinter 全部规则清单与配置说明crates/lint/README.mdlint 配置结构foundry.toml的[lint]段crates/config/src/lint.rs【免费下载链接】foundryFoundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.项目地址: https://gitcode.com/GitHub_Trending/fo/foundry创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Foundry unsafe-typecast 规则详解：拦截 Solidity 窄化转型中的静默截断
Foundry unsafe-typecast 规则详解拦截 Solidity 窄化转型中的静默截断【免费下载链接】foundryFoundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.项目地址: https://gitcode.com/GitHub_Trending/fo/foundry本篇文章围绕 Foundry 内置 Solidity 静态检查器forge-lint的中等严重度规则unsafe-typecast展开讲解它如何识别uint256 → uint128、int256 → uint128这类可能丢失数据的窄化转型分析其源码级判定逻辑含掩码豁免、链式转型溯源等并通过测试用例与实际配置演示如何在项目中启用、排除或按行抑制该规则。读完本文你将能够准确判断哪些 Solidity 类型转换会被该规则告警、哪些写法是安全的并学会在生产代码中用SafeCast或位掩码消除静默截断风险。规则概览ID 与严重度unsafe-typecast是 Foundry linter位于 crates/lint在中等严重度Med下注册的一条静态分析规则其定义位于 crates/lint/src/sol/med/mod.rsunsafe_typecast: (UnsafeTypecast, late, (UNSAFE_TYPECAST));SeverityMedIDunsafe-typecast触发时机lateLateLintPass即语义分析完成后基于 HIR 类型信息检查表达式诊断信息typecast can truncate values在 crates/lint/README.md 的规则清单中它的定位是Typecasts that can truncate values should be checked可能导致截断的类型转换应当被检查。它检查什么规则会报告源值类型可能超出目标类型范围的强制类型转换典型场景包括uint256 → uint128无符号整数从 256 位窄化为 128 位int256 → uint128有符号整数转无符号整数既可能丢符号也可能丢位宽同时它做了两类豁免掩码豁免被掩码约束到目标位宽的表达式不会被标记例如uint8(value 0xff)。源码在 crates/lint/src/sol/med/unsafe_typecast.rs 中通过is_bounded_by_mask判断当转型目标是uintN且源表达式是x MASK掩码为字面量且mask.bit_len() N时认为值已被限制在目标范围内直接跳过检查。升级转型豁免向更宽类型转换天然安全如uint8 → uint256、bytes1 → bytes32不会告警。需要特别注意的是即使代码在转型前做了手动范围检查规则依然可能产生告警。因为它只分析表达式的静态类型不追踪 require 等前置约束。文档明确建议在抑制该 lint 之前先复核手动范围检查是否覆盖了所有执行路径。为什么这是隐患Solidity 对窄化转型不会 revert而是静默保留最低位截断高位。这意味着function setAmount(uint256 amount) external { smallAmount uint128(amount); // silent truncation if amount 2**128 }当amount 2**128时smallAmount被悄悄截断为低 128 位。这种静默截断可能引发严重的记账类漏洞例如金额溢出amount overflow用户传入大额但被截断成小额或反之手续费计算错误wrong fees不变量被破坏broken invariants余额、供应量等状态不再自洽由于交易本身不会失败这类问题很难通过常规测试发现却可能被恶意输入利用。因此文档建议当源值无法被证明有界时使用带检查的转型辅助函数例如 OpenZeppelin 的SafeCastfunction setAmount(uint256 amount) external { smallAmount SafeCast.toUint128(amount); }SafeCast.toUint128在amount type(uint128).max时会 revert把静默错误变成显式失败杜绝资金状态被意外破坏。正确的修复写法规则文档给出的完整修复示例function setAmount(uint256 amount) external { smallAmount SafeCast.toUint128(amount); } // A mask that bounds the value to the target width is also recognized. smallByte uint8(amount 0xff);方式一用SafeCast.toUint128(amount)做运行时检查越界即回滚方式二用位掩码amount 0xff显式把值限定到目标位宽此时规则将其识别为安全表达式不再告警。源码级判定逻辑规则的实现位于 crates/lint/src/sol/med/unsafe_typecast.rs核心分三步1. 识别转换表达式check_expr只处理ExprKind::Call(call, args, _)且cast_type(call)能解析出目标基本类型、参数个数为 1 的表达式随后调用is_bounded_by_mask排除掩码豁免场景见上文。2. 溯源源值类型source_types函数unsafe_typecast.rs会穿透转换链与一元运算符、并收集二元运算两侧来得到最底层的基本类型集合若内层仍是转型ExprKind::Call且cast_type命中则递归到其参数例如uint64(uint128(int128(uint128(a))))最终溯源到uint64 a十六进制字符串字面量视为bytes普通字符串字面量视为string一元运算如取负继续向内递归二元运算如、-同时收集左右两侧类型例如uint128(int128(uint128(a)) b)会把b的int128一并纳入判断其他情况通过gcx.type_of_expr查询 HIR 类型系统的表达式类型。这意味着规则对外层看着安全、内层参与运算后可能越界的写法同样敏感而不仅是单层转换。3. 不安全矩阵is_unsafe_elementary_typecastunsafe_typecast.rs定义了不安全的精确规则源类型目标类型判定uint从 N 位uint到 M 位N M不安全int从 N 位int到 M 位N M不安全int任意位uint任意位恒不安全丢符号uint从 N 位int到 M 位N M不安全bytesNbytesMN M不安全bytes/string动态bytesN定长恒不安全可能截断address160 位uint到 M 位M 160不安全addressint恒不安全其余组合安全对照测试用例 crates/lint/testdata/UnsafeTypecast.sol 可以印证这些分支upcastSafeUint/upcastSafeInt/upcastSafeBytes第 9-113 行逐级升级转型全部安全、无告警safeSizeUint/safeSizeInt第 115-183 行uintN(type(uintN).max)这类与类型本身同宽的写法不告警sameSizeAddressSafe第 185-192 行address → uint160、address → bytes20等 160 位同宽转换安全downcastUnsafeUint/downcastUnsafeInt/downcastUnsafeBytes第 194-297 行每一级窄化转型都用//~WARN: typecast can truncate values注释断言告警unsignedSignedUnsafe/signedUnsignedUnsafe第 299-431 行有符号/无符号互转含同宽度全部告警downcastDynamicUnsafe第 433-438 行bytes memory → bytes32、string → bytes32动态转定长同样告警。在Repros合约第 441-466 行中还覆盖了若干边界回归场景function downcastBoundedByMaskSafe(uint256 value, uint256 length) public pure { uint8(value 0xff); // 掩码豁免安全 uint8(0x7f value); // 掩码在左侧同样识别 uint8((0x80 length) 0xfe); // 复合表达式 掩码安全 uint16(value 0xffff); } function nestedCastsAreEvaluatedAtAllDepths(uint64 a, int128 b) internal pure returns (uint64) { uint64 aAloneIsSafe uint64(uint128(int128(uint128(a)))); // 内层同宽环回安全 uint128 aPlusB uint128(int128(uint128(a)) b); // 二元运算引入 int128 b告警 uint64 unsafe uint64(aPlusB); // 继续窄化告警 return uint64(uint128(int128(uint128(a)) b)); // 一次表达式两处告警 }nestedCastsAreEvaluatedAtAllDepths证明了穿透多层转型 收集二元运算两侧的必要性仅仅把a环回为uint128并不危险但与bint128相加后结果再窄化到uint64就存在截断风险。对应期望输出可查看 crates/lint/testdata/UnsafeTypecast.stderr。诊断输出与抑制方式规则触发时forge-lint输出的告警形如节选自 UnsafeTypecast.stderrwarning[unsafe-typecast]: typecast can truncate values LL │ uint248 b uint248(a); │ ━━━━━━━━━━ ├ note: consider disabling this lint if youre certain the cast is safe │ │ // casting to uint248 is safe because [explain why] │ // forge-lint: disable-next-line(unsafe-typecast)实现中通过ctx.emit_with_suggestion附带了一条建议注释模板见 unsafe_typecast.rs提示你在确信转换安全时用forge-lint: disable-next-line(unsafe-typecast)按行抑制并写明理由// casting to uint248 is safe because [explain why] // forge-lint: disable-next-line(unsafe-typecast) uint248 b uint248(a);抑制注释的解析逻辑位于forge lint命令行实现 crates/forge/src/cmd/lint.rs它还支持报告未被使用的冗余抑制注释避免抑制注释长期残留、失去约束力。测试用例 UnsafeTypecast.sol 顶部也演示了文件级禁用语法forge-lint: disable-start(mixed-case-variable)…forge-lint: disable-end(mixed-case-variable)。在项目中配置该规则unsafe-typecast属于Med严重度默认的forge lint配置会运行High、Med、Low三个严重度的规则见 crates/config/src/lint.rs因此无需任何配置即可生效。在foundry.toml的[lint]段可以进一步控制[lint] # 只运行 high/med/low 三类严重度规则默认值 severity [high, med, low] # 显式排除某条规则即使它属于已启用的严重度 exclude_lints [unsafe-typecast] # 是否在 forge build 时自动执行 lint默认 true lint_on_build true # 按 glob 忽略的文件 # ignore [lib/**, test/**]对应配置结构体定义在 crates/config/src/lint.rs其字段含义severity要运行的严重度集合默认[high, med, low]可选值见 Severity 枚举High/Med/Low/Info/Gas/CodeSizeexclude_lints按规则 ID 排除例如unsafe-typecastignoreglob 模式列表用于跳过目录/文件lint_on_buildforge build时是否自动执行 lint。另外 crates/lint/README.md 说明配置的 test 与 script 目录下的文件默认对所有规则豁免unsafe-cheatcode、environment-read-across-mutation两条除外生产源码始终会被检查——unsafe-typecast覆盖范围即生产源码中的显式转型表达式。实践建议小结默认开启无需额外配置Med严重度在默认severity [high, med, low]中已启用。遇到告警先看类型矩阵同宽uint160 ↔ address、升级转型、uintN(value mask)掩码形式都是安全的int → uint、动态bytes/string → bytesN、任何位宽缩小的转型都应警惕。优先修复而非抑制用SafeCast.toUint128等带检查的辅助函数确实安全时再用forge-lint: disable-next-line(unsafe-typecast)按行抑制并注明理由避免误伤因为手动 require 检查不一定被规则识别。警惕链式与运算场景规则会穿透多层转型并收集二元运算两侧类型uint64(uint128(x) y)这类复合表达式即使外层位宽一致也可能被标记。延伸阅读规则完整文档crates/lint/docs/unsafe-typecast.md规则源码实现crates/lint/src/sol/med/unsafe_typecast.rs规则注册位置crates/lint/src/sol/med/mod.rs测试用例crates/lint/testdata/UnsafeTypecast.sol 与 crates/lint/testdata/UnsafeTypecast.stderrlinter 全部规则清单与配置说明crates/lint/README.mdlint 配置结构foundry.toml的[lint]段crates/config/src/lint.rs【免费下载链接】foundryFoundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.项目地址: https://gitcode.com/GitHub_Trending/fo/foundry创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
