面向 Rust 的 no_std 优先的 Ethereum 协议构建块。
显式域、有界解码策略、常量时间原语以及安全门控的发布证据。
# 以太
`eth` 是一个 `no_std` 优先的 Rust workspace，用于 Ethereum 执行层协议
构建块。
该项目的目标是在 `1.0.0` 版本时提供一个可用于生产环境的 Ethereum crate，通过带有明确安全、一致性和依赖证据的小型发布来实现。
初期的实现工作特意保持保守：在 RPC、signer、REVM、Reth 或 P2P 适配器成为实际依赖之前，优先考虑显式域、有界解码策略、稳定的 crate 边界以及安全性文档。
## 当前状态
状态：`v0.4.0` 开发中；`v0.3.0` 已发布。
目前已实现：
- 固定在稳定版 `1.96.0` 的 Rust workspace。
- 针对 Rust `1.90.0` 到 `1.96.0` 的 MSRV 策略。
- `no_std` 外观层和专注的第一方 crate。
- 针对链、区块、gas、nonce、时间戳、地址、hash、wei 和交易类型值的显式原始域。
- 针对定长 hash 和 wei 值的常量时间相等性组合。
- 有界解码限制以及有状态的累积分配记账。
- 针对 codec、协议、分叉、功能、资源和验证失败的稳定错误代码、消息、类别和格式化。
- 默认功能集之外的清理和派生支持 crate。
- EUPL-1.2 许可证。
- 安全性、模块化、供应链、实现和发布规划文档。
- 本地检查、发布门控、依赖策略、SBOM 和渗透测试证据。
- 针对 crates.io 推送限制的独立支持 crate 发布规划。
尚未实现：
- 无 RPC 传输。
- 无 signer 或本地密钥存储。
- 无 EVM 执行适配器。
- 无 Reth 或 P2P 集成。
- 暂无交易或区块解析器。
## 信任仪表板
| 领域 | 状态 |
| --- | --- |
| 许可证 | `EUPL-1.2` |
| MSRV | Rust `1.90.0` |
| 固定工具链 | Rust `1.96.0` |
| 默认目标 | `no_std` |
| 默认运行时依赖 | 仅限 protocol-core 支持crate |
| 可选加固依赖 | 选择性启用的 crate/feature 后面的 `sanitization` 和 proc-macro 工具 |
| unsafe 策略 | 第一方 crate 使用 `#![forbid(unsafe_code)]` |
| 默认 features | 仅限 protocol-core |
| 网络/签名默认值 | 无 |
| 发布证据 | 本地门控、cargo-deny、cargo-audit、SBOM、渗透测试报告 |
| crate 版本 | 记录在 [`docs/CRATE_VERSION_MATRIX.md`](docs/CRATE_VERSION_MATRIX.md) 中 |
| 1.0 目标 | 严肃的生产级 Ethereum 执行层工具包 |
## 安装
```
[dependencies]
eth = "0.4"
```
如需可选的清理支持：
```
[dependencies]
eth = { version = "0.4", features = ["sanitization"] }
```
## 功能
| Feature | 默认 | 用途 |
| --- | --- | --- |
| `std` | 否 | 在准入的核心 crate 中启用 `std` 支持。 |
| `evm` | 否 | 未来的显式 EVM 适配器边界。 |
| `rpc` | 否 | 未来的显式 RPC 信任策略边界。 |
| `sanitization` | 否 | 重新导出可选的敏感信息清理桥接 API。 |
| `signer` | 否 | 未来的 signer 隔离边界。 |
| `reth` | 否 | 未来的 Reth 集成边界。 |
| `testkit` | 否 | 测试夹具、一致性助手和对抗性输入。 |
默认构建不启用网络、签名、本地密钥存储、Reth、P2P 或 EVM 执行。
## 原始域
使用显式的 Ethereum 域，而不是无限定的整数和字节数组：
```
use eth::primitives::{
Address, B256, BlockNumber, ChainId, Gas, Nonce, TransactionType, Wei,
};
let chain = ChainId::new(1);
let block = BlockNumber::new(19_000_000);
let gas = Gas::new(21_000);
let nonce = Nonce::new(7);
let address = Address::from([0x11_u8; 20]);
let hash = B256::from([0x22_u8; 32]);
let value = Wei::from_u128(1_000_000_000_000_000_000);
let tx_type = TransactionType::try_new_typed(2);
assert_eq!(u64::from(chain), 1);
assert_eq!(u64::from(block), 19_000_000);
assert_eq!(u64::from(gas), 21_000);
assert_eq!(u64::from(nonce), 7);
assert_eq!(<[u8; 20]>::from(address), [0x11_u8; 20]);
assert_eq!(<[u8; 32]>::from(hash), [0x22_u8; 32]);
assert_eq!(value.to_be_bytes()[31], 0);
assert_eq!(tx_type.map(u8::from), Ok(2));
```
## 常量时间组合
`B256::ct_eq` 和 `Wei::ct_eq` 返回 `subtle::Choice`，因此复合检查可以使用 `&` 和 `|` 而不会发生短路：
```
use eth::primitives::B256;
let block_hash = B256::from([1_u8; 32]);
let expected_block_hash = B256::from([1_u8; 32]);
let receipts_root = B256::from([2_u8; 32]);
let expected_receipts_root = B256::from([2_u8; 32]);
let valid = block_hash.ct_eq(&expected_block_hash)
& receipts_root.ct_eq(&expected_receipts_root);
assert!(bool::from(valid));
```
仅在最终的信任边界处将 `Choice` 转换为 `bool`。
## 稳定的错误
错误值公开稳定的代码、消息和类别。它们不携带输入字节、密钥、签名或其他包含敏感信息的 payload：
```
use eth::error::{DecodeError, DecodeErrorCategory, ResourceError};
let error = DecodeError::AllocationExceeded;
assert_eq!(error.code(), "ETH_CODEC_ALLOCATION_EXCEEDED");
assert_eq!(error.category(), DecodeErrorCategory::ResourceExhaustion);
assert_eq!(error.resource(), Some(ResourceError::AllocationBytes));
assert_eq!(error.to_string(), "decoder exceeded the active allocation limit");
```
## 解码预算
每个未来的不受信任解码器都需要使用显式限制。当可能发生多次分配时，使用 `DecodeAccumulator`：
```
use eth::codec::{DecodeError, DecodeLimits};
let limits = DecodeLimits {
max_input_bytes: 1024,
max_list_items: 16,
max_nesting_depth: 4,
max_total_allocation: 64,
};
assert_eq!(limits.check_input_len(512), Ok(()));
let mut budget = limits.accumulator();
assert_eq!(budget.check_allocation(32), Ok(()));
assert_eq!(budget.check_allocation(32), Ok(()));
assert_eq!(budget.check_allocation(1), Err(DecodeError::AllocationExceeded));
```
## 可选的清理
默认情况下，主外观层保持精简。处理本地敏感材料的应用程序可以选择启用清理桥接：
```
use eth::sanitization::{SecretBytes32, SecureSanitize};
let mut key = SecretBytes32::from_array([0x42_u8; 32]);
key.secure_sanitize();
assert!(key.constant_time_eq(&[0_u8; 32]));
```
对于派生宏，请直接依赖支持 crate：
```
[dependencies]
eth-valkyoth-sanitization = { version = "0.4", features = ["derive"] }
```
## Workspace 结构
大多数用户应该依赖于外观 crate `eth`。支持 crate 单独发布，以保持实现边界精简、对 `no_std` 友好且可独立测试。
| Crate | 默认 | 用途 |
| --- | --- | --- |
| `eth` | 是 | 稳定的 protocol-core crate 之上的外观 crate。 |
| `eth-valkyoth-primitives` | 是 | 链、分叉、区块、gas、nonce、地址、hash、wei 和有界值类型。 |
| `eth-valkyoth-codec` | 是 | 有界的精确消耗网络解码策略。 |
| `eth-valkyoth-protocol` | 是 | 感知分叉的验证状态和协议上下文。 |
| `eth-valkyoth-verify` | 是 | 用于签名、证明和重放域的验证边界。 |
| `eth-valkyoth-sanitization` | 否 | 指向 `sanitization` crate 的可选桥接，用于包含敏感信息的 Ethereum 数据。 |
| `eth-valkyoth-derive` | 否 | 可选的清理派生宏。 |
| `eth-valkyoth-evm` | 否 | 未来的 REVM 适配器边界。 |
| `eth-valkyoth-rpc` | 否 | 未来的显式 RPC 信任策略边界。 |
| `eth-valkyoth-signer` | 否 | 未来的 signer 隔离边界。 |
| `eth-valkyoth-reth` | 否 | 未来的 Reth 集成边界。 |
| `eth-valkyoth-testkit` | 否 | 测试夹具、一致性助手和对抗性输入。 |
## Rust 版本支持
最低支持的 Rust 版本为 Rust `1.90.0`。在工具链策略更新之前，新部署应使用固定的稳定版 Rust `1.96.0`。
`0.4.0` 的兼容性证据：
| Rust | 本地证据 |
| --- | --- |
| `1.90.0` | `cargo check --workspace --all-features` |
| `1.91.0` | `cargo check --workspace --all-features` |
| `1.92.0` | `cargo check --workspace --all-features` |
| `1.93.0` | `cargo check --workspace --all-features` |
| `1.94.0` | `cargo check --workspace --all-features` |
| `1.95.0` | `cargo check --workspace --all-features` |
| `1.96.0` | 完整的发布门控 |
## 检查
```
scripts/checks.sh
scripts/release_0_4_gate.sh
scripts/validate-release-readiness.sh v0.4.0
```
如需进行依赖策略检查，请安装 `cargo-deny` 和 `cargo-audit`，然后运行：
```
cargo deny check
cargo audit
```
## 文档
- [实现计划](docs/IMPLEMENTATION_PLAN.md)
- [发布计划](docs/RELEASE_PLAN.md)
- [范围](docs/SCOPE.md)
- [威胁模型](docs/threat-model.md)
- [规范矩阵](docs/SPEC_MATRIX.md)
- [规范来源策略](docs/spec-source-policy.md)
- [GitHub 安全设置](docs/github-security-settings.md)
- [密钥处理策略](docs/secret-handling-policy.md)
- [模块化策略](docs/modularity-policy.md)
- [供应链安全](docs/supply-chain-security.md)
- [unsafe 策略](docs/unsafe-policy.md)
## 许可证
基于欧洲联盟公共许可证 1.2 (European Union Public Licence 1.2) 授权。