7. 使用C++进行智能合约开发

读者对象：本章节主要描述使用C++进行ChainMaker合约编写的方法，主要面向于使用C++进行ChainMaker的合约开发的开发者。

概览 1、运行时虚拟机类型（runtime_type）：WXVM 2、介绍了环境依赖 3、介绍了开发方式及sdk接口

7.1. 环境依赖

操作系统

目前仅支持Linux和MAC系统。

软件依赖

软件依赖表如下：

名称	版本	描述	是否必须
GCC	7.3+	C编译器	是

依赖软件安装：

Mac：brew install gcc

Linux:

yum install gcc —— Ubuntu/Debian安装命令。
apt-get install gcc —— CentOS/Redhat安装命令。

长安链环境准备

准备一条支持WXVM的长安链，以及长安链CMC工具，用于将写编写好的合约，部署到链上进行测试。相关安装教程请详见：

7.2. 编写C++智能合约

7.2.1. 搭建开发环境

开发者可根据ChainMaker提供的SDK开发C++合约，C++合约的SDK工程下载地址为：chainmaker-contract-sdk-cpp。

SDK下载完成后，开发者可根据自身习惯选择熟悉的C++编辑器或IDE。推荐使用CLion，CLion下载和安装请参见官网：https://www.jetbrains.com/clion/。

安装完成后，使用CLion打开SDK工程，通过编辑main.cc文件即可编辑自己的C++合约。

7.2.2. 代码编写规则

外部方法声明

只有声明为外部方法的函数，才可以（被用户或其他合约）从外部调用，否则，只能用于合约内部调用。外部方法声明规则如下：

WASM_EXPORT：必须，暴露声明
void：必须，无返回值
method_name()：必须，暴露方法名称

// 示例
WASM_EXPORT void init_contract() {
    
}

强制声明外部方法

强制声明外部方法为合约必须提供且必须对外暴露的方法，有以下两个：

init_contract：创建合约会自动执行该方法，无需指定方法名。
upgrade：升级合约会自动执行该方法，无需指定方法名。

// 在创建本合约时, 调用一次init方法. ChainMaker不允许用户直接调用该方法.
WASM_EXPORT void init_contract() {
    // 安装时的业务逻辑，可为空
    
}

// 在升级本合约时, 对于每一个升级的版本调用一次upgrade方法. ChainMaker不允许用户直接调用该方法.
WASM_EXPORT void upgrade() {
    // 升级时的业务逻辑，可为空
    
}

获取SDK 接口上下文

C++合约通过SDK接口上下文与链进行交互，具体信息可参考文章末尾[C++ SDK API描述](C++ SDK API描述)。

//获取SDK接口上下文
Context* ctx = context();

7.2.3. 合约示例源码展示

下文代码框内为一个C++编写的存证合约示例，该合约示例实现以下功能：

1、存储文件哈希、文件名称和该交易的ID；

2、通过文件哈希查询该条记录。

#include "chainmaker/chainmaker.h"

using namespace chainmaker;

class Counter : public Contract {
public:
    void init_contract() {}
    void upgrade() {}
    // 保存
    void save() {
        // 获取SDK 接口上下文
        Context* ctx = context();
        // 定义变量
        std::string time;
        std::string file_hash;
        std::string file_name;
        std::string tx_id;
		// 获取参数
        ctx->arg("time", time);
        ctx->arg("file_hash", file_hash);
        ctx->arg("file_name", file_name);
        ctx->arg("tx_id", tx_id);
        // 发送合约事件
        // 向topic:"topic_vx"发送2个event数据，file_hash,file_name
        ctx->emit_event("topic_vx",2,file_hash.c_str(),file_name.c_str());
		// 存储数据
        ctx->put_object("fact"+ file_hash,  tx_id+" "+time+" "+file_hash+" "+file_name);
        // 记录日志
        ctx->log("call save() result:" + tx_id+" "+time+" "+file_hash+" "+file_name);
        // 返回结果
        ctx->success(tx_id+" "+time+" "+file_hash+" "+file_name);
    }

    // 查询
    void find_by_file_hash() {
        // 获取SDK 接口上下文
    	Context* ctx = context();

		// 获取参数
        std::string file_hash;
        ctx->arg("file_hash", file_hash);
		
        // 查询数据
    	std::string value;
        ctx->get_object("fact"+ file_hash, &value);
        // 记录日志
        ctx->log("call find_by_file_hash()-" + file_hash + ",result:" + value);
        // 返回结果
        ctx->success(value);
    }

};

// 在创建本合约时, 调用一次init方法. ChainMaker不允许用户直接调用该方法.
WASM_EXPORT void init_contract() {
    Counter counter;
    counter.init_contract();
}

// 在升级本合约时, 对于每一个升级的版本调用一次upgrade方法. ChainMaker不允许用户直接调用该方法.
WASM_EXPORT void upgrade() {
    Counter counter;
    counter.upgrade();
}

WASM_EXPORT void save() {
    Counter counter;
    counter.save();
}

WASM_EXPORT void find_by_file_hash() {
    Counter counter;
    counter.find_by_file_hash();
}

7.2.4. 编译合约

7.2.4.1. 搭建编译环境

开发者可使用ChainMaker已经打包好的Docker镜像编译C++合约代码，ChainMaker官方已经将容器发布至 docker hub。

拉取镜像

请使用以下命令拉取用于编译C++合约的镜像。

docker pull chainmakerofficial/chainmaker-cpp-contract:2.1.0

启动镜像

启动镜像前，需要指定本地开发目录，用于映射为docker镜像的home目录。用于映射的本地开发目录一般为SDK工程目录，例如/data/workspace/chainmaker-contract-sdk-cpp，这样编辑开发的C++合约就可以在docker容器内的home目录直接编译了。

# 启动并进入容器，$WORK_DIR即本地工作目录
docker run -it --name chainmaker-cpp-contract -v $WORK_DIR:/home chainmakerofficial/chainmaker-cpp-contract:2.1.0 bash
# 或者先后台启动
docker run -d --name chainmaker-cpp-contract -v $WORK_DIR:/home chainmakerofficial/chainmaker-cpp-contract:2.1.0 bash -c "while true; do echo hello world; sleep 5;done"
# 再进入容器
docker exec -it chainmaker-cpp-contract bash

7.2.4.2. 编译示例合约

进入编译容器后，切换到home目录，这个home目录对应启动编译容器时映射的本地开发目录，进入后执行以下命令。

cd /home/
make clean
emmake make

编译完成后，将生成合约的字节码文件main.wasm

/home/main.wasm

7.2.4.3. SDK工程框架描述

chainmaker-contract-sdk-cpp工程的结构和文件描述如下：

chainmaker
- basic_iterator.cc：迭代器实现
- basic_iterator.h：迭代器头文件声明
- chainmaker.h： sdk主要接口头文件声明，详情见SDK API描述
- context_impl.cc：与链交互接口实现
- context_impl.h：与链交互头文件声明
- contract.cc：合约基础工具类
- error.h：异常处理类
- exports.js：编译合约导出函数
- safemath.h： assert异常处理
- syscall.cc：与链交互入口
- syscall.h：与链交互头文件声明
pb
- contract.pb.cc：与链交互数据协议
- contract.pb.h：与链交互数据协议头文件声明
main.cc：用户写合约入口
Makefile：常用build命令

7.2.4.4. 编译说明

在ChainMaker提供的Docker容器中中集成了编译器，可以对合约进行编译，集成的编译器是emcc 1.38.48版本，protobuf 使用3.7.1版本。用户如果手工编译需要先使用emcc 编译 protobuf ，编译之后执行emmake make即可。

7.2.4.5. 模拟运行示例合约

通过本地模拟环境运行合约(首次编译运行合约可能需要10秒左右，下面以存证作为示例)

# wxvm main.wasm save time 20210304 file_hash 12345678 file_name a.txt

2021-03-25 09:10:36.441      [DEBUG] [Vm]    xvm/context_service.go:257      wxvm log >>[1234567890123456789012345678901234567890123456789012345678901234] [1] call save() tx_id:
2021-03-25 09:10:36.463 [DEBUG] [Vm]    xvm/context_service.go:257      wxvm log >>[1234567890123456789012345678901234567890123456789012345678901234] [1] call save() file_hash:12345678
2021-03-25 09:10:36.464 [DEBUG] [Vm]    xvm/context_service.go:257      wxvm log >>[1234567890123456789012345678901234567890123456789012345678901234] [1] call save() file_name:a.txt
2021-03-25 09:10:36.465 [DEBUG] [Vm]    xvm/context_service.go:257      wxvm log >>[1234567890123456789012345678901234567890123456789012345678901234] [1] put success: a.txt 12345678
2021-03-25 09:10:36.466 [DEBUG] [Vm]    xvm/context_service.go:257      wxvm log >>[1234567890123456789012345678901234567890123456789012345678901234] [1] save====================================end
2021-03-25 09:10:36.467 [DEBUG] [Vm]    xvm/context_service.go:257      wxvm log >>[1234567890123456789012345678901234567890123456789012345678901234] [1] 
2021-03-25 09:10:36.467 [DEBUG] [Vm]    xvm/context_service.go:257      wxvm log >>[1234567890123456789012345678901234567890123456789012345678901234] [1] result:  a.txt 12345678
2021-03-25 09:10:36.469 [INFO]  [Vm] @chain01   main/main.go:31 contractResult :result:" a.txt 12345678"

7.2.5. 部署调用合约

编译完成后，将得到一个.wasm格式的合约文件，可将之部署到指定到长安链上，完成合约部署。部署合约的使用教程可详见：部署示例合约。

7.3. C++ SDK API描述

arg

// 该接口可返回属性名为 “name” 的参数的属性值。
// @param name: 要获取值的参数名称
// @param value: 获取的参数值
// @return: 是否成功
bool arg(const std::string& name, std::string& value){}

需要注意的是通过arg接口返回的参数，全都都是字符串，合约开发者有必要将其他数据类型的参数与字符串做转换，包括atoi、itoa、自定义序列化方式等。

get_object

// 获取key为"key"的值
// @param key: 获取对象的key
// @param value: 获取的对象值
// @return: 是否成功
bool get_object(const std::string& key, std::string* value){}

put_object

// 存储key为"key"的值
// @param key: 存储的对象key，注意key长度不允许超过64，且只允许大小写字母、数字、下划线、减号、小数点符号
// @param value: 存储的对象值install
// @return: 是否成功
bool put_object(const std::string& key, const std::string& value){}

delete_object

// 删除key为"key"的值
// @param key: 删除的对象key
// @return: 是否成功
bool delete_object(const std::string& key) {}

emit_event

// 发送合约事件
// @param topic: 合约事件主题
// @data_amount: 合约事件数据数量(data)，data_amount的值必须要和data数量一致，最多不可大于16，最少不可小于1,不可为空
// @data ...: 可变参数合约事件数据，数量与data_amount一致。
bool emit_event(const std::string &topic, int data_amount, const std::string data, ...)

success

// 返回成功的结果
// @param body: 成功信息
void success(const std::string& body) {}

error

// 返回失败结果
// @param body: 失败信息
void error(const std::string& body) {}

call

// 跨合约调用
// @param contract: 合约名称
// @param method: 合约方法
// @param args: 调用合约的参数
// @param resp: 调用合约的响应
// @return: 是否成功
bool call(const std::string &contract,
                          const std::string &method,
                          EasyCodecItems *args,
                          std::string *resp){}

log

// 输出日志事件。查看方式为在链配置的log.yml中，开启vm:debug即可看到类似：wxvm log>> + msg
// @param body: 事件信息
void log(const std::string& body) {}