Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
7ea3f95
docs(parts): mark Maix Amigo as discontinued, drop sale links
joaozinhom Jul 8, 2026
2fe2f5f
refactor: use native uUR on tests and simulator
odudex Jul 29, 2026
8090ac7
fix: remove Maix Bit and CIF camera support
odudex Jul 31, 2026
5c4ece9
chore: bump MaixPy with Shannon changes and RNG removal
odudex Jul 31, 2026
b0a7357
docs: add Maix Bit removal and Shannon calc fix to CHANGELOG
odudex Jul 31, 2026
fc80805
fix: verify PSBT input amounts before showing the fee
odudex Jul 30, 2026
c7e48ae
fix: render negative amounts correctly in format_btc
odudex Jul 30, 2026
d6813d8
fix: reject a PSBT whose outputs exceed its inputs
odudex Jul 30, 2026
518b331
feat: warn when PSBT input amounts cannot be verified
odudex Jul 30, 2026
bdaed1a
i18n: translate the unverified input amounts warning
odudex Jul 30, 2026
48920c3
docs: add PSBT input amount fixes to CHANGELOG
odudex Jul 31, 2026
f15308e
fix: register embed_fire in the bdftokff device list
odudex Jul 31, 2026
a932922
chore: bump MaixPy with updated glyphs
odudex Jul 31, 2026
dea991d
chore: bump version to 26.08.0
odudex Jul 31, 2026
74d6ed4
chore(Maixpy): bump cUR
odudex Aug 1, 2026
4c05cef
docs: update CHANGELOG
odudex Aug 1, 2026
0b3e01b
fix: bind BBQr parts to the first part of the stream
odudex Aug 1, 2026
ec058d8
docs: update CHANGELOG
odudex Aug 3, 2026
be5eda2
Merge branch 'release-26.08.0'
odudex Aug 4, 2026
1967e16
docs: add Jean Do as security contact
odudex Aug 6, 2026
8afa9ee
Merge pull request #920 from odudex/docs/security-contacts
jdlcdl Aug 6, 2026
ddea2c2
feat: add R&D focus disclaimer, acknowledged once per version at boot
odudex Aug 10, 2026
eb6a847
docs: add R&D disclaimer and mission hardening
odudex Aug 10, 2026
649ea07
fix(UI): add "estimated" term to entropy labels
odudex Aug 10, 2026
a499bba
fix(bip137): add checks for recid on sign message
qlrd Jun 24, 2026
9b02f88
test(bip137): add test vectors for bip137 fix
qlrd Jun 24, 2026
1ea74b2
docs: add BIP137 info
qlrd Jun 24, 2026
d7ddddb
feat: add BIP322 simple support
qlrd Jun 24, 2026
e9f37d9
test: added test vectors for BIP322
qlrd Jun 24, 2026
f2ab40c
docs: added info about BIP322
qlrd Jun 24, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 0 additions & 6 deletions .gitmodules
Original file line number Diff line number Diff line change
@@ -1,12 +1,6 @@
[submodule "embit"]
path = vendor/embit
url = ../../diybitcoinhardware/embit
[submodule "urtypes"]
path = vendor/urtypes
url = ../../selfcustody/urtypes
[submodule "foundation-ur-py"]
path = vendor/foundation-ur-py
url = ../../selfcustody/foundation-ur-py
[submodule "firmware/Kboot"]
path = firmware/Kboot
url = ../../selfcustody/Kboot
Expand Down
19 changes: 15 additions & 4 deletions .pylintrc
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@
# A comma-separated list of package or module names from where C extensions may
# be loaded. Extensions are loading into the active Python interpreter and may
# run arbitrary code.
extension-pkg-whitelist=
# uUR is the native BC-UR module: pylint has to import it to see UR, URDecoder,
# UREncoder and Types, which it cannot deduce from a compiled extension.
extension-pkg-whitelist=uUR

# Specify a score threshold to be exceeded before program exits with error.
fail-under=10.0
Expand All @@ -14,9 +16,7 @@ ignore=CVS,
.vagrant,
build,
embit,
foundation-ur-py,
MaixPy,
urtypes,
translations.py

# Add files or directories matching the regex patterns to the blacklist. The
Expand Down Expand Up @@ -183,9 +183,20 @@ contextmanager-decorators=contextlib.contextmanager
# List of members which are set dynamically and missed by pylint inference
# system, and so shouldn't trigger E1101 when accessed. Python regular
# expressions are accepted.
# uUR.Types is a submodule the C extension builds at import time, so pylint
# infers it as a bare module and cannot enumerate its codecs. Listing them keeps
# the rest of uUR checked instead of silencing the whole module.
generated-members=sleep_ms,
ticks_ms,
print_exception
print_exception,
CRYPTO_PSBT_TYPE,
bip39_words_from_cbor,
bytes_from_cbor,
bytes_to_cbor,
output_from_cbor,
output_from_cbor_account,
psbt_from_cbor,
psbt_to_cbor

# Tells whether missing members accessed in mixin class should be ignored. A
# mixin class is detected if its name ends with "mixin" (case insensitive).
Expand Down
36 changes: 29 additions & 7 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,44 @@
# Changelog 26.05.0 - May 2025
# Changelog 26.08.0 - August 2026

### Security Fixes
- Camera entropy: fix a heap buffer overflow in the Shannon entropy module. Only the Maix Bit could trigger it, a device discontinued in 25.09.0 with no known users; every other device feeds the module a frame that fits. The module copied the whole frame into a fixed 320x240 RGB565 (153,600 byte) scratch buffer, so the Maix Bit's larger CIF frames (352x288 RGB565, 202,752 bytes) wrote 49,152 bytes past the end. The scratch copy has been removed entirely, the read length is now capped and rounded to whole pixels, and the CIF path is gone along with the Maix Bit
- PSBT: stricter checks on the calculation of fee shown on screen
- PSBT: warn before signing when the wallet coordinator did not send enough data to confirm those amounts

### Removed Maix Bit Code
All Maix Bit support has been removed from the source tree, including its firmware build project. Support for the device was discontinued in 25.09.0, which at the time kept the build parameters available; those are now gone too. The OV5642 sensor handling, used only by that device, was removed along with it.

### Stackbit 1248 Vertical Layout
Added vertical layout option for Stackbit 1248 backup display, allowing users to choose between Standard (horizontal) and Vertical (transposed) grid orientations.

### Migrate UR encoding to uUR MicroPython C module
Switch from the pure-Python urtypes and foundation-ur-py packages to the new uUR C module, allowing faster UR QR codes decoding with a smaller RAM footprint.
### Migrate UR encoding to uUR C module
Switch from the pure-Python urtypes and foundation-ur-py packages to the new uUR C module, allowing faster UR QR codes decoding with a smaller RAM footprint. Tests and the simulator now build the same module for CPython instead of shimming the pure-Python packages, so host and device run identical UR code.


### Other Bug Fixes and Improvements
- Remove the unused `os.urandom()` from the MaixPy firmware. It was never called by Krux and played no part in generating keys or mnemonics, which draw entropy from the camera or dice. It was backed by a deterministic PRNG, so it has been removed to keep it from being mistaken for a secure source later
- Fix display of negative amounts
- Improve scan TinySeed and other binary visibility by drawing punches only
- Added `flash_success` method to standardize green success flashes across confirmation screens
- Update Embit to latest - 3ae0ef2
- Update Embit to latest - fff7ffa
- Replace custom quirc (library to decode QR codes from images) with k_quirc
- Fix default theme contrast failures for Light, CypherPink, network
indicators, and Amigo info panels
- Simplify generated-mnemonic confirmation with `Continue` and grouped
`Wallet Options`

# Changelog 26.04.0 - April 2025
- Stored mnemonics: a corrupt `seeds.json` is now reported and kept intact
instead of being overwritten when storing a new mnemonic
- Reject Base58 addresses whose version byte matches no network, previously
accepted as valid when verifying an address
- Settings: malformed `settings.json` content is handled without errors, and
reading a setting no longer writes back to storage
- Hide the QR code title in line and region view modes, where it overlapped
the part index
- Check for recids in BIP-137 message signing
- Add BIP-322 simple message signing for P2WPKH and P2TR single-sig
wallets, with BIP-137 fallback for P2PKH and P2SH-P2WPKH

# Changelog 26.04.0 - April 2026

### Security Fixes
- Reject PSBT inputs with non-standard sighash types before signing
Expand All @@ -31,7 +53,7 @@ Switch from the pure-Python urtypes and foundation-ur-py packages to the new uUR
- File manager: filter "."/".." and entries containing path separators from SD listings, blocking directory traversal via crafted FAT entries
- KEF decryption: in-session exponential backoff (1s, 2s, 4s … capped at 30s) on failed attempts, slowing interactive brute forcing without persisting lockout state to flash

# Changelog 26.03.0 - March 2025
# Changelog 26.03.0 - March 2026

### New Device Support: Embed Fire
This device shares similarities with the WonderMV but stands out with its larger 2.4" touchscreen.
Expand Down
3 changes: 1 addition & 2 deletions LICENSE.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,7 @@ All the source code in this repository is either MIT or Apache v2.0 licensed. Mo
The source code for the `MaixPy` firmware (which has been modified by the repository owner) is under the Apache v2.0 license. The source code within it related to `MicroPython` and `OpenMV` is released separately under the MIT license.

The source code for the `embit` library is under the MIT license.
The source code for the `urtypes` library is under the MIT license.
The source code for the `foundation-ur-py` library is under the BSD-2-Clause Plus Patent license.
The source code for the `cUR` library, which provides the `uUR` UR encoder/decoder module, is under the BSD-2-Clause Plus Patent license.
The source code for the `Adafruit Thermal Printer` library is under the MIT license.
The source code for the `Kboot` bootloader is under the Apache v2.0 license.

Expand Down
8 changes: 6 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,14 @@
<img src="docs/img/maixpy_cube/logo-400.en.png" alt="maixpy cube" style="width: 10%;">
</p>

Krux is an open-source firmware facilitating the creation of Bitcoin signing devices from readily available components, such as Kendryte K210 devices. It transforms these devices into airgapped tools capable of handling transactions for both single and multisignature wallets, supporting offline signing via QR code or SD card, thus empowering users to securely self-custody their Bitcoin.
Krux is an open-source firmware facilitating the creation of Bitcoin signing devices from readily available components, such as Kendryte K210 devices. It transforms these devices into airgapped tools capable of handling transactions for both single and multisignature wallets, supporting offline signing via QR code or SD card.

---
## Disclaimer
**WARNING**: *This software has not yet been formally audited by a third party. Use at your own risk!*

Krux is a research and development project, made by nerds building tools for their own interests, open to the world. Innovative features may have undiscovered flaws that endanger funds.

---

# Getting Started
Expand Down Expand Up @@ -66,11 +68,13 @@ To build and flash the firmware:
The first time, the build can take around an hour or so to complete. Subsequent builds should take only a few minutes. If all goes well, you should see a new `build` folder containing `firmware.bin` and `kboot.kfpkg` files when the build completes.

## Install Krux and dev tools
Krux uses [uv](https://docs.astral.sh/uv/) for Python packaging and environment management. Install uv by following its [installation guide](https://docs.astral.sh/uv/getting-started/installation/), then sync the project to install runtime deps ([embit](https://github.com/diybitcoinhardware/embit), [ur](https://github.com/selfcustody/foundation-ur-py), [urtypes](https://github.com/selfcustody/urtypes)) along with the `dev` group ([pytest](https://docs.pytest.org), [pylint](https://pypi.org/project/pylint/), [black](https://github.com/psf/black) and i18n helpers):
Krux uses [uv](https://docs.astral.sh/uv/) for Python packaging and environment management. Install uv by following its [installation guide](https://docs.astral.sh/uv/getting-started/installation/), then sync the project to install runtime deps ([embit](https://github.com/diybitcoinhardware/embit) and [uUR](https://github.com/selfcustody/cUR), the native UR module compiled from the same sources the devices run) along with the `dev` group ([pytest](https://docs.pytest.org), [pylint](https://pypi.org/project/pylint/), [black](https://github.com/psf/black) and i18n helpers):
```bash
uv sync
```

> **`uUR` is a C extension** It is built from the `bc-ur` submodule nested under `firmware/MaixPy`, so clone with `--recursive` (or run `git submodule update --init --recursive`) and make sure a C compiler and the Python development headers are installed (`python3-dev` on Debian/Ubuntu). After changing the submodule, rebuild it with `uv sync --reinstall-package uUR`.

`uv sync` creates a `.venv` in the project root, resolves `uv.lock` if needed, and installs everything — this is the day-to-day command. When dependencies in `pyproject.toml` change but you only want to refresh `uv.lock` without touching the venv, run `uv lock` instead; `uv sync` will then pick the new pins on its next run.

> **CI uses `uv sync --frozen`** The workflows refuse to silently re-resolve when `uv.lock` drifts (we value a lot reproducible builds). Whenever you edit `pyproject.toml` (add, remove, or bump a dependency), run `uv lock` (or `uv sync`) and commit `uv.lock` (in same change). Otherwise CI will fail.
Expand Down
11 changes: 7 additions & 4 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,14 @@
# Security policy

Please report any vulnerability or any bug that could potentially affect the
security of users' funds by mail to
[`odudex@proton.me`](mailto:odudex@proton.me).
security of users' funds by mail to both of these addresses:

You may use the [PGP public](https://github.com/odudex.gpg) key to encrypt your
mail.
- [`jean.dominique.lecomte.delisle@proton.me`](mailto:jean.dominique.lecomte.delisle@proton.me)
- [`odudex@proton.me`](mailto:odudex@proton.me)

You may use our PGP public keys to encrypt your mail:
[Jean Do](https://github.com/jdlcdl.gpg),
[odudex](https://github.com/odudex.gpg).

In the subject type `[Krux firmware] Security Report: <short description>`
and in the body a long description describing the issue. We aim to respond
Expand Down
2 changes: 1 addition & 1 deletion docs/faq.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Krux does not include hardware secure elements. The security of stored data reli
## What is the test (beta) version?
The test (beta) version includes the latest and most experimental features, which we occasionally share on our social media. The firmware can be found exclusively in the [test (beta) repository](https://github.com/odudex/krux_binaries). Use and flash the beta firmware if you are curious about new features or want to participate in the development process by hunting bugs, providing feedback, and sharing ideas in our Telegram groups or other social media platforms.

Just remember that for regular use, use the official versions, which are signed, thoroughly tested, and well documented.
Just remember that for regular use, use the official versions, which are the signed and documented ones.

## What is Krux Mobile Android app?

Expand Down
8 changes: 7 additions & 1 deletion docs/getting-started/index.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,10 @@ These wallet coordinators are currently **compatible with Krux**:

- [Electrum Bitcoin Wallet](https://electrum.org/) (desktop / mobile - error 'cannot sign')

<div style="clear: both"></div>
<div style="clear: both"></div>

## Disclaimer

Krux is a research and development project, made by nerds building tools for their own interests, open to the world. Innovative features may have undiscovered flaws that endanger funds.

**Use it at your own risk.**
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
8 changes: 5 additions & 3 deletions docs/index.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,12 @@ hide:
<img src="img/maixpy_m5stickv/logo-250.png" style="width: 6%; margin: 0 !important;">
<img src="img/maixpy_cube/backup-seed-qr-400.png" style="width: 10%; margin: 0 !important;">

Krux is an open-source firmware that transforms off-the-shelf Kendryte K210 devices, such as the Maix Amigo, M5StickV and [more](parts.md), into versatile bitcoin transaction signers. Beyond its core functionality, Krux is a flexible platform that can adapt to devices with different form factors, providing a suite of tools to assist with the creation and recovery of mnemonic backups, some of which include encryption options for enhanced security.
Krux is open-source firmware that runs on off-the-shelf Kendryte K210 devices, such as the Maix Amigo, M5StickV and [more](parts.md), turning them into bitcoin transaction signers. It adapts to devices with different form factors and includes tools to create and recover mnemonic backups, some of them with encryption options.

Devices like the Maix Amigo, Yahboom, WonderMV, TZT or Embed Fire come ready to use, with large touchscreens that make it easy and user-friendly to operate. These devices are ideal for those looking for a plug-and-play solution. On the other hand, Krux also supports development board kits, which are perfect for DIY enthusiasts who enjoy customizing and building their own hardware setups.
Devices like the Maix Amigo, Yahboom, WonderMV, TZT or Embed Fire come assembled and have touchscreens. Krux also runs on development board kits, which require assembly and, in some cases, soldering.

Interacting seamlessly with leading coordinator wallets through QR codes, SD cards, and even thermal printers, the user-friendly firmware offers unique features to support transactions and mnemonic backups in an offline environment.
It interacts with wallet coordinators through QR codes, SD cards and thermal printers, keeping transactions and mnemonic backups in an offline environment.

Krux is a research and development project. Read the [disclaimer](getting-started/index.md#disclaimer) before using it.

To learn more about Krux, check out [Getting Started](getting-started/index.md).
2 changes: 1 addition & 1 deletion docs/parts.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ Supported by Krux since September 2024, this touchscreen device features a metal
### TZT
<img src="../img/maixpy_tzt/logo-314.png" align="right" style="width: 15%;">

Supported by Krux since October 2025, this touchscreen device comes in a premium milled aluminum housing and features five buttons. Available through the following distributors:
Supported by Krux since October 2025, this touchscreen device comes in a milled aluminum housing and features five buttons. Available through the following distributors:

- [AliExpress](https://www.aliexpress.com/w/wholesale-canmv-k210-ai-vision.html)

Expand Down
2 changes: 1 addition & 1 deletion firmware/MaixPy
Submodule MaixPy updated 25 files
+1 −1 components/micropython/port/src/bc-ur
+16 −10 components/micropython/port/src/shannon/shannon.c
+4 −13 components/micropython/port/src/standard_lib/uos/moduos.c
+6 −4 components/micropython/port/src/standard_lib/uos/rng.c
+16 −16 projects/maixpy_amigo/compile/overrides/components/micropython/port/src/omv/img/include/font_device.h
+0 −1 projects/maixpy_bit/CMakeLists.txt
+0 −43 projects/maixpy_bit/builtin_py/board.py
+0 −1 projects/maixpy_bit/builtin_py/fpioa_manager.py
+0 −114 projects/maixpy_bit/compile/compile_flags.cmake
+0 −262 projects/maixpy_bit/compile/kendryte.ld
+0 −3,481 projects/maixpy_bit/compile/overrides/components/micropython/port/src/omv/img/include/font_device.h
+0 −11 projects/maixpy_bit/compile/priority.conf
+0 −1 projects/maixpy_bit/config_defaults.mk
+0 −1 projects/maixpy_bit/main/CMakeLists.txt
+0 −1 projects/maixpy_bit/main/src/main.cpp
+0 −32 projects/maixpy_bit/project.py
+12 −12 projects/maixpy_cube/compile/overrides/components/micropython/port/src/omv/img/include/font_device.h
+12 −12 projects/maixpy_dock/compile/overrides/components/micropython/port/src/omv/img/include/font_device.h
+12 −12 projects/maixpy_embed_fire/compile/overrides/components/micropython/port/src/omv/img/include/font_device.h
+12 −12 projects/maixpy_m5stickv/compile/overrides/components/micropython/port/src/omv/img/include/font_device.h
+12 −12 projects/maixpy_tzt/compile/overrides/components/micropython/port/src/omv/img/include/font_device.h
+12 −12 projects/maixpy_wonder_k/compile/overrides/components/micropython/port/src/omv/img/include/font_device.h
+12 −12 projects/maixpy_wonder_mv/compile/overrides/components/micropython/port/src/omv/img/include/font_device.h
+12 −12 projects/maixpy_yahboom/compile/overrides/components/micropython/port/src/omv/img/include/font_device.h
+12 −12 projects/maixpy_yahboom_devkit/compile/overrides/components/micropython/port/src/omv/img/include/font_device.h
2 changes: 1 addition & 1 deletion firmware/font/bdftokff.py
Original file line number Diff line number Diff line change
Expand Up @@ -50,12 +50,12 @@

SMALL_FONT_DEVICES_TO_COPY = ["cube"]
MID_FONT_DEVICES_TO_COPY = [
"bit",
"yahboom",
"wonder_mv",
"tzt",
"wonder_k",
"yahboom_devkit",
"embed_fire",
]
BIG_FONT_DEVICES_TO_COPY = []

Expand Down
Loading
Loading