sample.env

Overview

The `sample.env` file serves as a template for configuring environment variables required by the application. It defines both **secret keys** and **runtime configuration parameters** that control how the application interacts with external services, logging behavior, and network settings.

This file typically resides at the root of the project or configuration directory and is used as a reference for developers to create their own `.env` files by filling in the necessary secrets and endpoints. The environment variables declared here enable the application to:

Authenticate and authorize requests to third-party APIs (e.g., Etherscan, RPC, and Indexer APIs).
Configure URLs and WebSocket endpoints for backend services.
Set logging verbosity.
Define the blockchain network environment (e.g., mainnet).

This separation of secrets and configurable parameters supports secure and flexible deployments across development, testing, and production environments.

Detailed Explanation of Variables

Secret Environment Variables

These variables contain sensitive information such as API keys. They are left empty in `sample.env` and should be securely populated in a real `.env` file that is **excluded from version control** (e.g., via `.gitignore`).

Variable Name	Description	Expected Value	Example
`ETHERSCAN_API_KEY`	API key to access Etherscan services for blockchain data queries	String (secret)	`ABCDEF1234567890`
`INDEXER_API_KEY`	API key to authenticate requests to the Indexer backend service	String (secret)	`indexer-secret-key`
`RPC_API_KEY`	API key for accessing RPC endpoints, enabling blockchain calls	String (secret)	`rpc-abcdef123456`

Non-Secret Environment Variables

These variables control URLs, network modes, and logging levels.

Variable Name	Description	Expected Value	Example
`INDEXER_URL`	Base HTTP URL for the Indexer backend service	URL string	`https://gateway.liquify.com`
`INDEXER_WS_URL`	WebSocket URL for real-time Indexer subscription	WebSocket URL string	`wss://gateway.liquify.com`
`LOG_LEVEL`	Logging verbosity level	Enum (e.g., debug, info, error)	`debug`
`NETWORK`	Blockchain network environment	String (e.g., mainnet, testnet)	`mainnet`
`RPC_URL`	RPC endpoint URL for blockchain interaction	URL string	`https://gateway.liquify.com`

Usage Example

A developer would typically copy `sample.env` to a new `.env` file and populate the secret API keys:

cp sample.env .env

Then edit `.env`:

ETHERSCAN_API_KEY=ABCDEF1234567890
INDEXER_API_KEY=indexer-secret-key
RPC_API_KEY=rpc-abcdef123456

INDEXER_URL=https://gateway.liquify.com
INDEXER_WS_URL=wss://gateway.liquify.com
LOG_LEVEL=debug
NETWORK=mainnet
RPC_URL=https://gateway.liquify.com

The application loads these variables at startup using environment variable parsers (e.g., `dotenv` in Node.js, `python-dotenv` in Python) to configure API clients, logging, and network settings dynamically.

Important Implementation Details

Security: Secret keys should never be committed to source control. The sample.env acts as a safe template without actual secrets.
Configuration Flexibility: By decoupling configuration from code, multiple environments (development, staging, production) can be supported with minimal code changes.
WebSocket & HTTP: Both WebSocket (INDEXER_WS_URL) and HTTP (INDEXER_URL) endpoints are provided for the Indexer service, suggesting real-time data subscriptions alongside RESTful queries.
Logging: The LOG_LEVEL environment variable allows control over the verbosity of logs, facilitating debugging or production readiness.
Network Selection: The NETWORK variable indicates the blockchain network context, which affects how transactions and data are handled.

Interaction With Other System Components

API Clients: The API keys and URLs are consumed by various modules responsible for blockchain data retrieval and transaction processing.
Logging Module: The LOG_LEVEL variable configures the logging subsystem to filter messages appropriately.
Network Layer: The NETWORK and RPC_URL variables direct how the blockchain client connects and operates (e.g., mainnet vs testnet).
Indexer Service: The INDEXER_URL and INDEXER_WS_URL enable communication with the Indexer backend, likely providing indexed blockchain data and event subscriptions.

Together, these environment variables form the foundational configuration that enables seamless integration between the application and external blockchain infrastructure and services.

Visual Diagram

Below is a flowchart illustrating the role and relationships of the main environment variables in this file and their usage by system components:

flowchart TD
    subgraph ENV_VARS ["Environment Variables (sample.env)"]
        A[ETHERSCAN_API_KEY]
        B[INDEXER_API_KEY]
        C[RPC_API_KEY]
        D[INDEXER_URL]
        E[INDEXER_WS_URL]
        F[LOG_LEVEL]
        G[NETWORK]
        H[RPC_URL]
    end

    subgraph SYSTEM_COMPONENTS ["System Components"]
        I[Blockchain API Client]
        J[Indexer Service Client]
        K[Logging Module]
        L[Network Configuration]
    end

    A --> I
    C --> I
    H --> I
    G --> L
    G --> I

    B --> J
    D --> J
    E --> J

    F --> K

Summary

The `sample.env` file is a critical configuration template providing the necessary environment variables for secure, flexible, and environment-specific operation of the application. It separates secret keys from runtime parameters, enabling safe development workflows and production deployments while supporting integration with blockchain APIs, indexer services, and logging control.

*End of documentation for `sample.env`*