Module: services/eventService

Event Service for Satoshi Showdown. Provides functionalities for managing event-related operations such as creating, updating, deleting, and retrieving events. Also manages financial transactions and webhooks associated with events. This service acts as a bridge between the event controllers and the database models, ensuring that business logic and data manipulation are handled effectively.

Source:

Requires

Methods

(async, inner) awardWinner(eventId) → {Promise.<Object>}

Awards the prize to the winner of an event. This function is called after an event has been settled and a winner has been determined. It retrieves the event's UTXOs, calculates the total prize amount, creates a raw Bitcoin transaction for prize distribution, and updates the event status to 'completed'.

The function fetches the winner's user address from the participants array in the event document using the winner's user ID stored in the winners field. It ensures that the event is in the appropriate state for awarding the prize and that a winner is present. The prize is then sent to the winner's user address.

Parameters:
Name Type Description
eventId string

The unique identifier of the event whose winner is to be awarded.
Source:
Throws:

  • If the event or the winner is not found.

    Type
    NotFoundError

  • If the event is not in the correct state to award the winner or if there are issues in creating the transaction.

    Type
    Error
Returns:

An object containing details of the prize distribution transaction and the raw transaction.

Type
Promise.<Object>

(async, inner) castVote(eventId, userId, vote) → {Promise.<Object>}

Casts a vote for an event participant.

Parameters:
Name Type Description
eventId string

The event's unique identifier.
userId string

The user's unique identifier.
vote string

The vote cast by the user.
Source:
Throws:

  • If the event or user is not found.

    Type
    NotFoundError

  • If voting is not open or if invalid voting attempt.

    Type
    Error
Returns:

Confirmation message.

Type
Promise.<Object>

(async, inner) createEvent(eventData) → {Promise.<{event: Object, transaction: Object}>}

Creates a new event based on the provided user and event data, including financial setup. This process involves validating the event data, setting up a wallet, creating a transaction record, and saving the event to the database. The function returns both the created event and transaction details.

Parameters:
Name Type Description
eventData Object

Comprehensive data for creating the event.
Source:
Throws:

  • If the event data does not pass validation.

    Type
    ValidationError

  • If the user is not found in the database.

    Type
    NotFoundError
Returns:

An object containing the created event and transaction details.

Type
Promise.<{event: Object, transaction: Object}>

(async, inner) deleteEvent(eventId) → {Promise.<void>}

Deletes an event from the system based on its ID. This function removes the event and any associated data from the database, effectively canceling the event and cleaning up resources.

Parameters:
Name Type Description
eventId string

ID of the event to be deleted.
Source:
Throws:

When the event with the specified ID is not found.

Type
NotFoundError
Returns:

Indicates successful deletion of the event.

Type
Promise.<void>

(async, inner) determineOutcome(eventId) → {Promise.<Object>}

Determines the outcome of an event based on participant votes. Retrieves the event from the database, checks the vote results against the number of participants, and updates the event document accordingly.

Parameters:
Name Type Description
eventId string

The ID of the event to determine the outcome for.
Source:
Throws:

If the event is not found or if there's an error in processing the votes.

Type
Error
Returns:

An object representing the outcome of the event.

Type
Promise.<Object>

(async, inner) getAllEvents() → {Promise.<Array>}

Retrieves all events available in the system. This function is typically used to list all events, for example, in an administrative dashboard or a public event listing. It provides a complete overview of all events.

Source:
Returns:

An array containing all event objects in the database.

Type
Promise.<Array>

(async, inner) getEvent(eventId) → {Promise.<Object>}

Retrieves a specific event by its unique ID. This function is used to get detailed information about a single event, including its data and related transactions or webhooks.

Parameters:
Name Type Description
eventId string

ID of the event to be retrieved.
Source:
Throws:

When the event with the given ID does not exist in the database.

Type
NotFoundError
Returns:

The event object corresponding to the specified ID.

Type
Promise.<Object>

(async, inner) joinEvent(eventId, userId, prizePoolContributionopt) → {Promise.<Object>}

Adds a user to an event if there is space available, creates a transaction record, and sets up a webhook for transaction monitoring. Also handles optional prize pool contribution by the user.

Parameters:
Name Type Attributes Default Description
eventId string

The unique identifier of the event to join.
userId string

The unique identifier (UUID) of the user attempting to join the event.
prizePoolContribution number <optional>
 0

Optional contribution to the prize pool by the user.
Source:
Throws:

  • If the specified event or user is not found.

    Type
    NotFoundError

  • If the event is already full or closed for new participants.

    Type
    Error
Returns:

The updated event object reflecting the new participant and transaction.

Type
Promise.<Object>

(async, inner) refundEventCreator(eventId) → {Promise.<Object>}

Refunds the creator of an event.

Parameters:
Name Type Description
eventId string

ID of the event to refund.
Source:
Throws:

If the refund process encounters an issue.

Type
Error
Returns:

Details of the refund transaction.

Type
Promise.<Object>

(async, inner) refundUser(userId, eventId, refundAmountopt) → {Promise.<Object>}

Refunds a user associated with an event or a specific transaction.

Parameters:
Name Type Attributes Description
userId string

ID of the user to refund.
eventId string

ID of the event associated with the refund.
refundAmount number <optional>

Amount to refund. If not provided, full amount is refunded.
Source:
Throws:

If the refund process encounters an issue.

Type
Error
Returns:

Details of the refund transaction.

Type
Promise.<Object>

(async, inner) settleEvent(eventId)

Settles an event based on participant votes.

Parameters:
Name Type Description
eventId string

ID of the event to settle.
Source:

(async, inner) updateEvent(eventId, updateData) → {Promise.<Object>}

Updates an existing event based on the provided event ID and update data. This function looks up the event by its ID and applies the provided updates. It ensures that the event data is kept current and accurate.

Parameters:
Name Type Description
eventId string

ID of the event to be updated.
updateData Object

Data containing the updates to be applied to the event.

Properties
Name Type Description
name string

Updated name of the event.
description string

Updated detailed description of the event.
type string

Updated type or category of the event.
startTime Date

Updated scheduled start time of the event.
endTime Date

Updated scheduled end time of the event.
status string

Updated current status of the event.
entryFee number

Updated entry fee required to participate in the event.
prizePool number

Updated total prize pool available for the event winners.
creator ObjectID

Updated reference to the User model for the event creator.
participants Array

Updated list of participants in the event.
transactions Array

Updated associated financial transactions.
winners Array

Updated list of winners of the event.
config Object

Updated custom configuration options for the event.
streamingUrl string

Updated URL for live streaming of the event.
streamingSchedule Object

Updated schedule for the streaming of the event.
bettingOptions Array

Updated betting options available for the event.
viewCount number

Updated number of views or attendance count for the event.
feedback Array

Updated user feedback associated with the event.
socialSharingLinks Array

Updated links for social sharing of the event.
ageRestriction number

Updated age restriction for participation or viewing.
geographicRestrictions Array

Updated geographic restrictions for the event.
Source:
Throws:

When no event with the provided ID is found in the database.

Type
NotFoundError
Returns:

The updated event object, reflecting the changes made.

Type
Promise.<Object>