@devtion/backend 0.0.0-09f6b45

package/dist/src/functions/index.mjs

@@ -0,0 +1,2588 @@
+/**
+ * @module @p0tion/backend
+ * @version 1.1.0
+ * @file MPC Phase 2 backend for Firebase services management
+ * @copyright Ethereum Foundation 2022
+ * @license MIT
+ * @see [Github]{@link https://github.com/privacy-scaling-explorations/p0tion}
+*/
+import admin from 'firebase-admin';
+import * as functions from 'firebase-functions';
+import dotenv from 'dotenv';
+import { getCircuitsCollectionPath, getTimeoutsCollectionPath, commonTerms, finalContributionIndex, getContributionsCollectionPath, githubReputation, getBucketName, vmBootstrapCommand, vmDependenciesAndCacheArtifactsCommand, vmBootstrapScriptFilename, computeDiskSizeForVM, createEC2Instance, getParticipantsCollectionPath, terminateEC2Instance, formatZkeyIndex, getTranscriptStorageFilePath, getZkeyStorageFilePath, startEC2Instance, vmContributionVerificationCommand, runCommandUsingSSM, getPotStorageFilePath, genesisZkeyIndex, createCustomLoggerForFile, blake512FromPath, getVerificationKeyStorageFilePath, getVerifierContractStorageFilePath, computeSHA256ToHex, checkIfRunning, retrieveCommandOutput, stopEC2Instance, verificationKeyAcronym, verifierSmartContractAcronym, retrieveCommandStatus } from '@p0tion/actions';
+import { encode } from 'html-entities';
+import { Timestamp, FieldValue } from 'firebase-admin/firestore';
+import { S3Client, GetObjectCommand, PutObjectCommand, DeleteObjectCommand, HeadBucketCommand, CreateBucketCommand, PutPublicAccessBlockCommand, PutBucketCorsCommand, HeadObjectCommand, CreateMultipartUploadCommand, UploadPartCommand, CompleteMultipartUploadCommand } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { createWriteStream } from 'node:fs';
+import { pipeline } from 'node:stream';
+import { promisify } from 'node:util';
+import fs, { readFileSync } from 'fs';
+import mime from 'mime-types';
+import { setTimeout as setTimeout$1 } from 'timers/promises';
+import fetch from '@adobe/node-fetch-retry';
+import path from 'path';
+import os from 'os';
+import { SSMClient, CommandInvocationStatus } from '@aws-sdk/client-ssm';
+import { EC2Client } from '@aws-sdk/client-ec2';
+import * as functionsV1 from 'firebase-functions/v1';
+import * as functionsV2 from 'firebase-functions/v2';
+import { Timer } from 'timer-node';
+import { zKey } from 'snarkjs';
+
+/**
+ * Log levels.
+ * @notice useful to discriminate the log level for message printing.
+ * @enum {string}
+ */
+var LogLevel;
+(function (LogLevel) {
+    LogLevel["INFO"] = "INFO";
+    LogLevel["DEBUG"] = "DEBUG";
+    LogLevel["WARN"] = "WARN";
+    LogLevel["ERROR"] = "ERROR";
+    LogLevel["LOG"] = "LOG";
+})(LogLevel || (LogLevel = {}));
+
+/**
+ * Create a new custom HTTPs error for cloud functions.
+ * @notice the set of Firebase Functions status codes. The codes are the same at the
+ * ones exposed by {@link https://github.com/grpc/grpc/blob/master/doc/statuscodes.md | gRPC}.
+ * @param errorCode <FunctionsErrorCode> - the set of possible error codes.
+ * @param message <string> - the error messge.
+ * @param [details] <string> - the details of the error (optional).
+ * @returns <HttpsError>
+ */
+const makeError = (errorCode, message, details) => new functions.https.HttpsError(errorCode, message, details);
+/**
+ * Log a custom message on console using a specific level.
+ * @param message <string> - the message to be shown.
+ * @param logLevel <LogLevel> - the level of the log to be used to show the message (e.g., debug, error).
+ */
+const printLog = (message, logLevel) => {
+    switch (logLevel) {
+        case LogLevel.INFO:
+            functions.logger.info(`[${logLevel}] ${message}`);
+            break;
+        case LogLevel.DEBUG:
+            functions.logger.debug(`[${logLevel}] ${message}`);
+            break;
+        case LogLevel.WARN:
+            functions.logger.warn(`[${logLevel}] ${message}`);
+            break;
+        case LogLevel.ERROR:
+            functions.logger.error(`[${logLevel}] ${message}`);
+            break;
+        case LogLevel.LOG:
+            functions.logger.log(`[${logLevel}] ${message}`);
+            break;
+        default:
+            console.log(`[${logLevel}] ${message}`);
+            break;
+    }
+};
+/**
+ * Log and throw an HTTPs error.
+ * @param error <HttpsError> - the error to be logged and thrown.
+ */
+const logAndThrowError = (error) => {
+    printLog(`${error.code}: ${error.message} ${!error.details ? "" : `\ndetails: ${error.details}`}`, LogLevel.ERROR);
+    throw error;
+};
+/**
+ * A set of Cloud Function specific errors.
+ * @notice these are errors that happen only on specific cloud functions.
+ */
+const SPECIFIC_ERRORS = {
+    SE_AUTH_NO_CURRENT_AUTH_USER: makeError("failed-precondition", "Unable to retrieve the authenticated user.", "Authenticated user information could not be retrieved. No document will be created in the relevant collection."),
+    SE_AUTH_SET_CUSTOM_USER_CLAIMS_FAIL: makeError("invalid-argument", "Unable to set custom claims for authenticated user."),
+    SE_AUTH_USER_NOT_REPUTABLE: makeError("permission-denied", "The authenticated user is not reputable.", "The authenticated user is not reputable. No document will be created in the relevant collection."),
+    SE_STORAGE_INVALID_BUCKET_NAME: makeError("already-exists", "Unable to create the AWS S3 bucket for the ceremony since the provided name is already in use. Please, provide a different bucket name for the ceremony.", "More info about the error could be found at the following link https://docs.aws.amazon.com/simspaceweaver/latest/userguide/troubleshooting_bucket-name-too-long.html"),
+    SE_STORAGE_TOO_MANY_BUCKETS: makeError("resource-exhausted", "Unable to create the AWS S3 bucket for the ceremony since the are too many buckets already in use. Please, delete 2 or more existing Amazon S3 buckets that you don't need or increase your limits.", "More info about the error could be found at the following link https://docs.aws.amazon.com/simspaceweaver/latest/userguide/troubeshooting_too-many-buckets.html"),
+    SE_STORAGE_MISSING_PERMISSIONS: makeError("permission-denied", "You do not have privileges to perform this operation.", "Authenticated user does not have proper permissions on AWS S3."),
+    SE_STORAGE_BUCKET_NOT_CONNECTED_TO_CEREMONY: makeError("not-found", "Unable to generate a pre-signed url for the given object in the provided bucket.", "The bucket is not associated with any valid ceremony document on the Firestore database."),
+    SE_STORAGE_WRONG_OBJECT_KEY: makeError("failed-precondition", "Unable to interact with a multi-part upload (start, create pre-signed urls or complete).", "The object key provided does not match the expected one."),
+    SE_STORAGE_CANNOT_INTERACT_WITH_MULTI_PART_UPLOAD: makeError("failed-precondition", "Unable to interact with a multi-part upload (start, create pre-signed urls or complete).", "Authenticated user is not a current contributor which is currently in the uploading step."),
+    SE_STORAGE_DOWNLOAD_FAILED: makeError("failed-precondition", "Unable to download the AWS S3 object from the provided ceremony bucket.", "This could happen if the file reference stored in the database or bucket turns out to be wrong or if the pre-signed url was not generated correctly."),
+    SE_STORAGE_UPLOAD_FAILED: makeError("failed-precondition", "Unable to upload the file to the AWS S3 ceremony bucket.", "This could happen if the local file or bucket do not exist or if the pre-signed url was not generated correctly."),
+    SE_STORAGE_DELETE_FAILED: makeError("failed-precondition", "Unable to delete the AWS S3 object from the provided ceremony bucket.", "This could happen if the local file or the bucket do not exist."),
+    SE_CONTRIBUTE_NO_CEREMONY_CIRCUITS: makeError("not-found", "There is no circuit associated with the ceremony.", "No documents in the circuits subcollection were found for the selected ceremony."),
+    SE_CONTRIBUTE_NO_OPENED_CEREMONIES: makeError("not-found", "There are no ceremonies open to contributions."),
+    SE_CONTRIBUTE_CANNOT_PROGRESS_TO_NEXT_CIRCUIT: makeError("failed-precondition", "Unable to progress to next circuit for contribution", "In order to progress for the contribution the participant must have just been registered for the ceremony or have just finished a contribution."),
+    SE_PARTICIPANT_CEREMONY_NOT_OPENED: makeError("failed-precondition", "Unable to progress to next contribution step.", "The ceremony does not appear to be opened"),
+    SE_PARTICIPANT_NOT_CONTRIBUTING: makeError("failed-precondition", "Unable to progress to next contribution step.", "This may happen due wrong contribution step from participant."),
+    SE_PARTICIPANT_CANNOT_STORE_PERMANENT_DATA: makeError("failed-precondition", "Unable to store contribution hash and computing time.", "This may happen due wrong contribution step from participant or missing coordinator permission (only when finalizing)."),
+    SE_PARTICIPANT_CANNOT_STORE_TEMPORARY_DATA: makeError("failed-precondition", "Unable to store temporary data to resume a multi-part upload.", "This may happen due wrong contribution step from participant."),
+    SE_VERIFICATION_NO_PARTICIPANT_CONTRIBUTION_DATA: makeError("not-found", `Unable to retrieve current contribution data from participant document.`),
+    SE_CEREMONY_CANNOT_FINALIZE_CEREMONY: makeError("failed-precondition", `Unable to finalize the ceremony.`, `Please, verify to have successfully completed the finalization of each circuit in the ceremony.`),
+    SE_FINALIZE_NO_CEREMONY_CONTRIBUTIONS: makeError("not-found", "There are no contributions associated with the ceremony circuit.", "No documents in the contributions subcollection were found for the selected ceremony circuit."),
+    SE_FINALIZE_NO_FINAL_CONTRIBUTION: makeError("not-found", "There is no final contribution associated with the ceremony circuit."),
+    SE_VM_NOT_RUNNING: makeError("failed-precondition", "The EC2 VM is not running yet"),
+    SE_VM_FAILED_COMMAND_EXECUTION: makeError("failed-precondition", "VM command execution failed", "Please, contact the coordinator if this error persists."),
+    SE_VM_TIMEDOUT_COMMAND_EXECUTION: makeError("deadline-exceeded", "VM command execution took too long and has been timed-out", "Please, contact the coordinator if this error persists."),
+    SE_VM_CANCELLED_COMMAND_EXECUTION: makeError("cancelled", "VM command execution has been cancelled", "Please, contact the coordinator if this error persists."),
+    SE_VM_DELAYED_COMMAND_EXECUTION: makeError("unavailable", "VM command execution has been delayed since there were no available instance at the moment", "Please, contact the coordinator if this error persists."),
+    SE_VM_UNKNOWN_COMMAND_STATUS: makeError("unavailable", "VM command execution has failed due to an unknown status code", "Please, contact the coordinator if this error persists.")
+};
+/**
+ * A set of common errors.
+ * @notice these are errors that happen on multiple cloud functions (e.g., auth, missing data).
+ */
+const COMMON_ERRORS = {
+    CM_NOT_COORDINATOR_ROLE: makeError("permission-denied", "You do not have privileges to perform this operation.", "Authenticated user does not have the coordinator role (missing custom claims)."),
+    CM_MISSING_OR_WRONG_INPUT_DATA: makeError("invalid-argument", "Unable to perform the operation due to incomplete or incorrect data."),
+    CM_WRONG_CONFIGURATION: makeError("failed-precondition", "Missing or incorrect configuration.", "This may happen due wrong environment configuration for the backend services."),
+    CM_NOT_AUTHENTICATED: makeError("failed-precondition", "You are not authorized to perform this operation.", "You could not perform the requested operation because you are not authenticated on the Firebase Application."),
+    CM_INEXISTENT_DOCUMENT: makeError("not-found", "Unable to find a document with the given identifier for the provided collection path."),
+    CM_INEXISTENT_DOCUMENT_DATA: makeError("not-found", "The provided document with the given identifier has no data associated with it.", "This problem may occur if the document has not yet been written in the database."),
+    CM_INVALID_CEREMONY_FOR_PARTICIPANT: makeError("not-found", "The participant does not seem to be related to a ceremony."),
+    CM_NO_CIRCUIT_FOR_GIVEN_SEQUENCE_POSITION: makeError("not-found", "Unable to find the circuit having the provided sequence position for the given ceremony"),
+    CM_INVALID_REQUEST: makeError("unknown", "Failed request."),
+    CM_INVALID_COMMAND_EXECUTION: makeError("unknown", "There was an error while executing the command on the VM", "Please, contact the coordinator if the error persists.")
+};
+
+/**
+ * Return a configured and connected instance of the AWS S3 client.
+ * @dev this method check and utilize the environment variables to configure the connection
+ * w/ the S3 client.
+ * @returns <Promise<S3Client>> - the instance of the connected S3 Client instance.
+ */
+const getS3Client = async () => {
+    if (!process.env.AWS_ACCESS_KEY_ID ||
+        !process.env.AWS_SECRET_ACCESS_KEY ||
+        !process.env.AWS_REGION ||
+        !process.env.AWS_PRESIGNED_URL_EXPIRATION ||
+        !process.env.AWS_CEREMONY_BUCKET_POSTFIX)
+        logAndThrowError(COMMON_ERRORS.CM_WRONG_CONFIGURATION);
+    // Return the connected S3 Client instance.
+    return new S3Client({
+        credentials: {
+            accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+            secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
+        },
+        region: process.env.AWS_REGION
+    });
+};
+
+dotenv.config();
+/**
+ * Get a specific document from database.
+ * @dev this method differs from the one in the `actions` package because we need to use
+ * the admin SDK here; therefore the Firestore instances are not interchangeable between admin
+ * and user instance.
+ * @param collection <string> - the name of the collection.
+ * @param documentId <string> - the unique identifier of the document in the collection.
+ * @returns <Promise<DocumentSnapshot<DocumentData>>> - the requested document w/ relative data.
+ */
+const getDocumentById = async (collection, documentId) => {
+    // Prepare Firestore db instance.
+    const firestore = admin.firestore();
+    // Get document.
+    const doc = await firestore.collection(collection).doc(documentId).get();
+    // Return only if doc exists; otherwise throw error.
+    return doc.exists ? doc : logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT);
+};
+/**
+ * Get the current server timestamp.
+ * @dev the value is in milliseconds.
+ * @returns <number> - the timestamp of the server (ms).
+ */
+const getCurrentServerTimestampInMillis = () => Timestamp.now().toMillis();
+/**
+ * Interrupt the current execution for a specified amount of time.
+ * @param ms <number> - the amount of time expressed in milliseconds.
+ */
+const sleep = async (ms) => setTimeout$1(ms);
+/**
+ * Query for ceremony circuits.
+ * @notice the order by sequence position is fundamental to maintain parallelism among contributions for different circuits.
+ * @param ceremonyId <string> - the unique identifier of the ceremony.
+ * @returns Promise<Array<FirebaseDocumentInfo>> - the ceremony' circuits documents ordered by sequence position.
+ */
+const getCeremonyCircuits = async (ceremonyId) => {
+    // Prepare Firestore db instance.
+    const firestore = admin.firestore();
+    // Execute query.
+    const querySnap = await firestore.collection(getCircuitsCollectionPath(ceremonyId)).get();
+    if (!querySnap.docs)
+        logAndThrowError(SPECIFIC_ERRORS.SE_CONTRIBUTE_NO_CEREMONY_CIRCUITS);
+    return querySnap.docs.sort((a, b) => a.data().sequencePosition - b.data().sequencePosition);
+};
+/**
+ * Query for ceremony circuit contributions.
+ * @param ceremonyId <string> - the unique identifier of the ceremony.
+ * @param circuitId <string> - the unique identifier of the circuitId.
+ * @returns Promise<Array<FirebaseDocumentInfo>> - the contributions of the ceremony circuit.
+ */
+const getCeremonyCircuitContributions = async (ceremonyId, circuitId) => {
+    // Prepare Firestore db instance.
+    const firestore = admin.firestore();
+    // Execute query.
+    const querySnap = await firestore.collection(getContributionsCollectionPath(ceremonyId, circuitId)).get();
+    if (!querySnap.docs)
+        logAndThrowError(SPECIFIC_ERRORS.SE_FINALIZE_NO_CEREMONY_CONTRIBUTIONS);
+    return querySnap.docs;
+};
+/**
+ * Query not expired timeouts.
+ * @notice a timeout is considered valid (aka not expired) if and only if the timeout end date
+ * value is less than current timestamp.
+ * @param ceremonyId <string> - the unique identifier of the ceremony.
+ * @param participantId <string> - the unique identifier of the participant.
+ * @returns <Promise<QuerySnapshot<DocumentData>>>
+ */
+const queryNotExpiredTimeouts = async (ceremonyId, participantId) => {
+    // Prepare Firestore db.
+    const firestoreDb = admin.firestore();
+    // Execute and return query result.
+    return firestoreDb
+        .collection(getTimeoutsCollectionPath(ceremonyId, participantId))
+        .where(commonTerms.collections.timeouts.fields.endDate, ">=", getCurrentServerTimestampInMillis())
+        .get();
+};
+/**
+ * Query for opened ceremonies.
+ * @param firestoreDatabase <Firestore> - the Firestore service instance associated to the current Firebase application.
+ * @returns <Promise<Array<FirebaseDocumentInfo>>>
+ */
+const queryOpenedCeremonies = async () => {
+    const querySnap = await admin
+        .firestore()
+        .collection(commonTerms.collections.ceremonies.name)
+        .where(commonTerms.collections.ceremonies.fields.state, "==", "OPENED" /* CeremonyState.OPENED */)
+        .where(commonTerms.collections.ceremonies.fields.endDate, ">=", getCurrentServerTimestampInMillis())
+        .get();
+    if (!querySnap.docs)
+        logAndThrowError(SPECIFIC_ERRORS.SE_CONTRIBUTE_NO_OPENED_CEREMONIES);
+    return querySnap.docs;
+};
+/**
+ * Get ceremony circuit document by sequence position.
+ * @param ceremonyId <string> - the unique identifier of the ceremony.
+ * @param sequencePosition <number> - the sequence position of the circuit.
+ * @returns Promise<QueryDocumentSnapshot<DocumentData>>
+ */
+const getCircuitDocumentByPosition = async (ceremonyId, sequencePosition) => {
+    // Query for all ceremony circuits.
+    const circuits = await getCeremonyCircuits(ceremonyId);
+    // Apply a filter using the sequence position.
+    const matchedCircuits = circuits.filter((circuit) => circuit.data().sequencePosition === sequencePosition);
+    if (matchedCircuits.length !== 1)
+        logAndThrowError(COMMON_ERRORS.CM_NO_CIRCUIT_FOR_GIVEN_SEQUENCE_POSITION);
+    return matchedCircuits.at(0);
+};
+/**
+ * Create a temporary file path in the virtual memory of the cloud function.
+ * @dev useful when downloading files from AWS S3 buckets for processing within cloud functions.
+ * @param completeFilename <string> - the complete file name (name + ext).
+ * @returns <string> - the path to the local temporary location.
+ */
+const createTemporaryLocalPath = (completeFilename) => path.join(os.tmpdir(), completeFilename);
+/**
+ * Download an artifact from the AWS S3 bucket.
+ * @dev this method uses streams.
+ * @param bucketName <string> - the name of the bucket.
+ * @param objectKey <string> - the unique key to identify the object inside the given AWS S3 bucket.
+ * @param localFilePath <string> - the local path where the file will be stored.
+ */
+const downloadArtifactFromS3Bucket = async (bucketName, objectKey, localFilePath) => {
+    // Prepare AWS S3 client instance.
+    const client = await getS3Client();
+    // Prepare command.
+    const command = new GetObjectCommand({ Bucket: bucketName, Key: objectKey });
+    // Generate a pre-signed url for downloading the file.
+    const url = await getSignedUrl(client, command, { expiresIn: Number(process.env.AWS_PRESIGNED_URL_EXPIRATION) });
+    // Execute download request.
+    // @ts-ignore
+    const response = await fetch(url, {
+        method: "GET",
+        headers: {
+            "Access-Control-Allow-Origin": "*"
+        }
+    });
+    if (response.status !== 200 || !response.ok)
+        logAndThrowError(SPECIFIC_ERRORS.SE_STORAGE_DOWNLOAD_FAILED);
+    // Write the file locally using streams.
+    const writeStream = createWriteStream(localFilePath);
+    const streamPipeline = promisify(pipeline);
+    await streamPipeline(response.body, writeStream);
+    writeStream.on("finish", () => {
+        writeStream.end();
+    });
+};
+/**
+ * Upload a new artifact to the AWS S3 bucket.
+ * @dev this method uses streams.
+ * @param bucketName <string> - the name of the bucket.
+ * @param objectKey <string> - the unique key to identify the object inside the given AWS S3 bucket.
+ * @param localFilePath <string> - the local path where the file to be uploaded is stored.
+ */
+const uploadFileToBucket = async (bucketName, objectKey, localFilePath, isPublic = false) => {
+    // Prepare AWS S3 client instance.
+    const client = await getS3Client();
+    // Extract content type.
+    const contentType = mime.lookup(localFilePath) || "";
+    // Prepare command.
+    const command = new PutObjectCommand({
+        Bucket: bucketName,
+        Key: objectKey,
+        ContentType: contentType,
+        ACL: isPublic ? "public-read" : "private"
+    });
+    // Generate a pre-signed url for uploading the file.
+    const url = await getSignedUrl(client, command, { expiresIn: Number(process.env.AWS_PRESIGNED_URL_EXPIRATION) });
+    // Execute upload request.
+    // @ts-ignore
+    const response = await fetch(url, {
+        method: "PUT",
+        body: readFileSync(localFilePath),
+        headers: { "Content-Type": contentType }
+    });
+    if (response.status !== 200 || !response.ok)
+        logAndThrowError(SPECIFIC_ERRORS.SE_STORAGE_UPLOAD_FAILED);
+};
+const uploadFileToBucketNoFile = async (bucketName, objectKey, data, isPublic = false) => {
+    // Prepare AWS S3 client instance.
+    const client = await getS3Client();
+    // Prepare command.
+    const command = new PutObjectCommand({
+        Bucket: bucketName,
+        Key: objectKey,
+        ContentType: "text/plain",
+        ACL: isPublic ? "public-read" : "private"
+    });
+    // Generate a pre-signed url for uploading the file.
+    const url = await getSignedUrl(client, command, { expiresIn: Number(process.env.AWS_PRESIGNED_URL_EXPIRATION) });
+    // Execute upload request.
+    // @ts-ignore
+    const response = await fetch(url, {
+        method: "PUT",
+        body: data,
+        headers: { "Content-Type": "text/plain" }
+    });
+    if (response.status !== 200 || !response.ok)
+        logAndThrowError(SPECIFIC_ERRORS.SE_STORAGE_UPLOAD_FAILED);
+};
+/**
+ * Upload an artifact from the AWS S3 bucket.
+ * @param bucketName <string> - the name of the bucket.
+ * @param objectKey <string> - the unique key to identify the object inside the given AWS S3 bucket.
+ */
+const deleteObject = async (bucketName, objectKey) => {
+    // Prepare AWS S3 client instance.
+    const client = await getS3Client();
+    // Prepare command.
+    const command = new DeleteObjectCommand({ Bucket: bucketName, Key: objectKey });
+    // Execute command.
+    const data = await client.send(command);
+    if (data.$metadata.httpStatusCode !== 204)
+        logAndThrowError(SPECIFIC_ERRORS.SE_STORAGE_DELETE_FAILED);
+};
+/**
+ * Query ceremonies by state and (start/end) date value.
+ * @param state <string> - the state of the ceremony.
+ * @param needToCheckStartDate <boolean> - flag to discriminate when to check startDate (true) or endDate (false).
+ * @param check <WhereFilerOp> - the type of filter (query check - e.g., '<' or '>').
+ * @returns <Promise<admin.firestore.QuerySnapshot<admin.firestore.DocumentData>>> - the queried ceremonies after filtering operation.
+ */
+const queryCeremoniesByStateAndDate = async (state, needToCheckStartDate, check) => admin
+    .firestore()
+    .collection(commonTerms.collections.ceremonies.name)
+    .where(commonTerms.collections.ceremonies.fields.state, "==", state)
+    .where(needToCheckStartDate
+    ? commonTerms.collections.ceremonies.fields.startDate
+    : commonTerms.collections.ceremonies.fields.endDate, check, getCurrentServerTimestampInMillis())
+    .get();
+/**
+ * Return the document associated with the final contribution for a ceremony circuit.
+ * @dev this method is useful during ceremony finalization.
+ * @param ceremonyId <string> -
+ * @param circuitId <string> -
+ * @returns Promise<QueryDocumentSnapshot<DocumentData>> - the final contribution for the ceremony circuit.
+ */
+const getFinalContribution = async (ceremonyId, circuitId) => {
+    // Get contributions for the circuit.
+    const contributions = await getCeremonyCircuitContributions(ceremonyId, circuitId);
+    // Match the final one.
+    const matchContribution = contributions.filter((contribution) => contribution.data().zkeyIndex === finalContributionIndex);
+    if (!matchContribution)
+        logAndThrowError(SPECIFIC_ERRORS.SE_FINALIZE_NO_FINAL_CONTRIBUTION);
+    // Get the final contribution.
+    // nb. there must be only one final contributions x circuit.
+    const finalContribution = matchContribution.at(0);
+    return finalContribution;
+};
+/**
+ * Helper function to HTML encode circuit data.
+ * @param circuitDocument <CircuitDocument> - the circuit document to be encoded.
+ * @returns <CircuitDocument> - the circuit document encoded.
+ */
+const htmlEncodeCircuitData = (circuitDocument) => ({
+    ...circuitDocument,
+    description: encode(circuitDocument.description),
+    name: encode(circuitDocument.name),
+    prefix: encode(circuitDocument.prefix)
+});
+/**
+ * Fetch the variables related to GitHub anti-sybil checks
+ * @returns <any> - the GitHub variables.
+ */
+const getGitHubVariables = () => {
+    if (!process.env.GITHUB_MINIMUM_FOLLOWERS ||
+        !process.env.GITHUB_MINIMUM_FOLLOWING ||
+        !process.env.GITHUB_MINIMUM_PUBLIC_REPOS ||
+        !process.env.GITHUB_MINIMUM_AGE)
+        logAndThrowError(COMMON_ERRORS.CM_WRONG_CONFIGURATION);
+    return {
+        minimumFollowers: Number(process.env.GITHUB_MINIMUM_FOLLOWERS),
+        minimumFollowing: Number(process.env.GITHUB_MINIMUM_FOLLOWING),
+        minimumPublicRepos: Number(process.env.GITHUB_MINIMUM_PUBLIC_REPOS),
+        minimumAge: Number(process.env.GITHUB_MINIMUM_AGE)
+    };
+};
+/**
+ * Fetch the variables related to EC2 verification
+ * @returns <any> - the AWS EC2 variables.
+ */
+const getAWSVariables = () => {
+    if (!process.env.AWS_ACCESS_KEY_ID ||
+        !process.env.AWS_SECRET_ACCESS_KEY ||
+        !process.env.AWS_INSTANCE_PROFILE_ARN ||
+        !process.env.AWS_AMI_ID ||
+        !process.env.AWS_SNS_TOPIC_ARN)
+        logAndThrowError(COMMON_ERRORS.CM_WRONG_CONFIGURATION);
+    return {
+        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+        region: process.env.AWS_REGION || "eu-central-1",
+        instanceProfileArn: process.env.AWS_INSTANCE_PROFILE_ARN,
+        amiId: process.env.AWS_AMI_ID,
+        snsTopic: process.env.AWS_SNS_TOPIC_ARN
+    };
+};
+/**
+ * Create an EC2 client object
+ * @returns <Promise<EC2Client>> an EC2 client
+ */
+const createEC2Client = async () => {
+    const { accessKeyId, secretAccessKey, region } = getAWSVariables();
+    const ec2 = new EC2Client({
+        credentials: {
+            accessKeyId,
+            secretAccessKey
+        },
+        region
+    });
+    return ec2;
+};
+/**
+ * Create an SSM client object
+ * @returns <Promise<SSMClient>> an SSM client
+ */
+const createSSMClient = async () => {
+    const { accessKeyId, secretAccessKey, region } = getAWSVariables();
+    const ssm = new SSMClient({
+        credentials: {
+            accessKeyId,
+            secretAccessKey
+        },
+        region
+    });
+    return ssm;
+};
+
+dotenv.config();
+/**
+ * Record the authenticated user information inside the Firestore DB upon authentication.
+ * @dev the data is recorded in a new document in the `users` collection.
+ * @notice this method is automatically triggered upon user authentication in the Firebase app
+ * which uses the Firebase Authentication service.
+ */
+const registerAuthUser = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .auth.user()
+    .onCreate(async (user) => {
+    // Get DB.
+    const firestore = admin.firestore();
+    // Get user information.
+    if (!user.uid)
+        logAndThrowError(SPECIFIC_ERRORS.SE_AUTH_NO_CURRENT_AUTH_USER);
+    // The user object has basic properties such as display name, email, etc.
+    const { displayName } = user;
+    const { email } = user;
+    const { photoURL } = user;
+    const { emailVerified } = user;
+    // Metadata.
+    const { creationTime } = user.metadata;
+    const { lastSignInTime } = user.metadata;
+    // The user's ID, unique to the Firebase project. Do NOT use
+    // this value to authenticate with your backend server, if
+    // you have one. Use User.getToken() instead.
+    const { uid } = user;
+    // Reference to a document using uid.
+    const userRef = firestore.collection(commonTerms.collections.users.name).doc(uid);
+    // html encode the display name (or put the ID if the name is not displayed)
+    const encodedDisplayName = user.displayName === "Null" || user.displayName === null ? user.uid : encode(displayName);
+    // store the avatar URL of a contributor
+    let avatarUrl = "";
+    // we only do reputation check if the user is not a coordinator
+    if (!(email?.endsWith(`@${process.env.CUSTOM_CLAIMS_COORDINATOR_EMAIL_ADDRESS_OR_DOMAIN}`) ||
+        email === process.env.CUSTOM_CLAIMS_COORDINATOR_EMAIL_ADDRESS_OR_DOMAIN)) {
+        const auth = admin.auth();
+        // if provider == github.com let's use our functions to check the user's reputation
+        if (user.providerData[0].providerId === "github.com") {
+            const vars = getGitHubVariables();
+            // this return true or false
+            try {
+                const { reputable, avatarUrl: avatarURL } = await githubReputation(user.providerData[0].uid, vars.minimumFollowing, vars.minimumFollowers, vars.minimumPublicRepos, vars.minimumAge);
+                if (!reputable) {
+                    // Delete user
+                    await auth.deleteUser(user.uid);
+                    // Throw error
+                    logAndThrowError(makeError("permission-denied", "The user is not allowed to sign up because their Github reputation is not high enough.", `The user ${user.displayName === "Null" || user.displayName === null
+                        ? user.uid
+                        : user.displayName} is not allowed to sign up because their Github reputation is not high enough. Please contact the administrator if you think this is a mistake.`));
+                }
+                // store locally
+                avatarUrl = avatarURL;
+                printLog(`Github reputation check passed for user ${user.displayName === "Null" || user.displayName === null ? user.uid : user.displayName}`, LogLevel.DEBUG);
+            }
+            catch (error) {
+                // Delete user
+                await auth.deleteUser(user.uid);
+                logAndThrowError(makeError("permission-denied", "There was an error while checking the user's Github reputation.", `${error}`));
+            }
+        }
+    }
+    // Set document (nb. we refer to providerData[0] because we use Github OAuth provider only).
+    // In future releases we might want to loop through the providerData array as we support
+    // more providers.
+    await userRef.set({
+        name: encodedDisplayName,
+        encodedDisplayName,
+        // Metadata.
+        creationTime,
+        lastSignInTime,
+        // Optional.
+        email: email || "",
+        emailVerified: emailVerified || false,
+        photoURL: photoURL || "",
+        lastUpdated: getCurrentServerTimestampInMillis()
+    });
+    // we want to create a new collection for the users to store the avatars
+    const avatarRef = firestore.collection(commonTerms.collections.avatars.name).doc(uid);
+    await avatarRef.set({
+        avatarUrl: avatarUrl || ""
+    });
+    printLog(`Authenticated user document with identifier ${uid} has been correctly stored`, LogLevel.DEBUG);
+    printLog(`Authenticated user avatar with identifier ${uid} has been correctly stored`, LogLevel.DEBUG);
+});
+/**
+ * Set custom claims for role-based access control on the newly created user.
+ * @notice this method is automatically triggered upon user authentication in the Firebase app
+ * which uses the Firebase Authentication service.
+ */
+const processSignUpWithCustomClaims = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .auth.user()
+    .onCreate(async (user) => {
+    // Get user information.
+    if (!user.uid)
+        logAndThrowError(SPECIFIC_ERRORS.SE_AUTH_NO_CURRENT_AUTH_USER);
+    // Prepare state.
+    let customClaims;
+    // Check if user meets role criteria to be a coordinator.
+    if (user.email &&
+        (user.email.endsWith(`@${process.env.CUSTOM_CLAIMS_COORDINATOR_EMAIL_ADDRESS_OR_DOMAIN}`) ||
+            user.email === process.env.CUSTOM_CLAIMS_COORDINATOR_EMAIL_ADDRESS_OR_DOMAIN)) {
+        customClaims = { coordinator: true };
+        printLog(`Authenticated user ${user.uid} has been identified as coordinator`, LogLevel.DEBUG);
+    }
+    else {
+        customClaims = { participant: true };
+        printLog(`Authenticated user ${user.uid} has been identified as participant`, LogLevel.DEBUG);
+    }
+    try {
+        // Set custom user claims on this newly created user.
+        await admin.auth().setCustomUserClaims(user.uid, customClaims);
+    }
+    catch (error) {
+        const specificError = SPECIFIC_ERRORS.SE_AUTH_SET_CUSTOM_USER_CLAIMS_FAIL;
+        const additionalDetails = error.toString();
+        logAndThrowError(makeError(specificError.code, specificError.message, additionalDetails));
+    }
+});
+
+dotenv.config();
+/**
+ * Make a scheduled ceremony open.
+ * @dev this function automatically runs every 30 minutes.
+ * @todo this methodology for transitioning a ceremony from `scheduled` to `opened` state will be replaced with one
+ * that resolves the issues presented in the issue #192 (https://github.com/quadratic-funding/mpc-phase2-suite/issues/192).
+ */
+const startCeremony = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .pubsub.schedule(`every 30 minutes`)
+    .onRun(async () => {
+    // Get ready to be opened ceremonies.
+    const scheduledCeremoniesQuerySnap = await queryCeremoniesByStateAndDate("SCHEDULED" /* CeremonyState.SCHEDULED */, true, "<=");
+    if (!scheduledCeremoniesQuerySnap.empty)
+        scheduledCeremoniesQuerySnap.forEach(async (ceremonyDoc) => {
+            // Make state transition to start ceremony.
+            await ceremonyDoc.ref.set({ state: "OPENED" /* CeremonyState.OPENED */ }, { merge: true });
+            printLog(`Ceremony ${ceremonyDoc.id} is now open`, LogLevel.DEBUG);
+        });
+});
+/**
+ * Make a scheduled ceremony close.
+ * @dev this function automatically runs every 30 minutes.
+ * @todo this methodology for transitioning a ceremony from `opened` to `closed` state will be replaced with one
+ * that resolves the issues presented in the issue #192 (https://github.com/quadratic-funding/mpc-phase2-suite/issues/192).
+ */
+const stopCeremony = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .pubsub.schedule(`every 30 minutes`)
+    .onRun(async () => {
+    // Get opened ceremonies.
+    const runningCeremoniesQuerySnap = await queryCeremoniesByStateAndDate("OPENED" /* CeremonyState.OPENED */, false, "<=");
+    if (!runningCeremoniesQuerySnap.empty) {
+        runningCeremoniesQuerySnap.forEach(async (ceremonyDoc) => {
+            // Make state transition to close ceremony.
+            await ceremonyDoc.ref.set({ state: "CLOSED" /* CeremonyState.CLOSED */ }, { merge: true });
+            printLog(`Ceremony ${ceremonyDoc.id} is now closed`, LogLevel.DEBUG);
+        });
+    }
+});
+/**
+ * Register all ceremony setup-related documents on the Firestore database.
+ * @dev this function will create a new document in the `ceremonies` collection and as needed `circuit`
+ * documents in the sub-collection.
+ */
+const setupCeremony = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .https.onCall(async (data, context) => {
+    // Check if the user has the coordinator claim.
+    if (!context.auth || !context.auth.token.coordinator)
+        logAndThrowError(COMMON_ERRORS.CM_NOT_COORDINATOR_ROLE);
+    // Validate the provided data.
+    if (!data.ceremonyInputData || !data.ceremonyPrefix || !data.circuits.length)
+        logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA);
+    // Prepare Firestore DB.
+    const firestore = admin.firestore();
+    const batch = firestore.batch();
+    // Prepare data.
+    const { ceremonyInputData, ceremonyPrefix, circuits } = data;
+    const userId = context.auth?.uid;
+    // Create a new ceremony document.
+    const ceremonyDoc = await firestore.collection(`${commonTerms.collections.ceremonies.name}`).doc().get();
+    // Prepare tx to write ceremony data.
+    batch.create(ceremonyDoc.ref, {
+        title: encode(ceremonyInputData.title),
+        description: encode(ceremonyInputData.description),
+        startDate: new Date(ceremonyInputData.startDate).valueOf(),
+        endDate: new Date(ceremonyInputData.endDate).valueOf(),
+        prefix: ceremonyPrefix,
+        state: "SCHEDULED" /* CeremonyState.SCHEDULED */,
+        type: "PHASE2" /* CeremonyType.PHASE2 */,
+        penalty: ceremonyInputData.penalty,
+        timeoutType: ceremonyInputData.timeoutMechanismType,
+        coordinatorId: userId,
+        lastUpdated: getCurrentServerTimestampInMillis()
+    });
+    // Get the bucket name so we can upload the startup script
+    const bucketName = getBucketName(ceremonyPrefix, String(process.env.AWS_CEREMONY_BUCKET_POSTFIX));
+    // Create a new circuit document (circuits ceremony document sub-collection).
+    for (let circuit of circuits) {
+        // The VM unique identifier (if any).
+        let vmInstanceId = "";
+        // Get a new circuit document.
+        const circuitDoc = await firestore.collection(getCircuitsCollectionPath(ceremonyDoc.ref.id)).doc().get();
+        // Check if using the VM approach for contribution verification.
+        if (circuit.verification.cfOrVm === "VM" /* CircuitContributionVerificationMechanism.VM */) {
+            // VM command to be run at the startup.
+            const startupCommand = vmBootstrapCommand(`${bucketName}/circuits/${circuit.name}`);
+            // Get EC2 client.
+            const ec2Client = await createEC2Client();
+            // Get AWS variables.
+            const { snsTopic, region } = getAWSVariables();
+            // Prepare dependencies and cache artifacts command.
+            const vmCommands = vmDependenciesAndCacheArtifactsCommand(`${bucketName}/${circuit.files?.initialZkeyStoragePath}`, `${bucketName}/${circuit.files?.potStoragePath}`, snsTopic, region);
+            printLog(`Check VM dependencies and cache artifacts commands ${vmCommands.join("\n")}`, LogLevel.DEBUG);
+            // Upload the post-startup commands script file.
+            printLog(`Uploading VM post-startup commands script file ${vmBootstrapScriptFilename}`, LogLevel.DEBUG);
+            await uploadFileToBucketNoFile(bucketName, `circuits/${circuit.name}/${vmBootstrapScriptFilename}`, vmCommands.join("\n"));
+            // Compute the VM disk space requirement (in GB).
+            const vmDiskSize = computeDiskSizeForVM(circuit.zKeySizeInBytes, circuit.metadata?.pot);
+            printLog(`Check VM startup commands ${startupCommand.join("\n")}`, LogLevel.DEBUG);
+            // Configure and instantiate a new VM based on the coordinator input.
+            const instance = await createEC2Instance(ec2Client, startupCommand, circuit.verification.vm?.vmConfigurationType, vmDiskSize, circuit.verification.vm?.vmDiskType);
+            // Get the VM instance identifier.
+            vmInstanceId = instance.instanceId;
+            // Update the circuit document info accordingly.
+            circuit = {
+                ...circuit,
+                verification: {
+                    cfOrVm: circuit.verification.cfOrVm,
+                    vm: {
+                        vmConfigurationType: circuit.verification.vm?.vmConfigurationType,
+                        vmDiskSize,
+                        vmInstanceId
+                    }
+                }
+            };
+        }
+        // Encode circuit data.
+        const encodedCircuit = htmlEncodeCircuitData(circuit);
+        // Prepare tx to write circuit data.
+        batch.create(circuitDoc.ref, {
+            ...encodedCircuit,
+            lastUpdated: getCurrentServerTimestampInMillis()
+        });
+    }
+    // Send txs in a batch (to avoid race conditions).
+    await batch.commit();
+    printLog(`Setup completed for ceremony ${ceremonyDoc.id}`, LogLevel.DEBUG);
+    return ceremonyDoc.id;
+});
+/**
+ * Prepare all the necessary information needed for initializing the waiting queue of a circuit.
+ * @dev this function will add a new field `waitingQueue` in the newly created circuit document.
+ */
+const initEmptyWaitingQueueForCircuit = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .firestore.document(`/${commonTerms.collections.ceremonies.name}/{ceremony}/${commonTerms.collections.circuits.name}/{circuit}`)
+    .onCreate(async (doc) => {
+    // Prepare Firestore DB.
+    const firestore = admin.firestore();
+    // Get circuit document identifier and data.
+    const circuitId = doc.id;
+    // Get parent ceremony collection path.
+    const parentCollectionPath = doc.ref.parent.path; // == /ceremonies/{ceremony}/circuits/.
+    // Define an empty waiting queue.
+    const emptyWaitingQueue = {
+        contributors: [],
+        currentContributor: "",
+        completedContributions: 0,
+        failedContributions: 0
+    };
+    // Update the circuit document.
+    await firestore.collection(parentCollectionPath).doc(circuitId).set({
+        waitingQueue: emptyWaitingQueue,
+        lastUpdated: getCurrentServerTimestampInMillis()
+    }, { merge: true });
+    printLog(`An empty waiting queue has been successfully initialized for circuit ${circuitId} which belongs to ceremony ${doc.id}`, LogLevel.DEBUG);
+});
+/**
+ * Conclude the finalization of the ceremony.
+ * @dev checks that the ceremony is closed (= CLOSED), the coordinator is finalizing and has already
+ * provided the final contribution for each ceremony circuit.
+ */
+const finalizeCeremony = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .https.onCall(async (data, context) => {
+    if (!context.auth || !context.auth.token.coordinator)
+        logAndThrowError(COMMON_ERRORS.CM_NOT_COORDINATOR_ROLE);
+    if (!data.ceremonyId)
+        logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA);
+    // Prepare Firestore DB.
+    const firestore = admin.firestore();
+    const batch = firestore.batch();
+    // Extract data.
+    const { ceremonyId } = data;
+    const userId = context.auth?.uid;
+    // Look for the ceremony document.
+    const ceremonyDoc = await getDocumentById(commonTerms.collections.ceremonies.name, ceremonyId);
+    const participantDoc = await getDocumentById(getParticipantsCollectionPath(ceremonyId), userId);
+    if (!ceremonyDoc.data() || !participantDoc.data())
+        logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA);
+    // Get ceremony circuits.
+    const circuits = await getCeremonyCircuits(ceremonyId);
+    // Get final contribution for each circuit.
+    // nb. the `getFinalContributionDocument` checks the existance of the final contribution document (if not present, throws).
+    // Therefore, we just need to call the method without taking any data to verify the pre-condition of having already computed
+    // the final contributions for each ceremony circuit.
+    for await (const circuit of circuits)
+        await getFinalContribution(ceremonyId, circuit.id);
+    // Extract data.
+    const { state } = ceremonyDoc.data();
+    const { status } = participantDoc.data();
+    // Pre-conditions: verify the ceremony is closed and coordinator is finalizing.
+    if (state === "CLOSED" /* CeremonyState.CLOSED */ && status === "FINALIZING" /* ParticipantStatus.FINALIZING */) {
+        // Prepare txs for updates.
+        batch.update(ceremonyDoc.ref, { state: "FINALIZED" /* CeremonyState.FINALIZED */ });
+        batch.update(participantDoc.ref, {
+            status: "FINALIZED" /* ParticipantStatus.FINALIZED */
+        });
+        // Check for VM termination (if any).
+        for (const circuit of circuits) {
+            const circuitData = circuit.data();
+            const { verification } = circuitData;
+            if (verification.cfOrVm === "VM" /* CircuitContributionVerificationMechanism.VM */) {
+                // Prepare EC2 client.
+                const ec2Client = await createEC2Client();
+                const { vm } = verification;
+                await terminateEC2Instance(ec2Client, vm.vmInstanceId);
+            }
+        }
+        // Send txs.
+        await batch.commit();
+        printLog(`Ceremony ${ceremonyDoc.id} correctly finalized - Coordinator ${participantDoc.id}`, LogLevel.INFO);
+    }
+    else
+        logAndThrowError(SPECIFIC_ERRORS.SE_CEREMONY_CANNOT_FINALIZE_CEREMONY);
+});
+
+dotenv.config();
+/**
+ * Check the user's current participant status for the ceremony.
+ * @notice this cloud function has several tasks:
+ * 1) Check if the authenticated user is a participant
+ * 1.A) If not, register it has new participant for the ceremony.
+ * 1.B) Otherwise:
+ * 2.A) Check if already contributed to all circuits or,
+ * 3.A) If already contributed, return false
+ * 2.B) Check if it has a timeout in progress
+ * 3.B) If timeout expired, allows the participant to resume the contribution and remove stale/outdated
+ * temporary data.
+ * 3.C) Otherwise, return false.
+ * 2.C) Check if there are temporary stale contribution data if the contributor has interrupted the contribution
+ * while completing the `COMPUTING` step and, if any, delete them.
+ * 1.D) If no timeout / participant already exist, just return true.
+ * @dev true when the participant can participate (1.A, 3.B, 1.D); otherwise false.
+ */
+const checkParticipantForCeremony = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .https.onCall(async (data, context) => {
+    if (!context.auth || (!context.auth.token.participant && !context.auth.token.coordinator))
+        logAndThrowError(SPECIFIC_ERRORS.SE_AUTH_NO_CURRENT_AUTH_USER);
+    if (!data.ceremonyId)
+        logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA);
+    // Prepare Firestore DB.
+    const firestore = admin.firestore();
+    // Get data.
+    const { ceremonyId } = data;
+    const userId = context.auth?.uid;
+    // Look for the ceremony document.
+    const ceremonyDoc = await getDocumentById(commonTerms.collections.ceremonies.name, ceremonyId);
+    // Extract data.
+    const ceremonyData = ceremonyDoc.data();
+    const { state } = ceremonyData;
+    if (!ceremonyData)
+        logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA);
+    // Check pre-condition (ceremony state opened).
+    if (state !== "OPENED" /* CeremonyState.OPENED */)
+        logAndThrowError(SPECIFIC_ERRORS.SE_PARTICIPANT_CEREMONY_NOT_OPENED);
+    // Check (1).
+    // nb. do not use `getDocumentById()` here as we need the falsy condition.
+    const participantDoc = await firestore.collection(getParticipantsCollectionPath(ceremonyId)).doc(userId).get();
+    if (!participantDoc.exists) {
+        // Action (1.A).
+        const participantData = {
+            userId: participantDoc.id,
+            status: "WAITING" /* ParticipantStatus.WAITING */,
+            contributionProgress: 0,
+            contributionStartedAt: 0,
+            contributions: [],
+            lastUpdated: getCurrentServerTimestampInMillis()
+        };
+        // Register user as participant.
+        await participantDoc.ref.set(participantData);
+        printLog(`The user ${userId} has been registered as participant for ceremony ${ceremonyDoc.id}`, LogLevel.DEBUG);
+        return true;
+    }
+    // Check (1.B).
+    // Extract data.
+    const participantData = participantDoc.data();
+    const { contributionProgress, contributionStep, contributions, status, tempContributionData } = participantData;
+    if (!participantData)
+        logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA);
+    // Get ceremony' circuits.
+    const circuits = await getCeremonyCircuits(ceremonyDoc.id);
+    // Check (2.A).
+    if (contributionProgress === circuits.length && status === "DONE" /* ParticipantStatus.DONE */) {
+        // Action (3.A).
+        printLog(`Contributor ${participantDoc.id} has already contributed to all circuits`, LogLevel.DEBUG);
+        return false;
+    }
+    // Pre-conditions.
+    const staleContributionData = contributionProgress >= 1 && contributions.length === contributionProgress;
+    const wasComputing = !!contributionStep && contributionStep === "COMPUTING" /* ParticipantContributionStep.COMPUTING */;
+    // Check (2.B).
+    if (status === "TIMEDOUT" /* ParticipantStatus.TIMEDOUT */) {
+        // Query for not expired timeouts.
+        const notExpiredTimeouts = await queryNotExpiredTimeouts(ceremonyDoc.id, participantDoc.id);
+        if (notExpiredTimeouts.empty) {
+            // nb. stale contribution data is always the latest contribution.
+            if (staleContributionData)
+                contributions.pop();
+            // Action (3.B).
+            participantDoc.ref.update({
+                status: "EXHUMED" /* ParticipantStatus.EXHUMED */,
+                contributions,
+                tempContributionData: tempContributionData || FieldValue.delete(),
+                contributionStep: "DOWNLOADING" /* ParticipantContributionStep.DOWNLOADING */,
+                contributionStartedAt: 0,
+                verificationStartedAt: FieldValue.delete(),
+                lastUpdated: getCurrentServerTimestampInMillis()
+            });
+            printLog(`Timeout expired for participant ${participantDoc.id}`, LogLevel.DEBUG);
+            return true;
+        }
+        // Action (3.C).
+        printLog(`Timeout still in effect for the participant ${participantDoc.id}`, LogLevel.DEBUG);
+        return false;
+    }
+    // Check (2.C).
+    if (staleContributionData && wasComputing) {
+        // nb. stale contribution data is always the latest contribution.
+        contributions.pop();
+        participantDoc.ref.update({
+            contributions,
+            lastUpdated: getCurrentServerTimestampInMillis()
+        });
+        printLog(`Removed stale contribution data for ${participantDoc.id}`, LogLevel.DEBUG);
+    }
+    // Action (1.D).
+    return true;
+});
+/**
+ * Progress the participant to the next circuit preparing for the next contribution.
+ * @dev The participant can progress if and only if:
+ * 1) the participant has just been registered and is waiting to be queued for the first contribution (contributionProgress = 0 && status = WAITING).
+ * 2) the participant has just finished the contribution for a circuit (contributionProgress != 0 && status = CONTRIBUTED && contributionStep = COMPLETED).
+ */
+const progressToNextCircuitForContribution = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .https.onCall(async (data, context) => {
+    if (!context.auth || (!context.auth.token.participant && !context.auth.token.coordinator))
+        logAndThrowError(SPECIFIC_ERRORS.SE_AUTH_NO_CURRENT_AUTH_USER);
+    if (!data.ceremonyId)
+        logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA);
+    // Get data.
+    const { ceremonyId } = data;
+    const userId = context.auth?.uid;
+    // Look for the ceremony document.
+    const ceremonyDoc = await getDocumentById(commonTerms.collections.ceremonies.name, ceremonyId);
+    const participantDoc = await getDocumentById(getParticipantsCollectionPath(ceremonyId), userId);
+    // Prepare documents data.
+    const participantData = participantDoc.data();
+    if (!ceremonyDoc.data() || !participantData)
+        logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA);
+    // Extract data.
+    const { contributionProgress, contributionStep, status } = participantData;
+    // Define pre-conditions.
+    const waitingToBeQueuedForFirstContribution = status === "WAITING" /* ParticipantStatus.WAITING */ && contributionProgress === 0;
+    const completedContribution = status === "CONTRIBUTED" /* ParticipantStatus.CONTRIBUTED */ &&
+        contributionStep === "COMPLETED" /* ParticipantContributionStep.COMPLETED */ &&
+        contributionProgress !== 0;
+    // Check pre-conditions (1) or (2).
+    if (completedContribution || waitingToBeQueuedForFirstContribution)
+        await participantDoc.ref.update({
+            contributionProgress: contributionProgress + 1,
+            status: "READY" /* ParticipantStatus.READY */,
+            lastUpdated: getCurrentServerTimestampInMillis()
+        });
+    else
+        logAndThrowError(SPECIFIC_ERRORS.SE_CONTRIBUTE_CANNOT_PROGRESS_TO_NEXT_CIRCUIT);
+    printLog(`Participant/Contributor ${userId} progress to the circuit in position ${contributionProgress + 1}`, LogLevel.DEBUG);
+});
+/**
+ * Progress the participant to the next contribution step while contributing to a circuit.
+ * @dev this cloud function must enforce the order among the contribution steps:
+ * 1) Downloading the last contribution.
+ * 2) Computing the next contribution.
+ * 3) Uploading the next contribution.
+ * 4) Requesting the verification to the cloud function `verifycontribution`.
+ * 5) Completed contribution computation and verification.
+ */
+const progressToNextContributionStep = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .https.onCall(async (data, context) => {
+    if (!context.auth || (!context.auth.token.participant && !context.auth.token.coordinator))
+        logAndThrowError(SPECIFIC_ERRORS.SE_AUTH_NO_CURRENT_AUTH_USER);
+    if (!data.ceremonyId)
+        logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA);
+    // Get data.
+    const { ceremonyId } = data;
+    const userId = context.auth?.uid;
+    // Look for the ceremony document.
+    const ceremonyDoc = await getDocumentById(commonTerms.collections.ceremonies.name, ceremonyId);
+    const participantDoc = await getDocumentById(getParticipantsCollectionPath(ceremonyDoc.id), userId);
+    if (!ceremonyDoc.data() || !participantDoc.data())
+        logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA);
+    // Extract data.
+    const { state } = ceremonyDoc.data();
+    const { status, contributionStep } = participantDoc.data();
+    // Pre-condition: ceremony must be opened.
+    if (state !== "OPENED" /* CeremonyState.OPENED */)
+        logAndThrowError(SPECIFIC_ERRORS.SE_PARTICIPANT_CEREMONY_NOT_OPENED);
+    // Pre-condition: participant has contributing status.
+    if (status !== "CONTRIBUTING" /* ParticipantStatus.CONTRIBUTING */)
+        logAndThrowError(SPECIFIC_ERRORS.SE_PARTICIPANT_NOT_CONTRIBUTING);
+    // Prepare the next contribution step.
+    let nextContributionStep = contributionStep;
+    if (contributionStep === "DOWNLOADING" /* ParticipantContributionStep.DOWNLOADING */)
+        nextContributionStep = "COMPUTING" /* ParticipantContributionStep.COMPUTING */;
+    else if (contributionStep === "COMPUTING" /* ParticipantContributionStep.COMPUTING */)
+        nextContributionStep = "UPLOADING" /* ParticipantContributionStep.UPLOADING */;
+    else if (contributionStep === "UPLOADING" /* ParticipantContributionStep.UPLOADING */)
+        nextContributionStep = "VERIFYING" /* ParticipantContributionStep.VERIFYING */;
+    else if (contributionStep === "VERIFYING" /* ParticipantContributionStep.VERIFYING */)
+        nextContributionStep = "COMPLETED" /* ParticipantContributionStep.COMPLETED */;
+    // Send tx.
+    await participantDoc.ref.update({
+        contributionStep: nextContributionStep,
+        verificationStartedAt: nextContributionStep === "VERIFYING" /* ParticipantContributionStep.VERIFYING */
+            ? getCurrentServerTimestampInMillis()
+            : 0,
+        lastUpdated: getCurrentServerTimestampInMillis()
+    });
+    printLog(`Participant ${participantDoc.id} advanced to ${nextContributionStep} contribution step`, LogLevel.DEBUG);
+});
+/**
+ * Write the information about current contribution hash and computation time for the current contributor.
+ * @dev enable the current contributor to resume a contribution from where it had left off.
+ */
+const permanentlyStoreCurrentContributionTimeAndHash = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .https.onCall(async (data, context) => {
+    if (!context.auth || (!context.auth.token.participant && !context.auth.token.coordinator))
+        logAndThrowError(SPECIFIC_ERRORS.SE_AUTH_NO_CURRENT_AUTH_USER);
+    if (!data.ceremonyId || !data.contributionHash || data.contributionComputationTime <= 0)
+        logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA);
+    // Get data.
+    const { ceremonyId } = data;
+    const userId = context.auth?.uid;
+    const isCoordinator = context?.auth?.token.coordinator;
+    // Look for the ceremony document.
+    const ceremonyDoc = await getDocumentById(commonTerms.collections.ceremonies.name, ceremonyId);
+    const participantDoc = await getDocumentById(getParticipantsCollectionPath(ceremonyDoc.id), userId);
+    if (!ceremonyDoc.data() || !participantDoc.data())
+        logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA);
+    // Extract data.
+    const { status, contributionStep, contributions: currentContributions } = participantDoc.data();
+    // Pre-condition: computing contribution step or finalizing (only for coordinator when finalizing ceremony).
+    if (contributionStep === "COMPUTING" /* ParticipantContributionStep.COMPUTING */ ||
+        (isCoordinator && status === "FINALIZING" /* ParticipantStatus.FINALIZING */))
+        // Send tx.
+        await participantDoc.ref.set({
+            contributions: [
+                ...currentContributions,
+                {
+                    hash: data.contributionHash,
+                    computationTime: data.contributionComputationTime
+                }
+            ]
+        }, { merge: true });
+    else
+        logAndThrowError(SPECIFIC_ERRORS.SE_PARTICIPANT_CANNOT_STORE_PERMANENT_DATA);
+    printLog(`Participant ${participantDoc.id} has successfully stored the contribution hash ${data.contributionHash} and computation time ${data.contributionComputationTime}`, LogLevel.DEBUG);
+});
+/**
+ * Write temporary information about the unique identifier about the opened multi-part upload to eventually resume the contribution.
+ * @dev enable the current contributor to resume a multi-part upload from where it had left off.
+ */
+const temporaryStoreCurrentContributionMultiPartUploadId = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .https.onCall(async (data, context) => {
+    if (!context.auth || (!context.auth.token.participant && !context.auth.token.coordinator))
+        logAndThrowError(SPECIFIC_ERRORS.SE_AUTH_NO_CURRENT_AUTH_USER);
+    if (!data.ceremonyId || !data.uploadId)
+        logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA);
+    // Get data.
+    const { ceremonyId, uploadId } = data;
+    const userId = context.auth?.uid;
+    // Look for the ceremony document.
+    const ceremonyDoc = await getDocumentById(commonTerms.collections.ceremonies.name, ceremonyId);
+    const participantDoc = await getDocumentById(getParticipantsCollectionPath(ceremonyDoc.id), userId);
+    if (!ceremonyDoc.data() || !participantDoc.data())
+        logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA);
+    // Extract data.
+    const { contributionStep, tempContributionData: currentTempContributionData } = participantDoc.data();
+    // Pre-condition: check if the current contributor has uploading contribution step.
+    if (contributionStep !== "UPLOADING" /* ParticipantContributionStep.UPLOADING */)
+        logAndThrowError(SPECIFIC_ERRORS.SE_PARTICIPANT_CANNOT_STORE_TEMPORARY_DATA);
+    // Send tx.
+    await participantDoc.ref.set({
+        tempContributionData: {
+            ...currentTempContributionData,
+            uploadId,
+            chunks: []
+        },
+        lastUpdated: getCurrentServerTimestampInMillis()
+    }, { merge: true });
+    printLog(`Participant ${participantDoc.id} has successfully stored the temporary data for ${uploadId} multi-part upload`, LogLevel.DEBUG);
+});
+/**
+ * Write temporary information about the etags and part numbers for each uploaded chunk in order to make the upload resumable from last chunk.
+ * @dev enable the current contributor to resume a multi-part upload from where it had left off.
+ */
+const temporaryStoreCurrentContributionUploadedChunkData = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .https.onCall(async (data, context) => {
+    if (!context.auth || (!context.auth.token.participant && !context.auth.token.coordinator))
+        logAndThrowError(SPECIFIC_ERRORS.SE_AUTH_NO_CURRENT_AUTH_USER);
+    if (!data.ceremonyId || !data.chunk)
+        logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA);
+    // Get data.
+    const { ceremonyId, chunk } = data;
+    const userId = context.auth?.uid;
+    // Look for the ceremony document.
+    const ceremonyDoc = await getDocumentById(commonTerms.collections.ceremonies.name, ceremonyId);
+    const participantDoc = await getDocumentById(getParticipantsCollectionPath(ceremonyDoc.id), userId);
+    if (!ceremonyDoc.data() || !participantDoc.data())
+        logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA);
+    // Extract data.
+    const { contributionStep, tempContributionData: currentTempContributionData } = participantDoc.data();
+    // Pre-condition: check if the current contributor has uploading contribution step.
+    if (contributionStep !== "UPLOADING" /* ParticipantContributionStep.UPLOADING */)
+        logAndThrowError(SPECIFIC_ERRORS.SE_PARTICIPANT_CANNOT_STORE_TEMPORARY_DATA);
+    // Get already uploaded chunks.
+    const chunks = currentTempContributionData.chunks ? currentTempContributionData.chunks : [];
+    // Push last chunk.
+    chunks.push(chunk);
+    // Update.
+    await participantDoc.ref.set({
+        tempContributionData: {
+            ...currentTempContributionData,
+            chunks
+        },
+        lastUpdated: getCurrentServerTimestampInMillis()
+    }, { merge: true });
+    printLog(`Participant ${participantDoc.id} has successfully stored the temporary uploaded chunk data: ETag ${chunk.ETag} and PartNumber ${chunk.PartNumber}`, LogLevel.DEBUG);
+});
+/**
+ * Prepare the coordinator for the finalization of the ceremony.
+ * @dev checks that the ceremony is closed (= CLOSED) and that the coordinator has already +
+ * contributed to every selected ceremony circuits (= DONE).
+ */
+const checkAndPrepareCoordinatorForFinalization = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .https.onCall(async (data, context) => {
+    if (!context.auth || !context.auth.token.coordinator)
+        logAndThrowError(COMMON_ERRORS.CM_NOT_COORDINATOR_ROLE);
+    if (!data.ceremonyId)
+        logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA);
+    // Get data.
+    const { ceremonyId } = data;
+    const userId = context.auth?.uid;
+    // Look for the ceremony document.
+    const ceremonyDoc = await getDocumentById(commonTerms.collections.ceremonies.name, ceremonyId);
+    const participantDoc = await getDocumentById(getParticipantsCollectionPath(ceremonyId), userId);
+    if (!ceremonyDoc.data() || !participantDoc.data())
+        logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA);
+    // Get ceremony circuits.
+    const circuits = await getCeremonyCircuits(ceremonyId);
+    // Extract data.
+    const { state } = ceremonyDoc.data();
+    const { contributionProgress, status } = participantDoc.data();
+    // Check pre-conditions.
+    if (state === "CLOSED" /* CeremonyState.CLOSED */ &&
+        status === "DONE" /* ParticipantStatus.DONE */ &&
+        contributionProgress === circuits.length) {
+        // Make coordinator ready for finalization.
+        await participantDoc.ref.set({
+            status: "FINALIZING" /* ParticipantStatus.FINALIZING */,
+            lastUpdated: getCurrentServerTimestampInMillis()
+        }, { merge: true });
+        printLog(`The coordinator ${participantDoc.id} is now ready to finalize the ceremony ${ceremonyId}.`, LogLevel.DEBUG);
+        return true;
+    }
+    printLog(`The coordinator ${participantDoc.id} is not ready to finalize the ceremony ${ceremonyId}.`, LogLevel.DEBUG);
+    return false;
+});
+
+dotenv.config();
+/**
+ * Execute the coordination of the participant for the given circuit.
+ * @dev possible coordination scenarios:
+ * A) The participant becomes the current contributor of circuit X (single participant).
+ * B) The participant is placed in the contribution waiting queue because someone else is currently contributing to circuit X (single participant)
+ * C) The participant is removed as current contributor from Circuit X and gets coordinated for Circuit X + 1 (multi-participant).
+ *    C.1) The first participant in the waiting queue for Circuit X (if any), becomes the new contributor for circuit X.
+ * @param participant <QueryDocumentSnapshot> - the Firestore document of the participant.
+ * @param circuit <QueryDocumentSnapshot> - the Firestore document of the circuit.
+ * @param isSingleParticipantCoordination <boolean> - true if the coordination involves only a single participant; otherwise false (= involves multiple participant).
+ * @param [ceremonyId] <string> - the unique identifier of the ceremony (needed only for multi-participant coordination).
+ */
+const coordinate = async (participant, circuit, isSingleParticipantCoordination, ceremonyId) => {
+    // Prepare db and transactions batch.
+    const firestore = admin.firestore();
+    const batch = firestore.batch();
+    // Extract data.
+    const { status, contributionStep } = participant.data();
+    const { waitingQueue } = circuit.data();
+    const { contributors, currentContributor } = waitingQueue;
+    // Prepare state updates for waiting queue.
+    const newContributors = contributors;
+    let newCurrentContributorId = "";
+    // Prepare state updates for participant.
+    let newParticipantStatus = "";
+    let newContributionStep = "";
+    // Prepare pre-conditions.
+    const noCurrentContributor = !currentContributor;
+    const noContributorsInWaitingQueue = !contributors.length;
+    const emptyWaitingQueue = noCurrentContributor && noContributorsInWaitingQueue;
+    const participantIsNotCurrentContributor = currentContributor !== participant.id;
+    const participantIsCurrentContributor = currentContributor === participant.id;
+    const participantIsReady = status === "READY" /* ParticipantStatus.READY */;
+    const participantResumingAfterTimeoutExpiration = participantIsCurrentContributor && participantIsReady;
+    const participantCompletedOneOrAllContributions = (status === "CONTRIBUTED" /* ParticipantStatus.CONTRIBUTED */ || status === "DONE" /* ParticipantStatus.DONE */) &&
+        contributionStep === "COMPLETED" /* ParticipantContributionStep.COMPLETED */;
+    // Check for scenarios.
+    if (isSingleParticipantCoordination) {
+        // Scenario (A).
+        if (emptyWaitingQueue) {
+            printLog(`Coordinate - executing scenario A - emptyWaitingQueue`, LogLevel.DEBUG);
+            // Update.
+            newCurrentContributorId = participant.id;
+            newParticipantStatus = "CONTRIBUTING" /* ParticipantStatus.CONTRIBUTING */;
+            newContributionStep = "DOWNLOADING" /* ParticipantContributionStep.DOWNLOADING */;
+            newContributors.push(newCurrentContributorId);
+        }
+        // Scenario (A).
+        else if (participantResumingAfterTimeoutExpiration) {
+            printLog(`Coordinate - executing scenario A - single - participantResumingAfterTimeoutExpiration`, LogLevel.DEBUG);
+            newParticipantStatus = "CONTRIBUTING" /* ParticipantStatus.CONTRIBUTING */;
+            newContributionStep = "DOWNLOADING" /* ParticipantContributionStep.DOWNLOADING */;
+            newCurrentContributorId = participant.id;
+        }
+        // Scenario (B).
+        else if (participantIsNotCurrentContributor) {
+            printLog(`Coordinate - executing scenario B - single - participantIsNotCurrentContributor`, LogLevel.DEBUG);
+            newCurrentContributorId = currentContributor;
+            newParticipantStatus = "WAITING" /* ParticipantStatus.WAITING */;
+            newContributors.push(participant.id);
+        }
+        // Prepare tx - Scenario (A) only.
+        if (newContributionStep)
+            batch.update(participant.ref, {
+                contributionStep: newContributionStep,
+                lastUpdated: getCurrentServerTimestampInMillis()
+            });
+        // Prepare tx - Scenario (A) or (B).
+        batch.update(participant.ref, {
+            status: newParticipantStatus,
+            contributionStartedAt: newParticipantStatus === "CONTRIBUTING" /* ParticipantStatus.CONTRIBUTING */ ? getCurrentServerTimestampInMillis() : 0,
+            lastUpdated: getCurrentServerTimestampInMillis()
+        });
+    }
+    else if (participantIsCurrentContributor && participantCompletedOneOrAllContributions && !!ceremonyId) {
+        printLog(`Coordinate - executing scenario C - multi - participantIsCurrentContributor && participantCompletedOneOrAllContributions`, LogLevel.DEBUG);
+        newParticipantStatus = "CONTRIBUTING" /* ParticipantStatus.CONTRIBUTING */;
+        newContributionStep = "DOWNLOADING" /* ParticipantContributionStep.DOWNLOADING */;
+        // Remove from waiting queue of circuit X.
+        newContributors.shift();
+        // Step (C.1).
+        if (newContributors.length > 0) {
+            // Get new contributor for circuit X.
+            newCurrentContributorId = newContributors.at(0);
+            // Pass the baton to the new contributor.
+            const newCurrentContributorDocument = await getDocumentById(getParticipantsCollectionPath(ceremonyId), newCurrentContributorId);
+            // Prepare update tx.
+            batch.update(newCurrentContributorDocument.ref, {
+                status: newParticipantStatus,
+                contributionStep: newContributionStep,
+                contributionStartedAt: getCurrentServerTimestampInMillis(),
+                lastUpdated: getCurrentServerTimestampInMillis()
+            });
+            printLog(`Participant ${newCurrentContributorId} is the new current contributor for circuit ${circuit.id}`, LogLevel.DEBUG);
+        }
+    }
+    // Prepare tx - must be done for all Scenarios.
+    batch.update(circuit.ref, {
+        waitingQueue: {
+            ...waitingQueue,
+            contributors: newContributors,
+            currentContributor: newCurrentContributorId
+        },
+        lastUpdated: getCurrentServerTimestampInMillis()
+    });
+    // Send txs.
+    await batch.commit();
+    printLog(`Coordinate successfully completed`, LogLevel.DEBUG);
+};
+/**
+ * Wait until the command has completed its execution inside the VM.
+ * @dev this method implements a custom interval to check 5 times after 1 minute if the command execution
+ * has been completed or not by calling the `retrieveCommandStatus` method.
+ * @param {SSMClient} ssm the SSM client.
+ * @param {string} vmInstanceId the unique identifier of the VM instance.
+ * @param {string} commandId the unique identifier of the VM command.
+ * @returns <Promise<void>> true when the command execution succeed; otherwise false.
+ */
+const waitForVMCommandExecution = (ssm, vmInstanceId, commandId) => new Promise((resolve, reject) => {
+    const poll = async () => {
+        try {
+            // Get command status.
+            const cmdStatus = await retrieveCommandStatus(ssm, vmInstanceId, commandId);
+            printLog(`Checking command ${commandId} status => ${cmdStatus}`, LogLevel.DEBUG);
+            let error;
+            switch (cmdStatus) {
+                case CommandInvocationStatus.CANCELLING:
+                case CommandInvocationStatus.CANCELLED: {
+                    error = SPECIFIC_ERRORS.SE_VM_CANCELLED_COMMAND_EXECUTION;
+                    break;
+                }
+                case CommandInvocationStatus.DELAYED: {
+                    error = SPECIFIC_ERRORS.SE_VM_DELAYED_COMMAND_EXECUTION;
+                    break;
+                }
+                case CommandInvocationStatus.FAILED: {
+                    error = SPECIFIC_ERRORS.SE_VM_FAILED_COMMAND_EXECUTION;
+                    break;
+                }
+                case CommandInvocationStatus.TIMED_OUT: {
+                    error = SPECIFIC_ERRORS.SE_VM_TIMEDOUT_COMMAND_EXECUTION;
+                    break;
+                }
+                case CommandInvocationStatus.IN_PROGRESS:
+                case CommandInvocationStatus.PENDING: {
+                    // wait a minute and poll again
+                    setTimeout(poll, 60000);
+                    return;
+                }
+                case CommandInvocationStatus.SUCCESS: {
+                    printLog(`Command ${commandId} successfully completed`, LogLevel.DEBUG);
+                    // Resolve the promise.
+                    resolve();
+                    return;
+                }
+                default: {
+                    logAndThrowError(SPECIFIC_ERRORS.SE_VM_UNKNOWN_COMMAND_STATUS);
+                }
+            }
+            if (error) {
+                logAndThrowError(error);
+            }
+        }
+        catch (error) {
+            printLog(`Invalid command ${commandId} execution`, LogLevel.DEBUG);
+            const ec2 = await createEC2Client();
+            // if it errors out, let's just log it as a warning so the coordinator is aware
+            try {
+                await stopEC2Instance(ec2, vmInstanceId);
+            }
+            catch (error) {
+                printLog(`Error while stopping VM instance ${vmInstanceId} - Error ${error}`, LogLevel.WARN);
+            }
+            if (!error.toString().includes(commandId))
+                logAndThrowError(COMMON_ERRORS.CM_INVALID_COMMAND_EXECUTION);
+            // Reject the promise.
+            reject();
+        }
+    };
+    setTimeout(poll, 60000);
+});
+/**
+ * This method is used to coordinate the waiting queues of ceremony circuits.
+ * @dev this cloud function is triggered whenever an update of a document related to a participant of a ceremony occurs.
+ * The function verifies that such update is preparatory towards a waiting queue update for one or more circuits in the ceremony.
+ * If that's the case, this cloud functions proceeds with the "coordination" of the waiting queues, leading to three different scenarios:
+ * A) The participant becomes the current contributor of circuit X (single participant).
+ * B) The participant is placed in the contribution waiting queue because someone else is currently contributing to circuit X (single participant)
+ * C) The participant is removed as current contributor from Circuit X and gets coordinated for Circuit X + 1 (multi-participant).
+ *    C.1) The first participant in the waiting queue for Circuit X (if any), becomes the new contributor for circuit X.
+ * Before triggering the above scenarios, the cloud functions verifies that suitable pre-conditions are met.
+ * @notice The cloud function performs the subsequent steps:
+ * 0) Prepares the participant's previous and current data (after/before document change).
+ * 1) Retrieve the ceremony from the participant's document path.
+ * 2) Verifies that the participant has changed to a state for which it is ready for contribution.
+ * 2.A) If ready, verifies whether the participant is ready to:
+ * - Contribute for the first time or for the next circuit (other than the first) or contribute after a timeout has expired. If yes, coordinate (single participant scenario).
+ * 2.B) Otherwise, check whether the participant has:
+ * - Just completed a contribution or all contributions for each circuit. If yes, coordinate (multi-participant scenario).
+ */
+const coordinateCeremonyParticipant = functionsV1
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .firestore.document(`${commonTerms.collections.ceremonies.name}/{ceremonyId}/${commonTerms.collections.participants.name}/{participantId}`)
+    .onUpdate(async (participantChanges) => {
+    // Step (0).
+    const exParticipant = participantChanges.before;
+    const changedParticipant = participantChanges.after;
+    if (!exParticipant.data() || !changedParticipant.data())
+        logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA);
+    // Step (1).
+    const ceremonyId = exParticipant.ref.parent.parent.path.replace(`${commonTerms.collections.ceremonies.name}/`, "");
+    if (!ceremonyId)
+        logAndThrowError(COMMON_ERRORS.CM_INVALID_CEREMONY_FOR_PARTICIPANT);
+    // Extract data.
+    const { contributionProgress: prevContributionProgress, status: prevStatus, contributionStep: prevContributionStep } = exParticipant.data();
+    const { contributionProgress: changedContributionProgress, status: changedStatus, contributionStep: changedContributionStep } = changedParticipant.data();
+    printLog(`Coordinate participant ${exParticipant.id} for ceremony ${ceremonyId}`, LogLevel.DEBUG);
+    printLog(`Participant status: ${prevStatus} => ${changedStatus} - Participant contribution step: ${prevContributionStep} => ${changedContributionStep}`, LogLevel.DEBUG);
+    // Define pre-conditions.
+    const participantReadyToContribute = changedStatus === "READY" /* ParticipantStatus.READY */;
+    const participantReadyForFirstContribution = participantReadyToContribute && prevContributionProgress === 0;
+    const participantResumingContributionAfterTimeout = participantReadyToContribute && prevContributionProgress === changedContributionProgress;
+    const participantReadyForNextContribution = participantReadyToContribute &&
+        prevContributionProgress === changedContributionProgress - 1 &&
+        prevContributionProgress !== 0;
+    const participantCompletedEveryCircuitContribution = changedStatus === "DONE" /* ParticipantStatus.DONE */ && prevStatus !== "DONE" /* ParticipantStatus.DONE */;
+    const participantCompletedContribution = prevContributionProgress === changedContributionProgress &&
+        prevStatus === "CONTRIBUTING" /* ParticipantStatus.CONTRIBUTING */ &&
+        prevContributionStep === "VERIFYING" /* ParticipantContributionStep.VERIFYING */ &&
+        changedStatus === "CONTRIBUTED" /* ParticipantStatus.CONTRIBUTED */ &&
+        changedContributionStep === "COMPLETED" /* ParticipantContributionStep.COMPLETED */;
+    // Step (2).
+    if (participantReadyForFirstContribution ||
+        participantResumingContributionAfterTimeout ||
+        participantReadyForNextContribution) {
+        // Step (2.A).
+        printLog(`Participant is ready for first contribution (${participantReadyForFirstContribution}) or for the next contribution (${participantReadyForNextContribution}) or is resuming after a timeout expiration (${participantResumingContributionAfterTimeout})`, LogLevel.DEBUG);
+        // Get the circuit.
+        const circuit = await getCircuitDocumentByPosition(ceremonyId, changedContributionProgress);
+        // Coordinate.
+        await coordinate(changedParticipant, circuit, true);
+        printLog(`Coordination for circuit ${circuit.id} completed`, LogLevel.DEBUG);
+    }
+    else if (participantCompletedContribution || participantCompletedEveryCircuitContribution) {
+        // Step (2.B).
+        printLog(`Participant completed a contribution (${participantCompletedContribution}) or every contribution for each circuit (${participantCompletedEveryCircuitContribution})`, LogLevel.DEBUG);
+        // Get the circuit.
+        const circuit = await getCircuitDocumentByPosition(ceremonyId, prevContributionProgress);
+        // Coordinate.
+        await coordinate(changedParticipant, circuit, false, ceremonyId);
+        printLog(`Coordination for circuit ${circuit.id} completed`, LogLevel.DEBUG);
+    }
+});
+/**
+ * Recursive function to check whether an EC2 is in a running state
+ * @notice required step to run commands
+ * @param ec2 <EC2Client> - the EC2Client object
+ * @param vmInstanceId <string> - the instance Id
+ * @param attempts <number> - how many times to retry before failing
+ * @returns <Promise<boolean>> - whether the VM was started
+ */
+const checkIfVMRunning = async (ec2, vmInstanceId, attempts = 5) => {
+    // if we tried 5 times, then throw an error
+    if (attempts <= 0)
+        logAndThrowError(SPECIFIC_ERRORS.SE_VM_NOT_RUNNING);
+    await sleep(60000); // Wait for 1 min
+    const isVMRunning = await checkIfRunning(ec2, vmInstanceId);
+    if (!isVMRunning) {
+        printLog(`VM not running, ${attempts - 1} attempts remaining. Retrying in 1 minute...`, LogLevel.DEBUG);
+        return checkIfVMRunning(ec2, vmInstanceId, attempts - 1);
+    }
+    return true;
+};
+/**
+ * Verify the contribution of a participant computed while contributing to a specific circuit of a ceremony.
+ * @dev a huge amount of resources (memory, CPU, and execution time) is required for the contribution verification task.
+ * For this reason, we are using a V2 Cloud Function (more memory, more CPU, and longer timeout).
+ * Through the current configuration (16GiB memory and 4 vCPUs) we are able to support verification of contributions for 3.8M constraints circuit size.
+  @notice The cloud function performs the subsequent steps:
+ * 0) Prepare documents and extract necessary data.
+ * 1) Check if the participant is the current contributor to the circuit or is the ceremony coordinator
+ * 1.A) If either condition is true:
+ *   1.A.1) Prepare verification transcript logger, storage, and temporary paths.
+ *   1.A.2) Download necessary AWS S3 ceremony bucket artifacts.
+ *   1.A.3) Execute contribution verification.
+ *     1.A.3.0) Check if is using VM or CF approach for verification.
+ *     1.A.3.1) Start the instance and wait until the instance is up.
+ *     1.A.3.2) Prepare and run contribution verification command.
+ *     1.A.3.3) Wait until command complete.
+ *   1.A.4) Check contribution validity:
+ *   1.A.4.A) If valid:
+ *     1.A.4.A.1) Upload verification transcript to AWS S3 storage.
+ *     1.A.4.A.2) Creates a new valid contribution document on Firestore.
+ *   1.A.4.B) If not valid:
+ *     1.A.4.B.1) Creates a new invalid contribution document on Firestore.
+ *   1.A.4.C) Check if not finalizing:
+ *       1.A.4.C.1) If true, update circuit waiting for queue and average timings accordingly to contribution verification results;
+ * 2) Send all updates atomically to the Firestore database.
+ */
+const verifycontribution = functionsV2.https.onCall({ memory: "16GiB", timeoutSeconds: 3600, region: "europe-west1" }, async (request) => {
+    if (!request.auth || (!request.auth.token.participant && !request.auth.token.coordinator))
+        logAndThrowError(SPECIFIC_ERRORS.SE_AUTH_NO_CURRENT_AUTH_USER);
+    if (!request.data.ceremonyId ||
+        !request.data.circuitId ||
+        !request.data.contributorOrCoordinatorIdentifier ||
+        !request.data.bucketName)
+        logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA);
+    if (!process.env.CUSTOM_CONTRIBUTION_VERIFICATION_SOFTWARE_NAME ||
+        !process.env.CUSTOM_CONTRIBUTION_VERIFICATION_SOFTWARE_VERSION ||
+        !process.env.CUSTOM_CONTRIBUTION_VERIFICATION_SOFTWARE_COMMIT_HASH)
+        logAndThrowError(COMMON_ERRORS.CM_WRONG_CONFIGURATION);
+    // Step (0).
+    // Prepare and start timer.
+    const verifyContributionTimer = new Timer({ label: commonTerms.cloudFunctionsNames.verifyContribution });
+    verifyContributionTimer.start();
+    // Get DB.
+    const firestore = admin.firestore();
+    // Prepare batch of txs.
+    const batch = firestore.batch();
+    // Extract data.
+    const { ceremonyId, circuitId, contributorOrCoordinatorIdentifier, bucketName } = request.data;
+    const userId = request.auth?.uid;
+    // Look for the ceremony, circuit and participant document.
+    const ceremonyDoc = await getDocumentById(commonTerms.collections.ceremonies.name, ceremonyId);
+    const circuitDoc = await getDocumentById(getCircuitsCollectionPath(ceremonyId), circuitId);
+    const participantDoc = await getDocumentById(getParticipantsCollectionPath(ceremonyId), userId);
+    if (!ceremonyDoc.data() || !circuitDoc.data() || !participantDoc.data())
+        logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA);
+    // Extract documents data.
+    const { state } = ceremonyDoc.data();
+    const { status, contributions, verificationStartedAt, contributionStartedAt } = participantDoc.data();
+    const { waitingQueue, prefix, avgTimings, verification, files } = circuitDoc.data();
+    const { completedContributions, failedContributions } = waitingQueue;
+    const { contributionComputation: avgContributionComputationTime, fullContribution: avgFullContributionTime, verifyCloudFunction: avgVerifyCloudFunctionTime } = avgTimings;
+    const { cfOrVm, vm } = verification;
+    // we might not have it if the circuit is not using VM.
+    let vmInstanceId = "";
+    if (vm)
+        vmInstanceId = vm.vmInstanceId;
+    // Define pre-conditions.
+    const isFinalizing = state === "CLOSED" /* CeremonyState.CLOSED */ && request.auth && request.auth.token.coordinator; // true only when the coordinator verifies the final contributions.
+    const isContributing = status === "CONTRIBUTING" /* ParticipantStatus.CONTRIBUTING */;
+    const isUsingVM = cfOrVm === "VM" /* CircuitContributionVerificationMechanism.VM */ && !!vmInstanceId;
+    // Prepare state.
+    let isContributionValid = false;
+    let verifyCloudFunctionExecutionTime = 0; // time spent while executing the verify contribution cloud function.
+    let verifyCloudFunctionTime = 0; // time spent while executing the core business logic of this cloud function.
+    let fullContributionTime = 0; // time spent while doing non-verification contributions tasks (download, compute, upload).
+    let contributionComputationTime = 0; // time spent while computing the contribution.
+    let lastZkeyBlake2bHash = ""; // the Blake2B hash of the last zKey.
+    let verificationTranscriptTemporaryLocalPath = ""; // the local temporary path for the verification transcript.
+    let transcriptBlake2bHash = ""; // the Blake2B hash of the verification transcript.
+    let commandId = ""; // the unique identifier of the VM command.
+    // Derive necessary data.
+    const lastZkeyIndex = formatZkeyIndex(completedContributions + 1);
+    const verificationTranscriptCompleteFilename = `${prefix}_${isFinalizing
+        ? `${contributorOrCoordinatorIdentifier}_${finalContributionIndex}_verification_transcript.log`
+        : `${lastZkeyIndex}_${contributorOrCoordinatorIdentifier}_verification_transcript.log`}`;
+    const lastZkeyFilename = `${prefix}_${isFinalizing ? finalContributionIndex : lastZkeyIndex}.zkey`;
+    // Prepare state for VM verification (if needed).
+    const ec2 = await createEC2Client();
+    const ssm = await createSSMClient();
+    // Step (1.A.1).
+    // Get storage paths.
+    const verificationTranscriptStoragePathAndFilename = getTranscriptStorageFilePath(prefix, verificationTranscriptCompleteFilename);
+    // the zKey storage path is required to be sent to the VM api
+    const lastZkeyStoragePath = getZkeyStorageFilePath(prefix, `${prefix}_${isFinalizing ? finalContributionIndex : lastZkeyIndex}.zkey`);
+    const verificationTaskTimer = new Timer({ label: `${ceremonyId}-${circuitId}-${participantDoc.id}` });
+    const completeVerification = async () => {
+        // Stop verification task timer.
+        printLog("Completing verification", LogLevel.DEBUG);
+        verificationTaskTimer.stop();
+        verifyCloudFunctionExecutionTime = verificationTaskTimer.ms();
+        if (isUsingVM) {
+            // Create temporary path.
+            verificationTranscriptTemporaryLocalPath = createTemporaryLocalPath(`${circuitId}_${participantDoc.id}.log`);
+            await sleep(1000); // wait 1s for file creation.
+            // Download from bucket.
+            // nb. the transcript MUST be uploaded from the VM by verification commands.
+            await downloadArtifactFromS3Bucket(bucketName, verificationTranscriptStoragePathAndFilename, verificationTranscriptTemporaryLocalPath);
+            // Read the verification trascript and validate data by checking for core info ("ZKey Ok!").
+            const content = fs.readFileSync(verificationTranscriptTemporaryLocalPath, "utf-8");
+            if (content.includes("ZKey Ok!"))
+                isContributionValid = true;
+            // If the contribution is valid, then format and store the trascript.
+            if (isContributionValid) {
+                // eslint-disable-next-line no-control-regex
+                const updated = content.replace(/\x1b[[0-9;]*m/g, "");
+                fs.writeFileSync(verificationTranscriptTemporaryLocalPath, updated);
+            }
+        }
+        printLog(`The contribution has been verified - Result ${isContributionValid}`, LogLevel.DEBUG);
+        // Create a new contribution document.
+        const contributionDoc = await firestore
+            .collection(getContributionsCollectionPath(ceremonyId, circuitId))
+            .doc()
+            .get();
+        // Step (1.A.4).
+        if (isContributionValid) {
+            // Sleep ~3 seconds to wait for verification transcription.
+            await sleep(3000);
+            // Step (1.A.4.A.1).
+            if (isUsingVM) {
+                // Retrieve the contribution hash from the command output.
+                lastZkeyBlake2bHash = await retrieveCommandOutput(ssm, vmInstanceId, commandId);
+                const hashRegex = /[a-fA-F0-9]{64}/;
+                const match = lastZkeyBlake2bHash.match(hashRegex);
+                lastZkeyBlake2bHash = match.at(0);
+                // re upload the formatted verification transcript
+                await uploadFileToBucket(bucketName, verificationTranscriptStoragePathAndFilename, verificationTranscriptTemporaryLocalPath, true);
+            }
+            else {
+                // Upload verification transcript.
+                /// nb. do not use multi-part upload here due to small file size.
+                await uploadFileToBucket(bucketName, verificationTranscriptStoragePathAndFilename, verificationTranscriptTemporaryLocalPath, true);
+            }
+            // Compute verification transcript hash.
+            transcriptBlake2bHash = await blake512FromPath(verificationTranscriptTemporaryLocalPath);
+            // Free resources by unlinking transcript temporary file.
+            fs.unlinkSync(verificationTranscriptTemporaryLocalPath);
+            // Filter participant contributions to find the data related to the one verified.
+            const participantContributions = contributions.filter((contribution) => !!contribution.hash && !!contribution.computationTime && !contribution.doc);
+            /// @dev (there must be only one contribution with an empty 'doc' field).
+            if (participantContributions.length !== 1)
+                logAndThrowError(SPECIFIC_ERRORS.SE_VERIFICATION_NO_PARTICIPANT_CONTRIBUTION_DATA);
+            // Get contribution computation time.
+            contributionComputationTime = contributions.at(0).computationTime;
+            // Step (1.A.4.A.2).
+            batch.create(contributionDoc.ref, {
+                participantId: participantDoc.id,
+                contributionComputationTime,
+                verificationComputationTime: verifyCloudFunctionExecutionTime,
+                zkeyIndex: isFinalizing ? finalContributionIndex : lastZkeyIndex,
+                files: {
+                    transcriptFilename: verificationTranscriptCompleteFilename,
+                    lastZkeyFilename,
+                    transcriptStoragePath: verificationTranscriptStoragePathAndFilename,
+                    lastZkeyStoragePath,
+                    transcriptBlake2bHash,
+                    lastZkeyBlake2bHash
+                },
+                verificationSoftware: {
+                    name: String(process.env.CUSTOM_CONTRIBUTION_VERIFICATION_SOFTWARE_NAME),
+                    version: String(process.env.CUSTOM_CONTRIBUTION_VERIFICATION_SOFTWARE_VERSION),
+                    commitHash: String(process.env.CUSTOM_CONTRIBUTION_VERIFICATION_SOFTWARE_COMMIT_HASH)
+                },
+                valid: isContributionValid,
+                lastUpdated: getCurrentServerTimestampInMillis()
+            });
+            verifyContributionTimer.stop();
+            verifyCloudFunctionTime = verifyContributionTimer.ms();
+        }
+        else {
+            // Step (1.A.4.B).
+            // Free-up storage by deleting invalid contribution.
+            await deleteObject(bucketName, lastZkeyStoragePath);
+            // Step (1.A.4.B.1).
+            batch.create(contributionDoc.ref, {
+                participantId: participantDoc.id,
+                verificationComputationTime: verifyCloudFunctionExecutionTime,
+                zkeyIndex: isFinalizing ? finalContributionIndex : lastZkeyIndex,
+                verificationSoftware: {
+                    name: String(process.env.CUSTOM_CONTRIBUTION_VERIFICATION_SOFTWARE_NAME),
+                    version: String(process.env.CUSTOM_CONTRIBUTION_VERIFICATION_SOFTWARE_VERSION),
+                    commitHash: String(process.env.CUSTOM_CONTRIBUTION_VERIFICATION_SOFTWARE_COMMIT_HASH)
+                },
+                valid: isContributionValid,
+                lastUpdated: getCurrentServerTimestampInMillis()
+            });
+        }
+        // Stop VM instance
+        if (isUsingVM) {
+            // using try and catch as the VM stopping function can throw
+            // however we want to continue without stopping as the
+            // verification was valid, and inform the coordinator
+            try {
+                await stopEC2Instance(ec2, vmInstanceId);
+            }
+            catch (error) {
+                printLog(`Error while stopping VM instance ${vmInstanceId} - Error ${error}`, LogLevel.WARN);
+            }
+        }
+        // Step (1.A.4.C)
+        if (!isFinalizing) {
+            // Step (1.A.4.C.1)
+            // Compute new average contribution/verification time.
+            fullContributionTime = Number(verificationStartedAt) - Number(contributionStartedAt);
+            const newAvgContributionComputationTime = avgContributionComputationTime > 0
+                ? (avgContributionComputationTime + contributionComputationTime) / 2
+                : contributionComputationTime;
+            const newAvgFullContributionTime = avgFullContributionTime > 0
+                ? (avgFullContributionTime + fullContributionTime) / 2
+                : fullContributionTime;
+            const newAvgVerifyCloudFunctionTime = avgVerifyCloudFunctionTime > 0
+                ? (avgVerifyCloudFunctionTime + verifyCloudFunctionTime) / 2
+                : verifyCloudFunctionTime;
+            // Prepare tx to update circuit average contribution/verification time.
+            const updatedCircuitDoc = await getDocumentById(getCircuitsCollectionPath(ceremonyId), circuitId);
+            const { waitingQueue: updatedWaitingQueue } = updatedCircuitDoc.data();
+            /// @dev this must happen only for valid contributions.
+            batch.update(circuitDoc.ref, {
+                avgTimings: {
+                    contributionComputation: isContributionValid
+                        ? newAvgContributionComputationTime
+                        : avgContributionComputationTime,
+                    fullContribution: isContributionValid ? newAvgFullContributionTime : avgFullContributionTime,
+                    verifyCloudFunction: isContributionValid
+                        ? newAvgVerifyCloudFunctionTime
+                        : avgVerifyCloudFunctionTime
+                },
+                waitingQueue: {
+                    ...updatedWaitingQueue,
+                    completedContributions: isContributionValid
+                        ? completedContributions + 1
+                        : completedContributions,
+                    failedContributions: isContributionValid ? failedContributions : failedContributions + 1
+                },
+                lastUpdated: getCurrentServerTimestampInMillis()
+            });
+        }
+        // Step (2).
+        await batch.commit();
+        printLog(`The contribution #${isFinalizing ? finalContributionIndex : lastZkeyIndex} of circuit ${circuitId} (ceremony ${ceremonyId}) has been verified as ${isContributionValid ? "valid" : "invalid"} for the participant ${participantDoc.id}`, LogLevel.DEBUG);
+    };
+    // Step (1).
+    if (isContributing || isFinalizing) {
+        // Prepare timer.
+        verificationTaskTimer.start();
+        // Step (1.A.3.0).
+        if (isUsingVM) {
+            printLog(`Starting the VM mechanism`, LogLevel.DEBUG);
+            // Prepare for VM execution.
+            let isVMRunning = false; // true when the VM is up, otherwise false.
+            // Step (1.A.3.1).
+            await startEC2Instance(ec2, vmInstanceId);
+            await sleep(60000); // nb. wait for VM startup (1 mins + retry).
+            // Check if the startup is running.
+            isVMRunning = await checkIfVMRunning(ec2, vmInstanceId);
+            printLog(`VM running: ${isVMRunning}`, LogLevel.DEBUG);
+            // Step (1.A.3.2).
+            // Prepare.
+            const verificationCommand = vmContributionVerificationCommand(bucketName, lastZkeyStoragePath, verificationTranscriptStoragePathAndFilename);
+            // Run.
+            commandId = await runCommandUsingSSM(ssm, vmInstanceId, verificationCommand);
+            printLog(`Starting the execution of command ${commandId}`, LogLevel.DEBUG);
+            // Step (1.A.3.3).
+            return waitForVMCommandExecution(ssm, vmInstanceId, commandId)
+                .then(async () => {
+                // Command execution successfully completed.
+                printLog(`Command ${commandId} execution has been successfully completed`, LogLevel.DEBUG);
+                await completeVerification();
+            })
+                .catch((error) => {
+                // Command execution aborted.
+                printLog(`Command ${commandId} execution has been aborted - Error ${error}`, LogLevel.DEBUG);
+                logAndThrowError(COMMON_ERRORS.CM_INVALID_COMMAND_EXECUTION);
+            });
+        }
+        // CF approach.
+        printLog(`CF mechanism`, LogLevel.DEBUG);
+        const potStoragePath = getPotStorageFilePath(files.potFilename);
+        const firstZkeyStoragePath = getZkeyStorageFilePath(prefix, `${prefix}_${genesisZkeyIndex}.zkey`);
+        // Prepare temporary file paths.
+        // (nb. these are needed to download the necessary artifacts for verification from AWS S3).
+        verificationTranscriptTemporaryLocalPath = createTemporaryLocalPath(verificationTranscriptCompleteFilename);
+        const potTempFilePath = createTemporaryLocalPath(`${circuitId}_${participantDoc.id}.pot`);
+        const firstZkeyTempFilePath = createTemporaryLocalPath(`${circuitId}_${participantDoc.id}_genesis.zkey`);
+        const lastZkeyTempFilePath = createTemporaryLocalPath(`${circuitId}_${participantDoc.id}_last.zkey`);
+        // Create and populate transcript.
+        const transcriptLogger = createCustomLoggerForFile(verificationTranscriptTemporaryLocalPath);
+        transcriptLogger.info(`${isFinalizing ? `Final verification` : `Verification`} transcript for ${prefix} circuit Phase 2 contribution.\n${isFinalizing ? `Coordinator ` : `Contributor # ${Number(lastZkeyIndex)}`} (${contributorOrCoordinatorIdentifier})\n`);
+        // Step (1.A.2).
+        await downloadArtifactFromS3Bucket(bucketName, potStoragePath, potTempFilePath);
+        await downloadArtifactFromS3Bucket(bucketName, firstZkeyStoragePath, firstZkeyTempFilePath);
+        await downloadArtifactFromS3Bucket(bucketName, lastZkeyStoragePath, lastZkeyTempFilePath);
+        // Step (1.A.4).
+        isContributionValid = await zKey.verifyFromInit(firstZkeyTempFilePath, potTempFilePath, lastZkeyTempFilePath, transcriptLogger);
+        // Compute contribution hash.
+        lastZkeyBlake2bHash = await blake512FromPath(lastZkeyTempFilePath);
+        // Free resources by unlinking temporary folders.
+        // Do not free-up verification transcript path here.
+        try {
+            fs.unlinkSync(potTempFilePath);
+            fs.unlinkSync(firstZkeyTempFilePath);
+            fs.unlinkSync(lastZkeyTempFilePath);
+        }
+        catch (error) {
+            printLog(`Error while unlinking temporary files - Error ${error}`, LogLevel.WARN);
+        }
+        await completeVerification();
+    }
+});
+/**
+ * Update the related participant's document after verification of its last contribution.
+ * @dev this cloud functions is responsible for preparing the participant for the contribution toward the next circuit.
+ * this does not happen if the participant is actually the coordinator who is finalizing the ceremony.
+ */
+const refreshParticipantAfterContributionVerification = functionsV1
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .firestore.document(`/${commonTerms.collections.ceremonies.name}/{ceremony}/${commonTerms.collections.circuits.name}/{circuit}/${commonTerms.collections.contributions.name}/{contributions}`)
+    .onCreate(async (createdContribution) => {
+    // Prepare db.
+    const firestore = admin.firestore();
+    // Prepare batch of txs.
+    const batch = firestore.batch();
+    // Derive data from document.
+    // == /ceremonies/{ceremony}/circuits/.
+    const ceremonyId = createdContribution.ref.parent.parent?.parent?.parent?.path.replace(`${commonTerms.collections.ceremonies.name}/`, "");
+    // == /ceremonies/{ceremony}/participants.
+    const ceremonyParticipantsCollectionPath = `${createdContribution.ref.parent.parent?.parent?.parent?.path}/${commonTerms.collections.participants.name}`;
+    if (!createdContribution.data())
+        logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA);
+    // Extract data.
+    const { participantId } = createdContribution.data();
+    // Get documents from derived paths.
+    const circuits = await getCeremonyCircuits(ceremonyId);
+    const participantDoc = await getDocumentById(ceremonyParticipantsCollectionPath, participantId);
+    if (!participantDoc.data())
+        logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA);
+    // Extract data.
+    const { contributions, status, contributionProgress } = participantDoc.data();
+    // Define pre-conditions.
+    const isFinalizing = status === "FINALIZING" /* ParticipantStatus.FINALIZING */;
+    // Link the newest created contribution document w/ participant contributions info.
+    // nb. there must be only one contribution with an empty doc.
+    contributions.forEach((participantContribution) => {
+        // Define pre-conditions.
+        const isContributionWithoutDocRef = !!participantContribution.hash &&
+            !!participantContribution.computationTime &&
+            !participantContribution.doc;
+        if (isContributionWithoutDocRef)
+            participantContribution.doc = createdContribution.id;
+    });
+    // Check if the participant is not the coordinator trying to finalize the ceremony.
+    if (!isFinalizing)
+        batch.update(participantDoc.ref, {
+            // - DONE = provided a contribution for every circuit
+            // - CONTRIBUTED = some contribution still missing.
+            status: contributionProgress + 1 > circuits.length ? "DONE" /* ParticipantStatus.DONE */ : "CONTRIBUTED" /* ParticipantStatus.CONTRIBUTED */,
+            contributionStep: "COMPLETED" /* ParticipantContributionStep.COMPLETED */,
+            tempContributionData: FieldValue.delete()
+        });
+    // nb. valid both for participant or coordinator (finalizing).
+    batch.update(participantDoc.ref, {
+        contributions,
+        lastUpdated: getCurrentServerTimestampInMillis()
+    });
+    await batch.commit();
+    printLog(`Participant ${participantId} refreshed after contribution ${createdContribution.id} - The participant was finalizing the ceremony ${isFinalizing}`, LogLevel.DEBUG);
+});
+/**
+ * Finalize the ceremony circuit.
+ * @dev this cloud function stores the hashes and storage references of the Verifier smart contract
+ * and verification key extracted from the circuit final contribution (as part of the ceremony finalization process).
+ */
+const finalizeCircuit = functionsV1
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .https.onCall(async (data, context) => {
+    if (!context.auth || !context.auth.token.coordinator)
+        logAndThrowError(COMMON_ERRORS.CM_NOT_COORDINATOR_ROLE);
+    if (!data.ceremonyId || !data.circuitId || !data.bucketName || !data.beacon)
+        logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA);
+    // Get data.
+    const { ceremonyId, circuitId, bucketName, beacon } = data;
+    const userId = context.auth?.uid;
+    // Look for documents.
+    const ceremonyDoc = await getDocumentById(commonTerms.collections.ceremonies.name, ceremonyId);
+    const participantDoc = await getDocumentById(getParticipantsCollectionPath(ceremonyId), userId);
+    const circuitDoc = await getDocumentById(getCircuitsCollectionPath(ceremonyId), circuitId);
+    const contributionDoc = await getFinalContribution(ceremonyId, circuitId);
+    if (!ceremonyDoc.data() || !circuitDoc.data() || !participantDoc.data() || !contributionDoc.data())
+        logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA);
+    // Extract data.
+    const { prefix: circuitPrefix } = circuitDoc.data();
+    const { files } = contributionDoc.data();
+    // Prepare filenames and storage paths.
+    const verificationKeyFilename = `${circuitPrefix}_${verificationKeyAcronym}.json`;
+    const verifierContractFilename = `${circuitPrefix}_${verifierSmartContractAcronym}.sol`;
+    const verificationKeyStorageFilePath = getVerificationKeyStorageFilePath(circuitPrefix, verificationKeyFilename);
+    const verifierContractStorageFilePath = getVerifierContractStorageFilePath(circuitPrefix, verifierContractFilename);
+    // Prepare temporary paths.
+    const verificationKeyTemporaryFilePath = createTemporaryLocalPath(verificationKeyFilename);
+    const verifierContractTemporaryFilePath = createTemporaryLocalPath(verifierContractFilename);
+    // Download artifact from ceremony bucket.
+    await downloadArtifactFromS3Bucket(bucketName, verificationKeyStorageFilePath, verificationKeyTemporaryFilePath);
+    await downloadArtifactFromS3Bucket(bucketName, verifierContractStorageFilePath, verifierContractTemporaryFilePath);
+    // Compute hash before unlink.
+    const verificationKeyBlake2bHash = await blake512FromPath(verificationKeyTemporaryFilePath);
+    const verifierContractBlake2bHash = await blake512FromPath(verifierContractTemporaryFilePath);
+    // Free resources by unlinking temporary folders.
+    fs.unlinkSync(verificationKeyTemporaryFilePath);
+    fs.unlinkSync(verifierContractTemporaryFilePath);
+    // Add references and hashes of the final contribution artifacts.
+    await contributionDoc.ref.update({
+        files: {
+            ...files,
+            verificationKeyBlake2bHash,
+            verificationKeyFilename,
+            verificationKeyStoragePath: verificationKeyStorageFilePath,
+            verifierContractBlake2bHash,
+            verifierContractFilename,
+            verifierContractStoragePath: verifierContractStorageFilePath
+        },
+        beacon: {
+            value: beacon,
+            hash: computeSHA256ToHex(beacon)
+        }
+    });
+    printLog(`Circuit ${circuitId} finalization completed - Ceremony ${ceremonyDoc.id} - Coordinator ${participantDoc.id}`, LogLevel.DEBUG);
+});
+
+dotenv.config();
+/**
+ * Check if the pre-condition for interacting w/ a multi-part upload for an identified current contributor is valid.
+ * @notice the precondition is be a current contributor (contributing status) in the uploading contribution step.
+ * @param contributorId <string> - the unique identifier of the contributor.
+ * @param ceremonyId <string> - the unique identifier of the ceremony.
+ */
+const checkPreConditionForCurrentContributorToInteractWithMultiPartUpload = async (contributorId, ceremonyId) => {
+    // Get ceremony and participant documents.
+    const ceremonyDoc = await getDocumentById(commonTerms.collections.ceremonies.name, ceremonyId);
+    const participantDoc = await getDocumentById(getParticipantsCollectionPath(ceremonyId), contributorId);
+    // Get data from docs.
+    const ceremonyData = ceremonyDoc.data();
+    const participantData = participantDoc.data();
+    if (!ceremonyData || !participantData)
+        logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA);
+    // Check pre-condition to start multi-part upload for a current contributor.
+    const { status, contributionStep } = participantData;
+    if (status !== "CONTRIBUTING" /* ParticipantStatus.CONTRIBUTING */ && contributionStep !== "UPLOADING" /* ParticipantContributionStep.UPLOADING */)
+        logAndThrowError(SPECIFIC_ERRORS.SE_STORAGE_CANNOT_INTERACT_WITH_MULTI_PART_UPLOAD);
+};
+/**
+ * Helper function to check whether a contributor is uploading a file related to its contribution.
+ * @param contributorId <string> - the unique identifier of the contributor.
+ * @param ceremonyId <string> - the unique identifier of the ceremony.
+ * @param objectKey <string> - the object key of the file being uploaded.
+ */
+const checkUploadingFileValidity = async (contributorId, ceremonyId, objectKey) => {
+    // Get the circuits for the ceremony
+    const circuits = await getCeremonyCircuits(ceremonyId);
+    // Get the participant document
+    const participantDoc = await getDocumentById(getParticipantsCollectionPath(ceremonyId), contributorId);
+    const participantData = participantDoc.data();
+    if (!participantData)
+        logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA);
+    // The index of the circuit will be the contribution progress - 1
+    const index = participantData?.contributionProgress;
+    // If the index is zero the user is not the current contributor
+    if (index === 0)
+        logAndThrowError(SPECIFIC_ERRORS.SE_STORAGE_CANNOT_INTERACT_WITH_MULTI_PART_UPLOAD);
+    // We can safely use index - 1
+    const circuit = circuits.at(index - 1);
+    // If the circuit is undefined, throw an error
+    if (!circuit)
+        logAndThrowError(SPECIFIC_ERRORS.SE_STORAGE_CANNOT_INTERACT_WITH_MULTI_PART_UPLOAD);
+    // Extract the data we need
+    const { prefix, waitingQueue } = circuit.data();
+    const { completedContributions, currentContributor } = waitingQueue;
+    // If we are not a contributor to this circuit then we cannot upload files
+    if (currentContributor === contributorId) {
+        // Get the index of the zKey
+        const contributorZKeyIndex = formatZkeyIndex(completedContributions + 1);
+        // The uploaded file must be the expected one
+        const zkeyNameContributor = `${prefix}_${contributorZKeyIndex}.zkey`;
+        const contributorZKeyStoragePath = getZkeyStorageFilePath(prefix, zkeyNameContributor);
+        // If the object key does not have the expected storage path, throw an error
+        if (objectKey !== contributorZKeyStoragePath) {
+            logAndThrowError(SPECIFIC_ERRORS.SE_STORAGE_WRONG_OBJECT_KEY);
+        }
+    }
+    else
+        logAndThrowError(SPECIFIC_ERRORS.SE_STORAGE_CANNOT_INTERACT_WITH_MULTI_PART_UPLOAD);
+};
+/**
+ * Helper function that confirms whether a bucket is used for a ceremony.
+ * @dev this helps to prevent unauthorized access to coordinator's buckets.
+ * @param bucketName
+ */
+const checkIfBucketIsDedicatedToCeremony = async (bucketName) => {
+    // Get Firestore DB.
+    const firestoreDatabase = admin.firestore();
+    // Extract ceremony prefix from bucket name.
+    const ceremonyPrefix = bucketName.replace(String(process.env.AWS_CEREMONY_BUCKET_POSTFIX), "");
+    // Query the collection.
+    const ceremonyCollection = await firestoreDatabase
+        .collection(commonTerms.collections.ceremonies.name)
+        .where(commonTerms.collections.ceremonies.fields.prefix, "==", ceremonyPrefix)
+        .get();
+    if (ceremonyCollection.empty)
+        logAndThrowError(SPECIFIC_ERRORS.SE_STORAGE_BUCKET_NOT_CONNECTED_TO_CEREMONY);
+};
+/**
+ * Create a new AWS S3 bucket for a particular ceremony.
+ * @notice the S3 bucket is used to store all the ceremony artifacts and contributions.
+ */
+const createBucket = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .https.onCall(async (data, context) => {
+    // Check if the user has the coordinator claim.
+    if (!context.auth || !context.auth.token.coordinator)
+        logAndThrowError(COMMON_ERRORS.CM_NOT_COORDINATOR_ROLE);
+    if (!data.bucketName)
+        logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA);
+    // Connect to S3 client.
+    const S3 = await getS3Client();
+    try {
+        // Try to get information about the bucket.
+        await S3.send(new HeadBucketCommand({ Bucket: data.bucketName }));
+        // If the command succeeded, the bucket exists, throw an error.
+        logAndThrowError(SPECIFIC_ERRORS.SE_STORAGE_INVALID_BUCKET_NAME);
+    }
+    catch (error) {
+        // eslint-disable-next-line @typescript-eslint/no-shadow
+        if (error.name === "NotFound") {
+            // Prepare S3 command.
+            const command = new CreateBucketCommand({
+                Bucket: data.bucketName,
+                // CreateBucketConfiguration: {
+                //     LocationConstraint: String(process.env.AWS_REGION)
+                // },
+                ObjectOwnership: "BucketOwnerPreferred"
+            });
+            try {
+                // Execute S3 command.
+                const response = await S3.send(command);
+                // Check response.
+                if (response.$metadata.httpStatusCode === 200 && !!response.Location)
+                    printLog(`The AWS S3 bucket ${data.bucketName} has been created successfully`, LogLevel.LOG);
+                const publicBlockCommand = new PutPublicAccessBlockCommand({
+                    Bucket: data.bucketName,
+                    PublicAccessBlockConfiguration: {
+                        BlockPublicAcls: false,
+                        BlockPublicPolicy: false
+                    }
+                });
+                // Allow objects to be public
+                const publicBlockResponse = await S3.send(publicBlockCommand);
+                // Check response.
+                if (publicBlockResponse.$metadata.httpStatusCode === 204)
+                    printLog(`The AWS S3 bucket ${data.bucketName} has been set with the PublicAccessBlock disabled.`, LogLevel.LOG);
+                // Set CORS
+                const corsCommand = new PutBucketCorsCommand({
+                    Bucket: data.bucketName,
+                    CORSConfiguration: {
+                        CORSRules: [
+                            {
+                                AllowedMethods: ["GET", "PUT"],
+                                AllowedOrigins: ["*"],
+                                ExposeHeaders: ["ETag", "Content-Length"],
+                                AllowedHeaders: ["*"]
+                            }
+                        ]
+                    }
+                });
+                const corsResponse = await S3.send(corsCommand);
+                // Check response.
+                if (corsResponse.$metadata.httpStatusCode === 200)
+                    printLog(`The AWS S3 bucket ${data.bucketName} has been set with the CORS configuration.`, LogLevel.LOG);
+            }
+            catch (error) {
+                // eslint-disable-next-line @typescript-eslint/no-shadow
+                /** * {@link https://docs.aws.amazon.com/simspaceweaver/latest/userguide/troubeshooting_too-many-buckets.html | TooManyBuckets} */
+                if (error.$metadata.httpStatusCode === 400 && error.Code === `TooManyBuckets`)
+                    logAndThrowError(SPECIFIC_ERRORS.SE_STORAGE_TOO_MANY_BUCKETS);
+                // @todo handle more errors here.
+                const commonError = COMMON_ERRORS.CM_INVALID_REQUEST;
+                const additionalDetails = error.toString();
+                logAndThrowError(makeError(commonError.code, commonError.message, additionalDetails));
+            }
+        }
+        else {
+            // If there was a different error, re-throw it.
+            const commonError = COMMON_ERRORS.CM_INVALID_REQUEST;
+            const additionalDetails = error.toString();
+            logAndThrowError(makeError(commonError.code, commonError.message, additionalDetails));
+        }
+    }
+});
+/**
+ * Check if a specified object exist in a given AWS S3 bucket.
+ * @returns <Promise<boolean>> - true if the object exist in the given bucket; otherwise false.
+ */
+const checkIfObjectExist = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .https.onCall(async (data, context) => {
+    // Check if the user has the coordinator claim.
+    if (!context.auth || !context.auth.token.coordinator)
+        logAndThrowError(COMMON_ERRORS.CM_NOT_COORDINATOR_ROLE);
+    if (!data.bucketName || !data.objectKey)
+        logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA);
+    // Connect to S3 client.
+    const S3 = await getS3Client();
+    // Prepare S3 command.
+    const command = new HeadObjectCommand({ Bucket: data.bucketName, Key: data.objectKey });
+    try {
+        // Execute S3 command.
+        const response = await S3.send(command);
+        // Check response.
+        if (response.$metadata.httpStatusCode === 200 && !!response.ETag) {
+            printLog(`The object associated w/ ${data.objectKey} key has been found in the ${data.bucketName} bucket`, LogLevel.LOG);
+            return true;
+        }
+    }
+    catch (error) {
+        // eslint-disable-next-line @typescript-eslint/no-shadow
+        if (error.$metadata.httpStatusCode === 403)
+            logAndThrowError(SPECIFIC_ERRORS.SE_STORAGE_MISSING_PERMISSIONS);
+        // @todo handle more specific errors here.
+        // nb. do not handle common errors! This method must return false if not found!
+        // const commonError = COMMON_ERRORS.CM_INVALID_REQUEST
+        // const additionalDetails = error.toString()
+        // logAndThrowError(makeError(
+        //     commonError.code,
+        //     commonError.message,
+        //     additionalDetails
+        // ))
+    }
+    return false;
+});
+/**
+ * Return a pre-signed url for a given object contained inside the provided AWS S3 bucket in order to perform a GET request.
+ * @notice the pre-signed url has a predefined expiration expressed in seconds inside the environment
+ * configuration of the `backend` package. The value should match the configuration of `phase2cli` package
+ * environment to avoid inconsistency between client request and CF.
+ */
+const generateGetObjectPreSignedUrl = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .https.onCall(async (data, context) => {
+    if (!context.auth)
+        logAndThrowError(COMMON_ERRORS.CM_NOT_AUTHENTICATED);
+    if (!data.bucketName || !data.objectKey)
+        logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA);
+    // Prepare input data.
+    const { objectKey, bucketName } = data;
+    // Check whether the bucket for which we are generating the pre-signed url is dedicated to a ceremony.
+    await checkIfBucketIsDedicatedToCeremony(bucketName);
+    // Connect to S3 client.
+    const S3 = await getS3Client();
+    // Prepare S3 command.
+    const command = new GetObjectCommand({ Bucket: bucketName, Key: objectKey });
+    try {
+        // Execute S3 command.
+        const url = await getSignedUrl(S3, command, { expiresIn: Number(process.env.AWS_PRESIGNED_URL_EXPIRATION) });
+        if (url) {
+            printLog(`The generated pre-signed url is ${url}`, LogLevel.DEBUG);
+            return url;
+        }
+    }
+    catch (error) {
+        // eslint-disable-next-line @typescript-eslint/no-shadow
+        // @todo handle more errors here.
+        // if (error.$metadata.httpStatusCode !== 200) {
+        const commonError = COMMON_ERRORS.CM_INVALID_REQUEST;
+        const additionalDetails = error.toString();
+        logAndThrowError(makeError(commonError.code, commonError.message, additionalDetails));
+        // }
+    }
+});
+/**
+ * Start a new multi-part upload for a specific object in the given AWS S3 bucket.
+ * @notice this operation can be performed by either an authenticated participant or a coordinator.
+ */
+const startMultiPartUpload = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .https.onCall(async (data, context) => {
+    if (!context.auth || (!context.auth.token.participant && !context.auth.token.coordinator))
+        logAndThrowError(COMMON_ERRORS.CM_NOT_AUTHENTICATED);
+    if (!data.bucketName || !data.objectKey || (context.auth?.token.participant && !data.ceremonyId))
+        logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA);
+    // Prepare data.
+    const { bucketName, objectKey, ceremonyId } = data;
+    const userId = context.auth?.uid;
+    // Check if the user is a current contributor.
+    if (context.auth?.token.participant && !!ceremonyId) {
+        // Check pre-condition.
+        await checkPreConditionForCurrentContributorToInteractWithMultiPartUpload(userId, ceremonyId);
+        // Check whether the bucket where the object for which we are generating the pre-signed url is dedicated to a ceremony.
+        await checkIfBucketIsDedicatedToCeremony(bucketName);
+        // Check the validity of the uploaded file.
+        await checkUploadingFileValidity(userId, ceremonyId, objectKey);
+    }
+    // Connect to S3 client.
+    const S3 = await getS3Client();
+    // Prepare S3 command.
+    const command = new CreateMultipartUploadCommand({
+        Bucket: bucketName,
+        Key: objectKey,
+        ACL: context.auth?.token.participant ? "private" : "public-read"
+    });
+    try {
+        // Execute S3 command.
+        const response = await S3.send(command);
+        if (response.$metadata.httpStatusCode === 200 && !!response.UploadId) {
+            printLog(`The multi-part upload identifier is ${response.UploadId}. Requested by ${userId}`, LogLevel.DEBUG);
+            return response.UploadId;
+        }
+    }
+    catch (error) {
+        // eslint-disable-next-line @typescript-eslint/no-shadow
+        // @todo handle more errors here.
+        if (error.$metadata.httpStatusCode !== 200) {
+            const commonError = COMMON_ERRORS.CM_INVALID_REQUEST;
+            const additionalDetails = error.toString();
+            logAndThrowError(makeError(commonError.code, commonError.message, additionalDetails));
+        }
+    }
+});
+/**
+ * Generate a new pre-signed url for each chunk related to a started multi-part upload.
+ * @notice this operation can be performed by either an authenticated participant or a coordinator.
+ * the pre-signed url has a predefined expiration expressed in seconds inside the environment
+ * configuration of the `backend` package. The value should match the configuration of `phase2cli` package
+ * environment to avoid inconsistency between client request and CF.
+ */
+const generatePreSignedUrlsParts = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB",
+    timeoutSeconds: 300
+})
+    .https.onCall(async (data, context) => {
+    if (!context.auth || (!context.auth.token.participant && !context.auth.token.coordinator))
+        logAndThrowError(COMMON_ERRORS.CM_NOT_AUTHENTICATED);
+    if (!data.bucketName ||
+        !data.objectKey ||
+        !data.uploadId ||
+        data.numberOfParts <= 0 ||
+        (context.auth?.token.participant && !data.ceremonyId))
+        logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA);
+    // Prepare data.
+    const { bucketName, objectKey, uploadId, numberOfParts, ceremonyId } = data;
+    const userId = context.auth?.uid;
+    // Check if the user is a current contributor.
+    if (context.auth?.token.participant && !!ceremonyId) {
+        // Check pre-condition.
+        await checkPreConditionForCurrentContributorToInteractWithMultiPartUpload(userId, ceremonyId);
+    }
+    // Connect to S3 client.
+    const S3 = await getS3Client();
+    // Prepare state.
+    const parts = [];
+    for (let i = 0; i < numberOfParts; i += 1) {
+        // Prepare S3 command for each chunk.
+        const command = new UploadPartCommand({
+            Bucket: bucketName,
+            Key: objectKey,
+            PartNumber: i + 1,
+            UploadId: uploadId
+        });
+        try {
+            // Get the pre-signed url for the specific chunk.
+            const url = await getSignedUrl(S3, command, {
+                expiresIn: Number(process.env.AWS_PRESIGNED_URL_EXPIRATION)
+            });
+            if (url) {
+                // Save.
+                parts.push(url);
+            }
+        }
+        catch (error) {
+            // eslint-disable-next-line @typescript-eslint/no-shadow
+            // @todo handle more errors here.
+            // if (error.$metadata.httpStatusCode !== 200) {
+            const commonError = COMMON_ERRORS.CM_INVALID_REQUEST;
+            const additionalDetails = error.toString();
+            logAndThrowError(makeError(commonError.code, commonError.message, additionalDetails));
+            // }
+        }
+    }
+    return parts;
+});
+/**
+ * Complete a multi-part upload for a specific object in the given AWS S3 bucket.
+ * @notice this operation can be performed by either an authenticated participant or a coordinator.
+ */
+const completeMultiPartUpload = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .https.onCall(async (data, context) => {
+    if (!context.auth || (!context.auth.token.participant && !context.auth.token.coordinator))
+        logAndThrowError(COMMON_ERRORS.CM_NOT_AUTHENTICATED);
+    if (!data.bucketName ||
+        !data.objectKey ||
+        !data.uploadId ||
+        !data.parts ||
+        (context.auth?.token.participant && !data.ceremonyId))
+        logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA);
+    // Prepare data.
+    const { bucketName, objectKey, uploadId, parts, ceremonyId } = data;
+    const userId = context.auth?.uid;
+    // Check if the user is a current contributor.
+    if (context.auth?.token.participant && !!ceremonyId) {
+        // Check pre-condition.
+        await checkPreConditionForCurrentContributorToInteractWithMultiPartUpload(userId, ceremonyId);
+        // Check if the bucket is dedicated to a ceremony.
+        await checkIfBucketIsDedicatedToCeremony(bucketName);
+    }
+    // Connect to S3.
+    const S3 = await getS3Client();
+    // Prepare S3 command.
+    const command = new CompleteMultipartUploadCommand({
+        Bucket: bucketName,
+        Key: objectKey,
+        UploadId: uploadId,
+        MultipartUpload: { Parts: parts }
+    });
+    try {
+        // Execute S3 command.
+        const response = await S3.send(command);
+        if (response.$metadata.httpStatusCode === 200 && !!response.Location) {
+            printLog(`Multi-part upload ${data.uploadId} completed. Object location: ${response.Location}`, LogLevel.DEBUG);
+            return response.Location;
+        }
+    }
+    catch (error) {
+        // eslint-disable-next-line @typescript-eslint/no-shadow
+        // @todo handle more errors here.
+        if (error.$metadata.httpStatusCode !== 200) {
+            const commonError = COMMON_ERRORS.CM_INVALID_REQUEST;
+            const additionalDetails = error.toString();
+            logAndThrowError(makeError(commonError.code, commonError.message, additionalDetails));
+        }
+    }
+});
+
+dotenv.config();
+/**
+ * Check and remove the current contributor if it doesn't complete the contribution on the specified amount of time.
+ * @dev since this cloud function is executed every minute, delay problems may occur. See issue #192 (https://github.com/quadratic-funding/mpc-phase2-suite/issues/192).
+ * @notice the reasons why a contributor may be considered blocking are many.
+ * for example due to network latency, disk availability issues, un/intentional crashes, limited hardware capabilities.
+ * the timeout mechanism (fixed/dynamic) could also influence this decision.
+ * this cloud function should check each circuit and:
+ * A) avoid timeout if there's no current contributor for the circuit.
+ * B) avoid timeout if the current contributor is the first for the circuit
+ * and timeout mechanism type is dynamic (suggestion: coordinator should be the first contributor).
+ * C) check if the current contributor is a potential blocking contributor for the circuit.
+ * D) discriminate between blocking contributor (= when downloading, computing, uploading contribution steps)
+ * or verification (= verifying contribution step) timeout types.
+ * E) execute timeout.
+ * E.1) prepare next contributor (if any).
+ * E.2) update circuit contributors waiting queue removing the current contributor.
+ * E.3) assign timeout to blocking contributor (participant doc update + timeout doc).
+ */
+const checkAndRemoveBlockingContributor = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .pubsub.schedule("every 1 minutes")
+    .onRun(async () => {
+    // Prepare Firestore DB.
+    const firestore = admin.firestore();
+    // Get current server timestamp in milliseconds.
+    const currentServerTimestamp = getCurrentServerTimestampInMillis();
+    // Get opened ceremonies.
+    const ceremonies = await queryOpenedCeremonies();
+    // For each ceremony.
+    for (const ceremony of ceremonies) {
+        if (!ceremony.data())
+            // Do not use `logAndThrowError` method to avoid the function to exit before checking every ceremony.
+            printLog(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA.message, LogLevel.WARN);
+        else {
+            // Get ceremony circuits.
+            const circuits = await getCeremonyCircuits(ceremony.id);
+            // Extract ceremony data.
+            const { timeoutType: timeoutMechanismType, penalty } = ceremony.data();
+            for (const circuit of circuits) {
+                if (!circuit.data())
+                    // Do not use `logAndThrowError` method to avoid the function to exit before checking every ceremony.
+                    printLog(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA.message, LogLevel.WARN);
+                else {
+                    // Extract circuit data.
+                    const { waitingQueue, avgTimings, dynamicThreshold, fixedTimeWindow } = circuit.data();
+                    const { contributors, currentContributor, failedContributions, completedContributions } = waitingQueue;
+                    const { fullContribution: avgFullContribution, contributionComputation: avgContributionComputation, verifyCloudFunction: avgVerifyCloudFunction } = avgTimings;
+                    // Case (A).
+                    if (!currentContributor)
+                        // Do not use `logAndThrowError` method to avoid the function to exit before checking every ceremony.
+                        printLog(`No current contributor for circuit ${circuit.id} - ceremony ${ceremony.id}`, LogLevel.WARN);
+                    else if (avgFullContribution === 0 &&
+                        avgContributionComputation === 0 &&
+                        avgVerifyCloudFunction === 0 &&
+                        completedContributions === 0 &&
+                        timeoutMechanismType === "DYNAMIC" /* CeremonyTimeoutType.DYNAMIC */)
+                        printLog(`No timeout will be executed for the first contributor to the circuit ${circuit.id} - ceremony ${ceremony.id}`, LogLevel.WARN);
+                    else {
+                        // Get current contributor document.
+                        const participant = await getDocumentById(getParticipantsCollectionPath(ceremony.id), currentContributor);
+                        if (!participant.data())
+                            // Do not use `logAndThrowError` method to avoid the function to exit before checking every ceremony.
+                            printLog(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA.message, LogLevel.WARN);
+                        else {
+                            // Extract participant data.
+                            const { contributionStartedAt, verificationStartedAt, contributionStep } = participant.data();
+                            // Case (C).
+                            // Compute dynamic timeout threshold.
+                            const timeoutDynamicThreshold = timeoutMechanismType === "DYNAMIC" /* CeremonyTimeoutType.DYNAMIC */
+                                ? (avgFullContribution / 100) * Number(dynamicThreshold)
+                                : 0;
+                            // Compute the timeout expiration date (in ms).
+                            const timeoutExpirationDateInMsForBlockingContributor = timeoutMechanismType === "DYNAMIC" /* CeremonyTimeoutType.DYNAMIC */
+                                ? Number(contributionStartedAt) +
+                                    Number(avgFullContribution) +
+                                    Number(timeoutDynamicThreshold)
+                                : Number(contributionStartedAt) + Number(fixedTimeWindow) * 60000; // * 60000 = convert minutes to millis.
+                            // Case (D).
+                            const timeoutExpirationDateInMsForVerificationCloudFunction = contributionStep === "VERIFYING" /* ParticipantContributionStep.VERIFYING */ &&
+                                !!verificationStartedAt
+                                ? Number(verificationStartedAt) + 3540000 // 3540000 = 59 minutes in ms.
+                                : 0;
+                            // Assign the timeout type.
+                            let timeoutType = "";
+                            if (timeoutExpirationDateInMsForBlockingContributor < currentServerTimestamp &&
+                                (contributionStep === "DOWNLOADING" /* ParticipantContributionStep.DOWNLOADING */ ||
+                                    contributionStep === "COMPUTING" /* ParticipantContributionStep.COMPUTING */ ||
+                                    contributionStep === "UPLOADING" /* ParticipantContributionStep.UPLOADING */))
+                                timeoutType = "BLOCKING_CONTRIBUTION" /* TimeoutType.BLOCKING_CONTRIBUTION */;
+                            if (timeoutExpirationDateInMsForVerificationCloudFunction > 0 &&
+                                timeoutExpirationDateInMsForVerificationCloudFunction < currentServerTimestamp &&
+                                contributionStep === "VERIFYING" /* ParticipantContributionStep.VERIFYING */)
+                                timeoutType = "BLOCKING_CLOUD_FUNCTION" /* TimeoutType.BLOCKING_CLOUD_FUNCTION */;
+                            printLog(`${timeoutType} detected for circuit ${circuit.id} - ceremony ${ceremony.id}`, LogLevel.DEBUG);
+                            if (!timeoutType)
+                                // Do not use `logAndThrowError` method to avoid the function to exit before checking every ceremony.
+                                printLog(`No timeout for circuit ${circuit.id} - ceremony ${ceremony.id}`, LogLevel.WARN);
+                            else {
+                                // Case (E).
+                                let nextCurrentContributorId = "";
+                                // Prepare Firestore batch of txs.
+                                const batch = firestore.batch();
+                                // Remove current contributor from waiting queue.
+                                contributors.shift();
+                                // Check if someone else is ready to start the contribution.
+                                if (contributors.length > 0) {
+                                    // Step (E.1).
+                                    // Take the next participant to be current contributor.
+                                    nextCurrentContributorId = contributors.at(0);
+                                    // Get the document of the next current contributor.
+                                    const nextCurrentContributor = await getDocumentById(getParticipantsCollectionPath(ceremony.id), nextCurrentContributorId);
+                                    // Prepare next current contributor.
+                                    batch.update(nextCurrentContributor.ref, {
+                                        status: "READY" /* ParticipantStatus.READY */,
+                                        lastUpdated: getCurrentServerTimestampInMillis()
+                                    });
+                                }
+                                // Step (E.2).
+                                // Update accordingly the waiting queue.
+                                batch.update(circuit.ref, {
+                                    waitingQueue: {
+                                        ...waitingQueue,
+                                        contributors,
+                                        currentContributor: nextCurrentContributorId,
+                                        failedContributions: failedContributions + 1
+                                    },
+                                    lastUpdated: getCurrentServerTimestampInMillis()
+                                });
+                                // Step (E.3).
+                                batch.update(participant.ref, {
+                                    status: "TIMEDOUT" /* ParticipantStatus.TIMEDOUT */,
+                                    lastUpdated: getCurrentServerTimestampInMillis()
+                                });
+                                // Compute the timeout duration (penalty) in milliseconds.
+                                const timeoutPenaltyInMs = Number(penalty) * 60000; // 60000 = amount of ms x minute.
+                                // Prepare an empty doc for timeout (w/ auto-gen uid).
+                                const timeout = await firestore
+                                    .collection(getTimeoutsCollectionPath(ceremony.id, participant.id))
+                                    .doc()
+                                    .get();
+                                // Prepare tx to store info about the timeout.
+                                batch.create(timeout.ref, {
+                                    type: timeoutType,
+                                    startDate: currentServerTimestamp,
+                                    endDate: currentServerTimestamp + timeoutPenaltyInMs
+                                });
+                                // Send atomic update for Firestore.
+                                await batch.commit();
+                                printLog(`The contributor ${participant.id} has been identified as potential blocking contributor. A timeout of type ${timeoutType} has been triggered w/ a penalty of ${timeoutPenaltyInMs} ms`, LogLevel.DEBUG);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+});
+/**
+ * Resume the contributor circuit contribution from scratch after the timeout expiration.
+ * @dev The participant can resume the contribution if and only if the last timeout in progress was verified as expired (status == EXHUMED).
+ */
+const resumeContributionAfterTimeoutExpiration = functions
+    .region("europe-west1")
+    .runWith({
+    memory: "512MB"
+})
+    .https.onCall(async (data, context) => {
+    if (!context.auth || (!context.auth.token.participant && !context.auth.token.coordinator))
+        logAndThrowError(SPECIFIC_ERRORS.SE_AUTH_NO_CURRENT_AUTH_USER);
+    if (!data.ceremonyId)
+        logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA);
+    // Get data.
+    const { ceremonyId } = data;
+    const userId = context.auth?.uid;
+    // Look for the ceremony document.
+    const ceremonyDoc = await getDocumentById(commonTerms.collections.ceremonies.name, ceremonyId);
+    const participantDoc = await getDocumentById(getParticipantsCollectionPath(ceremonyId), userId);
+    // Prepare documents data.
+    const participantData = participantDoc.data();
+    if (!ceremonyDoc.data() || !participantData)
+        logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA);
+    // Extract data.
+    const { contributionProgress, status } = participantData;
+    // Check pre-condition for resumable contribution after timeout expiration.
+    if (status === "EXHUMED" /* ParticipantStatus.EXHUMED */)
+        await participantDoc.ref.update({
+            status: "READY" /* ParticipantStatus.READY */,
+            lastUpdated: getCurrentServerTimestampInMillis(),
+            tempContributionData: {}
+        });
+    else
+        logAndThrowError(SPECIFIC_ERRORS.SE_CONTRIBUTE_CANNOT_PROGRESS_TO_NEXT_CIRCUIT);
+    printLog(`Contributor ${userId} can retry the contribution for the circuit in position ${contributionProgress + 1} after timeout expiration`, LogLevel.DEBUG);
+});
+
+admin.initializeApp();
+
+export { checkAndPrepareCoordinatorForFinalization, checkAndRemoveBlockingContributor, checkIfObjectExist, checkParticipantForCeremony, completeMultiPartUpload, coordinateCeremonyParticipant, createBucket, finalizeCeremony, finalizeCircuit, generateGetObjectPreSignedUrl, generatePreSignedUrlsParts, initEmptyWaitingQueueForCircuit, permanentlyStoreCurrentContributionTimeAndHash, processSignUpWithCustomClaims, progressToNextCircuitForContribution, progressToNextContributionStep, refreshParticipantAfterContributionVerification, registerAuthUser, resumeContributionAfterTimeoutExpiration, setupCeremony, startCeremony, startMultiPartUpload, stopCeremony, temporaryStoreCurrentContributionMultiPartUploadId, temporaryStoreCurrentContributionUploadedChunkData, verifycontribution };