No Description

Peter D. Gray 71c9417d75 Add 608C support 18 hours ago
cli 5393e924ba Bugfix: firmware sizes must align with flash erase unit (4k) 5 months ago
docs 89d7cca418 docs: update with multisig name limitations 3 weeks ago
external 0ea48acfd2 submodule: ckcc-protocol move to f924f6d35ca0a6804b9e25d476cb53ae2f8ae8d6 3 weeks ago
graphics 652836e40b updated animation 2 years ago
hardware a493971eb3 vital change 1 year ago
misc 9b2ef862cb Add middle-dots character to font, use arrows/dots in address explorer menu; tweaks. 9 months ago
releases 8e43f6f4fc bugfix: reads in final 3 byte of file could return incorrect data 23 hours ago
shared 71c9417d75 Add 608C support 18 hours ago
stm32 f991f4125e New release: 2023-12-21T1526-v5.2.2 2 months ago
testing 4880292eae always use SettingsObject class for master data 2 weeks ago
unix bceaaf92e0 Seed Vault 4 months ago
.gitignore 307df0c013 Main seed and ephemeral seed from Tapsigner backup + ephemeral seed from extended private key 1 year ago
.gitmodules 157673da8f correct MPY submodule branch 1 year ago ecfb2c026d Create 2 years ago
COPYING-CC b6b9191145 dev squashed 3 years ago
LICENSE 22607a760c Add clone-your-Coldcard feature 3 years ago 0e455fde27 Created docs/ to explain how repro builds are checked and verified. 9 months ago
macos-mpy.patch c6205bb184 add patch to fix build on macOS; update 1 year ago 0414787cd7 Prettify 2 years ago
requirements.txt 2ba9fca8e0 Add ckcc tool 5 years ago

Coldcard Wallet

Coldcard is an Affordable, Ultra-secure & Verifiable Hardware Wallet for Bitcoin. Get yours at

Follow @COLDCARDwallet on Twitter to keep up with the latest updates and security alerts.

coldcard logo

Mk4 coldcard picture front

Reproducible Builds

To have confidence this source code tree is the same as the binary on your device, you can rebuild it from source and get exactly the same bytes. This process has been automated using Docker. Steps are as follows:

  1. Install Docker and start it.
  2. Install make (GNUMake) if you don't already have it.
  3. Checkout the code, and start the process.

    git clone
    cd firmware/stm32
    make repro
  4. At the end of the process a clear confirmation message is shown, or the differences.

  5. Build products can be found firmware/stm32/built.

  6. If you do not trust the results of make repro refer to docs/ which breaks down the process.

Long-Lived Branches

We are now maintaining two branches: master and edge.

"Edge" will contain features that may not be ready for prime time, such as Taproot or Miniscript. Our standards for releasing new Edge versions are lower, so we can iterate faster and get these advancements out to other developers.

Check-out and Setup

NOTE This is the master branch and covers the latest hardware (Mk4). See branch v4-legacy for firmware which supports only Mk3/Mk2 and earlier.

Do a checkout, recursively to get all the submodules:

git clone --recursive

Already checked-out and getting git errors? Do this:

git fetch
git reset --hard origin/master

Alternatively, to get the latest release, you checkout a tagged branch:

git clone
cd firmware
git checkout $(git describe --match "20*" --abbrev=0)
git submodule update --init --recursive

Do not use a path with any spaces in it. The Makefiles do not handle that well, and we're not planning to fix it.

Keep in mind that python requirements may change between versions, so at the top level, do this command:

pip install -r requirements.txt


Python 3.5 or higher and Homebrew is required.

If working on an ARM-based MacOS system, you may want to create a new shell with arch -x86_64 bash before starting, or continuing to work on this source tree.

Setup and run the desktop simulator

You'll probably need to install at least these packages:

brew install sdl2 xterm swig
brew install --cask xquartz gcc-arm-embedded

Used to be these were needed as well:

brew tap PX4/px4
brew search px4/px4/gcc-arm-none-eabi

Then install the newest version, currently 83:

brew install px4/px4/gcc-arm-none-eabi-83

You may need to brew upgrade gcc-arm-embedded because we need 10.2 or higher.


brew install automake autogen virtualenv
virtualenv -p python3 ENV
source ENV/bin/activate (or source ENV/bin/activate.csh based on shell preference)
pip install -U pip
pip install -r requirements.txt
# apply micropython patch
pushd external/micropython
git apply ../../macos-mpy.patch
make -C external/micropython/mpy-cross
cd unix; make setup && make ngu-setup && make && ./

You may need to reboot to avoid a DISPLAY is not set error.

The next time you want to run the simulator, you can simply do

source ENV/bin/activate && cd unix && ./

Building the firmware

  • cd ../cli; pip install --editable .
  • cd ../stm32; make setup && make; make firmware-signed.dfu
  • The resulting file, firmware-signed.dfu can be loaded directly onto a Coldcard, using this command (already installed based on above)
  • ckcc upgrade firmware-signed.dfu

Which looks like this:

[ENV] [firmware/stm32 42] ckcc upgrade firmware-signed.dfu  
675328 bytes (start @ 293) to send from 'firmware-signed.dfu'
Uploading  [##########--------------------------]   29%  0d 00:01:04

Big Sur Issues

defaults write org.python.python ApplePersistenceIgnoreState NO will suppress a warning about Python[22580:10101559] ApplePersistenceIgnoreState: Existing state will not be touched. New state will be written to...



All steps you need to install and run the Coldcard simulator on Ubuntu 20.04:

# Install (system) requirements, tools and libraries
apt install build-essential git python3 python3-pip libudev-dev gcc-arm-none-eabi libffi-dev xterm swig libpcsclite-dev python-is-python3 autoconf libtool python3-venv

# Get sources, this takes a long time (because of external libraries), then open
git clone --recursive
cd firmware

# Apply address patch
git apply unix/linux_addr.patch 

# Create Python virtual environment and activate it
python3 -m venv ENV  # or virtualenv -p python3 ENV
source ENV/bin/activate

# Install dependencies
pip install -U pip setuptools
pip install -r requirements.txt #general requirements
pip install pysdl2-dll # Ubuntu needs this dependency

# Build the Coldcard simulator
cd unix
pushd ../external/micropython/mpy-cross/
make  # mpy-cross
make setup
make ngu-setup

# Run the simulator in the active virtualenv

# Later, if you want to run it (after a reboot). This assumes you extracted the git repo in ~ (home)
cd ~/firmware
source ENV/bin/activate
cd unix

Also make sure that you have your python3 symlinked to python.

Code Organization

Top-level dirs:


  • shared code between desktop test version and real-deal
  • expected to be largely in python, and higher-level
  • new code found only on the Mk4 will be listed in code exclusive to earlier hardware is in


  • unix (macOS) version for testing/rapid dev
  • this is a simulator for the product


  • test cases and associated data


  • embedded binaries (and building), for actual product hardware
  • final target is a binary file for loading onto hardware


  • code from other projects, ie. the dreaded submodules


  • images which ship as part of the final product (icons)


  • 32k of factory-set code that you cannot change (Mk3)
  • however, you can inspect what code is on your coldcard and compare to this.


  • 128k of factory-set code that you cannot change for Mk4
  • however, you can inspect what code is on your coldcard and compare to this.


  • schematic and bill of materials for the Coldcard


  • /MicroSD/* files on "simulated" microSD card

  • /VirtDisk/* simulated emulated virtual Disk files.

  • /settings/*.aes persistent settings for Simulator


Found a bug? Email: