Validate Hardcoded Contract IDs and Fail Fast on Missing Environment Variables

[pragmaticAweds]

Context & Impact

Contract IDs in src/lib/constants.ts fall back to placeholder values ("CB...") when environment variables are missing. There is no runtime validation that these IDs are actual deployed Soroban contract addresses. If a deployment omits NEXT_PUBLIC_PAYMENT_STREAM_CONTRACT_ID or NEXT_PUBLIC_DISTRIBUTOR_CONTRACT_ID, the app silently uses invalid addresses — every transaction fails with cryptic contract errors.

Why this matters: Contributors setting up the project for the first time, or deployments with misconfigured environment variables, will see transactions fail with no clear indication that the root cause is a bad contract ID. The app should fail fast and loud at startup, not silently at transaction time.

Scope

• Add runtime validation for all required environment variables at application startup
• Validate that contract IDs match the Stellar address format (56 characters, starting with C)
• Create a startup check that runs before the app renders and shows a clear error if config is missing
• Remove placeholder fallback values that mask configuration errors
• Add validation for NEXT_PUBLIC_STELLAR_RPC_URL and NEXT_PUBLIC_STELLAR_HORIZON_URL as well

Implementation Guidelines

• Create a src/lib/env-validation.ts module that validates all required env vars
• Use Zod for schema validation of environment variables (already a project dependency)
• Call validation in the root layout or a provider that runs before any contract interaction
• In development, show a full-screen error overlay listing missing/invalid variables
• In production, log the error and show a generic "Configuration error" page
• Update .env.example with clear documentation of each required variable

Acceptance Criteria

• All placeholder/fallback contract IDs are removed from src/lib/constants.ts
• A Zod schema validates all required environment variables at startup
• Missing NEXT_PUBLIC_PAYMENT_STREAM_CONTRACT_ID causes a clear startup error
• Missing NEXT_PUBLIC_DISTRIBUTOR_CONTRACT_ID causes a clear startup error
• Missing NEXT_PUBLIC_STELLAR_RPC_URL causes a clear startup error
• Invalid contract ID format (wrong length, wrong prefix) is caught and reported
• .env.example documents every required variable with descriptions
• Development mode shows a detailed error overlay; production shows a safe generic message

Getting Started

1. Review src/lib/constants.ts to see current fallback values
2. Review .env.example for documented vs. undocumented variables
3. Create src/lib/env-validation.ts with a Zod schema for all NEXT_PUBLIC_* variables
4. Add a validation call in the root layout or a dedicated EnvProvider
5. Create a simple error UI component for the misconfiguration state
6. Remove all fallback values from constants.ts so missing vars are caught immediately
7. Test by removing env vars and verifying the error UI appears

---

PR Submission Guide

This section applies to every PR for this issue. Follow it exactly.

Before You Start

• Pull the latest main branch: git checkout main && git pull origin main
• Create your feature branch from main: git checkout -b fix/<issue-number>-env-validation

While Working

• Make atomic commits — one concern per commit, each commit must build
• Use Conventional Commits: feat(scope): description, fix(scope): description
• Keep your branch up to date: git pull origin main --rebase regularly

Before Submitting the PR

• Pull latest main and rebase: git checkout main && git pull origin main && git checkout <your-branch> && git rebase main
• Ensure the build passes: pnpm build
• Ensure linting passes: pnpm lint
• Record a screen recording of your implementation showing the feature/fix working in the browser. Attach it to the PR.

PR Requirements

• Link this issue in your PR description using Closes #<issue-number>
• Fill out the full PR template — Summary, What Was Implemented, Implementation Details, How to Test
• Attach your screen recording demonstrating the implementation
• Request a review from a maintainer

PRs without a screen recording or without a linked issue will not be reviewed.

[zainabb-dev]

@zainabb-dev has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

Hey Champ, Can i get on this and get it done?

ℹ️ Repo Maintainers: To accept this application, review their application or assign @zainabb-dev to this issue.

[drips-wave]

Congratulations, @zainabb-dev! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on March 30, 2026.

🧑‍💻 @zainabb-dev: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊