fibos-tracker

1.4.1 • Public • Published

fibos-tracker

NPM version Build Status

fibos-tracker 是一个 FIBOS 区块链数据 API 服务框架,基于 fib-app 框架实现.

  • 提供对 FIBOS 区块数据的 emitter 监听事件
  • 提供 http 服务,支持 GraphQL 调用
  • 支持使用 ORM模型 定制自己的数据模型 model,自定义数据表以及自定义 hook 监听数据

使用之前您可能需要去了解一下这些内容:

注意 如果您使用的是 ubuntu, 请确保使用 16.04(xenial) 及其以上的版本.

目录

FIBOS 版本支持
数据存储支持
安装 fibos-tracker
框架说明及 API 使用
Example-快速应用
高级篇-使用 ORM 自定义数据

升级指南

1.3.x -> 1.4.x

fibos-tracker 从 1.4.x 版本起,修改了默认数据表结构&表名。

执行以下 sql 语句进行表结构升级:

ALTER  TABLE  `transactions` RENAME TO `fibos_transactions`;
ALTER  TABLE  `blocks` RENAME TO `fibos_blocks`;
ALTER  TABLE `fibos_transactions` ADD `contract_action` varchar(64);
ALTER  TABLE `fibos_transactions` ADD INDEX contract_action_index (contract_action);
ALTER  TABLE `fibos_transactions` ADD `block_id` bigint(20) DEFAULT NULL;

测试对比

使用 FIBOS 主网数据进行 replay 测试,区块数据高度:70166754 机器性能:4核 8G

测试结果如下:

测试方式 耗时
使用区块数据 replay 12H
使用区块数据 + emitter 插件 replay 12H
使用 fibos-tracker的 db replay 1H

由上结果可以得知,使用 fibos-tracker 的 db replay 可以大大节省链下数据存储的时间。

FIBOS 版本支持

支持: v1.7.1.9+

快速安装: curl -s https://fibos.io/download/installer.sh | sh

数据存储支持

  • Mysql
  • SQLite

安装 fibos-tracker

fibos --install fibos-tracker

框架说明及 API 使用

fibos-tracker DB 说明

框架默认存储了 fibos_blocks 、fibos_transactions、fibos_actions 的基础数据,如下图显示:

数据模型

fibos_blocks 表数据

字段 类型 备注
id Number 自增长 id
block_num Number 区块高度
block_time Date 区块时间
producer_block_id String 区块 hash
producer String 区块 producer
previous String 上一块 hash
status String 可逆状态
createdAt Date 记录创建时间
updatedAt Date 记录更新时间

fibos_transactions 表数据

字段 类型 备注
id bigint 自增长 id
trx_id String 交易 hash
rawData JSON 原始数据
producer_block_id String 区块 hash
contract_action String 合约/动作
block_id bigint 事务关联区块id
createdAt Date 记录创建时间
updatedAt Date 记录更新时间

fibos_actions 表数据

| 字段 | 类型 | 备注 | | id | bigint | 自增长 id | | trx_id | String | 交易id | | rawData | JSON | action 对应的数据 | | contract_action | String | 合约/动作 | | transaction_id | String | 关联 transaction id | | parent_id | String | inline 上级id | | createdAt | Date | 记录创建时间 | | updatedAt | Date | 记录更新时间 |

fibos-tracker API 介绍

Tracker.Config

Config 是 Tracker 全局属性,可以使用该属性快速修改配置,如:修改存储引擎配置。

示例:

const Tracker = require("fibos-tracker");

Tracker.Config.DBconnString = "mysql://root:123456@127.0.0.1/fibos_chain";
Tracker.Config.replay = true;
Tracker.Config.replayStatrBn = 1000;


name desc default
DBconnString 数据存储引擎 默认使用 SQLite 存储引擎
replay 是否开启 DB replay false
replayStatrBn DB replay 指定高度(需要配合replay) 0

tracker.app

fib-app 的实例 app 对象,具体请阅读 fib-app 相关文档。

tracker.app 对象可支持路由访问。

示例:

const http = require("http");
const Tracker = require("fibos-tracker");
const tracker = new Tracker();

let httpServer = new http.Server("", 8080, {
    '/1.0/app': tracker.app
});

httpServer.run();

tracker.emitter

FIBOS emitter 插件,配合 FIBOS 的 action 插件使用。

示例:

const fibos = require("fibos");
const Tracker = require("fibos-tracker");
const tracker = new Tracker();

tracker.emitter();

tracker.diagram

生成数据表的关联图,如果自定义了数据表,需要先调用 tracker.use 再执行。

示例:

const Tracker = require("fibos-tracker");
const tracker = new Tracker();

//If exist other db modles,please exec tracker.use.

tracker.diagram();

tracker.stop

使 tracker 安全停止

示例:

const Tracker = require("fibos-tracker");
const tracker = new Tracker();

tracker.stop();

tracker.use

自定义 hook 监听数据,使用 ORM 模型自定义 DB 存储以及处理。

示例:

const fibos = require("fibos");
const Tracker = require("fibos-tracker");
const tracker = new Tracker();

tracker.use({
    defines: [(db) => {
        // ORM DB Define
    }, (db) => {
        // ORM DB Define
    }],
    hooks: {
        "eosio.token/transfer": (db, messages) => {
            // hook Tracker messages
        },
        "eosio/newaccount": (db, messages) => {
            // hook Tracker messages
        }
    }
});

defines 支持数组形式,满足某个 model 需要多个数据表的操作场景。

tracker.use 参数定义:

params type desc
model Object 自定义数据对象,包含 defines 和 hooks

model 内部参数定义:

key type desc params
defines Function 使用 ORM 模型定义数据表,提供 API 访问 (db) => {}参数 db 是 ORM 对象,可用于操作数据层
hooks Function 支持过滤 action 数据的 hook function (db, messages) => {} 参数 db 是 ORM 对象,参数 messages 是 action 原始数据集合

hooks 的过滤规则说明:

  • 过滤某个合约,如:eosio.token
  • 过滤某个合约的 action,如:eosio.token/transfer

hooks 的 messages 数据说明:

为了方便 hooks 业务研发,传递 messages 时做了优化:

  • 满足过滤规则的所有 action 合并成数组传递
  • 数组内每一个满足过滤规则的 action 包含 本层 action 以下所有 inline_action,并且如果存在上层 action,将携带 parent 属性,标识上层 parent 的 action 数据。

注:每层 parent_id 是该层 action 上级的 DB 自增长 id。

举一个返回示例结构:

[
  {
    "inline_traces": [
      {
        "parent": ... parent_id => 1
        "inline_traces": [
          {
            "parent": ... parent_id => 2
                "parent": ... parent_id => 1
          },
          {
            "parent": ... parent_id => 2
                "parent": ... parent_id => 1
          }
        ]
      }
    ]
  }
]

Example 快速应用

Example 源码

学习了解 fibos-trakcer 之后,让我们开始动手编写,使用框架写一个区块链数据存储展现的应用。

与 FIBOS 的 emiiter结合,写一个应用。 它可以同步 FIBOS TestNet 网络区块数据,并且使用 GraphQL 获取应用数据。

FIBOS TestNet WebSite

环境准备

  1. 快速安装 FIBOS
curl -s https://fibos.io/download/installer.sh | sh
  1. 查看 FIBOS 版本
$ fibos //Enter

输出:

(不同 FIBOS 版本输出信息不一致)

Welcome to FIBOS v1.7.1.8 Based on fibjs 0.29.0-dev.
Type ".help" for more information.
  1. 准备示例目录
 :$ mkdir example;cd example
 :$ fibos --init
 :$ fibos --install fibos-tracker

编写例子

genesis.json 是 FIBOS TestNet 网络的配置。

index.js:

const http = require("http");
const fibos = require("fibos");
const Tracker = require("fibos-tracker");
const tracker = new Tracker();

fibos.config_dir = "./data";
fibos.data_dir = "./data";
fibos.load("http", {
    "http-server-address": "0.0.0.0:8870",
    "access-control-allow-origin": "*",
    "http-validate-host": false,
    "verbose-http-errors": true
});

fibos.load("net", {
    "p2p-peer-address": ["p2p-testnet.fibos.fo:9870"],
    "p2p-listen-endpoint": "0.0.0.0:9870"
});

fibos.load("producer");
fibos.load("chain", {
    "contracts-console": true,
    "delete-all-blocks": true,
    "genesis-json": "genesis.json"
});

fibos.load("chain_api");

tracker.emitter();

fibos.start();

let httpServer = new http.Server("", 8080, [
    (req) => {
        req.session = {};
    }, {
        '^/ping': (req) => {
            req.response.write("pong");
        },
        '/1.0/app': tracker.app,
        "*": [function(req) {}]
    },
    function(req) {}
]);

httpServer.crossDomain = true;
httpServer.asyncRun();

启动服务

fibos index.js

使用 GraphQL 方式获取应用数据

  1. FIBOS GraphQL 客户端
const http = require("http");

let graphql = function(body) {
    return http.post(`http://127.0.0.1:8080/1.0/app/`, {
        headers: {
            'Content-Type': 'application/graphql'
        },
        body: body
    });
}
  1. Web GraphQL 客户端

Jquery Ajax 示例:

let graphql = function(body) {
    $.ajax({
        type: "POST",
        url: "http://127.0.0.1:8080/1.0/app",
        data: body,
        headers: {
            "Content-Type": "application/graphql"
        },
        success: (res) => {
            console.log("success");
        },
        error: (res) => {
            console.log("error");
        }
    });
}

GraphQL 获取应用-列表数据

graphql(`
{
    find_fibos_blocks(
       	skip: 0,
        limit: 10,
        order: "-id"
    ){
        id,
        block_time,
        block_num,
        producer_block_id,
        producer,
        status,
        createdAt,
        updatedAt
    }
}`)

GraphQL 获取应用-详情数据

graphql(`
{
    find_fibos_blocks(
        where:{
            id: 23
        }
    ) {
        id,
        block_time,
        block_num,
        producer_block_id,
        producer,
        status,
        createdAt,
        updatedAt,
        transactions{
            id,
            trx_id,
            rawData,
            createdAt,
            updatedAt
        }
    }
}`)

高级篇-使用 ORM 自定义数据

Example 源码

学习了基础篇的应用,让我们使用 fibos-tracker 的 use 完成一个仅监控 eosio.token 合约 transfer 的应用。

环境准备

基于上面的环境应用,让我们创建一个目录:

:$ mkdir addons;cd addons;

设计&&定义一个数据模型

设计数据表 eosio_token_transfers:

字段 类型 备注
id Number 自增长 id
from String 转出方
to String 转入方
quantity String 交易数量
memo String memo
createdAt Date 记录创建时间
updatedAt Date 记录更新时间

使用 ORM Define 数据表逻辑:

let defines = [db => {
    return db.define('eosio_token_transfers', {
        from: {
            required: true,
            type: "text",
            size: 12
        },
        to: {
            required: true,
            type: "text",
            size: 12
        },
        quantity: {
            required: true,
            type: "text",
            size: 256
        },
        memo: {
            type: "text",
            size: 256
        }
    }, {
        hooks: {},
        methods: {},
        validations: {},
        functions: {},
        ACL: function(session) {
            return {
                '*': {
                    find: true,
                    read: true
                }
            };
        }
    });
}];

定义 hook 数据监听

hook 监听的 messages 是一组系统排序过滤后的原始区块数据。

tracker.use 需要对 hook 的接受数据进行过滤。

let hooks = {
    "eosio.token/transfer": (db, messages) => {
        let eosio_token_transfers = db.models.eosio_token_transfers;
        try {
            db.trans(() => {
                messages.forEach((m) => {
                    eosio_token_transfers.createSync(m.act.data);
                });
            });
        } catch (e) {
            console.error("eosio.token/transfer Error:", e);
        }
    }
}

保存自定义数据模型代码

保存下面代码到 eosio_token_transfers.js:

let defines = [db => {
    return db.define('eosio_token_transfers', {
        from: {
            required: true,
            type: "text",
            size: 12
        },
        to: {
            required: true,
            type: "text",
            size: 12
        },
        quantity: {
            required: true,
            type: "text",
            size: 256
        },
        memo: {
            type: "text",
            size: 256
        }
    }, {
        hooks: {},
        methods: {},
        validations: {},
        functions: {},
        ACL: function(session) {
            return {
                '*': {
                    find: true,
                    read: true
                }
            };
        }
    });
}];

let hooks = {
    "eosio.token/transfer": (db, messages) => {
        let eosio_token_transfers = db.models.eosio_token_transfers;
        try {
            db.trans(() => {
                messages.forEach((m) => {
                    eosio_token_transfers.createSync(m.data);
                });
            });
        } catch (e) {
            console.error("eosio.token/transfer Error:", e);
        }
    }
}

module.exports = {
    defines: defines,
    hooks: hooks
}

使用 fibos-tracker 加载新的数据模型

tracker.use(require("./addons/eosio_token_transfers.js"));

启动服务&&使用 GraphQL 获取数据

启动服务:

fibos index.js

查询 eosio_token_transfers 列表:

graphql(`
{
    find_eosio_token_transfers(
        skip: 0,
        limit: 10,
        order: "-id"
    ){
        id,
        from,
        to,
        quantity,
        memo,
        createdAt,
        updatedAt
    }
}`)

Readme

Keywords

Package Sidebar

Install

npm i fibos-tracker

Weekly Downloads

7

Version

1.4.1

License

ISC

Unpacked Size

68.3 kB

Total Files

27

Last publish

Collaborators

  • anleb
  • d3j
  • licao
  • xicilion