TurtleCoin Block Explorer Cache

This library is designed to load block chain data for TurtleCoin into a standard SQL database that can be used to provide fast and robust access to block chain data using a service provider mentality.

Dependencies

• NodeJS >= 8.x
• turtle-service v0.8.4 or higher

Installation

1npm install --save turtlecoin-blockexplorer-cache

Initialization

1const BlockChainCache = require('turtlecoin-blockexplorer-cache')
2
3const cache = new BlockChainCache({
4  rpcHost: '127.0.0.1', // IP address or hostname of the TurtleCoind node
5  rpcPort: 11898, // Port that TurtleCoind is running on
6  timeout: 20000, // How many milliseconds to wait for RPC responses. I recommend 20,000ms to be safe for older block scans
7  maxDeviance: 5, // How many blocks away from the network before we stop responding to getLastBlockHeader?
8  updateInterval: 5, // How long, in seconds, that we pause for before checking for new blocks when we're synced up or we finish scanning a batch
9  dbEngine: 'sqlite', // What database engine to use, see below for additional detais.
10  dbFolder: 'db', // What folder to use to store the database file, only valid for some database engines
11  dbFile: 'turtlecoin', // The filename to use to store the database file, only valid for some database engines
12  dbHost: '127.0.0.1', // The IP address of the external DB server to connect to, only valid for some database engines
13  dbPort: 3306, // The port of the external DB server to connect to, only valid for some database engines
14  dbUser: '', // The username to the external DB server to, only valid for some database engines
15  dbPassword: '', // The password to the external DB server, only valid for some database engines
16  dbDatabase: '', // The database name used on the external DB server, only valid for some database engines
17  dbSocketPath: false, // The path to the nix socket for the external DB server, only valid for some database engines
18  dbConnectionLimit: 10, // The maximum number of connections to open to the external DB server, only valid for some database engines
19  autoStartUpdater: true, // Auto start the updater process at object creation?
20  targetBlockTime: 30 // Coin target block time
21})

Supported Database Engines

At this time, just three database engines are supported; however, in the future support for additional database engines will be added.

Engine	Database System	File Based	External Service Required
sqlite	SQLite	Yes	No
mysql	MySQL	No	Yes
mariadb	mariaDB	No	Yes

Events

error

This event fires when there is an error condition that has been encountered.

1cache.on('error', (err) => {
2  // do something
3})

info

This event fires when there is an info event that you may want to know about.

1cache.on('info', (info) => {
2  // do something
3})

ready

This event fires when the database is connected and is ready for read/write operations.

1cache.on('ready', () => {
2  // do something
3})

synced

This event fires when the block chain cache is sycnronized with the data available in the TurtleCoind daemon.

1cache.on('synced', () => {
2  // do something
3})

Service Methods

start()

Stards the update process if it was previously stopped.

1cache.start()

stop()

Stops the update process.

1cache.stop()

Data Lookup Methods

All data lookup methods will resolve the Promise if the data is in the cache; otherwise, it will reject the Promise.

cache.getBlocks(options)

Returns information on the last 30 blocks before height (inclusive).

options.height The height of the blockchain to start at - required

Example Data

1[
2  {
3    "cumul_size": 22041,
4    "difficulty": 285124963,
5    "hash": "62f0058453292af5e1aa070f8526f7642ab6974c6af2c17088c21b31679c813d",
6    "height": 500000,
7    "timestamp": 1527834137,
8    "tx_count": 4
9  },
10  {
11    "cumul_size": 384,
12    "difficulty": 258237161,
13    "hash": "74a45602da61b8b8ff565b1c81c854416046a23ca53f4416684ffaa60bc50796",
14    "height": 499999,
15    "timestamp": 1527834031,
16    "tx_count": 1
17  },
18  {
19    "cumul_size": 418,
20    "difficulty": 256087255,
21    "hash": "ed628ff13eacd5b99c5d7bcb3aeb29ef8fc61dbb21d48b65e0cdaf5ab21211c1",
22    "height": 499998,
23    "timestamp": 1527834020,
24    "tx_count": 1
25  }
26]

cache.getBlock(options)

Returns information on a single block

options.hash Block hash of the block you wish to retrieve - required

Sample Data

1{
2  "alreadyGeneratedCoins": "1484230931125",
3  "alreadyGeneratedTransactions": 974921,
4  "baseReward": 2935998,
5  "blockSize": 48846,
6  "depth": 0,
7  "difficulty": 358164537,
8  "effectiveSizeMedian": 100000,
9  "hash": "f11580d74134ac34673c74f8da458080aacbe1eccea05b197e9d10bde05139f5",
10  "height": 501854,
11  "major_version": 4,
12  "minor_version": 0,
13  "nonce": 214748383,
14  "orphan_status": false,
15  "penalty": 0,
16  "prev_hash": "674046ea53a8673c630bd34655c4723199e69fdcfd518503f4c714e16a7121b5",
17  "reward": 2936608,
18  "sizeMedian": 231,
19  "timestamp": 1527891820,
20  "totalFeeAmount": 610,
21  "transactions": [
22    {
23      "amount_out": 2936608,
24      "fee": 0,
25      "hash": "61b29d7a3fe931928388f14cffb5e705a68db219e1df6b4e15aee39d1c2a16e8",
26      "size": 266
27    },
28    {
29      "amount_out": 2005890,
30      "fee": 110,
31      "hash": "8096a55ccd0d4a736b3176836429905f349c3de53dd4e92d34f4a2db7613dc4b",
32      "size": 2288
33    },
34    {
35      "amount_out": 3999900,
36      "fee": 100,
37      "hash": "304a068cbe87cd02b48f80f8831197174b133870d0c118d1fe65d07a33331c4e",
38      "size": 2691
39    },
40    {
41      "amount_out": 7862058,
42      "fee": 100,
43      "hash": "29c0d6708e8148eec6e02173b3bab0093768e5f486f553939495a47f883b4445",
44      "size": 9638
45    },
46    {
47      "amount_out": 6951392,
48      "fee": 100,
49      "hash": "fe661f11a0ba9838610c147f70813c17755ab608c7b033f6432c0b434671182c",
50      "size": 10004
51    },
52    {
53      "amount_out": 6800150,
54      "fee": 100,
55      "hash": "4b0366f79ec341cf60d5ef8c9dd8e65974dacb1be1d30dc0bf11d2d9d8240b46",
56      "size": 11493
57    },
58    {
59      "amount_out": 7260417,
60      "fee": 100,
61      "hash": "066b86268b7bb2f780ed76f452d1e6f7213dc6cae273b71fbd4ba378befaed00",
62      "size": 12155
63    }
64  ],
65  "transactionsCumulativeSize": 48535
66}

cache.getTransaction(options)

Gets information on the single transaction.

options.hash The transaction hash - required

Sample Data

1{
2  "block": {
3    "cumul_size": 22041,
4    "difficulty": 103205633,
5    "hash": "62f0058453292af5e1aa070f8526f7642ab6974c6af2c17088c21b31679c813d",
6    "height": 500000,
7    "timestamp": 1527834137,
8    "tx_count": 4
9  },
10  "status": "OK",
11  "tx": {
12    "extra": "019e430ecdd501714900c71cb45fd49b4fa77ebd4a68d967cc2419ccd4e72378e3020800000000956710b6",
13    "unlock_time": 500040,
14    "version": 1,
15    "vin": [
16      {
17        "type": "ff",
18        "value": {
19          "height": 500000
20        }
21      }
22    ],
23    "vout": [
24      {
25        "amount": 80,
26        "target": {
27          "data": {
28            "key": "5ce69a87940df7ae8443261ff610861d2e4207a7556ef1aa35878c0a5e7e382d"
29          },
30          "type": "02"
31        }
32      },
33      {
34        "amount": 200,
35        "target": {
36          "data": {
37            "key": "7c7f316befaac16ba3782a2ce489e7c0f16c2b733ac0eaa0a72a12ee637822e9"
38          },
39          "type": "02"
40        }
41      },
42      {
43        "amount": 6000,
44        "target": {
45          "data": {
46            "key": "defcb7eb6537bf0a63368ed464df10197e67d7ea8f080e885911cf9ea71abb62"
47          },
48          "type": "02"
49        }
50      },
51      {
52        "amount": 30000,
53        "target": {
54          "data": {
55            "key": "9693e864dba53f308d0b59623c608b6fe16bbdc7cdc75be94f78582d547b46a4"
56          },
57          "type": "02"
58        }
59      },
60      {
61        "amount": 900000,
62        "target": {
63          "data": {
64            "key": "b739e9fbaa3ee976a9ed8ad93a2731ee191c384cf136929e737786573fcd3e96"
65          },
66          "type": "02"
67        }
68      },
69      {
70        "amount": 2000000,
71        "target": {
72          "data": {
73            "key": "5621667d44e7ffb87e5010a5984c188f58a799efb01569e8e42fa2415bb7d14a"
74          },
75          "type": "02"
76        }
77      }
78    ]
79  },
80  "txDetails": {
81    "amount_out": 2936280,
82    "fee": 0,
83    "hash": "702ad5bd04b9eff14b080d508f69a320da1909e989d6c163c18f80ae7a5ab832",
84    "mixin": 0,
85    "paymentId": "",
86    "size": 266
87  }
88}

cache.getTransactionHashesByPaymentId

Retrives all transaction hashes for transactions with the specified paymentId

options.paymentId The paymentId to search for - required

Sample Data

1{
2  "hashes": [
3    "205b88ff825d83308465921511e239ccd1e05005302669ffd16577714c559bab",
4    "259bf487af58574b43aea492a666a1aa29a316faf51490c460fef193f4f75636",
5    "2ed24b81b0b51b86223002e8515b141b8a4b09215be2afa86de46153fa8f2167",
6    "7dc8e17ef253a3805b7ae07d9e62f0311fa5098f1b1bcd9c745d7164c29ba286",
7    "8bc8b7dc1881601f9b659e11557e572b78500bc9cdb911535a9a3bc79d59cc38",
8    "e0a1dba9b03ca97f6ccac69bcbec6c5737cb972c0039a955b4446e4add6857fa"
9  ],
10  "status": "OK"
11}

cache.getBlockCount()

Gets the current block count

Sample Data

1502322

cache.getBlockHash(options)

Gets a block hash by height.

options.height The height of the block - required

Sample Data

174a45602da61b8b8ff565b1c81c854416046a23ca53f4416684ffaa60bc50796

cache.getLastBlockHeader()

Sample Data

1{
2  "block_header": {
3    "block_size": 419,
4    "depth": 0,
5    "difficulty": 200671816,
6    "hash": "7d6db7b77232d41c19d898e81c85ecf08c4e8dfa3434f975a319f6261a695739",
7    "height": 502345,
8    "major_version": 4,
9    "minor_version": 0,
10    "nonce": 130876,
11    "num_txes": 1,
12    "orphan_status": false,
13    "prev_hash": "5af657331edff98791720c23aacf72e8b6247ddba2a5c42c93984a46946abd14",
14    "reward": 2935955,
15    "timestamp": 1527907348
16  },
17  "status": "OK"
18}

cache.getBlockHeaderByHash(options)

options.hash Block hash - required

Sample Data

1{
2  "block_header": {
3    "block_size": 419,
4    "depth": 2,
5    "difficulty": 200671816,
6    "hash": "7d6db7b77232d41c19d898e81c85ecf08c4e8dfa3434f975a319f6261a695739",
7    "height": 502345,
8    "major_version": 4,
9    "minor_version": 0,
10    "nonce": 130876,
11    "num_txes": 1,
12    "orphan_status": false,
13    "prev_hash": "5af657331edff98791720c23aacf72e8b6247ddba2a5c42c93984a46946abd14",
14    "reward": 2935955,
15    "timestamp": 1527907348
16  },
17  "status": "OK"
18}

cache.getBlockHeaderByHeight(options)

options.height Block height - required

Sample Data

1{
2  "block_header": {
3    "block_size": 419,
4    "depth": 2,
5    "difficulty": 200671816,
6    "hash": "7d6db7b77232d41c19d898e81c85ecf08c4e8dfa3434f975a319f6261a695739",
7    "height": 502345,
8    "major_version": 4,
9    "minor_version": 0,
10    "nonce": 130876,
11    "num_txes": 1,
12    "orphan_status": false,
13    "prev_hash": "5af657331edff98791720c23aacf72e8b6247ddba2a5c42c93984a46946abd14",
14    "reward": 2935955,
15    "timestamp": 1527907348
16  },
17  "status": "OK"
18}

License

Copyright (C) 2018 Brandon Lehmann, The TurtleCoin Developers

Please see the included LICENSE file for more information.