@show-karma/karma-gap-sdk 0.4.15 → 0.4.16

package/csv-upload/config.ts

@@ -0,0 +1,41 @@
+import { ChainConfig } from "./types";
+
+export const CHAIN_IDS: ChainConfig = {
+  optimism: 10,
+  "optimism-sepolia": 11155420,
+  sepolia: 11155111,
+  arbitrum: 42161,
+};
+
+export const DEFAULT_CONFIG = {
+  DEFAULT_OWNER_ADDRESS: "0x23B7A53ecfd93803C63b97316D7362eae59C55B6",
+  DEFAULT_NETWORK: "optimism-sepolia" as const,
+  CSV_PROCESSING: {
+    DELAY_BETWEEN_ITEMS_MS: 2000,
+    ELLIPSIS_LIMIT: 100,
+  },
+  ENS_REGEX: /^\w+\.(eth)$/,
+  HEX_REGEX: /^0x[a-fA-F0-9]{64}$/,
+};
+
+export const API_ENDPOINTS = {
+  ATTESTATIONS: "/attestations",
+  PROJECTS: {
+    CHECK: "/projects/check",
+  },
+  GRANTS: {
+    EXTERNAL_ID: {
+      BULK_UPDATE: "/grants/external-id/bulk-update",
+    },
+  },
+};
+
+export const LINK_TYPES = {
+  WEBSITE: "website",
+  TWITTER: "twitter",
+  GITHUB: "github",
+} as const;
+
+export const GRANT_UPDATE_TYPES = {
+  GRANT_UPDATE: "grant-update",
+} as const;

package/csv-upload/example.csv

@@ -0,0 +1,2 @@
+URL,Owner,Twitter,Github,Website,Project,"Project Description","If you've participated in past grant rounds, please share any new updates or milestones from the prior months",How do you measure the impact of your project?
+https://explorer.gitcoin.co/#/round/424/0x222ea76664ed77d18d4416d2b2e77937b76f0a35/0x222ea76664ed77d18d4416d2b2e77937b76f0a35-5,ethdotlimo.eth,https://eth.limo,https://github.com/ethlimo,https://eth.limo,test-skywalker,"eth.limo is a privacy-preserving ENS gateway, enabling users to access Ethereum-native dApps and content. LIMO represents a shift in dweb adoption by providing an alternative means of accessing ENS resolvable domains.","Support for .art ENS domain resolution, maintained 100% uptime, 1w3.eth content pinning - this ensures fast and reliable access to ENS domain data, with multiple storage locations and a streamlined gateway to IPFS for improved speed and availability. We're also working on some back-end improvements.",

package/csv-upload/keys.example.json

@@ -0,0 +1,8 @@
+{
+    "optimism": {
+        "privateKey": "your_private_key_here",
+        "rpcURL": "your_rpc_url_here",
+        "ipfsKey": "your_ipfs_key_here"
+    },
+    "gapAccessToken": "your_gap_access_token_here"
+}

package/csv-upload/scripts/run.ts

@@ -0,0 +1,417 @@
+import axios from "axios";
+import { ethers, isAddress } from "ethers";
+import * as csv from "fast-csv";
+import * as fs from "fs";
+import {
+  GAP,
+  Grant,
+  Hex,
+  MemberOf,
+  Project,
+  TNetwork,
+  nullRef,
+} from "../../core";
+import { GrantUpdate, IGrantUpdate } from "../../core/class";
+import {
+  GrantDetails,
+  ProjectDetails,
+} from "../../core/class/types/attestations";
+import {
+  API_ENDPOINTS,
+  CHAIN_IDS,
+  DEFAULT_CONFIG,
+  GRANT_UPDATE_TYPES,
+  LINK_TYPES,
+} from "../config";
+import { Link } from "../types";
+
+const [, , fileName, communityUID] = process.argv;
+
+interface Keys {
+  privateKey: string;
+  rpcURL: string;
+  gapAPI: string;
+  ipfsKey: string;
+}
+
+interface Config {
+  [key: string]: Keys | string;
+  optimism: Keys;
+  "optimism-sepolia": Keys;
+  sepolia: Keys;
+  arbitrum: Keys;
+  "base-sepolia": Keys;
+  celo: Keys;
+  sei: Keys;
+  "sei-testnet": Keys;
+  lisk: Keys;
+  scroll: Keys;
+  gapAccessToken: string;
+}
+
+interface NetworkConfig {
+  networkName: TNetwork;
+  rpcURL: string;
+  gapAPI: string;
+  ipfsURL: string;
+  privateKey: string;
+  ipfsKey: string;
+  gapAccessToken: string;
+}
+
+function loadConfig(): NetworkConfig {
+  const networkName = DEFAULT_CONFIG.DEFAULT_NETWORK as TNetwork;
+  const { [networkName]: keys, gapAccessToken } = require(__dirname +
+    "/../keys.json") as Config;
+
+  return {
+    networkName,
+    rpcURL: keys.rpcURL,
+    gapAPI:
+      DEFAULT_CONFIG.DEFAULT_NETWORK === "optimism-sepolia"
+        ? "https://gapstagapi.karmahq.xyz"
+        : "https://gapapi.karmahq.xyz",
+    ipfsURL: `${keys.gapAPI}/ipfs`,
+    privateKey: keys.privateKey,
+    ipfsKey: keys.ipfsKey,
+    gapAccessToken: gapAccessToken,
+  };
+}
+
+const config = loadConfig();
+
+const web3 = new ethers.JsonRpcProvider(config.rpcURL);
+const wallet = new ethers.Wallet(config.privateKey, web3);
+
+const gap = GAP.getInstance({ network: config.networkName });
+
+interface CSV {
+  Project: string;
+  ProposalURL: string;
+  Owner: string;
+  Twitter: string;
+  Github: string;
+  Website: string;
+  FundingMapID: string;
+  GrantTitle: string;
+  "Project Description": string;
+  "Grant Update": string;
+  "Grant Title": string;
+  GrantDescription: string;
+  externalId: string;
+  Amount: string;
+  "Grant Link": string;
+  "Grant Objective": string;
+  "Grant Size Justification": string;
+  Updates: string;
+  Problem: string;
+  Solution: string;
+}
+
+const duplicatedGrants: {
+  project: {
+    uid: string;
+    name?: string;
+  };
+  grant: {
+    uid: string;
+    title?: string;
+  };
+  currentExtId: string;
+  candidateExtId: string;
+}[] = [];
+
+export function parseCsv<T>(
+  path: string,
+  parserFn?: (row: unknown) => Promise<void> | void
+): Promise<T[]> {
+  return new Promise((resolve, reject) => {
+    const res: T[] = [];
+    fs.createReadStream(path)
+      .pipe(csv.parse({ headers: true }))
+      .transform((row: unknown) => {
+        return row;
+      })
+      .on("data", (d) => res.push(parserFn ? parserFn(d) : d))
+      .on("error", reject)
+      .on("end", () => {
+        resolve(res);
+      });
+  });
+}
+
+const isEns = (str: string) => DEFAULT_CONFIG.ENS_REGEX.test(str);
+const isHex = (str: string): str is Hex => DEFAULT_CONFIG.HEX_REGEX.test(str);
+
+type DbAttestation = {
+  attester: string;
+  chainID: number;
+  createdAt: Date;
+  recipient: string;
+  revocationTime: number;
+  revoked: boolean;
+  schemaUID: string;
+  uid: string;
+  refUID: string;
+  data?: any;
+  type: string;
+  externalId?: string;
+};
+
+async function checkProjectExists(projectDetails: DbAttestation) {
+  try {
+    const { data } = await axios.post(
+      `${config.gapAPI}${API_ENDPOINTS.PROJECTS.CHECK}`,
+      projectDetails
+    );
+    return data;
+  } catch (e) {
+    return undefined;
+  }
+}
+
+async function updateExternalIds(
+  projectUID: string,
+  communityUID: string,
+  externalId: string
+) {
+  await axios.put(
+    `${config.gapAPI}${API_ENDPOINTS.GRANTS.EXTERNAL_ID.BULK_UPDATE}`,
+    {
+      projectUID,
+      communityUID,
+      externalId,
+    },
+    {
+      headers: {
+        "x-access-token": config.gapAccessToken,
+      },
+    }
+  );
+}
+
+async function validateInputs() {
+  if (!fileName || !fileName.endsWith(".csv")) {
+    throw new Error("Please provide a valid csv file name");
+  }
+
+  if (!communityUID || !isHex(communityUID)) {
+    throw new Error("Please provide a valid community UID");
+  }
+
+  if (!fs.existsSync(__dirname + `/../${fileName}`)) {
+    throw new Error(`File ${fileName} does not exist`);
+  }
+}
+
+async function bootstrap() {
+  try {
+    await validateInputs();
+
+    let missedGrants: string[] = [];
+    let uids: Hex[] = [];
+
+    const file = __dirname + `/../${fileName}`;
+    const data = await parseCsv<CSV>(file);
+    const filtered = data.filter((d) => isAddress(d.Owner) || isEns(d.Owner));
+
+    let count = 0;
+
+    for (const item of data) {
+      try {
+        console.log(`${count} - ${item.Project.trim()}`);
+        count += 1;
+        await new Promise((f) =>
+          setTimeout(f, DEFAULT_CONFIG.CSV_PROCESSING.DELAY_BETWEEN_ITEMS_MS)
+        );
+
+        let address =
+          item?.Owner?.trim() || DEFAULT_CONFIG.DEFAULT_OWNER_ADDRESS;
+
+        const slug = await gap.generateSlug(item.Project.trim());
+        const project = new Project({
+          data: { project: true },
+          recipient: address as Hex,
+          schema: gap.findSchema("Project"),
+          uid: nullRef,
+        });
+
+        const links: Link[] = [
+          {
+            type: LINK_TYPES.WEBSITE,
+            url: item.Website,
+          },
+          {
+            type: LINK_TYPES.TWITTER,
+            url: item.Twitter,
+          },
+          {
+            type: LINK_TYPES.GITHUB,
+            url: item.Github,
+          },
+        ];
+
+        project.details = new ProjectDetails({
+          data: {
+            description: item["Project Description"],
+            imageURL: "",
+            title: item.Project.trim(),
+            links,
+            slug,
+            problem: item.Problem,
+            solution: item.Solution,
+          },
+          refUID: project.uid,
+          recipient: project.recipient,
+          schema: gap.findSchema("ProjectDetails"),
+          uid: nullRef,
+        });
+
+        const member = new MemberOf({
+          data: { memberOf: true },
+          recipient: project.recipient,
+          schema: gap.findSchema("MemberOf"),
+          refUID: project.uid,
+          uid: nullRef,
+        });
+
+        project.members.push(member);
+
+        const grant = new Grant({
+          data: { communityUID: communityUID as Hex },
+          recipient: project.recipient,
+          schema: gap.findSchema("Grant"),
+        });
+
+        grant.details = new GrantDetails({
+          data: {
+            proposalURL: item.ProposalURL,
+            title: item.GrantTitle,
+            description: item.GrantDescription,
+            ...(item.Amount && { amount: item.Amount }),
+            payoutAddress: project.recipient,
+            programId: item.FundingMapID,
+          },
+          recipient: project.recipient,
+          schema: gap.findSchema("GrantDetails"),
+        });
+
+        grant.updates.push(
+          new GrantUpdate({
+            data: {
+              text: "Updates can be found here: " + item.ProposalURL,
+              type: GRANT_UPDATE_TYPES.GRANT_UPDATE,
+              title: "",
+            } as IGrantUpdate,
+            recipient: project.recipient,
+            schema: gap.findSchema("GrantDetails"),
+          })
+        );
+
+        project.grants.push(grant);
+
+        const defaultValues = {
+          recipient: project.recipient,
+          attester: project.recipient,
+          chainID: CHAIN_IDS[config.networkName],
+          createdAt: new Date(),
+          revocationTime: 0,
+          revoked: false,
+        };
+
+        const projectDetails: DbAttestation = {
+          data: {
+            description: item["Project Description"],
+            imageURL: "",
+            title: item.Project.trim(),
+            slug: slug,
+          },
+          type: "ProjectDetails",
+          refUID: project.uid,
+          schemaUID: gap.findSchema("ProjectDetails").uid,
+          uid: nullRef,
+          ...defaultValues,
+        };
+
+        // avoid duplicate projects
+        const hasProject = await checkProjectExists(projectDetails);
+
+        if (hasProject) {
+          const concurrentGrant = hasProject.grants.find(
+            (g) => g.details?.data?.title === item.GrantTitle
+          );
+
+          if (!concurrentGrant) {
+            console.log(`Didn't find grant for project ${item.Project}`);
+            Object.assign(grant, { refUID: hasProject.uid });
+            missedGrants.push(item.Project);
+            await grant.attest(wallet as any, hasProject.chainID);
+          } else {
+            console.log(`Found grant for project ${item.Project}`);
+          }
+
+          if (
+            item.externalId &&
+            concurrentGrant &&
+            concurrentGrant.externalId &&
+            concurrentGrant.externalId !== item.externalId
+          ) {
+            duplicatedGrants.push({
+              project: {
+                uid: hasProject.uid,
+                name: hasProject.details?.title,
+              },
+              grant: {
+                uid: concurrentGrant.uid,
+                title: concurrentGrant.details?.title,
+              },
+              currentExtId: concurrentGrant.externalId,
+              candidateExtId: item.externalId,
+            });
+          } else if (item.externalId) {
+            await updateExternalIds(
+              hasProject.uid,
+              communityUID,
+              item.externalId
+            );
+          }
+          continue;
+        }
+
+        try {
+          console.log(project.details.data);
+          console.log(project.grants?.[0]?.details?.data);
+          await project.attest(wallet as any);
+          uids.push(project.uid);
+        } catch (e) {
+          console.log(`Failed to save for ${item.Project}`);
+        }
+      } catch (error) {
+        console.error(`Error processing project ${item.Project}:`, error);
+        missedGrants.push(item.Project);
+        continue;
+      }
+    }
+
+    console.log("Attested projects: ", uids.length);
+    console.log(uids);
+
+    console.log("Found concurrent grants for external ids: ");
+    console.log(duplicatedGrants);
+    const concurrentGrantFile = `${__dirname}/${Date.now()}-concurrent-grants.json`;
+    fs.writeFileSync(
+      concurrentGrantFile,
+      JSON.stringify(duplicatedGrants, null, 2)
+    );
+    console.log(
+      `\x1b[36mConcurrent grants saved to ${concurrentGrantFile}\x1b[0m`
+    );
+
+    console.log("Missed grants:", missedGrants);
+  } catch (error) {
+    console.error("Fatal error:", error);
+    process.exit(1);
+  }
+}
+
+bootstrap();

package/csv-upload/types.ts

@@ -0,0 +1,39 @@
+export interface ChainConfig {
+  [key: string]: number;
+}
+
+export type LinkType = "website" | "twitter" | "github";
+
+export interface Link {
+  type: LinkType;
+  url: string;
+}
+
+export interface Tag {
+  name: string;
+}
+
+export interface ProjectData {
+  description: string;
+  imageURL: string;
+  title: string;
+  links: Link[];
+  tags?: Tag[];
+  slug?: string;
+}
+
+export interface GrantData {
+  proposalURL: string;
+  title: string;
+  description: string;
+  amount: string;
+  payoutAddress: string;
+  cycle?: string;
+  season?: string;
+}
+
+export interface GrantUpdateData {
+  text: string;
+  type: string;
+  title: string;
+}

package/gap-schema.yaml

@@ -0,0 +1,155 @@
+DatabaseEntities:
+  attestation: _id, uid, schemaUID, refUID, attester, recipient, revoked, revocationTime, createdAt, updatedAt, chainID, type, data, external, txid
+  category: _id, name, communityId, createdAt, updatedAt
+  project_category: _id, category, attestationId, createdAt, updatedAt
+  project_contact: _id, attestationId, name, email, telegram, createdAt, updatedAt
+  project_subscription: _id, name, email, subscriptionUids, createdAt, updatedAt
+  program_registry: _id, programId, profileId, chainID, name, isValid, createdAtBlock, createdByAddress, metadata, updatedAtBlock, projectNumber, projectType, registryAddress, anchorAddress, txHash, createdAt, updatedAt, approvedAt
+  embeddings: _id, entityId, entityType, embeddings, createdAt, updatedAt
+  offchain_program_registry: _id, profileID, name, chainID, metadata, isValid, createdAt, updatedAt
+  bulk_project_subscription: _id, email, publicAddress, createdAt, updatedAt
+  project_request_intro: _id, projectUID, chainID, email, telegram, message, status, createdAt, updatedAt
+  external_impact: _id, data, isOnchain, createdAt, updatedAt
+  milestone_evaluations: _id, projectUID, grantUID, chainID, milestoneUID, description, completionText, rating, reasoning, model, createdAt, updatedAt
+  project_member_invite_link: _id, attestationId, hash, revoked, createdAt, updatedAt
+  impact_indicators: _id, name, description, unitOfMeasure, communityUID, chainID, createdAt, updatedAt
+  impact_segments: _id, name, description, type, categoryId, createdAt, updatedAt, impact_indicators
+  impact_indicator_datapoints: _id, value, startDate, endDate, proof, projectUID, chainID, impactIndicatorId, createdAt, updatedAt
+
+# This is how GAP stores its entities
+Community:
+  type: attestation[]
+  reference: type("Community")
+  description: Used as the main entity for communities
+  relationships:
+    Details:
+      type: attestation
+      reference: refUID(Community.uid), type("CommunityDetails")
+      description: Details about the Community - always use the latest CommunityDetails by createdAt
+
+    Grant:
+      type: attestation
+      reference: refUID(Project.uid) data.communityUID(Community.uid), type("Grant")
+      description: Grants within a community recieved by a project
+      extras: external.gitcoin => contains gitcoin projectIds for the project, external.octant => contains octant projectIds for the project
+      relationships:
+        Details:
+          type: attestation
+          reference: refUID(Grant.uid), type("GrantDetails")
+          description: Details about the Grant - always use the latest GrantDetails by createdAt
+
+        Project:
+          type: attestation[]
+          reference: refUID(Project.uid), uid(Grant.uid), type("Project")
+          description: Used as the main entity for the projects
+          extras: external.oso[] => contains OSO(Open Source Obeservatory) slugs for the project, external.contractAddresses[] = ["0x123", "0x456"], contract addresses of the project
+          relationships:
+            Details:
+              type: attestation
+              reference: refUID(Project.uid), type("ProjectDetails")
+              description: Details about the Project - always use the latest ProjectDetails by createdAt
+
+            ProjectPointer:
+              type: attestation[]
+              reference: refUID(ProjectB.uid), type("ProjectPointer"), data.ogProjectUID(ProjectA.uid)
+              description: Pointer to the original project - used for merging projects
+
+            ProjectImpact:
+              type: attestation[]
+              reference: refUID(Project.uid), type("ProjectImpact")
+              description: Impacts of the project
+              relationship:
+                ProjectImpactVerified:
+                  type: attestation[]
+                  reference: refUID(ProjectImpact.uid), type("ProjectImpactVerified")
+                  description: Used to show the show verifications of the Project Impact
+
+            ProjectMilestone:
+              type: attestation[]
+              reference: refUID(Project.uid), type("ProjectMilestone")
+              description: Milestones of the project
+              relationships:
+                ProjectMilestoneCompleted:
+                  type: attestation[]
+                  reference: refUID(ProjectMilestone.uid), type("ProjectMilestoneCompleted")
+                  description: Entity to track if a milestone is completed
+
+            ProjectEndorsement:
+              type: attestation[]
+              reference: refUID(Project.uid), type("ProjectEndorsement")
+              description: Endorsements of the project
+
+            ProjectUpdate:
+              type: attestation[]
+              reference: refUID(Project.uid), type("ProjectUpdate")
+              description: Updates of the project
+
+            MemberOf:
+              type: attestation[]
+              reference: refUID(Project.uid), type("MemberOf")
+              description: Members of the project are represented in recipient(0x{string})
+
+            ProjectCategory:
+              type: project_category[]
+              references: attestationId(Project._id), categoryId(Category._id)
+              description: Mapping of categories to projects
+
+        GrantUpdate:
+          type: attestation[]
+          reference: refUID(Grant.uid), type("GrantUpdate")
+          description: Updates of a recieved Grant
+          relationships:
+            GrantUpdateStatus:
+              type: attestation
+              reference: refUID(GrantUpdate.uid), type("GrantUpdateStatus")
+              description: Used to describe the status of a GrantUpdate. data.type("grant-update-verified") is used to show verified
+
+        Milestone:
+          type: attestation[]
+          reference: refUID(Grant.uid), type("Milestone")
+          description: Milestones of a grant
+          relationships:
+            MilestoneStatus:
+              type: attestation
+              reference: refUID(Milestone.uid), type("MilestoneStatus")
+              description: Used to describe the status of a Milestone. data.type("verified") is used to show verified and data.type("completed") is for completed
+
+        Program:
+          type: program_registry
+          reference: data.programId(`${Program.programId}_${Program.chainID}`), type("GrantDetails")
+          description: Contains all the Grant programs in the funding map
+          relationships:
+            Community:
+              type: attestation[]
+              reference: metadata.communityRef[](Community.uid)
+              description: Communities linked to this program explicitly
+
+    ImpactIndicators:
+      type: impact_indicators[]
+      reference: communityUID(Community.uid)
+      description: Indicators within a Community
+      relationships:
+        ImpactIndicatorDatapoints:
+          type: impact_indicator_datapoints[]
+          reference: impactIndicatorId(ImpactIndicator._id), projectUID(Project.uid))
+          description: Data points stored for an Impact Indicator for a project
+
+    Category:
+      type: category
+      reference: communityId(Community._id)
+      description: Categories of projects in a community
+      relationships:
+        ProjectCategory:
+          type: project_category[]
+          reference: categoryId(Category._id) attestationId(Project._id)
+          description: Mapping of Categories to Projects
+
+        ImpactSegment:
+          type: impact_segments
+          reference: categoryId(Category._id)
+          description: Impact segments our output/outcome groups of indicators for a category of projects
+          relationships:
+            ImpactIndicator:
+              type: impact_indicators
+              reference: impact_indicators(impact_indicators._id)[]
+              description: List of impact indicators grouped under this impact segment