Module: services/walletService

Wallet Service for Satoshi Showdown. Provides functionalities for managing cryptocurrency wallets, specifically focusing on HD SegWit Bitcoin wallets. It includes operations such as wallet creation, retrieval, balance update, transaction association, and generating new addresses. This service is essential for financial transactions within the platform, ensuring secure and efficient management of wallets.

Source:

Requires

Methods

(async, inner) addUTXOToWallet(walletRef, utxoId) → {Promise.<Object>}

Adds a UTXO reference to a wallet. This function is essential for updating the wallet's transaction history and balance.

Parameters:
Name Type Description
walletRef string

The MongoDB ObjectId of the wallet.
utxoId string

The ID of the UTXO to add to the wallet.
Source:
Throws:

  • Thrown if the wallet or UTXO is not found.

    Type
    NotFoundError

  • Thrown if there is an issue updating the wallet.

    Type
    Error
Returns:

The updated wallet object with the new UTXO reference.

Type
Promise.<Object>

(async, inner) createAccurateFeeBitcoinTransaction(selectedUTXOs, toAddress, amountToSend, changeAddress, feeRate) → {Promise.<string>}

Creates a raw Bitcoin transaction with an accurately calculated fee.

Parameters:
Name Type Description
selectedUTXOs Array

Array of UTXOs to be used in the transaction.
toAddress string

The Bitcoin address to send the amount to.
amountToSend number

The amount to send in satoshis.
changeAddress string

The address where the change will be sent.
feeRate number

The fee rate in satoshis per byte.
Source:
Throws:
  • Throws an error if transaction creation fails.
Type
Error
Returns:
  • A promise that resolves to the raw transaction hex string.
Type
Promise.<string>

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

Creates a new HD SegWit wallet for an event, including the seed.

Source:
Throws:

If there's an issue in wallet generation or saving the wallet to the database.

Type
Error
Returns:

The created wallet object, including master public key, encrypted master private key, and encrypted seed.

Type
Promise.<Object>

(async, inner) createRawBitcoinTransaction(selectedUTXOs, toAddress, amountToSend, changeAddress, transactionFee) → {Promise.<string>}

Creates a raw Bitcoin transaction using UTXOs, target address, amount, change address, and a pre-calculated transaction fee. It signs the transaction inputs with the corresponding decrypted private keys from the wallets and includes the necessary witness scripts for SegWit transactions.

Parameters:
Name Type Description
selectedUTXOs Array

Array of selected UTXO objects for the transaction.
toAddress string

The Bitcoin address to send the amount to.
amountToSend number

The amount to send in satoshis.
changeAddress string

The address where the change will be sent.
transactionFee number

The pre-calculated transaction fee in satoshis.
Source:
Throws:

Throws an error if transaction creation fails.

Type
Error
Returns:

A promise that resolves to the raw transaction hex string.

Type
Promise.<string>

(async, inner) generateChildAddressForWallet(masterPublicKey, path) → {Promise.<Object>}

Generates a new child address from a given HD wallet's master public key.

Parameters:
Name Type Description
masterPublicKey string

The master public key of the HD wallet.
path string

The derivation path for the child address.
Source:
Throws:

If there's an issue in address generation.

Type
Error
Returns:

An object containing the child address and path.

Type
Promise.<Object>

(async, inner) getWalletByAddress(address) → {Promise.<Object>}

Retrieves a wallet by its public address from the database. This function is vital for various operations such as validating wallet existence, conducting transactions, and querying wallet balance. It is a key component in ensuring that operations involving a particular wallet address are accurately processed.

Parameters:
Name Type Description
address string

The public address of the wallet to be retrieved.
Source:
Throws:

  • Thrown if no wallet is found with the given public address.

    Type
    NotFoundError

  • Thrown if there is an issue with the database query.

    Type
    Error
Returns:

The wallet object corresponding to the provided public address.

Type
Promise.<Object>

(async, inner) getWalletById(walletId) → {Promise.<Wallet>}

Retrieves a wallet by its MongoDB ObjectId from the database. This function is essential for operations that require wallet details based on its unique ID.

Parameters:
Name Type Description
walletId string

The MongoDB ObjectId of the wallet to retrieve.
Source:
Throws:

Thrown if no wallet is found with the given ID.

Type
NotFoundError
Returns:

A promise that resolves to the wallet object.

Type
Promise.<Wallet>

(async, inner) updateWalletBalanceById(walletId, updateData) → {Promise.<Object>}

Updates the balance of an existing wallet record in the database by its MongoDB reference ID. This function focuses on updating only the confirmed and unconfirmed balances of the wallet. It retrieves the existing wallet record and applies balance updates as necessary.

Parameters:
Name Type Description
walletId string

The MongoDB reference ID of the wallet to update.
updateData Object

An object containing the new balance data for the wallet.
Source:
Throws:

  • Thrown if the wallet with the specified ID is not found in the database.

    Type
    NotFoundError

  • Thrown if there is an error during the update process.

    Type
    Error
Returns:

A promise that resolves to the updated wallet object.

Type
Promise.<Object>