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

WalletGenesisData

type WalletGenesisData = Record<string, unknown>;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:22

---

WalletEvents

type WalletEvents = object;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:24

Properties

shouldMonitorUpdated

shouldMonitorUpdated: boolean;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:25

addressesUpdated

addressesUpdated: WalletAddresses;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:26

transactionsUpdated

transactionsUpdated: WalletTransactions;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:27

unspentsUpdated

unspentsUpdated: BlockchainUTXOs;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:28

stateUpdated

stateUpdated: string | null;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:29

---

abstract BaseWallet

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:41

Common interface for all wallet types.

Remarks

All function signatures are deliberately asynchronous to accommodate for cases where wallets might be remote. For example, we might eventually want to support a multisig service. Or we might have to support some other custodial "Apple Pay"-like OS-interface to get accepted onto their app store.

Extends

• EventEmitter<WalletEventsType>

Extended by

• WalletP2PKH

Type Parameters

Type Parameter	Default type
WalletEventsType extends WalletEvents	WalletEvents

Constructors

Constructor

new BaseWallet<WalletEventsType>(): BaseWallet<WalletEventsType>;

Returns

BaseWallet<WalletEventsType>

Inherited from

EventEmitter<WalletEventsType>.constructor

Methods

deriveKey()

static deriveKey(genesisData, keyName): Uint8Array<ArrayBufferLike>;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:51

Derive a key to use based on the given Genesis Data.

Parameters

Parameter	Type
genesisData	WalletGenesisData
keyName	string

Returns

Uint8Array<ArrayBufferLike>

Remarks

These keys can be used for Wallet Id's, Signing Keys, Encryption Keys and for Dapp Samdboxes.

deriveId()

static deriveId(genesisData): Uint8Array<ArrayBufferLike>;

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

Parameters

Parameter	Type
genesisData	WalletGenesisData

Returns

Uint8Array<ArrayBufferLike>

getId()

getId(): Promise<string>;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:77

Get the ID for this wallet.

Returns

Promise<string>

getEncryptionKey()

getEncryptionKey(): Promise<string>;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:86

Get the encryption key to use for this wallet.

Returns

Promise<string>

getSigningKey()

getSigningKey(): Promise<string>;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:95

Get the signing key to use for this wallet.

Returns

Promise<string>

start()

abstract start(): Promise<void>;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:104

Start monitoring this wallet for any transaction activity.

Returns

Promise<void>

stop()

abstract stop(): Promise<void>;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:109

Stop monitoring this wallet for any transaction activity.

Returns

Promise<void>

destroy()

abstract destroy(): Promise<void>;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:114

Remove any event listeners from this wallet.

Returns

Promise<void>

getTransactions()

abstract getTransactions(): Promise<WalletTransactions>;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:134

Fetch all transactions from the blockchain involving this wallet.

Returns

Promise<WalletTransactions>

Remarks

We will want to add a query argument so that workers can use this efficiently:

{
  limit?: number;
  offset?: number;
  sort?: () => number;
  filter?: () => boolean;
}

This "query" argument should be turned into a generic type as we will want to re-use it for Activities.

getUnspents()

abstract getUnspents(): Promise<BlockchainUTXOs>;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:139

Fetch all unspents from the blockchain belonging to this wallet.

Returns

Promise<BlockchainUTXOs>

getUnspentTokens()

getUnspentTokens(): Promise<BlockchainUTXOs>;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:144

Fetch all unspents tokens from the blockchain belonging to this wallet.

Returns

Promise<BlockchainUTXOs>

getUnspentDirectives()

abstract getUnspentDirectives(): Promise<WalletUTXOs>;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:170

Fetch all unspents from the blockchain belonging to this wallet.

Returns

Promise<WalletUTXOs>

Remarks

I was considering removing this and just storing unspents as "UTXOSignable"s. But that might not be ideal if we want to have Watch-only wallets. A better approach might be to have Fetch Unspents return Array<UTXO | UTXOSignable> Still need to flesh that out.

EDIT: We're going to want to store state for caching anyway... May as well just getUnspentDirectives() from the local state instead of fetch. Likewise for balances.

getBalanceSats()

abstract getBalanceSats(): Promise<bigint>;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:182

Get the satoshi balance of this wallet.

Returns

Promise<bigint>

Remarks

Consider confirmed/unconfirmed balances (or some other representation).

This becomes important in some instances because services like BitPay require one confirmation. This'll also have bearing on how we define our UTXO Selection strategies.

getBalanceTokens()

abstract getBalanceTokens(): Promise<TokenBalances>;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:194

Get the token balance of this wallet.

Returns

Promise<TokenBalances>

Remarks

Consider confirmed/unconfirmed balances (or some other representation).

This becomes important in some instances because services like BitPay require one confirmation. This'll also have bearing on how we define our UTXO Selection strategies.

getAddresses()

abstract getAddresses(): Promise<WalletAddresses>;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:199

Get all addresses belonging to this wallet.

Returns

Promise<WalletAddresses>

getReceivingAddress()

abstract getReceivingAddress(): Promise<Address>;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:204

Get the address that this wallet should receive to.

Returns

Promise<Address>

signTransaction()

abstract signTransaction(template): Promise<TransactionBuilder>;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:216

Select UTXOs from this wallet to meet the amounts required.

Parameters

Parameter	Type
template	Partial<TransactionTemplate>

Returns

Promise<TransactionBuilder>

Remarks

TODO: We are going to want to return the Transaction that was compiled.

TODO: This should accept a second argument (probably function) that can filter/sory UTXOs. The intent here is to provide a "spending policy". E.g. Only use (or prioritise) UTXOs with 1-conf.

sendTransaction()

abstract sendTransaction(template): Promise<Uint8Array<ArrayBufferLike>>;

Defined in: packages/templates-dev/src/wallet/base-wallet.ts:227

Select UTXOs from this wallet to meet the amounts required and broadcast it to the Blockchain.

Parameters

Parameter	Type
template	Partial<TransactionTemplate>

Returns

Promise<Uint8Array<ArrayBufferLike>>

Remarks

TODO: We are going to want to return the Transaction that was compiled.

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 string | number | symbol	The event type key

Parameters

Parameter	Type	Description
type	K	The event type to listen for
listener	Listener<WalletEventsType[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 string | number | symbol	The event type key

Parameters

Parameter	Type	Description
type	K	The event type to listen for
listener	Listener<WalletEventsType[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 string | number | symbol	The event type key

Parameters

Parameter	Type	Description
type	K	The event type to remove the listener from
listener	Listener<WalletEventsType[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 string | number | symbol	The event type key

Parameters

Parameter	Type	Description
type	K	The event type to emit
payload	WalletEventsType[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<WalletEventsType[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 string | number | symbol	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<WalletEventsType[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

Properties

Property	Modifier	Type	Defined in
blockchain	abstract	WalletBlockchain	packages/templates-dev/src/wallet/base-wallet.ts:69
genesisData	abstract	WalletGenesisData	packages/templates-dev/src/wallet/base-wallet.ts:72