georgegoldman/Soroban-ZK-Std
GitHub: georgegoldman/Soroban-ZK-Std
Soroban-ZK-Std 是一款针对 Stellar 协议的高性能加密库。
Stars: 1 | Forks: 35
# Soroban-ZK-Std
**为 Stellar 协议 25 ZK-Primitives 设计的高性能加密标准库。**
## Stellar ZK 中的未解问题
虽然协议 25 ("X-Ray") 引入了原生主机函数用于 BN254 配对检查和 Poseidon 哈希，但仍然存在巨大的 **开发者体验 (DX) 差距**。要在 Stellar 上构建私有稳定币或合规的 RWA 协议，开发者目前面临三个“硬性障碍”：
1. **主机-客映射**：手动处理 Soroban 的主机管理 U256 和内部 256 位字段表示之间的转换容易出错。
2. **资源耗尽**：标准的 Rust ZK 库对于 Soroban 的 64KB WASM 限制来说过于庞大。
3. **气体效率低下**：仅软件的数学运算经常超过 400M 指令限制。
**Soroban-ZK-Std** 是解决方案——一个模块化、no_std Rust SDK，旨在使 Stellar 成为可配置、合规导向隐私的首选家园。
## 数学规范
- **曲线**：BN254 (alt_bn128)，针对原生 bn254_multi_pairing_check 主机函数进行了优化。
- **域模数 ($r$)**：21888242871839275222246405745257275088548364400416034343698204186575808495617
- **原语**：恒时模加法，自定义 512 位减少的 Schoolbook 乘法，以及基于 Fermat 的求逆。
## 性能基准（2026 年 3 月）
- **47% 更快的哈希**：直接通过 CAP-0075 利用 poseidon2_permutation 主机函数。
- **最小占用空间**：使用 ethnum 进行汇编优化的算术，将 WASM 二进制文件大小减少 ~22KB——节省 30% 的总合约空间。
- **指令效率**：优化的域算术允许复杂验证器在 400M 指令预算内运行良好。
## 公共利益影响与用例
这是 Stellar 生态系统的基础性基础设施。它使开发者能够构建：
- **屏蔽 RWA 转账**：通过 ElGamal 观看密钥（参见我们的 [屏蔽资产模板](./contracts/shielded-asset-template)）保持监管可见性的私有代币化资产。
- **可配置的隐私**：与 [协会集提供者 (ASPs)](./docs/ASP_Integration.md) 集成以符合规定。
- **无需信任的治理**：ZK-投票和匿名贡献跟踪，适用于 Stellar 原生 DAO。
## 安装
将以下内容添加到您的 `Cargo.toml`：
```
[dependencies]
zk-soroban = { git = "[https://github.com/georgegoldman/Soroban-ZK-Std](https://github.com/georgegoldman/Soroban-ZK-Std)" }
```
## 🛠️ 为 Soroban-ZK-Std 贡献
Soroban-ZK-Std 是一个针对 Stellar 网络优化的高性能、no_std 加密库。由于我们在 Soroban 虚拟机的严格限制下运行，我们的贡献标准高于标准的 Rust 项目。
💬 社区
加入我们的 Telegram 群组，与其他贡献者合作并获得实时支持：https://t.me/+beBHvsplOPVmYmM0
### 🚀 入门
1. **先决条件**
您必须安装以下内容：
- **Rust (Nightly/Stable)：** `rustup target add wasm32-unknown-unknown`
- **Soroban CLI：** `cargo install --locked soroban-cli`
- **Twiggy & Bloat：** (用于大小审计) `cargo install twiggy cargo-bloat`
2. 本地环境设置
克隆存储库并运行主检查以确保您的环境兼容：
```
git clone https://github.com/georgegoldman/Soroban-ZK-Std.git
cd Soroban-ZK-Std
make all
```
### 🏗️ 项目架构
为了保持库的模块化，我们将代码分为三个不同的区域：
| 组件 | 路径 | 目的 |
|------------------|-------------------------------|-------------------------------------------------------------------------|
| zk-core | crates/zk-core/ | 纯数学。椭圆曲线逻辑、域算术和 U256 映射。这里没有 Soroban 依赖。 |
| zk-soroban | crates/zk-soroban/ | Stellar 集成。扩展 Soroban Env 的特质、主机函数映射和 XDR 转换。 |
| verifier-sample | contracts/verifier-sample/ | 集成测试。一个用于验证 WASM 大小和气体成本的示例合约。 |
**规则**：
如果您添加了一个新的数学原语（例如，一个新的曲线），它将放在 `zk-core` 中。如果您为开发者在他们的合约中使用添加了一个工具，它将放在 `zk-soroban` 中。
### 📥 如何添加您的代码
1. **认领一个问题**
检查 [问题](https://www.google.com/search?q=https://github.com/georgegoldman/Soroban-ZK-Std/issues) 标签中的“良好入门问题”或“Stellar Wave 奖金”。在问题下评论以被分配。
2. **实现规则**
- **无标准库**：我们严格 `#![no_std]`。不要使用 `std::`。使用 `core::` 或 `alloc::`（如果绝对必要）。
- **无恐慌**：避免 `unwrap()` 和 `expect()`。使用 `Result` 允许合约优雅地处理错误。
- **恒时**：所有加密操作（加、乘、求逆）**必须**是恒时的，以防止旁路攻击。
3. **测试**
在您的代码所在的同一文件中添加单元测试，使用 `mod test` 块。确保它们可以运行：
```
cargo test -p
```
## 🚦 "绿灯"清单
在提交拉取请求 (PR) 之前，您 **必须** 运行本地 bouncer：
1. **代码检查**：make `clippy`（必须没有警告）。
2. **格式化**：`make fmt`（标准化样式）。
3. **大小检查**：`make build-wasm`
- 使用 twiggy top 检查大小 `target/wasm32-unknown-unknown/release/zk_soroban.wasm`。
- **如果您的代码增加了 > 5KB 的大小，您的 PR 将需要优化审查**。
## 📝 拉取请求模板
当您打开 PR 时，请使用提供的模板。简要说明您更改的 **数学逻辑**，如果适用，提供 **指令成本**（气体）。
标签：BN254, ElGamal, Poseidon, Rust, RWA, Stellar Protocol, WASM, ZK-SNARKs, 人工智能安全, 加密库, 区块链, 可视化界面, 合规性, 威胁情报, 安全协议, 开发者工具, 性能优化, 指令优化, 数学库, 智能合约, 检测绕过, 网络安全, 网络流量审计, 自动化攻击, 隐私交易, 隐私保护, 隐私币, 隐私资产, 隐私验证