DOCSEARCHbyAlgolia
Submit Docs

Cardano Community Guild Operators

repository·alpha·Indexed 18 days ago

https://github.com/cardano-community/guild-operators

Tools and documentation for Cardano Stake Pool Operators (SPOs) to manage, monitor, and set up stake pools. Includes automation scripts like setup_mon.sh for Prometheus, Node Exporter, and Grafana, as well as guides for PostgreSQL 18 tuning for cardano-db-sync and recovering Byron Era funds via cardano-wallet.

Tokens
33.2K
Snippets
98
Records
149
Agent score
60%

What's inside guild-operators

  1. Overview of Koios CNTools

    alpha

    Koios CNTools is a management tool for Cardano stake pool operators designed to simplify wallet key management and pool operations. It operates primarily through a shell script interface and relies on a specific folder structure and an env configuration file located in the same directory as the script.

    Core Components:

    • cntools.sh: The main entry point script.
    • cntools.library: Internal helper functions.
    • env: Configuration file used to connect CNTools to your node.

    Companion Scripts:

    • cncli.sh: Used on the core node (block producer) for monitoring blocks, calculating leader schedules, and block validation.
    • logMonitor.sh: Used alongside cncli.sh for enhanced monitoring.

  2. Overview of community-built components

    alpha

    The following tools are built by the community to extend the functionality of a standard cardano-node setup:

    • CNTools: A 'swiss army knife' for pool operators to simplify wallet key management and pool operations.
    • gLiveView: A local node monitoring tool with an intuitive UI, useful for systemd deployments or alongside Prometheus/Grafana.
    • Topology Updater: A node-to-node discovery solution used to activate relay nodes and maintain network health.
    • Koios/gRest: A local query layer for exploring blockchain data (via dbsync) using standardized API queries.
    • Ogmios: A lightweight bridge providing a WebSockets API for local clients to communicate with cardano-node via JSON/RPC.
    • CNCLI: A Rust-based CLI tool for low-level communication with cardano-node, used for checking leader logs and sending health info to pooltool.io.
    • Cardano Signer: A tool to sign or verify hex, text, or binary data using cryptographic keys, following CIP-8 and CIP-36 standards.

  3. Find community support and educational resources

    alpha

    The Guild Operators ecosystem provides several external resources for learning and support:

    • SPO Documentation: Detailed instructions for using guild tools to manage pools. Access SPO Site.
    • Community Support FAQ: Guides on Cardano wallets, blockchain explorers, and delegation. Access FAQ.
    • Blockchain Concepts: Educational articles explaining blockchain essentials. Access Concepts.
    • Telegram Support: Use the Telegram Announcement & Support channel for news on releases and general questions regarding documentation and scripts.

  4. Identify built-in Cardano software and tools in Guild Docker images

    alpha

    The Guild Operators Docker images provide a modular environment based on Debian that includes several pre-installed Cardano software components and management tools.

    Built-in Cardano Software:

    • cardano-address
    • cardano-cli
    • cardano-hw-cli
    • cardano-node
    • cardano-submit-api
    • mithril-client
    • mithril-signer

    Built-in Tools:

    • CNTools
    • gLiveView
    • CNCLI
    • Ogmios
    • Cardano Hardware CLI
    • Cardano Signer
    • Prometheus (for monitoring)

  5. What is blockPerf.sh and how does it work?

    alpha

    The blockPerf.sh script monitors the network propagation of new blocks as seen by a local cardano-node. It is most effective when run on upstream relays to observe how new blocks are announced by remote peers.

    The script measures the latency (delay times) for several specific stages of the block lifecycle:

    1. The time from the theoretical slot time of the block generator until the block header was offered to the local node.
    2. The time until the node requested the block.
    3. The time until the node downloaded the block.
    4. The time until the node has verified and adopted the block.

    Data can be viewed as a local console stream or run as a background systemd service. Additionally, blockPerf can send this data to the TopologyUpdater server, allowing operators to compare their relay performance (receive quality and delay times) against other nodes in the network.

  6. What is gRest

    alpha

    gRest is an open-source query layer built over dbsync using PostgREST and HAProxy. It provides a RESTful API for querying Cardano blockchain data stored in a PostgreSQL database.

    Key components include:

    • PostgREST: An RPC JSON interface that provides a RESTful Web Service for the PostgreSQL database. It is a stateless, low-overhead alternative to GraphQL.
    • HAProxy: A gateway proxy used for load balancing, failover, DDoS protection, and enabling TLS for public-facing instances.

  7. Security warnings for Guild Docker images

    alpha

    The Guild Docker images may not implement all standard security best practices due to their specific functional requirements. Users should be aware of the following:

    • Docker API Exposure: Never expose the Docker API publicly. It is disabled by default.
    • Docker Socket Ownership: By default, the socket is owned by the root user and the docker group. Do not change this ownership.
    • Root Execution: Avoid running Docker containers as root where possible.
    • Privileged Mode: Use --privileged mode with extreme caution.

  8. Configure node files: config.json and topology.json

    alpha

    Customizing the node behavior requires editing two main files in the ${CNODE_HOME} directory:

    1. files/config.json

    Used for logging configurations, genesis config paths, and Prometheus backend settings.

    • PeerSharing: If running a relay node and you want connecting peers to be shared, set this to true (ensure advertise is also true in topology.json).

    2. files/topology.json

    Defines how the node connects to the network.

    • localRoots > accessPoints: Add your local nodes (e.g., your own BP or relays) here and set trustable: true for persistent connections.
    • advertise: Set to true for peer groups you want to advertise for discovery. Do not set this to true on a Block Producing (BP) node.
    • localRoots > valency (or hotValency): The number of active connections to maintain from localRoots.
    • useLedgerAfterSlot: The slot number after which the node starts connecting to peers registered as pool relays.

    Important for Block Producers (BP): To ensure a BP node remains in non-P2P mode, set useLedgerAfterSlot to -1 and ensure PeerSharing is set to false in config.json.

  9. Understand the Guild Operators Docker strategy

    alpha

    The Guild Operators uses a modular Docker strategy based on Debian. The Cardano Node image is constructed in a single stage using a specific Dockerfile (found in files/docker/node/dockerfile_bin).

    The deployment process utilizes guild-deploy.sh to perform the following tasks:

    1. Install OS prerequisites.
    2. Install Cardano software from release binaries.
    3. Add Guild-specific SPO (Stake Pool Operator) tools and node configuration files.

  10. Understand the Offline Transaction workflow

    alpha

    For high-security environments, use a combination of an Online node and an Offline node to manage transactions. This ensures sensitive signing keys never touch an internet-connected machine.

    The Workflow Pattern:

    1. Online Node: Generate a 'staging' transaction file.
    2. Transfer: Move the staging file to the Offline node.
    3. Offline Node: Use Transaction >> Sign to authorize the transaction using local signing keys.
    4. Transfer: Move the signed transaction file back to the Online node.
    5. Online Node: Use Transaction >> Submit to broadcast the transaction to the blockchain.

    Key Security Note: When creating backups on an offline node to transfer to an online node, you can choose to exclude private keys.

    • Wallet keys excluded: payment.skey, stake.skey
    • Pool keys excluded: cold.skey

    Offline Node Requirements:

    • Binaries in $PATH: cardano-cli, bech32, cardano-address.
    • OS dependencies: jq, coreutils, pkgconfig, gcc-c++, bc.
    • Configuration: A copy of genesis/config files from your online node.

  11. Understand the cardano-node folder structure

    alpha

    The deployment script creates a specific directory hierarchy. While you do not need to set CNODE_HOME at the shell level (scripts derive it at runtime), adding it to ~/.bashrc is recommended for convenience.

    Standard Directory Layout:

    • /opt/cardano/cnode/files: Configuration, genesis, and topology files (e.g., config.json, topology.json, shelley-genesis.json).
    • /opt/cardano/cnode/db: DB Store for cardano-node.
    • /opt/cardano/cnode/guild-db: DB Store for guild-specific tools (e.g., cncli, cardano-db-sync schema).
    • /opt/cardano/cnode/logs: Logs for cardano-node.
    • /opt/cardano/cnode/priv: Folder for keys (Permissions: 600).
    • /opt/cardano/cnode/scripts: Scripts to start and interact with cardano-node.
    • /opt/cardano/cnode/sockets: Socket files created by cardano-node.

  12. Changes to logging and monitoring in node 10.5.x+

    alpha

    Starting with node 10.5.x, the cardano-tracer infrastructure was introduced. The Guild Operators implementation has shifted to a minimum viable equivalent for newer config formats, which results in the following changes:

    • Monitoring: EKG monitoring is no longer used; instead, use the SimplePrometheus backend available in the node.
    • Logging Format: Logging is no longer sent to JSON files by default. Instead, logs are sent to stdout.
    • Log Management: Monitoring logs should now be handled via journald, which allows for electing JSON formats if desired.
    • Tooling Impact: Because log locations and formats have changed, tools like blockperf and logmonitor may be temporarily disabled as they require updates to read the new formats.
    • Component Updates: Logging for submitapi and dbsync configurations has also been updated to use stdout (via journald) instead of dedicated log files.