# NAC SDK v2.0

**NAC (NewAssetChain) SDK** - Native Rust Implementation for RWA Blockchain

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Rust Version](https://img.shields.io/badge/rust-1.75%2B-blue.svg)](https://www.rust-lang.org)

NAC SDK是为RWA（真实世界资产）区块链设计的原生Rust SDK，提供完整的NAC公链功能访问接口。

---

## 核心特性

- ✅ **NAC原生设计** - 完全遵循NAC核心原则，不使用以太坊标准
- ✅ **六层架构** - 完整实现L0-L5所有层的适配器
- ✅ **统一接口** - 通过`NACAdapter`统一访问所有功能
- ✅ **高性能** - Rust实现，零成本抽象
- ✅ **类型安全** - 强类型系统，编译时错误检查
- ✅ **NAC Lens协议** - 支持NAC原生RPC协议
- ✅ **完整文档** - 每个API都有详细的文档和示例
- ✅ **测试覆盖** - 完整的单元测试和集成测试

---

## 快速开始

### 安装

在`Cargo.toml`中添加依赖：

```toml
[dependencies]
nac-sdk = { path = "../nac-sdk" }
tokio = { version = "1.35", features = ["full"] }
```

### 基本使用

```rust
use nac_sdk::adapters::{NACAdapter, config::NACConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. 创建配置
    let config = NACConfig::default();
    
    // 2. 创建适配器
    let adapter = NACAdapter::new(&config).await?;
    
    // 3. 使用L0原生层 - 生成密钥对
    let (private_key, public_key) = adapter.l0().generate_keypair();
    let address = adapter.l0().address_from_public_key(&public_key)?;
    println!("地址: {}", hex::encode(address));
    
    // 4. 使用L1协议层 - 查询ACC-20余额
    let balance = adapter.l1().acc20_balance(
        &token_address,
        &address
    ).await?;
    println!("余额: {}", balance);
    
    // 5. 使用L4 AI层 - 合规检查
    let compliance_result = adapter.l4().compliance_check(
        asset_data
    ).await?;
    println!("合规状态: {:?}", compliance_result);
    
    Ok(())
}
```

---

## 架构概览

NAC SDK采用六层架构设计：

```
┌─────────────────────────────────────────────────────────┐
│                    NACAdapter                           │
│                   (统一入口点)                           │
└─────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
┌───────▼───────┐  ┌───────▼───────┐  ┌───────▼───────┐
│  L0 原生层    │  │  L1 协议层    │  │  L2 宪政层    │
│  密钥/地址    │  │  NVM/CBPP    │  │  治理/网络    │
│  哈希/签名    │  │  GNACS/ACC   │  │  CSNP        │
└───────────────┘  └───────────────┘  └───────────────┘
        │                   │                   │
┌───────▼───────┐  ┌───────▼───────┐  ┌───────▼───────┐
│  L3 存储层    │  │  L4 AI层      │  │  L5 应用层    │
│  状态/区块    │  │  合规/估值    │  │  钱包/浏览器  │
│  IPFS/缓存    │  │  风险/XTZH   │  │  交易所       │
└───────────────┘  └───────────────┘  └───────────────┘
```

---

## 详细功能

### L0 原生层 (`adapter.l0()`)

提供NAC公链的基础密码学和编码功能。

**密钥对操作**：
```rust
// 生成密钥对
let (private_key, public_key) = adapter.l0().generate_keypair();

// 从私钥生成地址
let address = adapter.l0().address_from_private_key(&private_key)?;

// 验证地址
let is_valid = adapter.l0().validate_address(&address)?;
```

**哈希操作**：
```rust
// 计算SHA3-384哈希
let hash = adapter.l0().hash_sha3_384(data);

// 计算Merkle树根
let root = adapter.l0().merkle_root(&hashes)?;
```

**签名操作**：
```rust
// 签名数据
let signature = adapter.l0().sign(&private_key, data)?;

// 验证签名
let is_valid = adapter.l0().verify(&public_key, data, &signature)?;
```

### L1 协议层 (`adapter.l1()`)

提供NAC公链的核心协议功能。

**NVM虚拟机**：
```rust
// 部署合约
let contract_address = adapter.l1().deploy_contract(
    bytecode,
    constructor_args,
    gas_limit
).await?;

// 调用合约
let result = adapter.l1().call_contract(
    &contract_address,
    function_signature,
    args,
    gas_limit
).await?;

// 查询合约状态
let state = adapter.l1().query_contract_state(
    &contract_address,
    state_key
).await?;
```

**CBPP共识**：
```rust
// 提交交易
let tx_hash = adapter.l1().submit_transaction(
    &from,
    &to,
    amount,
    data
).await?;

// 查询交易状态
let status = adapter.l1().get_transaction_status(&tx_hash).await?;

// 获取区块信息
let block = adapter.l1().get_block(block_number).await?;
```

**GNACS资产分类**：
```rust
// 编码GNACS
let gnacs_code = adapter.l1().encode_gnacs(
    AssetCategory::RealEstate,
    Jurisdiction::US,
    ComplianceLevel::High
)?;

// 解码GNACS
let (category, jurisdiction, compliance) = adapter.l1().decode_gnacs(&gnacs_code)?;
```

**ACC协议**：
```rust
// ACC-20: 查询余额
let balance = adapter.l1().acc20_balance(&token, &address).await?;

// ACC-20: 转账
let tx_hash = adapter.l1().acc20_transfer(&token, &to, amount).await?;

// ACC-721: 查询NFT所有者
let owner = adapter.l1().acc721_owner_of(&nft, token_id).await?;

// ACC-721: 转移NFT
let tx_hash = adapter.l1().acc721_transfer_from(&nft, &from, &to, token_id).await?;
```

### L2 宪政/治理/网络层 (`adapter.l2()`)

提供NAC公链的宪政审查、链上治理和网络功能。

**宪法审查**：
```rust
// 提交宪法审查请求
let request_id = adapter.l2().submit_constitutional_review(
    transaction_data
).await?;

// 查询审查结果
let result = adapter.l2().get_constitutional_review_result(&request_id).await?;

// 验证交易是否符合宪法
let is_compliant = adapter.l2().verify_constitutional_compliance(
    transaction_data
).await?;
```

**链上治理**：
```rust
// 提交提案
let proposal_id = adapter.l2().submit_proposal(
    "提案标题",
    "提案描述",
    ProposalType::Constitutional
).await?;

// 投票
adapter.l2().vote(&proposal_id, VoteOption::Yes).await?;

// 查询提案状态
let status = adapter.l2().get_proposal_status(&proposal_id).await?;
```

**CSNP网络**：
```rust
// 连接CSNP网络
adapter.l2().connect_csnp_node(&node_url).await?;

// 广播消息
adapter.l2().broadcast_message(message_data).await?;

// 查询网络状态
let status = adapter.l2().get_network_status().await?;
```

### L3 存储层 (`adapter.l3()`)

提供NAC公链的数据存储功能。

**状态数据库**：
```rust
// 读取状态
let value = adapter.l3().read_state(key).await?;

// 写入状态
adapter.l3().write_state(key, value).await?;

// 批量操作
let values = adapter.l3().batch_read_state(&keys).await?;
adapter.l3().batch_write_state(&key_values).await?;
```

**区块数据存储**：
```rust
// 存储区块
adapter.l3().store_block(&block).await?;

// 读取区块
let block = adapter.l3().read_block(block_number).await?;

// 查询区块范围
let blocks = adapter.l3().query_block_range(start, end).await?;
```

**IPFS集成**：
```rust
// 存储到IPFS
let cid = adapter.l3().store_to_ipfs(data).await?;

// 从IPFS读取
let data = adapter.l3().read_from_ipfs(&cid).await?;

// 固定内容
adapter.l3().pin_ipfs(&cid).await?;
```

### L4 AI层 (`adapter.l4()`)

提供NAC公链的AI驱动功能。

**AI合规审批**：
```rust
// AI合规检查
let result = adapter.l4().compliance_check(asset_data).await?;

// 批量合规检查
let results = adapter.l4().batch_compliance_check(&assets).await?;

// 查询合规规则
let rules = adapter.l4().get_compliance_rules().await?;
```

**AI估值**：
```rust
// AI估值
let valuation = adapter.l4().ai_valuation(asset_data).await?;

// 批量估值
let valuations = adapter.l4().batch_ai_valuation(&assets).await?;

// 查询历史估值
let history = adapter.l4().get_valuation_history(&asset_id).await?;
```

**AI风险评估**：
```rust
// AI风险评估
let risk = adapter.l4().ai_risk_assessment(asset_data).await?;

// 批量风险评估
let risks = adapter.l4().batch_ai_risk_assessment(&assets).await?;
```

**XTZH AI引擎**：
```rust
// 查询XTZH价格
let price = adapter.l4().get_xtzh_price().await?;

// 查询储备金状态
let reserves = adapter.l4().get_xtzh_reserves().await?;

// 预测XTZH价格
let prediction = adapter.l4().predict_xtzh_price(days).await?;
```

### L5 应用层 (`adapter.l5()`)

提供NAC公链的应用级功能。

**钱包接口**：
```rust
// 查询钱包余额
let balance = adapter.l5().get_wallet_balance(&address).await?;

// 查询交易历史
let history = adapter.l5().get_transaction_history(&address, limit).await?;

// 创建钱包
let wallet = adapter.l5().create_wallet(password).await?;

// 导入钱包
let wallet = adapter.l5().import_wallet(&private_key, password).await?;
```

**浏览器接口**：
```rust
// 查询区块详情
let block = adapter.l5().get_block_details(block_number).await?;

// 查询交易详情
let tx = adapter.l5().get_transaction_details(&tx_hash).await?;

// 查询地址详情
let info = adapter.l5().get_address_details(&address).await?;

// 查询链统计信息
let stats = adapter.l5().get_chain_statistics().await?;
```

**交易所接口**：
```rust
// 查询交易对列表
let pairs = adapter.l5().get_trading_pairs().await?;

// 查询市场深度
let depth = adapter.l5().get_market_depth(&pair).await?;

// 下单
let order_id = adapter.l5().place_order(
    &pair,
    OrderType::Limit,
    OrderSide::Buy,
    price,
    amount
).await?;

// 取消订单
adapter.l5().cancel_order(&order_id).await?;

// 查询K线数据
let klines = adapter.l5().get_kline_data(&pair, interval, limit).await?;
```

---

## 配置

### 默认配置

```rust
let config = NACConfig::default();
```

### 自定义配置

```rust
use nac_sdk::adapters::config::*;

let config = NACConfig {
    l1: L1Config {
        nvm_url: "http://localhost:8545".to_string(),
        cbpp_url: "http://localhost:8546".to_string(),
        nrpc4_url: "http://localhost:8547".to_string(),
        gnacs_url: "http://localhost:8548".to_string(),
        acc_url: "http://localhost:8549".to_string(),
    },
    l2: L2Config {
        constitutional_url: "http://localhost:8550".to_string(),
        governance_url: "http://localhost:8551".to_string(),
        csnp_url: "http://localhost:8552".to_string(),
    },
    l3: L3Config {
        state_db_url: "http://localhost:8553".to_string(),
        block_storage_url: "http://localhost:8554".to_string(),
        ipfs_url: "http://localhost:5001".to_string(),
        cache_url: "redis://localhost:6379".to_string(),
    },
    l4: L4Config {
        compliance_url: "http://localhost:8555".to_string(),
        valuation_url: "http://localhost:8556".to_string(),
        risk_assessment_url: "http://localhost:8557".to_string(),
        xtzh_ai_url: "http://localhost:8558".to_string(),
    },
    l5: L5Config {
        wallet_url: "http://localhost:8559".to_string(),
        explorer_url: "http://localhost:8560".to_string(),
        exchange_url: "http://localhost:8561".to_string(),
    },
};

let adapter = NACAdapter::new(&config).await?;
```

---

## 完整示例

查看`examples/`目录获取完整的使用示例：

- `examples/basic_usage.rs` - 基本使用示例
- `examples/asset_onboarding.rs` - 资产上链完整流程
- `examples/trading.rs` - 交易所交易示例
- `examples/governance.rs` - 链上治理示例

运行示例：

```bash
cargo run --example basic_usage
cargo run --example asset_onboarding
```

---

## 测试

```bash
# 运行所有测试
cargo test

# 运行特定层的测试
cargo test l0_native
cargo test l1_protocol
cargo test l2_layer
cargo test l3_storage
cargo test l4_ai
cargo test l5_application

# 运行集成测试
cargo test --test integration
```

---

## 项目结构

```
nac-sdk/
├── Cargo.toml
├── README.md
├── examples/                    # 使用示例
│   ├── basic_usage.rs
│   ├── asset_onboarding.rs
│   ├── trading.rs
│   └── governance.rs
├── src/
│   ├── lib.rs                  # 库入口
│   ├── adapters/               # 适配器模块
│   │   ├── mod.rs             # 统一适配器入口
│   │   ├── config.rs          # 配置模块
│   │   ├── l0_native.rs       # L0原生层适配器
│   │   ├── l1_protocol.rs     # L1协议层适配器
│   │   ├── l2_layer.rs        # L2宪政/治理/网络层适配器
│   │   ├── l3_storage.rs      # L3存储层适配器
│   │   ├── l4_ai.rs           # L4 AI层适配器
│   │   └── l5_application.rs  # L5应用层适配器
│   ├── client/                 # RPC客户端
│   ├── crypto/                 # 密码学工具
│   ├── protocols/              # 协议实现
│   ├── types/                  # 类型定义
│   ├── utils/                  # 工具函数
│   └── error/                  # 错误处理
└── tests/                      # 集成测试
    └── integration.rs
```

---

## 依赖

### 核心依赖
- `nac-udm` - NAC统一数据模型
- `nac-nvm` - NAC虚拟机
- `nac-cbpp` - CBPP共识协议
- `nac-lens` - NAC Lens协议

### 第三方依赖
- `tokio` - 异步运行时
- `serde` - 序列化/反序列化
- `reqwest` - HTTP客户端
- `ed25519-dalek` - Ed25519签名
- `sha3` - SHA3哈希

---

## 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启Pull Request

---

## 许可证

本项目采用MIT许可证 - 详见[LICENSE](LICENSE)文件

---

## 联系方式

- **项目主页**: https://git.newassetchain.io/nacadmin/NAC_Blockchain
- **问题反馈**: https://git.newassetchain.io/nacadmin/NAC_Blockchain/issues
- **邮箱**: dev@newassetchain.io

---

## 更新日志

### v2.0.0 (2026-02-19)

- ✅ 完成所有层（L0-L5）适配器的100%实现
- ✅ 实现统一的`NACAdapter`接口
- ✅ 添加完整的文档和示例
- ✅ 添加完整的测试覆盖

### v1.0.0 (2026-02-18)

- ✅ 初始版本发布
- ✅ 实现基础RPC客户端
- ✅ 实现密码学工具
- ✅ 实现ACC协议

---

**维护**: NAC开发团队  
**创建日期**: 2026-02-18  
**最后更新**: 2026-02-19