Skip to main content

Integrating DeVouch

DeVouch prioritizes accessiblity of information and easy integration. Reading and writing data to DeVouch is accessible to all! We have three topics to cover in this article:

  • How to issue DeVouch attestations
  • Adding your Attester Group to DeVouch
  • Overview of the DeVouch Graphql API & Cookbook

How to issue DeVouch attestations​

There is a standardized attestation schema that all DeVouch eligible attestations MUST USE. You can find them here:

We recommend using the EAS SDK to integrate making attestations from your application, but for demonstration purposes we will show you how it looks on the easscan UI.

easscan view of devouch attestation

Make the Attestation Onchain​

You need to set the attestation as onchain in order for it to be indexed by DeVouch.

No recipient address​

You don't need to set a recipient address for DeVouch attestations.

Project Source​

This is the name of the source platform that the project is from, currently there are these three: gitcoin, giveth, rf4 (Retro Funding round 4). More source platforms may be added later.

Project Id​

Project identifier (ID) from the source platform. This is the unique identifier for the project on the source platform.

Giveth​

For Giveth projects you can find the id of a project by going to the Giveth graphQL API and running a query like this:

query { 
  projectBySlug(slug: "project/slug/goes/here") {
    id
    title
  }
}

This will give you a number like 12345 that you should use for the project Id when attesting to a Giveth project.

Gitcoin​

For Gitcoin grants projects you can find the id of a project by going to the Gitcoin graphQL API and running a query like this:

query {
  projects(
    filter: {tags: {contains: "allo-v2"}, projectType: {equalTo: CANONICAL}, not: {tags: {contains: "program"}}, rounds: {every: {applicationsExist: true}}}
    condition: {name: "{name of project}"}
  ) {
    id
    name
  }
}

This will give you a hash like 0x7f4b4b6cecc3bdaf95098ea2b2f5cd9c31ea742880d5076b540f83caf8247e16 that you should use for the project Id when attesting to a Gitcoin project.

Retro Funding 4​

For Retro Funding projects you can find the id of a project by going to the Retrolist projects API:

https://round4-api-eas.retrolist.app/projects

the response on this page will be a very large JSON file which can be parsed to find the project ID you need to use for the attestation.

Vouch​

This is a simple true/false value, vouching = true, flagging = false.

Comment​

This is a text comment that will be displayed on the DeVouch UI next to the associated attestation. This should be limited to 256 characters for it to be shown appropriately on the DeVouch UI and to limit gas expenses on submitting the transaction.

Referenced Attestations​

This is an important part where you associate the attestations with an attester organization. You'll need to get the attestation UID that links the attester organization relation to the attestation. Look at this example below in the easscan UI:

easscan view of attester org referencing

This for example is used to associate divinecomedian.eth as an RPGF3 Badgeholder, you can see the attestation UID near the top of the page. This is the value you need to use in the Referenced Attestations field.

Ready to submit!​

When you have all those fields filled out, you can submit the attestation to the blockchain. Once it is confirmed, it will be indexed by DeVouch and show up on the DeVouch UI and graphQL API.

Adding your Attester Group to DeVouch​

In order to add your attester group to DeVouch there's a few steps you need to take:

  1. Fork the DeVouch BE repo on Github
  2. Make a org-config.jsonc config file by copying from org-config.template.jsonc. a. Change the name variable to the name of your attester group. b. Change the schemaId variable to the schema ID of the attestations related to your organization c. Change the authorizedAttestor variable to the address authorized to add addresses to your attester group or whoever the issuer is/was of the valid attestations. d. Ensure the network variable is set to the correct network. eth-sepolia for testing, optimism-mainnet for production. e. Optional to change the color variable to a hex colour value that will be associated with your attester group & shown on the UI. f. Optional to set startBlock to the block number you want to start indexing attestations from. This is useful if you have attestation in the past that you want to index. If so, the startBlcock should the block number of the first attestation you want to index.
  3. Run the script with node add-organisation.js. You should noticy a new migration file was made under the db/migrations folder.
  4. Create a PR to the main DeVouch BE repo with your changes.
  5. Wait for Approval and merging from the DeVouch team.

Overview of the DeVouch Graphql API & Cookbook​

The DeVouch Graphql API is an accessible endpoint that allows you to query for any information from the DeVouch indexer. There are two endpoints available:

The graphQL API is hyper flexible and provides a nearly unlimited amount of ways to query data. The rest of this document will be dedicated to providing examples of how to query the DeVouch API.

Fetching All Projects

This query will fetch information for all projects listed on DeVouch.

query MyQuery {
  projects {
    id
    image
    description
    projectId
    source
    title
    totalAttests
    totalFlags
    totalVouches
  }
}

To query for projects from a specific source, you can add a where clause to the query like this:

query MyQuery {
  projects(where: {source_eq: "giveth"}) {
    id
    image
    description
    projectId
    source
    title
    totalAttests
    totalFlags
    totalVouches
  }
}

To query for projects that have only received attestations from a specific attester group, you'll need the schemaID associated with the attester group. When you have this you can make a quiery like this:

query {
  projectAttestations (where:{
    attestorOrganisation:{
      organisation:{
        id_eq: "0xf63f2a7159ee674aa6fce42196a8bb0605eafcf20c19e91a7eafba8d39fa0404"
      }
    }
  }) {
    project {
      id
      title
    }
    }
  }

Search all projects for keyword match in title:

{
  projects(where: {title_containsInsensitive: "blockchain"}) {
    totalFlags
    totalVouches
    title
    source
    description
    slug
    attestedOrganisations {
      id
      count
      vouch
  
    }
  }
}
Fetching Information for a specific Project

To query the Attestation data made to a specific project you will need to know the source platform and the project ID. Once you have that you can query attestation data like this:

query {
  projects(where: {source_eq: "rf4", projectId_eq: "0x897d6172efca2d24a6b14f235db5127f7d747d923287ede38d776126bf02cbfe"}) {
    id
    source
    projectId
    totalFlags
    totalVouches
    attests {
      vouch
      comment
      attestorOrganisation {
        attestor {
          id
        }
        organisation {
          id
          name
        }
      }
    }
  }
}

Note: Inside of the attests field you can query for the attestor and organisation entities. The organisation refers to the attester group associated with the attestation. The attestor is the user that made the attestation and it's id is their address.

Details

Fetching Information about a specific attester To fetch information about a specific attestor you'll need their address, then you can query like this:

{
  projectAttestations(where: {attestorOrganisation: {attestor: {id_eq: "0x826976d7c600d45fb8287ca1d7c76fc8eb732030"}}}) {
    attestTimestamp
    comment
    vouch
    project {
      id
      title
    }
    attestorOrganisation {
      attestor {
        id
      }
      attestTimestamp
      organisation {
        name
      }
    }
  }
}

This response provided all the attestations made by the attestor with the address 0x826976d7c600d45fb8287ca1d7c76fc8eb732030. This include which projects they attested to, the details of the attestation, the attester group they used and the timestamp they attested.