zkcloudworker 0.1.17 → 0.1.19

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";

package/src/mina.ts

@@ -0,0 +1,230 @@
+export {
+  initBlockchain,
+  Memory,
+  makeString,
+  sleep,
+  accountBalance,
+  accountBalanceMina,
+  formatTime,
+  MinaNetworkInstance,
+  currentNetwork,
+  getNetworkIdHash,
+};
+
+import {
+  Mina,
+  PublicKey,
+  PrivateKey,
+  UInt64,
+  fetchAccount,
+  Field,
+  CircuitString,
+} from "o1js";
+import { networks, blockchain, MinaNetwork, Local } from "./networks";
+
+interface MinaNetworkInstance {
+  keys: {
+    publicKey: PublicKey;
+    privateKey: PrivateKey;
+  }[];
+  network: MinaNetwork;
+  networkIdHash: Field;
+}
+
+let currentNetwork: MinaNetworkInstance | undefined = undefined;
+
+function getNetworkIdHash(): Field {
+  if (currentNetwork === undefined) {
+    throw new Error("Network is not initialized");
+  }
+  return currentNetwork.networkIdHash;
+}
+
+/*function getNetworkIdHash(params: {
+  chainId?: blockchain;
+  verbose?: boolean;
+}): Field {
+  const { chainId, verbose } = params;
+  if (chainId !== undefined) {
+    if (verbose) console.log(`Chain ID: ${chainId}`);
+    return CircuitString.fromString(chainId).hash();
+  }
+  const networkId = Mina.getNetworkId();
+  if (verbose) console.log(`Network ID: ${networkId}`);
+  if (networkId === "testnet")
+    throw new Error(
+      "Network ID is not set, please call initBlockchain() first"
+    );
+
+  if (networkId === "mainnet")
+    return CircuitString.fromString("mainnet").hash();
+  else {
+    if (
+      networkId.custom === undefined ||
+      typeof networkId.custom !== "string"
+    ) {
+      throw new Error(
+        "Network ID is not set, please call initBlockchain() first"
+      );
+    }
+    return CircuitString.fromString(networkId.custom).hash();
+  }
+}
+*/
+
+function initBlockchain(
+  instance: blockchain,
+  deployersNumber: number = 0
+): MinaNetworkInstance {
+  if (instance === "mainnet") {
+    throw new Error("Mainnet is not supported yet by zkApps");
+  }
+
+  if (instance === "local") {
+    const local = Mina.LocalBlockchain({
+      proofsEnabled: true,
+    });
+    Mina.setActiveInstance(local);
+    currentNetwork = {
+      keys: local.testAccounts,
+      network: Local,
+      networkIdHash: CircuitString.fromString("local").hash(),
+    };
+    return currentNetwork;
+  }
+
+  const network = networks.find((n) => n.chainId === instance);
+  if (network === undefined) {
+    throw new Error("Unknown network");
+  }
+
+  const networkInstance = Mina.Network({
+    mina: network.mina,
+    archive: network.archive,
+    lightnetAccountManager: network.accountManager,
+  });
+  Mina.setActiveInstance(networkInstance);
+
+  const keys: {
+    publicKey: PublicKey;
+    privateKey: PrivateKey;
+  }[] = [];
+
+  if (deployersNumber > 0) {
+    if (instance === "lighnet") {
+      throw new Error(
+        "Use await Lightnet.acquireKeyPair() to get keys for Lightnet"
+      );
+    } else {
+      const deployers = process.env.DEPLOYERS;
+      if (
+        deployers === undefined ||
+        Array.isArray(deployers) === false ||
+        deployers.length < deployersNumber
+      )
+        throw new Error("Deployers are not set");
+      for (let i = 0; i < deployersNumber; i++) {
+        const privateKey = PrivateKey.fromBase58(deployers[i]);
+        const publicKey = privateKey.toPublicKey();
+        keys.push({ publicKey, privateKey });
+      }
+    }
+  }
+
+  currentNetwork = {
+    keys,
+    network,
+    networkIdHash: CircuitString.fromString(instance).hash(),
+  };
+  return currentNetwork;
+}
+
+async function accountBalance(address: PublicKey): Promise<UInt64> {
+  await fetchAccount({ publicKey: address });
+  if (Mina.hasAccount(address)) return Mina.getBalance(address);
+  else return UInt64.from(0);
+}
+
+async function accountBalanceMina(address: PublicKey): Promise<number> {
+  return Number((await accountBalance(address)).toBigInt()) / 1e9;
+}
+
+function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function makeString(length: number): string {
+  // eslint-disable-next-line @typescript-eslint/no-inferrable-types
+  let outString: string = ``;
+  // eslint-disable-next-line @typescript-eslint/no-inferrable-types
+  const inOptions: string = `abcdefghijklmnopqrstuvwxyz0123456789`;
+
+  for (let i = 0; i < length; i++) {
+    outString += inOptions.charAt(Math.floor(Math.random() * inOptions.length));
+  }
+
+  return outString;
+}
+
+function formatTime(ms: number): string {
+  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) {
+    const minutes = parseInt((ms / 1000 / 60).toString());
+    const seconds = parseInt(((ms - minutes * 60 * 1000) / 1000).toString());
+    return minutes.toString() + " min " + seconds.toString() + " sec";
+  } else {
+    const hours = parseInt((ms / 1000 / 60 / 60).toString());
+    const minutes = parseInt(
+      ((ms - hours * 60 * 60 * 1000) / 1000 / 60).toString()
+    );
+    return hours.toString() + " h " + minutes.toString() + " min";
+  }
+}
+
+class Memory {
+  // eslint-disable-next-line @typescript-eslint/no-inferrable-types
+  static rss: number = 0;
+  constructor() {
+    Memory.rss = 0;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-inferrable-types
+  public static info(description: string = ``, fullInfo: boolean = false) {
+    const memoryData = process.memoryUsage();
+    const formatMemoryUsage = (data: number) =>
+      `${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);
+  }
+}

package/src/networks.ts

@@ -0,0 +1,88 @@
+export {
+  blockchain,
+  MinaNetwork,
+  networks,
+  Mainnet,
+  Berkeley,
+  Zeko,
+  TestWorld2,
+  Lightnet,
+  Local,
+};
+
+type blockchain =
+  | "local"
+  | "berkeley"
+  | "lighnet"
+  | "mainnet"
+  | "testworld2"
+  | "zeko";
+
+interface MinaNetwork {
+  mina: string[];
+  archive: string[];
+  chainId: blockchain;
+  name?: string;
+  accountManager?: string;
+  explorerAccountUrl?: string;
+  explorerTransactionUrl?: string;
+}
+
+const Mainnet: MinaNetwork = {
+  mina: [],
+  archive: [],
+  chainId: "mainnet",
+};
+
+const Local: MinaNetwork = {
+  mina: [],
+  archive: [],
+  chainId: "local",
+};
+
+const Berkeley: MinaNetwork = {
+  mina: [
+    "https://api.minascan.io/node/berkeley/v1/graphql",
+    "https://proxy.berkeley.minaexplorer.com/graphql",
+  ],
+  archive: [
+    "https://api.minascan.io/archive/berkeley/v1/graphql",
+    "https://archive.berkeley.minaexplorer.com",
+  ],
+  explorerAccountUrl: "https://minascan.io/berkeley/account/",
+  explorerTransactionUrl: "https://minascan.io/berkeley/tx/",
+  chainId: "berkeley",
+  name: "Berkeley",
+};
+
+const Zeko: MinaNetwork = {
+  mina: ["http://sequencer-zeko-dev.dcspark.io/graphql"],
+  archive: [],
+  chainId: "zeko",
+};
+
+const TestWorld2: MinaNetwork = {
+  mina: ["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",
+};
+
+const Lightnet: MinaNetwork = {
+  mina: ["http://localhost:8080/graphql"],
+  archive: ["http://localhost:8282"],
+  accountManager: "http://localhost:8181",
+  chainId: "lighnet",
+  name: "Lightnet",
+};
+
+const networks: MinaNetwork[] = [
+  Mainnet,
+  Local,
+  Berkeley,
+  Zeko,
+  TestWorld2,
+  Lightnet,
+];

package/tsconfig.json

@@ -0,0 +1,41 @@
+{
+  "compilerOptions": {
+    "target": "es2021" /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', 'ES2021', or 'ESNEXT'. */,
+    "lib": ["es2021"],
+    "module": "CommonJS" /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'. */,
+    "outDir": "./dist/lib/ts" /* Redirect output structure to the directory. */,
+    "strict": true /* Enable all strict type-checking options. */,
+    "esModuleInterop": true /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */,
+    "skipLibCheck": true /* Skip type checking of declaration files. */,
+    "forceConsistentCasingInFileNames": true /* Disallow inconsistently-cased references to the same file. */,
+    "composite": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "strictPropertyInitialization": false,
+    "resolveJsonModule": true
+  },
+  "typedocOptions": {
+    "entryPoints": ["src/index.ts"],
+    "out": "docs",
+    "plugin": [],
+    "excludeExternals": true,
+    "sourceLinkTemplate": "https://github.com/zkcloudworker/zkcloudworker-lib/blob/master/{path}#L{line}"
+  },
+  "include": ["src/**/*"],
+  "exclude": [
+    "dist/**",
+    "tests/**",
+    "docs/**",
+    "experimental/**",
+    "mycache/**",
+    "nftcache/**",
+    "experimental/**",
+    "node_modules",
+    "deprecated/**",
+    "images/**"
+  ],
+  "ts-node": {
+    "esm": true, // «———— enabling ESM for ts-node
+    "experimentalSpecifierResolution": "node"
+  }
+}