EOS智能合约开发（一）

一、 智能合约功能

EOSIO智能合约是在区块链上注册并在EOSIO节点上执行的软件，实现了“合约”的功能，合约行动请求帐目存储在区块链中。智能合约定义了接口（操作，参数，数据结构）和实现接口的代码。代码被编译成规范的字节码格式，使节点可以检索和执行。区块链存储合约的交易（例如，合法转移，游戏移动）。每份智能合约都必须附有一份李嘉图合约，其中定义了具有法律约束力的条款和条件。

二、 通讯模式

2.1 运行机制

EOSIO智能合约由一组操作和类型定义组成。操作定义指定并实现合约的行为，类型定义指定所需的内容和结构。 操作主要在基于消息的通信体系结构中运行：客户端通过向nodeos发送（推送）消息来调用操作。可以使用cleos命令完成。它也可以使用EOSIO发送方法（例如，eosio :: action :: send）来完成。 nodeos将操作请求分派给实现合约的WASM代码，该代码运行完之后继续处理下一个操作。
EOSIO智能合约可以彼此通信，例如，让另一个合约执行与当前交易的完成相关的某些操作，或者触发当前交易范围之外的未来交易。
EOSIO支持两种基本通信模型，内联和延迟。在当前交易中执行的操作是内联操作的示例，而触发的将来交易是延迟操作的示例。
合约之间的沟通应视为异步发生，异步通信模型可能导致垃圾邮件，资源限制算法将解析垃圾邮件。

2.2 内联通信

内联通信采用请求其他操作的形式，需要作为调用操作的一部分执行。其使用和原始交易的相同作用域和权限进行操作，并保证使用当前交易执行，即调用交易中的嵌套交易。 如果交易的任何部分失败，则内联操作将与交易的其余部分一起展开。无论成功与否，调用内联操作都不会在交易范围之外生成任何通知。

2.3 延迟通信

延迟通信在采用发送到对等交易的动作通知的形式。 根据生产者的判断，延迟的操作最多可以安排在稍后的时间运行，无法保证将执行延期操作。从始发交易的角度来看，即创建延迟交易的交易，它只能确定创建请求是否成功提交或者是否失败（如果失败，它将立即失败）。 延期交易具有发送合约的权限，交易可以取消延期交易。

2.4 交易和动作

动作表示单个操作，而交易是一个或多个动作的集合。 合约和帐户以行动的形式进行沟通。 如果要将操作作为一个整体执行，则可以单独发送操作，也可以以组合形式发送操作。
交易中可以有一个动作也可以有多个 ，当有多个操作时，其中一个操作失败，则这个交易失败。

2.5 交易确认

交易完成后，将生成交易收据，此收据采用散列形式。 接收交易散列并不意味着交易已被确认，它只意味着节点接受它而没有错误，这也意味着其他生产者很可能会接受它。通过确认，在交易历史记录中可以看到包含它的块编号的交易。

2.6 动作处理程序和动作的apply上下文

智能合约提供动作处理程序来执行所请求操作的工作。每次动作运行时，通过在合约实现中运行apply方法“应用”操作，EOSIO会创建一个新的动作“应用”上下文，动作在该上下文中运行。 下图说明了apply上下文动作的关键元素：

EOSIO网络中的每个节点都会获得每个合约中的每个动作的副本并运行。一些节点正在执行合约的实际工作，而其他节点正在处理以证明交易块的有效性。因此，重要的是合约能够确定“他们是谁”，或者基本上，他们在哪个环境下运行。在动作上下文中提供上下文标识信息，如上图中 的receiver, code, action。 receiver是当前正在处理该操作的帐户。code 是授权合约的帐户。 action是当前正在运行的操作的ID。
动作在交易中运作;如果交易失败，则必须回滚所有操作的结果。动作上下文的关键部分是当前交易数据，这包含交易头、交易中所有原始操作的有序向量、交易中上下文自由操作的向量，由code定义的可修复的上下文无关数据集（作为blob的向量提供）实现合约，以及blob向量的完整索引。
在处理动作之前，EOSIO会为动作设置一个干净的工作内存。操作的工作内存仅对该操作可用，即使对于同一交易中的操作也是如此。在执行另一个操作时可能已设置的变量在另一个操作的上下文中不可用。在动作之间传递状态的唯一方法是将其持久化并从EOSIO数据库中检索它。动作可能有许多影响， 其中包括：更改状态在EOSIO持久存储中保持不变；通知当前交易的收件人；将内联操作请求发送给新接收方；生成新的（延期）交易；取消现有的延期交易。

2.7 交易限制

每个交易必须在30ms或更短时间内执行。 如果交易包含多个操作，并且这些操作的总和大于30毫秒，则整个交易将失败。 在没有对其操作进行并发性要求的情况下，可以通过在单独的交易中包含CPU消费动作来规避这种情况。

三、文件结构

3.1 创建框架

$ eosiocpp -n ${contract}

以上将在./$ {conttract}目录中创建一个带有两个文件：

${contract}.hpp ${contract}.cpp

3.2 apply处理程序

每个智能合约都必须提供应用操作处理程序。 apply动作处理程序是一个侦听所有传入操作并执行所需行为的函数。 为了响应特定操作，code识别和响应特定操作请求。 apply使用receiver、code、action输入参数作为过滤器，来映射到实现特定操作的所需功能。 apply函数可以使用以下方法过滤code参数：

if (code == N(${contract_name}) {
   //对特定动作的处理
}

在给定code之后，可以使用如下方法过滤action参数：

if (action == N(${action_name}) {
    //your handler to respond to a particular action
}

3.3 EOSIO_ABI 宏

EOSIO_ABI宏封装了apply函数的基本动作：

#define EOSIO_ABI( TYPE, MEMBERS ) \
extern "C" { \
   void apply( uint64_t receiver, uint64_t code, uint64_t action ) { \
      auto self = receiver; \
      if( code == self ) { \
         TYPE thiscontract( self ); \
         switch( action ) { \
            EOSIO_API( TYPE, MEMBERS ) \
         } \
         /* does not allow destructor of thiscontract to run: eosio_exit(0); */ \
      } \
   } \
} \

只需要在宏中指定合约中的code和action名称即可，所有底层C代码映射逻辑都由宏生成。 如EOSIO_ABI（hello，（hi））中，hello和hi是来自合约的值。
apply函数记录所交付的行为，不做任何其他检查。 如果块生产者允许，任何人都可以随时提供任何操作。 如果没有任何必要的签名，合约将按消耗的带宽计费。
（1）apply:动作处理程序，它监听所有传入的动作并根据函数中的规范做出反应。 需要两个输入参数code和action。
（2）code filter：

if (code == N(${contract_name}) {
    // your handler to respond to particular action
}

（3）action filter：

if (action == N(${action_name}) {
    //your handler to respond to a particular action
}

（4）wast：部署到区块链的程序必须是wast格式，编译方法如下：

$ eosiocpp -o ${contract}.wast ${contract}.cpp

（5）abi:应用程序二进制接口（ABI）是一个JSON，在JSON和二进制之间转换用户操作。 abi还描述了如何将数据库状态转换为JSON或从JSON转换。 通过abi描述合约后，开发人员和用户将能够通过JSON无缝地与所开发的合约进行交互。可以如下编译产生：

$ eosiocpp -g ${contract}.abi ${contract}.hpp

ABI的一个例子：

{
//定义现有类型的别名列表,在这里，将name定义为account_name的别名。
  "types": [{
      "new_type_name": "account_name",
      "type": "name"
    }
  ],
  "structs": [{
  //在此处定义了transfer类型
      "name": "transfer",
      "base": "",
  //from、to、quantity与"types"相对应
      "fields": {
        "from": "account_name",
        "to": "account_name",
        "quantity": "uint64"
      }
    },{
      "name": "account",
      "base": "",
      "fields": {
        "account": "name",
        "balance": "uint64"
      }
    }
  ],
  //在此定义了action:transfer,类型为transfer。告诉EOSIO遇到${account}->transfer时应该载入trransfer类
  "actions": [{
      "action": "transfer",
      "type": "transfer"
    }
  ],
  "tables": [{
      "table": "account",
      "type": "account",
      "index_type": "i64",
      "key_names" : ["account"],
      "key_types" : ["name"]
    }
  ]
}

四、多索引数据库API

EOSIO提供了一组服务和接口，使合约开发人员能够跨行动保持状态，从而保持事务边界。 如果没有持久性，当处理超出范围时，在处理操作和事务期间生成的状态将丢失。
对持久性服务的需求
acttion执行EOSIO合同的工作。 action在上下文的环境中运行。 如action apply上下文关系图中所示，操作上下文提供了执行操作所需的一些操作。 在处理操作之前，EOSIO会为操作设置一个干净的工作内存。 在操作之间传递状态的唯一方法是将其持久化并从EOSIO数据库中检索它。
持久性组件包括：
1）在数据库中保持状态的服务
2）增强查询功能以查找和检索数据库内容
3）服务的C ++ API，供合约开发人员使用
4）用于访问核心服务的C API，对库和系统开发人员有用

4.1 EOSIO多索引API

eosio :: multi_index对应传统数据库中的表，其中行是容器中的单个对象，列是容器中对象的成员属性，索引提供了对象的快速查找。 key与对象成员属性兼容。
传统的数据库表允许索引是表中某些列的用户定义函数。 eosio :: multi_index类似地允许索引是任何用户定义的函数（作为元素类型的类/结构的成员函数提供），但其返回值仅限于一组受限的支持键类型。
统的数据库表通常只有一个允许的唯一主键明确标识表中的特定行，并提供表中行的标准排序顺序。 eosio :: multi_index支持类似的语义，但eosio :: multi_index容器中对象的主键必须是唯一的无符号64位整数。 eosio :: multi_index容器中的对象按主键索引按无符号64位整数主键的升序排序。

4.2 EOSIO多索引迭代器

EOSIO持久性服务提供多索引迭代器。 与仅提供键值存储的其他区块链不同，EOSIO多索引表允许合同开发者保留按各种不同键类型排序的对象集合，这些键类型可以从对象内的数据派生。 这实现了丰富的检索功能。 最多可以定义16个二级索引，每个索引都有自己的排序和检索表内容的方式。
EOSIO多索引迭代器遵循C ++迭代器通用的模式。 所有迭代器都是双向const，const_iterator或const_reverse_iterator。 可以取消引用迭代器以提供对多索引表中对象的访问。

4.3 创建多索引表

以下是使用EOSIO Multi-Index表创建自己的持久数据的步骤：
1）使用C ++类或结构体定义对象。每个对象都在其自己的多索引表中。
2）在名为primary_key的类/结构中定义一个const成员函数，该函数返回对象的uint64_t主键值。
3）确定二级指数。最多支持16个附加索引。二级指数支持几种密钥类型：
idx64 - 原始64位无符号整数键
idx128 - 原始128位无符号整数键，或128位固定大小的词典键
idx256 - 256位固定大小的词典键
idx_double - 双精度浮点键
idx_long_double - 四倍精度浮点键
为每个二级索引定义一个密钥提取器。密钥提取器是用于从多索引表的元素获取密钥的函数。

4.4 创建多索引表

（1）实例化多索引表

#include 
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
     EOSLIB_SERIALIZE( address, (account_name)(first_name)(last_name)(street)(city)(state) )
  };
  public:
    addressbook(account_name self):contract(self) {}
    typedef eosio::multi_index< N(address), address > address_index;
    void myaction() {
      address_index addresses(_self, _self); // code, scope
    }
}
EOSIO_ABI( addressbook, (myaction) )

（2）插入操作：

#include 
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
     EOSLIB_SERIALIZE( address, (account_name)(first_name)(last_name)(street)(city)(state) )
  };
  public:
    addressbook(account_name self):contract(self) {}
    typedef eosio::multi_index< N(address), address > address_index;
    void myaction() {
      address_index addresses(_self, _self); // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(_self, [&](auto& address) {
        address.account_name = N(dan);
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
    }
}
EOSIO_ABI( addressbook, (myaction) )

（2）修改：

#include 
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
     EOSLIB_SERIALIZE( address, (account_name)(first_name)(last_name)(street)(city)(state) )
  };
  public:
    addressbook(account_name self):contract(self) {}
    typedef eosio::multi_index< N(address), address > address_index;
    void myaction() {
      address_index addresses(_self, _self); // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(_self, [&](auto& address) {
        address.account_name = N(dan);
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
      auto itr = addresses.find(N(dan));
      eosio_assert(itr != addresses.end(), "Address for account not found");
      addresses.modify( itr, account payer, [&]( auto& address ) {
        address.city = "San Luis Obispo";
        address.state = "CA";
      });
    }
}
EOSIO_ABI( addressbook, (myaction) )

（3）删除

#include 
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
     EOSLIB_SERIALIZE( address, (account_name)(first_name)(last_name)(street)(city)(state) )
  };
  public:
    addressbook(account_name self):contract(self) {}
    typedef eosio::multi_index< N(address), address > address_index;
    void myaction() {
      address_index addresses(_self, _self); // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(_self, [&](auto& address) {
        address.account_name = N(dan);
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
      auto itr = addresses.find(N(dan));
      eosio_assert(itr != addresses.end(), "Address for account not found");
      addresses.erase( itr );
      eosio_assert(itr != addresses.end(), "Address not erased properly");
    }
}
EOSIO_ABI( addressbook, (myaction) )

（5）get
使用主键查找，返回对包含指定主键的对象的常量引用。

#include 
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
     EOSLIB_SERIALIZE( address, (account_name)(first_name)(last_name)(street)(city)(state) )
  };
  public:
    addressbook(account_name self):contract(self) {}
    typedef eosio::multi_index< N(address), address > address_index;
    void myaction() {
      address_index addresses(_self, _self); // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(_self, [&](auto& address) {
        address.account_name = N(dan);
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
      auto user = addresses.get(N(dan));
      eosio_assert(user.first_name == "Daniel", "Couldn't get him.");
    }
}
EOSIO_ABI( addressbook, (myaction) )

（6）find
使用主键在表中搜索现有对象。如果找不到具有主键primary的对象，则找到的对象的迭代器，其主键等于主键或引用表的结束迭代器。

#include 
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
     EOSLIB_SERIALIZE( address, (account_name)(first_name)(last_name)(street)(city)(state) )
  };
  public:
    addressbook(account_name self):contract(self) {}
    typedef eosio::multi_index< N(address), address > address_index;
    void myaction() {
      address_index addresses(_self, _self); // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(_self, [&](auto& address) {
        address.account_name = N(dan);
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
      auto itr = addresses.find(N(dan));
      eosio_assert(itr != addresses.end(), "Couldn't get him.");
    }
}
EOSIO_ABI( addressbook, (myaction) )