1  # DarkFi Blockchain Explorer
  2  
  3  The DarkFi Blockchain Explorer facilitates the exploration of chain data and interaction with the DarkFi blockchain. It provides detailed insights into block and transaction activity, gas usage metrics, and native contract source code. 
  4  
  5  ## Table of Contents
  6  1. [Key Features](#key-features)
  7  2. [Network Status](#network-status)
  8  3. [Quick Start Guide](#quick-start-guide)
  9  
 10  4. [Explorer Components](#explorer-components)
 11      - [Explorer Nodes](#explorer-nodes)
 12      - [Explorer Site](#explorer-site)
 13  
 14  5. [Configuration](#configuration)
 15      - [Configuration Files](#configuration-files)
 16      - [Supported Networks](#supported-networks)
 17  
 18  6. [Feature Details](#feature-details)
 19      - [Home Page Overview](#home-page-overview)
 20      - [Block and Transaction Exploration](#block-and-transaction-exploration)
 21      - [Gas Analytics](#gas-analytics)
 22          - [Network-Wide Gas Consumption Metrics](#network-wide-gas-consumption-metrics)
 23          - [Transaction-Level Gas Consumption Metrics](#transaction-level-gas-consumption-metrics)
 24      - [Native Contract Source Code Navigation](#native-contract-source-code-navigation)
 25  
 26  ## Key Features
 27  - **DarkFi Blockchain Synchronization**: Ensures real-time synchronization of blockchain data, providing an accurate and unified view of DarkFi activity across supported networks.
 28  - **Blockchain Data Exploration**: Access detailed information about blocks and transactions.
 29  - **Gas Analytics**: Analyze gas usage metrics at both the network level and on a per-transaction basis.
 30  - **Native Contract Source Code Access**: Review the implementation details of native contract source code for improved transparency.
 31  - **Search Blocks and Transactions**: Locate specific blocks or transactions using search.
 32  
 33  ## Network Status
 34  
 35  The testnet and mainnet configurations serve as placeholders in preparation for their respective launch. When starting environment with these environment configurations , the site will connect to an Explorer Node that point to their respective darkfid networks, but currently only display the network's genesis block.
 36  
 37  In addition, testnet and mainnet configurations are currently using development servers for the site and work is ongoing for production-like setups.
 38  
 39  ## Quick Start Guide
 40  
 41  The DarkFi Explorer provides a visual interface to explore blockchains on DarkFi networks. Follow the steps below to launch explorer environments for your desired Darkfi blockchain network. 
 42  
 43  ### Prerequisites
 44  Before you begin, ensure you have the following installed and configured:
 45  - **Rust 1.86 or later**: Required for building components written in Rust (like `darkfid`, `minerd`, `explorerd`)
 46  - **Python 3.12**: Required for building and running the Explorer Site (`site`).
 47  - **Darkfi Project Dependencies**: System dependencies required to compile Darkfi code. For details, see [Darkfi Build Dependencies](../../README.md#build).
 48  - **Darkfid**: Runs DarkFi blockchain nodes on respective networks.
 49  - **Minerd**: Mines blocks and is required if Darkfid is configured with a miner JSON-RPC endpoint and the associated miner isn’t running.
 50  
 51  > **Note** When using the `make` commands in the [Quick Start Guide](#quick-start-guide), Darkfid and Minerd are automatically built when needed.
 52  
 53  ### Start Localnet Explorer Environment
 54  
 55  ```sh
 56  # Launch an explorer environment using the localnet configuration  
 57  make start-localnet
 58  ```
 59  
 60  ### Start Testnet Explorer Environment
 61  
 62  ```sh
 63  # Launch an explorer environment using the latest testnet configuration 
 64  make start-testnet
 65  ```
 66  
 67  ### Start Mainnet Explorer Environment
 68  
 69  ```sh
 70  # Launch an explorer environment using the latest mainnet configuration 
 71  make start-mainnet
 72  ```
 73  
 74  ### Start Explorer Environment in No-Sync Mode
 75  An explorer environment can be started in a no-sync mode that does not connect a darkfi blockchain network or sync new blocks, allowing you to work with an existing local explorer database. This feature is particularly useful for UI development, testing, development tasks that don't require syncing, or exploring functionality without the overhead of running a blockchain network.
 76  
 77  Below is an example of how to launch a no-sync environment configured for localnet. You can also start testnet or mainnet similarly (using `start-no-sync-testnet` or `start-no-sync-mainnet`):
 78  
 79  ```sh
 80  # Launch localnet explorer environment without connecting or syncing with a Darkfi blockchain network
 81  make start-no-sync-localnet
 82  ```
 83  
 84  > **Note** Once started, navigate to http://127.0.0.1:5000 in your browser to access the explorer interface.
 85  
 86  ### Confirming Successful Start
 87  
 88  Upon successful initialization of the Explorer environment, confirmation messages will appear in the startup logs. If these logs are not visible, the Explorer environment is still initializing. Allow sufficient time for the initialization process to complete before accessing the block explorer.
 89  
 90  ```
 91  07:09:22 [INFO] ========================================================================================
 92  07:09:22 [INFO]                    Started DarkFi Explorer Node                                        
 93  07:09:22 [INFO] ========================================================================================
 94  07:09:22 [INFO]   - Network: localnet                                 
 95  07:09:22 [INFO]   - JSON-RPC Endpoint: tcp://127.0.0.1:14567          
 96  07:09:22 [INFO]   - Database: ~/.local/share/darkfi/explorerd/localnet
 97  07:09:22 [INFO]   - Configuration: ./explorerd_config.toml
 98  07:09:22 [INFO]   - Reset Blocks: No
 99  07:09:22 [INFO] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
100  07:09:22 [INFO]   - Synced Blocks: 9                                  
101  07:09:22 [INFO]   - Synced Transactions: 9                            
102  07:09:22 [INFO]   - Connected Darkfi Node: tcp://127.0.0.1:8240       
103  07:09:22 [INFO] ========================================================================================
104  07:09:22 [INFO] All is good. Waiting for block notifications...
105  Started explorer site on localnet network (PID=31911)
106  Started localnet environment. Press Ctrl-C to stop.
107  ```
108  
109  > **Note** Localnet explorer site logs appear directly in the console, while testnet and mainnet logs are written to `~/.local/share/darkfi/explorer_site/{network}/app.log`. For non-localnet environments, the console displays: `See site logfile /home/user/.local/share/darkfi/explorer_site/{network}/app.log for server startup details`.
110  > **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”.
111  
112  The explorer site log contains the following statup details.
113  ```
114  ============================================================
115  Started Explorer Site
116  ============================================================
117  Network: localnet
118  Explorer Node Endpoint: 127.0.0.1:14567
119  Log Path: ~/.local/share/darkfi/explorer_site/localnet
120  ============================================================
121  ```
122  
123  ### Stopping the Explorer Environment
124  
125  #### Ctrl-C
126  To stop the environment, press the keyboard combination Ctrl-C and wait for all components to stop.
127  
128  #### Make Command
129  You can also stop the environment using Make:
130  ```sh
131  # Stop the running explorer environment (nodes and site)
132  make stop
133  ```
134  
135  ### Getting Help
136  ```shell
137  make help
138  ```
139  
140  ## Explorer Components
141  
142  ### Explorer Nodes
143  
144  DarkFi explorers rely on explorer nodes who are responsible for syncing with DarkFi blockchain networks. Explorer nodes function as background daemons, running continuously to ensure the Explorer database stays up-to-date. They synchronize with the latest blocks during startup and actively listen for new blocks using DarkFi's subscription interface. This ensures that the Explorer provides an accurate and consistent view of blockchain activity. Explorer nodes are implemented in Rust, designed to reliably handle real-world blockchain changes, including reorganizations (reorgs) and block updates, while maintaining data integrity.
145  
146  For more details on explorer nodes and their functionality, see [explorerd/README.md](explorerd/README.md).
147  
148  ### Explorer Site
149  
150  The Explorer Site is a web application that serves as the user interface for viewing DarkFi blockchain data. It provides an interactive way for users to explore blockchain information, analyze gas usage, and navigate contract source code. The site connects to explorer nodes to fetch real-time data, ensuring accurate and up-to-date information is provided.
151  
152  For more details on the Explorer Site, see [site/README.md](site/README.md).
153  
154  ## Configuration
155  
156  ### Configuration Files
157  
158  The Explorer uses configuration files to define `darkfid` endpoints for block synchronization, `explorerd` endpoints for retrieving blockchain data, and other settings such as log file locations. These configurations can be reviewed and updated as needed.
159  
160  | Configuration File | Description                                                                                                              |
161  | --- |--------------------------------------------------------------------------------------------------------------------------|
162  | **[Darkfid Config](../darkfid/darkfid_config.toml)** | Contains darkfid network configurations for `localnet`, `testnet`, and `mainnet`.                                        |
163  | **[Explorerd Config](./explorerd/explorerd_config.toml)** | Specifies the `darkfid` endpoint for block synchronization and the `explorerd` endpoint for retrieving synchronized data. |
164  | **[ExplorerSite Config](./site/site_config.toml)** | Defines the `explorerd` endpoints for fetching synchronized data, as well as other settings for the Explorer site.|
165  
166  ### Supported Networks
167  The Explorer is configured to support the following pre-configured DarkFi blockchain networks.
168  
169  | **Network**    | **Description**                                              |
170  | -------------- | ------------------------------------------------------------ |
171  | **`localnet`** | Ideal for development and testing in a local environment using `darkfid`'s localnet configuration. |
172  | **`testnet`**  | Used for testing the explorer with `darkfid`'s testnet network (pending availability). |
173  | **`mainnet`**  | The production environment for running the explorer on DarkFi's canonical chain (pending availability). |
174  
175  > **Note** Once the testnet and mainnet are fully available, the explorer will sync more than just the genesis blocks for these networks.
176  
177  ## Feature Details
178  
179  ### Home Page Overview
180  
181  The explorer’s home page serves as the starting point for navigating blockchain data and features. It provides a high-level overview of available resources, including:
182  - **Search Box**: Search for blocks and transactions based on hash.
183  - **At-a-Glance Summary**: View summaries of network activity, like recent blocks, native contracts, and total gas consumption.
184  - **Navigation Links**: Access block details and native contract source code, as well as navigate DarkFi social media links.
185  
186  <details>
187  <summary>Click to view the Home Page</summary>
188  <img src="docs/images/explorer-home.png" width="60%" alt="DarkFi Blockchain Explorer Home Page">
189  </details>
190  
191  ___
192  
193  ### Block and Transaction Exploration
194  The Explorer provides insights into blockchain activity by giving users the ability to view blocks, obtain transaction details, and analyze the relationships between blocks and transactions.
195  
196  #### Key Features
197  - **Block Details Overview**: Provides key information about each block.
198  - **Transaction Details**: Displays details for individual transactions.
199  - **Search Functionality**: Enables users to locate specific blocks or transactions using the Explorer's search tools.
200  - **Detail Navigation**: Allows users to navigate into block-level details from the Block Explorer home page or view transaction details from within blocks.
201  
202  #### Block Details
203  The Explorer presents detailed information about each block, offering insights into the transactions it contains and other metadata. Below, you’ll find an example of the block details view.
204  
205  <img src="docs/images/explorer-block-details.png" width="60%" alt="DarkFi Block Details Example">
206  
207  The detailed block view displays the following details.
208  
209  | **Field** | **Description** |
210  | --- | --- |
211  | **Version** | Indicates the block's version. |
212  | **Previous Block** | A navigable link to the previous block's hash. |
213  | **Block Hash** | The unique identifier of the block. |
214  | **Block Height** | The block's position within the blockchain. |
215  | **Timestamp** | The UTC time at which the block was created. |
216  | **Nonce** | The proof-of-work or equivalent nonce value for the block. |
217  | **Root** | The Merkle root summarizing the hashes of all transactions. |
218  | **Signature** | The digital signature of the block. |
219  | **Transactions** | List of transaction hashes, each navigable for detailed views. |
220  
221  #### Transaction Details
222  
223  The Explorer provides an in-depth view of individual transactions, whether accessed from a block's detailed view or using the search functionality. Below is an example of the transaction details view.
224  
225  <img src="docs/images/explorer-tx-details.png" width="60%" alt="Transaction Details Example">
226  
227  For each transaction, the Explorer displays the following details.
228  
229  | **Field** | **Description** |
230  | --- | --- |
231  | **Transaction Hash** | A unique identifier for the transaction. |
232  | **Block** | The hash of the containing block, linking back to the block’s details. |
233  | **Payload** | Call data associated with the transaction. |
234  | **Gas Consumption** | The amount of gas used for execution (see [Transaction Gas Consumption](#transaction-level-gas-consumption-metrics) for more details). |
235  
236  #### Key Benefits
237  This feature enables users to:
238  1. View key details of blockchain activity, including blocks and transactions.
239  2. Analyze relationships between blocks and transactions.
240  3. Search for specific blocks or transactions of interest.
241  4. Gain insights into gas usage across the blockchain and individual transactions.
242  
243  ## Gas Analytics
244  
245  The Explorer provides detailed analytics on gas usage, covering both network-wide metrics and transaction-level consumption. This feature empowers users to understand execution costs, identify optimization opportunities, and manage gas expenses.
246  
247  ### Key Features
248  
249  | Feature                        | Description                                                  |
250  | ------------------------------ | ------------------------------------------------------------ |
251  | **Network-Wide Gas Metrics**   | Displays gas consumption across all operations on the blockchain, categorized into multiple categories such as WASM, ZK circuits, signatures, and deployments. |
252  | **Transaction-Level Analysis** | Provides per-transaction gas usage details, allowing users to evaluate the efficiency and execution costs of individual transactions. |
253  
254  ### Network-Wide Gas Consumption Metrics
255  
256  The Explorer tracks gas consumption across the blockchain broken down by category. Below is an example of the Explorer’s network-wide gas tracking view.
257  
258  <img src="docs/images/explorer-gas-metrics-total-consumption.png" width="60%" alt="Total Gas Consumption">
259  
260  Each category is outlined in the table below.
261  
262  | Category                 | Description                                                  |
263  | ------------------------ | ------------------------------------------------------------ |
264  | **Total Gas Usage**      | The cumulative amount of gas consumed across all blockchain transactions. |
265  | **WASM Gas Usage**       | Tracks gas used by WASM-based smart contract execution.      |
266  | **ZK Circuit Gas Usage** | Monitors gas usage related to Zero-Knowledge Proof execution. |
267  | **Signature Gas Usage**  | Represents gas consumed for transaction signatures.          |
268  | **Deployment Gas Usage** | Gas required for deploying contracts on the blockchain.      |
269  
270  For each of these categories, the Explorer provides the following metrics.
271  
272  | Metric                | Description                                                  |
273  | --------------------- | ------------------------------------------------------------ |
274  | **Average Gas Usage** | The average gas spent per transaction across relevant operations. |
275  | **Minimum Gas Usage** | The smallest amount of gas recorded in any transaction.      |
276  | **Maximum Gas Usage** | The highest gas value observed across transactions.          |
277  
278  ### Transaction-Level Gas Consumption Metrics
279  
280  The Explorer provides detailed data on gas consumption for individual transactions, helping users evaluate the cost and efficiency of specific operations. Below is an example of the gas consumption view for a specific transaction.
281  
282  <img src="docs/images/explorer-gas-metrics-tx-consumption.png" width="60%" alt="Transaction Gas Consumption">
283  
284  ### Transaction Metrics
285  
286  | Metric              | Description                                                  |
287  | ------------------- | ------------------------------------------------------------ |
288  | **Total Gas Usage** | The total gas consumed by all operations within the transaction. |
289  | **WASM Gas**        | The gas used during WASM contract execution.                 |
290  | **ZK Circuit Gas**  | Gas consumed for Zero-Knowledge Proof components in the transaction. |
291  | **Signature Gas**   | Gas required for transaction signature verification.         |
292  | **Deployment Gas**  | Gas spent specifically on deploying smart contracts.         |
293  
294  ### Key Benefits
295  This feature empowers users to:
296  1. Track blockchain-wide gas consumption across various operational categories
297  2. Analyze the gas efficiency and cost of transactions, identifying resource-intensive operations and opportunities for optimization
298  3. Improve cost management by understanding precise gas usage for specific actions
299  ___
300  
301  ## Native Contract Source Code Navigation
302  
303  The Explorer allows users to inspect native contracts deployed on the DarkFi blockchain by presenting their metadata and source code. This feature enhances transparency and facilitates a better understanding of native DarkFi contract behavior.
304  
305  ### Key Features
306  - **Metadata Exploration**: Displays contract metadata such as its name and description.
307  - **Native Contract List**: Provides access to all DarkFi native contracts directly from the Explorer home page.
308  - **Source Code List for a Contract**: Displays all source files associated with a native contract.
309  - **Detailed Source File View**: Allows users to view individual source files with syntax highlighting for better readability.
310  
311  ### List of Native Contracts
312  The Explorer presents users with an organized list of native contracts on the Explorer home page.
313  
314  <img src="docs/images/explorer-native-contract-list.png" width="60%" alt="DarkFi Explorer Native Contracts List">
315  
316  ### List of Source Code for a Contract
317  
318  From the list of native contracts, users can navigate to view the individual source files associated with a specific contract.
319  
320  <img src="docs/images/explorer-source-code-list.png" width="60%" alt="DarkFi Explorer Native Contract Source Code List">
321  
322  ### Source Code View
323  
324  Users can select source files from the list to view source code content.
325  
326  <img src="docs/images/explorer-native-contract-source-code.png" width="60%" alt="DarkFi Explorer Native Source Code">
327  
328  ### Key Benefits
329  
330  This feature allows users to:
331  1. Transparently review the purpose and behavior of DarkFi native contracts
332  2. View contract source code associated with the native smart contracts
333  3. Explore Zero-Knowledge Proof implementations within the contract code
334  4. Examine interactions between associated files to understand the overall contract structure
335