bitbox-wallet-app: Instructions file for Codex

Repository Guidelines for bitbox-wallet-app

Architecture Overview

BitBoxApp is a cryptocurrency hardware wallet companion app. A Go backend provides an HTTP API consumed by a React/TypeScript single-page app. The same frontend is embedded in desktop (Qt WebEngine), Android, and iOS shells via platform-specific bridges.

Project Structure & Module Organization

The repository powers the BitBoxApp. Core Go services live under backend/ with entrypoints in cmd/ (e.g., cmd/servewallet). Frontend clients reside in frontends/ (web for React, qt for the desktop app, android and ios for mobile artifacts). Shared assets and docs sit in docs/, while automation lives in scripts/. Use vendor/ for pinned Go modules.

Key backend packages:

• backend/coins/btc/ — Bitcoin (also used for LTC); backend/coins/eth/ — Ethereum + ERC20 tokens
• backend/coins/btc/handlers/handlers.go — account-level HTTP handlers shared by all account types
• backend/devices/bitbox02/ — BitBox02 USB/Bluetooth device drivers
• backend/handlers/handlers.go — top-level HTTP routing (gorilla/mux)

Backend and Frontend Responsibilities

The frontend should ideally concern itself only with presentation and collecting user input. Keep business logic in the backend so that it has one authoritative implementation. This includes generating UUIDs, parsing amounts, and performing arithmetic on amounts. The frontend may format backend-provided values for display, but it should not independently implement domain rules or calculations.

Build, Test, and Development Commands

Requirements

See go.mod and frontends/web/package.json for required Go and Node.js versions. Run make envinit once to install golangci-lint, gomobile, moq, mockery, goimports, and other dev tooling.

Getting Started

Run make buildweb before the first make webdev to install npm dependencies. Then run make servewallet and make webdev in separate terminals.

Key Make Targets

• make servewallet starts the Go backend (port 8082) in testnet mode by default. Pair with make webdev (port 8080) for live UI development.
• Backend variants: make servewallet-mainnet, make servewallet-regtest, make servewallet-simulator, make servewallet-prodservers.
• The Go backend does not hot-reload — restart it after code changes. The Vite frontend hot-reloads automatically.
• make buildweb performs a clean web build (npm ci --ignore-scripts && npm run build) used by desktop packages.
• make webtest and make webtestwatch run Vitest unit tests (one-shot and watch mode).
• make webe2etest runs Playwright E2E tests. make weblint runs ESLint + type-check. make webfix auto-fixes lint issues.
• make ci (or ./scripts/ci.sh) mirrors CI: Go race tests (with GORACE="halt_on_error=1"), frontend build, linting, and i18n format checks. Use it before large pull requests.
• make go-vendor re-vendors Go dependencies.
• All Go commands require -mod=vendor (e.g., go build -mod=vendor ./...).