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.
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.
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
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 column2ALTER TABLE wallets3ADD COLUMN updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP;45-- Create a function to update the updated_at column6CREATE OR REPLACE FUNCTION update_timestamp()7RETURNS TRIGGER AS $$8BEGIN9 NEW.updated_at = NOW();10 RETURN NEW;11END;12$$ LANGUAGE plpgsql;1314-- Attach a trigger that uses the function15CREATE TRIGGER update_your_table_timestamp16BEFORE UPDATE ON wallets17FOR EACH ROW18EXECUTE FUNCTION update_timestamp();1920-- Add index21CREATE INDEX idx_wallets_updated_at ON wallets (updated_at DESC);
These queries make the following changes:
- it adds an
updated_atcolumn 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.
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.
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
listen_addresses - The first parameter you will need to edit is
listen_addresses. In essence, you will need to change:
1listen_addresses = 'localhost'
1listen_addresses = '*'
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.
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 md52host <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
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.
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.
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