1. 摘要
此标准概述了一种智能合约接口,可以表示任意数量的同质化和非同质化代币类型。现有标准如ERC-20需要为每种代币类型部署单独的合约。ERC-721标准的代币ID是一个单一的非同质化索引,这些非同质化代币的集合作为一个单独的合约部署,具有适用于整个集合的设置。相比之下,ERC-1155多代币标准允许每个代币ID表示一种新的可配置代币类型,该类型可以有其自己的元数据、供应量和其他属性。
每个函数参数集中的_id参数表示交易中的特定代币或代币类型。
2. 动机
像ERC-20和ERC-721这样的代币标准要求为每种代币类型或集合部署单独的合约。这在以太坊区块链上放置了大量冗余的字节码,并且由于将每个代币合约分离到其自己的受限地址中,限制了某些功能。随着区块链游戏和像Enjin Coin这样的平台的兴起,游戏开发者可能会创建数千种代币类型,因此需要一种新的代币标准来支持它们。然而,ERC-1155并不仅限于游戏,许多其他应用也能从这种灵活性中受益。
这种设计可以实现新的功能,比如一次转移多种代币类型,从而节省交易成本。基于此标准可以构建多种代币的交易(托管/原子交换),并且不需要分别“批准”单个代币合约。在一个合约中描述和混合多种同质化或非同质化代币类型也变得容易。
3. 原理
- 多代币管理:
- 一个ERC-1155智能合约可以同时管理多个代币类型,每个代币类型用唯一的ID(
_id
)标识。 balanceOf
和balanceOfBatch
函数用于查询特定地址持有的单种或多种代币类型的余额。
- 一个ERC-1155智能合约可以同时管理多个代币类型,每个代币类型用唯一的ID(
- 高效的批量转移:
safeTransferFrom
函数用于单个代币类型的转移,而safeBatchTransferFrom
函数允许在一次调用中批量转移多个代币类型,提高了转移操作的效率。safeTransferFrom
和safeBatchTransferFrom
函数带有安全检查,确保目标地址能够处理代币。
- 授权和管理:
setApprovalForAll
函数允许代币持有者批量授权某地址管理其所有代币。isApprovedForAll
函数查询授权状态,确定某地址是否被授权管理代币。
ERC-1155标准的定义和实现,使得开发者能够在以太坊区块链上高效、灵活地创建和管理多种类型的数字资产,为去中心化应用和数字资产市场提供了强大的支持。
4. 规范
4.1. 初始化接口
部署合约时,填写合约的基本信息。会触发执行合约入口init方法,需要携带以下参数
调用示例:
{
"params":{
"name": "",
"symbol": "",
"describe": "",
"protocol": "",
"version": "",
"url": "",
"reserved": ""
}
}
调用示例参数说明:
参数 | 类型 | 描述 |
---|---|---|
name | String | 必填,合约名称,长度限64字节内 |
symbol | String | 必填,合约简称,长度限32字节内 |
describe | String | 必填,合约描述,长度限1024字节 |
protocol | String | 必填,资产数量,字符串型的数字 |
version | String | 必填,合约版本号, |
url | String | 选填,项目方网址 |
reserved | String | 选填,扩展字段 |
4.2. 调用接口
safeTransferFrom [required]
安全转移单个资产
注意事项:
- 触发事件: TransferSingle
调用示例:
{
"method": "safeTransferFrom",
"params":{
"from": "",
"to": "",
"id": "",
"value": "",
"data": ""
}
}
调用示例参数说明:
参数 | 类型 | 描述 |
---|---|---|
from | String | 源地址 |
to | String | 目标地址 |
id | String | 资产ID,64字节长度,16进制字符串数字 |
value | String | 资产数量,字符串型的数字 |
data | String | 附加数据 |
safeBatchTransferFrom [required]
批量安全转移多个资产
注意事项:
- 触发事件: TransferBatch
调用示例:
{
"method": "safeTransferFrom",
"params":{
"from": "",
"to": "",
"ids":["2", "3"],
"value":["1", "10"],
"datas":["data1", "data2"]
}
}
调用示例参数说明:
参数 | 类型 | 描述 |
---|---|---|
from | String | 源地址 |
to | String | 目标地址 |
ids | Array[String] | 资产ID数组列表。ids、values、datas的数组长度必须一致,(id, value,data)按索引匹配。 |
values | Array[String] | 资产数量,字符串型的数字数组列表。ids、values、datas的数组长度必须一致,(id, value,data)按索引匹配。 |
datas | Array[String] | 附加数据,数组列表。ids、values、datas的数组长度必须一致,(id, value,data)按索引匹配。 |
setApprovalForAll [required]
批准或者撤销第三方账户操作自己名下的所有资产
注意事项:
- 触发事件: ApprovalForAll
调用示例:
{
"method": "setApprovalForAll",
"params":{
"operator": "",
"approved": true
}
}
调用示例参数说明:
参数 | 类型 | 描述 |
---|---|---|
operator | String | 被批准的第三方账户地址 |
approved | Bool | 是否批准和撤销,True是批准,False是撤销 |
mint [optional]
发行单个的NFT资产
注意事项:
- 触发事件: TransferSingle,其中 from 参数为 "0x" 空地址
调用示例:
{
"method": "mint",
"params":{
"to": "",
"id": "000000000000000000000000000000000000000000000000000000000004cce0",
"value": "123",
"uri": "http://xxxx"
}
}
调用示例参数说明:
参数 | 类型 | 描述 |
---|---|---|
to | String | 发行的资产归属账户地址 |
id | String | 资产ID,64字节长度,16进制字符串数字 |
value | String | 发行个数,1的时候为非同质化资产,大于1为同质化资产 |
uri | String | URI资源地址。 |
burn [optional]
销毁NFT资产
注意事项:
- 触发事件: TransferSingle,其中 to参数为 "0x" 空地址
调用示例:
{
"method": "burn",
"params":{
"from": "",
"id": "000000000000000000000000000000000000000000000000000000000004cce0",
"value": "123"
}
}
调用示例参数说明:
参数 | 类型 | 描述 |
---|---|---|
from | String | 资产拥有者的地址 |
id | String | 资产ID,64字节长度,16进制字符串数字 |
value | String | 发行个数,1的时候为非同质化资产,大于1为同质化资产 |
4.3. 查询接口
balanceOf [required]
查询指定用户和ID的资产余额
调用示例:
{
"method": "balanceOf",
"params":{
"owner": "",
"id": ""
}
}
调用示例参数说明:
参数 | 类型 | 描述 |
---|---|---|
owner | String | 源地址 |
id | String | 资产ID |
响应数据:
{
"result":{
"type": "string",
"value": "xxxxx"// 为json字符串格式,json对象描述如下
}
}
{
"balance": "123"
}
balanceOfBatch [required]
批量获取资产余额
调用示例:
{
"method": "balanceOf",
"params":{
"owners":["", ""],
"ids": ["", ""],
}
}
调用示例参数说明:
参数 | 类型 | 描述 |
---|---|---|
owners[] | Array(String) | 资产拥有者的账户地址,数组。owners和ids长度一致,(owner, id)按索引匹配。 |
ids[] | Array(String) | 资产ID,数组。owners和ids长度一致,(owner, id)按索引匹配。 |
响应数据:
{
"result":{
"type": "string",
"value": "xxxxx"// 为json字符串格式,json对象描述如下
}
}
{
"balances": ["123", "456"]
}
isApprovedForAll [required]
查询给定第三方账户是否被资产的拥有者审批
调用示例:
{
"method": "isApprovedForAll",
"params":{
"owner": "",
"operator": ""
}
}
调用示例参数说明:
参数 | 类型 | 描述 |
---|---|---|
owner | String | 资产的拥有者 |
operator | String | 第三方操作者 |
响应数据:
{
"result":{
"type": "string",
"value": "xxxxx"// 为json字符串格式,json对象描述如下
}
}
{
"approved": true
}
contractInfo [required]
返回合约的基本信息
调用示例:
{
"method": "contractInfo"
}
调用示例参数说明:
无
响应数据:
{
"result":{
"type": "string",
"value": "xxxxx"// 为json字符串格式,json对象描述如下
}
}
{
"name": "contract Name",
"symbol": "symbol",
"describe": "describe",
"atp": "atp1155",
"version": "1.0.0",
"url:": "",
"reserved": ""
}
uri [required]
返回指定资产ID的JSON uri路径
调用示例:
{
"method": "uri",
"params":{
"id": "111111111"
}
}
调用示例参数说明:
无
响应数据:
{
"result":{
"type": "string",
"value": "xxxxx"// 为json字符串格式,json对象描述如下
}
}
{
"uri": ""
}
4.4. 事件定义
TransferSingle[required]
当资产被单独转移时候,需要触发该事件,包括铸造和销毁操作。
tlog('TransferSingle', operator, from, to, id, value);
事件参数:
参数 | 类型 | 描述 |
---|---|---|
TransferSingle | String | Tlog的 topic 主题名称 |
operator | String | 触发合约执行的源账户地址 |
from | String | 源账户地址 |
to | Object | 目标账户地址 |
id | String | 资产ID |
value | String | 资产数量,字符串型的数字 |
TransferBatch[required]
当资产被批量转移时候,需要触发该事件,包括铸造和销毁操作。
tlog('TransferBatch', operator, from, to, ids, values);
事件参数:
参数 | 类型 | 描述 |
---|---|---|
TransferBatch | String | Tlog的 topic 主题名称 |
operator | String | 触发合约执行的源账户地址 |
from | String | 源账户地址 |
to | Object | 目标账户地址 |
ids | String | 资产ID数组列表,JSON字符串格式。 |
values | String | 资产数量,字符串型的数字数组列表,JSON字符串格式。 |
ApprovalForAll[required]
当批准启用或禁用第三方使用权时候,需要发出该事件
tlog('ApprovalForAll', owner, operator, approved);
事件参数:
参数 | 类型 | 描述 |
---|---|---|
ApprovalForAll | String | Tlog的 topic 主题名称 |
owner | String | 触发合约执行的源账户地址 |
operator | String | 被批准的第三方账户地址 |
approved | Bool | 是否批准 |
URI[required]
当资产的URI发生变化时,必须抛出该事件。指向一个符合协议的JSON文件。
tlog('URI', value, id);
事件参数:
参数 | 类型 | 描述 |
---|---|---|
URI | String | Tlog的 topic 主题名称 |
value | String | url地址 |
id | String | 资产ID |