# repchain-block-courier

**Repository Path**: linkel/repchain-block-courier

## Basic Information

- **Project Name**: repchain-block-courier
- **Description**: RepChain Block Courier作为一种通知工具，可根据配置信息将RepChain/ThyLand区块链网络中产生的新区块数据推送给目标系统
- **Primary Language**: NodeJS
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2020-09-09
- **Last Updated**: 2022-07-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# repchain-block-courier

## 介绍
RepChain Block Courier作为一种通知工具，可根据配置信息将RepChain区块链网络中产生的区块数据推送给已订阅区块数据的目标系统。

## 软件架构

![系统架构](docs/working-struct.drawio.svg)

订阅者通常是使用RepChain区块链的具体业务应用，repchain-block-courier将自动从RepChain区块链网络获取到区块数据，并根据配置信息将区块数据推送给订阅者所代表的业务应用(接收处理区块数据的API需该业务应用自行实现，相关描述可参考配置文件[config/default.js](config/default.js)中的相关说明)，业务应用得到区块数据后可将其用于支持自己的特定业务需求。

repchain-block-courier观察RepChain的出块事件，按区块的高度顺序，向订阅者推送区块数据，当观察到RepChain出了新区块时，若此时没有前序区块需要推送，则将立即推送该新区块，否则将等待前序区块推送完成后，再继续推送该新区块。此外，repchain-block-courier会定时检查是否有未推送成功的区块数据，若有，则会继续推送未推送成功的区块数据。

## 安装使用
目前主要有2种安装使用方式：
1. 将repchain-block-courier本身构建为docker镜像，以docker容器的方式运行
2. 直接在主机上安装运行repchain-block-courier

### 方式一 
将repchain-block-courier本身构建为docker镜像，以docker容器的方式运行
#### 安装依赖
- node(V10.23.0+)(推荐使用[nvm](https://github.com/nvm-sh/nvm) 安装管理node)
- yarn(可选): 安装好node之后可使用命令
    ```bash
    npm i -g yarn
    ```
- [docker](https://docs.docker.com/install/)

#### 构建docker镜像
1. git clone本项目到本地
    ```bash
    git clone https://gitee.com/linkel/repchain-block-courier.git
    ```
2.  到项目根目录下，运行命令：
    ```bash
    yarn build:docker
    或者
    npm run build:docker
    ```
    > Note: 构建过程中会从github下载依赖可能出现网络错误，可在上述命令前加网络代理环境变量http_proxy，如：
    > ```bash
    > http_proxy=http://192.168.2.11:1080 npm run build:docker
    > 或者
    > http_proxy=http://192.168.2.11:1080 yarn build:docker
    > ```
    检查主机中是否有构建好的docker镜像，会出现名为repchain_block_courier的镜像：
    ```
    docker images
    ```
#### 运行 
构建完成后，在项目根目录下：

- 可以直接运行预先写好的脚本（目前只提供适配Linux和MacOS的脚本）:
    ```bash
    启动：
      在项目根目录下运行
        yarn start:docker
      或者运行
        npm run start:docker 
      或者到子目录scripts/docker下运行
        ./start.sh
    停止：
      在项目根目录下运行
        yarn stop:docker
      或者运行
        npm run stop:docker 
      或者到子目录scripts/docker下运行
        ./stop.sh
    ```
- 或者也可自己使用docker run命令启动：

    ```bash
    docker run \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ${PWD}/config:/usr/app/repchain-block-courier/config \
    -v ${PWD}/logs:/usr/app/repchain-block-courier/logs \
    -p 8008:8008 \
    -d --name courier_repchain-block-courier \
    repchain_block_courier:2.0.0 bash -c \
    "export HOST_NAME=\$(ip route show | awk '/default/{print \$3}') \
    && sed -i \"s/\(.*\:\/\/\)\(localhost\)\(.*\)/\1\${HOST_NAME}\3/\" config/default.js \
    && export echo \$(npx babel-node ./scripts/setup.js getEnvUrls) \
    && yarn deploy && cd database && npx prisma1 generate && yarn start"
    ```

> Note: 若主机已开启iptables防火墙设置，请确保主机接受通过docker0网卡进入的连接，如使用命令：
> ```
> iptables -I INPUT 4 -i docker0 -j ACCEPT
> iptables-save
> ```

### 方式二
直接在主机上安装运行repchain-block-courier
#### 安装依赖
准备或安装好以下依赖
- Linux or MacOS
- JDK(not just JRE)
- git
- Python v2.x
- 编译工具:
  - make
  - g++
- node(V10.23.0)(推荐使用[nvm](https://github.com/nvm-sh/nvm) 安装管理node)
- node-gyp:
    ```
    npm i -g node-gyp
    ```
- yarn: 安装好node之后可使用命令
    ```bash
    npm i -g yarn
    ```
- [docker](https://docs.docker.com/install/)
- [docker-compose](https://docs.docker.com/compose/install/)

#### 安装本项目程序
- git clone本项目到本地
    ```bash
    git clone https://gitee.com/linkel/repchain-block-courier.git
    ```
- 到项目根目录下，安装npm包：
    ```bash
    yarn install
    ```
    > Note: 若JDK或编译工具等未正确安装配置，在安装npm包时会失败

#### 运行
上述安装步骤完成后:
1.  部署Prisma和MySQL服务
    ```bash
    yarn deploy
    ```
    该命令会启动运行[Prisma(V1) Server](https://v1.prisma.io/docs/1.34/prisma-server/) 和MySQL的docker容器

    > Note: 若当前用户无运行docker命令的权限，则需要赋予其对应权限，如使用sudo或将当前用户加入docker用户组

2.  根据实际的需求修改配置文件config/default.js(参考该配置文件中对各配置项的说明)
3.  运行
    ```bash
    yarn start
    ```
    > 建议: 在实际生产环境中，最好使用NodeJS程序管理工具(e.g. [forever](https://github.com/foreversd/forever) , [pm2](https://pm2.keymetrics.io/) )来运行

## 状态检查
默认将开启8008端口(可在配置文件修改)提供状态检查Rest API: GET /status。
成功运行后，可随时访问该API，将返回当前程序已同步及已推送数据的情况信息(application/json)，如访问http://localhost:8008/status 返回：
```json
{
    "blockchain": [ // 所订阅的区块链组网
        {
        "id": "identity-net",          // 区块链组网标识
        "blockCount": 89,              // 该区块链组网已产生的区块数
        "transactionCount": 162,      // 该区块链组网已产生的交易数
        "syncedBlockHeight": 89,       // 本服务已从该区块链组网同步的区块数/最新高度
        "syncedTransactionCount": 162   // 本服务已从该区块链组网同步的交易数
        },
        {
        "id": "credence-net",          // 区块链组网标识
        "blockCount": 6,
        "transactionCount": 12,
        "syncedBlockHeight": 6,
        "syncedTransactionCount": 12
        }
    ],
    "subscribers": [                             // 区块数据订阅者信息
        {
            "interestingBlockHeightRange": "1-null", // 该订阅者所要同步的区块范围(1-null表示区块高度范围不受限)
            "name": "subscriber1",                   // 该订阅者名称(唯一标识)
            "url": "http://localhost:9000/blocks",   // 该订阅者用于接收区块的API URL
            "latestReceivedBlockHeights": [          // 该订阅者已成功接收的最高区块高度（顺序与blockchainIds中对应，表示从对应标识表示的区块链组网中接收的最高区块高度）
                89,
                6
            ],
            "blockchainIds": [                       // 该订阅者订阅的区块链组网的标识
                "identity-net",
                "credence-net"
            ]
        }
    ],
    "timestamp": "2022-07-01T11:49:08.321Z"          // 当前查询时间(UTC) 
}
```

### 配置
具体配置项及其说明，见配置文件[config/default.js](config/default.js)

推送的区块数据的数据结构，请直接参考配置文件中的[相应说明描述](config/default.js#L111)

## 参与贡献

1.  Fork 本仓库
2.  新建 Feat_xxx 分支
3.  提交代码
4.  新建 Pull Request