You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Complete reference for every environment variable used by CarbonLedger — description, type, example value, whether it is required, and how to obtain it.
cp .env.example .env
# Fill in required values, then verify:
./scripts/verify-setup.sh
For a local development environment without external API access, only the Required variables marked below are needed. Optional and production-only variables can be left blank or at their defaults.
Format Rules
Rule
Detail
Key format
SCREAMING_SNAKE_CASE. No spaces around =.
Secret keys
Stellar secret keys start with S and are 56 characters (e.g. SABCDE...). Never commit them.
Public keys
Stellar public keys (G-addresses) start with G and are 56 characters.
Contract IDs
Soroban contract IDs are 56-character StrKey strings starting with C.
USDC amounts
All USDC values stored in the contracts use stroops (1 USDC = 10,000,000 stroops). Environment variables that represent USDC amounts follow the same convention unless noted.
URLs
No trailing slash. Use https:// for all external services.
Booleans
Use true or false (lowercase).
Duration strings
JWT expiry uses the ms library format: 7d, 1h, 30m.
Quoted values
Values containing spaces (e.g. NETWORK_PASSPHRASE) must be quoted in the .env file: NETWORK_PASSPHRASE="Test SDF Network ; September 2015".
Frontend prefix
All variables consumed by Next.js client-side code must be prefixed NEXT_PUBLIC_. Variables without this prefix are server-side only.
Stellar Network
Variables that point to Stellar infrastructure endpoints.
STELLAR_NETWORK
Property
Value
Description
Selects the Stellar network. Controls which default RPC and Horizon endpoints the oracle and backend use.
Type
enum
Allowed values
testnet, mainnet
Example
STELLAR_NETWORK=testnet
Required
Yes
How to obtain
Set to testnet for local development. Change to mainnet for production.
STELLAR_RPC_URL
Property
Value
Description
Soroban RPC endpoint. The backend and oracle use this to submit contract transactions and read contract state.
Testnet: use https://soroban-testnet.stellar.org (public SDF endpoint, no API key required). Mainnet: use https://soroban-mainnet.stellar.org or a private RPC from Quicknode, Ankr, or self-hosted. For high-throughput production workloads, the public endpoint has rate limits — use a dedicated provider.
STELLAR_HORIZON_URL
Property
Value
Description
Stellar Horizon REST API endpoint. Used by the backend indexer to stream ledger events and by the frontend for account queries.
Testnet: the testnet USDC contract ID is published in the Stellar testnet asset list. Mainnet: the official Circle USDC contract ID is published at centre.io.
Oracle Keypair
The oracle keypair is used by the Python oracle services to sign monitoring data before submitting it to the carbon_oracle contract. The contract stores the public key and verifies each submission's Ed25519 signature.
ORACLE_SECRET_KEY
Property
Value
Description
Stellar secret key used by oracle services to sign contract transactions. Must match the public key registered in the oracle contract via initialize().
Type
Stellar secret key (56-char string starting with S)
Create a local database: createdb carbonledger. Then set <password> to the value of POSTGRES_PASSWORD. For production, use a managed service (AWS RDS, Supabase, Neon).
POSTGRES_PASSWORD
Property
Value
Description
Password for the carbonledger PostgreSQL user. Interpolated into DATABASE_URL by Docker Compose.
Type
string
Example
POSTGRES_PASSWORD=changeme
Required
Yes (Docker Compose)
How to obtain
Choose a strong random password. openssl rand -base64 32 generates a suitable value.
DB_POOL_MAX
Property
Value
Description
Maximum number of database connections Prisma keeps open simultaneously.
Type
integer
Default
10
Example
DB_POOL_MAX=10
Required
No
Rule of thumb
(num_cpu_cores × 2) + 1, capped at pg_max_connections / num_replicas.
DB_POOL_TIMEOUT_MS
Property
Value
Description
Milliseconds to wait for a free connection before Prisma throws P2024 (connection pool timeout).
Type
integer (milliseconds)
Default
10000
Example
DB_POOL_TIMEOUT_MS=10000
Required
No
DB_CONNECT_TIMEOUT_S
Property
Value
Description
Seconds to wait when opening a new TCP connection to PostgreSQL before timing out.
Type
integer (seconds)
Default
10
Example
DB_CONNECT_TIMEOUT_S=10
Required
No
Authentication
JWT_SECRET
Property
Value
Description
Secret used to sign and verify JWT access tokens issued by the backend API.
Type
string (min 32 characters recommended)
Example
JWT_SECRET=a-very-long-random-string-here
Required
Yes
How to obtain
Generate with openssl rand -hex 32. Rotate by restarting the backend — all existing tokens immediately become invalid.
1. Create a GCP project. 2. Enable the Earth Engine API. 3. Create a service account and grant it the Earth Engine Resource Writer role. 4. Download the JSON key file. 5. Register the service account email at code.earthengine.google.com (requires approval).
PLANET_LABS_API_KEY
Property
Value
Description
API key for Planet Labs satellite imagery (secondary validation source).
Type
string
Example
PLANET_LABS_API_KEY=pl.XXXXXXXXX
Required
No (GEE is the primary source; Planet Labs is optional supplementary data)
How to obtain
Register at planet.com and request API access under the Education & Research or Commercial tier.
GEE_WEBHOOK_SECRET
Property
Value
Description
Shared secret used to verify the HMAC-SHA256 signature on incoming Google Earth Engine webhook events received by satellite_monitor.py.
Generate with openssl rand -hex 32. Configure the same value in your GEE webhook endpoint configuration.
Price Feeds
The oracle service (price_oracle.py) fetches carbon credit benchmark prices from market data providers every 12 hours and posts them to the carbon_oracle contract.
XPANSIV_API_KEY
Property
Value
Description
API key for the Xpansiv CBL (Carbon, Biodiversity, and Land) marketplace — the primary carbon credit price data source.
Type
string
Example
XPANSIV_API_KEY=xpansiv_live_...
Required
Yes (price feed)
How to obtain
Contact Xpansiv to request API access. This requires a commercial relationship or institutional access. Sandbox keys are available for development.
TOUCAN_API_KEY
Property
Value
Description
API key for Toucan Protocol — used as a secondary price reference for on-chain carbon credit prices.
Maximum allowed size of JSON request bodies. Uses the express body-parser size format.
Type
size string
Default
10kb
Example
BODY_SIZE_LIMIT=10kb
Required
No
Allowed formats
10kb, 1mb, 500b, or a byte integer like 10240.
Oracle Service (Python — additional)
The Python oracle services (verification_listener.py, price_oracle.py, satellite_monitor.py) read some additional variables not listed in .env.example. Set these in the same .env file or as system environment variables.
BACKEND_API_URL
Property
Value
Description
Base URL of the CarbonLedger backend API. The oracle service posts monitoring results to the backend indexer.
Type
URL
Example
BACKEND_API_URL=http://localhost:3001/api/v1
Required
Yes (oracle services)
BACKEND_JWT_TOKEN
Property
Value
Description
Pre-issued JWT token for the oracle service account. The oracle uses this to authenticate against the backend API when reporting monitoring results.
Issue a long-lived service token from the backend using an admin account, or configure a dedicated oracle user and generate a token via POST /api/v1/auth/login.
Production-Only Variables
These variables are not in .env.example because they are not needed for local development. Configure them for staging and production deployments.
Variable
Description
Example
NODE_ENV
Node.js environment mode. Set to production to disable debug logging and enable performance optimisations.
NODE_ENV=production
LOG_LEVEL
Minimum log level for the backend (error, warn, info, debug, verbose).
LOG_LEVEL=info
JWT_REFRESH_SECRET
Separate secret for signing refresh tokens. Must differ from JWT_SECRET.
JWT_REFRESH_SECRET=...
JWT_REFRESH_EXPIRY
Lifetime of refresh tokens.
JWT_REFRESH_EXPIRY=30d
AWS_REGION
AWS region for CloudWatch log delivery.
AWS_REGION=us-east-1
AWS_CLOUDWATCH_GROUP
CloudWatch log group name for structured backend logs.
AWS_CLOUDWATCH_GROUP=/carbonledger/backend
EMAIL_FROM
Sender address used for outbound emails (retirement certificate delivery, alerts).
EMAIL_FROM=noreply@carbonledger.com
REDIS_SENTINELS
Comma-separated host:port pairs for Redis Sentinel failover configuration.
REDIS_SENTINELS=sentinel1:26379,sentinel2:26379
REDIS_SENTINEL_NAME
Name of the Redis master in Sentinel configuration.
REDIS_SENTINEL_NAME=mymaster
NEXT_PUBLIC_NETWORK_PASSPHRASE
Network passphrase exposed to browser for Freighter wallet configuration.
NEXT_PUBLIC_NETWORK_PASSPHRASE="Public Global Stellar Network ; September 2015"
NEXT_PUBLIC_APP_URL
Canonical public URL of the app. Used for generating QR code links in certificates.