Documentation / @cashconnect-js/templates-dev / blockchain/base-blockchain

BlockchainEvents

type BlockchainEvents = object;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:19

Properties

isConnectedUpdated

isConnectedUpdated: boolean;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:20

blockHeightUpdated

blockHeightUpdated: number | undefined;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:21

---

abstract BaseBlockchain

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:35

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.

Extends

• EventEmitter<BlockchainEvents>

Extended by

• BlockchainElectrum
• BlockchainTest

Type Parameters

Type Parameter	Default type
AddressNotificationPayload	undefined
TransactionNotificationPayload	undefined

Constructors

Constructor

new BaseBlockchain<AddressNotificationPayload, TransactionNotificationPayload>(): BaseBlockchain<AddressNotificationPayload, TransactionNotificationPayload>;

Returns

BaseBlockchain<AddressNotificationPayload, TransactionNotificationPayload>

Inherited from

EventEmitter<BlockchainEvents>.constructor

Methods

start()

abstract start(): Promise<void>;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:56

Initializes the blockchain connection and required resources. Should be called before performing any blockchain operations.

Returns

Promise<void>

A promise that resolves when the blockchain connection is established

Throws

If the connection cannot be established

stop()

abstract stop(): Promise<void>;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:64

Gracefully terminates the blockchain connection and cleans up resources. Should be called when blockchain operations are no longer needed.

Returns

Promise<void>

A promise that resolves when the shutdown is complete

fetchUTXO()

abstract fetchUTXO(outpoint): Promise<Output>;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:70

Parameters

Parameter	Type
outpoint	string | Outpoint

Returns

Promise<Output>

fetchUTXOs()

abstract fetchUTXOs(address): Promise<BlockchainUTXOs>;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:79

Retrieves all unspent transaction outputs (UTXOs) for a given address.

Parameters

Parameter	Type	Description
address	string	The blockchain address to query

Returns

Promise<BlockchainUTXOs>

A promise that resolves with the unspent outputs

Throws

If the address is invalid or the query fails

fetchAddressHistory()

abstract fetchAddressHistory(address): Promise<BlockchainTransactions>;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:88

Retrieves all transactions associated with a specific address.

Parameters

Parameter	Type	Description
address	string	The blockchain address to query

Returns

Promise<BlockchainTransactions>

A promise that resolves with the list of transactions

Throws

If the address is invalid or the query fails

fetchBlockHeader()

abstract fetchBlockHeader(blockHeight): Promise<BlockHeader>;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:99

Retrieves the Block Header at the given height.

Parameters

Parameter	Type	Description
blockHeight	number	The block height of the header to retrieve

Returns

Promise<BlockHeader>

A promise that resolves with the Block Header

Throws

If the block number is invalid or the query fails

fetchChainTip()

abstract fetchChainTip(): Promise<BlockchainChainTip>;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:107

Retrieves the current chain tip block.

Returns

Promise<BlockchainChainTip>

A promise that resolves with the current chain tip

Throws

If the chain tip cannot be retrieved

fetchTransaction()

abstract fetchTransaction(txHash): Promise<Transaction>;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:116

Retrieves detailed information about a specific transaction.

Parameters

Parameter	Type	Description
txHash	string | Uint8Array<ArrayBufferLike>	The transaction hash/ID to look up

Returns

Promise<Transaction>

A promise that resolves with the transaction details

Throws

If the transaction cannot be found or the query fails

broadcastTransaction()

abstract broadcastTransaction(transaction): Promise<Transaction>;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:125

Broadcasts a raw transaction to the blockchain network.

Parameters

Parameter	Type	Description
transaction	| string | Transaction | Uint8Array<ArrayBufferLike> | TransactionBCH	The serialized transaction data to broadcast

Returns

Promise<Transaction>

A promise that resolves when the transaction is successfully broadcast

Throws

If the transaction is invalid or broadcasting fails

subscribeLockscript()

abstract subscribeLockscript(lockscript, callback): Promise<BlockchainUnsubscribeCallback>;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:138

Subscribes to updates for a specific lockscript. The provided callback will be invoked when relevant events occur for the address.

Parameters

Parameter	Type	Description
lockscript	string | Uint8Array<ArrayBufferLike>	The blockchain lockscript to monitor
callback	BlockchainCallback<AddressNotificationPayload>	The callback function to handle address-related events

Returns

Promise<BlockchainUnsubscribeCallback>

A promise that resolves when the subscription is established

Throws

If the subscription cannot be created

unsubscribeLockscript()

abstract unsubscribeLockscript(lockscript, callback): Promise<boolean>;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:151

Removes a subscription for a specific blockchain address.

Parameters

Parameter	Type	Description
lockscript	string | Uint8Array<ArrayBufferLike>	The blockchain lockscript to unsubscribe from
callback	BlockchainCallback<AddressNotificationPayload>	The callback function to remove

Returns

Promise<boolean>

A promise that resolves when the subscription is removed

Throws

If the subscription cannot be removed

subscribeAddress()

abstract subscribeAddress(address, callback): Promise<BlockchainUnsubscribeCallback>;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:165

Subscribes to updates for a specific blockchain address. The provided callback will be invoked when relevant events occur for the address.

Parameters

Parameter	Type	Description
address	string	The blockchain address to monitor
callback	BlockchainCallback<AddressNotificationPayload>	The callback function to handle address-related events

Returns

Promise<BlockchainUnsubscribeCallback>

A promise that resolves when the subscription is established

Throws

If the subscription cannot be created

unsubscribeAddress()

abstract unsubscribeAddress(address, callback): Promise<boolean>;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:178

Removes a subscription for a specific blockchain address.

Parameters

Parameter	Type	Description
address	string	The blockchain address to unsubscribe from
callback	BlockchainCallback<AddressNotificationPayload>	The callback function to remove

Returns

Promise<boolean>

A promise that resolves when the subscription is removed

Throws

If the subscription cannot be removed

subscribeTransaction()

abstract subscribeTransaction(transactionHash, callback): Promise<BlockchainUnsubscribeCallback>;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:192

Subscribes to updates for a specific transaction. The provided callback will be invoked when relevant events occur for the transaction.

Parameters

Parameter	Type	Description
transactionHash	string	The transaction hash to monitor
callback	BlockchainCallback<TransactionNotificationPayload>	The callback function to handle transaction-related events

Returns

Promise<BlockchainUnsubscribeCallback>

A promise that resolves when the subscription is established

Throws

If the subscription cannot be created

unsubscribeTransaction()

abstract unsubscribeTransaction(transactionHash, callback): Promise<boolean>;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:205

Removes a subscription for a specific transaction.

Parameters

Parameter	Type	Description
transactionHash	string	The transaction hash to unsubscribe from
callback	BlockchainCallback<TransactionNotificationPayload>	The callback function to remove

Returns

Promise<boolean>

A promise that resolves when the subscription is removed

Throws

If the subscription cannot be removed

broadcastTransactions()

broadcastTransactions(transactions): Promise<Transaction[]>;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:210

Parameters

Parameter	Type
transactions	( | string | Transaction | Uint8Array<ArrayBufferLike> | TransactionBCH)[]

Returns

Promise<Transaction[]>

waitForTransaction()

waitForTransaction(tx, timeoutMs): Promise<void>;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:232

Waits for a transaction to be seen by the node.

Parameters

Parameter	Type	Default value	Description
tx	| string | Transaction | Uint8Array<ArrayBufferLike> | TransactionBCH	undefined	The transaction to wait for. Can be a Uint8Array, Transaction instance, or a string.
timeoutMs	number	10_000	The maximum time to wait in milliseconds before timing out. Defaults to 10,000ms (10 seconds).

Returns

Promise<void>

A Promise that resolves when the transaction is seen by the node or rejects if the timeout is reached.

Throws

Error if the transaction is not seen by the node within the specified timeout.

waitForTransactionHash()

waitForTransactionHash(txHash, timeoutMs): Promise<void>;

Defined in: packages/templates-dev/src/blockchain/base-blockchain.ts:242

Parameters

Parameter	Type	Default value
txHash	string | TransactionHash | Uint8Array<ArrayBufferLike>	undefined
timeoutMs	number	10_000

Returns

Promise<void>

on()

on<K>(
   type, 
   listener, 
   debounceMilliseconds?): OffCallback;

Defined in: packages/core/dist/primitives.d.ts:593

Registers a listener for the specified event type.

Type Parameters

Type Parameter	Description
K extends keyof BlockchainEvents	The event type key

Parameters

Parameter	Type	Description
type	K	The event type to listen for
listener	Listener<BlockchainEvents[K]>	The function to call when the event is emitted
debounceMilliseconds?	number	Optional debounce time in milliseconds

Returns

OffCallback

A callback function that can be used to unregister this listener

Example

const off = emitter.on('data-change', (data) => {
  console.log('Data updated:', data);
}, 300); // Debounce for 300ms

// Later, unregister the listener
off();

Inherited from

EventEmitter.on

once()

once<K>(
   type, 
   listener, 
   debounceMilliseconds?): OffCallback;

Defined in: packages/core/dist/primitives.d.ts:611

Registers a one-time listener for the specified event type. The listener will be automatically removed after being called once.

Type Parameters

Type Parameter	Description
K extends keyof BlockchainEvents	The event type key

Parameters

Parameter	Type	Description
type	K	The event type to listen for
listener	Listener<BlockchainEvents[K]>	The function to call when the event is emitted
debounceMilliseconds?	number	Optional debounce time in milliseconds

Returns

OffCallback

A callback function that can be used to unregister this listener before it fires

Example

emitter.once('user-login', ({ userId }) => {
  console.log(`Welcome ${userId}! This will only show once.`);
});

Inherited from

EventEmitter.once

off()

off<K>(type, listener): void;

Defined in: packages/core/dist/primitives.d.ts:626

Removes a specific listener for the given event type.

Type Parameters

Type Parameter	Description
K extends keyof BlockchainEvents	The event type key

Parameters

Parameter	Type	Description
type	K	The event type to remove the listener from
listener	Listener<BlockchainEvents[K]>	The listener function to remove

Returns

void

Example

const handler = (data) => console.log(data);
emitter.on('test', handler);
emitter.off('test', handler); // Removes the listener

Inherited from

EventEmitter.off

emit()

emit<K>(type, payload): boolean;

Defined in: packages/core/dist/primitives.d.ts:648

Emits an event of the specified type with the given payload. All registered listeners for this event type will be called.

Type Parameters

Type Parameter	Description
K extends keyof BlockchainEvents	The event type key

Parameters

Parameter	Type	Description
type	K	The event type to emit
payload	BlockchainEvents[K]	The data to pass to all listeners

Returns

boolean

true if there were listeners for this event, false otherwise

Example

const hasListeners = emitter.emit('user-login', {
  userId: '123',
  timestamp: Date.now()
});

if (!hasListeners) {
  console.log('No one was listening for user-login events');
}

Inherited from

EventEmitter.emit

removeAllListeners()

removeAllListeners(): void;

Defined in: packages/core/dist/primitives.d.ts:659

Removes all listeners for all events. This effectively resets the EventEmitter to its initial state.

Returns

void

Example

emitter.removeAllListeners();
// All previously registered listeners are now gone

Inherited from

EventEmitter.removeAllListeners

waitFor()

waitFor<K>(
   type, 
   predicate, 
   timeoutMs?): Promise<BlockchainEvents[K]>;

Defined in: packages/core/dist/primitives.d.ts:685

Returns a Promise that resolves when an event of the specified type is emitted and matches the given predicate.

Type Parameters

Type Parameter	Description
K extends keyof BlockchainEvents	The event type key

Parameters

Parameter	Type	Description
type	K	The event type to wait for
predicate	(payload) => boolean	A function that determines if the event payload matches what we're waiting for
timeoutMs?	number	Optional timeout in milliseconds. If specified, the promise will reject after this time

Returns

Promise<BlockchainEvents[K]>

A Promise that resolves with the event payload when the condition is met

Throws

If the timeout is reached before a matching event occurs

Example

try {
  const loginData = await emitter.waitFor(
    'user-login',
    ({ userId }) => userId === 'admin',
    5000 // Wait up to 5 seconds
  );
  console.log('Admin logged in:', loginData);
} catch (error) {
  console.log('Timeout: Admin never logged in');
}

Inherited from

EventEmitter.waitFor