NAC_Blockchain/sdk/nac-sdk

NAC SDK v2.0

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

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

---

核心特性

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

---

快速开始

安装

在Cargo.toml中添加依赖：

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

基本使用

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公链的基础密码学和编码功能。

密钥对操作：

// 生成密钥对
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)?;

哈希操作：

// 计算SHA3-384哈希
let hash = adapter.l0().hash_sha3_384(data);

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

签名操作：

// 签名数据
let signature = adapter.l0().sign(&private_key, data)?;

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

L1 协议层 (adapter.l1())

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

NVM虚拟机：

// 部署合约
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共识：

// 提交交易
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资产分类：

// 编码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协议：

// 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公链的宪政审查、链上治理和网络功能。

宪法审查：

// 提交宪法审查请求
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?;

链上治理：

// 提交提案
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网络：

// 连接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公链的数据存储功能。

状态数据库：

// 读取状态
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?;

区块数据存储：

// 存储区块
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集成：

// 存储到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合规审批：

// 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估值：

// 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风险评估：

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

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

XTZH AI引擎：

// 查询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公链的应用级功能。

钱包接口：

// 查询钱包余额
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?;

浏览器接口：

// 查询区块详情
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?;

交易所接口：

// 查询交易对列表
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?;

---

配置

默认配置

let config = NACConfig::default();

自定义配置

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 - 链上治理示例

运行示例：

cargo run --example basic_usage
cargo run --example asset_onboarding

---

测试

# 运行所有测试
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文件

---

联系方式

• 项目主页: 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