905 lines
22 KiB
Markdown
905 lines
22 KiB
Markdown
# nac-serde 模块深度分析报告
|
||
|
||
**模块名称**: nac-serde
|
||
**版本**: 0.1.0
|
||
**分析日期**: 2026-02-18
|
||
**分析人员**: NAC开发团队
|
||
|
||
---
|
||
|
||
## 📋 模块概览
|
||
|
||
**功能定位**: NAC序列化框架 - GNACS编码、宪法数据序列化、RWA资产序列化
|
||
**英文全称**: NAC Serialization Framework
|
||
**代码行数**: 164行
|
||
**完成度**: 40%
|
||
**测试覆盖**: 0% (无测试)
|
||
**编译状态**: ✅ 通过
|
||
|
||
---
|
||
|
||
## 🏗️ 架构设计
|
||
|
||
### 核心功能
|
||
|
||
nac-serde是NAC公链的序列化框架，提供三大核心功能：
|
||
|
||
1. **GNACS编码**: 48位二进制资产分类编码系统
|
||
2. **宪法数据序列化**: 宪法参数的二进制和JSON序列化
|
||
3. **RWA资产序列化**: 实物资产元数据的序列化
|
||
|
||
### 技术特点
|
||
|
||
1. **多格式支持**: Binary (bincode) + JSON
|
||
2. **48位GNACS编码**: 全球NAC资产分类系统
|
||
3. **统一错误处理**: SerdeError枚举
|
||
4. **零拷贝设计**: 使用引用避免不必要的复制
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
nac-serde/
|
||
├── Cargo.toml
|
||
├── README.md
|
||
└── src/
|
||
├── lib.rs (34行) - 模块导出和错误定义
|
||
├── gnacs/
|
||
│ └── mod.rs (61行) - GNACS编码
|
||
├── constitutional/
|
||
│ └── mod.rs (41行) - 宪法数据序列化
|
||
└── rwa/
|
||
└── mod.rs (28行) - RWA资产序列化
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 依赖关系
|
||
|
||
```toml
|
||
[dependencies]
|
||
serde = { version = "1.0", features = ["derive"] } # 序列化框架
|
||
serde_json = "1.0" # JSON序列化
|
||
bincode = "1.3" # 二进制序列化
|
||
hex = "0.4" # 十六进制编码
|
||
sha2 = "0.10" # SHA256哈希
|
||
|
||
[dev-dependencies]
|
||
criterion = "0.5" # 性能基准测试
|
||
```
|
||
|
||
**关键依赖**:
|
||
- **serde**: Rust生态标准序列化框架
|
||
- **bincode**: 高效的二进制序列化（用于存储和网络传输）
|
||
- **serde_json**: JSON序列化（用于API和配置）
|
||
- **sha2**: 用于GNACS编码的哈希计算
|
||
|
||
---
|
||
|
||
## 🔍 核心功能详解
|
||
|
||
### 1. 错误处理 (lib.rs - 34行)
|
||
|
||
#### 1.1 错误类型定义
|
||
|
||
```rust
|
||
pub enum SerdeError {
|
||
InvalidEncoding(String), // 无效编码
|
||
InvalidLength(usize, usize), // 长度错误（期望，实际）
|
||
DecodingError(String), // 解码错误
|
||
SerializationError(String), // 序列化错误
|
||
}
|
||
```
|
||
|
||
**错误处理特点**:
|
||
- 实现了`Display` trait（用户友好的错误信息）
|
||
- 实现了`Error` trait（标准错误类型）
|
||
- 提供了`Result<T>`类型别名
|
||
|
||
**示例**:
|
||
```rust
|
||
pub type Result<T> = std::result::Result<T, SerdeError>;
|
||
```
|
||
|
||
---
|
||
|
||
### 2. GNACS编码 (gnacs/mod.rs - 61行)
|
||
|
||
#### 2.1 GNACS简介
|
||
|
||
**GNACS**: Global NAC Asset Classification System（全球NAC资产分类系统）
|
||
|
||
**编码格式**: 48位二进制编码（6字节）
|
||
|
||
**设计目标**:
|
||
- 唯一标识480种资产场景（12类型 × 8辖区 × 5协定）
|
||
- 支持快速查询和分类
|
||
- 紧凑存储（6字节）
|
||
|
||
---
|
||
|
||
#### 2.2 GnacsCode结构
|
||
|
||
```rust
|
||
pub struct GnacsCode {
|
||
pub code: u64, // 48位编码存储在u64中（高16位为0）
|
||
}
|
||
```
|
||
|
||
**核心方法**:
|
||
|
||
##### 创建GNACS编码
|
||
```rust
|
||
pub fn new(code: u64) -> Result<Self> {
|
||
if code > 0xFFFFFFFFFFFF { // 检查是否超过48位
|
||
return Err(SerdeError::InvalidEncoding("GNACS code must be 48-bit".to_string()));
|
||
}
|
||
Ok(Self { code })
|
||
}
|
||
```
|
||
|
||
**验证**: 确保编码不超过48位（最大值：281,474,976,710,655）
|
||
|
||
---
|
||
|
||
##### 从字节数组创建
|
||
```rust
|
||
pub fn from_bytes(bytes: &[u8]) -> Result<Self> {
|
||
if bytes.len() != 6 {
|
||
return Err(SerdeError::InvalidLength(6, bytes.len()));
|
||
}
|
||
|
||
let mut code: u64 = 0;
|
||
for (i, &byte) in bytes.iter().enumerate() {
|
||
code |= (byte as u64) << (i * 8); // 小端序
|
||
}
|
||
|
||
Ok(Self { code })
|
||
}
|
||
```
|
||
|
||
**字节序**: 小端序（Little-Endian）
|
||
|
||
**示例**:
|
||
```
|
||
bytes = [0x01, 0x02, 0x03, 0x04, 0x05, 0x06]
|
||
code = 0x060504030201
|
||
```
|
||
|
||
---
|
||
|
||
##### 转换为字节数组
|
||
```rust
|
||
pub fn to_bytes(&self) -> [u8; 6] {
|
||
let mut bytes = [0u8; 6];
|
||
for i in 0..6 {
|
||
bytes[i] = ((self.code >> (i * 8)) & 0xFF) as u8;
|
||
}
|
||
bytes
|
||
}
|
||
```
|
||
|
||
**逆操作**: 将u64编码转换回6字节数组
|
||
|
||
---
|
||
|
||
##### 转换为十六进制字符串
|
||
```rust
|
||
pub fn to_hex(&self) -> String {
|
||
hex::encode(self.to_bytes())
|
||
}
|
||
```
|
||
|
||
**输出**: 12个十六进制字符（例如："010203040506"）
|
||
|
||
---
|
||
|
||
#### 2.3 GNACS编码器
|
||
|
||
```rust
|
||
pub struct GnacsEncoder;
|
||
|
||
impl GnacsEncoder {
|
||
pub fn encode(asset_type: &str, region: &str, industry: &str) -> Result<GnacsCode> {
|
||
// 1. 拼接输入
|
||
let input = format!("{}{}{}", asset_type, region, industry);
|
||
|
||
// 2. SHA256哈希
|
||
let hash = sha2::Sha256::digest(input.as_bytes());
|
||
|
||
// 3. 取前6字节
|
||
let code = u64::from_le_bytes([hash[0], hash[1], hash[2], hash[3], hash[4], hash[5], 0, 0]);
|
||
|
||
// 4. 确保48位
|
||
GnacsCode::new(code & 0xFFFFFFFFFFFF)
|
||
}
|
||
}
|
||
```
|
||
|
||
**编码算法**:
|
||
1. 拼接资产类型、地区、行业
|
||
2. 计算SHA256哈希（32字节）
|
||
3. 取前6字节作为GNACS编码
|
||
4. 确保不超过48位
|
||
|
||
**问题**: 当前实现过于简化，应该：
|
||
- 使用结构化的编码方案（而非哈希）
|
||
- 支持解码（从编码反推资产类型、地区、行业）
|
||
- 符合GNACS白皮书规范
|
||
|
||
---
|
||
|
||
#### 2.4 GNACS解码器
|
||
|
||
```rust
|
||
pub struct GnacsDecoder;
|
||
|
||
impl GnacsDecoder {
|
||
pub fn decode(code: &GnacsCode) -> Result<String> {
|
||
Ok(format!("GNACS:{}", code.to_hex()))
|
||
}
|
||
}
|
||
```
|
||
|
||
**问题**: 当前实现只是返回十六进制字符串，没有实际解码功能
|
||
|
||
**应该实现**:
|
||
```rust
|
||
pub fn decode(code: &GnacsCode) -> Result<(String, String, String)> {
|
||
// 解码出资产类型、地区、行业
|
||
let asset_type = extract_asset_type(code.code);
|
||
let region = extract_region(code.code);
|
||
let industry = extract_industry(code.code);
|
||
Ok((asset_type, region, industry))
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 宪法数据序列化 (constitutional/mod.rs - 41行)
|
||
|
||
#### 3.1 宪法数据结构
|
||
|
||
```rust
|
||
pub struct ConstitutionalData {
|
||
pub clause_id: String, // 条款ID（如"NET_CONN_MIN_CBP"）
|
||
pub param_name: String, // 参数名称
|
||
pub param_value: serde_json::Value, // 参数值（支持任意JSON类型）
|
||
pub version: u32, // 版本号
|
||
pub timestamp: u64, // 时间戳
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
|
||
| 字段 | 类型 | 说明 | 示例 |
|
||
|------|------|------|------|
|
||
| `clause_id` | String | 宪法条款ID | "NET_CONN_MIN_CBP" |
|
||
| `param_name` | String | 参数名称 | "min_connections" |
|
||
| `param_value` | serde_json::Value | 参数值 | 12 或 "value" 或 {...} |
|
||
| `version` | u32 | 版本号 | 1 |
|
||
| `timestamp` | u64 | Unix时间戳 | 1708300800 |
|
||
|
||
**设计亮点**: 使用`serde_json::Value`支持任意类型的参数值
|
||
|
||
---
|
||
|
||
#### 3.2 宪法序列化器
|
||
|
||
```rust
|
||
pub struct ConstitutionalSerializer;
|
||
|
||
impl ConstitutionalSerializer {
|
||
// 二进制序列化（用于存储和网络传输）
|
||
pub fn serialize(data: &ConstitutionalData) -> Result<Vec<u8>> {
|
||
bincode::serialize(data)
|
||
.map_err(|e| SerdeError::SerializationError(e.to_string()))
|
||
}
|
||
|
||
// JSON序列化（用于API和配置文件）
|
||
pub fn serialize_json(data: &ConstitutionalData) -> Result<String> {
|
||
serde_json::to_string(data)
|
||
.map_err(|e| SerdeError::SerializationError(e.to_string()))
|
||
}
|
||
}
|
||
```
|
||
|
||
**两种格式**:
|
||
1. **Binary (bincode)**: 紧凑、高效，用于链上存储
|
||
2. **JSON**: 可读、可编辑，用于配置和API
|
||
|
||
**示例**:
|
||
```rust
|
||
let data = ConstitutionalData {
|
||
clause_id: "NET_CONN_MIN_CBP".to_string(),
|
||
param_name: "min_connections".to_string(),
|
||
param_value: serde_json::json!(12),
|
||
version: 1,
|
||
timestamp: 1708300800,
|
||
};
|
||
|
||
// 二进制序列化
|
||
let bytes = ConstitutionalSerializer::serialize(&data)?;
|
||
|
||
// JSON序列化
|
||
let json = ConstitutionalSerializer::serialize_json(&data)?;
|
||
// {"clause_id":"NET_CONN_MIN_CBP","param_name":"min_connections","param_value":12,"version":1,"timestamp":1708300800}
|
||
```
|
||
|
||
---
|
||
|
||
#### 3.3 宪法反序列化器
|
||
|
||
```rust
|
||
pub struct ConstitutionalDeserializer;
|
||
|
||
impl ConstitutionalDeserializer {
|
||
// 二进制反序列化
|
||
pub fn deserialize(bytes: &[u8]) -> Result<ConstitutionalData> {
|
||
bincode::deserialize(bytes)
|
||
.map_err(|e| SerdeError::DecodingError(e.to_string()))
|
||
}
|
||
|
||
// JSON反序列化
|
||
pub fn deserialize_json(json: &str) -> Result<ConstitutionalData> {
|
||
serde_json::from_str(json)
|
||
.map_err(|e| SerdeError::DecodingError(e.to_string()))
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. RWA资产序列化 (rwa/mod.rs - 28行)
|
||
|
||
#### 4.1 资产元数据结构
|
||
|
||
```rust
|
||
pub struct AssetMetadata {
|
||
pub gnacs_code: String, // GNACS编码（十六进制字符串）
|
||
pub asset_name: String, // 资产名称
|
||
pub asset_type: String, // 资产类型
|
||
pub owner: String, // 所有者地址
|
||
pub value: u64, // 资产价值（单位：最小单位）
|
||
pub timestamp: u64, // 时间戳
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
|
||
| 字段 | 类型 | 说明 | 示例 |
|
||
|------|------|------|------|
|
||
| `gnacs_code` | String | GNACS编码 | "010203040506" |
|
||
| `asset_name` | String | 资产名称 | "北京朝阳区房产" |
|
||
| `asset_type` | String | 资产类型 | "Real Estate" |
|
||
| `owner` | String | 所有者地址 | "0x1234..." |
|
||
| `value` | u64 | 资产价值 | 5000000000000 (5M XTZH) |
|
||
| `timestamp` | u64 | 创建/更新时间 | 1708300800 |
|
||
|
||
**问题**: 缺少关键字段：
|
||
- 资产描述
|
||
- 资产证明（文档哈希）
|
||
- 合规状态
|
||
- 估值报告
|
||
|
||
---
|
||
|
||
#### 4.2 RWA资产序列化器
|
||
|
||
```rust
|
||
pub struct RwaAssetSerializer;
|
||
|
||
impl RwaAssetSerializer {
|
||
// 序列化
|
||
pub fn serialize(metadata: &AssetMetadata) -> Result<Vec<u8>> {
|
||
bincode::serialize(metadata)
|
||
.map_err(|e| SerdeError::SerializationError(e.to_string()))
|
||
}
|
||
|
||
// 反序列化
|
||
pub fn deserialize(bytes: &[u8]) -> Result<AssetMetadata> {
|
||
bincode::deserialize(bytes)
|
||
.map_err(|e| SerdeError::DecodingError(e.to_string()))
|
||
}
|
||
}
|
||
```
|
||
|
||
**特点**: 只支持二进制序列化（bincode），没有JSON支持
|
||
|
||
**建议**: 添加JSON序列化方法（用于API）
|
||
|
||
---
|
||
|
||
## 🐛 发现的问题
|
||
|
||
### 问题1: 缺少测试覆盖
|
||
|
||
**严重程度**: ⚠️ 高
|
||
|
||
**描述**: 模块没有任何单元测试
|
||
|
||
**影响**:
|
||
- 无法验证GNACS编码的正确性
|
||
- 无法验证序列化/反序列化的可逆性
|
||
- 无法验证错误处理
|
||
|
||
**建议测试用例**:
|
||
```rust
|
||
#[cfg(test)]
|
||
mod tests {
|
||
use super::*;
|
||
|
||
#[test]
|
||
fn test_gnacs_code_creation() {
|
||
let code = GnacsCode::new(0x123456789ABC).unwrap();
|
||
assert_eq!(code.code, 0x123456789ABC);
|
||
}
|
||
|
||
#[test]
|
||
fn test_gnacs_code_overflow() {
|
||
let result = GnacsCode::new(0x1000000000000); // 超过48位
|
||
assert!(result.is_err());
|
||
}
|
||
|
||
#[test]
|
||
fn test_gnacs_bytes_roundtrip() {
|
||
let original = GnacsCode::new(0x123456789ABC).unwrap();
|
||
let bytes = original.to_bytes();
|
||
let decoded = GnacsCode::from_bytes(&bytes).unwrap();
|
||
assert_eq!(original.code, decoded.code);
|
||
}
|
||
|
||
#[test]
|
||
fn test_constitutional_serialization_roundtrip() {
|
||
let data = ConstitutionalData {
|
||
clause_id: "TEST".to_string(),
|
||
param_name: "test_param".to_string(),
|
||
param_value: serde_json::json!(42),
|
||
version: 1,
|
||
timestamp: 1000,
|
||
};
|
||
|
||
let bytes = ConstitutionalSerializer::serialize(&data).unwrap();
|
||
let decoded = ConstitutionalDeserializer::deserialize(&bytes).unwrap();
|
||
assert_eq!(data.clause_id, decoded.clause_id);
|
||
}
|
||
|
||
#[test]
|
||
fn test_rwa_asset_serialization() {
|
||
let metadata = AssetMetadata {
|
||
gnacs_code: "010203040506".to_string(),
|
||
asset_name: "Test Asset".to_string(),
|
||
asset_type: "Real Estate".to_string(),
|
||
owner: "0x1234".to_string(),
|
||
value: 1000000,
|
||
timestamp: 1000,
|
||
};
|
||
|
||
let bytes = RwaAssetSerializer::serialize(&metadata).unwrap();
|
||
let decoded = RwaAssetSerializer::deserialize(&bytes).unwrap();
|
||
assert_eq!(metadata.asset_name, decoded.asset_name);
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态**: ❌ 待添加
|
||
|
||
---
|
||
|
||
### 问题2: GNACS编码算法不符合规范
|
||
|
||
**严重程度**: ⚠️ 高
|
||
|
||
**描述**: 当前使用SHA256哈希，而非结构化编码
|
||
|
||
**问题**:
|
||
1. 无法从编码反推资产类型、地区、行业
|
||
2. 不符合GNACS白皮书的48位结构化编码方案
|
||
3. 哈希碰撞风险
|
||
|
||
**GNACS标准编码方案**（根据白皮书）:
|
||
```
|
||
48位 = 12位资产类型 + 8位辖区 + 8位行业 + 20位保留
|
||
```
|
||
|
||
**建议实现**:
|
||
```rust
|
||
impl GnacsEncoder {
|
||
pub fn encode(asset_type: u16, region: u8, industry: u8) -> Result<GnacsCode> {
|
||
// 验证输入范围
|
||
if asset_type >= 4096 { // 2^12
|
||
return Err(SerdeError::InvalidEncoding("Asset type must be < 4096".to_string()));
|
||
}
|
||
if region >= 256 { // 2^8
|
||
return Err(SerdeError::InvalidEncoding("Region must be < 256".to_string()));
|
||
}
|
||
if industry >= 256 { // 2^8
|
||
return Err(SerdeError::InvalidEncoding("Industry must be < 256".to_string()));
|
||
}
|
||
|
||
// 结构化编码
|
||
let code = ((asset_type as u64) << 36) // 高12位
|
||
| ((region as u64) << 28) // 中8位
|
||
| ((industry as u64) << 20); // 低8位
|
||
|
||
GnacsCode::new(code)
|
||
}
|
||
}
|
||
|
||
impl GnacsDecoder {
|
||
pub fn decode(code: &GnacsCode) -> Result<(u16, u8, u8)> {
|
||
let asset_type = ((code.code >> 36) & 0xFFF) as u16;
|
||
let region = ((code.code >> 28) & 0xFF) as u8;
|
||
let industry = ((code.code >> 20) & 0xFF) as u8;
|
||
Ok((asset_type, region, industry))
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态**: ❌ 待重构
|
||
|
||
---
|
||
|
||
### 问题3: RWA资产元数据不完整
|
||
|
||
**严重程度**: ⚠️ 中等
|
||
|
||
**描述**: `AssetMetadata`缺少关键字段
|
||
|
||
**缺失字段**:
|
||
- 资产描述（description）
|
||
- 资产证明文档哈希（proof_hash）
|
||
- 合规状态（compliance_status）
|
||
- 估值报告（valuation_report）
|
||
- 资产位置（location）
|
||
- 资产状态（status: active/frozen/transferred）
|
||
|
||
**建议**:
|
||
```rust
|
||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||
pub struct AssetMetadata {
|
||
pub gnacs_code: String,
|
||
pub asset_name: String,
|
||
pub asset_type: String,
|
||
pub description: String, // 新增
|
||
pub owner: String,
|
||
pub value: u64,
|
||
pub proof_hash: String, // 新增：资产证明文档哈希
|
||
pub compliance_status: String, // 新增：合规状态
|
||
pub valuation_report_hash: String, // 新增：估值报告哈希
|
||
pub location: Option<String>, // 新增：资产位置
|
||
pub status: AssetStatus, // 新增：资产状态
|
||
pub created_at: u64,
|
||
pub updated_at: u64,
|
||
}
|
||
|
||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||
pub enum AssetStatus {
|
||
Active,
|
||
Frozen,
|
||
Transferred,
|
||
Retired,
|
||
}
|
||
```
|
||
|
||
**状态**: ❌ 待扩展
|
||
|
||
---
|
||
|
||
### 问题4: 缺少JSON序列化支持（RWA）
|
||
|
||
**严重程度**: ⚠️ 低
|
||
|
||
**描述**: `RwaAssetSerializer`只支持二进制序列化
|
||
|
||
**影响**: API无法返回JSON格式的资产元数据
|
||
|
||
**建议**:
|
||
```rust
|
||
impl RwaAssetSerializer {
|
||
pub fn serialize_json(metadata: &AssetMetadata) -> Result<String> {
|
||
serde_json::to_string(metadata)
|
||
.map_err(|e| SerdeError::SerializationError(e.to_string()))
|
||
}
|
||
|
||
pub fn deserialize_json(json: &str) -> Result<AssetMetadata> {
|
||
serde_json::from_str(json)
|
||
.map_err(|e| SerdeError::DecodingError(e.to_string()))
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态**: ❌ 待添加
|
||
|
||
---
|
||
|
||
### 问题5: 缺少版本兼容性处理
|
||
|
||
**严重程度**: ⚠️ 中等
|
||
|
||
**描述**: 没有处理不同版本数据的兼容性
|
||
|
||
**影响**: 升级后无法读取旧版本数据
|
||
|
||
**建议**:
|
||
```rust
|
||
impl ConstitutionalDeserializer {
|
||
pub fn deserialize_versioned(bytes: &[u8]) -> Result<ConstitutionalData> {
|
||
// 尝试反序列化
|
||
match bincode::deserialize::<ConstitutionalData>(bytes) {
|
||
Ok(data) => Ok(data),
|
||
Err(_) => {
|
||
// 尝试旧版本格式
|
||
Self::deserialize_v0(bytes)
|
||
}
|
||
}
|
||
}
|
||
|
||
fn deserialize_v0(bytes: &[u8]) -> Result<ConstitutionalData> {
|
||
// 旧版本反序列化逻辑
|
||
// ...
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态**: ❌ 待实现
|
||
|
||
---
|
||
|
||
### 问题6: 缺少性能基准测试
|
||
|
||
**严重程度**: ⚠️ 低
|
||
|
||
**描述**: 虽然添加了criterion依赖，但没有实际的基准测试
|
||
|
||
**影响**: 无法评估序列化性能
|
||
|
||
**建议**: 创建`benches/gnacs_bench.rs`
|
||
```rust
|
||
use criterion::{black_box, criterion_group, criterion_main, Criterion};
|
||
use nac_serde::*;
|
||
|
||
fn gnacs_encode_benchmark(c: &mut Criterion) {
|
||
c.bench_function("gnacs_encode", |b| {
|
||
b.iter(|| {
|
||
GnacsEncoder::encode(
|
||
black_box("Real Estate"),
|
||
black_box("Beijing"),
|
||
black_box("Residential")
|
||
)
|
||
});
|
||
});
|
||
}
|
||
|
||
fn constitutional_serialize_benchmark(c: &mut Criterion) {
|
||
let data = ConstitutionalData {
|
||
clause_id: "TEST".to_string(),
|
||
param_name: "test".to_string(),
|
||
param_value: serde_json::json!(42),
|
||
version: 1,
|
||
timestamp: 1000,
|
||
};
|
||
|
||
c.bench_function("constitutional_serialize", |b| {
|
||
b.iter(|| {
|
||
ConstitutionalSerializer::serialize(black_box(&data))
|
||
});
|
||
});
|
||
}
|
||
|
||
criterion_group!(benches, gnacs_encode_benchmark, constitutional_serialize_benchmark);
|
||
criterion_main!(benches);
|
||
```
|
||
|
||
**状态**: ❌ 待添加
|
||
|
||
---
|
||
|
||
## 📊 完成度评估
|
||
|
||
| 功能模块 | 代码行数 | 完成度 | 状态 |
|
||
|---------|---------|--------|------|
|
||
| 错误处理 | 34行 | 100% | ✅ 完成 |
|
||
| GNACS编码 | 61行 | 30% | ❌ 需重构 |
|
||
| 宪法序列化 | 41行 | 80% | ⚠️ 基本完成 |
|
||
| RWA序列化 | 28行 | 50% | ⚠️ 需扩展 |
|
||
| **总计** | **164行** | **40%** | **🚧 进行中** |
|
||
|
||
### 待完善功能
|
||
|
||
1. **高优先级**:
|
||
- ❌ 重构GNACS编码算法（符合白皮书规范）
|
||
- ❌ 添加完整的单元测试
|
||
- ❌ 扩展RWA资产元数据
|
||
|
||
2. **中优先级**:
|
||
- ❌ 添加版本兼容性处理
|
||
- ❌ 添加JSON序列化支持（RWA）
|
||
- ⏳ 添加性能基准测试
|
||
|
||
3. **低优先级**:
|
||
- ⏳ 优化序列化性能
|
||
- ⏳ 添加更多错误类型
|
||
- ⏳ 添加文档注释
|
||
|
||
---
|
||
|
||
## 🌟 设计亮点
|
||
|
||
1. **统一错误处理**
|
||
- `SerdeError`枚举
|
||
- 实现`Error` trait
|
||
- 提供`Result<T>`类型别名
|
||
|
||
2. **多格式支持**
|
||
- Binary (bincode) - 紧凑高效
|
||
- JSON - 可读可编辑
|
||
|
||
3. **48位GNACS编码**
|
||
- 紧凑存储（6字节）
|
||
- 支持480种资产场景
|
||
|
||
4. **零拷贝设计**
|
||
- 序列化方法接受引用
|
||
- 避免不必要的复制
|
||
|
||
---
|
||
|
||
## 🔗 模块依赖关系
|
||
|
||
```
|
||
nac-serde
|
||
├── 依赖
|
||
│ ├── serde (序列化框架)
|
||
│ ├── bincode (二进制序列化)
|
||
│ ├── serde_json (JSON序列化)
|
||
│ ├── hex (十六进制编码)
|
||
│ └── sha2 (哈希算法)
|
||
├── 被依赖
|
||
│ ├── nac-udm (使用GNACS编码)
|
||
│ ├── nac-cbpp-l0 (序列化共识参数)
|
||
│ ├── nac-cee (序列化宪法数据)
|
||
│ └── nac-api-server (JSON序列化)
|
||
└── 协作模块
|
||
└── nac-constitution-state (宪法状态存储)
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 开发建议
|
||
|
||
### 短期目标 (1周)
|
||
|
||
1. **添加单元测试** (优先级P1)
|
||
- GNACS编码测试
|
||
- 序列化往返测试
|
||
- 错误处理测试
|
||
|
||
2. **重构GNACS编码** (优先级P1)
|
||
- 实现结构化编码
|
||
- 实现解码功能
|
||
- 符合白皮书规范
|
||
|
||
### 中期目标 (2周)
|
||
|
||
3. **扩展RWA资产元数据** (优先级P2)
|
||
- 添加缺失字段
|
||
- 添加JSON序列化
|
||
- 添加验证逻辑
|
||
|
||
4. **添加版本兼容性** (优先级P2)
|
||
- 版本号检测
|
||
- 旧版本兼容
|
||
- 迁移工具
|
||
|
||
### 长期目标 (1个月)
|
||
|
||
5. **性能优化** (优先级P3)
|
||
- 添加基准测试
|
||
- 优化序列化性能
|
||
- 减少内存分配
|
||
|
||
6. **文档完善** (优先级P3)
|
||
- 添加文档注释
|
||
- 编写使用指南
|
||
- 添加示例代码
|
||
|
||
---
|
||
|
||
## 💡 使用示例
|
||
|
||
```rust
|
||
use nac_serde::*;
|
||
|
||
// 1. GNACS编码
|
||
let gnacs_code = GnacsEncoder::encode("Real Estate", "Beijing", "Residential")?;
|
||
println!("GNACS Code: {}", gnacs_code.to_hex());
|
||
|
||
// 2. 宪法数据序列化
|
||
let const_data = ConstitutionalData {
|
||
clause_id: "NET_CONN_MIN_CBP".to_string(),
|
||
param_name: "min_connections".to_string(),
|
||
param_value: serde_json::json!(12),
|
||
version: 1,
|
||
timestamp: 1708300800,
|
||
};
|
||
|
||
// 二进制序列化
|
||
let bytes = ConstitutionalSerializer::serialize(&const_data)?;
|
||
println!("Binary size: {} bytes", bytes.len());
|
||
|
||
// JSON序列化
|
||
let json = ConstitutionalSerializer::serialize_json(&const_data)?;
|
||
println!("JSON: {}", json);
|
||
|
||
// 反序列化
|
||
let decoded = ConstitutionalDeserializer::deserialize(&bytes)?;
|
||
assert_eq!(decoded.clause_id, "NET_CONN_MIN_CBP");
|
||
|
||
// 3. RWA资产序列化
|
||
let asset = AssetMetadata {
|
||
gnacs_code: gnacs_code.to_hex(),
|
||
asset_name: "北京朝阳区房产".to_string(),
|
||
asset_type: "Real Estate".to_string(),
|
||
owner: "0x1234567890abcdef".to_string(),
|
||
value: 5_000_000_000_000, // 5M XTZH
|
||
timestamp: 1708300800,
|
||
};
|
||
|
||
let asset_bytes = RwaAssetSerializer::serialize(&asset)?;
|
||
let decoded_asset = RwaAssetSerializer::deserialize(&asset_bytes)?;
|
||
println!("Asset: {}", decoded_asset.asset_name);
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 与NAC技术栈的集成
|
||
|
||
### 与nac-udm的集成
|
||
|
||
```rust
|
||
// nac-udm使用GNACS编码标识资产
|
||
use nac_udm::primitives::Asset;
|
||
use nac_serde::GnacsEncoder;
|
||
|
||
let gnacs_code = GnacsEncoder::encode("Real Estate", "Beijing", "Residential")?;
|
||
let asset = Asset::new(gnacs_code.to_hex(), owner, value);
|
||
```
|
||
|
||
### 与nac-cee的集成
|
||
|
||
```rust
|
||
// nac-cee使用宪法数据序列化存储参数
|
||
use nac_cee::ConstitutionEngine;
|
||
use nac_serde::{ConstitutionalData, ConstitutionalSerializer};
|
||
|
||
let param = ConstitutionalData {
|
||
clause_id: "GAS_LIMIT_MAX".to_string(),
|
||
param_name: "max_gas".to_string(),
|
||
param_value: serde_json::json!(100_000_000),
|
||
version: 1,
|
||
timestamp: now(),
|
||
};
|
||
|
||
let bytes = ConstitutionalSerializer::serialize(¶m)?;
|
||
cee.store_parameter(¶m.clause_id, &bytes)?;
|
||
```
|
||
|
||
### 与nac-api-server的集成
|
||
|
||
```rust
|
||
// nac-api-server使用JSON序列化返回API响应
|
||
use nac_api_server::handlers;
|
||
use nac_serde::{AssetMetadata, ConstitutionalSerializer};
|
||
|
||
async fn get_asset(id: String) -> Result<String, Error> {
|
||
let asset = db.get_asset(&id)?;
|
||
// 返回JSON
|
||
Ok(serde_json::to_string(&asset)?)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
**分析完成时间**: 2026-02-18
|
||
**下一步**: 重构GNACS编码算法并添加完整测试
|