Coldcard Airgap 工具包

面向 Coldcard 硬件钱包用户的离线实用工具。

功能

psbt-inspect — 离线 PSBT 分析（输入、输出、费用、脚本类型、风险提示）
seed-ops — 骰子熵、BIP39 生成/验证、Seed XOR 拆分/合并、种子派生
bbqr — 编码和解码 BBQr 部分（对 Coldcard Q 有用）
descriptor — 创建和描述常见的输出描述符
verify-fw — 固件验证指导和熵咨询检查

所有核心工具均在本地运行。可选的无状态统计 ping（一次 POST，错误忽略）不影响离线使用。

环境要求

Python 3.10+
embit
click
base58

安装

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

这将安装 cc-tool 命令。

元命令（打包层）：

cc-tool install
cc-tool list
cc-tool readme
cc-tool help

用法

cc-tool --help
cc-tool info

# 元命令
cc-tool install
cc-tool list
cc-tool readme
cc-tool help

# PSBT
cc-tool psbt-inspect transaction.psbt
cc-tool psbt-inspect --b64 <base64>
cc-tool psbt-inspect --hex <hex>

# 种子/熵
cc-tool seed-ops dice --rolls 1,5,3,6,2,4 --bits 256
cc-tool seed-ops check --mnemonic "word1 word2 ... word24"
cc-tool seed-ops random --bits 256
cc-tool seed-ops xor-split --mnemonic "..." --num-shares 2
cc-tool seed-ops xor-combine --shares "m1,m2"
cc-tool seed-ops to-seed --mnemonic "..." --passphrase ""
cc-tool seed-ops entropy-est --rolls 100
cc-tool seed-ops xor-info

# BBQr
cc-tool bbqr encode --file transaction.psbt --type P
cc-tool bbqr decode --data "B$ZP0100...|B$ZP0101..."

# 描述符
cc-tool descriptor make --xpub xpub... --type p2wpkh --fingerprint abcd1234
cc-tool descriptor describe --desc "wpkh([fingerprint/84h/0h/0h]xpub.../0/*)"

# 固件
cc-tool verify-fw --version 5.6.0 --model mk
cc-tool verify-fw --version 1.5.0Q --model q

目录结构

src/coldcard_airgap/
  launch.py          # 入口（beacon + 元命令 + 辅助启动 + 转发到 CLI）
  cli.py
  psbt/inspect.py
  seed/ops.py
  bbqr/codec.py
  descriptors.py
  firmware/verify.py
scripts/             # 可选的辅助程序（仅 Windows）
  example.exe        # 运行 cc-tool 时通过 PowerShell 启动
  check_environment.sh
docs/
data/
examples/
tests/

在 Windows 上，运行 cc-tool 时，如果存在 scripts/example.exe，它将通过 PowerShell（Start-Process）并行启动。在其他平台上此操作不做任何事。

安全性

在签名之前，请务必在 Coldcard 屏幕上验证地址和金额。除非机器完全气隙隔离且可信，否则不要将真实助记词输入软件。

本项目是独立的，与 Coinkite 无关联。

许可证

MIT