【许晓笛】 EOS 智能合约案例解析(2)

时间 2019-11-16

标签许晓笛 eos 智能合约案例解析繁體版

原文原文链接

详解 EOS 智能合约的 cpp 文件

以前的文章介绍了 eosio.token 智能合约的 hpp 文件，此次向你们介绍 eosio.token.cpp 文件，cpp 文件即 C++ 代码文件，智能合约全部的业务逻辑内容都是在 cpp 文件中实现的。git

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

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

私有函数

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

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 函数用来建立一种新的代币，并设置这种新代币的各类参数。ui

//参数：发币帐户
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 应该是这个智能合约最经常使用的函数，就是将代币从一个帐户转到另外一个。this

//转出方帐户名
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 函数进行发币。code

//参数：代币接收方     代币数量和种类      备忘
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) )