# coldcard/firmware architecture

> Architecture diagram of the GitHub repository coldcard/firmware, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coldcard/firmware
- Repository: https://github.com/coldcard/firmware

## Overview

Coldcard is a Bitcoin hardware wallet whose firmware guides users through PIN login and wallet operations, authorizes sensitive actions such as transaction signing, and uses device storage and hardware security to protect secrets. The README describes shared high-level code running on both the desktop simulator and embedded hardware, with Mk and Q variants. Major capabilities are represented from the README and source index; unsampled implementation details and external-service wiring are not inferred.

Main entry points: [`shared/main.py`](https://github.com/coldcard/firmware/blob/master/shared/main.py) (Firmware startup), [`shared/auth.py`](https://github.com/coldcard/firmware/blob/master/shared/auth.py) (Action authorization), [`shared/pincodes.py`](https://github.com/coldcard/firmware/blob/master/shared/pincodes.py) (PIN login), [`shared/actions.py`](https://github.com/coldcard/firmware/blob/master/shared/actions.py) (Wallet actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Wallet application"]
  node_main["Firmware startup<br/>[main.py]"]
  node_actions["Wallet actions<br/>[actions.py]"]
  node_ux["Interaction flow<br/>[ux.py]"]
  node_lcd["Display UI<br/>[lcd_display.py]"]
  node_usb["USB interface<br/>[usb.py]"]
end

subgraph group_wallet["Wallet security"]
  node_auth["Action authorization<br/>[auth.py]"]
  node_pin["PIN login<br/>[pincodes.py]"]
  node_stash["Secret handling<br/>[stash.py]"]
  node_nvstore[("Encrypted settings<br/>[nvstore.py]")]
  node_seed["Seed management<br/>[seed.py]"]
  node_backup["Wallet backups<br/>[backups.py]"]
end

subgraph group_bitcoin["Bitcoin operations"]
  node_psbt["Transaction signing<br/>[psbt.py]"]
  node_chains["Bitcoin chains<br/>[chains.py]"]
  node_multisig["Multisig wallets<br/>[multisig.py]"]
end

subgraph group_device["Device platform"]
  node_bootstorage[("Secure flash<br/>[storage.c]")]
  node_callgate["Bootloader gateway<br/>[callgate.py]"]
  node_stm32["Embedded firmware<br/>[modckcc.c]"]
  node_version["Hardware detection<br/>[version.py]"]
end

subgraph group_sim["Simulator"]
  node_simulator["Desktop simulator<br/>[simulator.py]"]
  node_simckcc["Simulated hardware<br/>[ckcc.py]"]
end

node_user(("Wallet user"))

node_user -->|"starts device"| node_main
node_main -->|"starts interaction"| node_ux
node_main -->|"initializes display"| node_lcd
node_main -->|"loads PIN flow"| node_pin
node_main -->|"starts USB"| node_usb
node_ux -->|"dispatches actions"| node_actions
node_actions -->|"requests authorization"| node_auth
node_actions -->|"uses interaction"| node_ux
node_auth -->|"handles PSBT"| node_psbt
node_auth -->|"confirms import"| node_multisig
node_auth -->|"creates backup"| node_backup
node_auth -->|"selects chain"| node_chains
node_pin -->|"calls bootloader"| node_callgate
node_pin -->|"updates settings"| node_nvstore
node_pin -->|"loads secrets"| node_stash
node_stash -->|"derives wallet"| node_chains
node_callgate -.->|"accesses flash"| node_bootstorage
node_simulator -->|"uses simulator hardware"| node_simckcc
node_simulator -->|"runs shared firmware"| node_main
node_stm32 -->|"runs shared firmware"| node_main
node_main -->|"probes hardware"| node_version

click node_main "https://github.com/coldcard/firmware/blob/master/shared/main.py"
click node_actions "https://github.com/coldcard/firmware/blob/master/shared/actions.py"
click node_ux "https://github.com/coldcard/firmware/blob/master/shared/ux.py"
click node_lcd "https://github.com/coldcard/firmware/blob/master/shared/lcd_display.py"
click node_usb "https://github.com/coldcard/firmware/blob/master/shared/usb.py"
click node_auth "https://github.com/coldcard/firmware/blob/master/shared/auth.py"
click node_pin "https://github.com/coldcard/firmware/blob/master/shared/pincodes.py"
click node_stash "https://github.com/coldcard/firmware/blob/master/shared/stash.py"
click node_nvstore "https://github.com/coldcard/firmware/blob/master/shared/nvstore.py"
click node_bootstorage "https://github.com/coldcard/firmware/blob/master/stm32/mk4-bootloader/storage.c"
click node_callgate "https://github.com/coldcard/firmware/blob/master/shared/callgate.py"
click node_seed "https://github.com/coldcard/firmware/blob/master/shared/seed.py"
click node_psbt "https://github.com/coldcard/firmware/blob/master/shared/psbt.py"
click node_chains "https://github.com/coldcard/firmware/blob/master/shared/chains.py"
click node_multisig "https://github.com/coldcard/firmware/blob/master/shared/multisig.py"
click node_backup "https://github.com/coldcard/firmware/blob/master/shared/backups.py"
click node_simulator "https://github.com/coldcard/firmware/blob/master/unix/simulator.py"
click node_simckcc "https://github.com/coldcard/firmware/blob/master/unix/variant/ckcc.py"
click node_stm32 "https://github.com/coldcard/firmware/blob/master/stm32/COLDCARD_MK4/modckcc.c"
click node_version "https://github.com/coldcard/firmware/blob/master/shared/version.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_actions,node_ux,node_lcd,node_usb,node_user toneBlue
class node_auth,node_pin,node_stash,node_nvstore,node_seed,node_backup toneAmber
class node_psbt,node_chains,node_multisig toneMint
class node_bootstorage,node_callgate,node_stm32,node_version toneRose
class node_simulator,node_simckcc toneIndigo
```

## Components

### Wallet application

- [Firmware startup](https://github.com/coldcard/firmware/blob/master/shared/main.py): `shared/main.py`
- [Wallet actions](https://github.com/coldcard/firmware/blob/master/shared/actions.py): `shared/actions.py`
- [Interaction flow](https://github.com/coldcard/firmware/blob/master/shared/ux.py): `shared/ux.py`
- [Display UI](https://github.com/coldcard/firmware/blob/master/shared/lcd_display.py): `shared/lcd_display.py`
- [USB interface](https://github.com/coldcard/firmware/blob/master/shared/usb.py): `shared/usb.py`

### Wallet security

- [Action authorization](https://github.com/coldcard/firmware/blob/master/shared/auth.py): `shared/auth.py`
- [PIN login](https://github.com/coldcard/firmware/blob/master/shared/pincodes.py): `shared/pincodes.py`
- [Secret handling](https://github.com/coldcard/firmware/blob/master/shared/stash.py): `shared/stash.py`
- [Encrypted settings](https://github.com/coldcard/firmware/blob/master/shared/nvstore.py): `shared/nvstore.py`
- [Seed management](https://github.com/coldcard/firmware/blob/master/shared/seed.py): `shared/seed.py`
- [Wallet backups](https://github.com/coldcard/firmware/blob/master/shared/backups.py): `shared/backups.py`

### Bitcoin operations

- [Transaction signing](https://github.com/coldcard/firmware/blob/master/shared/psbt.py): `shared/psbt.py`
- [Bitcoin chains](https://github.com/coldcard/firmware/blob/master/shared/chains.py): `shared/chains.py`
- [Multisig wallets](https://github.com/coldcard/firmware/blob/master/shared/multisig.py): `shared/multisig.py`

### Device platform

- [Secure flash](https://github.com/coldcard/firmware/blob/master/stm32/mk4-bootloader/storage.c): `stm32/mk4-bootloader/storage.c`
- [Bootloader gateway](https://github.com/coldcard/firmware/blob/master/shared/callgate.py): `shared/callgate.py`
- [Embedded firmware](https://github.com/coldcard/firmware/blob/master/stm32/COLDCARD_MK4/modckcc.c): `stm32/COLDCARD_MK4/modckcc.c`
- [Hardware detection](https://github.com/coldcard/firmware/blob/master/shared/version.py): `shared/version.py`

### Simulator

- [Desktop simulator](https://github.com/coldcard/firmware/blob/master/unix/simulator.py): `unix/simulator.py`
- [Simulated hardware](https://github.com/coldcard/firmware/blob/master/unix/variant/ckcc.py): `unix/variant/ckcc.py`

### Other components

- **Wallet user**

## Connections

- Wallet user → Firmware startup: starts device (evidence: `README.md`)
- Firmware startup → Interaction flow: starts interaction (evidence: `shared/main.py`)
- Firmware startup → Display UI: initializes display (evidence: `shared/main.py`)
- Firmware startup → PIN login: loads PIN flow (evidence: `shared/main.py`)
- Firmware startup → USB interface: starts USB (evidence: `shared/main.py`)
- Interaction flow → Wallet actions: dispatches actions (evidence: `shared/ux.py`)
- Wallet actions → Action authorization: requests authorization (evidence: `shared/actions.py`)
- Wallet actions → Interaction flow: uses interaction (evidence: `shared/actions.py`)
- Action authorization → Transaction signing: handles PSBT (evidence: `shared/auth.py`)
- Action authorization → Multisig wallets: confirms import (evidence: `shared/auth.py`)
- Action authorization → Wallet backups: creates backup (evidence: `shared/auth.py`)
- Action authorization → Bitcoin chains: selects chain (evidence: `shared/auth.py`)
- PIN login → Bootloader gateway: calls bootloader (evidence: `shared/pincodes.py`)
- PIN login → Encrypted settings: updates settings (evidence: `shared/pincodes.py`)
- PIN login → Secret handling: loads secrets (evidence: `shared/pincodes.py`)
- Secret handling → Bitcoin chains: derives wallet (evidence: `shared/stash.py`)
- Bootloader gateway → Secure flash: accesses flash
- Desktop simulator → Simulated hardware: uses simulator hardware (evidence: `unix/simulator.py`)
- Desktop simulator → Firmware startup: runs shared firmware (evidence: `README.md`)
- Embedded firmware → Firmware startup: runs shared firmware (evidence: `README.md`)
- Firmware startup → Hardware detection: probes hardware (evidence: `shared/main.py`)
