darkfi/bin/explorer/explorerd/README.md

Explorerd

The explorerd is a Rust-based daemon responsible for running a DarkFi Explorer node to synchronize blockchain data with DarkFi nodes across multiple networks. During startup, it syncs missing or outdated blocks and then listens for live updates to ensure the Explorer provides accurate and up-to-date information about blockchain activity, including blocks, transactions, and key metrics such as gas consumption.

The explorerd is designed to handle real-world blockchain events, such as reorganizations ("reorgs"), missing blocks, and divergences between networks. Its primary purpose is to ensure a consistent view of DarkFi blockchain data across different networks. For its storage layer, it leverages sled to take advantage of its performance, scalability, and reliability.

---

Key Features

• Full Blockchain Synchronization: Ensures the Explorer's database reflects the current state of the DarkFi blockchain by syncing missing or outdated block data.
• Reorg Mitigation: Detects and resolves chain reorganizations to maintain alignment with the respective networks.
• Real-Time Updates: Leverages DarkFi's subscription interface to receive live block and transaction data.
• On-The-Fly Metric Calculations: Computes analytics and blockchain metrics for use in the Explorer's UI. This includes maintaining data such as running totals, min/max values, and transaction counts when processing blocks, allowing for efficient gas metric calculations without iterating through previous transactions.

Network Status

The testnet and mainnet configurations serve as placeholders in preparation for their respective launch. When starting daemons with these configurations, each node will connect to their respective darkfid network, but currently only sync the network's genesis block. Once the DarkFi blockchain testnet and mainnet are fully available, the explorer daemon will sync blocks beyond genesis for these networks.

Prerequisites

Before you begin, ensure you have the following installed and configured:

• Rust 1.86 or later: Required for building components written in Rust (like darkfid, explorerd).
• Darkfi Project Dependencies: System dependencies required to compile DarkFi code (see Darkfi Build Dependencies).
• Darkfid: Runs DarkFi blockchain nodes on respective networks.

Note

When using the make commands in the Quick Start Guide, Darkfid is automatically built when needed.

Quick-Start Guide

Run the following commands to run a node on respective network.

Start a Localnet Node

# Run a node using localnet configuration 
make start-localnet

Start a Testnet Node

# Run a node using testnet configuration 
make start-testnet

Start a Mainnet Node

# Run a node using mainnet configuration 
make start-mainnet

Start in No-Sync Mode

You can run explorerd in a no-sync mode that does not connect to any nodes or sync blocks. This approach is useful if you only need to work with an existing local explorer database, perform tests, or work on the site UI without running blockchain nodes or miners (which can be resource-intensive).

Below is an example of how to launch a no-sync environment for localnet. You can also start testnet or mainnet in the same manner (for example, using start-no-sync-testnet or start-no-sync-mainnet).

# Launch an explorer without connecting to or syncing with any blockchain nodes
make start-no-sync-localnet

Stopping the Node

# Stop the running explorer node
make stop

Confirming Successful Start

When a DarkFi Explorer Node successfully starts, users should a startup banner displaying the node's configuration details and current sync status. Here is a successful localnet node startup example:

[INFO] ========================================================================================
[INFO]                    Started DarkFi Explorer Node
[INFO] ========================================================================================
[INFO]   - Network: localnet
[INFO]   - JSON-RPC Endpoint: tcp://127.0.0.1:14567
[INFO]   - Database: ~/.local/share/darkfi/explorerd/localnet
[INFO]   - Configuration: ./explorerd_config.toml
[INFO]   - Reset Blocks: No
[INFO] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[INFO]   - Synced Blocks: 8
[INFO]   - Synced Transactions: 8
[INFO]   - Connected Darkfi Node: tcp://127.0.0.1:28345
[INFO] ========================================================================================

Note

In no-sync mode, you will see “Started DarkFi Explorer Node (No-Sync Mode)” in the banner header, and the “Connected Darkfi Node:” line will show “Not connected”.

Getting Help

make help

Detailed Guide

Configuration

The explorerd uses a TOML configuration file to manage different network settings, located at Explorerd Config. These settings are configured to automatically connect to DarkFi blockchain nodes running on localnet, testnet, and mainnet. When running an explorer daemon for the first time without a configuration file, the default configuration file is automatically copied to ~/.config/darkfi/explorerd_config.toml. Once this file exists, running explorerd again will automatically start a node based on this configuration.

Example Configuration

Below is an example of a localnet configuration for explorerd (~/.config/darkfi/explorerd_config.toml):

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Localnet Configuration
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[network_config."localnet"]

# Path to daemon database
database = "~/.local/share/darkfi/explorerd/localnet"

# darkfid JSON-RPC endpoint
endpoint = "tcp://127.0.0.1:28345"

## Localnet JSON-RPC settings
[network_config."localnet".rpc]
# JSON-RPC listen URL
rpc_listen = "tcp://127.0.0.1:14567"

# Disabled RPC methods
#rpc_disabled_methods = []

Note: When updating the configuration, ensure the endpoint field matches the rpc_listen endpoint in the respective darkfid configuration, and that the database and rpc_listen paths are consistent with your environment.

Supported DarkFi Blockchain Networks

The explorer daemon comes pre-configured to automatically connect to the following DarkFi's blockchain environments:

• localnet: For development and testing in a local environment
• testnet: For testing on DarkFi's test network (pending availability)
• mainnet: For production use on DarkFi's main network (pending availability)

For more details about these darkfid networks, see the Darkfid Configuration.

Note

: Once the testnet and mainnet are fully available, the explorer will sync more than just the genesis blocks for these networks.

Custom Configuration

To create a custom explorerd configuration, use Explorerd Configuration as a template and modify it as needed. Ensure that the endpoint in the explorerd configuration matches the rpc_listen value in the corresponding darkfid_config.toml file, enabling proper connection to the corresponding DarkFi blockchain node.

Example Alignment:

• darkfid_config.toml:

  [network_config."localnet".rpc]
  rpc_listen = "tcp://127.0.0.1:28345"
  

• explorerd_config.toml:

  [network_config."localnet"]
  endpoint = "tcp://127.0.0.1:28345"
  

Installation

The explorerd binary can be installed to your system path using the make install command, which places it in ~/.cargo/bin/explorerd. This directory is typically included in your PATH, making the command accessible system-wide.

From the explorerd directory:

make install

Use make without install to build the explorerd binary in bin/explorerd without installing it.

Running an Explorer Node

1. Start Supporting Nodes

Using darkfid's networks

Start the darkfid daemon using their configurations.

# Start darkfid (example uses localnet) 
darkfid --network localnet

Replace localnet with testnet or mainnet to connect to those networks instead.

Using the single-node development environment

Run the DarkFi single-node development environment.

# Change directory and start the single-node environment
cd contrib/localnet/darkfid-single-node
./tmux_sessions.sh

Ensure you update your explorerd configuration file to point to the single node network

2. Start the explorerd Daemon

Connecting to darkfid networks

Run the explorerd daemon to sync with the darkfid instance.

# Start the explorer daemon (example uses localnet)
explorerd --network localnet

Replace localnet with testnet or mainnet to connect to those networks instead.

Connecting to custom networks

To connect to a custom blockchain network, provide a configuration file with your specific network settings:

# Run explorerd with a custom configuration
explorerd -c explorerd-config.toml --network localnet

Update the endpoint in your explorerd-config.toml to point to your custom darkfid instance. The --network parameter can be set to localnet, testnet, or mainnet to match your target network configuration.