eos合约案例导读

为了帮助大家熟悉 EOS 智能合约，EOS 官方提供了一个代币（资产）智能合约 Demo —— eosio.token。eosio.token 智能合约目前还不是特别完善，个别功能还没有完成。但这个示例合约给出了 EOS 官方智能合约开发的标准结构和开发方法，并且真正的 EOS 代币也会借鉴这个示例合约的逻辑，是 EOS 智能合约入门的经典案例。

照例，eosio.token 合约由三个文件（cpp，hpp，abi）文件组成，本篇文章将为大家讲解 eosio.token.hpp 文件。原文件地址：https://github.com/EOSIO/eos/tree/master/contracts/eosio.token

预处理指令 & 头文件
代码的开头声明了头文件，主要是 eos 智能合约的 API 库。

//预处理指令，防止文件被重复包含

pragma once

//eos 资产（asset）头文件

include <eosiolib/asset.hpp>

//eos 智能合约 API 库

include <eosiolib/eosio.hpp>

构造函数
智能合约的类名可以与智能合约名不同，智能合约的名字是其账户名。构造函数为空，参数为智能合约账户名。

//每个智能合约类都要继承 contract 类
class token : public contract {
public:
//类构造函数
token( account_name self ):contract(self){}

创建代币函数(action)
声明 create 函数，这个函数用来新建一种代币，并输入代币的各种属性，同时 create 函数也是一个 action。action 是 eos 智能合约的接口函数，定义外界可以对智能合约做什么动作。

                  //参数：发币者
     void create( account_name issuer,
                  //资产最大数目
                  asset        maximum_supply,
                  //资产是否可以冻结
                  uint8_t      issuer_can_freeze,
                  //资产是否可以召回
                  uint8_t      issuer_can_recall,
                  //资产是否可以设置白名单
                  uint8_t      issuer_can_whitelist );

增发代币函数(action)
声明 issue 函数，这个函数用来增发代币，eosio.token 合约并不是新建了代币就会得到代币，新建的代币只是存储了资料，发币者要想获取代币，需要调用 issue action 来获得代币。

     //参数：接收新代币账户，新增多少代币，memo
     void issue( account_name to, asset quantity, string memo );

1
2
转账函数(action)
声明 transfer 函数，这个函数用来转账，是代币智能合约最常用的函数。

                    //发送账户
     void transfer( account_name from,
                    //接收账户
                    account_name to,
                    //代币数量
                    asset        quantity,
                    //memo
                    string       memo );

私有数据结构
智能合约需要存储每种代币的资料，还要存储每个账户持有每种代币的数量。

  private:
     //account 结构体，单个记录账户存储单个代币的情况
     struct account {
        //资产余额
        asset    balance;
        //账户是否冻结
        bool     frozen    = false;
        //账户是否在白名单
        bool     whitelist = true;
        //设置账户主键为代币名称
        uint64_t primary_key()const { return balance.symbol.name(); }
     };
     //currency_stats 结构体，记录当代币状态信息
     struct currency_stats {
        //流通量
        asset          supply;
        //最大可流通量
        asset          max_supply;
        //发币者
        account_name   issuer;
        //是否可以冻结
        bool           can_freeze         = true;
        //是否可以召回
        bool           can_recall         = true;
        //是否可以设置白名单
        bool           can_whitelist      = true;
        //是否已经冻结
        bool           is_frozen          = false;
        //是否已经设置白名单
        bool           enforce_whitelist  = false;
        //设置主键为代币名称
        uint64_t primary_key()const { return supply.symbol.name(); }
     };
     //设置一个multi_index类型，存储 account 结构体
     typedef eosio::multi_index<N(accounts), account> accounts;
     //设置一个multi_index类型，存储 currency_stats 结构体
     typedef eosio::multi_index<N(stat), currency_stats> stats;

私有函数
合约公有两个私有函数，分别是给账户增加某种资产，和给账户减少某种资产。

     //增加资产函数：账户，增加数量，代币状态结构体
     void sub_balance( account_name owner, asset value, const currency_stats& st );
     //减少资产函数:账户，减少数量   ，代币状态结构体
     void add_balance( account_name owner, asset value, const currency_stats& st,
                       //ram 资源支付者
                       account_name ram_payer );

之前的文章介绍了 eosio.token 智能合约的 hpp 文件，这次向大家介绍 eosio.token.cpp 文件，cpp 文件即 C++ 代码文件，智能合约所有的业务逻辑内容都是在 cpp 文件中实现的。

eosio.token.cpp 文件地址： https://github.com/EOSIO/eos/blob/master/contracts/eosio.token/eosio.token.cpp

了解 C/C++ 开发的同学肯定熟悉，cpp 文件的主要使命是实现 hpp 文件中声明的函数（方法），包括公有函数（EOS 里也叫 action）和私有函数。hpp 里挖的坑，cpp 要一个不留地实现。

私有函数
照惯例，私有函数都是工具函数，供类内部的其他函数调用。

sub_balance（减资产）函数
作用：从指定账户中减去资产
参数：被操作账户，资产数，资产状态

// 参数：被操作账户 资产种类与数量 资产状态结构体
void token::sub_balance( account_name owner, asset value, const currency_stats& st ) {
//建立一个 multi_index，用来操作数据库
//这里的参数 _self 表示数据的拥有者为智能合约本身，参数 owner 表示储存在名为被操作账户的表中
//这样并不是直接建立了一个新表，而是让 C++ 程序与数据库对应的表之间建立了数据传输的通道
accounts from_acnts( _self, owner );

//在数据表中查询要减少的代币结构体，就是 hpp 文件中定义的 account 结构体
const auto& from = from_acnts.get( value.symbol.name() );
//校验，要减少的代币数量应该小于目前拥有的代币数量，否则会报错。
eosio_assert( from.balance.amount >= value.amount, "overdrawn balance" );

//判断是否有被操作账户的授权
if( has_auth( owner ) ) {
//校验，账户是否被冻结
eosio_assert( !st.can_freeze || !from.frozen, "account is frozen by issuer" );
//校验，这种代币是否被冻结
eosio_assert( !st.can_freeze || !st.is_frozen, "all transfers are frozen by issuer" );
//校验，账户是否在白名单中
eosio_assert( !st.enforce_whitelist || from.whitelist, "account is not white listed" );
//如果没有被操作账户的授权，检查是否有发币者的授权
} else if( has_auth( st.issuer ) ) {
//如果有发币者的授权，那么肯定是在召回代币，查看代币是否可以召回
eosio_assert( st.can_recall, "issuer may not recall token" );
} else {
//如果两种授权都没有，则失败，没有足够的权限
eosio_assert( false, "insufficient authority" );
}
//通过 Lambda 表达式（匿名函数）修改将代币结构体
from_acnts.modify( from, owner, [&]( auto& a ) {
//匿名函数 函数体
a.balance -= value;
});
}

add_balance（增加资产）函数
作用：从指定账户中增加资产
参数：被操作账户，资产数，资产状态，存储资源支付账户

// 参数：被操作账户 代币数量 代币状态结构体 储存支付账户
void token::add_balance( account_name owner, asset value, const currency_stats& st, account_name ram_payer )
{
//建立一个 multi_index，用来操作数据库
accounts to_acnts( _self, owner );
//在数据表中查询要增加的代币结构体
auto to = to_acnts.find( value.symbol.name() );
//如果 to == to_acnts.end()，说明查找到数据表的末尾都没有对应的结构体，说明该账户没有该代币
if( to == to_acnts.end() ) {
//校验，该代币是否开启了白名单功能
eosio_assert( !st.enforce_whitelist, "can only transfer to white listed accounts" );
//使用 emplace 方法，在数据表中增加一项
to_acnts.emplace( ram_payer, [&]( auto& a ){
//匿名函数体，代币数量等于每次转入的数量，因为之前没有
a.balance = value;
});
//如果数据表中已经存在此项，只需增加代币数量
} else {
//检查账户是否在白名单中
eosio_assert( !st.enforce_whitelist || to->whitelist, "receiver requires whitelist by issuer" );
//使用 modify 方法，修改项目
to_acnts.modify( to, 0, [&]( auto& a ) {
//直接修改代币数量
a.balance += value;
});
}
}

公有函数
EOS 合约中的公有函数大多是供别的账户调用的 Action，根据 hpp 文件，我们需要实现 create、issue、transfer 三个公有函数（action）。

create（新建代币）函数
create 函数用来创建一种新的代币，并设置这种新代币的各种参数。

                //参数：发币账户

void token::create( account_name issuer,
//最大发行量
asset maximum_supply,
//发币者是否可以冻结代币
uint8_t issuer_can_freeze,
//发币者是否可以召回代币
uint8_t issuer_can_recall,
//是否可以设置白名单
uint8_t issuer_can_whitelist )
{
//需要 eosio.token 账户本身的授权
require_auth( _self );

auto sym = maximum_supply.symbol;
//校验，新代币名称是否有效
eosio_assert( sym.is_valid(), "invalid symbol name" );
//校验，最大发行量是否有效
eosio_assert( maximum_supply.is_valid(), "invalid supply");
//校验，最大发行量是否大于零
eosio_assert( maximum_supply.amount > 0, "max-supply must be positive");

//建立一个 milti_index 数据表，用来与数据库交互
stats statstable( _self, sym.name() );
//在表中搜索相同名称的代币
auto existing = statstable.find( sym.name() );
//校验，是否已经存在相同名称的代币
eosio_assert( existing == statstable.end(), "token with symbol already exists" );

//使用 emplace 方法，在数据表中增加一项
statstable.emplace( _self, [&]( auto& s ) {
   // 使用匿名函数，将传入的参数赋值给 currency_stats 结构体
   s.supply.symbol = maximum_supply.symbol;
   s.max_supply    = maximum_supply;
   s.issuer        = issuer;
   s.can_freeze    = issuer_can_freeze;
   s.can_recall    = issuer_can_recall;
   s.can_whitelist = issuer_can_whitelist;
});

}

transfer（转账）函数
transfer 应该是这个智能合约最常用的函数，就是将代币从一个账户转到另一个。

                //转出方账户名

void token::transfer( account_name from,
//转入方账户名
account_name to,
//代币种类与数量
asset quantity,
//转账备忘（目前还没实现）
string /memo/ )
{
//打印转账提示
print( "transfer" );
//检查转出方权限
require_auth( from );
//得到代币名称
auto sym = quantity.symbol.name();

//建立一个 milti_index 数据表，用来与数据库交互
stats statstable( _self, sym );
//在数据表中寻找代币的 currency_stats 结构体
const auto& st = statstable.get( sym );

//向转出方获取回执
require_recipient( from );
//向转入方获取回执
require_recipient( to );

//校验，转出的代币是否有效
eosio_assert( quantity.is_valid(), "invalid quantity" );
//校验，转账数量要大于0
eosio_assert( quantity.amount > 0, "must transfer positive quantity" );

//调用 sub_balance 私有方法
sub_balance( from, quantity, st );
//调用 add_balance 私有方法
add_balance( to, quantity, st, from );

}

issue（发币）函数
上面的 create 函数创建代币后只是给定了参数，并没有真正的代币被创建出来，需要 issue 函数进行发币。

            //参数：代币接收方     代币数量和种类      备忘

void token::issue( account_name to, asset quantity, string memo )
{
//打印提示
print( "issue" );
//获取代币名称
auto sym = quantity.symbol.name();
//建立一个 milti_index 数据表，用来与数据库交互
stats statstable( _self, sym );
//在数据表中搜索代币 currency_stats 结构体
const auto& st = statstable.get( sym );

//检查发币者授权
require_auth( st.issuer );
//检查资产是否有效
eosio_assert( quantity.is_valid(), "invalid quantity" );
//检查资产是否大于零
eosio_assert( quantity.amount > 0, "must issue positive quantity" );
//检查创造的总资产是否大于最大代币数
eosio_assert( quantity <= st.max_supply - st.supply, "quantity exceeds available supply");

//更新资产创造数量记录
statstable.modify( st, 0, [&]( auto& s ) {
   s.supply += quantity;
});

//给发布者增加资产
add_balance( st.issuer, quantity, st, st.issuer );

//判断代币接受方是否是发币者
if( to != st.issuer )
{
    //这里使用了一个特殊处理，先给发币者增加相应的代币，再调用 transfer 函数转账给代币接受方。
    //这样做的目的是让代币接受方收到通知
   SEND_INLINE_ACTION( *this, transfer, {st.issuer,N(active)}, {st.issuer, to, quantity, memo} );
}

}

设置 action
大家知道 EOS 系统的智能合约是以 action 为基本动作单位的，我们要将需要声明为 action 的函数告知 EOS 系统，通过以下宏即可实现。

//将 create issue transfer 三个共有函数声明为 action，供其他账户调用。
EOSIO_ABI( eosio::token, (create)(issue)(transfer) )
1
2
End ————————————————————————————————
圆方圆学院汇集大批区块链名师，打造精品的区块链技术课程。
许晓笛老师的CSDN学院视频专栏 https://edu.csdn.net/lecturer/2008
郭金宏老师的csdn学院视频专栏：https://edu.csdn.net/lecturer/2214