425 lines
8.6 KiB
Markdown
425 lines
8.6 KiB
Markdown
# ACC-1155: 多代币证书协议使用指南
|
||
|
||
## 概述
|
||
|
||
ACC-1155是NAC原生的多代币证书协议，允许在单个证书中管理多种代币类型。与ERC-1155不同，ACC-1155深度集成了NAC的核心特性，提供了更强大的资产管理能力。
|
||
|
||
## 核心特性
|
||
|
||
### 1. 三种代币类型
|
||
|
||
ACC-1155支持三种代币类型：
|
||
|
||
- **Fungible（可替代代币）**：类似ACC-20，每个单位完全相同，可互换
|
||
- **NonFungible（不可替代代币）**：类似ACC-721，每个单位都是唯一的
|
||
- **SemiFungible（半可替代代币）**：介于两者之间，如游戏道具
|
||
|
||
### 2. 代币类型DNA
|
||
|
||
每个代币类型都有唯一的DNA，包含：
|
||
- DNA哈希（Blake3）
|
||
- GNACS编码
|
||
- 代币类型（可替代性）
|
||
- 主权类型
|
||
- 元数据哈希
|
||
- 生成时间
|
||
|
||
### 3. 主权类型（A0-G5）
|
||
|
||
ACC-1155支持7种资产权利类型：
|
||
|
||
| 类型 | 名称 | 说明 |
|
||
|------|------|------|
|
||
| A0 | 完全所有权 | 拥有资产的所有权利 |
|
||
| B1 | 使用权 | 仅拥有使用资产的权利 |
|
||
| C2 | 收益权 | 仅拥有获取资产收益的权利 |
|
||
| D2 | 处置权 | 仅拥有处置资产的权利 |
|
||
| E3 | 担保权 | 资产作为担保物的权利 |
|
||
| F4 | 优先权 | 优先购买或使用的权利 |
|
||
| G5 | 其他权利 | 其他特殊权利 |
|
||
|
||
### 4. 批量操作
|
||
|
||
ACC-1155针对批量操作进行了优化：
|
||
- 批量铸造（mint_batch）
|
||
- 批量转移（safe_transfer_batch）
|
||
- 批量销毁（burn_batch）
|
||
- 批量查询余额（balance_of_batch）
|
||
|
||
### 5. 混合资产管理
|
||
|
||
单个ACC-1155证书可以同时管理：
|
||
- 可替代代币（如游戏金币）
|
||
- 不可替代代币（如传奇装备）
|
||
- 半可替代代币（如消耗品）
|
||
|
||
### 6. NAC原生特性
|
||
|
||
- **GNACS编码**：48位全球原生资产链统一分类标准
|
||
- **托管系统**：按代币类型的托管信息
|
||
- **保险系统**：按代币类型的保险信息
|
||
- **AI估值**：支持AI估值提供商
|
||
- **宪法收据**：所有批量操作都返回宪法收据哈希
|
||
- **NRPC3.0**：使用NAC原生RPC协议
|
||
|
||
## 快速开始
|
||
|
||
### 1. 添加依赖
|
||
|
||
```toml
|
||
[dependencies]
|
||
nac-sdk = "0.1.0"
|
||
nac-udm = "0.1.0"
|
||
tokio = { version = "1.0", features = ["full"] }
|
||
```
|
||
|
||
### 2. 创建客户端
|
||
|
||
```rust
|
||
use nac_sdk::client::NRPC3Client;
|
||
use nac_sdk::protocols::ACC1155;
|
||
|
||
let client = NRPC3Client::new("https://rpc.newassetchain.io");
|
||
let acc1155 = ACC1155::new(client);
|
||
```
|
||
|
||
### 3. 创建代币类型
|
||
|
||
```rust
|
||
use nac_udm::l1_protocol::gnacs::{GNACSCode, AssetCategory, Jurisdiction, ComplianceLevel, RiskLevel};
|
||
use nac_udm::l1_protocol::acc::acc1155::{TokenType, SovereigntyType, TokenTypeMetadata};
|
||
use nac_udm::primitives::Timestamp;
|
||
|
||
// 创建GNACS编码
|
||
let gnacs = GNACSCode::new(
|
||
AssetCategory::Digital,
|
||
1,
|
||
Jurisdiction::US,
|
||
ComplianceLevel::High,
|
||
RiskLevel::Low,
|
||
);
|
||
|
||
// 创建代币元数据
|
||
let metadata = TokenTypeMetadata {
|
||
token_id: 1,
|
||
name: "Game Gold".to_string(),
|
||
symbol: "GOLD".to_string(),
|
||
token_type: TokenType::Fungible,
|
||
uri: "ipfs://QmGameGold".to_string(),
|
||
max_supply: Some(10_000_000),
|
||
current_supply: 0,
|
||
created_at: Timestamp::now(),
|
||
};
|
||
|
||
// 创建代币类型
|
||
let token_dna = acc1155.create_token_type(
|
||
&certificate_address,
|
||
1,
|
||
TokenType::Fungible,
|
||
gnacs,
|
||
SovereigntyType::A0,
|
||
metadata,
|
||
Some(10_000_000),
|
||
).await?;
|
||
|
||
println!("Token DNA: {}", token_dna.dna_hash);
|
||
```
|
||
|
||
### 4. 批量铸造代币
|
||
|
||
```rust
|
||
let batch_mint = acc1155.mint_batch(
|
||
&certificate_address,
|
||
&owner_address,
|
||
vec![1, 2, 3],
|
||
vec![1000, 500, 200],
|
||
).await?;
|
||
|
||
println!("Constitutional Receipt: {}", batch_mint.constitutional_receipt);
|
||
```
|
||
|
||
### 5. 批量转移代币
|
||
|
||
```rust
|
||
let batch_transfer = acc1155.safe_transfer_batch(
|
||
&certificate_address,
|
||
&from_address,
|
||
&to_address,
|
||
vec![1, 2],
|
||
vec![100, 50],
|
||
).await?;
|
||
|
||
println!("Transfer Receipt: {}", batch_transfer.constitutional_receipt);
|
||
```
|
||
|
||
## API参考
|
||
|
||
### 基础查询
|
||
|
||
#### balance_of
|
||
获取单个代币余额
|
||
|
||
```rust
|
||
let balance = acc1155.balance_of(
|
||
&certificate_address,
|
||
&holder_address,
|
||
token_id,
|
||
).await?;
|
||
```
|
||
|
||
#### balance_of_batch
|
||
批量获取代币余额
|
||
|
||
```rust
|
||
let balances = acc1155.balance_of_batch(
|
||
&certificate_address,
|
||
vec![holder1, holder2, holder3],
|
||
vec![token_id1, token_id2, token_id3],
|
||
).await?;
|
||
```
|
||
|
||
### 代币类型管理
|
||
|
||
#### create_token_type
|
||
创建新的代币类型（含DNA生成）
|
||
|
||
```rust
|
||
let token_dna = acc1155.create_token_type(
|
||
&certificate_address,
|
||
token_id,
|
||
token_type,
|
||
gnacs_code,
|
||
sovereignty_type,
|
||
metadata,
|
||
max_supply,
|
||
).await?;
|
||
```
|
||
|
||
#### get_token_metadata
|
||
获取代币元数据
|
||
|
||
```rust
|
||
let metadata = acc1155.get_token_metadata(
|
||
&certificate_address,
|
||
token_id,
|
||
).await?;
|
||
```
|
||
|
||
#### get_token_dna
|
||
获取代币类型DNA
|
||
|
||
```rust
|
||
let token_dna = acc1155.get_token_dna(
|
||
&certificate_address,
|
||
token_id,
|
||
).await?;
|
||
```
|
||
|
||
### 批量操作
|
||
|
||
#### mint_batch
|
||
批量铸造代币
|
||
|
||
```rust
|
||
let batch_mint = acc1155.mint_batch(
|
||
&certificate_address,
|
||
&to_address,
|
||
vec![token_id1, token_id2],
|
||
vec![amount1, amount2],
|
||
).await?;
|
||
```
|
||
|
||
#### safe_transfer_batch
|
||
批量安全转移
|
||
|
||
```rust
|
||
let batch_transfer = acc1155.safe_transfer_batch(
|
||
&certificate_address,
|
||
&from_address,
|
||
&to_address,
|
||
vec![token_id1, token_id2],
|
||
vec![amount1, amount2],
|
||
).await?;
|
||
```
|
||
|
||
#### burn_batch
|
||
批量销毁代币
|
||
|
||
```rust
|
||
let batch_burn = acc1155.burn_batch(
|
||
&certificate_address,
|
||
&from_address,
|
||
vec![token_id1, token_id2],
|
||
vec![amount1, amount2],
|
||
).await?;
|
||
```
|
||
|
||
### 授权管理
|
||
|
||
#### set_approval_for_all
|
||
设置授权
|
||
|
||
```rust
|
||
acc1155.set_approval_for_all(
|
||
&certificate_address,
|
||
&owner_address,
|
||
&operator_address,
|
||
true,
|
||
).await?;
|
||
```
|
||
|
||
#### is_approved_for_all
|
||
检查授权状态
|
||
|
||
```rust
|
||
let is_approved = acc1155.is_approved_for_all(
|
||
&certificate_address,
|
||
&owner_address,
|
||
&operator_address,
|
||
).await?;
|
||
```
|
||
|
||
### NAC特色功能
|
||
|
||
#### get_custody_info
|
||
获取托管信息
|
||
|
||
```rust
|
||
let custody_info = acc1155.get_custody_info(
|
||
&certificate_address,
|
||
token_id,
|
||
).await?;
|
||
```
|
||
|
||
#### get_insurance_info
|
||
获取保险信息
|
||
|
||
```rust
|
||
let insurance_info = acc1155.get_insurance_info(
|
||
&certificate_address,
|
||
token_id,
|
||
).await?;
|
||
```
|
||
|
||
#### update_token_valuation
|
||
更新代币估值
|
||
|
||
```rust
|
||
let valuation = TokenTypeValuation {
|
||
token_id,
|
||
value_per_unit_xtzh: 1_000_000_000_000_000u128,
|
||
valuation_provider,
|
||
valued_at: Timestamp::now(),
|
||
validity_period: 30 * 24 * 3600,
|
||
};
|
||
|
||
acc1155.update_token_valuation(
|
||
&certificate_address,
|
||
token_id,
|
||
valuation,
|
||
).await?;
|
||
```
|
||
|
||
#### get_token_valuation
|
||
获取代币估值
|
||
|
||
```rust
|
||
let valuation = acc1155.get_token_valuation(
|
||
&certificate_address,
|
||
token_id,
|
||
).await?;
|
||
```
|
||
|
||
## 与ERC-1155的对比
|
||
|
||
| 特性 | ERC-1155 | ACC-1155 |
|
||
|------|----------|----------|
|
||
| 基础功能 | ✅ | ✅ |
|
||
| 代币类型DNA | ❌ | ✅ |
|
||
| GNACS编码 | ❌ | ✅ |
|
||
| 主权类型 | ❌ | ✅ |
|
||
| 三种代币类型 | ❌ | ✅ |
|
||
| 托管系统 | ❌ | ✅ |
|
||
| 保险系统 | ❌ | ✅ |
|
||
| AI估值 | ❌ | ✅ |
|
||
| 混合资产池 | ❌ | ✅ |
|
||
| 宪法收据 | ❌ | ✅ |
|
||
| 批量操作优化 | ✅ | ✅ |
|
||
| RPC协议 | JSON-RPC | NRPC3.0 |
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 代币类型设计
|
||
|
||
- 为不同用途的代币使用不同的代币ID
|
||
- 合理设置最大供应量
|
||
- 使用GNACS编码进行分类
|
||
|
||
### 2. 批量操作
|
||
|
||
- 尽可能使用批量操作以提高效率
|
||
- 批量操作中的token_ids和amounts数组长度必须一致
|
||
|
||
### 3. 授权管理
|
||
|
||
- 谨慎设置授权，避免安全风险
|
||
- 定期检查授权状态
|
||
|
||
### 4. 估值更新
|
||
|
||
- 定期更新代币估值
|
||
- 设置合理的估值有效期
|
||
|
||
### 5. 混合资产管理
|
||
|
||
- 在同一证书中管理相关的代币类型
|
||
- 使用HybridAssetPool进行分类管理
|
||
|
||
## 错误处理
|
||
|
||
```rust
|
||
use nac_sdk::error::{NACError, Result};
|
||
|
||
match acc1155.balance_of(&certificate_address, &holder, token_id).await {
|
||
Ok(balance) => println!("Balance: {}", balance),
|
||
Err(NACError::InvalidAddress(e)) => eprintln!("Invalid address: {}", e),
|
||
Err(NACError::InvalidResponse(e)) => eprintln!("Invalid response: {}", e),
|
||
Err(e) => eprintln!("Error: {:?}", e),
|
||
}
|
||
```
|
||
|
||
## 测试
|
||
|
||
运行单元测试：
|
||
|
||
```bash
|
||
cargo test acc1155
|
||
```
|
||
|
||
运行集成测试（需要NAC节点）：
|
||
|
||
```bash
|
||
cargo test --test acc1155_integration_test -- --ignored
|
||
```
|
||
|
||
## 示例代码
|
||
|
||
完整的示例代码请参考：`examples/acc1155_example.rs`
|
||
|
||
运行示例：
|
||
|
||
```bash
|
||
cargo run --example acc1155_example
|
||
```
|
||
|
||
## 相关资源
|
||
|
||
- [NAC技术白皮书](https://newassetchain.io/whitepaper)
|
||
- [GNACS编码标准](https://newassetchain.io/gnacs)
|
||
- [ACC协议族文档](https://newassetchain.io/acc)
|
||
- [NRPC3.0协议规范](https://newassetchain.io/nrpc3)
|
||
|
||
## 许可证
|
||
|
||
MIT License
|