594 lines
15 KiB
Markdown
594 lines
15 KiB
Markdown
# NAC SDK v2.0
|
||
|
||
**NAC (NewAssetChain) SDK** - Native Rust Implementation for RWA Blockchain
|
||
|
||
[](https://opensource.org/licenses/MIT)
|
||
[](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
|