|
1 | | -# Repository Guidelines for bitbox-wallet-app |
| 1 | +# Repository Guidelines for bitbox-api-rs |
2 | 2 |
|
3 | | -## Project Structure & Module Organization |
4 | | -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 shell, `android` for mobile artifacts). Shared assets and docs sit in `docs/`, while automation lives in `scripts/`. Use `vendor/` for pinned Go modules and keep `config/` aligned with the scenarios documented in `docs/BUILD.md`. |
5 | | - |
6 | | -## Build, Test, and Development Commands |
7 | | -- `make envinit` installs golangci-lint, gomobile, and other dev tooling. Run once per environment refresh. |
8 | | -- `make servewallet` starts the Go backend against the vendored modules; pair it with `make webdev` (which calls `npm start`) for live UI development. |
9 | | -- `make buildweb` performs a clean web build (`npm ci && npm run build`) used by desktop packages. |
10 | | -- `make webtest`, `make webe2etest`, and `make weblint` proxy to the React test, Playwright, and ESLint pipelines under `frontends/web`. |
11 | | -- `./scripts/ci.sh` mirrors CI: Go race tests, frontend build, and packaging checks. Use it before large pull requests. |
12 | | - |
13 | | -## Coding Style & Naming Conventions |
14 | | -Go code must stay gofmt/goimports clean; prefer package-level names that mirror directory names (`backend/accounts`, `backend/rates`). TypeScript follows the ESLint config surfaced by `npm run lint`; keep React components PascalCased and colocate styles alongside component folders. When adding Make targets or scripts, stick to lowercase hyphenated names (`servewallet-prodservers`). |
15 | | - |
16 | | -## Testing Guidelines |
17 | | -Place Go tests in `_test.go` files and run `go test -mod=vendor ./...` (optionally via `scripts/coverage.sh` to emit `coverage.cov`). Frontend unit specs live beside components as `*.test.ts(x)`; invoke `make webtest` for the suite. Use `make webe2etest` for Playwright smoke flows and document new scenarios in `frontends/web/tests/README.md` if they require fixtures. |
18 | | - |
19 | | -## Commit & Pull Request Guidelines |
20 | | -Follow the existing `context: summary` convention (lowercase imperative, no trailing period)—e.g., `frontend: simplify account selector`. Keep commits atomic and under ~500 lines when possible. Pull requests should: reference related issues (`Fixes #123`), summarize backend/UI impact, list manual verification steps, and attach UI screenshots or simulator recordings when user-facing. Ensure all listed commands above succeed before requesting review; note deliberate deviations explicitly in the PR description. |
| 3 | +This repo contains both a Rust library and a NPM library. |
21 | 4 |
|
22 | | -# Repository Guidelines for bitbox02-firmware |
| 5 | +## Versioning |
| 6 | +- The Rust client version is in Cargo.toml. The changelog is in CHANGELOG-rust.md. The readme is in README-rust.md |
| 7 | +- The NPM client version is in NPM_VERSION. The changelog is in CHANGELOG-npm.md. The readme is in README-npm.md. |
23 | 8 |
|
24 | 9 | ## Project Structure & Module Organization |
25 | | -Core firmware and bootloader code sits in `src/`, grouped by subsystem (`bootloader`, `usb`, `ui`, `securechip`, plus a `rust/` workspace). Tests live in `test/`: `unit-test/` for cmocka suites, `hardware-fakes/` for device shims, and `simulator/` assets. The BitB02 Python client library is in `py/bitbox02`. Supporting tooling is in `scripts/` (CI, J-Link macros), and `doc/` for manuals. Vendored dependencies are tracked in `external/`. |
26 | | - |
27 | | -The firmware has C and Rust code. Rust code lines in src/rust. The rust crates are: |
28 | | -- bitbox02-rust: the main app logic. It can expose functions to C using extern "C". If it needs access to C functions, it has to go through the bitbox02 crate. Never add bitbox02-sys dep to bitbox02-rust or use if the dep is present. |
29 | | -- bitbox02-sys: generated bindings to C code. build.rs contains the functions etc that are exposed. See also `wrapper.h`, it needs to include any C headers/declarations that are added to build.rs. |
30 | | -- bitbox02: wraps bitbox02-sys functions as idiomatic safe Rust |
31 | | - |
32 | | -bitbox02-rust is pure Rust. If it needs to use a C function, it should instead use the safe C wrapper in the bitbox02 crate. |
| 10 | +- `src/`: core Rust library (transport, protocol, coin-specific modules). |
| 11 | +- `tests/`: integration tests; prefer adding new end-to-end flows here. |
| 12 | +- `examples/`: runnable usage samples (`cargo run --example …`) for common flows. |
| 13 | +- `messages/`: protobuf definitions; regenerated via `make build-protos`. |
| 14 | +- `sandbox/`: browser demo for the WASM/JS API, used with WebHID. |
| 15 | +- `scripts/`: build utilities (for example, protocol buffer generation). |
33 | 16 |
|
34 | 17 | ## Build, Test, and Development Commands |
35 | | -- `make dockerpull` / `make dockerdev`: fetch and enter the maintained development container. |
36 | | - |
37 | | -All make commands are to be run inside docker like this: `./scripts/docker_exec.sh make -j <command>`, e.g. `./scripts/docker_exec.sh make -j firmware`. |
38 | | - |
39 | | -- `make firmware` / `make bootloader`: compile firmware or bootloader ELFs into `build/`. |
40 | | -- `make simulator`: build the Linux simulator under `build-build-noasan/bin/`. |
41 | | -- `make unit-test && make run-unit-tests`: build and run the C cmocka/CTest suite with ASan/UBSan. |
42 | | -- `make run-rust-unit-tests`: build and run the Rust unit tests |
43 | | -- `make run-rust-clippy`: lint Rust code with the workspace configuration. |
| 18 | +- `cargo build` – build the Rust crate. |
| 19 | +- `cargo test` – run unit and integration tests. |
| 20 | +- `cargo fmt` – format Rust code using the repo’s `rustfmt` settings. |
| 21 | +- `make build-protos` – regenerate Rust code from `messages/*.proto`. |
| 22 | +- `make wasm` – build the WASM/JS package (`pkg/`) via `wasm-pack`. |
| 23 | +- `make build-sandbox` - build the WebHID sandbox in `sandbox/`. |
| 24 | +- `make run-sandbox` – start the WebHID sandbox in `sandbox/` for manual testing. |
44 | 25 |
|
45 | 26 | ## Coding Style & Naming Conventions |
46 | | -`.clang-format` (Chromium base, 4-space indent, Linux braces) and `.clang-tidy` govern C/C++. Use `snake_case` for symbols, `PascalCase` for types, and `ALL_CAPS` for macros. Python utilities follow `.pylintrc` rules (100-column limit, explicit imports). Rust crates rely on `rustfmt.toml` and the pinned toolchain in `rust-toolchain.toml`; keep module paths aligned with `src/rust` and regenerate bindings (`cbindgen`, protobuf) when interfaces change. |
47 | | - |
48 | | -For C code changes, run ./scripts/format to format the code. For Python changes, run `black` to format the code. |
| 27 | +- Rust edition 2021; rely on `cargo fmt` for formatting (4-space indents, standard rustfmt defaults). |
| 28 | +- Modules and files: `snake_case`; types and traits: `PascalCase`; functions and methods: `snake_case`. |
| 29 | +- Prefer explicit, typed errors using `thiserror`; avoid `unwrap`/`expect` in library code. |
49 | 30 |
|
50 | 31 | ## Testing Guidelines |
51 | | -Place new C specs in `test/unit-test` and add doubles to `test/hardware-fakes` when hardware behavior is mocked; follow the `test_<feature>.c` naming pattern and update CMake lists. Rust crates use standard `te |
52 | | -sts/` modules or `#[cfg(test)]` blocks. Before opening a PR, run both `make run-unit-tests` and `make run-rust-unit-tests`, and refresh `make coverage` for cryptography or security-sensitive areas. |
53 | | - |
54 | | -- in Rust unit tests, prefer .unwrap() over .expect(). |
55 | | -- In Rust unit tests, if testing a function foo, name the test `test_foo` (or `test_foo_xyz` if it needs qualifiers). |
56 | | -- in Rust unit tests, prefer .as_slice() instead of `&*` for wrapped/zeroized Vec<u8>. |
| 32 | +- Place integration tests in `tests/` and unit tests next to the code in `src/`. |
| 33 | +- Name tests after the behavior under test (for example, `sign_psbt_roundtrip`). |
| 34 | +- Run `cargo test` before opening a PR; for deeper changes, consider `cargo tarpaulin --features=simulator,tokio --out Html`. |
| 35 | +- Check README-rust.md for how to run simulator tests. |
| 36 | +- Check ./ci/ci.sh for how to run tests |
| 37 | +- `cargo test` will output a lot of warnings, that is normal without the right features selected (see ci.sh). Don't attempt to fix them if not prompted to do so. |
57 | 38 |
|
58 | 39 | ## Commit & Pull Request Guidelines |
59 | | -Write commits with a ≤50 character subject, blank line, and explanatory body per `CONTRIBUTING.md`; reference issues via `refs #1234` or `fixes #1234`. Keep patches atomic—avoid mixing formatting and logic. Pull requests should outline the change, list verification commands or screenshots, and flag hardware requirements; mark drafts with `[WIP]` until they are ready. Rebase on `master` regularly, and wait to squash until reviews conclude. |
60 | | - |
61 | | - |
62 | | -## Various |
63 | | - |
64 | | -- when converting C code to Rust code, make the Rust code idiomatic, not a 1:1 rewrite. |
65 | | -- when exposing Rust functions to C using extern "C", use util::bytes::Bytes and util::Bytes::BytesMut ot pass in buffers and write to out buffers. |
66 | | -- when using Zeroizing<...> for buffers, use Zeroizing<Vec<u8>>. For other sensitive data, use Zeroizing<Box<...>>. |
67 | | -- when wrapping C functions in the bitbox02 crate, make it safe idiomatic Rust, with no C types in the input/output. Results should be returned, not passed to an out param. |
68 | | -- don't stop the Rust docker container unless you have restart it, e.g. if the .containerversion changed after checking out a different commit. |
69 | | -- never commit a change if not explicitly being instructed to |
70 | | -- when porting or refactoring or rewriting code, retain original comments and docstrings if they still apply. when reviewing commits that refactor/move/rewrite code, point out if comments were dropped. |
71 | | -- when editing code, unless otherwise instructed, try to keep the diff small and not do any unprompted refactorings or core reorganizations. |
72 | | -- rust fmt all Rust files you modify, using 2024 edition. |
| 40 | +- Use short, focused commits; prefix with area when useful (for example, `btc: …`, `npm: …`, `tests: …`). |
| 41 | +- Write commit subjects in imperative mood (for example, `add OP_RETURN example`). |
| 42 | +- PRs should describe motivation, key changes, and any API or protocol impacts; link related issues and mention how it was tested (commands, examples, or sandbox runs). |
0 commit comments