Resolve "WIP: UTXO Selection and Storage"

2025-01-11 08:39:24 +00:00
parent f934216d68
commit 33fd9bac4d
156 changed files with 13304 additions and 4595 deletions
@@ -0,0 +1,155 @@
+import { EventEmitter } from '../utils';
+
+import {
+  type AddressCallback,
+  type BlockchainUTXOs,
+  type BlockchainTransactions,
+  type TransactionCallback,
+} from './types.js';
+
+import { type Transaction } from '@xocash/primitives';
+
+export type BlockchainEvents = {
+  isConnectedUpdated: boolean;
+  blockHeightUpdated: number | undefined;
+};
+
+/**
+ * Abstract base class representing a blockchain interface implementation.
+ * Extends EventEmitter to provide blockchain-specific event handling capabilities.
+ *
+ * This class serves as a template for concrete blockchain implementations,
+ * providing a standardized interface for common blockchain operations such as
+ * fetching transactions, managing UTXOs, and handling blockchain subscriptions.
+ *
+ * @abstract
+ * @extends {EventEmitter<BlockchainEvents>}
+ */
+export abstract class BaseBlockchain extends EventEmitter<BlockchainEvents> {
+  // TODO: Lockscript might be better as the Subscribe Handler.
+  //       From this, we can convert it to address.
+  //       Fulcrum has Scripthash too - but I'm hesitant about this.
+  //       Scripthash means SHA256'ing the Lockscript.
+  //       This is fine - but, at scale, will become expensive.
+  //       For example, imagine a HDWallet with 2000+ addresses.
+  //       And we want to subscribe to all of them.
+  //       Alternatively, we could just pass in an Address Primitive?
+  //       And then have the Adapter decide what it wants to use?
+
+  /**
+   * Initializes the blockchain connection and required resources.
+   * Should be called before performing any blockchain operations.
+   *
+   * @abstract
+   * @returns {Promise<void>} A promise that resolves when the blockchain connection is established
+   * @throws {Error} If the connection cannot be established
+   */
+  abstract start(): Promise<void>;
+
+  /**
+   * Gracefully terminates the blockchain connection and cleans up resources.
+   * Should be called when blockchain operations are no longer needed.
+   *
+   * @abstract
+   * @returns {Promise<void>} A promise that resolves when the shutdown is complete
+   */
+  abstract stop(): Promise<void>;
+
+  /**
+   * Retrieves all unspent transaction outputs (UTXOs) for a given address.
+   *
+   * @abstract
+   * @param {string} address - The blockchain address to query
+   * @returns {Promise<BlockchainUTXOs>} A promise that resolves with the unspent outputs
+   * @throws {Error} If the address is invalid or the query fails
+   */
+  abstract fetchUnspents(address: string): Promise<BlockchainUTXOs>;
+
+  /**
+   * Retrieves detailed information about a specific transaction.
+   *
+   * @abstract
+   * @param {string} txHash - The transaction hash/ID to look up
+   * @returns {Promise<Transaction>} A promise that resolves with the transaction details
+   * @throws {Error} If the transaction cannot be found or the query fails
+   */
+  abstract fetchTransaction(txHash: string): Promise<Transaction>;
+
+  /**
+   * Retrieves all transactions associated with a specific address.
+   *
+   * @abstract
+   * @param {string} address - The blockchain address to query
+   * @returns {Promise<BlockchainTransactions>} A promise that resolves with the list of transactions
+   * @throws {Error} If the address is invalid or the query fails
+   */
+  abstract fetchTransactions(address: string): Promise<BlockchainTransactions>;
+
+  /**
+   * Broadcasts a raw transaction to the blockchain network.
+   *
+   * @abstract
+   * @param {Uint8Array} transaction - The serialized transaction data to broadcast
+   * @returns {Promise<void>} A promise that resolves when the transaction is successfully broadcast
+   * @throws {Error} If the transaction is invalid or broadcasting fails
+   */
+  abstract broadcastTransaction(transaction: Uint8Array): Promise<void>;
+
+  /**
+   * Subscribes to updates for a specific blockchain address.
+   * The provided callback will be invoked when relevant events occur for the address.
+   *
+   * @abstract
+   * @param {string} address - The blockchain address to monitor
+   * @param {AddressCallback} callback - The callback function to handle address-related events
+   * @returns {Promise<void>} A promise that resolves when the subscription is established
+   * @throws {Error} If the subscription cannot be created
+   */
+  abstract subscribeAddress(
+    address: string,
+    callback: AddressCallback,
+  ): Promise<void>;
+
+  /**
+   * Removes a subscription for a specific blockchain address.
+   *
+   * @abstract
+   * @param {string} address - The blockchain address to unsubscribe from
+   * @param {AddressCallback} callback - The callback function to remove
+   * @returns {Promise<void>} A promise that resolves when the subscription is removed
+   * @throws {Error} If the subscription cannot be removed
+   */
+  abstract unsubscribeAddress(
+    address: string,
+    callback: AddressCallback,
+  ): Promise<void>;
+
+  /**
+   * Subscribes to updates for a specific transaction.
+   * The provided callback will be invoked when relevant events occur for the transaction.
+   *
+   * @abstract
+   * @param {string} transactionHash - The transaction hash to monitor
+   * @param {TransactionCallback} callback - The callback function to handle transaction-related events
+   * @returns {Promise<void>} A promise that resolves when the subscription is established
+   * @throws {Error} If the subscription cannot be created
+   */
+  abstract subscribeTransaction(
+    transactionHash: string,
+    callback: TransactionCallback,
+  ): Promise<void>;
+
+  /**
+   * Removes a subscription for a specific transaction.
+   *
+   * @abstract
+   * @param {string} transactionHash - The transaction hash to unsubscribe from
+   * @param {TransactionCallback} callback - The callback function to remove
+   * @returns {Promise<void>} A promise that resolves when the subscription is removed
+   * @throws {Error} If the subscription cannot be removed
+   */
+  abstract unsubscribeTransaction(
+    transactionHash: string,
+    callback: TransactionCallback,
+  ): Promise<void>;
+}