Refactor code and enhance maintainability.

Author: abrar2030

.github/workflows/cicd.yml

@@ -58,7 +58,43 @@ jobs:
             --check "**/*.{js,jsx,ts,tsx,json,html,css,md,sol,yml,yaml}"
 
   # ============================================================
-  # Job 2 -- Backend Tests (Python / Pytest)
+  # Job 2 -- Blockchain (Smart Contract) Compile & Test
+  # ============================================================
+  # Previously nothing in CI actually compiled or ran the Solidity test
+  # suite - code_quality only checked contract *formatting* via Prettier.
+  # A contract change that broke compilation or a test could merge with a
+  # fully green CI run.
+  blockchain_tests:
+    name: Blockchain Compile & Test
+    runs-on: ubuntu-latest
+    needs: code_quality
+
+    defaults:
+      run:
+        working-directory: code/blockchain
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: code/blockchain/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Compile contracts
+        run: npm run compile
+
+      - name: Run contract test suite
+        run: npm test
+
+  # ============================================================
+  # Job 3 -- Backend Tests (Python / Pytest)
   # ============================================================
   backend_tests:
     name: Backend Tests
@@ -107,7 +143,7 @@ jobs:
           retention-days: 30
 
   # ============================================================
-  # Job 3 -- Web Frontend Build
+  # Job 4 -- Web Frontend Build
   # ============================================================
   web-frontend_test_and_build:
     name: Web-Frontend Test & Build
@@ -147,7 +183,7 @@ jobs:
           retention-days: 7
 
   # ============================================================
-  # Job 4 -- Mobile Frontend (Expo) Build & Test
+  # Job 5 -- Mobile Frontend (Expo) Build & Test
   # ============================================================
   mobile_frontend:
     name: Mobile-Frontend Test & Build

code/backend/.env.example

@@ -54,6 +54,11 @@ ENCRYPTION_KEY=your-encryption-key-32-chars-long
 FIELD_ENCRYPTION_ENABLED=true
 
 # Blockchain Configuration
+# For local development, leave ETH_RPC_URL/addresses unset and instead run
+# `npm run deploy:localhost` in code/blockchain (after `npm run node` there
+# in another terminal) - the backend automatically picks up RPC URL and
+# contract addresses from the deployment manifest that writes to
+# (BLOCKCHAIN_DEPLOYMENT_FILE below), no copy-pasting addresses required.
 ETH_RPC_URL=https://mainnet.infura.io/v3/YOUR_PROJECT_ID
 ETH_WEBSOCKET_URL=wss://mainnet.infura.io/ws/v3/YOUR_PROJECT_ID
 ETH_CHAIN_ID=1
@@ -63,8 +68,19 @@ BSC_RPC_URL=https://bsc-dataseed.binance.org/
 BSC_CHAIN_ID=56
 GAS_PRICE_STRATEGY=medium
 MAX_GAS_PRICE=100
+WEB3_REQUEST_TIMEOUT=5
+
+# ChainFinity's own deployed contracts (see code/blockchain/contracts).
+# Leave unset to resolve from BLOCKCHAIN_DEPLOYMENT_FILE instead (local dev
+# default); set explicitly for staging/production, where they take
+# priority over the deployment file.
 GOVERNANCE_TOKEN_ADDRESS=
 ASSET_VAULT_ADDRESS=
+CROSS_CHAIN_MANAGER_ADDRESS=
+DEFI_PROTOCOL_ADDRESS=
+GOVERNANCE_ADDRESS=
+BLOCKCHAIN_DEPLOYMENT_FILE=../blockchain/deployments/contracts.localhost.json
+
 ETHERSCAN_API_KEY=your_etherscan_api_key
 POLYGONSCAN_API_KEY=your_polygonscan_api_key
 

code/backend/app/api/v1/endpoints/blockchain.py

@@ -12,7 +12,14 @@
 from fastapi import APIRouter, Depends, HTTPException, Query, status
 from models.blockchain import BlockchainNetwork, ContractEvent, SmartContract
 from models.user import User
-from schemas.blockchain import ContractResponse, EventResponse, NetworkResponse
+from schemas.blockchain import (
+    ContractResponse,
+    DeployedContractResponse,
+    DeployedContractsResponse,
+    EventResponse,
+    NetworkResponse,
+)
+from services.blockchain import BlockchainUnavailableError, web3_client
 from sqlalchemy import desc, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -232,19 +239,30 @@ async def verify_blockchain_address(
     Verify blockchain address format and validity
     """
     try:
-        # Basic validation
-        is_valid = False
+        # web3's is_address covers what a hand-rolled `len(address) == 42`
+        # check doesn't: non-hex characters, and (via is_checksum_address)
+        # a mixed-case address whose checksum doesn't match its digits -
+        # both silently passed the old length-only check.
+        is_valid = web3_client.is_valid_address(address)
         address_type = "unknown"
-
-        if network.lower() in ["ethereum", "polygon", "bsc"]:
-            # Check if it's a valid Ethereum-style address
-            if address.startswith("0x") and len(address) == 42:
-                is_valid = True
-                address_type = "EOA"  # Externally Owned Account
-                # Could check if it's a contract by querying the network
+        checksum_address = None
+
+        if is_valid:
+            checksum_address = web3_client.to_checksum_address(address)
+            try:
+                is_contract = await web3_client.is_contract_address(address)
+                address_type = "contract" if is_contract else "EOA"
+            except BlockchainUnavailableError as exc:
+                # Format is still valid even if we can't reach the chain to
+                # tell EOA from contract - report that distinctly from an
+                # actually-invalid address instead of returning "unknown"
+                # silently for both cases.
+                logger.info(f"Could not classify address {address}: {exc}")
+                address_type = "unknown (RPC unavailable)"
 
         return {
             "address": address,
+            "checksum_address": checksum_address,
             "network": network,
             "is_valid": is_valid,
             "address_type": address_type,
@@ -267,20 +285,33 @@ async def get_address_balance(
     db: AsyncSession = Depends(get_async_session),
 ) -> Any:
     """
-    Get balance for a blockchain address
+    Get the native-currency balance for a blockchain address on the
+    configured RPC network (see ETH_RPC_URL). "network" is currently
+    informational only - this backend talks to a single configured chain;
+    per-network routing (Polygon, BSC, ...) would need a
+    network -> Web3Client mapping in services.blockchain.
     """
+    if not web3_client.is_valid_address(address):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid blockchain address",
+        )
     try:
-        # In a real implementation, this would query the blockchain
-        # For now, return a mock response
+        balance_wei = await web3_client.get_balance(address)
         return {
             "address": address,
             "network": network,
-            "balance": "0",
-            "balance_usd": "0",
+            "balance": str(balance_wei / 10**18),
+            "balance_wei": str(balance_wei),
             "tokens": [],
             "last_updated": datetime.now(timezone.utc).isoformat(),
         }
-
+    except BlockchainUnavailableError as e:
+        logger.warning(f"Blockchain unavailable while fetching balance: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Blockchain RPC endpoint is currently unavailable",
+        )
     except Exception as e:
         logger.error(f"Error getting address balance: {e}")
         raise HTTPException(
@@ -295,13 +326,32 @@ async def get_gas_price(
     db: AsyncSession = Depends(get_async_session),
 ) -> Any:
     """
-    Get current gas price for a network
+    Get the current gas price from the configured RPC network. Falls back to
+    a clearly-labeled estimate (rather than erroring the whole request) when
+    the RPC endpoint isn't reachable, since this is typically a secondary
+    display widget rather than something a transaction is submitted from.
     """
     try:
-        # Mock gas price response
+        gas_price_wei = await web3_client.get_gas_price()
+        gas_price_gwei = gas_price_wei / 10**9
+        return {
+            "network": network,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "live": True,
+            "gas_prices": {
+                "slow": str(round(gas_price_gwei * 0.9, 2)),
+                "standard": str(round(gas_price_gwei, 2)),
+                "fast": str(round(gas_price_gwei * 1.2, 2)),
+                "rapid": str(round(gas_price_gwei * 1.5, 2)),
+            },
+            "unit": "gwei",
+        }
+    except BlockchainUnavailableError as e:
+        logger.info(f"Gas price RPC call failed, returning estimate: {e}")
         return {
             "network": network,
             "timestamp": datetime.now(timezone.utc).isoformat(),
+            "live": False,
             "gas_prices": {
                 "slow": "20",
                 "standard": "25",
@@ -310,7 +360,6 @@ async def get_gas_price(
             },
             "unit": "gwei",
         }
-
     except Exception as e:
         logger.error(f"Error getting gas price: {e}")
         raise HTTPException(
@@ -319,6 +368,38 @@ async def get_gas_price(
         )
 
 
+@router.get("/deployed-contracts", response_model=DeployedContractsResponse)
+async def get_deployed_contracts() -> Any:
+    """
+    Address book for ChainFinity's own protocol contracts (AssetVault,
+    CrossChainManager, InstitutionalDeFiProtocol, GovernanceToken,
+    InstitutionalGovernance) on the connected network. This is the
+    integration point clients (web/mobile) use to know what to call - see
+    web-frontend/src/services/api.js's blockchainAPI.getDeployedContracts.
+
+    `connected: false` with an empty/partial contract list means the RPC
+    endpoint (ETH_RPC_URL) isn't reachable right now, not that the contracts
+    don't exist - addresses resolved from BLOCKCHAIN_DEPLOYMENT_FILE or the
+    explicit *_ADDRESS settings are still returned either way.
+    """
+    contracts = web3_client.get_deployed_contracts()
+    connected = await web3_client.is_connected()
+    chain_id = await web3_client.get_chain_id() if connected else None
+
+    return DeployedContractsResponse(
+        chain_id=chain_id,
+        connected=connected,
+        contracts=[
+            DeployedContractResponse(
+                name=name,
+                address=contract.address,
+                has_abi=bool(contract.abi),
+            )
+            for name, contract in sorted(contracts.items())
+        ],
+    )
+
+
 # ── Frontend convenience endpoints ───────────────────────────────────────────
 # The web and mobile clients call these portfolio/transaction/eth-balance
 # routes. They return blockchain-derived views in the shapes the clients
@@ -442,18 +523,36 @@ async def get_eth_balance(
     db: AsyncSession = Depends(get_async_session),
 ) -> Any:
     """
-    Return the current user's native ETH balance. Uses the user's primary
-    wallet address when available.
+    Return the current user's native ETH balance, read live from the
+    configured RPC network for their linked primary_wallet_address.
     """
+    wallet = getattr(current_user, "primary_wallet_address", None)
+
+    if not wallet:
+        return {
+            "address": None,
+            "network": "ethereum",
+            "balance": None,
+            "balance_wei": None,
+            "message": "No wallet address linked to this account",
+            "last_updated": datetime.now(timezone.utc).isoformat(),
+        }
+
     try:
-        wallet = getattr(current_user, "primary_wallet_address", None)
+        balance_wei = await web3_client.get_balance(wallet)
         return {
             "address": wallet,
             "network": "ethereum",
-            "balance": "4.2",
-            "balance_usd": "12600.00",
+            "balance": str(balance_wei / 10**18),
+            "balance_wei": str(balance_wei),
             "last_updated": datetime.now(timezone.utc).isoformat(),
         }
+    except BlockchainUnavailableError as e:
+        logger.warning(f"Blockchain unavailable while fetching ETH balance: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Blockchain RPC endpoint is currently unavailable",
+        )
     except Exception as e:
         logger.error(f"Error getting ETH balance: {e}")
         raise HTTPException(

code/backend/config/settings.py

@@ -83,8 +83,36 @@ class Settings(BaseSettings):
     BSC_CHAIN_ID: int = Field(default=56)
     GAS_PRICE_STRATEGY: str = Field(default="medium")
     MAX_GAS_PRICE: int = Field(default=100)
+    # RPC request timeout, in seconds. Applies to every call the backend
+    # makes to ETH_RPC_URL (see services/blockchain/client.py). Kept
+    # short so a misconfigured/unreachable node degrades an API response
+    # in ~5s instead of hanging the request.
+    WEB3_REQUEST_TIMEOUT: int = Field(default=5)
+
+    # ChainFinity protocol contract addresses on ETH_RPC_URL / ETH_CHAIN_ID.
+    # For local development these are picked up automatically from
+    # code/blockchain/deployments/contracts.<network>.json (see
+    # BLOCKCHAIN_DEPLOYMENT_FILE below and Web3Client._load_deployment) after
+    # running `npm run deploy:localhost` in code/blockchain - you don't need
+    # to copy addresses here by hand. Set these explicitly for staging/
+    # production, where they take priority over the deployment file.
     GOVERNANCE_TOKEN_ADDRESS: Optional[str] = None
     ASSET_VAULT_ADDRESS: Optional[str] = None
+    CROSS_CHAIN_MANAGER_ADDRESS: Optional[str] = None
+    DEFI_PROTOCOL_ADDRESS: Optional[str] = None
+    GOVERNANCE_ADDRESS: Optional[str] = None
+
+    # Path to the JSON manifest scripts/deploy.js writes (address + ABI per
+    # contract). Relative paths are resolved against the backend package
+    # root (see services/blockchain/client.py:_BACKEND_ROOT), not the
+    # process's current working directory. Defaults to the localhost
+    # deployment produced by the blockchain workspace's own dev workflow
+    # (see code/blockchain/README and scripts/run_chainfinity.sh) so a
+    # fresh local checkout works with zero configuration once contracts are
+    # deployed.
+    BLOCKCHAIN_DEPLOYMENT_FILE: str = Field(
+        default="../blockchain/deployments/contracts.localhost.json"
+    )
     ETHERSCAN_API_KEY: Optional[str] = None
     POLYGONSCAN_API_KEY: Optional[str] = None
 
@@ -261,8 +289,13 @@ def __init__(self, settings: Settings) -> None:
                 self.BSC_CHAIN_ID = settings.BSC_CHAIN_ID
                 self.GAS_PRICE_STRATEGY = settings.GAS_PRICE_STRATEGY
                 self.MAX_GAS_PRICE = settings.MAX_GAS_PRICE
+                self.WEB3_REQUEST_TIMEOUT = settings.WEB3_REQUEST_TIMEOUT
                 self.GOVERNANCE_TOKEN_ADDRESS = settings.GOVERNANCE_TOKEN_ADDRESS
                 self.ASSET_VAULT_ADDRESS = settings.ASSET_VAULT_ADDRESS
+                self.CROSS_CHAIN_MANAGER_ADDRESS = settings.CROSS_CHAIN_MANAGER_ADDRESS
+                self.DEFI_PROTOCOL_ADDRESS = settings.DEFI_PROTOCOL_ADDRESS
+                self.GOVERNANCE_ADDRESS = settings.GOVERNANCE_ADDRESS
+                self.BLOCKCHAIN_DEPLOYMENT_FILE = settings.BLOCKCHAIN_DEPLOYMENT_FILE
                 self.ETHERSCAN_API_KEY = settings.ETHERSCAN_API_KEY
                 self.POLYGONSCAN_API_KEY = settings.POLYGONSCAN_API_KEY
 

code/backend/models/base.py

@@ -2,7 +2,7 @@
 from datetime import datetime, timezone
 from typing import Any, Dict, Optional
 
-from sqlalchemy import JSON, UUID, Boolean, Column, DateTime, Integer, String
+from sqlalchemy import JSON, Boolean, Column, DateTime, Integer, String, Uuid
 from sqlalchemy.ext.declarative import declared_attr
 from sqlalchemy.orm import declarative_base
 
@@ -11,7 +11,7 @@
 
 class BaseModel(Base):
     __abstract__ = True
-    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4, index=True)
+    id = Column(Uuid(as_uuid=True), primary_key=True, default=uuid.uuid4, index=True)
 
     @declared_attr
     def __tablename__(cls: Any) -> str:
@@ -61,8 +61,8 @@ def restore(self) -> None:
 
 
 class AuditMixin:
-    created_by = Column(UUID(as_uuid=True), nullable=True, index=True)
-    updated_by = Column(UUID(as_uuid=True), nullable=True, index=True)
+    created_by = Column(Uuid(as_uuid=True), nullable=True, index=True)
+    updated_by = Column(Uuid(as_uuid=True), nullable=True, index=True)
     audit_metadata = Column(JSON, nullable=True)
 
     def set_audit_info(