Skip to content

LEDGER_IMPLEMENTATION_GUIDE.md

Latest commit

 

History

History
237 lines (186 loc) · 7.96 KB

LEDGER_IMPLEMENTATION_GUIDE.md

File metadata and controls

237 lines (186 loc) · 7.96 KB
Raw

Ledger Hardware Wallet Implementation Guide

Overview

This document describes the implementation of Ledger hardware wallet support for Stellar MicroPay, allowing security-conscious users to connect their Ledger devices instead of using Freighter.

Implementation Details

Dependencies Added

  • @ledgerhq/hw-app-stellar@^6.3.0 - Stellar app interface for Ledger devices
  • @ledgerhq/hw-transport-webhid@^6.28.0 - WebHID transport for browser communication

New Functions in frontend/lib/wallet.ts

isLedgerSupported()

  • Checks if WebHID is supported in the browser
  • Tests basic connectivity with a Ledger device
  • Returns boolean indicating support status

getLedgerPublicKey(accountPath?, confirmOnDevice?)

  • Connects to Ledger device via WebHID
  • Retrieves public key from specified BIP32 path (default: "44'/148'/0'")
  • Optional device confirmation for enhanced security
  • Handles common error cases:
    • Device not connected/unlocked
    • Stellar app not open
    • User rejection
    • App not installed

signTransactionWithLedger(transactionXDR, accountPath?)

  • Signs Stellar transactions using Ledger device
  • Uses default BIP32 path "44'/148'/0'"
  • Returns signed transaction XDR
  • Comprehensive error handling for all failure scenarios

Updated frontend/components/WalletConnect.tsx

UI Changes

  • Added wallet selection interface with two options:
    • Connect Freighter Wallet (primary option)
    • Connect Ledger Hardware Wallet (secondary option)
  • Dynamic loading states for each wallet type
  • Contextual help text and browser compatibility warnings

State Management

  • selectedWallet - tracks which wallet type user is connecting
  • ledgerSupported - indicates WebHID/browser compatibility
  • Separate handlers for each wallet type

Error Handling

  • WebHID not supported warning for unsupported browsers
  • Ledger-specific error messages with actionable guidance
  • Maintains existing Freighter error handling

Error Handling Implementation

Ledger Error Codes and Messages

  • Device not found: "Ledger device not found. Make sure your Ledger is connected and unlocked."
  • App not open (6985): "Stellar app is not open on your Ledger device. Open the Stellar app and try again."
  • User rejection (6986): "Action rejected on the Ledger device. Please try again."
  • App not installed (6480): "Stellar app is not installed on your Ledger device. Install it from Ledger Live."
  • WebHID not supported: "WebHID is not supported in this browser. Use Chrome, Edge, or another Chromium-based browser."

Testing Plan

Prerequisites

  1. Ledger Nano S/X device
  2. Stellar app installed on Ledger (via Ledger Live)
  3. Chrome, Edge, or other Chromium-based browser
  4. Test environment with HTTPS (required for WebHID)

Test Cases

1. Basic Connectivity

  • Ledger device appears as option in WalletConnect
  • "Connect Ledger Hardware Wallet" button is enabled in supported browsers
  • Button is disabled with warning message in unsupported browsers
  • Device detection works when connected/unlocked

2. Public Key Retrieval

  • Successfully retrieve public key from Ledger device
  • Public key matches expected format (starts with 'G')
  • Device shows confirmation prompt when confirmOnDevice=true
  • User can approve/reject on device

3. Error Scenarios

  • Device not connected: Clear error message displayed
  • Device locked: Error message instructs to unlock device
  • Stellar app not open: Error message instructs to open app
  • User rejects: Clear rejection message
  • App not installed: Installation instructions provided
  • WebHID not supported: Browser compatibility warning

4. Transaction Signing

  • Successfully sign transaction XDR
  • Device shows transaction details for confirmation
  • User can approve/reject transaction signing
  • Signed transaction is valid and can be submitted

5. SEP-0010 Authentication

  • Complete authentication flow with Ledger
  • Challenge transaction signing works
  • JWT token received upon successful authentication

6. UI/UX Testing

  • Loading states display correctly during each operation
  • Error messages are clear and actionable
  • Help text provides useful guidance
  • Responsive design works on mobile/desktop

7. Compatibility Testing

  • Chrome browser: Full functionality
  • Edge browser: Full functionality
  • Firefox browser: WebHID warning, Ledger disabled
  • Safari browser: WebHID warning, Ledger disabled

Manual Testing Steps

  1. Setup Environment

    cd frontend
npm install
npm run dev

    Open http://localhost:3000 in Chrome

  2. Test Freighter (Baseline)

    • Connect with Freighter wallet
    • Verify existing functionality works
    • Complete SEP-0010 authentication

  3. Test Ledger Hardware Wallet

    • Connect Ledger device via USB
    • Unlock device and open Stellar app
    • Click "Connect Ledger Hardware Wallet"
    • Approve public key export on device
    • Complete SEP-0010 authentication
    • Test transaction signing

  4. Test Error Cases

    • Try connecting with device locked
    • Try connecting with Stellar app closed
    • Reject operations on device
    • Test in unsupported browsers

Security Considerations

WebHID Security

  • Requires HTTPS in production
  • Browser prompts for device permission
  • User must physically approve operations on device

Key Derivation

  • Uses standard BIP32 path: 44'/148'/0'
  • Follows Stellar SLIP-0010 standard
  • Supports custom account paths for advanced users

Transaction Security

  • All transactions require physical device confirmation
  • Device shows transaction details before signing
  • Private keys never leave the hardware device

Browser Compatibility

Supported Browsers

  • Chrome 89+ (full WebHID support)
  • Edge 89+ (full WebHID support)
  • Other Chromium-based browsers (full WebHID support)

Unsupported Browsers

  • Firefox (WebHID not implemented)
  • Safari (WebHID not implemented)
  • Mobile browsers (limited WebHID support)

Deployment Notes

HTTPS Requirement

WebHID requires secure context in production. Ensure:

  • SSL certificate is properly configured
  • All resources load over HTTPS
  • Mixed content issues are resolved

CSP Headers

Update Content Security Policy to allow WebHID:

connect-src 'self' https:;
feature: hid 'self';

Troubleshooting

Common Issues

"WebHID not supported"

  • Use Chrome, Edge, or Chromium browser
  • Ensure HTTPS in production environment

"Device not found"

  • Check USB connection
  • Unlock Ledger device
  • Open Stellar app

"App not open"

  • Navigate to Stellar app on Ledger
  • Wait for app to fully load

"Transaction signing failed"

  • Ensure sufficient XLM balance
  • Check network connectivity
  • Verify transaction format

Debug Information

Enable browser console to see detailed error messages and WebHID communication logs.

Future Enhancements

Potential Improvements

  1. Multiple Account Support: Allow users to select different account paths
  2. Ledger Live Integration: Direct integration with Ledger Live desktop app
  3. WebUSB Support: Fallback transport for older browsers
  4. Transaction Preview: Enhanced transaction details on device
  5. Multi-signature Support: Support for multi-sig transactions

Performance Optimization

  • Connection pooling for repeated operations
  • Cached device information
  • Optimized error handling

Conclusion

The Ledger hardware wallet implementation provides a secure alternative to Freighter for users who prefer hardware wallet security. The implementation follows best practices for WebHID communication and provides comprehensive error handling for all failure scenarios.

All acceptance criteria have been met:

  • ✅ Ledger option appears in WalletConnect
  • ✅ Public key fetched from Ledger device
  • ✅ Transactions signed on the Ledger device
  • ✅ Error states for disconnected device and closed app
  • ✅ Freighter option still works as before