JSPM

��# Shogun Stealth Address A comprehensive library for creating and managing stealth addresses in the Shogun SDK ecosystem. Stealth addresses enhance privacy by generating one-time addresses for each transaction, preventing address reuse and improving transaction privacy. This library integrates with the Fluidkey Stealth Account Kit for advanced stealth address functionality and provides seamless compatibility with the Shogun Core framework. ## Features - Generate stealth addresses for enhanced privacy - Dual key system (viewing and spending keys) for secure operations - Fluidkey integration for advanced stealth functionality - Gun database storage for secure key management - TypeScript support with full type definitions - Plugin architecture for Shogun Core - Multi-format builds (ESM, CJS, Browser) - Ethereum compatibility with ethers.js ## Installation bash npm install shogun-stealth-address # or yarn add shogun-stealth-address ### Dependencies - @fluidkey/stealth-account-kit: Advanced stealth functionality - ethers: Ethereum wallet and cryptographic operations - gun: Decentralized database for key storage ### Peer Dependencies - shogun-core: Required when using as a plugin. ## Usage shogun-stealth-address is designed to be used as a plugin within shogun-core. First, enable it in the ShogunCore configuration. typescript import { ShogunCore } from 'shogun-core'; // Initialize Shogun Core with the stealth plugin enabled const shogun = new ShogunCore({ peers: ['https://gun-manhattan.herokuapp.com/gun'], scope: 'my-stealth-app', // Assuming shogun-core supports a 'stealth' configuration key // to enable and configure the plugin. stealth: { enabled: true, } }); // After initialization, you need to authenticate the user // This is required for operations that save/retrieve keys from user storage await shogun.login('username', 'password'); // or any other auth method // Get the stealth plugin instance // Assuming a getPlugin method exists on the shogun instance const stealthPlugin = shogun.getPlugin('stealth'); // --- Example Operations --- // 1. Get or generate stealth keys for the current user const keys = await stealthPlugin.getUserStealthKeys(); console.log('User stealth keys:', keys); // 2. Get public stealth keys for another user (by their Gun public key) const recipientGunPubKey = 'RECIPIENT_GUN_PUBLIC_KEY'; const recipientPublicKeys = await stealthPlugin.getPublicStealthKeys(recipientGunPubKey); if (recipientPublicKeys) { // 3. Generate a stealth address for the recipient const stealthResult = await stealthPlugin.generateStealthAddress( recipientPublicKeys.viewingKey, recipientPublicKeys.spendingKey ); console.log('Generated stealth address for recipient:', stealthResult.stealthAddress); // 4. As the recipient, open the stealth address to access funds const wallet = await stealthPlugin.openStealthAddress( stealthResult.stealthAddress, stealthResult.ephemeralPublicKey, keys.viewingKey.privateKey, keys.spendingKey.privateKey ); console.log('Opened stealth wallet address:', wallet.address); } ### Browser Usage To use it in a browser, include the required scripts and initialize ShogunCore with the plugin enabled. html <!-- Dependencies --> <script src="https://cdn.jsdelivr.net/npm/gun/gun.js"></script> <script src="https://cdn.jsdelivr.net/npm/gun/sea.js"></script> <script src="https://cdn.jsdelivr.net/npm/ethers@5.7.0/dist/ethers.umd.min.js"></script> <!-- Shogun Core and Stealth Plugin --> <script src="https://cdn.jsdelivr.net/npm/shogun-core/dist/browser/shogun-core.js"></script> <script src="https://unpkg.com/shogun-stealth-address/dist/browser/shogun-stealth-address.js"></script> <script> // Shogun Core is available via initShogun const shogun = initShogun({ peers: ['https://gun-manhattan.herokuapp.com/gun'], scope: 'my-browser-stealth-app', stealth: { enabled: true } // Enable the plugin }); // The StealthPlugin is added automatically and can be accessed after auth // const stealthPlugin = shogun.getPlugin('stealth'); </script> ## API Reference The main interface is StealthPlugin. ### stealthPlugin.getUserStealthKeys(): Promise<StealthKeys> Retrieves the current user's stealth keys from storage. If no keys exist, it generates a new pair, saves them, and returns them. An authenticated user is required. ### stealthPlugin.getPublicStealthKeys(gunPublicKey: string): Promise<{viewingKey: string, spendingKey: string} | null> Fetches the public viewing and spending keys for a given user identified by their Gun public key. ### stealthPlugin.generateStealthAddress(recipientViewingKey: string, recipientSpendingKey: string): Promise<StealthAddressResult> Generates a new one-time stealth address for a recipient. - Returns: StealthAddressResult object: typescript interface StealthAddressResult { stealthAddress: string; ephemeralPublicKey: string; recipientViewingPublicKey: string; recipientSpendingPublicKey: string; } ### stealthPlugin.openStealthAddress(stealthAddress: string, ephemeralPublicKey: string, viewingPrivateKey: string, spendingPrivateKey: string): Promise<ethers.Wallet> Opens a stealth address by deriving its private key. This should be called by the recipient of a transaction. ### stealthPlugin.generateAndSaveStealthKeys(): Promise<StealthKeys> Forces the generation of a new pair of stealth keys and saves them to the user's authenticated Gun graph, overwriting any existing keys. ### stealthPlugin.generateKeysFromSignature(signature: FluidkeySignature): Promise<FluidkeyKeys> Generates stealth keys from a signature, using the Fluidkey method. This is useful for integrating with existing key management systems. ## Security Features - Encrypted storage using Gun's SEA encryption. - Dual key system separating viewing and spending capabilities. - One-time addresses for each transaction to prevent address reuse and enhance privacy. ## Development ### Building bash npm run build ### Testing bash npm test ## License MIT License - see the [LICENSE](LICENSE) file for details.