pwc-sdk-wallet 0.6.3

package/dist/services/QRCodeService.js

@@ -0,0 +1,299 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QRCodeService = void 0;
+const EncryptionService_1 = require("../crypto/EncryptionService");
+/**
+ * Service for generating and scanning QR codes for wallet operations.
+ * Supports address sharing, mnemonic backup, and transaction signing.
+ */
+class QRCodeService {
+    /**
+     * Generates QR code data for a wallet address
+     * @param address - The wallet address to encode
+     * @param label - Optional label for the address
+     * @returns QR code data string
+     */
+    static generateAddressQR(address, label) {
+        const qrData = {
+            type: 'address',
+            data: {
+                address: address,
+                label: label || '',
+            },
+            timestamp: Date.now(),
+            version: this.QR_VERSION,
+        };
+        return JSON.stringify(qrData);
+    }
+    /**
+     * Generates QR code data for encrypted mnemonic backup
+     * @param mnemonic - The mnemonic phrase to encrypt
+     * @param password - Password for encryption
+     * @param chainType - Type of blockchain (evm, solana, etc.)
+     * @param accountCount - Number of accounts to import
+     * @returns Promise resolving to QR code data string
+     * @throws Error if encryption fails
+     */
+    static async generateMnemonicQR(mnemonic, password, chainType = 'evm', accountCount = 1) {
+        // Encrypt the mnemonic
+        const encryptedMnemonic = await EncryptionService_1.EncryptionService.encrypt(mnemonic, password);
+        const walletImportData = {
+            encryptedMnemonic,
+            chainType,
+            accountCount,
+        };
+        const qrData = {
+            type: 'wallet-import',
+            data: walletImportData,
+            timestamp: Date.now(),
+            version: this.QR_VERSION,
+        };
+        return JSON.stringify(qrData);
+    }
+    /**
+     * Generates QR code data for transaction signing
+     * @param transactionData - Transaction details
+     * @returns QR code data string
+     */
+    static generateTransactionQR(transactionData) {
+        const qrData = {
+            type: 'transaction',
+            data: transactionData,
+            timestamp: Date.now(),
+            version: this.QR_VERSION,
+        };
+        return JSON.stringify(qrData);
+    }
+    /**
+     * Parses QR code data and validates its structure
+     * @param qrString - The QR code string to parse
+     * @returns Parsed QR code data
+     * @throws Error if QR data is invalid or unsupported
+     */
+    static parseQRData(qrString) {
+        try {
+            const qrData = JSON.parse(qrString);
+            // Validate required fields
+            if (!qrData.type || !qrData.data || !qrData.timestamp || !qrData.version) {
+                throw new Error('Invalid QR code format: missing required fields');
+            }
+            // Validate type
+            const validTypes = ['address', 'mnemonic', 'transaction', 'wallet-import'];
+            if (!validTypes.includes(qrData.type)) {
+                throw new Error(`Unsupported QR code type: ${qrData.type}`);
+            }
+            // Validate timestamp (not too old, not in future)
+            const now = Date.now();
+            const maxAge = 24 * 60 * 60 * 1000; // 24 hours
+            if (qrData.timestamp > now || qrData.timestamp < now - maxAge) {
+                throw new Error('QR code is too old or has invalid timestamp');
+            }
+            return qrData;
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                throw new Error('Invalid QR code: not a valid JSON');
+            }
+            throw error;
+        }
+    }
+    /**
+     * Extracts wallet address from QR code data
+     * @param qrString - The QR code string
+     * @returns The wallet address
+     * @throws Error if QR code doesn't contain address data
+     */
+    static extractAddress(qrString) {
+        const qrData = this.parseQRData(qrString);
+        if (qrData.type !== 'address') {
+            throw new Error('QR code does not contain address data');
+        }
+        const address = qrData.data.address;
+        if (!address || typeof address !== 'string') {
+            throw new Error('Invalid address in QR code');
+        }
+        return address;
+    }
+    /**
+     * Extracts wallet import data from QR code
+     * @param qrString - The QR code string
+     * @returns Wallet import data
+     * @throws Error if QR code doesn't contain wallet import data
+     */
+    static extractWalletImportData(qrString) {
+        const qrData = this.parseQRData(qrString);
+        if (qrData.type !== 'wallet-import') {
+            throw new Error('QR code does not contain wallet import data');
+        }
+        const importData = qrData.data;
+        // Validate required fields
+        if (!importData.encryptedMnemonic || !importData.chainType) {
+            throw new Error('Invalid wallet import data in QR code');
+        }
+        return importData;
+    }
+    /**
+     * Extracts transaction data from QR code
+     * @param qrString - The QR code string
+     * @returns Transaction data
+     * @throws Error if QR code doesn't contain transaction data
+     */
+    static extractTransactionData(qrString) {
+        const qrData = this.parseQRData(qrString);
+        if (qrData.type !== 'transaction') {
+            throw new Error('QR code does not contain transaction data');
+        }
+        const txData = qrData.data;
+        // Validate required fields
+        if (!txData.txType || !txData.chainId || !txData.to || !txData.amount) {
+            throw new Error('Invalid transaction data in QR code');
+        }
+        return txData;
+    }
+    /**
+     * Validates if a string is a valid Ethereum address
+     * @param address - Address to validate
+     * @returns True if valid Ethereum address
+     */
+    static isValidEthereumAddress(address) {
+        return /^0x[a-fA-F0-9]{40}$/.test(address);
+    }
+    /**
+     * Validates if a string is a valid Solana address
+     * @param address - Address to validate
+     * @returns True if valid Solana address
+     */
+    static isValidSolanaAddress(address) {
+        return /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(address);
+    }
+    /**
+     * Gets the address type based on format
+     * @param address - Address to check
+     * @returns 'ethereum', 'solana', or 'unknown'
+     */
+    static getAddressType(address) {
+        if (this.isValidEthereumAddress(address)) {
+            return 'ethereum';
+        }
+        if (this.isValidSolanaAddress(address)) {
+            return 'solana';
+        }
+        return 'unknown';
+    }
+    /**
+     * Clears sensitive data from memory
+     * @param data - Sensitive data to clear
+     */
+    static clearSensitiveData(data) {
+        // Overwrite the string with zeros (as much as possible in JS)
+        if (typeof data === 'string') {
+            // Note: JavaScript strings are immutable, so we can't directly clear them
+            // But we can help the garbage collector by removing references
+            setTimeout(() => {
+                // This helps reduce the time sensitive data stays in memory
+            }, 0);
+        }
+    }
+    // --- Utility Functions for External Use ---
+    /**
+     * Generates QR code data for a wallet address from Vault.
+     * Utility function to be used outside of Vault class.
+     * @param vault - The vault instance
+     * @param accountIndex - Index of the account to generate QR for (default: 0)
+     * @param label - Optional label for the address
+     * @returns QR code data string
+     * @throws Error if account index is invalid
+     *
+     * @example
+     * ```typescript
+     * import { QRCodeService, Vault } from 'pwc-wallet-sdk';
+     *
+     * // Generate QR for first account
+     * const qrData = QRCodeService.generateAddressQRFromVault(vault, 0, 'My Wallet');
+     * ```
+     */
+    static generateAddressQRFromVault(vault, accountIndex = 0, label) {
+        const accounts = vault.getAccounts();
+        if (accountIndex < 0 || accountIndex >= accounts.length) {
+            throw new Error(`Invalid account index: ${accountIndex}. Available accounts: ${accounts.length}`);
+        }
+        const account = accounts[accountIndex];
+        return this.generateAddressQR(account.address, label || account.name);
+    }
+    /**
+     * Generates QR code data for encrypted mnemonic backup from Vault.
+     * Utility function to be used outside of Vault class.
+     * @param vault - The vault instance
+     * @param password - Password for encryption
+     * @param accountCount - Number of accounts to import (default: 1)
+     * @returns Promise resolving to QR code data string
+     * @throws Error if encryption fails or no HD keyring available
+     *
+     * @example
+     * ```typescript
+     * import { QRCodeService, Vault } from 'pwc-wallet-sdk';
+     *
+     * // Generate backup QR with password
+     * const qrData = await QRCodeService.generateMnemonicQRFromVault(vault, 'my-secure-password', 3);
+     * ```
+     */
+    static async generateMnemonicQRFromVault(vault, password, accountCount = 1) {
+        const hdKeyring = vault.keyrings.find((k) => k.type === 'HD');
+        if (!hdKeyring) {
+            throw new Error('No HD keyring available. Cannot generate mnemonic QR.');
+        }
+        // Get the mnemonic from the HD keyring
+        const mnemonic = hdKeyring.getMnemonic();
+        if (!mnemonic) {
+            throw new Error('Mnemonic not available in HD keyring.');
+        }
+        const chainType = vault.chainId === 'solana' ? 'solana' : 'evm';
+        return this.generateMnemonicQR(mnemonic, password, chainType, accountCount);
+    }
+    /**
+     * Validates QR code data without processing it.
+     * @param qrString - QR code string to validate
+     * @returns Object containing validation result and data type
+     *
+     * @example
+     * ```typescript
+     * // Validate QR code before processing
+     * const validation = QRCodeService.validateQRCode(qrString);
+     * console.log('QR type:', validation.type);
+     * console.log('Is valid:', validation.isValid);
+     * ```
+     */
+    static validateQRCode(qrString) {
+        try {
+            const qrData = this.parseQRData(qrString);
+            return {
+                isValid: true,
+                type: qrData.type,
+                data: qrData.data
+            };
+        }
+        catch (error) {
+            return {
+                isValid: false,
+                type: 'unknown',
+                data: null
+            };
+        }
+    }
+    /**
+     * Generates an EIP-681 compatible QR string for wallet address.
+     * This format is compatible with Metamask, Binance, Trust Wallet, etc.
+     * @param address - The wallet address to encode
+     * @returns EIP-681 URI string (e.g., 'ethereum:0x1234...')
+     * @example
+     * ```typescript
+     * const qrString = QRCodeService.generateEIP681AddressQR('0x1234...');
+     * // Use this string with a QR code generator for maximum wallet compatibility
+     * ```
+     */
+    static generateEIP681AddressQR(address) {
+        return `ethereum:${address}`;
+    }
+}
+exports.QRCodeService = QRCodeService;
+QRCodeService.QR_VERSION = '1.0';

package/dist/services/TokenUtils.d.ts

@@ -0,0 +1,307 @@
+import { ethers, TransactionRequest } from 'ethers';
+import { ChainId } from '../config/chains';
+import { Vault } from '../Vault';
+/**
+ * Gets or creates a cached provider for the specified chain.
+ * @param chainId - The chain ID (e.g., '1' for Ethereum, '56' for BSC)
+ * @returns Cached ethers provider for the chain
+ */
+export declare function getProviderAuto(chainId: ChainId): ethers.JsonRpcProvider;
+/**
+ * Gets the token balance for a specific account.
+ * @param tokenAddress - The ERC-20 token contract address
+ * @param account - The account address to check balance for
+ * @param chainId - The chain ID (e.g., '1' for Ethereum, '56' for BSC)
+ * @returns Promise resolving to the token balance as bigint
+ * @example
+ * ```typescript
+ * const balance = await getTokenBalance('0xToken...', '0xAccount...', '1');
+ * console.log('Balance:', ethers.formatUnits(balance, 18));
+ * ```
+ */
+export declare function getTokenBalance(tokenAddress: string, account: string, chainId: ChainId): Promise<bigint>;
+/**
+ * Gets comprehensive information about an ERC-20 token.
+ * @param tokenAddress - The ERC-20 token contract address
+ * @param chainId - The chain ID (e.g., '1' for Ethereum, '56' for BSC)
+ * @returns Promise resolving to token information including name, symbol, decimals, total supply
+ * @example
+ * ```typescript
+ * const info = await getTokenInfo('0xToken...', '1');
+ * console.log('Token:', info.name, '(', info.symbol, ')');
+ * ```
+ */
+export declare function getTokenInfo(tokenAddress: string, chainId: ChainId): Promise<{
+    name: string;
+    symbol: string;
+    decimals: number;
+    totalSupply: bigint;
+    address: string;
+}>;
+/**
+ * Gets the native token balance (ETH, BNB, MATIC, etc.) for an account.
+ * @param account - The account address to check balance for
+ * @param chainId - The chain ID (e.g., '1' for Ethereum, '56' for BSC)
+ * @returns Promise resolving to the native token balance as bigint
+ * @example
+ * ```typescript
+ * const balance = await getNativeBalance('0xAccount...', '1');
+ * console.log('ETH Balance:', ethers.formatEther(balance));
+ * ```
+ */
+export declare function getNativeBalance(account: string, chainId: ChainId): Promise<bigint>;
+/**
+ * Checks the allowance granted by an owner to a spender for a specific token.
+ * @param tokenAddress - The ERC-20 token contract address
+ * @param owner - The token owner's address
+ * @param spender - The spender's address (e.g., DEX contract address)
+ * @param chainId - The chain ID (e.g., '1' for Ethereum, '56' for BSC)
+ * @returns Promise resolving to the allowance amount as bigint
+ * @example
+ * ```typescript
+ * const allowance = await checkAllowance('0xToken...', '0xOwner...', '0xSpender...', '1');
+ * console.log('Allowance:', ethers.formatUnits(allowance, 18));
+ * ```
+ */
+export declare function checkAllowance(tokenAddress: string, owner: string, spender: string, chainId: ChainId): Promise<bigint>;
+/**
+ * Builds a generic transaction for any contract method.
+ * @param contractAddress - The contract address to interact with
+ * @param abi - The contract ABI array
+ * @param method - The method name to call
+ * @param args - Arguments to pass to the method (default: [])
+ * @param value - Native token value to send with transaction (default: undefined)
+ * @param chainId - The chain ID (e.g., '1' for Ethereum, '56' for BSC)
+ * @returns Promise resolving to the unsigned transaction object
+ * @example
+ * ```typescript
+ * const tx = await buildTransaction({
+ *   contractAddress: '0xContract...',
+ *   abi: [...],
+ *   method: 'transfer',
+ *   args: ['0xTo...', '1000000000000000000'],
+ *   chainId: '1'
+ * });
+ * ```
+ */
+export declare function buildTransaction({ contractAddress, abi, method, args, value, chainId }: {
+    contractAddress: string;
+    abi: any[];
+    method: string;
+    args?: any[];
+    value?: bigint;
+    chainId: ChainId;
+}): Promise<ethers.TransactionRequest>;
+/**
+ * Signs an unsigned transaction using Vault (RECOMMENDED).
+ * @param unsignedTx - The unsigned transaction object
+ * @param vault - The vault instance containing the account
+ * @param fromAddress - The sender's address
+ * @param chainId - The chain ID (e.g., '1' for Ethereum, '56' for BSC)
+ * @returns Promise resolving to the signed transaction as hex string
+ * @example
+ * ```typescript
+ * const signedTx = await signTransactionWithVault(unsignedTx, vault, '0xYourAddress', '1');
+ * ```
+ */
+export declare function signTransactionWithVault(unsignedTx: TransactionRequest, vault: Vault, fromAddress: string, chainId: ChainId): Promise<string>;
+/**
+ * Approves a spender to spend tokens on behalf of the owner using Vault (RECOMMENDED).
+ * @param vault - The vault instance containing the owner's account
+ * @param fromAddress - The owner's address
+ * @param tokenAddress - The ERC-20 token contract address
+ * @param spender - The spender's address (e.g., DEX contract address)
+ * @param amount - The amount to approve (string or bigint)
+ * @param chainId - The chain ID (e.g., '1' for Ethereum, '56' for BSC)
+ * @returns Promise resolving to the transaction response
+ * @example
+ * ```typescript
+ * const receipt = await approveTokenWithVault(vault, '0xOwner...', '0xToken...', '0xSpender...', '1000', '1');
+ * ```
+ */
+export declare function approveTokenWithVault(vault: Vault, fromAddress: string, tokenAddress: string, spender: string, amount: string | bigint, chainId: ChainId): Promise<ethers.TransactionResponse>;
+/**
+ * Broadcasts a signed transaction to the network.
+ * @param signedTx - The signed transaction as hex string
+ * @param chainId - The chain ID (e.g., '1' for Ethereum, '56' for BSC)
+ * @returns Promise resolving to the transaction response
+ * @example
+ * ```typescript
+ * const txResponse = await sendTransaction(signedTx, '1');
+ * console.log('Transaction hash:', txResponse.hash);
+ * ```
+ */
+export declare function sendTransaction(signedTx: string, chainId: ChainId): Promise<ethers.TransactionResponse>;
+/**
+ * Tracks the status of a transaction with polling and callback notifications.
+ * @param txHash - The transaction hash to track
+ * @param chainId - The chain ID (e.g., '1' for Ethereum, '56' for BSC)
+ * @param callback - Function called with status updates ('pending', 'confirmed', 'failed')
+ * @param pollInterval - Polling interval in milliseconds (default: 3000)
+ * @example
+ * ```typescript
+ * trackTxStatus('0xTxHash...', '1', (status, receipt) => {
+ *   if (status === 'confirmed') {
+ *     console.log('Transaction confirmed!');
+ *   }
+ * });
+ * ```
+ */
+export declare function trackTxStatus(txHash: string, chainId: ChainId, callback: (status: 'pending' | 'confirmed' | 'failed', receipt?: any) => void, pollInterval?: number): Promise<void>;
+/**
+ * Gets the transaction count (nonce) for an address.
+ * This is useful for message signing with nonce and transaction building.
+ * @param address - The address to get nonce for
+ * @param chainId - The chain ID (e.g., '1' for Ethereum, '56' for BSC)
+ * @returns Promise resolving to the nonce as number
+ * @example
+ * ```typescript
+ * const nonce = await getNonce('0xYourAddress', '1');
+ * console.log('Current nonce:', nonce);
+ * ```
+ */
+export declare function getNonce(address: string, chainId: ChainId): Promise<number>;
+/**
+ * Signs a message using Vault (RECOMMENDED).
+ * This is equivalent to MetaMask's personal_sign method.
+ * @param message - The message to sign (string or hex string)
+ * @param vault - The vault instance containing the account
+ * @param fromAddress - The signer's address
+ * @returns Promise resolving to the signature as hex string
+ * @example
+ * ```typescript
+ * const signature = await signMessageWithVault('Hello World', vault, '0xYourAddress');
+ * console.log('Signature:', signature);
+ * ```
+ */
+export declare function signMessageWithVault(message: string, vault: Vault, fromAddress: string): Promise<string>;
+/**
+ * Signs a message using private key (DEPRECATED).
+ * ⚠️ **DEPRECATED**: Use signMessageWithVault instead for better security.
+ * @param message - The message to sign (string or hex string)
+ * @param privateKey - The private key to sign with (without 0x prefix)
+ * @returns Promise resolving to the signature as hex string
+ * @example
+ * ```typescript
+ * const signature = await signMessage('Hello World', 'your-private-key');
+ * console.log('Signature:', signature);
+ * ```
+ */
+export declare function signMessage(message: string, privateKey: string): Promise<string>;
+/**
+ * Verifies a message signature and returns the signer's address.
+ * @param message - The original message that was signed
+ * @param signature - The signature to verify
+ * @returns Promise resolving to the signer's address
+ * @example
+ * ```typescript
+ * const signerAddress = await verifyMessage('Hello World', '0xSignature...');
+ * console.log('Message was signed by:', signerAddress);
+ * ```
+ */
+export declare function verifyMessage(message: string, signature: string): Promise<string>;
+/**
+ * Signs a typed data message using Vault (RECOMMENDED).
+ * This is equivalent to MetaMask's eth_signTypedData method.
+ * @param typedData - The typed data object to sign
+ * @param vault - The vault instance containing the account
+ * @param fromAddress - The signer's address
+ * @returns Promise resolving to the signature as hex string
+ * @example
+ * ```typescript
+ * const typedData = {
+ *   types: {
+ *     Person: [
+ *       { name: 'name', type: 'string' },
+ *       { name: 'wallet', type: 'address' }
+ *     ]
+ *   },
+ *   primaryType: 'Person',
+ *   domain: { name: 'MyApp', version: '1' },
+ *   message: { name: 'Alice', wallet: '0x123...' }
+ * };
+ * const signature = await signTypedDataWithVault(typedData, vault, '0xYourAddress');
+ * ```
+ */
+export declare function signTypedDataWithVault(typedData: any, vault: Vault, fromAddress: string): Promise<string>;
+/**
+ * Signs a typed data message using private key (DEPRECATED).
+ * ⚠️ **DEPRECATED**: Use signTypedDataWithVault instead for better security.
+ * @param typedData - The typed data object to sign
+ * @param privateKey - The private key to sign with (without 0x prefix)
+ * @returns Promise resolving to the signature as hex string
+ * @example
+ * ```typescript
+ * const typedData = {
+ *   types: { Person: [{ name: 'name', type: 'string' }] },
+ *   primaryType: 'Person',
+ *   domain: { name: 'MyApp' },
+ *   message: { name: 'Alice' }
+ * };
+ * const signature = await signTypedData(typedData, 'your-private-key');
+ * ```
+ */
+export declare function signTypedData(typedData: any, privateKey: string): Promise<string>;
+/**
+ * Verifies a typed data signature and returns the signer's address.
+ * @param typedData - The original typed data that was signed
+ * @param signature - The signature to verify
+ * @returns Promise resolving to the signer's address
+ * @example
+ * ```typescript
+ * const signerAddress = await verifyTypedData(typedData, '0xSignature...');
+ * console.log('Typed data was signed by:', signerAddress);
+ * ```
+ */
+export declare function verifyTypedData(typedData: any, signature: string): Promise<string>;
+/**
+ * Signs a message with nonce using Vault (RECOMMENDED).
+ * This includes nonce in the message to prevent replay attacks.
+ * @param message - The message to sign (string or hex string)
+ * @param vault - The vault instance containing the account
+ * @param fromAddress - The signer's address
+ * @param chainId - The chain ID (e.g., '1' for Ethereum, '56' for BSC)
+ * @returns Promise resolving to an object containing signature and nonce
+ * @example
+ * ```typescript
+ * const result = await signMessageWithNonce('Hello World', vault, '0xYourAddress', '1');
+ * console.log('Signature:', result.signature);
+ * console.log('Nonce:', result.nonce);
+ * ```
+ */
+export declare function signMessageWithNonce(message: string, vault: Vault, fromAddress: string, chainId: ChainId): Promise<{
+    signature: string;
+    nonce: number;
+}>;
+/**
+ * Signs a message with nonce using private key (DEPRECATED).
+ * ⚠️ **DEPRECATED**: Use signMessageWithNonceWithVault instead for better security.
+ * @param message - The message to sign (string or hex string)
+ * @param privateKey - The private key to sign with (without 0x prefix)
+ * @param address - The signer's address (needed to get nonce)
+ * @param chainId - The chain ID (e.g., '1' for Ethereum, '56' for BSC)
+ * @returns Promise resolving to an object containing signature and nonce
+ * @example
+ * ```typescript
+ * const result = await signMessageWithNoncePrivateKey('Hello World', 'your-private-key', '0xYourAddress', '1');
+ * console.log('Signature:', result.signature);
+ * console.log('Nonce:', result.nonce);
+ * ```
+ */
+export declare function signMessageWithNoncePrivateKey(message: string, privateKey: string, address: string, chainId: ChainId): Promise<{
+    signature: string;
+    nonce: number;
+}>;
+/**
+ * Verifies a message signature with nonce and returns the signer's address.
+ * @param message - The original message that was signed (without nonce)
+ * @param signature - The signature to verify
+ * @param nonce - The nonce that was used in signing
+ * @returns Promise resolving to the signer's address
+ * @example
+ * ```typescript
+ * const signerAddress = await verifyMessageWithNonce('Hello World', '0xSignature...', 5);
+ * console.log('Message was signed by:', signerAddress);
+ * ```
+ */
+export declare function verifyMessageWithNonce(message: string, signature: string, nonce: number): Promise<string>;