sip-protocol/circuits

## 目录 - [什么是 SIP Circuits？](#-what-are-sip-circuits) - [Circuit 概述](#-circuits-overview) - [快速开始](#-quick-start) - [Circuit 详情](#-circuit-details) - [架构](#%EF%B8%8F-architecture) - [密码学原语](#-cryptographic-primitives) - [集成](#-integration) - [开发](#-development) - [规范](#-specifications) - [相关项目](#-related-projects) - [许可证](#-license) ## 🛡️ 什么是 SIP Circuits？ SIP Circuits 是用 Noir 编写的**零知识证明 circuit**，能够在不透露敏感数据的情况下实现隐私保护操作。它们是 SIP Protocol 的密码学基础。 ``` Traditional Transaction → Everyone sees balance, amount, recipient SIP with ZK Proofs → Prove validity without revealing anything ``` **证明你拥有足够余额。证明你已获授权。证明它是正确的。不透露任何信息。** ## 📊 Circuit 概述 | Circuit | 用途 | ACIR Opcodes | 测试 | |---------|---------|--------------|-------| | **funding_proof** | 在不透露余额的情况下证明余额 ≥ 最低要求 | 972 | 5 | | **validity_proof** | 在不透露发送者的情况下证明 intent 授权 | 1,113 | 6 | | **fulfillment_proof** | 证明 swap 执行的正确性 | 1,691 | 8 | **总计：3 个 circuit，3,776 个 ACIR opcodes，19 个通过的测试** ### 各 Circuit 证明的内容 ``` ┌─────────────────────────────────────────────────────────────────┐ │ FUNDING PROOF │ │ "I have enough balance" │ │ ───────────────────── │ │ Public: commitment_hash, minimum_required, asset_id │ │ Private: actual_balance, blinding_factor │ │ Proves: balance >= minimum (without revealing balance) │ ├─────────────────────────────────────────────────────────────────┤ │ VALIDITY PROOF │ │ "I authorized this intent" │ │ ───────────────────────── │ │ Public: intent_hash, sender_commitment, nullifier, timestamps │ │ Private: sender_address, signature, secrets │ │ Proves: valid signature from committed sender │ ├─────────────────────────────────────────────────────────────────┤ │ FULFILLMENT PROOF │ │ "The swap was executed correctly" │ │ ───────────────────────────────── │ │ Public: intent_hash, output_commitment, recipient, min_output │ │ Private: actual_output, oracle_attestation │ │ Proves: output >= min_output with oracle verification │ └─────────────────────────────────────────────────────────────────┘ ``` ## 🚀 快速开始 ### 前置条件 - [Nargo CLI](https://noir-lang.org/docs/getting_started/installation) ### 安装 ``` # 安装 Nargo（Noir 的 package manager） curl -L https://raw.githubusercontent.com/noir-lang/noirup/main/install | bash noirup # 克隆仓库 git clone https://github.com/sip-protocol/circuits.git cd circuits ``` ### 编译与测试 ``` # 编译 circuit cd funding_proof nargo compile # 运行测试 nargo test # 获取 circuit 信息（constraint count） nargo info # 生成 proof（需要 Prover.toml） nargo prove # 验证 proof nargo verify ``` ### 运行所有测试 ``` # 从 circuits 根目录 cd funding_proof && nargo test && cd .. cd validity_proof && nargo test && cd .. cd fulfillment_proof && nargo test && cd .. ``` ## 🔐 Circuit 详情 ### 1. Funding Proof 在不透露实际金额的情况下，证明用户拥有足够的余额。 **用例：** 在执行前预先验证用户能够承担 swap。 ``` // Public Inputs commitment_hash: [u8; 32] // Hash of Pedersen commitment to balance minimum_required: u64 // Minimum balance required asset_id: Field // Asset identifier // Private Inputs (never revealed) balance: u64 // Actual user balance blinding: Field // Commitment blinding factor ``` **验证：** 1. 根据 `balance` 和 `blinding` 重新计算 commitment 2. 验证 commitment 哈希是否与公共输入匹配 3. 断言 `balance >= minimum_required` ### 2. Validity Proof 在不透露发送者身份的情况下证明 intent 授权。 **用例：** 在隐藏进行 swap 的用户身份的同时，授权 swap intent。 ``` // Public Inputs intent_hash: Field // Hash of the intent sender_commitment_x: Field // Commitment X coordinate sender_commitment_y: Field // Commitment Y coordinate nullifier: Field // Prevents double-spending timestamp: u64 // Current timestamp expiry: u64 // Intent expiry time // Private Inputs (never revealed) sender_address: Field // Actual sender address sender_blinding: Field // Commitment blinding sender_secret: Field // For nullifier derivation pub_key_x: [u8; 32] // ECDSA public key X pub_key_y: [u8; 32] // ECDSA public key Y signature: [u8; 64] // ECDSA signature message_hash: [u8; 32] // Signed message hash nonce: Field // Unique nonce ``` **验证：** 1. 验证消息上的 ECDSA 签名 2. 验证发送者的 commitment 是否与地址匹配 3. 验证 nullifier 推导 4. 检查时间戳是否在有效期内 ### 3. Fulfillment Proof 通过 oracle attestation 证明 swap 的正确执行。 **用例：** 验证 solver 交付了正确的输出金额。 ``` // Public Inputs intent_hash: Field // Intent being fulfilled output_commitment_x: Field // Output commitment X output_commitment_y: Field // Output commitment Y recipient_stealth: Field // Stealth delivery address min_output_amount: u64 // Required minimum output solver_id: Field // Solver identifier fulfillment_time: u64 // When fulfilled expiry: u64 // Must fulfill before // Private Inputs (never revealed) output_amount: u64 // Actual delivered amount output_blinding: Field // Commitment blinding solver_secret: Field // Derives solver_id oracle_recipient: Field // Oracle-attested recipient oracle_amount: u64 // Oracle-attested amount oracle_tx_hash: [u8; 32] // Transaction hash oracle_block: u64 // Block number oracle_signature: [u8; 64] // Oracle signature oracle_message_hash: [u8; 32] // Signed message oracle_pub_key_x: [u8; 32] // Oracle public key oracle_pub_key_y: [u8; 32] ``` **验证：** 1. 验证 attestation 上的 oracle 签名 2. 验证输出 commitment 是否与金额匹配 3. 断言 `output_amount >= min_output_amount` 4. 验证 solver_id 推导 5. 检查兑现是否在有效期内 ## 🏗️ 架构 ### 项目结构 ``` circuits/ ├── funding_proof/ │ ├── Nargo.toml # Circuit manifest │ ├── src/ │ │ └── main.nr # Circuit implementation │ └── target/ │ └── funding_proof.json # Compiled artifact │ ├── validity_proof/ │ ├── Nargo.toml │ ├── src/ │ │ └── main.nr │ └── target/ │ └── validity_proof.json # ✅ Compiled │ ├── fulfillment_proof/ │ ├── Nargo.toml │ ├── src/ │ │ └── main.nr │ └── target/ │ └── fulfillment_proof.json # ✅ Compiled │ ├── README.md └── CLAUDE.md ``` ### 证明流程 ``` Private Inputs + Public Inputs → Noir Circuit → ACIR → Barretenberg → Proof │ ▼ SDK Verifies Proof (Browser or Server) ``` ## 🔢 密码学原语 | 原语 | 用途 | Noir 标准库 | |-----------|-------|----------------------| | **Pedersen Hash** | Commitment, nullifier | `std::hash::pedersen_hash` | | **BLAKE3** | Commitment 绑定, 消息哈希 | `std::hash::blake3` | | **ECDSA secp256k1** | 签名验证 | `std::ecdsa_secp256k1::verify_signature` | ### 为什么选择这些原语？ - **Pedersen**：加法同态，在 ZK circuit 中非常高效 - **BLAKE3**：快速、安全、circuit 规模小 - **ECDSA secp256k1**：兼容 Ethereum/Bitcoin 签名 ## 🔌 集成 ### SDK 集成 SDK 的 `NoirProofProvider` 会使用编译好的 JSON 构件： ``` import { NoirProofProvider } from '@sip-protocol/sdk' // Initialize provider (loads WASM) const provider = new NoirProofProvider() await provider.initialize() // Generate a funding proof const result = await provider.generateFundingProof({ balance: 100n, minimumRequired: 50n, blindingFactor: new Uint8Array(32), assetId: '0xABCD', }) console.log(result.proof) // Proof bytes console.log(result.publicInputs) // Public inputs ``` ### 浏览器端证明 Circuit 已通过 WASM 针对浏览器执行进行了优化： ``` import { BrowserNoirProvider } from '@sip-protocol/sdk' // Browser-compatible proving const provider = new BrowserNoirProvider() await provider.initialize() // Proof generation happens client-side const proof = await provider.generateFundingProof({ ... }) ``` ## 💻 开发 ### 命令 ``` nargo compile # Compile circuit to ACIR nargo test # Run circuit tests nargo info # Show constraint count nargo prove # Generate proof (needs Prover.toml) nargo verify # Verify proof nargo check # Type check without compiling ``` ### 编写测试 ``` // In src/main.nr #[test] fn test_valid_funding() { let balance = 100; let minimum = 50; let blinding = 12345; // This should pass main( pedersen_hash(balance, blinding), minimum, 1, // asset_id balance, blinding ); } #[test(should_fail)] fn test_insufficient_balance() { let balance = 30; let minimum = 50; // This should fail: 30 < 50 main(...); } ``` ### 添加新 Circuit 1. 创建目录：`mkdir new_circuit && cd new_circuit` 2. 初始化：`nargo init` 3. 在 `src/main.nr` 中实现 circuit 4. 添加测试 5. 编译：`nargo compile` 6. 与 SDK 集成 ## 📋 规范 文档中的详细规范： | 规范 | 链接 | |------|------| | Funding Proof | [docs.sip-protocol.org/specs/funding-proof](https://docs.sip-protocol.org/specs/funding-proof) | | Validity Proof | [docs.sip-protocol.org/specs/validity-proof](https://docs.sip-protocol.org/specs/validity-proof) | | Fulfillment Proof | [docs.sip-protocol.org/specs/fulfillment-proof](https://docs.sip-protocol.org/specs/fulfillment-proof) | ## 🔗 相关项目 | 项目 | 描述 | 链接 | |---------|-------------|------| | **sip-protocol** | 核心 SDK（使用编译后的 circuit） | [GitHub](https://github.com/sip-protocol/sip-protocol) | | **docs-sip** | Circuit 规范 | [docs.sip-protocol.org](https://docs.sip-protocol.org) | | **Noir** | ZK DSL 文档 | [noir-lang.org](https://noir-lang.org/docs) | | **Barretenberg** | 证明后端 | [GitHub](https://github.com/AztecProtocol/barretenberg) | ## 📄 许可证 [MIT License](LICENSE) — 详情请参阅 LICENSE 文件。

标签：区块链, 密码学, 手动系统调用, 智能合约, 隐私计算, 零知识证明