# Allo Grants

This document describes the user flows and features for Allo Grants platform.

## Key Goals
- Users should be able to interact with the platform without thinking about Web3 wallets and networks *(to include a broader audience)*
- Round Operators should be able to create rounds of different mechanisms *(starting with QF)*
- Projects should be able to apply to Rounds using existing Application data
- Projects should be able to stay updated on their Application status
- Projects should be able to KYC so they can receive funding *(only $15k+?)*
- ...

## Key Features
- **Multi-Mechanism Support** - new mechanisms and round types should be easy to add
- **Multichain Orchestration** - users shouldn't have to bridge assets + new networks are easy to add
- **Sybil-defense / KYC** - proof of human for each address + compliance *(What about Self Protocol to scan passport?)*

## User Roles
- **Round Operator** - creates and manages rounds
- **Project** - submits application and receives funding
- **Donor/User** - discovers projects and donates
- **Badgeholder/Expert** - expert domain knowledge and votes for funding decisions
- **Admin/Platform** - oversees compliance, analytics?

## Flows

### Create Round
Round Operators create a Round for projects to apply for funding from.

#### User Flow

1. Round Operator navigates to Create Round page and enter details:
a. Title
b. Description and Eligibility
c. Start and End date *(should it be more granular with dates for applications start/end and payout?)*
d. Network *(Ethereum, Base, Arbitrum)*
e. Token *(ETH, USDC)* *(could there be multiple tokens?)*
f. Round type *(Direct Grants, Quadratic Funding, RetroFunding, etc)*
2. Press Create to submit
3. Round metadata is stored, contract is called, and user redirected to View Round page

#### Round Types
Quadratic Funding is the first Round Type to be supported but the architecture should easily support others.

##### Direct Grants
1. Project applications are directly approved and funded by Round Operators.

*Does it make sense for Direct Grants rounds to be continuous without any start or end dates?*

##### Quadratic Funding
In Quadratic Funding, the total match a project receives increases with the number of distinct contributors, calculated using the square of the sum of square roots of donations. This rewards collective action but can be exploited by fake or collusive identities.

###### User Flow
1. Applications are reviewed and approved by Round Operators.
2. A Matching Pool is funded by stakeholders.
3. The public votes for projects by donating to them.
4. Matching funds are distributed to projects based on their donations and calculated with a QF formula.

###### Distribution Calculation
Calculation of Matching Funds is done off-chain via a backend API. This is more flexible and scalable than running the calculations on-chain. Additionally, we can

###### Connection-Oriented Cluster-Matching
COCM improves Quadratic Funding by detecting and down-weighting donations from tightly connected or suspicious donor groups, ensuring funds go to projects with authentic, community-wide support.

We can use the GG23 donations data as the cluster data to implement COCM.

https://www.gitcoin.co/blog/leveling-the-field-how-connection-oriented-cluster-matching-strengthens-quadratic-funding

##### RetroFunding
1. Applications are reviewed and approved by Round Operators
2. A panel of experts / badgeholders is chosen for the Round
3. Panel votes for projects to determine how much funding they should receive

### Manage Round
- Update Round settings
- Add/Remove Round Operators? *(would it make sense to have each Round owned by a Safe Multisig instead?)*
- List Applications *(depends on round type)*
- Review Application *(supported by AI review)*
- Approve / Reject

### Discover Rounds
Users should be able to explore active and historical Rounds.

- Search by Round title
- Search by Project name
- Search by semantic similarity
- Filter by active / past
- Filter by network
- Filter by token
- Filter by round type (QF, RF, DC)
- Sort by date created
- Sort by payout amount (in USD)
- Sort by matching funds *(only when QF is selected)*
- Sort by project count

### View Round

- Display Round details
a. Title
b. Description + Eligibility
c. Start / End dates *(and other relevant dates configured in the round)*
d. Network
e. Token(s)
f. Round Type
- Manage Round Button *(for round operators)*
- Fund Round *(eg. Matching Pool)*
- List Projects

*(sharing a round on socials should render an engaging OpenGraph image encouraing viewers to participate).*

### Apply to Round / Create Grant
Projects can apply to Rounds by submitting an application. They should be able to see their previous applications and simply make a clone of it to edit.

#### User Flow

1. Load previous Applications *(from Gitcoin Grants data)*
2. Select Application to clone and make changes to
3. Fill out Application details:
a. **To Be Determined** *(some data might need to be encrypted or we could find ways to not store sensitive data?)*
4. Press Submit
5. Application metadata is stored, contract is called, and user redirected to Application Status page

### Application Status
Applicants can see their status of their application and subscribe to updates by entering their e-mail. They can also make changes to the application details.

### Discover Projects
Users should be able to explore projects to support.

- Search by title
- Search by semantic similarity *(eg. tree-planting should show GainForest)*
- Filter by network *(is it possible with multichain projects?)*
- Sort by funding amount (in USD)
- Sort by round count

### View Project / Application
- Display Project details
- Name
- Description
- List previous Funding + Donations
- Add Project to Checkout *(only if a round has been selected)*

*(sharing a project on socials should render an engaging OpenGraph image encouraing viewers to interact or support).*

### Checkout
The Checkout works like a Shopping Cart. Projects can be added and removed. Amounts (votes or donations) can be edited similar to the quantity of a cart.

#### User Flow
1. A list of Projects that have been added already are displayed. *(the specific Round name and network is also displayed)*
2. User makes changes to the allocations for each project
3. A summary and overview of total amounts are displayed
4. A dialog window is displayed

## Web2 UX
There are 3 problems we would like to solve:
1. Users should be able to sign in with their email or socials (Farcaster, Google etc).
2. It should be easy to use the platform with the same account on mobile and computer.
3. Users shouldn't have to worry about networks and bridging assets

Privy is a great solution for Web2 UX-style wallets while still allowing Metamask and other Web3 wallets to be connected.

https://www.privy.io

#### Multichain Orchestration (Cross-Chain)
With Multichain Orchestration we can abstract away all the networks and bridging for the end-users. This means a user can sign one transaction to transfer USDC 10 from Arbitrum to a Round deployed on Base.

> Multichain orchestration is a powerful pattern that allows users to perform complex sequences of actions across multiple blockchains with just a single signature. Traditional blockchain interactions require users to sign separate transactions for each step in a process (approve, transfer, bridge, swap, etc.), often across different chains with different gas tokens.
> https://docs.biconomy.io/multichain-orchestration/comprehensive
> https://docs.privy.io/recipes/react/eip-7702#2-follow-biconomy-setup-instructions

*(we should do a spike to verify this flow on the networks we wish to support before committing on this solution)*

## Success Metrics
- Time to create a round < 5 min
- % of users completing donation flow
- % of users using social login
- Avg. application review time

## Roadmap
Suggested prioritization.

| Feature | Priority | Version |
| ------------ | -------- | ------- |
| Web2 Account | High | v1 |
| QF Rounds | High | v1 |
| GS Data | Medium | v2 |
| Crosschain | Medium | v2 |
| AI Review | Medium | v3 |
| COCM | Medium | v3 |
| RF Rounds | Low | v4 |
| DG Rounds | Low | v4 |
| KYC | Low | v5 |

---

## Spec
### App
The App is used by Grantees to submit applications to pools, Supporters to vote for or donate to applications.

Vote and Donate is the same functionality. If the token is ETH or USDC (or other with a monetary value, it's a donation. Some pools use custom ERC20 as a way to give vote tokens to a curated panel of voters).

#### Explore Pools

Pools can be explored by searching, filtering, sorting. Clicking on them navigates to the View Pool page.

#### View Pool
Details about the pool, pool token, amount, network, the approved applications (projects) are also listed.

#### View Project / Application
Details about the Project and Application.

### Dashboard
The Dashboard is used by Funders to create and manage pools. The review incoming applications and handle distribution of funds.

- total funds in pool (+ token)
- contributors
- voters

#### Pools
show relevant stats for the pools for the user.
show the most recently created pools.

##### Create New Pool
- pool name
- pool description (and eligibility critera) (wysiwyg editor)
- pool token
- pool cap / max amount
- admin addresses

##### View/Manage Pool
show relevant stats and information about the pool.

###### update pool details
- update name and description
- pool token cannot be updated once created
- pool cap / max amount
- add / remove admins

###### fund pool
input to enter amount. should also be a link to a public page where anyone can fund the pool by connecting their wallet.

###### review applications

applications can be listed and reviewed by pool admins.

###### distribution
transfer tokens to projects. quadratic or linear calculation.

# suggested app structure
/:network(eg. base/optimism/...)
  /app
  	/pools
  	  /:id
  	/projects
  	  /:id


  /dashboard
  	/pools
  		/:id
  			/details
  			/funding
  			/distribute

- app
  - pools
    - explore pools
    - view
    - register
      - form (wysiwyg editor)
      - import application (button to open dialog)
  - projects
    - browse
    - view
  - checkout
- dashboard
  - pools
    - create
    - manage
  - applications
    - review

const data = {
  chainId: 10,
  token: "USDC", // Pool token
  cap: 1000, // Max pool amount
  registerBefore: 0,
  fundBefore: 0,
  metadata: {
    title: "Pool Name",
    description: "Description and eligibility"
  }
}
const poolId = await kit.pools.create(strategy, data)
kit.pools.query({ where })
kit.pools.register(poolId, metadata)
kit.pools.allocate(to, amount, token)
kit.pools.distribute(to, amount, token)

kit.pools.deposit(amount, token) // Wrapper for allocate to strategyAddress
kit.pools.withdraw(amount, token) // Wrapper for distribute to connected address

kit.allocations.query({ where }) // Votes, Donations, Matching Funds, Distributions, ...

kit.applications.query({ where })
kit.applications.approve(id, review)

struct PoolConfig {
  string metadataURI
  address token
  uint256 cap
  uint256 registerBefore // optional
  uint256 fundBefore // optional
}

type Metadata = {
  title: string;
  description: string;
  image: string;
  imageLogo: string;
  imageBanner: string
}
type Pool = {
  id: string;
  creator: Address;
  metadata: Metadata;
  token: Address;
  cap: bigint;
  
  admins: Address[];
}

type Application = {
  id: string;
  creator: Address;
  metadata: Metadata;
}

---

interface Pool {
  voteToken = Address
  matchToken = Address
  
  function register() {}
  function update() {}
  function approve() {}
  function allocate(to, token, amount) {}
  function distribute(to, token, amount) {}
}