feat: Server-Side Contract Address Resolution

.env.local.example

@@ -1,6 +1,7 @@
 # Stellar Network Configuration
 NEXT_PUBLIC_STELLAR_NETWORK=testnet
 NEXT_PUBLIC_STELLAR_RPC_URL=https://soroban-testnet.stellar.org
+SOROBAN_NETWORK=testnet
 
 # Soroban Contract Addresses
 NEXT_PUBLIC_SAVINGS_GOALS_CONTRACT_ID=your_contract_id_here

docs/CONTRACT_INTEGRATION.md

@@ -9,13 +9,20 @@ This document describes the server-side integration with the Soroban remittance_
 Add to your `.env.local`:
 
 ```bash
-STELLAR_NETWORK=testnet
-REMITTANCE_SPLIT_CONTRACT_ID=<your_deployed_contract_id>
+SOROBAN_NETWORK=testnet
+
+# Option A: per-network contract IDs
+REMITTANCE_SPLIT_CONTRACT_ID_TESTNET=<your_testnet_contract_id>
+REMITTANCE_SPLIT_CONTRACT_ID_MAINNET=<your_mainnet_contract_id>
+
+# Option B: single JSON value with network keys
+# CONTRACT_IDS_JSON={"testnet":{"REMITTANCE_SPLIT_CONTRACT_ID":"<id>"},"mainnet":{"REMITTANCE_SPLIT_CONTRACT_ID":"<id>"}}
 ```
 
 **Prerequisites:**
 - The remittance_split contract must be deployed on the specified network
-- The contract ID must be set in environment variables
+- `SOROBAN_NETWORK` must be set to `testnet` or `mainnet`
+- The contract ID must be configured for that network
 
 ## Contract Functions
 
@@ -85,7 +92,7 @@ Calculates split amounts for a given remittance amount.
 
 All endpoints handle the following errors:
 
-- **Contract not configured**: Returns 500 with message "REMITTANCE_SPLIT_CONTRACT_ID not configured"
+- **Contract not configured**: Returns 500 with message indicating the missing network-specific key (for example `REMITTANCE_SPLIT_CONTRACT_ID_TESTNET`)
 - **Contract not deployed**: Returns 404 with message "Split configuration not found"
 - **RPC errors**: Returns 500 with descriptive error message
 - **Invalid parameters**: Returns 400 with validation error

lib/contracts/README.md

@@ -16,3 +16,11 @@ Contract read/write layer for the family wallet functionality.
 - `checkSpendingLimit(...)` - Verify spending allowance
 
 See `/docs/FAMILY_WALLET_INTEGRATION.md` for complete documentation.
+
+## Contract ID Resolution
+
+Server-side contract integrations resolve contract IDs by `SOROBAN_NETWORK` (`testnet` or `mainnet`) via `lib/contracts/contract-id-resolver.ts`.
+
+Supported configuration:
+- Network-specific env vars (example: `REMITTANCE_SPLIT_CONTRACT_ID_TESTNET`, `REMITTANCE_SPLIT_CONTRACT_ID_MAINNET`)
+- `CONTRACT_IDS_JSON` with top-level `testnet` and `mainnet` keys

lib/contracts/contract-id-resolver.ts

@@ -0,0 +1,94 @@
+export type SorobanNetwork = 'testnet' | 'mainnet';
+
+const SUPPORTED_NETWORKS: ReadonlyArray<SorobanNetwork> = ['testnet', 'mainnet'];
+
+const CONTRACT_ENV_KEYS = {
+  remittanceSplit: 'REMITTANCE_SPLIT_CONTRACT_ID',
+  savingsGoals: 'SAVINGS_GOALS_CONTRACT_ID',
+  billPayments: 'BILL_PAYMENTS_CONTRACT_ID',
+  insurance: 'INSURANCE_CONTRACT_ID',
+  familyWallet: 'FAMILY_WALLET_CONTRACT_ID',
+} as const;
+
+type ContractKey = keyof typeof CONTRACT_ENV_KEYS;
+
+function parseContractIdsJson(): Record<string, Record<string, string> | string> | null {
+  const raw = process.env.CONTRACT_IDS_JSON;
+  if (!raw) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('CONTRACT_IDS_JSON must be a JSON object');
+    }
+    return parsed as Record<string, Record<string, string> | string>;
+  } catch (error) {
+    throw new Error(
+      `Failed to parse CONTRACT_IDS_JSON: ${error instanceof Error ? error.message : 'Unknown parse error'}`
+    );
+  }
+}
+
+export function getSorobanNetwork(): SorobanNetwork {
+  const raw = (process.env.SOROBAN_NETWORK ?? 'testnet').toLowerCase();
+  if (raw !== 'testnet' && raw !== 'mainnet') {
+    throw new Error(
+      `Invalid SOROBAN_NETWORK "${raw}". Expected one of: ${SUPPORTED_NETWORKS.join(', ')}`
+    );
+  }
+  return raw;
+}
+
+export function resolveContractId(
+  envBaseKey: string,
+  network: SorobanNetwork = getSorobanNetwork()
+): string {
+  const normalizedBaseKey = envBaseKey.trim().toUpperCase();
+  const networkKey = `${normalizedBaseKey}_${network.toUpperCase()}`;
+
+  const networkSpecificEnv = process.env[networkKey];
+  if (networkSpecificEnv) {
+    return networkSpecificEnv;
+  }
+
+  const fromJson = parseContractIdsJson()?.[network];
+  if (fromJson && typeof fromJson === 'object' && !Array.isArray(fromJson)) {
+    const jsonNetworkValue = fromJson[networkKey] ?? fromJson[normalizedBaseKey];
+    if (typeof jsonNetworkValue === 'string' && jsonNetworkValue.length > 0) {
+      return jsonNetworkValue;
+    }
+  }
+
+  // Backward-compatible fallback to a single contract ID.
+  const fallback = process.env[normalizedBaseKey];
+  if (fallback) {
+    return fallback;
+  }
+
+  throw new Error(
+    `Contract ID not configured for ${normalizedBaseKey} on ${network}. ` +
+      `Set ${networkKey} or provide CONTRACT_IDS_JSON with a "${network}" key.`
+  );
+}
+
+export function getResolvedContractIdsForNetwork(
+  network: SorobanNetwork = getSorobanNetwork()
+): Record<ContractKey, string | null> {
+  return {
+    remittanceSplit: safeResolve(CONTRACT_ENV_KEYS.remittanceSplit, network),
+    savingsGoals: safeResolve(CONTRACT_ENV_KEYS.savingsGoals, network),
+    billPayments: safeResolve(CONTRACT_ENV_KEYS.billPayments, network),
+    insurance: safeResolve(CONTRACT_ENV_KEYS.insurance, network),
+    familyWallet: safeResolve(CONTRACT_ENV_KEYS.familyWallet, network),
+  };
+}
+
+function safeResolve(envBaseKey: string, network: SorobanNetwork): string | null {
+  try {
+    return resolveContractId(envBaseKey, network);
+  } catch {
+    return null;
+  }
+}