# Dotenv Files Reference

Summary of `.env*` files across the workspace: what each defines and where to get values. **Never commit real `.env` files**; use the examples/templates below.

---

## Root / workspace

| File | Purpose | Key variables |
|------|---------|----------------|
| **`.env.example`** (repo root) | Proxmox workspace: infra, NPM, Cloudflare, Chain 138, OMNIS, alerts, APIs | `PROXMOX_*`, `CLOUDFLARE_*`, `NPM_*`, `ETHEREUM_MAINNET_RPC`, `RPC_URL_138`, `COINGECKO_API_KEY`, `ETHERSCAN_API_KEY`, `UNIFI_*`, `DATABASE_URL`, `JWT_*`, OMNIS/The Order, Tezos/Etherlink, alerts |
| **`.env`** (repo root) | Your local overrides; copy from `.env.example` | Same as above; fill placeholders |

---

## smom-dbis-138 (contracts & deployment) — **single source**

**`smom-dbis-138/.env`** (copy from **`smom-dbis-138/.env.example`**) is the **single source** for the whole subproject: deploy scripts, **relay** (services/relay), **token-aggregation** (services/token-aggregation), and **frontend** (frontend-dapp). Fill this file once; relay and token-aggregation load it automatically when run from repo root or service dir. For the frontend, copy the `VITE_*` vars into `frontend-dapp/.env.local` for local dev (or set in CI for production build).

| File | Purpose | Key variables |
|------|---------|----------------|
| **`smom-dbis-138/.env.example`** | Template for the single .env | Deploy: `PRIVATE_KEY`, `RPC_URL_138`, `ETHEREUM_MAINNET_RPC`, `INFURA_*`, `ETHERSCAN_API_KEY`, bridge/CCIP/reserve addresses. Relay: same RPC/CCIP/PRIVATE_KEY. Token-aggregation: `CHAIN_138_RPC_URL` / `CHAIN_651940_RPC_URL` (or `RPC_URL_138`), `DATABASE_URL`, `COINGECKO_*`, `LOCKBOX_138`, `CHAIN_138_DODO_PMM_INTEGRATION`. Frontend: `VITE_*` (copy to frontend-dapp/.env.local). |
| **`smom-dbis-138/.env`** | Your values; copy from `.env.example` | **Required**: `PRIVATE_KEY`, `RPC_URL_138`, `ETHEREUM_MAINNET_RPC`. Optional: Infura, Etherscan, contract addresses, DATABASE_URL, VITE_*, etc. |
| **`smom-dbis-138/.env.alerts`** | Alerting (if used) | Alert webhooks / recipients |
| **`smom-dbis-138/terraform/phases/phase1/.env.chain138`** | Terraform phase1 – Chain 138 | `RPC_URL`, `PRIVATE_KEY`, Chain 138 CCIP/LINK/WETH addresses |
| **`smom-dbis-138/terraform/phases/phase1/.env.mainnet`** | Terraform phase1 – Ethereum mainnet | `RPC_URL` (Infura/Alchemy), `PRIVATE_KEY`, mainnet CCIP/LINK/WETH, `ETHERSCAN_API_KEY`, thirdweb |
| **`terraform/phases/phase1/config/env.chain138.example`** | Example for Chain 138 phase1 | See `env.chain138.example` |
| **`terraform/phases/phase1/config/env.mainnet.example`** | Example for mainnet phase1 | `RPC_URL=https://mainnet.infura.io/v3/<KEY>` or Alchemy; `PRIVATE_KEY`, thirdweb, Etherscan |

---

## smom-dbis-138 services

Both **relay** and **token-aggregation** load **`smom-dbis-138/.env`** first (single source). Optional per-service `.env` or `.env.local` can override for that service only.

| File | Purpose | Key variables |
|------|---------|----------------|
| **`services/token-aggregation/.env.example`** | Reference only; prefer vars in **smom-dbis-138/.env** | `CHAIN_138_RPC_URL` (or `RPC_URL_138`), `CHAIN_651940_RPC_URL`, `DATABASE_URL`, `COINGECKO_*`, `CHAIN_138_DODO_PMM_INTEGRATION`. Optional: `ROUTING_REGISTRY_JSON_PATH` (override path to config/routing-registry.json). For bridge quote API (QuoteService): `LIFI_ENABLED`, `LIFI_API_URL`, `JUMPER_ENABLED`, `JUMPER_API_URL` (see smom-dbis-138/env.additions.example). |
| **`services/token-aggregation/.env`** | Optional overrides | Only if you need service-specific overrides |
| **`services/relay/.env`** | Optional overrides | Relay already loads **smom-dbis-138/.env** first |
| **`services/relay/.env.local`** | Optional overrides | **Do not commit** if it contains relayer private key; prefer **smom-dbis-138/.env** (PRIVATE_KEY or RELAYER_PRIVATE_KEY) |
| **`services/state-anchoring-service/.env`** | State anchoring service | Service-specific (RPC, keys as needed) |
| **`services/transaction-mirroring-service/.env`** | Transaction mirroring service | Service-specific (RPC, keys as needed) |

---

## smom-dbis-138 frontend

**VITE_*** variables are listed in **smom-dbis-138/.env.example** (Frontend section). For local dev, copy those into **`frontend-dapp/.env.local`** (Vite reads only from the app directory). For production builds, set them in CI or in `frontend-dapp/.env.production`.

| File | Purpose | Key variables |
|------|---------|----------------|
| **`frontend-dapp/.env.example`** | Reference; see **smom-dbis-138/.env.example** Frontend section | `VITE_WALLETCONNECT_PROJECT_ID`, `VITE_THIRDWEB_CLIENT_ID`, `VITE_RPC_URL_138`, `VITE_ETHERSCAN_API_KEY`, `VITE_SAFE_SERVICE_URL`, `VITE_SENTRY_DSN`, `VITE_ENV` |
| **`frontend-dapp/.env.local`** | Local dev (Vite requires .env in app dir) | Copy `VITE_*` from **smom-dbis-138/.env** or `.env.example` |

---

## config/production

| File | Purpose | Key variables |
|------|---------|----------------|
| **`config/production/.env.production.example`** | Production env template | `CHAIN138_RPC`, `ETHEREUM_MAINNET_RPC` (Infura/Alchemy), trustless bridge contract addresses, multisig, monitoring, `PRIVATE_KEY`, alerting |

---

## metamask-integration / chain138-snap

| File | Purpose | Key variables |
|------|---------|----------------|
| **`chain138-snap/.env.example`** | Snap publish / companion | `NPM_ACCESS_TOKEN`, optional `GATSBY_SNAP_API_BASE_URL`, `SNAP_ORIGIN` |
| **`chain138-snap/.env`** | Local snap config | Copy from `.env.example` |
| **`chain138-snap/packages/site/.env.production.dist`** | Snap site production | `SNAP_ORIGIN`, `GATSBY_SNAP_API_BASE_URL` (token-aggregation API for market/bridge/swap) |

---

## OMNIS

| File | Purpose | Key variables |
|------|---------|----------------|
| **`OMNIS/.env.example`** | OMNIS frontend | `VITE_API_URL`, `VITE_USE_REAL_API`, `VITE_SANKOFA_PHOENIX_*`, `VITE_WS_URL` |
| **`OMNIS/backend/.env.example`** | OMNIS backend | `PORT`, `DATABASE_URL`, `JWT_*`, `SANKOFA_PHOENIX_*`, storage (local/S3/Azure), SMTP, `SENTRY_DSN` |
| **`OMNIS/backend/.env`** | Local backend config | Copy from backend `.env.example` |

---

## Other projects

| File | Purpose | Key variables |
|------|---------|----------------|
| **`dbis_core/.env.example`** | dbis_core (alerts, OTC, Chain 138) | `SLACK_WEBHOOK_URL`, `PAGERDUTY_*`, `EMAIL_ALERT_*`, `CRYPTO_COM_*`, `CHAIN138_RPC_URL` |
| **`phoenix-deploy-api/.env.example`** | Phoenix Deploy API (Gitea webhook/deploy) | `PORT`, `GITEA_URL`, `GITEA_TOKEN`, optional `PHOENIX_DEPLOY_SECRET` |
| **`unifi-api/.env.example`** | UniFi API (UDM Pro) | `UNIFI_UDM_URL`, `UNIFI_API_KEY`, `UNIFI_VERIFY_SSL` |
| **`the-order/services/legal-documents/.env.example`** | Legal documents (e-signature, e-filing) | `E_SIGNATURE_BASE_URL`, `E_FILING_ENABLED` |
| **`explorer-monorepo/frontend/.env.example`** | Explorer frontend | `NEXT_PUBLIC_API_URL`, `NEXT_PUBLIC_CHAIN_ID` |
| **`ProxmoxVE/api/.env.example`** | Proxmox API (Mongo) | `MONGO_USER`, `MONGO_PASSWORD`, `MONGO_IP`, `MONGO_PORT`, `MONGO_DATABASE` |
| **`omnl-fineract/.env.example`** | OMNL Fineract | Fineract API URL/tenant/auth |
| **`miracles_in_motion/.env.example`** | MIM app | App-specific env |

---

## RPC / Infura usage

- **Root `.env.example`** and **smom-dbis-138 `.env.example`** document:
  - `ETHEREUM_MAINNET_RPC` (e.g. `https://eth.llamarpc.com` or `https://mainnet.infura.io/v3/<PROJECT_ID>`).
  - Optional: `INFURA_PROJECT_ID`, `INFURA_PROJECT_SECRET` (scripts build Infura URLs and Basic Auth; see `docs/deployment/INFURA_ENDPOINTS_REFERENCE.md` and `RPC_URLS_AND_INFURA_ACCESS.md` in smom-dbis-138).
- **Terraform mainnet** (`env.mainnet.example`): `RPC_URL=https://mainnet.infura.io/v3/<YOUR_INFURA_KEY>` or Alchemy.
- **Production config**: `ETHEREUM_MAINNET_RPC` with Infura or Alchemy.

---

## Security notes

1. **Never commit** real `.env` or `.env.local` files; ensure they are in `.gitignore`.
2. **Relay**: `smom-dbis-138/services/relay/.env.local` contains a relayer private key; keep it local and rotate if ever exposed.
3. **Deploy keys**: Prefer HSM/vault; if in files, use `smom-dbis-138/.env` or root `.env` only and restrict permissions (`chmod 600`).
4. Use **strong, unique secrets** for JWT, DB, and API keys (min 32 chars where applicable).