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, & {
//匿名函数 函数体
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, &{
//匿名函数体，代币数量等于每次转入的数量，由于以前没有
a.balance = value;
});
//若是数据表中已经存在此项，只需增长代币数量
} else {
//检查帐户是否在白名单中
eosio_assert( !st.enforce_whitelist || to->whitelist, "receiver requires whitelist by issuer" );
//使用 modify 方法，修改项目
to_acnts.modify( to, 0, & {
//直接修改代币数量
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