giveth / devouch-be Goto Github PK

When querying for user's attestations we should be able to filter the response to only look for attestations they made to projects listed on a specific source platform.

AC

Each attestation made by the given user address, filtered by source platform, we need to meet these requirements/information:

• filter by giveth source works
• filter by gitcoin source works
• filter by rpgf source works
• when filtering does not show attestations made to projects on other source platforms
• - Title of project attested to
• source platform of project (giveth, gitcoin, RPGF etc..)
• - date of attestation
• - name of attestor group(s) they attested as
• - comments made with given attestation if applicable
• - if attestation is flag or vouch
• link/slug to project details page

When fetching attestations done by a user address we should be able to sort the responses according to the date the attestation was created in both ascending and descending order.

AC

• can query attestation data for a single user
• does not return data for other users not specified
• can sort by date attestation made in ascending order
• can sort by date attestation made in descending order

attestation data contains:

• if flag or vouch
• name of attester organization the attestation was associated with
• comments included in attestation (if any)
• date attestation was made
• title of project
• slug/link to project
• source platform of project

There will be a keyword search function available, we should be able to take in a keyword search in our query and return a sorted list of results that are closes to the keyword match.

This should also be able to handle any filters that have been applied in the query as well such as attester group or source platform

AC

• can handle filtered by source platform
• can handle filtering by attester group
• returns expected results using search of partial project title
• returns expected results using search of complete project title

each project returned in the response has the following data:

• the titles of the project
• the source platform
• the short description of the project
• count of flags AND vouches made by all attestor groups for each project listed in response
• banner image

From the query response of all projects for the list view - we will need to be able to know the count from each registered/tracked attester groups that have FLAGGED a project and show the count in order from group that has made the MOST flags down the group that has made the lowest (descending order)

endpoint: https://backend.devouch.xyz/graphql

It will be used on this card component to give you a visual example:

AC

in the query response should fulfill the following requirements:

• flags are sorted in correct order from highest to lowest
• count is correct number
• title of attestor organization is included in response

We will need to be able to sort the response given by the list of all projects should be the total count of vouches made by all tracked attester groups in ascending/descending order.

If a filter is applied to look for only certain attester groups this should be reflected as well.

If a filter is applied to look for only projects from a certain platform this should be reflected.

For example

Project A

vouches received

• Attester group a - 10
• attester goup b - 5
• attester group c - 7
• total vouches = 22

Project B

vouches received

• Attester group a - 15
• attester goup b - 10
• attester group c - 15
• total vouches = 40

Project C

vouches received

• Attester group a - 7
• attester goup b - 5
• attester group c - 3
• total vouches = 15

So the order of responses should be given in descending order as projects B, A, C

Alternatively, the user will be able to sort by ASCENDING order - so we should be able to handle this as well.

AC

• can sort all projects in response by highest count of vouches from all tracked attester groups
• can sort all projects in response by lowest count of vouches from all tracked attester groups
• sorting can also handle when filtered by specific attester organization
• sorting can handle filter by specific source platform

response also contains information about each project listed:

• project title
• count of vouches from each tracked attester groups
• count of flags from each tracked attester groups
• project short description
• banner image
• slug/link to project page
• source platform
• if a given address has attested for this project before

When fetching attestations related to a single project we should be able to sort the responses according to the date the attestation was created in both ascending and descending order.

AC

• can query attestation data for a single project
• does not return data for other projects not specified
• can sort by date attestation made in ascending order
• can sort by date attestation made in descending order

attestation data contains:

• if flag or vouch
• address that made attestation
• name of attester organization the attestation was associated with
• comments included in attestation (if any)
• date attestation was made

We will need to provide a unified list of projects to the front-end. Projects will come from three different sources but more could be added in the future.

The three sources in order of importance for MVP are:

1. Agora Optimism API (pre-alpha phase) - https://vote.optimism.io/api_v1
2. Giveth - https://mainnet.serve.giveth.io/graphql
3. Gitcoin - https://grants-stack-indexer-v2.gitcoin.co/graphiql OR https://indexer-staging.fly.dev/graphiql

We'll need to provide the following information for each project:

• source of the project
• title of the project
• preview description of the project first 60 characters
• project banner image (if applicable)

If an address is provided (user is connected to website) we will need to know for each project if the user has previously vouched/flagged a project in the list, which should be queried from #7

Including this we will also need information from #7 to know in the unified list of projects some certain information about each project.

From each project we will need to get the list of pre-defined attester groups in #9 and query for each project for each attestor group:

• How many vouches this project has received from unique addresses
• How many unique flags this project has received from unique addresses

The unified list should be able to be FILTERED to show only projects that have been vouched for by a single attestor group, either pre-defined from #9 or a custom user-defined attestor group (by schemaID & issuing authority address). This list can be SORTED by ascending or descending order based on the count of vouches OR flags it has received from the given attestor group. By default the unified list is SORTED by highest -> lowest count of vouches made by all tracked attestor groups

Lastly, the unified list should be able to be filtered additionally with a keyword search of title provided by the user.

We'll need to determine how often we fetch the project information from API

I believe we should do this at least once a day - this will be a devOps issue in the configuration

@aminlatifi could you provide more details on this? Once we setup the back-end logic for retrieving project information there needs to be some sort of cronJob that call its periodically and updates our DB?

We'll need the following information about a specific project from a platform

• project title
• project description
• banner image
• link to source project page

AC

querying this endpoint ____ for we should get the result:

Optimism

• Querying an Optimism source project, can retrieve project title
• Querying an Optimism source project, can retrieve full project description
• Querying an Optimism source project, can retrieve project banner image
• Querying an Optimism source project, can retrieve link to source project page

Gitcoin

• Querying a Gitcoin source project, can retrieve project title
• Querying a Gitcoin source project, can retrieve full project description
• Querying a Gitcoin source project, can retrieve project banner image
• Querying a Gitcoin source project, can retrieve link to source project page

Giveth

• Querying a Giveth source project, can retrieve project title
• Querying a Giveth source project, can retrieve full project description
• Querying a Giveth source project, can retrieve project banner image
• Querying a Giveth source project, can retrieve link to source project page

We should be able to query the backend service and know for a single given project how many vouches and flags have been given to this project from all of the tracked attestor groups

https://backend.devouch.xyz/graphql

AC

when querying the response should be able to give us

• returns response for each tracked attester group

response contains

• count of vouches
• count of flags
• name of attester group

An API will be needed to fetch information regarding a specific address. It will need to provide the following:

• Projects that the given address has attested to
• The data of each attestation made (vouch/flag, related attestor group, date, comments)
• Specific data regarding each project they attested to - Title, source, ID, slug, source link

The should be able to FILTER this data by:

• Projects from only a specific source that they have attested to
• Only a specific attestor group that they belong to (might be one or many they belong to)
• ONLY vouches they have made
• ONLY flags they have made
• keyword search of project title

they should be able to SORT the list with or without filter by ascending/descending of date attestation was made

Filter the response to ONLY show Vouches made by address

OR

Filter the response to ONLY show Flags made by address

https://backend.devouch.xyz/graphql

AC

we should be able to query the endpoint above, for a specific user address, filtered by only vouches or flags, the response should be able to include:

For Vouches

• all vouches made by a user
• does not include flags made by user
• pagination works to see all vouches (skip, take, limit etc..)
• title of project
• source platform (giveth, gitcoin, rpgf)
• link/slug to project details
• attester group attestation was done as
• if it was a vouch
• comment included in attestation (if applicable)
• date of attestations

For Flags

• all flags made by a user
• does not include vouches made by user
• pagination works to see all vouches (skip, take, limit etc..)
• title of project
• source platform (giveth, gitcoin, rpgf)
• link/slug to project details
• attester group attestation was done as
• if it was a flag
• comment included in attestation (if applicable)
• date of attestations

We will need to be able to know the count of flags and vouches made to a specific project from each tracked attester group when querying the list of all projects.
https://backend.devouch.xyz/graphql

for visual reference this is where it gets used:

AC

the following information should be included in the response:

• a response is given for every project
• each tracked attestor group is included in response
• count of vouches from each attester group
• count of flags from each attester group
• name of each attester group

#6

The CI/CD solution must be able to deploy a subsquid project automatically and set configurations (e.g. RPC node) in .env file

We will need an endpoint to fetch the details of a single project including:

• source of the project
• title of the project
• link to project (on source platform)
• description of the project
• project banner image (if applicable)

If an address is provided (user is connected to website) we will need to know if the user has previously vouched/flagged the project previously, which should be queried from #7

Including this we will also need information from #7 to know certain information about each project.

From the list of pre-defined attester groups in #9 and query for the given project for the pre-defined attestor groups combined AND by individual attestor group:

• How many vouches this project has received from unique addresses
• How many unique flags this project has received from unique addresses
• The addresses which have vouched for this project & which attestor group they belong to
• The addresses which have flagged this project & which attestor group they belong to
• the content of the comments in the attestation made by an address if applicable
• the date the attestation was made

We will need to filter attestation details by the following:

• Only attestations (flags & vouches) done by a certain attestor group, pre-defined or custom user-input
• Only VOUCHES done by a certain attestor group, pre-defined or custom user-input
• Only FLAGS done by a certain attestor group, pre-defined or custom user-input
• only VOUCHES done by ALL the pre-defined attestor groups
• only FLAGS done by ALL the pre-defined attestor groups

The filters as well as the default responses should be able to be sorted by date, ascending/descending

We will need to be able to sort the response given by the list of all projects should be the total count of FLAGS made by all tracked attester groups in ascending/descending order.

If a filter is applied to look for only certain attester groups this should be reflected as well.

If a filter is applied to look for only projects from a certain platform this should be reflected.

For example

Project A

flags received

• Attester group a - 10
• attester goup b - 5
• attester group c - 7
• total vouches = 22

Project B

flags received

• Attester group a - 15
• attester goup b - 10
• attester group c - 15
• total vouches = 40

Project C

flags received

• Attester group a - 7
• attester goup b - 5
• attester group c - 3
• total vouches = 15

So the order of responses should be given in descending order as projects B, A, C

Following up on the DeVouch call April 30 we should ensure that we cover the following case:

1.User makes attestation to project as attestor group A
2. next day or 1 month later they make an attestation to the same project as attestor group B

We should:

• Only allow attestations to be made with one schemaID, not an array of schemaIDs in the corresponding field
• NOT overwrite their previous attestation but instead create a new indexed entry related to the project and the user.

@aminlatifi - just to make sure we cover these cases as a result of our discussions.

https://grants-stack-indexer-v2.gitcoin.co/graphiql
We'll need to provide the following information for each project:

• source of the project
• title of the project
• link to project (on source platform)
• description of the project
• project banner image (if applicable)

Acceptance Criteria

From unified API endpoint _____ we can fetch the following details from a single Gitcoin grant project:

• - source of the project
• - title of the project
• - 60 character shortened description of the project
• - project banner image (if applicable)

From the project details endpoint ______ we can fetch the following details from a single Gitcoin grant project:

• - source of the project
• - title of the project
• - link to project (on source platform)
• - description of the project
• - project banner image (if applicable)

https://mainnet.serve.giveth.io/graphql

We'll need to provide the following information for each project:

• source of the project
• title of the project
• link to project (on source platform)
• description of the project
• project banner image (if applicable)

Acceptance Criteria

From unified API endpoint _____ we can fetch the following details from a single Giveth project:

• - source of the project
• - title of the project
• - 60 character shortened description of the project
• - project banner image (if applicable)

From the project details endpoint ______ we can fetch the following details from a single single Giveth project:

• - source of the project
• - title of the project
• - link to project (on source platform)
• - description of the project
• - project banner image (if applicable)

We should be able to query the backend service and know for a single given project how many vouches and flags have been given to this project from ONE specific attester group

https://backend.devouch.xyz/graphql

AC

the response should be able to give us

• count of vouches
• count of flags
• name of attester group

From the query response of all projects for the list view - we will need to be able to know the count from each registered/tracked attester groups that have VOUCHED a project and show the count in order from group that has made the MOST flags down the group that has made the lowest (descending order)

It will be used on this card component to give you a visual example:

AC

in the query response should fulfill the following requirements:

• vouches are sorted in correct order from highest to lowest
• count is correct number
• title of attestor organization is included in response

I've fixed the length, but to show the styled version, we need to convert it to the html on BE, I'll do it after the MVP.

Originally posted by @MohammadPCh in Giveth/DeVouch-FE#65 (comment)

In order to properly handle markdown formatted responses received in the project description we'll need to convert it to HTML in the back-end. This will allow us to show properly formatted project descriptions

e.g. of the visual problems we hope to solve:

When getting the unified list of projects we should be able to filter for only projects that are from a particular source such as Giveth, Gitcoin or RPGF.

The response should only show projects from the filtered platform, along with any other applicable filtering or sorting applied.

AC

• can filter list for only projects from Giveth
• can filter list for only projects from Gitcoin
• can filter list for only projects from RPGF
• does not return projects from platform not specified in filter query

each project returned in the response has the following data:

• the titles of the project
• the source platform
• the short description of the project
• count of flags AND vouches made my all attestor groups for each project listed in response
• comment included in attestation
• banner image

When a user creates an attestation using our schema id #6 it should be indexed by the subsquid service. The related attestation data should be able to tell us the following information:

• the address that minted the attestation
• the timestamp of when the attestation was made
• if the attestation is a flag or a vouch
• the source and id of the project
• the recipient of the attestation
• comment with attestation
• attestor groups the attestor is attesting with

AC

There should be a queryable endpoint and the following information can be retrieved for attestations made with our schema from #6

• - the address that minted the attestation
• - the timestamp of when the attestation was made
• - if the attestation is a flag or a vouch (true for vouch flag for false)
• - the source and id of the project
• - the recipient of the attestation
• - comment with attestation
• - attestor groups the attestor is attesting with (array of arrays)

can be tested with this link https://backend.devouch.xyz/graphql

Here is the sample attestation that can be used:
https://sepolia.easscan.org/schema/view/0x97b0c9911936fad57e77857fac6eef6771f8d0bf025be9549214e32bf9e2415a

Here is the schema ID for Giveth Verification Team
https://sepolia.easscan.org/schema/view/0xf63f2a7159ee674aa6fce42196a8bb0605eafcf20c19e91a7eafba8d39fa0404

You can find the attestation made with this schema ID to your address and use the UID in the reference field when making a test attestaion (using a giveth project on production)

We'll need to develop a subquid service to serve as the main back-end service, providing information to not only the DeVouch front-end but also external organizations who wish to integrate our attestations data layer.

Technical Design of this service has been started by @aminlatifi in https://www.notion.so/giveth/Project-Verification-Attestation-Support-Design-a991597acd0e4220b23131fa434e2339

A note on Attestor Groups

These are groups of web3 users who belong to an organization or team that have some sort of notable reputation. In DeVouch we identify Attestor Groups by two parameters:

• Holds an attestation from a specific schemaID
• Attestation they hold was minted from a specific address (issuing authority)

This service should be queryable via graphQL and allow for the following operations:

Index on-chain attestation events as they occur

• Only for users who use our defined attestation schema #6
• Parse & make queryable all details included in our defined schema #6

Query project related information

• Only Vouches made to this project by a given attestor group (using the two necessary parameters defined above)
• Only Flags made to this project by a given attestor group (using the two necessary parameters defined above)
• All attestations made to this project, vouch or flag, by a given attestor group
• Count of flags/vouches made to this project by given attestor group
• Addresses that have vouched/flagged this project & what attestor groups they attested from

Query user related information

• Projects that have been vouched for by the given user address
• Projects that have been flagged for by the given user address
• All attestations, vouch or flag, made to projects by the given user address
• If an address belongs to a given attestor group (?)

When we fetch the details of a single project we should be able to filter the attestation data made to this specific project to only look for attestations made from a specific attester group.

AC

querying for a single project with attestations from a specific attester group we should get the following information:

• name of attester group
• date of attestation was made
• if it is a vouch or flag
• address of attester
• comment in attestation

pre-defined attestor groups will be arbitrarily added by DeVouch at launch and expanded as more external teams wish to integrate with DeVouch.

An attestor group is defined by 3 fields:

• schemaID
• issuing authority (address that has to have issued the attestation)
• name of attestor group

These attestor groups are used by #8 and other services to pass to the FE, showing vouches/flag details and counts.

This list should be structured in a way that external teams can make PRs requesting to update or add new attestor groups.

The attestation service runs on the Sepolia network. Our indexer (Subsquid) needs an archive node of Sepolia chain (11155111) for staging env.
We can use personal alchemy nodes for development purpose, but it's safer to have a separate one on the server.

This schema will need to contain fields for the following information

• if it's a flag or a vouch
• the source and id of the project
• attestor group they are attesting as (possibly multiple or none)
• comment related to their attestation

Acceptance Criteria

Can successfully create on-chain attestation using generated schema on EAS website with the following fields:

• flag/vouch boolean (true for vouch, false for flag)
• source of project (giveth, gitcoin, optimism) as string
• id of project (number)
• reference field to use UID of attestation issued to authorized attestor that identifies them
• string containing a comment

link to schema:
https://sepolia.easscan.org/schema/view/0x97b0c9911936fad57e77857fac6eef6771f8d0bf025be9549214e32bf9e2415a

Filtering to show ONLY VOUCHES or ONLY FLAGS to a specific project from all tracked attestor groups

Acceptance criteria

When we query for a specific project defined by source + id using the graphql API AND filter to look for a specific attester organization we get the following information related to attestations made to it

• date of attestation
• address that made the attestation
• if attestation was vouch or flag
• comment included in attestation

When fetching attestations done by a user address we should be able to sort the responses according to the alphabetical order by project title in both ascending and descending order.

AC

• can query attestation data for a single user
• does not return data for other users not specified
• can sort by project title alphabetically in ascending order
• can sort by project title alphabetically in descending order

attestation data contains:

• if flag or vouch
• name of attester organization the attestation was associated with
• comments included in attestation (if any)
• date attestation was made
• title of project
• slug/link to project
• source platform of project

The default sorting given by the unified API response of the projects should be projects that have the highest count of attestations (vouch AND Flags together) from all tracked attester groups.

If a filter has been applied to look only for a certain attester group then the default sorting should filter by this as well. Similarly if we filter for a specific platform.

We should be able to know from a list of projects if a given address has attested for it before and how many times from different attestor groups for the same address to the given project.

This will be for the list view of projects so users can know at a glance which projects they have attested for.

AC

querying https://backend.devouch.xyz/graphql endpoint for unified API we should be able to get the following information for each project provided in the response:

• which projects the user has attested to before from the ones provided

We should be able to know if a given address has attested for a project before, including the following information related to any relevant attestations. The difference between this one and #10 is this is meant for the single project page

• attester group they attested as
• if vouch or flag
• comments included in attestation

https://backend.devouch.xyz/graphql

AC

Should see results that shows:

• name/title of attester group the given address has attested as (could be with multiple attester organizations)
• If each relevant attestation is a vouch or flag (true/false)
• comments included in each relevant attestation (if any)
• date of attestation

When querying for attestations made by a specific user, we should be able to search by title of a project name and get some results of the required project info and attestation data related to it.

AC

• partial spelling of project title returns expected results
• complete/exact spelling of project title returns correct results

Attestation info contains:

• - Title of project attested to
• source platform of project (giveth, gitcoin, RPGF etc..)
• - date of attestation
• - name of attestor group(s) they attested as
• - comments made with given attestation if applicable
• - if attestation is flag or vouch
• link/slug to project details page

we should be able to filter the data of all attestations made by a specific user to only show attestations they have made from a specific attester organization/group

AC

when querying https://backend.devouch.xyz/graphql we should be able to look for user attestations and filter by a specific attester group, the response should include:

• does not include attestations from other attester groups
• pagination works to see all attestations (skip, take, limit etc..)
• title of project
• source platform (giveth, gitcoin, rpgf)
• link/slug to project details
• attester group attestation was done as
• if it was a vouch
• comment included in attestation (if applicable)
• date of attestations

We'll need a simple swagger page where we have can have our documentation written on how to use your graphql endpoint to fetch information

https://graphql-demo.mead.io/

https://nordicapis.com/how-to-autogenerate-graphql-api-documentation/

In the list of projects provided by the unified API we should be able to apply a filter for a certain attestor group, this will filter the returned response to only show projects that have received at least 1 attestation from a given attestor group.

We should be able to filter this list by on or multiple pre-defined attestor groups in the UI.

Acceptance criteria

When we query for all projects using the graphql API, filtering to look only for projects that have received an attestation from a specific group we receive:

• a list of only projects that have received at least 1 attestation from specified group
• can include projects from multiple sources (giveth, gitcoin, optimism)
• does not show projects that are not specified
• can handle also being filtered by source platform simultaenously
• the titles of the projects
• the source platform
• the short description of the project
• count of flags AND vouches made my all attestor groups for each project listed in response
• comment included in attestation
• banner image

Pre-alpha API: https://vote.optimism.io/api_v1

We'll need to provide the following information for each project:

• source of the project
• title of the project
• link to project (on source platform)
• description of the project
• project banner image (if applicable)

Acceptance Criteria

From unified API endpoint _____ we can fetch the following details from a single project from the Optimism RF Applicants:

• - source of the project
• - title of the project
• - 60 character shortened description of the project
• - project banner image (if applicable)

From the project details endpoint ______ we can fetch the following details from a single project from the Optimism RF Applicants:

• - source of the project
• - title of the project
• - link to project (on source platform)
• - description of the project
• - project banner image (if applicable)

can change EAS contract, schema contract etc. are all in the environment variables.

here is our attestation schema on optimism
https://optimism.easscan.org/schema/view/0x97b0c9911936fad57e77857fac6eef6771f8d0bf025be9549214e32bf9e2415a

EAS contract:
https://optimistic.etherscan.io/address/0x4200000000000000000000000000000000000021

for each unique address that attested to this project we should retrieve the following information about the relevant attestation:

• address of attestor
• as which attestor group the attestation was made with
• date attestation was made
• if attestation was vouch or flag
• comment included in attestation if applicable

Acceptance Criteria

We can query to this service https://backend.devouch.xyz/graphql for a specific project identified by source and project ID and get the following information for each entry of an attestation made:

• - address of attestor
• - which attester organization the attestation belongs to
• - date attestation was made
• - if attestation was vouch or flag
• - comment included in attestation if applicable

For each attestation made by the given user address we need to make available the following information:

• - Title of project attested to
• source platform of project (giveth, gitcoin, RPGF etc..)
• - date of attestation
• - name of attestor group(s) they attested as
• - comments made with given attestation if applicable
• - if attestation is flag or vouch
• link/slug to project details page