Chaincore, the NodeJS package that enables simplistic APIs among cryptocurrency blockchains.

• Supported Chains
• Prerequisites
• Installation
• Configuration
• Usage
  • REST API
    • Serving the API
    • Endpoints List
    • HTTP JSON Response Structure
  • Websockets
    • Serving the Stream
    • Socket JSON Request Structure
    • Socket JSON Response Structure
    • NodeJS Code Example
    • Vanilla JS Code Example
• Ubuntu Setup Cheatsheet
• License

• bch
• btc
• ltc

• npm >= 6.0.0
• node >= 10.0.0
• libzmq3-dev

npm install chaincore-node

Create a config.json using config.example.json

{
  "api": {
    "port": 7070
  },
  "stream": {
    "port": 8080
  },
  "network": "mainnet",
  "chains": {
    "bch": {
      "zmq": {
        "host": "127.0.0.1",
        "port": 20000
      },
      "rpc": {
        "user": "username",
        "pass": "password",
        "host": "127.0.0.1",
        "port": 30000
      }
    },
    "btc": {
      "zmq": {
        "host": "127.0.0.1",
        "port": 20001
      },
      "rpc": {
        "user": "username",
        "pass": "password",
        "host": "127.0.0.1",
        "port": 30001
      }
    },
    "ltc": {
      "zmq": {
        "host": "127.0.0.1",
        "port": 20002
      },
      "rpc": {
        "user": "username",
        "pass": "password",
        "host": "127.0.0.1",
        "port": 30002
      }
    }
  }
}

Chaincore provides REST and Websocket APIs for: Bitcoin, Bitcoin Cash and Litecoin nodes.

The Chaincore REST API allows for effective blockchain interaction via HTTP endpoints.

node node_modules/chaincore-node/serve-api.js /path/to/config.json

Please note: endpoints that get address UTXOs or balance will only return data that occurred after the address was imported. Chaincore is designed to be watch-only, therefore no rescan happens following an address import.

{
    "success": <bool>,
    "message": <null|string>,
    "results": <object|array>
}

The Chaincore websockets stream allows for real-time blockchain event subscriptions.

node node_modules/chaincore-node/serve-stream.js /path/to/config.json

{
    "method": <string>,
    "channel": <string>,
    "params": <array>
}

{
    "success": <bool>,
    "message": <null|string>,
    "channel": <string>,
    "method": <string>,
    "results": <object>
}

Example using: ws as a client on the server.

First, install ws via the following command: npm install ws - then, subscribe to channels and receive events like so:

const WebSocket = require('ws')
const ws = new WebSocket('ws://127.0.0.1:8080')

ws.on('open', () => {
  console.log('Connected')

  let request = {method: 'subscribe', channel: 'btc:utxo', params: []}

  ws.send(JSON.stringify(request))
})

ws.on('message', message => {
  let event = JSON.parse(message)

  console.log(event)
})

No need to install anything else, simply run the following code in any modern browser:

const ws = new WebSocket('ws://127.0.0.1:8080')

ws.addEventListener('open', () => {
  console.log('Connected')

  let request = {method: 'subscribe', channel: 'btc:utxo', params: []}

  ws.send(JSON.stringify(request))
})

ws.addEventListener('message', message => {
  let event = JSON.parse(message.data)

  console.log(event)
})

Get Chaincore working on Ubuntu 18.04 (from-scratch) using the following instructions:

sudo apt update
sudo apt install npm
sudo apt install nodejs
sudo apt install libzmq3-dev

npm install pm2@latest -g
pm2 install pm2-logrotate

cd /var
git clone https://github.com/Vimiso/chaincore-node.git
cd /var/chaincore-node
npm install

vi /var/chaincore-node/config.json

mkdir /root/.bitcoin
cd /root/.bitcoin
wget https://bitcoin.org/bin/bitcoin-core-0.20.1/bitcoin-0.20.1-x86_64-linux-gnu.tar.gz
tar -xf bitcoin-0.20.1-x86_64-linux-gnu.tar.gz

vi /root/.bitcoin/bitcoin.conf

port=10001
whitelist=127.0.0.1
txindex=1
listen=1
server=1
upnp=1
dbcache=512

rpcport=30001
rpcallowip=127.0.0.1

rpcuser=username
rpcpassword=password

datadir=/mnt/bitcoin

zmqpubrawblock=tcp://127.0.0.1:20001
zmqpubrawtx=tcp://127.0.0.1:20001
zmqpubhashtx=tcp://127.0.0.1:20001
zmqpubhashblock=tcp://127.0.0.1:20001

Important: a mounted disk (/mnt/bitcoin) with at-least 350GB is required to store the Bitcoin blockchain.

/root/.bitcoin/bitcoin-0.20.1/bin/bitcoind -conf=/root/.bitcoin/bitcoin.conf -daemon

Now you must wait for Bitcoin to sync... you can find the sync progress and other useful logs in: /mnt/bitcoin/debug.log.

Once synced you're ready to run Chaincore as a daemon using pm2!

pm2 startup
pm2 start /var/chaincore-node/serve-api.js
pm2 start /var/chaincore-node/serve-stream.js
pm2 save

You can monitor pm2 daemons by running: pm2 monit

You can repeat these instructions with other supported blockchains, here's the list:

• Bitcoin: https://bitcoin.org/bin/bitcoin-core-0.20.1/bitcoin-0.20.1-x86_64-linux-gnu.tar.gz
• Bitcoin Cash: https://github.com/bitcoin-cash-node/bitcoin-cash-node/releases/download/v22.1.0/bitcoin-cash-node-22.1.0-x86_64-linux-gnu.tar.gz
• Litecoin: https://download.litecoin.org/litecoin-0.18.1/linux/litecoin-0.18.1-x86_64-linux-gnu.tar.gz

Copyright 2020 Vimiso

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.