37 KiB

Raw Blame History

NAC UDM API规范文档

版本: 1.0.0
作者: NAC公链开发小组
日期: 2025-02-07
状态: 正式发布

📋 目录

概述
架构设计
核心注册表系统API
基础原语类型API
L2宪法治理层API
L1多链协议层API
L0 CSNP网络层API
多语言绑定
错误处理
版本管理

概述

NAC统一定义模块（UDM）是NewAssetChain区块链生态系统的单一真理来源（Single Source of Truth），统一管理所有类型定义、函数签名、常量、版本信息和协议规范。

核心特性

❌ 不使用任何ERC标准（ERC-20、ERC-721、ERC-1155等）
❌ 不继承以太坊或其他链的实现
❌ 不是P2P网络 - 使用CSNP宪政结构化网络协议
✅ 100% NAC原生设计
✅ 专注于RWA（真实世界资产）应用场景
✅ 基于CBPP宪政共识，不需要投票治理
✅ 支持Rust/Go/Charter多语言绑定

设计哲学

"宪法治下，节点产生区块，参与即是共识，交易扩张区块的大小和高度。"

架构设计

NAC采用3层架构体系：

L2: 宪法治理层 (Constitutional Governance Layer)

最高层级，定义整个系统的治理规则（不是投票治理，而是规则定义层）：

网络规则定义: 连接规则、传播规则、惩罚条款（跨链适用）
跨链中继授权: 授权跨链中继节点（CCRN）列表
宪法条款库: 宪法收据（CR）验证规则
宪法执行引擎: CEE管理与签发机制

L1: 多链协议层 (Multi-Chain Protocol Layer)

核心协议层，实现"宪法即共识"：

CBPP核心: 宪法区块生产协议（宪法收据CR、OPN、FBM、RVGP）
ACC协议族: 13个原生资产协议（ACC-20, ACC-721, ACC-1155, ACC-RWA等）
NVM 2.0: 虚拟机层（225个基础操作码 + 125个RWA专属指令）
GNACS: 全球资产分类系统（48位编码）

L0: CSNP结构化网络层 (CSNP Structured Network Layer)

宪政结构化网络层，提供5大核心组件（不是P2P网络）：

GIDS: 全域身份目录服务 - 多链DID解析与信誉聚合
MA-RCM: 多链自适应连接管理器 - 跨链优化连接拓扑
AA-PE: 资产感知传播引擎 - 基于GNACS的智能路由
FTAN: 碎片化交易聚合网络 - 批量签名与传播
UCA: 统一跨链审计器 - 跨链行为追踪与惩罚

核心注册表系统API

UID (Unified Identifier)

统一标识符，用于唯一标识每个定义。

数据结构

pub struct UID {
    namespace: String,  // 命名空间 (e.g., "nac.l1.cbpp.receipt")
}

构造方法

// 创建新的UID
pub fn new(namespace: impl Into<String>) -> Self

// 从字符串解析UID
pub fn from_str(s: &str) -> Result<Self, String>

查询方法

// 获取完整命名空间
pub fn namespace(&self) -> &str

// 获取层级（l0, l1, l2）
pub fn layer(&self) -> Option<&str>

// 获取模块名称
pub fn module(&self) -> Option<&str>

// 获取定义名称
pub fn definition(&self) -> Option<&str>

// 获取父UID
pub fn parent(&self) -> Option<UID>

// 获取子UID
pub fn child(&self, name: &str) -> UID

// 是否是另一个UID的祖先
pub fn is_ancestor_of(&self, other: &UID) -> bool

示例

use nac_udm::registry::UID;

// 创建UID
let uid = UID::new("nac.l1.cbpp.receipt");

// 查询层级
assert_eq!(uid.layer(), Some("l1"));
assert_eq!(uid.module(), Some("cbpp"));
assert_eq!(uid.definition(), Some("receipt"));

// 父子关系
let parent = uid.parent().unwrap();
assert_eq!(parent.namespace(), "nac.l1.cbpp");

let child = uid.child("field1");
assert_eq!(child.namespace(), "nac.l1.cbpp.receipt.field1");

Version (版本管理)

语义化版本管理，遵循SemVer 2.0.0规范。

数据结构

pub struct Version {
    major: u32,
    minor: u32,
    patch: u32,
    pre_release: Option<String>,
    build_metadata: Option<String>,
}

构造方法

// 创建新版本
pub fn new(major: u32, minor: u32, patch: u32) -> Self

// 从字符串解析版本
pub fn from_str(s: &str) -> Result<Self, String>

版本操作

// 递增主版本号
pub fn bump_major(&mut self)

// 递增次版本号
pub fn bump_minor(&mut self)

// 递增补丁版本号
pub fn bump_patch(&mut self)

// 设置预发布标签
pub fn set_pre_release(&mut self, pre_release: impl Into<String>)

// 设置构建元数据
pub fn set_build_metadata(&mut self, metadata: impl Into<String>)

版本比较

// 是否兼容（主版本号相同）
pub fn is_compatible_with(&self, other: &Version) -> bool

// 是否向后兼容（主版本号相同，次版本号>=）
pub fn is_backward_compatible_with(&self, other: &Version) -> bool

示例

use nac_udm::registry::Version;

// 创建版本
let mut v = Version::new(1, 2, 3);
assert_eq!(v.to_string(), "1.2.3");

// 递增版本
v.bump_minor();
assert_eq!(v.to_string(), "1.3.0");

// 版本比较
let v1 = Version::from_str("1.2.3").unwrap();
let v2 = Version::from_str("1.3.0").unwrap();
assert!(v1.is_compatible_with(&v2));

Definition (定义抽象)

元定义系统，定义"什么是定义"。

数据结构

pub struct Definition {
    uid: UID,
    version: Version,
    name: String,
    description: String,
    definition_type: DefinitionType,
    tags: Vec<String>,
    dependencies: Vec<UID>,
    deprecated: bool,
    language_bindings: HashMap<Language, LanguageBinding>,
}

定义类型

pub enum DefinitionType {
    Type,           // 类型定义
    Function,       // 函数定义
    Constant,       // 常量定义
    Protocol,       // 协议定义
    Module,         // 模块定义
    Interface,      // 接口定义
}

构造方法

// 使用构建器模式创建定义
pub fn builder() -> DefinitionBuilder

// 构建器方法
impl DefinitionBuilder {
    pub fn uid(mut self, uid: UID) -> Self
    pub fn version(mut self, version: Version) -> Self
    pub fn name(mut self, name: impl Into<String>) -> Self
    pub fn description(mut self, description: impl Into<String>) -> Self
    pub fn definition_type(mut self, dt: DefinitionType) -> Self
    pub fn add_tag(mut self, tag: impl Into<String>) -> Self
    pub fn add_dependency(mut self, dep: UID) -> Self
    pub fn deprecated(mut self, deprecated: bool) -> Self
    pub fn add_language_binding(mut self, lang: Language, binding: LanguageBinding) -> Self
    pub fn build(self) -> Definition
}

查询方法

// 获取UID
pub fn uid(&self) -> &UID

// 获取版本
pub fn version(&self) -> &Version

// 获取名称
pub fn name(&self) -> &str

// 获取描述
pub fn description(&self) -> &str

// 获取定义类型
pub fn definition_type(&self) -> &DefinitionType

// 获取标签
pub fn tags(&self) -> &[String]

// 获取依赖
pub fn dependencies(&self) -> &[UID]

// 是否已弃用
pub fn is_deprecated(&self) -> bool

// 获取语言绑定
pub fn language_binding(&self, lang: Language) -> Option<&LanguageBinding>

示例

use nac_udm::registry::{Definition, DefinitionType, UID, Version, Language, LanguageBinding};

// 创建定义
let def = Definition::builder()
    .uid(UID::new("nac.l1.cbpp.receipt"))
    .version(Version::new(1, 0, 0))
    .name("ConstitutionalReceipt")
    .description("宪法收据，交易进入区块链的唯一门票")
    .definition_type(DefinitionType::Type)
    .add_tag("cbpp")
    .add_tag("core")
    .add_language_binding(
        Language::Rust,
        LanguageBinding::new("pub struct ConstitutionalReceipt { ... }")
    )
    .build();

// 查询定义
assert_eq!(def.name(), "ConstitutionalReceipt");
assert_eq!(def.version().to_string(), "1.0.0");
assert!(def.tags().contains(&"cbpp".to_string()));

DefinitionRegistry (定义注册表)

线程安全的定义管理系统。

数据结构

pub struct DefinitionRegistry {
    // 内部使用Arc<RwLock<...>>实现线程安全
}

注册方法

// 注册新定义
pub fn register(&self, definition: Definition) -> Result<(), String>

// 批量注册定义
pub fn register_batch(&self, definitions: Vec<Definition>) -> Result<(), String>

查询方法

// 通过UID查询定义
pub fn get(&self, uid: &UID) -> Option<Definition>

// 通过UID和版本查询定义
pub fn get_version(&self, uid: &UID, version: &Version) -> Option<Definition>

// 获取最新版本
pub fn get_latest(&self, uid: &UID) -> Option<Definition>

// 获取所有版本
pub fn get_all_versions(&self, uid: &UID) -> Vec<Definition>

// 通过标签查询定义
pub fn find_by_tag(&self, tag: &str) -> Vec<Definition>

// 通过类型查询定义
pub fn find_by_type(&self, dt: &DefinitionType) -> Vec<Definition>

// 获取依赖关系
pub fn get_dependencies(&self, uid: &UID) -> Vec<UID>

// 获取反向依赖
pub fn get_dependents(&self, uid: &UID) -> Vec<UID>

统计方法

// 获取定义总数
pub fn count(&self) -> usize

// 获取版本总数
pub fn version_count(&self) -> usize

// 按类型统计
pub fn count_by_type(&self, dt: &DefinitionType) -> usize

示例

use nac_udm::registry::{DefinitionRegistry, Definition, UID};

// 创建注册表
let registry = DefinitionRegistry::new();

// 注册定义
registry.register(definition).unwrap();

// 查询定义
let uid = UID::new("nac.l1.cbpp.receipt");
let def = registry.get(&uid).unwrap();
println!("Found: {}", def.name());

// 按标签查询
let cbpp_defs = registry.find_by_tag("cbpp");
println!("Found {} CBPP definitions", cbpp_defs.len());

基础原语类型API

Address (地址类型)

20字节地址类型，用于标识账户、合约等实体。

数据结构

pub struct Address([u8; 20]);

构造方法

// 创建新地址
pub fn new(bytes: [u8; 20]) -> Self

// 从切片创建
pub fn from_slice(slice: &[u8]) -> Result<Self, String>

// 从十六进制字符串创建
pub fn from_hex(hex: &str) -> Result<Self, String>

// 零地址
pub fn zero() -> Self

查询方法

// 获取字节数组
pub fn as_bytes(&self) -> &[u8; 20]

// 转换为十六进制字符串
pub fn to_hex(&self) -> String

// 是否为零地址
pub fn is_zero(&self) -> bool

示例

use nac_udm::primitives::Address;

// 创建地址
let addr = Address::from_hex("0x1234567890123456789012345678901234567890").unwrap();

// 查询
assert!(!addr.is_zero());
assert_eq!(addr.to_hex(), "0x1234567890123456789012345678901234567890");

Hash (哈希类型)

32字节哈希类型（SHA256），用于标识交易、区块等。

数据结构

pub struct Hash([u8; 32]);

构造方法

// 创建新哈希
pub fn new(bytes: [u8; 32]) -> Self

// 从切片创建
pub fn from_slice(slice: &[u8]) -> Result<Self, String>

// 从十六进制字符串创建
pub fn from_hex(hex: &str) -> Result<Self, String>

// 计算SHA256哈希
pub fn sha256(data: &[u8]) -> Self

// 零哈希
pub fn zero() -> Self

查询方法

// 获取字节数组
pub fn as_bytes(&self) -> &[u8; 32]

// 转换为十六进制字符串
pub fn to_hex(&self) -> String

// 是否为零哈希
pub fn is_zero(&self) -> bool

示例

use nac_udm::primitives::Hash;

// 计算哈希
let data = b"Hello, NAC!";
let hash = Hash::sha256(data);

// 查询
assert!(!hash.is_zero());
println!("Hash: {}", hash.to_hex());

Timestamp (时间戳类型)

Unix时间戳类型（u64秒级精度）。

数据结构

pub struct Timestamp(u64);

构造方法

// 当前时间
pub fn now() -> Self

// 从秒数创建
pub fn from_secs(secs: u64) -> Self

查询方法

// 获取秒数
pub fn as_secs(&self) -> u64

// 是否过期
pub fn is_expired(&self, current: u64) -> bool

时间操作

// 增加秒数
pub fn add_secs(&self, secs: u64) -> Self

// 减少秒数
pub fn sub_secs(&self, secs: u64) -> Self

示例

use nac_udm::primitives::Timestamp;

// 当前时间
let now = Timestamp::now();

// 时间操作
let future = now.add_secs(3600); // 1小时后
let past = now.sub_secs(3600);   // 1小时前

// 过期检查
assert!(!future.is_expired(now.as_secs()));
assert!(past.is_expired(now.as_secs()));

Signature (签名类型)

数字签名类型（可变长度）。

数据结构

pub struct Signature(Vec<u8>);

构造方法

// 创建新签名
pub fn new(bytes: Vec<u8>) -> Self

// 从切片创建
pub fn from_slice(slice: &[u8]) -> Self

// 从十六进制字符串创建
pub fn from_hex(hex: &str) -> Result<Self, String>

// 空签名
pub fn empty() -> Self

查询方法

// 获取字节数组
pub fn as_bytes(&self) -> &[u8]

// 转换为十六进制字符串
pub fn to_hex(&self) -> String

// 是否为空
pub fn is_empty(&self) -> bool

// 获取长度
pub fn len(&self) -> usize

示例

use nac_udm::primitives::Signature;

// 创建签名
let sig = Signature::from_hex("0x1234...").unwrap();

// 查询
assert!(!sig.is_empty());
println!("Signature length: {}", sig.len());

L2宪法治理层API

ConstitutionalClause (宪法条款)

宪法条款定义。

数据结构

pub struct ConstitutionalClause {
    pub clause_id: u32,
    pub title: String,
    pub content: String,
    pub version: String,
    pub active: bool,
}

NetworkRule (网络规则)

网络规则定义。

数据结构

pub struct NetworkRule {
    pub rule_id: u32,
    pub rule_type: RuleType,
    pub description: String,
    pub parameters: Vec<(String, String)>,
}

pub enum RuleType {
    Connection,    // 连接规则
    Propagation,   // 传播规则
    Validation,    // 验证规则
    Penalty,       // 惩罚规则
}

CrossChainRelayNode (跨链中继节点)

跨链中继节点授权。

数据结构

pub struct CrossChainRelayNode {
    pub node_address: Address,
    pub authorized_chains: Vec<String>,
    pub stake_amount: u128,
    pub reputation_score: u8,
}

PenaltyRecord (惩罚记录)

惩罚条款记录。

数据结构

pub struct PenaltyRecord {
    pub violator: Address,
    pub violation_type: ViolationType,
    pub penalty_amount: u128,
    pub timestamp: u64,
}

pub enum ViolationType {
    InvalidBlock,      // 无效区块
    DoubleSpend,       // 双花攻击
    MaliciousRelay,    // 恶意中继
    RuleViolation,     // 规则违反
}

L1多链协议层API

CBPP模块

ConstitutionalReceipt (宪法收据)

宪法收据，交易进入区块链的唯一门票。

数据结构:

pub struct ConstitutionalReceipt {
    pub receipt_id: Hash,
    pub transaction_hash: Hash,
    pub constitutional_hash: Hash,
    pub clause_index: u32,
    pub execution_result_hash: Hash,
    pub timestamp: Timestamp,
    pub validity_window: u64,
    pub validator_signature: Signature,
    pub validation_types: Vec<ValidationType>,
    pub validation_results: Vec<ValidationResult>,
}

pub enum ValidationType {
    KYC,                  // 身份验证
    AML,                  // 反洗钱
    AssetValuation,       // 资产估值
    Compliance,           // 合规性
    Custody,              // 托管验证
    Collateral,           // 抵押验证
    Insurance,            // 保险验证
    Governance,           // 治理验证
}

pub struct ValidationResult {
    pub validation_type: ValidationType,
    pub passed: bool,
    pub score: u8,
    pub validator: Address,
    pub timestamp: Timestamp,
}

构造方法:

pub fn new(
    transaction_hash: Hash,
    constitutional_hash: Hash,
    clause_index: u32,
    execution_result_hash: Hash,
    timestamp: Timestamp,
    validity_window: u64,
    validator_signature: Signature,
) -> Self

验证方法:

// 验证收据是否有效
pub fn is_valid(&self, current_timestamp: u64) -> bool

// 验证收据是否过期
pub fn is_expired(&self, current_timestamp: u64) -> bool

// 计算收据ID
pub fn calculate_receipt_id(&self) -> Hash

// 添加验证结果
pub fn add_validation_result(&mut self, result: ValidationResult)

// 获取验证通过率
pub fn validation_pass_rate(&self) -> f64

// 计算收据权重
pub fn calculate_weight(&self) -> u64

示例:

use nac_udm::l1_protocol::cbpp::*;
use nac_udm::primitives::*;

// 创建宪法收据
let receipt = ConstitutionalReceipt::new(
    tx_hash,
    const_hash,
    1,
    result_hash,
    Timestamp::now(),
    3600,
    signature,
);

// 添加验证结果
receipt.add_validation_result(ValidationResult {
    validation_type: ValidationType::KYC,
    passed: true,
    score: 95,
    validator: validator_addr,
    timestamp: Timestamp::now(),
});

// 验证收据
if receipt.is_valid(Timestamp::now().as_secs()) {
    println!("Receipt is valid!");
    println!("Pass rate: {:.2}%", receipt.validation_pass_rate() * 100.0);
}

FluidBlock (流体区块)

流体区块，支持DAG结构的三维坐标系统。

数据结构:

pub struct FluidBlock {
    pub coordinates: BlockCoordinates,
    pub parent_hashes: Vec<Hash>,
    pub transactions: Vec<TransactionWithReceipt>,
    pub timestamp: Timestamp,
    pub producer: Address,
    pub signature: Signature,
    pub capacity: u64,
    pub used_capacity: u64,
}

pub struct BlockCoordinates {
    pub epoch: u64,
    pub round: u64,
    pub branch: u64,
}

pub struct TransactionWithReceipt {
    pub transaction: Transaction,
    pub receipt: ConstitutionalReceipt,
}

构造方法:

pub fn new(
    coordinates: BlockCoordinates,
    parent_hashes: Vec<Hash>,
    producer: Address,
) -> Self

区块操作:

// 添加交易
pub fn add_transaction(&mut self, tx: TransactionWithReceipt) -> Result<(), String>

// 计算区块哈希
pub fn calculate_hash(&self) -> Hash

// 验证区块
pub fn validate(&self) -> Result<(), String>

// 是否已满
pub fn is_full(&self) -> bool

// 获取容量使用率
pub fn capacity_usage(&self) -> f64

OpenProductionNetwork (开放生产网络)

开放生产网络，管理区块生产者。

数据结构:

pub struct OpenProductionNetwork {
    pub producers: Vec<BlockProducer>,
    pub min_stake: u128,
    pub reputation_threshold: u8,
}

pub struct BlockProducer {
    pub address: Address,
    pub stake: u128,
    pub reputation: u8,
    pub blocks_produced: u64,
    pub last_active: Timestamp,
}

生产者管理:

// 添加生产者
pub fn add_producer(&mut self, producer: BlockProducer) -> Result<(), String>

// 移除生产者
pub fn remove_producer(&mut self, address: &Address) -> Result<(), String>

// 获取活跃生产者
pub fn get_active_producers(&self) -> Vec<&BlockProducer>

// 选择生产者
pub fn select_producer(&self, seed: u64) -> Option<&BlockProducer>

GossipProtocol (Gossip协议)

Gossip协议，用于消息传播。

数据结构:

pub struct GossipProtocol {
    pub peers: Vec<Address>,
    pub message_cache: Vec<Hash>,
    pub max_cache_size: usize,
}

pub struct GossipMessage {
    pub message_id: Hash,
    pub content: Vec<u8>,
    pub timestamp: Timestamp,
    pub sender: Address,
}

消息传播:

// 广播消息
pub fn broadcast(&self, message: &GossipMessage) -> Vec<Vec<u8>>

// 接收消息
pub fn receive(&mut self, message: GossipMessage) -> bool

// 是否已见过消息
pub fn has_seen(&self, message_id: &Hash) -> bool

GNACS模块

GNACSCode (GNACS编码)

48位资产分类编码。

数据结构:

pub struct GNACSCode([u8; 6]);

构造方法:

// 创建新编码
pub fn new(bytes: [u8; 6]) -> Self

// 从十六进制创建
pub fn from_hex(hex: &str) -> Result<Self, String>

// 从组件创建
pub fn from_components(
    jurisdiction: Jurisdiction,
    asset_category: AssetCategory,
    compliance_level: ComplianceLevel,
    risk_level: RiskLevel,
) -> Self

解析方法:

// 获取司法辖区
pub fn jurisdiction(&self) -> Jurisdiction

// 获取资产类别
pub fn asset_category(&self) -> AssetCategory

// 获取合规级别
pub fn compliance_level(&self) -> ComplianceLevel

// 获取风险级别
pub fn risk_level(&self) -> RiskLevel

// 验证编码
pub fn validate(&self) -> bool

// 计算校验和
pub fn checksum(&self) -> u8

格式转换:

// 转换为十六进制
pub fn to_hex(&self) -> String

// 转换为人类可读格式
pub fn to_human_readable(&self) -> String

示例:

use nac_udm::l1_protocol::gnacs::*;

// 创建GNACS编码
let gnacs = GNACSCode::from_components(
    Jurisdiction::US,
    AssetCategory::RealEstate,
    ComplianceLevel::High,
    RiskLevel::Low,
);

// 解析编码
println!("Jurisdiction: {:?}", gnacs.jurisdiction());
println!("Category: {:?}", gnacs.asset_category());
println!("Compliance: {:?}", gnacs.compliance_level());
println!("Risk: {:?}", gnacs.risk_level());

// 验证
assert!(gnacs.validate());

AssetCategory (资产分类)

11种资产大类。

pub enum AssetCategory {
    RealEstate,        // 房地产
    Equity,            // 股权
    Debt,              // 债权
    Commodity,         // 商品
    IntellectualProperty, // 知识产权
    ArtCollectible,    // 艺术收藏品
    Vehicle,           // 车辆
    Machinery,         // 机械设备
    Inventory,         // 存货
    FinancialInstrument, // 金融工具
    Other,             // 其他
}

Jurisdiction (司法辖区)

17个司法辖区。

pub enum Jurisdiction {
    US,    // 美国
    EU,    // 欧盟
    UK,    // 英国
    CN,    // 中国
    JP,    // 日本
    SG,    // 新加坡
    HK,    // 香港
    CH,    // 瑞士
    AE,    // 阿联酋
    AU,    // 澳大利亚
    CA,    // 加拿大
    KR,    // 韩国
    IN,    // 印度
    BR,    // 巴西
    ZA,    // 南非
    MX,    // 墨西哥
    Unknown, // 未知
}

ComplianceLevel (合规级别)

6个合规等级。

pub enum ComplianceLevel {
    VeryHigh,  // 极高 (100分)
    High,      // 高 (80分)
    Medium,    // 中 (60分)
    Low,       // 低 (40分)
    VeryLow,   // 极低 (20分)
    Unknown,   // 未知 (0分)
}

RiskLevel (风险等级)

6个风险等级。

pub enum RiskLevel {
    VeryLow,   // 极低 (20分)
    Low,       // 低 (40分)
    Medium,    // 中 (60分)
    High,      // 高 (80分)
    VeryHigh,  // 极高 (100分)
    Unknown,   // 未知 (0分)
}

ACC协议族

ACC-20 (可替代代币)

数据结构:

pub struct ACC20Token {
    pub name: String,
    pub symbol: String,
    pub decimals: u8,
    pub total_supply: u128,
    pub balances: HashMap<Address, u128>,
    pub allowances: HashMap<Address, HashMap<Address, u128>>,
}

核心方法:

// 转账
pub fn transfer(&mut self, from: Address, to: Address, amount: u128) -> Result<(), String>

// 授权
pub fn approve(&mut self, owner: Address, spender: Address, amount: u128) -> Result<(), String>

// 授权转账
pub fn transfer_from(&mut self, spender: Address, from: Address, to: Address, amount: u128) -> Result<(), String>

// 铸造
pub fn mint(&mut self, to: Address, amount: u128) -> Result<(), String>

// 销毁
pub fn burn(&mut self, from: Address, amount: u128) -> Result<(), String>

// 查询余额
pub fn balance_of(&self, account: &Address) -> u128

// 查询授权额度
pub fn allowance(&self, owner: &Address, spender: &Address) -> u128

ACC-721 (不可替代代币)

数据结构:

pub struct ACC721Token {
    pub name: String,
    pub symbol: String,
    pub owners: HashMap<u128, Address>,
    pub balances: HashMap<Address, u128>,
    pub token_approvals: HashMap<u128, Address>,
    pub operator_approvals: HashMap<Address, HashMap<Address, bool>>,
}

核心方法:

// 铸造NFT
pub fn mint(&mut self, to: Address, token_id: u128) -> Result<(), String>

// 转移NFT
pub fn transfer(&mut self, from: Address, to: Address, token_id: u128) -> Result<(), String>

// 授权NFT
pub fn approve(&mut self, owner: Address, to: Address, token_id: u128) -> Result<(), String>

// 设置操作员
pub fn set_approval_for_all(&mut self, owner: Address, operator: Address, approved: bool)

// 查询所有者
pub fn owner_of(&self, token_id: u128) -> Option<Address>

// 查询余额
pub fn balance_of(&self, owner: &Address) -> u128

// 销毁NFT
pub fn burn(&mut self, token_id: u128) -> Result<(), String>

ACC-1155 (多代币标准)

数据结构:

pub struct ACC1155Token {
    pub balances: HashMap<Address, HashMap<u128, u128>>,
    pub operator_approvals: HashMap<Address, HashMap<Address, bool>>,
}

核心方法:

// 单个转账
pub fn safe_transfer_from(&mut self, from: Address, to: Address, id: u128, amount: u128) -> Result<(), String>

// 批量转账
pub fn safe_batch_transfer_from(&mut self, from: Address, to: Address, ids: Vec<u128>, amounts: Vec<u128>) -> Result<(), String>

// 查询余额
pub fn balance_of(&self, account: &Address, id: u128) -> u128

// 批量查询余额
pub fn balance_of_batch(&self, accounts: Vec<Address>, ids: Vec<u128>) -> Vec<u128>

// 设置操作员
pub fn set_approval_for_all(&mut self, owner: Address, operator: Address, approved: bool)

// 查询操作员
pub fn is_approved_for_all(&self, owner: &Address, operator: &Address) -> bool

ACC-RWA (RWA资产标准)

数据结构:

pub struct RWAAsset {
    pub asset_id: Hash,
    pub gnacs_code: GNACSCode,
    pub owner: Address,
    pub custodian: Address,
    pub valuation: u128,
    pub metadata_uri: String,
    pub constitutional_receipt: Hash,
}

核心方法:

// 创建RWA资产
pub fn create(gnacs_code: GNACSCode, owner: Address, custodian: Address) -> Self

// 转移所有权
pub fn transfer_ownership(&mut self, new_owner: Address, receipt: Hash) -> Result<(), String>

// 更新估值
pub fn update_valuation(&mut self, new_valuation: u128, appraiser: Address) -> Result<(), String>

// 验证合规性
pub fn verify_compliance(&self) -> bool

ACC-Compliance (合规协议)

数据结构:

pub struct ComplianceRecord {
    pub entity: Address,
    pub jurisdiction: Jurisdiction,
    pub compliance_level: ComplianceLevel,
    pub kyc_verified: bool,
    pub aml_verified: bool,
    pub accreditation_verified: bool,
    pub verification_date: Timestamp,
    pub expiry_date: Timestamp,
    pub verifier: Address,
    pub document_hash: Hash,
}

ACC-Valuation (估值协议)

数据结构:

pub struct ValuationReport {
    pub asset_id: Hash,
    pub valuation_amount: u128,
    pub currency: String,
    pub valuation_method: String,
    pub appraiser: Address,
    pub report_date: Timestamp,
    pub validity_period: u64,
    pub confidence_score: u8,
    pub report_hash: Hash,
}

ACC-Custody (托管协议)

数据结构:

pub struct CustodyRecord {
    pub asset_id: Hash,
    pub custodian: Address,
    pub owner: Address,
    pub custody_type: CustodyType,
    pub start_date: Timestamp,
    pub end_date: Option<Timestamp>,
    pub terms_hash: Hash,
}

pub enum CustodyType {
    Physical,      // 实物托管
    Digital,       // 数字托管
    Legal,         // 法律托管
    Escrow,        // 第三方托管
}

ACC-Collateral (抵押协议)

数据结构:

pub struct CollateralRecord {
    pub collateral_id: Hash,
    pub asset_id: Hash,
    pub borrower: Address,
    pub lender: Address,
    pub collateral_value: u128,
    pub loan_amount: u128,
    pub ltv_ratio: u8,
    pub start_date: Timestamp,
    pub maturity_date: Timestamp,
}

ACC-Redemption (赎回协议)

数据结构:

pub struct RedemptionRequest {
    pub request_id: Hash,
    pub asset_id: Hash,
    pub requester: Address,
    pub redemption_amount: u128,
    pub request_date: Timestamp,
    pub status: RedemptionStatus,
}

pub enum RedemptionStatus {
    Pending,
    Approved,
    Rejected,
    Completed,
}

ACC-Insurance (保险协议)

数据结构:

pub struct InsurancePolicy {
    pub policy_id: Hash,
    pub asset_id: Hash,
    pub insured: Address,
    pub insurer: Address,
    pub coverage_amount: u128,
    pub premium: u128,
    pub start_date: Timestamp,
    pub end_date: Timestamp,
    pub policy_terms_hash: Hash,
}

ACC-Governance (治理协议)

数据结构:

pub struct GovernanceProposal {
    pub proposal_id: Hash,
    pub proposer: Address,
    pub title: String,
    pub description: String,
    pub voting_start: Timestamp,
    pub voting_end: Timestamp,
    pub votes_for: u128,
    pub votes_against: u128,
    pub status: ProposalStatus,
}

pub enum ProposalStatus {
    Pending,
    Active,
    Passed,
    Rejected,
    Executed,
}

ACC-XTZH (XTZH稳定币协议)

数据结构:

pub struct XTZHToken {
    pub total_supply: u128,
    pub reserve_assets: Vec<ReserveAsset>,
    pub peg_rate: u128,
    pub balances: HashMap<Address, u128>,
}

pub struct ReserveAsset {
    pub asset_type: String,
    pub amount: u128,
    pub value_in_sdr: u128,
}

ACC-Reserve (储备协议)

数据结构:

pub struct ReservePool {
    pub pool_id: Hash,
    pub assets: Vec<ReserveAsset>,
    pub total_value: u128,
    pub manager: Address,
    pub last_audit: Timestamp,
}

NVM 2.0模块

OpCode (操作码)

350个操作码（225个基础 + 125个RWA专属）。

数据结构:

pub enum OpCode {
    // 基础操作码 (0x00-0xE0)
    STOP = 0x00,
    ADD = 0x01,
    MUL = 0x02,
    // ... 225个基础操作码
    
    // RWA专属操作码 (0xE1-0xFF)
    CR_CREATE = 0xE1,        // 创建宪法收据
    CR_VERIFY = 0xE2,        // 验证宪法收据
    CR_GET = 0xE3,           // 获取宪法收据
    CR_REVOKE = 0xE4,        // 撤销宪法收据
    CR_EXTEND = 0xE5,        // 延长宪法收据
    
    GNACS_ENCODE = 0xE6,     // GNACS编码
    GNACS_DECODE = 0xE7,     // GNACS解码
    GNACS_VALIDATE = 0xE8,   // GNACS验证
    GNACS_CATEGORY = 0xE9,   // 获取资产类别
    GNACS_JURISDICTION = 0xEA, // 获取司法辖区
    
    ACC20_TRANSFER = 0xEB,   // ACC-20转账
    ACC20_APPROVE = 0xEC,    // ACC-20授权
    ACC20_MINT = 0xED,       // ACC-20铸造
    ACC20_BURN = 0xEE,       // ACC-20销毁
    ACC20_BALANCE = 0xEF,    // ACC-20余额查询
    
    ACC721_MINT = 0xF6,      // ACC-721铸造
    ACC721_TRANSFER = 0xF7,  // ACC-721转移
    ACC721_OWNER = 0xF8,     // ACC-721所有者查询
    ACC721_BURN = 0xF9,      // ACC-721销毁
}

方法:

// 获取操作码名称
pub fn name(&self) -> &'static str

// 是否是RWA专属操作码
pub fn is_rwa_specific(&self) -> bool

// 从字节创建操作码
pub fn from_u8(byte: u8) -> Option<Self>

Instruction (指令)

数据结构:

pub struct Instruction {
    pub opcode: OpCode,
    pub operands: Vec<u8>,
    pub gas_cost: u64,
}

构造方法:

// 创建新指令
pub fn new(opcode: OpCode) -> Self

// 创建带操作数的指令
pub fn with_operands(opcode: OpCode, operands: Vec<u8>) -> Self

GasCalculator (Gas计量)

方法:

// 计算操作码的Gas成本
pub fn calculate(opcode: &OpCode) -> u64

Gas成本表:

操作码类型	Gas成本
STOP	0
ADD, SUB	3
MUL, DIV	5
SLOAD	200
SSTORE	20,000
CR_CREATE	50,000
CR_VERIFY	10,000
GNACS_ENCODE	5,000
ACC20_TRANSFER	21,000

L0 CSNP网络层API

GIDS (全域身份目录服务)

数据结构:

pub struct GlobalIdentity {
    pub address: Address,
    pub identity_type: IdentityType,
    pub verification_level: u8,
    pub metadata: Vec<(String, String)>,
}

pub enum IdentityType {
    Individual,       // 个人
    Organization,     // 组织
    SmartContract,    // 智能合约
    RelayNode,        // 中继节点
}

MA-RCM (多链自适应连接管理器)

数据结构:

pub struct ChainConnection {
    pub chain_id: String,
    pub connection_type: ConnectionType,
    pub latency_ms: u32,
    pub bandwidth_mbps: u32,
}

pub enum ConnectionType {
    Direct,    // 直连
    Relay,     // 中继
    Bridge,    // 桥接
}

AA-PE (资产感知传播引擎)

数据结构:

pub struct AssetAwarePropagation {
    pub asset_id: Hash,
    pub priority: u8,
    pub propagation_strategy: PropagationStrategy,
}

pub enum PropagationStrategy {
    Broadcast,  // 广播
    Targeted,   // 定向
    Layered,    // 分层
}

FTAN (碎片化交易聚合网络)

数据结构:

pub struct FragmentedTransaction {
    pub tx_id: Hash,
    pub fragments: Vec<TransactionFragment>,
    pub total_fragments: u32,
}

pub struct TransactionFragment {
    pub fragment_id: u32,
    pub data: Vec<u8>,
}

UCA (统一跨链审计器)

数据结构:

pub struct CrossChainAuditRecord {
    pub audit_id: Hash,
    pub source_chain: String,
    pub target_chain: String,
    pub transaction_hash: Hash,
    pub auditor: Address,
    pub status: AuditStatus,
}

pub enum AuditStatus {
    Pending,    // 待审计
    Verified,   // 已验证
    Rejected,   // 已拒绝
}

多语言绑定

UDM支持Rust、Go、Charter三种语言的绑定。

语言枚举

pub enum Language {
    Rust,
    Go,
    Charter,
}

语言绑定

pub struct LanguageBinding {
    pub code: String,
    pub imports: Vec<String>,
    pub type_mappings: HashMap<String, String>,
}

类型映射表

UDM类型	Rust	Go	Charter
u8	u8	uint8	u8
u64	u64	uint64	u64
u128	u128	*big.Int	u128
u256	U256	*big.Int	u256
address	Address	[20]byte	address
hash	Hash	[32]byte	hash
bool	bool	bool	bool
string	String	string	string
bytes	Vec	[]byte	bytes

错误处理

所有可能失败的操作都返回Result<T, String>类型。

常见错误

错误类型	描述
`InvalidAddress`	无效的地址格式
`InvalidHash`	无效的哈希格式
`InvalidGNACSCode`	无效的GNACS编码
`ReceiptExpired`	宪法收据已过期
`InsufficientBalance`	余额不足
`UnauthorizedAccess`	未授权访问
`InvalidSignature`	无效的签名
`DuplicateDefinition`	重复的定义
`VersionConflict`	版本冲突

错误处理示例

use nac_udm::primitives::Address;

match Address::from_hex("0xinvalid") {
    Ok(addr) => println!("Address: {}", addr.to_hex()),
    Err(e) => eprintln!("Error: {}", e),
}

版本管理

UDM遵循语义化版本管理（SemVer 2.0.0）。

版本号格式

MAJOR.MINOR.PATCH[-PRE_RELEASE][+BUILD_METADATA]

版本兼容性规则

主版本号（MAJOR）: 不兼容的API变更
次版本号（MINOR）: 向后兼容的功能新增
补丁版本号（PATCH）: 向后兼容的问题修复

版本查询

use nac_udm::VERSION;

println!("UDM Version: {}", VERSION);

附录

A. 完整的模块清单

模块	描述	UID前缀
registry	核心注册表系统	nac.registry
primitives	基础原语类型	nac.primitives
l2_governance	L2宪法治理层	nac.l2
l1_protocol	L1多链协议层	nac.l1
l0_native	L0 CSNP网络层	nac.l0

B. 完整的ACC协议清单

协议	描述	UID
ACC-20	可替代代币	nac.l1.acc.acc20
ACC-721	不可替代代币	nac.l1.acc.acc721
ACC-1155	多代币标准	nac.l1.acc.acc1155
ACC-RWA	RWA资产标准	nac.l1.acc.rwa
ACC-Compliance	合规协议	nac.l1.acc.compliance
ACC-Valuation	估值协议	nac.l1.acc.valuation
ACC-Custody	托管协议	nac.l1.acc.custody
ACC-Collateral	抵押协议	nac.l1.acc.collateral
ACC-Redemption	赎回协议	nac.l1.acc.redemption
ACC-Insurance	保险协议	nac.l1.acc.insurance
ACC-Governance	治理协议	nac.l1.acc.governance
ACC-XTZH	XTZH稳定币协议	nac.l1.acc.xtzh
ACC-Reserve	储备协议	nac.l1.acc.reserve

C. 完整的NVM操作码清单

详见NVM 2.0模块章节。

D. 参考资源

NAC官方网站: https://newassetchain.io
NAC技术白皮书: https://docs.newassetchain.io/whitepaper
UDM GitHub仓库: https://github.com/newassetchain/nac-udm
CSNP协议规范: https://docs.newassetchain.io/csnp
CBPP共识协议: https://docs.newassetchain.io/cbpp
GNACS编码标准: https://docs.newassetchain.io/gnacs

文档结束

版本: 1.0.0
最后更新: 2025-02-07
维护者: NAC公链开发小组
许可证: MIT License

37 KiB Raw Blame History Unescape Escape

NAC UDM API规范文档

📋 目录

概述

核心特性

设计哲学

架构设计

L2: 宪法治理层 (Constitutional Governance Layer)

L1: 多链协议层 (Multi-Chain Protocol Layer)

L0: CSNP结构化网络层 (CSNP Structured Network Layer)

核心注册表系统API

UID (Unified Identifier)

数据结构

构造方法

查询方法

示例

Version (版本管理)

数据结构

构造方法

版本操作

版本比较

示例

Definition (定义抽象)

数据结构

定义类型

构造方法

查询方法

示例

DefinitionRegistry (定义注册表)

数据结构

注册方法

查询方法

统计方法

示例

基础原语类型API

Address (地址类型)

数据结构

构造方法

查询方法

示例

Hash (哈希类型)

数据结构

构造方法

查询方法

示例

Timestamp (时间戳类型)

数据结构

构造方法

查询方法

时间操作

示例

Signature (签名类型)

数据结构

构造方法

查询方法

示例

L2宪法治理层API

ConstitutionalClause (宪法条款)

数据结构

NetworkRule (网络规则)

数据结构

CrossChainRelayNode (跨链中继节点)

数据结构

PenaltyRecord (惩罚记录)

数据结构

L1多链协议层API

CBPP模块

ConstitutionalReceipt (宪法收据)

FluidBlock (流体区块)

OpenProductionNetwork (开放生产网络)

GossipProtocol (Gossip协议)

GNACS模块

GNACSCode (GNACS编码)

AssetCategory (资产分类)

Jurisdiction (司法辖区)

ComplianceLevel (合规级别)

RiskLevel (风险等级)

ACC协议族

ACC-20 (可替代代币)

ACC-721 (不可替代代币)

37 KiB

Raw Blame History