[区块链]Clarity智能合约程序开发语言｜SIP010协议，可替代代币标准

该英文文档原地址：https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md

前言

SIP号码：010

标题：可替代(易于交易的)代币的标准特征定义

作者：Hank Stoever hstove@gmail.com，Pascal Belloncle psq@nanorails.com

归类：技术

类型：标准

状态：已批准

创建时间：2021 年 1 月 25 日

许可证：CC0-1.0

签字人：Jude Nelson jude@stacks.org，技术指导委员会主席

层：特征

讨论区域：https://github.com/stacksgov/sips

总览

同质化代币是可以发送、接收、组合和分割的数字资产。大多数形式的加密货币都是可替代的代币。它们已成为几乎所有区块链的基石。该 SIP 旨在提供一种灵活且易于实施的标准，供开发人员在 Stacks 区块链上创建自己的代币。

许可和版权

本 SIP10协议 根据 Creative Commons CC0 1.0 通用许可条款撰写，大家可以在 https://creativecommons.org/publicdomain/zero/1.0/ 获得。 本 SIP协议的版权由 Stacks Open Internet Foundation 持有。

介绍

数字资产可以具有易于交易的特点。一个易于交易的代币可以分解成小单元并加在一起。易于交易的资产的所有者只需要关心他们的余额，即他们所拥有的特定易于交易的资产的总量。大多数知名货币都是可替代的。对于易于交易的代币，任何两种不同数量的易于交易的代币之间没有区别。

例如，如果用户拥有10个单位的易于交易的资产，他们可以将2个单位发送给不同的用户。此时，他们的余额为8个单位。如果他们以后收到更多单位，他们的总余额将被更新。

在区块链上，易于交易的代币是核心组件。带有智能合约程序功能的区块链，包括Stacks区块链，允许开发人员和用户创建使用易于交易的代币的智能合约，并与之交互。

Stacks区块链有一个原生的易于交易的代币：Stacks 代币 (STX)。除了原生的STX代币之外，Stacks 区块链用于开发智能合约程序的编程语言 Clarity 还具有用于定义和使用易于交易的代币的内置语言原语。尽管存在这些原语，但定义一个通用接口（在 Clarity 中称为“特征”）是有价值的，该接口允许不同的智能合约以可重用的方式与易于交易的代币合约进行互操作。此SIP协议定义了这种特征。

规范

易于交易的代币特征 sip-010-trait 有 7 个功能：

Transfer（转账）

(transfer ((amount uint) (sender principal) (recipient principal) (memo (optional (buff 34)))) (response bool uint))

将易于交易的代币从交易的发送方转移到接收方。该金额是一个无符号整数。建议执行合约程序时使用内置的 ft-transfer? Clarity方法。如果发送方没有足够的代币来完成交易，则交易应中止并返回 (err uint)。

此方法必须使用define-public 定义，因为它会改变状态，并且应该从外部调用。

合约程序的执行人应注意对transfer方法进行授权。例如，想要确保只有交易的发送方能够转移请求的易于交易的代币的合约程序，可能要首先检查发送方参数是否等于 tx-sender。

在此函数内部返回错误时，错误代码应遵循与内置的 ft-transfer?和stx-transfer?函数相同的样式。

合约程序执行人应该注意，在 Stacks 2.0 中，memo 备注字段不会包含在已经发送成功的 ft-transfer？事件中。因此，如果需要遵守交易所规则，建议发出一个包括memo备忘字段的事件，通过添加一个 print声明语句 如果 ft-transfer?执行成功的话。

举例：

(try! (ft-transfer? token amount sender recipient))
? (print memo)

命名：

(get-name () (response (string-ascii 32) uint))

?

为合约程序返回一个人类可以读的懂的名称，例如“CoolPoints”等。

此方法应定义为只读，即 define-read-only。

符号

(get-symbol () (response (string-ascii 32) uint))

?

返回一个符号，允许用更简短的符号来代表代币。这有时被称为“ticker”。示例：“STX”、“COOL”等。通常，在以书面形式谈到代币时，可以将其称为 $SYMBOL。

此方法应定义为只读，即define-read-only。

小数

(get-decimals () (response uint uint))

代币中的小数位数。所有易于交易的代币余额都必须表示为整数，但提供小数位数提供了人类更熟悉的代币的抽象概念。例如，如果基本单位是“美分”，则美元有2位小数，这在财务中是典型的做法。 Stacks 有6位小数，比特币有8位小数，依此类推。

再举一个例子，如果一个代币有4位小数，并且特定用户的 get-balance 方法返回 100345000，钱包和交易所可能会将该值表示为 10034.5。

此方法应定义为只读，即define-read-only。

余额

(get-balance (principal) (response uint uint))

返回一个特定主体用户（也称为“地址”或“帐户”）的余额。通常应该使用Clarity语言中内置的方法 ft-get-balance。

此方法应定义为只读，即define-read-only。

总供应量

(get-total-supply () (response uint uint))

?

返回此代币的总供应量。通常应该使用Clarity语言中内置的方法 ft-get-supply。

此方法应定义为只读，即define-read-only。

代币URI

(get-token-uri () (response (optional (string-utf8 256)) uint))

返回一个可选字符串，该字符串是一个有效URI，它解析为该代币的元数据。这允许您的代币提供有关合约程序的链外元数据，例如描述文字和图像图标。

此元数据的JSON格式如下：

{
? "title": "Asset Metadata",
? "type": "object",
? "properties": {
? ? "name": {
? ? ? "type": "string",
? ? ? "description": "Identifies the asset to which this token represents"
? ? },
? ? "description": {
? ? ? "type": "string",
? ? ? "description": "Describes the asset to which this token represents"
? ? },
? ? "image": {
? ? ? "type": "string",
? ? ? "description": "A URI pointing to a resource with mime type image/* representing the asset to which this token represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive."
? ? }
? }
}

获取此数据的客户端应该更喜欢链上数据，例如代币的名称，而不是 get-token-uri 中提供的元数据。

特征实现

下面的代码提供了所提议特征的实现。

(define-trait sip-010-trait
? (
? ? ;; Transfer from the caller to a new principal
? ? (transfer (uint principal principal (optional (buff 34))) (response bool uint))

? ? ;; the human readable name of the token
? ? (get-name () (response (string-ascii 32) uint))

? ? ;; the ticker symbol, or empty if none
? ? (get-symbol () (response (string-ascii 32) uint))

? ? ;; the number of decimals used, e.g. 6 would mean 1_000_000 represents 1 token
? ? (get-decimals () (response uint uint))

? ? ;; the balance of the passed principal
? ? (get-balance (principal) (response uint uint))

? ? ;; the current total supply (which does not need to be a constant)
? ? (get-total-supply () (response uint uint))

? ? ;; an optional URI that represents metadata of this token
? ? (get-token-uri () (response (optional (string-utf8 256)) uint))
? )
)

在钱包内执行或者在其他应用程序里面执行

开发人员如果希望与易于交易的代币合约程序交互，首先提供或跟踪各种不同的易于交易的代币实现。在验证易于交易的代币合约程序时，他们应该获取该合约程序的接口和/或源代码。如果合约程序实现了这个特征，那么钱包就可以使用这个标准的合约接口进行转账和获取余额。

实现此特征的合约的下游消费者应该知道 get-name 和 get-symbol 函数不能保证是全局唯一的。因此，应告知消费者 get-name 和 get-token 只是提供更易读的体验的提示。应始终注意验证合约的标识符是否与客户端打算与之交互的代币的标识符相匹配。

此特征中的所有函数都返回response类型，这是 Clarity 中 trait 定义的要求。但是，其中一些函数应该是“fail-proof”，即它们永远不应该返回错误。这些“fail-proof”函数是那些被推荐为只读的函数。如果实现此特征的合约程序为这些函数返回错误，则可能表明合约程序有问题，这些合约程序的使用者应谨慎行事。

使用原生资产函数

尽管不可能在 Clarity 语言特征中进行授权，但合约程序执行人应该始终使用作为 Clarity 原来提供的已经内置的资产函数。这允许客户使用Post条件（如下所述），另外还可以使用其他的功能，例如 通过 stacks-blockchain-api函数对这些资产余额和转账提供原生的支持。此 SIP 中包含的参考实现使用原生的初始化函数，并为其使用提供了一个非常好的样板。

原生的资产函数包括：

* define-fungible-token

* ft-burn?

* ft-get-balance

* ft-get-supply

* ft-mint?

* ft-transfer?

Post条件的使用

除了易于交易的代币合约程序的内置方法外，Stacks区块链还包括一个称为post条件的功能。通过定义post条件，用户可以创建交易，其中包含有关该合约程序中可能发生的事情的预定义保证。

一个post条件可能是“我将转移100个 X 代币”，其中“X 代币”被称为特定合约程序的易于交易的代币。当钱包和应用程序实现 transfer 方法时，它们应该始终使用 post 条件，来指定用户将转移他们在 transfer 函数的 amount 参数中所指定的代币数量。只有在非常特殊的情况下，才不应包含这样的post条件。

相关资料

以太坊 ERC20协议

也许最古老、最著名的易于交易的代币标准是以太坊的 ERC20 标准。它已成为以太坊生态系统最强大的构建块之一。当所有易于交易的代币都遵循相同的标准时，任何钱包或应用程序开发人员都可以与其进行交互，而无需创建用于处理每个单独代币的自定义逻辑。

易于交易的代币变得如此流行，以至于 Clarity 智能合约语言内置了对基本易于交易的代币操作的支持。事实上，从本提案的参考实现中可以看出，实现易于交易的代币只需要很少的代码。该标准的重要部分是定义所有易于交易的代币都可以实现的 Clarity 特征。尽管 Clarity 内置了易于交易的代币操作，但每个合约程序都必须定义相同的方法，以便它们的合约易于集成。

激活

此特征已部署到主网：SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.sip-010-trait-ft-standard

当这个trait部署到主网上时，这个trait将被视为激活，并且该trait的3种不同实现已经部署到主网上，在比特币区块高度700000之前。

参考实现

与此提案一起提交了一个示例实现，以及一个 Javascript 客户端和测试。
https://github.com/hstove/stacks-fungible-token

下面是2个实现易于交易的代币的 Clarity合约程序的示例，尽管这2个示例不完全符合此规范标准：

@psq's trait and implementation

@friedger's 的一个易于交易的代币实现案例

注释：fungible token在这篇教学文档中被翻译成易于交易的代币，是为了普通用户更容易地理解，跟同质化代币、可替代代币是同一个意思。