gitcoinco / easy-retro-pgf

Retroactive Public Goods Funding for everyone.

EasyRetroPGF

Website | Telegram Group

Documentation

• Setup & Deployment
• Adding Projects & Approving
• Creating Badgeholders/Voters
• Voting
• Results
• Distribute

Supported Networks

All networks EAS is deployed to are supported

• https://docs.attest.sh/docs/quick--start/contracts

Mainnets

• Ethereum
• Optimism
• Base
• Arbitrum One
• Linea
• Celo
• Filecoin

Testnets

• Sepolia
• Optimism Goerli
• Base Goerli
• Arbitrum Goerli
• Polygon Mumbai
• Linea Goerli

Development

To run locally follow these instructions:

git clone https://github.com/gitcoinco/easy-retro-pgf

bun install # (or pnpm / yarn / npm)

cp .env.example .env # and update .env variables

docker-compose up # starts a local postgres instance

bun run dev

bun run db:push # create database tables

open localhost:3000

Technical details

• EAS - Projects, profiles, etc are all stored on-chain in Ethereum Attestation Service
• Batched requests with tRPC - Multiple requests are batched into one (for example when the frontend requests the metadata for 24 projects they are batched into 1 request)
• Server-side caching of requests to EAS and IPFS - Immediately returns the data without calling EAS and locally serving ipfs cids.
• SQL database for ballots - Votes are stored privately in a Postgres database
• Allo2 for token distribution - Payouts are calculated based on amount of configured tokens in the pool and the vote calculation

easy-retro-pgf's Issues

Update Prisma Schema

• Add Round.type String @default("project") and Round.metrics Json[]

Submit ballot hashcode mismatch

I found the tool practical and functional! I just had one problem when trying to submit my basket, the signature in the metamask didn't arrive, then when I tried again there was a conflict in the submission hash code, so I just changed the allocated value of one of the projects and everything worked. Thank you for everyone's time and energy.

Update RoundAdmin page to configure metrics

• Render ImpactConfig or CategoryConfig based on round.type
  • if round.type === impact ImpactConfig, if type === project CategoryConfig
• Create router endpoint metrics.search
  • Return available metrics (id, name, description) (Ask OSO for name and description for metrics)
• Create component for admin to select available metrics (react-select multi?)
• Store selected metrics in db round.metrics

Available metrics:

active_contract_count_90_days
address_count
address_count_90_days
days_since_first_transaction
display_name
event_source
gas_fees_sum
gas_fees_sum_6_months
high_activity_address_count_90_days
low_activity_address_count_90_days
medium_activity_address_count_90_days
multi_project_address_count_90_days
new_address_count_90_days
project_id
project_name
project_namespace
project_source
returning_address_count_90_days
transaction_count
transaction_count_6_months

Projects not loading - TRPC returns 400

Noticing that occasionally when routing from /ballot to /projects, the projects don't load

e.g. navigating to projects via the nav link:
https://easy-retro-pgf.vercel.app/projects?orderBy=name&sortOrder=asc&limit=12&cursor=0&seed=0&search=null

Looks like this request is failing:
https://easy-retro-pgf.vercel.app/api/trpc/projects.search?batch=1&input=%7B%220%22%3A%7B%22json%22%3A%7B%22limit%22%3A%2212%22%2C%22seed%22%3A%220%22%2C%22orderBy%22%3A%22name%22%2C%22sortOrder%22%3A%22asc%22%2C%22cursor%22%3Anull%2C%22search%22%3A%22null%22%7D%2C%22meta%22%3A%7B%22values%22%3A%7B%22cursor%22%3A%5B%22undefined%22%5D%7D%7D%7D%7D

[
{
"error": {
"json": {
"message": "[\n  {\n    \"code\": \"invalid_type\",\n    \"expected\": \"number\",\n    \"received\": \"string\",\n    \"path\": [\n      \"limit\"\n    ],\n    \"message\": \"Expected number, received string\"\n  },\n  {\n    \"code\": \"invalid_type\",\n    \"expected\": \"number\",\n    \"received\": \"string\",\n    \"path\": [\n      \"seed\"\n    ],\n    \"message\": \"Expected number, received string\"\n  }\n]",
"code": -32600,
"data": {
"code": "BAD_REQUEST",
"httpStatus": 400,
"path": "projects.search",
"zodError": {
"formErrors": [],
"fieldErrors": {
"limit": [
"Expected number, received string"
],
"seed": [
"Expected number, received string"
]
}
}
}
}
}
}
]

Error on ballot submission did not show up in UI, had to inspect console

There was hidden restriction that I was unaware of that no single project can receive over 10000 votes. I did not realise this until I set my votes and cast the ballot, which failed.

The error did not appear in a dialog, nor was the blockchain transaction given any visual feedback that it failed. I had to inspect the console to see the error response from the transaction (which did highlight the 10k issue).

I now see that there is validation on the vote box, the border goes red if the amount is out of bounds, but there is no hover over to help me and show me what is giving the red border. Subsequently, I submitted the ballot as I didn't understand what the red border was meant to be indicating.

Fil RetroPGF Feedback

(tweet)

Just cast my ballot for 47/106 projects participating in Fil RetroPGF!

Some thoughts:

• Loved seeing the Lotus Dependencies as well as other ecosystem projects building on Filecoin in the round!
• The voting portal worked well. It was easy to populate my ballot, browse projects, etc. Allocating voting points rather than tokens was nice too.
• My biggest challenge was reconciling overlapping impact claims: it's hard to attribute the impact of specific PRs or contributions within a repo to separate teams.
• There's also the challenge of evaluating software contributions alongside other forms of contribution (education, ops, etc), but that's nothing new.
• Ops were very smooth (IMHO), esp given that this was a new concept for many badgeholders. h/t to @tomhihihihihi and team for all their behind the scenes work.
• Badgeholder chat was very civil, with good debate and tradeoff discussions. From a governance perspective, this is where much of the value lies.

Update Distributions to support Metrics ballots

Create Postgres database for dev/staging environment (and update .env files)

Explore possibility of Round Settings page

Much of the configuration we do in the .env file could be moved to a Round Settings page and stored in the prisma db.

This page would also include:

• Configuration for payout style (custom or OP-style)
• Create Pool and store Pool ID (currently, the admin needs to create a pool, copy the pool id, store in .env, and re-deploy)

Error submitting ballot - Votes hash mismatch

Tried submitting a ballot, received this error:

context
: 
{}
elapsedMs
: 
322
input
: 
{signature: '0xb471858b73e7364e890dc1c0c35c22dd089ab3c01b8784a7…3d3f02408ef9851dc2ee06661821225a000393aa81870c81b', message: {…}, chainId: 420}
result
: 
TRPCClientError: Votes hash mismatch at u.from (https://easy-retro-pgf.vercel.app/_next/static/chunks/pages/_app-71854ee0ad1f082d.js:1361:202769) at https://easy-retro-pgf.vercel.app/_next/static/chunks/pages/_app-71854ee0ad1f082d.js:1361:206666
data
: 
{code: 'BAD_REQUEST', httpStatus: 400, path: 'ballot.publish', zodError: null}
meta
: 
{response: Response, responseJSON: Array(1)}
name
: 
"TRPCClientError"
shape
: 
{message: 'Votes hash mismatch', code: -32600, data: {…}}
cause
: 
undefined
message
: 
"Votes hash mismatch"
stack
: 
"TRPCClientError: Votes hash mismatch\n    at u.from (https://easy-retro-pgf.vercel.app/_next/static/chunks/pages/_app-71854ee0ad1f082d.js:1361:202769)\n    at https://easy-retro-pgf.vercel.app/_next/static/chunks/pages/_app-71854ee0ad1f082d.js:1361:206666"
[[Prototype]]
: 
Error
[[Prototype]]
: 
Object

POST https://easy-retro-pgf.vercel.app/api/trpc/ballot.publish?batch=1 400 (Bad Request)

error: {json: {message: "Votes hash mismatch", code: -32600,…}}

Not sure if this is a related issue to #13 with the TRPC?

Improve Distributions and Applications when many items

These components are heavy to load when there are a lot of applications because they need to fetch a lot of data:

• Attestations
• Metadata

The Distributions component has additional complexity with the payout address and amount inputs.

How can we make these components lighter and simpler?

• Working on this in #84

Create Impact Ballot api

Whenever a voter make changes to the ballot it should store the state. A voter can also publish the votes by signing a message.

• Should work similar to OP RF4
• Auto-balance
• Lock metric state (this functionality is useful for ProjectBallot also)
• Ballot votes are currently { projectId, amount } - can we refactor to use { id, amount, locked }?
• Add vote.type in-case both projects and metrics are in the ballot. This helps with querying metrics from ballot.

Show AllocationSidebar on Metrics and Metrics Ballot page

Metrics sidebar should be rendered differently based on if the user is on Ballots, Metrics, or MetricsDetails page.
The sidebar in Ballot and Metrics should display the distribution of the ballot and the MetricsDetailsPage the distribution of the Metric.

See these files:

• https://github.com/gitcoinco/op-rf4-voting-ui/blob/main/src/components/ballot/ballot-sidebar.tsx
• https://github.com/gitcoinco/op-rf4-voting-ui/blob/main/src/components/metrics/distribution-sidebar.tsx

Create API route to fetch Metrics

• Create metrics router (src/api/routers/metrics)
• Call OpenSourceObserver
  • Calculate allocation per project by summing each metric and dividing by the total
  • OSO api: https://cloud.hasura.io/public/graphiql?endpoint=...
  • EzRF x OpenSourceObserver API

Query:

query ImpactMetrics($projects: [String], $source: String) {
  onchain_metrics_by_project_v1(
    where: {
      project_name: {_in: $projects}, 
      event_source: {_eq: $source}}
  ) {
    active_contract_count_90_days
    address_count
    ...
  }
}

{
  "variables": {"projects": ["zora", "uniswap", "safe-global", "gitcoin"], "source": ["BASE"] }
}

Example output data:

{
  "data": {
    "onchain_metrics_by_project_v1": [
      {
        "active_contract_count_90_days": 4,
        "address_count": 107212,
        "address_count_90_days": 39488,
        "days_since_first_transaction": 944,
        "display_name": "Safe",
        "event_source": "OPTIMISM",
        "gas_fees_sum": 65.79755716649302,
        "gas_fees_sum_6_months": 1.1451389979817548,
        "high_activity_address_count_90_days": 1,
        "low_activity_address_count_90_days": 39391,
        "medium_activity_address_count_90_days": 89,
        "multi_project_address_count_90_days": 37591,
        "new_address_count_90_days": 37301,
        "project_id": "HW-DsDcsApBwqtMlSu8S7BpNvtLdq5jvBrJD7kxz7pM=",
        "project_name": "safe-global",
        "project_namespace": "oso",
        "project_source": "OSS_DIRECTORY",
        "returning_address_count_90_days": 2187,
        "transaction_count": 2844231,
        "transaction_count_6_months": 97315
      },

• Where do we get the name and description for the metric?

Lists

Write docs on how to use them

Update Ballot page to render MetricsBallot

Route: /[domain]/ballot

• If round.type === impact render MetricsBallot component (See OP RF4)
• Else render current ballot (and rename to ProjectsBallot)

Create Round(s) for OnChainSummer in the Admin UI

No code required.

Search Functionality

Requested at https://gov.optimism.io/t/easyretropgf-xyz-run-your-own-optimism-style-rpgf-round/7359/5

Users want to see the status of their submitted applications

As a user I want to see the applications I have sent to the round so I know what information I have sent and the approval status of it.

• Create a profile page
• List applications by user (Similar to ApplicationsToApprove component)
  • Button to review
  • Show application status (pending or approved)

Round managers and users want to see progress of voting

1. There's already the Distribute page for the round admins where they can see the allocation of tokens based on votes.
   Are more detailed information required?

2. What could a UI look like for voters and users to see the status of the voting?

Use token symbol from configured token address across the app

Now that we have a token address in the config we can use this to display the token symbol.

• Remove NEXT_PUBLIC_TOKEN_NAME from .env.example
• Remove tokenName from src/config.ts
• usePoolToken to render the token symbol (see AllocationInput component)

Improve OpenGraph image

Improve the design of the OG image:

• https://www.opengraph.xyz/url/https%3A%2F%2Feasy-retro-pgf.vercel.app

Ideas:

• When linking a project - include name, description, avatar and banner in the OG image
  • pages/api/og.tsx and pages/projects/[projectId]/index.tsx

Handle Admin addresses added after Pool is created

If an admin is added after the pool has been created they dont have access to call Distribute.

In the Admin addresses UI:

• Check if pool has been created
• For each admin - allo.isPoolAdmin(poolId, address)
• Show indication if admin address is also Pool admin
• Add button to call allo.addPoolManager(poolId, address)

API keys for external requests

Add capability for a wallet signed message to create an api key.

• page to list created api keys api.keys.list
• button to create new key (signs message)
• call api.keys.create
• generate key and store in prisma
• create prisma model for ApiKey
• update procedure to verify api key

Thomas from Obol's issues

Quick other feedback piece when trying to add projects

• Previous project details load while it has already been registered
• I get prompted to sign the registration even if not click on the button at regular intervals
• It can take time for the project to appear on on the review page so might be worth adding a disclaimer to avoid people logging it twice. It could be worth checking for duplicates

View: Root TypeError: Cannot read property 'trim' of undefined

I having problems trying to log in on https://ezrpgf-training.vercel.app/applications/new from mobile, i tried with wallet connect and metamask, but everytime this shows up before i can sign to log in.

Update Project ballot to BallotV2

Combine how we handle votes and ballots. Currently projects have one way and metrics another.

• Reuse BallotEditor from metrics

Revoke Voter and Application

Admin wants to revoke already approved voters and applications.

• Make voters selectable with checkboxes similar to Applications
• Make approved applications selectable
• Create Revoke button with prop uid where attestation id is being passed into a useRevoke hook
• Add Revoke button in VoterList and ApplicationsToApprove components
• Create useRevoke in src/hooks/useEAS hook that calls eas.multiRevoke
  • See useAttest for how to implement
  • https://github.com/ethereum-attestation-service/eas-sdk/blob/439417803c5f7c08fe986ff98a7995d0f40b0a23/src/eas.ts#L278

Deduplicate Feedback Card

After submitting a ballot, the sucess page displays three cards. The first and third card are essentially the same ones and both asking for feedback. They should be merged

Ballot Project allocations API

Should return the projects included in the metrics added to ballot.

{
    "projectAllocations": [{
        "projectId": "0x9102357674825ed224734387fbefbf41c16fe5d9764c2f7f3e897ad3325d3990",
        "name": "Zora",
        "image": "",
        "isOpenSource": true,
        "allocationsPerMetric": [
            {
                "metricId": "trusted_daily_active_users",
                "allocation": 372038.49
            },
            {
                "metricId": "gas_fees",
                "allocation": 127961.51
            }
        ],
        "allocation": 500000
    }, {...}, {...}]
}

Evaluate feedback from RetroPGF3: Learnings & Reflections

https://optimism.mirror.xyz/Bbu5M1mTNV2Z637QxOiF7Qt7R9hy6nxghbZiFbtZOBA

“Extremely unfortunate that there was no way to import CSV so it had to all be added back to the interface manually. :/” - Amy

“I used West’s voting platform 4, and overall I found it quite intuitive and easy to use. For the next round of RPGF it would be good to add a) functionality for editing, forking, removing lists, and b) ballot import/export functionality to support the people working offline with spreadsheets - this would also be useful at times when the servers are experiencing overload.” - Joanbp

• Import / Export CSV

“We should have the option to write notes on applications for ourselves (i.e. non public). And e.g. have buttons to indicate if we want to vote for them or not (“Yes”, “No”, “Maybe” or blank), and then use that to filter applications.” - CheekyGorilla

• Private comments for applications (low effort could be to store in device local storage)

“it would be great if there was a "hide from view" for projects that i have looked at and evaluated as not a candidate / that i will not be allocating towards / voting to” - Jenny

“I have a few pieces of feedback I shared with the agora team before voting started that I think could make it better-have the ability to mark a project as seen or “don’t put in ballot” option-have the ability to allocate percentages as well as dollar amount-get rid of the lists function” - Katie

• Hide projects (low effort could be to store in device local storage)

Custom Ballot size per Badgeholder

Currently all badgeholders receive the same amount of votes to cast across applications.
I propose to allow for custom allocation of votes to cast.

The reasoning is that some badgeholders may have contributed more or deserve more votes to cast. E.g. for Obol EasyRPG, badgeholders are contributors to a fund based on the fees they paid to the protocol. The more fees they paid the more votes they should be able to cast.

Proposed solution

• Import a CSV with address and amount of votes in the badgeholder creation page.

Add Quadratic Distribute Payout Style

Currently there are two options

• Custom: simple sum (should probably not be named Custom and more something like Simple)
• OP-style

Would be great to add another style which is quadratic calculations, where it's the square root of the sum.

Metrics List

• Create a MetricsListPage (/pages/[domain]/metrics/index.tsx)
• Create MetricsList component (/features/metrics/components/MetricsList.tsx)
• Fetch Metrics for round (api built in #69)]

Add license

Hey folks!

I remember reading your OP forum post where you mention that you're:

now open sourcing it and releasing it for others’ use

...but I'm noticing there's no actual license on this repo.

Could you please add a license (e.g. MIT) to clarify this?

For context, we're working on a fork and we intend to open source our code as well (in additional to merging any improvements upstream back to you, if that's of interest).

Thanks!

Fix types for fetch

EAS GraphQL API wraps response in data while metadata doesn't.

• Update utils/fetchAttestations with the wrapping data (r.data.data...)
  

  easy-retro-pgf/src/utils/fetchAttestations.ts

  Lines 66 to 80 in fb4e971

  	return fetch<{ attestations: AttestationWithMetadata[] }>(eas.url, {
  	method: "POST",
  	body: JSON.stringify({
  	query: AttestationsQuery,
  	variables: {
  	...filter,
  	where: {
  	schemaId: { in: schema },
  	revoked: { equals: false },
  	time: { gte: startsAt },
  	...filter?.where,
  	},
  	},
  	}),
  	}).then((r) => r.data?.attestations.map(parseAttestation));

• Update utils/fetch to return (await r.json()) as T

• https://github.com/gitcoinco/easy-retro-pgf/blob/main/src/utils/fetch.ts#L20

Improve Info Tab

The info tab is a great start but the progress bar is a bit confusing in its current form

Suggestions

• Include start and end date for each step
• Highlight which steps are open and which are closed
• Fix alignment of the table/progress bar as it currently looks off and between steps

ENS names in Voter list

• Create a VoterItem component in features/voters/components/VoterList
• Render NameENS with voter.recipient as address prop

OP RPGF3-style voting calculation

https://gov.optimism.io/t/retropgf-3-round-design/6802

Results are calculated using the median. Each application needs to receive a minimum Quorum of votes from 17 badgeholders to qualify.

Implementation could be written in: /src/server/api/routers/results.ts

'results.votes' shouldn't be public until distribution

It appears the api releases votes immediately. A phased structure should support some way to limit the visibility of votes until the round has decided it's time to publicize results.

https://github.com/gitcoinco/easy-retro-pgf/blob/main/src/server/api/routers/results.ts#L12

Update RoundAdmin page to select Round type (Project or Impact voting)

Create MetricsBallot component

• Query ballot API - should return { id: string; amount: string; locked?: boolean }[]
• Render each metric with name, buttons (lock, inc, dec, remove), input
• Update DB with ballot data

Look at OP RF4 for how components are structured

• MetricsEditor (components/metrics-editor/index.tsx)
• useMetricsEditor (hooks/useBallotEditor.ts)