synor/apps/desktop-wallet/README.md

# Synor Desktop Wallet

A secure desktop wallet for the Synor blockchain network with post-quantum cryptography support (Dilithium3).

## Features

- **24-word BIP39 Mnemonic**: Industry-standard seed phrase generation
- **Post-Quantum Signatures**: Dilithium3 (NIST FIPS 204) for future-proof security
- **QR Code Generation**: Easily share receive addresses with scannable QR codes
- **OS Keychain Integration**: Secure storage via macOS Keychain, Windows Credential Manager, or Linux Secret Service
- **System Tray**: Minimize to tray for background operation
- **Auto-Updates**: Built-in updater for seamless version upgrades (when code-signed)
- **Multiple Addresses**: Generate and manage multiple receiving addresses

## Installation

### Download Pre-built Binaries

Download the latest release from [GitHub Releases](https://github.com/g1-technologies/synor/releases):

| Platform | File | Notes |
|----------|------|-------|
| **macOS (Apple Silicon)** | `Synor-Wallet_x.x.x_aarch64.dmg` | M1/M2/M3 Macs |
| **macOS (Intel)** | `Synor-Wallet_x.x.x_x64.dmg` | Intel Macs |
| **Windows** | `Synor-Wallet_x.x.x_x64_en-US.msi` | Recommended installer |
| **Windows (portable)** | `Synor-Wallet_x.x.x_x64-setup.exe` | Alternative installer |
| **Linux** | `Synor-Wallet_x.x.x_amd64.AppImage` | Universal Linux |

### macOS First Launch

If the app is not code-signed, macOS Gatekeeper will block it. To bypass:
1. Right-click the app → Open
2. Click "Open" in the dialog

Or run from terminal:
```bash
xattr -cr /Applications/Synor\ Wallet.app
```

## Development

### Prerequisites

- **Node.js 20+**
- **pnpm** (`npm install -g pnpm`)
- **Rust 1.75+** (`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`)
- **Tauri CLI** (`cargo install tauri-cli`)

**macOS additional:**
```bash
brew install rocksdb
```

**Linux additional:**
```bash
sudo apt-get install -y \
  libgtk-3-dev \
  libwebkit2gtk-4.1-dev \
  libsoup-3.0-dev \
  libjavascriptcoregtk-4.1-dev \
  libappindicator3-dev \
  librsvg2-dev \
  patchelf \
  libclang-dev \
  llvm-dev
```

### Development Mode

#### Full Development (with Rust backend)

```bash
cd apps/desktop-wallet
pnpm install
pnpm tauri:dev
```

#### Browser Preview Mode (UI only)

For rapid UI development without compiling Rust:

```bash
cd apps/desktop-wallet
pnpm install
pnpm dev
```

Then open http://localhost:1420 in your browser.

> **Note**: Browser preview mode uses mock data. Wallet operations (create, import, sign) are simulated.

### Build for Production

```bash
cd apps/desktop-wallet
pnpm install
pnpm tauri:build
```

Output locations:
- **macOS**: `src-tauri/target/release/bundle/dmg/`
- **Windows**: `src-tauri/target/release/bundle/msi/`
- **Linux**: `src-tauri/target/release/bundle/appimage/`

### Docker Development

```bash
cd apps/desktop-wallet
docker-compose -f docker-compose.dev.yml up
```

Runs frontend at http://localhost:19420

### Testing

```bash
# Run Playwright E2E tests
pnpm test

# Run with UI
pnpm test:ui

# Run headed (visible browser)
pnpm test:headed
```

## Project Structure

```
apps/desktop-wallet/
├── src/                    # React frontend
│   ├── components/         # Reusable UI components
│   ├── pages/              # Route pages
│   │   ├── Welcome.tsx     # Create/import wallet
│   │   ├── Dashboard.tsx   # Balance overview
│   │   ├── Send.tsx        # Send transactions
│   │   ├── Receive.tsx     # Receive with QR codes
│   │   ├── Transactions.tsx # Transaction history
│   │   └── Settings.tsx    # App settings
│   ├── store/              # Zustand state management
│   │   ├── wallet.ts       # Wallet state
│   │   ├── node.ts         # Node connection state
│   │   └── mining.ts       # Mining state
│   ├── lib/                # Utilities
│   │   └── tauri.ts        # Tauri invoke wrapper
│   └── App.tsx             # Route definitions
├── src-tauri/              # Rust backend
│   ├── src/
│   │   ├── commands.rs     # Tauri command handlers
│   │   ├── keychain.rs     # OS keychain integration
│   │   ├── crypto.rs       # Cryptographic operations
│   │   └── lib.rs          # Main library
│   ├── Cargo.toml          # Rust dependencies
│   ├── tauri.conf.json     # Tauri configuration
│   └── icons/              # App icons
├── e2e/                    # Playwright E2E tests
├── playwright.config.ts    # Test configuration
└── package.json            # Node.js dependencies
```

## Configuration

### Tauri Configuration

Edit `src-tauri/tauri.conf.json`:

```json
{
  "app": {
    "windows": [{
      "title": "Synor Wallet",
      "width": 1024,
      "height": 768,
      "minWidth": 800,
      "minHeight": 600
    }]
  },
  "plugins": {
    "updater": {
      "endpoints": ["https://releases.synor.io/wallet/{{target}}/{{arch}}/{{current_version}}"]
    }
  }
}
```

### Security

The Content Security Policy (CSP) is configured to:
- Allow connections to `*.synor.io` and localhost
- Block inline scripts (except WASM)
- Prevent embedding in iframes

## Embedded Node (Optional)

The wallet can optionally include a full node for decentralized operation:

```bash
# Build with embedded node support
cargo build --release --features embedded-node
```

This enables:
- Running a full node inside the wallet
- Mining directly from the wallet
- No external RPC dependency

## Changelog

### v0.1.1 (2026-02-02)

**New Features:**
- QR code generation on Receive page for easy address sharing
- Improved navigation flow on unlock screen

**Bug Fixes:**
- Fixed app crash on macOS after installation (Tauri 2.0 plugin configuration)
- Fixed icon bit depth compatibility issue (16-bit to 8-bit RGBA)
- Removed deprecated plugin scope configurations

**Technical:**
- Updated to Tauri 2.0 stable plugin APIs
- Added missing Rust dependencies (`once_cell`, `md5`)
- Removed duplicate imports in commands.rs

### v0.1.0 (Initial Release)

- Basic wallet creation and import
- Send/receive SYN tokens
- Transaction history
- Multiple address support
- OS keychain integration
- System tray support

## Security Notes

- **Seed phrases** are encrypted with Argon2id and stored in OS keychain
- **Private keys** are derived using BIP32 HD wallet standard
- **Transactions** are signed locally; private keys never leave the device
- **Post-quantum signatures** use Dilithium3 (NIST FIPS 204)

## License

MIT OR Apache-2.0