Skip to content

Commit 2cce6d4

Browse files
author
kalm
committed
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
1 parent c4e2294 commit 2cce6d4

1 file changed

Lines changed: 115 additions & 63 deletions

File tree

‎bin/explorer/explorerd/README.md‎

Lines changed: 115 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -13,22 +13,79 @@ The `explorerd` is designed to handle real-world blockchain events, such as reor
1313
- **Real-Time Updates**: Leverages DarkFi's subscription interface to receive live block and transaction data.
1414
- **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.
1515

16-
---
16+
## Network Status
1717

18-
## Getting Started
18+
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.
1919

20-
### Prerequisites
21-
Before you begin, ensure you have the following installed and configured:
20+
## Prerequisites
2221

2322
- **Rust 1.86.0 or later**: For building and running the explorer daemon (`explorerd`).
24-
- **Darkfid**: Installed and configurable using [Darkfid Config](../../darkfid/darkfid_config.toml).
25-
- **Minerd**: Installed and configurable using [Minerd Config](../../minerd/minerd_config.toml).
23+
- **Darkfi Project Dependencies**: Dependencies required to compile the Darkfi code. For more details, see [Darkfi Build Dependencies](../../../README.md#build).
24+
- **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.
25+
- **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.
2626

27-
---
27+
## Quick-Start Guide
28+
29+
Run the following commands to run a node on respective network.
30+
31+
### Start a Localnet Node
32+
33+
```sh
34+
# Run a node using localnet configuration
35+
make start-localnet
36+
```
37+
38+
### Start a Testnet Node
39+
40+
```sh
41+
# Run a node using testnet configuration
42+
make start-testnet
43+
```
44+
45+
### Start a Mainnet Node
46+
47+
```sh
48+
# Run a node using mainnet configuration
49+
make start-mainnet
50+
```
51+
52+
### Stopping the Node
53+
54+
```sh
55+
# Stop the running explorer node
56+
make stop
57+
```
58+
59+
### Confirming Successful Start
60+
61+
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:
62+
63+
```
64+
03:31:37 [INFO] ========================================================================================
65+
03:31:37 [INFO] Started DarkFi Explorer Node
66+
03:31:37 [INFO] ========================================================================================
67+
03:31:37 [INFO] - Network: localnet
68+
03:31:37 [INFO] - JSON-RPC Endpoint: tcp://127.0.0.1:14567
69+
03:31:37 [INFO] - Database: ~/.local/share/darkfi/explorerd/localnet
70+
03:31:37 [INFO] - Configuration: ./explorerd_config.toml
71+
03:31:37 [INFO] - Reset Blocks: No
72+
03:31:37 [INFO] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
73+
03:31:37 [INFO] - Synced Blocks: 8
74+
03:31:37 [INFO] - Synced Transactions: 8
75+
03:31:37 [INFO] - Connected Darkfi Node: tcp://127.0.0.1:8240
76+
03:31:37 [INFO] ========================================================================================
77+
```
78+
79+
### Getting Help
80+
```shell
81+
make help
82+
```
83+
84+
## Detailed Guide
2885

2986
### Configuration
3087

31-
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.
88+
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.
3289

3390
#### Example Configuration
3491

@@ -57,103 +114,98 @@ rpc_listen = "tcp://127.0.0.1:14567"
57114

58115
**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.
59116

60-
---
61-
62-
### Supported DarkFi Blockchain Networks
63-
64-
The `explorerd` daemon is pre-configured to support the following DarkFi blockchain environments:
117+
#### Supported DarkFi Blockchain Networks
65118

66-
- **`localnet`**: Ideal for development and testing in a local environment using `darkfid`'s localnet configuration.
67-
- **`testnet`**: Used for testing the explorer with `darkfid`'s testnet network (pending availability).
68-
- **`mainnet`**: The production environment for running the explorer on DarkFi's canonical chain (pending availability).
119+
The explorer daemon comes pre-configured to automatically connect to the following DarkFi's blockchain environments:
120+
- **`localnet`**: For development and testing in a local environment
121+
- **`testnet`**: For testing on DarkFi's test network (pending availability)
122+
- **`mainnet`**: For production use on DarkFi's main network (pending availability)
69123

70-
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.
124+
For more details about these darkfid networks, see the [Darkfid Configuration](../../darkfid/darkfid_config.toml).
71125

72126
> **Note**: Once the testnet and mainnet are fully available, the explorer will sync more than just the genesis blocks for these networks.
73127
74-
### Installation
128+
#### Custom Configuration
75129

76-
Navigate to the `explorerd` directory, build the binary using `make`, and install it:
130+
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.
77131

78-
```bash
79-
cd bin/explorer/explorerd
80-
make install
81-
```
132+
**Example Alignment**:
82133

83-
> Use `make` without `install` to build the `explorerd` binary in `bin/explorerd` without installing it.
134+
- `darkfid_config.toml`:
84135

85-
---
136+
```toml
137+
[network_config."localnet".rpc]
138+
rpc_listen = "tcp://127.0.0.1:8240"
139+
```
140+
141+
- `explorerd_config.toml`:
86142

87-
### Running the Daemon
143+
```toml
144+
[network_config."localnet"]
145+
endpoint = "tcp://127.0.0.1:8240"
146+
```
88147

89-
#### 1. Configure the Daemons
148+
### Installation
90149

91-
- **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.
92-
- **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.
150+
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.
93151

94-
**Example Alignment**:
152+
From the `explorerd` directory:
95153

96-
- `darkfid_config.toml`:
97-
98-
```toml
99-
[network_config."localnet".rpc]
100-
rpc_listen = "tcp://127.0.0.1:8240"
101-
```
102-
103-
- `explorerd_config.toml`:
104-
105-
```toml
106-
[network_config."localnet"]
107-
endpoint = "tcp://127.0.0.1:8240"
108-
```
154+
```bash
155+
make install
156+
```
109157

110-
- **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.
158+
> Use `make` without `install` to build the `explorerd` binary in `bin/explorerd` without installing it.
111159
112-
> For information on configuring `darkfid` and `minerd`, refer to their respective documentation.
160+
### Running an Explorer Node
113161

114-
#### 2. Start Supporting Daemons
162+
#### 1. Start Supporting Nodes
115163

116-
##### Running Against `darkfid's localnet`
164+
##### Using darkfid's networks
117165

118-
Start the `minerd` and `darkfid` daemons using their default configurations.
166+
Start the `minerd` and `darkfid` daemons using their configurations.
119167

120168
```bash
121-
# Start the mining daemon using default settings
169+
# Start the mining daemon
122170
minerd
123171

124-
# Start darkfid using default settings on localnet
172+
# Start darkfid (example uses localnet)
125173
darkfid --network localnet
126174
```
127175

128-
##### Running Against `contrib/localnet/darkfid-single-node`
176+
> Replace `localnet` with `testnet` or `mainnet` to connect to those networks instead.
129177
130-
Run the DarkFi single-node.
178+
##### Using the single-node development environment
179+
180+
Run the DarkFi single-node development environment.
131181

132182
```bash
133-
# Change directory and start contrib/localnet/singlenode
183+
# Change directory and start the single-node environment
134184
cd contrib/localnet/darkfid-single-node
135185
./tmux_sessions.sh
136186
```
187+
> Ensure you update your explorerd configuration file to point to the single node network
188+
189+
#### 2. Start the `explorerd` Daemon
137190

138-
#### 3. Start the `explorerd` Daemon
139-
##### Syncing with `darkfid's localnet`
191+
##### Connecting to darkfid networks
140192

141-
Run the `explorerd` daemon to sync with `darkfid's` localnet blockchain data.
193+
Run the `explorerd` daemon to sync with the darkfid instance.
142194

143195
```bash
144-
# Start the explorer daemon using pre-configured localnet configuration
196+
# Start the explorer daemon (example uses localnet)
145197
explorerd --network localnet
146198
```
147199

148-
##### Syncing with Custom DarkFi Blockchain Endpoint
200+
> Replace `localnet` with `testnet` or `mainnet` to connect to those networks instead.
201+
202+
##### Connecting to custom networks
149203

150-
Run the `explorerd` daemon using a custom configuration with updated `darkfid` endpoint:
204+
To connect to a custom blockchain network, provide a configuration file with your specific network settings:
151205

152206
```bash
153-
# Run explorerd using a custom configuration
207+
# Run explorerd with a custom configuration
154208
explorerd -c explorerd-config.toml --network localnet
155209
```
156210

157-
> Ensure the `endpoint` in `explorerd-config.toml` is updated to match the desired `darkfid` endpoint.
158-
159-
---
211+
> 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.

0 commit comments

Comments
 (0)