feat: implement Strict environment validation across services and fro…

[nikkybel]

PR Description

Implementation Summary

1. Coordinator (coordinator/src/config.ts)

• Added Zod schema validation for all config parameters
• Implemented mainnet audit confirmation gate (MAINNET_AUDIT_CONFIRMED=true)
• Added testnet contract address validation (fails if missing)
• Validates Ethereum RPC URL format and Soroban RPC URL format

2. Resolver (resolver/src/config.ts)

• Added Zod schema validation matching coordinator
• Implemented mainnet audit confirmation gate
• Added testnet contract address validation
• Validates resolver private key format (0x-prefixed 64-byte hex)

3. Relayer (relayer/src/index.ts)

• Created comprehensive validateRelayerConfig() function
• Validates RPC URLs, private keys, and contract addresses
• Checks timeout ranges (1000-300000ms)
• Calls process.exit(1) on validation failure (fails fast)

4. Frontend (frontend/src/config/networks.ts)

• Added validateFrontendEnv() function that runs at build time
• Two-step mainnet gate: Requires both VITE_MAINNET_ENABLED=true AND VITE_MAINNET_AUDIT_CONFIRMED=true
• Validates testnet/mainnet contract addresses based on network mode
• Fails Vite build with descriptive errors if validation fails

5. Mainnet Safety Mechanism

All services now require explicit audit confirmation before allowing mainnet deployment:

• Backend: MAINNET_AUDIT_CONFIRMED=true
• Frontend: VITE_MAINNET_ENABLED=true + VITE_MAINNET_AUDIT_CONFIRMED=true

This prevents accidental mainnet enablement with clear error messages.

6. Smoke Tests (coordinator/test/config-validation.test.ts)

Created 8 test cases covering:

• ✅ Valid testnet configuration
• ✅ Missing testnet contracts (throws error)
• ✅ Mainnet without audit confirmation (throws error)
• ✅ Mainnet with audit confirmation=false (throws error)
• ✅ Valid mainnet with audit confirmation
• ✅ Invalid network mode
• ✅ Invalid RPC URL format
• ✅ Valid RPC URL acceptance

7. Documentation

• env.example: Comprehensive list of all environment variables with descriptions and warnings
• docs/DEPLOYMENT.md: Updated with environment validation section, troubleshooting guide, and environment variable reference
• docs/ENVIRONMENT_VALIDATION.md: Complete implementation guide with error messages, deployment checklists, and migration guide

Acceptance Criteria Met

✅ Each service fails at startup/build with clear error when required env vars are missing or malformed
✅ Mainnet enablement requires explicit audited/deployment confirmation variable (MAINNET_AUDIT_CONFIRMED=true)
✅ Tests cover invalid env cases (8 test cases in coordinator)
✅ Env documentation updated in canonical place (env.example + docs/DEPLOYMENT.md + docs/ENVIRONMENT_VALIDATION.md)

Key Features

1. Fail Fast: Services refuse to start with invalid configuration
2. Clear Errors: Descriptive error messages guide operators to fix issues
3. Prevents Accidental Mainnet: Multi-step mainnet enablement prevents costly mistakes
4. CI/CD Friendly: Build failures surface configuration issues before deployment
5. Type Safety: Zod schemas provide runtime type validation with TypeScript inference

close #33

[vercel]

Someone is attempting to deploy a commit to the karagoz's projects Team on Vercel.

A member of the Team first needs to authorize it.