Merge pull request Gildado#89 from ryzen-xp/feature/Contract-Address-Registry-API

feature  : Contract-Address-Registry-API

Author: Wilfred007

backend/environments.toml

@@ -0,0 +1,14 @@
+[testnet.bulk_payment]
+contractId = "CBULK_TEST_123"
+version = "1.0.0"
+deployedAt = 1456789
+
+[testnet.vesting_escrow]
+contractId = "CVEST_TEST_456"
+version = "1.1.0"
+deployedAt = 1456795
+
+[mainnet.bulk_payment]
+contractId = "CBULK_MAIN_789"
+version = "1.0.0"
+deployedAt = 9876543

backend/package.json

@@ -27,6 +27,7 @@
     "passport-github2": "^0.1.12",
     "passport-google-oauth20": "^2.0.0",
     "pg": "^8.18.0",
+    "toml": "^3.0.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {

backend/src/controllers/__tests__/contractRegistry.test.ts

@@ -0,0 +1,96 @@
+import request from 'supertest';
+import express from 'express';
+import contractRegistryRoutes from '../../routes/contractRegistryRoutes.js';
+import { ContractRegistryService } from '../../services/contractRegistryService.js';
+import logger from '../../utils/logger.js';
+
+jest.mock('../../services/contractRegistryService');
+jest.mock('../../utils/logger');
+
+const app = express();
+app.use(express.json());
+app.use('/api', contractRegistryRoutes);
+
+describe('Contract Registry API Integration', () => {
+     beforeEach(() => {
+          jest.clearAllMocks();
+     });
+
+     describe('GET /api/contracts', () => {
+          it('returns all networks when no query param provided', async () => {
+               (ContractRegistryService.getAllContracts as jest.Mock)
+                    .mockReturnValue({
+                         testnet: {
+                              bulk_payment: {
+                                   contractId: 'CBULK_TEST',
+                                   version: '1.0.0',
+                                   deployedAt: 123456,
+                              },
+                         },
+                    });
+
+               const response = await request(app).get('/api/contracts');
+
+               expect(response.status).toBe(200);
+               expect(response.body).toHaveProperty('networks');
+               expect(response.body.count).toBe(1);
+               expect(response.body.networks.testnet).toBeDefined();
+               expect(response.body).toHaveProperty('timestamp');
+          });
+
+          it('returns specific network when query param is provided', async () => {
+               (ContractRegistryService.getContractsByNetwork as jest.Mock)
+                    .mockReturnValue({
+                         bulk_payment: {
+                              contractId: 'CBULK_TEST',
+                              version: '1.0.0',
+                              deployedAt: 123456,
+                         },
+                    });
+
+               const response = await request(app)
+                    .get('/api/contracts')
+                    .query({ network: 'testnet' });
+
+               expect(response.status).toBe(200);
+               expect(response.body.network).toBe('testnet');
+               expect(response.body.contracts.bulk_payment).toBeDefined();
+               expect(response.body.count).toBe(1);
+          });
+
+          it('returns 500 when service throws error', async () => {
+               (ContractRegistryService.getAllContracts as jest.Mock)
+                    .mockImplementation(() => {
+                         throw new Error('Registry load failed');
+                    });
+
+               const response = await request(app).get('/api/contracts');
+
+               expect(response.status).toBe(500);
+               expect(response.body.error).toBe('Internal Server Error');
+               expect(response.body.message).toBe('Registry load failed');
+               expect(logger.error).toHaveBeenCalled();
+          });
+
+          it('logs warning if response time exceeds 500ms', async () => {
+               (ContractRegistryService.getAllContracts as jest.Mock)
+                    .mockReturnValue({});
+
+               // Mock slow response
+               const originalNow = Date.now;
+               let time = 0;
+               Date.now = jest.fn(() => {
+                    time += 600;
+                    return time;
+               });
+
+               await request(app).get('/api/contracts');
+
+               expect(logger.warn).toHaveBeenCalledWith(
+                    expect.stringContaining('Contract registry response slow')
+               );
+
+               Date.now = originalNow;
+          });
+     });
+});

backend/src/controllers/contractRegistryController.ts

@@ -0,0 +1,66 @@
+import { Request, Response } from 'express';
+import { ContractRegistryService } from '../services/contractRegistryService.js';
+import logger from '../utils/logger.js';
+
+export class ContractRegistryController {
+     /**
+      * GET /api/contracts
+      * Returns all contracts across all networks
+      * Optional query param: ?network=testnet
+      */
+     static async getContracts(req: Request, res: Response): Promise<void> {
+          const startTime = Date.now();
+
+          try {
+               const { network } = req.query;
+
+               let responseData;
+
+               if (typeof network === 'string' && network.length > 0) {
+                    const contracts =
+                         ContractRegistryService.getContractsByNetwork(network);
+
+                    responseData = {
+                         network,
+                         contracts,
+                         count: Object.keys(contracts).length,
+                    };
+               } else {
+                    const networks = ContractRegistryService.getAllContracts();
+
+                    responseData = {
+                         networks,
+                         count: Object.keys(networks).length,
+                    };
+               }
+
+               // Set response headers
+               res.setHeader('Content-Type', 'application/json');
+               res.setHeader('Cache-Control', 'public, max-age=3600'); // cache 1 hour
+
+               const responseTime = Date.now() - startTime;
+
+               if (responseTime > 500) {
+                    logger.warn(
+                         `Contract registry response slow: ${responseTime}ms`
+                    );
+               }
+
+               res.status(200).json({
+                    ...responseData,
+                    timestamp: new Date().toISOString(),
+               });
+          } catch (error) {
+               logger.error('Error retrieving contract registry', error);
+
+               res.status(500).json({
+                    error: 'Internal Server Error',
+                    message:
+                         error instanceof Error
+                              ? error.message
+                              : 'Failed to load contract registry',
+                    timestamp: new Date().toISOString(),
+               });
+          }
+     }
+}

backend/src/routes/contractRegistryRoutes.ts

@@ -0,0 +1,13 @@
+
+import { Router } from 'express';
+import { ContractRegistryController } from '../controllers/contractRegistryController.js';
+
+const router = Router();
+
+/**
+ * GET /api/contracts
+ * Optional: ?network=testnet
+ */
+router.get('/contracts', ContractRegistryController.getContracts);
+
+export default router;

backend/src/services/contractRegistryService.ts

@@ -0,0 +1,56 @@
+import fs from 'fs';
+import path from 'path';
+import toml from 'toml';
+
+export interface ContractInfo {
+     contractId: string;
+     version: string;
+     deployedAt: number;
+}
+
+export interface NetworkRegistry {
+     [contractName: string]: ContractInfo;
+}
+
+export interface ContractRegistry {
+     [network: string]: NetworkRegistry;
+}
+
+export class ContractRegistryService {
+     private static cache: ContractRegistry | null = null;
+
+     /**
+      * Load registry from environments.toml
+      * Cached after first read.
+      */
+     static loadRegistry(): ContractRegistry {
+          if (this.cache) return this.cache;
+
+          const filePath = path.join(process.cwd(), 'environments.toml');
+
+          if (!fs.existsSync(filePath)) {
+               throw new Error('environments.toml not found');
+          }
+
+          const raw = fs.readFileSync(filePath, 'utf-8');
+          const parsed = toml.parse(raw);
+
+          this.cache = parsed as ContractRegistry;
+          return this.cache;
+     }
+
+     /**
+      * Get all contracts across all networks
+      */
+     static getAllContracts(): ContractRegistry {
+          return this.loadRegistry();
+     }
+
+     /**
+      * Get contracts for a specific network
+      */
+     static getContractsByNetwork(network: string): NetworkRegistry {
+          const registry = this.loadRegistry();
+          return registry[network] ?? {};
+     }
+}