mirror of
https://github.com/darkrenaissance/darkfi.git
synced 2026-01-08 22:28:12 -05:00
explorerd: enhance explorerd README with quick-start guide
This commit improves the explorerd documentation by: - Adding a "Quick-Start Guide" section allowing users to start different explorer node network configurations using a single make command - Adding "Network Status" section explaining testnet/mainnet availability - Provided more details and clarifications in the prerequisites section - Adding "Confirming Successful Start" section with startup banner example - Adding "Getting Help" section with make help command - Restructuring documentation with clearer section organization - Improving guidance for running against different network configurations
This commit is contained in:
kalm
@@ -13,22 +13,79 @@ The `explorerd` is designed to handle real-world blockchain events, such as reor
|
||||
- **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
|
||||
|
||||
## Getting Started
|
||||
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:
|
||||
## Prerequisites
|
||||
|
||||
- **Rust 1.86.0 or later**: For building and running the explorer daemon (`explorerd`).
|
||||
- **Darkfid**: Installed and configurable using [Darkfid Config](../../darkfid/darkfid_config.toml).
|
||||
- **Minerd**: Installed and configurable using [Minerd Config](../../minerd/minerd_config.toml).
|
||||
- **Darkfi Project Dependencies**: Dependencies required to compile the Darkfi code. For more details, see [Darkfi Build Dependencies](../../../README.md#build).
|
||||
- **Darkfid**: Required for running DarkFi blockchain nodes on respective networks. The make commands build the binary from source code in `../../darkfid` (if not already built in project root) and apply the appropriate network configuration.
|
||||
- **Minerd**: Needed for setups where Darkfid is configured with a miner JSON-RPC endpoint, but the configured miner is not running on the desired network. The make commands build the binary from source code in `../../minerd` (if not already built in project root) and apply the appropriate network configuration.
|
||||
|
||||
---
|
||||
## Quick-Start Guide
|
||||
|
||||
Run the following commands to run a node on respective network.
|
||||
|
||||
### Start a Localnet Node
|
||||
|
||||
```sh
|
||||
# Run a node using localnet configuration
|
||||
make start-localnet
|
||||
```
|
||||
|
||||
### Start a Testnet Node
|
||||
|
||||
```sh
|
||||
# Run a node using testnet configuration
|
||||
make start-testnet
|
||||
```
|
||||
|
||||
### Start a Mainnet Node
|
||||
|
||||
```sh
|
||||
# Run a node using mainnet configuration
|
||||
make start-mainnet
|
||||
```
|
||||
|
||||
### Stopping the Node
|
||||
|
||||
```sh
|
||||
# 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:
|
||||
|
||||
```
|
||||
03:31:37 [INFO] ========================================================================================
|
||||
03:31:37 [INFO] Started DarkFi Explorer Node
|
||||
03:31:37 [INFO] ========================================================================================
|
||||
03:31:37 [INFO] - Network: localnet
|
||||
03:31:37 [INFO] - JSON-RPC Endpoint: tcp://127.0.0.1:14567
|
||||
03:31:37 [INFO] - Database: ~/.local/share/darkfi/explorerd/localnet
|
||||
03:31:37 [INFO] - Configuration: ./explorerd_config.toml
|
||||
03:31:37 [INFO] - Reset Blocks: No
|
||||
03:31:37 [INFO] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
03:31:37 [INFO] - Synced Blocks: 8
|
||||
03:31:37 [INFO] - Synced Transactions: 8
|
||||
03:31:37 [INFO] - Connected Darkfi Node: tcp://127.0.0.1:8240
|
||||
03:31:37 [INFO] ========================================================================================
|
||||
```
|
||||
|
||||
### Getting Help
|
||||
```shell
|
||||
make help
|
||||
```
|
||||
|
||||
## Detailed Guide
|
||||
|
||||
### Configuration
|
||||
|
||||
The `explorerd` uses a TOML configuration file to manage different environment settings, located at [Explorerd Config](explorerd_config.toml). If no configuration file is provided, a default configuration file is automatically generated at `~/.config/darkfi/explorerd_config.toml` the first time the `explorerd` daemon is run. This pre-configured `explorerd` configuration is set up to connect to the DarkFi `darkfid` localnet, testnet, and mainnet networks.
|
||||
The `explorerd` uses a TOML configuration file to manage different network settings, located at [Explorerd Config](explorerd_config.toml). 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
|
||||
|
||||
@@ -57,103 +114,98 @@ rpc_listen = "tcp://127.0.0.1:14567"
|
||||
|
||||
**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
|
||||
|
||||
### 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)
|
||||
|
||||
The `explorerd` daemon is pre-configured to support the following DarkFi blockchain environments:
|
||||
|
||||
- **`localnet`**: Ideal for development and testing in a local environment using `darkfid`'s localnet configuration.
|
||||
- **`testnet`**: Used for testing the explorer with `darkfid`'s testnet network (pending availability).
|
||||
- **`mainnet`**: The production environment for running the explorer on DarkFi's canonical chain (pending availability).
|
||||
|
||||
These blockchain environments are defined in the `darkfid` configuration file, located at [Darkfid Config](../darkfid/darkfid_config.toml). The pre-configured `explorerd` network settings are configured to connect to the `darkfid` nodes running these networks.
|
||||
For more details about these darkfid networks, see the [Darkfid Configuration](../../darkfid/darkfid_config.toml).
|
||||
|
||||
> **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](../explorerd_config.toml) 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`:
|
||||
|
||||
```toml
|
||||
[network_config."localnet".rpc]
|
||||
rpc_listen = "tcp://127.0.0.1:8240"
|
||||
```
|
||||
|
||||
- `explorerd_config.toml`:
|
||||
|
||||
```toml
|
||||
[network_config."localnet"]
|
||||
endpoint = "tcp://127.0.0.1:8240"
|
||||
```
|
||||
|
||||
### Installation
|
||||
|
||||
Navigate to the `explorerd` directory, build the binary using `make`, and install it:
|
||||
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:
|
||||
|
||||
```bash
|
||||
cd bin/explorer/explorerd
|
||||
make install
|
||||
```
|
||||
|
||||
> Use `make` without `install` to build the `explorerd` binary in `bin/explorerd` without installing it.
|
||||
|
||||
---
|
||||
### Running an Explorer Node
|
||||
|
||||
### Running the Daemon
|
||||
#### 1. Start Supporting Nodes
|
||||
|
||||
#### 1. Configure the Daemons
|
||||
##### Using darkfid's networks
|
||||
|
||||
- **For Darkfid Localnet**: Explorerd is pre-configured to connect to the respective `darkfid` networks. No additional configuration is required when running `explorerd` without a configuration file.
|
||||
- **For Custom Configurations**: To create a custom configuration file, use [explorerd_config.toml](../explorerd_config.toml) 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`:
|
||||
|
||||
```toml
|
||||
[network_config."localnet".rpc]
|
||||
rpc_listen = "tcp://127.0.0.1:8240"
|
||||
```
|
||||
|
||||
- `explorerd_config.toml`:
|
||||
|
||||
```toml
|
||||
[network_config."localnet"]
|
||||
endpoint = "tcp://127.0.0.1:8240"
|
||||
```
|
||||
|
||||
- **For Contrib/Localnet Networks**: If you're using a `contrib/localnet` network, update the `endpoint` in your `explorerd_config.toml` to match the `rpc_listen` endpoint in the respective darkfid configuration.
|
||||
|
||||
> For information on configuring `darkfid` and `minerd`, refer to their respective documentation.
|
||||
|
||||
#### 2. Start Supporting Daemons
|
||||
|
||||
##### Running Against `darkfid's localnet`
|
||||
|
||||
Start the `minerd` and `darkfid` daemons using their default configurations.
|
||||
Start the `minerd` and `darkfid` daemons using their configurations.
|
||||
|
||||
```bash
|
||||
# Start the mining daemon using default settings
|
||||
# Start the mining daemon
|
||||
minerd
|
||||
|
||||
# Start darkfid using default settings on localnet
|
||||
# Start darkfid (example uses localnet)
|
||||
darkfid --network localnet
|
||||
```
|
||||
|
||||
##### Running Against `contrib/localnet/darkfid-single-node`
|
||||
> Replace `localnet` with `testnet` or `mainnet` to connect to those networks instead.
|
||||
|
||||
Run the DarkFi single-node.
|
||||
##### Using the single-node development environment
|
||||
|
||||
Run the DarkFi single-node development environment.
|
||||
|
||||
```bash
|
||||
# Change directory and start contrib/localnet/singlenode
|
||||
# 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
|
||||
|
||||
#### 3. Start the `explorerd` Daemon
|
||||
##### Syncing with `darkfid's localnet`
|
||||
#### 2. Start the `explorerd` Daemon
|
||||
|
||||
Run the `explorerd` daemon to sync with `darkfid's` localnet blockchain data.
|
||||
##### Connecting to darkfid networks
|
||||
|
||||
Run the `explorerd` daemon to sync with the darkfid instance.
|
||||
|
||||
```bash
|
||||
# Start the explorer daemon using pre-configured localnet configuration
|
||||
# Start the explorer daemon (example uses localnet)
|
||||
explorerd --network localnet
|
||||
```
|
||||
|
||||
##### Syncing with Custom DarkFi Blockchain Endpoint
|
||||
> Replace `localnet` with `testnet` or `mainnet` to connect to those networks instead.
|
||||
|
||||
Run the `explorerd` daemon using a custom configuration with updated `darkfid` endpoint:
|
||||
##### Connecting to custom networks
|
||||
|
||||
To connect to a custom blockchain network, provide a configuration file with your specific network settings:
|
||||
|
||||
```bash
|
||||
# Run explorerd using a custom configuration
|
||||
# Run explorerd with a custom configuration
|
||||
explorerd -c explorerd-config.toml --network localnet
|
||||
```
|
||||
|
||||
> Ensure the `endpoint` in `explorerd-config.toml` is updated to match the desired `darkfid` endpoint.
|
||||
|
||||
---
|
||||
> 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.
|
||||
Reference in New Issue
Block a user