nexa-wallet-sdk 0.1.2

package/src/wallet/WatchOnlyWallet.ts

@@ -0,0 +1,169 @@
+import {Networkish, Networks, TransactionBuilder} from "libnexa-ts";
+import WatchOnlyTransactionCreator from "./transactions/WatchOnlyTransactionCreator";
+import {rostrumProvider} from "../network/RostrumProvider";
+import {WatchOnlyAddress} from "../models/wallet.entities";
+import {isArray, isBuffer, isNil, isObject, isString} from "lodash-es";
+import ValidationUtils from "../utils/ValidationUtils";
+import {isValidNexaAddress} from "../utils/WalletUtils";
+import {SubscribeCallback} from "@vgrunner/electrum-cash";
+import {isNullOrEmpty} from "../utils/CommonUtils";
+
+/**
+ * WatchOnlyWallet provides functionality for monitoring and creating transactions
+ * for addresses without storing private keys. This allows users to track balances
+ * and create unsigned transactions that can be signed elsewhere.
+ */
+export default class WatchOnlyWallet {
+    /** The blockchain network this wallet operates on */
+    private readonly _network: Networkish
+    /** Array of addresses to monitor without their private keys */
+    private readonly _addressesToWatch: WatchOnlyAddress[];
+
+    /**
+     * Creates a new WatchOnlyWallet instance
+     * @param addressesToWatch Array of addresses to monitor
+     * @param network Optional network name (defaults to mainnet)
+     * @throws Error if validation fails
+     */
+    constructor(addressesToWatch: WatchOnlyAddress[], network?: string) {
+        // Validate network parameter
+        if (network !== undefined && !isString(network)) {
+            throw new Error('Network must be a string');
+        }
+
+        if (network !== undefined && isString(network)) {
+            const n = Networks.get(network)
+            if (n === undefined) {
+                throw new Error(`Invalid network: ${network}`);
+            }
+        }
+
+        this._network = Networks.get(network) ?? Networks.mainnet;
+        // Validate addressesToWatch parameter
+        this._addressesToWatch = this.validateAddressesToWatch(addressesToWatch);
+    }
+
+    /**
+     * Validates the addresses to watch array
+     * @param addressesToWatch Array of addresses to validate
+     * @returns Validated array of WatchOnlyAddress objects
+     * @throws Error if validation fails
+     */
+    private validateAddressesToWatch(addressesToWatch: WatchOnlyAddress[]): WatchOnlyAddress[] {
+        if (addressesToWatch === null || addressesToWatch === undefined) {
+            throw new Error('addresesToWatch is required');
+        }
+        
+        if (!isArray(addressesToWatch)) {
+            throw new Error('addressesToWatch must be an array');
+        }
+
+        // Check if array is not empty
+        if (addressesToWatch.length === 0) {
+            throw new Error('addressesToWatch cannot be empty');
+        }
+
+        // Validate each address object
+        const validatedAddresses: WatchOnlyAddress[] = [];
+
+        for (let i = 0; i < addressesToWatch.length; i++) {
+            const addr = addressesToWatch[i];
+
+            // Check if address is an object
+            if (!isObject(addr) || isArray(addr)) {
+                throw new Error(`addressesToWatch[${i}] must be an object`);
+            }
+
+            // Check if address property exists and is a string
+            if (!addr.hasOwnProperty('address') || !isString(addr.address)) {
+                throw new Error(`addressesToWatch[${i}].address must be a string`);
+            }
+
+            // Check if address is not empty
+            if (addr.address.trim() === '') {
+                throw new Error(`addressesToWatch[${i}].address cannot be empty`);
+            }
+
+            // Validate address format
+            if (!isValidNexaAddress(addr.address, this._network)) {
+                throw new Error(`addressesToWatch[${i}].address is not a valid NEXA address: ${addr.address}`);
+            }
+
+            // Validate optional xPub property
+            if (addr.xPub !== undefined && !isObject(addr.xPub)) {
+                throw new Error(`addressesToWatch[${i}].xPub must be a PublicKey object`);
+            }
+
+            // Validate optional derivationPath property
+            if (addr.derivationPath !== undefined && !isString(addr.derivationPath)) {
+                throw new Error(`addressesToWatch[${i}].derivationPath must be a string`);
+            }
+
+            // Check for duplicate addresses
+            const isDuplicate = validatedAddresses.some(existingAddr =>
+                existingAddr.address === addr.address
+            );
+            if (isDuplicate) {
+                throw new Error(`Duplicate address found: ${addr.address}`);
+            }
+
+            validatedAddresses.push({
+                address: addr.address.trim(),
+                xPub: addr.xPub,
+                derivationPath: addr.derivationPath
+            });
+        }
+
+        return validatedAddresses;
+    }
+
+    /**
+     * Creates a new transaction creator for this watch-only wallet
+     * @param x Optional transaction data - can be a TransactionBuilder, hex string, or Buffer
+     * @returns WatchOnlyTransactionCreator configured with wallet's addresses and network
+     */
+    public newTransaction(x?: TransactionBuilder | string | Buffer): WatchOnlyTransactionCreator {
+        let tx: WatchOnlyTransactionCreator;
+
+        // Handle different input types for creating transactions
+        if (x instanceof TransactionBuilder) {
+            // Use existing TransactionBuilder instance
+            tx = new WatchOnlyTransactionCreator(x);
+        } else if (isString(x)) {
+            // Parse transaction from hex string
+            tx = new WatchOnlyTransactionCreator().parseTxHex(x);
+        } else if (isBuffer(x) && !isNil(x)) {
+            // Parse transaction from buffer
+            tx = new WatchOnlyTransactionCreator().parseTxBuffer(x);
+        } else {
+            // Create new empty transaction
+            tx = new WatchOnlyTransactionCreator();
+        }
+
+        // Configure transaction with wallet's addresses and network
+        return tx.from(this._addressesToWatch).onNetwork(this._network);
+    }
+
+    /**
+     * Broadcasts a signed transaction to the network
+     * @param transaction Hex-encoded signed transaction
+     * @returns Promise resolving to transaction ID
+     * @throws Error if transaction is invalid or broadcast fails
+     */
+    public async sendTransaction(transaction: string): Promise<string> {
+        ValidationUtils.validateArgument(isString(transaction), 'transaction must be present and valid')
+        return rostrumProvider.broadcast(transaction)
+    }
+
+    public async subscribeToAddressNotifications(callback: SubscribeCallback): Promise<void>{
+        await rostrumProvider.subscribeToAddresses(this._addressesToWatch.map(addr => addr.address), callback)
+    }
+
+    /**
+     * Gets the list of addresses being watched
+     * @returns Array of watched addresses (copy to prevent mutation)
+     */
+    public getWatchedAddresses(): WatchOnlyAddress[] {
+        return [...this._addressesToWatch];
+    }
+}

package/src/wallet/accounts/AccountStore.ts

@@ -0,0 +1,173 @@
+import bigDecimal from "js-big-decimal";
+import {BaseAccount} from "./interfaces/BaseAccountInterface";
+import {
+    AccountType,
+    discoverNexaAccount,
+    generateAccountKey,
+    generateKeyAndAddress, generateKeysAndAddresses,
+    getNextAccountIndex
+} from "../../utils/WalletUtils";
+import {HDPrivateKey} from "libnexa-ts";
+import DAppAccount from "./models/DappAccount";
+import VaultAccount from "./models/VaultAccount";
+import DefaultAccount from "./models/DefaultAccount";
+import {AccountIndexes, AddressKey} from "../../models/wallet.entities";
+
+/**
+ * AccountStore manages a collection of wallet accounts of different types.
+ * It provides functionality to create, import, export, and manage accounts
+ * including DApp accounts, Vault accounts, and Default NEXA accounts.
+ */
+export default class AccountStore {
+
+    /** Map storing all accounts indexed by their unique store key */
+    private readonly _accounts: Map<string, BaseAccount>
+
+    /**
+     * Creates a new AccountStore instance
+     * Initializes an empty map to store accounts
+     */
+    public constructor() {
+        this._accounts = new Map<string, BaseAccount>()
+    }
+
+    /**
+     * Generates a unique store key for an account based on its type and index
+     * @param accountType The type of account (DAPP, VAULT, or DEFAULT)
+     * @param index The account index
+     * @returns Unique string key for storing the account
+     */
+    private getAccountStoreKey(accountType: AccountType, index: number): String {
+        switch (accountType){
+            case AccountType.DAPP_ACCOUNT:
+                // DApp accounts use format: "2.index"
+                return String(accountType + '.' + index);
+            case AccountType.VAULT_ACCOUNT:
+                // Vault accounts use format: "1.index"
+                return String(accountType + '.' + index);
+            default:
+                // Default accounts use just the index
+                return String(index)
+        }
+    }
+
+    /**
+     * Creates a new account of the specified type
+     * @param accountType Type of account to create (DAPP, VAULT, or DEFAULT)
+     * @param masterKey Master HD private key for deriving account keys
+     * @returns Promise resolving to the created account
+     */
+    async createAccount(accountType: AccountType, masterKey: HDPrivateKey): Promise<BaseAccount> {
+        // Get the next available index for this account type
+        const nextIndex = await getNextAccountIndex(accountType, masterKey);
+        const accountStoreKey = this.getAccountStoreKey(accountType, nextIndex)
+        
+        // Check if account already exists
+        const indexExists = this._accounts.get(String(accountStoreKey))
+        if(indexExists) {
+            return indexExists
+        }
+        
+        switch (accountType){
+            case AccountType.DAPP_ACCOUNT:
+                // Create DApp account (purpose 2)
+                let dappAccountKey = generateAccountKey(masterKey, 2);
+                const dAppAccount = new DAppAccount(2, nextIndex, generateKeyAndAddress(dappAccountKey, nextIndex))
+                await dAppAccount.loadBalances();
+                this._accounts.set(dAppAccount.getAccountStoreKey(), dAppAccount)
+                return dAppAccount
+            case AccountType.VAULT_ACCOUNT:
+                // Create Vault account (purpose 1)
+                let vaultAccountKey = generateAccountKey(masterKey, 1);
+                const vaultAccount = new VaultAccount(1, nextIndex, generateKeyAndAddress(vaultAccountKey, nextIndex))
+                await vaultAccount.loadBalances();
+                this._accounts.set(vaultAccount.getAccountStoreKey(), vaultAccount)
+                return vaultAccount
+            default:
+                // Create default NEXA account with receive and change addresses
+                let nexaAccountKey = generateAccountKey(masterKey, nextIndex);
+                const nexaAccountIndexes: AccountIndexes = { rIndex: 0, cIndex: 0 };
+                const nexaAccount = new DefaultAccount(nextIndex, nexaAccountIndexes, generateKeysAndAddresses(nexaAccountKey, nexaAccountIndexes.rIndex + 1, nexaAccountIndexes.rIndex + 20, nexaAccountIndexes.cIndex + 1, nexaAccountIndexes.cIndex + 20))
+                await nexaAccount.loadBalances()
+                this._accounts.set(nexaAccount.getAccountStoreKey(), nexaAccount)
+                return nexaAccount;
+        }
+    }
+
+    /**
+     * Finds the private key associated with a given address across all accounts
+     * @param address The address to search for
+     * @returns The AddressKey containing the private key, or null if not found
+     */
+    findKeyForAddress(address: string): AddressKey | null {
+        // Search through all accounts
+        for (const [_, account] of this._accounts.entries()) {
+            // Combine receive and change keys for this account
+            const allKeys = account.accountKeys.receiveKeys.concat(account.accountKeys.changeKeys)
+            
+            // Check each key for a matching address
+            for(const key of allKeys){
+                if(key.address == address) {
+                    return key
+                }
+            }
+        }
+        return null
+    }
+
+    /**
+     * Imports an existing account into the store
+     * @param accountData The account data to import
+     * @throws Error if an account with the same key already exists
+     */
+    importAccount(accountData: BaseAccount): void {
+        let index: string = accountData.getAccountStoreKey()
+        if(this._accounts.get(index)) {
+            throw Error('Account already exists!')
+        }
+        this._accounts.set(String(index), accountData)
+    }
+
+    /**
+     * Exports account data by index
+     * @param accountIndex The account index to export
+     * @returns The account data
+     * @throws Error if the account doesn't exist
+     */
+    exportAccount(accountIndex: string): BaseAccount {
+        if(!this._accounts.get(accountIndex)) {
+            throw Error('Cannot find account!')
+        }
+
+        return this._accounts.get(accountIndex)!
+    }
+
+    /**
+     * Removes an account from the store
+     * @param accountIndex The account index to remove
+     * @throws Error if the account doesn't exist
+     */
+    removeAccount(accountIndex: string): void {
+        if(!this._accounts.get(accountIndex)) {
+            throw Error('Cannot find account!')
+        }
+        this._accounts.delete(accountIndex)
+    }
+
+    /**
+     * Returns all accounts in the store
+     * @returns Map of account store keys to BaseAccount objects
+     */
+    listAccounts(): Map<string, BaseAccount> {
+        return this._accounts
+    }
+
+    /**
+     * Retrieves a specific account by its index
+     * @param index The account index to retrieve
+     * @returns The account if found, undefined otherwise
+     */
+    getAccount(index:string): BaseAccount | undefined {
+        return this._accounts.get(index)
+    }
+}

package/src/wallet/accounts/interfaces/BaseAccountInterface.ts

@@ -0,0 +1,56 @@
+import {AccountIndexes, AccountKeys, AddressKey, Balance} from "../../../models/wallet.entities";
+import DefaultAccount from "../models/DefaultAccount";
+import bigDecimal from "js-big-decimal";
+import {AccountType} from "../../../utils/WalletUtils";
+import {PrivateKey} from "libnexa-ts";
+import {TransactionEntity} from "../../../models/transaction.entities";
+
+export abstract class BaseAccount {
+    get transactions(): Map<string, TransactionEntity> {
+        return this._transactions;
+    }
+
+    set transactions(value: Map<string, TransactionEntity>) {
+        this._transactions = value;
+    }
+
+    protected readonly _bip44Account: number;
+    private _balance?: Balance;
+    private _tokenBalances?: Record<string, Balance> = {};
+    private _transactions : Map<string, TransactionEntity> = new Map<string, TransactionEntity>()
+
+    protected constructor(_bip44Account: number) {
+        this._bip44Account = _bip44Account;
+        this._balance = {
+            confirmed: 0,
+            unconfirmed: 0
+        }
+        this._tokenBalances = {};
+    }
+
+    abstract get accountIndexes(): AccountIndexes;
+    abstract get accountKeys(): AccountKeys;
+    abstract getNewChangeAddress(): string;
+    abstract getNewAddress(): string;
+    abstract getAccountStoreKey(): string;
+    abstract getAccountType(): AccountType;
+    abstract loadBalances(): Promise<void>;
+    abstract getKeyFromAddress(address:string): AddressKey;
+    abstract getTransactions(fromHeight?: number, address?:string): Promise<Map<string, TransactionEntity>>;
+
+    get balance(): Balance {
+        return this._balance!;
+    }
+
+    set balance(value: Balance) {
+        this._balance = value;
+    }
+
+    get tokenBalances(): Record<string, Balance> {
+        return this._tokenBalances!;
+    }
+
+    set tokenBalances(value: Record<string, Balance>) {
+        this._tokenBalances = value;
+    }
+}

package/src/wallet/accounts/models/DappAccount.ts

@@ -0,0 +1,80 @@
+import {AccountIndexes, AccountKeys, AddressKey} from "../../../models/wallet.entities";
+import {BaseAccount} from "../interfaces/BaseAccountInterface";
+import {
+    AccountType, classifyTransaction,
+    fetchTotalBalance,
+    fetchTransactionsHistory,
+    sumBalance,
+    sumTokensBalance
+} from "../../../utils/WalletUtils";
+import {PrivateKey} from "libnexa-ts";
+import {TransactionEntity} from "../../../models/transaction.entities";
+
+export default class DAppAccount extends BaseAccount {
+
+    private readonly _accountIndex: number;
+    private readonly _accountKey: AddressKey;
+
+    constructor(bip44Account: number, accountIndex: number, addressKey: AddressKey) {
+        super(bip44Account)
+        this._accountIndex = accountIndex;
+        this._accountKey = addressKey
+    }
+
+    // this is used in AccountStore.ts to get the key to be used in the map for this account
+    public getAccountStoreKey(): string {
+        return String(this._bip44Account + '.' + this._accountIndex);
+    }
+
+    public getAccountType(): AccountType {
+        return AccountType.DAPP_ACCOUNT;
+    }
+
+    public getNewAddress() {
+        return this._accountKey.address;
+    }
+
+    public getNewChangeAddress(): string {
+        return this._accountKey.address;
+    }
+
+    get accountIndexes(): AccountIndexes {
+        return {
+            rIndex: this._accountIndex,
+            cIndex: 0
+        };
+    }
+
+    get accountKeys(): AccountKeys {
+        return {
+            receiveKeys: [this._accountKey],
+            changeKeys: [this._accountKey]
+        };
+    }
+
+    async loadBalances(): Promise<void> {
+        let balances = await fetchTotalBalance([this._accountKey]);
+        let tokenBalances = [this._accountKey].map(k => k.tokensBalance);
+        super.balance = sumBalance(balances)
+        super.tokenBalances = sumTokensBalance(tokenBalances)
+    }
+
+    getKeyFromAddress(address: string): AddressKey {
+        return this._accountKey;
+    }
+
+    async getTransactions(fromHeight?: number, address?: string): Promise<Map<string, TransactionEntity>> {
+        let txPromises:TransactionEntity[] = []
+
+        const transactions = await fetchTransactionsHistory([address ?? this._accountKey.address], fromHeight ?? 0)
+        for (let tx of transactions.txs.values()) {
+            let t = await classifyTransaction(tx, [address ?? this._accountKey.address])
+            txPromises.push(t)
+        }
+        await Promise.all(txPromises)
+        for (let txEntity of txPromises){
+            this.transactions.set(txEntity.txId, txEntity)
+        }
+        return this.transactions
+    }
+}

package/src/wallet/accounts/models/DefaultAccount.ts

@@ -0,0 +1,96 @@
+import {AccountIndexes, AccountKeys, AddressKey} from "../../../models/wallet.entities";
+import {BaseAccount} from "../interfaces/BaseAccountInterface";
+import {
+    AccountType, classifyTransaction,
+    fetchTotalBalance,
+    fetchTransactionsHistory,
+    sumBalance,
+    sumTokensBalance
+} from "../../../utils/WalletUtils";
+import {PrivateKey} from "libnexa-ts";
+import {TransactionEntity} from "../../../models/transaction.entities";
+
+export default class DefaultAccount extends BaseAccount {
+
+    private readonly _accountIndexes: AccountIndexes; // either a list of indexes or a single bip44 account index
+    private _accountKeys: AccountKeys; // either a list of keys or a single key
+
+    constructor(bip44Account: number, accountIndexes: AccountIndexes, accountKeys: AccountKeys) {
+        super(bip44Account)
+        if (accountIndexes.rIndex < 0) {
+            throw new Error(`Can not create nexa account with an rindex of ${accountIndexes.rIndex}. must be >= 0.`);
+        }
+        if (accountIndexes.cIndex < 0) {
+            throw new Error(`Can not create nexa account with an cindex of ${accountIndexes.cIndex}. must be >= 0.`);
+        }
+        this._accountIndexes = accountIndexes;
+        this._accountKeys = accountKeys;
+    }
+
+    // this is used in AccountStore.ts to get the key to be used in the map for this account
+    public getAccountStoreKey() {
+        return String(this._bip44Account);
+    }
+
+    public getAccountType(): AccountType {
+        return AccountType.NEXA_ACCOUNT
+    }
+
+    public getNewAddress() {
+        return this._accountKeys.receiveKeys[this._accountKeys.receiveKeys.length - 1]?.address ?? '';
+    }
+
+    public getNewChangeAddress(): string {
+        return this._accountKeys.changeKeys[this._accountKeys.changeKeys.length - 1]?.address ?? ''
+    }
+
+    get accountIndexes(): AccountIndexes {
+        return this._accountIndexes;
+    }
+
+    get accountKeys(): AccountKeys {
+        return this._accountKeys;
+    }
+
+    async loadBalances(): Promise<void> {
+        let balances = await fetchTotalBalance(this._accountKeys.receiveKeys.concat(this._accountKeys.changeKeys));
+        let tokenBalances = this._accountKeys.receiveKeys.concat(this._accountKeys.changeKeys).map(k => k.tokensBalance);
+        super.balance = sumBalance(balances)
+        super.tokenBalances = sumTokensBalance(tokenBalances)
+    }
+
+    getKeyFromAddress(address: string): AddressKey {
+        const allKeys = this._accountKeys.receiveKeys.concat(this._accountKeys.changeKeys)
+        const keyFound = allKeys.find(key => key.address === address)
+        return keyFound!
+    }
+
+    async getTransactions(fromHeight?: number, address?: string): Promise<Map<string, TransactionEntity>> {
+
+        let receiveAddresses = this.accountKeys.receiveKeys.map(ak => ak.address);
+        let changeAddresses = this.accountKeys.changeKeys.map(ak => ak.address);
+        let allAddresses = receiveAddresses.concat(changeAddresses);
+
+        let rTxs = fetchTransactionsHistory(address != null ? [address]: receiveAddresses, fromHeight ?? 0);
+        let cTxs = fetchTransactionsHistory(address != null ? [address] : receiveAddresses, fromHeight ?? 0);
+
+        let [rData, cData] = await Promise.all([rTxs, cTxs]);
+
+        let txHistory = rData.txs;
+        for (let tx of cData.txs.values()) {
+            txHistory.set(tx.tx_hash, tx);
+        }
+
+        let txPromises: TransactionEntity[] = [];
+        for (let tx of txHistory.values()) {
+            let t = await classifyTransaction(tx, allAddresses);
+            txPromises.push(t);
+        }
+        await Promise.all(txPromises)
+
+        for (let txEntity of txPromises){
+            this.transactions.set(txEntity.txId, txEntity)
+        }
+        return this.transactions
+    }
+}

package/src/wallet/accounts/models/VaultAccount.ts

@@ -0,0 +1,81 @@
+import {AccountIndexes, AccountKeys, AddressKey} from "../../../models/wallet.entities";
+import {BaseAccount} from "../interfaces/BaseAccountInterface";
+import {
+    AccountType, classifyTransaction,
+    fetchTotalBalance,
+    fetchTransactionsHistory,
+    sumBalance,
+    sumTokensBalance
+} from "../../../utils/WalletUtils";
+import {PrivateKey} from "libnexa-ts";
+import {TransactionEntity} from "../../../models/transaction.entities";
+import {rostrumProvider} from "../../../network/RostrumProvider";
+
+export default class VaultAccount extends BaseAccount {
+
+    private readonly _accountIndex: number;
+    private readonly _accountKey: AddressKey;
+
+    constructor(bip44Account: number, accountIndex: number, addressKey: AddressKey) {
+        super(bip44Account)
+        this._accountIndex = accountIndex;
+        this._accountKey = addressKey;
+    }
+
+    // this is used in AccountStore.ts to get the key to be used in the map for this account
+    public getAccountStoreKey(): string {
+        return String(this._bip44Account + '.' + this._accountIndex);
+    }
+
+    public getAccountType(): AccountType {
+        return AccountType.VAULT_ACCOUNT
+    }
+
+    public getNewAddress() {
+        return this._accountKey.address
+    }
+
+    public getNewChangeAddress(): string {
+        return this._accountKey.address
+    }
+
+    get accountIndexes(): AccountIndexes {
+        return {
+            rIndex: this._accountIndex,
+            cIndex: 0
+        };
+    }
+
+    get accountKeys(): AccountKeys {
+        return {
+            receiveKeys: [this._accountKey],
+            changeKeys: [this._accountKey]
+        };
+    }
+
+    async loadBalances(): Promise<void> {
+        let balances = await fetchTotalBalance([this._accountKey]);
+        let tokenBalances = [this._accountKey].map(k => k.tokensBalance);
+        super.balance = sumBalance(balances)
+        super.tokenBalances = sumTokensBalance(tokenBalances)
+    }
+
+    getKeyFromAddress(address: string): AddressKey {
+        return this._accountKey;
+    }
+
+    async getTransactions(fromHeight?: number, address?: string): Promise<Map<string, TransactionEntity>> {
+        let txPromises:TransactionEntity[] = []
+
+        const transactions = await fetchTransactionsHistory([address ?? this._accountKey.address], fromHeight ?? 0)
+        for (let tx of transactions.txs.values()) {
+            let t = await classifyTransaction(tx, [address ?? this._accountKey.address])
+            txPromises.push(t)
+        }
+        await Promise.all(txPromises)
+        for (let txEntity of txPromises){
+            this.transactions.set(txEntity.txId, txEntity)
+        }
+        return this.transactions
+    }
+}