# FlashDAO
###ˇ Multi-Chain Event-Based Donation and Governance System

This document details the functionalities, processes, and the interactions between different roles within the FlashDAO system. FlashDAO is a multi-chain donation and governance system that enables users to create, participate in, and manage event-specific DAOs.

## Table of Contents

- [System Architecture](#system-architecture)
- [Contract Structure](#contract-structure)
- [System Workflow](#system-workflow)
- [User Perspectives](#user-perspectives)
- [System Administrator](#system-administrator)
- [Event Creator](#event-creator)
- [Donor](#donor)
- [Volunteer](#volunteer)
- [Voter](#voter)
- [Function Interface Details](#function-interface-details)
- [Cross-Chain Interoperability](#cross-chain-interoperability)
- [Security Considerations](#security-considerations)

## System Architecture

The FlashDAO system consists of four main components:

1. **EventDAOFactory**: Creates and manages single-chain EventDAO instances.
2. **MultiChainDAOFactory**: Provides cross-chain deployment and coordination capabilities.
3. **EventDAO**: The DAO for a specific event, managing donations, voting, and fund distribution.
4. **VolunteerRegistry**: Manages volunteer registration and identity verification.

Additionally, the system integrates with:
- **FlashDAOToken**: The governance token used for calculating voting weight.
- **Self Protocol**: Used for identity verification.

## Contract Structure

FlashDAO
├── EventDAOFactory.sol - Event DAO factory contract
├── MultiChainDAOFactory.sol - Multi-chain DAO factory contract
├── EventDAO.sol - Main contract for the event-specific DAO
├── VolunteerRegistry.sol - Volunteer registration contract
├── FlashDAOToken.sol - Governance token contract
├── interfaces/
│   └── ISelfProtocol.sol - Self Protocol interface
└── mocks/
    ├── SelfProtocolMock.sol - Self Protocol mock for testing
    └── ERC20Mock.sol - ERC20 token mock for testing

## System Workflow

Below is the overall workflow of the system, from event creation to fund distribution:

### 1. Event Creation and Cross-Chain Deployment

sequenceDiagram
    participant Creator
    participant EventDAOFactory
    participant MultiChainDAOFactory
    participant Ethereum
    participant Base
    participant Avalanche

    Creator->>EventDAOFactory: createEventDAO(name, description, lifetime)
    EventDAOFactory->>EventDAOFactory: generateEventIdWithParams(name, description, timestamp, creator)
    EventDAOFactory->>EventDAOFactory: Deploy a new EventDAO
    EventDAOFactory-->>Creator: Return eventId and DAO address
    
    Creator->>MultiChainDAOFactory: generateEventIdWithParams(same parameters)
    Creator->>MultiChainDAOFactory: deployDAO(eventId, addresses)
    Note over Ethereum: Deployed on Ethereum
    
    Creator->>MultiChainDAOFactory: deployDAO(same eventId, addresses)
    Note over Base: Deployed on Base
    
    Creator->>MultiChainDAOFactory: deployDAO(same eventId, addresses)
    Note over Avalanche: Deployed on Avalanche

### 2. Volunteer Registration and Approval

sequenceDiagram
    participant Volunteer
    participant EventDAO
    participant SelfProtocol
    participant Admin

    Volunteer->>SelfProtocol: Perform identity verification
    SelfProtocol-->>Volunteer: Return credentials
    
    Volunteer->>EventDAO: registerAsVolunteer(name, description, credentials)
    EventDAO->>SelfProtocol: verifyCredentials(address, credentials)
    SelfProtocol-->>EventDAO: Verification result
    EventDAO-->>Volunteer: Registration outcome
    
    Admin->>EventDAO: approveVolunteer(volunteerIndex)
    EventDAO-->>Admin: Approval outcome

### 3. Donation and Token Issuance

sequenceDiagram
    participant Donor
    participant USDC
    participant EventDAO
    
    Donor->>USDC: approve(eventDAO, amount)
    Donor->>EventDAO: donate(amount)
    EventDAO->>USDC: transferFrom(donor, this, amount)
    EventDAO->>EventDAO: calculateTokenAmount(amount)
    EventDAO->>EventDAO: Update donation records and issue tokens
    EventDAO-->>Donor: Donation confirmation and token amount

### 4. Voting Process

sequenceDiagram
    participant Voter
    participant EventDAO
    
    Voter->>EventDAO: vote(volunteerIndex)
    EventDAO->>EventDAO: Check voting weight
    EventDAO->>EventDAO: Record the vote
    EventDAO-->>Voter: Vote confirmation

### 5. Election Conclusion and Fund Distribution

sequenceDiagram
    participant Anyone
    participant EventDAO
    participant WinningVolunteer
    participant Donor
    
    Note over EventDAO: DAO expires
    
    Anyone->>EventDAO: concludeElection()
    EventDAO->>EventDAO: Calculate the winner
    
    alt Winner exists
        Anyone->>EventDAO: distributeFunds()
        EventDAO->>WinningVolunteer: Transfer all USDC
    else No winner
        Donor->>EventDAO: claimRefund()
        EventDAO->>Donor: Refund USDC proportionally
    end

### 6. Cross-Chain Result Aggregation (External Process)

sequenceDiagram
    participant Relay
    participant EthereumDAO
    participant BaseDAO
    participant AvalancheDAO
    participant ResultAggregationService
    
    Relay->>EthereumDAO: Fetch voting results
    Relay->>BaseDAO: Fetch voting results
    Relay->>AvalancheDAO: Fetch voting results
    
    Relay->>ResultAggregationService: Submit all results
    ResultAggregationService->>ResultAggregationService: Calculate overall winner
    
    Relay->>EthereumDAO: concludeElection()
    Relay->>BaseDAO: concludeElection()
    Relay->>AvalancheDAO: concludeElection()
    
    Relay->>EthereumDAO: distributeFunds()
    Relay->>BaseDAO: distributeFunds()
    Relay->>AvalancheDAO: distributeFunds()

## User Perspectives

### System Administrator

The system administrator is responsible for deploying and managing the overall system.

**Related Contracts**: `EventDAOFactory`, `MultiChainDAOFactory`

| Stage | Operation | Function Call |
|------------------|--------------------------------------|------------------------------------------------|
| Initial Deployment | Deploy EventDAOFactory | `constructor(usdcAddress, selfProtocolAddress)` |
| Initial Deployment | Deploy MultiChainDAOFactory | `constructor()` |
| Permission Management | Grant event creator role | `grantRole(CREATOR_ROLE, address)` |
| Permission Management | Grant deployer role | `grantRole(DEPLOYER_ROLE, address)` |
| Emergency Operations | Deactivate DAO on a specific chain | `deactivateDAO(eventId)` |

### Event Creator

Event creators are responsible for creating and managing DAOs for specific events.

**Related Contracts**: `EventDAOFactory`, `MultiChainDAOFactory`, `EventDAO`

| Stage | Operation | Function Call |
|------------------|--------------------------------------------------|---------------------------------------------------------------------|
| Event Creation | Generate event ID | `generateEventIdWithParams(name, description, timestamp, creator)` |
| Event Creation | Create an event DAO | `createEventDAO(name, description, lifetime)` |
| Cross-Chain Deployment | Deploy the same DAO on other chains | `deployDAO(eventId, daoAddress, tokenAddress, registryAddress)` |
| Volunteer Management | Approve volunteers | `approveVolunteer(volunteerIndex)` |
| Election Management | Conclude the election | `concludeElection()` |
| Fund Distribution | Distribute funds to the winner | `distributeFunds()` |
| Data Query | View active events | `getActiveEventDAOs()` |
| Data Query | View expired events | `getExpiredEventDAOs()` |
| Cross-Chain Management | Check deployment on a specific chain | `getDeployment(eventId, chainId)` |
| Cross-Chain Management | Query active deployments on the current chain | `getActiveDeploymentsOnCurrentChain()` |

### Donor

Donors provide funds for the event and receive voting rights.

**Related Contract**: `EventDAO`

| Stage | Operation | Function Call |
|---------------|------------------------------------------|--------------------------------------------------------|
| Donation Preparation | Approve USDC spending | USDC: `approve(eventDAOAddress, amount)` |
| Donation | Donate USDC | `donate(amount)` |
| Voting | Vote for a volunteer | `vote(volunteerIndex)` |
| Refund | Claim a refund if there is no winner | `claimRefund()` |
| Data Query | Check individual voting power | `votingPower(address)` |
| Data Query | Check individual donation amount | `donations(address)` |
| Data Query | Check token balance | `balanceOf(address)` |

### Volunteer

Volunteers register to participate in specific events and provide services.

**Related Contracts**: `EventDAO`, `SelfProtocol`

| Stage | Operation | Function Call |
|-----------------|--------------------------------------------|------------------------------------------------------------|
| Identity Verification | Verify identity using Self Protocol | Self Protocol: (follow relevant identity verification steps)|
| Registration | Register as a volunteer | `registerAsVolunteer(name, description, credentials)` |
| Awaiting Approval | Wait for administrator approval | N/A |
| Receiving Funds | Automatically receive USDC if winning | Automatic USDC transfer |
| Data Query | Query volunteer information | `getVolunteer(volunteerIndex)` |
| Data Query | Check the number of votes received | `volunteerVotes(volunteerIndex)` |

### Voter

Voters use tokens to vote for volunteers.

**Related Contract**: `EventDAO`

| Stage | Operation | Function Call |
|-----------------|------------------------------------------|----------------------------------------------------|
| Acquiring Voting Rights | Donate USDC to obtain tokens | `donate(amount)` |
| Viewing Volunteers | Retrieve volunteer information | `getVolunteer(volunteerIndex)` |
| Voting | Vote for a volunteer | `vote(volunteerIndex)` |
| Data Query | Check voting power | `votingPower(address)` |
| Data Query | Verify if already voted | `hasVoted(address)` |

## Function Interface Details

### EventDAOFactory

// Create an event DAO
function createEventDAO(
    string calldata eventName,
    string calldata eventDescription,
    uint256 lifetime
) external onlyRole(CREATOR_ROLE) returns (bytes32)

// Generate an event ID
function generateEventIdWithParams(
    string memory eventName,
    string memory eventDescription,
    uint256 creationTimestamp,
    address creator
) public pure returns (bytes32)

// Retrieve active event DAOs
function getActiveEventDAOs() external view returns (bytes32[] memory)

// Retrieve expired event DAOs
function getExpiredEventDAOs() external view returns (bytes32[] memory)

// Get the total number of event DAOs
function getEventDAOCount() external view returns (uint256)

### MultiChainDAOFactory

// Deploy DAO on the current chain
function deployDAO(
    bytes32 eventId,
    address eventDAOAddress,
    address tokenAddress,
    address volunteerRegistryAddress
) external onlyRole(DEPLOYER_ROLE)

// Generate an event ID (using the same logic as EventDAOFactory)
function generateEventIdWithParams(
    string memory eventName,
    string memory eventDescription,
    uint256 creationTimestamp,
    address creator
) public pure returns (bytes32)

// Compatibility method
function generateEventId(
    string memory eventName,
    string memory eventDescription
) external view returns (bytes32)

// Deactivate a DAO
function deactivateDAO(bytes32 eventId) external onlyRole(ADMIN_ROLE)

// Retrieve deployment information on a specific chain
function getDeployment(bytes32 eventId, uint256 chainId) external view returns (ChainDeployment memory)

// Retrieve deployment information on the current chain
function getCurrentChainDeployment(bytes32 eventId) external view returns (ChainDeployment memory)

// Retrieve all event IDs
function getAllEventIds() external view returns (bytes32[] memory)

// Get the total number of events
function getEventCount() external view returns (uint256)

// Retrieve all active deployments on the current chain
function getActiveDeploymentsOnCurrentChain() external view returns (bytes32[] memory)

### EventDAO

// Donate USDC
function donate(uint256 amount) external nonReentrant

// Register as a volunteer
function registerAsVolunteer(
    string calldata name,
    string calldata description,
    bytes calldata credentials
) external nonReentrant

// Approve a volunteer
function approveVolunteer(uint256 _volunteerIndex) external onlyRole(ADMIN_ROLE)

// Vote for a volunteer
function vote(uint256 _volunteerIndex) external nonReentrant

// Conclude the election
function concludeElection() external nonReentrant

// Distribute funds to the winner
function distributeFunds() external nonReentrant

// Claim a refund if there is no winner
function claimRefund() external nonReentrant

// Calculate the token amount
function calculateTokenAmount(uint256 donationAmount) public pure returns (uint256)

// Retrieve total donation amount
function getTotalDonations() public view returns (uint256)

// Retrieve all donors
function getDonors() public view returns (address[] memory)

// Retrieve the number of donors
function getDonorCount() external view returns (uint256)

// Retrieve the number of volunteers
function getVolunteerCount() external view returns (uint256)

// Retrieve volunteer information
function getVolunteer(uint256 index) external view returns (address, string memory, string memory, bool, uint256)

// Check if the DAO has expired
function isExpired() external view returns (bool)

// Check if it is in refund mode
function isInRefundMode() external view returns (bool)

### VolunteerRegistry

// Register a volunteer
function registerVolunteer(address volunteer, string memory name, string memory description) external

// Approve a volunteer
function approveVolunteer(address volunteer) external onlyRole(ADMIN_ROLE)

// Remove a volunteer
function removeVolunteer(address volunteer) external onlyRole(ADMIN_ROLE)

// Check if an address is a volunteer
function isVolunteer(address volunteer) external view returns (bool)

// Retrieve volunteer information
function getVolunteerInfo(address volunteer) external view returns (VolunteerInfo memory)

// Retrieve all volunteers
function getAllVolunteers() external view returns (address[] memory)

// Get the number of volunteers
function getVolunteerCount() external view returns (uint256)

## Cross-Chain Interoperability

FlashDAO supports deploying the same event DAO on multiple blockchains by generating consistent event IDs to achieve cross-chain coordination.

### Cross-Chain Event ID Generation

Generating a consistent event ID is crucial for cross-chain operations:

function generateEventIdWithParams(
    string memory eventName,
    string memory eventDescription,
    uint256 creationTimestamp,
    address creator
) public pure returns (bytes32) {
    return keccak256(abi.encodePacked(eventName, eventDescription, creationTimestamp, creator));
}

This ensures that the same parameters will produce an identical ID on any chain.

### Cross-Chain Coordination Workflow

1. Create the event DAO on the first chain and record the event parameters and ID.
2. Deploy the DAO on other chains using the same parameters to ensure the event ID is consistent.
3. Donors and voters can participate on any chain.
4. An external relay system collects voting results from each chain.
5. The relay calls `concludeElection()` and `distributeFunds()` on each chain.
6. Funds on each chain are distributed to the winning volunteer.

## Security Considerations

### Parameter Validation

All critical functions perform input validation:

// During event creation
require(bytes(eventName).length > 0, "Event name cannot be empty");

// During donation
require(amount > 0, "Amount must be greater than 0");

// During voting
require(_volunteerIndex < volunteers.length, "Invalid volunteer index");
require(volunteers[_volunteerIndex].approved, "Volunteer not approved");
require(votingPower[msg.sender] > 0, "No voting power");
require(!hasVoted[msg.sender], "Already voted");

### Reentrancy Protection

Sensitive functions use ReentrancyGuard:

function donate(uint256 amount) external nonReentrant { ... }
function vote(uint256 _volunteerIndex) external nonReentrant { ... }
function concludeElection() external nonReentrant { ... }
function distributeFunds() external nonReentrant { ... }
function claimRefund() external nonReentrant { ... }

### Access Control

Role permissions are managed using AccessControl:

function approveVolunteer(uint256 _volunteerIndex) external onlyRole(ADMIN_ROLE) { ... }
function createEventDAO(...) external onlyRole(CREATOR_ROLE) returns (bytes32) { ... }
function deployDAO(...) external onlyRole(DEPLOYER_ROLE) { ... }
function deactivateDAO(bytes32 eventId) external onlyRole(ADMIN_ROLE) { ... }

### Fund Security

USDC transfers are executed using the Checks-Effects-Interactions (CEI) pattern:

// In distributeFunds()
require(electionConcluded, "Election not concluded");
require(!fundsDistributed, "Funds already distributed");
require(!noWinner, "No winner elected");

fundsDistributed = true; // Set state first

// Then execute the transfer
uint256 balance = usdcToken.balanceOf(address(this));
require(usdcToken.transfer(winner, balance), "USDC transfer failed");

---

Let me know if you need any further adjustments or additions, Ella!