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

BlockchainTest

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:51

Remarks

This provider DOES NOT enforce the 100 confirmations Coinbase Transaction rule.

Extends

• BaseBlockchain<AddressStatusPayload, BlockHeightPayload>

Constructors

Constructor

new BlockchainTest(parentBlockchain?): BlockchainTest;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:86

Parameters

Parameter	Type
parentBlockchain?	BaseBlockchain<unknown, unknown>

Returns

BlockchainTest

Overrides

BaseBlockchain.constructor

Methods

from()

static from<T>(this, parentBlockchain?): Promise<InstanceType<T>>;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:55

Type Parameters

Type Parameter
T extends typeof BlockchainTest

Parameters

Parameter	Type
this	T
parentBlockchain?	BaseBlockchain<unknown, unknown>

Returns

Promise<InstanceType<T>>

validateMiningFeeSats()

static validateMiningFeeSats(
   tx, 
   sourceOutputs, 
   feeRateSatsPerKb): void;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:863

Parameters

Parameter	Type
tx	Transaction
sourceOutputs	Output[]
feeRateSatsPerKb	bigint

Returns

void

start()

start(): Promise<void>;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:97

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

Overrides

BaseBlockchain.start

stop()

stop(): Promise<void>;

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

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

Overrides

BaseBlockchain.stop

fetchUTXO()

fetchUTXO(outpoint): Promise<Output>;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:101

Parameters

Parameter	Type
outpoint	string | Outpoint

Returns

Promise<Output>

Overrides

BaseBlockchain.fetchUTXO

fetchUTXOs()

fetchUTXOs(address): Promise<ExtMap<BlockchainUTXO>>;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:134

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

Parameters

Parameter	Type	Description
address	string	The blockchain address to query

Returns

Promise<ExtMap<BlockchainUTXO>>

A promise that resolves with the unspent outputs

Throws

If the address is invalid or the query fails

Overrides

BaseBlockchain.fetchUTXOs

fetchTransaction()

fetchTransaction(txHash): Promise<Transaction>;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:150

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

Overrides

BaseBlockchain.fetchTransaction

fetchAddressHistory()

fetchAddressHistory(address): Promise<ExtMap<BlockchainTransaction>>;

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

Retrieves all transactions associated with a specific address.

Parameters

Parameter	Type	Description
address	string	The blockchain address to query

Returns

Promise<ExtMap<BlockchainTransaction>>

A promise that resolves with the list of transactions

Throws

If the address is invalid or the query fails

Overrides

BaseBlockchain.fetchAddressHistory

fetchBlockHeader()

fetchBlockHeader(blockHeight): Promise<BlockHeader>;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:186

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

Overrides

BaseBlockchain.fetchBlockHeader

fetchChainTip()

fetchChainTip(): Promise<BlockchainChainTip>;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:197

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

Overrides

BaseBlockchain.fetchChainTip

broadcastTransaction()

broadcastTransaction(tx, opts): Promise<Transaction>;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:207

Broadcasts a raw transaction to the blockchain network.

Parameters

Parameter	Type	Description
tx	| string | Transaction | Uint8Array<ArrayBufferLike> | TransactionBCH	The serialized transaction data to broadcast
opts	{ skipValidation?: boolean; feeRateSatsPerKb?: bigint; }	-
opts.skipValidation?	boolean	-
opts.feeRateSatsPerKb?	bigint	-

Returns

Promise<Transaction>

A promise that resolves when the transaction is successfully broadcast

Throws

If the transaction is invalid or broadcasting fails

Overrides

BaseBlockchain.broadcastTransaction

subscribeLockscript()

subscribeLockscript(lockscript, callback): Promise<() => Promise<boolean>>;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:262

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<AddressStatusPayload>	The callback function to handle address-related events

Returns

Promise<() => Promise<boolean>>

A promise that resolves when the subscription is established

Throws

If the subscription cannot be created

Overrides

BaseBlockchain.subscribeLockscript

unsubscribeLockscript()

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

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:276

Removes a subscription for a specific blockchain address.

Parameters

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

Returns

Promise<boolean>

A promise that resolves when the subscription is removed

Throws

If the subscription cannot be removed

Overrides

BaseBlockchain.unsubscribeLockscript

subscribeAddress()

subscribeAddress(address, callback): Promise<() => Promise<boolean>>;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:290

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<AddressStatusPayload>	The callback function to handle address-related events

Returns

Promise<() => Promise<boolean>>

A promise that resolves when the subscription is established

Throws

If the subscription cannot be created

Overrides

BaseBlockchain.subscribeAddress

unsubscribeAddress()

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

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:309

Removes a subscription for a specific blockchain address.

Parameters

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

Returns

Promise<boolean>

A promise that resolves when the subscription is removed

Throws

If the subscription cannot be removed

Overrides

BaseBlockchain.unsubscribeAddress

subscribeTransaction()

subscribeTransaction(transactionHash, callback): Promise<() => Promise<boolean>>;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:335

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	The callback function to handle transaction-related events

Returns

Promise<() => Promise<boolean>>

A promise that resolves when the subscription is established

Throws

If the subscription cannot be created

Overrides

BaseBlockchain.subscribeTransaction

unsubscribeTransaction()

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

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:349

Removes a subscription for a specific transaction.

Parameters

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

Returns

Promise<boolean>

A promise that resolves when the subscription is removed

Throws

If the subscription cannot be removed

Overrides

BaseBlockchain.unsubscribeTransaction

addTransaction()

addTransaction(tx): void;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:421

Parameters

Parameter	Type
tx	BlockchainTransaction

Returns

void

removeTransaction()

removeTransaction(txHash): void;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:425

Parameters

Parameter	Type
txHash	string

Returns

void

deriveSpentUtxos()

deriveSpentUtxos(): Set<string>;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:429

Returns

Set<string>

deriveUtxoSet()

deriveUtxoSet(): BlockchainUTXOs;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:444

Returns

BlockchainUTXOs

mineBlock()

mineBlock(outputs, includeTransactionHashes?): Promise<void>;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:471

Parameters

Parameter	Type
outputs	Output[]
includeTransactionHashes?	string[]

Returns

Promise<void>

replaceBlocks()

replaceBlocks(blocks, options): void;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:562

Replace only the last N blocks (N = blocks.length) of the chain with the provided blocks. Transactions confirmed in the replaced blocks are first unconfirmed (set to height 0). Transactions listed in the new blocks are then confirmed at their new heights. Earlier blocks are preserved.

Parameters

Parameter	Type
blocks	object[]
options	Partial<{ dropMempool: boolean; }>

Returns

void

validateTransaction()

validateTransaction(
   tx, 
   sourceOutputs, 
   feeRateSatsPerKb): void;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:636

Parameters

Parameter	Type	Default value
tx	Transaction	undefined
sourceOutputs	Output[]	undefined
feeRateSatsPerKb	bigint	1000n

Returns

void

Remarks

Consider moving this to Transaction Primitive. Trade-off is that it's probably big. Maybe standalone util?

registerSourceMap()

registerSourceMap(scriptHex, debug): void;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:726

Parameters

Parameter	Type
scriptHex	string
debug	{ }

Returns

void

registerSourceMaps()

registerSourceMaps(scripts): void;

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:755

Parameters

Parameter	Type
scripts	TemplateScripts

Returns

void

toBlocks()

toBlocks(): object[];

Defined in: packages/templates-dev/src/blockchain/blockchain-test.ts:854

Convert the in-memory blockchain transactions to an array of blocks.

Returns

object[]

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[]>

Inherited from

BaseBlockchain.broadcastTransactions

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.

Inherited from

BaseBlockchain.waitForTransaction

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>

Inherited from

BaseBlockchain.waitForTransactionHash

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

BaseBlockchain.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

BaseBlockchain.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

BaseBlockchain.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

BaseBlockchain.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

BaseBlockchain.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

BaseBlockchain.waitFor