name: midnight-core-concepts:architecture description: 当询问关于Midnight交易结构、系统架构、构建模块、Zswap/Kachina/Impact组件如何组合、绑定、承诺或Schnorr证明时使用。

Midnight 架构

Midnight 将零知识证明、屏蔽代币和智能合约结合成一个统一的隐私保护系统。理解各个部分如何连接对于构建应用程序至关重要。

系统概览

┌─────────────────────────────────────────────────────────┐
│                    Midnight 网络                        │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Zswap     │  │   Kachina   │  │   Impact    │     │
│  │  (代币)     │←→│ (合约)      │←→│    (虚拟机) │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
│         ↑                ↑                ↑             │
│         └────────────────┼────────────────┘             │
│                          │                              │
│              ┌───────────────────────┐                  │
│              │   ZK 证明系统        │                  │
│              │   (ZK SNARKs)        │                  │
│              └───────────────────────┘                  │
└─────────────────────────────────────────────────────────┘

交易剖析

每个 Midnight 交易包含：

交易 {
  guaranteed_zswap_offer,    // 必需：代币操作
  fallible_zswap_offer?,     // 可选：可能失败的代币操作
  contract_calls?,           // 可选：合约交互
  binding_randomness         // 密码学绑定
}

保证执行 vs 容错执行

部分	行为
保证执行	必须成功，否则整个交易被拒绝
容错执行	可能失败，不影响保证执行部分

使用场景：保证执行部分收取费用。容错执行部分尝试交换。如果交换失败，费用仍被收取。

构建模块

1. Zswap 报价

代币移动层：

报价 {
  inputs: 代币[],      // 花费的代币（零知识证明）
  outputs: 代币[],     // 创建的代币（承诺）
  transient: 代币[],   // 在同一交易中创建并花费
  balance: Map<类型, 价值>  // 每种代币的净价值
}

2. 合约调用

计算层：

合约调用 {
  guaranteed_transcript,     // 可见效果
  fallible_transcript,       // 可能失败的效果
  communication_commitment,  // 跨合约通信（未来）
  zk_proofs                  // 有效性证明
}

3. 密码学绑定

所有组件通过以下方式绑定在一起：

Pedersen 承诺 - 同态价值绑定
Schnorr 证明 - 合约贡献不携带隐藏价值
ZK 证明 - 交易记录有效性

交易完整性

同态承诺

Midnight 扩展了 Zswap 的 Pedersen 承诺方案：

承诺(v1) + 承诺(v2) = 承诺(v1 + v2)

这允许验证总价值而无需揭示单个价值。

绑定机制

交易绑定确保：
1. Zswap 价值平衡（输入 = 输出 + 费用）
2. 合约效果与证明匹配
3. 所有组件密码学链接
4. 无中生有价值

状态架构

账本结构

账本 {
  zswap_state: {
    coin_commitments: 默克尔树,
    free_slot_index: 索引,
    nullifier_set: 集合<零知识证明>,
    valid_roots: 集合<默克尔根>
  },
  contract_map: 映射<地址, 合约状态>
}

合约状态

合约状态 {
  public_fields: 映射<名称, 值>,
  merkle_trees: 映射<名称, 默克尔树>,
  sets: 映射<名称, 集合>
}

执行流程

交易处理

1. 格式良好性检查（无状态）
   ├─ 格式验证
   ├─ ZK 证明验证
   ├─ Schnorr 证明验证
   ├─ 余额验证
   └─ 声明匹配

2. 保证执行（有状态）
   ├─ 合约查找
   ├─ Zswap 报价应用
   ├─ 合约调用执行
   └─ 状态持久化

3. 容错执行（有状态，可能失败）
   ├─ 类似于保证执行
   └─ 失败不会回滚保证执行

合约调用执行

对于每个合约调用：
1. 查找合约状态
2. 根据电路验证 ZK 证明
3. 执行 Impact 程序
4. 验证效果与声明的效果匹配
5. 更新状态

合并交易

Zswap 支持原子组合：

交易1 (参与方 A)     交易2 (参与方 B)
     ↓                     ↓
     └─────┬───────────────┘
           ↓
    合并交易
    (原子性，全部成功或全部失败)

合并规则

至少一个交易必须具有空的合约调用
合并时价值必须平衡
证明保持独立有效

地址派生

合约地址 = 哈希(部署数据)
代币类型 = 哈希(合约地址, 域分隔符)
代币承诺 = Pedersen(类型, 价值, 所有者, 随机性)
零知识证明 = 哈希(承诺, 所有者秘密)

组件集成

代币如何流动

用户钱包                    合约
    │                          │
    │ ──── Zswap 输入 ──────→  │  (花费代币)
    │                          │
    │ ←─── Zswap 输出 ──────── │  (接收代币)
    │                          │
    │ ──── 合约调用 ────────→  │  (调用逻辑)

隐私如何工作

私有域              公共域
──────────────      ─────────────
用户秘密     ──ZK 证明──→  交易记录
本地状态                    状态变更
默克尔路径                  零知识证明
见证数据                    承诺

实用模式

简单价值转移

1. 构建 Zswap 报价
   - 输入：您的代币（创建零知识证明）
   - 输出：接收者代币（创建承诺）
2. 余额必须为零（减去费用）
3. 生成 ZK 证明
4. 提交交易

合约交互

1. 准备见证数据（私有输入）
2. 构建合约调用
3. 生成 ZK 证明（证明有效执行）
4. 可选地与 Zswap 报价组合
5. 提交交易

原子交换

1. 参与方 A：创建部分报价（给出 TokenX）
2. 参与方 B：创建部分报价（给出 TokenY，想要 TokenX）
3. 链下合并报价
4. 提交合并交易
5. 两次转移原子性完成

参考资料

详细技术信息：

references/transaction-deep-dive.md - 完整的交易结构
references/state-management.md - 账本操作，状态转换
references/cryptographic-binding.md - Pedersen, Schnorr, 证明组合

示例

工作模式：

examples/transaction-construction.md - 逐步构建交易