Inferara/soroban-ret

[](https://github.com/Inferara/soroban-ret/actions/workflows/build.yml) [](https://codecov.io/gh/Inferara/soroban-ret) [](https://crates.io/crates/soroban-ret) [](https://crates.io/crates/soroban-ret-cli) # Stellar Soroban 智能合约逆向工程工具 ## 状态 早期开发阶段。当前版本涵盖了完整的五个阶段 pipeline，针对仅限于简单算术运算、基础存储、自定义类型、事件、授权以及跨合约调用的合约，已实现端到端的部分反编译。 - **阶段 1** — WASM 解析：节（sections）、导入（imports）、导出（exports）、函数体（function bodies）、数据段（data segments）、自定义节（`contractspecv0`、`contractmetav0`、`contractenvmetav0`）。 - **阶段 2** — Spec 提取：从合约的 `contractspecv0` XDR 中提取函数、struct、union、enum、错误 enum 和事件的类型化查找表；SEP-41 / Stellar Asset 标准接口检测；从 `contractmetav0` 获取 SDK 版本。 - **阶段 3** — 模式匹配器：host-call 提升、控制流结构化、dispatch 剥离、wrapper 检测。 - **阶段 4** — IR 优化器 + 后优化 pass：常量折叠、has/get 融合、存储键恢复、enum 键构造、event 发布恢复、auth/跨合约修复、死代码消除。 - **阶段 5** — Rust 源码生成器：通过 `soroban-spec-rust` 生成类型定义、生成函数体、通过 `#[contract]`/`#[contractimpl]` 组装 module、通过 `prettyplease` 进行格式化。 ## 安装 库和 CLI 作为独立的 crate 发布。 ``` # 作为库使用 cargo add soroban-ret # 安装 CLI (提供 `soroban-ret` 二进制程序) cargo install soroban-ret-cli ``` ## CLI 用法 ``` # 将反编译的 Rust 打印到 stdout soroban-ret path/to/contract.wasm # 将反编译的 Rust 写入文件 soroban-ret path/to/contract.wasm -o lib.rs # 仅打印 type definitions 和 function signatures soroban-ret path/to/contract.wasm --spec-only # 打印 contract metadata (SDK 版本、function/type 计数、signatures) soroban-ret path/to/contract.wasm --info # 强制 generic WASM 模式 (无 Soroban 假设) soroban-ret path/to/contract.wasm --generic ``` Flags： | Flag | 用途 | |---|---| | `-o, --output ` | 将反编译的源码写入文件，而不是输出到 stdout | | `--spec-only` | 仅生成类型定义和函数签名 | | `-O, --pre-optimize` | 在反编译前使用 `wasm-opt` 预优化 WASM（需要 binaryen） | | `--info` | 打印合约元数据（SDK 版本、函数、类型、事件）并退出 | | `--generic` | 强制使用通用 WASM 模式（不包含 Soroban 假设） | | `-v, --verbose` | 启用调试日志 | ## 库用法 ``` use soroban_ret::{decompile, decompile_with_options, DecompileOptions}; let wasm = std::fs::read("contract.wasm")?; // Simple: WASM bytes → formatted Rust source. let source: String = decompile(&wasm)?; println!("{source}"); // With options + metadata. let mut options = DecompileOptions::default(); options.spec_only = true; let result = decompile_with_options(&wasm, &options)?; println!("SDK version: {:?}", result.sdk_version); println!("Standard interfaces: {:?}", result.standard_interfaces); for diag in &result.validation.diagnostics { eprintln!("diag: {diag}"); } ``` 为了进行更底层的检查（原始解析的 WASM、类型化的 spec 注册表、验证诊断），阶段 1 / 阶段 2 的 API 仍然是公开的： ``` use soroban_ret::{TypeRegistry, WasmModule}; let module = WasmModule::parse(&wasm)?; let registry = TypeRegistry::from_wasm(&wasm)?; ``` 对于不符合 Soroban 规范的构造（float、reference type、multi-memory、`call_indirect` 等），其验证诊断可以通过 `WasmModule::parse_diagnostics` 获取。 ## 从源码构建 需要稳定的 Rust 工具链（MSRV 在工作区的 `Cargo.toml` 中声明）。 ``` git clone https://github.com/Inferara/soroban-ret.git cd soroban-ret cargo build --workspace cargo test --workspace cargo run -p soroban-ret-cli -- path/to/contract.wasm ``` ## 路线图 | 阶段 | 范围 | 状态 | |---|---|---| | 1 | WASM 解析器 | 完成 | | 2 | Spec 提取器 + 标准接口检测器 | 完成 | | 3 | 模式匹配器：host-call 提升、控制流结构化、wrapper 检测 | 完成（部分） | | 4 | IR 优化器 + 后优化 pass | 完成（部分） | | 5 | Rust 源码生成器 | 完成（部分） | “部分”反映了当前的交付范围：简单算术运算、基础存储、自定义类型、事件、auth 和跨合约调用可以生成具有正确类型和签名且可编译的 Rust 代码。对更高级模式（allowance 流程、复杂的 token 合约、快照级别的恢复）的覆盖已在路线图中。 针对每个模式的代码、测试夹具（fixtures）和显式断言的审计位于 [`docs/pattern-coverage.md`](docs/pattern-c overage.md)。 ## 贡献 欢迎贡献！ ## 许可证 本项目采用 Apache License 2.0 授权。详情请参阅 [LICENSE](./LICENSE)。

标签：Rust, Stellar, WebAssembly, 云资产清单, 区块链安全, 反编译器, 可视化界面, 智能合约, 网络流量审计, 逆向工程, 通知系统