@show-karma/karma-gap-sdk 0.1.29

package/core/class/GAP.d.ts

@@ -0,0 +1,212 @@
+import { AttestArgs, Facade, SchemaInterface, TNetwork, TSchemaName, SignerOrProvider } from "../types";
+import { GapSchema } from "./GapSchema";
+import { ethers } from "ethers";
+import { Fetcher } from "./Fetcher";
+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;
+    };
+}
+/**
+ * GAP SDK Facade.
+ *
+ * This is the main class that is used to interact with the GAP SDK.
+ *
+ * This class can behave as a singleton or as a regular class.
+ *
+ * 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);
+ *
+ * // Use GAP.createClient to create a singleton GAP client
+ * const gap = GAP.createClient({
+ *   network: "sepolia",
+ *   owner: "0xd7d1DB401EA825b0325141Cd5e6cd7C2d01825f2",
+ *   schemas: Object.values(schemas),
+ * });
+ *
+ * gap.fetcher
+ *   .fetchProjects()
+ *   .then((res) => {
+ *     console.log(JSON.stringify(res, null, 2));
+ *   })
+ *
+ * ```
+ */
+export declare class GAP extends Facade {
+    private static client;
+    readonly fetch: Fetcher;
+    readonly network: TNetwork;
+    private _schemas;
+    private static _gelatoOpts;
+    constructor(args: GAPArgs);
+    private assert;
+    /**
+     * Creates the attestation payload using a specific schema.
+     * @param from
+     * @param to
+     * @param data
+     * @param schema
+     */
+    attest<T>(attestation: AttestArgs<T> & {
+        schemaName: TSchemaName;
+    }): Promise<`0x${string}`>;
+    /**
+     * Replaces the schema list with a new list.
+     * @param schemas
+     */
+    replaceSchemas(schemas: GapSchema[]): void;
+    /**
+     *  Replaces a schema from the schema list.
+     * @throws {SchemaError} if desired schema name does not exist.
+     */
+    replaceSingleSchema(schema: GapSchema): void;
+    /**
+     * Generates a slug from a text.
+     * @param text
+     * @returns
+     */
+    generateSlug: (text: string) => Promise<string>;
+    /**
+     * Creates or returns an existing GAP client.
+     *
+     * _Use the constructor only if multiple clients are needed._
+     * @static
+     * @param {GAPArgs} args
+     * @returns
+     */
+    static createClient(args: GAPArgs): GAP;
+    /**
+     * Get the multicall contract
+     * @param signer
+     */
+    static getMulticall(signer: SignerOrProvider): ethers.Contract;
+    get schemas(): GapSchema[];
+    /**
+     * 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(value);
+    /**
+     * 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"];
+    static set useGasLess(useGasLess: boolean);
+}
+export {};

package/core/class/GAP.js

@@ -0,0 +1,206 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GAP = void 0;
+const types_1 = require("../types");
+const Schema_1 = require("./Schema");
+const GapSchema_1 = require("./GapSchema");
+const GapEasClient_1 = require("./GraphQL/GapEasClient");
+const eas_sdk_1 = require("@ethereum-attestation-service/eas-sdk");
+const consts_1 = require("../consts");
+const ethers_1 = require("ethers");
+const MultiAttester_json_1 = __importDefault(require("../abi/MultiAttester.json"));
+const package_json_1 = require("../../package.json");
+/**
+ * GAP SDK Facade.
+ *
+ * This is the main class that is used to interact with the GAP SDK.
+ *
+ * This class can behave as a singleton or as a regular class.
+ *
+ * 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);
+ *
+ * // Use GAP.createClient to create a singleton GAP client
+ * const gap = GAP.createClient({
+ *   network: "sepolia",
+ *   owner: "0xd7d1DB401EA825b0325141Cd5e6cd7C2d01825f2",
+ *   schemas: Object.values(schemas),
+ * });
+ *
+ * gap.fetcher
+ *   .fetchProjects()
+ *   .then((res) => {
+ *     console.log(JSON.stringify(res, null, 2));
+ *   })
+ *
+ * ```
+ */
+class GAP extends types_1.Facade {
+    constructor(args) {
+        super();
+        /**
+         * Generates a slug from a text.
+         * @param text
+         * @returns
+         */
+        this.generateSlug = async (text) => {
+            let slug = text
+                .toLowerCase()
+                .replace(/ /g, "-")
+                .replace(/[^\w-]+/g, "");
+            const slugExists = await this.fetch.slugExists(slug);
+            if (slugExists) {
+                const parts = slug.split("-");
+                const counter = parts.pop();
+                slug = /\d+/g.test(counter) ? parts.join("-") : slug;
+                // eslint-disable-next-line no-param-reassign
+                const nextSlug = `${slug}-${counter && /\d+/g.test(counter) ? +counter + 1 : 1}`;
+                console.log({ nextSlug, counter, slug });
+                return this.generateSlug(nextSlug);
+            }
+            return slug.toLowerCase();
+        };
+        const schemas = args.schemas || Object.values((0, consts_1.MountEntities)(consts_1.Networks[args.network]));
+        this.network = args.network;
+        GAP._eas = new eas_sdk_1.EAS(consts_1.Networks[args.network].contracts.eas);
+        this.fetch = args.apiClient || new GapEasClient_1.GapEasClient({ network: args.network });
+        this.assert(args);
+        GAP._gelatoOpts = args.gelatoOpts;
+        this._schemas = schemas.map((schema) => new GapSchema_1.GapSchema(schema, false, args.globalSchemas ? !args.globalSchemas : false));
+        Schema_1.Schema.validate();
+        console.info(`Loaded GAP SDK v${package_json_1.version}`);
+    }
+    assert(args) {
+        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(attestation) {
+        const schema = GapSchema_1.GapSchema.find(attestation.schemaName);
+        return schema.attest(attestation);
+    }
+    /**
+     * Replaces the schema list with a new list.
+     * @param schemas
+     */
+    replaceSchemas(schemas) {
+        Schema_1.Schema.replaceAll(schemas);
+    }
+    /**
+     *  Replaces a schema from the schema list.
+     * @throws {SchemaError} if desired schema name does not exist.
+     */
+    replaceSingleSchema(schema) {
+        Schema_1.Schema.replaceOne(schema);
+    }
+    /**
+     * Creates or returns an existing GAP client.
+     *
+     * _Use the constructor only if multiple clients are needed._
+     * @static
+     * @param {GAPArgs} args
+     * @returns
+     */
+    static createClient(args) {
+        if (!this.client)
+            this.client = new this(args);
+        return this.client;
+    }
+    /**
+     * Get the multicall contract
+     * @param signer
+     */
+    static getMulticall(signer) {
+        const address = consts_1.Networks[this.client.network].contracts.multicall;
+        return new ethers_1.ethers.Contract(address, MultiAttester_json_1.default, signer);
+    }
+    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.
+     */
+    static set gelatoOpts(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() {
+        return this._gelatoOpts;
+    }
+    static set useGasLess(useGasLess) {
+        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;
+    }
+}
+exports.GAP = GAP;
+GAP._gelatoOpts = null;

package/core/class/GapSchema.d.ts

@@ -0,0 +1,33 @@
+import { IGapSchema, SchemaInterface, TSchemaName } from "../types";
+import { Schema } from "./Schema";
+/**
+ * Represents the GapSchema
+ * @extends Schema
+ */
+export declare class GapSchema extends Schema implements IGapSchema {
+    readonly name: TSchemaName;
+    readonly references: TSchemaName;
+    constructor(args: SchemaInterface<TSchemaName>, strict?: boolean, ignoreSchema?: boolean);
+    /**
+     * Clones a schema without references to the original.
+     * @param schema
+     * @returns
+     */
+    static clone(schema: GapSchema): GapSchema;
+    /**
+     * Returns a copy of the original schema with no pointers.
+     * @param name
+     * @returns
+     */
+    static find(name: TSchemaName): GapSchema;
+    /**
+     * Find many schemas by name and return their copies as an array in the same order.
+     * @param names
+     * @returns
+     */
+    static findMany(names: TSchemaName[]): GapSchema[];
+    /**
+     * Get all schemas that references this schema.
+     */
+    get children(): GapSchema[];
+}

package/core/class/GapSchema.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GapSchema = void 0;
+const utils_1 = require("../utils");
+const Schema_1 = require("./Schema");
+/**
+ * Represents the GapSchema
+ * @extends Schema
+ */
+class GapSchema extends Schema_1.Schema {
+    constructor(args, strict = false, ignoreSchema = false) {
+        super(args, strict, ignoreSchema);
+        if (!ignoreSchema)
+            Schema_1.Schema.add(new GapSchema({
+                name: args.name,
+                schema: args.schema.map((s) => ({ ...s })),
+                uid: args.uid,
+                references: args.references,
+                revocable: args.revocable,
+            }, strict, true));
+    }
+    /**
+     * Clones a schema without references to the original.
+     * @param schema
+     * @returns
+     */
+    static clone(schema) {
+        return new GapSchema({
+            name: schema.name,
+            schema: schema.schema.map((s) => ({ ...s })),
+            uid: schema.uid,
+            references: schema.references,
+            revocable: schema.revocable,
+        }, false, true);
+    }
+    /**
+     * Returns a copy of the original schema with no pointers.
+     * @param name
+     * @returns
+     */
+    static find(name) {
+        const found = Schema_1.Schema.get(name);
+        return this.clone(found);
+    }
+    /**
+     * Find many schemas by name and return their copies as an array in the same order.
+     * @param names
+     * @returns
+     */
+    static findMany(names) {
+        const schemas = Schema_1.Schema.getMany(names);
+        return schemas.map((s) => this.clone(s));
+    }
+    /**
+     * Get all schemas that references this schema.
+     */
+    get children() {
+        return (0, utils_1.mapFilter)(GapSchema.schemas, (s) => s.references === this.name || s.references === this.uid, (s) => new GapSchema(s, false, true));
+    }
+}
+exports.GapSchema = GapSchema;