From e384fc541adf7cf2fe5f64c7be2afaa5afbf6eb1 Mon Sep 17 00:00:00 2001 From: SONIA Date: Fri, 26 Jun 2026 22:32:57 +0000 Subject: [PATCH] docs: document environment variables and secret injection (#287) - New docs/environment-variables.md covering all backend and frontend vars - Per-network RPC URL and passphrase reference table - Local dev, testnet, and mainnet example configs - Secret injection guidance for GitHub Actions, Docker, and CI/CD - Notes on validate-env.sh and frontend startup validation --- docs/environment-variables.md | 192 ++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 docs/environment-variables.md diff --git a/docs/environment-variables.md b/docs/environment-variables.md new file mode 100644 index 0000000..27fc3bb --- /dev/null +++ b/docs/environment-variables.md @@ -0,0 +1,192 @@ +# Environment Variables & Secret Injection + +This document covers every environment variable used by CosmosVote — scripts, deployment, and the frontend — with examples for local development and production. + +--- + +## Quick Start + +```bash +# Backend / scripts +cp .env.example .env + +# Frontend +cp frontend/.env.example frontend/.env.local +``` + +Never commit `.env` or `.env.local` to version control. Both files are listed in `.gitignore`. + +--- + +## Backend & Script Variables (`.env`) + +### Network + +| Variable | Required | Default | Description | +|----------|----------|---------|-------------| +| `NETWORK` | ✅ | `local` | Target network. One of `local`, `testnet`, `mainnet`. | +| `STELLAR_RPC_URL` | ✅ | `http://localhost:8000` | Soroban RPC endpoint. | +| `STELLAR_NETWORK_PASSPHRASE` | ✅ | Standalone passphrase | Network passphrase for transaction signing. | + +**Per-network values:** + +| Network | `STELLAR_RPC_URL` | `STELLAR_NETWORK_PASSPHRASE` | +|---------|-------------------|------------------------------| +| `local` | `http://localhost:8000` | `Standalone Network ; February 2021` | +| `testnet` | `https://soroban-testnet.stellar.org` | `Test SDF Network ; September 2015` | +| `mainnet` | `https://soroban-mainnet.stellar.org` | `Public Global Stellar Network ; September 2015` | + +### Admin Keys + +| Variable | Required | Description | +|----------|----------|-------------| +| `STELLAR_SECRET_KEY` | ✅ | Stellar secret key (`S...`, 56 chars) for the deploying admin account. **Never share or commit this value.** | + +For production, inject this via your CI/CD secrets manager — see [Secret Injection](#secret-injection) below. + +### Contract Addresses + +Populated automatically by `scripts/deploy.sh`. Set manually if deploying outside the script. + +| Variable | Required | Description | +|----------|----------|-------------| +| `GOVERNANCE_CONTRACT_ID` | ✅ (post-deploy) | Deployed governance contract address (`C...`, 56 chars). | +| `TOKEN_CONTRACT_ID` | ✅ (post-deploy) | Deployed token contract address (`C...`, 56 chars). | + +### Governance Parameters + +These configure the on-chain governance contract at initialization time. + +| Variable | Required | Default | Description | +|----------|----------|---------|-------------| +| `MIN_PROPOSAL_BALANCE` | ❌ | `1000000` | Minimum token balance (in base units) to submit a proposal. Set `0` to disable. | +| `PROPOSAL_COOLDOWN` | ❌ | `86400` | Minimum seconds between proposals per address. Set `0` to disable. | +| `RESTRICT_ADMIN_VOTE` | ❌ | `true` | If `true`, the admin cannot vote on proposals they created. | + +### Token Parameters + +| Variable | Required | Default | Description | +|----------|----------|---------|-------------| +| `INITIAL_TOKEN_SUPPLY` | ❌ | `1000000000` | Initial token supply (base units) minted to the admin address on first deploy. | + +--- + +## Frontend Variables (`frontend/.env.local`) + +Vite exposes only variables prefixed with `VITE_` to the browser bundle. + +| Variable | Required | Description | +|----------|----------|-------------| +| `VITE_NETWORK` | ✅ | Network to connect to. One of `testnet`, `mainnet`. | +| `VITE_GOVERNANCE_CONTRACT_ID` | ✅ | Governance contract address (`C...`, 56 chars). | +| `VITE_TOKEN_CONTRACT_ID` | ✅ | Token contract address (`C...`, 56 chars). | + +The frontend validates these at startup via `validateConfig()` in `src/config.ts` and shows a clear error banner if they are missing or malformed. + +--- + +## Example Configurations + +### Local Development + +```bash +# .env +NETWORK=local +STELLAR_RPC_URL=http://localhost:8000 +STELLAR_NETWORK_PASSPHRASE="Standalone Network ; February 2021" +STELLAR_SECRET_KEY=SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +GOVERNANCE_CONTRACT_ID= +TOKEN_CONTRACT_ID= +MIN_PROPOSAL_BALANCE=0 +PROPOSAL_COOLDOWN=0 +RESTRICT_ADMIN_VOTE=false +INITIAL_TOKEN_SUPPLY=1000000000 +``` + +```bash +# frontend/.env.local +VITE_NETWORK=testnet +VITE_GOVERNANCE_CONTRACT_ID=CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA +VITE_TOKEN_CONTRACT_ID=CBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB +``` + +### Testnet + +```bash +# .env +NETWORK=testnet +STELLAR_RPC_URL=https://soroban-testnet.stellar.org +STELLAR_NETWORK_PASSPHRASE="Test SDF Network ; September 2015" +STELLAR_SECRET_KEY=SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +GOVERNANCE_CONTRACT_ID=C... +TOKEN_CONTRACT_ID=C... +MIN_PROPOSAL_BALANCE=1000000 +PROPOSAL_COOLDOWN=86400 +RESTRICT_ADMIN_VOTE=true +INITIAL_TOKEN_SUPPLY=1000000000 +``` + +### Production (Mainnet) + +Never store `STELLAR_SECRET_KEY` in a plain `.env` file in production. Use secret injection instead — see below. + +```bash +# .env (non-secret values only) +NETWORK=mainnet +STELLAR_RPC_URL=https://soroban-mainnet.stellar.org +STELLAR_NETWORK_PASSPHRASE="Public Global Stellar Network ; September 2015" +GOVERNANCE_CONTRACT_ID=C... +TOKEN_CONTRACT_ID=C... +MIN_PROPOSAL_BALANCE=1000000 +PROPOSAL_COOLDOWN=86400 +RESTRICT_ADMIN_VOTE=true +INITIAL_TOKEN_SUPPLY=1000000000 +``` + +--- + +## Secret Injection + +`STELLAR_SECRET_KEY` is the only secret in this project. Inject it at runtime, never at rest. + +### GitHub Actions + +```yaml +- name: Deploy contracts + env: + STELLAR_SECRET_KEY: ${{ secrets.STELLAR_SECRET_KEY }} + run: bash scripts/deploy.sh +``` + +Store the value in **Settings → Secrets and variables → Actions**. + +### Docker / docker-compose + +```yaml +# docker-compose.yml +services: + deploy: + environment: + - STELLAR_SECRET_KEY=${STELLAR_SECRET_KEY} +``` + +Pass at runtime: +```bash +STELLAR_SECRET_KEY=S... docker compose run deploy +``` + +### Other CI/CD systems + +Inject `STELLAR_SECRET_KEY` as an environment variable from your platform's secret store (HashiCorp Vault, AWS Secrets Manager, etc.) and never write it to disk. + +--- + +## Validation + +Run `scripts/validate-env.sh` before any deployment to confirm all required variables are set: + +```bash +bash scripts/validate-env.sh +``` + +The frontend performs its own validation on startup via `src/config.ts`.