zkcloudworker 0.1.18 → 0.1.19

package/src/api/api.ts

@@ -0,0 +1,250 @@
+import axios from "axios";
+import { sleep } from "../mina";
+import config from "../config";
+const { ZKCLOUDWORKER_AUTH, ZKCLOUDWORKER_API } = config;
+
+/**
+ * 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 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) {
+    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
+   */
+  public async createJob(data: {
+    transactions: string[];
+    developer: string;
+    name: string;
+    task: string;
+    args: string[];
+    metadata?: string;
+  }): Promise<{
+    success: boolean;
+    error?: string;
+    jobId?: string;
+  }> {
+    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
+   */
+  public async jobResult(data: { jobId: string }): Promise<{
+    success: boolean;
+    error?: string;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    result?: any;
+  }> {
+    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 result of the job using serverless api call
+   * @param data the data for the deploy call
+   * @param data.packageName the name of the zip file with the code to be deployed
+   * @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
+   */
+  public async deploy(data: { packageName: string }): Promise<{
+    success: boolean;
+    error?: string;
+    jobId?: string;
+  }> {
+    const result = await this.apiHub("deploy", data);
+    if (result.data === "error")
+      return {
+        success: false,
+        error: result.error,
+      };
+    else
+      return {
+        success: result.success,
+        jobId: result.data,
+        error: result.error,
+      };
+  }
+
+  /**
+   * Gets the billing report for the jobs sent using JWT
+   * @returns { success: boolean, error?: string, result?: any }
+   * where result is the billing report
+   */
+  public async queryBilling(): Promise<{
+    success: boolean;
+    error?: string;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    result?: any;
+  }> {
+    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
+   */
+  public async waitForJobResult(data: {
+    jobId: string;
+    maxAttempts?: number;
+    interval?: number;
+    maxErrors?: number;
+  }): Promise<{
+    success: boolean;
+    error?: string;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    result?: any;
+  }> {
+    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 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 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
+   * */
+  private async apiHub(
+    command: string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    data: any
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ): Promise<{ success: boolean; data?: any; error?: any }> {
+    const apiData = {
+      auth: ZKCLOUDWORKER_AUTH,
+      command: command,
+      jwtToken: this.jwt,
+      data: data,
+    };
+
+    try {
+      const response = await axios.post(this.endpoint, apiData);
+      return { success: true, data: response.data };
+    } catch (error: any) {
+      console.error("apiHub error:", error.message ?? error);
+      return { success: false, error: error };
+    }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private isError(data: any): boolean {
+    if (data === "error") return true;
+    if (data?.jobStatus === "failed") return true;
+    if (typeof data === "string" && data.toLowerCase().startsWith("error"))
+      return true;
+    return false;
+  }
+}

package/src/api/client-api.ts

@@ -0,0 +1,186 @@
+/**
+ * Client API for calling the zkCloudWorker
+ */
+export {
+  TxnPayload,
+  IsError,
+  SerializedTxn,
+  SignedSerializedTxn,
+  TxnResult,
+  JobPayload,
+  JobResult,
+  zkCloudWorkerAPI,
+};
+
+interface TxnPayload {
+  data: object;
+  options?: object;
+}
+
+interface IsError {
+  code: number;
+  message: string;
+  exception: any;
+}
+
+interface SerializedTxn {
+  hash: string | null;
+  transaction: any | null;
+  error: IsError | null;
+}
+
+interface SignedSerializedTxn {
+  hash: string | null;
+  transaction: any | null;
+  error: IsError | null;
+}
+
+interface TxnResult {
+  hash: string | null;
+  data: any | null;
+  error: IsError | null;
+}
+
+interface JobPayload {
+  data: object;
+  options?: object;
+}
+
+interface JobResult {
+  data: any | null;
+  error: IsError | null;
+}
+
+class zkCloudWorkerAPI {
+  private API_KEY: string = "";
+
+  constructor(apiKey: string) {
+    this.API_KEY = apiKey;
+  }
+
+  /**
+   * prove() sign() and send()
+   *
+   * The called cloud worker is expected to compile the needed Contract,
+   * create the transaction, prove it and send it back serialized.
+   *
+   * Then the serialized transaction can be signed locally using AuroWallet
+   * and finally send it to MINA using the cloud worker.
+   *
+   * IMPORTANT: the transaction fee  will be paid by the local sender, using
+   * the Auro Wallet at the moment of signing the serialized transaction.
+   *
+   * We only need the sender public key to create and prove the transaction.
+   * The sender private key NEVER leaves the local wallet.
+   *
+   * Example:
+   * ~~~
+   *  let zkWorker = new ZKRunner(API_KEY);
+   *
+   *  let serializedTxn = await zkWorker.prove('batch-voting-...', {
+   *    data: {
+   *      claimUid: '012345...789',
+   *      // ...
+   *    },
+   *    options: {
+   *      senderAddress: 'B62...',
+   *      fee: MIN_FEE // MAX_FEE | AUTO_FEE | number
+   *    }
+   *  });
+   *  if (serializedTxn.error)
+   *    // treat error here
+   *
+   *  let signedTxn = await zkWorker.sign(signerAddress, serializedTxn);
+   *  if (signedTxn.error)
+   *    // treat error here
+   *
+   *  let txnResult = await zkWorker.send(signedTxn) ;
+   *  if (txnResult.error)
+   *    // treat error here
+   * ~~~
+   */
+  async prove(
+    jobName: string,
+    payload: TxnPayload //: Promise < SerializedTxn > {
+  ) {}
+
+  async sign(
+    signerAddress: string,
+    serializedTxn: SerializedTxn //: Promise<SignedSerializedTxn> {
+  ) {}
+
+  async send(
+    txn: SignedSerializedTxn //: Promise<TxnResult> {
+  ) {}
+
+  /**
+   * proveAndSend()
+   *
+   * The called cloud worker is expected to do all: compile the needed Contract,
+   * create the transaction, prove it, sign it using one of the available
+   * fee payers, and finally send it to MINA.
+   *
+   * IMPORTANT: the transaction fee  will be paid by the first fee payer
+   * available from the list of fee payers provided by the ZKRunner service.
+   * Also the fee will be set by the cloud worker using some optimal algorithm
+   * that minimizes fees.
+   *
+   * In this case the sender public key to create and prove the transaction
+   * will be the selected ZKRunner fee payer previously mentioned.
+   *
+   * Example:
+   * ~~~
+   *  let zkWorker = new ZKRunner(API_KEY);
+   *
+   *  let txnResult = await zkWorker.proveAndSend('batch-voting-...', {
+   *    data: {
+   *      claimUid: '012345...789',
+   *      // ...
+   *    }
+   *  });
+   *
+   *  if (txnResult.error)
+   *    // treat error here
+   * ~~~
+   */
+  async proveAndSend(
+    jobName: string,
+    payload: TxnPayload //: Promise<TxnResult> {
+  ) {}
+
+  /**
+   * runJob()
+   *
+   * The called cloud worker can also be used to easily run jobs not related to
+   * a MINA transaction, and will act just like any serverless function.
+   *
+   * This "generic" job can benefit from the easy to use deploy and call service
+   * already implemented for cloud proving without no extra costs.
+   *
+   * IMPORTANT: there will be a small fee that needs to be paid for service usage,
+   * but no MINA fees need to be paid.
+   *
+   * Example:
+   * ~~~
+   *  let zkWorker = new ZKRunner(API_KEY);
+   *
+   *  let jobResult = await zkWorker.runJob('send-email-to-judges', {
+   *    data: {
+   *      judges: [
+   *        // ...
+   *      ],
+   *    },
+   *    options: {
+   *      // ...
+   *    }
+   *  });
+   *
+   *  if (txnResult.error)
+   *    // treat error here
+   * ~~~
+   */
+  async runJob(
+    jobName: string,
+    payload: JobPayload //: Promise<JobResult> {
+  ) {}
+}

package/src/cloud/cloud.ts

@@ -0,0 +1,22 @@
+import { Cache, PrivateKey } from "o1js";
+
+export abstract class Cloud {
+  cache: Cache;
+  constructor(cache: Cache) {
+    this.cache = cache;
+  }
+  // TODO: change it to the sign method to protect the private key
+  abstract getDeployer(): Promise<PrivateKey>;
+  abstract log(msg: string): void;
+
+  /* TODO: add more methods 
+      -getDataByKey
+      -saveDataByKey
+      -saveFile
+      -loadFile 
+  */
+  abstract getDataByKey(key: string): Promise<string | undefined>;
+  abstract saveDataByKey(key: string, value: string): Promise<void>;
+  abstract saveFile(filename: string, value: Buffer): Promise<void>;
+  abstract loadFile(filename: string): Promise<Buffer | undefined>;
+}

package/src/cloud/local.ts

@@ -0,0 +1,34 @@
+import { Cache, PrivateKey } from "o1js";
+import { Cloud } from "./cloud";
+
+export class LocalCloud extends Cloud {
+  cache: Cache;
+  data: Map<string, string> = new Map<string, string>();
+
+  constructor() {
+    const cache = Cache.FileSystem("./cache");
+    super(cache);
+  }
+  public async getDeployer(): Promise<PrivateKey> {
+    throw new Error("Method not implemented.");
+  }
+  public async log(msg: string): Promise<void> {
+    console.log("LocalCloud:", msg);
+  }
+
+  public async getDataByKey(key: string): Promise<string | undefined> {
+    const value = this.data.get(key);
+    return value;
+  }
+
+  public async saveDataByKey(key: string, value: string): Promise<void> {
+    this.data.set(key, value);
+  }
+
+  public async saveFile(filename: string, value: Buffer): Promise<void> {
+    throw new Error("Method not implemented.");
+  }
+  public async loadFile(filename: string): Promise<Buffer | undefined> {
+    throw new Error("Method not implemented.");
+  }
+}

package/src/config.ts

@@ -0,0 +1,9 @@
+const config = {
+  MINAFEE: "200000000",
+  ZKCLOUDWORKER_AUTH:
+    "M6t4jtbBAFFXhLERHQWyEB9JA9xi4cWqmYduaCXtbrFjb7yaY7TyaXDunKDJNiUTBEcyUomNXJgC",
+  ZKCLOUDWORKER_API:
+    "https://cuq99yahhi.execute-api.eu-west-1.amazonaws.com/dev/zkcloudworker",
+};
+
+export default config;

package/src/custom/backend.ts

@@ -0,0 +1,30 @@
+export { BackendPlugin };
+import type { Cache } from "o1js";
+
+abstract class BackendPlugin {
+  name: string;
+  task: string;
+  args: string[];
+  jobId?: string;
+
+  constructor(params: {
+    name: string;
+    task: string;
+    args: string[];
+    jobId?: string;
+  }) {
+    const { name, task, args, jobId } = params;
+    this.name = name;
+    this.task = task;
+    this.args = args;
+    this.jobId = jobId;
+  }
+
+  abstract compile(cache: Cache): Promise<void>;
+  abstract create(transaction: string): Promise<string | undefined>;
+  abstract merge(proof1: string, proof2: string): Promise<string | undefined>;
+
+  abstract send(transaction: string): Promise<string | undefined>;
+  abstract mint(transaction: string): Promise<string | undefined>;
+  abstract verify(proof: string): Promise<string | undefined>;
+}

package/src/fee.ts

@@ -0,0 +1,7 @@
+import { UInt64 } from "o1js";
+import config from "./config";
+
+export async function fee(): Promise<UInt64> {
+  //TODO: update after mainnet launch
+  return UInt64.fromJSON(config.MINAFEE);
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+export { zkCloudWorker } from "./api/api";
+export { Cloud } from "./cloud/cloud";
+export { LocalCloud } from "./cloud/local";
+export {
+  initBlockchain,
+  Memory,
+  makeString,
+  sleep,
+  accountBalance,
+  accountBalanceMina,
+  formatTime,
+  MinaNetworkInstance,
+  currentNetwork,
+  getNetworkIdHash,
+} from "./mina";
+export { fee } from "./fee";
+export {
+  blockchain,
+  MinaNetwork,
+  networks,
+  Mainnet,
+  Berkeley,
+  Zeko,
+  TestWorld2,
+  Lightnet,
+  Local,
+} from "./networks";
+export {
+  TxnPayload,
+  IsError,
+  SerializedTxn,
+  SignedSerializedTxn,
+  TxnResult,
+  JobPayload,
+  JobResult,
+  zkCloudWorkerAPI,
+} from "./api/client-api";
+export { BackendPlugin } from "./custom/backend";