sample.env

Overview

The `sample.env` file serves as a template for environment configuration variables required to run the application. It defines key-value pairs used to configure application settings such as API keys, network endpoints, logging levels, and network selection. This file is not intended to be used directly but rather copied and renamed (commonly to `.env`) with actual secret values filled in to prevent accidental exposure of sensitive information.

Environment variables from this file are loaded at runtime to configure the application's behavior, enabling it to connect to external services like blockchain indexers and RPC nodes, control logging verbosity, and select the network environment (e.g., mainnet).

Detailed Explanation of Variables

The file contains two main sections: **Secret Environment Variables** and **Environment Variables**.

Secret Environment Variables

These variables contain sensitive information such as API keys and should never be committed to public repositories or shared insecurely.

Variable Name	Description	Example Value
`INDEXER_API_KEY`	API key used to authenticate with the blockchain indexer service.	(empty, to be filled)
`RPC_API_KEY`	API key for accessing RPC endpoints securely.	(empty, to be filled)

Environment Variables

These variables configure non-secret runtime settings.

Variable Name	Description	Example Value
`INDEXER_URL`	The HTTPS URL endpoint of the blockchain indexer service.	`https://bchbook.nownodes.io`
`INDEXER_WS_URL`	The WebSocket URL endpoint for real-time indexer communication.	`wss:/bchbook.nownodes.io/wss` (note: likely typo, see Implementation Details)
`LOG_LEVEL`	Logging verbosity level for the application (e.g., `debug`, `info`, `warn`, `error`).	`debug`
`NETWORK`	Specifies the blockchain network environment (e.g., `mainnet`, `testnet`).	`mainnet`
`RPC_URL`	HTTPS URL endpoint for the blockchain RPC node.	`https://bch.nownodes.io`

Usage Example

Copy the template:
```
cp sample.env .env
```

Fill in secret keys:

Edit .env and add your actual API keys:

INDEXER_API_KEY=your_real_indexer_api_key_here
RPC_API_KEY=your_real_rpc_api_key_here

Run the application:
Depending on the application setup, environment variables from .env will be loaded automatically, or you may need to use a package such as dotenv in Node.js.

Implementation Details and Notes

The file follows the common .env format where each line has a KEY=VALUE assignment.
The separation between secret and non-secret variables is for clarity; in practice, all variables are loaded similarly.
URL Formats:
- The INDEXER_WS_URL value is wss:/bchbook.nownodes.io/wss but appears to have a typo: the WebSocket Secure URL scheme should be wss:// (two slashes), not wss:/.
- Correct format: wss://bchbook.nownodes.io/wss
This file does not contain any executable code, but is critical for configuring connections to external blockchain indexer and RPC services.
The environment variables here enable the application to:
- Authenticate API requests (INDEXER_API_KEY, RPC_API_KEY)
- Connect to blockchain data sources (INDEXER_URL, INDEXER_WS_URL, RPC_URL)
- Configure operational behavior (LOG_LEVEL, NETWORK)

Interaction with Other System Components

API Clients / Services: The application modules responsible for accessing blockchain data will read INDEXER_URL, INDEXER_WS_URL, and RPC_URL to establish HTTP or WebSocket connections to the respective services.
Authentication Modules: Use the API keys (INDEXER_API_KEY, RPC_API_KEY) to authenticate requests and access protected resources.
Logging Framework: Reads LOG_LEVEL to determine the verbosity of logs for debugging or production monitoring.
Network Selection Logic: Uses the NETWORK variable to select the blockchain network context, e.g., mainnet vs testnet, influencing which nodes or chain parameters are used.

Because these variables are environment-level configuration, they are injected typically at process start time and consumed primarily by the configuration or service initialization layers in the application.

Visual Diagram

The following flowchart illustrates how the environment variables defined in `sample.env` are consumed by different parts of the system to support configuration and external service interaction.

flowchart TD
    ENV_VARS[Environment Variables<br/>(From sample.env)]
    CONFIG[Configuration Loader]
    AUTH[Authentication Module]
    INDEXER_CLIENT[Blockchain Indexer Client]
    RPC_CLIENT[Blockchain RPC Client]
    LOGGER[Logging Framework]
    NETWORK_LOGIC[Network Selection Logic]

    ENV_VARS --> CONFIG
    CONFIG --> AUTH
    CONFIG --> INDEXER_CLIENT
    CONFIG --> RPC_CLIENT
    CONFIG --> LOGGER
    CONFIG --> NETWORK_LOGIC

    AUTH -->|Uses API Keys| INDEXER_CLIENT
    AUTH -->|Uses API Keys| RPC_CLIENT

Summary

sample.env is a template for defining environment variables necessary for the application to connect to blockchain services securely and configure runtime behavior.
It separates secret keys from general configuration and requires users to fill in sensitive values before deployment.
The file is essential for controlling external service endpoints, authentication, network context, and logging, enabling the modular application to operate correctly in different environments.
Proper handling and protection of this file and its secrets are critical for application security and stability.

**End of `sample.env` documentation**