Naveenub/zksn

# 零知识主权网络 (ZKSN) [](./LICENSE) []() [](https://www.rust-lang.org/) [](https://soliditylang.org/) [](./CONTRIBUTING.md) ## 目录 1. [ZKSN 是什么？](#what-is-zksn) 2. [核心原则](#core-principles) 3. [架构](#architecture) 4. [仓库结构](#repository-structure) 5. [技术栈](#tech-stack) 6. [快速开始](#quick-start) 7. [运行 Mix Node](#running-a-mix-node) 8. [客户端 CLI](#client-cli) 9. [配置参考](#configuration-reference) 10. [密码学设计](#cryptographic-design) 11. [经济层](#economic-layer) 12. [治理](#governance) 13. [基础设施与部署](#infrastructure--deployment) 14. [开发](#development) 15. [威胁模型](#threat-model) 16. [法律](#legal) 17. [路线图](#roadmap) 18. [贡献](#contributing) 19. [安全](#security) 20. [许可证](#license) ## ZKSN 是什么？ ZKSN 是一个**闭环、隐私保护的 P2P 网络**的生产级参考实现。每一层都围绕一个单一不变量设计：**任何参与者、节点、观察者或运营商都不应能够得知谁在与谁通信、通信内容是什么或何时通信。** 该网络通过五种正交、独立可验证的机制实现这一点： 1. **Sphinx 洋葱数据包** — 每个 Mix Node 仅解密一层加密。它只能看到上一跳和下一跳。永远无法看到源或目的地。 2. **Poisson 延迟混合** — 数据包在转发前被保留 `Exp(1/λ)` 随机间隔。即使针对监视所有链路的全球被动攻击者，时间相关性攻击也会失败。 3. **强制掩护流量** — 节点持续发出与真实流量无法区分的 `DROP` 和 `LOOP` 数据包。协议级别不允许静默。 4. **Chaumian ecash 支付** — 每包微支付使用盲签名 Token。即使是 Mint 也无法将发行与赎回关联起来。 5. **无状态节点操作** — NixOS 节点从 RAM 启动。硬件被扣押不会泄露任何信息。 ## 核心原则 | 原则 | 实现 | 保证 | |---|---|---| | 身份消除 | 仅 Ed25519 密钥对 | 从不存储电子邮件、用户名、电话或 IP | | 元数据擦除 | Sphinx + Poisson 混合 + 掩护流量 | 发送者、接收者、时间和内容均被隐藏 | | 传输主权 | Yggdrasil 加密 IPv6 Mesh | 无 IANA，无 ASN，无路由权威机构 | | 匿名服务 | I2P (i2pd) 大蒜路由 | 服务器 IP 永远不会暴露给客户端 | | 经济主权 | Cashu (Chaumian ecash) + Monero (XMR) | 不可链接的微支付，私密结算 | | 节点健忘 | NixOS tmpfs 根目录，无持久写入 | 硬件扣押产生零数据 | | 免信任治理 | 链上 ZK-SNARK 投票 | 匿名、不可胁迫、完全自主执行 | | 代码即言论 | MIT 许可证，无基金会 | 无法被扣押；受 *Bernstein v. DOJ* 保护 | ## 架构 ### 系统层图解 ``` ┌─────────────────────────────────────────────────────┐ │ User Application │ └──────────────────────────┬──────────────────────────┘ │ ┌──────────────────────────▼──────────────────────────┐ │ Layer 4 — Identity Plane │ │ Ed25519 keypair · X25519 session exchange │ │ Noise_XX handshake · No PII · Ever │ └──────────────────────────┬──────────────────────────┘ │ ┌──────────────────────────▼──────────────────────────┐ │ Layer 3 — Economic Plane │ │ Cashu blind-signed ecash · Per-packet token │ │ Monero XMR settlement · Batch redemption │ └──────────────────────────┬──────────────────────────┘ │ ┌──────────────────────────▼──────────────────────────┐ │ Layer 2 — Mixnet Plane │ │ Sphinx packets · Fixed 2048-byte size │ │ Poisson(λ) delays · DROP + LOOP cover traffic │ └──────────────────────────┬──────────────────────────┘ │ ┌──────────────────────────▼──────────────────────────┐ │ Layer 1 — Anonymous Service Plane │ │ I2P / i2pd · .b32.i2p addressing │ │ .zksn internal TLD · DHT petname resolution │ └──────────────────────────┬──────────────────────────┘ │ ┌──────────────────────────▼──────────────────────────┐ │ Layer 0 — Mesh Transport Plane │ │ Yggdrasil IPv6 mesh · Address = SHA-512(pubkey) │ │ CJDNS fallback · LoRa/Meshtastic air-gap capable │ └─────────────────────────────────────────────────────┘ ``` ### 数据包流程（发送消息） ``` [Client] │ 1. Encrypt payload with recipient X25519 public key │ 2. Build Sphinx packet: │ select random path: [mix₁, mix₂, mix₃, destination] │ layer-encrypt: Enc(Enc(Enc(payload, mix₃), mix₂), mix₁) │ 3. Attach blind-signed Cashu token │ 4. Transmit to entry mix node over Yggdrasil ▼ [Mix Node 1] ← decrypts outer layer → sees only "forward to mix₂" ← holds for Exp(1/λ) ms → emits cover traffic continuously ▼ [Mix Node 2] ← decrypts → sees only "forward to mix₃" ▼ [Mix Node 3] ← decrypts → sees only "forward to destination" ▼ [I2P Service] ← receives encrypted payload, decrypts with private key sender unknown · path unknown · timing obfuscated ``` ### 数据包结构 ``` ┌────────────────────────────────────────────────────┐ │ Sphinx Header (fixed size) │ │ ├── Ephemeral public key (32 bytes, X25519) │ │ ├── Routing header (layered encrypted, 96 bytes) │ │ └── MAC chain │ ├────────────────────────────────────────────────────┤ │ Cashu Payment Token (blind-signed ecash) │ ├────────────────────────────────────────────────────┤ │ Payload (padded to fixed size) │ │ └── Application data (ChaCha20-Poly1305) │ └────────────────────────────────────────────────────┘ Total: FIXED 2048 bytes — eliminates length-based correlation ``` ## 仓库结构 ``` zksn/ │ ├── crypto/ # Cryptographic primitives (no external I/O) │ └── src/ │ ├── identity.rs # Ed25519 keypair · sign/verify · fingerprinting │ ├── sphinx.rs # Sphinx packet build/unwrap · fixed 2048B · cover packets │ ├── noise.rs # Noise_XX handshake · mutual auth · forward secrecy │ └── zkp.rs # Merkle membership tree · nullifiers · DAO credentials ├── node/ # Mix node binary (zksn-node) │ ├── src/ │ │ ├── main.rs # CLI entry point (clap) · config load · tracing init │ │ ├── node.rs # Subsystem orchestrator · TCP listener · channel wiring │ │ ├── mixer.rs # Poisson delay pool · Exp(λ) sampling · reordering │ │ ├── cover.rs # DROP + LOOP cover traffic generator │ │ ├── router.rs # TCP packet forwarding · fixed-size framing │ │ ├── config.rs # TOML config · IdentityHolder · defaults │ │ ├── metrics.rs # Prometheus counters/gauges/histograms (local only) │ │ └── lib.rs # Module exports │ ├── node.toml.example # Fully annotated config template │ └── README.md ├── client/ # Client library + CLI (zksn) │ ├── src/ │ │ ├── lib.rs # ZksnClient API · send() · receive() │ │ ├── send.rs # Encrypt → Sphinx → attach token → transmit │ │ ├── receive.rs # TCP listener · decrypt · deliver │ │ ├── route.rs # Random route selection (DHT integration pending) │ │ └── config.rs # ClientConfig · entry node · hop count · mint URL │ ├── cli/ │ │ └── main.rs # identity · send · receive · wallet subcommands │ └── README.md ├── economic/ # Payment layer │ └── src/ │ ├── cashu.rs # Cashu NUT-00 tokens · blind signatures · batch redemption │ ├── monero.rs # Monero RPC · stealth addresses · piconero conversion │ ├── token.rs # PacketToken — Cashu token attached to Sphinx packets │ └── lib.rs ├── governance/ # DAO smart contracts (Foundry) │ ├── contracts/ │ │ ├── ZKSNGovernance.sol # Core DAO · ZK voting · time-lock · autonomous execution │ │ ├── IVerifier.sol # Interface for ZK-SNARK verifier │ │ └── MockVerifier.sol # Always-true + StrictMock verifiers for tests │ ├── scripts/ │ │ └── Deploy.s.sol # Foundry deployment script │ ├── test/ │ │ └── ZKSNGovernance.t.sol # 20 tests: voting · double-vote · quorum · time-lock │ ├── foundry.toml │ └── README.md ├── infra/ │ ├── nixos/ │ │ ├── node.nix # RAM-only NixOS · tmpfs root · Yggdrasil · dm-verity · LUKS2 │ │ └── README.md │ └── docker/ │ ├── docker-compose.yml # 7-service devnet: 3 mix nodes + 2 Yggdrasil + i2pd + Cashu mint │ ├── Dockerfile.mixnode # Multi-stage Rust build → Debian slim │ ├── Dockerfile.client # Multi-stage Rust build → Debian slim │ └── config/ │ ├── i2pd.conf # i2pd settings (HTTP 4444 · SOCKS 4447 · console 7070) │ ├── tunnels.conf # i2pd tunnel definitions │ ├── yggdrasil-seed.conf # Seed node · multicast discovery │ ├── yggdrasil-peer.conf # Peer node · connects to seed │ └── cashu.env # Cashu mint env (FakeWallet for dev) ├── scripts/ │ ├── gen-identity.sh # Ed25519 keypair generator · fingerprint · secure permissions │ └── bootstrap-seed.sh # Seed node setup: Yggdrasil + i2pd + identity + Cashu mint ├── docs/ │ ├── ARCHITECTURE.md # Full 5-layer technical blueprint │ ├── THREAT_MODEL.md # 6 adversary classes with mitigations │ ├── LEGAL.md # Mere conduit · Bernstein · Tornado Cash analysis │ └── ROADMAP.md # 8-phase development plan ├── .github/ │ ├── workflows/ │ │ └── ci.yml # Rust (clippy · test · audit) + Foundry (forge test) │ ├── ISSUE_TEMPLATE/ │ │ ├── bug_report.md │ │ └── feature_request.md │ └── PULL_REQUEST_TEMPLATE.md # Crypto review checklist ├── Cargo.toml # Workspace (node · client · crypto · economic) ├── Cargo.lock ├── flake.nix # Nix dev shell: Rust 1.78 · Foundry · Yggdrasil · i2pd · just ├── Justfile # 30+ developer commands (build · test · devnet · contracts) ├── CHANGELOG.md ├── CONTRIBUTING.md # Anonymous contribution guide · GPG · Tor/I2P push ├── SECURITY.md # Responsible disclosure · severity matrix ├── LICENSE # MIT └── README.md ``` ## 技术栈 | 组件 | 技术 | 版本 | 用途 | |---|---|---|---| | 节点实现 | Rust | 1.75+ | Mix node，客户端，密码学原语 | | 异步运行时 | Tokio | 1.x | 所有异步 I/O | | Mesh 传输 | [Yggdrasil](https://yggdrasil-network.github.io/) | latest | 加密 IPv6 Mesh，地址 = 密钥 | | Mesh 传输 (备选) | [CJDNS](https://github.com/cjdelisle/cjdns) | latest | 冗余覆盖层，不同的路由 | | 匿名服务 | [I2P (i2pd)](https://i2pd.website/) | latest | .b32.i2p 服务托管 | | 数据包格式 | Sphinx | custom | 固定大小的洋葱数据包 | | 节点握手 | [Noise Protocol](https://noiseprotocol.org/) `XX` | snow 0.9 | 相互认证，前向保密 | | 签名 | Ed25519 | ed25519-dalek 2 | 节点身份 | | 密钥交换 | X25519 | x25519-dalek 2 | 会话 ECDH | | 加密 | ChaCha20-Poly1305 | chacha20poly1305 0.10 | 数据包负载 | | 哈希 | SHA-256 / SHA-512 | sha2 0.10 | 指纹，Merkle 树 | | 微支付 | [Cashu](https://cashu.space/) | NUT-00 | 盲签每包 ecash | | 结算 | [Monero (XMR)](https://getmonero.org/) | RPC v2 | 私密链上结算 | | 治理 | Solidity 0.8.20 | Foundry | ZK-SNARK 匿名投票 DAO | | ZK 证明 | 验证器接口 | pluggable | 兼容 Circom / Noir / Halo2 | | 节点操作系统 | [NixOS](https://nixos.org/) | 24.x | 仅 RAM，可复现构建 | | 开发环境 | Nix flakes + just | — | 可复现 Shell，30+ 快捷方式 | | 指标 | Prometheus | 0.13 | 仅本地，从不传输 | | CI | GitHub Actions | — | Rust + Foundry 流水线 | ## 快速开始 ### 前置条件 ``` # Rust (稳定版 1.75+) curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Foundry (用于治理合约) curl -L https://foundry.paradigm.xyz | bash && foundryup # (可选) Nix — 一条命令即可获得所有内容 nix develop # inside the repo root ``` ### 克隆并构建 ``` git clone https://github.com/Naveenob/zksn.git cd zksn # 构建所有 crates cargo build --release # 或使用 just (推荐) just build-release ``` ### 生成您的身份 ``` # 使用 shell 脚本 chmod +x scripts/gen-identity.sh ./scripts/gen-identity.sh # → identity.pub (分享此文件) # → identity.key (绝不可分享 — 存储 32 字节 Ed25519 密钥) # 或通过 CLI ./target/release/zksn identity generate --output ~/.zksn/identity.key ``` ### 启动开发网络 (Docker) ``` cd infra/docker docker compose up # 启动：3 个 mix nodes + 2 个 Yggdrasil nodes + i2pd + Cashu mint ``` ### 运行测试 ``` # 所有 Rust 单元 + 集成测试 cargo test --workspace # 治理合约 (Foundry) cd governance && forge test -vv # 通过 just 完成所有操作 just test-all ``` ## 运行 Mix Node ### 1. 配置 ``` cp node/node.toml.example node.toml $EDITOR node.toml ``` 关键参数： ``` [network] listen_addr = "[200:your:yggdrasil:addr::1]:9001" # Yggdrasil IPv6 in production max_peers = 64 bootstrap_peers = [ "[200:abcd:1234:5678::1]:9001", # Known seed nodes ] [mixing] poisson_lambda_ms = 200 # Mean delay: 200ms. Higher = more anonymity, more latency. cover_traffic_rate = 5 # Cover packets/sec. Set ≥ expected real traffic rate. max_queue_depth = 10000 # DoS protection: drop after this many queued packets. loop_cover_fraction = 0.3 # 30% LOOP (verify liveness), 70% DROP (pure cover) [economic] cashu_mint_url = "http://mint.zksn.internal:3338" monero_rpc_url = "http://127.0.0.1:18082" redemption_batch_size = 100 # Batch to reduce linkability [keys] persist_identity = false # false = ephemeral key per boot (fully stateless) ``` ### 2. 运行 ``` # 开发 cargo run --package zksn-node -- --config node.toml # 生产二进制文件 ./target/release/zksn-node --config node.toml # Testnet (无支付强制) ./target/release/zksn-node --config node.toml --testnet # Debug 日志 ./target/release/zksn-node --config node.toml --debug ``` ### 3. 节点启动输出 ``` ╔══════════════════════════════════════╗ ║ ZKSN Mix Node — Starting Up ║ ╚══════════════════════════════════════╝ Node ID: a3f8:c2d1:9e47:... Listen: [200:abcd::1]:9001 Poisson λ: 200ms Cover rate: 5 pkt/s Testnet: false Mix node ready — accepting Sphinx packets ``` ### 4. 内部子系统架构 ``` [TCP :9001] → handle_connection() │ tx_incoming (mpsc channel) ▼ [PoissonMixer] ← cover packets ← [CoverTrafficGenerator] Exp(1/λ) delay pool Pool reordering │ tx_outgoing (mpsc channel) ▼ [PacketRouter] → TCP → next hop (fixed PACKET_SIZE bytes) ``` 所有四个子系统作为独立的 Tokio 任务运行，通过有界通道进行通信。 ## 客户端 CLI `zksn` 二进制文件提供了完整的命令行界面。 ``` # 构建 CLI cargo build --release --package zksn-client # 或使用 just just build-client ``` ### 命令 ``` zksn [OPTIONS] Options: -k, --key Path to identity key file -n, --node Entry mix node address (default: [::1]:9001) -d, --debug Enable debug logging Commands: identity generate [--output ] Create a new Ed25519 keypair identity show Display current identity fingerprint send Send encrypted message through mixnet receive Listen for incoming messages (blocks) wallet balance Show Cashu token balance wallet topup Top up via XMR payment to mint ``` ### 使用示例 ``` # 生成并保存 identity zksn identity generate --output ~/.zksn/identity.key # 显示你的指纹 (分享此信息以便他人联系你) zksn --key ~/.zksn/identity.key identity show # → Identity: a3f8c2d19e47... # 发送消息 zksn --key ~/.zksn/identity.key \ --node [200:abcd::1]:9001 \ send a3f8c2d19e47... "Hello, sovereign network." # 监听消息 zksn --key ~/.zksn/identity.key receive # 正在以 a3f8c2d19e47... 身份监听消息 # 按 Ctrl+C 停止。 ``` ## 配置参考 ### 节点 (`node.toml`) | 部分 | 键 | 默认值 | 描述 | |---|---|---|---| | `[network]` | `listen_addr` | `[::1]:9001` | Sphinx 数据包监听器。生产环境中使用 Yggdrasil IPv6。 | | | `max_peers` | `64` | 最大并发对等 TCP 连接数。 | | | `connect_timeout_ms` | `5000` | 出站连接超时。 | | | `bootstrap_peers` | `[]` | 启动时连接的已知种子节点地址。 | | `[mixing]` | `poisson_lambda_ms` | `200` | 平均混合延迟（毫秒）。实际延迟 ~ Exp(1/λ)。 | | | `cover_traffic_rate` | `5` | 掩护数据包/秒。`0` 禁用掩护流量（不安全）。 | | | `max_queue_depth` | `10000` | 丢弃前混合池中的最大数据包数（DoS 保护）。 | | | `loop_cover_fraction` | `0.3` | LOOP 与 DROP 的掩护比例。 | | `[economic]` | `cashu_mint_url` | — | 用于 Token 验证的 Cashu Mint 端点。 | | | `min_token_value` | `1` | 每个数据包的最小 Token 值。 | | | `monero_rpc_url` | `http://127.0.0.1:18082` | 用于结算的 Monero RPC。 | | | `redemption_batch_size` | `100` | 赎回前批量处理此数量的 Token（减少可链接性）。 | | `[keys]` | `key_store_path` | `/var/lib/zksn/keys/identity.key` | 加密密钥文件的路径。 | | | `persist_identity` | `false` | `false` = 每次启动生成新密钥（仅 RAM / 无状态）。 | ### 匿名性调优 | 场景 | `poisson_lambda_ms` | `cover_traffic_rate` | 备注 | |---|---|---|---| | 交互式消息传递 | 100–300 | 5–10 | 低延迟，合理的匿名性 | | 高安全性异步 | 1000–5000 | 10–20 | 高延迟，强匿名性 | | 高吞吐量中继 | 50–100 | 20–50 | 吞吐量优化，较弱的时间抵抗力 | | 研究/测试网 | 1–10 | 0–1 | 快速反馈，无匿名保证 | ## 密码学设计 ### 身份 (`crypto/src/identity.rs`) - **算法：** Ed25519 (通过 `ed25519-dalek` 2.x) - **密钥生成：** `ZksnIdentity::generate()` — 通过 OS 熵的安全随机 - **指纹：** `SHA-256(public_key)[0..8]` 显示为十六进制 — 人类可识别的短句柄 - **秘密导出：** `to_secret_bytes()` — 32 字节原始秘密；通过 `zeroize` 实现归零丢弃 ### Sphinx 数据包 (`crypto/src/sphinx.rs`) - **数据包大小：** 固定 `PACKET_SIZE = 2048` 字节 — 所有数据包长度相同 - **临时密钥：** 头部中的 32 字节 X25519 公钥 - **路由头部：** 分层加密的 96 字节 — 每一跳解密一层 - **负载：** ChaCha20-Poly1305 加密的应用数据 - **掩护类型：** `PacketType::Drop`（随机目的地）· `PacketType::Loop`（路由回发送者） - **ECDH 注：** X25519 密钥派生标记为 `todo!()` — 故意留给贡献者仔细实现。参见内联注释。 ### Noise 握手 (`crypto/src/noise.rs`) 模式：`Noise_XX_25519_ChaChaPoly_SHA256` ``` → e ← e, ee, s, es → s, se ``` - **相互认证** — 双方证明拥有静态密钥 - **前向保密** — 每个会话使用临时密钥；密钥泄露后过去的会话仍然安全 - **身份隐藏** — 静态密钥加密传输；线路上无明文身份 - **实现：** `snow` 0.9 库；带有 2 个通过集成测试的 `NoiseInitiator` / `NoiseResponder` 结构体 ### ZK 凭证 (`crypto/src/zkp.rs`) - **承诺：** `SHA-256(secret || nonce)` — 在不透露身份的情况下绑定成员资格 - **Merkle 树：** 基于成员承诺的二叉树；根存储在治理合约的链上 - **Nullifier：** `SHA-256(secret || proposal_id)` — 每对 (成员, 提案) 唯一；防止双重投票而不泄露成员 - **生产注：** 将 SHA-256 替换为 Poseidon 哈希以兼容 ZK-SNARK 电路 ## 经济层 ### 概述 ``` [User] │ Sends XMR to mint's stealth address ▼ [Cashu Mint] │ Issues blind-signed ecash tokens (NUT-00) │ Cannot link issued token to redemption → no usage tracking ▼ [Client] │ Attaches token to each Sphinx packet ▼ [Mix Node] │ Validates token, forwards packet │ Batches N tokens (default: 100) before redeeming │ → batch redemption breaks per-packet linkability ▼ [Cashu Mint] │ Redeems batch → pays out in XMR to node's stealth address ▼ [Monero Network] RingCT + ring signatures + stealth addresses → on-chain amounts and senders private ``` ### Cashu (`economic/src/cashu.rs`) 实现 Cashu NUT-00： - `CashuToken` — 盲签名证明包，Mint URL，面额证明 - `CashuWallet` — 本地余额跟踪，批量赎回队列 - 盲签名协议：客户端盲化秘密 → Mint 签名盲化点 → 客户端去盲 → Mint 无法链接 - **隐私属性：** 即使是 Mint 运营商也对使用模式一无所知 ### Monero (`economic/src/monero.rs`) - 用于 `monero-wallet-rpc` 的 JSON-RPC 客户端 - `get_balance()` `new_subaddress()` · `transfer()` - Piconero (`u64`) ↔ XMR (`f64`) 转换工具 - 隐身地址：每笔付款生成一个全新的一次性地址 ### 每包 Token (`economic/src/token.rs`) `PacketToken` 将 Cashu 证明序列化到 Sphinx 数据包负载中，与加密消息并存。Mix Node 在转发前验证 Token，拒绝无付费的数据包。 ## 治理 ZKSN 由一个匿名的链上 DAO 治理，没有具名的管理员。 ### 合约：`ZKSNGovernance.sol` ``` No multisig. No admin. No upgradeable proxy. Protocol changes execute autonomously after vote + time-lock. ``` | 参数 | 值 | |---|---| | 投票期 | 7 天 | | 时间锁 | 2 天 | | 法定人数 | 最低 10 票 | | 通过阈值 | >50% 赞成 | | 执行 | 自主（时间锁后无需调用者） | ### 投票如何运作 1. **提议：** 任何成员调用 `createProposal(contentHash)`，附带更改描述的哈希。 2. **投票：** 成员提交 ZK-SNARK 证明，证明： 属于有效成员资格凭证， 尚未对此提案投票， 投票值（0/1）。该证明不透露任何关于身份的信息。 3. **执行：** 投票结束且时间锁到期后，任何人调用 `execute(proposalId)`。合约自主运行编码的调用。 4. **成员更新：** 新成员仅通过治理投票添加 — 没有管理员可以单方面修改成员根。 ### ZK 证明接口 ``` interface IVerifier { function verifyProof( bytes calldata proof, uint256[4] calldata publicSignals // [nullifierHash, proposalId, voteValue, membershipRoot] ) external view returns (bool); } ``` 兼容任何 ZK-SNARK 系统（Circom + SnarkJS, Noir, Halo2）。无需更改治理逻辑即可交换验证器合约。 ### Foundry 测试 ``` cd governance forge test -vv # 20 项测试通过： # ✓ 提案创建和事件 # ✓ 带.nullifiers 的赞成/反对投票 # ✓ 防止双重投票 # ✓ 投票截止日期强制执行 # ✓ 无效证明拒绝 # ✓ 法定人数要求 (最少 10 票) # ✓ 多数门槛 (>50%) # ✓ 时间锁强制执行 # ✓ 单次执行 # ✓ 仅通过治理更新 membership root ``` ## 基础设施与部署 ### 生产环境：NixOS (`infra/nixos/node.nix`) 专为 **仅 RAM 操作** 设计 — 物理扣押硬件产生零用户数据。 关键属性： | 特性 | 实现 | |---|---| | 无状态根目录 | `tmpfs` 挂载在 `/` — 重启后所有写入丢失 | | 验证启动 | 只读镜像上的 `dm-verity` | | 密钥存储 | 仅 LUKS2 加密的 USB 密钥存储 | | 网络隔离 | 防火墙仅允许 `200::/7`（Yggdrasil 空间） | | 传输 | 由 systemd 管理的 Yggdrasil + i2pd 服务 | | 内核加固 | `kernel.dmesg_restrict`, `unprivileged_bpf_disabled` 等 | | 可复现构建 | Nix flakes — 跨机器字节 identical 的二进制文件 | ``` # 部署到裸金属节点 nixos-rebuild switch --target-host root@[200:your:node:addr::1] \ --flake .#zksn-node # 从零开始引导 seed node chmod +x scripts/bootstrap-seed.sh ./scripts/bootstrap-seed.sh ``` ### 开发环境：Docker Compose (`infra/docker/`) 一个 7 服务的本地开发网，仅用于测试和开发。**不用于生产环境。** ``` cd infra/docker docker compose up # 服务： # mix-node-1:3 — 端口 9001–9003 上的 ZKSN mix nodes # yggdrasil-seed — Yggdrasil seed node # yggdrasil-peer — Yggdrasil peer node # i2pd — I2P 路由器 (HTTP 4444, SOCKS 4447) # cashu-mint — Cashu mint (FakeWallet backend, 端口 3338) ``` ### Nix 开发 Shell (`flake.nix`) ``` nix develop # 进入带有以下环境的 shell： # Rust 1.78.0 + rust-analyzer + clippy + rustfmt + llvm-tools # Yggdrasil · i2pd · Foundry · just · jq · curl · git ``` ### Justfile (30+ 命令) ``` just build # cargo build (debug) just build-release # cargo build --release just test # cargo test --workspace just test-all # Rust tests + forge test just lint # clippy --deny warnings just fmt # rustfmt + forge fmt just audit # cargo audit (vulnerability check) just devnet # docker compose up (background) just devnet-stop # docker compose down just devnet-logs # docker compose logs -f just identity # generate a fresh identity keypair just node # run node with node.toml just sol-build # forge build just sol-test # forge test -vv just anvil # local Anvil EVM node just docs # cargo doc --open just release # full release build ``` ## 开发 ### Crate 依赖图 ``` zksn-crypto ← no internal deps zksn-economic ← no internal deps zksn-node ← zksn-crypto, zksn-economic zksn-client ← zksn-crypto, zksn-economic ``` ### Workspace 布局 ``` [workspace] members = ["node", "client", "crypto", "economic"] [profile.release] opt-level = 3 lto = true codegen-units = 1 panic = "abort" ``` ### 运行测试 ``` # 完整 workspace cargo test --workspace # 带有输出的单个 crate cargo test --package zksn-crypto -- --nocapture # 治理合约 cd governance && forge test -vv # 全部一起 just test-all ``` ### 当前测试覆盖率 | Crate / 合约 | 测试 | 备注 | |---|---|---| | `zksn-crypto` | 14 | 身份签名/验证，Noise 往返，ZKP Merkle/nullifier | | `zksn-node` | 10 | 混合器 Poisson 分布，掩护发出/禁用，配置加载，节点绑定，路由器固定大小 | | `zksn-economic` | 4 | Cashu Token 编码/解码，Monero RPC 桩 | | `ZKSNGovernance.sol` | 20 | 完整的治理生命周期 | ### 已知 `todo!()` 桩 这些是**故意留给贡献者实现的** — 它们需要仔细的密码学审查： | 位置 | 描述 | |---|---| | `crypto/src/sphinx.rs` | `build_packet()` 和 `process_packet()` 中的 X25519 ECDH 密钥派生 | | `client/src/route.rs` | 基于 DHT 的实时路由选择（目前为随机） | | `node/src/cover.rs` | 用于掩护路由的实时网络注册表采样 | | `client/cli/main.rs` | Cashu `wallet balance` 和 `wallet topup`（见 `economic/src/cashu.rs`） | ## 威胁模型 ### 攻击者类别 | 类别 | 能力 | ZKSN 防御 | 残余风险 | |---|---|---|---| | **A — 本地被动** | 观察一条网络链路 | Sphinx 加密 + 固定数据包大小 | 链路级别无风险 | | **B — 全球被动 (GPA)** | 同时观察所有链路 | Poisson(λ) 混合 + 强制掩护流量 | 数月统计相关性（开放研究问题；掩护流量大幅提高成本） | | **C — 主动** | 注入、丢弃、修改、延迟数据包 | Noise MAC 拒绝修改；丢弃触发重传 | 批处理部分缓解 n-1 攻击；完全防御需要阈值混合 | | **D — 受损节点** | 控制部分 Mix Node | 多跳路由；单节点仅见一跳 | 如果攻击者同时控制入口和出口节点则存在路径相关性 | | **E — 法律/强迫** | 扣押硬件，发出传票 | 无状态仅 RAM 节点；无法人实体；匿名贡献者 | 敌对司法管辖区的基础设施运营商仍面临个人风险 | | **F — 女巫** | 创建许多虚假节点/身份 | 路由选择中的经济质押 + 节点声誉加权 | 资金充足的攻击者可尝试治理捕获 | ### 已知局限性 - **匿名集大小：** 无论密码学如何，小型网络都很容易被去匿名化。有意义的匿名性需要数百个活跃节点和用户。 - **端点安全：** ZKSN 保护网络路径，而非客户端设备。受损的端点会破坏所有网络级别的保证。 - **长期流量分析：** 即使有掩护流量，长时间观察也会导致概率性去匿名化。文献中不存在完整的解决方案。 - **引导发现：** 初始对等发现是一个弱点。与种子节点的首次接触未完全匿名化。 - **出口节点：** 任何提供 Clearnet 出口的节点在设计上都是暴露的。闭环默认设置（无出口）缓解了这一点。 完整 adversary 分析见 [docs/THREAT_MODEL.md](./docs/THREAT_MODEL.md)。 ## 法律 ZKSN 在任何司法管辖区都无法人实体、无基金会、无高管、无注册代理人，也无公司资产。这是一个深思熟虑的架构决策。 **关键法律基础：** | 基础 | 来源 | 相关性 | |---|---|---| | 代码即言论 | *Bernstein v. DOJ*, 9th Cir. 1999 | 发布此代码库是受保护的行为 | | 加密软件 | *Junger v. Daley*, 6th Cir. 2000 | 加密工具是受保护的表达 | | 单纯传输 | DSA Art. 4 (EU) · CDA §230 (US) | Mix Node 运营商不看、不存储或不控制转发的內容 | | 司法管辖区碎片化 | 目标：30+ 国家，无任何国家节点占比 >15% | 无单方法院命令能影响超过一小部分网络 | Mix Node 运营商传输他们无法阅读且不知道内容的加密数据包。这在结构上类似于 ISP 公共承运人地位。 **运营商应该：** 1. 了解其当地关于匿名化工具的法律 2. 记录其节点的非商业、研究/教育目的 3. 仔细考虑出口流量 — 仅混合节点比出口节点风险低得多 4. 在法治健全和数据保护框架强大的司法管辖区运营 完整司法管辖区分析和判例法见 [docs/LEGAL.md](./docs/LEGAL.md)。 ## 路线图 | 阶段 | 描述 | 状态 | |---|---|---| | **0 — 密码学基础** | Ed25519, X25519, Noise_XX, Sphinx, ZKP 原语 | 🟡 进行中 — X25519 ECDH 待定 | | **1 — Mesh 传输** | Yggdrasil 集成，种子节点工具，对等发现 | 🟡 基础设施已搭建，DHT 待定 | | **2 — Mixnet 层** | Poisson 混合，掩护流量，Sphinx 路由，指标 | 🟡 核心已实现，ECDH 接线待定 | | **3 — 内部服务层** | i2pd 集成，.zksn TLD，DHT petnames，消息传递 | 🔴 未开始 | | **4 — 经济层** | Cashu NUT-00，每包 Token，XMR 结算 | 🟡 已搭建脚手架，Mint 集成待定 | | **5 — 无状态节点操作系统** | NixOS 实时启动，dm-verity，LUKS2，可复现构建 | 🟡 配置已写入，硬件测试待定 | | **6 — DAO 治理** | ZK-SNARK 投票合约，成员资格凭证 | 🟡 Solidity 完成，ZK 电路待定 | | **7 — 客户端 SDK 与 CLI** | Rust 库，Python 绑定，完整 CLI | 🟡 已搭建脚手架，DHT 路由待定 | | **8 — 加固与审计** | 外部密码学审计，GPA 模拟，漏洞赏金 | 🔴 未开始 | **最小可行网络** = 阶段 0–3 完成：匿名身份 + 无元数据消息传递 + 内部服务托管。 详细分阶段里程碑见 [docs/ROADMAP.md](./docs/ROADMAP.md)。 ## 贡献 欢迎贡献。尊重匿名 — 您无需使用真名贡献。 ``` # 设置匿名 git identity git config user.name "anon" git config user.email "anon@zksn.invalid" # 生成匿名 GPG 密钥 gpg --batch --gen-key <

标签：Cashu电子现金, Mixnet, P2P混合网络, Rust, Solidity, Sphinx Packets, ZKSN, 元数据隐私, 匿名通信, 去中心化, 可视化界面, 密码学主权, 抗审查, 抗监控, 斯芬克斯数据包, 泊松混合, 洋葱路由, 网络安全, 网络安全, 网络流量审计, 自定义请求头, 请求拦截, 通知系统, 门罗币结算, 隐私保护, 隐私保护, 零知识证明治理