11.3 1808开发完整案例

在阅读此文当前建议先了解1808 非同质数字资产标准和世界观系统

1. 1808非同质资产数据结构说明

1808 标准非同质资产的数据结构分为两个基本功能区:固有数据区域用来存储非同质数字资产的基本信息,分为资产 ID、世界观申明以及基础数据区域三段;扩展数据区域是为非同质数字资产属性扩展专门设计的功能性数据区域,包括组合关系数据和域数据两部分。

固有数据定义该非同质数字资产 ID、世界观及其他基础数据,其中资产 ID是该资产实例在分布 记账式网络中的唯一标识,是该资产实例在进行访问、查询、修改等动作时的唯一凭据;世界观包 括该资产生效和支持的游戏类型、世界,以及此资产在网络中流通需要使用的世界流通货币类型; 基础数据包括资产所有者 ID、制作者 ID、制作时间和该资产的基本属性(例如装备描述等);另外 基础数据中也包含资产使用权黑白名单,用来约束使用者对此资产的数据访问范围,可根据需要定义为黑名单或白名单模式。

扩展数据区域是该资产支持的世界观内各业务数据的存储区域,包含组合关系数据区与域数据 两个部分,其中组合关系数据区包含两个表用于表达资产之间的嵌套组合关系;域数据区域则是不同业务实体在该区域拥有的专属数据区,不同业务实体间的数据区相互隔离,域数据以域标识和数据的键值对形式存储。

1. 创建非同质资产

即创建非同质资产固有数据

1.1 合约方式创建

create_nh_asset
原型

asset_id create_nh_asset(string owner_id_or_name, string symbol, string world_view, string base_describe, bool enable_logger)

说明
创建非同质道具,合约拥有者必须有对应的创建权限。
参数
name_or_id:非同质资产的拥有者
symbol:流通限定同质资产符号,例COCOS
world_view:世界观
base_describe:基础描述
enable_logger:标识是否在contract result中记录相关影响
合约代码

--创建非同质资产
function create_nh_asset(name_or_id,symbol,world_view,base_describe)
    asset_id = chainhelper:create_nh_asset(name_or_id,symbol,world_view,base_describe,true)
    chainhelper:log('new asset:'..asset_id)
end

1.2 SDK工具创建

通过Cocos-BCX JSSDK工具创建非同质资产。

方法
creatNHAsset
说明
创建一个唯一的NH资产,具有唯一性。
参数
assetId:当前NH资产交易时,适用的资产ID;
worldView:世界观;
baseDescribe:当前NH资产的具体内容描述,由制造者定义;
ownerAccount:指定NH资产拥有者(NH资产归属权账户,默认为NH资产创建者)
NHAssetsCount (Number):创建NH资产的数量,默认值为1,只有type为0即创建同一种NH资产生效
type:创建NH资产方式的类型,默认值为0。值为0时默认创建同一种NH资产,1是创建不同NH资产。
NHAssets(Array)示例:
[{
"assetId": "X.X.X",
"worldView": "GNK",
"baseDescribe": "{name:"预言家"}",
"ownerAccount": "gnkhandsome1"
}, {
"assetId": "X.X.X",
"worldView": "GNK",
"baseDescribe": "{name:"女巫"}",
"ownerAccount": "gnkhandsome1"
}, {
"assetId": "X.X.X",
"worldView": "GNK",
"baseDescribe": "{name:"猎人"}",
"ownerAccount": "gnkhandsome1"
}]

代码示例

1.3 Terminal 工具创建

Cocos Terminal -- 开发工具 -- 资产管理 -- 添加模板 -- 生产

2. 转移非同质资产

资产转移后资产所有者和使用者发生变更

2.1 合约方式转移

transfer_nht_from_caller
原型

void transfer_nht_from_caller(string to, string token_hash_or_id,bool enable_logger)

说明
从合约调用者转移非同质资产到账户to。
参数
to:接收账户id
token_hash_or_id:指定的非同质资产hash值或者id编号
enable_logger: 标识是否在contract result中记录相关影响

transfer_nht_from_owner
原型

void transfer_nht_from_owner(string to, string token_hash_or_id,bool enable_logger)

说明
从合约拥有者转移非同质资产到账户to。
参数
to:接收账户id
token_hash_or_id:指定的非同质资产hash值或者id编号
enable_logger: 标识是否在contract result中记录相关影响

合约代码

-- 从合约调用者转移非同质资产到账户to
function transfer_nht_from_caller(to,token_hash_or_id)
chainhelper:transfer_nht_from_caller(to,token_hash_or_id,true)
end
-- 从合约拥有者转移非同质资产到账户to。
function transfer_nht_from_owner(to,token_hash_or_id)
chainhelper:transfer_nht_from_owner(to,token_hash_or_id,true)
end

2.2 SDK工具转移

通过Cocos-BCX JSSDK工具转移非同质资产。

方法
transferNHAsset
说明
用户可以将自己的NH资产转移到另外一个用户
参数
toAccount:转移NH资产的目标用户名
NHAssetIds(Array):多个NH资产id组成的数组,示例:[X.X.X, X.X.X]

代码示例

bcx.transferNHAsset({ // bcx:sdk工具包对象
     toAccount:"gnkhandsome1",// 转移目标账户
     NHAssetIds:["4.2.xx"],// 非同质资产ids
     callback:function(res){
          console.info("transferNHAsset",res);
     }
 });

2.3 CocosWallet 工具转移
CocosWallet -- 我的 -- 资产总览 -- 非同质资产 -- 转移

3删除非同质资产

3.1 SDK工具删除

通过Cocos-BCX JSSDK工具删除非同质资产。

方法
deleteNHAsset
功能
删除整条NH资产数据记录,通常在商品销毁时使用(仅能由用户自己授权处理自己想要销毁的数据)。
参数
NHAssetIds (Array):NH资产实例的唯一标识ID;示例:[X.X.X, X.X.X]
代码示例

bcx.deleteNHAsset({
     NHAssetIds:["4.2.xx"],
     callback:function(res){
        console.info('deleteNHAsset res',res);
     }
 })

3.2 Terminal 工具删除

Cocos Terminal -- 交易市场 -- 非同质资产 -- 丢弃

3.3 CocosWallet 工具删除

CocosWallet -- 我的 -- 资产总览 -- 非同质资产 -- 删除

4.创建非同质资产出售单

4.1 SDK工具创建非同质资产出售单

通过Cocos-BCX JSSDK工具创建非同质资产出售单。

方法
creatNHAssetOrder
功能
卖出NH资产(在交易前可调用queryAccountGameItems函数,列举用户NH资产,以便用户选着卖出)
参数
otcAccount:OTC交易平台账户,用于收取挂单费用;(OTC平台填写)
orderFee:挂单费用,用户向OTC平台账户支付的挂单费用;(OTC平台填写)
NHAssetId:NH资产实例的唯一标识ID; (用户填写)
price:商品挂单价格;(用户填写)
priceAssetId:商品挂单价格所使用的代币种类;(用户填写)
expiration:挂单时间,如3600(秒),为1小时
memo:挂单备注信息;
callback:设置执行挂单卖出后的回调函数
代码示例

bcx.creatNHAssetOrder({
      otcAccount:"otcAccount",
      orderFee:1,
      NHAssetId:"4.2.xx",
      price:20,
      priceAssetId:"COCOS",
      expiration:3600,
      memo:"资产售卖"
      }).then(res=>{
         console.info('creatNHAssetOrder result',res);
      })

4.2 Terminal 工具创建非同质资产出售单

Cocos Terminal -- 交易市场 -- 非同质资产 -- 卖出

4.3 CocosWallet 工具创建非同质资产出售单

CocosWallet -- 我的 -- 资产总览 --非同质资产 -- 出售

5.购买全网非同质资产售卖单

5.1 SDK工具购买全网非同质资产售卖单

通过Cocos-BCX JSSDK工具购买全网非同质资产出售单。
方法
fillNHAssetOrder
功能
买入NH资产,支付购买游戏装备的代币费用,同时修改用户拥有的商品数据。该操作是一个多步合成的原子操作,在支付费用的同时完成用户账户NH资产数据的更新,如果支付动作或账户商品数据更新动作中某一个动作不被主链区块认可,则整个交易将被回滚,避免异常交易。
参数
orderId:订单ID
代码示例

bcx.fillNHAssetOrder({
       orderId:"4.3.xx",
       callback:function(res){
              console.info("fillNHAssetOrder res",res)          
         }
 })

5.2 Terminal 工具购买非同质资产出售单

Cocos Terminal -- 交易市场 -- 资产商店 -- 立即购买

5.3 CocosWallet 工具购买非同质资产出售单

CocosWallet -- 我的 -- 资产总览 -- 订单管理 -- 全网订单 -- 购买

6. 取消非同质资产售卖单

6.1 SDK工具取消非同质资产售卖单

通过Cocos-BCX JSSDK工具取消非同质资产出售单。

方法
cancelNHAssetOrder
功能
取消NH资产挂卖订单
参数
orderId:订单ID

代码示例

bcx.cancelNHAssetOrder({
       orderId:"4.3.xx",
       callback:function(res){
              console.info("cancelNHAssetOrder res",res)          
         }
   })

6.2 Terminal 工具取消非同质资产出售单

Cocos Terminal -- 交易市场 -- 交易订单-- 取消

6.3 CocosWallet 工具取消非同质资产出售单

CocosWallet -- 我的 -- 资产总览 -- 订单管理 -- 我的订单 -- 取消

7. 非同质资产的使用权限变更

7.1 非同质资产使用权限说明

nh_asset_active:可用于修改nh资产的扩展数据

7.2 变更合约拥有者非同质资产使用权

change_nht_active_by_owner
原型
void change_nht_active_by_owner (string beneficiary_account, string token_hash_or_id, bool enable_logger)
说明
修改非同质资产的使用权限,合约拥有者必须具有指定非同质资产代理权限或同时具有拥有权和使用权。
参数
beneficiary_account:将被赋予指定非同质资产使用权的账户名或账户ID
token_hash_or_id:指定的非同质资产的hash或id
enable_logger:标识是否在contract result中记录相关影响

合约代码

-- 修改非同质资产的使用权限,合约拥有者必须具有指定非同质资产(token_hash_or_id)的代理权限或同时具有拥有权和使用权。
function change_nht_active_by_owner (beneficiary_account, token_hash_or_id)
    chainhelper:change_nht_active_by_owner(beneficiary_account, token_hash_or_id, true)
end

7.3 变更合约调用者非同质资产使用权
transfer_nht_active_from_caller
原型
void transfer_nht_active_from_caller( string to, string token_hash_or_id, bool enable_logger)
说明
从合约调用者转移非同质资产使用权,调用者必须具有指定非同质资产代理权限或同时具有拥有权和使用权。
参数
to:将被赋予指定非同质资产使用权的账户名或账户ID
token_hash_or_id:指定的非同质资产的hash或id
enable_logger:标识是否在contract result中记录相关影响

合约代码

-- 从合约调用者转移非同质资产使用权,调用者必须具有指定非同质资产代理权限或同时具有拥有权和使用权。
function transfer_nht_active_from_caller(to, token_hash_or_id)
    chainhelper:transfer_nht_active_from_caller(to, token_hash_or_id, true)
end

8. 非同质资产代理控制权转移

8.1 非同质资产代理控制权

dealership:主要用于合约代理管理nh_asset_active权限的转移

8.2 转移合约拥有者非同质资产代理控制权

transfer_nht_dealership_from_owner
原型

void transfer_nht_dealership_from_owner(string to, string token_hash_or_id, bool enable_logger)

说明
从合约拥有者转移非同质资产代理控制权,合约拥有者必须具有指定非同质资产代理权限。
参数
to:将被赋予指定非同质资产代理控制权的账户名或账户ID
token_hash_or_id:指定的非同质资产的hash或id
enable_logger:标识是否在contract result中记录相关影响
合约代码

--从合约拥有者转移非同质资产代理权限到账户to。
function transfer_nht_dealership_from_owner(to, token_hash_or_id)
    chainhelper:transfer_nht_dealership_from_owner(to,token_hash_or_id,true)
end

8.3 转移合约调用者非同质资产代理控制权

transfer_nht_dealership_from_caller
原型

void transfer_nht_authority_from_caller( string to, string token_hash_or_id, bool enable_logger)

说明
从合约拥有者转移非同质资产代理控制权,调用者必须拥有指定非同质资产代理权限。
参数
to:将被赋予指定非同质代资产理控制权的账户名或账户ID
token_hash_or_id:指定的非同质资产的hash或id
enable_logger:标识是否在contract result中记录相关影响

合约代码

--从合约调用者转移非同质资产代理权限到账户to。
function transfer_nht_dealership_from_caller(to, token_hash_or_id)
  chainhelper:transfer_nht_dealership_from_caller(to,token_hash_or_id,true)
end

设置非同质资产扩展数据域的读写权限
##9.1 方法调用说明
方法调用者必须同时具有指定非同质资产的拥有权和使用权。

set_nht_limit_list
原型

void set_nht_limit_list( string token_hash_or_id, string contract_name_or_ids, bool limit_type, bool enable_logger)

说明
设置指定道具的指定扩展域(合约数据域)的读写权限,调用者者必须具有指定非同质资产的拥有权和使用权。
参数
token_hash_or_id:指定的非同质资产的hash或id
contract_name_or_ids:多个数据域(合约)使用“,”分割
limit_type:为true时代表白名单,被指定的数据域将允许写入;为false时代表黑名单,被指定的数据域将不允许写入
enable_logger:标识是否在contract result中记录相关影响

合约代码

function set_nht_limit_list(token_hash_or_id,contract_name_or_ids,limit_type)
 chainhelper:set_nht_limit_list(token_hash_or_id,contract_name_or_ids,limit_type,true)
end

10. 关联非同质资产

10.1 合约部署特殊性和方法调用说明

使用到该方法的合约部署时,合约权限需要使用账户的active公钥,所以合约只有该部署账户可调用,并且该账户需拥有要关联的父级非同质资产和子级非同质资产的拥有权。

relate_nh_asset
原型
void relate_nh_asset(string parent_token_hash_or_id, string child_token_hash_or_id, bool relate, bool enable_logger)
说明
将两个非同质资产进行关联。
参数
parent_token_hash_or_id:指定的父级非同质资产的hash或id
child_token_hash_or_id :指定的子级非同质资产的hash或id
relate :是否关联
enable_logger:标识是否在contract result中记录相关影响

合约代码

-- 将两个非同质资产进行关联。
function relate_nh_asset(parent_token_hash_or_id, child_token_hash_or_id, relate)
  chainhelper:relate_nh_asset(parent_token_hash_or_id,child_token_hash_or_id,relate,true)
end

11. 修改非同质资产合约对应的域数据

nht_describe_change
原型

void nht_describe_change(string nht_hash_or_id, string key, string value,bool enable_logger)

说明
修改非同质资产的域数据描述,只能修改合约对应的域,调用者者必须具有指定非同质资产的使用权或代理控制权。
参数
token_hash_or_id:指定的非同质资产hash值或者id编号
key:域数据键名
value: 域数据键对应值
enable_logger: 标识是否在contract result中记录相关影响

合约代码

-- 通过传入json字符串,修改非同质资产的域数据描述,只能修改合约对应的域。
function nht_change_with_json( nht_hash_or_id,values_json) 
    local values=cjson.decode(values_json) 
    for key,value in pairs(values)  do  
        chainhelper:log('key:'..key..',value:'..value)   
        chainhelper:nht_describe_change( nht_hash_or_id,key,value,true)  
    end  
end

-- 通过传入table对象,修改非同质资产的域数据描述,只能修改合约对应的域。
function nht_change_with_table( nht_hash_or_id,values_table) 
    for key,value in pairs(values_table)  do  
        chainhelper:log('key:'..key..',value:'..value)   
        chainhelper:nht_describe_change( nht_hash_or_id,key,value,true)  
    end  
end

11.1 合约被加入资产域数据修改的黑名单时的权限说明

如果合约被加入资产域数据修改的黑名单,则合约调用账户需要同时拥有非同质资产的使用权和拥有权,才能修改资产对应的该合约域的数据。

12. 合约案例

合约案例

Updated 9 months ago

11.3 1808开发完整案例


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.