zkcloudworker 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# zkCloudWorker library
+
+In the fast-paced realm of ZK proving, zkCloudWorker stands out as a potential game-changer for both zkApp developers and users.
+
+By delivering ultra-fast proving in the cloud, along with robust isolation, composability, and an excellent user experience (UX), zkCloudWorker has the potential to significantly streamline and expedite the development of MINA zkApps both on web and mobile devices.
+
+Instead of downloading 1 GB of proving keys, compiling, and performing proofs on a web or mobile worker, a simple API call can be made to the powerful zkCloudWorker to launch a worker in the cloud. This offers ample memory, CPU power, and parallel processing capabilities for recursive proof calculations.
+
+Privacy is maintained through the isolation of processes, encryption of all data, and the ability to process private data on the web using technologies like hashing and Merkle Tree calculations. Preprocessed data is then sent to the cloud worker.
+
+This opens doors for a diverse range of Web2 developers to seamlessly enter the exciting world of the MINA protocol and o1js.
+
+## Features
+
+- Compiling the contract in the cloud.
+
+- Calculating transactions proofs tx.prove().
+
+- Calculating recursive proofs.
+
+- Sending transactions to network.
+
+- Verifying proofs.
+
+- Providing deployers to pay the tx fee.
+
+- API to be accessed inside the zkCloudWorker.
+
+- API to be accessed inside the web application.
+
+- Billing panel to show the cost of the running zkCloudWorkers to the developer.
+
+- Web dashboard to easily deploy and access deployed zkCloudWorkers and their logs.
+
+- Providing key-value off-chain storage for zkApps, up to 400K size for values.
+
+- Providing file storage for zkApps, unlimited size.
+
+- Encryption utilities for sending and storing the data in the encrypted form.
+
+- Verifying the text of the contracts for uploading to the minascan.io explorer.
+
+- Providing additional metadata for the transactions, including custom metadata defined by the developer and the conversion of the actions and events to the human-readable form as defined by the developer for publishing on the minascan.io explorer.
+
+- Code templates and question-answer sets for the zkApp Umstad AI Chatbot.
+
+- The CLI tool to deploy the code to the cloud and verify the code on the minascan.io.
+
+- Availability of the zkCloudWorker for SmartContract, ZkProgram and general calculations, including running ProtoKit chains in case ProtoKit will support running on the serverless infrastructure, that is possible in principle.
+
+- Custom integration of the zkApps for the cases that do not fit in the standard framework for some reason.
+
+## Installation
+
+```
+yarn add zkcloudworker
+```
+
+## Documentation
+
+https://docs.zkcloudworker.com
+
+## Website
+
+https://zkcloudworker.com
+
+## Library on NPM
+
+https://www.npmjs.com/package/zkcloudworker
+
+## Homomorphic Encryption Example
+
+https://github.com/dfstio/he-contract-demo
+
+## Faucet
+
+https://faucet.minaprotocol.com
+
+https://minanft.io/faucet

package/lib/ts/src/api/api.d.ts

@@ -0,0 +1,93 @@
+/**
+ * API class for interacting with the zkCloudWorker
+ * @property jwt The jwt token for authentication, get it at https://t.me/minanft_bot?start=auth
+ * @property endpoint The endpoint of the serverless api
+ */
+export declare class zkCloudWorker {
+    jwt: string;
+    endpoint: string;
+    /**
+     * Constructor for the API class
+     * @param jwt The jwt token for authentication, get it at https://t.me/minanft_bot?start=auth
+     */
+    constructor(jwt: string);
+    /**
+     * Starts a new job for the proof calculation using serverless api call
+     * The developer and name should correspond to the BackupPlugin of the API
+     * All other parameters should correspond to the parameters of the BackupPlugin
+     * @param data the data for the proof call
+     * @param data.transactions the transactions
+     * @param data.developer the developer
+     * @param data.name the name of the job
+     * @param data.task the task of the job
+     * @param data.args the arguments of the job
+     * @returns { success: boolean, error?: string, jobId?: string }
+     * where jonId is the jobId of the job
+     */
+    createJob(data: {
+        transactions: string[];
+        developer: string;
+        name: string;
+        task: string;
+        args: string[];
+    }): Promise<{
+        success: boolean;
+        error?: string;
+        jobId?: string;
+    }>;
+    /**
+     * Gets the result of the job using serverless api call
+     * @param data the data for the jobResult call
+     * @param data.jobId the jobId of the job
+     * @returns { success: boolean, error?: string, result?: any }
+     * where result is the result of the job
+     * if the job is not finished yet, the result will be undefined
+     * if the job failed, the result will be undefined and error will be set
+     * if the job is finished, the result will be set and error will be undefined
+     * if the job is not found, the result will be undefined and error will be set
+     */
+    jobResult(data: {
+        jobId: string;
+    }): Promise<{
+        success: boolean;
+        error?: string;
+        result?: any;
+    }>;
+    /**
+     * Gets the billing report for the jobs sent using JWT
+     * @returns { success: boolean, error?: string, result?: any }
+     * where result is the billing report
+     */
+    queryBilling(): Promise<{
+        success: boolean;
+        error?: string;
+        result?: any;
+    }>;
+    /**
+     * Waits for the job to finish
+     * @param data the data for the waitForJobResult call
+     * @param data.jobId the jobId of the job
+     * @param data.maxAttempts the maximum number of attempts, default is 360 (2 hours)
+     * @param data.interval the interval between attempts, default is 20000 (20 seconds)
+     * @param data.maxErrors the maximum number of network errors, default is 10
+     * @returns { success: boolean, error?: string, result?: any }
+     * where result is the result of the job
+     */
+    waitForJobResult(data: {
+        jobId: string;
+        maxAttempts?: number;
+        interval?: number;
+        maxErrors?: number;
+    }): Promise<{
+        success: boolean;
+        error?: string;
+        result?: any;
+    }>;
+    /**
+     * Calls the serverless API
+     * @param command the command of the API
+     * @param data the data of the API
+     * */
+    private apiHub;
+    private isError;
+}

package/lib/ts/src/api/api.js

@@ -0,0 +1,188 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zkCloudWorker = void 0;
+const axios_1 = __importDefault(require("axios"));
+const mina_1 = require("../mina");
+const config_1 = __importDefault(require("../config"));
+const { ZKCLOUDWORKER_AUTH, ZKCLOUDWORKER_API } = config_1.default;
+/**
+ * API class for interacting with the zkCloudWorker
+ * @property jwt The jwt token for authentication, get it at https://t.me/minanft_bot?start=auth
+ * @property endpoint The endpoint of the serverless api
+ */
+class zkCloudWorker {
+    /**
+     * Constructor for the API class
+     * @param jwt The jwt token for authentication, get it at https://t.me/minanft_bot?start=auth
+     */
+    constructor(jwt) {
+        this.jwt = jwt;
+        this.endpoint = ZKCLOUDWORKER_API;
+    }
+    /**
+     * Starts a new job for the proof calculation using serverless api call
+     * The developer and name should correspond to the BackupPlugin of the API
+     * All other parameters should correspond to the parameters of the BackupPlugin
+     * @param data the data for the proof call
+     * @param data.transactions the transactions
+     * @param data.developer the developer
+     * @param data.name the name of the job
+     * @param data.task the task of the job
+     * @param data.args the arguments of the job
+     * @returns { success: boolean, error?: string, jobId?: string }
+     * where jonId is the jobId of the job
+     */
+    async createJob(data) {
+        const result = await this.apiHub("createJob", data);
+        if (result.data === "error")
+            return {
+                success: false,
+                error: result.error,
+            };
+        else
+            return {
+                success: result.success,
+                jobId: result.data,
+                error: result.error,
+            };
+    }
+    /**
+     * Gets the result of the job using serverless api call
+     * @param data the data for the jobResult call
+     * @param data.jobId the jobId of the job
+     * @returns { success: boolean, error?: string, result?: any }
+     * where result is the result of the job
+     * if the job is not finished yet, the result will be undefined
+     * if the job failed, the result will be undefined and error will be set
+     * if the job is finished, the result will be set and error will be undefined
+     * if the job is not found, the result will be undefined and error will be set
+     */
+    async jobResult(data) {
+        const result = await this.apiHub("jobResult", data);
+        if (this.isError(result.data))
+            return {
+                success: false,
+                error: result.error,
+                result: result.data,
+            };
+        else
+            return {
+                success: result.success,
+                error: result.error,
+                result: result.data,
+            };
+    }
+    /**
+     * Gets the billing report for the jobs sent using JWT
+     * @returns { success: boolean, error?: string, result?: any }
+     * where result is the billing report
+     */
+    async queryBilling() {
+        const result = await this.apiHub("queryBilling", {});
+        if (this.isError(result.data))
+            return {
+                success: false,
+                error: result.error,
+                result: result.data,
+            };
+        else
+            return {
+                success: result.success,
+                error: result.error,
+                result: result.data,
+            };
+    }
+    /**
+     * Waits for the job to finish
+     * @param data the data for the waitForJobResult call
+     * @param data.jobId the jobId of the job
+     * @param data.maxAttempts the maximum number of attempts, default is 360 (2 hours)
+     * @param data.interval the interval between attempts, default is 20000 (20 seconds)
+     * @param data.maxErrors the maximum number of network errors, default is 10
+     * @returns { success: boolean, error?: string, result?: any }
+     * where result is the result of the job
+     */
+    async waitForJobResult(data) {
+        const maxAttempts = data?.maxAttempts ?? 360; // 2 hours
+        const interval = data?.interval ?? 20000;
+        const maxErrors = data?.maxErrors ?? 10;
+        const errorDelay = 30000; // 30 seconds
+        let attempts = 0;
+        let errors = 0;
+        while (attempts < maxAttempts) {
+            const result = await this.apiHub("jobResult", data);
+            if (result.success === false) {
+                errors++;
+                if (errors > maxErrors) {
+                    return {
+                        success: false,
+                        error: "Too many network errors",
+                        result: undefined,
+                    };
+                }
+                await (0, mina_1.sleep)(errorDelay * errors);
+            }
+            else {
+                if (this.isError(result.data))
+                    return {
+                        success: false,
+                        error: result.error,
+                        result: result.data,
+                    };
+                else if (result.data?.result !== undefined) {
+                    return {
+                        success: result.success,
+                        error: result.error,
+                        result: result.data,
+                    };
+                }
+                await (0, mina_1.sleep)(interval);
+            }
+            attempts++;
+        }
+        return {
+            success: false,
+            error: "Timeout",
+            result: undefined,
+        };
+    }
+    /**
+     * Calls the serverless API
+     * @param command the command of the API
+     * @param data the data of the API
+     * */
+    async apiHub(command, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    data
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ) {
+        const apiData = {
+            auth: ZKCLOUDWORKER_AUTH,
+            command: command,
+            jwtToken: this.jwt,
+            data: data,
+        };
+        try {
+            const response = await axios_1.default.post(this.endpoint, apiData);
+            return { success: true, data: response.data };
+        }
+        catch (error) {
+            console.error("catch api", error);
+            return { success: false, error: error };
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    isError(data) {
+        if (data === "error")
+            return true;
+        if (data?.jobStatus === "failed")
+            return true;
+        if (typeof data === "string" && data.toLowerCase().startsWith("error"))
+            return true;
+        return false;
+    }
+}
+exports.zkCloudWorker = zkCloudWorker;

package/lib/ts/src/cloud/cloud.d.ts

@@ -0,0 +1,7 @@
+import { Cache, PrivateKey } from "o1js";
+export declare abstract class Cloud {
+    cache: Cache;
+    constructor(cache: Cache);
+    abstract getDeployer(): Promise<PrivateKey>;
+    abstract log(msg: string): void;
+}

package/lib/ts/src/cloud/cloud.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cloud = void 0;
+class Cloud {
+    constructor(cache) {
+        this.cache = cache;
+    }
+}
+exports.Cloud = Cloud;

package/lib/ts/src/config.d.ts

@@ -0,0 +1,6 @@
+declare const config: {
+    MINAFEE: string;
+    ZKCLOUDWORKER_AUTH: string;
+    ZKCLOUDWORKER_API: string;
+};
+export default config;

package/lib/ts/src/config.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const config = {
+    MINAFEE: "200000000",
+    ZKCLOUDWORKER_AUTH: "AkRjS8yioA7i1CwvB3nOvcyLYh6sNMi4em7C0ybmYy67lhDC2KxEQtm1z45llEAR",
+    ZKCLOUDWORKER_API: "https://n1zjzclr99.execute-api.eu-west-1.amazonaws.com/dev/api",
+};
+exports.default = config;

package/lib/ts/src/fee.d.ts

@@ -0,0 +1,2 @@
+import { UInt64 } from "o1js";
+export declare function fee(): Promise<UInt64>;

package/lib/ts/src/fee.js

@@ -0,0 +1,13 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fee = void 0;
+const o1js_1 = require("o1js");
+const config_1 = __importDefault(require("./config"));
+async function fee() {
+    //TODO: update after mainnet launch
+    return o1js_1.UInt64.fromJSON(config_1.default.MINAFEE);
+}
+exports.fee = fee;

package/lib/ts/src/index.d.ts

@@ -0,0 +1,5 @@
+export { zkCloudWorker } from "./api/api";
+export { Cloud } from "./cloud/cloud";
+export { blockchain, initBlockchain, Memory, makeString, sleep, accountBalance, accountBalanceMina, formatTime, MinaNetwork, } from "./mina";
+export { fee } from "./fee";
+export { MinaNetworkURL, Berkeley, Lightnet, TestWorld2 } from "./networks";

package/lib/ts/src/index.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestWorld2 = exports.Lightnet = exports.Berkeley = exports.fee = exports.formatTime = exports.accountBalanceMina = exports.accountBalance = exports.sleep = exports.makeString = exports.Memory = exports.initBlockchain = exports.Cloud = exports.zkCloudWorker = void 0;
+var api_1 = require("./api/api");
+Object.defineProperty(exports, "zkCloudWorker", { enumerable: true, get: function () { return api_1.zkCloudWorker; } });
+var cloud_1 = require("./cloud/cloud");
+Object.defineProperty(exports, "Cloud", { enumerable: true, get: function () { return cloud_1.Cloud; } });
+var mina_1 = require("./mina");
+Object.defineProperty(exports, "initBlockchain", { enumerable: true, get: function () { return mina_1.initBlockchain; } });
+Object.defineProperty(exports, "Memory", { enumerable: true, get: function () { return mina_1.Memory; } });
+Object.defineProperty(exports, "makeString", { enumerable: true, get: function () { return mina_1.makeString; } });
+Object.defineProperty(exports, "sleep", { enumerable: true, get: function () { return mina_1.sleep; } });
+Object.defineProperty(exports, "accountBalance", { enumerable: true, get: function () { return mina_1.accountBalance; } });
+Object.defineProperty(exports, "accountBalanceMina", { enumerable: true, get: function () { return mina_1.accountBalanceMina; } });
+Object.defineProperty(exports, "formatTime", { enumerable: true, get: function () { return mina_1.formatTime; } });
+var fee_1 = require("./fee");
+Object.defineProperty(exports, "fee", { enumerable: true, get: function () { return fee_1.fee; } });
+var networks_1 = require("./networks");
+Object.defineProperty(exports, "Berkeley", { enumerable: true, get: function () { return networks_1.Berkeley; } });
+Object.defineProperty(exports, "Lightnet", { enumerable: true, get: function () { return networks_1.Lightnet; } });
+Object.defineProperty(exports, "TestWorld2", { enumerable: true, get: function () { return networks_1.TestWorld2; } });

package/lib/ts/src/mina.d.ts

@@ -0,0 +1,22 @@
+export { blockchain, initBlockchain, Memory, makeString, sleep, accountBalance, accountBalanceMina, formatTime, MinaNetwork, };
+import { PublicKey, PrivateKey, UInt64 } from "o1js";
+import { MinaNetworkURL } from "./networks";
+type blockchain = "local" | "berkeley" | "lighnet" | "mainnet" | "testworld2";
+interface MinaNetwork {
+    keys: {
+        publicKey: PublicKey;
+        privateKey: PrivateKey;
+    }[];
+    url?: MinaNetworkURL;
+}
+declare function initBlockchain(instance: blockchain): MinaNetwork;
+declare function accountBalance(address: PublicKey): Promise<UInt64>;
+declare function accountBalanceMina(address: PublicKey): Promise<number>;
+declare function sleep(ms: number): Promise<unknown>;
+declare function makeString(length: number): string;
+declare function formatTime(ms: number): string;
+declare class Memory {
+    static rss: number;
+    constructor();
+    static info(description?: string, fullInfo?: boolean): void;
+}

package/lib/ts/src/mina.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatTime = exports.accountBalanceMina = exports.accountBalance = exports.sleep = exports.makeString = exports.Memory = exports.initBlockchain = void 0;
+const o1js_1 = require("o1js");
+const networks_1 = require("./networks");
+function initBlockchain(instance) {
+    if (instance === "local") {
+        const Local = o1js_1.Mina.LocalBlockchain({ proofsEnabled: true });
+        o1js_1.Mina.setActiveInstance(Local);
+        return { keys: Local.testAccounts };
+    }
+    else if (instance === "berkeley") {
+        const network = o1js_1.Mina.Network({
+            mina: networks_1.Berkeley.graphql,
+            archive: networks_1.Berkeley.archive,
+        });
+        o1js_1.Mina.setActiveInstance(network);
+        return { keys: [], url: networks_1.Berkeley };
+    }
+    else if (instance === "testworld2") {
+        const network = o1js_1.Mina.Network({
+            mina: networks_1.TestWorld2.graphql,
+            archive: networks_1.TestWorld2.archive,
+        });
+        o1js_1.Mina.setActiveInstance(network);
+        return { keys: [], url: networks_1.TestWorld2 };
+    }
+    else if (instance === "lighnet") {
+        const network = o1js_1.Mina.Network({
+            mina: networks_1.Lightnet.graphql,
+            archive: networks_1.Lightnet.archive,
+            lightnetAccountManager: networks_1.Lightnet.accountManager,
+        });
+        o1js_1.Mina.setActiveInstance(network);
+        return { keys: [], url: networks_1.Lightnet };
+    }
+    else {
+        throw new Error("Mainnet is not supported yet by zkApps");
+    }
+}
+exports.initBlockchain = initBlockchain;
+async function accountBalance(address) {
+    await (0, o1js_1.fetchAccount)({ publicKey: address });
+    if (o1js_1.Mina.hasAccount(address))
+        return o1js_1.Mina.getBalance(address);
+    else
+        return o1js_1.UInt64.from(0);
+}
+exports.accountBalance = accountBalance;
+async function accountBalanceMina(address) {
+    return Number((await accountBalance(address)).toBigInt()) / 1e9;
+}
+exports.accountBalanceMina = accountBalanceMina;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+exports.sleep = sleep;
+function makeString(length) {
+    // eslint-disable-next-line @typescript-eslint/no-inferrable-types
+    let outString = ``;
+    // eslint-disable-next-line @typescript-eslint/no-inferrable-types
+    const inOptions = `abcdefghijklmnopqrstuvwxyz0123456789`;
+    for (let i = 0; i < length; i++) {
+        outString += inOptions.charAt(Math.floor(Math.random() * inOptions.length));
+    }
+    return outString;
+}
+exports.makeString = makeString;
+function formatTime(ms) {
+    if (ms === undefined)
+        return "";
+    if (ms < 1000)
+        return ms.toString() + " ms";
+    if (ms < 60 * 1000)
+        return parseInt((ms / 1000).toString()).toString() + " sec";
+    if (ms < 60 * 60 * 1000)
+        return parseInt((ms / 1000 / 60).toString()).toString() + " min";
+    return parseInt((ms / 1000 / 60 / 60).toString()).toString() + " h";
+}
+exports.formatTime = formatTime;
+class Memory {
+    constructor() {
+        Memory.rss = 0;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-inferrable-types
+    static info(description = ``, fullInfo = false) {
+        const memoryData = process.memoryUsage();
+        const formatMemoryUsage = (data) => `${Math.round(data / 1024 / 1024)} MB`;
+        const oldRSS = Memory.rss;
+        Memory.rss = Math.round(memoryData.rss / 1024 / 1024);
+        const memoryUsage = fullInfo
+            ? {
+                step: `${description}:`,
+                rssDelta: `${(oldRSS === 0
+                    ? 0
+                    : Memory.rss - oldRSS).toString()} MB -> Resident Set Size memory change`,
+                rss: `${formatMemoryUsage(memoryData.rss)} -> Resident Set Size - total memory allocated`,
+                heapTotal: `${formatMemoryUsage(memoryData.heapTotal)} -> total size of the allocated heap`,
+                heapUsed: `${formatMemoryUsage(memoryData.heapUsed)} -> actual memory used during the execution`,
+                external: `${formatMemoryUsage(memoryData.external)} -> V8 external memory`,
+            }
+            : `RSS memory ${description}: ${formatMemoryUsage(memoryData.rss)}${oldRSS === 0
+                ? ``
+                : `, changed by ` + (Memory.rss - oldRSS).toString() + ` MB`}`;
+        console.log(memoryUsage);
+    }
+}
+exports.Memory = Memory;
+// eslint-disable-next-line @typescript-eslint/no-inferrable-types
+Memory.rss = 0;

package/lib/ts/src/networks.d.ts

@@ -0,0 +1,13 @@
+export { MinaNetworkURL, Berkeley, Lightnet, TestWorld2 };
+interface MinaNetworkURL {
+    graphql: string;
+    archive: string;
+    chainId?: string;
+    name?: string;
+    accountManager?: string;
+    explorerAccountUrl?: string;
+    explorerTransactionUrl?: string;
+}
+declare const Berkeley: MinaNetworkURL;
+declare const TestWorld2: MinaNetworkURL;
+declare const Lightnet: MinaNetworkURL;

package/lib/ts/src/networks.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestWorld2 = exports.Lightnet = exports.Berkeley = void 0;
+const Berkeley = {
+    graphql: "https://api.minascan.io/node/berkeley/v1/graphql",
+    archive: "https://api.minascan.io/archive/berkeley/v1/graphql", // "https://api.minascan.io/archive/berkeley/v1/graphql"
+    explorerAccountUrl: "https://minascan.io/berkeley/account/",
+    explorerTransactionUrl: "https://minascan.io/berkeley/tx/",
+    chainId: 'berkeley',
+    name: 'Berkeley'
+};
+exports.Berkeley = Berkeley;
+const TestWorld2 = {
+    graphql: "https://api.minascan.io/node/testworld/v1/graphql",
+    archive: "https://archive.testworld.minaexplorer.com",
+    explorerAccountUrl: "https://minascan.io/testworld/account/",
+    explorerTransactionUrl: "https://minascan.io/testworld/tx/",
+    chainId: 'testworld2',
+    name: 'TestWorld2'
+};
+exports.TestWorld2 = TestWorld2;
+const Lightnet = {
+    graphql: "http://localhost:8080/graphql",
+    archive: "http://localhost:8282 ",
+    accountManager: "http://localhost:8181",
+};
+exports.Lightnet = Lightnet;