Coldcard 固件的结构以及为什么开发者应该在 PC 上运行其模拟器

硬件加密钱包的源代码会受到特别严格的审查。随机数生成器的一个小失误或代码中的一个 bug 都可能造成数百万美元的损失。看一下 Coldcard 代码库中的 README 头部：作者们公开警告了一个影响 2021 年至 2026 年发布版本的严重熵漏洞。开发者们诚实地建议更新固件并重新生成密钥。

这种透明度得益于开放的架构。Coldcard 固件对所有人开放，你可以在自己的笔记本电脑上逐字节地构建其二进制文件。

代码库内部结构

该项目整合了多代钱包的软件：Mk3、Mk4、Mk5 系列，以及配备完整键盘的旗舰 Q1。主要技术栈包括用于高层逻辑的 MicroPython 和用于 STM32 芯片底层操作的 C 语言。

代码以相当逻辑的方式分布在各个目录中：

• shared 存储模拟器和设备的共享 Python 逻辑。
• stm32 包含固件、引导加载程序和用于构建最终微控制器二进制文件的 makefile。
• unix 包含 macOS 和 Linux 的模拟器源代码。
• hardware 包含原理图和组件规格。

在一个地方同时找到软件、模拟器和硬件原理图是很罕见的。对于对 Python 嵌入式开发感兴趣的人来说，这是极好的学习材料。

有趣的技术方案

通过 Docker 实现可重现构建

信任安全硬件的主要标准之一是确信编译后的文件与 GitHub 上的源代码一致。Coldcard 团队将这个过程自动化了。构建通过 Docker 运行，只需一条命令：

git clone https://github.com/Coldcard/firmware.git
cd firmware
git checkout 2026-03-05T2052-v5.5.0
cd stm32
make -f MK4-Makefile repro

脚本在隔离环境中编译代码，并将生成的文件与官方发布版本进行比较。如果文件逐字节匹配，则过程成功。

无需物理硬件的全功能模拟器

你不需要花几百美元买一个设备来学习代码。unix 文件夹包含一个基于 SDL2 和 MicroPython 的模拟器。它重新创建了屏幕、按钮和虚拟 SD 卡文件系统。

在 Linux 或 macOS 上运行模拟器只需几个步骤：

git clone --recursive https://github.com/Coldcard/firmware.git
cd firmware
python3 -m venv ENV
source ENV/bin/activate
pip install -r requirements.txt
cd unix
make setup && make ngu-setup && make
./simulator.py

启动后，屏幕上会出现一个钱包界面窗口。你可以使用键盘或鼠标与其交互，测试自己的脚本，并验证 PSBT（部分签名的比特币交易）处理。

两个分支，不同用途

团队在 Git 中维护两个主要分支：

• master 包含当前 Mk4、Mk5 和 Q1 设备的已测试代码。
• edge 作为实验的测试场。Taproot 支持或 Miniscript 等功能在出现在主要发布版本之前会先在这里。edge 中的代码质量要求较低，因此变更进展更快。

谁会发现这个代码库有用

这个项目的意义远不止比特币爱好者。嵌入式系统开发者将从 MicroPython 与 STM32 微控制器上 C 语言的结合经验中受益。安全专家将在这里找到一个清晰的可重现构建实现示例。

运行本地模拟器可以帮助你了解冷钱包设备上的交易签名是如何工作的，而无需额外花费。