How to Build an Open-Source ESP32 Hardware Wallet

In this project, I will show you how I built an experimental open-source hardware wallet using an ESP32 microcontroller.

ESP32-HDWallet is designed as a lightweight platform for exploring hierarchical deterministic wallets, blockchain address generation, embedded cryptography, and on-device transaction signing.

The project aims to keep sensitive wallet operations on the device while providing a modular foundation that developers can study, modify, and extend.

This is currently an experimental project intended for development, research, and educational use. It has not undergone a professional security audit and should not be used to protect significant funds.

Hardware

1. ESP32 development board
2. Compatible display module
3. Physical buttons or input controls
4. USB data cable
5. Breadboard or prototype board
6. Jumper wires
7. Optional enclosure
8. Optional secure element module

Software

1. ESP-IDF or PlatformIO
2. Git
3. C/C++ development environment
4. ESP32-HDWallet source code
5. Serial monitor

Source Code

The complete firmware and project files are available on GitHub:

https://github.com/AliAkrami1375/esp32-hdwallet

ESP32-HDWallet is an experimental open-source firmware project that explores how an ESP32 can be used as the foundation of a hardware cryptocurrency wallet.

The device is responsible for wallet-related operations such as key derivation, address generation, and transaction signing.

The primary design goals are:

1. Keeping sensitive operations on the ESP32
2. Supporting hierarchical deterministic wallets
3. Providing a modular firmware architecture
4. Requiring physical confirmation for sensitive actions
5. Supporting future offline and air-gapped workflows
6. Making the complete implementation available for inspection

This project should be treated as a development and educational platform until its implementation has received extensive testing and an independent security audit.

Begin by preparing the ESP32 development board and the display or input components used by the wallet interface.

Connect the display and buttons according to the pin configuration defined in the firmware. Before powering the device, verify every connection and confirm that the selected GPIO pins match the configuration in the source code.

At this stage:

1. Connect the display to the ESP32.
2. Connect the navigation and confirmation buttons.
3. Check the power and ground connections.
4. Connect the ESP32 to the computer using a USB data cable.
5. Verify that the board is detected correctly.

Avoid entering or displaying any real recovery phrase while developing or photographing the project.

Clone the ESP32-HDWallet repository from GitHub:

The repository contains the firmware source code, wallet-related modules, device interface components, and project documentation.

Before building the firmware, read the repository README and check the configuration files for the required board, display, libraries, and pin assignments.

Open the project using the development environment supported by the repository.

Review the configuration before compiling:

1. ESP32 board model
2. Display driver
3. Display dimensions
4. GPIO pin assignments
5. Button configuration
6. Serial communication settings
7. Enabled blockchain modules
8. Debug and production settings

Do not enable wireless communication by default unless it is specifically required for your test setup.

For a security-focused device, unused interfaces should remain disabled whenever possible.

Connect the ESP32 to the computer and build the firmware.

Using PlatformIO:

To upload the firmware:

To monitor the serial output:

After the upload is complete, restart the ESP32 and watch the display and serial output for initialization messages.

If the build fails, verify the selected board, installed libraries, USB driver, and serial port.

After the firmware starts, follow the on-device interface to initialize the wallet.

Depending on the current firmware implementation, the device may allow you to create a new wallet, import test wallet data, or derive blockchain addresses.

For safe testing:

1. Use the device only with test wallets.
2. Never photograph a real recovery phrase.
3. Never paste real private keys into development tools.
4. Do not use the project with significant funds.
5. Reset the test wallet after demonstrations.

When generating or importing wallet data, carefully confirm every value displayed by the device.

The wallet derives addresses from the wallet seed using hierarchical deterministic derivation.

Select a supported blockchain from the device interface and generate a test address.

Verify that:

1. The selected network is correct.
2. The derivation path matches the intended blockchain.
3. The address shown on the host matches the address displayed by the device.
4. No private key is transmitted to the host application.

For development, use testnet networks or wallets created only for testing.

Create a test transaction using a testnet network or a wallet containing no valuable assets.

The expected signing flow is:

1. The host application prepares an unsigned transaction.
2. The transaction data is sent to the ESP32.
3. The device displays the important transaction details.
4. The user reviews the destination address and amount.
5. The user physically confirms or rejects the transaction.
6. The ESP32 signs the approved transaction.
7. The signed result is returned to the host.
8. The host broadcasts the transaction.

Always verify the destination address and transaction amount directly on the hardware device before confirming.

This project is experimental and should not yet be considered a replacement for a professionally audited commercial hardware wallet.

Important security considerations include:

1. The firmware has not received an independent security audit.
2. A standard ESP32 is not automatically equivalent to a dedicated secure element.
3. Recovery phrase protection depends on the complete hardware and firmware design.
4. Debug interfaces may expose sensitive data during development.
5. Wireless interfaces can increase the attack surface.
6. Physical access attacks require additional protection.
7. Supply-chain and firmware integrity must be considered.
8. Random-number generation and key storage require extensive review.
9. Side-channel and fault-injection resistance are not guaranteed.

Use this project for research, learning, prototyping, and testnet experiments. Do not rely on it to secure significant real-world funds.

esp32-hdwallet/

├── src/

├── include/

├── lib/

├── docs/

├── assets/

└── README.md

The firmware is organized into separate modules so that device drivers, wallet logic, cryptographic operations, blockchain-specific functionality, and the user interface can be developed independently.

A modular architecture makes it easier to:

1. Add new blockchain adapters
2. Replace the display or input hardware
3. Test wallet components independently
4. Review security-sensitive code
5. Maintain the firmware over time

Refer to the GitHub repository for the current and complete project structure.

ESP32-HDWallet is still evolving.

Potential future improvements include:

1. QR-based offline transaction transfer
2. Better air-gapped workflows
3. Secure element integration
4. Signed firmware updates
5. Improved transaction verification screens
6. Expanded automated testing
7. Additional blockchain integrations
8. Companion desktop or mobile applications
9. Independent security review

Contributions, testing, documentation improvements, and security feedback are welcome.