BitcoinZ Light Wallet Development Assistant

Expert assistant for working with the BitcoinZ Light Wallet codebase - a z-Addr first, Sapling compatible lightwallet client for BitcoinZ built with Electron, React, TypeScript, and Rust.

What This Skill Does

This skill provides comprehensive guidance for developing, building, testing, and maintaining the BitcoinZ Light Wallet. It understands the hybrid architecture combining TypeScript/React frontend with Rust native modules, and helps navigate the codebase, dependencies, and build toolchain.

Instructions

1. Critical Rules - Git Commits

**NEVER include Claude-specific attribution in git commits:**

Do NOT add "🤖 Generated with Claude Code"

Do NOT add "Co-Authored-By: Claude <[email protected]>"

Keep all commits clean and professional without AI assistant references

2. Project Context Awareness

When working with this codebase, understand it is:

**Architecture**: Hybrid TypeScript/React + Rust application

**Framework**: Electron 13 desktop application

**Privacy Focus**: Z-address first with shielded transactions

**Network**: BitcoinZ blockchain (coin type 177, Sapling activation at block 328,500)

**Connectivity**: Light client connecting to remote lightwalletd servers

3. Development Workflow

#### First-Time Setup

1. Verify Node.js version (v14 or v16 required - NOT v17+ due to OpenSSL/Webpack 4 incompatibility)

2. Check directory structure: Repository must be sibling to `zecwallet-light-cli-bitcoinz`

3. Run `yarn install` to install dependencies

4. Run `yarn neon` to build the native Rust module (REQUIRED before any other commands)

5. Run `yarn start` to launch development server

#### Daily Development

Always run `yarn neon` after pulling changes that affect the native module

Use `yarn start` for hot-reload development

Run `yarn test` before committing changes

For single component testing: `yarn test src/components/ComponentName.test.tsx --watch`

#### Building Distributions

macOS: `yarn dist:mac`

Windows: `yarn dist:win`

Linux: `yarn dist:linux`

4. Code Navigation

#### Frontend Structure (`/src`)

**Entry points**: `index.tsx` (React), `public/electron.js` (Electron main)

**Core components**: `App.tsx`, `Dashboard.tsx`, `Send.tsx`, `Receive.tsx`, `Transactions.tsx`

**State management**: `AppState.ts` defines all application state types

**RPC layer**: `rpc.ts` handles all blockchain communication

#### Native Module (`/native`)

Rust codebase using `zecwalletlitelib`

Built as Node.js addon via Neon

Provides cryptographic operations and blockchain connectivity

Interface exposed through `src/native.node` (auto-generated)

Implementation in `native/src/lib.rs`

5. Common Development Tasks

#### Adding New Components

1. Review existing components for patterns and conventions

2. Use TypeScript with complete type definitions

3. Follow AppState pattern for state management

4. Match existing import and styling patterns

5. Add corresponding tests using Jest and React Testing Library

#### Modifying RPC Communication

1. Frontend RPC logic: Update `src/rpc.ts`

2. Native interface: Modify `native/src/lib.rs`

3. Rebuild with `yarn neon` after changes

4. Test with `yarn test` and manual verification

#### Working with Transactions

Type definitions: `src/components/AppState.ts`

Send functionality: `src/components/Send.tsx`

History display: `src/components/Transactions.tsx`

Parsing logic: Look for transaction parsing utilities in `Transactions.tsx`

6. Key Technical Constraints

#### Node.js Version

**Required**: v14 or v16 only

**Reason**: Webpack 4 + OpenSSL compatibility issues with v17+

**Workaround**: Project uses `NODE_OPTIONS=--openssl-legacy-provider`

#### Rust Toolchain

**Version**: 1.62+ (specified in `rust-toolchain`)

**Build**: Always run `yarn neon` before starting development or building distributions

#### Directory Structure

**Sibling repositories required**:

- `../bitcoinz-light-wallet/` (this repo)

- `../zecwallet-light-cli-bitcoinz/` (dependency)

#### Platform Build Dependencies

**Windows**: Visual Studio Build Tools

**Linux**: gcc, make, standard build tools

**macOS**: Xcode Command Line Tools

7. Security Considerations

**NEVER log or expose:**

Private keys

Seed phrases

Unencrypted wallet data

**Security mechanisms:**

Private keys encrypted and stored locally via electron-settings

View keys used for blockchain synchronization

All sensitive operations performed in native Rust module

8. Architecture Patterns

#### Light Client Design

Connects to remote lightwalletd servers (no full node required)

Efficient blockchain synchronization using compact blocks

Privacy-preserving query protocols

#### Privacy First

Default to shielded (z-address) transactions

Automatic note management and UTXO selection

Sapling protocol support for enhanced privacy

#### State Management

Centralized state types in `AppState.ts`

RPC class manages blockchain data updates via callbacks

Component-local state for UI-specific concerns

9. Testing Guidelines

**Framework**: Jest + React Testing Library

**Coverage**: Run `yarn test` for full suite

**Watch mode**: `yarn test --watch` for TDD workflow

**Component isolation**: Test individual components with specific file paths

**Integration**: Test RPC communication with mock responses

10. Troubleshooting Common Issues

#### Build Failures

Verify Node.js version (v14 or v16)

Ensure `yarn neon` completed successfully

Check sibling directory structure for `zecwallet-light-cli-bitcoinz`

Verify platform build tools are installed

#### Runtime Issues

Check lightwalletd server connectivity

Verify blockchain synchronization status

Review Electron console for frontend errors

Check native module logs for Rust errors

#### Testing Failures

Ensure all dependencies installed with `yarn install`

Rebuild native module with `yarn neon`

Clear Jest cache if encountering stale test data

Usage Examples

Example 1: Setting Up Development Environment

```bash

Verify Node.js version

node --version # Should be v14.x or v16.x

Clone and navigate to repository

cd bitcoinz-light-wallet

Install dependencies

yarn install

Build native Rust module

yarn neon

Start development server

yarn start

```

Example 2: Adding a New Transaction Feature

1. Define new state types in `src/components/AppState.ts`

2. Add RPC methods in `src/rpc.ts` if blockchain communication needed

3. Create or update component in `src/components/`

4. Add tests in corresponding `.test.tsx` file

5. Rebuild and test: `yarn neon && yarn test`

Example 3: Building for Distribution

```bash

Build native module

yarn neon

Run tests

yarn test

Build for target platform

yarn dist:mac # or dist:win, dist:linux

```

Important Reminders

Always run `yarn neon` before starting development or building

Never use Node.js v17+ (Webpack 4 incompatibility)

Keep sibling directory structure intact

Never expose private keys or seed phrases

Remove all AI attribution from git commits

Test thoroughly before building distributions

Follow existing code patterns and conventions

BitcoinZ Light Wallet Development Assistant

BitcoinZ Light Wallet Development Assistant

What This Skill Does

Instructions

1. Critical Rules - Git Commits

2. Project Context Awareness

3. Development Workflow

4. Code Navigation

5. Common Development Tasks

6. Key Technical Constraints

7. Security Considerations

8. Architecture Patterns

9. Testing Guidelines

10. Troubleshooting Common Issues

Usage Examples

Example 1: Setting Up Development Environment

Verify Node.js version

Clone and navigate to repository

Install dependencies

Build native Rust module

Start development server

Example 2: Adding a New Transaction Feature

Example 3: Building for Distribution

Build native module

Run tests

Build for target platform

Important Reminders

Reviews (0)