Skip to content

README.md

Latest commit

 

History

History
356 lines (273 loc) · 11.5 KB

README.md

File metadata and controls

356 lines (273 loc) · 11.5 KB

BSV Desktop

A cross-platform desktop wallet application for the BSV Blockchain, built with Electron and Vite. BSV Desktop provides a complete wallet interface with support for both self-custody (local) and remote storage options.

The default configuration is for locally stored transactions and metadata, entirely self custody.

Note: This project was migrated from Tauri to Electron to enable local database storage. See PORTED.md for the full migration story.

What is BSV Desktop?

BSV Desktop is a feature-rich Bitcoin SV wallet that runs on macOS, Windows, and Linux. It provides:

  • 🔐 Self-Custody Mode - Full control with local key management and SQLite storage
  • ☁️ Remote Storage Mode - WAB (Wallet Authentication Backend) integration with remote storage
  • 🌐 BRC-100 Interface - HTTPS server on port 2121 for external app integration
  • 📱 Identity Certificates - BRC-64/65 certificate management
  • 💸 Payment Protocol - BRC-29 payment support
  • 🎯 Overlay Services - App permissions, baskets, protocols, counterparties
  • 🔄 Background Monitoring - Automatic transaction and proof updates
  • 💾 Flexible Storage - Choose between local SQLite or remote storage providers

Architecture

BSV Desktop consists of three main components:

1. React UI Library (src/lib/)

Reusable React components and wallet logic:

  • WalletContext.tsx - Wallet state management and initialization
  • UserInterface.tsx - Main router and permission handlers
  • Permission handlers for baskets, certificates, protocols, spending
  • Dashboard pages for apps, identity, trust, settings

2. Electron Main Process (electron/)

Native functionality and backend services:

  • main.ts - Window management, IPC handlers
  • httpServer.ts - BRC-100 HTTPS server on port 2121
  • storage.ts - SQLite storage manager with IPC proxy
  • monitor-worker.ts - Background monitoring process

3. Renderer Process (src/)

Application entry point that uses the UI library:

  • main.tsx - React app entry, wallet initialization
  • onWalletReady.ts - HTTP request handler for BRC-100 interface
  • electronFunctions.ts - Native handlers (focus, downloads, dialogs)

Getting Started

Prerequisites

  • Node.js 18+ and npm
  • Git

Linux-Specific Requirements

BSV Desktop supports both Wayland and X11 display servers on Linux. The application automatically detects and uses the appropriate display server:

  • Wayland: Automatically detected and used when available
  • X11: Used as fallback when Wayland is unavailable or fails to initialize
  • Manual Override: Set environment variables to force X11 if needed: 
    export GDK_BACKEND=x11
./BSV-Desktop-*.AppImage

The application includes GPU sandbox disabling for better compatibility with AppImages and containerized environments.

Installation

git clone https://github.com/bsv-blockchain/bsv-desktop.git
cd bsv-desktop
npm install

Development Mode

Run the app in development mode with hot reload:

npm run dev

This will:

  1. Start Vite dev server on port 5173
  2. Compile TypeScript for Electron backend
  3. Launch Electron with DevTools open
  4. Enable hot module replacement for React code

Dev Mode Features:

  • Automatic recompilation on file changes
  • React DevTools enabled
  • Console logs from both main and renderer processes
  • HTTPS server running on https://localhost:2121

Building

Build the application for production:

npm run build

This runs:

  • npm run build:renderer - Vite build → dist/
  • npm run build:electron - TypeScript build → dist-electron/

Packaging

Package the app for distribution:

# Build for current platform
npm run package

# Platform-specific builds
npm run package:mac    # macOS (DMG + ZIP)
npm run package:win    # Windows (NSIS + Portable)
npm run package:linux  # Linux (AppImage + DEB)

Built packages will be in the release/ directory with versioned filenames.

Project Structure

bsv-desktop/
├── src/lib/                      # React UI library (reusable)
│   ├── WalletContext.tsx         # Wallet state and initialization
│   ├── UserContext.tsx           # App metadata and native handlers
│   ├── components/               # Reusable components
│   │   ├── WalletConfig.tsx      # WAB/storage configuration
│   │   ├── AmountDisplay.tsx     # Currency display with rates
│   │   └── *Handler.tsx          # Permission request modals
│   ├── pages/                    # Dashboard pages
│   │   ├── Dashboard/            # Main dashboard and settings
│   │   └── Recovery/             # Password/phone recovery
│   └── navigation/               # Menu and routing
│
├── src/                          # Electron app entry
│   ├── main.tsx                  # React app initialization
│   ├── onWalletReady.ts          # BRC-100 HTTPS handler
│   ├── electronFunctions.ts      # Native handlers (focus, downloads, dialogs)
│   └── StorageElectronIPC.ts     # IPC storage proxy
│
├── electron/                     # Electron backend
│   ├── main.ts                   # Main process, window lifecycle
│   ├── httpServer.ts             # Express server (port 2121)
│   ├── storage.ts                # Storage manager + IPC handlers
│   ├── monitor-worker.ts         # Background monitoring process
│   ├── preload.ts                # IPC bridge (context isolation)
│   └── storage-loader.cjs        # Lazy-load better-sqlite3
│
├── dist/                         # Vite build output
├── dist-electron/                # TypeScript build output
├── release/                      # Packaged apps
│
├── package.json                  # Dependencies and scripts
├── tsconfig.json                 # TypeScript config (renderer)
├── tsconfig.electron.json        # TypeScript config (main)
├── vite.config.ts                # Vite build config
└── electron-builder.json5        # Packaging config

Configuration

Users can configure at runtime via the WalletConfig component:

  • Authentication: WAB or self-custody (default: self-custody)
  • Network: Mainnet or testnet
  • Storage: Remote (StorageClient) or local (SQLite)
  • Message Box: Enable/disable message box integration

Configuration is persisted in Version 3 snapshots (localStorage + encrypted).

Storage Modes

Local Storage (Self-Custody)

  • Database: SQLite via better-sqlite3 + Knex
  • Location: ~/.bsv-desktop/wallet.db (mainnet) or wallet-test.db (testnet)
  • Features: Full offline mode, no external dependencies
  • Architecture: IPC proxy from renderer → main → StorageKnex

Remote Storage (WAB)

  • Provider: StorageClient (HTTP-based)
  • Server: User-configured URL (e.g., https://storage.babbage.systems)
  • Features: Cloud backup, multi-device sync
  • Authentication: WAB (Wallet Authentication Backend) with phone/DevConsole verification

Background Monitoring

BSV Desktop runs a separate Monitor worker process that:

  • Monitors for new transactions
  • Updates merkle proofs
  • Tracks UTXO state changes
  • Syncs certificates and outputs

Implementation:

  • electron/monitor-worker.ts - Separate Node.js process
  • SQLite WAL mode enables concurrent access
  • Automatic start on wallet initialization
  • Graceful shutdown on app exit

HTTP Server (BRC-100 Interface)

External apps can connect to the wallet via HTTPS on port 2121:

Endpoints:

  • POST /createAction - Create and broadcast transactions
  • POST /createHmac - Generate HMAC signatures
  • POST /createCertificate - Create identity certificates
  • GET /isAuthenticated - Check wallet authentication status
  • And all other BRC-100 interface methods

CORS: Enabled for all origins in dev mode

Testing:

curl https://127.0.0.1:2121/isAuthenticated

Contributing

We welcome contributions! Here's how to get started:

Development Workflow

  1. Fork and clone the repository
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Make changes and test with npm run dev
  4. Build: npm run build to ensure compilation succeeds
  5. Test packaging: npm run package to verify build output
  6. Commit: Use clear commit messages
  7. Push and create PR: Describe changes and test coverage

Code Structure

  • UI components go in src/lib/components/
  • Pages go in src/lib/pages/
  • Electron backend changes go in electron/
  • Shared types go in src/lib/types/ or src/global.d.ts

Testing

Currently no automated tests. Manual testing checklist:

  • App launches and shows login screen
  • WAB authentication works (with real WAB server)
  • Self-custody mode works (local database)
  • Balance displays correctly
  • Sending transactions works
  • HTTPS server responds on port 2121
  • App packages without errors

Debugging

Main Process (Electron backend):

# Logs appear in terminal where `npm run dev` runs
console.log('[Main]', 'Debug message')

Renderer Process (React UI):

# Open DevTools (auto-opens in dev mode)
# Cmd+Option+I (macOS) or Ctrl+Shift+I (Windows/Linux)
console.log('[Renderer]', 'Debug message')

HTTP Server:

# Test endpoints
curl -X POST https://127.0.0.1:2121/isAuthenticated

Releasing a New Version

1. Update Version

Edit package.json:

{
  "version": "0.7.0"
}

2. Commit and Tag

git add package.json
git commit -m "Bump version to 0.7.0"
git tag v0.7.0
git push origin master --tags

3. Build Packages

# Build for all platforms (requires platform-specific machines)
npm run package:mac
npm run package:win
npm run package:linux

# Or build for current platform only
npm run package

4. Publish Release

  1. Go to GitHub Releases
  2. Click "Draft a new release"
  3. Select tag v0.7.0
  4. Upload files from release/ directory:
    • BSV-Desktop-0.7.0.dmg (macOS)
    • BSV-Desktop-0.7.0-mac.zip (macOS)
    • BSV-Desktop-Setup-0.7.0.exe (Windows)
    • BSV-Desktop-0.7.0.AppImage (Linux)
    • bsv-desktop_0.7.0_amd64.deb (Linux)
  5. Write release notes highlighting changes
  6. Click "Publish release"

5. Update Documentation

Update README.md, PORTED.md, or CHANGELOG.md as needed.

Dependencies

Core Wallet

  • @bsv/wallet-toolbox - Wallet managers, storage, permissions
  • @bsv/sdk - BSV blockchain primitives
  • @bsv/message-box-client - Message box integration
  • @bsv/uhrp-react - UHRP protocol support

Electron Backend

  • electron - Desktop framework
  • express - HTTP server
  • better-sqlite3 - SQLite database
  • knex - SQL query builder

React Frontend

  • react + react-dom - UI framework
  • @mui/material + @emotion - Material-UI components
  • react-router-dom - Routing (v5)
  • react-toastify - Toast notifications

License

Open BSV License

Support

Related Projects