BSV Planaria框架技术总结一节点搭建

变形虫Planaria是Unwriter大神基于bitdb在bsv链上开发的一个可编程化的持久层框架，关于变形虫的特点和编程思想，可以参考我之前的文章，强烈建议先看完前文再阅读本文。

Bitcoin SV的开发哲学——变形虫框架

这篇文章从纯技术的角度总结一下使用变形虫框架进行开发所需要的注意的一些点和踩过的一些坑。

Unwriter大神在变形虫的技术支持文档中已经很详细的写了如何去部署和搭建一个节点，以及如何去调用节点提供的接口来实现应用程序的功能。我自己也照着文档去尝试着搭建节点，在搭建的过程中也遇到了一些坑，也遇到过各种各样的异常情形不能成功运行节点，也为了解决这些异常去详细地研读过源代码。现在将一些心得和学习记录总结出来分享。

一般使用Planaria实现一个bsv的链上应用需要以下的一些步骤：

搭建一个变形虫的实现节点（machine），根据业务逻辑，编写变形虫的planaria（面向区块链的爬虫）和planarium（面向人类的接口），决定变形虫如何去爬行区块链，如何规范化地将链上数据存储为可读数据。这是一个变形虫开发的重点，之后专门学习总结如何编写planaria.js和planarium.js。
客户端使用比特币的SDK构造特定格式交易来生成应用数据，广播这些交易让数据上链。然后由变形虫去监听这些数据并储存到mongoDB中提供给客户端使用。构造交易也是应用开发的重点，可以借助各种已有的库，比如bitcoinj-sv，比如money button维护的bsv.js，或者使用unwriter大神封装好的datapay.js
客户端使用刚才搭建好的节点，或者使用第三方已经提供的节点，使用bitquery查询语句调用节点的api，从节点的mongoDB中获取链上数据或者监听区块链事件
客户端获取到数据或者监听到事件之后，采取相应的动作，此处的开发就和一般的应用没有区别了

节点搭建和部署

如果想定制化的开发变形虫，指定变形虫的特征和行为，就需要自行搭建节点，自行编写planaria和planarium。

因为搭建和维护一个节点目前需要相对较高的成本，如果应用本身不需要定制化的变形虫，可以使用unwriter已经公开的一些endpoint。这些已经实现了和部署了的节点包括genesis，chronos，babel，c协议，以及新出的file-server这些变形虫的变体节点（这些变体节点的功能在之前的文章有说明），可以根据自身的需要去调用这些公开api。如果不清楚具体需要哪一种功能，可以调用genesis，具备全量的且相对原始的数据。

已经公开注册的变形虫节点

目前版本的变形虫需要将bsv全节点和变形虫节点置于同一台服务器（这是代码在配置上的原因，planaria在代码中共用了mongoDB的HOST和bitcoind的HOST），应该会在后续的版本上优化。我开始的时候将bsv全节点和变形虫节点搭建在两个不同的服务器上，结果吃了不少亏，研究了源码才发现这个问题。

另外为了部署方便，变形虫采用的是docker compose进行自动化的容器化部署，首次部署时我采用的操作系统是Ubuntu 18.04，但是在启动planaria容器后一直报异常，深入到docker内部查看npm的异常日志发现了如下的错误信息，大概是在build zeromq的时候出现了问题，照理说docker容器应该是可以跨平台使用的，我目前还没有很好的解决掉这个问题，不知道底层的原因是什么。后面更换了操作系统Ubuntu 16.04，一切正常，我把错误日志贴出来，希望知道原因的朋友多指教。

13592 silly saveTree `-- zeromq@4.6.0
13592 silly saveTree   `-- prebuild-install@2.5.3
13592 silly saveTree     +-- expand-template@1.1.1
13592 silly saveTree     +-- minimist@1.2.0
13592 silly saveTree     `-- pump@2.0.1
13593 warn planaria@0.0.1 No description
13594 warn planaria@0.0.1 No repository field.
13595 warn optional SKIPPING OPTIONAL DEPENDENCY: fsevents@1.2.8 (node_modules/fsevents):
13596 warn notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for fsevents@1.2.8: wanted {"os":"darwin","arch":"any"} (current: {"os":"linux","arch":"x64"})
13597 verbose notsup SKIPPING OPTIONAL DEPENDENCY: Valid OS:    darwin
13597 verbose notsup SKIPPING OPTIONAL DEPENDENCY: Valid Arch:  any
13597 verbose notsup SKIPPING OPTIONAL DEPENDENCY: Actual OS:   linux
13597 verbose notsup SKIPPING OPTIONAL DEPENDENCY: Actual Arch: x64
13598 verbose stack Error: zeromq@4.6.0 install: `node scripts/prebuild-install.js || (node scripts/preinstall.js && node-gyp rebuild)`
13598 verbose stack Exit status 1
13598 verbose stack     at EventEmitter.<anonymous> (/usr/lib/node_modules/npm/node_modules/npm-lifecycle/index.js:301:16)
13598 verbose stack     at EventEmitter.emit (events.js:182:13)
13598 verbose stack     at ChildProcess.<anonymous> (/usr/lib/node_modules/npm/node_modules/npm-lifecycle/lib/spawn.js:55:14)
13598 verbose stack     at ChildProcess.emit (events.js:182:13)
13598 verbose stack     at maybeClose (internal/child_process.js:962:16)
13598 verbose stack     at Process.ChildProcess._handle.onexit (internal/child_process.js:251:5)
13599 verbose pkgid zeromq@4.6.0
13600 verbose cwd /planaria
13601 verbose Linux 4.15.0-1035-aws
13602 verbose argv "/usr/bin/node" "/usr/bin/npm" "install"
13603 verbose node v10.10.0
13604 verbose npm  v6.4.1
13605 error code ELIFECYCLE
13606 error errno 1
13607 error zeromq@4.6.0 install: `node scripts/prebuild-install.js || (node scripts/preinstall.js && node-gyp rebuild)`
13607 error Exit status 1
13608 error Failed at the zeromq@4.6.0 install script.
13608 error This is probably not a problem with npm. There is likely additional logging output above.
13609 verbose exit [ 1, true

上面两个问题给我开始的部署带来了很大的麻烦，希望后续版本可以改进这些问题。下面说一下节点所需要的配置：

至少2G的内存
至少300G的硬盘储存空间（unwriter写200G，肯定不够用）

这些配置是为了支撑一个bsv的全节点，加上docker，以及运行在docker上的planaria和planarium，其中还要运行一个mongoDB的服务器。如果机器性能太差，则在同步区块和读写数据库的时候会消耗大量的时间，更可能在BSV突如其来的大区块冲击下被搞垮，这也就是为什么bsv不提倡使用家庭电脑运行全节点，搭建节点就是为了商用。只是学习和了解的话建议直接使用公开节点api。

而我的节点搭建在AWS上，考虑成本和性能，加上为了研究和学习使用，采用了如下的配置：

T2 Medium的EC2实例类型（2 vCPUs，4GB内存）
1000GB的EBS磁盘（Megnetic Standartd）
Ubuntu 16.04的操作系统

更低的配置我测试过，效果很不好，同步区块校验交易效率很低，读写性能也很受限制，上面的配置的成本每个月大概100美元（如果要推广商用，这个成本还要翻N倍），所以再次强调，full node is about business。所以如果要开发区块链应用，那么应用的收益至少要能涵盖这个成本，这就是资本主义竞争的残酷，树莓派节点只会拖慢网络，不会服务用户。

机器准备好了之后，就可以开始搭建节点了。英文好的可以直接参考Unwriter的文档

Run a Node

安装bitcoin sv全节点客户端

bsv全节点没有可视化客户端，只能通过命令行来安装和运行，这也一定程度上避免了个人运行全节点来浪费资源。

首先从bitcoinsv.io的网站下载客户端软件（版本0.1.1）：
官方下载镜像

然后下载名称为bitcoin-sv-0.1.1-x86_64-linux-gnu.tar.gz 的压缩包到你的程序目录文件下。

解压客户端文件

tar -zxvf bitcoin-sv-0.1.1-x86_64-linux-gnu.tar.gz

然后在根目录建立bitcoin的数据文件夹，准备编辑启动配置bitcoin.conf。

cd ~mkdir .bitcoincd .bitcoin/vi bitcoin.conf

bicoin.conf 是比特币客户端的配置文件，变形虫节点的运行需要依赖bsv节点的index和zeroMQ，因此要对其进行相应的配置，我的配置如下：

dbcache=4000
# Must set txindex=1 so Bitcoin keeps the full index
txindex=1# [rpc]
# Accept command line and JSON-RPC commands.
server=1
# Default Username and Password for JSON-RPC connections
# Planaria uses these values by default, but if you can change the settings
# When you run 'pc start'
rpcuser=YOURNAME
rpcpassword=YOURPASSWORD
# If you want to allow remote JSON-RPC access
rpcallowip=0.0.0.0/0
rpcbind=0.0.0.0
# [wallet]
disablewallet=1# [ZeroMQ]
# ZeroMQ messages power the realtime Planaria crawler
# so it's important to set the endpoint
zmqpubhashtx=tcp://0.0.0.0:28332
zmqpubhashblock=tcp://0.0.0.0:28332# Planaria makes heavy use of JSON-RPC so it's set to a higher number
# But you can tweak this number as you want
rpcworkqueue=512# Support large mempool
maxmempool=4000# Support large pushdata
datacarriersize=100000# Long mempool chain support
limitancestorsize=100000
limitdescendantsize=100000addnode=104.215.14.250
addnode=13.231.139.183
addnode=13.231.20.63
addnode=13.231.92.219
addnode=54.95.24.226
addnode=52.195.19.127

最后的几个ip是我手动添加的距离比较近的sv节点ip，因为bsv和bchabc在网络层没有做隔离，在首次同步的时候经常会链接到分叉前的abc的节点，在同步到分叉高度后就会因为不兼容而无法继续同步，所以我手动添加了一些节点来帮助我同步数据，更快地找到组织。寻找这些节点也很简单，打开blockchair的节点接口，就可以查看现有的的节点了，选取"version": "/Bitcoin SV:0.1.0(EB128.0)/",这样的节点ip添加到conf中。

blockchair nodes

然后切换到bitcoin-sv的bin目录下，启动客户端，可以用deamon模式也可以nohup挂载。

cd bitcoin-sv-0.1.1/bin/sudo nohup ./bitcoind &./bitcoin-cli getinfo

如果bitcoin-cli成功返回以下结果，说明全节点启动成功

{"version": 100010100,"protocolversion": 70015,"blocks": 581047,"timeoffset": 0,"connections": 36,"proxy": "","difficulty": 85497465595.02908,"testnet": false,"stn": false,"paytxfee": 0.00000000,"relayfee": 0.00001000,"errors": "","maxblocksize": 128000000,"maxminedblocksize": 32000000
}

安装docker

变形虫框架依赖多个组件运行，unwriter为了方便人们部署变形虫，将这些组件整合在容器中，这样就具备了便携性和跨平台的特性。

安装docker请直接参考docker的官方文档或者在网上搜索安装方法，这里不赘述。

Ubuntu下安装docker的官方文档

安装docker compose

docker compose是用来将多个容器进行管理和协调的工具。安装同样不赘述。

Install Compose on Linux systems

安装node

虽然变形虫等框架是运行在docker内，docker内集成了nodejs等环境，但是如果使用Unwriter提供的Planaria Computer（后文简称PC）工具来管理各个组件容器（这样可以不用直接跟docker打交道），就需要在机器上安装PC所需要的Node 环境。
Planaria Computer提供了一系列命令和cli工具来轻松管理，发布，下载，部署，维护变形虫节点，因此我们安装PC之前需要安装其运行的NodeJs环境。

ubuntu下安装nodeJs很简单，可以用nodesource的源来安装

# Using Ubuntu
curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
sudo apt-get install -y nodejs

安装后执行node -v如果返回v12.0.0就说明安装成功。

安装Planaria Computer与启动变形虫

npm install -g planaria

安装好之后，就可以开始创建变形虫的状态机（machine）了。

先给planaria创建一个文件夹，作为变形虫节点的数据文件夹：

mkdir planariacd planaria/

然后创建第一个状态机

pc new genesis

这里为了简单起见，我们创建了一个genesis（创世纪）的状态机，如果要创建自定义状态机，则执行下面的指令（推荐学习者使用genesis的状态机，获取全量数据并方便后面的bitquery查询）：

pc new machine

注意，如果创建的是Genesis这种已经定制好的状态机，则不需要编写内部的js代码，如果创建的空的状态机，则需要编写js代码来实现自定义的状态码，这部分技术之后总结。

我们创建好了一个Genesis的状态机之后，PC会生成一个文件夹，名称叫genes（基因），这里储存了全部的状态机，每一个状态机有一个独特的比特币地址作为文件夹名称，正是因为变形虫采用地址作为状态机的基因（特征标志），状态机理论上就可以有比特币地址那么多的个数，而且同一个地址的状态机可以更新换代，这就涉及到另一个关于Bitcom协议的概念了，后文会说。我们进去其中一个状态机的文件夹之后就可以发现如下的几个文件：

-rw-rw-r-- 1 1001 1001  100 Apr 26 16:32 .env
-rw-rw-r-- 1 1001 1001  169 Apr 26 16:32 package.json
-rw-rw-r-- 1 1001 1001 4599 Apr 26 16:34 planaria.js
-rw-rw-r-- 1 1001 1001  514 Apr 26 16:32 planarium.js
-rw-rw-r-- 1 1001 1001    0 Apr 26 16:32 README.md

.env中放置了这个状态机地址和对应的私钥，是证明状态机所有权和用来修改状态机的权限秘钥，建议如果自定制了协议，请务必备份好.env文件，这是协议和状态机所有权的标志。

package.json是常见的nodejs依赖管理，如果你的变形虫代码逻辑需要依赖一些其他的nodejs的库，可以在这里面进行编辑。

Planaria.js是面向区块链的爬虫逻辑，里面需要编写如何解析原始交易，并提取其中的信息储存到MongoDB中。

Planarium.js是面向应用的展示层逻辑，将MongoDB的数据读取出来，加工成应用需要的格式，返回给应用。

README.md是你的自定义协议或者状态机的一个说明文档（markdown格式），在公开发布此状态机的时候会上传此文档，作为描述状态机功能和使用方法的文档。

然后启动所有的变形虫（genes文件夹下所有的变形虫实现都会被启动）：

pc start

然后程序会问你一些问题，你根据实际情形来进行配置。

Storage Path： docker volume所挂载的文件路径。推荐用默认
Memory in GB：需要为容器预留的内存，推荐2G，我这里设置的1G
域名：这个域名是为了发布变形虫之后，提供给外界使用的，可以直接用ip地址
Join the planaria network：如果你想运行一个私有的节点，选择No，如果你想公开协议或者公开节点，选择Yes
Port: 变形虫的对外端口，默认3000
BITCOIN_USER： bsv节点rpc的用户名，上文有写
BITCOIN_PASSWORD： bsv节点json-rpc的密码，上文有写

上面的配置在Planaria根目录下的.env中可以随时修改。然后就会看到代码开始启动两个docker容器(interplanaria/planarium和interplanaria/planaria）。之后就会看到容器启动成功。但是容器启动成功并不等于变形虫已经启动成功，需要通过日志来查看。容器的日志可以通过docker命令来查看，但这里我们有PC工具，不用和docker打交道，直接执行

pc logs writepc logs read

write指的是planaria容器的日志，read指的是planarium的容器，如果容器里发生任何错误或异常，都可以从日志中获取到信息。如果容器内部没有异常，正常启动，就可以看到容器对外开放了3000端口。此时从外部浏览器访问服务器的3000端口（http://XXX.XXX.XXX.XXX:3000/），就可以显示如下的画面：

有几个Gene，就有几个状态机显示在这里，点击query进去，就会发现和以下公开的genesis数据库一样的bitquery查询界面：

genesis的query界面

在自己搭建的query中执行默认查询语句，能正确返回结果，说明已经搭建完成了。

然后就可以愉快地使用bitquery玩耍链上数据了。