Merge pull request #84 from Alhaji-naira/feature/core-protocol-enhancements

feat: implement Docker setup, Property IDs, Yield Generator, and Part…

Author: elizabetheonoja-art

Dockerfile

@@ -0,0 +1,13 @@
+FROM node:18-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+
+RUN npm install
+
+COPY . .
+
+EXPOSE 3000
+
+CMD ["npm", "start"]

PROPERTY_METADATA_STANDARD.md

@@ -0,0 +1,48 @@
+# Standardizing On-Chain Property IDs (LeaseFlow Protocol)
+
+## Overview
+To ensure interoperability with future Real Estate Marketplaces on the Stellar network, LeaseFlow implements a universal "Property Asset Metadata" standard. This allows properties to be universally identified and described on-chain.
+
+## On-Chain Representation
+Each property is represented as a distinct asset or within a Soroban smart contract state, associated with a unique IPFS CID containing the property metadata. The standard relies on a deterministic hashing of the property's physical location (coordinates + standardized address) combined with the owner's Stellar account to create a unique identifier.
+
+## JSON Schema Standard (Stored on IPFS)
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "PropertyAssetMetadata",
+  "type": "object",
+  "properties": {
+    "propertyId": {
+      "type": "string",
+      "description": "Unique deterministic hash of the property"
+    },
+    "address": {
+      "type": "object",
+      "properties": {
+        "street": { "type": "string" },
+        "city": { "type": "string" },
+        "stateProvince": { "type": "string" },
+        "country": { "type": "string" },
+        "postalCode": { "type": "string" }
+      },
+      "required": ["street", "city", "country"]
+    },
+    "specifications": {
+      "type": "object",
+      "properties": {
+        "bedrooms": { "type": "number" },
+        "bathrooms": { "type": "number" },
+        "squareFootage": { "type": "number" },
+        "zoning": { "type": "string" },
+        "yearBuilt": { "type": "number" }
+      },
+      "required": ["bedrooms", "squareFootage", "zoning"]
+    }
+  },
+  "required": ["propertyId", "address", "specifications"]
+}
+```
+
+By agreeing on how to store "Bedrooms," "SqFt," and "Zoning" on-chain, we ensure that LeaseFlow is interoperable with any decentralized application built on Stellar.

docker-compose.yml

@@ -0,0 +1,62 @@
+version: '3.8'
+
+services:
+  api:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=development
+      - PORT=3000
+      - DATABASE_URL=postgresql://leaseflow:password@postgres:5432/leaseflow_db
+      - REDIS_URL=redis://redis:6379
+      - STELLAR_NETWORK=testnet
+      - HORIZON_URL=http://stellar:8000
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    volumes:
+      - .:/app
+      - /app/node_modules
+
+  postgres:
+    image: postgres:14-alpine
+    environment:
+      - POSTGRES_USER=leaseflow
+      - POSTGRES_PASSWORD=password
+      - POSTGRES_DB=leaseflow_db
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U leaseflow -d leaseflow_db"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+  redis:
+    image: redis:6-alpine
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  stellar:
+    image: stellar/quickstart:testing
+    command: --testnet --enable-soroban-rpc
+    ports:
+      - "8000:8000"
+      - "11626:11626"
+      - "11625:11625"
+    volumes:
+      - stellar_data:/opt/stellar
+
+volumes:
+  postgres_data:
+  stellar_data:

services/rentPaymentTrackerService.js

@@ -130,7 +130,28 @@ class RentPaymentTrackerService {
 
     // Update the lease payment status if we matched a lease.
     if (leaseId) {
-      this.database.updateLeasePaymentStatus(leaseId, 'paid', op.created_at);
+      const expectedRent = parseFloat(lease.rent_amount) || 0;
+      const paidAmount = parseFloat(op.amount);
+      const previousBalance = parseFloat(lease.remaining_balance) || 0;
+      
+      const totalDue = expectedRent + previousBalance;
+      
+      if (paidAmount < totalDue) {
+        const remainingBalance = totalDue - paidAmount;
+        const lateFeePercentage = 0.05; // 5% late fee on unpaid portion
+        const appliedLateFee = remainingBalance * lateFeePercentage;
+        
+        this.database.updateLeasePaymentStatus(leaseId, 'partial', op.created_at);
+        if (this.database.updateLeaseBalance) {
+          this.database.updateLeaseBalance(leaseId, remainingBalance, appliedLateFee);
+        }
+        console.warn(`[Debt Alert] Lease ${leaseId} partially paid. Remaining: ${remainingBalance}, Late Fee: ${appliedLateFee}`);
+      } else {
+        this.database.updateLeasePaymentStatus(leaseId, 'paid', op.created_at);
+        if (this.database.updateLeaseBalance) {
+          this.database.updateLeaseBalance(leaseId, 0, 0);
+        }
+      }
     }
 
     return 'recorded';

src/db/appDatabase.js

@@ -65,6 +65,8 @@ class AppDatabase {
         bedrooms INTEGER,
         bathrooms INTEGER,
         square_footage INTEGER,
+        remaining_balance REAL DEFAULT 0,
+        applied_late_fee REAL DEFAULT 0,
         created_at TEXT NOT NULL,
         updated_at TEXT NOT NULL
       );
@@ -452,6 +454,8 @@ class AppDatabase {
           end_date AS endDate,
           renewable,
           disputed,
+          remaining_balance AS remainingBalance,
+          applied_late_fee AS appliedLateFee,
           created_at AS createdAt,
           updated_at AS updatedAt
         FROM leases
@@ -484,6 +488,8 @@ class AppDatabase {
           disputed,
           tenant_account_id AS tenantAccountId,
           payment_status    AS paymentStatus,
+          remaining_balance AS remainingBalance,
+          applied_late_fee  AS appliedLateFee,
           last_payment_at   AS lastPaymentAt,
           created_at        AS createdAt,
           updated_at        AS updatedAt
@@ -1247,6 +1253,8 @@ class AppDatabase {
            renewable,
            disputed,
            payment_status    AS paymentStatus,
+           remaining_balance AS remainingBalance,
+           applied_late_fee  AS appliedLateFee,
            last_payment_at   AS lastPaymentAt,
            created_at        AS createdAt,
            updated_at        AS updatedAt
@@ -1261,6 +1269,26 @@ class AppDatabase {
     return row ? normalizeLeaseRow(row) : null;
   }
 
+  /**
+   * Update a lease's remaining balance and applied late fee.
+   *
+   * @param {string} leaseId Lease identifier.
+   * @param {number} remainingBalance The unpaid rent balance.
+   * @param {number} appliedLateFee The newly applied late fee.
+   * @returns {void}
+   */
+  updateLeaseBalance(leaseId, remainingBalance, appliedLateFee) {
+    this.db
+      .prepare(
+        `UPDATE leases
+         SET remaining_balance = ?,
+             applied_late_fee  = ?,
+             updated_at        = ?
+         WHERE id = ?`,
+      )
+      .run(remainingBalance, appliedLateFee, new Date().toISOString(), leaseId);
+  }
+
   /**
    * Persist an uploaded utility bill and the computed tenant share.
    *

src/services/yieldGeneratorService.js

@@ -0,0 +1,52 @@
+/**
+ * YieldGeneratorService
+ * 
+ * Moves security deposits from a "Static Escrow" to a "Lending Pool" on Stellar.
+ * The interest earned is split between the tenant and the platform.
+ */
+
+class YieldGeneratorService {
+  constructor(stellarService, database) {
+    this.stellarService = stellarService;
+    this.database = database;
+    this.lendingPoolAddress = process.env.STELLAR_LENDING_POOL_ADDRESS;
+  }
+
+  /**
+   * Moves the security deposit to the lending pool.
+   * Requires explicit tenant consent.
+   */
+  async depositToYieldPool(leaseId, amount, tenantConsent) {
+    if (!tenantConsent) {
+      throw new Error("Tenant consent required for yield generation");
+    }
+    
+    // Move from static escrow to lending pool
+    const txHash = await this.stellarService.transferToPool(this.lendingPoolAddress, amount);
+    
+    // Record yield deposit in database
+    await this.database.recordYieldDeposit(leaseId, amount, txHash);
+    
+    return { success: true, txHash };
+  }
+
+  /**
+   * Calculates the yield generated and splits it between tenant and platform.
+   */
+  async calculateAndSplitYield(leaseId) {
+    // Calculate total yield generated from the pool for this lease
+    const yieldAmount = await this.stellarService.getYieldBalance(leaseId);
+    
+    // Split: 80% to tenant, 20% to platform
+    const tenantShare = yieldAmount * 0.8;
+    const platformShare = yieldAmount * 0.2;
+    
+    return {
+      totalYield: yieldAmount,
+      tenantShare,
+      platformShare
+    };
+  }
+}
+
+module.exports = { YieldGeneratorService };