@devtion/backend 0.0.0-7e983e3

package/src/functions/timeout.ts

@@ -0,0 +1,294 @@
+import * as functions from "firebase-functions"
+import admin from "firebase-admin"
+import dotenv from "dotenv"
+import {
+    CeremonyTimeoutType,
+    getParticipantsCollectionPath,
+    ParticipantContributionStep,
+    TimeoutType,
+    ParticipantStatus,
+    getTimeoutsCollectionPath,
+    commonTerms
+} from "@p0tion/actions"
+import {
+    getCeremonyCircuits,
+    getCurrentServerTimestampInMillis,
+    getDocumentById,
+    queryOpenedCeremonies
+} from "../lib/utils"
+import { COMMON_ERRORS, logAndThrowError, printLog, SPECIFIC_ERRORS } from "../lib/errors"
+import { LogLevel } from "../types/enums"
+
+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).
+ */
+export 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 { 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 === 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 === CeremonyTimeoutType.DYNAMIC
+                                        ? (avgFullContribution / 100) * Number(dynamicThreshold)
+                                        : 0
+
+                                // Compute the timeout expiration date (in ms).
+                                const timeoutExpirationDateInMsForBlockingContributor =
+                                    timeoutMechanismType === CeremonyTimeoutType.DYNAMIC
+                                        ? Number(contributionStartedAt) +
+                                          Number(avgFullContribution) +
+                                          Number(timeoutDynamicThreshold)
+                                        : Number(contributionStartedAt) + Number(fixedTimeWindow) * 60000 // * 60000 = convert minutes to millis.
+
+                                // Case (D).
+                                const timeoutExpirationDateInMsForVerificationCloudFunction =
+                                    contributionStep === ParticipantContributionStep.VERIFYING &&
+                                    !!verificationStartedAt
+                                        ? Number(verificationStartedAt) + 3540000 // 3540000 = 59 minutes in ms.
+                                        : 0
+
+                                // Assign the timeout type.
+                                let timeoutType: string = ""
+
+                                if (
+                                    timeoutExpirationDateInMsForBlockingContributor < currentServerTimestamp &&
+                                    (contributionStep === ParticipantContributionStep.DOWNLOADING ||
+                                        contributionStep === ParticipantContributionStep.COMPUTING ||
+                                        contributionStep === ParticipantContributionStep.UPLOADING)
+                                )
+                                    timeoutType = TimeoutType.BLOCKING_CONTRIBUTION
+
+                                if (
+                                    timeoutExpirationDateInMsForVerificationCloudFunction > 0 &&
+                                    timeoutExpirationDateInMsForVerificationCloudFunction < currentServerTimestamp &&
+                                    contributionStep === ParticipantContributionStep.VERIFYING
+                                )
+                                    timeoutType = 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(1)
+
+                                    // 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: 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: 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).
+ */
+export const resumeContributionAfterTimeoutExpiration = functions
+    .region("europe-west1")
+    .runWith({
+        memory: "512MB"
+    })
+    .https.onCall(async (data: { ceremonyId: string }, context: functions.https.CallableContext): Promise<void> => {
+        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 === ParticipantStatus.EXHUMED)
+            await participantDoc.ref.update({
+                status: ParticipantStatus.READY,
+                lastUpdated: getCurrentServerTimestampInMillis()
+            })
+        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
+        )
+    })

package/src/functions/user.ts

@@ -0,0 +1,142 @@
+import * as functions from "firebase-functions"
+import { UserRecord } from "firebase-functions/v1/auth"
+import admin from "firebase-admin"
+import dotenv from "dotenv"
+import { commonTerms, githubReputation } from "@p0tion/actions"
+import { encode } from "html-entities"
+import { getGitHubVariables, getCurrentServerTimestampInMillis } from "../lib/utils"
+import { logAndThrowError, makeError, printLog, SPECIFIC_ERRORS } from "../lib/errors"
+import { LogLevel } from "../types/enums"
+
+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.
+ */
+export const registerAuthUser = functions
+    .region("europe-west1")
+    .runWith({
+        memory: "512MB"
+    })
+    .auth.user()
+    .onCreate(async (user: UserRecord) => {
+        // 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
+        const encodedDisplayName = encode(displayName)
+        // 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 res = await githubReputation(
+                        user.providerData[0].uid,
+                        vars.minimumFollowing,
+                        vars.minimumFollowers,
+                        vars.minimumPublicRepos
+                    )
+                    if (!res) {
+                        // 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} 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.`
+                            )
+                        )
+                    }
+                    printLog(`Github reputation check passed for user ${user.displayName}`, LogLevel.DEBUG)
+                } catch (error: any) {
+                    // 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).
+        await userRef.set({
+            name: encodedDisplayName,
+            encodedDisplayName,
+            // Metadata.
+            creationTime,
+            lastSignInTime,
+            // Optional.
+            email: email || "",
+            emailVerified: emailVerified || false,
+            photoURL: photoURL || "",
+            lastUpdated: getCurrentServerTimestampInMillis()
+        })
+        printLog(`Authenticated user document 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.
+ */
+export const processSignUpWithCustomClaims = functions
+    .region("europe-west1")
+    .runWith({
+        memory: "512MB"
+    })
+    .auth.user()
+    .onCreate(async (user: UserRecord) => {
+        // Get user information.
+        if (!user.uid) logAndThrowError(SPECIFIC_ERRORS.SE_AUTH_NO_CURRENT_AUTH_USER)
+        // Prepare state.
+        let customClaims: any
+        // 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: any) {
+            const specificError = SPECIFIC_ERRORS.SE_AUTH_SET_CUSTOM_USER_CLAIMS_FAIL
+            const additionalDetails = error.toString()
+            logAndThrowError(makeError(specificError.code, specificError.message, additionalDetails))
+        }
+    })

package/src/lib/errors.ts

@@ -0,0 +1,237 @@
+import * as functions from "firebase-functions"
+import { FunctionsErrorCode, HttpsError } from "firebase-functions/v1/https"
+import { LogLevel } from "../types/enums"
+
+/**
+ * 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>
+ */
+export const makeError = (errorCode: FunctionsErrorCode, message: string, details?: string): HttpsError =>
+    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).
+ */
+export const printLog = (message: string, logLevel: 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.
+ */
+export const logAndThrowError = (error: HttpsError) => {
+    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.
+ */
+export 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."
+    )
+}
+
+/**
+ * A set of common errors.
+ * @notice these are errors that happen on multiple cloud functions (e.g., auth, missing data).
+ */
+export 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."
+    )
+}