@lumenkit/stellar-wallets

v1.1.4

Published

8 months ago

A comprehensive TypeScript library for integrating multiple Stellar wallets into your dApp with a beautiful, modern UI

LumenKit

A comprehensive TypeScript library for integrating multiple Stellar wallets into your dApp with a beautiful, modern UI. Built with Lit Web Components and designed for seamless wallet connectivity across the Stellar ecosystem.

✨ Features

🎨 Modern UI Components - Beautiful, responsive modals and buttons
🔌 Multi-Wallet Support - Connect to 10+ Stellar wallets
🌐 Network Selector - Switch between Mainnet, Testnet, and Futurenet
📱 Mobile-First Design - Optimized for all screen sizes
🎯 TypeScript Support - Full type safety and IntelliSense
⚡ Lightweight - Minimal bundle size with tree-shaking
🔧 Customizable - Themes and styling options
🛡️ Secure - Built following Stellar security best practices

🚀 Quick Start

Installation

npm install @lumenkit/stellar-wallets
# or
yarn add @lumenkit

Basic Usage

import { 
  StellarWalletsKit, 
  WalletNetwork,
  StellarWalletsModal,
  StellarWalletsButton 
} from '@lumenkit';

// Initialize the kit
const kit = new StellarWalletsKit({
  network: WalletNetwork.TESTNET,
  selectedWalletId: 'freighter'
});

// Get wallet address
const { address } = await kit.getAddress();

// Sign a transaction
const { signedTxXdr } = await kit.signTransaction(xdr, {
  networkPassphrase: WalletNetwork.TESTNET
});

🎨 UI Components

Wallet Selection Modal

<stellar-wallets-modal
  show-modal="true"
  modal-title="Choose Your Wallet"
  @wallet-selected="${(e) => console.log('Selected:', e.detail)}"
  @modal-closed="${() => console.log('Modal closed')}">
</stellar-wallets-modal>

Connect Wallet Button

<stellar-wallets-button
  button-text="Connect Wallet"
  @wallet-selected="${(e) => console.log('Connected:', e.detail)}">
</stellar-wallets-button>

Review Transaction Modal

<stellar-review-transaction-modal
  show-modal="true"
  @modal-closed="${() => console.log('Review closed')}">
</stellar-review-transaction-modal>

Network Selector Button

<stellar-network-selector-button
  network-name="Stellar Testnet"
  selected-network="testnet"
  @network-changed="${(e) => console.log('Network changed:', e.detail)}">
</stellar-network-selector-button>

Network Selector Features:

🌐 Real Network Switching - Switch between Mainnet, Testnet, and Futurenet
🔄 Automatic Integration - Updates StellarWalletsKit network automatically
📍 Horizon URL Management - Automatically switches Horizon endpoints
🔑 Passphrase Updates - Updates network passphrase for transactions
🎨 Visual Indicators - Color-coded network status indicators
📱 Responsive Design - Works on all screen sizes

🔧 Configuration

Kit Configuration

import { StellarWalletsKit, WalletNetwork } from '@lumenkit';

const kit = new StellarWalletsKit({
  // Required: Stellar network
  network: WalletNetwork.TESTNET,
  
  // Optional: Pre-selected wallet
  selectedWalletId: 'freighter',
  
  // Optional: Custom modules
  modules: [customWalletModule],
  
  // Optional: Wallet filtering
  allowedWallets: ['freighter', 'albedo', 'rabet']
});

Network Selector Integration

import { StellarWalletsKit, WalletNetwork } from '@lumenkit';

// Initialize with default network
let currentNetwork = WalletNetwork.TESTNET;
let currentHorizonUrl = 'https://horizon-testnet.stellar.org';
let currentNetworkPassphrase = 'Test SDF Network ; September 2015';

const kit = new StellarWalletsKit({
  network: currentNetwork,
  // ... other config
});

// Listen for network changes
document.addEventListener('network-changed', (event) => {
  const { networkId, networkName, horizonUrl, networkPassphrase } = event.detail;
  
  // Update current network variables
  currentNetwork = networkId === 'mainnet' ? WalletNetwork.MAINNET : 
                  networkId === 'testnet' ? WalletNetwork.TESTNET : 
                  WalletNetwork.FUTURENET;
  currentHorizonUrl = horizonUrl;
  currentNetworkPassphrase = networkPassphrase;
  
  // Update the kit's network
  kit.updateNetwork(currentNetwork);
  
  console.log(`🌐 Switched to ${networkName}`);
  console.log(`📍 Horizon URL: ${horizonUrl}`);
});

Theme Customization

import { ModalThemes, ButtonThemes, NetworkSelectorThemes } from '@lumenkit/stellar-wallets-kit';

// Use built-in themes
const darkTheme = ModalThemes.DARK;
const lightTheme = ModalThemes.LIGHT;
const networkTheme = NetworkSelectorThemes.LIGHT;

// Or create custom theme
const customTheme = {
  bgColor: '#1a1a1a',
  textColor: '#ffffff',
  solidTextColor: '#ffffff',
  headerButtonColor: '#666666',
  dividerColor: 'rgba(255, 255, 255, 0.1)',
  helpBgColor: '#2a2a2a',
  notAvailableTextColor: '#999999',
  notAvailableBgColor: '#333333',
  notAvailableBorderColor: '#444444'
};

📱 Supported Wallets

| Wallet | Type | Mobile | Desktop | Status | |--------|------|--------|---------|--------| | Freighter | Browser Extension | ❌ | ✅ | Official Stellar Foundation wallet | | Albedo | Web Wallet | ✅ | ✅ | No extension required | | Rabet | Browser Extension | ❌ | ✅ | DeFi features integrated | | LOBSTR | Browser Extension | ❌ | ✅ | User-friendly interface | | xBull | Browser Extension | ❌ | ✅ | Secure and reliable | | WalletConnect | Bridge | ✅ | ✅ | Mobile wallet connection | | Ledger | Hardware | ✅ | ✅ | Maximum security | | Trezor | Hardware | ✅ | ✅ | Market leader | | Klever | Multi-chain | ✅ | ✅ | Multi-blockchain support | | Hana | Web Wallet | ✅ | ✅ | Simple and intuitive | | HOT Wallet | Web Wallet | ✅ | ✅ | Connect to start |

🛠️ API Reference

StellarWalletsKit

The main class for wallet operations.

class StellarWalletsKit {
  constructor(config: KitConfig);
  
  // Get current wallet address
  getAddress(params?: { path?: string; skipRequestAccess?: boolean }): Promise<{ address: string }>;
  
  // Sign a transaction
  signTransaction(xdr: string, opts?: SignTransactionOptions): Promise<{ signedTxXdr: string; signerAddress?: string }>;
  
  // Sign an auth entry
  signAuthEntry(authEntry: string, opts?: SignAuthEntryOptions): Promise<{ signedAuthEntry: string; signerAddress?: string }>;
  
  // Sign a message
  signMessage(message: string, opts?: SignMessageOptions): Promise<{ signedMessage: string; signerAddress?: string }>;
  
  // Get current network
  getNetwork(): Promise<{ network: string; networkPassphrase: string }>;
  
  // Update network (for network selector integration)
  updateNetwork(network: WalletNetwork): void;
  
  // Disconnect wallet
  disconnect(): Promise<void>;
}

Configuration Options

interface KitConfig {
  network: WalletNetwork;
  selectedWalletId?: string;
  modules?: ModuleInterface[];
  allowedWallets?: string[];
}

interface SignTransactionOptions {
  networkPassphrase?: string;
  address?: string;
  path?: string;
  submit?: boolean;
  submitUrl?: string;
}

🎨 Styling

CSS Custom Properties

:root {
  --modal-bg-color: #ffffff;
  --modal-text-color: #181818;
  --modal-solid-text-color: #000000;
  --modal-header-button-color: #8f8f8f;
  --modal-divider-color: rgba(0, 0, 0, 0.15);
  --modal-help-bg-color: #f8f8f8;
  --modal-not-available-text-color: #6f6f6f;
  --modal-not-available-bg-color: #f3f3f3;
  --modal-not-available-border-color: #e2e2e2;
}

Custom Styling

stellar-wallets-modal {
  --modal-bg-color: #1a1a1a;
  --modal-text-color: #ffffff;
  --modal-solid-text-color: #ffffff;
}

stellar-wallets-button {
  --button-bg-color: #007bff;
  --button-text-color: #ffffff;
  --button-border-radius: 8px;
}

📦 Bundle Information

Size: ~45KB gzipped
Dependencies: Minimal external dependencies
Tree Shaking: Supported
TypeScript: Full support
Browsers: Modern browsers with ES2020 support

🔒 Security

All wallet interactions follow Stellar security best practices
No private keys are stored or transmitted
All operations are performed locally in the user's wallet
Supports hardware wallets for maximum security

🚀 Advanced Usage

Custom Wallet Module

import { ModuleInterface, ModuleType } from '@lumenkit';

class CustomWalletModule implements ModuleInterface {
  moduleType = ModuleType.HOT_WALLET;
  productId = 'custom-wallet';
  productName = 'Custom Wallet';
  productUrl = 'https://custom-wallet.com';
  productIcon = 'https://custom-wallet.com/icon.png';

  async isAvailable(): Promise<boolean> {
    return typeof window.customWallet !== 'undefined';
  }

  async getAddress(): Promise<{ address: string }> {
    return { address: await window.customWallet.getAddress() };
  }

  async signTransaction(xdr: string): Promise<{ signedTxXdr: string }> {
    return { signedTxXdr: await window.customWallet.signTransaction(xdr) };
  }

  // ... implement other required methods
}

Event Handling

// Listen for wallet selection
document.addEventListener('wallet-selected', (event) => {
  console.log('Wallet selected:', event.detail);
  // event.detail contains the selected wallet information
});

// Listen for network changes
document.addEventListener('network-changed', (event) => {
  console.log('Network changed:', event.detail);
  // event.detail contains:
  // - networkId: 'mainnet' | 'testnet' | 'futurenet'
  // - networkName: 'Mainnet' | 'Testnet' | 'Futurenet'
  // - horizonUrl: Horizon endpoint URL
  // - networkPassphrase: Network passphrase for transactions
  // - isConnected: boolean
});

// Listen for modal events
document.addEventListener('modal-closed', (event) => {
  console.log('Modal closed');
});

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

🏗️ Built With

Lit - Web Components framework
TypeScript - Type safety
Rollup - Module bundler
Stellar SDK - Stellar integration

Made with ❤️ by LumenKit