FIO Chronicle Project

FIO.Chronicle is a software application designed to process the state and trace history of the FIO blockchain and is a fork of the EOSChronicle project. For more detailed information regarding FIO.Chronicle and its origin, EOSChronicle, see the FIO.Chronicle Overview.

For information on FIO Protocol, visit FIO.
For information on the FIO Chain, API, and SDKs, including detailed clone, build and deploy instructions, visit FIO Protocol Developer Hub.

Licenses and Copyrights

FIO.Chronicle License

Source code repository: https://github.com/fioprotocol/fio.chronicle

Forked Source code repository: https://github.com/EOSChronicleProject/eos-chronicle

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Releases

See the release notes for information regarding FIO/EOS Chronicle releases.

Clone the repository

To clone the FIO.Chronicle repository, execute the command;

git clone --recursive https://github.com/fioprotocol/fio.chronicle.git

Build and Install Instructions

Minimum build requirements: Cmake 3.11, GCC 8.3.0

Dependencies:

Boost, version 1.80.0
Clang, version 11.0.1
CMake, version 3.31.2
LLVM, version 7.1.0
PostgreSQL, version 16*

PostgreSQL is a mandatory dependency regardless of the plugin used. To install PostgreSQL execute the following commands (taken from https://www.postgresql.org/download/linux/ubuntu/)

sudo apt install curl ca-certificates
sudo install -d /usr/share/postgresql-common/pgdg
sudo curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc --fail https://www.postgresql.org/media/keys/ACCC4CF8.asc
sudo sh -c 'echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
sudo apt update
sudo apt -y install libpq-dev

See the FIO.Relic Readme for specific instructions to stand up the FIO.Relic database.

Build

The build script takes one argument, the directory where to find or install the build dependencies including Boost, Clang, and LLVM. It is recommended to use a non-system directory such as '/opt'. Note that any future builds, if given the same directory, will reuse those build dependencies.

To build fio.chronicle, execute the following commands;

cd fio.chronicle
./scripts/build.sh /opt

Install

To install fio.chronicle to the default install directory, '/opt/fio-chronicle', execute the following command;

./scripts/install.sh

To install fio.chronicle to the custom location, i.e. '/home/ubuntu/fio/chronicle', execute the following command;

./scripts/install.sh -i /home/ubuntu/fio/chronicle

To install fio.chronicle as a service, under control of systemd and managed using systemctl, execute the following command;

./scripts/install.sh -s

For non-service installations, the FIO.Chronicle executable, configuration, and state are installed to the target directory. Startup, shutdown, and state capture are accomplished either manually or through use of the convenience scripts; start.sh, stop.sh, and snapshot.sh.

For service installations the FIO.Chronicle executable is installed to /usr/local/sbin, the configuration and state are installed to /srv/fio. Startup and shutdown are accomplished through use of systemctl.

The script will output installation details including information about configuration. See the following configuration overview for more insight into the default configuration as well as how to customize it.

Configuration

The configuration of FIO.Chronicle is designated via options specified on the command-line as well as captured in a config.ini that is read as part of start up. The configuration options include, but are not limited to, the following;

Command-Line Options

--config-dir=<directory where to find the config.ini>
--data-dir=<directory where to store data>

Config.Ini Options

host = <the nodeos state history host (upstream connection to FIO.Nodeos state history api endpoint)>
port = <the nodeos state history api port (upstream connection to FIO.Nodeos state history api endpoint port)>
plugin = <the active plugin (max 1 active); options include 'exp-ws-plugin', 'exp-relic-plugin' >

Relic DB Exporter Plugin:

plugin = exp-relic-plugin
exp-relic-host = <the FIO.Relic database server host, valid for 'exp-ws-plugin' only (the downstream connnection to a PostgreSQL server host)>
exp-relic-port = <the FIO.Relic database port, valid for 'exp-ws-plugin' only (the downstream connnection to a PostgreSQL server port)>
exp-relic-username = <the FIO.Relic database user name, valid for 'exp-ws-plugin' only>
exp-relic-password = <the FIO.Relic database password, valid for 'exp-ws-plugin' only>

Given configuration of the Relic DB Exporter plugin, the config.ini is as follows;

host = 127.0.0.1
port = 8080
mode = scan
plugin = exp_relic_plugin
exp-relic-host = 127.0.0.1
exp-relic-port = 5432
exp-relic-username = chronicle_user
exp-relic-password = password123!

These options will allow FIO.Chronicle to connect to a FIO State History node at 127.0.0.1:8080 (host:port) and will export processed data to the FIO.Relic PostgreSQL DB server running on host 127.0.0.1 and port 5432.

Starting the application

To manually start FIO.Chronicle, execute the command;

/opt/fio-chronicle/chronicle-receiver --config-dir=/opt/fio-chronicle/config --data-dir=/opt/fio-chronicle/data --start-block=1 --end-block=1000

Note that in the above command both a start and an end block number are specified, which limits processing to that block range. Specify a very large number for the --end-block parameter to process blocks for the foreseeable future.

To capture standard output to a log, execute the above command redirecting standard ouput as follows;

mkdir -p /opt/fio-chronicle/log
/opt/fio-chronicle/chronicle-receiver --config-dir=/opt/fio-chronicle/config --data-dir=/opt/fio-chronicle/data --start-block=1 --end-block=1000 2>&1 | tee -a /opt/fio-chronicle/log/chronicle.log &

For FIO.Chronicle service installations;

systemctl start chronicle_receiver@fio

Using the start script, start.sh, execute the command (note that logging is captured in chronicle.log);

./scripts/start.sh

or

./scripts/start.sh -b /home/ubuntu/fio/chronicle

In the case that FIO.Chronicle is a service;

./scripts/start.sh -s

Stopping the application

To stop FIO.Chronicle, execute the command;

pgrep chronicle
kill -INT <PID>

For FIO.Chronicle service installations;

systemctl stop chronicle_receiver@fio

Using the start script, stop.sh, execute the command;

./scripts/start.sh

In the case that FIO.Chronicle is a service;

./scripts/start.sh -s

WARNING: An exporter plugin as well as the application supporting that exporter should be in place before executing the command above. See the FIO.Relic Readme for specific instructions to stand up the FIO.Relic database or the addendum below to set up a web socket server.

Logging:

For local/non-service installations tail the log if standard output was redirected as follows;

tail -f /opt/fio-chronicle/log/chronicle.log

For service installations, execute the following command;

journalctl -u chronicle_receiver@fio -f

Data Capture: Export and Import

To periodically take a snapshot of the FIO.Chronicle state, primarily for stand-up of another server or fallback to a previous state, the snapshot.sh script is provided. This script provides functionality to both export and import state. Note that this state should coincide with the state resident in the FIO.Relic database.

To export the FIO.Chronicle state execute the script, snapshot.sh, passing the argument '-e' (for export). In addition, providing the '-s' argument will export data to a specific directory or file. In the case that a directory is provided, a default file name will be created in the form 'fc-snapshot-.tar.gz'. Following are three examples for exporting data;

sudo ./scripts/snapshot.sh -e

The snapshot file, /opt/fio-chronicle/bkup/fc-snapshot-2025-03-16T132648.tar.gz, will be created in the /opt/fio-chronicle/bkup directory containing the FIO.Chronicle state at March 16, 2025, 1:26:48 pm. Note that /opt/fio-chronicle is the default installation directory for FIO.Chronicle.

Other examples include;

sudo ./scripts/snapshot.sh -e -a /tmp

The snapshot file, /tmp/fc-snapshot-2025-03-16T132648.tar.gz, will be created in the /tmp directory containing the FIO.Chronicle state at March 16, 2025, 1:26:48 pm.

sudo ./scripts/snapshot.sh -e -a /tmp/chronicle_snapshot

The snapshot file, /tmp/chronicle_snapshot, will be created containing the FIO.Chronicle state at March 16, 2025, 1:26:48 pm. Note that the file format is a tar gzip file regardless of the extention provided.

sudo ./scripts/snapshot.sh -e -s

The snapshot file, /srv/fio/chronicle-bkup/fc-snapshot-2025-03-16T132648.tar.gz_, will be created containing the FIO.Chronicle state at March 16, 2025, 1:26:48 pm. Note that the '-s' argument signified that FIO.Chronicle was installed as a service.

To import the FIO.Chronicle state execute the script, snapshot.sh, passing the argument '-i' (for import), and the '-s' argument specifying the snapshot file. For example, to import the data previously exported to the file /tmp/chronicle_snapshot, execute the command;

sudo ./scripts/snapshot.sh -i -a /tmp/chronicle_snapshot

Addendum

For the purposes of confirming end-to-end connectivity refer to the configuration as well as the documents below to start a local FIO state history node as well as a local web socket server

Web Socker Exporter Plugin Configuration:

plugin = exp-ws-plugin
exp-ws-host = <the websocket server host (the downstream connnection to a web socket server host)>
exp-ws-port = <the websocket server port (the downstream connnection to a web socket server port)>

Supporting Documentation:

Name		Name	Last commit message	Last commit date
Latest commit History 525 Commits
.github/workflows		.github/workflows
chronicle-receiver		chronicle-receiver
config		config
docs		docs
examples		examples
external		external
scripts		scripts
systemd		systemd
testing		testing
.gitignore		.gitignore
.gitmodules		.gitmodules
CMakeLists.txt		CMakeLists.txt
CREDITS		CREDITS
LICENSE.txt		LICENSE.txt
README.md		README.md
package.cmake		package.cmake

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

FIO Chronicle Project

Licenses and Copyrights

Releases

Clone the repository

Build and Install Instructions

Build

Install

Configuration

Starting the application

Stopping the application

Logging:

Data Capture: Export and Import

Addendum

About

Uh oh!

Releases

Packages

Languages

License

fioprotocol/fio.chronicle

Folders and files

Latest commit

History

Repository files navigation

FIO Chronicle Project

Licenses and Copyrights

Releases

Clone the repository

Build and Install Instructions

Build

Install

Configuration

Starting the application

Stopping the application

Logging:

Data Capture: Export and Import

Addendum

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages