369 lines
9.7 KiB
Markdown
369 lines
9.7 KiB
Markdown
# nac-csnp-l0 模块深度分析报告
|
||
|
||
**模块名称**: nac-csnp-l0
|
||
**版本**: 0.1.0
|
||
**分析日期**: 2026-02-18
|
||
**分析人员**: NAC开发团队
|
||
|
||
---
|
||
|
||
## 📋 模块概览
|
||
|
||
**功能定位**: CSNP L0层 - 宪政结构化网络协议基础层实现
|
||
**英文全称**: Constitutional Structured Network Protocol - Layer 0 Implementation
|
||
**代码行数**: 619行
|
||
**完成度**: 85%
|
||
**测试覆盖**: 7个测试全部通过
|
||
|
||
---
|
||
|
||
## 🏗️ 架构设计
|
||
|
||
### 核心组件
|
||
|
||
nac-csnp-l0实现了CSNP协议的L0层，包含两个核心子系统：
|
||
|
||
1. **GIDS** - Global Identity Directory Service（全域身份目录服务）
|
||
2. **AA-PE** - Asset-Aware Propagation Engine（资产感知传播引擎）
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
nac-csnp-l0/
|
||
├── Cargo.toml
|
||
├── README.md
|
||
└── src/
|
||
├── lib.rs (42行) - 统一接口
|
||
├── gids/
|
||
│ └── mod.rs (256行) - 全域身份目录服务
|
||
└── aa_pe/
|
||
└── mod.rs (324行) - 资产感知传播引擎
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 依赖关系
|
||
|
||
```toml
|
||
[dependencies]
|
||
nac-udm = { path = "../nac-udm" } # NAC统一定义模块
|
||
tokio = { version = "1", features = ["full"] } # 异步运行时
|
||
libp2p = { version = "0.53", features = ["tcp", "noise", "yamux", "kad", "mdns", "gossipsub"] } # P2P网络
|
||
serde = { version = "1.0", features = ["derive"] } # 序列化
|
||
serde_json = "1.0"
|
||
thiserror = "1.0" # 错误处理
|
||
tracing = "0.1" # 日志追踪
|
||
dashmap = "5.5" # 并发哈希表
|
||
lru = "0.12" # LRU缓存
|
||
blake3 = "1.5" # Blake3哈希
|
||
```
|
||
|
||
**关键依赖**:
|
||
- **nac-udm**: 提供Address、Hash等基础类型
|
||
- **libp2p**: P2P网络协议栈（支持Kademlia DHT、mDNS、Gossipsub）
|
||
- **dashmap**: 高性能并发哈希表，用于身份注册表和资产注册表
|
||
|
||
---
|
||
|
||
## 🔍 核心功能详解
|
||
|
||
### 1. GIDS - 全域身份目录服务 (256行)
|
||
|
||
#### 1.1 多链DID格式
|
||
|
||
```rust
|
||
pub struct MultiChainDid {
|
||
pub chain_id: u64,
|
||
pub unique_id: String,
|
||
}
|
||
```
|
||
|
||
**DID格式**: `did:nac:<chain_id>:<unique_id>`
|
||
|
||
**示例**:
|
||
- `did:nac:1:alice` - NAC主链上的alice
|
||
- `did:nac:2:bob` - NAC侧链2上的bob
|
||
|
||
#### 1.2 节点身份信息
|
||
|
||
```rust
|
||
pub struct NodeIdentity {
|
||
pub root_did: MultiChainDid, // 根DID
|
||
pub chain_addresses: DashMap<u64, Address>, // 多链地址映射
|
||
pub reputation_score: f64, // 全域信誉分 (0.0-1.0)
|
||
pub kyc_level: u8, // KYC等级
|
||
pub registered_at: u64, // 注册时间戳
|
||
}
|
||
```
|
||
|
||
**核心特性**:
|
||
- **多链身份聚合**: 一个DID可以关联多条链的地址
|
||
- **全域信誉系统**: 跨链信誉分数聚合
|
||
- **KYC等级**: 支持0-255级KYC等级
|
||
|
||
#### 1.3 信誉评分机制
|
||
|
||
```rust
|
||
pub struct ReputationRecord {
|
||
pub chain_id: u64,
|
||
pub behavior_type: String, // "forward", "relay", "validate"
|
||
pub score_delta: f64, // 分数变化
|
||
pub timestamp: u64,
|
||
}
|
||
```
|
||
|
||
**行为类型**:
|
||
- `forward`: 转发消息（+分）
|
||
- `relay`: 中继数据（+分）
|
||
- `validate`: 验证区块（+分）
|
||
- `censorship`: 审查内容（-分）
|
||
|
||
**分数范围**: 0.0 - 1.0（自动clamp）
|
||
|
||
#### 1.4 核心API
|
||
|
||
| 方法 | 功能 | 参数 | 返回值 |
|
||
|------|------|------|--------|
|
||
| `register_chain` | 注册新链 | chain_id, chain_name | - |
|
||
| `register_did` | 注册新DID | root_did, kyc_level | Result<(), GidsError> |
|
||
| `associate_chain_address` | 关联链地址 | did, chain_id, address | Result<(), GidsError> |
|
||
| `resolve_did` | 通过DID查询身份 | did | Result<NodeIdentity, GidsError> |
|
||
| `resolve_address` | 通过地址反向查询DID | address | Option<String> |
|
||
| `update_reputation` | 更新信誉分数 | did, chain_id, behavior_type, score_delta | Result<(), GidsError> |
|
||
| `get_reputation` | 获取节点信誉分 | did | Result<f64, GidsError> |
|
||
| `get_high_reputation_nodes` | 获取高信誉节点列表 | min_score, limit | Vec<NodeIdentity> |
|
||
|
||
---
|
||
|
||
### 2. AA-PE - 资产感知传播引擎 (324行)
|
||
|
||
#### 2.1 传播策略类型
|
||
|
||
```rust
|
||
pub enum PropagationStrategy {
|
||
/// 即时全网广播（高流动性、低风险资产）
|
||
ImmediateBroadcast {
|
||
target_network: TargetNetwork,
|
||
max_latency_ms: u64,
|
||
},
|
||
/// 定向推送+订阅（复杂或场外资产）
|
||
DirectedPush {
|
||
target_nodes: Vec<String>, // DID列表
|
||
},
|
||
/// 警报传播通道（异常状态资产）
|
||
AlertChannel {
|
||
alert_level: AlertLevel,
|
||
notify_nodes: Vec<String>, // 监管节点、预言机
|
||
},
|
||
/// 按需请求+缓存（NFT等）
|
||
OnDemandCache {
|
||
cache_ttl_secs: u64,
|
||
},
|
||
}
|
||
```
|
||
|
||
#### 2.2 GNACS编码解析
|
||
|
||
```rust
|
||
pub struct GnacsAttributes {
|
||
pub asset_class: u8, // GG: 资产类别
|
||
pub credit_rating: u8, // CC: 信用评级
|
||
pub liquidity: u8, // LL: 流动性
|
||
pub operational_status: u8, // OO: 运营状态
|
||
pub token_standard: u8, // HH: 代币标准
|
||
pub jurisdiction: u8, // II: 主权管辖
|
||
}
|
||
```
|
||
|
||
**GNACS编码**: 48字节（前6字节为关键属性）
|
||
|
||
#### 2.3 智能传播策略决策
|
||
|
||
**决策逻辑**:
|
||
|
||
1. **异常状态 → 警报通道**
|
||
```
|
||
if operational_status != 0:
|
||
return AlertChannel
|
||
```
|
||
|
||
2. **高流动性 + 低风险 → 即时广播**
|
||
```
|
||
if asset_class == 1 && credit_rating <= 2:
|
||
return ImmediateBroadcast(All, 200ms)
|
||
```
|
||
|
||
3. **无公开市场 + 衍生品 → 定向推送**
|
||
```
|
||
if asset_class == 5 && (liquidity == 4 || liquidity == 5):
|
||
return DirectedPush
|
||
```
|
||
|
||
4. **NFT/多代币标准 → 按需缓存**
|
||
```
|
||
if token_standard == 2 || token_standard == 3:
|
||
return OnDemandCache(3600s)
|
||
```
|
||
|
||
#### 2.4 核心API
|
||
|
||
| 方法 | 功能 | 参数 | 返回值 |
|
||
|------|------|------|--------|
|
||
| `register_asset` | 注册资产 | asset_address, gnacs_encoding | Result<(), AaPeError> |
|
||
| `get_strategy` | 查询资产传播策略 | asset_address | Result<PropagationStrategy, AaPeError> |
|
||
| `subscribe` | 添加订阅节点 | asset_class, node_did | - |
|
||
| `get_subscribers` | 获取订阅节点列表 | asset_class | Vec<String> |
|
||
| `register_regulatory_node` | 注册监管节点 | node_did, level | - |
|
||
| `get_regulatory_nodes` | 获取监管节点列表 | - | Vec<String> |
|
||
| `determine_propagation_targets` | 决定传播目标 | asset_address | Result<Vec<String>, AaPeError> |
|
||
|
||
---
|
||
|
||
## 🧪 测试覆盖
|
||
|
||
### 测试结果
|
||
|
||
```
|
||
running 7 tests
|
||
test aa_pe::tests::test_gnacs_parsing ... ok
|
||
test aa_pe::tests::test_strategy_determination ... ok
|
||
test aa_pe::tests::test_asset_registration ... ok
|
||
test gids::tests::test_gids_registration ... ok
|
||
test gids::tests::test_multi_chain_did ... ok
|
||
test gids::tests::test_reputation_update ... ok
|
||
test tests::test_csnp_l0_creation ... ok
|
||
|
||
test result: ok. 7 passed; 0 failed; 0 ignored; 0 measured
|
||
```
|
||
|
||
### 测试用例详解
|
||
|
||
#### GIDS测试
|
||
|
||
1. **test_multi_chain_did** - DID格式解析
|
||
- 测试DID字符串生成和解析
|
||
- 验证格式：`did:nac:1:alice`
|
||
|
||
2. **test_gids_registration** - DID注册
|
||
- 注册链和DID
|
||
- 验证KYC等级和初始信誉分（0.5）
|
||
|
||
3. **test_reputation_update** - 信誉更新
|
||
- 测试正面行为（+0.1）
|
||
- 测试负面行为（-0.3）
|
||
- 验证分数边界（0.0-1.0）
|
||
|
||
#### AA-PE测试
|
||
|
||
1. **test_gnacs_parsing** - GNACS解析
|
||
- 解析48字节GNACS编码
|
||
- 验证属性提取
|
||
|
||
2. **test_strategy_determination** - 策略决策
|
||
- 测试高流动性低风险 → 即时广播
|
||
- 测试异常状态 → 警报通道
|
||
|
||
3. **test_asset_registration** - 资产注册
|
||
- 注册资产并自动决策策略
|
||
- 验证策略缓存
|
||
|
||
---
|
||
|
||
## 🐛 发现的问题
|
||
|
||
### 问题1: Address类型构造错误
|
||
|
||
**位置**: `src/aa_pe/mod.rs:314`
|
||
|
||
**原始代码**:
|
||
```rust
|
||
let asset_addr = Address::from([1u8; 32]);
|
||
```
|
||
|
||
**错误信息**:
|
||
```
|
||
error[E0308]: mismatched types
|
||
expected `Address`, found `[u8; 32]`
|
||
```
|
||
|
||
**修复方案**:
|
||
```rust
|
||
let asset_addr = Address::new([1u8; 32]);
|
||
```
|
||
|
||
**状态**: ✅ 已修复
|
||
|
||
---
|
||
|
||
## 📊 完成度评估
|
||
|
||
| 组件 | 代码行数 | 完成度 | 状态 |
|
||
|------|---------|--------|------|
|
||
| lib.rs | 42行 | 100% | ✅ 完成 |
|
||
| GIDS | 256行 | 90% | ✅ 基本完成 |
|
||
| AA-PE | 324行 | 80% | ⚠️ 需完善 |
|
||
| **总计** | **619行** | **85%** | **🚧 进行中** |
|
||
|
||
### 待完善功能
|
||
|
||
1. **GIDS**:
|
||
- ⏳ 实现基于libp2p的DHT分布式查询
|
||
- ⏳ 添加信誉分数衰减机制
|
||
- ⏳ 实现跨链信誉聚合算法
|
||
|
||
2. **AA-PE**:
|
||
- ⏳ 实现实际的网络传播逻辑（目前只有策略决策）
|
||
- ⏳ 集成libp2p的Gossipsub协议
|
||
- ⏳ 添加传播性能监控
|
||
|
||
3. **未实现的子模块**:
|
||
- ❌ `ftan/` - FTAN（待实现）
|
||
- ❌ `ma_rcm/` - MA-RCM（待实现）
|
||
- ❌ `uca/` - UCA（待实现）
|
||
|
||
---
|
||
|
||
## 🌟 创新亮点
|
||
|
||
1. **多链DID聚合**
|
||
- 一个身份跨多条链
|
||
- 全域信誉分数
|
||
- 支持跨链身份解析
|
||
|
||
2. **资产感知传播**
|
||
- 基于GNACS编码自动决策传播策略
|
||
- 4种传播策略覆盖不同资产类型
|
||
- 智能路由优化网络效率
|
||
|
||
3. **信誉驱动的网络**
|
||
- 信誉分数影响节点选择
|
||
- 行为记录可追溯
|
||
- 支持高信誉节点查询
|
||
|
||
---
|
||
|
||
## 🔗 模块依赖关系
|
||
|
||
```
|
||
nac-csnp-l0
|
||
├── 依赖 nac-udm (Address, Hash等基础类型)
|
||
├── 被依赖 (待分析其他模块)
|
||
└── 协作模块
|
||
├── nac-csnp-l1 (L1层)
|
||
└── nac-csnp (主模块)
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 开发建议
|
||
|
||
1. **优先级P1**: 实现libp2p集成，完成实际网络传播
|
||
2. **优先级P2**: 完善GIDS的DHT查询功能
|
||
3. **优先级P3**: 实现ftan、ma_rcm、uca子模块
|
||
4. **优先级P4**: 添加性能监控和日志追踪
|
||
|
||
---
|
||
|
||
**分析完成时间**: 2026-02-18
|
||
**下一步**: 继续分析nac-csnp-l1模块
|