From c6b5cfcb8848f70815a6f651a22c38c469e05b83 Mon Sep 17 00:00:00 2001 From: Okey Amy Date: Sun, 21 Jun 2026 14:27:55 +0100 Subject: [PATCH] docs: improve contributor env setup --- .env.example | 2 +- CONTRIBUTING.md | 10 +++++++- README.md | 64 +++++++++++++++++++++++++++++++++++-------------- 3 files changed, 56 insertions(+), 20 deletions(-) diff --git a/.env.example b/.env.example index 676ead3..4498bab 100644 --- a/.env.example +++ b/.env.example @@ -18,7 +18,7 @@ KYC_DOCUMENT_ENCRYPTION_KEY=replace_with_optional_local_kyc_encryption_secret NEXT_PUBLIC_PRIVY_APP_ID=replace_with_privy_app_id PRIVY_APP_ID=replace_with_privy_app_id_for_server_validation PRIVY_APP_SECRET=replace_with_privy_secret -PRIVY_JWKS_URL=https://auth.privy.io/api/v1/apps/replace_with_privy_app_id/jwks.json +PRIVY_JWKS_URL=replace_with_privy_jwks_url # Paystack PAYSTACK_PUBLIC_KEY=replace_with_paystack_test_public_key diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c3ef153..855ff3b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +20,15 @@ cp .env.example .env.local npm run dev ``` -Then update `.env.local` with local placeholders or your own test credentials. +Then update `.env.local` with local placeholders or your own test credentials. Keep the mock flags enabled unless your issue specifically requires a live sandbox provider. The template is safe to commit; `.env.local` is not. + +### Environment categories + +- **Required for local app state:** `NEXT_PUBLIC_APP_URL`, `MONGODB_URI`, and `JWT_SECRET`. +- **Required for live Privy auth testing:** `NEXT_PUBLIC_PRIVY_APP_ID`, `PRIVY_APP_SECRET`, and `PRIVY_JWKS_URL`; `PRIVY_APP_ID` is an optional server-side override. +- **Optional local/server features:** `AUTH_SESSION_SECRET`, `KYC_DOCUMENT_ENCRYPTION_KEY`, `PAYSTACK_DVA_PREFERRED_BANK`, `PAYSTACK_PUBLIC_KEY`, and `BLOB_READ_WRITE_TOKEN`. +- **Mock-only by default:** `PAYSTACK_SECRET_KEY`, `RESEND_API_KEY`, `STELLAR_ISSUER_PUBLIC_KEY`, `STELLAR_DISTRIBUTION_PUBLIC_KEY`, and `STELLAR_CONTRACT_ID` can remain placeholders while mock mode is enabled. +- **Planned Stellar testnet defaults:** `STELLAR_NETWORK`, `STELLAR_HORIZON_URL`, `STELLAR_RPC_URL`, and `STELLAR_ASSET_CODE` document the intended testnet configuration and do not require maintainer credentials. ## Mock mode diff --git a/README.md b/README.md index 7de85ea..6fd906b 100644 --- a/README.md +++ b/README.md @@ -133,36 +133,64 @@ cd chain_move npm install ``` -3. Create `.env.local` and set the required variables: +3. Create your local environment file from the safe contributor template: ```bash -MONGODB_URI= -JWT_SECRET= -NEXT_PUBLIC_APP_URL=http://localhost:3000 -NEXT_PUBLIC_PRIVY_APP_ID= -PRIVY_APP_SECRET= -PRIVY_JWKS_URL= -PAYSTACK_SECRET_KEY= -PAYSTACK_DVA_PREFERRED_BANK= -RESEND_API_KEY= +cp .env.example .env.local ``` -4. Start the development server: +`.env.example` intentionally contains placeholder, localhost, and public testnet values only. Do not ask maintainers for production credentials, and never commit `.env.local` or any file containing real secrets. The repository `.gitignore` keeps `.env*` files ignored while explicitly allowing `.env.example` to remain tracked. + +4. Keep mock mode enabled for normal contributor work: + +```env +ENABLE_MOCK_PAYMENTS=true +ENABLE_MOCK_EMAILS=true +ENABLE_MOCK_STELLAR=true +``` + +With mock mode enabled, contributors can develop UI and most backend flows without maintainer Paystack, Resend, or Stellar signing credentials. Replace placeholders only with your own sandbox/test credentials when an issue explicitly requires live provider testing. + +5. Start the development server: ```bash npm run dev ``` -5. Open `http://localhost:3000`. +6. Open `http://localhost:3000`. ## Environment Notes -- `MONGODB_URI` and `JWT_SECRET` are required for application and session state. -- `NEXT_PUBLIC_PRIVY_APP_ID`, `PRIVY_APP_SECRET`, and `PRIVY_JWKS_URL` are required for the current Privy-backed auth flow. -- `PAYSTACK_SECRET_KEY` is required for wallet funding flows. -- `PAYSTACK_DVA_PREFERRED_BANK` optionally overrides the bank slug used when provisioning Paystack dedicated virtual accounts. For test keys, the app defaults to `test-bank`. -- `RESEND_API_KEY` is only needed for email features. -- Stellar variables are not required by the current code yet. The expected integration pass should introduce explicit values such as `STELLAR_NETWORK`, `STELLAR_HORIZON_URL`, `STELLAR_RPC_URL`, issuer account public keys, distribution account public keys, and contract IDs. +Use `.env.example` as the source of truth for safe local defaults. The categories below explain which values contributors normally need to edit. + +| Variable | Status | Notes | +| --- | --- | --- | +| `NEXT_PUBLIC_APP_URL` | Required | Local app origin. Keep `http://localhost:3000` unless you run on another port. | +| `MONGODB_URI` | Required | Use a local MongoDB database or your own disposable development database. Do not use maintainer production data. | +| `JWT_SECRET` | Required | Set to any strong local development string. Do not reuse production secrets. | +| `AUTH_SESSION_SECRET` | Optional | Fallback session secret for local development. | +| `KYC_DOCUMENT_ENCRYPTION_KEY` | Optional | Local-only encryption fallback for KYC document references. Production uses maintainer-managed secrets. | +| `NEXT_PUBLIC_PRIVY_APP_ID` | Required for Privy auth | Public Privy app ID for the current auth flow. Use your own test app when exercising auth. | +| `PRIVY_APP_ID` | Optional | Server-side Privy app ID override; can match your test `NEXT_PUBLIC_PRIVY_APP_ID`. | +| `PRIVY_APP_SECRET` | Required for live Privy auth | Server-only Privy test secret. Leave as a placeholder unless you are testing live Privy flows. | +| `PRIVY_JWKS_URL` | Required for live Privy token verification | Use the JWKS URL for your own Privy test app. | +| `PAYSTACK_PUBLIC_KEY` | Optional | Public test key for live Paystack checkout experiments. | +| `PAYSTACK_SECRET_KEY` | Mock-only by default; required for live Paystack | Keep placeholder while `ENABLE_MOCK_PAYMENTS=true`; use only your own Paystack test secret for live payment testing. | +| `PAYSTACK_DVA_PREFERRED_BANK` | Optional | Bank slug for Paystack dedicated virtual account tests. The contributor template uses `test-bank`. | +| `RESEND_API_KEY` | Mock-only by default; required for live email | Keep placeholder while `ENABLE_MOCK_EMAILS=true`; use only your own Resend test key for live email testing. | +| `BLOB_READ_WRITE_TOKEN` | Optional | Needed only when exercising Vercel Blob-backed uploads outside managed environments. | +| `STELLAR_NETWORK` | Planned / mock-safe | Defaults to `testnet` for future Stellar integration work. | +| `STELLAR_HORIZON_URL` | Planned / mock-safe | Public Stellar Testnet Horizon URL. | +| `STELLAR_RPC_URL` | Planned / mock-safe | Public Stellar Testnet Soroban RPC URL. | +| `STELLAR_ASSET_CODE` | Planned / mock-safe | Development asset code placeholder, currently `CMOVE`. | +| `STELLAR_ISSUER_PUBLIC_KEY` | Planned / mock-only placeholder | Public key placeholder only; never commit secret keys or seed phrases. | +| `STELLAR_DISTRIBUTION_PUBLIC_KEY` | Planned / mock-only placeholder | Public key placeholder only; never commit secret keys or seed phrases. | +| `STELLAR_CONTRACT_ID` | Planned / mock-only placeholder | Fill only after deploying your own test contract. | +| `ENABLE_MOCK_PAYMENTS` | Mock mode | Keep `true` unless testing Paystack with your own sandbox keys. | +| `ENABLE_MOCK_EMAILS` | Mock mode | Keep `true` unless testing Resend with your own key. | +| `ENABLE_MOCK_STELLAR` | Mock mode | Keep `true` unless testing public Stellar Testnet reads or your own test deployment. | + +Maintainer-only values such as production database URLs, production Paystack/Resend/Privy secrets, treasury private keys, Stellar signer secrets, wallet recovery material, and deployment credentials must never be committed or requested for contributor setup. ## Driver Dedicated Repayment Accounts