Merge pull request #367 from raizo07/multi-network-support

feat: Add multi-network support

Author: Otaiki1

backend/.env.example

@@ -21,7 +21,13 @@ ADMIN_IP_ALLOWLIST=
 # Server
 PORT=3001
 
-# Indexer — tikka-indexer internal API
+# Stellar — testnet (default) or mainnet; drives Horizon / contract defaults and indexer URL if INDEXER_URL is unset
+STELLAR_NETWORK=testnet
+# Optional overrides (otherwise derived from STELLAR_NETWORK)
+# STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
+# STELLAR_CONTRACT_ID=C...
+
+# Indexer — tikka-indexer internal API (omit to use the default URL for STELLAR_NETWORK)
 INDEXER_URL=http://localhost:3002
 INDEXER_TIMEOUT_MS=5000
 

backend/README.md

@@ -159,6 +159,32 @@ The endpoint returns **HTTP 503** when `status` is `degraded`, so orchestrators
 
 ---
 
+## Stellar network (Testnet / Mainnet)
+
+The backend selects a Stellar network with **`STELLAR_NETWORK`** (`testnet` or `mainnet`). That value drives:
+
+- **Horizon URL** — defaults to the public Horizon for the chosen network (`https://horizon-testnet.stellar.org` or `https://horizon.stellar.org`). Override with **`STELLAR_HORIZON_URL`** if you use a proxy or custom Horizon.
+- **Network passphrase** — exposed at runtime via `env.stellar.networkPassphrase` (same constants as the Stellar SDK) for any logic that must sign or verify against a specific network.
+- **Contract ID** — defaults are empty until you deploy; set **`STELLAR_CONTRACT_ID`** to your raffle (or other) contract for the environment you are running.
+- **Indexer base URL** — if **`INDEXER_URL`** is not set, it defaults to the URL in `stellar.constants.ts` for that network (currently `http://localhost:3002` for both). In production, set **`INDEXER_URL`** explicitly to the tikka-indexer instance that indexes the same chain as **`STELLAR_NETWORK`**.
+
+Injectable services should read **`INDEXER_URL`** and **`INDEXER_TIMEOUT_MS`** from Nest **`ConfigService`** (validated at startup). For scripts or non-DI code, use **`env.indexer`** and **`env.stellar`** from `src/config/env.config.ts`.
+
+Example `.env` fragments:
+
+```dotenv
+# Local development against testnet
+STELLAR_NETWORK=testnet
+INDEXER_URL=http://localhost:3002
+
+# Production-style: mainnet Horizon defaults; point indexer at your fleet
+STELLAR_NETWORK=mainnet
+STELLAR_CONTRACT_ID=YOUR_MAINNET_CONTRACT_ID
+INDEXER_URL=https://your-indexer.example.com
+```
+
+---
+
 ## Environment Variables
 
 Copy `.env.example` to `.env` and fill in the required values before starting the server.
@@ -186,7 +212,10 @@ These must be set or the app will refuse to start:
 | Variable                   | Default                    | Description                                      |
 | -------------------------- | -------------------------- | ------------------------------------------------ |
 | `PORT`                     | `3001`                     | HTTP port the server listens on                  |
-| `INDEXER_URL`              | `http://localhost:3002`    | Base URL of the tikka-indexer internal API       |
+| `STELLAR_NETWORK`          | `testnet`                  | `testnet` or `mainnet` — Horizon, contract, and default indexer base |
+| `STELLAR_HORIZON_URL`      | (from network)             | Override Horizon URL (optional)                  |
+| `STELLAR_CONTRACT_ID`     | (none)                     | On-chain contract id for this deployment (optional) |
+| `INDEXER_URL`              | (per `STELLAR_NETWORK`)    | Base URL of tikka-indexer; set explicitly in prod |
 | `INDEXER_TIMEOUT_MS`       | `5000`                     | HTTP timeout for indexer requests (ms)           |
 | `JWT_EXPIRES_IN`           | `7d`                       | JWT expiry duration (e.g. `1h`, `7d`)            |
 | `SIWS_DOMAIN`              | `tikka.io`                 | Domain shown in the SIWS sign-in message         |

backend/pnpm-lock.yaml

@@ -2,18 +2,45 @@
  * Environment configuration for tikka-backend.
  * Using getters ensures environment variables are read at runtime,
  * avoiding issues where they might be cached before values are loaded.
+ *
+ * Stellar network fields align with Nest `ConfigService` after `env.schema` validation.
+ * Prefer `ConfigService` in injectable services for INDEXER_URL / timeouts;
+ * use this module for `stellar` resolution and non-DI contexts.
  */
+import {
+  resolveIndexerBaseUrl,
+  resolveStellarContractId,
+  resolveStellarHorizonUrl,
+  resolveStellarNetworkId,
+  resolveStellarNetworkPassphrase,
+} from './stellar.constants';
+
+function envLikeFromProcess(): Record<string, string | undefined> {
+  return { ...process.env };
+}
+
 export const env = {
   get supabase() {
     return {
-      url: process.env.SUPABASE_URL ?? "",
-      serviceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY ?? "",
+      url: process.env.SUPABASE_URL ?? '',
+      serviceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY ?? '',
     };
   },
   get indexer() {
+    const envLike = envLikeFromProcess();
     return {
-      url: process.env.INDEXER_URL ?? "http://localhost:3002",
-      timeoutMs: parseInt(process.env.INDEXER_TIMEOUT_MS ?? "5000", 10),
+      url: resolveIndexerBaseUrl(envLike),
+      timeoutMs: parseInt(process.env.INDEXER_TIMEOUT_MS ?? '5000', 10),
+    };
+  },
+  get stellar() {
+    const envLike = envLikeFromProcess();
+    const network = resolveStellarNetworkId(envLike);
+    return {
+      network,
+      horizonUrl: resolveStellarHorizonUrl(envLike),
+      networkPassphrase: resolveStellarNetworkPassphrase(envLike),
+      contractId: resolveStellarContractId(envLike),
     };
   },
   get jwt() {
@@ -25,7 +52,7 @@ export const env = {
   },
   get siws() {
     return {
-      domain: process.env.SIWS_DOMAIN ?? "tikka.io",
+      domain: process.env.SIWS_DOMAIN ?? 'tikka.io',
     };
   },
   get fcm() {

backend/src/config/env.config.ts

@@ -4,6 +4,7 @@ const validEnv: Record<string, string> = {
   PORT: '3001',
   SUPABASE_URL: 'https://test.supabase.co',
   SUPABASE_SERVICE_ROLE_KEY: 'test-service-role-key',
+  STELLAR_NETWORK: 'testnet',
   INDEXER_URL: 'http://localhost:3002',
   INDEXER_TIMEOUT_MS: '5000',
   JWT_SECRET: 'a'.repeat(32),
@@ -25,6 +26,8 @@ describe('env.schema validate()', () => {
     const minimal: Record<string, string> = {
       SUPABASE_URL: 'https://test.supabase.co',
       SUPABASE_SERVICE_ROLE_KEY: 'key',
+      STELLAR_NETWORK: 'testnet',
+      INDEXER_URL: '',
       JWT_SECRET: 'b'.repeat(32),
       VITE_FRONTEND_URL: 'https://app.tikka.io',
       ADMIN_TOKEN: 'my-admin-token',
@@ -96,4 +99,39 @@ describe('env.schema validate()', () => {
     const result = validate({ ...validEnv, ADMIN_IP_ALLOWLIST: '192.168.1.0/24,10.0.0.1' });
     expect(result.ADMIN_IP_ALLOWLIST).toBe('192.168.1.0/24,10.0.0.1');
   });
+
+  it('defaults STELLAR_NETWORK to testnet when omitted', () => {
+    const prev = process.env.STELLAR_NETWORK;
+    delete process.env.STELLAR_NETWORK;
+    try {
+      const { STELLAR_NETWORK: _, ...withoutStellar } = validEnv;
+      const result = validate(withoutStellar);
+      expect(result.STELLAR_NETWORK).toBe('testnet');
+    } finally {
+      if (prev !== undefined) process.env.STELLAR_NETWORK = prev;
+    }
+  });
+
+  it('fills INDEXER_URL from network defaults when INDEXER_URL is omitted', () => {
+    const prevIndexer = process.env.INDEXER_URL;
+    delete process.env.INDEXER_URL;
+    try {
+      const { INDEXER_URL: _, ...rest } = validEnv;
+      const result = validate({ ...rest, STELLAR_NETWORK: 'mainnet' });
+      expect(result.INDEXER_URL).toBe('http://localhost:3002');
+      expect(result.STELLAR_NETWORK).toBe('mainnet');
+    } finally {
+      if (prevIndexer !== undefined) process.env.INDEXER_URL = prevIndexer;
+    }
+  });
+
+  it('accepts STELLAR_CONTRACT_ID and STELLAR_HORIZON_URL overrides', () => {
+    const result = validate({
+      ...validEnv,
+      STELLAR_CONTRACT_ID: 'CCONTRACTTEST1234567890123456789012',
+      STELLAR_HORIZON_URL: 'https://horizon-custom.example.com',
+    });
+    expect(result.STELLAR_CONTRACT_ID).toBe('CCONTRACTTEST1234567890123456789012');
+    expect(result.STELLAR_HORIZON_URL).toBe('https://horizon-custom.example.com');
+  });
 });

backend/src/config/env.schema.spec.ts

@@ -1,4 +1,46 @@
 import { z } from 'zod';
+import {
+  resolveIndexerBaseUrl,
+  resolveStellarNetworkId,
+} from './stellar.constants';
+
+function toEnvLike(config: Record<string, unknown>): Record<string, string | undefined> {
+  const merged: Record<string, string | undefined> = { ...process.env };
+  for (const [k, v] of Object.entries(config)) {
+    if (v === undefined || v === null) continue;
+    merged[k] = String(v);
+  }
+  return merged;
+}
+
+/**
+ * Normalize STELLAR_NETWORK and fill INDEXER_URL when omitted so it matches
+ * the active Stellar network (see stellar.constants).
+ */
+function preprocessStellarEnv(
+  input: Record<string, unknown>,
+): Record<string, unknown> {
+  const c = { ...input };
+  const envLike = toEnvLike(c);
+  const network = resolveStellarNetworkId(envLike);
+  c.STELLAR_NETWORK = network;
+
+  const idx = c.INDEXER_URL;
+  if (idx === undefined || idx === null || String(idx).trim() === '') {
+    c.INDEXER_URL = resolveIndexerBaseUrl({
+      ...envLike,
+      STELLAR_NETWORK: network,
+      INDEXER_URL: undefined,
+    });
+  }
+
+  const hz = c.STELLAR_HORIZON_URL;
+  if (hz === '' || hz === null) delete c.STELLAR_HORIZON_URL;
+  const cid = c.STELLAR_CONTRACT_ID;
+  if (cid === '' || cid === null) delete c.STELLAR_CONTRACT_ID;
+
+  return c;
+}
 
 /**
  * Zod schema for process.env validation.
@@ -10,7 +52,7 @@ import { z } from 'zod';
  * through without failing validation — ConfigModule passes the entire
  * process.env object to the validate function.
  */
-export const envSchema = z
+const envSchemaInner = z
   .object({
     // Server
     PORT: z.coerce.number().int().positive().default(3001),
@@ -19,8 +61,13 @@ export const envSchema = z
     SUPABASE_URL: z.string().url(),
     SUPABASE_SERVICE_ROLE_KEY: z.string().min(1),
 
-    // Indexer
-    INDEXER_URL: z.string().url().default('http://localhost:3002'),
+    // Stellar — network drives Horizon / contract defaults unless overridden
+    STELLAR_NETWORK: z.enum(['testnet', 'mainnet']).default('testnet'),
+    STELLAR_HORIZON_URL: z.string().url().optional(),
+    STELLAR_CONTRACT_ID: z.string().min(1).optional(),
+
+    // Indexer (INDEXER_URL filled in preprocess when empty)
+    INDEXER_URL: z.string().url(),
     INDEXER_TIMEOUT_MS: z.coerce.number().int().positive().default(5000),
 
     // JWT
@@ -56,7 +103,9 @@ export const envSchema = z
   })
   .passthrough();
 
-export type EnvConfig = z.infer<typeof envSchema>;
+export const envSchema = z.preprocess(preprocessStellarEnv, envSchemaInner);
+
+export type EnvConfig = z.infer<typeof envSchemaInner>;
 
 /**
  * Validate function for `ConfigModule.forRoot({ validate })`.

backend/src/config/env.schema.ts

@@ -0,0 +1,80 @@
+/**
+ * Stellar network identifiers and defaults (Horizon, passphrase, indexer base URL).
+ * Used by env validation and runtime env.config getters so behavior stays aligned.
+ */
+export const STELLAR_NETWORK_IDS = ['testnet', 'mainnet'] as const;
+export type StellarNetworkId = (typeof STELLAR_NETWORK_IDS)[number];
+
+export const STELLAR_NETWORK_DEFAULTS: Record<
+  StellarNetworkId,
+  {
+    horizonUrl: string;
+    networkPassphrase: string;
+    /** Base URL when INDEXER_URL is unset — override INDEXER_URL in production. */
+    defaultIndexerUrl: string;
+    /** Placeholder; set STELLAR_CONTRACT_ID for your deployment. */
+    contractId: string;
+  }
+> = {
+  testnet: {
+    horizonUrl: 'https://horizon-testnet.stellar.org',
+    networkPassphrase: 'Test SDF Network ; September 2015',
+    defaultIndexerUrl: 'http://localhost:3002',
+    contractId: '',
+  },
+  mainnet: {
+    horizonUrl: 'https://horizon.stellar.org',
+    networkPassphrase: 'Public Global Stellar Network ; September 2015',
+    defaultIndexerUrl: 'http://localhost:3002',
+    contractId: '',
+  },
+};
+
+function normalizeNetwork(
+  raw: string | undefined,
+): StellarNetworkId {
+  const n = (raw ?? 'testnet').toLowerCase();
+  return n === 'mainnet' ? 'mainnet' : 'testnet';
+}
+
+/** Resolve network id from a loose env record (e.g. validate() input merged with process.env). */
+export function resolveStellarNetworkId(
+  envLike: Record<string, string | undefined>,
+): StellarNetworkId {
+  return normalizeNetwork(envLike.STELLAR_NETWORK);
+}
+
+/** Indexer API base URL: explicit INDEXER_URL wins, else per-network default. */
+export function resolveIndexerBaseUrl(
+  envLike: Record<string, string | undefined>,
+): string {
+  const explicit = envLike.INDEXER_URL?.trim();
+  if (explicit) return explicit;
+  const network = resolveStellarNetworkId(envLike);
+  return STELLAR_NETWORK_DEFAULTS[network].defaultIndexerUrl;
+}
+
+export function resolveStellarHorizonUrl(
+  envLike: Record<string, string | undefined>,
+): string {
+  const override = envLike.STELLAR_HORIZON_URL?.trim();
+  if (override) return override;
+  const network = resolveStellarNetworkId(envLike);
+  return STELLAR_NETWORK_DEFAULTS[network].horizonUrl;
+}
+
+export function resolveStellarContractId(
+  envLike: Record<string, string | undefined>,
+): string {
+  const override = envLike.STELLAR_CONTRACT_ID?.trim();
+  if (override) return override;
+  const network = resolveStellarNetworkId(envLike);
+  return STELLAR_NETWORK_DEFAULTS[network].contractId;
+}
+
+export function resolveStellarNetworkPassphrase(
+  envLike: Record<string, string | undefined>,
+): string {
+  const network = resolveStellarNetworkId(envLike);
+  return STELLAR_NETWORK_DEFAULTS[network].networkPassphrase;
+}

backend/src/config/stellar.constants.ts

@@ -1,3 +1,4 @@
+import { ConfigService } from '@nestjs/config';
 import { Test, TestingModule } from '@nestjs/testing';
 import { HealthService } from './health.service';
 
@@ -18,7 +19,20 @@ describe('HealthService', () => {
 
   beforeEach(async () => {
     const module: TestingModule = await Test.createTestingModule({
-      providers: [HealthService],
+      providers: [
+        HealthService,
+        {
+          provide: ConfigService,
+          useValue: {
+            getOrThrow: (key: string) => {
+              if (key === 'INDEXER_URL') return 'http://indexer.test';
+              throw new Error(`unexpected key ${key}`);
+            },
+            get: (key: string, def?: number) =>
+              key === 'INDEXER_TIMEOUT_MS' ? 3000 : def,
+          },
+        },
+      ],
     }).compile();
 
     service = module.get<HealthService>(HealthService);

backend/src/health/health.service.spec.ts

@@ -1,4 +1,5 @@
 import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
 import { env } from '../config/env.config';
 
 export interface HealthResult {
@@ -15,9 +16,11 @@ export class HealthService {
   private readonly supabaseUrl: string;
   private readonly supabaseKey: string;
 
-  constructor() {
-    this.indexerUrl = env.indexer.url.replace(/\/$/, '');
-    this.indexerTimeoutMs = env.indexer.timeoutMs;
+  constructor(private readonly config: ConfigService) {
+    this.indexerUrl = this.config
+      .getOrThrow<string>('INDEXER_URL')
+      .replace(/\/$/, '');
+    this.indexerTimeoutMs = this.config.get<number>('INDEXER_TIMEOUT_MS', 5000);
     this.supabaseUrl = env.supabase.url.replace(/\/$/, '');
     this.supabaseKey = env.supabase.serviceRoleKey;
   }