zkcloudworker 0.7.2 → 0.7.4

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

@@ -5,8 +5,24 @@ import { TaskData } from "./task";
 import { blockchain } from "../networks";
 import { CloudTransaction, DeployerKeyPair } from "./cloud";
 import { ApiCommand } from "../api/api";
+/**
+ * LocalCloud is a cloud that runs on the local machine for testing and development
+ * It uses LocalStorage to store jobs, tasks, transactions, and data
+ * It uses a localWorker to execute the tasks
+ * It can be used to test the cloud functionality without deploying to the cloud
+ * @param localWorker the worker to execute the tasks
+ */
 export declare class LocalCloud extends Cloud {
     readonly localWorker: (cloud: Cloud) => Promise<zkCloudWorker>;
+    /**
+     * Constructor for LocalCloud
+     * @param params the parameters to create the LocalCloud
+     * @param params.job the job data
+     * @param params.chain the blockchain to execute the job on, can be any blockchain, not only local
+     * @param params.cache the cache folder
+     * @param params.stepId the step id
+     * @param params.localWorker the worker to execute the tasks
+     */
     constructor(params: {
         job: JobData;
         chain: blockchain;
@@ -14,21 +30,80 @@ export declare class LocalCloud extends Cloud {
         stepId?: string;
         localWorker: (cloud: Cloud) => Promise<zkCloudWorker>;
     });
+    /**
+     * Provides the deployer key pair for testing and development
+     * @returns the deployer key pair
+     */
     getDeployer(): Promise<DeployerKeyPair | undefined>;
+    /**
+     * Releases the deployer key pair
+     */
     releaseDeployer(params: {
         publicKey: string;
         txsHashes: string[];
     }): Promise<void>;
-    log(msg: string): Promise<void>;
+    /**
+     * Gets the data by key
+     * @param key the key to get the data
+     * @returns the data
+     */
     getDataByKey(key: string): Promise<string | undefined>;
+    /**
+     * Saves the data by key
+     * @param key the key to save the data
+     * @param value the value to save
+     */
     saveDataByKey(key: string, value: string | undefined): Promise<void>;
+    /**
+     * Saves the file
+     * @param filename the filename to save
+     * @param value the value to save
+     */
     saveFile(filename: string, value: Buffer): Promise<void>;
+    /**
+     * Loads the file
+     * @param filename
+     * @returns the file data
+     */
     loadFile(filename: string): Promise<Buffer | undefined>;
+    /**
+     * Loads the environment
+     * @param password
+     */
     loadEnvironment(password: string): Promise<void>;
+    /**
+     * Generates an id for local cloud
+     * @returns generated unique id
+     */
     private static generateId;
+    /**
+     * Adds transactions to the local cloud
+     * @param transactions the transactions to add
+     * @returns the transaction ids
+     */
     static addTransactions(transactions: string[]): Promise<string[]>;
+    /**
+     * Deletes a transaction from the local cloud
+     * @param txId the transaction id to delete
+     */
     deleteTransaction(txId: string): Promise<void>;
     getTransactions(): Promise<CloudTransaction[]>;
+    /**
+     * Runs the worker in the local cloud
+     * @param params the parameters to run the worker
+     * @param params.command the command to run
+     * @param params.data the data to use
+     * @param params.data.developer the developer of the repo
+     * @param params.data.repo the repo
+     * @param params.data.transactions the transactions to process
+     * @param params.data.task the task to execute
+     * @param params.data.userId the user id
+     * @param params.data.args the arguments for the job
+     * @param params.data.metadata the metadata for the job
+     * @param params.chain the blockchain to execute the job on
+     * @param params.localWorker the worker to execute the tasks
+     * @returns the job id
+     */
     static run(params: {
         command: ApiCommand;
         data: {
@@ -43,6 +118,16 @@ export declare class LocalCloud extends Cloud {
         chain: blockchain;
         localWorker: (cloud: Cloud) => Promise<zkCloudWorker>;
     }): Promise<string>;
+    /**
+     * Runs the recursive proof in the local cloud
+     * @param data the data to use
+     * @param data.transactions the transactions to process
+     * @param data.task the task to execute
+     * @param data.userId the user id
+     * @param data.args the arguments for the job
+     * @param data.metadata the metadata for the job
+     * @returns the job id
+     */
     recursiveProof(data: {
         transactions: string[];
         task?: string;
@@ -50,6 +135,16 @@ export declare class LocalCloud extends Cloud {
         args?: string;
         metadata?: string;
     }): Promise<string>;
+    /**
+     * Executes the task in the local cloud
+     * @param data the data to use
+     * @param data.transactions the transactions to process
+     * @param data.task the task to execute
+     * @param data.userId the user id
+     * @param data.args the arguments for the job
+     * @param data.metadata the metadata for the job
+     * @returns the job id
+     */
     execute(data: {
         transactions: string[];
         task: string;
@@ -57,7 +152,22 @@ export declare class LocalCloud extends Cloud {
         args?: string;
         metadata?: string;
     }): Promise<string>;
+    /**
+     * Gets the job result
+     * @param jobId the job id
+     * @returns the job data
+     */
     jobResult(jobId: string): Promise<JobData | undefined>;
+    /**
+     * Adds a task to the local cloud
+     * @param data the data to use
+     * @param data.task the task to execute
+     * @param data.startTime the start time for the task
+     * @param data.userId the user id
+     * @param data.args the arguments for the job
+     * @param data.metadata the metadata for the job
+     * @returns the task id
+     */
     addTask(data: {
         task: string;
         startTime?: number;
@@ -65,14 +175,43 @@ export declare class LocalCloud extends Cloud {
         args?: string;
         metadata?: string;
     }): Promise<string>;
+    /**
+     * Deletes a task from the local cloud
+     * @param taskId the task id to delete
+     */
     deleteTask(taskId: string): Promise<void>;
+    /**
+     * Processes the tasks in the local cloud
+     */
     processTasks(): Promise<void>;
+    /**
+     * Processes the local tasks
+     * @param params the parameters to process the local tasks
+     * @param params.developer the developer of the repo
+     * @param params.repo the repo
+     * @param params.localWorker the worker to execute the tasks
+     * @param params.chain the blockchain to execute the job on
+     */
     static processLocalTasks(params: {
         developer: string;
         repo: string;
         localWorker: (cloud: Cloud) => Promise<zkCloudWorker>;
         chain: blockchain;
     }): Promise<number>;
+    /**
+     * Runs the sequencer in the local cloud
+     * @param params the parameters to run the sequencer
+     * @param params.worker the worker to execute the tasks
+     * @param params.data the data to use
+     * @param params.data.developer the developer of the repo
+     * @param params.data.repo the repo
+     * @param params.data.transactions the transactions to process
+     * @param params.data.task the task to execute
+     * @param params.data.userId the user id
+     * @param params.data.args the arguments for the job
+     * @param params.data.metadata the metadata for the job
+     * @returns the proof
+     */
     static sequencer(params: {
         worker: zkCloudWorker;
         data: {
@@ -86,6 +225,15 @@ export declare class LocalCloud extends Cloud {
         };
     }): Promise<string>;
 }
+/**
+ * LocalStorage is a local storage for the local cloud
+ * It stores jobs, tasks, transactions, and data
+ * It can be used to test the cloud functionality without deploying to the cloud
+ * @param jobs the jobs
+ * @param data the data
+ * @param transactions the transactions
+ * @param tasks the tasks
+ */
 export declare class LocalStorage {
     static jobs: {
         [key: string]: JobData;
@@ -102,6 +250,14 @@ export declare class LocalStorage {
     static tasks: {
         [key: string]: TaskData;
     };
+    /**
+     * Saves the data
+     * @param name the name to save the data
+     */
     static saveData(name: string): Promise<void>;
+    /**
+     * Loads the data
+     * @param name the name to load the data
+     */
     static loadData(name: string): Promise<void>;
 }

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

@@ -4,7 +4,23 @@ exports.LocalStorage = exports.LocalCloud = void 0;
 const cloud_1 = require("./cloud");
 const utils_1 = require("../utils/utils");
 const files_1 = require("./files");
+/**
+ * LocalCloud is a cloud that runs on the local machine for testing and development
+ * It uses LocalStorage to store jobs, tasks, transactions, and data
+ * It uses a localWorker to execute the tasks
+ * It can be used to test the cloud functionality without deploying to the cloud
+ * @param localWorker the worker to execute the tasks
+ */
 class LocalCloud extends cloud_1.Cloud {
+    /**
+     * Constructor for LocalCloud
+     * @param params the parameters to create the LocalCloud
+     * @param params.job the job data
+     * @param params.chain the blockchain to execute the job on, can be any blockchain, not only local
+     * @param params.cache the cache folder
+     * @param params.stepId the step id
+     * @param params.localWorker the worker to execute the tasks
+     */
     constructor(params) {
         const { job, chain, cache, stepId, localWorker } = params;
         const { id, jobId, developer, repo, task, userId, args, metadata, taskId } = job;
@@ -25,6 +41,10 @@ class LocalCloud extends cloud_1.Cloud {
         });
         this.localWorker = localWorker;
     }
+    /**
+     * Provides the deployer key pair for testing and development
+     * @returns the deployer key pair
+     */
     async getDeployer() {
         const privateKey = process.env.DEPLOYER_PRIVATE_KEY;
         const publicKey = process.env.DEPLOYER_PUBLIC_KEY;
@@ -41,35 +61,68 @@ class LocalCloud extends cloud_1.Cloud {
             return undefined;
         }
     }
+    /**
+     * Releases the deployer key pair
+     */
     async releaseDeployer(params) {
         console.log("LocalCloud: releaseDeployer", params);
     }
-    async log(msg) {
-        console.log("LocalCloud:", msg);
-    }
+    /**
+     * Gets the data by key
+     * @param key the key to get the data
+     * @returns the data
+     */
     async getDataByKey(key) {
         const value = LocalStorage.data[key];
         return value;
     }
+    /**
+     * Saves the data by key
+     * @param key the key to save the data
+     * @param value the value to save
+     */
     async saveDataByKey(key, value) {
         if (value !== undefined)
             LocalStorage.data[key] = value;
         else
             delete LocalStorage.data[key];
     }
+    /**
+     * Saves the file
+     * @param filename the filename to save
+     * @param value the value to save
+     */
     async saveFile(filename, value) {
         await (0, files_1.saveBinaryFile)({ data: value, filename });
     }
+    /**
+     * Loads the file
+     * @param filename
+     * @returns the file data
+     */
     async loadFile(filename) {
         const data = await (0, files_1.loadBinaryFile)(filename);
         return data;
     }
+    /**
+     * Loads the environment
+     * @param password
+     */
     async loadEnvironment(password) {
         throw new Error("Method not implemented.");
     }
+    /**
+     * Generates an id for local cloud
+     * @returns generated unique id
+     */
     static generateId() {
         return "local." + Date.now().toString() + "." + (0, utils_1.makeString)(32);
     }
+    /**
+     * Adds transactions to the local cloud
+     * @param transactions the transactions to add
+     * @returns the transaction ids
+     */
     static async addTransactions(transactions) {
         const timeReceived = Date.now();
         const txId = [];
@@ -80,6 +133,10 @@ class LocalCloud extends cloud_1.Cloud {
         });
         return txId;
     }
+    /**
+     * Deletes a transaction from the local cloud
+     * @param txId the transaction id to delete
+     */
     async deleteTransaction(txId) {
         if (LocalStorage.transactions[txId] === undefined)
             throw new Error(`deleteTransaction: Transaction ${txId} not found`);
@@ -96,6 +153,22 @@ class LocalCloud extends cloud_1.Cloud {
         });
         return txs;
     }
+    /**
+     * Runs the worker in the local cloud
+     * @param params the parameters to run the worker
+     * @param params.command the command to run
+     * @param params.data the data to use
+     * @param params.data.developer the developer of the repo
+     * @param params.data.repo the repo
+     * @param params.data.transactions the transactions to process
+     * @param params.data.task the task to execute
+     * @param params.data.userId the user id
+     * @param params.data.args the arguments for the job
+     * @param params.data.metadata the metadata for the job
+     * @param params.chain the blockchain to execute the job on
+     * @param params.localWorker the worker to execute the tasks
+     * @returns the job id
+     */
     static async run(params) {
         const { command, data, chain, localWorker } = params;
         const { developer, repo, transactions, task, userId, args, metadata } = data;
@@ -148,6 +221,16 @@ class LocalCloud extends cloud_1.Cloud {
         LocalStorage.jobs[jobId] = job;
         return jobId;
     }
+    /**
+     * Runs the recursive proof in the local cloud
+     * @param data the data to use
+     * @param data.transactions the transactions to process
+     * @param data.task the task to execute
+     * @param data.userId the user id
+     * @param data.args the arguments for the job
+     * @param data.metadata the metadata for the job
+     * @returns the job id
+     */
     async recursiveProof(data) {
         return await LocalCloud.run({
             command: "recursiveProof",
@@ -164,6 +247,16 @@ class LocalCloud extends cloud_1.Cloud {
             localWorker: this.localWorker,
         });
     }
+    /**
+     * Executes the task in the local cloud
+     * @param data the data to use
+     * @param data.transactions the transactions to process
+     * @param data.task the task to execute
+     * @param data.userId the user id
+     * @param data.args the arguments for the job
+     * @param data.metadata the metadata for the job
+     * @returns the job id
+     */
     async execute(data) {
         return await LocalCloud.run({
             command: "execute",
@@ -180,9 +273,24 @@ class LocalCloud extends cloud_1.Cloud {
             localWorker: this.localWorker,
         });
     }
+    /**
+     * Gets the job result
+     * @param jobId the job id
+     * @returns the job data
+     */
     async jobResult(jobId) {
         return LocalStorage.jobs[jobId];
     }
+    /**
+     * Adds a task to the local cloud
+     * @param data the data to use
+     * @param data.task the task to execute
+     * @param data.startTime the start time for the task
+     * @param data.userId the user id
+     * @param data.args the arguments for the job
+     * @param data.metadata the metadata for the job
+     * @returns the task id
+     */
     async addTask(data) {
         const taskId = LocalCloud.generateId();
         LocalStorage.tasks[taskId] = {
@@ -196,11 +304,18 @@ class LocalCloud extends cloud_1.Cloud {
         };
         return taskId;
     }
+    /**
+     * Deletes a task from the local cloud
+     * @param taskId the task id to delete
+     */
     async deleteTask(taskId) {
         if (LocalStorage.tasks[taskId] === undefined)
             throw new Error(`deleteTask: Task ${taskId} not found`);
         delete LocalStorage.tasks[taskId];
     }
+    /**
+     * Processes the tasks in the local cloud
+     */
     async processTasks() {
         await LocalCloud.processLocalTasks({
             developer: this.developer,
@@ -209,6 +324,14 @@ class LocalCloud extends cloud_1.Cloud {
             chain: this.chain,
         });
     }
+    /**
+     * Processes the local tasks
+     * @param params the parameters to process the local tasks
+     * @param params.developer the developer of the repo
+     * @param params.repo the repo
+     * @param params.localWorker the worker to execute the tasks
+     * @param params.chain the blockchain to execute the job on
+     */
     static async processLocalTasks(params) {
         const { developer, repo, localWorker, chain } = params;
         for (const taskId in LocalStorage.tasks) {
@@ -258,6 +381,20 @@ class LocalCloud extends cloud_1.Cloud {
             count++;
         return count;
     }
+    /**
+     * Runs the sequencer in the local cloud
+     * @param params the parameters to run the sequencer
+     * @param params.worker the worker to execute the tasks
+     * @param params.data the data to use
+     * @param params.data.developer the developer of the repo
+     * @param params.data.repo the repo
+     * @param params.data.transactions the transactions to process
+     * @param params.data.task the task to execute
+     * @param params.data.userId the user id
+     * @param params.data.args the arguments for the job
+     * @param params.data.metadata the metadata for the job
+     * @returns the proof
+     */
     static async sequencer(params) {
         const { worker, data } = params;
         const { transactions } = data;
@@ -281,7 +418,20 @@ class LocalCloud extends cloud_1.Cloud {
     }
 }
 exports.LocalCloud = LocalCloud;
+/**
+ * LocalStorage is a local storage for the local cloud
+ * It stores jobs, tasks, transactions, and data
+ * It can be used to test the cloud functionality without deploying to the cloud
+ * @param jobs the jobs
+ * @param data the data
+ * @param transactions the transactions
+ * @param tasks the tasks
+ */
 class LocalStorage {
+    /**
+     * Saves the data
+     * @param name the name to save the data
+     */
     static async saveData(name) {
         const data = {
             jobs: LocalStorage.jobs,
@@ -292,6 +442,10 @@ class LocalStorage {
         const filename = name + ".cloud";
         await (0, files_1.saveFile)({ data, filename });
     }
+    /**
+     * Loads the data
+     * @param name the name to load the data
+     */
     static async loadData(name) {
         const filename = name + ".cloud";
         const data = await (0, files_1.loadFile)(filename);

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

@@ -1,4 +1,22 @@
 import { blockchain } from "../networks";
+/**
+ * TaskData is the data structure for a task, keeping track of the task status, result, logs, and metadata
+ * @param id the id of the user
+ * @param taskId the id of the task
+ *
+ * @param startTime the time the task was started
+ * @param timeCreated the time the task was created
+ * @param maxAttempts the maximum number of attempts
+ * @param attempts the number of attempts
+ *
+ * @param developer the developer of the repo executing the task
+ * @param repo the repo executing the task
+ * @param task the task to execute
+ * @param userId the id of the user
+ * @param args the arguments for the task
+ * @param metadata the metadata for the task
+ * @param chain the blockchain to execute the task on
+ */
 export interface TaskData {
     id: string;
     taskId: string;

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

@@ -1,5 +1,25 @@
 export { blockchain, MinaNetwork, networks, Mainnet, Devnet, Zeko, Lightnet, Local, };
+/**
+ * blockchain is the type for the chain id
+ * @param local the local chain id
+ * @param devnet the devnet chain id
+ * @param lightnet the lightnet chain id
+ * @param mainnet the mainnet chain id
+ * @param zeko the zeko chain id
+ * @param mainnet the mainnet chain id
+ */
 type blockchain = "local" | "devnet" | "lightnet" | "mainnet" | "zeko" | "mainnet";
+/**
+ * MinaNetwork is the data structure for a Mina network, keeping track of the mina and archive endpoints, chain id, name, account manager, explorer account url, explorer transaction url, and faucet
+ * @param mina the mina endpoints
+ * @param archive the archive endpoints
+ * @param chainId the chain id
+ * @param name the name of the network
+ * @param accountManager the account manager for Lightnet
+ * @param explorerAccountUrl the explorer account url
+ * @param explorerTransactionUrl the explorer transaction url
+ * @param faucet the faucet url
+ */
 interface MinaNetwork {
     mina: string[];
     archive: string[];

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

@@ -1,2 +1,6 @@
 import { UInt64 } from "o1js";
+/**
+ * Calculate the fee for a transaction
+ * @returns the fee for a transaction
+ */
 export declare function fee(): Promise<UInt64>;

package/lib/ts/src/utils/fee.js

@@ -6,8 +6,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.fee = void 0;
 const o1js_1 = require("o1js");
 const config_1 = __importDefault(require("../config"));
+/**
+ * Calculate the fee for a transaction
+ * @returns the fee for a transaction
+ */
 async function fee() {
-    //TODO: update after mainnet launch
+    //TODO: update after mainnet launch and resolution of the issue https://github.com/o1-labs/o1js/issues/1626
     return o1js_1.UInt64.fromJSON(config_1.default.MINAFEE);
 }
 exports.fee = fee;

package/lib/ts/src/utils/fetch.d.ts

@@ -1,4 +1,12 @@
 import { PublicKey, Field } from "o1js";
+/**
+ * Fetches the Mina account for a given public key with error handling
+ * @param params the parameters for fetching the account
+ * @param params.publicKey the public key of the account
+ * @param params.tokenId the token id of the account
+ * @param params.force whether to force the fetch - use it only if you are sure the account exists
+ * @returns the account object
+ */
 export declare function fetchMinaAccount(params: {
     publicKey: string | PublicKey;
     tokenId?: string | Field | undefined;
@@ -9,10 +17,22 @@ export declare function fetchMinaAccount(params: {
     account: import("o1js/dist/node/bindings/mina-transaction/gen/transaction").Account;
     error: undefined;
 }>;
+/**
+ * Fetches the Mina actions for a given public key with error handling
+ * @param publicKey the public key of the contract
+ * @param fromActionState the starting action state
+ * @param endActionState the ending action state
+ * @returns the actions array
+ */
 export declare function fetchMinaActions(publicKey: PublicKey, fromActionState: Field, endActionState?: Field): Promise<{
     actions: string[][];
     hash: string;
 }[] | undefined>;
+/**
+ * Fetches the Mina transaction for a given hash with error handling
+ * @param hash the hash of the transaction
+ * @returns the transaction object
+ */
 export declare function checkMinaZkappTransaction(hash: string): Promise<{
     success: boolean;
     failureReason: string[][][];

package/lib/ts/src/utils/fetch.js

@@ -3,6 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkMinaZkappTransaction = exports.fetchMinaActions = exports.fetchMinaAccount = void 0;
 const o1js_1 = require("o1js");
 const utils_1 = require("./utils");
+/**
+ * Fetches the Mina account for a given public key with error handling
+ * @param params the parameters for fetching the account
+ * @param params.publicKey the public key of the account
+ * @param params.tokenId the token id of the account
+ * @param params.force whether to force the fetch - use it only if you are sure the account exists
+ * @returns the account object
+ */
 async function fetchMinaAccount(params) {
     const { publicKey, tokenId, force } = params;
     const timeout = 1000 * 60 * 2; // 2 minutes
@@ -48,6 +56,13 @@ async function fetchMinaAccount(params) {
     return result;
 }
 exports.fetchMinaAccount = fetchMinaAccount;
+/**
+ * Fetches the Mina actions for a given public key with error handling
+ * @param publicKey the public key of the contract
+ * @param fromActionState the starting action state
+ * @param endActionState the ending action state
+ * @returns the actions array
+ */
 async function fetchMinaActions(publicKey, fromActionState, endActionState) {
     const timeout = 1000 * 60 * 600; // 10 hours
     const startTime = Date.now();
@@ -71,6 +86,11 @@ async function fetchMinaActions(publicKey, fromActionState, endActionState) {
     return undefined;
 }
 exports.fetchMinaActions = fetchMinaActions;
+/**
+ * Fetches the Mina transaction for a given hash with error handling
+ * @param hash the hash of the transaction
+ * @returns the transaction object
+ */
 async function checkMinaZkappTransaction(hash) {
     try {
         const result = await (0, o1js_1.checkZkappTransaction)(hash);

package/lib/ts/src/utils/fields.d.ts

@@ -1,3 +1,13 @@
 import { Field } from "o1js";
+/**
+ * Serialize fields to a string using base64 URL-friendly encoding
+ * @param fields the fields array to serialize
+ * @returns the serialized string
+ */
 export declare function serializeFields(fields: Field[]): string;
+/**
+ * Deserialize fields from a string using base64 URL-friendly encoding
+ * @param s the string to deserialize
+ * @returns the deserialized fields array
+ */
 export declare function deserializeFields(s: string): Field[];