QiHDWallet

The Qi HD wallet is a BIP44-compliant hierarchical deterministic wallet used for managing a set of addresses in the Qi ledger. This is wallet implementation is the primary way to interact with the Qi UTXO ledger on the Quai network.

The Qi HD wallet supports:

• Adding accounts to the wallet heierchy
• Generating addresses for a specific account in any Zone
• Signing and sending transactions for any address in the wallet
• Serializing the wallet to JSON and deserializing it back to a wallet instance.

​

Example

import { QiHDWallet, Zone } from 'quais';

const wallet = new QiHDWallet();
const cyrpus1Address = await wallet.getNextAddress(0, Zone.Cyrpus1); // get the first address in the Cyrpus1 zone
await wallet.sendTransaction({ txInputs: [...], txOutputs: [...] }); // send a transaction
const serializedWallet = wallet.serialize(); // serialize current (account/address) state of the wallet
.
.
.
const deserializedWallet = QiHDWallet.deserialize(serializedWallet); // create a new wallet instance from the serialized data

​

Extends

• AbstractHDWallet

​

Properties

​

Accessors

​

openChannels

get openChannels(): string[]

Gets the payment codes for all open channels.

​

Returns

string[]

The payment codes for all open channels.

​

Source

wallet/qi-hdwallet.ts:206

​

xPub

get xPub(): string

Returns the extended public key of the root node of the HD wallet.

​

Returns

string

The extended public key.

​

Source

wallet/hdwallet.ts:94

​

Methods

​

_findLastUsedIndex()

private _findLastUsedIndex(
   addresses, 
   account, 
   zone): number

Finds the last used index in an array of QiAddressInfo objects. If no index is found, returns -1.

​

Parameters

​

Returns

number

The last used index.

​

Source

wallet/qi-hdwallet.ts:227

​

_getNextQiAddress()

private _getNextQiAddress(
   account, 
   zone, 
   isChange): QiAddressInfo

Derives the next Qi BIP 44 address for the specified account and zone.

​

Parameters

​

Returns

QiAddressInfo

The next Qi address information.

​

Source

wallet/qi-hdwallet.ts:242

​

_getPaymentCodePrivate()

private _getPaymentCodePrivate(account): PaymentCodePrivate

Generates a BIP47 private payment code for the specified account. The payment code is created by combining the account’s public key and chain code.

​

Parameters

​

Returns

PaymentCodePrivate

A promise that resolves to the PaymentCodePrivate instance.

​

Source

wallet/qi-hdwallet.ts:1376

​

_scan()

private _scan(zone, account?): Promise<void>

Internal method to scan the specified zone for addresses with unspent outputs. This method handles the actual scanning logic, generating new addresses until the gap limit is reached for both gap and change addresses.

​

Parameters

​

Returns

Promise<void>

A promise that resolves when the scan is complete.

​

Throws

If the provider is not set.

​

Source

wallet/qi-hdwallet.ts:1015

​

_scanDerivationPath()

private _scanDerivationPath(
   path, 
   zone, 
account): Promise<void>

Scans for the next address in the specified zone and account, checking for associated outpoints, and updates the address count and gap addresses accordingly.

​

Parameters

​

Returns

Promise<void>

A promise that resolves when the scan is complete.

​

Throws

If an error occurs during the address scanning or outpoints retrieval process.

​

Source

wallet/qi-hdwallet.ts:1033

​

addAddress()

addAddress(
   account, 
   addressIndex, 
   isChange?): NeuteredAddressInfo

Adds an address to the wallet.

​

Parameters

​

Returns

NeuteredAddressInfo

The added address info.

​

Inherited from

AbstractHDWallet.addAddress

​

Source

wallet/hdwallet.ts:152

​

checkAddressUse()

private checkAddressUse(address): Promise<{
  "isUsed": boolean;
  "outpoints": Outpoint[];
}>

Checks if the specified address is used by querying the network node for the outpoints of the address. If the address is used, the outpoints are imported into the wallet.

​

Parameters

​

Returns

Promise<{ "isUsed": boolean; "outpoints": Outpoint[]; }>

A promise that resolves to an object containing a boolean indicating whether the address is used and an array of outpoints.

isUsed

isUsed: boolean;

outpoints

outpoints: Outpoint[];

​

Throws

If the query fails.

​

Source

wallet/qi-hdwallet.ts:1124

​

checkPendingOutpoints()

private checkPendingOutpoints(zone): Promise<void>

Checks the status of pending outpoints and updates the wallet’s UTXO set accordingly.

​

Parameters

​

Returns

Promise<void>

​

Source

wallet/qi-hdwallet.ts:778

​

connect()

connect(provider): void

Connects the wallet to a provider.

​

Parameters

​

Returns

void

​

Inherited from

AbstractHDWallet.connect

​

Source

wallet/hdwallet.ts:385

​

convertToQuai()

convertToQuai(destinationAddress, amount): Promise<TransactionResponse>

Converts an amount of Qi to Quai and sends it to a specified Quai address.

​

Parameters

​

Returns

Promise<TransactionResponse>

A promise that resolves to the transaction response.

​

Throws

If the destination address is invalid, the amount is zero, or the conversion fails.

​

Source

wallet/qi-hdwallet.ts:644

​

getAddressInfo()

getAddressInfo(address): null | NeuteredAddressInfo

Gets the address info for a given address.

​

Parameters

​

Returns

null | NeuteredAddressInfo

The address info or null if not found.

​

Inherited from

AbstractHDWallet.getAddressInfo

​

Source

wallet/hdwallet.ts:243

​

getAddressesForAccount()

getAddressesForAccount(account): NeuteredAddressInfo[]

Gets the addresses for a given account.

​

Parameters

​

Returns

NeuteredAddressInfo[]

The addresses for the account.

​

Inherited from

AbstractHDWallet.getAddressesForAccount

​

Source

wallet/hdwallet.ts:269

​

getAddressesForZone()

getAddressesForZone(zone): QiAddressInfo[]

Gets the addresses for the specified zone.

​

Parameters

​

Returns

QiAddressInfo[]

The addresses for the zone.

​

Overrides

AbstractHDWallet.getAddressesForZone

​

Source

wallet/qi-hdwallet.ts:1147

​

getBalanceForZone()

getBalanceForZone(zone): bigint

Gets the total balance for the specified zone, including locked UTXOs.

​

Parameters

​

Returns

bigint

The total balance for the zone.

​

Source

wallet/qi-hdwallet.ts:381

​

getChangeAddressInfo()

getChangeAddressInfo(address): null | QiAddressInfo

Gets the address info for a given address.

​

Parameters

​

Returns

null | QiAddressInfo

The address info or null if not found.

​

Source

wallet/qi-hdwallet.ts:1529

​

getChangeAddressesForZone()

getChangeAddressesForZone(zone): QiAddressInfo[]

Gets the change addresses for the specified zone.

​

Parameters

​

Returns

QiAddressInfo[]

The change addresses for the zone.

​

Source

wallet/qi-hdwallet.ts:1158

​

getGapAddressesForZone()

getGapAddressesForZone(zone): QiAddressInfo[]

Gets the gap addresses for the specified zone.

​

Parameters

​

Returns

QiAddressInfo[]

The gap addresses for the zone.

​

Source

wallet/qi-hdwallet.ts:1169

​

getGapChangeAddressesForZone()

getGapChangeAddressesForZone(zone): QiAddressInfo[]

Gets the gap change addresses for the specified zone.

​

Parameters

​

Returns

QiAddressInfo[]

The gap change addresses for the zone.

​

Source

wallet/qi-hdwallet.ts:1183

​

getGapPaymentChannelAddresses()

getGapPaymentChannelAddresses(paymentCode): QiAddressInfo[]

Gets the gap payment channel addresses for the specified payment code.

​

Parameters

​

Returns

QiAddressInfo[]

The gap payment channel addresses for the payment code.

​

Source

wallet/qi-hdwallet.ts:1208

​

getLockedBalanceForZone()

getLockedBalanceForZone(zone, blockNumber?): Promise<bigint>

Gets the locked balance for the specified zone.

​

Parameters

​

Returns

Promise<bigint>

The locked balance for the zone.

​

Source

wallet/qi-hdwallet.ts:420

​

getNextAddress()

getNextAddress(account, zone): Promise<QiAddressInfo>

Promise that resolves to the next address for the specified account and zone.

​

Parameters

​

Returns

Promise<QiAddressInfo>

The next Qi address information.

​

Overrides

AbstractHDWallet.getNextAddress

​

Source

wallet/qi-hdwallet.ts:267

​

getNextAddressSync()

getNextAddressSync(account, zone): QiAddressInfo

Synchronously retrieves the next address for the specified account and zone.

​

Parameters

​

Returns

QiAddressInfo

The next Qi address information.

​

Overrides

AbstractHDWallet.getNextAddressSync

​

Source

wallet/qi-hdwallet.ts:278

​

getNextChangeAddress()

getNextChangeAddress(account, zone): Promise<QiAddressInfo>

Promise that resolves to the next change address for the specified account and zone.

​

Parameters

​

Returns

Promise<QiAddressInfo>

The next change neutered address information.

​

Source

wallet/qi-hdwallet.ts:289

​

getNextChangeAddressSync()

getNextChangeAddressSync(account, zone): QiAddressInfo

Synchronously retrieves the next change address for the specified account and zone.

​

Parameters

​

Returns

QiAddressInfo

The next change neutered address information.

​

Source

wallet/qi-hdwallet.ts:300

​

getNextReceiveAddress()

getNextReceiveAddress(
   senderPaymentCode, 
   zone, 
   account): QiAddressInfo

Generates a payment address for receiving funds from the specified sender’s BIP47 payment code. Uses Diffie-Hellman key exchange to derive the address from the sender’s public key and receiver’s private key.

​

Parameters

​

Returns

QiAddressInfo

A promise that resolves to the payment address for receiving funds.

​

Throws

Throws an error if the payment code version is invalid.

​

Source

wallet/qi-hdwallet.ts:1458

​

getNextSendAddress()

getNextSendAddress(
   receiverPaymentCode, 
   zone, 
   account): QiAddressInfo

Generates a payment address for sending funds to the specified receiver’s BIP47 payment code. Uses Diffie-Hellman key exchange to derive the address from the receiver’s public key and sender’s private key.

​

Parameters

​

Returns

QiAddressInfo

A promise that resolves to the payment address for sending funds.

​

Throws

Throws an error if the payment code version is invalid.

​

Source

wallet/qi-hdwallet.ts:1408

​

getOutpoints()

getOutpoints(zone): OutpointInfo[]

Gets the outpoints for the specified zone.

​

Parameters

​

Returns

OutpointInfo[]

The outpoints for the zone.

​

Source

wallet/qi-hdwallet.ts:329

​

getPaymentChannelAddressesForZone()

getPaymentChannelAddressesForZone(paymentCode, zone): QiAddressInfo[]

Gets the payment channel addresses for the specified zone.

​

Parameters

​

Returns

QiAddressInfo[]

The payment channel addresses for the zone.

​

Source

wallet/qi-hdwallet.ts:1198

​

getPaymentCode()

getPaymentCode(account): string

Creates a new BIP47 payment code for the specified account. The payment code is derived from the account’s BIP32 root key.

​

Parameters

​

Returns

string

A promise that resolves to the Base58-encoded BIP47 payment code.

​

Source

wallet/qi-hdwallet.ts:1363

​

getPrivateKey()

getPrivateKey(address): string

Returns the private key for a given address. This method should be used with caution as it exposes the private key to the user.

​

Parameters

​

Returns

string

The private key.

​

Inherited from

AbstractHDWallet.getPrivateKey

​

Source

wallet/hdwallet.ts:258

​

getPrivateKeyForTxInput()

private getPrivateKeyForTxInput(input): string

Retrieves the private key for a given transaction input.

This method derives the private key for a transaction input by locating the address info and then deriving the private key based on where the address info was found:

• For BIP44 addresses (standard or change), it uses the HD wallet to derive the private key.
• For payment channel addresses (BIP47), it uses PaymentCodePrivate to derive the private key.

​

Parameters

​

Returns

string

The private key corresponding to the transaction input.

​

Throws

If the input does not contain a public key or if the address information cannot be found.

​

Source

wallet/qi-hdwallet.ts:917

​

getSpendableBalanceForZone()

getSpendableBalanceForZone(zone, blockNumber?): Promise<bigint>

Gets the locked balance for the specified zone.

​

Parameters

​

Returns

Promise<bigint>

The locked balance for the zone.

​

Source

wallet/qi-hdwallet.ts:398

​

importOutpoints()

importOutpoints(outpoints): void

Imports an array of outpoints.

​

Parameters

​

Returns

void

​

Source

wallet/qi-hdwallet.ts:309

​

locateAddressInfo()

locateAddressInfo(address): null | QiAddressInfo

Locates the address information for the given address, searching through standard addresses, change addresses, and payment channel addresses.

​

Parameters

​

Returns

null | QiAddressInfo

The address info or null if not found.

​

Source

wallet/qi-hdwallet.ts:365

​

moveOutpointToAvailable()

private moveOutpointToAvailable(outpointInfo): void

Moves an outpoint from pending back to available outpoints.

​

Parameters

​

Returns

void

​

Source

wallet/qi-hdwallet.ts:844

​

moveOutpointsToPending()

private moveOutpointsToPending(inputs): void

Moves specified inputs to pending outpoints.

​

Parameters

​

Returns

void

​

Source

wallet/qi-hdwallet.ts:815

​

openChannel()

openChannel(paymentCode): void

Receives a payment code and stores it in the wallet for future use. If the payment code is already in the wallet, it will be ignored.

​

Parameters

​

Returns

void

​

Source

wallet/qi-hdwallet.ts:1506

​

outpointsToUTXOs()

private outpointsToUTXOs(zone, minDenominationToUse?): UTXO[]

Converts outpoints for a specific zone to UTXO format.

​

Parameters

​

Returns

UTXO[]

An array of UTXO objects.

​

Source

wallet/qi-hdwallet.ts:443

​

removeOutpointFromPending()

private removeOutpointFromPending(outpoint): void

Removes an outpoint from the pending outpoints.

​

Parameters

​

Returns

void

​

Source

wallet/qi-hdwallet.ts:833

​

scan()

scan(zone, account?): Promise<void>

Scans the specified zone for addresses with unspent outputs. Starting at index 0, it will generate new addresses until the gap limit is reached for external and change BIP44 addresses and payment channel addresses.

​

Parameters

​

Returns

Promise<void>

A promise that resolves when the scan is complete.

​

Throws

If the zone is invalid.

​

Source

wallet/qi-hdwallet.ts:967

​

sendTransaction()

sendTransaction(
   recipientPaymentCode, 
   amount, 
   originZone, 
destinationZone): Promise<TransactionResponse>

Sends a transaction to a specified recipient payment code in a specified zone.

​

Parameters

​

Returns

Promise<TransactionResponse>

A promise that resolves to the transaction response.

​

Throws

If the payment code is invalid, the amount is zero, or the zones are invalid.

​

Source

wallet/qi-hdwallet.ts:675

​

serialize()

serialize(): SerializedQiHDWallet

Serializes the HD wallet state into a format suitable for storage or transmission.

​

Returns

SerializedQiHDWallet

An object representing the serialized state of the HD wallet, including outpoints, change addresses, gap addresses, and other inherited properties.

​

Overrides

AbstractHDWallet.serialize

​

Source

wallet/qi-hdwallet.ts:1237

​

setAddressUseChecker()

setAddressUseChecker(checker): void

Sets the address use checker. The provided callback function should accept an address as input and return a boolean indicating whether the address is in use. If the callback returns true, the address is considered used and if it returns false, the address is considered unused.

​

Parameters

​

Returns

void

​

Source

wallet/qi-hdwallet.ts:217

​

signMessage()

signMessage(address, message): Promise<string>

Signs a message using the private key associated with the given address.

​

Parameters

​

Returns

Promise<string>

A promise that resolves to the signature of the message in hexadecimal string format.

​

Overrides

AbstractHDWallet.signMessage

​

Throws

If the address does not correspond to a valid HD node or if signing fails.

​

Source

wallet/qi-hdwallet.ts:1223

​

signTransaction()

signTransaction(tx): Promise<string>

Signs a Qi transaction and returns the serialized transaction.

​

Parameters

​

Returns

Promise<string>

The serialized transaction.

​

Overrides

AbstractHDWallet.signTransaction

​

Throws

If the UTXO transaction is invalid.

​

Source

wallet/qi-hdwallet.ts:341

​

sync()

sync(zone, account?): Promise<void>

Scans the specified zone for addresses with unspent outputs. Starting at the last address index, it will generate new addresses until the gap limit is reached for external and change BIP44 addresses and payment channel addresses.

​

Parameters

​

Returns

Promise<void>

A promise that resolves when the sync is complete.

​

Throws

If the zone is invalid.

​

Source

wallet/qi-hdwallet.ts:1000

​

createRandom()

static createRandom<T>(
   this, 
   password?, 
   wordlist?): T

Creates a random HD wallet.

​

Type parameters

​

Parameters

​

Returns

T

The created instance.

​

Inherited from

AbstractHDWallet.createRandom

​

Source

wallet/hdwallet.ts:324

​

deserialize()

static deserialize(serialized): Promise<QiHDWallet>

Deserializes a serialized QiHDWallet object and reconstructs the wallet instance.

​

Parameters

​

Returns

Promise<QiHDWallet>

A promise that resolves to a reconstructed QiHDWallet instance.

​

Overrides

AbstractHDWallet.deserialize

​

Throws

If the serialized data is invalid or if any addresses in the gap addresses or gap change addresses do not exist in the wallet.

​

Source

wallet/qi-hdwallet.ts:1261

​

fromMnemonic()

static fromMnemonic<T>(this, mnemonic): T

Creates an HD wallet from a mnemonic.

​

Type parameters

​

Parameters

​

Returns

T

The created instance.

​

Inherited from

AbstractHDWallet.fromMnemonic

​

Source

wallet/hdwallet.ts:309

​

fromPhrase()

static fromPhrase<T>(
   this, 
   phrase, 
   password?, 
   wordlist?): T

Creates an HD wallet from a phrase.

​

Type parameters

​

Parameters

​

Returns

T

The created instance.

​

Inherited from

AbstractHDWallet.fromPhrase

​

Source

wallet/hdwallet.ts:348