magic-wallet-sdk

import * as _stacks_network from '@stacks/network'; import { StacksMainnet, StacksTestnet } from '@stacks/network'; export { StacksNetwork } from '@stacks/network'; interface MagicWalletConfig { /** Network to connect to (mainnet, testnet, devnet) */ network: 'mainnet' | 'testnet' | 'devnet'; /** Auto-fund temporary wallets with STX */ autoFund?: boolean; /** Amount of STX to fund (in micro-STX) */ fundAmount?: number; /** Enable session persistence */ persistSession?: boolean; /** Custom storage adapter */ storage?: StorageAdapter; } interface StorageAdapter { getItem(key: string): Promise<string | null>; setItem(key: string, value: string): Promise<void>; removeItem(key: string): Promise<void>; } interface TemporaryWallet { /** Wallet address */ address: string; /** Private key (securely managed) */ privateKey: string; /** Public key */ publicKey: string; /** Mnemonic phrase for recovery */ mnemonic: string; /** Wallet type identifier */ type: 'temporary'; /** Creation timestamp */ createdAt: number; /** STX balance (in micro-STX) */ balance?: number; } interface WalletConnection { /** Connected wallet address */ address: string; /** Wallet type */ type: 'temporary' | 'hiro' | 'xverse' | 'leather' | 'other'; /** Connection status */ connected: boolean; /** Network */ network: string; } interface TransactionOptions { /** Transaction fee (in micro-STX) */ fee?: number; /** Transaction memo */ memo?: string; /** Post conditions */ postConditions?: any[]; } interface FaucetResponse { success: boolean; txid?: string; message?: string; amount?: number; } interface ExportData { /** Private key for import */ privateKey: string; /** Mnemonic phrase */ mnemonic: string; /** Wallet address */ address: string; /** Export format */ format: 'json' | 'mnemonic' | 'privatekey' | 'pdf' | 'qr'; } interface PDFExportOptions { /** Include QR codes for easy scanning */ includeQR?: boolean; /** Add security warnings and instructions */ includeInstructions?: boolean; /** Custom title for the PDF */ title?: string; /** Include wallet balance if available */ includeBalance?: boolean; /** Add timestamp */ includeTimestamp?: boolean; } interface WalletProvider { name: string; id: string; icon?: string; installUrl?: string; isInstalled?: boolean; } type WalletEventType = 'wallet_created' | 'wallet_connected' | 'wallet_disconnected' | 'transaction_signed' | 'transaction_broadcast' | 'wallet_exported' | 'wallet_upgraded'; interface WalletEvent { type: WalletEventType; data: any; timestamp: number; } type EventCallback = (event: WalletEvent) => void; /** * Simple Seed Phrase Modal UI Component * * A clean, secure modal for displaying seed phrases with copy and download options. * Works in any web environment - just include this CSS and JS. */ interface SeedModalOptions { title?: string; warning?: string; showCopy?: boolean; showDownloadTxt?: boolean; showDownloadPdf?: boolean; } interface SeedModalData { address: string; mnemonic: string; network: string; createdAt?: number; } /** * Create and show a seed phrase modal */ declare function showSeedModal(data: SeedModalData, options?: SeedModalOptions): Promise<void>; /** * Magic Wallet SDK - One-click wallets for Stacks blockchain */ declare class MagicWallet { private config; private currentWallet; private connection; private storage; private eventListeners; constructor(config?: Partial<MagicWalletConfig>); /** * 🪄 Create a new temporary wallet (MVP Feature) */ createTemporaryWallet(): Promise<TemporaryWallet>; /** * 🔄 Restore wallet from mnemonic */ restoreFromMnemonic(mnemonic: string): Promise<TemporaryWallet>; /** * 🔄 Restore wallet from private key */ restoreFromPrivateKey(privateKey: string): Promise<TemporaryWallet>; /** * 💰 Request faucet funds for testnet/devnet */ requestFaucetFunds(address?: string): Promise<FaucetResponse>; /** * 💸 Send STX tokens */ sendSTX(recipient: string, amount: number, options?: TransactionOptions): Promise<string>; /** * 📤 Export wallet data for migration (Phase 2 Feature) */ exportWallet(format?: 'json' | 'mnemonic' | 'privatekey'): ExportData; /** * 📄 One-click PDF export of wallet backup (Enhanced Feature) * Downloads a secure PDF backup with seed phrase, QR codes, and instructions */ exportWalletToPDF(options?: PDFExportOptions): Promise<void>; /** * 📄 Generate wallet PDF blob (for Node.js environments) * Returns the PDF blob without downloading it */ generateWalletPDFBlob(options?: PDFExportOptions): Promise<Blob>; /** * 🖨️ Generate printable HTML backup (Alternative to PDF) * Returns HTML content that can be printed or saved */ generatePrintableBackup(): string; /** * 📱 Generate QR code for easy wallet import * Returns QR code data URL for the mnemonic phrase */ generateWalletQR(): Promise<string>; /** * 🔑 Show seed phrase in a secure modal UI * Simple, clean modal with copy and download options */ showSeedPhrase(options?: SeedModalOptions): Promise<void>; /** * 🔗 Get available wallet providers for upgrade */ getAvailableProviders(): WalletProvider[]; /** * ⬆️ Guide user through wallet upgrade process */ getUpgradeInstructions(providerId: string): { steps: string[]; exportData: ExportData; }; /** * 📊 Get current wallet info */ getWalletInfo(): WalletConnection | null; /** * 🔌 Disconnect current wallet */ disconnect(): Promise<void>; /** * 📻 Event system */ on(event: string, callback: EventCallback): void; off(event: string, callback: EventCallback): void; /** * 💰 Get wallet STX balance */ getBalance(address?: string): Promise<number>; /** * 🚀 ONE-CLICK MAGIC: Create, fund, and connect wallet instantly for dApps * This is the main feature for dApp integration - everything happens automatically */ oneClickConnect(options?: { appName?: string; fundingAmount?: number; onProgress?: (step: string, progress: number) => void; autoShowSeed?: boolean; }): Promise<{ wallet: TemporaryWallet; connection: WalletConnection; funded: boolean; ready: boolean; }>; /** * 🎯 Quick connect for existing users (restores previous session) */ quickConnect(appName?: string): Promise<{ wallet: TemporaryWallet; connection: WalletConnection; isExisting: boolean; }>; /** * 🌐 Get wallet provider for dApp integration (mimics standard wallet interface) */ getWalletProvider(): { isConnected: boolean; account: string | null; network: string; connect: () => Promise<string>; disconnect: () => Promise<void>; sendTransaction: (txOptions: any) => Promise<string>; signMessage: (message: string) => Promise<string>; }; private saveWalletToStorage; private restoreSession; private updateConnection; private emitEvent; private checkProviderInstallation; } /** * Generate a new temporary wallet with mnemonic and keys */ declare function generateTemporaryWallet(): TemporaryWallet; /** * Restore wallet from mnemonic (simplified) */ declare function restoreWalletFromMnemonic(mnemonic: string): TemporaryWallet; /** * Restore wallet from private key */ declare function restoreWalletFromPrivateKey(privateKeyHex: string): TemporaryWallet; /** * Validate Stacks address format */ declare function isValidStacksAddress(address: string): boolean; /** * Convert STX to micro-STX */ declare function stxToMicroStx(stx: number): number; /** * Convert micro-STX to STX */ declare function microStxToStx(microStx: number): number; declare const NETWORKS: { readonly mainnet: StacksMainnet; readonly testnet: StacksTestnet; readonly devnet: _stacks_network.StacksMocknet; }; declare const DEFAULT_CONFIG: { network: "testnet"; autoFund: boolean; fundAmount: number; persistSession: boolean; }; declare const WALLET_PROVIDERS: readonly [{ readonly id: "hiro"; readonly name: "Hiro Wallet"; readonly installUrl: "https://wallet.hiro.so/"; readonly icon: "🦊"; }, { readonly id: "xverse"; readonly name: "Xverse"; readonly installUrl: "https://www.xverse.app/"; readonly icon: "🌟"; }, { readonly id: "leather"; readonly name: "Leather"; readonly installUrl: "https://leather.io/"; readonly icon: "🔶"; }]; export { DEFAULT_CONFIG, type EventCallback, type ExportData, type FaucetResponse, MagicWallet, type MagicWalletConfig, NETWORKS, type PDFExportOptions, type SeedModalData, type SeedModalOptions, type StorageAdapter, type TemporaryWallet, type TransactionOptions, WALLET_PROVIDERS, type WalletConnection, type WalletEvent, type WalletProvider, generateTemporaryWallet, isValidStacksAddress, microStxToStx, restoreWalletFromMnemonic, restoreWalletFromPrivateKey, showSeedModal, stxToMicroStx };