# Quilibrium - 2.1 - Bloom ## Quick Start Running production nodes from source is no longer recommended given build complexity. Please refer to our release information to obtain the latest version. ## Running From Source Ensure you have all required dependencies. ### Ubuntu Linux For Ubuntu Linux, you can install these by running the following from the project root: ./scripts/install-deps-ubuntu.sh ### macOS Because Mac varies in terms of dependency management, we recommend installing Xcode for build toolchain, then use homebrew to install openssl. Other dependencies via homebrew are the dynamically linked version of the libraries, so we recommend manually fetching the required packages: curl https://gmplib.org/download/gmp/gmp-6.3.0.tar.xz > /tmp/gmp.tar.xz pushd /tmp/ tar xvf gmp.tar.xz pushd gmp-6.3.0 ./configure make make check sudo make install popd git clone https://github.com/flintlib/flint.git pushd flint git checkout flint-3.0 ./bootstrap.sh ./configure \ --prefix=/usr/local \ --with-gmp=/usr/local \ --with-mpfr=/usr/local \ --enable-static \ --disable-shared \ CFLAGS="-O3" make sudo make install popd popd From there, you can trigger generation of all dependencies to build the node with: task build_node_arm64_macos ## gRPC/REST Support If you want to enable gRPC/REST, add the following entries to your config.yml: listenGrpcMultiaddr: listenRESTMultiaddr: Please note: this interface, while read-only, is unauthenticated and not rate- limited. It is recommended that you only enable if you are properly controlling access via firewall or only query via localhost. ## Prometheus Metrics Quilibrium nodes expose comprehensive Prometheus metrics for monitoring and observability. The metrics are organized across several subsystems: ### Disk Monitoring (`disk_monitor` namespace) Tracks disk usage and space metrics for the node's data directory. - `disk_monitor_usage_percentage` - Current disk usage percentage - `disk_monitor_total_bytes` - Total disk space in bytes - `disk_monitor_used_bytes` - Used disk space in bytes - `disk_monitor_free_bytes` - Free disk space in bytes ### P2P Networking (`blossomsub` namespace) Monitors the BlossomSub peer-to-peer protocol performance. - `blossomsub_*_total` - Various operation counters (add_peer, remove_peer, join, leave, graft, prune, etc.) - `blossomsub_*_messages` - Message count histograms for IHave, IWant, IDontWant messages ### Consensus Time Reel (`quilibrium.time_reel` subsystem) Tracks consensus timing, fork choice, and blockchain tree operations. - `frames_processed_total` - Total frames processed (by type and status) - `equivocations_detected_total` - Equivocation detection counter - `head_changes_total` - Blockchain head changes (advances vs reorganizations) - `reorganization_depth` - Depth histogram of blockchain reorganizations - `tree_depth` / `tree_node_count` - Current tree structure metrics - `fork_choice_evaluations_total` - Fork choice algorithm executions ### Dynamic Fees (`quilibrium.dynamic_fees` subsystem) Monitors fee voting and calculation based on sliding window averages. - `fee_votes_added_total` / `fee_votes_dropped_total` - Fee vote tracking - `current_fee_multiplier` - Current calculated fee multiplier - `sliding_window_size` - Current number of votes in window - `fee_vote_distribution` - Distribution histogram of fee votes ### Event Distribution (`quilibrium.event_distributor` subsystem) Tracks internal event processing and distribution. - `events_processed_total` - Events processed by type - `subscribers_count` - Current active subscribers - `broadcasts_total` - Event broadcast counter - `uptime_seconds` - Distributor uptime ### Hypergraph State (`quilibrium.hypergraph` subsystem) The most comprehensive metrics tracking the CRDT hypergraph operations. #### Core Operations - `add_vertex_total` / `remove_vertex_total` - Vertex operations - `add_hyperedge_total` / `remove_hyperedge_total` - Hyperedge operations - `*_duration_seconds` - Operation timing histograms #### Lookups and Queries - `lookup_vertex_total` / `lookup_hyperedge_total` - Lookup counters - `get_vertex_total` / `get_hyperedge_total` - Get operation counters #### Transactions - `transaction_total` - Transaction counters by status - `commit_total` / `commit_duration_seconds` - Commit metrics #### Proofs - `traversal_proof_create_total` / `traversal_proof_verify_total` - Proof operations - `traversal_proof_duration_seconds` - Proof timing ### Execution Intrinsics (`quilibrium.intrinsics` subsystem) Monitors the execution engine's intrinsic operations. - `materialize_total` / `materialize_duration_seconds` - State materialization - `invoke_step_total` / `invoke_step_errors_total` - Step execution - `commit_total` / `commit_errors_total` - State commits - `state_size_bytes` - Current state size by intrinsic type ### gRPC Metrics Standard gRPC server and client metrics are automatically registered, including request duration, message sizes, and in-flight requests. ### App Consensus Engine (`quilibrium.app_consensus` subsystem) Monitors shard-specific consensus operations for application shards. - `frames_processed_total` - Total frames processed (by app_address and status) - `frame_processing_duration_seconds` - Frame processing time - `frame_validation_total` - Frame validation results - `frame_proving_total` / `frame_proving_duration_seconds` - Frame proving metrics - `frame_publishing_total` / `frame_publishing_duration_seconds` - Frame publishing metrics - `transactions_collected_total` - Transactions collected for frames - `pending_messages_count` - Current pending message count - `executors_registered` - Current number of registered executors - `engine_state` - Current engine state (0=stopped through 7=stopping) - `current_difficulty` - Current mining difficulty - `current_frame_number` - Current frame number being processed - `time_since_last_proven_frame_seconds` - Time elapsed since last proven frame ### Global Consensus Engine (`quilibrium.global_consensus` subsystem) Monitors global consensus operations across all shards. - `frames_processed_total` - Total global frames processed (by status) - `frame_processing_duration_seconds` - Global frame processing time - `frame_validation_total` - Global frame validation results - `frame_proving_total` / `frame_proving_duration_seconds` - Global frame proving metrics - `frame_publishing_total` / `frame_publishing_duration_seconds` - Global frame publishing metrics - `shard_commitments_collected` - Number of shard commitments collected - `shard_commitment_collection_duration_seconds` - Time to collect shard commitments - `executors_registered` - Current number of registered shard executors - `engine_state` - Current engine state (0=stopped through 7=stopping) - `current_difficulty` - Current global consensus difficulty - `current_frame_number` - Current global frame number - `time_since_last_proven_frame_seconds` - Time elapsed since last proven global frame - `global_coordination_total` / `global_coordination_duration_seconds` - Global coordination metrics - `state_summaries_aggregated` - Number of shard state summaries aggregated ## Development Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information on how to contribute to this repository. ## License + Interpretation Significant portions of Quilibrium's codebase depends on GPL-licensed code, mandating a minimum license of GPL, however Quilibrium is licensed as AGPL to accomodate the scenario in which a cloud provider may wish to coopt the network software. The AGPL allows such providers to do so, provided they are willing to contribute back the management code that interacts with the protocol and node software. To provide clarity, our interpretation is with respect to node provisioning and management tooling for deploying alternative networks, and not applications which are deployed to the network, mainnet status monitors, or container deployments of mainnet nodes from the public codebase.