Core Setup

The following guide specifies all the necessary steps to set up a Core Relay and prepare it for use with ARKScan. Before proceeding further, take note that you should ideally set up a Core instance behind a firewall with remote access to your database and a read-only user. As such, it is best to disable all public services (such as APIs and Webhooks) to reduce unnecessary overhead.

Setup

In essence, the setup process is split into two interdependent procedures, namely:

  • A Core Relay Setup, and
  • Providing Remote Access to the Core Database

You will first need to set up a Core Relay before proceeding any further. Follow the steps below and navigate to the relevant resources as and when you require them.


Set Up a Core Relay

The procedure on how to carry this out already exists, so only the second part of the setup process is explicitly discussed here.

Navigate to the Installation Guide - A Core Relay is required in order to successfully set up ARKScan. Please follow any one of the guides located here and return to this page upon completion.

Help

In principle, two means of installing ARK Core exist, namely by Using the Install Script or via Docker on Linux/macOS and Windows. Ensure that you select the method relevant to your requirements and that you adhere to the steps as closely as possible.


Enable Wallets Table - Once your Core Relay is functioning, enter ark env:paths to locate your .env file and navigate to it. Scroll to the relevant section and add CORE_WALLET_SYNC_ENABLED=true. Take note that you will need to type the full parameter out when adding it to your Environment.


Restart the Core Process - Once your configuration is saved, restart using ark relay:restart and wait while the table syncs (this may take several minutes depending on your setup, so please wait patiently). You can then run pm2 logs to view the synchronization process. If successful, you should see readouts similar to the following:

10|ark-relay | [2022-01-01 00:00:00.000] INFO: Wallets table synchronized at height 10,000,000`

Adjust the Core Wallets Table

Information

This adjustment is necessary for ARKScan versions 2.9.0 and above that make use of Meilisearch

To improve search indexing logic for adjustments being made to wallets, for example transactions coming/going to an address and new addresses that come into existence, we add an updated_at column to the wallets table. Login to your core database on the server with sudo -u postgres psql <database-name> and run the following SQL queries:

1-- Add column
2ALTER TABLE wallets
3ADD COLUMN updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP;
4
5-- Create a function to update the updated_at column
6CREATE OR REPLACE FUNCTION update_timestamp()
7RETURNS TRIGGER AS $$
8BEGIN
9 NEW.updated_at = NOW();
10 RETURN NEW;
11END;
12$$ LANGUAGE plpgsql;
13
14-- Attach a trigger that uses the function
15CREATE TRIGGER update_your_table_timestamp
16BEFORE UPDATE ON wallets
17FOR EACH ROW
18EXECUTE FUNCTION update_timestamp();
19
20-- Add index
21CREATE INDEX idx_wallets_updated_at ON wallets (updated_at DESC);

These queries make the following changes:

  • it adds an updated_at column to the wallets table, with the default value being the current time
  • it adds a database function to update the column
  • it adds a database trigger to call the update function whenever the wallet data changes
  • it adds an index to the new column

Provide Remote Access to the Core Database

This officially marks the second part of the setup process in which you will enable remote access to the Core database that ARKScan will require in order to function. Please adhere to the steps outlined below and follow them accordingly.

Information

As a result of the various available databases, <database-name> will appear in the ensuing instructions. Ensure that you replace this placeholder value with the database name relevant to your setup (so for example, sudo -u postgres psql <database-name> becomes sudo -u postgres psql ark_mainnet if you wish to make use of the ARK mainnet for your instance of ARKScan). For more on custom databases, check the configuration file located here.


Set Up ARKScan User in PostgreSQL - The next step entails creating a new ARKScan user in PostgreSQL. Remember to substitute <database-name> with the database name relevant to your setup before running the first command. The subsequent command allows you to create a new user and set an encrypted password. Please ensure that you replace <password> with an actual password to maximize security and avoid any unnecessary mishaps.

1sudo -u postgres psql <database-name>
2CREATE USER explorer WITH ENCRYPTED PASSWORD '<password>';

Once you have specified the user and password, exit psql before continuing further.

Help

When entering the create user command, observe the necessary syntactical conventions to ensure commands execute as intended. For example, failing to include the ; at the end of a line will result in your inputs failing to execute as required.


Grant Permissions to ARKScan User - The following three commands will grant the necessary permissions to your ARKScan user. Before creating permissions, ensure that you use the correct database by entering sudo -u postgres psql <database-name> first.

1grant CONNECT on DATABASE <database-name> to explorer;
2grant USAGE on SCHEMA public to explorer;
3grant SELECT on ALL tables in schema public to explorer;

Check Your New User Has Database Access - Before continuing, exit out of psql first. You will then need to specify the host in order to avoid any peer authentication issues that may arise by entering the following command.

1psql -h 127.0.0.1 -d <database-name> -U explorer -W

Search for the postgresql.conf File - Since each system is unique, you will need to locate the postgresql.conf by searching for it using the following command.

1sudo find / -name "postgresql.conf"

Access the File - Once located, you will need to access the file using nano and entering the relevant path. Take note that the path specified here is merely an example and that you will need to substitute it with the location of your postgresql.conf file in order for it to execute as intended.

1sudo nano /etc/postgresql/13/main/postgresql.conf

Edit listen_addresses - The first parameter you will need to edit is listen_addresses. In essence, you will need to change:

1listen_addresses = 'localhost'

to:

1listen_addresses = '*'

Warning

When editing listen_addresses, ensure that you remove the # at the beginning of the line if it is present, otherwise your changes will not have any effect.


Access pg_hba.conf - Having edited and saved the postgresql.conf file, you will need to access and edit the pg_hba.conf file. Fortunately this file resides in the same folder as your postgresql.conf file, so you need to alter the path as necessary in order to access the pg_hba.conf file. Once again, you will need to substitute the sample path detailed below with the one relevant to your setup before you use nano to edit the parameters.

1sudo nano /etc/postgresql/13/main/pg_hba.conf

Add Entries to pg_hba.conf - Scroll down until you see parameters listing databases and IP addresses. Once you have located the relevant section, add the following ipv4 and ipv6 entries accordingly.

1host <database-name> explorer 0.0.0.0/0 md5
2host <database-name> explorer ::/0 md5

Restart PostgreSQL - Upon inserting the required entries and saving the pg_hba.conf file, you will need to restart psql. You can carry this out by executing the following command.

1sudo /etc/init.d/postgresql restart

Open the Port - If the port is disabled in your firewall, use the following command to open it.

1sudo ufw allow 5432

Test Your Connection

Now that you have set all the parameters and configured your server, the next logical step is to first test your connection before setting it up in ARKScan. By making use of a database manager such as TablePlus , you can effectively add your server as a remote connection. Enter in the required details when prompted and click on ‘Connect.’

Database Managers such as TablePlus allow you to test your settings before altering parameters in your Environment. TablePlus is available for both macOS and Windows via their official website

Success

If everything is functioning as it should, your server connection should reveal various tables containing relevant network data. You can click on these fields to view more details regarding the server’s various operations and processes if you wish.


Update Your ARKScan Instance - Once you have successfully tested your connection, you may navigate to your .env file and alter the parameters in order to make your instance of ARKScan point to your server. Adjust the following variables according to your requirements.

1ARKSCAN_DB_HOST=<your-core-ip>
2ARKSCAN_DB_PORT=5432
3ARKSCAN_DB_DATABASE=<your-core-database-name>
4ARKSCAN_DB_USERNAME=<your-core-database-username>
5ARKSCAN_DB_PASSWORD=<your-core-database-password>

Depending on the nature of the network in question, you will need to adjust the ARKSCAN_NETWORK variable to either ARKSCAN_NETWORK=production for mainnet or ARKSCAN_NETWORK=development for devnet.

Information

If you change the network data from an ARKScan node (that is, you switch it from devnet to mainnet), you will need to clear the existing caches and rerun the commands to fetch data and resynchronize everything. You can clear all caches by running php artisan optimize:clear and subsequently re-cache your data using php artisan explorer:cache-development-data

Last updated 1 year ago
Edit Page
Share: