Introduced reusable utility functions to streamline JSON-RPC parameter extraction and validation. These functions aim to reduce the amount of code needed to extract RPC parameters. Error handling provides additional context by providing the parameter name responsible for invalid JSON error. Added `TryFrom` trait implementations for converting `JsonResult` into a `JsonResponse` or `JsonError`.
New utility functions include:
- `parse_json_string`: Extracts a `String` from a `JsonValue`.
- `parse_json_number`: Extracts a `f64` from a `JsonValue`.
- `parse_json_array_string`: Extracts a `String` from a `JsonValue` array at a specific index.
- `parse_json_array_number`: Extracts a `f64` from a `JsonValue` array at a specific index.
- `parse_json_response_string`: Extracts a `String` result from a `JsonResponse`.
- `to_json_array`: Converts a `JsonValue` into a JSON array (`Vec<JsonValue>`).
- `validate_empty_params`: Ensures that JSON parameters are empty.
This update introduces a dedicated `sync` module, moving explorer synchronization-related logic from the RPC layer to the service layer. The RPC block code has been separated from the explorer's synchronization and reorganization logic. By creating a `sync` module, synchronization—one of the most complex and integral aspects of the explorer's functionality—has been isolated. This restructuring provides a cleaner separation of concerns and simplifies the management of synchronization complexity.
Updates include:
- Created `explorer/service/sync` module and moved the following functions from `rpc/blocks.rs`:
- `sync_blocks`
- `subscribe_blocks`
- `reorg_blocks` (renamed from process_sync_blocks_reorg)
- Updated `mod.rs` to include the `sync` module definition
- Added `darkfid_client` to `ExplorerService` to fetch blocks from a Darkfi blockchain network during sync
- Updated the `contracts.rs` test module setup method to use the new `ExplorerService` constructor
Updates include:
- Updated `explorer/README` quick start guide with instructions on starting an explorer environment (site + explorerd) in no-sync mode (skipping blockchain node connections)
- Updated `explorer/explorerd/README` quick start guide with details on running `explorerd` in no-sync mode
This commit adds targets to the explorer's Makefiles for starting the explorer in no-sync mode. This allows node environments to launch without connecting to a Darkfi blockchain network, relying instead on existing explorer databases. A `check-contracts` target was added to ensure required WASM files are built to start explorerd in no-sync mode. This setup enhances the mode implementation by simplifying the process of starting environments without sync.
Summary of Updates:
- Introduced `start-no-sync-%` targets in `explorer/Makefile` and `explorer/explorerd/Makefile`
- Added `await-startup-no-sync-%` in `explorer/explorerd/Makefile` to wait for explorerd startup while skipping the Darkfid connection and sync
- Implemented a `check-contracts` target to verify the presence of required contract artifacts and build them if necessary
Introduced a `no-sync` mode to the `explorerd` daemon, allowing the application to operate solely on a local explorer database without connecting to a `darkfid` blockchain network or syncing new blocks. 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 node or miner.
This setup reduces resource consumption and accelerates the development workflow by avoiding the need to sync or connect to a blockchain network when it is not needed. It also simplifies the build setup, as the explorer can run without building `darkfid` or `minerd`, reducing dependencies.
Updates include:
- Added a `--no-sync` CLI argument to toggle this mode
- Updated the sync logic to skip tasks like `subscriber_task` and `listener_task` when `no-sync` mode is enabled
- Enhanced the `Explorerd` struct to support conditional connection handling
- Updated the startup banner to display `(No-Sync Mode)` and to show "Not connected" for the connected node in `no-sync` mode
Refactored Darkfid JSON-RPC interaction methods into the new `DarkfidRpcClient` struct. This change consolidates functionality for reuse across ownership boundaries and introduces support for operating the explorer in no-sync mode.
Summary of Updates:
- Created `DarkfidRpcClient` and moved core methods like `ping` and block retrieval (`get_block_by_height`, `get_last_confirmed_block`) from `Explorerd` into it
- Updated `rpc_client` to use the `RwLock<Option<RpcClient>>` type for internally immutability and defer its creation to the `connect` method, allowing initialization without an active connection
- Added a `connect` method to establish connections to Darkfid on demand
- Updated the `stop` method to set the `RpcClient` to `None`
- Renamed and updated the `request` method to return an error when a request is made without an active connection to Darkfid
- Updated the `Explorerd` struct and implementation to integrate with `DarkfidRpcClient`
- Updated the `explorerd` binary to explicitly call `connect`
Design considerations:
- Changed `Explorerd.darkfid_client` to an `Arc` and used an `RwLock` for `DarkfidRpcClient.rpc_client` to enable shared access across ownership boundaries
- Updated `RpcClient` to be an `Option`, deferring initialization until `connect` is called. This allows startup without an active connection (`None`), supporting use cases like the explorer no-sync mode
- The `RwLock` in `DarkfidRpcClient` provides internal mutability for the connection state, ensuring that callers remain unaffected by implementation changes, such as adding a `connect` function to the `RpcClient` to delegate connection management and removing the need for `DarkfidRpcClient` to handle the connection state
Future considerations:
- The `RwLock` may be removed later by refactoring `RpcClient` for lazy connections with a `connect` method, but is kept for now to avoid wider system changes
- Plan to move `DarkfidRpcClient` to the Darkfi SDK, laying the foundation for an easy-to-use client to accelerate the creation of future Darkfi DApps
This commit reorganizes the project structure by grouping RPC, service, and store functionalities into dedicated module folders:
- `rpc`: Handles JSON-RPC interactions, migrated from `rpc_*.rs` (e.g., `rpc_transactions.rs` → `rpc/transactions.rs`)
- `service`: structured to contain the core logic for block synchronization, chain data access, metadata storage/retrieval, and statistics computation
- `store`: manages persistent storage for blockchain, contracts, metrics, and metadata
This structural refactor introduces no functional changes.
Benefits:
- Simplifies the crate root
- Groups related functionality into cohesive module boundaries
- Removes need for file prefixes and suffixes (e.g., `rpc_`, `_store`) by relying on folder-based module names for context (e.g., `rpc::blocks`, `store::metrics`)
- Enhances separation of concerns with defined responsibilities across the `rpc`, `service`, and `store` modules
- Implements domain-based boundaries that reflect the system's architecture
- Aims to improve maintainability and readability, particularly for new contributors
This commit cleans up the explorerd Makefile by:
- Adding named variables for all binary and configuration paths
- Enhancing the `bundle_contracts_src` target's documentation
- Cleaning up path handling to use variable references
- Improving comments in the `start-%` target to explain the workflow
- Updating all project root path references to use the `$(PROJECT_ROOT)` variable
- Reorganizing the `await-startup-%` target to group it with other targets
This commit streamlines the prerequisites section and adds a note indicating that Darkfid and Minerd are automatically built when using the make commands referenced in the Quick Start Guide.
This update improves documentation usability by providing more context in the prerequisites section and adding step-by-step guidance for verifying a successful Explorer environment startup.
Summary of Updates:
- Refactored the prerequisites section for better clarity and organization
- Introduced a new "Confirming Successful Start" section with guidance on environment initialization
- Updated the Quick Start Guide overview paragraph
- Adjusted the Table of Contents to reflect the prerequisites refactor
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 enhances the process termination mechanism in the 'stop' target by:
- Adding a check to verify that a PID is running before attempting to terminate it
- Implementing a more graceful termination approach by first sending SIGTERM (15) and only using SIGKILL (9) as a fallback
This commit replaces the GNU tar-specific `--transform` flag with a more portable solution, ensuring contract bundling works correctly on both Linux and BSD/macOS systems. It also includes witness proof JSON files in the native contract source code.
Summary of Updates
- Removed dependency on the GNU-specific `--transform` option
- Specified PAX format explicitly (`--format=pax`) for better cross-platform compatibility
- Refactored to use a temporary directory structure that mirrors the desired archive layout before generating tar files
- Included proof witness JSON files as part of the native contract bundling
Updated the README's explorer home image to reflect the latest version, which includes a network label indicating the network the explorer is running on. Currently, "localnet" is the default, with plans to switch to testnet as the default once it is released.
This commit enhances the explorer README by updating the quick-start guide to work with new enhancements that automatically start node environments including installing missing dependencies. Additionally, it clarifies the current network status for testnet and mainnet environments.
Summary of Updates:
- Added Quick-Start Guide section to README documenting new make commands to start explorer environments
- Added Network Status section explaining the current placeholder state of testnet and mainnet
- Reorganized and updated the prerequisites section to reflect automatic building from source for missing node dependencies
- Added help command information (make help) for quick reference
- Updated table of contents to reflect new organization
This commit enhances the explorer site README by adding a quick-start guide. Additionally, it clarifies the current network status for testnet and mainnet environments, and improves the overall document organization.
Summary of Updates:
- Added Quick-Start Guide section to README documenting new make commands for server management
- Added Network Status section explaining the current placeholder state of testnet and mainnet
- Reorganized README structure into Quick-Start and Detailed Guide sections for better navigation
- Added help command information (make help) for quick reference
It's possible that we cannot find a host on any active hostlist if
the host has been blacklisted just prior to the downgrade inside
subscribe_on_stop(). Instead of panicking, we simply return an error
and do not proceed with the downgrade operation.
This commit adds the ability to start an explorer environment with a single command. The new Makefile addition streamlines the process of working with the DarkFi explorer across various network configurations, catering to users with diverse needs.
The implementation automates startup and shutdown for explorer environments while managing dependencies efficiently, ensuring that missing components are automatically built. It also launches the explorer site (UI), verifying that all required dependencies are installed beforehand. The startup process is orchestrated so that `darkfid` initializes first, followed by `explorerd`, and the UI is launched after verifying that the explorer node is fully operational.
These improvements allow a diverse community of users to focus on what matters most to them without concern for environment setup, startup, or shutdown.
For usage details, run: `make help`
Key Features:
- Single-command to start/stop explorer environments for Darkfi localnet, testnet, or mainnet networks
- Automatic dependency management and node building
- Graceful shutdown with a single keyboard interrupt (Ctrl-C)
- Sequential startup to prevent race conditions
- Organized node logging for each network (localnet, testnet, mainnet)
- Enhanced `make help` help documentation
Enhanced Makefile with capabilities to automate the startup and shutdown of explorerd and its dependencies using a single `make` command. These additions create a streamlined user experience for running explorer nodes across the DarkFi networks, orchestrating the process by automatically building necessary dependencies prior to starting an explorer node environment. Ordered startup sequencing has been implemented to ensure darkfid starts before launching explorerd, with a mechanism to wait for explorerd to complete initialization to avoid startup race conditions.
The implementation maintains PID tracking for graceful process shutdown. Additionally, it organizes logs by network type (localnet, testnet, mainnet) in dedicated directories (`~/.local/share/darkfi/logs/NETWORK`) that are monitored to determine when nodes are initialized.
To view a list of available make commands (targets), run: `make help`.
Key Features:
- Single Command Launch: Provides targets to start explorer node environments with a single command (`make start-localnet/testnet/mainnet`)
- Automatic Dependency Checks and Builds: Automatic dependency resolution that builds missing `darkfid`, `explorerd`, and `minerd` binaries before starting nodes
- Graceful Shutdown: Added graceful network shutdown capability with PID tracking (`make stop`)
- Ordered Initialization: Implemented ordered startup sequencing for network nodes, ensuring `darkfid` starts before launching `explorerd`, and waiting for explorerd to complete initialization before it is marked as started
- Organized Logging: Logs for each started network (localnet, testnet, mainnet) are saved in their respective directories (~/.local/share/darkfi/logs/NETWORK)
- Log Monitoring: Implemented log monitoring to ensure that nodes are not started before their dependencies are ready
- Error Handling: Ensures invalid or unsupported network arguments are reported with an error message
- Add help target with organized documentation of available commands
- Rename 'stop-server' target to more concise 'stop'
- Fix Python executable path (use generic 'python' instead of hard-coded path)
- Reorganize sections for better logical grouping
- Generalized naming to explorer site
- Added console statements to show the testnet and mainnet log locations on startup to see server startup details
Introduced a Makefile to streamline the setup, startup, and shutdown of the Flask Explorer site across different networks (localnet, testnet, mainnet). It simplifies server management and cleanup with straightforward commands.
In future iterations, `testnet` and `mainnet` environments may transition to production-ready setups (e.g., running behind a reverse proxy). This implementation serves as a starting point and is expected to be expanded upon.
Summary of Updates:
- Automatic virtual environment setup and dependency installation (`all`, ``install` targets)
- Added targets to start the Flask server for localnet, testnet, and mainnet networks
- Implemented the use of a `flask.pid` file to track the Flask server’s process ID (PID), enabling proper process termination during the `stop-server` target
- Provided a `clean` target to remove the virtual environment and reset the workspace
This commit enables users to identify which network the explorer site is currently running, improving clarity for users navigating the site.
- Added a `<div>` in `base.html` to display the current network in the nav bar
- Updated `app.py` to store the network environment in app config, making it accessible for use in the nav bar
- Renamed references from env to network in app.py
- Added new CSS variables: `--color-input-background: #3B3B3B;`, `--color-source-code-link: #D1CDC7;`, `--color-text-primary: #D1CDC7;`
- Set the default color of the content container to `--color-text-primary`
- Updated the search input to explicitly set the background color (`--color-input-background`) and border color (`--color-border-primary`)
- Explicitly set the table text color to `--color-text-primary`
- Overrode Bootstrap's default `pre` and `pre code` styles to use `--color-text-primary`
Created the initial top-level README documentation for the DarkFi Blockchain Explorer, with the expectation of future refinements, updates to align with the latest UI design, and the addition of more details over time.
Summary of Updates:
- Introduced a project description, highlighting the Explorer’s purpose and core functionalities
- Added a Key Features section outlining the Explorer's capabilities
- Provided a Quick Start Guide with prerequisites, installation steps, and instructions for running on localnet
- Documented Explorer Components, including the explorer nodes and web interface
- Included a Configuration section covering configuration files and supported networks
- Detailed Feature Highlights, such as block exploration, gas analytics, and contract source navigation
- Integrated initial explorer screenshots to help with clarity and user guidance
Expanded site README documentation to provide updated instructions reflecting the latest code.
Summary of Updates:
- Updated overall project description
- Included a key features section detailing core site functionality
- Reorganized the Usage section into a Getting Started section, separating prerequisites, installation, and running the application
- Moved supporting daemons and explorerd-related setup to explorerd/README.md and explorer/README.md
- Added a configuration section describing the site's configuration options
- Added a Logging section providing insights on the site's use of logs, log locations, log output, and log level configuration
Upon restarting darkirc, messages from paired identities (i.e. users
who have exchanged and configured chacha keypairs) on unjoined
channels would be nevertheless be delivered. IRC clients like
`weechat` would ignore such events, but other clients such as `ERC`
would deliver such messages without joining the channel resulting in
confusing "phantom" channels popping up.
Added a README to document the `explorerd` daemon, including its key functionality, configuration, supported networks, setup, and instructions for running it.
Summary of Updates:
- Added an overview of `explorerd` functionality, including synchronization, reorg mitigation, and real-time updates
- Documented key features such as full blockchain synchronization and analytics support
- Included a configuration section with example configurations aligned to DarkFi network setups
- Documented supported networks (`localnet`, `testnet`, and `mainnet`)
- Provided instructions for building, installing, configuring, and starting explorer nodes
- Included steps to start supporting daemons (`darkfid` and `minerd`) for synchronization
