1. 摘要
本标准说明了在智 能合约中实现代币的标准API。
该标准提供了代币的基本功能:如转移代币,授权代币给其他人(如链上第三方应用)使用。
2. 动机
标准接口允许布比链上的任何代币被其他应用程序重用,如钱包、去中心化交易所等。
3. 原理
- 代币创建和总供应量:
- 创建合约时,代币的总供应量会被定义,并且通常会分配给合约创建者。
totalSupply
函数返回这个总供应量,balanceOf
函数用于查询任意地址的代币余额。
- 代币转移:
- 使用
transfer
函数可以直接从调用者的地址向另一个地址发送代币。 transferFrom
函数允许在授权后,由第三方账户从一个地址向另一个地址转移代币。
- 使用
- 代币授权和消费:
approve
函数允许代币所有者预先授权一个账户可以使用其代币。- 授权账户可以通过
transferFrom
函数消费被授权的代币数量。 allowance
函数用来查询被授权账户仍然可以使用的代币余额。
数字积分标准的定义和实现使得不同的代币可以在以太坊生态系统中互相兼容,方便了代币的创建、交易和管理。
4. 规范
4.1. 初始化接口
部署合约时,填写合约的基本信息。会触发执行合约入口init方法,需要携带以下参数
调用示例:
{
"params":{
"name": "",
"symbol": "",
"describe": "",
"decimals":"",
"supply": "",
"protocol":"",
"version": "",
"url": "",
"reserved": ""
}
}
变量 | 描述 |
---|---|
name | Token 名称 |
symbol | Token 符号 |
describe | 合约描述 |
decimals | Token 小数位数 |
supply | 发行数量 |
protocol | ATP协议信息,必须填 ATP20 |
version | 版本信息。合约版本,如 1.0.0 |
url | 项目介绍地址,可为空 |
reserved | 保留信息,可为空 |
注意:
- name:推荐使用单词全拼,每个首字母大写。如 Demo Token
- symbol:推荐使用大写首字母缩写。如 DT
- describe:合约描述
- decimals:小数位在 0~8 的范围,0 表示无小数位
- supply:范围是 1~2^63-1
- protocol:atp的信息。如 atp20
- version:版本信息。合约版本,如
1.0.0
- url:项目介绍地址
- reserved:保留信息
4.2. 调用接口
transfer[required]
转移 value 数量的 token 到的地址 to,并且必须触发 log 事件。 如果资金转出账户余额没有足够的token来支出,该函数应该被throw。
注意事项:
- 触发事件: Transfer
调用示例:
{
"method":"transfer",
"params":{
"to":"xxxx",
"value":"1000000"
}
}
调用示例参数说明:
参数 | 类型 | 描述 |
---|---|---|
to | String | 必填,目标地址 |
value | String | 必填,资产数量,字符串型的数字 |
approve[required]
授权账户 spender 可以从交易发送者账户转出数量为 value 的token。
注意事项:
- 触发事件: Approve
调用示例:
{
"method":"approve",
"params":{
"spender":"xxxx",
"value":"1000000"
}
}
调用示例参数说明:
参数 | 类型 | 描述 |
---|---|---|
spender | String | 必填,账户地址 |
value | String | 必填,被授权可转移数量,字符串型的数字 |
transferFrom[required]
从from发送数量为 value 的 token 到 to,必须触发 log 事件。 在 transferFrom 之前,from 必须给当前交易的发起者进行授权额度(即approve操作)。如果 from 余额没有足够的 token 来支出或者 from 授权给当前交易的发起者的额度不足,该函数应该被 throw。
注意事项:
- 触发事件: Transfer
调用示例:
{
"method":"transferFrom",
"params":{
"from":"xxxx",
"to":"xxxx",
"value":"1000000"
}
}
调用示例参数说明:
参数 | 类型 | 描述 |
---|---|---|
from | String | 必填,源地址 |
to | String | 必填,目标地址 |
value | String | 必填,资产数量,字符串型的数字 |
4.3. 查询接口
balanceOf[required]
返回指定账户的 token
注意事项:
- address参数为合法地址
调用示例:
{
"method":"balanceOf",
"params":{
"address":"xxxx"
}
}
调用示例参数说明:
参数 | 类型 | 描述 |
---|---|---|
address | String | 必填,账户地址 |
响应数据:
{
"result":{
"type": "string",
"value": "xxxxx"// 为json字符串格式,json对象描述如下
}
}
{
"balance": "123"
}
allowance[required]
返回 spender 仍然被允许从 owner 提取的金额。
注意事项:
- owner参数为合法地址
- spender参数为合法地址
调用示例:
{
"method":"allowance",
"params":{
"owner":"xxxx",
"spender":"xxxx"
}
}
调用示例参数说明:
参数 | 类型 | 描述 |
---|---|---|
owner | String | 必填,账户地址 |
spender | String | 必填,账户地址 |
响应数据:
{
"result":{
"type": "string",
"value": "xxxxx"// 为json字符串格式,json对象描述如下
}
}
{
"allowance": "1000000"
}
contractInfo[required]
返回 Token 的基本信息。
调用示例:
{
"method":"contractInfo"
}
调用示例参数说明:
无
响应数据:
{
"result":{
"type": "string",
"value": "xxxxx"// 为json字符串格式,json对象描述如下
}
}
{
"name": "DemoToken",
"symbol": "DT",
"describe": "",
"decimals": "8",
"supply": "5000000000000",
"protocol": "ATP20",
"version": "1.0.0",
"url": "",
"reserved": ""
}
4.4. 事件定义
Transfer[required]
当资产被转移时候,需要触发该事件,包括铸造和销毁操作。
tlog('Transfer', from, to, value);
事件参数:
参数 | 类型 | 描述 |
---|---|---|
Transfer | String | Tlog的 topic 主题名称 |
from | String | 合约调用账户地址 |
to | String | 目标账户地址 |
value | String | 转移数量(字符串类型) |
Approve[required]
授权时候,需要触发该事件。
tlog('Approve', owner, spender, value);
事件参数:
参数 | 类型 | 描述 |
---|---|---|
Approve | String | Tlog的 topic 主题名称 |
owner | String | 合约调用账户地址 |
spender | String | 被授权账户地址 |
value | String | 被授权可转移数量(字符串类型) |