owned this note
owned this note
Published
Linked with GitHub
# 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
```mermaid
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
```mermaid
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
```mermaid
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
```mermaid
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
```mermaid
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)
```mermaid
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
```solidity
// 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
```solidity
// 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
```solidity
// 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
```solidity
// 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:
```solidity
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:
```solidity
// 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:
```solidity
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:
```solidity
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:
```solidity
// 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!
Google Drive
Gist
Clipboard
Sign in with Wallet
