@0xneves @heronlancellot @RafaDSan

Intro

We are still in the early stages of this journey, meticulously brainstorming the architecture to deliver the most optimized, legible, and scalable code. Our primary focus lies in fine-tuning the parameters that will seamlessly intertwine the scorer, EAS badges, and the front-end. In this pivotal moment, our primary objective is to seamlessly bridge the gap between the data structure and design, leaving only a sliver of space for the Hadron Collider to unleash the most modular and scalable scorer contract for Karma.

Updates

Architecture

Grant

We discussed the architecture in great detail because there isn't a clear standard on the internet to follow. We concluded that the best way to approach this was to observe other market players and understand how they register their grants. We observed the strongest projects, including Gitcoin, Chainlink, and Uniswap to come up with the following fields:

grantUID: bytes32 // Grant Id
network: uint256 // Blockchain network where the grant is being developed
protocol: string // Name of the protocol that issued the grant
grantee: address // Address of the person responsible for delivering and receiving the grant
project: string // Name of the project or company, that received the grant
externalLink: string // Link that redirects to the grant proposal
fundingToken[]: address // Tokens that will be granted
fundingAmount[]: uint256 // Amount of tokens granted to the grantee
initData: uint256 // Initial data for grant rewards and the beginning of grant development
endDate: uint256 // Expected completion date for the grant
status: enum(Status) // Current status of the grant

We considered the possibility of transforming this structure into an EIP (Ethereum Improvement Proposal) to standardize future development of grants.

Review

We thought carefully about how the review process should work, the major challenge is ensuring that the person who receives the grant is indeed the one who will review the grant. And there is no escape but having the entire grant proposal registered on-chain. This way we can access the grantee, among other properties, and assure that the reviewer is indeed the owner of the grant.

We propose the following structure which contains the reference to the grant attestation, the grantee, the review date, and the badges that were reviewed with their respective scores. For now, we are thinking about storing badges as base 2 to save storage slots but still looking for non-exhaustive alternatives that avoid paginations and don't rely on lengthy arrays.

reviewUID: bytes32 // Review Unique Identifier
grantUID: bytes32 // Reference to the Grant's attestation
grantee: address // Who submitted (attested) the review
badges: uint256[] // The total sum of base2 values of all available badges
scorer: uint256[]  // Value from 1 to 5 for each badge
reviewDate: uint256 // Review date in unix timestamp

Draft

Reflecting on the previous structures, we have the following workflow:

1. Execute the attestation on EAS, registering the Grant Schema shown above and having the grantee officialized for on-chain usage. We are still considering moving the Grant Schema to the Trustful Score because it will allow us to edit fields like status, endDate, and external links. Which cannot be done using EAS.
2. The Resolver contract is customized for Karma purpose, checking for specifications to generate the attestation, like:
   1. Is this user allowed to create a grant?
3. The grantee (marked as the owner of the grant in item 2) will review the grant.
4. Executes the attestation on EAS, using the Review Schema
5. The Resolver contract will check for specifications to generate the attestation, like:
   1. Is this user allowed to review this grant?
   2. Is this grant finalized?
6. Calculate the score on the Trustful Scorer Contract to be displayed in the screen
7. Subgraph will check for updates in the Trustful Scorer on the blockchain
8. The data is displayed in the frontend

Front-end

In the initial stages, we created the frontend-initial-design of the Review Section, with this we were able to create some Architecture to deal with the components related to the karma-gap infrastructure.

Looking at how the current Karma architecture is integrated, we created this to handle the new Review page feature:

Folder Structure

Additionally: The folder structure was created to make the integration of the feature easy. Creating new components to replace the old “Reviews” and "Review this grant”, using now only the “Review” option. We won't be removing the old reviews as discussed with Karma.

Current Implementation

For now, the frontend data is mocked. This data is not real data. In the next steps we will integrate the real data into these components. You can follow up current state in here: https://github.com/blockful-io/gap-app-v2/pull/2

index

CardReview

DynamicStarsReview

NavbarReview

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAQAAAAngNWGAAABDUlEQVR4AYXRgUZDYRjH4TegFTKgpEqiFJgoWAoMEQGBgBboChaaAKxLKAhAhQqAdAmpBIQolkCFqp2nITvNKXuA7+/Hhzey5OWjE4Nq3rzY1f9/NGHPB549492+8Ww060iCS2XdctZdI3GsECmb+HJoIX6x6EgDm+lURTH+YB7V9nAqE5WNme4YKuOiY6iMe6PaQxUUIuTbswgFVNJwA8sO3Bn6yR6bWZMSNtJwDtuWfHpQxaPx9C9zadil7jrCigbq6UXceNIVKTWUIqypm2ytJdTiNyNeXclF6GttOVfeDEc7qzjR23r3OMFqZKng1kw0mXGLrfibHTScOZWgGv9TdC6ROFeMTgwYiIxvJzMRWQbeGZUAAAAASUVORK5CYII=

EAS

Creating grants attestations

We need to communicate with the blockchain through the Karma Gap application, specifically with the Ethereum Attestation Service (EAS) smart contracts, to create a permanent and immutable grant on the blockchain, which is the attestation of a single grant.

Considering this, within the Karma Gap project, we created a file that will run every time a new grant is created. It will automatically generate a unique grant on the blockchain that can later be referenced so that the grantee can review this grant.

At present, this file remains in its developmental phase, requiring further refinement to dynamically interact with varying dataset information. Currently, it operates exclusively with predefined data sets, laying the groundwork for its eventual full functionality.

Visualizing reviews attestations

To effectively showcase the grantee's review, we must retrieve the pertinent data from the blockchain. To streamline this process, we've developed a dedicated file tasked with managing these data retrievals. Upon submission of a review by the grantee, this triggers an event on the blockchain, encapsulating all necessary data of the grant, the review, and the user.

We use Subgraph to extract the required information, which is then displayed to the user through the frontend interface. Given the structured nature and widespread adoption of this process within the industry, our task primarily involves customizing it to fit within our specific operational context.

At the moment this process is not yet finalized, working only with predefined data, as it is necessary to have the architecture completed and finalized to know exactly what data we need to fetch from the blockchain.

Smart Contract

There are two contexts in the smart contract at the moment: the Resolver Contract and the Scorer Contract.

• Regarding the Resolver contract, we are not very inclined to worry as it will only validate certain fields of the Grant and Review Schemas to make sure they respect the expected logic.
• The Scorer contract is more complex since will require the logic to scale and score badges for long periods. We are currently developing the indexing architecture to serve as a registry.
• We also used some time to think about backward compatibility with older badges/reviews/scores but it won't be worth the time due to the extensive time it will take to handle non-standardized data that varies between time and protocols.

Currently, the contracts are our smallest focus since our team is more experienced in the subject and can handle it more easily. The most important thing at the moment is having the architecture and design finalized and validated with Karma's approval.

Another challenge is to guarantee that other protocols will be able to use these data schemas for their scores. And that the old scores can still be used and recognized by future changes in the protocol.

Next Steps

aa

Finalize the Grant Structure

• Review and Refine: Conduct a thorough review of the proposed grant structure, refining the definitions and relationships between the fields to ensure clarity, efficiency, and scalability coming up with a final version of the architecture design.

Front-end

Switch the Review/Write Review button

• Review Button: Clicking the Review button will create a new Review, creating a new star in the first of the stars option with Card Review with empty badge scores
• Design and Layout:
  • Diminish the font size by 1~2. This will avoid the impact of having too much information on the screen and highlight the badges.
  • Create a margin for the CardReview Component, aligning the badges vertically with the first star of the NavbarReview.
  • Increase the badge sizes between 10~20%.
  • Create inner padding on the Card Review Component elements. That goes for badges, descriptions, and star scores.
  • Divisors between stars on NavbarReview should not go up to the top but rather shorter 10% on each side.
  • Decrease data font or increase div space in NavbarReview to have the dates on a single line when viewed from most desktop devices.
  • Increase the margin-bottom on the scroll of NavbarReview to avoid having the scroll appear and blocking the visibility of the component's inner elements.
  • Remove the gray border of stars in NavbarReview.
• Data Integration: Add the real deal, and change the mock for the actual data. This is currently blocked by the lack of smart contracts.

EAS

Enhance File Development for Grant Attestations

• Dynamic Data Interaction: Focus on developing the file designed to generate grant attestations on the blockchain. Blocked by the architecture, this involves enhancing its capability to be edited dynamically, moving beyond the current limitation of operating solely with a single state. We might move this issue from the EAS schemas to a regular smart contract struct due to the lack of malleability and backward compatibility.

Finalize Data Retrieval Mechanism

• Define Required Data: Precisely discuss and define the data requirements for displaying grantee reviews and other data coming from the blockchain.
• Integrate with Subgraph: Proceed with integrating the Subgraph technology into the Karma Gap application using the same code aesthetics originally used by Karma.

Smart Contract

Badge Registry Research

• Long-term badge availability with backward compatibility: We are working with two solutions, one which is good for the short-term but complex in the making and bad for the long-term, while the other is the regular way, using arrays and wasting gas. Hence we are looking for a third and more elegant option. The main problem is not how we store those badges, but how we fetch them. Just a few are all right, but we must try to avoid an array with 80, 200, or more badges. The most elegant way right now is to create a profile for each resolver implementer where they can choose up to 256 badges from the badge mapping. Allowing that a single uint256 is used for all badges, but capping at a maximum of 256 thought.