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

package/core/class/Fetcher.ts

@@ -0,0 +1,224 @@
+import { Hex, IAttestation, TSchemaName } from "core/types";
+import { Attestation } from "./Attestation";
+import { Community, Grant, MemberOf, Milestone, Project } from "./entities";
+import { Grantee } from "./types/attestations";
+import { AxiosGQL } from "./GraphQL/AxiosGQL";
+import { GAP } from "./GAP";
+
+export abstract class Fetcher extends AxiosGQL {
+  protected gap: GAP;
+
+  constructor(url: string) {
+    super(url);
+  }
+
+  set gapInstance(gap: GAP) {
+    this.gap = gap;
+  }
+
+  /**
+   * Fetch a single attestation by its UID.
+   * @param uid
+   */
+  abstract attestation<T = unknown>(uid: Hex): Promise<Attestation<T>>;
+
+  /**
+   * Fetch attestations of a schema.
+   * @param schemaName
+   * @param search if set, will search decodedDataJson by the value.
+   * @returns
+   */
+  abstract attestations(
+    schemaName: TSchemaName,
+    search?: string
+  ): Promise<IAttestation[]>;
+
+  /**
+   * Fetch attestations of a schema.
+   * @param schemaName
+   * @param recipient
+   * @returns
+   */
+  abstract attestationsOf(
+    schemaName: TSchemaName,
+    recipient: Hex
+  ): Promise<IAttestation[]>;
+
+  /**
+   * Fetch attestations of a schema for a specific recipient.
+   * @param schemaName
+   * @param recipient
+   * @returns
+   */
+  abstract attestationsTo(
+    schemaName: TSchemaName,
+    recipient: Hex
+  ): Promise<IAttestation[]>;
+
+  /**
+   * Fetch all available communities with details and grantees uids.
+   *
+   * If search is defined, will try to find communities by the search string.
+   * @param search
+   * @returns
+   */
+  abstract communities(search?: string): Promise<Community[]>;
+
+  /**
+   * Fetch all available communities with details for a grantee;
+   *
+   * If search is defined, will try to find communities by the search string.
+   * @param address grantee address
+   * @param withGrants if true, will get community grants.
+   * @returns
+   */
+  abstract communitiesOf(
+    address: Hex,
+    withGrants?: boolean
+  ): Promise<Community[]>;
+
+  /**
+   * Fetch all available communities (admin) with details for a grantee;
+   *
+   * If search is defined, will try to find communities by the search string.
+   * @param address grantee address
+   * @param withGrants if true, will get community grants.
+   * @returns
+   */
+  abstract communitiesAdminOf(
+    address: Hex,
+    withGrants?: boolean
+  ): Promise<Community[]>;
+
+  /**
+   * Fetch a set of communities by their ids.
+   * @param uids
+   * @returns
+   */
+  abstract communitiesByIds(uids: Hex[]): Promise<Community[]>;
+
+  /**
+   * Fetch a community by its name with details, grants and milestones.
+   *
+   * It is possible that the resulted community is not the one you are looking for.
+   * @param name
+   * @returns
+   */
+  abstract communityBySlug(slug: string): Promise<Community>;
+
+  /**
+   * Fetch a community by its id. This method will also return the
+   * community details and projects.
+   */
+  abstract communityById(uid: Hex): Promise<Community>;
+
+  /**
+   * Fetch a project by its id.
+   * @param uid
+   * @returns
+   */
+  abstract projectById(uid: Hex): Promise<Project>;
+
+  /**
+   * Fetch a project by its slug.
+   * @param slug
+   * @returns
+   */
+  abstract projectBySlug(slug: string): Promise<Project>;
+
+  /**
+   * Search projects and communities by name. This method will return a list of projects and a list of communities
+   * __Must be implemented by the indexer__
+   * @param query
+   */
+  abstract search(
+    query: string
+  ): Promise<{ projects: Project[]; communities: Community[] }>;
+
+  /**
+   * Search projects by name. This method will return a list of projects
+   * __Must be implemented by the indexer__
+   * @param query
+   */
+  abstract searchProjects(query: string): Promise<Project[]>;
+
+  /**
+   * Fetch projects with details and members.
+   * @param name if set, will search by the name.
+   * @returns
+   */
+  abstract projects(name?: string): Promise<Project[]>;
+
+  /**
+   * Fetch projects with details and members.
+   * @param grantee the public address of the grantee
+   * @returns
+   */
+  abstract projectsOf(grantee: Hex): Promise<Project[]>;
+
+  /**
+   * Fetch Grantee with details and projects.
+   * @param address
+   * @param withProjects if true, will get grantee project details.
+   * @returns
+   */
+  abstract grantee(address: Hex): Promise<Grantee>;
+
+  /**
+   * Fetch all Grantees with details.
+   * @returns
+   */
+  abstract grantees(): Promise<Grantee[]>;
+
+  /**
+   * Fetches the grantes related to a grantee address (recipient).
+   * @param grantee grantee address
+   * @returns
+   */
+  abstract grantsOf(grantee: Hex, withCommunity?: boolean): Promise<Grant[]>;
+
+  /**
+   * Fetch grants for an array of projects with milestones.
+   * @param projects
+   * @returns
+   */
+  abstract grantsFor(
+    projects: Project[],
+    withCommunity?: boolean
+  ): Promise<Grant[]>;
+
+  /**
+   * Fetch a grants that belongs to a community.
+   * @param uid community uid
+   * @returns
+   */
+  abstract grantsByCommunity(uid: Hex, page?: number, pageLimit?: number);
+
+  /**
+   * Fetch all milestones related to an array of Grants.
+   * @param grants
+   * @returns
+   */
+  abstract milestonesOf(grants: Grant[]): Promise<Milestone[]>;
+
+  /**
+   * Bulk fetch members with details of an array of Projects.
+   * @param projects
+   * @returns
+   */
+  abstract membersOf(projects: Project[]): Promise<MemberOf[]>;
+
+  /**
+   * Check if a name is already in use.
+   * @param slug
+   * @returns
+   */
+  abstract slugExists(slug: string): Promise<boolean>;
+
+  /**
+   * Get grants for a project by an external uid
+   * > Works only for the indexed projects
+   * @param projectExtId
+   */
+  abstract grantsForExtProject(projectExtId: string): Promise<Grant[]>;
+}

package/core/class/GAP.ts

@@ -0,0 +1,481 @@
+import CommunityResolverABI from "../abi/CommunityResolverABI.json";
+import MulticallABI from "../abi/MultiAttester.json";
+import ProjectResolverABI from "../abi/ProjectResolver.json";
+
+import { EAS } from "@ethereum-attestation-service/eas-sdk";
+import { ethers } from "ethers";
+import { version } from "../../package.json";
+import { MountEntities, Networks } from "../consts";
+import {
+  AttestArgs,
+  Facade,
+  SchemaInterface,
+  SignerOrProvider,
+  TNetwork,
+  TSchemaName,
+} from "../types";
+import { getWeb3Provider } from "../utils/get-web3-provider";
+import { Fetcher } from "./Fetcher";
+import { GapSchema } from "./GapSchema";
+import { GapEasClient } from "./GraphQL";
+import { RemoteStorage } from "./remote-storage/RemoteStorage";
+import { Schema } from "./Schema";
+
+interface GAPArgs {
+  network: TNetwork;
+  globalSchemas?: boolean;
+  /**
+   * Custom API Client to be used to fetch attestation data.
+   * If not defined, will use the default EAS Client and rely on EAS's GraphQL API.
+   */
+  apiClient?: Fetcher;
+  schemas?: SchemaInterface<TSchemaName>[];
+  /**
+   * Defined if the transactions will be gasless or not.
+   *
+   * In case of true, the transactions will be sent through [Gelato](https://gelato.network)
+   * and an API key is needed.
+   *
+   * > __Note that to safely transact through Gelato, the user must
+   * have set a handlerUrl and not expose gelato api in the frontend.__
+   */
+  gelatoOpts?: {
+    /**
+     * Endpoint in which the transaction will be sent.
+     * A custom endpoint will ensure that the transaction will be sent through Gelato
+     * and api keys won't be exposed in the frontend.
+     *
+     * __If coding a backend, you can use `apiKey` prop instead.__
+     *
+     * `core/utils/gelato/sponsor-handler.ts` is a base handler that can be used
+     * together with NextJS API routes.
+     *
+     * @example
+     *
+     * ```ts
+     * // pages/api/gelato.ts
+     * import { handler as sponsorHandler } from "core/utils/gelato/sponsor-handler";
+     *
+     * export default const handler(req, res) => sponsorHandler(req, res, "GELATO_API_KEY_ENV_VARIABLE");
+     *
+     * ```
+     */
+    sponsorUrl?: string;
+    /**
+     * If true, env_gelatoApiKey will be marked as required.
+     * This means that the endpoint at sponsorUrl is contained in this application.
+     *
+     * E.g. Next.JS api route.
+     */
+    contained?: boolean;
+    /**
+     * The env key of gelato api key that will be used in the handler.
+     *
+     * @example
+     *
+     * ```
+     * // .env
+     * GELATO_API_KEY=1234567890
+     *
+     * // sponsor-handler.ts
+     *
+     * export async function handler(req, res) {
+     *  // ...code
+     *
+     *  const { env_gelatoApiKey } = GAP.gelatoOpts;
+     *
+     *  // Will be used to get the key from environment.
+     *  const { [env_gelatoApiKey]: apiKey } = process.env;
+     *
+     *  // send txn
+     *  // res.send(result);
+     * }
+     * ```
+     */
+    env_gelatoApiKey?: string;
+    /**
+     * API key to be used in the handler.
+     *
+     * @deprecated Use this only if you have no option of setting a backend, next/nuxt api route
+     * or if this application is a backend.
+     *
+     * > __This will expose the api key if used in the frontend.__
+     */
+    apiKey?: string;
+    /**
+     * If true, will use gelato to send transactions.
+     */
+    useGasless?: boolean;
+  };
+  /**
+   * Defines a remote storage client to be used to store data.
+   * If defined, all the details data from an attestation will
+   * be stored in the remote storage, e.g. IPFS.
+   */
+  remoteStorage?: RemoteStorage;
+}
+
+/**
+ * GAP SDK Facade.
+ *
+ * This is the main class that is used to interact with the GAP SDK.
+ *
+ * This class implements the singleton pattern to ensure only one instance exists
+ * throughout the application lifecycle.
+ *
+ * Using this class, the user will be able to:
+ *
+ * - Create and manage attestations
+ * - Create and manage schemas
+ * - Fetch data from the EAS
+ *
+ * #### Features
+ *  - EAS Client: used to interact with EAS contracts
+ *  - EAS Fetcher: used to fetch data from the EAS GraphQL API, providing methods for:
+ *    - Get projects
+ *    - Get grants with its details
+ *    - Get grantees
+ *    - Get members
+ *    - Get tags
+ *    - Get external links
+ *    - Get schemas
+ *    - Get attestations by pair, attester, recipient, schema, or UID
+ *    - Get dependent attestations
+ * - Schema: used to create and manage schemas
+ * - Attestation: used to create and manage attestations
+ * - Replace schemas: used to replace the schema list with a new list
+ * - Replace single schema: used to replace a single schema from the schema list
+ *
+ * ---
+ * @example
+ * ```ts
+ * import { GAP } from "./core/class/GAP";
+ * import { GapSchema } from "./core/class/GapSchema";
+ * import { Schema } from "./core/class/Schema";
+ * import { MountEntities, Networks } from "./core/consts";
+ *
+ * const schemas = MountEntities(Networks.sepolia);
+ *
+ * // Initialize the singleton instance
+ * const gap = GAP.getInstance({
+ *   network: "sepolia",
+ *   owner: "0xd7d1DB401EA825b0325141Cd5e6cd7C2d01825f2",
+ *   schemas: Object.values(schemas),
+ * });
+ *
+ * // Later in the code, get the same instance
+ * const sameGap = GAP.getInstance();
+ *
+ * gap.fetcher
+ *   .fetchProjects()
+ *   .then((res) => {
+ *     console.log(JSON.stringify(res, null, 2));
+ *   })
+ *
+ * ```
+ */
+export class GAP extends Facade {
+  private static remoteStorage?: RemoteStorage;
+  private static instances: Map<TNetwork, GAP> = new Map();
+
+  readonly fetch: Fetcher;
+  readonly network: TNetwork;
+
+  private _schemas: GapSchema[];
+  private static _gelatoOpts = null;
+
+  /**
+   * Get the singleton instance of GAP for a specific network.
+   * If no instance exists for the network, creates one with the provided args.
+   * @param args Optional initialization arguments
+   * @returns The singleton instance of GAP for the specified network
+   */
+  static getInstance(args?: GAPArgs): GAP {
+    if (!args) {
+      throw new Error("Network must be specified when getting GAP instance");
+    }
+
+    const existingInstance = GAP.instances.get(args.network);
+    if (existingInstance) {
+      return existingInstance;
+    }
+
+    if (!args) {
+      throw new Error("Initialization arguments required for first instance");
+    }
+
+    const newInstance = new GAP(args);
+    GAP.instances.set(args.network, newInstance);
+    return newInstance;
+  }
+
+  /**
+   * Creates a new instance of GAP.
+   * You can either use this constructor directly or use the singleton pattern via getInstance().
+   * @param args Initialization arguments
+   */
+  constructor(args: GAPArgs) {
+    super();
+
+    const schemas =
+      args.schemas || Object.values(MountEntities(Networks[args.network]));
+
+    this.network = args.network;
+
+    this._eas = new EAS(Networks[args.network].contracts.eas);
+
+    this.fetch =
+      args.apiClient ||
+      new GapEasClient({
+        network: args.network,
+      });
+
+    this.fetch.gapInstance = this;
+
+    this.assertGelatoOpts(args);
+    GAP._gelatoOpts = args.gelatoOpts;
+
+    GAP.remoteStorage = args.remoteStorage;
+
+    this._schemas = schemas.map(
+      (schema) =>
+        new GapSchema(
+          schema,
+          this,
+          false,
+          args.globalSchemas ? !args.globalSchemas : false
+        )
+    );
+
+    Schema.validate(this.network);
+
+    console.info(`Loaded GAP SDK v${version} for network ${this.network}`);
+
+    GAP.instances.set(this.network, this);
+  }
+
+  private assertGelatoOpts(args: GAPArgs) {
+    if (
+      args.gelatoOpts &&
+      !(args.gelatoOpts.sponsorUrl || args.gelatoOpts.apiKey)
+    ) {
+      throw new Error("You must provide a `sponsorUrl` or an `apiKey`.");
+    }
+
+    if (
+      args.gelatoOpts?.sponsorUrl &&
+      args.gelatoOpts?.contained &&
+      !args.gelatoOpts.env_gelatoApiKey
+    ) {
+      throw new Error(
+        "You must provide `env_gelatoApiKey` to be able to use it in a backend handler."
+      );
+    }
+
+    if (
+      (args.gelatoOpts?.env_gelatoApiKey ||
+        args.gelatoOpts?.apiKey ||
+        args.gelatoOpts?.sponsorUrl) &&
+      !args.gelatoOpts?.useGasless
+    ) {
+      console.warn(
+        "GAP::You are using gelatoOpts but not setting useGasless to true. This will send transactions through the normal provider."
+      );
+    }
+  }
+
+  /**
+   * Creates the attestation payload using a specific schema.
+   * @param from
+   * @param to
+   * @param data
+   * @param schema
+   */
+  async attest<T>(attestation: AttestArgs<T> & { schemaName: TSchemaName }) {
+    const schema = GapSchema.find(attestation.schemaName, this.network);
+    return schema.attest(attestation);
+  }
+
+  /**
+   * Replaces the schema list with a new list.
+   * @param schemas
+   */
+  replaceSchemas(schemas: GapSchema[]) {
+    Schema.replaceAll(schemas, this.network);
+  }
+
+  /**
+   *  Replaces a schema from the schema list.
+   * @throws {SchemaError} if desired schema name does not exist.
+   */
+  replaceSingleSchema(schema: GapSchema) {
+    Schema.replaceOne(schema, this.network);
+  }
+
+  /**
+   * Generates a slug from a text.
+   * @param text
+   * @returns
+   */
+  generateSlug = async (text: string): Promise<string> => {
+    let slug = text
+      .toLowerCase()
+      // Remove emojis
+      .replace(
+        /([\uE000-\uF8FF]|\uD83C[\uDF00-\uDFFF]|\uD83D[\uDC00-\uDDFF])/g,
+        ""
+      )
+      // Remove basic text emoticons
+      .replace(/[:;=][()DP]/g, "")
+      .replace(/ /g, "-")
+      .replace(/[^\w-]+/g, "")
+      .trim()
+      .replace(/^-+|-+$/g, ""); // Remove leading and trailing hyphens
+
+    const checkSlug = async (
+      currentSlug: string,
+      counter: number = 0
+    ): Promise<string> => {
+      const slugToCheck =
+        counter === 0 ? currentSlug : `${currentSlug}-${counter}`;
+      const slugExists = await this.fetch.slugExists(slugToCheck);
+
+      if (slugExists) {
+        return checkSlug(currentSlug, counter + 1);
+      }
+
+      return slugToCheck.toLowerCase();
+    };
+
+    return checkSlug(slug);
+  };
+
+  /**
+   * Returns a copy of the original schema with no pointers.
+   * @param name
+   * @returns
+   */
+  findSchema(name: TSchemaName): GapSchema {
+    const found = Schema.get<TSchemaName, GapSchema>(name, this.network);
+    return GapSchema.clone(found);
+  }
+
+  /**
+   * Find many schemas by name and return their copies as an array in the same order.
+   * @param names
+   * @returns
+   */
+  findManySchemas(names: TSchemaName[]): GapSchema[] {
+    const schemas = Schema.getMany<TSchemaName, GapSchema>(names, this.network);
+    return schemas.map((s) => GapSchema.clone(s));
+  }
+
+  /**
+   * Get the multicall contract
+   * @param signer
+   */
+  static async getMulticall(signer: SignerOrProvider) {
+    const chain =
+      (await signer.provider.getNetwork()) || (signer.provider as any).network;
+    const network = Object.values(Networks).find(
+      (n) => +n.chainId === Number(chain.chainId)
+    );
+    if (!network)
+      throw new Error(`Network ${chain.name || chain.chainId} not supported.`);
+
+    const address = network.contracts.multicall;
+    return new ethers.Contract(address, MulticallABI, signer as any);
+  }
+
+  /**
+   * Get the multicall contract
+   * @param signer
+   */
+  static async getProjectResolver(
+    signer: SignerOrProvider & { getChainId?: () => Promise<number> },
+    chainId?: number
+  ) {
+    const currentChainId =
+      chainId ||
+      Number(
+        (await signer.provider.getNetwork())?.chainId ||
+          (await signer.getChainId())
+      );
+
+    const provider = chainId ? getWeb3Provider(chainId) : signer;
+    const network = Object.values(Networks).find(
+      (n) => +n.chainId === Number(currentChainId)
+    );
+    const address = network.contracts.projectResolver;
+    return new ethers.Contract(address, ProjectResolverABI, provider as any);
+  }
+
+  /**
+   * Get the multicall contract
+   * @param signer
+   */
+  static async getCommunityResolver(
+    signer: SignerOrProvider & { getChainId?: () => Promise<number> },
+    chainId?: number
+  ) {
+    const currentChainId =
+      chainId ||
+      Number(
+        (await signer.provider.getNetwork())?.chainId ||
+          (await signer.getChainId())
+      );
+
+    const provider = chainId ? getWeb3Provider(chainId) : signer;
+    const network = Object.values(Networks).find(
+      (n) => +n.chainId === Number(currentChainId)
+    );
+    const address = network.contracts.communityResolver;
+    return new ethers.Contract(address, CommunityResolverABI, provider as any);
+  }
+
+  get schemas() {
+    return this._schemas;
+  }
+
+  /**
+   * Defined if the transactions will be gasless or not.
+   *
+   * In case of true, the transactions will be sent through [Gelato](https://gelato.network)
+   * and an API key is needed.
+   */
+  private static set gelatoOpts(gelatoOpts: GAPArgs["gelatoOpts"]) {
+    if (typeof this._gelatoOpts === "undefined") {
+      this._gelatoOpts = gelatoOpts;
+    } else {
+      throw new Error("Cannot change a readonly value gelatoOpts.");
+    }
+  }
+
+  /**
+   * Defined if the transactions will be gasless or not.
+   *
+   * In case of true, the transactions will be sent through [Gelato](https://gelato.network)
+   * and an API key is needed.
+   */
+  static get gelatoOpts(): GAPArgs["gelatoOpts"] {
+    return this._gelatoOpts;
+  }
+
+  static set useGasLess(useGasLess: boolean) {
+    if (
+      useGasLess &&
+      !this._gelatoOpts?.apiKey &&
+      !this._gelatoOpts?.sponsorUrl &&
+      !this._gelatoOpts?.env_gelatoApiKey
+    ) {
+      throw new Error(
+        "You must provide a `sponsorUrl` or an `apiKey` before using gasless transactions."
+      );
+    }
+    this._gelatoOpts.useGasless = useGasLess;
+  }
+
+  static get remoteClient() {
+    return this.remoteStorage;
+  }
+}