sample.env

Overview

The `sample.env` file serves as a template for environment variables necessary to configure and run the application. It defines both secret keys and public configuration parameters that the software uses to connect to APIs, set logging levels, and specify the network environment. This file is typically used as a reference to create an actual `.env` file containing sensitive information and deployment-specific values. It helps maintain a clear separation between code and configuration, enabling easier environment management across development, staging, and production setups.

Detailed Explanation of Contents

This file contains two main sections:

1. Secret Environment Variables

These variables hold sensitive information, such as API keys, which should **never** be committed to version control or exposed publicly.

• INDEXER_API_KEY
  Purpose: API key for authenticating with the Indexer service.
  Value: Empty in this sample, to be filled with the actual secret key.
  Usage: Used by backend services to securely access indexer APIs.

• RPC_API_KEY
  Purpose: API key for the RPC (Remote Procedure Call) service.
  Value: Empty in this sample, to be filled securely.
  Usage: Enables authenticated communication with blockchain or other RPC services.

2. Public Environment Variables

These are configuration parameters that define service endpoints, logging behavior, and network selection.

• INDEXER_URL
  Purpose: HTTP endpoint URL for the Indexer service.
  Example Value: https://gateway.liquify.com
  Usage: Used by components requiring RESTful access to the Indexer API.

• INDEXER_WS_URL
  Purpose: WebSocket URL for real-time communication with the Indexer service.
  Example Value: wss://gateway.liquify.com
  Usage: Used for subscribing to live updates or events from the Indexer.

• LOG_LEVEL
  Purpose: Sets the verbosity of application logging.
  Example Value: debug (typical values: debug, info, warn, error)
  Usage: Controls the detail of logs for troubleshooting or monitoring.

• NETWORK
  Purpose: Specifies the blockchain network environment.
  Example Value: mainnet (could be devnet, testnet, etc.)
  Usage: Guides the application to interact with the correct network endpoints and configurations.

• RPC_URL
  Purpose: HTTP endpoint URL for the RPC service.
  Example Value: https://gateway.liquify.com
  Usage: Used by application modules to perform RPC calls.

Usage Example

When setting up the project, developers copy `sample.env` to `.env` and fill in the secret keys:

cp sample.env .env

Then edit `.env` to add the actual API keys:

INDEXER_API_KEY=your_real_indexer_api_key
RPC_API_KEY=your_real_rpc_api_key

The application reads these environment variables at runtime (commonly via libraries like `dotenv` in Node.js or equivalents in other languages) to configure service connections.

Implementation Details and Best Practices

• Security:
  The secret keys are intentionally left empty in this sample file to prevent accidental exposure. The .env file that the application uses should be listed in .gitignore.

• Consistency:
  Using a sample environment file standardizes the configuration process for developers and deployment environments.

• Flexibility:
  Changing endpoints or log levels does not require code changes but only environment variable updates, enabling smoother configuration management.

Interaction with Other Parts of the System

• Backend Services:
  Use these environment variables to authenticate and communicate with the Indexer and RPC services.

• Logging Module:
  Reads LOG_LEVEL to determine how verbose logging should be.

• Network Configuration:
  The NETWORK variable informs modules which blockchain network to connect to, affecting API endpoints and transaction processing logic.

• Real-time Updates:
  The INDEXER_WS_URL is used by WebSocket clients in the system to listen to live data streams.

This file is foundational for the application's configuration layer, influencing multiple system components that rely on external services and environment-specific settings.

Visual Diagram

The following flowchart illustrates how the environment variables defined in this file are consumed by different parts of the application to establish configurations and service connections.

flowchart TD
    subgraph sample.env
        SECRETS[Secret Keys]
        CONFIGS[Public Configs]
    end

    SECRETS --> INDEXER_API_KEY["INDEXER_API_KEY"]
    SECRETS --> RPC_API_KEY["RPC_API_KEY"]

    CONFIGS --> INDEXER_URL["INDEXER_URL"]
    CONFIGS --> INDEXER_WS_URL["INDEXER_WS_URL"]
    CONFIGS --> LOG_LEVEL["LOG_LEVEL"]
    CONFIGS --> NETWORK["NETWORK"]
    CONFIGS --> RPC_URL["RPC_URL"]

    INDEXER_API_KEY --> BackendServices["Backend Services (API Authentication)"]
    RPC_API_KEY --> BackendServices

    INDEXER_URL --> IndexerClient["Indexer REST Client"]
    INDEXER_WS_URL --> IndexerWSClient["Indexer WebSocket Client"]
    RPC_URL --> RPCClient["RPC Client"]

    LOG_LEVEL --> LoggingModule["Logging Module"]

    NETWORK --> NetworkConfigModule["Network Configuration Module"]

    BackendServices -->|Uses| IndexerClient
    BackendServices -->|Uses| RPCClient
    IndexerWSClient -->|Receives Events| RealTimeProcessor["Real-time Data Processor"]

Summary

The `sample.env` file is a critical configuration template that defines both secret credentials and public parameters necessary for the application to connect to external APIs, set logging verbosity, and select the network environment. It is designed for ease of use, security, and flexibility, enabling developers and deployment pipelines to configure the system without modifying source code. This file underpins the connectivity and operational behavior of multiple subsystems within the software architecture.