[HIP-1] Implement EAS evaluations for hypercerts

[bitbeckers]

Summary

Implement evaluations using EAS in the hypercerts ecosystem.

Abstract

This is the first iteration of implementing attestations into the hypercert ecosystem. The scope of this dev cycle will be establishing the patterns required to grow our evaluation ecosystem.

We propose:

• implementing evaluations in a side-app using the starter app
• provide an initial schema for attesting correctness of claim data
• setting up a basic registry of trusted attestors
• create and deploy an indexing service to make hypercerts queryable (either via our Graph deployment or a custom API)

Motivation and rationale

Evaluations are a cornerstone of the hypercerts ecosystem. As frequently discussed we should add value (or truthiness) to impact claim by providing a marketplace for impact evaluations. To do this we've identified multiple steps:

1. Support basic evaluation patters like 'correctness' and 'duplicates'.
2. Provide a generalizable pattern for evaluating hypercerts.
3. Support partners in our ecosystem to use the patterns from 2) to grow an open ecosystem of impact evaluations.

The current proposal focusses on 1) and will lay the groundwork for 2).

Implementation

Scope

We propose a full-stack solution providing an attestation schema, trusted attestor registry, indexing service, and a front-end application for reviewing hypercerts and inspect available attestations.

Attestations schema

The attestation schema is designed to attest to the correctness of the hypercert claim data. In other words, evaluators can attest “Yes, this hypercert was part of GG19 and has the correct data”.

The following schema is proposed:

# Identy the hypercerts (required)
ChainID: uint256
Contract: address
ClaimID: uint256

# Evaluate the dimensions of the impact claim (at least one)
Creator: boolean
Contributors: boolean
Work: boolean
Work timeframe: boolean
Impact: boolean
Impact timeframe: boolean

# Comment required when anything is false
Comment: string 

#  E.g. [“gitcoin”, “gg19”, “climate round”]
Tags: string[]

Trusted attestor registry

While striving for an open ecosystem, the value of knowing who is creating certain attestations should be acknowledged. The set the first steps in knowing who is submitting the evaluations, we propose a reposity containing a JSON that functions as a registry of evaluators provided by impact organisations.

This registry will be maintained by the hypercerts team. Additions and changes can be provided by anyone by submitting a PR.

The inital data object will look like this:

{
  "gitcoin": {
    "website": "https://gitcoin.co",
    "logo": "ipfs://sdmiadncawsc...cascasf",
    "evaluators": {
      "handle0x1": {
        "address": "0x1"
      },
      "handle0x2": {
        "address": "0x2"
      },
      "handle0x3": {
        "address": "0x3"
      }
    }
  }
}

This schema will probably change as we learn that we require more data. When the format is stable, we can explore migrating this to EAS in the future.

Front-end application

The application will be side-app to the hypercerts application to enable rapid itterations without introducing breaking changes to our users. The front-end provides the following features:

• As a user, I can query for hypercerts that I want to evaluates
• As a user, I can attest to the correctness of the data in the hypercert claim data
• As a user, I can inspect attestations provided for a given hypercerts
• As a user, I can identify trustes attestors based on a badge attached to the hypercert data

Indexing service

The streamline the process of evaluating the thousands of hypercerts that have been minted, we need to provide a search experience for attestors so that they can easily find the hypercerts they want to attest to but also identify duplicates.

Our prefered solution is to implement the Graph as a single source of truth but when setting up a Proof of Concept we can into indexing issues. Therefore the current proposal is to expand the IPFS upload API provided by the Hypercerts Foundation with endpoints to querying hypercerts.

We propose a GET request with query parameters covering the name, description, and hypercert claim data as optional parameters.

Pseudocode for endpoint:

GET /v1/metadata?name="test SDK"&description="open source"&work_timeframe="170720"

It will return HypercertMetadata[].

Additionally any attestations found for the hypercerts will be returned by also monitoring available attestations provided by the EAS indexer service.

Data will be aggregated by setting up and indexing service that monitors emitted events and stores those in a Postgres database.

Visuals

Miro board

Operation requirements and ownership

Ownership and development will be shared by @bitbeckers and @kristoferlund

We designed the infrastructure to utilize EAS so the attestation data and schema will be publicly available to all users of EAS.

---

Links and additional information

Inital discussion
Miro board

[holkexyz]

Thank you @bitbeckers and @kristoferlund. I like this a lot.

Here are some comments:

1. reg. Trusted attestor registry: Suppose some organisation builds a funding platform on top of the hypercerts protocol. And they want to define a set of trusted attestors, who will attest hypercerts on their platform. Do these attestors have to be approved by the hypercerts foundation? If so, we will need a good governance system for that. The alternative would be that they would be able to define a trusted attestor registry that they use for their platform. In that case the hypercerts foundation has a less critical role in the process.
2. I'm not convinced we need the details about which dimension is correct or not because what will matter in the frontend is if the hypercert is attested or not. However, I can see a future use case for the details if we allow mutable metadata. In that case a hypercert creator could respond to the attestation and correct it. Is that what you had in mind or is there a different reason for the level of detail?
3. We have the overview page for hypercert and the detail view page for hypercerts in the marketplace app. Do we reuse those components? We also have some designs for the filter functionality. Ultimately, we want to show attestations where hypercerts can be bought and sold. If we would either reuse those components or if we would integrate the evaluations into the marketplace app, would that change the required work? I would like to think them together right away.
4. Will the user be able to filter by metadata, e.g. I filter for all hypercerts with attestations and search for the work scope “libp2p”?
5. Reg. "Stretch: script for batch wise attestations ; only if time/budget left": This is described specifically for matching grant recipients. I think I have an alternative batch attestation function in mind: (a) An attestor knows that these 100 wallets likely created hypercerts for their projects, (b) she inputs all wallet addresses, (c) the frontend shows all hypercerts from these wallets grouped by wallet, (d) she filters by time of work or date created, (e) she selects all hypercerts that she wants to attest, (f) she confirms the batch attestation, (g) those that she didn't attest, she can go into the detail page and create more detailed attestations with comments. Does that make sense?

[bitbeckers]

Thanks :)

1. No, it would be more akin to tokenlists where orgs can provide the list of tokens they acknowledge. So we maintain our list, and OP RPGF is free to maintain their own. Within OP RPGF, they're using ENS for this and maybe we can as well in the future. The current step is the bare minimum to get there.
2. The level of detail is for multiple reasons:
   a. Maybe an evaluator is not knowledgeable of all details. For example GitCoin can acknowledge round participation, a recipient of the work declared can attest to that piece.
   b. Indeed future proofing, on the FE we can default all to true for initial purposes, but this allows us to open up to finer granularity
3. Would you also want to create attestations where they're bought and sold? If it's about the same design language maybe @kristoferlund could work of a fork of https://github.com/hypercerts-org/hyperboards that already has the chakra theming?
4. That's the goal of the indexer, yes.
5. We hadn't considered batch attestations on the front-end just yet. It introduces some gotcha's:

• Will the user batch review the full content of the hypercert? Is it realistic one user can do this for >3 hypercerts at the same time?
• If the user is incentivised to do this, will this facilitate sloppy attestations?
• The one thing the user can be sure of, when they know the public address of an project, is that the hypercert creator address matches the one of the public project. This is related to 2)
• I'm happy to be wrong here, but I think state management for batch-wise attestations which also enable the user to drill down into the hypercert, might blow up the scope. I defer to @kristoferlund 's judgment.

[holkexyz]

Thanks, that sounds good.

On 3. Yes, I think a separate page in the same app that is only accessible/visible for those that are in the Trusted Attestor Registry makes sense for that.

On 5. Fair points, I think only the users and observed user behavior will answer this. Maybe we can check in with Gitcoin on this as they would be a first user.

[kristoferlund]

Hi!

3: Sure, we use the same design language. 👍 Is hyperboards "the marketplace app"? Don't have the full picture yet of what does exist already and where.

5: Yes, we would definitely have a detailed look at a real usecase to determine what kind of batch attestation support would be valuable. It does risk becoming fairly complex pretty soon though if we want to allow evaluators to batch attest to many hypercerts and have the option to look at details if needed. I'd recommend we move this to next iteration.

[holkexyz]

Another general comment:
6. Suppose I have an overall evaluation of a project like libp2p. The project creates multiple evaluations over time and for separate aspects, e.g. for go-libp2p and rust-libp2p. What is the evaluation addressed to?

Proposal: The evaluation could point to the work scope "libp2p" in a given time period, e.g. from 01-01-2023 to 31-12-2023. Then the evaluator can choose which hypercerts that fall into this space of the public goods space to include, e.g. both "go-libp2p" and "rust-libp2p" have the work scope "libp2p" and hence can be chosen to be included.

Ideally, the evaluator would have attested that these two hypercerts are correct and based on the correctness and the scope it would be automatically included, but that seems too complex, doesn't it?

This would ultimately mean that the evaluations point to a space of the public goods space and specify what the evaluator attests is in that space.

[holkexyz]

Here is another use case, where we might need something like this in the future: Suppose we want to evaluate the biodiversity in a region, but no hypercert exists yet that claims to have influenced this result (potentially because in that region hypercerts aren't being used yet).

That use case would be possible if we point it to the space rather than the specific hypercert(s).

I guess an alternative implementation would be if it would point to an empty dynamic "hypercert collection" that can be associated with hypercerts later.

[bitbeckers]

I see where you're going, but this is something we can't account for currently. There's no standardised language around work, impact, etc. So there's a hypothetical case an user creates and attestation for impact, or simply provides observation data, and that work/impact should be claimed by another user. In theory, a third party evaluator could create prefilled attestations in a database and allow users to claim the impact and automatically receive the attestation form the 3rd party after passing certain checks. We're not blocking nor facilitating this with the current design.

It's good to ideate on this, but I think it's beyond the purpose of this iteration.

Do you feel anything is missing?

[holkexyz]

Agree that it might go beyond this first implementation, but I wonder if the structure of this iteration should be influenced by this later use case. What I am suggesting is that an evaluation could instead of pointing to a hypercert, could point to dimensions of the impact space, e.g. for a later impact evaluation:

# Identify the hypercerts
ChainID: uint256[]
Contract: address[]
ClaimID: uint256[]

Identify the impact space
ScopeOfWork (required)
TimeOfWork (required)
Contributors (optional)
ScopeOfImpact (optional)
TimeOfImpact (optional)

# Evaluate the impact 
[template based on the impact domain]

If it is pointing to a hypercert directly, the information about the impact space is filled in from the information of the hypercert.

If this evaluation is mutable, the evaluator can create it without any hypercerts included. Later when hypercerts are created that claim this impact, the evaluator could attest that those hypercerts should be included in the evaluation. This enables a case where the scope of work could be a a forest with a specific geographical location that was protected and we evaluate the outcomes of that. Later a hypercert claims part of this impact.

[bitbeckers]

We're talking about a different schema here and that is something we must support. The idea is that we define schemas per use case and they can have unique datafields and requirements. For the case we're outlining in our proposal ('this is the one') the existence of an hypercert is implicit and we make that explicit in the schema.

In short, schemas are independent and schema A should not be a blocker for schema B.

[holkexyz]

Perfect, that sounds great