Skip to content

ORGANIZATION_FUND_DISTRIBUTION.md

Latest commit

 

History

History
147 lines (115 loc) · 5.35 KB

ORGANIZATION_FUND_DISTRIBUTION.md

File metadata and controls

147 lines (115 loc) · 5.35 KB

Organization Fund Distribution System

✅ Implementation Complete

Successfully implemented a comprehensive fund distribution system for organizations that allows equal distribution of funds to all members when the organization ends.

🎯 Features Implemented

1. Database Schema

Added to OrganisationModel:

  • distributionCompleted (boolean) - Tracks if funds have been distributed
  • distributionDate (timestamp) - When distribution occurred
  • distributionTxHash (varchar) - Blockchain transaction hash(es)

2. Backend API

DistributionHandler (server/handlers/DistributionHandler.js):

  • distributeOrganisationFunds() - Distributes funds equally to all members
  • getDistributionStatus() - Returns distribution status for an organization
  • canDistribute() - Checks if user has permission to distribute
  • checkAndDistributeExpired() - Finds expired orgs for cron job

API Endpoints (/api/distributions):

  • POST /organisation/:id/distribute - Trigger distribution (owner only)
  • GET /organisation/:id/status - Get distribution status
  • GET /organisation/:id/can-distribute - Check distribution permission

3. Frontend UI

OrganisationPage Updates:

  • "End Organization" Button - Visible only to owners when:
    • User is the organization owner
    • Funds haven't been distributed yet
    • Organization has funds to distribute
  • Distribution Status Badge - Shows "✓ FUNDS DISTRIBUTED" when complete
  • Confirmation Modal - Shows:
    • Total funds to distribute
    • Number of recipients
    • Amount per member
    • Warning that action cannot be undone

DistributionAPI (client/src/ApiFactory/DistributionAPI.js):

  • distributeOrganisationFunds(orgId) - Trigger distribution
  • getDistributionStatus(orgId) - Get status
  • canDistribute(orgId) - Check permission

💡 How It Works

Distribution Logic

// Equal distribution calculation
const totalFunds = BigInt(organisation.addedFunds);
const sharePerMember = totalFunds / BigInt(members.length);

// Transfer to each member
for (const member of members) {
    await ctkToken.transfer(member.userAddress, sharePerMember);
}

User Flow

For Organization Owners:

  1. Navigate to organization page
  2. See "END ORGANIZATION" button (if funds exist and not distributed)
  3. Click button → Confirmation modal appears
  4. Modal shows:
    • Total funds: e.g., "100 CTK"
    • Recipients: e.g., "5 members"
    • Amount per member: e.g., "20 CTK"
  5. Click "Confirm & Distribute"
  6. Funds transferred to all members
  7. Button changes to "✓ FUNDS DISTRIBUTED"

For Members:

  • See distribution status badge when funds are distributed
  • Receive equal share of organization funds
  • Can verify transaction on blockchain

🔒 Security Features

  1. Permission Control: Only owner can trigger distribution
  2. Idempotency: distributionCompleted flag prevents double distribution
  3. Transaction Safety: All transfers wrapped in try-catch
  4. Balance Verification: Checks owner has sufficient balance before distributing
  5. Audit Trail: Records all transaction hashes and timestamps

📊 Distribution Details

What Gets Distributed

  • All funds in organisation.addedFunds
  • Includes investments from all investors
  • Split equally among ALL members (regardless of role)

Who Receives Funds

  • All active organization members
  • Includes owners, users, and any other roles
  • Members who left (leftDate !== null) are excluded

Blockchain Integration

  • Uses CTKToken contract's transfer function
  • Oracle wallet executes transfers
  • All transactions recorded on-chain
  • Transaction hashes stored in database

🚀 Next Steps (Optional Enhancements)

Automatic Distribution (Cron Job)

  • Set up cron job to run checkAndDistributeExpired() daily
  • Automatically distribute funds when endDate passes
  • Requires cron service setup

Enhanced Features

  • Weighted Distribution: Distribute based on contribution or role
  • Partial Distribution: Allow distributing specific amounts
  • Distribution History: Track all distributions per organization
  • Email Notifications: Notify members when funds are distributed

📝 Files Modified

Backend

  • server/models/OrganisationModel.js - Added distribution fields
  • server/handlers/DistributionHandler.js - Distribution logic (NEW)
  • server/routes/DistributionRouter.js - API routes (NEW)
  • server/routes/IndexRouter.js - Added distribution router
  • server/apply_distribution_migration.js - Migration script (NEW)

Frontend

  • client/src/ApiFactory/DistributionAPI.js - API client (NEW)
  • client/src/pages/OrganisationPage.jsx - UI updates

✅ Testing Checklist

  • Create test organization with funds
  • Add multiple members
  • Click "End Organization" button
  • Verify modal shows correct calculations
  • Confirm distribution
  • Verify all members received equal amounts
  • Check distribution status updates
  • Verify button changes to "FUNDS DISTRIBUTED"
  • Test permission (non-owner cannot distribute)
  • Test duplicate prevention (cannot distribute twice)

🎉 Summary

The organization fund distribution system is fully implemented and ready for use. Owners can now easily end their organizations and distribute funds equally to all members with a single click. The system includes comprehensive security measures, blockchain integration, and a user-friendly interface.