Gitcoin Attestation Network Backend Service

Overview

The Gitcoin Attestation Network Backend Service is a Next.js API that facilitates the signing of attestations for users to mint their donations as on-chain attestations. This service aggregates user donation data, encodes it according to the Ethereum Attestation Service (EAS) schema, and provides a signed attestation that users can submit on-chain via the Gitcoin Explorer frontend.

How It Works

Workflow diagram

sequenceDiagram
    participant User
    participant Gitcoin Explorer Frontend
    participant Backend API
    participant Grants Stack Indexer
    participant Signing Handler
    participant Secure Vault
    participant Blockchain

    User->>Gitcoin Explorer Frontend: Submit Mint Donations Impact Attestation Request
    Gitcoin Explorer Frontend->>Backend API: Send Attestation Request (/api/getAttestation)
    Backend API->>Grants Stack Indexer: Fetch Donation Details
    Grants Stack Indexer-->>Backend API: Return Donation Data
    Backend API->>Backend API: Aggregate & Format Data
    Backend API->>Backend API: Calculate Attestation Fee (getAttestationFee Service)
    Backend API->>Backend API: Encode Attestation Data (using the Encoder)
    Backend API->>Signing Handler: Send Encoded Attestation Data
    Signing Handler->>Secure Vault: Retrieve Private Key
    Signing Handler->>Signing Handler: Sign Attestation
    Signing Handler-->>Backend API: Return Signed Attestation
    Backend API-->>Gitcoin Explorer Frontend: Return Signed Attestation
    Gitcoin Explorer Frontend->>User: Prompt to Submit Transaction
    User->>Blockchain: Submit Attestation On-Chain

Loading

Detailed Step Breakdown

Below is a detailed breakdown of each step in the process:

1. Submit Mint Donations Impact Attestation Request:

   • The user accesses the Gitcoin Explorer frontend and opts to mint an attestation for their donations.
   • The user provides the necessary transactionHashes and selects the desired chainId.

2. Send Attestation Request to Backend:

   • The frontend sends a POST request to the backend API endpoint /api/getAttestation with the user's donation details.

3. Backend Processes the Request:

   • Fetch Donation Details:

     • The backend queries the Grants Stack Indexer using the provided transactionHashes to retrieve detailed information about each donation.

   • Aggregate and Format Data:

     • The backend aggregates the fetched donation data to compile metrics such as the number of projects contributed to, total donation amount in USD, and other relevant details.

   • Calculate Attestation Fee:

     • The getAttestationFee service calculates the necessary fee for minting the attestation based on the selected chainId and current network conditions.

       • Purpose: Calculates the dynamic fee required to mint the attestation based on the selected blockchain network's native token price.
       • Functionality:
         • Fetches the current price of the native token for the specified chainId.
         • Computes the attestation fee in the native token.
       • Integration:
         • Invoked during the backend processing phase to determine the appropriate fee before signing the attestation.

   • Encode Attestation Data:

     • The aggregated data is encoded into the GitcoinAttestationNetwork schema format.

4. Sign Attestation:

   • Retrieve Private Key:

     • The Signing Handler securely retrieves the delegator's private key from the Secure Vault.

   • Generate Signed Attestation:

     • The Signing Handler uses the private key to sign the encoded attestation data, creating a Delegated Attestation.

5. Return Signed Attestation to Frontend:

   • The backend sends the signed attestation back to the frontend.
   • The frontend notifies the user and prompts them to approve and submit the transaction to the blockchain.

6. Submit Attestation On-Chain:

   • The user confirms the transaction, and the signed attestation is submitted to the blockchain.
   • The attestation is recorded on-chain.

API Endpoint

POST /api/getAttestation

Request Body:

• transactionHashes (string[]): Array of transaction hashes of the user's donations.
• chainId (number): Chain ID of the network to mint the attestation.

Response:

• Returns the signed Delegated Attestation data.

Installation and Setup

To run the backend service locally:

1. Clone the Repository:

   git clone https://github.com/gitcoinco/gitcoin-server-api.git

2. Install Dependencies:

   cd gitcoin-server-api
   npm install

3. Environment Variables:

   cp .env.example .env

   Set the enviroment variables:

4. Run the Development Server:

   npm run dev