Bowser Wallet can be used over Web Serial with the LNbits WatchOnly extension or its standalone web client. It can also operate air-gapped using a microSD card and the optional keypad.

Wallet entropy can be generated by the ESP32 hardware random-number generator or supplied by entering 100 rolls of a six-sided die.

All of the software and hardware designs are free, libre and open source (FLOSS).

Using generic, widely available hardware is a huge gain against the supply chain attack from purpose built devices, but it does not eliminate supply-chain risk entirely. Because the device has no secure element, it should be stored securely when not in use and treated as physically sensitive.

WebSerial mode is intended for smaller day-to-day amounts. For more sensitive use, the air-gapped microSD and keypad mode with dice-generated entropy is recommended. For significant funds, consider a mature, independently audited hardware wallet such as Trezor.

Maintainers are not responsible for any loss of funds.

What you need

• A LILYGO TTGO T-Display ESP32
• A USB data cable for flashing and connected operation
• A computer with one of the following:
  • Chrome, Chromium, or Brave for the web installer and Web Serial
  • Arduino CLI or Arduino IDE for compiling and flashing manually
• Optional: the LILYGO T-Display Keyboard Module and a microSD card for air-gapped commands and dice-roll wallet creation
• Optional: the LNbits OnchainWallet extension for connected wallet operation
• Optional: a case, or a complete kit from the LNbits shop

For use with

The LNbits WatchOnly Extension

The standalone Bowser Wallet webapp

Installation

Web installer (easy)

Use the LNbits Hardware Wallet web installer.

Build from source with Arduino CLI (tinfoil)

Install Arduino CLI using the normal method for your operating system.

Install pyserial

# Install pyserial
sudo pip3 install pyserial

Then clone and build the firmware:

git clone https://github.com/lnbits/hardware-wallet
cd hardware-wallet

# Install the exact ESP32 core version used by this project.
arduino-cli config add board_manager.additional_urls \
  https://espressif.github.io/arduino-esp32/package_esp32_index.json
arduino-cli core update-index
arduino-cli core install esp32:esp32@2.0.17
arduino-cli core list

# Connect the device and identify its serial port.
arduino-cli board list

# Set this to the port shown above. Common Linux ports are ttyACM0 and ttyUSB0.
HWW_PORT=/dev/ttyACM0

# Compile and upload for the LILYGO T-Display.
arduino-cli compile --verbose --clean --upload \
  --fqbn esp32:esp32:ttgo-lora32 \
  --port "$HWW_PORT" \
  --libraries "$PWD/libraries" \
  "$PWD/wallet"

Device commands

The LNbits OnchainWallet extension or another client communicates with the device using commands in this form:

/command-name {param1} {param2} ... {paramN}

• Parameter order is significant.
• Use a minus (-) when an optional positional value is omitted.
• Example: /password my-password-1

The device can respond with a string in the same form:

/command-name {response1} {response2} ... {responseN}

Each command is documented in its implementation file:

• /ping — 720_ping.ino
• /pair — 712_cmd_pair.ino
• /check-pairing — 721_check_pairing.ino
• /password — 713_cmd_password_check.ino
• /password-clear — 714_cmd_password_clear.ino
• /restore — 717_cmd_restore.ino
• /create — 723_cmd_create.ino
• /wipe — 716_cmd_wipe_hww.ino
• /psbt — 718_cmd_sign_psbt.ino
• /seed — 719_show_seed.ino
• /xpub — 715_cmd_xpub.ino
• /address — 722_show_address.ino
• /help — 711_cmd_help.ino

Run from a microSD card (air-gapped)

1. Mount the microSD card on a computer.
2. Create commands.in.txt in the card's root directory.
3. Add commands to the file. Start with the commented complete command template, consult the output reference, or see the worked examples.
4. Safely eject the card and insert it into the hardware wallet.
5. Reboot the device. It will detect and execute commands.in.txt.
6. Wait for command execution to finish, then return the card to the computer.
7. Read the generated files:
   • commands.out.txt contains command results such as signed PSBTs.
   • commands.log.txt contains diagnostic logs.

Create a wallet from dice rolls

The air-gapped T-Display Keyboard Module can create a 24-word BIP39 wallet using a physical six-sided die:

1. Put /create your-password in commands.in.txt. The password must contain at least 8 characters and cannot contain spaces.
2. Insert the microSD card and reboot the device.
3. Roll a fair six-sided die 100 times, entering each result with keypad keys 1 through 6. Press * to remove the most recent entry.
4. At 100/100, press # to create the wallet.
5. Write down each seed word shown on the device. Press # for the next word and * for the previous word. Press # on word 24 to finish.

The keypad matrix uses columns GPIO 33, 32, and 25 and rows GPIO 21, 27, 26, and 22. The firmware hashes the exact 100 ASCII dice digits with SHA-256 and uses the resulting 256 bits directly as BIP39 entropy. This makes the process reproducible for recovery and provides more than 256 bits of input entropy when the die is fair.

Neither the dice sequence nor the seed words are written to the microSD card by /create; commands.out.txt only receives /create 1 on success. Protect or remove commands.in.txt, because it contains the wallet password. The wallet is persisted in the device's existing password-encrypted storage even if a previous /pair command disabled persistence for SD restores. The existing /seed command writes the seed to the microSD card and should not be used when the goal is to keep the seed exclusively on the device and paper backup.

Entropy lines (the important bit)

• uBitcoin obtains random words from the ESP32 hardware RNG through esp_random().
• Before using that RNG, the wallet checks its conditioned output for stuck values, stuck bit positions, repeated words, and gross bit imbalance in hardwareRngPassesHealthCheck().
• The wallet adds 32 bytes directly from the ESP32 hardware RNG through esp_fill_random().
• Dice wallet creation hashes the exact 100-character dice-roll buffer with SHA-256, then passes the resulting 32 bytes directly as BIP39 entropy to mnemonicFromEntropy().

Troubleshooting

• If the device does not appear as a serial port, install the CP210x USB-to-UART driver.
• If uploading stalls at Connecting..., hold the device's BOOT button while the connection starts, then release it.
• On Linux, ensure your user has permission to access the serial device.

Questions? Join the LNbits Telegram group or the MakerBits Telegram group.

This project uses the uBitcoin library.