Alephium explorer backend

Development

1. Install the dependencies

You need to have Postgresql and sbt installed in your system.

2. Create the database

Start the postgresql service.

psql postgres # or `psql -U postgres` depending on your OS

Ensure that the postgres role exists, and if not, create it. List all roles:
```
postgres=# \du
```
Create postgres role:
```
postgres=# CREATE ROLE postgres WITH LOGIN;
```
Then, create the database:
```
postgres=# CREATE DATABASE explorer;
```

3. Start the server

sbt app/run

4. Single Jar

sbt app/assembly

The resulting assembly file will appear in app/target/scala-2.13/ directory.

5. Restore archived database

Syncing all data from scratch can take a while, you can choose to start from a snapshot instead. Snapshots are available at https://archives.alephium.org/ Download the explore-db dump you want and simply run:

psql database_name < dump_file

Please note that database_name must have been created before, see point 2 on how to do it.

Querying hashes

Hash strings are stored as bytea. To query a hash string in SQL use the Postgres function decode which converts it to bytea.

select *
from "utransactions"
where "hash" = decode('f25f43b7fb13b1ec5f1a2d3acd1bebb9d27143cdc4586725162b9d88301b9bd7', 'hex');

6. Configuration

There are two ways to configure the application:

Environment variables

Every value in application.conf file can be overridden by an environment variable.

export BLOCKFLOW_NETWORK_ID = 1
export DB_NAME = "testnet"

Using `user.conf` file

The same way it's done in our full node, you can override the application.conf file by creating a user.conf file in the EXPLORER_HOME folder, which default to ~/.alephium-explorer-backend.

alephium.blockflow.network-id = 1
db.db.name = "testnet"

Benchmark

1. Create benchmark database

The benchmark database (set via dbName) should exist:

CREATE DATABASE benchmarks;

2. Set benchmark duration

Update the time value in the following annotation in DBBenchmark to set the benchmark run duration:

@Measurement(iterations = 1, time = 1, timeUnit = TimeUnit.MINUTES)

3. Executing benchmarks

Execute the following sbt commands to run JMH benchmarks

sbt benchmark/jmh:run

Testing

The tests are using the Postgresql database and the default postgres table.

sbt test

Scaladoc

To generate scala-doc run: sbt unidoc

Referencing external libraries in scala-docs

To reference external libraries in scala-docs make sure the library is recognised by adding an apiMapping.

See scalaDocsAPIMapping in build.sbt file as a reference for creating this apiMapping for an external library.

def myLibraryAPIMapping(classPath: Classpath, scalaVersion: String): (sbt.File, sbt.URL) =
  ??? //follow `scalaDocsAPIMapping` in build.sbt

//add the apiMapping to the project that depends on `myLibrary`
apiMappings ++=
  Map(
    myLibraryAPIMapping(
      classPath = (Compile / fullClasspath).value,
      scalaVersion = scalaVersion.value
    )
  )

Node Customization

The steps below are for developers who want to reference a full node on another computer, such as a Raspberry Pi, that is on the same subnet.

Explorer: `/app/src/main/resources/application.conf`

blockflow {
    host = "full-node-ip-address"
    port = 12973

    direct-clique-access = false
    direct-clique-access = ${?BLOCKFLOW_DIRECT_CLIQUE_ACCESS}

    network-id = 0
    network-id = ${?BLOCKFLOW_NETWORK_ID}
    groupNum = 4
    api-key = "full-node-api-key"
}

Full Node: `user.conf`

alephium.api.api-key = "full-node-api-key"
alephium.api.network-interface = "0.0.0.0"

alephium.network.bind-address  = "0.0.0.0:9973"
alephium.network.internal-address  = "full-node-ip-address:9973"
alephium.network.coordinator-address  = "full-node-ip-address:9973"

alephium/explorer-backend