@prosopo/database 2.1.5 → 2.1.6

package/dist/cjs/databases/provider.cjs

@@ -0,0 +1,983 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const is = require("@polkadot/util/is");
+const common = require("@prosopo/common");
+const types = require("@prosopo/types");
+const typesDatabase = require("@prosopo/types-database");
+const mongo = require("../base/mongo.cjs");
+var TableNames = /* @__PURE__ */ ((TableNames2) => {
+  TableNames2["captcha"] = "captcha";
+  TableNames2["dataset"] = "dataset";
+  TableNames2["solution"] = "solution";
+  TableNames2["commitment"] = "commitment";
+  TableNames2["usersolution"] = "usersolution";
+  TableNames2["pending"] = "pending";
+  TableNames2["scheduler"] = "scheduler";
+  TableNames2["powcaptcha"] = "powcaptcha";
+  TableNames2["client"] = "client";
+  TableNames2["session"] = "session";
+  return TableNames2;
+})(TableNames || {});
+const PROVIDER_TABLES = [
+  {
+    collectionName: "captcha",
+    modelName: "Captcha",
+    schema: typesDatabase.CaptchaRecordSchema
+  },
+  {
+    collectionName: "powcaptcha",
+    modelName: "PowCaptcha",
+    schema: typesDatabase.PoWCaptchaRecordSchema
+  },
+  {
+    collectionName: "dataset",
+    modelName: "Dataset",
+    schema: typesDatabase.DatasetRecordSchema
+  },
+  {
+    collectionName: "solution",
+    modelName: "Solution",
+    schema: typesDatabase.SolutionRecordSchema
+  },
+  {
+    collectionName: "commitment",
+    modelName: "UserCommitment",
+    schema: typesDatabase.UserCommitmentRecordSchema
+  },
+  {
+    collectionName: "usersolution",
+    modelName: "UserSolution",
+    schema: typesDatabase.UserSolutionRecordSchema
+  },
+  {
+    collectionName: "pending",
+    modelName: "Pending",
+    schema: typesDatabase.PendingRecordSchema
+  },
+  {
+    collectionName: "scheduler",
+    modelName: "Scheduler",
+    schema: typesDatabase.ScheduledTaskRecordSchema
+  },
+  {
+    collectionName: "client",
+    modelName: "Client",
+    schema: typesDatabase.ClientRecordSchema
+  },
+  {
+    collectionName: "session",
+    modelName: "Session",
+    schema: typesDatabase.SessionRecordSchema
+  }
+];
+class ProviderDatabase extends mongo.MongoDatabase {
+  constructor(url, dbname, authSource, logger) {
+    super(url, dbname, authSource, logger);
+    this.tables = {};
+    this.tables = {};
+  }
+  async connect() {
+    await super.connect();
+    this.loadTables();
+  }
+  loadTables() {
+    const tables = {};
+    PROVIDER_TABLES.map(({ collectionName, modelName, schema }) => {
+      if (this.connection) {
+        tables[collectionName] = this.connection.model(modelName, schema);
+      }
+    });
+    this.tables = tables;
+  }
+  getTables() {
+    if (!this.tables) {
+      throw new common.ProsopoDBError("DATABASE.TABLES_UNDEFINED", {
+        context: { failedFuncName: this.getTables.name },
+        logger: this.logger
+      });
+    }
+    return this.tables;
+  }
+  /**
+   * @description Load a dataset to the database
+   * @param {Dataset}  dataset
+   */
+  async storeDataset(dataset) {
+    try {
+      this.logger.debug("Storing dataset in database");
+      const parsedDataset = types.DatasetWithIdsAndTreeSchema.parse(dataset);
+      const datasetDoc = {
+        datasetId: parsedDataset.datasetId,
+        datasetContentId: parsedDataset.datasetContentId,
+        format: parsedDataset.format,
+        contentTree: parsedDataset.contentTree,
+        solutionTree: parsedDataset.solutionTree
+      };
+      await this.tables.dataset?.updateOne(
+        { datasetId: parsedDataset.datasetId },
+        { $set: datasetDoc },
+        { upsert: true }
+      );
+      const captchaDocs = parsedDataset.captchas.map(
+        ({ solution, ...captcha }, index) => ({
+          ...captcha,
+          datasetId: parsedDataset.datasetId,
+          datasetContentId: parsedDataset.datasetContentId,
+          index,
+          solved: !!solution?.length
+        })
+      );
+      this.logger.debug("Inserting captcha records");
+      if (captchaDocs.length) {
+        await this.tables?.captcha.bulkWrite(
+          captchaDocs.map((captchaDoc) => ({
+            updateOne: {
+              filter: { captchaId: captchaDoc.captchaId },
+              update: { $set: captchaDoc },
+              upsert: true
+            }
+          }))
+        );
+      }
+      const captchaSolutionDocs = parsedDataset.captchas.filter(({ solution }) => solution?.length).map((captcha) => ({
+        captchaId: captcha.captchaId,
+        captchaContentId: captcha.captchaContentId,
+        solution: captcha.solution,
+        salt: captcha.salt,
+        datasetId: parsedDataset.datasetId,
+        datasetContentId: parsedDataset.datasetContentId
+      }));
+      this.logger.debug("Inserting solution records");
+      if (captchaSolutionDocs.length) {
+        await this.tables?.solution.bulkWrite(
+          captchaSolutionDocs.map((captchaSolutionDoc) => ({
+            updateOne: {
+              filter: { captchaId: captchaSolutionDoc.captchaId },
+              update: { $set: captchaSolutionDoc },
+              upsert: true
+            }
+          }))
+        );
+      }
+      this.logger.debug("Dataset stored in database");
+    } catch (err) {
+      throw new common.ProsopoDBError("DATABASE.DATASET_LOAD_FAILED", {
+        context: { failedFuncName: this.storeDataset.name, error: err },
+        logger: this.logger
+      });
+    }
+  }
+  /** @description Get solutions for a dataset
+   * @param {string} datasetId
+   */
+  async getSolutions(datasetId) {
+    const docs = await this.tables?.solution.find({ datasetId }).lean();
+    return docs ? docs : [];
+  }
+  /** @description Get a dataset from the database
+   * @param {string} datasetId
+   */
+  async getDataset(datasetId) {
+    const datasetDoc = await this.tables?.dataset.findOne({ datasetId }).lean();
+    if (datasetDoc) {
+      const { datasetContentId, format, contentTree, solutionTree } = datasetDoc;
+      const captchas = await this.tables?.captcha.find({ datasetId }).lean() || [];
+      const solutions = await this.tables?.solution.find({ datasetId }).lean() || [];
+      const solutionsKeyed = {};
+      for (const solution of solutions) {
+        solutionsKeyed[solution.captchaId] = solution;
+      }
+      return {
+        datasetId,
+        datasetContentId,
+        format,
+        contentTree: contentTree || [],
+        solutionTree: solutionTree || [],
+        captchas: captchas.map((captchaDoc) => {
+          const { captchaId, captchaContentId, items, target, salt, solved } = captchaDoc;
+          const solution = solutionsKeyed[captchaId];
+          return {
+            captchaId,
+            captchaContentId,
+            solved: !!solved,
+            salt,
+            items,
+            target,
+            solution: solved && solution ? solution.solution : []
+          };
+        })
+      };
+    }
+    throw new common.ProsopoDBError("DATABASE.DATASET_GET_FAILED", {
+      context: { failedFuncName: this.getDataset.name, datasetId }
+    });
+  }
+  /**
+   * @description Get random captchas that are solved or not solved
+   * @param {boolean}  solved    `true` when captcha is solved
+   * @param {string}   datasetId  the id of the data set
+   * @param {number}   size       the number of records to be returned
+   */
+  async getRandomCaptcha(solved, datasetId, size) {
+    if (!is.isHex(datasetId)) {
+      throw new common.ProsopoDBError("DATABASE.INVALID_HASH", {
+        context: { failedFuncName: this.getRandomCaptcha.name, datasetId }
+      });
+    }
+    const sampleSize = size ? Math.abs(Math.trunc(size)) : 1;
+    const cursor = this.tables?.captcha.aggregate([
+      { $match: { datasetId, solved } },
+      { $sample: { size: sampleSize } },
+      {
+        $project: {
+          datasetId: 1,
+          datasetContentId: 1,
+          captchaId: 1,
+          captchaContentId: 1,
+          items: 1,
+          target: 1
+        }
+      }
+    ]);
+    const docs = await cursor;
+    if (docs?.length) {
+      return docs.map(({ _id, ...keepAttrs }) => keepAttrs);
+    }
+    throw new common.ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED", {
+      context: {
+        failedFuncName: this.getRandomCaptcha.name,
+        solved,
+        datasetId,
+        size
+      }
+    });
+  }
+  /**
+   * @description Get captchas by id
+   * @param {string[]} captchaId
+   */
+  async getCaptchaById(captchaId) {
+    const cursor = this.tables?.captcha.find({ captchaId: { $in: captchaId } }).lean();
+    const docs = await cursor;
+    if (docs?.length) {
+      return docs.map(({ _id, ...keepAttrs }) => keepAttrs);
+    }
+    throw new common.ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED", {
+      context: { failedFuncName: this.getCaptchaById.name, captchaId }
+    });
+  }
+  /**
+   * @description Update a captcha
+   * @param {Captcha}  captcha
+   * @param {string}   datasetId  the id of the data set
+   */
+  async updateCaptcha(captcha, datasetId) {
+    if (!is.isHex(datasetId)) {
+      throw new common.ProsopoDBError("DATABASE.INVALID_HASH", {
+        context: { failedFuncName: this.updateCaptcha.name, datasetId }
+      });
+    }
+    try {
+      await this.tables?.captcha.updateOne(
+        { datasetId },
+        { $set: captcha },
+        { upsert: false }
+      );
+    } catch (err) {
+      throw new common.ProsopoDBError("DATABASE.CAPTCHA_UPDATE_FAILED", {
+        context: { failedFuncName: this.getDatasetDetails.name, error: err }
+      });
+    }
+  }
+  /**
+   * @description Remove captchas
+   */
+  async removeCaptchas(captchaIds) {
+    await this.tables?.captcha.deleteMany({ captchaId: { $in: captchaIds } });
+  }
+  /**
+   * @description Get a dataset by Id
+   */
+  async getDatasetDetails(datasetId) {
+    if (!is.isHex(datasetId)) {
+      throw new common.ProsopoDBError("DATABASE.INVALID_HASH", {
+        context: { failedFuncName: this.getDatasetDetails.name, datasetId }
+      });
+    }
+    const doc = await this.tables?.dataset.findOne({ datasetId }).lean();
+    if (doc) {
+      return doc;
+    }
+    throw new common.ProsopoDBError("DATABASE.DATASET_GET_FAILED", {
+      context: {
+        failedFuncName: this.getDatasetDetails.name,
+        datasetId
+      }
+    });
+  }
+  /**
+   * @description Store a Dapp User's captcha solution commitment
+   */
+  async storeDappUserSolution(captchas, commit) {
+    const commitmentRecord = typesDatabase.UserCommitmentSchema.parse({
+      ...commit,
+      lastUpdatedTimestamp: Date.now()
+    });
+    if (captchas.length) {
+      await this.tables?.commitment.updateOne(
+        {
+          id: commit.id
+        },
+        commitmentRecord,
+        { upsert: true }
+      );
+      const ops = captchas.map((captcha) => ({
+        updateOne: {
+          filter: { commitmentId: commit.id, captchaId: captcha.captchaId },
+          update: {
+            $set: {
+              captchaId: captcha.captchaId,
+              captchaContentId: captcha.captchaContentId,
+              salt: captcha.salt,
+              solution: captcha.solution,
+              commitmentId: commit.id,
+              processed: false
+            }
+          },
+          upsert: true
+        }
+      }));
+      await this.tables?.usersolution.bulkWrite(ops);
+    }
+  }
+  /**
+   * @description Adds a new PoW Captcha record to the database.
+   * @param {string} challenge The challenge string for the captcha.
+   * @param components The components of the PoW challenge.
+   * @param difficulty
+   * @param providerSignature
+   * @param ipAddress
+   * @param serverChecked
+   * @param userSubmitted
+   * @param storedStatus
+   * @param userSignature
+   * @returns {Promise<void>} A promise that resolves when the record is added.
+   */
+  async storePowCaptchaRecord(challenge, components, difficulty, providerSignature, ipAddress, headers, serverChecked = false, userSubmitted = false, storedStatus = typesDatabase.StoredStatusNames.notStored, userSignature) {
+    const tables = this.getTables();
+    const powCaptchaRecord = {
+      challenge,
+      ...components,
+      ipAddress,
+      headers,
+      result: { status: types.CaptchaStatus.pending },
+      userSubmitted,
+      serverChecked,
+      difficulty,
+      providerSignature,
+      userSignature,
+      lastUpdatedTimestamp: Date.now()
+    };
+    try {
+      await tables.powcaptcha.create(powCaptchaRecord);
+      this.logger.info("PowCaptcha record added successfully", {
+        challenge,
+        userSubmitted,
+        serverChecked,
+        storedStatus
+      });
+    } catch (error) {
+      this.logger.error("Failed to add PowCaptcha record", {
+        error,
+        challenge,
+        userSubmitted,
+        serverChecked,
+        storedStatus
+      });
+      throw new common.ProsopoDBError("DATABASE.CAPTCHA_UPDATE_FAILED", {
+        context: {
+          error,
+          challenge,
+          userSubmitted,
+          serverChecked,
+          storedStatus
+        },
+        logger: this.logger
+      });
+    }
+  }
+  /**
+   * @description Retrieves a PoW Captcha record by its challenge string.
+   * @param {string} challenge The challenge string to search for.
+   * @returns {Promise<PoWCaptchaRecord | null>} A promise that resolves with the found record or null if not found.
+   */
+  async getPowCaptchaRecordByChallenge(challenge) {
+    if (!this.tables) {
+      throw new common.ProsopoEnvError("DATABASE.DATABASE_UNDEFINED", {
+        context: { failedFuncName: this.getPowCaptchaRecordByChallenge.name },
+        logger: this.logger
+      });
+    }
+    try {
+      const record = await this.tables.powcaptcha.findOne({ challenge }).lean();
+      if (record) {
+        this.logger.info("PowCaptcha record retrieved successfully", {
+          challenge
+        });
+        return record;
+      }
+      this.logger.info("No PowCaptcha record found", { challenge });
+      return null;
+    } catch (error) {
+      this.logger.error("Failed to retrieve PowCaptcha record", {
+        error,
+        challenge
+      });
+      throw new common.ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED", {
+        context: { error, challenge },
+        logger: this.logger
+      });
+    }
+  }
+  /**
+   * @description Updates a PoW Captcha record in the database.
+   * @param {string} challenge The challenge string of the captcha to be updated.
+   * @param result
+   * @param serverChecked
+   * @param userSubmitted
+   * @param userSignature
+   * @returns {Promise<void>} A promise that resolves when the record is updated.
+   */
+  async updatePowCaptchaRecord(challenge, result, serverChecked = false, userSubmitted = false, userSignature) {
+    const tables = this.getTables();
+    const timestamp = Date.now();
+    const update = {
+      result,
+      serverChecked,
+      userSubmitted,
+      userSignature,
+      lastUpdatedTimestamp: timestamp
+    };
+    try {
+      const updateResult = await tables.powcaptcha.updateOne(
+        { challenge },
+        {
+          $set: update
+        }
+      );
+      if (updateResult.matchedCount === 0) {
+        this.logger.info("No PowCaptcha record found to update", {
+          challenge,
+          ...update
+        });
+        throw new common.ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED", {
+          context: {
+            challenge,
+            ...update
+          },
+          logger: this.logger
+        });
+      }
+      this.logger.info("PowCaptcha record updated successfully", {
+        challenge,
+        ...update
+      });
+    } catch (error) {
+      this.logger.error("Failed to update PowCaptcha record", {
+        error,
+        challenge,
+        ...update
+      });
+      throw new common.ProsopoDBError("DATABASE.CAPTCHA_UPDATE_FAILED", {
+        context: {
+          error,
+          challenge,
+          ...update
+        },
+        logger: this.logger
+      });
+    }
+  }
+  /** @description Get processed Dapp User captcha solutions from the user solution table
+   */
+  async getProcessedDappUserSolutions() {
+    const docs = await this.tables?.usersolution.find({ processed: true }).lean();
+    return docs || [];
+  }
+  /** @description Get processed Dapp User image captcha commitments from the commitments table
+   */
+  async getProcessedDappUserCommitments() {
+    const docs = await this.tables?.commitment.find({ processed: true }).lean();
+    return docs || [];
+  }
+  /** @description Get serverChecked Dapp User image captcha commitments from the commitments table
+   */
+  async getCheckedDappUserCommitments() {
+    const docs = await this.tables?.commitment.find({ [typesDatabase.StoredStatusNames.serverChecked]: true }).lean();
+    return docs || [];
+  }
+  /** @description Get Dapp User captcha commitments from the commitments table that have not been counted towards the
+   * client's total
+   */
+  async getUnstoredDappUserCommitments() {
+    const docs = await this.tables?.commitment.find({
+      $or: [
+        { storedStatus: { $ne: typesDatabase.StoredStatusNames.stored } },
+        { storedStatus: { $exists: false } }
+      ]
+    }).lean();
+    return docs || [];
+  }
+  /** @description Mark a list of captcha commits as stored
+   */
+  async markDappUserCommitmentsStored(commitmentIds) {
+    const updateDoc = {
+      storedAtTimestamp: Date.now()
+    };
+    await this.tables?.commitment.updateMany(
+      { id: { $in: commitmentIds } },
+      { $set: updateDoc },
+      { upsert: false }
+    );
+  }
+  /** @description Mark a list of captcha commits as checked
+   */
+  async markDappUserCommitmentsChecked(commitmentIds) {
+    const updateDoc = {
+      [typesDatabase.StoredStatusNames.serverChecked]: true,
+      lastUpdatedTimestamp: Date.now()
+    };
+    await this.tables?.commitment.updateMany(
+      { id: { $in: commitmentIds } },
+      { $set: updateDoc },
+      { upsert: false }
+    );
+  }
+  /** @description Get Dapp User PoW captcha commitments that have not been counted towards the client's total
+   */
+  async getUnstoredDappUserPoWCommitments() {
+    const docs = await this.tables?.powcaptcha.find({
+      $or: [
+        { storedStatus: { $ne: typesDatabase.StoredStatusNames.stored } },
+        { storedStatus: { $exists: false } }
+      ]
+    }).lean();
+    return docs || [];
+  }
+  /** @description Mark a list of PoW captcha commits as stored
+   */
+  async markDappUserPoWCommitmentsStored(challenges) {
+    const updateDoc = {
+      storedAtTimestamp: Date.now()
+    };
+    await this.tables?.powcaptcha.updateMany(
+      { challenge: { $in: challenges } },
+      { $set: updateDoc },
+      { upsert: false }
+    );
+  }
+  /** @description Mark a list of PoW captcha commits as checked by the server
+   */
+  async markDappUserPoWCommitmentsChecked(challenges) {
+    const updateDoc = {
+      [typesDatabase.StoredStatusNames.serverChecked]: true,
+      lastUpdatedTimestamp: Date.now()
+    };
+    await this.tables?.powcaptcha.updateMany(
+      { challenge: { $in: challenges } },
+      {
+        $set: updateDoc
+      },
+      { upsert: false }
+    );
+  }
+  /**
+   * Store a new session record
+   */
+  async storeSessionRecord(sessionRecord) {
+    try {
+      await this.tables.session.create(sessionRecord);
+    } catch (err) {
+      throw new common.ProsopoDBError("DATABASE.SESSION_STORE_FAILED", {
+        context: { error: err, sessionId: sessionRecord.sessionId },
+        logger: this.logger
+      });
+    }
+  }
+  /**
+   * Check if a session exists and remove it if it does
+   * @returns The session record if it existed, undefined otherwise
+   */
+  async checkAndRemoveSession(sessionId) {
+    try {
+      const session = await this.tables.session.findOneAndDelete({ sessionId }).lean();
+      return session || void 0;
+    } catch (err) {
+      throw new common.ProsopoDBError("DATABASE.SESSION_CHECK_REMOVE_FAILED", {
+        context: { error: err, sessionId },
+        logger: this.logger
+      });
+    }
+  }
+  /** @description Remove processed Dapp User captcha solutions from the user solution table
+   */
+  async removeProcessedDappUserSolutions(commitmentIds) {
+    return this.tables?.usersolution.deleteMany({
+      processed: true,
+      commitmentId: { $in: commitmentIds }
+    });
+  }
+  /** @description Remove processed Dapp User captcha commitments from the user commitments table
+   */
+  async removeProcessedDappUserCommitments(commitmentIds) {
+    return this.tables?.commitment.deleteMany({
+      processed: true,
+      id: { $in: commitmentIds }
+    });
+  }
+  /**
+   * @description Store a Dapp User's pending record
+   */
+  async storeDappUserPending(userAccount, requestHash, salt, deadlineTimestamp, requestedAtTimestamp, ipAddress) {
+    if (!is.isHex(requestHash)) {
+      throw new common.ProsopoDBError("DATABASE.INVALID_HASH", {
+        context: {
+          failedFuncName: this.storeDappUserPending.name,
+          requestHash
+        }
+      });
+    }
+    const pendingRecord = {
+      accountId: userAccount,
+      pending: true,
+      salt,
+      requestHash,
+      deadlineTimestamp,
+      requestedAtTimestamp,
+      ipAddress
+    };
+    await this.tables?.pending.updateOne(
+      { requestHash },
+      { $set: pendingRecord },
+      { upsert: true }
+    );
+  }
+  /**
+   * @description Get a Dapp user's pending record
+   */
+  async getDappUserPending(requestHash) {
+    if (!is.isHex(requestHash)) {
+      throw new common.ProsopoEnvError("DATABASE.INVALID_HASH", {
+        context: { failedFuncName: this.getDappUserPending.name, requestHash }
+      });
+    }
+    const doc = await this.tables?.pending.findOne({ requestHash }).lean();
+    if (doc) {
+      return doc;
+    }
+    throw new common.ProsopoEnvError("DATABASE.PENDING_RECORD_NOT_FOUND", {
+      context: { failedFuncName: this.getDappUserPending.name, requestHash }
+    });
+  }
+  /**
+   * @description Mark a pending request as used
+   */
+  async updateDappUserPendingStatus(requestHash) {
+    if (!is.isHex(requestHash)) {
+      throw new common.ProsopoEnvError("DATABASE.INVALID_HASH", {
+        context: {
+          failedFuncName: this.updateDappUserPendingStatus.name,
+          requestHash
+        }
+      });
+    }
+    await this.tables?.pending.updateOne(
+      { requestHash },
+      {
+        $set: {
+          [types.CaptchaStatus.pending]: false
+        }
+      },
+      { upsert: true }
+    );
+  }
+  /**
+   * @description Get all unsolved captchas
+   */
+  async getAllCaptchasByDatasetId(datasetId, state) {
+    const cursor = this.tables?.captcha.find({
+      datasetId,
+      solved: state === types.CaptchaStates.Solved
+    }).lean();
+    const docs = await cursor;
+    if (docs) {
+      return docs.map(({ _id, ...keepAttrs }) => keepAttrs);
+    }
+    throw new common.ProsopoEnvError("DATABASE.CAPTCHA_GET_FAILED");
+  }
+  /**
+   * @description Get all dapp user solutions by captchaIds
+   */
+  async getAllDappUserSolutions(captchaId) {
+    const cursor = this.tables?.usersolution?.find({ captchaId: { $in: captchaId } }).lean();
+    const docs = await cursor;
+    if (docs) {
+      return docs.map(
+        ({ _id, ...keepAttrs }) => keepAttrs
+      );
+    }
+    throw new common.ProsopoEnvError("DATABASE.SOLUTION_GET_FAILED");
+  }
+  async getDatasetIdWithSolvedCaptchasOfSizeN(solvedCaptchaCount) {
+    const cursor = this.tables?.solution.aggregate([
+      {
+        $match: {}
+      },
+      {
+        $group: {
+          _id: "$datasetId",
+          count: { $sum: 1 }
+        }
+      },
+      {
+        $match: {
+          count: { $gte: solvedCaptchaCount }
+        }
+      },
+      {
+        $sample: { size: 1 }
+      }
+    ]);
+    const docs = await cursor;
+    if (docs?.length) {
+      return docs[0]._id;
+    }
+    throw new common.ProsopoDBError("DATABASE.DATASET_WITH_SOLUTIONS_GET_FAILED");
+  }
+  async getRandomSolvedCaptchasFromSingleDataset(datasetId, size) {
+    if (!is.isHex(datasetId)) {
+      throw new common.ProsopoDBError("DATABASE.INVALID_HASH", {
+        context: {
+          failedFuncName: this.getRandomSolvedCaptchasFromSingleDataset.name,
+          datasetId
+        }
+      });
+    }
+    const sampleSize = size ? Math.abs(Math.trunc(size)) : 1;
+    const cursor = this.tables?.solution.aggregate([
+      { $match: { datasetId } },
+      { $sample: { size: sampleSize } },
+      {
+        $project: {
+          captchaId: 1,
+          captchaContentId: 1,
+          solution: 1
+        }
+      }
+    ]);
+    const docs = await cursor;
+    if (docs?.length) {
+      return docs;
+    }
+    throw new common.ProsopoDBError("DATABASE.SOLUTION_GET_FAILED", {
+      context: {
+        failedFuncName: this.getRandomSolvedCaptchasFromSingleDataset.name,
+        datasetId,
+        size
+      }
+    });
+  }
+  /**
+   * @description Get dapp user solution by ID
+   * @param {string[]} commitmentId
+   */
+  async getDappUserSolutionById(commitmentId) {
+    const cursor = this.tables?.usersolution?.findOne(
+      {
+        commitmentId
+      },
+      { projection: { _id: 0 } }
+    ).lean();
+    const doc = await cursor;
+    if (doc) {
+      return doc;
+    }
+    throw new common.ProsopoDBError("DATABASE.SOLUTION_GET_FAILED", {
+      context: { failedFuncName: this.getCaptchaById.name, commitmentId }
+    });
+  }
+  /**
+   * @description Get dapp user commitment by user account
+   * @param commitmentId
+   */
+  async getDappUserCommitmentById(commitmentId) {
+    const commitmentCursor = this.tables?.commitment?.findOne({ id: commitmentId }).lean();
+    const doc = await commitmentCursor;
+    return doc ? doc : void 0;
+  }
+  /**
+   * @description Get dapp user commitment by user account
+   * @param {string} userAccount
+   * @param {string} dappAccount
+   */
+  async getDappUserCommitmentByAccount(userAccount, dappAccount) {
+    const docs = await this.tables?.commitment?.find({ userAccount, dappAccount }, { _id: 0 }, { sort: { _id: -1 } }).lean();
+    return docs ? docs : [];
+  }
+  /**
+   * @description Approve a dapp user's solution
+   * @param {string[]} commitmentId
+   */
+  async approveDappUserCommitment(commitmentId) {
+    try {
+      const result = { status: types.CaptchaStatus.approved };
+      const updateDoc = {
+        result,
+        lastUpdatedTimestamp: Date.now()
+      };
+      await this.tables?.commitment?.findOneAndUpdate(
+        { id: commitmentId },
+        { $set: updateDoc },
+        { upsert: false }
+      ).lean();
+    } catch (err) {
+      throw new common.ProsopoDBError("DATABASE.SOLUTION_APPROVE_FAILED", {
+        context: { error: err, commitmentId }
+      });
+    }
+  }
+  /**
+   * @description Disapprove a dapp user's solution
+   * @param {string} commitmentId
+   * @param reason
+   */
+  async disapproveDappUserCommitment(commitmentId, reason) {
+    try {
+      const updateDoc = {
+        result: { status: types.CaptchaStatus.disapproved, reason },
+        lastUpdatedTimestamp: Date.now()
+      };
+      await this.tables?.commitment?.findOneAndUpdate(
+        { id: commitmentId },
+        { $set: updateDoc },
+        { upsert: false }
+      ).lean();
+    } catch (err) {
+      throw new common.ProsopoDBError("DATABASE.SOLUTION_APPROVE_FAILED", {
+        context: { error: err, commitmentId }
+      });
+    }
+  }
+  /**
+   * @description Flag a dapp user's solutions as used by calculated solution
+   * @param {string[]} captchaIds
+   */
+  async flagProcessedDappUserSolutions(captchaIds) {
+    try {
+      await this.tables?.usersolution?.updateMany(
+        { captchaId: { $in: captchaIds } },
+        { $set: { processed: true } },
+        { upsert: false }
+      ).lean();
+    } catch (err) {
+      throw new common.ProsopoDBError("DATABASE.SOLUTION_FLAG_FAILED", {
+        context: { error: err, captchaIds }
+      });
+    }
+  }
+  /**
+   * @description Flag dapp users' commitments as used by calculated solution
+   * @param {string[]} commitmentIds
+   */
+  async flagProcessedDappUserCommitments(commitmentIds) {
+    try {
+      const distinctCommitmentIds = [...new Set(commitmentIds)];
+      await this.tables?.commitment?.updateMany(
+        { id: { $in: distinctCommitmentIds } },
+        { $set: { processed: true } },
+        { upsert: false }
+      ).lean();
+    } catch (err) {
+      throw new common.ProsopoDBError("DATABASE.COMMITMENT_FLAG_FAILED", {
+        context: { error: err, commitmentIds }
+      });
+    }
+  }
+  /**
+   * @description Get a scheduled task status record by task ID and status
+   */
+  async getScheduledTaskStatus(taskId, status) {
+    const cursor = await this.tables?.scheduler?.findOne({ taskId, status }).lean();
+    return cursor ? cursor : void 0;
+  }
+  /**
+   * @description Get the most recent scheduled task status record for a given task
+   */
+  async getLastScheduledTaskStatus(task, status) {
+    const lookup = { processName: task };
+    if (status) {
+      lookup.status = status;
+    }
+    const cursor = await this.tables?.scheduler?.findOne(lookup).sort({ datetime: -1 }).limit(1).lean();
+    return cursor ? cursor : void 0;
+  }
+  /**
+   * @description Create the status of a scheduled task
+   */
+  async createScheduledTaskStatus(taskName, status) {
+    const now = (/* @__PURE__ */ new Date()).getTime();
+    const doc = typesDatabase.ScheduledTaskSchema.parse({
+      processName: taskName,
+      datetime: now,
+      status
+    });
+    const taskRecord = await this.tables?.scheduler.create(doc);
+    return taskRecord._id;
+  }
+  /**
+   * @description Update the status of a scheduled task and an optional result
+   */
+  async updateScheduledTaskStatus(taskId, status, result) {
+    const update = {
+      status,
+      updated: (/* @__PURE__ */ new Date()).getTime(),
+      ...result && { result }
+    };
+    await this.tables?.scheduler.updateOne(
+      { _id: taskId },
+      { $set: update },
+      {
+        upsert: false
+      }
+    );
+  }
+  /**
+   * @description Update the client records
+   */
+  async updateClientRecords(clientRecords) {
+    const ops = clientRecords.map((record) => {
+      const clientRecord = {
+        account: record.account,
+        settings: record.settings
+      };
+      return {
+        updateOne: {
+          filter: { account: record.account },
+          update: {
+            $set: clientRecord
+          },
+          upsert: true
+        }
+      };
+    });
+    await this.tables?.client.bulkWrite(ops);
+  }
+  /**
+   * @description Get a client record
+   */
+  async getClientRecord(account) {
+    const doc = await this.tables?.client.findOne({ account }).lean();
+    return doc ? doc : void 0;
+  }
+}
+exports.ProviderDatabase = ProviderDatabase;