revert SSSP bypass PIN login

For 'U'/'J' payloads data is a str; planning counted codepoints while
b32encode consumes UTF-8 bytes, so multi-byte text (e.g. paper-wallet QR
art) overflowed target_vers and tripped the assert in show_bbqr_codes.

.gitignore

@@ -24,3 +24,5 @@ __pycache__/
 
 .tags
 pp
+
+.idea/

.gitmodules

@@ -1,7 +1,7 @@
 [submodule "external/micropython"]
 	path = external/micropython
 	url = https://github.com/Coldcard/micropython.git
-	branch = master
+	branch = mk4-base
 [submodule "external/ckcc-protocol"]
 	path = external/ckcc-protocol
 	url = https://github.com/Coldcard/ckcc-protocol.git
@@ -14,3 +14,9 @@
 [submodule "stm32/mk4-bootloader/hal"]
 	path = stm32/mk4-bootloader/hal
 	url = https://github.com/STMicroelectronics/STM32CubeL4.git
+[submodule "misc/gpu/external/stm32c0xx_hal_driver"]
+	path = misc/gpu/external/stm32c0xx_hal_driver
+	url = https://github.com/STMicroelectronics/stm32c0xx_hal_driver.git
+[submodule "misc/gpu/external/cmsis_device_c0"]
+	path = misc/gpu/external/cmsis_device_c0
+	url = https://github.com/STMicroelectronics/cmsis_device_c0.git

README.md

@@ -1,16 +1,20 @@
-# Coldcard Wallet
+# COLDCARD Hardware Wallet
 
-
-Coldcard is a Cheap, Ultra-secure & Opensource Hardware Wallet for Bitcoin.
-Get yours at [ColdcardWallet.com](http://coldcardwallet.com)
+Coldcard is an Affordable, Ultra-secure & Verifiable Hardware Wallet for Bitcoin.
+Get yours at [Coldcard.com](http://coldcard.com)
 
 [Follow @COLDCARDwallet on Twitter](https://twitter.com/coldcardwallet) to keep up
-with the latest updates and security alerts. 
+with the latest updates and security alerts.
 
-![coldcard logo](https://coldcardwallet.com/static/images/coldcard-logo-nav.png)
+![coldcard logo](https://coldcard.com/static/images/coldcard-logo-nav.png)
 
-![coldcard picture front](https://coldcardwallet.com/static/images/coldcard-front.png)
-![coldcard picture back](https://coldcardwallet.com/static/images/coldcard-back.png)
+![Mk5 coldcard picture front](https://coldcard.com/static/images/mk5-front.png)
+
+## Quick Links
+
+- [Latest firmware changes and updates](releases/ChangeLog.md)
+- [PGP signature file](releases/signatures.txt)
+- [Firmware binaries](https://coldcard.com/downloads)
 
 ## Reproducible Builds
 
@@ -18,45 +22,135 @@ To have confidence this source code tree is the same as the binary on your devic
 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.
+1. Install [Docker](https://www.docker.com) and start it.
 2. Install [make (GNUMake)](https://www.gnu.org/software/make/) if you don't already have it.
-3. Checkout the code, and start the process.
+3. Checkout a specific version of the code, and start the process.
 
+    ```shell
     git clone https://github.com/Coldcard/firmware.git
-    cd firmware/stm32
-    make repro
+    cd firmware
+    # DOWNLOAD https://coldcard.com/downloads
+    # get a copy of binary into ./releases/2026-03-05T2052-v5.5.0-mk-coldcard.dfu
+    git checkout 2026-03-05T2052-v5.5.0
+    cd stm32
+    make -f MK4-Makefile 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/notes-on-repro.md`
+   which breaks down the process.
+7. Process for Q firmware is the same, but change `MK4-Makefile` in last step to `Q1-Makefile`
+
+## 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.
+
+Q and Mk series share the same code base. Individual files that are added,
+or removed, can be see in differences between `shared/manifest_mk4.py`
+and `shared/manifest_q1.py`. Common files are in `shared/manifest.py`.
+Firmware built for Mk5, supports the Mk4 without any functional differences.
+
 
 ## Check-out and Setup
 
-Do a checkout, recursively to get all the submodules:
+**NOTE** This is the `master` branch and covers the latest hardware (Mk and Q).
+See branch `v4-legacy` for firmware which supports only Mk3/Mk2 and earlier.
 
-    git clone --recursive https://github.com/Coldcard/firmware.git
+Do a checkout, recursively, to get all the submodules:
+
+```shell
+git clone --recursive https://github.com/Coldcard/firmware.git
+```
 
 Already checked-out and getting git errors? Do this:
 
-    git fetch
-    git reset --hard origin/master
+```shell
+git fetch
+git reset --hard origin/master
+```
+
+Alternatively, to get the latest release, you checkout a tagged branch:
+
+```shell
+git clone https://github.com/Coldcard/firmware.git
+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.
+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:
+
+```shell
+pip install -r requirements.txt
+```
+
+### macOS
+
+[Python 3.5 or higher](https://www.python.org) and [Homebrew](https://brew.sh) 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:
+
+```shell
+brew install sdl2 xterm swig
+brew install --cask xquartz gcc-arm-embedded
+```
+
+Used to be these were needed as well:
+
+```shell
+brew tap PX4/px4
+brew search px4/px4/gcc-arm-none-eabi
+```
+
+Then install the newest version, currently 83:
+
+```shell
+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.
 
 Then:
 
-- `cd firmware`
-- `git submodule update --init` _(if needed?)_
-- `brew install autogen virtualenv`
-- `virtualenv -p python3 ENV` (Python > 3.5 is required)
-- `source ENV/bin/activate` (or `source ENV/bin/activate.csh` based on shell preference)
-- `pip install -r requirements.txt`
+```shell
+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
+popd
+make -C external/micropython/mpy-cross
+cd unix; make setup && make ngu-setup && make && ./simulator.py
+```
 
-Setup and Run the Desktop-based Coldcard simulator:
+You may need to reboot to avoid a `DISPLAY is not set` error.
 
-- `cd unix; make setup && make; ./simulator.py`
+The next time you want to run the simulator, you can simply do
 
-Building the firmware:
+```shell
+source ENV/bin/activate && cd unix && ./simulator.py
+```
+
+#### Building the firmware
 
 - `cd ../cli; pip install --editable .`
 - `cd ../stm32; make setup && make; make firmware-signed.dfu`
@@ -66,49 +160,73 @@ Building the firmware:
 
 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
-
-
-### MacOS
-
-You'll probably need to install at least these packages:
-
-    brew install --cask xquartz
-    brew install sdl2 xterm
-    brew install --cask gcc-arm-embedded
-
-Used to be these were needed as well:
-
-    brew tap PX4/px4
-    brew search px4
-    brew install px4/px4/gcc-arm-none-eabi-80 (latest gcc-arm-none-eabi-XX, currently 80)
-
-You may need to reboot to avoid a `DISPLAY is not set` error.
-
-You may need to `brew upgrade gcc-arm-embedded` because we need 10.2 or higher.
+```shell
+[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 supress a warning
-  about `Python[22580:10101559] ApplePersistenceIgnoreState: Existing state will not be touched. New state will be written to...` see <https://bugs.python.org/issue32909>
+`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...`
+
+See <https://bugs.python.org/issue32909>
 
 ### Linux
 
-You'll probably need to install these (Ubuntu 16):
+All steps you need to install and run the Coldcard simulator on Ubuntu 20.04:
 
-    apt install libudev-dev python-sdl2 gcc-arm-none-eabi
 
-If you get stuck on the "Skip PIN" screen after the startup, edit the `pyb.py` file located under `/unix/frozen-modules/` and follow the instructions from line 27 to line 31:
-```
-# If on linux, try commenting the following line
-addr = bytes([len(fn)+2, socket.AF_UNIX] + list(fn))
-# If on linux, try uncommenting the following two lines
-#import struct
-#addr = struct.pack('H108s', socket.AF_UNIX, fn)
+```shell
+# 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 https://github.com/Coldcard/firmware.git
+cd firmware
+
+# Apply address patch
+# if unix/linux_addr.patch exists use below command
+# not needed in current revision
+# git apply unix/linux_addr.patch
+
+#  * below is needed for ubuntu 24.04
+pushd external/micropython
+git apply ../../ubuntu24_mpy.patch
+popd
+#  * 
+
+
+# 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
+popd
+make setup
+make ngu-setup
+make
+
+# Run the simulator in the active virtualenv
+./simulator.py
+
+# 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
+./simulator.py
 ```
 
+Also make sure that you have your python3 symlinked to python.
+
 ## Code Organization
 
 Top-level dirs:
@@ -117,40 +235,55 @@ Top-level dirs:
 
 - shared code between desktop test version and real-deal
 - expected to be largely in python, and higher-level
+- code exclusive to the Mk4 or Mk5 will be listed in `manifest_mk4.py`, and
+  to the Q will be listed in `manifest_q1.py`
 
 `unix`
 
-- unix (MacOS) version for testing/rapid dev
+- unix (macOS) version for testing/rapid dev
 - this is a simulator for the product
 
 `testing`
 
 - test cases and associated data
 
-
 `stm32`
 
-- embedded micro version, for actual product
+- embedded binaries (and building), for actual product hardware
 - final target is a binary file for loading onto hardware
 
 `external`
 
 - code from other projects, ie. the dreaded submodules
 
+`graphics`
+
+- images which ship as part of the final product (icons)
+
 `stm32/bootloader`
 
-- 32k of factory-set code that you cannot change
+- 32k of factory-set code that you cannot change (Mk3)
+- however, you can inspect what code is on your coldcard and compare to this.
+
+`stm32/mk4-bootloader`
+`stm32/q1-bootloader`
+
+- 128k of factory-set code that you cannot change
 - however, you can inspect what code is on your coldcard and compare to this.
 
 `hardware`
 
-- schematic and bill of materials for the Coldcard
+- schematic and bill of materials for the Coldcard, all versions.
 
-`unix/work/MicroSD`
+`unix/work/...`
 
-- files on "simulated" microSD card 
+- `/MicroSD/*` files on "simulated" microSD card
 
+- `/VirtDisk/*` simulated emulated virtual Disk files.
+
+- `/settings/*.aes` persistent settings for Simulator
 
 ## Support
 
 Found a bug? Email: support@coinkite.com
+

cli/setup.py

@@ -11,7 +11,7 @@ from setuptools import setup
 setup(
     name='signit',
     version='1.0',
-    #py_modules=['ckcc'],
+    py_modules=['signit', 'sigheader'],
     install_requires=[
         'Click',
     ],

cli/sigheader.py

@@ -1 +1 @@
-../stm32/bootloader/sigheader.py
+../stm32/sigheader.py

cli/signit.py

@@ -208,7 +208,9 @@ def readback(fname):
             if v & MK_2_OK: d.append('Mk2')
             if v & MK_3_OK: d.append('Mk3')
             if v & MK_4_OK: d.append('Mk4')
-            if v & ~(MK_1_OK | MK_2_OK | MK_3_OK | MK_4_OK):
+            if v & MK_5_OK: d.append('Mk5')
+            if v & MK_Q1_OK: d.append('Q1')
+            if v & ~(MK_1_OK | MK_2_OK | MK_3_OK | MK_4_OK | MK_5_OK | MK_Q1_OK):
                 d.append('?other?')
             v = nv + '+'.join(d)
         elif fld == 'timestamp':
@@ -244,7 +246,7 @@ def readback(fname):
 @click.option('--pubkey-num', '-k', type=int, help='Which key # to use for signing', default=0)
 @click.option('--high_water', '-h', is_flag=True, help='Mark version as new highwater mark (no downgrades below this version)')
 @click.option('--verbose', '-v', default=False, is_flag=True, help='Show numbers related to signature')
-@click.option('--hw-compat', '-m', type=int, metavar='BITMASK', help="Set HW compat field (mk number)")
+@click.option('--hw-compat', '-m', type=str, metavar='mk', help="Set HW compat field (hw_label value)")
 @click.option('--backdate', type=int, metavar='DAYS',
                             help='Make downgrade attack test version', default=0)
 @click.option('--build_dir', '-b', default='l-port/build-COLDCARD')
@@ -277,9 +279,12 @@ def doit(keydir, outfn=None, build_dir=None, high_water=False,
         vectors = open(build_dir + '/firmware0.bin', 'rb').read()
         body = open(build_dir + '/firmware1.bin', 'rb').read()
 
-    if hw_compat == 4:
-        hw_compat = MK_4_OK
-    elif hw_compat in {3, None}:
+    if hw_compat in { 'mk4', '4', 'mk5', '5', 'mk' }:
+        # Mk4 and 5 can run the same firmware, once Mk5 support was added
+        hw_compat = MK_4_OK | MK_5_OK
+    elif hw_compat == 'q1':
+        hw_compat = MK_Q1_OK
+    elif hw_compat in { 'mk3', '3'}:
         hw_compat = MK_2_OK | MK_3_OK
     else:
         assert not "known"
@@ -288,7 +293,17 @@ def doit(keydir, outfn=None, build_dir=None, high_water=False,
     assert len(body) >= FW_MIN_LENGTH, "main firmware is too small: %d" % len(body)
 
     body_len = align_to(len(body), 512)
-    assert body_len % 512 == 0, body_len
+
+    if hw_compat & (MK_1_OK | MK_2_OK | MK_3_OK):
+        # bugfix: size must be non-page aligned, so extra bytes are erased past end
+        if (body_len % 4096) == 0:
+            body_len += 512
+        assert body_len % 512 == 0, body_len
+    else:
+        # bugfix: PSRAM-based products (Mk4, Q1) need to erase 4k blocks, so
+        # trouble happens if final binary isn't aligned to that size.
+        body_len = align_to(body_len, 4096)
+        assert body_len % 4096 == 0, body_len
 
     # pad out 
     vectors = pad_to(vectors, FW_HEADER_OFFSET)
@@ -306,14 +321,15 @@ def doit(keydir, outfn=None, build_dir=None, high_water=False,
                     pubkey_num=pubkey_num,
                     timestamp=timestamp(backdate) )
 
-    assert FW_MIN_LENGTH <= hdr.firmware_length <= FW_MAX_LENGTH, hdr.firmware_length
 
-    if hw_compat & MK_4_OK:
-        # new value for Mk4: limited only by final binary size, not SPI flash
-        USB_MAX_LEN = 1472 * 1024
-    else:
+    if hw_compat & MK_3_OK:
         # actual file length limited by size of SPI flash area reserved to txn data/uploads
+        assert FW_MIN_LENGTH <= hdr.firmware_length <= FW_MAX_LENGTH, hdr.firmware_length
         USB_MAX_LEN = (786432-128)
+    else:
+        # new value for Mk4 and later: limited only by final binary size, not SPI flash
+        assert FW_MIN_LENGTH <= hdr.firmware_length <= FW_MAX_LENGTH_MK4, hdr.firmware_length
+        USB_MAX_LEN = 1472 * 1024
 
     assert hdr.firmware_length <= USB_MAX_LEN, \
         "too big for our USB upgrades: %d = %d bytes too big" % (

docs/README.md

@@ -3,14 +3,32 @@
 These docs are meant for you hackers out there... but also for anyone who
 wants to understand why it's safe to put your moneys into Coldcard.
 
+- [`security-model.md`](security-model.md) The COLDCARD Mk4/Mk5/Q security model.
 - [`pin-entry.md`](pin-entry.md) Huge and detailed discussion of PIN codes and the security element that holds the secrets.
+- [`secure-elements.md`](secure-elements.md) How the dual secure elements work together.
 - [`dev-access.md`](dev-access.md) How developers can modify Coldcard to extend it.
 - [`memory-map.md`](memory-map.md) Memory map highlights
+- [`notes-on-repro.md`](notes-on-repro.md) Detailed breakdown of the reproducible build process.
+- [`upgrade-recovery.md`](upgrade-recovery.md) Firmware upgrade and recovery process.
 - [`backup-files.md`](backup-files.md) Some details of our encrypted backup files.
+- [`temporary-seeds.md`](temporary-seeds.md) Temporary (ephemeral) seeds and the Seed Vault.
+- [`seed-xor.md`](seed-xor.md) More about _Seed XOR_ feature, including fully worked Seed XOR example, and useful XOR lookup chart.
+- [`key-teleport.md`](key-teleport.md) Key Teleport: encrypted transfer of seeds and secrets between Q devices.
+- [`spending-policy.md`](spending-policy.md) Spending policy: autonomous signing with configurable limits.
+- [`microsd-2fa.md`](microsd-2fa.md) Using a MicroSD card as a second factor for login.
+- [`web2fa.md`](web2fa.md) Web 2FA authentication.
+- [`bip85-passwords.md`](bip85-passwords.md) Deriving deterministic passwords via BIP-85.
+- [`msg-signing.md`](msg-signing.md) COLDCARD message signing.
+- [`proof-of-reserves-bip-322.md`](proof-of-reserves-bip-322.md) BIP-322 generic signed message format and proof of reserves.
+- [`generic-wallet-export.md`](generic-wallet-export.md) Generic JSON wallet export file format.
+- [`bip-21-extensions.md`](bip-21-extensions.md) Coldcard's BIP-21 URI extensions, including multisig ownership address check.
+- [`nfc-coldcard.md`](nfc-coldcard.md) NFC support on Coldcard Mk4 and Q.
+- [`nfc-pushtx.md`](nfc-pushtx.md) NFC Push Transaction: broadcast a signed transaction via your phone.
+- [`usb-batteries.md`](usb-batteries.md) Using USB battery packs with Coldcard.
 - [`electrum-usage.md`](electrum-usage.md) Importing seed words into Electrum for funds usage (and other tips).
 - [`bitcoin-core-usage.md`](bitcoin-core-usage.md) How to use with Bitcoin Core.
+- [`bitcoin-core2of2desc.md`](bitcoin-core2of2desc.md) Airgapped 2-of-2 multisig with Bitcoin Core using descriptors.
 - [`limitations.md`](limitations.md) Documented limitations, policy choices, and TODO items.
 - [`paperwallet.pdf`](paperwallet.pdf) Example paper wallet template file.
-- [`seed-xor.md`](seed-xor.md) More about _Seed XOR_ feature, including fully worked Seed XOR example, and useful XOR lookup chart.
 - [`menu-tree.txt`](menu-tree.txt) Dump of the menu system. Incomplete, may be out of date.
 

docs/backup-files.md

@@ -38,6 +38,17 @@ a single file, which is a simple text file and
 easy to read. Before version 4.0.0, this text file was always
 called `ckcc-backup.txt`, but the filename is now picked randomly.
 
+## BIP39 Passphrase
+
+If BIP39 passphrase is active the default behavior is to back-up
+main wallet - not BIP39 passphrase wallet. From version `5.2.0`
+users can choose to back-up also BIP39 passphrase wallet.
+
+## Ephemeral Seeds
+
+If ephemeral seed is active the default behavior is to always 
+back-up ephemeral wallet instead of the main wallet.
+
 ## Limitations
 
 - The archive file names are not encrypted. You can see there is a single

docs/bip-21-extensions.md

@@ -0,0 +1,15 @@
+## Multisig Ownership address check: "wallet"
+
+If the name of the multisig wallet related to an address is provided, address search
+can be greatly accelerated. Just provide `wallet=name` parameter in a standard
+[BIP-21](https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki) URL
+shown in QR code or NFC record. If omitted, search will continue across 
+all multisig wallets known by COLDCARD.
+
+### Examples
+
+```
+tb1q4d67p7stxml3kdudrgkg5mgaxsrgzcqzjrrj4gg62nxtvnsnvqjsxjkej0?wallet=goldmine
+
+bitcoin:mtHSVByP9EYZmB26jASDdPVm19gvpecb5R?label=coldcard_purchase&amount=50&wallet=Haystack%20Four
+```

docs/bip85-passwords.md

@@ -0,0 +1,113 @@
+# BIP-85 Passwords
+
+This feature derives a deterministic password from your seed,
+according to [BIP-85 PWD BASE64](https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki#pwd-base64).
+Generated passwords can be sent as keystrokes via USB to the host computer,
+effectively using Coldcard as specialized password manager.
+
+In addition to deriving up to 10,000 distinct secure passwords, the Coldcard
+can also type them into a computer by emulating a USB keyboard, and simulating the
+keystrokes needed to type the password.
+
+#### Requirements
+
+* Coldcard Mk4 or Mk5 (firmware 5.0.5 or newer), or any Q
+* USB-C with data link (won't work with power only cable from Coinkite)
+
+## Type Passwords over USB
+
+1. To enable "Type Passwords" feature, connect your Coldcard to host PC with USB cable (check requirements) and go to Settings -> Keyboard EMU -> Enable.
+2. Go back to top menu and "Type Passwords" option will be shown below "Address Explorer".
+3. When it is time to enter a secret password, select "Type Passwords" from the main menu. After 
+an information screen, the USB emulation will be switch to keyboard emulation
+and `Switching...` shown on the screen.
+4. Choose "Password index" (BIP-85 index) and press OK to generate that password.
+5. It takes a moment to generate the password, and then you can scroll down to check BIP-85 path used and double-check password to be typed.
+6. To send keystrokes, place mouse at required password prompt and press OK. This will send desired keystrokes plus hit enter at the end.
+6. You are back at step 4, and can continue to generate passwords or you can press X
+to exit. Exiting from "Type Passwords" will cause Coldcard to turn off keyboard emulation and enable normal USB mode if it was enabled before. Otherwise, USB stays disabled.
+
+## View BIP-85 passwords
+
+1. Go to Advanced/Tools -> Derive Seed B85 -> Passwords
+2. Choose "Password/Index number" (BIP-85 index) and press OK to generate password.
+3. Screen shows generated password, path, and entropy from which password was derived
+4. A few different options are available at this point (on Mk; on Q the NFC and
+   QR buttons are used instead of (3)/(4)):
+   1. press (1) to save password backup file on MicroSD card (cleartext!)
+   2. press (2) to save to Virtual Disk (only when available)
+   3. press (3) to send over NFC (only appears when NFC is enabled)
+   4. press (4) to view password as QR code
+   5. press (6) to send keystrokes over USB (this enables keyboard emulation, sends keystrokes + enter, then disables keyboard emulation)
+
+## Keyboard language settings
+
+Emulated Keystrokes are mapped to specific characters based on your host PC keyboard
+language settings. For Coldcard to be able to type the correct BIP-85
+password your host computer MUST use language settings that
+corresponds to a [QWERTY](https://simple.wikipedia.org/wiki/QWERTY) key layout,
+including number row directly above QWERTY:
+
+```
+1 2 3 4 5 6 7 8 9 0 - =
+ Q W E R T Y U I O P [ ] \
+  A S D F G H J K L ; '
+   Z X C V B N M , . /
+```
+
+Passwords generated and shown on Coldcard will always be correct
+with respect to BIP-85. However, when sending keystrokes, for example
+on German keyboard, what was typed will not match the text that was
+generated and shown on Coldcard's screen.
+
+For example, if the correct password is `zYLoepugzdVJvdL56ogNV` but when used
+with German keyboard language settings, what will be typed is
+`yZLoepugydVJvdL56ogNV`. You can see that German keyboard is not
+QWERTY, but it is QUERTZ (y and z are swapped).
+
+Even with "non-standard" keyboard language settings, Coldcard always
+sends exact same keystrokes for specific password index and it is
+deterministic, as long the keyboard language setting do not change.
+However, BIP-85 won't be respected in this case.
+
+## Coldcard Specifics
+
+Check [BIP-85](https://github.com/scgbckbone/bips/blob/passwords/bip-0085.mediawiki)
+for complete specification of the new addition to BIP-85.
+
+Coldcard does not allow you to specify password length - we always
+use length of **21**. Passwords of this length generated according
+to BIP will have approximately 126 bits of entropy. This is on par
+with bitcoin security model and therefore all passwords the Coldcard
+will generate are considered very strong.
+
+## Examples
+
+Using below seed, path and index, we generate passwords shown in the table:
+
+```shell
+wife shiver author away frog air rough vanish fantasy frozen noodle athlete pioneer citizen symptom firm much faith extend rare axis garment kiwi clarify
+```
+
+| Index | Path                       | Password |
+|-------|----------------------------|----------|
+| 0     | m/83696968'/707764'/21'/0' |  BSdrypS+J4Wr1q8DWjbFE |
+| 1     | m/83696968'/707764'/21'/1' |  TkDX7d9fnX9FZ9QEpjFDB |
+| 2     | m/83696968'/707764'/21'/2' |  cvfdmoZL3BcIpJ7G+Rb8k |
+| 3     | m/83696968'/707764'/21'/3' |  wsCALdN+GgbSOGyGE9aRN |
+| 4     | m/83696968'/707764'/21'/4' |  HfYbWx7gVmUmb2Bw4o4QD |
+| 5     | m/83696968'/707764'/21'/5' |  vLOf9WPO5QiPbOTEbz/yJ |
+| 6     | m/83696968'/707764'/21'/6' |  1oSUs7Cy3fnpdh/fAS7EK |
+| 7     | m/83696968'/707764'/21'/7' |  seh9WN6mlvPPB5jdVz3xN |
+| 8     | m/83696968'/707764'/21'/8' |  U4RD0R0A0RjpHOFtwnv9k |
+
+
+## Incompatible Applications
+
+Although the Coldcard is emulating a keyboard at the lowest possible level,
+for some reason occasionally high-level applications have
+trouble with our high-speed typing.
+
+- KeePass2 2.45 (under Ubuntu). Capital/lowercase letters may be incorrectly typed. Use KeePassXC instead.
+
+

docs/bitcoin-core-usage.md

@@ -17,15 +17,19 @@ Step 1: Create a new descriptor-based wallet in Bitcoin Core
 
 - File -> Create Wallet ... 
 - give it a unique name
+- check "Disable Private Keys"
+- check "Make Blank Wallet"
 - check "Descriptor Wallet"
 
 Step 2: Export descriptor from Coldcard to Core
 
-- on Coldcard, go to Advanced -> MicroSD card -> Export Wallet -> Bitcoin Core
+- (singlesig) on Coldcard, go to Advanced -> MicroSD card -> Export Wallet -> Bitcoin Core
+- (multisig) on Coldcard, go to Settings -> Multisig Wallets -> Choose desired multisig wallet -> Descriptors -> Bitcoin Core
 - on your computer, open `bitcoin-core-XX.txt`, copy the `importdescriptor` command line
 - in Bitcoin Core, go to Windows -> Console
 - select your newly created descriptor wallet in the wallet pulldown (top left)
 - paste the `importdescriptor` command. It should respond with a success message
+  - in Bitcoin Core v24.1, the console response will include `"message": "Ranged descriptors should not have a label"` and Bitcoin Core won't allow address generation. Removing the entry `"label": "Coldcard x0x0x0x0"` from the .txt file fixes this issue.
 
 NOTE: If you are importing an existing wallet this way, with UTXO on the blockchain,
 you may need to rescan and/or delete "timestamp=now" from the command. If the

docs/bitcoin-core2of2desc.md

@@ -0,0 +1,134 @@
+## Airgapped 2of2 Multisig with Bitcoin Core (and descriptors)
+
+#### Prerequisites
+* Coldcard Mk4 signing device
+* SD card and SD card reader (or NFC reader)
+* bitcoind (version v23.0)
+* [jq](https://stedolan.github.io/jq/)
+
+### Tutorial 1
+2of2 with two Mk4 signing devices (+ bitcoin-qt watch only wallet as a coordinator)
+* full tutorial now on [coldcard.com](https://coldcard.com/docs/bitcoin-core-2of2desc)
+
+### Tutorial 2
+2of2 with one Mk4 signing device and bitcoind sww (+ bitcoind watch only wallet as a coordinator)
+
+1. start bitcoind (here I will use regtest)
+```shell
+bitcoind -regtest
+```
+2. Create descriptor wallet with private keys enabled. This wallet will be used for signing (1of2)
+```shell
+bitcoin-cli -regtest createwallet "signer"
+# if using core older than v23.0 you need to specify descriptor wallet as below
+bitcoin-cli -regtest help  createwallet "signer" false false "__strong-random_password&%4568479" false true
+```
+3. Fill keypool for signer as we will generate addresses with watch_only wallet (this is needed, otherwise signer will not be able to sign other than index 0). If you spend more than 100 adress, you will need to refill keypool again with same command.
+```shell
+$ bitcoin-cli -regtest -rpcwallet="signer" keypoolrefill 100
+```
+4. Create watch-only descriptor wallet. This wallet will contain watch-only multisig descriptor (coordinator)
+```shell
+bitcoin-cli -regtest  createwallet "watch_only" true true
+# if older than v23.0
+bitcoin-cli -regtest  createwallet "watch_only" true true "" false true
+```
+5. Get descriptor from Coldcard Mk4 (Settings->Multisig Wallets->Eport XPUB + choose account number -> in our case 0)
+6. Step 4. produced a text file on SD card or in your  .... as we will be creating wsh multisig get `p2wsh_desc` key from produced file (should start with ccxp-<xfp>.json). Should look like this:
+```shell
+"wsh(sortedmulti(M,[0F056943/48'/1'/0'/2']tpubDF2rnouQaaYrXF4noGTv6rQYmx87cQ4GrUdhpvXkhtChwQPbdGTi8GA88NUaSrwZBwNsTkC9bFkkC8vDyGBVVAQTZ2AS6gs68RQXtXcCvkP/0/*,...))"
+```
+7. Above descriptor template needs to be filled with information form other signers (in our case only bitcoind). Specifically one must add all extended keys with key origin info and substitute `M` with threshold value.
+8. Bitcoin (unfortunately) does not support deriving xpubs at will, so we will use legacy derivations path which we can get from `listdescriptors`
+```shell
+$ bitcoin-cli -regtest -rpcwallet="signer" listdescriptors
+{
+  "wallet_name": "signer",
+  "descriptors": [
+    {
+      "desc": "pkh([122b6f56/44'/1'/0']tpubDCmC5bJAfQxjCFrRCG9qzBmz4FDy6SVieb4KZaPD5D8AFx5vYjngiRfJSCds4LzKcpy9Mx3he4uSdfdkJHGZBG2gJqz63ndKj9miiVbYzfc/0/*)#ryqp0qxp",
+      "timestamp": 1656067182,
+      "active": true,
+      "internal": false,
+      "range": [
+        0,
+        999
+      ],
+      "next": 0
+    },
+    {
+      "desc": "wpkh([122b6f56/84'/1'/0']tpubDCSoM4w4NXN5sAorw6pnEcwho1dJRiyLTjgK9FTkgc25RguDZ2Vnk3dt9bCdFt9oU5YHNWkjEaYERXbLro8HMTbF9ze7Shn15xdKNa2umkG/0/*)#pg8w9ku3",
+      "timestamp": 1656067182,
+      "active": true,
+      "internal": false,
+      "range": [
+        0,
+        999
+      ],
+      "next": 0
+    },
+    ...
+  ]
+}
+```
+9. Copy extended key (with key origin and derivation information) from `pkh` descriptor (shown below)
+```shell
+[122b6f56/44'/1'/0']tpubDCmC5bJAfQxjCFrRCG9qzBmz4FDy6SVieb4KZaPD5D8AFx5vYjngiRfJSCds4LzKcpy9Mx3he4uSdfdkJHGZBG2gJqz63ndKj9miiVbYzfc/0/*
+```
+10. Insert above to the multisig descriptor from step 5. and replace M with 2
+11. Use bitcoind to calculate descriptor checksum
+```shell
+$ bitcoin-cli -regtest getdescriptorinfo "wsh(sortedmulti(2,[0f056943/48'/1'/0'/2']tpubDF2rnouQaaYrXF4noGTv6rQYmx87cQ4GrUdhpvXkhtChwQPbdGTi8GA88NUaSrwZBwNsTkC9bFkkC8vDyGBVVAQTZ2AS6gs68RQXtXcCvkP/0/*,[122b6f56/44'/1'/0']tpubDCmC5bJAfQxjCFrRCG9qzBmz4FDy6SVieb4KZaPD5D8AFx5vYjngiRfJSCds4LzKcpy9Mx3he4uSdfdkJHGZBG2gJqz63ndKj9miiVbYzfc/0/*))"
+{
+  "descriptor": "wsh(sortedmulti(2,[0f056943/48'/1'/0'/2']tpubDF2rnouQaaYrXF4noGTv6rQYmx87cQ4GrUdhpvXkhtChwQPbdGTi8GA88NUaSrwZBwNsTkC9bFkkC8vDyGBVVAQTZ2AS6gs68RQXtXcCvkP/0/*,[122b6f56/44'/1'/0']tpubDCmC5bJAfQxjCFrRCG9qzBmz4FDy6SVieb4KZaPD5D8AFx5vYjngiRfJSCds4LzKcpy9Mx3he4uSdfdkJHGZBG2gJqz63ndKj9miiVbYzfc/0/*))#flsx3jj8",
+  "checksum": "flsx3jj8",
+  "isrange": true,
+  "issolvable": true,
+  "hasprivatekeys": false
+}
+```
+12. Copy descriptor with checksum to new file (2of2core.txt) on SD card (descriptor has to be in single line)
+13. Insert SD card to Coldcard and import multisig wallet.(Settings->Multisig Wallets->Import from file) select 2of2core.txt and approve.
+14. Export imported multisig wallet for bitcoin core (Settings->Multisig Wallets->2/2: 2of2core->Descriptors->Bitcoin Core)
+15. Step 14. will produce `bitcoin-core-2of2core.txt` file on SD card. Copy command from file.
+16. Import descriptor to watch_only wallet (signer would not allow us as he has private keys)
+```shell
+bitcoin-cli -regtest -rpcwallet=watch_only importdescriptors '[{"active": true, "timestamp": "now", "range": [0, 100], "internal": true, "desc": "wsh(sortedmulti(2,[0f056943/48h/1h/0h/2h]tpubDF2rnouQaaYrXF4noGTv6rQYmx87cQ4GrUdhpvXkhtChwQPbdGTi8GA88NUaSrwZBwNsTkC9bFkkC8vDyGBVVAQTZ2AS6gs68RQXtXcCvkP/1/*,[122b6f56/44h/1h/0h]tpubDCmC5bJAfQxjCFrRCG9qzBmz4FDy6SVieb4KZaPD5D8AFx5vYjngiRfJSCds4LzKcpy9Mx3he4uSdfdkJHGZBG2gJqz63ndKj9miiVbYzfc/1/*))#tv5t5plj"}, {"active": true, "timestamp": "now", "range": [0, 100], "internal": false, "desc": "wsh(sortedmulti(2,[0f056943/48h/1h/0h/2h]tpubDF2rnouQaaYrXF4noGTv6rQYmx87cQ4GrUdhpvXkhtChwQPbdGTi8GA88NUaSrwZBwNsTkC9bFkkC8vDyGBVVAQTZ2AS6gs68RQXtXcCvkP/0/*,[122b6f56/44h/1h/0h]tpubDCmC5bJAfQxjCFrRCG9qzBmz4FDy6SVieb4KZaPD5D8AFx5vYjngiRfJSCds4LzKcpy9Mx3he4uSdfdkJHGZBG2gJqz63ndKj9miiVbYzfc/0/*))#zyueunr0"}]'
+```
+15. Get address and get some funds
+```shell
+$ bitcoin-cli -regtest -rpcwallet=watch_only  getnewaddress
+bcrt1q6u8s97fnd6ggad4apqs8vvcgup0d085ttd9v0c6fmpf38tf6q0ysgfh4vm
+```
+16. If you use regtest as I do, make sure to set Coldcard to regtest (Advanced/Tools-> Danger Zone->Testnet Mode->Regtest)
+17. Check that core generated address matches with address generated by Coldcard (Address Explorer->multi_2of2_core)
+18. Fund address
+```shell
+# this is only useful for those who use regtest - if you're on testnet use faucet
+bitcoin-cli -regtest -rpcwallet=watch_only  generatetoaddress 101 "bcrt1q6u8s97fnd6ggad4apqs8vvcgup0d085ttd9v0c6fmpf38tf6q0ysgfh4vm"
+```
+19. Generate destination address to send to (in our case another `getnewaddress` -> self spend)
+```shell
+`bitcoin-cli -regtest -rpcwallet=watch_only getnewaddress`
+```
+20. Create PSBT
+```shell
+# we need to use change address as we do not support change descriptor - yet
+psbt=$(bitcoin-cli -regtest -rpcwallet=watch_only walletcreatefundedpsbt '[]' '[{"bcrt1qagwmv5706xm8da8fh2dldk6rsjcxv06zae9w2nm8yex6rsvanf6s5re53w": 1.0}]' 0 '{"fee_rate": 20}' | jq -r '.psbt')
+```
+21. Sign with core (signer wallet)
+```shell
+psbt_core_signed=$(bitcoin-cli -regtest -rpcwallet=signer walletprocesspsbt $psbt true "ALL" | jq -r '.psbt')
+```
+22. Get half signed PSBT to Coldcard (via SD card or NFC) for signing
+```shell
+# move half signed PSBT to micro SD card (must end with .psbt)
+echo $psbt_core_signed > /media/MicroSD/core_signed.psbt
+```
+23. On Coldcard (Ready To Sign) verify transaction (check addresses, amounts...) and sign. Coldcard will produce `core_signed-part.psbt`. Copy this file back to PC.
+24. Finalize and send
+```shell
+$ tx_hex=$(bitcoin-cli -regtest  finalizepsbt $(cat /media/MicroSD/core_signed-part.psbt | head -n 1) | jq -r ".hex")
+$ bitcoin-cli -regtest sendrawtransaction $tx_hex
+93fcd4e926978260406844ffb73a2e506cd427b0e0c3ee2882bffd6c2855d7a5  # tx id returned
+```

docs/dev-access.md

@@ -39,7 +39,7 @@ Yes, external developers can modify COLDCARD and make their own versions!
 If the red/green light is red, this means some part of flash was
 changed without the secure checksum inside SE1 being first updated.
 The upgrade process does this correctly in Mk4, and there is no
-point time the checksum is wrong, so there should be no way to see this
+point in time the checksum is wrong, so there should be no way to see this
 screen:
 
 ![warning screen](dev-warning.png)

docs/generic-wallet-export.md

@@ -5,9 +5,12 @@ wallet systems, but we also have a file format for general purpose
 exports, which we hope future wallet makers will leverage.
 
 It contains master XPUB, XFP for that, and derived values for the top hardened
-position of BIP44, BIP84 and BIP49.
+position of the single-signature schemes BIP44, BIP49 and BIP84, plus the
+multisig schemes BIP48 (`bip48_1` = `.../1h` P2SH-P2WSH and `bip48_2` = `.../2h` P2WSH).
+When the account number is zero, a BIP45 (`m/45h`) multisig section is also included
+(it is omitted for non-zero accounts, as in the example below).
 
-The feature can be found here: _Advanced > MicroSD > Export Wallet > Generic JSON_
+The feature can be found here: _Advanced/Tools > Export Wallet > Generic JSON_
 
 Please contact us (or better yet, make a pull request), if you need something
 more in this file.
@@ -18,32 +21,51 @@ Here is an example, produced by the Simulator for account number 123.
 
 ```javascript
 {
-    "chain": "XTN",
+    "chain": "BTC",
     "xfp": "0F056943",
-    "xpub": "tpubD6NzVbkrYhZ4XzL5Dhayo67Gorv1YMS7j8pRUvVMd5odC2LBPLAygka9p7748JtSq82FNGPppFEz5xxZUdasBRCqJqXvUHq6xpnsMcYJzeh",
     "account": 123,
+    "xpub": "xpub661MyMwAqRbcGC9DmWbtbAmuUjpMYxw4BWE88NSDHB3jSjfUK7KtYJuKa52GbowD3DVLkgsxH9QwPnTx5mjdHykYFEncnmAsNsCTbWzBhA7",
     "bip44": {
-        "deriv": "m/44'/1'/123'",
-        "first": "n44vs1Rv7T8SANrg2PFGQhzVkhr5Q6jMMD",
         "name": "p2pkh",
-        "xfp": "B7908B26",
-        "xpub": "tpubDCiHGUNYdRRGoSH22j8YnruUKgguCK1CC2NFQUf9PApeZh8ewAJJWGMUrhggDNK73iCTanWXv1RN5FYemUH8UrVUBjqDb8WF2VoKmDh9UTo"
+        "xfp": "5F898064",
+        "deriv": "m/44h/0h/123h",
+        "xpub": "xpub6DStQXfAgHuLbMpCf86ruVkF4yT9pSLyWsFiqQTWY9osuinq8Dyee4W5jCjMfyku5LNkRB9oFinrY5ufn9XXEn8Vvzc2jnifKMaQCNV7RBZ",
+        "desc": "pkh([0f056943/44h/0h/123h]xpub6DStQXfAgHuLbMpCf86ruVkF4yT9pSLyWsFiqQTWY9osuinq8Dyee4W5jCjMfyku5LNkRB9oFinrY5ufn9XXEn8Vvzc2jnifKMaQCNV7RBZ/<0;1>/*)#4tl8jryn",
+        "first": "1GTNtzG5xX2UhdD5e3Nu7i1WPxFdjxQMJt"
     },
     "bip49": {
-        "_pub": "upub5DMRSsh6mNak9KbcVjJ7xAgHJvbE3Nx22CBTier5C35kv8j7g2q58ywxskBe6JCcAE2VH86CE2aL4MifJyKbRw8Gj9ay7SWvUBkp2DJ7y52",
-        "deriv": "m/49'/1'/123'",
-        "first": "2N87V39riUUCd4vmXfDjMWAu9gUCiBji5jB",
-        "name": "p2wpkh-p2sh",
-        "xfp": "CEE1D809",
-        "xpub": "tpubDCDqt7XXvhAdy1MpSze5nMJA9x8DrdRaKALRRPasfxyHpiqWWEAr9cbDBQ9BcX7cB3up98Pk97U2QQ3xrvQsi5dNPmRYYhdcsKY9wwEY87T"
+        "name": "p2sh-p2wpkh",
+        "xfp": "A748B1FC",
+        "deriv": "m/49h/0h/123h",
+        "xpub": "xpub6DDm8WzH5a9qjKkttzqSB3uGofNohU9D3n3UG8WMxkUZzJEMPTYiQRf1dvTFCQR82MjGW4LUMVuTtnW4hF17RpzCqVwhf6Z2fnJPWtjG164",
+        "desc": "sh(wpkh([0f056943/49h/0h/123h]xpub6DDm8WzH5a9qjKkttzqSB3uGofNohU9D3n3UG8WMxkUZzJEMPTYiQRf1dvTFCQR82MjGW4LUMVuTtnW4hF17RpzCqVwhf6Z2fnJPWtjG164/<0;1>/*))#5j7t2n2u",
+        "_pub": "ypub6Y42SBfCEFhKacx1jMd4P8zmydXFe68hxtZh3XQFLkrT3Q3ae7iH2VK9f8QqCK53Rzr5FXw2pAG1n57dQwR8E4fohqe8F1NWwWN2uVRfBry",
+        "first": "3CeBRbJKCpg7BpJME2vM8ZxhCjBnhG4toy"
     },
     "bip84": {
-        "_pub": "vpub5Y5a91QvDT45EnXQaKeuvJupVvX8f9BiywDcadSTtaeJ1VgJPPXMitnYsqd9k7GnEqh44FKJ5McJfu6KrihFXhAmvSWgm7BAVVK8Gupu4fL",
-        "deriv": "m/84'/1'/123'",
-        "first": "tb1qc58ys2dphtphg6yuugdf3d0kufmk0tye044g3l",
         "name": "p2wpkh",
-        "xfp": "78CF94E5",
-        "xpub": "tpubDC7jGaaSE66VDB6VhEDFYQSCAyugXmfnMnrMVyHNzW9wryyTxvha7TmfAHd7GRXrr2TaAn2HXn9T8ep4gyNX1bzGiieqcTUNcu2poyntrET"
+        "xfp": "2C5207AA",
+        "deriv": "m/84h/0h/123h",
+        "xpub": "xpub6CaWStGvcXqSW9BzU2vpCoP7aWjz9VfR5DS2nuYWVvKV2nug2dESg3HdFsaWHeoZaxuAhNcPB3TH2gq8MugS3JX1yGuhB4QbC2BneaYqB16",
+        "desc": "wpkh([0f056943/84h/0h/123h]xpub6CaWStGvcXqSW9BzU2vpCoP7aWjz9VfR5DS2nuYWVvKV2nug2dESg3HdFsaWHeoZaxuAhNcPB3TH2gq8MugS3JX1yGuhB4QbC2BneaYqB16/<0;1>/*)#yk84tprf",
+        "_pub": "zpub6rF34DckutvQCjaE8kW4cya7vT2t2jeQuSUUMhLHFw5F8zY8XwZZvAbuJHVgHU7QQF8nCKoW6NANoG4FoJWTdmtDhxJYLt3ZjUK5RqUSMdF",
+        "first": "bc1qhj6avwmp5lhpgqwm6dgxrf3v5lf67rjm99a8an"
+    },
+    "bip48_1": {
+        "name": "p2sh-p2wsh",
+        "xfp": "845A3542",
+        "deriv": "m/48h/0h/123h/1h",
+        "xpub": "xpub6EkcQSTygvxVnBP2X2fM6HY5D7wv46tWbBc54ADaypuCr47vQh1GPdPAZFdx81ou5Rp4vBnzeJT5MDWDZstzijxkHfrofXRycpt1ASfg1La",
+        "desc": "sh(wsh(sortedmulti(M,[0f056943/48h/0h/123h/1h]xpub6EkcQSTygvxVnBP2X2fM6HY5D7wv46tWbBc54ADaypuCr47vQh1GPdPAZFdx81ou5Rp4vBnzeJT5MDWDZstzijxkHfrofXRycpt1ASfg1La/0/*,...)))",
+        "_pub": "Ypub6kUxqLsLQa4M43jXJ3ux8SyP6t8dD5ZbpZmxkpP1jc7VXLW4RkZ76ouEPAZ1gMgiiXzrYFPfzBC8MfjYaoTxfTm1zUfdeqiTnHDX8raCfeg"
+    },
+    "bip48_2": {
+        "name": "p2wsh",
+        "xfp": "2A01C6B0",
+        "deriv": "m/48h/0h/123h/2h",
+        "xpub": "xpub6EkcQSTygvxVneXmk3ywiS2PFhBdiPxeMxYf6RFxHCHH36NxdcN7DjUpudCppAAxs58CG6DQLjtqZNmyC3MpgVob6wpdeATjpZZ1woX92EF",
+        "desc": "wsh(sortedmulti(M,[0f056943/48h/0h/123h/2h]xpub6EkcQSTygvxVneXmk3ywiS2PFhBdiPxeMxYf6RFxHCHH36NxdcN7DjUpudCppAAxs58CG6DQLjtqZNmyC3MpgVob6wpdeATjpZZ1woX92EF/0/*,...))",
+        "_pub": "Zpub75KE91YFZFbpup5PMS2AxgZCKRWnozdEWTEmaUKGQysSmUaKuL5WYyf2kk5UNQhhupRnddQe9GzST7crvfLoRTHTg6KtDPZiFjxBJobzcUz"
     }
 }
 ```
@@ -51,16 +73,23 @@ Here is an example, produced by the Simulator for account number 123.
 ## Notes
 
 1. The `first` address is formed by added `/0/0` onto the given derivation, and is assumed
-to be the first (non-change) receive address for the wallet.
+to be the first (non-change) receive address for the wallet. It is only present on the
+single-signature sections (`bip44`, `bip49`, `bip84`); multisig sections omit it.
+
+1a. Each section includes a `desc` field: a ready-to-import Bitcoin output descriptor
+(with `#checksum`). Single-sig descriptors use the `<0;1>/*` multipath form. Multisig
+sections (`bip48_1`, `bip48_2`, and `bip45` when present) emit a `sortedmulti(...)`
+template with `M` and a trailing `...` as placeholders, to be completed with your
+threshold and the other co-signers' keys.
 
 2. The user may specify any value (up to 9999) for the account number, and it's meant to
 segregate funds into sub-wallets. Don't assume it's zero.
 
 3. When making your PSBT files to spend these amounts, remember that the XFP of the master
-(`0F056943` in this example) is is the root of the subkey paths found in the file, and 
+(`0F056943` in this example) is the root of the subkey paths found in the file, and 
 you must include the full derivation path from master. So based on this example,
-to spend a UTXO on `tb1qc58ys2dphtphg6yuugdf3d0kufmk0tye044g3l`, the input section
-of your PSBT would need to specify `(m=0F056943)/84'/1'/123'/0/0`.
+to spend a UTXO on `bc1qhj6avwmp5lhpgqwm6dgxrf3v5lf67rjm99a8an`, the input section
+of your PSBT would need to specify `(m=0F056943)/84'/0'/123'/0/0`.
 
 4. The `_pub` value is the [SLIP-132](https://github.com/satoshilabs/slips/blob/master/slip-0132.md) style "ypub/zpub/etc" which some systems might want. It implies
 a specific address format.

docs/installing.md

@@ -1,23 +0,0 @@
-
-# Check-out and build
-
-- clone repo
-- do submodule magic in `external`
-- make top-level virtual env: `virtualenv -p python3 ENV`
-- activate it
-- then:
-
-    cd external/ckcc-protocol
-    pip install -r requirements.txt
-    pip install --editable .
-    cd ../..
-    pip install -r requirements.txt
-    pip install -r unix/requirements.txt
-
-- should give you a command-line program "ckcc" in your path
-- should be able to do:
-
-    cd unix
-    make && ./simulator.py
-
-

docs/key-teleport.md

@@ -0,0 +1,224 @@
+
+# Key Teleport
+
+Purpose: Send a small quantity of very secret data between two COLDCARD Q systems, with
+no risk of anything in the middle learning the secret.
+
+Method: ECDH and AES-256-CTR plus an extra wrapping layer, transmitted over a mixture of
+NFC, passive websites, and QR/BBQr codes.
+
+# Protocol Overview
+
+## Steps
+
+- Receiver picks an EC keypair, stores it in settings, and publishes the pubkey via a QR/NFC
+- The pubkey is encrypted by a short 8-digit numeric code, which should be
+  sent by a different channel.
+- Sender gets QR and numeric code, picks own keypair, and does ECDH to arrive at a
+  shared session key
+- Sender picks a human-readable secret which is independent of anything else (P key)
+- The secret data (perhaps a seed phrase, XPRV, secure note, full backup, etc) is
+  AES-256-CTR encrypted with P key, then encrypted + MAC added with session key
+- Data packet is sent to receiver (via BBQr), who can reconstruct the session key via ECDH
+- Prompt user for the P key to finish decoding
+- Decoded secret value is saved to Seed Vault or secure notes as appropriate
+- Receiver destroys EC keypair used in transfer
+
+### When used for PSBT Multisig
+
+- No action required on receiver
+- Sender uses the pubkey derived from pre-shared XPUB involved in the multisig wallet.
+- Same steps, but drops immediately into signing process when decoded correctly
+
+## Notes and Limitations
+
+- max 4k (after encoding) of data is possible due to HTTP limitations
+- all transfers are "data typed" and decode only on COLDCARD
+- Q model is required due to the use of QR codes to ultimately get data into the COLDCARD
+
+
+# Details
+
+## Data Type Codes
+
+The first byte encodes what the package contents (under all the encryption).
+
+- `s` - 12/18/24 words/raw master/xprv - 17-72 bytes follow, encoded in an internal format
+- `x` - XPRV mode, full details - 4 bytes (XPRV) + base58 *decoded* binary-XPRV follows
+- `n` - one or many notes export (JSON array)
+- `v` - seed vault export (JSON: one secret key but includes name, source of key)
+- `p` - binary PSBT to be signed, perhaps multisig but not required.
+- `b` - complete system backup file (text lines, internal format)
+
+## QR details
+
+BBQr is always used for the QR's involved in this process, even if
+they are short enough for a normal QR code. Because the BBQr is
+being generated by the COLDCARD embedded firmware, it will not be
+compressed and will always be Base32 encoded.
+
+New type codes for BBQr are defined for the purposes of this application:
+
+- `R` contains `(pubkey)` ... begins the process from receiver; compressed pubkey is 33 bytes
+- `S` contains `(pubkey)(data)` ... data from sender; first 33 bytes are sender's pubkey
+- `E` for Multisig PSBT: `(randint)(data)` ... randint (4 byte nonce) indicates which 
+  derived subkey from pre-shared xpub associated with receiver
+
+All the data is encrypted with the exception randint. Keep in mind
+this is a nonce value picked uniquely for each transfer. The
+receiver's pubkey is only weakly encrypted by the 8-digit numeric
+password, but is also a nonce effectively.
+
+### PSBT Key Selection
+
+When sending PSBT data, a nonce is picked at random by the sender
+in range: `0..(2^28)`
+
+This nonce is called `randint`. The receiver's pubkey will be
+
+    .../20250317/(randint)
+
+where `...` is the derivation used in the multisig wallet for the co-signer who will
+receive the package. The sender's keypair has the same sub key path assuming all
+co-signers have same derivation path from root (not required).
+
+Because both the sender and receiver already have each other's XPUB they can derive
+the appropriate pubkeys (and privkey for their side) without communicating 
+more than `randint`. The sending COLDCARD will pick a new random value each time.
+
+When receiving a multisig PSBT encrypted this way, the receiver does not need
+to do any setup (nor numeric password) and can receive a QR code at any time.
+This works because the shared multisig wallet is already setup. Receiver will
+take the nonce value (randint) and seach all pre-defined multisig wallets for
+any pubkey that can decrypt the package successfully (based on checksum inside
+first layer of ECDH encryption).
+
+The next layer of encryption (paranoid password) is unchanged.
+
+## Encryption Details
+
+AES-256-CTR is used exclusively. Session key is picked via ECDH with final
+key value being the SHA256 over 64 bytes of coordinate X (concat) Y.
+
+While ECDH is enough to assure privacy from men in the middle, we
+add an additional layer of encryption. We call this the "paranoid key" internally
+and in the UX it is called "Teleport Password".
+
+The user sees a random 8-character password, generated as a random 40-bit value, but
+shown in Base32 (8 chars) for the human to enter. We apply PBKDF2-SHA512 with
+an iteration count of 5000 to stretch that to 512 bits, of which we use half.
+The session key is used as the key for the KDF, and the entered value as salt.
+
+- ECDH arrives at session key
+- decrypt (AES-256-CTR) the binary body of message
+- verify checksum:
+    - final 2 bytes should be `== SHA256(decrypted body[0:-2])[-2:]`
+    - if not, corruption, truncation, or wrong keys
+- if that decryption is correct, then prompt user for the paranoid key (8 chars)
+- stretch that value using session key and 5000 iterations of PBKDF2-SHA512
+- use upper 256 bits and run AES-256-CTR again
+- same checksum of 2 bytes of SHA256 are found inside after decryption
+
+Encryption adds 4 bytes of overhead because of these MAC values, 
+but should catch truncation and bitrot. There are no other
+protections against truncation as length data is not transmitted.
+
+# Receiver Password
+
+When the teleport process is started, the receiver shares his pubkey
+as QR. However, we also show an 8-digit numeric password. The
+purpose of this is force the receiver to share this separately from
+the pubkey QR on another channel. The code is randomly picked, but
+only represents about 26 bits of entropy and is stretched with
+a single round of SHA256 before being used as a AES-256-CTR key
+to decrypt the pubkey. No checksum verifies correct
+decryption, so any code is accepted, and will with near-50% odds,
+decrypt to a valid pubkey.
+
+When the sender is given the receiver's pubkey via QR code, it
+prompts for the numeric code and uses it to decrypt the pubkey.
+Thus a MiTM who injects their pubkey will be detected and blocked.
+
+The "paranoid key" serves the same role in the other direction but
+it is Base32 character set, so it will not look similar or be
+confusing as to its purpose.
+
+# Web Component
+
+In order to "teleport" the contents of a QR code over NFC, we will
+publish a static website directly from an open Github repository.
+The single-page website contains javascript code which looks at the
+"hash" part of the incoming URL (`window.location.hash`) and if it
+meets the requirements, renders a large QR. The QR data must look like
+a correctly-encoded BBQr with one of the 3 type-codes above (`R` `S` or `E`).
+Otherwise the website could render any QR, which we don't want to
+support.
+
+The page will offer "copy to clipboard" features for the data inside
+the QR as a URL (ie. same URL as shown) and as an image and of course,
+the COLDCARD Q can scan from the web browser screen itself.
+
+When the BBQr data is larger than comfortable for a single QR, the
+website can split into a multi-frame BBQr. The website can
+do this without understanding the contents of the BBQr data (all
+of which is encrypted). Download options will be provided for
+single-frame QR, animated PNG, and "stacked BBQr" (a single tall
+PNG with each QR frame stacked).
+
+On the COLDCARD side, when NFC is tapped, it will offer a long URL
+to this site with the data to be transferred "after the hash".  This
+is optional since the QR can be shown on the Q itself, and would
+pass the same data.
+
+Since the website is running on Github, Coinkite does not have
+access to IP addresses or other access log details. Because the data for
+teleport is "after the hash" it is never sent to Github's servers
+but remains in the browser only. All JS resources referenced by the
+webpage will have content hashes applied to prevent interference,
+and the site will be served over SSL.
+
+Visit [keyteleport.com](https://keyteleport.com/), or an
+[example small QR](https://keyteleport.com/#B$2R0100VHT2AGUUH7KUZUUSTOWOIWHJX3XM7GA2N4BHQOXDFHXLVHVA7K6ZO)
+and [view source code](https://github.com/coinkite/keyteleport.com).
+
+# UX Details
+
+- When the receive process is started by the user, a pubkey is picked
+  and stored, so that they can come back later (after a power cycle)
+  and make use of the data encoded by the sender. However once a package
+  is decoded successfully, that key is deleted.
+
+- Sender must start by scanning the QR from a receiver. Then can pick what
+  to send, from secure notes to seeds and so on.
+
+- For PSBT multisig, user must pick a single co-signer (who hasn't already
+  signed) and the QR is prepared for that receiver. Because we
+  cannot do arbitary combining, it's best if the next signer continues
+  to teleport the updated PSBT to further signers. In other words,
+  a daisy-chain pattern is prefered to a star pattern. The signer
+  who completes the Mth (of N) signature will be able to finalize
+  the transaction, and ideally with PushTx feature, broadcast it.
+
+# Security Comments
+
+## Such short passwords?
+
+We are using 8-character passwords because we want them to be
+practical to share over non-digital channels such as a voice phone
+call, or hand-written note.
+
+It is very important to remind users that the passwords should be sent
+by a different channel from the QR itself. Best is to call up your
+other party and say the letters to them directly.
+
+## Is it safe to save image of QR to cloud?
+
+Yes, this seems safe. Of course, if you can control it, perhaps not
+a risk to accept... but the QR is encrypted via ECDH using a key
+that is forgotten after the transfer, so forward privacy is protected.
+Also your cloud service (or photo roll, chat app log, etc) will not
+have the 8-character password which is also required unpack the secrets.
+
+The QR codes themselves are fully random and do not reveal the
+identity of your COLDCARD, your on chain funds or anything linked
+to you.

docs/limitations.md

@@ -1,12 +1,12 @@
-# BIP39 Import
+# BIP-39 Import
 
-- there must be 12, 16 or 24 words in your mnemonic
+- there must be 12, 18 or 24 words in your mnemonic
 - we have only the English word list
-- ~~we do not support BIP39 passwords during import~~ (full support added in version 2.0.0)
+- we support BIP-39 passwords during import
 
 # XPRV Import
 
-- we can import a BIP32 HD-wallet root private key in XPRV format
+- we can import a BIP-32 HD-wallet root private key in XPRV format
 - it's assumed to be top-level, and we don't store the parent fingerprint or depth value
 - SLIP-132 format HD-wallet keys are also supported (xprv/yprv/zprv), but we strip
   the implied address format
@@ -14,11 +14,12 @@
 # PIN Codes
 
 - 2-2 through 6-6 in size, numeric digits only
-- pin code 999999-999999 is reserved (means 'clear pin')
+- pin code 999999-999999 was reserved (meaning 'clear pin'), but now available again
 
 # Backup Files
 
 - we don't know what day it is, so meta data on files will not have correct date/time
+- release date of the firmware version that made the file is used instead of true date
 - encrypted files produced cannot be changed, and we don't support other tools making them
 
 # Micro SD
@@ -32,7 +33,7 @@
 - with Electrum, we support classic payment addresses (p2pkh), Bech32 Segwit and P2SH/Segwit
     - however, each wallet must be of a single address type; cannot be mixed (their limitation)
     - the same Coldcard could be used in each of the three modes (we don't care about address format)
-- with Bitcoin Core (version 0.17?), we can do PSBT transactions, which support all address types
+- with Bitcoin Core (version 0.17+), we can do PSBT transactions, which support all address types
 - we don't support signing coinbase transactions, so don't mine directly into a Coldcard wallet
 
 # Max Transaction Size
@@ -41,47 +42,69 @@
     - we support transactions up to 384k-bytes in size when serialized into PSBT format
     - we can handle transactions with up to 20 inputs to be signed at one time.
     - a maximum of 250 outputs per transaction is supported (will attempt more if memory allows)
-- mk4:
+- mk4/Q:
     - we support PSBT files up to 2M bytes in size.
     - any number of inputs and outputs are supported, limited only by final transaction size (100k)
     - tested with: 250 inputs, 2000 outputs
 - bitcoin limits transactions to 100k, but there could be large input transactions
   inside the PSBT. Reduce this by using segwit signatures and provide only the
   individual UTXO ("out points").
+- every transaction needs to have at least one output, or we reject it
 
 
 # P2SH / Multisig
 
 - only one signature will be added per input. However, if needed the partly-signed 
   PSBT can be given again, and the "next" leg will be signed.
-- we do not support PSBT combining or finalizing of transactions involving
-  P2SH signatures (so the combine step must be off-device)
+- finalizing of multisig transactions involving P2SH signatures:
+    * SD/Vdisk signing exports both signed PSBT and finalized txn ready for broadcast (if txn is complete)
+    * QR/NFC outputs finalized txn ready for broadcast if txn is complete otherwise signed PSBT only
+    * USB signing requires `--finalize` parameter (as for standard single signature wallets)
+
 - we can sign for P2SH and P2WSH addresses that represent multisig (M of N) but
   we cannot sign for non-standard scripts because we don't know how to present
   that to the user for approval.
 - during USB "show address" for multisig, we limit subkey paths to
   16 levels deep (including master fingerprint)
-- max of 15 co-signers due to 520 byte script limitation in consensus layer with classic P2SH
+- max of 15 co-signers due to 1650 byte `scriptSig` limitation in policy with classic P2SH (same limit applies to segwit even though consensus allows up to 20 co-signers).
+  note: the consensus layer sets an upper bound of 520 bytes for the length of each stack element
 - (mk3) we have space for up to 8 M-of-3 wallets, or a single M-of-15 wallet. YMMV
 - only a single multisig wallet can be involved in a PSBT; can't sign inputs from two different
     multisig wallets at the same time.
-- we always store xpubs in BIP32 format, although we can read SLIP132 format (Ypub/Zpub/etc)
+- we always store xpubs in BIP-32 format, although we can read SLIP132 format (Ypub/Zpub/etc)
 - change outputs (indicated with paths, scripts in output section) must correspond to
   the active multisig wallet, and cannot be used to describe an unrelated (multisig) wallet.
 - derivation path for each cosigner must be known and consistent with PSBT
-- fixed: XFP values (fingerprints) for each of the co-signers must be unique (limitation removed)
+- XFP values (fingerprints) MUST be unique for each of the co-signers
+- multisig wallet `name` can only contain printable ASCII characters `range(32, 127)`
+
+### BIP-67
+
+- importing multisig from PSBT can ONLY create `sortedmulti(...)` multisig according to BIP-67, DO NOT use with `multi(...)`
+- creating airgapped multisig using COLDCARD as coordinator always produces `sortedmulti(...)` multisig according to BIP-67
+- COLDCARD import/export [format](https://coldcard.com/docs/multisig/#configuration-text-file-for-multisig) only supports `sortedmulti(...)` multisig according to BIP-67. To import multisig wallet with `multi(...)` use descriptor import [format](https://github.com/bitcoin/bips/blob/master/bip-0383.mediawiki)
+- encrypted COLDCARD backups that contains multisig wallets with `multi(...)` MUST only be restored on firmware versions with `multi(...)` support
+- all imported `multi(...)` must differ in keys (same as `sortedmulti(...)`). If `wsh(multi(2,A,B))` is already registered, `wsh(multi(2,B,A))` will be rejected upon import as duplicate, even thought they are actually different script/wallet.
+- just BIP67 difference is also treated as duplicate. If `wsh(multi(2,A,B)` is registered, `wsh(sortedmulti(2,A,B))` will be rejected as duplicate and vice-versa.
 
 # SIGHASH types
 
-- only `SIGHASH_ALL` is supported at this time
-- in time, we will add support for others, especially to support Coinjoin usage
+- all sighash flags are supported:
+    - `ALL`
+    - `NONE`
+    - `SINGLE`
+    - `ALL|ANYONECANPAY`
+    - `NONE|ANYONECANPAY`
+    - `SINGLE|ANYONECANPAY`
+- any value other than ALL will cause a warning to be shown to user
+- by default, we reject `NONE` and `NONE|ANYONECANPAY` but there is a setting to allow
 
 # U2F Protocol / Web Access to USB / WebUSB
 
 - we do not support U2F protocol, WebUSB or any other means for random websites to talk to us
 - only native desktop/mobile apps, or helpers for those, will be able to talk USB to Coldcard
 
-# Policy Stuff
+# Fee Limits / Warnings
 
 - Coldcard will, by default, reject any txn that pays a fee of more than 10% of its total
   value to miners. This limit is a setting: 10% (default), 25%, 50% or 'no limit'.
@@ -94,9 +117,9 @@
 
 # Change Outputs
 
-We will hide transaction outputs if they are "change" back into same wallet, however:
+We will summarize transaction outputs as "change" back into same wallet, however:
 
-- PSBT must specify BIP32 path in corresponding output section for us to treat as change
+- PSBT must specify BIP-32 path in corresponding output section for us to treat as change
 - for p2sh-wrapped segwit outputs, redeem script must be provided when needed
 - any incorrect values here are assumed to be fraud attempts, and are highlighted to user
 - the _redeemScript_ for `p2wsh-p2sh` is optional, but if provided must be
@@ -117,31 +140,84 @@ We will hide transaction outputs if they are "change" back into same wallet, how
 
 - key derivatation paths must be 12 or less in depth (`MAX_PATH_DEPTH`)
 
+# Pay-to-Pubkey
 
-# NFC Feature (Mk4)
+- although we have some code for "pay to pubkey" (P2PK not P2PKH), it is untested
+  and unused since this style of payment address is obsolete and largely unused today
+
+# NFC Feature
 
 - can share up to 8000 bytes of PSBT or signed transaction data.
 - NFC-V (ISO-15693) radio/modulation is common on mobile phones but very rare on desktops
 
-# Fast Wipe (Mk4)
+# Fast Wipe
 
 - each use of "fast wipe" feature consumes a MCU key slot, of which there are 256.
 - use _Advanced > Danger Zone > MCU Key Slots_ to view usage
 
-# Trick Pins (Mk4)
+# Trick Pins
 
 - "deltamode" PIN must be same length as true pin, and differ only in final 4 positions.
-- there are 14 trick "slots" 
-- duress wallets consume 2 slots (or 3 slots for legacy duress wallet)
+- there are 14 trick "slots", but on mk4, we avoid slot 10, so 13 available. (Q: 14)
+- duress wallets consume 2 slots (or 3 slots for legacy duress wallet) which must be contiguous
 - when restoring trick pins from backup files, "forgotten" pins are not restored,
   and any trick pin which matches the true PIN of the restored system will be dropped
 - deltamode PIN requirements are checked during wallet restore, and if the new true PIN
   is not compatible, the deltamode trick PIN is dropped and not restored
 - duress wallets are supported when derived from 24- or 12-word seed phrases
 
-# Debug Serial Port (Mk4)
+# Debug Serial Port
 
 - virtual USB serial port disabled completely by default, and even if enabled
   in Danger Zone, only echos output, and does not accept any input
 - use hardware serial port for interactive REPL access (3.3v TTL levels)
 
+# BBQr Scanning (Q)
+
+- files up to 2MiB in size can be accepted
+- when 14 or less parts, we display status of each part, if more, just percent complete
+
+# QR Scanning (Q)
+
+- if not BBQr (or sent as unicode inside BBQr) we auto detect these data types:
+    - PSBT in Base64 or hex
+    - Wire Transaction in Base64 or hex
+    - XPRV, XPUB, bare payment addresses, BIP-21 invoices
+    - seed words (truncated, or full)
+    - SeedQR (but not Compact SeedQR)
+- for Base58, Bech32 encoded values, if checksum is wrong then it is shown as text
+- binary QR codes are not supported
+- when pasting into a secure note, if the QR's data is > 60 chars long, we assume done
+
+# Secure Notes & Passwords (Q)
+
+- when Q picks a password for you (using F1 thru F5), the entropy is 126 bits or more,
+  except F3 which makes an easier to type password of around 48 bits entropy.
+- Title, Sitename and Username fields are limited to 32 characters in length.
+- Passwords are limited to 128 characters.
+- Note text is unlimited, but storing very large notes may affect performance system-wide.
+- Q Backup files restored onto Mk4 will lose their notes, since notes feature is not supported.
+
+# Address Ownership
+
+- only the first 1528 addresses (764 each from internal and external (change/not) paths)
+  are considered
+- if you have used an sub-account, without ever exploring it in the Address Explorer, nor
+  signing a PSBT with those account numbers, we do not search it.
+- does not search Seed Vault, you'll need to load each of those and re-search
+- if you have an XFP collision between multiple wallets in SeedVault (ie. two wallets
+  with same descriptors, but different seeds) you will get false negatives
+
+# Spending Policy
+
+- (Cosign mode) only 12 or 24 word seeds (not XPRV) are accepted for "key C"
+- velocity limit:
+    - based on a max magnitude per txn, and a required minimum block height
+      gap, based on previous `nLockTime` value in last-signed PSBT.
+    - if you sign a transaction, but never broadcast it, you will still have to wait out 
+      the velocity policy.
+    - PSBT creator must put in `nLockTime` block heights (most already do to avoid fee sniping)
+- maximum of 25 whitelisted addresses can be stored
+- Web2FA: any number of mobile devices can be enrolled, but all will have the same shared secret
+- any warning from the PSBT, such as huge fees, will cause the transaction to be rejected
+

docs/memory-map.md

@@ -38,7 +38,7 @@ directly from python programs.
 
 | Start         | Size      | Notes
 |---------------|-----------|--------------------------
-| 0x0800 0000   | 128k      | Bootloader code, including reset vector. See `stm32/mk4-bootloader`
+| 0x0800 0000   | 112k      | Bootloader code, including reset vector. See `stm32/mk4-bootloader`
 | 0x0801 c000   | 8k        | Sensitive "pairing secrets" for SE1 and SE2
 | 0x0801 e000   | 8k        | MCU keys, consumable; 256 32-bit write-once slots.
 | 0x0802 0000   | 16k       | Interrupt handlers, file header (Micropython and Coldcard code)

docs/menu-tree.txt

@@ -2,11 +2,6 @@
   Choose PIN Code
   Advanced/Tools
     View Identity
-    Upgrade Firmware
-      Show Version
-      From MicroSD
-      From VirtDisk [IF VIRTDISK ENABLED]
-      Bless Firmware
     Paper Wallets
     Perform Selftest
     Secure Logout
@@ -16,71 +11,95 @@
 
 [IF BLANK WALLET]
   New Seed Words
-    24 Word (default)
-    12 Word
-    24 Word Dice Roll
-    12 Word Dice Roll
-  Import Existing
-    24 Words
-      [SEED WORD MENUS]
-    18 Words
-      [SEED WORD MENUS]
     12 Words
-      [SEED WORD MENUS]
+    24 Words
+    Advanced
+      12 Word Dice Roll
+      24 Word Dice Roll
+  Import Existing
+    12 Words
+    [SEED WORD ENTRY]
+    18 Words
+    [SEED WORD ENTRY]
+    24 Words
+    [SEED WORD ENTRY]
+    Scan QR Code [IF QR SCANNER]
     Restore Backup
     Clone Coldcard
     Import XPRV
+    Tapsigner Backup
     Seed XOR
+  Migrate Coldcard
+  Key Teleport (start)
   Help
   Advanced/Tools
     View Identity
-    Upgrade Firmware
+    Temporary Seed
+      Generate Words
+        12 Words
+        24 Words
+        12 Word Dice Roll
+        24 Word Dice Roll
+      Import from QR Scan [IF QR SCANNER]
+      Import Words
+        12 Words
+        18 Words
+        24 Words
+        Import via NFC [IF NFC ENABLED]
+      Import XPRV
+      Tapsigner Backup
+      Coldcard Backup
+      Restore Seed XOR
+    Upgrade Firmware [IF NOT TMP SEED]
       Show Version
       From MicroSD
       From VirtDisk [IF VIRTDISK ENABLED]
-      Bless Firmware
     File Management
       Verify Backup
       List Files
+      Verify Sig File
       NFC File Share [IF NFC ENABLED]
+      BBQr File Share [IF QR SCANNER]
+      QR File Share [IF QR SCANNER]
       Format SD Card
       Format RAM Disk [IF VIRTDISK ENABLED]
+    Key Teleport (start)
     Paper Wallets
     Perform Selftest
     I Am Developer.
       Serial REPL
-      Wipe LFS
       Warm Reset
-      Restore Txt Bkup
+      Restore Bkup
+      Reflash GPU [IF QWERTY KEYBOARD]
     Secure Logout
   Settings
     Login Settings
       Change Main PIN
-      PIN Options
-      Trick PINs
-        Trick PINs:
-        ↳22-22
-        Add New Trick
-        Add If Wrong
-        Delete All
       Set Nickname
-      Scramble Keypad
+      Scramble Keys
       Kill Key
       Login Countdown
         Disabled
+         5 minutes
         15 minutes
         30 minutes
-         4 hours
          1 hour
-         5 minutes
+         2 hours
+         4 hours
          8 hours
         12 hours
-         2 hours
-         3 days
-        48 hours
-         1 week
         24 hours
+        48 hours
+         3 days
+         1 week
         28 days later
+      MicroSD 2FA [IF SECRET AND NOT TMP SEED]
+        Add Card
+        Check Card
+        Remove Card #1
+      Calculator Login [IF QWERTY KEYBOARD]
+        Default Off
+        Calculator Login
       Test Login Now
     Hardware On/Off
       USB Port
@@ -93,13 +112,11 @@
       NFC Sharing
         Default Off
         Enable NFC
-    Multisig Wallets
-      (none setup yet)
-      Import from SD
-      Export XPUB
-      Create Airgapped
-      Trust PSBT?
-      Skip Checks?
+    NFC Push Tx
+      coldcard.com
+      mempool.space
+      Custom URL...
+      Disable
     Display Units
       BTC
       mBTC
@@ -118,17 +135,106 @@
        4 hours
        8 hours
        Never
+    Idle Timeout (on battery) [IF BATTERIES]
+       30 seconds
+       60 seconds
+       2 minutes
+       5 minutes
+      10 minutes
+      15 minutes
+      30 minutes
+       1 hour
+       4 hours
+       Never
+    LCD Brightness (on battery) [IF BATTERIES]
+      25%
+      50%
+      60%
+      70%
+      80%
+      90%
+      95% (default)
+      100%
     Delete PSBTs
       Default Keep
       Delete PSBTs
+    Buried Settings
+      Home Menu XFP [IF SECRET AND NOT TMP SEED]
+        Only Tmp
+        Always Show
+      Menu Wrapping
+        Default
+        Always Wrap
+  [QR key shortcut] [IF QR SCANNER]
 ---
 
 [NORMAL OPERATION]
   Ready To Sign
-  Passphrase
+  Passphrase [IF WORD BASED SEED]
+    Restore Saved
+      c*******
+        [3A14F788]
+        Restore
+        Delete
+    Edit Phrase
+  Scan Any QR Code [IF QR SCANNER]
   Start HSM Mode [IF HSM POLICY]
   Address Explorer
-  Secure Logout
+    Classic P2PKH
+     ↳ mtHSVByP9EYZ⋯Vm19gvpecb5R
+    P2SH-Segwit
+     ↳ 2NCAJ5wD4Gvm⋯NphNU8UYoEJv
+    Segwit P2WPKH
+     ↳ tb1qupyd58nd⋯vu9jtdyws9n9
+    Applications
+      Samourai
+        Post-mix
+        Pre-mix
+      Wasabi
+    Account Number
+    Custom Path
+    CC-2-of-4
+  Secure Notes & Passwords [IF ENBALED] [MAYBE]
+    1: note0
+      "note0"
+      View Note
+      Edit
+      Delete
+      Export
+      Sign Note Text
+    2: secret-PWD
+      "secret-PWD"
+      ↳ satoshi
+      ↳ abc.org
+      View Password
+      Send Password [MAYBE]
+      Export
+      Edit Metadata
+      Delete
+      Change Password
+      Sign Note Text
+    New Note
+    New Password
+    Export All
+    Sort By Title
+    Import
+  Type Passwords [MAYBE]
+  Seed Vault [MAYBE]
+     1: [7126EB3C]
+      [7126EB3C]
+      Use This Seed
+      Rename
+      Delete
+     2: [CCEE13B9]
+      [CCEE13B9]
+      Use This Seed
+      Rename
+      Delete
+     3: [03EE9989]
+      [03EE9989]
+      Use This Seed
+      Rename
+      Delete
   Advanced/Tools
     Backup
       Backup System
@@ -136,101 +242,229 @@
       Restore Backup
       Clone Coldcard
     Export Wallet
+      Sparrow
+      Cove
       Bitcoin Core
+      Nunchuk
+      Bull Bitcoin
+      Blue Wallet
       Electrum Wallet
       Wasabi Wallet
-      Unchained Capital
+      Fully Noded
+      Unchained
+      Theya
+      Bitcoin Safe
+      Zeus
+      Samourai Postmix
+      Samourai Premix
+      Descriptor
       Generic JSON
       Export XPUB
         Segwit (BIP-84)
         Classic (BIP-44)
-        P2WPKH/P2SH (49)
+        P2WPKH/P2SH (BIP-49)
         Master XPUB
         Current XFP
+      Key Expression
       Dump Summary
-    Upgrade Firmware
+    Upgrade Firmware [IF NOT TMP SEED]
       Show Version
       From MicroSD
       From VirtDisk [IF VIRTDISK ENABLED]
-      Bless Firmware
     File Management
       Verify Backup
       Backup System
       Export Wallet
+        Sparrow
+        Cove
         Bitcoin Core
+        Nunchuk
+        Bull Bitcoin
+        Blue Wallet
         Electrum Wallet
         Wasabi Wallet
-        Unchained Capital
+        Fully Noded
+        Unchained
+        Theya
+        Bitcoin Safe
+        Zeus
+        Samourai Postmix
+        Samourai Premix
+        Descriptor
         Generic JSON
         Export XPUB
           Segwit (BIP-84)
           Classic (BIP-44)
-          P2WPKH/P2SH (49)
+          P2WPKH/P2SH (BIP-49)
           Master XPUB
           Current XFP
+        Key Expression
         Dump Summary
       Sign Text File
-      Clone Coldcard
+      Batch Sign PSBT
+      Teleport Multisig PSBT
       List Files
+      Verify Sig File
       NFC File Share [IF NFC ENABLED]
+      BBQr File Share [IF QR SCANNER]
+      QR File Share [IF QR SCANNER]
+      Clone Coldcard
       Format SD Card
       Format RAM Disk [IF VIRTDISK ENABLED]
-    Derive Seed B85
+    Secure Notes & Passwords [IF QWERTY KEYBOARD]
+      1: note0
+        "note0"
+        View Note
+        Edit
+        Delete
+        Export
+        Sign Note Text
+      2: secret-PWD
+        "secret-PWD"
+        ↳ satoshi
+        ↳ abc.org
+        View Password
+        Send Password [MAYBE]
+        Export
+        Edit Metadata
+        Delete
+        Change Password
+        Sign Note Text
+      New Note
+      New Password
+      Export All
+      Sort By Title
+      Import
+    Derive Seeds (BIP-85)
     View Identity
+    Temporary Seed
+      Generate Words
+        12 Words
+        24 Words
+        12 Word Dice Roll
+        24 Word Dice Roll
+      Import from QR Scan [IF QR SCANNER]
+      Import Words
+        12 Words
+        18 Words
+        24 Words
+        Import via NFC [IF NFC ENABLED]
+      Import XPRV
+      Tapsigner Backup
+      Coldcard Backup
+      Restore Seed XOR
+    Key Teleport (start)
+    Spending Policy [IF SECRET AND NOT TMP SEED]
+      Single-Signer [IF SECRET AND NOT TMP SEED]
+      Co-Sign Multisig (CCC) [IF NOT TMP SEED]
+      HSM Mode [IF HSM AND SECRET]
+        Default Off
+        Enable
+      User Management [MAYBE]
     Paper Wallets
-    User Management
-      (no users yet)
+    WIF Store
+    NFC Tools [IF NFC ENABLED]
+      Sign PSBT
+      Show Address
+      Sign Message
+      Verify Sig File
+      Verify Address
+      File Share
+      Import Multisig
+      Push Transaction [IF PUSHTX ENABLED]
     Danger Zone
       Debug Functions
       Seed Functions
         View Seed Words
         Seed XOR
-          Split Existing
+          Split Existing [IF WORD BASED SEED]
           Restore Seed XOR
-        Destroy Seed
-        Lock Down Seed
+        Destroy Seed [IF SECRET AND NOT TMP SEED]
+        Lock Down Seed [MAYBE]
+        Export SeedQR [IF WORD BASED SEED]
       I Am Developer.
         Serial REPL
-        Wipe LFS
         Warm Reset
-        Restore Txt Bkup
+        Restore Bkup
+        BKPW Override
+        Reflash GPU [IF QWERTY KEYBOARD]
+      Seed Vault [IF SECRET AND NOT TMP SEED]
+        Default Off
+        Enable
       Perform Selftest
       Set High-Water
       Wipe HSM Policy [IF HSM POLICY]
       Clear OV cache
+      Clear Address cache
+      Sighash Checks
+        Default: Block
+        Warn
       Testnet Mode
         Bitcoin
-        Testnet3
+        Testnet4
+        Regtest
+      AE Start Index
+        Default Off
+        Enable
+      B85 Idx Values
+        Default Off
+        Unlimited
       Settings Space
       MCU Key Slots
+      Bless Firmware
+      Wipe LFS
+      Nuke Device
   Settings
     Login Settings
       Change Main PIN
-      PIN Options
-      Trick PINs
+      Trick PINs [IF SECRET AND NOT TMP SEED]
         Trick PINs:
-        ↳22-22
+        ↳11-11
+          PIN 11-11
+          ↳Bricks CC
+          Hide Trick
+          Delete Trick
+          Change PIN
+        ↳333-3334
+          PIN 333-3334
+          ↳Duress Wallet
+          Activate Wallet
+          Hide Trick
+          Delete Trick
+          Change PIN
+        ↳WRONG PIN
+          After 3 wrong:
+          ↳Wipes seed
+          ↳Reboots
+          Hide Trick
+          Delete Trick
         Add New Trick
-        Add If Wrong
         Delete All
       Set Nickname
-      Scramble Keypad
+      Scramble Keys
       Kill Key
       Login Countdown
         Disabled
+         5 minutes
         15 minutes
         30 minutes
-         4 hours
          1 hour
-         5 minutes
+         2 hours
+         4 hours
          8 hours
         12 hours
-         2 hours
-         3 days
-        48 hours
-         1 week
         24 hours
+        48 hours
+         3 days
+         1 week
         28 days later
+      MicroSD 2FA [IF SECRET AND NOT TMP SEED]
+        Add Card
+        Check Card
+        Remove Card #1
+      Calculator Login [IF QWERTY KEYBOARD]
+        Default Off
+        Calculator Login
       Test Login Now
     Hardware On/Off
       USB Port
@@ -244,12 +478,30 @@
         Default Off
         Enable NFC
     Multisig Wallets
-      (none setup yet)
-      Import from SD
+      2/4: CC-2-of-4
+        "CC-2-of-4"
+        View Details
+        Delete
+        Coldcard Export
+        Electrum Wallet
+        Descriptors
+          View Descriptor
+          Export
+          Bitcoin Core
+      Import
       Export XPUB
       Create Airgapped
       Trust PSBT?
       Skip Checks?
+      Full Address View?
+        Partly Censor
+        Show Full
+      Unsorted Multisig?
+    NFC Push Tx
+      coldcard.com
+      mempool.space
+      Custom URL...
+      Disable
     Display Units
       BTC
       mBTC
@@ -268,17 +520,205 @@
        4 hours
        8 hours
        Never
+    Idle Timeout (on battery) [IF BATTERIES]
+       30 seconds
+       60 seconds
+       2 minutes
+       5 minutes
+      10 minutes
+      15 minutes
+      30 minutes
+       1 hour
+       4 hours
+       Never
+    LCD Brightness (on battery) [IF BATTERIES]
+      25%
+      50%
+      60%
+      70%
+      80%
+      90%
+      95% (default)
+      100%
     Delete PSBTs
       Default Keep
       Delete PSBTs
+    Keyboard EMU
+      Default Off
+      Enable
+    Buried Settings
+      Home Menu XFP [IF SECRET AND NOT TMP SEED]
+        Only Tmp
+        Always Show
+      Menu Wrapping
+        Default
+        Always Wrap
+  Secure Logout
+  [NFC key shortcut] [IF NFC ENABLED]
+    Sign PSBT
+    Show Address
+    Sign Message
+    Verify Sig File
+    Verify Address
+    File Share
+    Import Multisig
+    Push Transaction [IF PUSHTX ENABLED]
 ---
 
 [FACTORY MODE]
   Bag Me Now
+  Version: 5.x.x
   DFU Upgrade
-  Show Version
   Ship W/O Bag
   Debug Functions
   Perform Selftest
 ---
 
+[SSSP]
+  Ready To Sign
+  Passphrase [IF WORD BASED SEED & SSSP RELATED KEYS ENABLED]
+    Restore Saved
+      c*******
+        [3A14F788]
+        Restore
+        Delete
+    Edit Phrase
+  Scan Any QR Code [IF QR SCANNER]
+  Address Explorer
+    Classic P2PKH
+     ↳ mtHSVByP9EYZ⋯Vm19gvpecb5R
+    P2SH-Segwit
+     ↳ 2NCAJ5wD4Gvm⋯NphNU8UYoEJv
+    Segwit P2WPKH
+     ↳ tb1qupyd58nd⋯vu9jtdyws9n9
+    Applications
+      Samourai
+        Post-mix
+        Pre-mix
+      Wasabi
+    Account Number
+    Custom Path
+    CC-2-of-4
+  Secure Notes & Passwords[IF ENABLED & SSSP ALLOW NOTES]
+    1: note0
+      "note0"
+      View Note
+      Sign Note Text
+    2: secret-PWD
+      "secret-PWD"
+      ↳ satoshi
+      ↳ abc.org
+      View Password
+      Send Password [MAYBE]
+      Sign Note Text
+  Type Passwords [MAYBE]
+  Seed Vault[IF ENABLED & SSSP RELATED KEYS ENABLED]
+     1: [7126EB3C]
+      [7126EB3C]
+      Use This Seed
+     2: [CCEE13B9]
+      [CCEE13B9]
+      Use This Seed
+     3: [03EE9989]
+      [03EE9989]
+      Use This Seed
+  Advanced/Tools
+    File Management
+      Sign Text File
+      Batch Sign PSBT
+      List Files
+      Export Wallet
+        Sparrow
+        Cove
+        Bitcoin Core
+        Nunchuk
+        Bull Bitcoin
+        Blue Wallet
+        Electrum Wallet
+        Wasabi Wallet
+        Fully Noded
+        Unchained
+        Theya
+        Bitcoin Safe
+        Zeus
+        Samourai Postmix
+        Samourai Premix
+        Descriptor
+        Generic JSON
+        Export XPUB
+          Segwit (BIP-84)
+          Classic (BIP-44)
+          P2WPKH/P2SH (BIP-49)
+          Master XPUB
+          Current XFP
+        Key Expression
+        Dump Summary
+      Verify Sig File
+      NFC File Share [IF NFC ENABLED]
+      BBQr File Share [IF QR SCANNER]
+      QR File Share [IF QR SCANNER]
+      Format SD Card
+      Format RAM Disk [IF VIRTDISK ENABLED]
+    Export Wallet
+      Sparrow
+      Cove
+      Bitcoin Core
+      Nunchuk
+      Bull Bitcoin
+      Blue Wallet
+      Electrum Wallet
+      Wasabi Wallet
+      Fully Noded
+      Unchained
+      Theya
+      Bitcoin Safe
+      Zeus
+      Samourai Postmix
+      Samourai Premix
+      Descriptor
+      Generic JSON
+      Export XPUB
+        Segwit (BIP-84)
+        Classic (BIP-44)
+        P2WPKH/P2SH (BIP-49)
+        Master XPUB
+        Current XFP
+      Key Expression
+      Dump Summary
+    Teleport Multisig PSBT [MAYBE]
+    View Identity
+    Temporary Seed [IF SSSP RELATED KEYS ENABLED]
+      Import from QR Scan [IF QR SCANNER]
+      Import Words
+        12 Words
+        18 Words
+        24 Words
+        Import via NFC [IF NFC ENABLED]
+      Import XPRV
+      Tapsigner Backup
+      Coldcard Backup
+      Restore Seed XOR
+    Paper Wallets
+    WIF Store
+    NFC Tools [IF NFC ENABLED]
+      Sign PSBT
+      Show Address
+      Sign Message
+      Verify Sig File
+      Verify Address
+      File Share
+      Push Transaction [IF PUSHTX ENABLED]
+    Show Firmware Version
+    Destroy Seed [IF SECRET AND NOT TMP SEED]
+  Secure Logout
+  EXIT TEST DRIVE [MAYBE]
+  [NFC key shortcut] [IF NFC ENABLED]
+    Sign PSBT
+    Show Address
+    Sign Message
+    Verify Sig File
+    Verify Address
+    File Share
+    Push Transaction [IF PUSHTX ENABLED]
+---
+

docs/microsd-2fa.md

@@ -0,0 +1,100 @@
+
+# MicroSD as a Second Factor for Login
+
+When enabled, this feature requires a specially prepared MicroSD
+card to be inserted during login process. After correct PIN is
+provided, if card slot is empty or unknown card present, the seed
+is wiped.
+
+## How it Works
+
+To "enroll" a card, a small encrypted file is written to the card.
+
+During login, after the correct (true) PIN is entered, we use
+the master secret to construct an AES key which is used to decrypt
+the file found on the card. If the file is JSON and contains a nonce,
+we check that in our list of acceptable cards.
+
+The AES key includes the master secret and also a hash of the
+unique serial number of the card, retrieved using low-level 
+protocols. This prevents moving the file to another card.
+
+To allow the same card to unlock multiple Coldcards, we write the
+file using a filename derived from the serial number of the Coldcard
+(hashed). Thus there could be a number of 2FA-enabling files on a
+single card.
+
+The file name starts with a dot, and has extension `.2fa`. Your
+tools may or may not hide it from you based on Unix filename
+conventions. Reformating the card will certainly remove this file,
+so keep that in mind when managing your "special" cards.
+
+If using COLDCARD Q and both card slot are populated during login
+make sure that enrolled card is in top slot (slot A).
+
+## Menu Settings
+
+See menu in: `Settings -> Login Settings -> MicroSD 2FA`
+
+The option is enabled only once the main secret is picked. It cannot
+be used with ephemeral seeds, as that secret will not be in effect
+during boot time.
+
+The menu initially contains only "Add Card". Once one or more
+cards are enabled (and the feature is activated), additional
+options appear: "Check Card" and "Remove Card #N" (for each
+enrolled card).
+
+"Check Card" validates the card inserted and indicates if it would 
+be accepted or not.
+
+Use "Remove Card #N" is remove cards from the approved list. When
+the last card is removed, the feature is disabled and no card will
+be required for login. Access to the card in question is not required
+to remove it.
+
+## During Login
+
+After the PIN is entered, and if it is the true PIN (or the main
+code thinks it is, in Delta Mode or Duress Wallet cases) the main
+settings are read. After this point, if there are one or more card
+enrolled, then the check is performed. If the slot is empty or
+the card fails the check, a fast wipe of the seed is done and shown
+on screen. The memory is wipe and system stops. You must power cycle
+to continue.
+
+## Tricky Thinking
+
+Because settings are encrypted by the master seed, if you have a
+duress wallet, it could have required cards set as well. Generally,
+we do not see a good use for this, and assume that typically only
+the "true" PIN will have required cards associated with it. Remember
+any Trick PIN can wipe the seed directly.
+
+In Delta Mode, the usual card policy is in effect. However, if you
+are relying on this 2FA feature to wipe the seed in a case of duress,
+there doesn't seem to be any need for Delta Mode.
+
+## Duress Defenses
+
+We recommend simply keeping no card in your Coldcard once activating
+this feature. Your attacker, or yourself under duress, will login
+normally and trigger this defense without you taking any explicit
+action.
+
+If you were being forced to prepare a PSBT under duress, you can
+choose which SD card to use (so pick a normal one, which isn't
+enrolled) and you may also have a chance to clear your card of the
+special file. Either way would be an opportunity to ensure the
+automatic wipe occurs, even as you comply and provide the PIN code.
+
+Your enrolled SD cards can also be stored at another location away
+from your Coldcard. This could be a bank safety deposit box, since
+it contains no sensitive data.
+
+If you are closely surveilled when logging and using your Coldcard,
+the PIN code might already be known to your attacker. However, there
+is no indication on the screen during a normal (successful) login
+that this feature is in effect, so they would not know if the SD
+card was inserted by chance or necessity.
+

docs/msg-signing.md

@@ -0,0 +1,62 @@
+# COLDCARD Message Signing 
+
+COLDCARD can sign messages send to it via USB with the help of `ckcc` utility, 
+sign messages provided via specially crafted file on SD card or Vdisk, 
+and NFC-equipped models (Mk4, Mk5, and Q) can also sign messages sent to COLDCARD via NFC.
+The resulting signature can be returned over SD card/Vdisk, NFC, or — on Q — as a QR code.
+
+Signature format follows [BIP-0137](https://github.com/bitcoin/bips/blob/master/bip-0137.mediawiki) specification.
+COLDCARD Mk3 and COLDCARD Mk4 up to version `5.1.0` used compressed P2PKH header byte for all script types.
+From version `5.1.0` correct header byte is used for corresponding script type.
+
+### Verification
+
+From version `5.1.0` users can verify signed messages directly on the device.
+If signature file is on SD card or Virtual disk `Advanced/Tools -> File Management -> Verify Sig File`. In case
+signature file is detached signature of signed export (or any other file), COLDCARD can check if digest of file 
+specified in the message matches contents of file. This requires file signed to be  available on SD card or Vdisk.
+File size limit for signature files is approximately 10KB.
+If signature file is imported via NFC `Advance/Tools -> NFC Tools -> Verify Sig File`.
+To cross-verify COLDCARD verification use https://www.verifybitcoinmessage.com/ as it supports multiple script types.
+Bitcoin core can only verify P2PKH.
+
+## Signed Exports
+
+From version `5.1.0` most of SD card and Virtual disk exports are accompanied by detached signature file.
+If exported file name is `addresses.csv` signature file name will be `addresses.sig`.
+
+### Message construction and signature file format
+
+1. contents of the exported file are hashed with single SHA256 hash
+2. `msg = hash from step 1. + two spaces + exported filename (basename)`
+3. msg from step 2. is hashed again with Bitcoin msg hash `"Bitcoin Signed Message:" + ser_compact_size(len(msg)) + msg`
+4. detached signature file format:
+```text
+-----BEGIN BITCOIN SIGNED MESSAGE-----
+f1591bfb04a89f723e1f14eb01a6b2f6f507eb0967d0a5d7822b329b98018ae4  coldcard-export.json
+-----BEGIN BITCOIN SIGNATURE-----
+mtHSVByP9EYZmB26jASDdPVm19gvpecb5R
+IFOvGVJrm31S0j+F4dVfQ5kbRKWKcmhmXIn/Lw8iIgaCG5QNZswjrN4X673R7jTZo1kvLmiD4hlIrbuLh/HqDuk=
+-----END BITCOIN SIGNATURE-----
+```
+
+### What Is Signed
+
+1. **Single sig address explorer exports:** Signed by the key corresponding to the first (0th) address on the exported list.
+2. **Specific single sig exports:** Signed by the key corresponding to the external address at index zero of chosen application specific derivation `m/<app_deriv>h/<coin_type>'h/<account>h/0/0`.
+    * Bitcoin Core
+    * Electrum Wallet
+    * Wasabi Wallet
+    * Samourai Postmix
+    * Samourai Premix
+    * Descriptor
+3. **Generic single sig exports:** Signed by key that corresponds to first (0th) external address at derivation `m/44h/<coin_type>h/<account>h/0/0`.
+    * Lily Wallet
+    * Generic JSON
+    * Dump Summary
+4. **BIP85 derived entropy exports:** Signed by path that corresponds to specific BIP85 application.
+5. **Paper wallet exports:** Signed by key and address exported as paper wallet itself.
+6. **Multisig exports:** public keys are encoded as P2PKH address for all multisg signature exports
+    * Multisig wallet descriptor: signed by the key corresponding to the first external address of own enrolled extended key `my_key/0/0`
+    * Generic XPUBs export: signed by the key corresponding to the first external address of own standard P2WSH derivation `m/48h/<coin_type>h/<account>h/2h/0/0`
+    * Multisig address explorer export: Signed by own key at the same derivation as first (0th) row on exported list. `my_key/<change>/<start_index>`

docs/nfc-coldcard.md

@@ -1,6 +1,29 @@
-# NFC and Coldcard Mk4
+# NFC and Coldcard
 
-(Applies to Coldcard Mk4 only)
+(Applies to NFC-equipped models: Mk4, Mk5, and Q)
+
+## Usage
+
+The NFC antenna location depends on the hardware:
+
+- **Mk4**: a PCB trace loop, centered under number `8` on the keypad.
+- **Mk5**: a discrete coil (`L6`) in the **top-right corner** of the device
+- **Q1**: a flexible "sticker" antenna behind the display. The green LED below the
+  bottom-right of the display (`D12`) lights up while an NFC transfer is active —
+  it is the activity indicator, not the antenna.
+
+![nfc tap sweet-spots per model](nfc-tap-locations.png)
+
+Before using NFC,
+it is important to locate the position of NFC antenna on your device and point it 
+correctly towards the Coldcard NFC antenna. Picture below shows an example with iPhone
+that has NFC antenna located at the top right edge. The NFC smartphone antenna 
+can be positioned almost anywhere on the device, but mostly on the top, middle, 
+or bottom of the back side of the phone, and it is rarely indicated on the phone case. 
+It is always best to look up your specific phone model on the internet to find 
+the exact antenna location.
+
+![iphone_nfc](iphone_nfc.jpg)
 
 ## Standards Background
 
@@ -23,7 +46,7 @@ in general. Good interoperability is critical with radio standards.
 
 ## Lower Layers
 
-The Coldcard Mk4 has an chip that acts as a Type 5 NFC tag.  The
+The Coldcard has a chip that acts as a Type 5 NFC tag.  The
 radio standard is called "NFC-V" or ISO-15693, and operates on a
 13.56 Mhz carrier wave.
 
@@ -45,15 +68,19 @@ unless we are actively sharing something. We disable the "energy
 harvesting" features of the chip, so it will not do anything when
 the Coldcard is powered-down, regardless of the NFC setting.
 
-If the above is not enough for you, the antenna can be destroyed
-by cutting the trace labeled "NFC" inside the hole for the MicroSD
-card. Use the point of a sharp knife to cut and peel up the trace.
+If the above is not enough for you, the antenna can be destroyed:
+
+- **Mk4**: cut the trace labeled "NFC" inside the hole for the MicroSD card,
+  using the point of a sharp knife to cut and peel up the trace.
+- **Mk5**: has no such trace — its antenna is the discrete coil `L6` in the
+  top-right corner, which would have to be physically removed instead.
+- **Q1**: cut the trace labeled "NFC DATA" under the batteries.
 
 The NFC traffic is not encrypted and is subject to eavesdropping.
 While the NFC feature is active, your Coldcard can be uniquely
 identified because the NFC protocol requires a unique ID (64 bits)
 that is defined by the NFC tag chip and shared automatically as
-part of the anti-collion protocol. Again, that happens only during
+part of the anti-collision protocol. Again, that happens only during
 active transfers, not when idle.
 
 ## Desktop Testing

docs/nfc-pushtx.md

@@ -0,0 +1,103 @@
+# NFC Push Tx
+
+This feature allows single-tap broadcast of the freshly-signed transaction.
+
+`PSBT ==[SD|QR|NFC]==> COLDCARD signed TXN ==[NFC tap]==> Phone Browser ==> Server TXN Broadcast`
+
+Once enabled with a URL, the COLDCARD will show the NFC animation
+after signing the transaction. When the user taps their phone, the
+phone will see an NFC tag with URL inside. That URL contains the
+signed transaction ready to go, and once opening in the mobile
+browser, that URL will load. The landing page will connect to a
+Bitcoin node (or similar) and send the transaction on the public
+Bitcoin network.
+
+This feature is available on Q and Mk4 and requires NFC to be enabled.
+See `Settings > NFC Push Tx`.
+
+See the latest on our feature minisite: [PushTx.org](https://pushtx.org)
+
+## Protocol Spec
+
+The COLDCARD needs a URL prefix. To that it appends some values:
+
+- `t=...` 
+  - this is the transaction, in binary encoded with
+    [base64url](https://datatracker.ietf.org/doc/html/rfc4648#section-5)
+
+- `&c=...`
+    - the rightmost 8 bytes of SHA256 over the transaction. Also `base64url` encoded.
+
+- `&n=XTN`
+    - if, and only if, the COLDCARD is set for Testnet, this value is appended to
+      indicate that the transaction is for Testnet3 and not MainNet.
+    - when RegTest is enabled, the value will be `XRT`
+
+We provide a few default URL values to our customers, including one backend we
+will operate on `coldcard.com`. The URL can also be directly entered by the
+customer. On the Q, it can be scanned from a QR code.
+
+For COLDCARD backend, the url used is:
+
+    https://coldcard.com/pushtx#
+
+The complete URL with a typical transaction might look like this (but longer):
+
+    https://coldcard.com/pushtx#t=AgAAAAMNCxXtp2GVYVhkRXHLMmdZFs4p3kbFK ⋯ ABf&c=uiSVRda-1tw
+
+We are using hash symbol here so that our server logs do not get
+contaminated with the arguments. The landing page uses javascript
+to read the hash part of the URL and decodes from there. If you
+prefer, your URL can end with `?` and then the arguments will be
+sent by the phone's browser to your server. Your processing can be
+entirely done in the backend in this case.
+
+## Expectations for the Backend
+
+Your code should decode the transaction and check the SHA-256 hash
+matches. If it does not match, or if `c` value is missing, assume
+the URL has been truncated and report that to the user.
+
+Once decoded, your code should immediately broadcast the transaction.
+A confirmation step is not required in our opinion. Once it is
+submitted to Bitcoin Core (or other API), any status response should
+be decoded and shown to the user so they know it is on it's way.
+If it was not accepted, please report the error to the user as
+clearly as possible.
+
+Next, it would make sense to either link to the TXID on a block
+explorer to provide further proof that it has been sent and that
+it is now waiting in the mempool.
+
+## Backend Implementations
+
+- Mempool.space's [implementation of this feature](https://github.com/mempool/mempool/pull/5132).
+
+- A single-file (html and javascript) file is available
+  at [coldcard.com/static/coldcard-pushtx.html](https://coldcard.com/static/coldcard-pushtx.html).
+  You can host this file anywhere your phone can reach, and then use that URL in your
+  COLDCARD settings. It uses your phone's browser to submit directly
+  to `mempool.space` and `blockstream.info` sites (both at same time). It is equivalent
+  to the page hosted at `https://coldcard.com/pushtx#`. Full source code is published here:
+  [github.com/Coldcard/push-tx](https://github.com/Coldcard/push-tx)
+
+### Notes
+
+- Complete URL might be as large as 8,000 bytes. Some web servers will not support beyond
+  4k bytes and the NFC implementation of the phone may also have limits.
+- The service URL provided must end in `?` or `#` or `&`.
+- `base64url` values from COLDCARD will not have padding (`=` bytes) at end.
+- POST cannot be used directly because the expect the phone to do a GET on the URL provided.
+- Honest backends will not log the IP address of incoming transactions, but there is
+  no way to enforce that, and CloudFlare sees all.
+
+## Example URL
+
+```
+https://mempool.space/pushtx#t=AgAAAAOHqK3w3hC6PSC0buthnJA5R9Y88WAlEvm9cifNVUPhIwAAAABqRzBEAiB-M9YprNYoohqHdQHg4wY_qcEMwDmyIQH8prykk8-0KwIgARxcojKrtixicouiUxhk4jQq_MAl11ptIgHDlRjgk5ABIQM4bgMAVDbDSr_9CvLjbg5nxrWnDGI-kVmkfL81GXZtCf____8OaH0RxW7DjZKdIF6rvbHvvyFGCBQ0PTgpx20nA_wbLgAAAABqRzBEAiBwUFigORJDPK8ptnYPAntjV-RUn1jAuzphicQstwVv-QIgEbMC8FWXQ5Jve5DaAqKJsqoj3peK83iub_oOkmbiYg4BIQO5Ehn2t0oUG3hnK4cBnwCwMc33DcdJ8aSMWzRQ_wjZL_____-UG6M-eBeAun-EZp6EbVypvVJ3mXCQrN_fUDn-kwoEnQAAAABqRzBEAiAgFAtVTpQYTKplc9NuV7Ws7ZFYeNO8BCS4ozgWrgd2ogIgGTTcw98xQdcGWeWQhVfVm_vZorBIOYovQPQeK0Lg9t8BIQLPWPioVWvj1z4NMHBCkeirYOUalCa83wbSH0CREnGZvv____8CjM_wCAAAAAAZdqkUIJA8_yqzaj0NzhvYVEIBno5gETGIrIzP8AgAAAAAGXapFEaV7xTyleuEX9OejdlUlsz7RTr0iKwAAAAA&c=hre47vyMC78&n=XTN
+```
+
+- this transaction doesn't have valid inputs, and will cause an error
+- mempool.space will redirect this to a testnet endpoint (because ends with `n=XTN`)
+
+

docs/notes-on-repro.md

@@ -0,0 +1,196 @@
+# Notes on Reproducible Builds
+
+The following document aims to breakdown how reproducibility is verified in the `make repro` build step.
+
+## stm32/shared.mk
+
+The entrypoint makefile for repro builds.
+
+### repro
+
+The `repro` command in `shared.mk` is the first step in the repro build process, which triggers a docker build and run process.
+
+```makefile
+repro: submods-match code-committed
+repro: 
+	docker build -t coldcard-build - < dockerfile.build
+	(cd ..; docker run $(DOCK_RUN_ARGS) sh src/stm32/repro-build.sh $(VERSION_STRING) $(HW_MODEL) $(PARENT_MKFILE))
+```
+
+`$(HW_MODEL)` is the model string (e.g. `mk4`, `q1`) and `$(PARENT_MKFILE)` is the
+top-level makefile being used (`MK-Makefile` or `Q1-Makefile`). The `submods-match`
+and `code-committed` prerequisites ensure the submodules and working tree are clean
+before a repro build.
+
+Below are interesting sections from the docker logs that give an idea as to what is going on in build process:
+
+```stdout
++ mkdir /tmp/checkout
++ mount -t tmpfs tmpfs /tmp/checkout
+
+...
+```
+We will pull the release from coldcard.com into the `/tmp/checkout` directory.
+
+```
++ git clone /work/src/.git firmware
+
+...
+
++ cd firmware/external
++ git submodule update --init
+
+...
+
+Successfully installed signit-1.0
+
+...
+
++ cd ../stm32
++ cd ../releases
++ '[' -f '*-v5.0.7-mk4-coldcard.dfu' ]
++ dd 'bs=66' 'skip=1'
++ grep -F v5.0.7-mk4-coldcard.dfu signatures.txt
+0+1 records in
+0+1 records out
++ PUBLISHED_BIN=2022-10-05T1724-v5.0.7-mk4-coldcard.dfu
++ '[' -z 2022-10-05T1724-v5.0.7-mk4-coldcard.dfu ]
++ wget -S https://coldcard.com/downloads/2022-10-05T1724-v5.0.7-mk4-coldcard.dfu
+
+...
+
+'2022-10-05T1724-v5.0.7-mk4-coldcard.dfu' saved
+
+...
+
++ PUBLISHED_BIN=/tmp/checkout/firmware/releases/2022-10-05T1724-v5.0.7-mk4-coldcard.dfu
+
+...
+
++ make -f MK-Makefile setup
+
+...
+
++ make -f MK-Makefile firmware-signed.bin firmware-signed.dfu production.bin dev.dfu firmware.lss firmware.elf
+
+...
+
+signit sign -b l-port/build-COLDCARD_MK4 -m mk4 5.0.7 -o firmware-signed.bin
+
+...
+
+signit sign -m mk4 5.0.7 -r firmware-signed.bin -k 1 -o production.bin
+You don't have that key (1), so using key zero instead!
+...
+
+cd ../external/micropython/ports/stm32 && make BOARD=COLDCARD_MK4 -j 4 EXCLUDE_NGU_TESTS=1 DEBUG_BUILD=0
+
+...
+
+../external/micropython/tools/dfu.py -b 0x08020000:dev.bin dev.dfu
+arm-none-eabi-objdump -h -S l-port/build-COLDCARD_MK4/firmware.elf > firmware.lss
+cp l-port/build-COLDCARD_MK4/firmware.elf .
++ '[' /tmp/checkout/firmware/stm32 '!=' /work/src/stm32 ]
++ rsync -av --ignore-missing-args firmware-signed.bin firmware-signed.dfu production.bin dev.dfu firmware.lss firmware.elf /work/built
+sending incremental file list
+dev.dfu
+firmware-signed.bin
+firmware-signed.dfu
+firmware.elf
+firmware.lss
+production.bin
+
+...
+
++ make -f MK-Makefile 'PUBLISHED_BIN=/tmp/checkout/firmware/releases/2022-10-05T1724-v5.0.7-mk4-coldcard.dfu' check-repro
+
+...
+
+Comparing against: /tmp/checkout/firmware/releases/2022-10-05T1724-v5.0.7-mk4-coldcard.dfu
+test -n "/tmp/checkout/firmware/releases/2022-10-05T1724-v5.0.7-mk4-coldcard.dfu" -a -f /tmp/checkout/firmware/releases/2022-10-05T1724-v5.0.7-mk4-coldcard.dfu
+rm -f -f check-fw.bin check-bootrom.bin
+signit split /tmp/checkout/firmware/releases/2022-10-05T1724-v5.0.7-mk4-coldcard.dfu check-fw.bin check-bootrom.bin
+start 293 for 870400 bytes: Firmware => check-fw.bin
+start 870701 for 114688 bytes: Bootrom => check-bootrom.bin
+signit check check-fw.bin
+     magic_value: 0xcc001234
+       timestamp: 2022-10-05 17:24:55 UTC
+  version_string: 5.0.7
+      pubkey_num: 1
+ firmware_length: 870400
+   install_flags: 0x0 =>
+       hw_compat: 0x8 => Mk4
+         best_ts: b'\x00\x00\x00\x00\x00\x00\x00\x00'
+          future: 0000000000000000 ... 0000000000000000
+       signature: 293948e7ce4a3555 ... 766437aa65d3e88a
+sha256^2: 7f3a7c5f794ce72f68280447cddc837fa62245fdf4b795822127624f8775dca2
+ ECDSA Signature: CORRECT
+signit check firmware-signed.bin
+     magic_value: 0xcc001234
+       timestamp: 2022-10-24 13:33:16 UTC
+  version_string: 5.0.7
+      pubkey_num: 0
+ firmware_length: 870400
+   install_flags: 0x0 =>
+       hw_compat: 0x8 => Mk4
+         best_ts: b'\x00\x00\x00\x00\x00\x00\x00\x00'
+          future: 0000000000000000 ... 0000000000000000
+       signature: deb643d0a140d89e ... c544f09cd80fa65c
+sha256^2: a46ddd6e599a49a573bf76054f438c9efe1ee031bfae74a00b0e7bbe76f516c3
+ECDSA Signature: CORRECT
+hexdump -C firmware-signed.bin | sed -e 's/^00003f[89abcdef]0 .*/(firmware signature here)/' > repro-got.txt
+hexdump -C check-fw.bin | sed -e 's/^00003f[89abcdef]0 .*/(firmware signature here)/' > repro-want.txt
+diff repro-got.txt repro-want.txt
+
+SUCCESS. 
+
+You have built a bit-for-bit identical copy of Coldcard firmware for v5.0.7
+```
+
+## check-repro
+
+The `check-repro` section of the makefile contains the steps required to verify that the build artifacts are infact a bit-for-bit match to the release candidates.
+
+```makefile
+check-repro: TRIM_SIG = sed -e 's/^00003f[89abcdef]0 .*/(firmware signature here)/'
+check-repro: firmware-signed.bin
+ifeq ($(PUBLISHED_BIN),)
+	@echo ""
+	@echo "Need published binary for: $(VERSION_STRING)"
+	@echo ""
+	@echo "Copy it into ../releases"
+	@echo ""
+else
+	@echo Comparing against: $(PUBLISHED_BIN)
+	test -n "$(PUBLISHED_BIN)" -a -f $(PUBLISHED_BIN)
+	$(RM) -f check-fw.bin check-bootrom.bin
+	$(SIGNIT) split $(PUBLISHED_BIN) check-fw.bin check-bootrom.bin
+	$(SIGNIT) check check-fw.bin
+	$(SIGNIT) check firmware-signed.bin
+	hexdump -C firmware-signed.bin | $(TRIM_SIG) > repro-got.txt
+	hexdump -C check-fw.bin | $(TRIM_SIG) > repro-want.txt
+	diff repro-got.txt repro-want.txt
+	@echo ""
+	@echo "SUCCESS. "
+	@echo ""
+	@echo "You have built a bit-for-bit identical copy of Coldcard firmware for v$(VERSION_STRING)"
+endif
+```
+
+To summarize `check-repro`:
+
+- At the final `check-repro` step, we have a locally built `firmware-signed.bin` and we want to check that it matches the binary release provided by Coinkite.
+
+- This step verifies the signature of the binary is valid, using either the Coinkite key factory key or the "debug" key zero which is public.
+
+- An identical checksum match will not be possible as is, since there is signature data embedded into into the binary, which must be removed.
+
+- The specific release of the version that is being built is fetched, and placed it under /tmp/checkout/firmware/releases/*.dfu
+
+- `split` (cli/signit.py: Line 153-175) is run against the release `*.dfu` resulting in a `check-fw.bin` and `check-bootrom.bin`. "This splits the DFU file into the two parts it contains: the main firmware (COLDCARD application) and the boot loader code."
+
+- `check` (cli/signit.py: Line 176-243) is run against each the release `check-fw.bin` and our built `firmware-signed.bin`.
+
+- a hexdump is taken of each the release `check-fw.bin` and our built `firmware-signed.bin` piped through $TRIM_SIG which removes 64 bytes of signature data and subsitutes it with a common string.
+
+- Finally the diff of the two hexdumps are compared to prove reproducibility.

docs/pin-entry.md

@@ -81,7 +81,7 @@ of your duress PIN.
 The attackers could tell when the brick-me PIN has worked, but when
 the brick-me PIN works, the Coldcard will immediately use it to
 destroy the main pairing secret. This renders the security element
-useless. This happens in about 50 milliseconds and is done long before
+useless. This happens in about 50 milliseconds and is done long 
 before anyone gets an on-screen confirmation that it worked.
 
 There is little time to interrupt this or jam the bus to stop it.
@@ -183,12 +183,12 @@ This double-hashed value is what's stored inside the secure element
 as it travels on the bus. Because of the inclusion of the pairing
 secret, the hashes generated by each Coldcard will be different.
 
-With Mark3 hardware, we've added a key-streching step, which starts
+With Mark3 hardware, we've added a key-stretching step, which starts
 with the above value, and does HMAC-SHA256 using a secret key known
 only to the 608a (repeatedly). That value is used directly to check the
 duress PIN, and if that doesn't match, it is HMAC-SHA256'ed again,
 using a key that is usage limited. This limits actual PIN login attempts
-to a set value and is enfoced by the 608a internally.
+to a set value and is enforced by the 608a internally.
 
 ## Genuine vs. Caution Lights
 
@@ -281,7 +281,7 @@ Here's what the warning screen looks like:
 
 ### Benefits
 
-- no warnings, but still trustable thanks to ATECC608A
+- no warnings, but still trustable thanks to ATECC608
 - random devs can replace 99% of firmware at Micropython layer (everything but bootloader)
 - but they need to retain our code for talking to bootloader and secure element,
   so that PIN can be entered and verified.

docs/proof-of-reserves-bip-322.md

@@ -0,0 +1,112 @@
+# BIP-322 Generic Signed Message Format
+
+BIP-322 specification: <https://github.com/bitcoin/bips/blob/master/bip-0322.mediawiki>
+
+## Proof of Reserves (POR)
+
+### PoR PSBT
+
+COLDCARD accepts a specially crafted PSBT file to sign as BIP-322 Proof of Reserves. The PSBT
+must meet all these requirements:
+
+* COLDCARD acts as a BIP-322 PSBT signer. It validates the BIP-322 `to_sign`
+  transaction, shows the message from `PSBT_GLOBAL_GENERIC_SIGNED_MESSAGE`, and
+  adds signatures to the PSBT. Finalizing and encoding the final BIP-322
+  signature string is the responsibility of the finalizer.
+* PSBT MUST include `PSBT_GLOBAL_GENERIC_SIGNED_MESSAGE = 0x09`; the value is
+  the exact message shown to the user and signed by BIP-322.
+* PSBT requires `PSBT_IN_BIP32_DERIVATION` for each input
+* P2SH wrapped segwit addresses MUST have proper redeem script in PSBT: `PSBT_IN_REDEEM_SCRIPT`
+* P2WSH segwit addresses MUST have proper witness script in PSBT: `PSBT_IN_WITNESS_SCRIPT`
+* PSBT (`to_sign`) MUST have at least one input.
+* First (0th) input of `to_sign` MUST spend the BIP-322 `to_spend` output.
+* Input 0 MUST include one of `PSBT_IN_NON_WITNESS_UTXO` or `PSBT_IN_WITNESS_UTXO`.
+* When input 0 provides `PSBT_IN_WITNESS_UTXO`, COLDCARD reconstructs the
+  expected `to_spend` txid from `PSBT_GLOBAL_GENERIC_SIGNED_MESSAGE` and the
+  witness UTXO scriptPubKey.
+* When input 0 provides `PSBT_IN_NON_WITNESS_UTXO`, it MUST be the BIP-322
+  `to_spend` transaction as defined in
+  [BIP-322](https://github.com/bitcoin/bips/blob/master/bip-0322.mediawiki#full):
+    * 1 input, 1 output
+    * output nValue is 0
+    * input prevout hash is 0
+    * input prevout n is 0xffffffff
+    * input scriptSig is `OP_0 PUSH32 message_hash`
+* PSBT (`to_sign`) MUST only have one output with null-data `OP_RETURN`
+* `to_sign` transaction version MUST be 0 or 2.
+* Optionally inputs can be added to `to_sign` for Proof of Reserve signing.
+* PSBT MUST be version 0 or 2.
+* Foreign inputs not allowed in POR PSBT.
+
+The signatures created by the BIP-322 process will never be suitable
+for a on-chain Bitcoin transaction that could move funds, because
+of these restrictions imposed by BIP-322.
+
+### Output
+
+COLDCARD always returns a signed PSBT for BIP-322 message signing and Proof of
+Reserves. It never returns an extracted/finalized transaction for these PSBTs.
+This is true even when finalization is requested over USB, such as with
+`ckcc unsigned.psbt --finalize`.
+
+The signed PSBT is the handoff artifact for the external finalizer/verifier. It
+keeps the PSBT metadata needed to verify or finalize the BIP-322 signature,
+including public keys, scripts, partial signatures, and UTXO data. This matters
+because the address being proven normally commits only to a hash of the public
+key or script, not the public key or script itself.
+
+### Proof of Reserves Signing Experience
+
+After Coldcard recognizes a BIP-322 PSBT it reads the message from
+`PSBT_GLOBAL_GENERIC_SIGNED_MESSAGE` and shows it to the user for approval.
+COLDCARD verifies that the message hash matches the input 0 `to_spend`
+commitment before offering to sign.
+
+When the PSBT contains only input 0, COLDCARD labels the request as
+`BIP-322 Message`, because it is message signing and does not prove ownership
+of any additional reserve UTXOs. In that case it does not show transaction
+input/output counts. When the PSBT contains additional inputs, COLDCARD labels
+the request as `Proof of Reserves` and shows the reserve amount.
+
+If the message contains non-ASCII characters, COLDCARD warns that some
+characters may not be readable on screen.
+
+Legacy PoR PSBTs without `PSBT_GLOBAL_GENERIC_SIGNED_MESSAGE` are rejected by
+this flow.
+
+Read more [here.](https://gist.github.com/orangesurf/0c1d0a31d3ebe7e48335a34d56788d4c)
+
+Example screen text for a one-input BIP-322 message signing PSBT:
+
+```text
+BIP-322 Message
+
+ Message:
+ This is the signed message
+
+ Challenge Address:
+ bc1qzvjnhf7k70uxv6xvneaqxql7k09dd6nsr5wheq
+
+ Press ENTER to approve and sign message. Press (2) to explore transaction.
+ CANCEL to abort.
+```
+
+Example screen text for a Proof of Reserves PSBT:
+
+```text
+Proof of Reserves
+
+ Message:
+ POR
+
+ Amount 0.20000000 BTC
+
+ Challenge Address:
+ bc1qzvjnhf7k70uxv6xvneaqxql7k09dd6nsr5wheq
+
+ 21 inputs
+ 1 output
+
+ Press ENTER to approve and sign proof of reserves. Press (2) to explore transaction.
+ CANCEL to abort.
+```

docs/rolls.py

@@ -8,36 +8,6 @@
 #
 from hashlib import sha256
 
-# Read input, remove whitespace around it
-r = input().strip()
-
-# Calc sha256
-h = sha256(r.encode()).digest()
-
-# Show the hash
-print(h.hex())
-print()
-
-# Sanity check for empty input
-empty = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
-if h.hex() == empty:
-    print('WARNING: Input is empty. This is a known wallet\n')
-
-# Warnings for short length
-if len(r) < 99:
-    ae = 2.585 * len(r)
-    print('WARNING: Input is only %d bits of entropy\n' % ae)
-
-# Apply BIP39 to convert into seed words
-v = int.from_bytes(h, 'big') << 8
-w = []
-for i in range(24):
-    v, m = divmod(v, 2048)
-    w.insert(0, m)
-assert not v
-
-# final 8 bits are a checksum
-w[-1] |= sha256(h).digest()[0]
 
 # English wordlist
 wl = '''\
@@ -212,5 +182,42 @@ window wine wing wink winner winter wire wisdom wise wish witness wolf woman
 wonder wood wool word work world worry worth wrap wreck wrestle wrist write
 wrong yard year yellow you young youth zebra zero zone zoo'''.split()
 
-# Print index number and each word (24)
-print('\n'.join('%4d: %s' % (n+1, wl[i]) for n, i in enumerate(w)))
+
+def entropy_to_mnemonic24(entropy):
+    # Apply BIP39 to convert entropy into seed words
+    assert len(entropy) == 32
+    v = int.from_bytes(entropy, 'big') << 8
+    indexes = []
+    for i in range(24):
+        v, m = divmod(v, 2048)
+        indexes.insert(0, m)
+    assert not v
+    # final 8 bits are a checksum
+    indexes[-1] |= sha256(entropy).digest()[0]
+    return [wl[i] for i in indexes]
+
+
+def main():
+    # Read input, remove whitespace around it
+    r = input().strip()
+    # Calc sha256
+    h = sha256(r.encode()).digest()
+    # Show the hash
+    print(h.hex())
+    print()
+    # Sanity check for empty input
+    empty = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    if h.hex() == empty:
+        print('WARNING: Input is empty. This is a known wallet\n')
+    # Warnings for short length
+    if len(r) < 99:
+        ae = 2.585 * len(r)
+        print('WARNING: Input is only %d bits of entropy\n' % ae)
+
+    mnemonic = entropy_to_mnemonic24(h)
+    # Print index number and each word (24)
+    print('\n'.join('%4d: %s' % (n + 1, word) for n, word in enumerate(mnemonic)))
+
+
+if __name__ == "__main__":
+    main()

docs/rolls12.py

@@ -0,0 +1,222 @@
+# Usage:
+#
+#   echo 123456123456 | python3 rolls12.py
+#
+# - Requires python3 and nothing else!
+# - This file is <https://coldcardwallet.com/docs/rolls12.py>
+# - Public domain.
+#
+from hashlib import sha256
+
+
+# English wordlist
+wl = '''\
+abandon ability able about above absent absorb abstract absurd abuse access
+accident account accuse achieve acid acoustic acquire across act action actor
+actress actual adapt add addict address adjust admit adult advance advice
+aerobic affair afford afraid again age agent agree ahead aim air airport aisle
+alarm album alcohol alert alien all alley allow almost alone alpha already
+also alter always amateur amazing among amount amused analyst anchor ancient
+anger angle angry animal ankle announce annual another answer antenna antique
+anxiety any apart apology appear apple approve april arch arctic area arena
+argue arm armed armor army around arrange arrest arrive arrow art artefact
+artist artwork ask aspect assault asset assist assume asthma athlete atom
+attack attend attitude attract auction audit august aunt author auto autumn
+average avocado avoid awake aware away awesome awful awkward axis baby bachelor
+bacon badge bag balance balcony ball bamboo banana banner bar barely bargain
+barrel base basic basket battle beach bean beauty because become beef before
+begin behave behind believe below belt bench benefit best betray better between
+beyond bicycle bid bike bind biology bird birth bitter black blade blame blanket
+blast bleak bless blind blood blossom blouse blue blur blush board boat body
+boil bomb bone bonus book boost border boring borrow boss bottom bounce box
+boy bracket brain brand brass brave bread breeze brick bridge brief bright
+bring brisk broccoli broken bronze broom brother brown brush bubble buddy
+budget buffalo build bulb bulk bullet bundle bunker burden burger burst bus
+business busy butter buyer buzz cabbage cabin cable cactus cage cake call calm
+camera camp can canal cancel candy cannon canoe canvas canyon capable capital
+captain car carbon card cargo carpet carry cart case cash casino castle casual
+cat catalog catch category cattle caught cause caution cave ceiling celery
+cement census century cereal certain chair chalk champion change chaos chapter
+charge chase chat cheap check cheese chef cherry chest chicken chief child
+chimney choice choose chronic chuckle chunk churn cigar cinnamon circle citizen
+city civil claim clap clarify claw clay clean clerk clever click client cliff
+climb clinic clip clock clog close cloth cloud clown club clump cluster clutch
+coach coast coconut code coffee coil coin collect color column combine come
+comfort comic common company concert conduct confirm congress connect consider
+control convince cook cool copper copy coral core corn correct cost cotton
+couch country couple course cousin cover coyote crack cradle craft cram crane
+crash crater crawl crazy cream credit creek crew cricket crime crisp critic
+crop cross crouch crowd crucial cruel cruise crumble crunch crush cry crystal
+cube culture cup cupboard curious current curtain curve cushion custom cute
+cycle dad damage damp dance danger daring dash daughter dawn day deal debate
+debris decade december decide decline decorate decrease deer defense define
+defy degree delay deliver demand demise denial dentist deny depart depend
+deposit depth deputy derive describe desert design desk despair destroy detail
+detect develop device devote diagram dial diamond diary dice diesel diet differ
+digital dignity dilemma dinner dinosaur direct dirt disagree discover disease
+dish dismiss disorder display distance divert divide divorce dizzy doctor
+document dog doll dolphin domain donate donkey donor door dose double dove
+draft dragon drama drastic draw dream dress drift drill drink drip drive drop
+drum dry duck dumb dune during dust dutch duty dwarf dynamic eager eagle early
+earn earth easily east easy echo ecology economy edge edit educate effort egg
+eight either elbow elder electric elegant element elephant elevator elite else
+embark embody embrace emerge emotion employ empower empty enable enact end
+endless endorse enemy energy enforce engage engine enhance enjoy enlist enough
+enrich enroll ensure enter entire entry envelope episode equal equip era erase
+erode erosion error erupt escape essay essence estate eternal ethics evidence
+evil evoke evolve exact example excess exchange excite exclude excuse execute
+exercise exhaust exhibit exile exist exit exotic expand expect expire explain
+expose express extend extra eye eyebrow fabric face faculty fade faint faith
+fall false fame family famous fan fancy fantasy farm fashion fat fatal father
+fatigue fault favorite feature february federal fee feed feel female fence
+festival fetch fever few fiber fiction field figure file film filter final
+find fine finger finish fire firm first fiscal fish fit fitness fix flag flame
+flash flat flavor flee flight flip float flock floor flower fluid flush fly
+foam focus fog foil fold follow food foot force forest forget fork fortune
+forum forward fossil foster found fox fragile frame frequent fresh friend
+fringe frog front frost frown frozen fruit fuel fun funny furnace fury future
+gadget gain galaxy gallery game gap garage garbage garden garlic garment gas
+gasp gate gather gauge gaze general genius genre gentle genuine gesture ghost
+giant gift giggle ginger giraffe girl give glad glance glare glass glide glimpse
+globe gloom glory glove glow glue goat goddess gold good goose gorilla gospel
+gossip govern gown grab grace grain grant grape grass gravity great green grid
+grief grit grocery group grow grunt guard guess guide guilt guitar gun gym
+habit hair half hammer hamster hand happy harbor hard harsh harvest hat have
+hawk hazard head health heart heavy hedgehog height hello helmet help hen hero
+hidden high hill hint hip hire history hobby hockey hold hole holiday hollow
+home honey hood hope horn horror horse hospital host hotel hour hover hub huge
+human humble humor hundred hungry hunt hurdle hurry hurt husband hybrid ice
+icon idea identify idle ignore ill illegal illness image imitate immense immune
+impact impose improve impulse inch include income increase index indicate
+indoor industry infant inflict inform inhale inherit initial inject injury
+inmate inner innocent input inquiry insane insect inside inspire install intact
+interest into invest invite involve iron island isolate issue item ivory jacket
+jaguar jar jazz jealous jeans jelly jewel job join joke journey joy judge juice
+jump jungle junior junk just kangaroo keen keep ketchup key kick kid kidney
+kind kingdom kiss kit kitchen kite kitten kiwi knee knife knock know lab label
+labor ladder lady lake lamp language laptop large later latin laugh laundry
+lava law lawn lawsuit layer lazy leader leaf learn leave lecture left leg legal
+legend leisure lemon lend length lens leopard lesson letter level liar liberty
+library license life lift light like limb limit link lion liquid list little
+live lizard load loan lobster local lock logic lonely long loop lottery loud
+lounge love loyal lucky luggage lumber lunar lunch luxury lyrics machine mad
+magic magnet maid mail main major make mammal man manage mandate mango mansion
+manual maple marble march margin marine market marriage mask mass master match
+material math matrix matter maximum maze meadow mean measure meat mechanic
+medal media melody melt member memory mention menu mercy merge merit merry
+mesh message metal method middle midnight milk million mimic mind minimum minor
+minute miracle mirror misery miss mistake mix mixed mixture mobile model modify
+mom moment monitor monkey monster month moon moral more morning mosquito mother
+motion motor mountain mouse move movie much muffin mule multiply muscle museum
+mushroom music must mutual myself mystery myth naive name napkin narrow nasty
+nation nature near neck need negative neglect neither nephew nerve nest net
+network neutral never news next nice night noble noise nominee noodle normal
+north nose notable note nothing notice novel now nuclear number nurse nut oak
+obey object oblige obscure observe obtain obvious occur ocean october odor off
+offer office often oil okay old olive olympic omit once one onion online only
+open opera opinion oppose option orange orbit orchard order ordinary organ
+orient original orphan ostrich other outdoor outer output outside oval oven
+over own owner oxygen oyster ozone pact paddle page pair palace palm panda
+panel panic panther paper parade parent park parrot party pass patch path
+patient patrol pattern pause pave payment peace peanut pear peasant pelican
+pen penalty pencil people pepper perfect permit person pet phone photo phrase
+physical piano picnic picture piece pig pigeon pill pilot pink pioneer pipe
+pistol pitch pizza place planet plastic plate play please pledge pluck plug
+plunge poem poet point polar pole police pond pony pool popular portion position
+possible post potato pottery poverty powder power practice praise predict
+prefer prepare present pretty prevent price pride primary print priority prison
+private prize problem process produce profit program project promote proof
+property prosper protect proud provide public pudding pull pulp pulse pumpkin
+punch pupil puppy purchase purity purpose purse push put puzzle pyramid quality
+quantum quarter question quick quit quiz quote rabbit raccoon race rack radar
+radio rail rain raise rally ramp ranch random range rapid rare rate rather
+raven raw razor ready real reason rebel rebuild recall receive recipe record
+recycle reduce reflect reform refuse region regret regular reject relax release
+relief rely remain remember remind remove render renew rent reopen repair
+repeat replace report require rescue resemble resist resource response result
+retire retreat return reunion reveal review reward rhythm rib ribbon rice rich
+ride ridge rifle right rigid ring riot ripple risk ritual rival river road
+roast robot robust rocket romance roof rookie room rose rotate rough round
+route royal rubber rude rug rule run runway rural sad saddle sadness safe sail
+salad salmon salon salt salute same sample sand satisfy satoshi sauce sausage
+save say scale scan scare scatter scene scheme school science scissors scorpion
+scout scrap screen script scrub sea search season seat second secret section
+security seed seek segment select sell seminar senior sense sentence series
+service session settle setup seven shadow shaft shallow share shed shell sheriff
+shield shift shine ship shiver shock shoe shoot shop short shoulder shove
+shrimp shrug shuffle shy sibling sick side siege sight sign silent silk silly
+silver similar simple since sing siren sister situate six size skate sketch
+ski skill skin skirt skull slab slam sleep slender slice slide slight slim
+slogan slot slow slush small smart smile smoke smooth snack snake snap sniff
+snow soap soccer social sock soda soft solar soldier solid solution solve
+someone song soon sorry sort soul sound soup source south space spare spatial
+spawn speak special speed spell spend sphere spice spider spike spin spirit
+split spoil sponsor spoon sport spot spray spread spring spy square squeeze
+squirrel stable stadium staff stage stairs stamp stand start state stay steak
+steel stem step stereo stick still sting stock stomach stone stool story stove
+strategy street strike strong struggle student stuff stumble style subject
+submit subway success such sudden suffer sugar suggest suit summer sun sunny
+sunset super supply supreme sure surface surge surprise surround survey suspect
+sustain swallow swamp swap swarm swear sweet swift swim swing switch sword
+symbol symptom syrup system table tackle tag tail talent talk tank tape target
+task taste tattoo taxi teach team tell ten tenant tennis tent term test text
+thank that theme then theory there they thing this thought three thrive throw
+thumb thunder ticket tide tiger tilt timber time tiny tip tired tissue title
+toast tobacco today toddler toe together toilet token tomato tomorrow tone
+tongue tonight tool tooth top topic topple torch tornado tortoise toss total
+tourist toward tower town toy track trade traffic tragic train transfer trap
+trash travel tray treat tree trend trial tribe trick trigger trim trip trophy
+trouble truck true truly trumpet trust truth try tube tuition tumble tuna
+tunnel turkey turn turtle twelve twenty twice twin twist two type typical ugly
+umbrella unable unaware uncle uncover under undo unfair unfold unhappy uniform
+unique unit universe unknown unlock until unusual unveil update upgrade uphold
+upon upper upset urban urge usage use used useful useless usual utility vacant
+vacuum vague valid valley valve van vanish vapor various vast vault vehicle
+velvet vendor venture venue verb verify version very vessel veteran viable
+vibrant vicious victory video view village vintage violin virtual virus visa
+visit visual vital vivid vocal voice void volcano volume vote voyage wage wagon
+wait walk wall walnut want warfare warm warrior wash wasp waste water wave way
+wealth weapon wear weasel weather web wedding weekend weird welcome west wet
+whale what wheat wheel when where whip whisper wide width wife wild will win
+window wine wing wink winner winter wire wisdom wise wish witness wolf woman
+wonder wood wool word work world worry worth wrap wreck wrestle wrist write
+wrong yard year yellow you young youth zebra zero zone zoo'''.split()
+
+
+def entropy_to_mnemonic12(entropy):
+    # Apply BIP39 to convert entropy into seed words
+    assert len(entropy) == 16
+    v = int.from_bytes(entropy, 'big') << 4
+    indexes = []
+    for i in range(12):
+        v, m = divmod(v, 2048)
+        indexes.insert(0, m)
+    # final 4 bits are a checksum
+    indexes[-1] += sha256(entropy).digest()[0] >> 4
+    return [wl[i] for i in indexes]
+
+
+def main():
+    # Read input, remove whitespace around it
+    r = input().strip()
+    # Calc sha256
+    h = sha256(r.encode()).digest()[:16]
+    # Show the hash
+    print(h.hex())
+    print()
+    # Sanity check for empty input
+    empty = "e3b0c44298fc1c149afbf4c8996fb924"
+    if h.hex() == empty:
+        print('WARNING: Input is empty. This is a known wallet\n')
+    # Warnings for short length
+    if len(r) < 50:
+        ae = 2.585 * len(r)
+        print('WARNING: Input is only %d bits of entropy\n' % ae)
+
+    mnemonic = entropy_to_mnemonic12(h)
+    # Print index number and each word (12)
+    print('\n'.join('%4d: %s' % (n + 1, word) for n, word in enumerate(mnemonic)))
+
+
+if __name__ == "__main__":
+    main()

docs/secure-elements.md

@@ -2,9 +2,9 @@
 
 ## Background
 
-The Mk4 **COLDCARD<sup>&reg;</sup>** has two secure elements:  
+The **COLDCARD<sup>&reg;</sup>** Mk4 and Q have two secure elements:  
 
-- SE1 (Secure Element 1): Microchip ATECC608B
+- SE1 (Secure Element 1): Microchip ATECC608
 - SE2 (Secure Element 2): Maxim DS28C36B
 
 Because different vendors make them, they do not share bugs and weaknesses.
@@ -20,15 +20,13 @@ HMAC-SHA256.
 
 Assume attackers have physical access to a COLDCARD, have opened
 the case, and can probe the bus connections between the MCU and SE1
-or SE2. They may even desolder SE1 and SE2 from the board, and put
-active circuits between them and the MCU &mdash; an active MiTM
-attack. (The Mk4 has improved goop on all three parts and all these
-critical signals run on internal layers of the PCBA.)
+or SE2. They may even de-solder SE1 and SE2 from the board, and put
+active circuits between them and the MCU &mdash; an active MiTM attack.
 
 
 ### The Solutions
 
-Three parties hold secrets in the Mk4: the main MCU (microcontroller)
+Three parties hold secrets in the COLDCARD: the main MCU (microcontroller)
 and the two secure elements. Our goal is that **all three** must
 be fully compromised to access the seed words. Thus, if one part
 has a vulnerability, the COLDCARD as a whole is still secure.
@@ -37,7 +35,7 @@ if all three devices are cracked wide open. (This is a last line
 of defence, a brute-force attack on all PIN combinations will breach
 it.)
 
-The Mk4 also supports new Trick PIN codes with side effects such
+COLDCARD also supports new Trick PIN codes with side effects such
 as wiping or bricking the COLDCARD, or providing access to a decoy
 or duress wallet. Ideally, attackers will not detect using a false
 PIN, even while probing the signals on the board.
@@ -53,7 +51,7 @@ and the MicroPython code cannot read this area of the chip. Using
 an internal firewall feature and PCROP (proprietary code readout
 protection) achieves this result.
 
-Mk4 also shares a secret between SE2 and the MCU. Just like SE1,
+COLDCARD also shares a secret between SE2 and the MCU. Just like SE1,
 this authenticates SE2 to the MCU and encrypts their mutual
 communications. The Pairing Secret for SE2 is not stored in SE1 and
 is unique from the other Pairing Secret used for SE1.
@@ -85,23 +83,23 @@ increases flexibility and resistance to known plain text attacks.
 
 ## All the Keys
 
-| Symbol        | Chip's Name | Type | Holder   | Purpose
-|---------------|-------------|------|----------|----------
-| `SE1 pairing` | slot 1      | HMAC | SE1, MCU | Protects communications between SE1 and MCU
-| `SE2 pairing` | secret A    | HMAC | SE2, MCU | Pairing for SE2
-| `SE2 comms`   | keypair A   | ECC  | SE2      | MCU captures pubkey half, used in ECDH comms
-| `SE joiner`   | slot 7, pubkey C    | ECC  | SE1/SE2  | SE2 knows only public part, SE1 has privkey
-| `pin stretch` | slot 2      | HMAC | SE1      | Key stretching for PIN entry and anti-phish words
-| `firmware`    | slot 14     | SHA256d | SE1      | Firmware checksum, controls green/red LEDs
-| `nonce/chksum` | slot 10    | data | SE1        | AES nonce and GMAC tag, protected by PIN
-| `SE2 easy key` | page 15    | AES via HMAC  | SE2      | Another SE2 part of AES seed key
-| `SE2 hard key` | page 14    | AES via ECC  | SE2      | SE2's part of AES seed key; ECC used to unlock
-| `tpin key`      | `tpin_key` | HMAC(key) | MCU   | Key for HMAC used to encrypt trick PINs
-| `trick PIN slots` | pages 0-12 | HMAC | SE2     | Protect duress wallet seeds and pins (6 spots)
-| `SE2 trash`   | secret B    | HMAC | SE2      | Used to destroy values (only SE2 knows the value)
-| `hash cache secret` | `hash_cache_secret`  | XOR/AES | MCU   | In-memory encryption of actual PIN when unlocked
-| `mcu hmac key`     | `mcu_hmac_key` | HMAC | MCU | Used as HMAC key to compress other keys
-| `replaceable mcu key`       | `MCU_KEYS` | AES | MCU    | Replaceable MCU key (up to 256 times)
+| Symbol                | Chip's Name         | Type         | Holder   | Purpose
+|-----------------------|---------------------|--------------|----------|----------
+| `SE1 pairing`         | slot 1              | HMAC         | SE1, MCU | Protects communications between SE1 and MCU
+| `SE2 pairing`         | secret A            | HMAC         | SE2, MCU | Pairing for SE2
+| `SE2 comms`           | keypair A           | ECC          | SE2      | MCU captures pubkey half, used in ECDH comms
+| `SE joiner`           | slot 7, pubkey C    | ECC          | SE1/SE2  | SE2 knows only public part, SE1 has privkey
+| `pin stretch`         | slot 2              | HMAC         | SE1      | Key stretching for PIN entry and anti-phish words
+| `firmware`            | slot 14             | SHA256d      | SE1      | Firmware checksum, controls green/red LEDs
+| `nonce/chksum`        | slot 10             | data         | SE1      | AES nonce and GMAC tag, protected by PIN
+| `SE2 easy key`        | page 14             | AES via HMAC | SE2      | Another SE2 part of AES seed key
+| `SE2 hard key`        | page 15             | AES via ECC  | SE2      | SE2's part of AES seed key; ECC used to unlock
+| `tpin key`            | `tpin_key`          | HMAC(key)    | MCU      | Key for HMAC used to encrypt trick PINs
+| `trick PIN slots`     | pages 0-12          | HMAC         | SE2      | Protect duress wallet seeds and pins (6 spots)
+| `SE2 trash`           | secret B            | HMAC         | SE2      | Used to destroy values (only SE2 knows the value)
+| `hash cache secret`   | `hash_cache_secret` | XOR/AES      | MCU      | In-memory encryption of actual PIN when unlocked
+| `mcu hmac key`        | `mcu_hmac_key`      | HMAC         | MCU      | Used as HMAC key to compress other keys
+| `replaceable mcu key` | `MCU_KEYS`          | AES          | MCU      | Replaceable MCU key (up to 256 times)
 
 All keys listed are 32 bytes long and picked randomly using the hardware RNG.
 
@@ -134,7 +132,7 @@ end of the message and checking they decode correctly.
 
 A new keyslot, 10, stores the MAC data (encrypted zeros).
 
-The startgin nonce for CTR mode is fixed random value composed of
+The starting nonce for CTR mode is fixed random value composed of
 the first 15 bytes of the `mcu hmac key`, followed by a zero (this
 increments if more than 16 bytes are encrypted or decrypted).
 
@@ -195,7 +193,7 @@ user enters against all the slots and works silently to support the
 Trick features.
 
 The type of support depends on the type of Trick. Duress wallets
-require storing 32 bytes of seed words (generated from the true
+require storing 32 or 64 bytes of seed words (generated from the true
 seed via BIP-85). Other cases dictate encoding a short numeric code
 provided to higher layers for implementation. For example, a flag
 in that code can trigger the boot ROM to wipe the `mcu seed key`.
@@ -206,7 +204,8 @@ key` being zero makes the seed permanently inaccessible.
 
 The MCU code may continue speaking to SE1 to complete the fraud,
 but in general, SE1 will no longer store the duress wallet or Brick
-Me PINs. Mk4 implements those feature in SE2.
+Me PINs as in previous generations (Mk1-3). Mk4 and Q implement
+those feature in SE2.
 
 
 ### Trick PIN Operation
@@ -249,7 +248,7 @@ timer and the time that must elapse before logging in is allowed.
 
 **Example 3** Although SE2 holds the Trick PINs, it does not know
 the True PIN and Delta Mode will not reveal the full True PIN. The
-"Delta More" Trick PIN has its unique hash result, and an entry from SE1 is used
+"Delta Mode" Trick PIN has its unique hash result, and an entry from SE1 is used
 to calculate the True PIN. This is accomplished by masking out the
 last four digits of the hash and substituting four digits from
 `tc_arg`. Limiting it to four digits enables a difference between
@@ -268,7 +267,7 @@ inside SE1. This storage is called Spare Secrets. Spare Secrets has
 3 &times; 72 bytes of space, protected by the same measures as the
 seed words.
 
-Mk4 still supports the Long Secret (416 bytes), but its API is
+Mk4/Q still supports the Long Secret (416 bytes), but its API is
 changed. The slow speed of fetching the Long Secret in 32-byte
 blocks due to the reconstructing the primary AES Seed Key for each
 call necessitated the change.
@@ -292,7 +291,7 @@ PINs that continue operation (duress PINs), unlike the average thug.
 
 ## Fast Brick
 
-On the Mk4, quickly bricking the system is done by rotating the SE1
+Quickly bricking the system is done by rotating the SE1
 pairing secret by mixing in a random nonce via the chip's key
 rotation process. Only a knowledge of the old pairing secret is
 needed for this change. This is similar the to `brick_me` PIN

docs/security-model.md

@@ -1,4 +1,4 @@
-# COLDCARD Mk4 Security Model
+# COLDCARD Mk4/Mk5/Q Security Model
 
 ## Abstract
 
@@ -8,11 +8,14 @@ seed words used to generate a deterministic wallet. This secure
 element is in a limited and read-only state until authorized by PIN entry.
 
 Clearing the secure element is impossible without first entering
-the correct PIN. The Mark 4 COLDCARD (Mk4) introduces several new
-security features, including a second secure element and Trick PINs
-which can render stored data unrecoverable, or brick the COLDCARD
-entirely if necessary, without entering the true authorization PIN
-(True PIN).
+the correct PIN. The Mk4 COLDCARD introduced several new security
+features, including a second secure element and Trick PINs which
+can render stored data unrecoverable, or brick the COLDCARD entirely
+if necessary, without entering the true authorization PIN (True
+PIN).
+
+The COLDCARD Q continues with the same security model introduced
+in Mk4.
 
 
 ## Introduction
@@ -22,7 +25,7 @@ the Microchip ATECC508A and later the ATECC608B, to store its
 secrets. This secure element has 72 bytes of storage protected by
 a 4- to 12-digit PIN code.
 
-Mk4 adds a second secure element to the COLDCARD. The ATECC608B is
+Mk4 adds a second secure element to the COLDCARD. The ATECC608 is
 still used, now called SE1 (Secure Element 1), along with a new
 chip, the Maxim DS28C36B, called SE2 (Secure Element 2).  The
 DS28C36B (SE2) has more memory with fifteen 32-byte slots of secure
@@ -93,9 +96,10 @@ user entered the True PIN. An attacker will only have access to the
 duress wallet. They won't have access to steal the main stash.
 
 The private key can be automatically derived using BIP-85 methods,
-based on account numbers 1001, 1002, or 1003. Because this is BIP-85
-based and uses a 24-word seed, it behaves exactly like a normal
-wallet. Defining a passphrase for the wallet is also possible.
+based on account numbers 1001, 1002, or 1003 for a 24-word duress wallet
+(or 2001, 2002, 2003 for a 12-word one). Because this is BIP-85
+based, it behaves exactly like a normal wallet. Defining a passphrase
+for the wallet is also possible.
 
 The Mk4 also supports older COLDCARD duress wallets and their UTXOs
 on the blockchain. There is an option to create compatible wallets
@@ -187,9 +191,9 @@ customers suggested.
 
 ### Kill Key Feature
 
-This feature allows the user to execute a Fast Wipe when the
-anti-phishing words are displayed on the screen. This feature is
-turned off by default.
+On the Mk4, this feature allows the user to execute a Fast Wipe
+when the anti-phishing words are displayed on the screen. This
+feature is turned off by default.
 
 The user sets a particular key number to trigger Fast Wipe. If that
 key is pressed while viewing the anti-phishing words, the seed is
@@ -200,13 +204,19 @@ It is strongly recommended that the first digit for the second half
 of the True PIN is **not** used as the Kill Key. Missing a step
 would unintentionally wipe the seed.
 
+For the COLDCARD Q, the same feature exists: any letter may be
+specified but numbers are not supported. This change allows the
+"kill button" to be active through-out the entire login process.
+It can be even be pressed while the nickname is shown, and at any
+point during the PIN entry.
+
 
 ### SPI Serial Flash Removed
 
 The Mk3 and earlier had a dedicated, external chip to hold settings
-and the PSBT during operation.  Mk4 does not have that chip. The
-settings now reside inside the main MCU, increasing security.
-Settings are still AES-encrypted as before.
+and the PSBT during operation.  Mk4 and later, do not have that
+chip. The settings now reside inside the main MCU, increasing
+security. Settings are still AES-encrypted as before.
 
 The separate settings chip could be blanked externally or even
 removed/replaced. This possibility might enable getting around
@@ -234,11 +244,11 @@ COLDCARD's case to do so, but the option is there if needed.
 
 ## SD Card Recovery Mode
 
-Mk4 bootloader is smart enough to be able to read an SD card. You
+Mk4/Mk5/Q bootloader is smart enough to be able to read an SD card. You
 will only be able to trigger the SD card loading code, if the
 COLDCARD was powered down during the upgrade process. At that point,
 the intended firmware image has been lost because it it held in
-PSRAM only during the flash writing process. The bootloader knows
+PSRAM only, during the flash writing process. The bootloader knows
 main flash (ie. Micropython code) is corrupt because it fails the
 checksum check (and/or signature check).
 
@@ -256,6 +266,9 @@ If any other parts of flash---beyond the normal upgradable firmware
 area---have also been corrupted, this process will not work and the
 unit will be a brick.
 
+On the COLDCARD Q, only the top slot (A) is supported for this
+operation.
+
 
 ## Flash ECC (Error Detection/Correction Codes)
 
@@ -274,7 +287,7 @@ that it's an attack, such as exposing the bare die to targeted UV-C
 radiation.  If the attacker is able to flip 2 or more bits, then
 this will effectively brick the COLDCARD once the ECC error is detected.
 
-Critical flash cells, such as those that prevent both JTAG access,
-are not a single bit (it's a special bit pattern), and regardless
-are protected via ECC the same as other flash cells.
+Critical flash cells, such as those that prevent JTAG access, are
+not a single bit (it's a special bit pattern), and regardless are
+protected via ECC the same as other flash cells.
 

docs/seed-xor.md

@@ -12,31 +12,32 @@ are not discrete and you could be compelled to produce the passphrase.
 
 Enter [_Seed XOR_](https://seedxor.com), a plausibly deniable means
 of storing secrets in two or more parts that look and behave just
-like the original secret. One 24-word seed phrase becomes two or more parts
+like the original secret. One 12-, 18-, or 24-word seed phrase becomes two or more parts
 that are also BIP-39 compatible seeds phrases. These should be backed up in your
 preferred method, metal or otherwise. These parts can be individually loaded
-with honeypot funds as each one is 24 words, with the 24th being
+with honeypot funds as each one has same word length, with the last being
 the checksum and will work as such in any normal BIP-39 compatible wallet.
 
 This one more solution for your game-theory arsenal.
 
 - *Q*: I'm lazy, can I do this to my Existing Seed?
 - *A*: Yes. You can split the words you have already in your Coldcard, making
-  2, 3 or 4 new SEEDPLATES.  You could also any number of existing SEEDPLATES
+  2, 3 or 4 new SEEDPLATES. You could also use any number of existing SEEDPLATES
   you have, and combine them to make a new random wallet that is the XOR of
   their values. Effectively that makes a new random wallet.
 
 ## Background
 
-[_Seed XOR_](https://seedxor.com) works by taking any number of 24-word
+[_Seed XOR_](https://seedxor.com) works by taking any number of
 seed phrases in BIP-39 style, and simply XOR-ing them together,
-bit-by-bit into a new phrase.
+bit-by-bit into a new phrase. All seed phrases have to be of the same length.
 
-The last word (in 24-word case, which is the only width we support) has
-8 bits of checksum. For the "parts" (sometimes called "shares") this checksum 
-is calculated as normal for BIP-39, but those final 8-bits are not used in
+The last word contains checksum.
+For the "parts" (sometimes called "shares") this checksum 
+is calculated as normal for BIP-39, but those final bits are not used in
 the XOR process. But the checksums still protects the integrity of the
-individual parts.
+individual parts. In 24-words XOR last 8 bits are checksum and in 12-words
+XOR last 4 bits are checksum.
 
 Useful properties of this approach:
 
@@ -50,7 +51,7 @@ Useful properties of this approach:
 - You can store funds on the seeds of any part, and any subset of parts, which
   opens even more duress options.
 
-We recommend storing the checksum word (24-th) of the original
+We recommend storing the checksum word of the original
 wallet along with your N parts. This allows you to be sure you've
 gotten all the parts and assembled them correctly. This does reveal
 3 bits of your real wallet however, and also reveals that a
@@ -72,15 +73,17 @@ Advanced > Danger Zone > Seed Functions > Seed XOR > Split Existing
 You can choose between 2, 3 or 4 parts. You can also choose (next
 screen) to generate them deterministically or using the TRNG. The
 advantage of the deterministic approach is you'll always get the
-same answers, so you can check that you've recorded the correct
-48 to 96 words right the next day.
+same answers, so you can check that you've recorded the correct 
+words right the next day.
 
 When the parts are made deterministically, we take a double-SHA256 over
 a fixed string (`Batshitoshi`), your master secret, and the text
-`1 of 4 parts` which changes for each part.
+`0 of 4 parts` which changes for each part (the index is 0-based).
 
-In random mode, we simply pick 32 random bytes (and then double-SHA256
-them) from the Coldcard's True Random Number Generator (TRNG)..
+In random mode, we simply pick random bytes (and then double-SHA256
+them) from the Coldcard's True Random Number Generator (TRNG). The number
+of bytes matches your secret length: 16, 24, or 32 bytes for a 12-, 18-,
+or 24-word seed respectively.
 
 This is done to make all but the one part. The final part is the
 value needed to get back to your secret, so it's the XOR of the
@@ -109,7 +112,7 @@ of all the parts.
 
 - You can pick your XOR parts randomly, and the result when XOR'ed
 together, is a random wallet. However, it would be best to get the
-24-th word checksum recorded correctly, so please use a tool such
+last word checksum recorded correctly, so please use a tool such
 as the Coldcard to lookup the 24th word and save that (for each
 part).  For example, you might take a fresh Coldcard (no secret)
 and draw 23 words from a hat. After providing the 23rd word, the
@@ -156,9 +159,15 @@ with the others on a SEEDPLATE.
     - right to A, down to B ... take that number, and go to that column
     - down to C, that is answer: a ⊕ b ⊕ c
 
+## Open Standard
+Seed XOR is an open standard. Other software and hardware wallets are encouraged to
+implement support. No license or permission is required, including usage of the term
+"Seed XOR" when referring to implementations of this feature. Such implementations
+should match the process described in this documentation and be fully interoperable.
+
 ---
 
-# XOR Seed Example Using 3 Parts
+# 24 Words XOR Seed Example Using 3 Parts
 
 ## Seed A  (1 of 3)
 
@@ -209,10 +218,56 @@ with the others on a SEEDPLATE.
       final word between: gas [300] - lend [3FF]
       correct final word: indoor [398]
 
+
+
+# 12 Words XOR Seed Example Using 3 Parts
+
+## Seed A  (1 of 3)
+
+      1=romance [5DC], 2=wink [7DE], 3=lottery [420], 4=autumn [07D], 5=shop [635], 6=bring [0E1],
+      7=dawn [1BF], 8=tongue [723], 9=range [58E], 10=crater [194], 11=truth [74E], 12=ability [001]
+
+      A = 5DC 7DE 420 07D 635 0E1 1BF 723 58E 194 74E 001
+
+
+## Seed B  (2 of 3)
+
+      1=boat [0C6], 2=unfair [768], 3=shell [62B], 4=violin [7A2], 5=tree [73F], 6=robust [5DA], 7=open [4D9],
+      8=ride [5CB], 9=visual [7A7], 10=forest [2D9], 11=vintage [7A1], 12=approve [056]
+
+      B = 0C6 768 62B 7A2 73F 5DA 4D9 5CB 7A7 2D9 7A1 056
+
+
+## Seed C  (3 of 3)
+
+      1=lion [411], 2=misery [46D], 3=divide [1FF], 4=hurry [37D], 5=latin [3EB], 6=fluid [2CD], 7=camp [106],
+      8=advance [01F], 9=illegal [388], 10=lab [3E0], 11=pyramid [578], 12=unhappy [76A]
+
+      C = 411 46D 1FF 37D 3EB 2CD 106 01F 388 3E0 578 76A
+
+
+## Calculation (XOR each hex digit)
+
+      A = 5DC 7DE 420 07D 635 0E1 1BF 723 58E 194 74E 001
+      B = 0C6 768 62B 7A2 73F 5DA 4D9 5CB 7A7 2D9 7A1 056
+      C = 411 46D 1FF 37D 3EB 2CD 106 01F 388 3E0 578 76A
+          |               |               |              
+    XOR = 10B 4DB 3F4 4A2 2E1 7F6 460 2F7 1A1 0AD 597 73x
+
+
+## Resulting Seed Phrase
+
+      1=cannon [10B], 2=opinion [4DB], 3=leader [3F4], 4=nephew [4A2], 5=found [2E1], 6=yard [7F6],
+      7=metal [460], 8=galaxy [2F7], 9=crouch [1A1], 10=between [0AD], 11=real [597]
+
+      final word between: toward [730] - tree [73F]
+      correct final word: trade [735]
+
+
+
 - It's not possible to calculate the checksum of the final seed phrase on paper (needs SHA256).
-- But it must start with the indicated digit, and there will be only one
+- But it must start with the indicated digit(s). If using 24 words XOR, there will be only one
   suitable choice offered by the Coldcard in that range (x00 to xFF),
   once you have entered the other 23 words.
 - The checksum of each of the XOR-parts protects the final result, assuming your XOR
-  math is correct.
-
+  math is correct.

docs/spending-policy.md

@@ -0,0 +1,209 @@
+# Spending Policy
+
+This special mode will stop you from signing transactions if they
+exceed a spending policy you define beforehand. Once enabled, many
+features of the COLDCARD are disabled or inaccessible.
+
+You might want to use this feature when traveling with your COLDCARD.
+
+## Spending Policy: Multisig (formerly CCC)
+
+We also support a mode where the COLDCARD is a multisig co-signer
+and only performs its signature when a spending policy is met. The
+other multisig signers are free to sign or not sign as appropriate.
+
+Multisig mode is more advanced and requires use of multisig addresses,
+new UTXO, and cooperating multisig on-chain wallets.
+
+This document will only discuss the "Single signer" version of
+Spending Policy. Both modes can be active at the same time, but if
+a transaction would be signed by Multisig policy, then we assume
+it's also okay to sign your main key as well.
+
+# Before You Start
+
+When a Spending Policy is in effect, there are limitations
+in effect:
+
+- Firmware updates are blocked.
+- There is no way to backup the COLDCARD.
+- Seed vault and Secure Notes are read-only (and can also be hidden).
+- Settings menu is inaccessible.
+- BIP-39 passphrases may be blocked (optional).
+
+We recommend getting the COLDCARD fully configured and setup
+for typical transactions before enabling the Spending Policy.
+
+# Setup Spending Policy
+
+Visit `Advanced / Tools > Spending Policy` menu and choose
+"Single-Signer". First some background information is shown,
+then you are prompted to define the "Bypass PIN". This PIN code
+is only used when you need to disable the spending policy, but is 
+also the only way to do so once enabled... so don't loose it.
+
+Once the "Bypass PIN" is confirmed, you will arrive at menu for
+related settings. Use "Edit Policy..." to change the spending policy
+and define a Max Magnitude (limit number of BTC per transaction),
+Velocity (minimum time gaps between signed transactions). You can
+define a whitelist of up to 25 destination addresses (leave empty
+for any). Finally you can enroll your phone in 2FA (second factor)
+so that you must open an Authenticator app on your phone before
+transactions are signed.
+
+## Other Security Settings
+
+In addition to policy itself, there are a number of on/off
+switches which affect operation of the COLDCARD while the Spending
+Policy is in effect:
+
+### Word Check
+
+If enabled, you will have to enter the first and last seed word
+after the Bypass PIN as an additional security check.
+
+### Allow Notes
+
+On the Q, secure notes and passwords may be visible or hidden
+using this setting. In either case they are strictly readonly.
+
+### Related Keys
+
+BIP-39 passphrase entry, Seed Vault usage will be blocked unless this
+setting is enabled. Even when enabled, the Seed Vault is always readonly
+and cannot be changed.
+
+# Other Menu Items
+
+## Last Violation
+
+If you have recently tried and failed to sign a transaction, the
+reason for the transaction being rejected can be viewed and cleared,
+using menu item "Last Violation". It is shown only if a Spending
+Policy violation (attempt) has occurred since the last valid signing.
+
+This is meant as a debugging tool, and the information stored is
+terse.
+
+## Remove Policy
+
+This will remove your spending policy completely and remove
+the Bypass PIN. Your COLDCARD will be back to normal.
+
+## Test Drive
+
+Experiment with how the COLDCARD will function if the Spending
+Policy was enabled. You can try to sign transactions that should
+be rejected and view the menus in the new mode without rebooting.
+
+Choose "EXIT TEST DRIVE" on top menu to return to the Spending
+Policy menu. Reboot will also restore normal operation without
+any special challenges.
+
+## ACTIVATE
+
+This step will enable the Spending Policy and return to the
+main menu with it in effect. When you reboot the COLDCARD,
+the policy will still be in effect. You must use the
+Bypass PIN, followed by the normal main PIN, possibly
+followed by entering the first and last words of your seed
+phrase, before you can disable and change the policy.
+
+We recommend test-driving the feature before doing that.
+
+
+# Tips and Tricks
+
+## Money Manager Mode
+
+You could setup a Coldcard for another person, perhaps a family member,
+and enable web 2FA authentication. There does not need to be any
+other spending policy limits (velocity could be unlimited).
+
+Then enroll your own phone with the required 2FA values, and
+keep both that and the spending policy bypass PIN confidential.
+
+The holder the the Coldcard will need a 2FA code from your phone
+when they want to spend. They can call you for the 6-digit code
+from the 2FA app on your phone. This is not hard to provide over a
+voice call.
+
+Because a spending policy is in effect, they will not be able to
+see the seed words, other private key material, so regardless of
+any spoofing or phishing, they cannot move funds without your help.
+
+You should record the bypass PIN, so it can be revealed somehow,
+should you die. You do not need to share the risks associated with
+holding a copy of the seed words.
+
+## Passphrase Considerations
+
+If you are using the same BIP-39 passphrase for everything, you should
+probably do a "Lock Down Seed" (Advanced/Tools > Danger Zone > Seed
+Functions) first. This takes your master seed and BIP-39 passphrase
+and cooks them together into an XPRV which then is stored as your
+master secret. (Replacing the master seed phrase.) This process
+cannot be reversed, so other funds you may have on the same seed
+words are protected. Once you are operating in XPRV mode, you can
+define a spending policy, and know that it is restricted to only
+that wallet.
+
+When operating in XPRV mode, the "Passphrase" menu item is not shown
+because BIP-39 passwords cannot be applied to XPRV secrets.
+
+## Trick PIN Thoughts
+
+When doing your game theory w.r.t to bypass mode and this feature,
+remember that you should assume the attacker already has your main
+PIN. That's how they know they cannot spend all your coin, because
+they either tried to, or noticed the menus are very limited. They also
+have all your UTXO locations and total wallet balance (because they
+can export your xpubs to any wallet and load balance from there).
+
+Therefore, a trick pin that leads to a duress wallet after giving up 
+the bypass unlock PIN, will not fool them. Best would be to provide
+a false bypass PIN that is in fact a brick/wipe PIN.
+
+
+## Lock Out Changes to Policy
+
+In the Trick Pin menu once Spending Policy has been enabled, you will
+find the Bypass PIN listed.  You could delete or "hide" it. Hiding
+it is pointless since you cannot get to the trick PIN menu while
+the policy is in effect. Deleting the PIN however, is useful because
+it assures changes to spending policy are impossible. To recover
+the COLDCARD when this move is later regretted, under Advanced,
+there is "Destroy Seed" option which will clear the seed words and
+all settings, including the spending policy.
+
+### Unlock Policy & Wipe
+
+We've provided a new trick PIN that pretends to be the unlock
+spending policy pin, so the login sequence is correct... but it
+will wipe the seed in the process. It will be obvious to your
+attackers that you've wiped the seed because the main PIN will lead
+to blank wallet now (no seed loaded).
+
+### Delta Mode and Spending Policy
+
+If, from the start, you gave your "delta mode PIN" to the attackers,
+then when they bypass the policy (after also getting the bypass PIN
+from you), they will still be in Delta Mode.
+
+They could attempt unlimited spending, but transactions signed will
+not be valid. If they try to view the seed words or generally export
+private key material, they will hit many of the "wipe seed if delta
+mode" cases.
+
+## Forgotten Bypass PIN Code
+
+If you've enabled a spending policy and still remember the main PIN,
+but cannot disable the feature because you've forgotten the Bypass
+PIN, your only option is to use `Advanced > Destroy Seed`. After
+some confirmations, this erases the master seed, all settings, seed
+vault items, secure notes, and trick pins. It's basically a factory
+reset except for the main PIN code which is unchanged. Once you've
+done that, you can enter your seed words from backup (or restore a
+backup file) and continue to use the COLDCARD again.
+
+

docs/temporary-seeds.md

@@ -0,0 +1,122 @@
+# Temporary Seeds
+
+
+[_(new in v5.0.7, requires Mk4, Mk5, or Q)_](upgrade.md)
+
+
+Temporary seed (renamed in `5.2.0` from Ephemeral seed) is a temporary secret completely separate 
+from the master seed, typically held in **COLDCARD<sup>&reg;</sup>** RAM and 
+not persisted between reboots in the Secure Element.
+Temporary seeds *completely* defeat the design
+of Coldcard's security model, based on secure elements.
+Enable the `Seed Vault` feature to store these secrets longer-term.
+Read more about `Seed Vault` feature below.
+
+
+!!! warning "Make sure you know what you're doing!"
+
+    This feature is intended for those one-off signings, like recovering
+    a lost seed from some other system or importing some seed as a
+    balance check. We do not recommend handing unencrypted seed material
+    on a regular basis!
+
+
+## Usage
+
+* if temporary seed is already in use, first home menu option `[<xfp>]` is visible with fingerprint of temporary master secret
+* go to `Advanced/Tools > Temporary Seed`
+
+* temporary seed words can be Generated with TRNG
+    - `Advanced/Tools > Temporary Seed > Generate Words`
+
+* temporary seed words can be imported
+    - `Advanced/Tools > Temporary Seed > Import Words`
+
+* importing extended private keys
+    - `Advanced/Tools > Temporary Seed > Import XPRV`
+    - `Advanced/Tools > Temporary Seed > Tapsigner Backup`
+
+* temporary seed can be activated from BIP-85 derived secrets - go to `Advanced/Tools > Derive Seed B85` and pick types of secret. Keep in mind that only word based and xprv based secrets can be used as temporary seed.
+    - `12 words`
+    - `18 words`
+    - `24 words`
+    - `XPRV (BIP-32)`
+    - pick derivation `Index` in next prompt, or just press OK for index 0
+    - Press (0) in next prompt to activate derived secret as a temporary seed
+
+* temporary seed can be activated from Duress Wallet
+    - go to `Settings -> Login Settings -> Trick Pins`
+    - add new Duress Wallet trick pin and save it
+    - choose newly created trick pin in trick pins menu and use `Activate Wallet` option
+
+* temporary seed can be obtained from `SeedXOR`
+    - go to `Advanced/Tools -> Danger Zone -> Seed Functions -> SeedXOR`
+    - pick `Restore Seed XOR` option and provide all XOR parts
+    - Press (2) to activate restored seed as temporary seed
+
+* BIP-39 passphrase is from version `5.2.0` handled internally as temporary seed
+
+
+Ability to generate and use **Temporary seed** is available on Coldcard when:
+
+1. no PIN chosen and no secret chosen (newly unpacked Coldcard)
+2. PIN set up but no secret chosen yet
+3. with both PIN and secret already picked
+
+
+# Restore Master
+
+[_(new in v5.2.0, requires Mk4, Mk5, or Q)_](upgrade.md)
+
+From version `5.2.0` users no longer need to reboot COLDCARD to return
+to their "master seed" (one stored in SE2). Once COLDCARD has temporary
+seed active, first item in home menu is `[xfp]` and is a clone of `Ready To Sign`.
+Last item in home menu is `Restore Master`.
+
+`Restore Master` offers two options. First, if user presses OK, COLDCARD wipes temporary seed settings
+and switches back to master seed and its settings.
+If user presses (1) temporary seed settings are preserved for later use and COLDCARD only switches
+back to master seed and its settings.
+
+If current temporary seed is also saved in Seed Vault, option to wipe settings is not available.
+Seed Vault entries can only be deleted in Seed Vault menu.
+
+
+# Seed Vault
+
+[_(new in v5.2.0, requires Mk4, Mk5, or Q)_](upgrade.md)
+
+Seed Vault adds the ability to store multiple temporary secrets into encrypted settings for simple
+recall and later use (AES-256-CTR encrypted with your master seed's key).
+Users can capture and hold master secret from any temporary seed source, including: TRNG, Dice Rolls,
+SeedXOR, TAPSIGNER backups, BIP-85 derived values, BIP-39 passphrase wallets.
+
+## Enable Seed Vault
+
+Enable this functionality in `Advanced/Tools -> Danger Zone -> Seed Vault -> Enable`.
+Once seed vault is enabled new menu item is visible in home menu `Seed Vault`.
+To disable Seed Vault user needs to remove all entries from Seed Vault first.
+
+
+## Add Seed to Vault
+
+After `Seed Vault` is enabled, users will see a new prompt, after
+creation of temporary seed, asking whether to save this temporary
+seed to Seed Vault. Press (1) to save or any other key to ignore.
+
+If option to save was chosen, confirmation prompt is shown - `Saved to seed vault.`
+
+
+## Seed Vault menu
+
+* if Seed Vault is empty `(none saved yet)` is the first menu item followed by shortcut to `Temporary Seed` menu.
+* if not empty, saved seeds are listed in menu as `[xfp]`
+* if current active temporary seed is stored in Seed Vault - it has checkmark next to it
+* if temporary seed is active - last menu item of Seed Vault menu is `Restore Master`
+
+## Seed Vault entry submenu
+
+1. by default `[xfp]` but can be renamed to allow user labeling and leads to additional information about the seed
+2. `Use This Seed` allows to switch to the saved temporary seed. If it is already active `In Use` is shown instead.
+3. `Rename` allows to change 1. menu item to something personalized to user (limited to 40 characters)
+4. `Delete` allows to remove temporary seed from Seed Vault and optionally to completely wipe its settings.

docs/upgrade-recovery.md

@@ -1,11 +1,12 @@
 
 # Firmware Upgrade and Recovery Process
 
-_This document applies only to the Mk4. Earlier COLDCARDs did not use this approach._
+_This document applies to the Mk4, Mk5, and Q. Earlier COLDCARDs did not use this approach._
 
-On the new Mk4 COLDCARD, we have done away with the slow external
-SPI flash (serial flash) chip entirely. In it's place we use a much
-faster and huge 64 Mbit PSRAM chip (quad SPI RAM chip: ESP-PSRAM64H).
+On the COLDCARD, we have done away with the slow external SPI flash
+(serial flash) chip entirely (used in Mk1-Mk3). In it's place we
+use a much faster and huge 64 Mbit PSRAM chip (quad SPI RAM chip:
+ESP-PSRAM64H).
 
 This chip is volatile and forgets its contents at power down.
 
@@ -14,7 +15,7 @@ can be a problem during firmware upgrades. This document explains
 how we've solved the risks of firmware upgrades and possible bricking
 that can happen with power fails at just the wrong time.
 
-## Firmware Upgrade Process on Mk4
+## Firmware Upgrade Process
 
 Steps:
 
@@ -26,7 +27,7 @@ Steps:
 - a checksum is calculated over the new firmware, and the current contents of
   flash, including the bootloader code, its secrets, unique identity bits
   (for the main chip). We call this the "world checksum".
-- before anything else happens, we update the main secure element (608B) with
+- before anything else happens, we update the main secure element (608C) with
   the world checksum, and during boot, knowledge of the world checksum is required
   to light the green genuine light.
 - the light stays green at this point, and the system could still boot the old firmware
@@ -79,7 +80,7 @@ to main flash. The PSRAM will forget it's contents, and the COLDCARD
 no longer has a complete copy of firmware anywhere.
 
 Most products would be a "brick" at this point, and the docs would
-warn against power fails during upgrade.  However, the Mk4 can read
+warn against power fails during upgrade.  However, the COLCARD can read
 SD Cards to load replacement firmware. The card does not need to
 be specially prepared, but we recommend erasing it, formating with
 FAT32 and then copying just the firmware onto the card.
@@ -91,7 +92,7 @@ Once a card is inserted, a search is made for a suitable firmware file.
 All DFU files will be considered, but you must provide the firmware
 file that you were attempting to upgrade to during the power failure,
 because the "world checksum" is calculated for each image found on
-the card. You will not be able to substitue a newer version of firmware.
+the card. You will not be able to substitute a newer version of firmware.
 Of course, firmware factory signatures are checked as well.
 
 

docs/web2fa.md

@@ -0,0 +1,97 @@
+# Web 2FA Authentication
+
+How to support [RFC 6238](https://www.rfc-editor.org/rfc/rfc6238)
+TOTP (Time based One Time Password) 2FA check, on our little embedded
+device without a real-time clock?
+
+Solution: Store the pre-shared secret in the COLDCARD, and send that
+securely to a trusted webserver which knows the time and can do a
+fancy UX. That webserver accepts the time-based-one-time 2FA numeric
+code from the user, and if correct, reveals a secret
+that can be used back on the COLDCARD to authorize an action.
+
+For the Mk4, the secret is 8 digit numeric code to be entered,
+for the COLDCARD Q, it is a QR code to be scanned.
+
+### History / Background
+
+The HSM feature uses HOTP tokens, which do not require a backend,
+but are not as robust as time-based tokens.
+
+Web2FA is available to be enabled as part of a Spending Policy,
+both in Multisig and Single Signer modes. When enabled, you will be
+prompted complete 2FA authentication after viewing the details of
+the transaction to be signed. You will not be able to sign without
+the correct code.
+
+## How It Works
+
+- Web backend has a ECC keypair, with pubkey known to CC firmware releases.
+- Usual 2fa base32 secret is picked by CC and stored in CC (so that server is stateless)
+- CC creates URL encrypted to the pubkey of server, containing args: 
+  - shared secret for TOTP (same value as held in user's phone)
+  - the response nonce (32 bytes, shown as 64 hex chars, on Q; or 8 digits on Mk4)
+    to be revealed to the user on successful auth
+  - flag if Q model, so can provide a QR to be scanned in that case (rather than digits)
+  - some text label for what's being approved, which is presented to user so they can pick
+    correct 2fa shared secret.
+  - above is all encrypted in transit, and only the server can decrypt
+- user is sent to that encrypted URL using NFC tap on the COLDCARD
+- user arrives at server:
+  - shown label [which also indicates the server can be trusted, since only it could decrypt it]
+  - prompt for 6 digits from authenticator app
+  - does [RFC 6238](https://www.rfc-editor.org/rfc/rfc6238) 2FA check using current time
+- checks using current time and the shared secret provided by CC, fails if wrong.
+  - time based failure: offer retry (they typed too slow / minor clock drift)
+  - can offer to retry, but also do some rate limiting (only one attempt per 30-sec period)
+  - server will store very recent responses so attacker cannot get two codes
+    in any 30sec period (ie. blocks immediate reuse of same URL)
+  - until a valid code is given, user is stuck here
+- when valid token received:
+    - if Q, show a QR code to be scanned, with the full nonce
+    - for non-Q system, a 8-digit decimal value is given: user has to enter that into the COLDCARD
+    - web site shows instructions about what to do next on product.
+
+## From COLDCARD PoV
+
+- makes complex encrypted URL, which contains a nonce it wants, waits for that nonce back (or QR)
+- it's either the nonce from the URL, or fail
+- if the right nonce, then we know the server knows the decryption key, and we
+  are trusting it actually verify the 2FA token properly.
+
+## Encryption - Simple ECDH
+
+- CC picks a secp256k1 keypair, generates compressed pubkey
+- multiplies that private key by server's known public key
+- apply sha256(resulting coordinate) => the session key
+- apply AES-256-CTR over URL contents (ascii text)
+- prepend 33 bytes of pubkey, and then base64url encode all of it
+- full url is: `https://coldcard.com/2fa?{base64 encoded binary}`
+
+## Trust Issues
+
+- 2FA enrol happens on the CC, which picks the shared secret and shows QR for mobile
+  app setup. Same TRNG process as picking a seed.
+- Server knows the shared secret, but only during operation, and we won't store it [sorry,
+  gotta trust us on that, but no help to us to store it].
+- Only we can run the server, because the private key is company-secret.
+- MiTM and network snoopers get nothing because HTTPS is used and only your browser
+  can see the nonce, and only after you've given the right digits.
+- Coinkite server could skip the 2FA checks and just give you the answer
+  you want to type into the COLDCARD. Again, you have to trust us on that.
+
+## URL Format 
+
+    https://coldcard.com/2fa?g={nonce}&ss={shared_secret}&nm={label_text}&q={is_q}
+
+(the query string is then encrypted to the server's pubkey, so the args above
+are what is inside the encrypted payload.)
+
+- `nonce`: text string that is either 8 digits on Mk4, or 64 hex chars on Q
+- `shared_secret`: 16 chars of Base32-encoded pre-shared secret
+- `nm`: human readable label for the transaction/purpose
+- `is_q`: flag indicating use of QR to provide nonce back to user
+
+Server will accept plaintext arguments as above, but normally everything
+after the question mark is encrypted.
+

external/README.md

@@ -1,7 +1,7 @@
 
 ## Background on Submodules
 
-This project uses many submodules, and to build the final produts, you will
+This project uses many submodules, and to build the final products, you will
 have to get all the submodules into place and build them in appropriate orders.
 
 A good resource, from an unrelated project, is:

external/ckcc-protocol

@@ -1 +1 @@
-Subproject commit ef61911047e77d54bc0c6edd5400a424405d814e
+Subproject commit 3d1dfa858beb58b8dac37d8c66d7aed2909812f2

external/libngu

@@ -1 +1 @@
-Subproject commit 61ffc74af171197ef5d5d79b78b59ab750ef35c7
+Subproject commit 537519a829259622ea6b0334fbafd6cae852852f

external/micropython

@@ -1 +1 @@
-Subproject commit 6d7527823c3fd9b2c860c8cc1612cc68f6e2cef2
+Subproject commit 4107246f8a080807b62c3b4838e71e812ea68b6f

external/mpy-qr

@@ -1 +1 @@
-Subproject commit 3ccf19ca142e9059904f0c8e53b6baeccb9c6b79
+Subproject commit 11347d83f4eb325b10676a4eb8e17deccfe0df44

graphics/Makefile

@@ -1,15 +1,16 @@
 # (c) Copyright 2018 by Coinkite Inc. This file is covered by license found in COPYING-CC.
 
-all: graphics.py graphics_mk4.py
+all: graphics_mk4.py graphics_q1.py
 	
-SOURCES = $(filter-out mk4_%, $(wildcard *.txt) $(wildcard *.png))
-MK4_SOURCES = $(wildcard mk4_*.txt) $(wildcard mk4_*.png)
-
-graphics.py: Makefile $(SOURCES) build.py
-	./build.py graphics.py $(SOURCES)
+MK4_SOURCES = $(wildcard mono/*.txt) $(wildcard mono/*.png)
+Q1_SOURCES = colour/*.???
 
 graphics_mk4.py: Makefile $(MK4_SOURCES) build.py
 	./build.py graphics_mk4.py $(MK4_SOURCES)
 
+graphics_q1.py: Makefile $(Q1_SOURCES) compress.py
+	./compress.py graphics_q1.py $(Q1_SOURCES)
+
 up: all
 	(cd ../shared; make up)
+

graphics/build.py

@@ -33,7 +33,7 @@ def read_text(fname):
 def read_img(fn):
     img = Image.open(fn)
     w,h = img.size
-    assert 1 <= w < 128, w
+    assert 1 <= w < 128, (w, fn)
 
     img = img.convert('L')
     # fix colour issues: assume minority colour is white (1)
@@ -88,7 +88,7 @@ class Graphics:
         assert img.mode == '1'
         #img.show()
 
-        varname = fn.split('.')[0].replace('-', '_')
+        varname = fn.split('/')[-1].split('.')[0].replace('-', '_')
 
         w,h = img.size
         raw = img.tobytes()

graphics/compress.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+#
+# (c) Copyright 2023 by Coinkite Inc. This file is covered by license found in COPYING-CC.
+#
+# Read in PNG (or even JPG) and output heavily compressed RGB565 data suited to Q1's LCD panel.
+#
+# - also renders status bar icons/indicators
+#
+import os, sys, pdb
+from PIL import Image, ImageOps, ImageFont, ImageDraw
+import zlib
+from struct import pack
+
+WBITS = -10
+
+FONT_PATH = './fonts/'
+
+def read_img(fn):
+    img = Image.open(fn)
+    w,h = img.size
+    assert 1 <= w <= 320, f'too wide; {w}'
+    assert 1 <= h <= 240, f'too tall: {h}'
+
+    img = img.convert('RGB')
+
+    # maybe: quantitize to a reasonable num colours, so compression
+    # can work better?
+
+    return img
+
+def compress(n, wbits=WBITS):
+    # NOTE: neg wbits implies no zlib header, and receiver may need to know it?
+    z = zlib.compressobj(wbits=wbits, level=zlib.Z_BEST_COMPRESSION)
+    rv = z.compress(n)
+    rv += z.flush(zlib.Z_FINISH)
+    return rv
+
+def crunch(n):
+    # try them all... not finding any difference tho.
+    a = [(wb,compress(n, wb)) for wb in range(-9, -15, -1)]
+
+    a.sort(key=lambda i: (-len(i[1]), -i[0]))
+
+    print("Wbit values:")
+    print('\n'.join("%3d => %d" % (wb,len(d)) for wb,d in a))
+
+    return a[0]
+
+# LCD Display wants RGB565 values, but big endian, so green gets split weird.
+def swizzle(r,g,b):
+    # from 0-255 per component => two bytes
+    b = (b >> 3)
+    g = (g >> 3)        # should be >> 2 for 6 bits; but looks trash?
+    r = (r >> 3)
+
+    return pack('>H', ((r<<11) | (g<<6) | b))
+
+# these values tested on real hardware
+assert swizzle(255, 0, 0) == b'\xf8\x00'        # red
+##assert swizzle(0, 255, 0) == b'\xc0\x0f'        # green (6 bits)
+assert swizzle(0, 255, 0) == b'\x07\xc0'        # green (5 bits)
+assert swizzle(0, 0, 255) == b'\x00\x1f'        # blue
+
+        
+def into_bgr565(img):
+    # get the raw bytes needed for this specific display
+    rv = bytearray()
+    for y in range(img.height):
+        for x in range(img.width):
+            px = img.getpixel((x, y))
+            assert len(px) == 3
+            r,g,b = px
+            rv.extend(swizzle(r,g,b))
+
+    return rv
+
+def make_icons():
+    # return list of (varname, img) for each image
+    
+    # - see  shared/lcd_display.py TOP_MARGIN for this
+    ICON_SIZE = 14
+    MAX_HEIGHT = 14
+
+    # PROBLEM: this file costs money... altho free version looks okay too
+    try:
+        awesome = ImageFont.truetype(FONT_PATH + 'Font Awesome 6 Sharp-Regular-400.otf', ICON_SIZE)
+    except:
+        raise
+
+    # use a bitmap font for best readability
+    sm_font = ImageFont.load('ter-powerline-x12b.pil')
+
+    targets = [
+        #( 'brand', True, 'Q', dict(col='#ffb000') ),
+        ( 'shift', True, 'SHIFT', {} ),
+        ( 'symbol', True, 'SYM', {} ),
+        ( 'caps', True, 'CAPS', {} ),
+        ( 'bip39', True, 'PASSPHRASE', dict(col_1='yellow') ),
+        ( 'tmp', True, 'TMP.SEED', dict(col_0='black', col_1='red') ),
+        ( 'devmode', True, 'DEV', dict(col='#66E6FF') ),
+        ( 'edge', True, 'EDGE', dict(col='#66E6FF') ),
+        ( 'bat_0', False, '\uf244', dict(col='red', y=-1, pad=1)),
+        ( 'bat_1', False, '\uf243', dict(col='yellow', y=-1, pad=1)),
+        ( 'bat_2', False, '\uf242', dict(col='amber', y=-1, pad=1)),
+        ( 'bat_3', False, '\uf240', dict(col='amber', y=-1, pad=1)),
+        ( 'plugged', False, '\uf1e6', dict(col='amber', x=3, w=16, y=-2)),   # to match width of bat_*
+        #( 'locked', False, '\uf023', dict(col='green')),
+        #( 'unlocked', False, '\uf3c1', dict(col='green')),      # why tho?
+    ]
+
+    targets += [ ( 'ch_'+c, True, c.upper(), dict(col='white') ) for c in 
+                    '0123456789abcdef']
+
+    samples = Image.new('RGB', (320*3, ICON_SIZE+1))
+    s_x = 5
+
+    for basename, is_text, body, opts in targets:
+        for state in [0, 1]:
+            col = opts.get('col', '#fff' if state else '#444')
+            vn = f'{basename}_{state}'
+
+            if 'col' in opts:
+                if state == 0: continue
+                vn = basename
+
+            if state == 0 and 'col_0' in opts:
+                col = opts['col_0']
+            if state == 1 and 'col_1' in opts:
+                col = opts['col_1']
+
+            img = Image.new('RGB', (100,100))
+            d = ImageDraw.Draw(img)
+            f = sm_font if is_text else awesome
+
+
+            x, y = (0, 1 if is_text else 0)
+            y += opts.get('y', 0)
+            x += opts.get('x', 0)
+
+            tl = (x, y)
+            _,_, w,h = d.textbbox(tl, body, font=f)
+
+            w = opts.get('w', w)
+
+            if h > MAX_HEIGHT:
+                h = MAX_HEIGHT
+                print(f'"{vn}" too tall, cropped')
+            elif opts.get('pad'):
+                h = MAX_HEIGHT
+
+            if col == 'amber':
+                # brand colour
+                col = '#ffb000'
+
+            d.text(tl, body, font=f, fill=col)
+            rv = img.crop( (0, 0, w,h) )
+
+            samples.paste(rv, (s_x, 0))
+            s_x += w + 10
+
+            yield (vn, rv)
+            
+    samples = samples.crop( (0,0, s_x, samples.height ))
+    samples.save('icon-samples.png')
+            
+    
+
+def doit(outfname, fnames):
+
+    assert outfname.endswith('.py')
+    assert outfname != 'compress.py'
+    assert fnames, "need some files"
+
+    fp = open(outfname, 'wt')
+
+    fp.write("""\
+# autogenerated; don't edit
+#
+# BGR565 pixel data
+#
+class Graphics:
+    # (w,h, data)
+
+""")
+
+    fnames += make_icons()
+
+    for fn in fnames:
+        if isinstance(fn, str):
+            img = read_img(fn)
+            varname = fn.split('/')[-1].split('.')[0].replace('-', '_')
+        else:
+            varname, img = fn
+
+        assert img.mode == 'RGB'
+
+        w,h = img.size
+        raw = into_bgr565(img)
+        comp = compress(raw)
+        #crunch(raw)
+
+        print("    %s = (%d, %d,\n     %r\n    )\n" % (varname, w, h, comp), file=fp)
+
+        print("done: '%s' (%d x %d) => %d raw => %d compressed bytes" % (
+                    varname, w, h, len(raw), len(comp)))
+
+    fp.write("\n# EOF\n")
+
+if 1:
+    doit(sys.argv[1], sys.argv[2:])
+
+# EOF

graphics/cylon.py

@@ -1,4 +1,7 @@
 #!/usr/bin/env python3
+#
+# Generate some data for hsm_ux.py animation
+#
 from math import sin, pi
 from collections import Counter
 

graphics/fonts/.gitignore

@@ -0,0 +1,3 @@
+Font Awesome 6*.otf
+iosevka-*.ttf
+!iosevka-heavy.ttf

graphics/fonts/README.md

@@ -0,0 +1,11 @@
+
+# Fonts for Q1
+
+This directory may contain font files from Font Awesome.
+
+We cannot re-distribute the OTF files themselves due to their license.
+
+However, once we render and build the compressed graphics file that we need,
+the font is not required anymore.
+
+Iosveka is open and can be re-distributed here.

graphics/fonts/font-awesome-license.txt

@@ -0,0 +1,18 @@
+Font Awesome Pro License
+------------------------
+
+Font Awesome Pro is commercial software that requires a paid license. Full
+Font Awesome Pro license: https://fontawesome.com/license.
+
+# Commercial License
+The Font Awesome Pro commercial license allows you to pay for FA Pro once, own
+it, and use it just about everywhere you'd like.
+
+# Attribution
+Attribution is not required by the Font Awesome Pro commercial license.
+
+# Brand Icons
+All brand icons are trademarks of their respective owners. The use of these
+trademarks does not indicate endorsement of the trademark holder by Font
+Awesome, nor vice versa. **Please do not use brand logos for any purpose except
+to represent the company, product, or service to which they refer.**

graphics/graphics.py

@@ -1,27 +0,0 @@
-# autogenerated; don't edit
-#
-class Graphics:
-    # (w,h, w_bytes, wbits, data)
-
-    arrow_down = (7, 11,  1, 0, b'\x10\x10\x10\x10\x10\x10\x10\xfe|8\x10')
-
-    arrow_up = (7, 11,  1, 0, b'\x108|\xfe\x10\x10\x10\x10\x10\x10\x10')
-
-    box = (13, 21,  2, 0, b'?\xe0@\x10\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08@\x10?\xe0')
-
-    scroll = (3, 61,  1, 0, b'@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@@\xe0@')
-
-    selected = (15, 12,  2, 0, b'\x00\x00\x00\x00\x00\x06\x00\x0c\x00\x18\x0000`\x18\xc0\r\x80\x07\x00\x02\x00\x00\x00')
-
-    sm_box = (11, 17,  2, 0, b'\xe4\xe0\x80 \x80 \x80 \x00\x00\x00\x00\x80 \x00\x00\x00\x00\x00\x00\x80 \x00\x00\x00\x00\x80 \x80 \x80 \xe4\xe0')
-
-    space = (9, 2,  2, 0, b'\x80\x80\xff\x80')
-
-    spin = (13, 36,  2, 0, b'\x02\x00\x07\x00\x0f\x80\x1f\xc0\x00\x00\x00\x00\x00\x00\xf2x\x80\x08\x80\x08\x80\x08\x00\x00\x00\x00\x80\x08\x00\x00\x00\x00\x00\x00\x80\x08\x00\x00\x00\x00\x00\x00\x80\x08\x00\x00\x00\x00\x80\x08\x80\x08\x80\x08\xf2x\x00\x00\x00\x00\x00\x00\x1f\xc0\x0f\x80\x07\x00\x02\x00\x00\x00')
-
-    wedge = (6, 11,  1, 0, b'\x00\x00\xc0\xe0p8\x1c8p\xe0\xc0')
-
-    xbox = (13, 21,  2, 0, b'?\xe0b0\x88\x88\xa2(\x88\x88\xa2(\x88\x88\xa2(\x88\x88\xa2(\x88\x88\xa2(\x88\x88\xa2(\x88\x88\xa2(\x88\x88\xa2(\x88\x88b0?\xe0')
-
-
-# EOF

graphics/graphics_mk4.py

@@ -3,6 +3,12 @@
 class Graphics:
     # (w,h, w_bytes, wbits, data)
 
+    arrow_down = (7, 11,  1, 0, b'\x10\x10\x10\x10\x10\x10\x10\xfe|8\x10')
+
+    arrow_up = (7, 11,  1, 0, b'\x108|\xfe\x10\x10\x10\x10\x10\x10\x10')
+
+    box = (13, 21,  2, 0, b'?\xe0@\x10\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08\x80\x08@\x10?\xe0')
+
     mk4_nfc_1 = (126, 49,  16, 0, b'\x00\x7f\xff\xff\xff\xfc\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xcf\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xcf\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xcf\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xcf\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x0e\x00\xe0\x0e\x03\xff\xff\xff\xff\xff\xff\xff\xff\x80\x00\xe0\x0e\x00\xe0\x0e\x07\xff\xff\xff\xff\xff\xff\xff\xff\xe0\x00\xe0\x0e\x00\xe0\x0e\x1f\xff\xff\xff\xff\xff\xff\xff\xff\xf0\x00\xe0\x0e\x00\xe0\x0e0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0\x0e0\x00 G\xe3\xe0\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0\x0e0\x00 G\xe3\xe0\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0\x0e0\x000D\x04\x10\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0\x0e0\x000D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00(D\x04\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00(D\x04\x00\x00\x00xp\x00\xff\xff\xff\xff\xfe0\x00$G\xe4\x00\x00\x00xp\x00\xff\xff\xff\xff\xfe0\x00$G\xe4\x00\x00\x00xp\x00\xe0\x0e\x00\xe0\x0e0\x00"D\x04\x00\x00\x00xp\x00\xe0\x0e\x00\xe0\x0e0\x00"D\x04\x00\x00\x00xp\x00\xe0\x0e\x00\xe0\x0e0\x00 \xc4\x04\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0\x0e0\x00 \xc4\x04\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00 D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00 D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00 D\x03\xe0\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00 D\x03\xe0\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0\x0e0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0\x0e0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0\x0e0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0\x0e?\xff\xff\xff\xff\xff\xff\xff\xff\xe0\x00\xff\xff\xff\xff\xfe\x1f\xff\xff\xff\xff\xff\xff\xff\xff\xc0\x00\xff\xff\xff\xff\xfe\x0f\xff\xff\xff\xff\xff\xff\xff\xff\x00\x00\x7f\xff\xff\xff\xfc\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00?\xff\xff\xff\xf8\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')
 
     mk4_nfc_2 = (118, 49,  15, 0, b'\x00\x7f\xff\xff\xff\xfc\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xcf\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xcf\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xcf\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xcf\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xe0\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x0e\x00\xe0\x03\xff\xff\xff\xff\xff\xff\xff\xff\x80\x00\xe0\x0e\x00\xe0\x07\xff\xff\xff\xff\xff\xff\xff\xff\xe0\x00\xe0\x0e\x00\xe0\x1f\xff\xff\xff\xff\xff\xff\xff\xff\xf0\x00\xe0\x0e\x00\xe00\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe00\x00 G\xe3\xe0\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe00\x00 G\xe3\xe0\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe00\x000D\x04\x10\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe00\x000D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00(D\x04\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00(D\x04\x00\x00\x00xp\x00\xff\xff\xff\xff0\x00$G\xe4\x00\x00\x00xp\x00\xff\xff\xff\xff0\x00$G\xe4\x00\x00\x00xp\x00\xe0\x0e\x00\xe00\x00"D\x04\x00\x00\x00xp\x00\xe0\x0e\x00\xe00\x00"D\x04\x00\x00\x00xp\x00\xe0\x0e\x00\xe00\x00 \xc4\x04\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe00\x00 \xc4\x04\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00 D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00 D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00 D\x03\xe0\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00 D\x03\xe0\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe00\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe00\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe00\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0?\xff\xff\xff\xff\xff\xff\xff\xff\xe0\x00\xff\xff\xff\xff\x1f\xff\xff\xff\xff\xff\xff\xff\xff\xc0\x00\xff\xff\xff\xff\x0f\xff\xff\xff\xff\xff\xff\xff\xff\x00\x00\x7f\xff\xff\xff\xfc\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00?\xff\xff\xff\xf8\x00\x00\x00\x00\x00\x00\x00\x00\x00')
@@ -11,5 +17,27 @@ class Graphics:
 
     mk4_nfc_4 = (102, 49,  13, 0, b'\x00\x7f\xff\xff\xff\xfc\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xcf\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xcf\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xcf\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xcf\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x03\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xf0\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x0e\x03\xff\xff\xff\xff\xff\xff\xff\xff\x80\x00\xe0\x0e\x07\xff\xff\xff\xff\xff\xff\xff\xff\xe0\x00\xe0\x0e\x1f\xff\xff\xff\xff\xff\xff\xff\xff\xf0\x00\xe0\x0e0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e0\x00 G\xe3\xe0\x00\x00\x7f\xf0\x00\xe0\x0e0\x00 G\xe3\xe0\x00\x00\x7f\xf0\x00\xe0\x0e0\x000D\x04\x10\x00\x00\x7f\xf0\x00\xe0\x0e0\x000D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00(D\x04\x00\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00(D\x04\x00\x00\x00xp\x00\xff\xff\xb0\x00$G\xe4\x00\x00\x00xp\x00\xff\xff\xb0\x00$G\xe4\x00\x00\x00xp\x00\xe0\x0e0\x00"D\x04\x00\x00\x00xp\x00\xe0\x0e0\x00"D\x04\x00\x00\x00xp\x00\xe0\x0e0\x00 \xc4\x04\x00\x00\x00\x7f\xf0\x00\xe0\x0e0\x00 \xc4\x04\x00\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00 D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00 D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00 D\x03\xe0\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00 D\x03\xe0\x00\x00\x7f\xf0\x00\xe0\x0e0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e?\xff\xff\xff\xff\xff\xff\xff\xff\xe0\x00\xff\xff\x9f\xff\xff\xff\xff\xff\xff\xff\xff\xc0\x00\xff\xff\x8f\xff\xff\xff\xff\xff\xff\xff\xff\x00\x00\x7f\xff\xc0\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00?\xff\xff\xff\xf8\x00\x00\x00\x00\x00\x00\x00')
 
+    mk5_nfc_1 = (126, 49,  16, 0, b'\x00\x7f\xff\xff\xff\xfc\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xf0\xf0\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x0e\x00\xe0\x0e\x03\xff\xff\xff\xff\xff\xff\xff\xff\x80\x00\xe0\x0e\x00\xe0\x0e\x07\xff\xff\xff\xff\xff\xff\xff\xff\xe0\x00\xe0\x0e\x00\xe0\x0e\x1f\xff\xff\xff\xff\xff\xff\xff\xff\xf0\x00\xe0\x0e\x00\xe0\x0e0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0\x0e0\x00 G\xe3\xe0\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0\x0e0\x00 G\xe3\xe0\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0\x0e0\x000D\x04\x10\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0\x0e0\x000D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00(D\x04\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00(D\x04\x00\x00\x00xp\x00\xff\xff\xff\xff\xfe0\x00$G\xe4\x00\x00\x00xp\x00\xff\xff\xff\xff\xfe0\x00$G\xe4\x00\x00\x00xp\x00\xe0\x0e\x00\xe0\x0e0\x00"D\x04\x00\x00\x00xp\x00\xe0\x0e\x00\xe0\x0e0\x00"D\x04\x00\x00\x00xp\x00\xe0\x0e\x00\xe0\x0e0\x00 \xc4\x04\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0\x0e0\x00 \xc4\x04\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00 D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00 D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00 D\x03\xe0\x00\x00\x7f\xf0\x00\xff\xff\xff\xff\xfe0\x00 D\x03\xe0\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0\x0e0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0\x0e0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0\x0e0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0\x0e?\xff\xff\xff\xff\xff\xff\xff\xff\xe0\x00\xff\xff\xff\xff\xfe\x1f\xff\xff\xff\xff\xff\xff\xff\xff\xc0\x00\xff\xff\xff\xff\xfe\x0f\xff\xff\xff\xff\xff\xff\xff\xff\x00\x00\x7f\xff\xff\xff\xfc\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00?\xff\xff\xff\xf8\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')
+
+    mk5_nfc_2 = (118, 49,  15, 0, b'\x00\x7f\xff\xff\xff\xfc\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xf0\xf0\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xe0\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x0e\x00\xe0\x03\xff\xff\xff\xff\xff\xff\xff\xff\x80\x00\xe0\x0e\x00\xe0\x07\xff\xff\xff\xff\xff\xff\xff\xff\xe0\x00\xe0\x0e\x00\xe0\x1f\xff\xff\xff\xff\xff\xff\xff\xff\xf0\x00\xe0\x0e\x00\xe00\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe00\x00 G\xe3\xe0\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe00\x00 G\xe3\xe0\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe00\x000D\x04\x10\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe00\x000D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00(D\x04\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00(D\x04\x00\x00\x00xp\x00\xff\xff\xff\xff0\x00$G\xe4\x00\x00\x00xp\x00\xff\xff\xff\xff0\x00$G\xe4\x00\x00\x00xp\x00\xe0\x0e\x00\xe00\x00"D\x04\x00\x00\x00xp\x00\xe0\x0e\x00\xe00\x00"D\x04\x00\x00\x00xp\x00\xe0\x0e\x00\xe00\x00 \xc4\x04\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe00\x00 \xc4\x04\x00\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00 D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00 D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00 D\x03\xe0\x00\x00\x7f\xf0\x00\xff\xff\xff\xff0\x00 D\x03\xe0\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe00\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe00\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe00\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00\xe0?\xff\xff\xff\xff\xff\xff\xff\xff\xe0\x00\xff\xff\xff\xff\x1f\xff\xff\xff\xff\xff\xff\xff\xff\xc0\x00\xff\xff\xff\xff\x0f\xff\xff\xff\xff\xff\xff\xff\xff\x00\x00\x7f\xff\xff\xff\xfc\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00?\xff\xff\xff\xf8\x00\x00\x00\x00\x00\x00\x00\x00\x00')
+
+    mk5_nfc_3 = (110, 49,  14, 0, b'\x00\x7f\xff\xff\xff\xfc\x00\x00\x00\x00\x00\x00\x00\x00\x00\xf0\xf0\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xf0\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x0e\x00\x03\xff\xff\xff\xff\xff\xff\xff\xff\x80\x00\xe0\x0e\x00\x07\xff\xff\xff\xff\xff\xff\xff\xff\xe0\x00\xe0\x0e\x00\x1f\xff\xff\xff\xff\xff\xff\xff\xff\xf0\x00\xe0\x0e\x000\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xff0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x000\x00 G\xe3\xe0\x00\x00\x7f\xf0\x00\xe0\x0e\x000\x00 G\xe3\xe0\x00\x00\x7f\xf0\x00\xe0\x0e\x000\x000D\x04\x10\x00\x00\x7f\xf0\x00\xe0\x0e\x000\x000D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xff0\x00(D\x04\x00\x00\x00\x7f\xf0\x00\xff\xff\xff0\x00(D\x04\x00\x00\x00xp\x00\xff\xff\xff0\x00$G\xe4\x00\x00\x00xp\x00\xff\xff\xff0\x00$G\xe4\x00\x00\x00xp\x00\xe0\x0e\x000\x00"D\x04\x00\x00\x00xp\x00\xe0\x0e\x000\x00"D\x04\x00\x00\x00xp\x00\xe0\x0e\x000\x00 \xc4\x04\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x000\x00 \xc4\x04\x00\x00\x00\x7f\xf0\x00\xff\xff\xff0\x00 D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xff0\x00 D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xff0\x00 D\x03\xe0\x00\x00\x7f\xf0\x00\xff\xff\xff0\x00 D\x03\xe0\x00\x00\x7f\xf0\x00\xe0\x0e\x000\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x000\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x000\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e\x00?\xff\xff\xff\xff\xff\xff\xff\xff\xe0\x00\xff\xff\xff\x1f\xff\xff\xff\xff\xff\xff\xff\xff\xc0\x00\xff\xff\xff\x0f\xff\xff\xff\xff\xff\xff\xff\xff\x00\x00\x7f\xff\xff\xc0\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00?\xff\xff\xff\xf8\x00\x00\x00\x00\x00\x00\x00\x00')
+
+    mk5_nfc_4 = (102, 49,  13, 0, b'\x00\x7f\xff\xff\xff\xfc\x00\x00\x00\x00\x00\x00\x00\x00\xf0\xf0\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x00\x00\x00\x0e\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xff\xff\xfe\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xf0\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xe0\x0e\x03\xff\xff\xff\xff\xff\xff\xff\xff\x80\x00\xe0\x0e\x07\xff\xff\xff\xff\xff\xff\xff\xff\xe0\x00\xe0\x0e\x1f\xff\xff\xff\xff\xff\xff\xff\xff\xf0\x00\xe0\x0e0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e0\x00 G\xe3\xe0\x00\x00\x7f\xf0\x00\xe0\x0e0\x00 G\xe3\xe0\x00\x00\x7f\xf0\x00\xe0\x0e0\x000D\x04\x10\x00\x00\x7f\xf0\x00\xe0\x0e0\x000D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00(D\x04\x00\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00(D\x04\x00\x00\x00xp\x00\xff\xff\xb0\x00$G\xe4\x00\x00\x00xp\x00\xff\xff\xb0\x00$G\xe4\x00\x00\x00xp\x00\xe0\x0e0\x00"D\x04\x00\x00\x00xp\x00\xe0\x0e0\x00"D\x04\x00\x00\x00xp\x00\xe0\x0e0\x00 \xc4\x04\x00\x00\x00\x7f\xf0\x00\xe0\x0e0\x00 \xc4\x04\x00\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00 D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00 D\x04\x10\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00 D\x03\xe0\x00\x00\x7f\xf0\x00\xff\xff\xb0\x00 D\x03\xe0\x00\x00\x7f\xf0\x00\xe0\x0e0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e0\x00\x00\x00\x00\x00\x00\x00\x7f\xf0\x00\xe0\x0e?\xff\xff\xff\xff\xff\xff\xff\xff\xe0\x00\xff\xff\x9f\xff\xff\xff\xff\xff\xff\xff\xff\xc0\x00\xff\xff\x8f\xff\xff\xff\xff\xff\xff\xff\xff\x00\x00\x7f\xff\xc0\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00?\xff\xff\xff\xf8\x00\x00\x00\x00\x00\x00\x00')
+
+    scroll = (3, 61,  1, 0, b'@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@\x00\x00@@\xe0@')
+
+    selected = (9, 12,  2, 0, b'\x00\x00\x00\x00\x00\x80\x01\x80\x01\x00\x03\x00\x82\x00\xc6\x00d\x00<\x00\x18\x00\x00\x00')
+
+    sm_box = (11, 17,  2, 0, b'\xe4\xe0\x80 \x80 \x80 \x00\x00\x00\x00\x80 \x00\x00\x00\x00\x00\x00\x80 \x00\x00\x00\x00\x80 \x80 \x80 \xe4\xe0')
+
+    space = (9, 2,  2, 0, b'\x80\x80\xff\x80')
+
+    spin = (13, 36,  2, 0, b'\x02\x00\x07\x00\x0f\x80\x1f\xc0\x00\x00\x00\x00\x00\x00\xf2x\x80\x08\x80\x08\x80\x08\x00\x00\x00\x00\x80\x08\x00\x00\x00\x00\x00\x00\x80\x08\x00\x00\x00\x00\x00\x00\x80\x08\x00\x00\x00\x00\x80\x08\x80\x08\x80\x08\xf2x\x00\x00\x00\x00\x00\x00\x1f\xc0\x0f\x80\x07\x00\x02\x00\x00\x00')
+
+    wedge = (6, 11,  1, 0, b'\x00\x00\xc0\xe0p8\x1c8p\xe0\xc0')
+
+    xbox = (13, 21,  2, 0, b'?\xe0b0\x88\x88\xa2(\x88\x88\xa2(\x88\x88\xa2(\x88\x88\xa2(\x88\x88\xa2(\x88\x88\xa2(\x88\x88\xa2(\x88\x88\xa2(\x88\x88b0?\xe0')
+
 
 # EOF

graphics/mono/mk5_nfc_1.txt

@@ -0,0 +1,49 @@
+         xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
+        xxxx    xxxx    xxxxxxxxxxxxxxxxxxxxxxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxx         xxx         xxx         xxx       yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
+        xxx         xxx         xxx         xxx      yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
+        xxx         xxx         xxx         xxx    yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
+        xxx         xxx         xxx         xxx   yy                                                             yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   yy                                                             yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   yy                                                             yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   yy                                                             yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   yy                                                             yyyyyyyyyyy
+        xxx         xxx         xxx         xxx   yy              n      n   ffffff   ccccc                      yyyyyyyyyyy
+        xxx         xxx         xxx         xxx   yy              n      n   ffffff   ccccc                      yyyyyyyyyyy
+        xxx         xxx         xxx         xxx   yy              nn     n   f       c     c                     yyyyyyyyyyy
+        xxx         xxx         xxx         xxx   yy              nn     n   f       c     c                     yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   yy              n n    n   f       c                           yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   yy              n n    n   f       c                           yyyy    yyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   yy              n  n   n   ffffff  c                           yyyy    yyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   yy              n  n   n   ffffff  c                           yyyy    yyy
+        xxx         xxx         xxx         xxx   yy              n   n  n   f       c                           yyyy    yyy
+        xxx         xxx         xxx         xxx   yy              n   n  n   f       c                           yyyy    yyy
+        xxx         xxx         xxx         xxx   yy              n     nn   f       c                           yyyyyyyyyyy  
+        xxx         xxx         xxx         xxx   yy              n     nn   f       c                           yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   yy              n      n   f       c     c                     yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   yy              n      n   f       c     c                     yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   yy              n      n   f        ccccc                      yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   yy              n      n   f        ccccc                      yyyyyyyyyyy
+        xxx         xxx         xxx         xxx   yy                                                             yyyyyyyyyyy
+        xxx         xxx         xxx         xxx   yy                                                             yyyyyyyyyyy
+        xxx         xxx         xxx         xxx   yy                                                             yyyyyyyyyyy
+        xxx         xxx         xxx         xxx   yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy 
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx    yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy  
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx     yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy    
+         xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx    
+          xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx     

graphics/mono/mk5_nfc_2.txt

@@ -0,0 +1,49 @@
+         xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
+        xxxx    xxxx    xxxxxxxxxxxxxxxxxxxxxxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxx         xxx         xxx           yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
+        xxx         xxx         xxx          yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
+        xxx         xxx         xxx        yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
+        xxx         xxx         xxx       yy                                                             yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  yy                                                             yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  yy                                                             yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  yy                                                             yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  yy                                                             yyyyyyyyyyy
+        xxx         xxx         xxx       yy              n      n   ffffff   ccccc                      yyyyyyyyyyy
+        xxx         xxx         xxx       yy              n      n   ffffff   ccccc                      yyyyyyyyyyy
+        xxx         xxx         xxx       yy              nn     n   f       c     c                     yyyyyyyyyyy
+        xxx         xxx         xxx       yy              nn     n   f       c     c                     yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  yy              n n    n   f       c                           yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  yy              n n    n   f       c                           yyyy    yyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  yy              n  n   n   ffffff  c                           yyyy    yyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  yy              n  n   n   ffffff  c                           yyyy    yyy
+        xxx         xxx         xxx       yy              n   n  n   f       c                           yyyy    yyy
+        xxx         xxx         xxx       yy              n   n  n   f       c                           yyyy    yyy
+        xxx         xxx         xxx       yy              n     nn   f       c                           yyyyyyyyyyy  
+        xxx         xxx         xxx       yy              n     nn   f       c                           yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  yy              n      n   f       c     c                     yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  yy              n      n   f       c     c                     yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  yy              n      n   f        ccccc                      yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  yy              n      n   f        ccccc                      yyyyyyyyyyy
+        xxx         xxx         xxx       yy                                                             yyyyyyyyyyy
+        xxx         xxx         xxx       yy                                                             yyyyyyyyyyy
+        xxx         xxx         xxx       yy                                                             yyyyyyyyyyy
+        xxx         xxx         xxx       yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy 
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy  
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx    yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy    
+         xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx    
+          xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx     

graphics/mono/mk5_nfc_3.txt

@@ -0,0 +1,49 @@
+         xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
+        xxxx    xxxx    xxxxxxxxxxxxxxxxxxxxxxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxx         xxx               yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
+        xxx         xxx              yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
+        xxx         xxx            yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
+        xxx         xxx           yy                                                             yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxx  yy                                                             yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxx  yy                                                             yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxx  yy                                                             yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxx  yy                                                             yyyyyyyyyyy
+        xxx         xxx           yy              n      n   ffffff   ccccc                      yyyyyyyyyyy
+        xxx         xxx           yy              n      n   ffffff   ccccc                      yyyyyyyyyyy
+        xxx         xxx           yy              nn     n   f       c     c                     yyyyyyyyyyy
+        xxx         xxx           yy              nn     n   f       c     c                     yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxx  yy              n n    n   f       c                           yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxx  yy              n n    n   f       c                           yyyy    yyy
+        xxxxxxxxxxxxxxxxxxxxxxxx  yy              n  n   n   ffffff  c                           yyyy    yyy
+        xxxxxxxxxxxxxxxxxxxxxxxx  yy              n  n   n   ffffff  c                           yyyy    yyy
+        xxx         xxx           yy              n   n  n   f       c                           yyyy    yyy
+        xxx         xxx           yy              n   n  n   f       c                           yyyy    yyy
+        xxx         xxx           yy              n     nn   f       c                           yyyyyyyyyyy  
+        xxx         xxx           yy              n     nn   f       c                           yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxx  yy              n      n   f       c     c                     yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxx  yy              n      n   f       c     c                     yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxx  yy              n      n   f        ccccc                      yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxxxxxxxxx  yy              n      n   f        ccccc                      yyyyyyyyyyy
+        xxx         xxx           yy                                                             yyyyyyyyyyy
+        xxx         xxx           yy                                                             yyyyyyyyyyy
+        xxx         xxx           yy                                                             yyyyyyyyyyy
+        xxx         xxx           yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy 
+        xxxxxxxxxxxxxxxxxxxxxxxx   yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy  
+        xxxxxxxxxxxxxxxxxxxxxxxx    yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy    
+         xxxxxxxxxxxxxxxxxxxxxxxxx
+          xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx     

graphics/mono/mk5_nfc_4.txt

@@ -0,0 +1,49 @@
+         xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
+        xxxx    xxxx    xxxxxxxxxxxxxxxxxxxxxxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxx                                 xxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+        xxxxxxxxxxxxxxxxxxxx
+        xxx         xxx       yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
+        xxx         xxx      yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
+        xxx         xxx    yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
+        xxx         xxx   yy                                                             yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxx yy                                                             yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxx yy                                                             yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxx yy                                                             yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxx yy                                                             yyyyyyyyyyy
+        xxx         xxx   yy              n      n   ffffff   ccccc                      yyyyyyyyyyy
+        xxx         xxx   yy              n      n   ffffff   ccccc                      yyyyyyyyyyy
+        xxx         xxx   yy              nn     n   f       c     c                     yyyyyyyyyyy
+        xxx         xxx   yy              nn     n   f       c     c                     yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxx yy              n n    n   f       c                           yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxx yy              n n    n   f       c                           yyyy    yyy
+        xxxxxxxxxxxxxxxxx yy              n  n   n   ffffff  c                           yyyy    yyy
+        xxxxxxxxxxxxxxxxx yy              n  n   n   ffffff  c                           yyyy    yyy
+        xxx         xxx   yy              n   n  n   f       c                           yyyy    yyy
+        xxx         xxx   yy              n   n  n   f       c                           yyyy    yyy
+        xxx         xxx   yy              n     nn   f       c                           yyyyyyyyyyy  
+        xxx         xxx   yy              n     nn   f       c                           yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxx yy              n      n   f       c     c                     yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxx yy              n      n   f       c     c                     yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxx yy              n      n   f        ccccc                      yyyyyyyyyyy
+        xxxxxxxxxxxxxxxxx yy              n      n   f        ccccc                      yyyyyyyyyyy
+        xxx         xxx   yy                                                             yyyyyyyyyyy
+        xxx         xxx   yy                                                             yyyyyyyyyyy
+        xxx         xxx   yy                                                             yyyyyyyyyyy
+        xxx         xxx   yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy 
+        xxxxxxxxxxxxxxxxx  yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy  
+        xxxxxxxxxxxxxxxxx   yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy    
+         xxxxxxxxxxxxxxxxx
+          xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx     

graphics/mono/selected.txt

@@ -0,0 +1,12 @@
+
+
+        X
+       XX
+       X
+      XX 
+X     X
+XX   XX  
+ XX  X  
+  XXXX   
+   XX
+   

graphics/selected.txt

@@ -1,12 +0,0 @@
-
-
-             xx
-            xx
-           xx
-          xx
-  xx     xx
-   xx   xx
-    xx xx 
-     xxx
-      x
-   

hardware/README.md

@@ -1,4 +1,3 @@
-
 # Coldcard Hardware Details
 
 This directory contains enough information for you to be able to
@@ -6,23 +5,42 @@ build your own Coldcard from off-the-shelf parts.
 We are sharing this information for the benefit of security
 researchers who wish to analyse the Coldcard more completely.
 
-
 # Schematic
 
+![](schematic-q1d.png)
+
+`schematic-q1d.png`
+
+This is the Q rev D schematic.
+
+![](schematic-mark5f.png)
+
+`schematic-mark5f.png`
+
+This is the Mark4 rev F schematic.
+
+![](schematic-mark4d.png)
+
+`schematic-mark4d.png`
+
+This is the Mark4 rev D schematic.
+
 ![](schematic-mark3b.png)
 
 `schematic-mark3b.png`
 
-This is the Mark3 rev B schematic. It's just one page and pretty simple.
+This is the Mark3 rev B schematic.
 
 
 # BOM - Bill of Materials
 
-`bom-mark3b.xlsx`
+The parts used in the Coldcard are detailed in these spreadsheets.
+Most of them could be bought on Digikey, but some are direct from suppliers.
 
-The parts used in the Coldcard are detailed in this spreadsheet file.
-All of them could be bought on Digikey, and where we know
-it, we've included the Digikey SKU.
+- BOM for Q rev D: `bom-q1d.xlsx`
+- BOM for Mk5 rev F: `bom-mark5f.xlsx`
+- BOM for Mk4 rev D: `bom-mark4d.xlsx`
+- BOM for Mk3 rev B: `bom-mark3b.xlsx`
 
 Not included are these minor bits:
 
@@ -30,11 +48,10 @@ Not included are these minor bits:
 - the secure bag (with barcode serial number)
 - pin-recovery card
 
-
 # Important
 
-- No promises that these files are 100% current because we do make quality improvements.
+- No promises that these files are 100% current because we constantly make quality improvements.
 - Copyright of these files, and all design elements of the Coldcard remain with Coinkite Inc.
-- This information is for research and testing purposes only no warranties. 
-- **Coinkite does not grant license of this information for comercial use.**
+- This information is for research and testing purposes only—no warranties. 
+- **Coinkite does NOT grant license of this information for comercial use.**
 

macos-mpy.patch

@@ -0,0 +1,28 @@
+diff --git a/mpy-cross/Makefile b/mpy-cross/Makefile
+index 971f2f81a..0c25a11e0 100644
+--- a/mpy-cross/Makefile
++++ b/mpy-cross/Makefile
+@@ -17,7 +17,8 @@ INC += -I$(BUILD)
+ INC += -I$(TOP)
+ 
+ # compiler settings
+-CWARN = -Wall -Werror
++CWARN = -Wall -Werror -Wno-error=unused-but-set-variable -Wno-error=array-bounds
++CWARN += -Wno-error=unknown-warning-option
+ CWARN += -Wextra -Wno-unused-parameter -Wpointer-arith
+ CFLAGS = $(INC) $(CWARN) -std=gnu99 $(CFLAGS_MOD) $(COPT) $(CFLAGS_EXTRA)
+ CFLAGS += -fdata-sections -ffunction-sections -fno-asynchronous-unwind-tables
+diff --git a/ports/unix/Makefile b/ports/unix/Makefile
+index 6a936a242..43e6bf02a 100644
+--- a/ports/unix/Makefile
++++ b/ports/unix/Makefile
+@@ -38,7 +38,8 @@ INC +=  -I$(TOP)
+ INC += -I$(BUILD)
+ 
+ # compiler settings
+-CWARN = -Wall -Werror
++CWARN = -Wall -Werror -Wno-error=unused-but-set-variable -Wno-error=array-bounds
++CWARN += -Wno-error=unknown-warning-option -Wno-error=deprecated-non-prototype -Wno-error=bitwise-instead-of-logical
+ CWARN += -Wextra -Wno-unused-parameter -Wpointer-arith -Wdouble-promotion -Wfloat-conversion
+ CFLAGS += $(INC) $(CWARN) -std=gnu99 -DUNIX $(CFLAGS_MOD) $(COPT) -I$(VARIANT_DIR) $(CFLAGS_EXTRA)
+ 

misc/binfonter/config.py

@@ -9,7 +9,6 @@ font_files = {
 }
 
 # test with:
-#
 #   ./build.py build --portable && ./testit.py --msg "hello→world←\n↳this\n•Bullet\n•Text" -f small
 #
 special_chars = dict(small=[
@@ -65,5 +64,19 @@ special_chars = dict(small=[
 
   xxxxx 
 '''),
+('⋯', dict(y=0), '''\
+
+
+
+
+
+
+  x x x x x
+'''),
+
+# thin space
+('\u2009', dict(y=0, w=5), '''\
+
+'''),
 
 ])

misc/gpu/.gitignore

@@ -0,0 +1,10 @@
+
+# build products, see Makefile:
+gpu.lss
+gpu.sym
+gpu.bin.tmp
+
+checksums.txt
+version-full.txt
+version.txt
+

misc/gpu/Makefile

@@ -0,0 +1,184 @@
+# (c) Copyright 2023 by Coinkite Inc. This file is covered by license found in COPYING-CC.
+#
+# Makefile for Q1's GPU co-processor.
+#
+# Targets:
+#	all - make everything, look for dafu.elf inparticular
+#	clean - delete intermediates
+#	clobber - delete all build products
+#
+
+# Toolchain
+TOOLCHAIN = arm-none-eabi-
+CC = $(TOOLCHAIN)gcc
+OBJDUMP = $(TOOLCHAIN)objdump
+OBJCOPY = $(TOOLCHAIN)objcopy
+NM = $(TOOLCHAIN)nm
+SIZE = $(TOOLCHAIN)size
+
+# Basename of all targets
+TARGET_NAME = gpu
+
+# Source files, listed here as the object files they will become.
+OBJS += startup.o
+OBJS += main.o lcd.o version.o interrupts.o
+OBJS += stm32c0xx_ll_gpio.o stm32c0xx_ll_spi.o stm32c0xx_ll_i2c.o stm32c0xx_ll_utils.o
+
+# Have to have copies of these because the DMA and interrupt stuff
+# needs to be commented-out.
+#OBJS += stm32l4xx_hal_gpio.o stm32l4xx_hal_spi.o
+#OBJS += stm32l4xx_hal_rcc.o stm32l4xx_hal_rcc_ex.o
+
+# Where we will end up in the memory map (at start of flash)
+GPU_FLASH_BASE = 0x08000000
+GPU_FLASH_SIZE = 0x4000
+GPU_FLASH_LAST = 0x08004000
+
+# Use all of 6k of SRAM...
+GPU_SRAM_BASE = 0x20000000
+GPU_SRAM_SIZE = 0x00001800
+
+# Compiler flags.
+CFLAGS = -I. -Wall --std=gnu99 -Os -g3 \
+			-mthumb -mfpu=fpv4-sp-d16 -mfloat-abi=soft -mtune=cortex-m0 \
+			-ffunction-sections -fdata-sections \
+			-mcpu=cortex-m0 -DMCU_SERIES_C0 -DSTM32C011xx \
+			-DUSE_FULL_LL_DRIVER
+#-DUSE_HAL_DRIVER
+
+# Pass in the locations of stuff
+CFLAGS += -D GPU_FLASH_BASE=$(GPU_FLASH_BASE) -D GPU_FLASH_SIZE=$(GPU_FLASH_SIZE)
+CFLAGS += -D GPU_SRAM_BASE=$(GPU_SRAM_BASE) -D GPU_SRAM_SIZE=$(GPU_SRAM_SIZE) 
+
+# Header file search path
+INC_PATHS = external/cmsis_device_c0/Include \
+			external/stm32c0xx_hal_driver/Inc \
+			../../external/micropython/lib/cmsis/inc
+
+CFLAGS += $(foreach INC,$(INC_PATHS),-I$(INC))
+
+# Specialized linker-script here. Not the standard one!
+#
+LINKER_SCRIPT = link-script.ld
+LDFLAGS += -Wl,-T$(LINKER_SCRIPT)
+
+LDFLAGS += -flto -Wl,--gc-sections --specs=nano.specs
+LDFLAGS += -Wl,--defsym,GPU_FLASH_BASE=$(GPU_FLASH_BASE)
+LDFLAGS += -Wl,--defsym,GPU_FLASH_SIZE=$(GPU_FLASH_SIZE)
+LDFLAGS += -Wl,--defsym,GPU_SRAM_BASE=$(GPU_SRAM_BASE)
+LDFLAGS += -Wl,--defsym,GPU_SRAM_SIZE=$(GPU_SRAM_SIZE)
+LDFLAGS += -Wl,-Map=$(TARGET_NAME).map
+
+ASFLAGS += -Wa,--defsym,GPU_FLASH_BASE=$(GPU_FLASH_BASE) -Wa,--defsym,GPU_FLASH_SIZE=$(GPU_FLASH_SIZE)
+ASFLAGS += -Wa,--defsym,GPU_SRAM_BASE=$(GPU_SRAM_BASE) -Wa,--defsym,GPU_SRAM_SIZE=$(GPU_SRAM_SIZE)
+
+
+TARGET_ELF = $(TARGET_NAME).elf
+TARGETS = $(TARGET_NAME).lss $(TARGET_NAME).bin $(TARGET_NAME).sym gpu_binary.py
+
+all: $(TARGETS)
+
+# recompile on any Makefile change, because with a small project like this...
+$(OBJS): Makefile
+$(TARGETS): $(TARGET_ELF) Makefile
+
+# link step
+$(TARGET_ELF): $(OBJS) $(LINKER_SCRIPT) Makefile
+	$(CC) $(CFLAGS) -o $(TARGET_ELF) $(LDFLAGS) $(OBJS)
+	$(SIZE) -Ax $@
+
+# detailed listing, very handy
+%.lss: $(TARGET_ELF)
+	$(OBJDUMP) -h -S $< > $@
+
+# symbol dump, meh
+%.sym: $(TARGET_ELF)
+	$(NM) -n $< > $@
+
+# raw binary, forced to right size, pad w/ 0xff
+%.bin: $(TARGET_ELF)
+	$(OBJCOPY) -O binary --gap-fill 0xff $< $@
+
+# assumes openocd running from current directory
+up:
+	echo 'flash write_image $(TARGET_ELF)' | nc localhost 4444
+
+# make a 'release' build
+release: code-committed clean all capture
+release: CFLAGS += -DRELEASE=1 -Werror
+
+.PHONY: code-committed
+code-committed:
+	@echo ""
+	@echo "Are all changes commited already?"
+	git diff --stat --exit-code .
+	@echo '... yes'
+
+# these files are what we capture and store for each release.
+DELIVERABLES = $(TARGET_NAME).bin $(TARGET_NAME).lss gpu_binary.py
+
+# package the binary into a mpy file to be frozen/included into main micro code
+gpu_binary.py: version.txt $(TARGET_NAME).bin repackage.py
+	./repackage.py `cat version.txt` $(TARGET_NAME).bin > $@
+	wc -c $(TARGET_NAME).bin
+
+checksums.txt: $(DELIVERABLES)
+	shasum -a 256 $(DELIVERABLES) > $@
+
+lcd.o: barcode.h
+barcode.h: make_barcode.py Makefile
+	python3 make_barcode.py
+
+# Track released versions
+.PHONY: capture
+capture: version.txt version-full.txt $(DELIVERABLES) checksums.txt
+	V=`cat version.txt` && cat checksums.txt > releases/$$V.txt && cat version-full.txt >> releases/$$V.txt && mkdir -p releases/$$V; cp $(DELIVERABLES) releases/$$V
+	@echo
+	@echo "      Version: " `cat version.txt`
+	@echo
+	V=`cat version.txt` && git tag -am "Q1 GPU version $$V" "q1-gpu-"$$V
+	git add -f releases/*/gpu.* releases/*.txt releases/*/*.py
+
+# Pull out the version string from binary object (already linked in) and 
+# construct a text file (version.txt) with those contents
+version.txt version-full.txt: version.o Makefile
+	$(OBJCOPY) -O binary -j .rodata.version_string version.o version-tmp.txt
+	cat version-tmp.txt | sed -e 's/ .*//' | sed -e 's/ .*//' > version.txt
+	cat version-tmp.txt | tr '\0' '\n' > version-full.txt
+	@echo
+	@echo "Version string: " `cat version-full.txt`
+	@echo
+	$(RM) version-tmp.txt
+
+# nice version numbers.
+BUILD_TIME = $(shell date '+%Y%m%d.%H%M%S')
+BRANCH = $(shell git rev-parse --abbrev-ref HEAD)
+SHA_VERSION = $(shell git rev-parse --short HEAD)
+GIT_HASH = "$(BRANCH)@$(SHA_VERSION)"
+version.o: CFLAGS += -DBUILD_TIME='"$(BUILD_TIME)"' -DGIT_HASH='$(GIT_HASH)'
+version.o main.o: Makefile version.h
+
+clean:
+	$(RM) $(OBJS)
+
+clobber: clean
+	$(RM) $(TARGETS)
+
+# In another window: 
+#
+#	openocd-stm -s /usr/local/Cellar/open-ocd/0.12.0/share/openocd/scripts -f openocd-gpu.cfg
+#
+# Can do:
+# - "load" which writes the flash (medium speed, lots of output on st-util)
+# - "cont" starts/continues system
+# - "br main" sets breakpoints
+# - "mon reset" to reset micro
+# - and so on
+#
+debug:
+	arm-none-eabi-gdb $(TARGET_ELF) -x gogo.gdb
+
+tags:
+	ctags -f .tags *.[ch] -R $(INC_PATHS)
+
+# EOF

misc/gpu/README.md

@@ -0,0 +1,97 @@
+# GPU on Q1
+
+The name is a joke. It's not a GPU, just a very simple and cheap micro that can
+animate a progress bar. And that's all we want it to do.
+
+It is field upgradable, but we will remove that and start locking it down in 
+production once it's features are stable.
+
+
+## Hardware
+
+It's a STM32C011F4:
+
+- 16k bytes of Flash
+- 6k bytes of RAM
+- 4-48Mhz
+- 18 GPIO
+- 20 pins
+- a newer part, so some challenges there
+
+Of the two TagConnect spots, the GPU is the inboard one; other is for main micro.
+
+## OpenOCD
+
+Version 0.12.0 of OpenOCD, the latest release as of this writing, does not yet support this chip.
+
+You'll need to compile from ST Micro's fork of OpenOCD. In particular we need
+this diff:
+<https://github.com/STMicroelectronics/OpenOCD/commit/21c81a2b2edf5402afbba8c22feaeda6f626554e>
+
+I am using brew's install of normal 0.12.0 for config files, and
+a compiled version named `openocd-stm`, so my command line is:
+
+    openocd-stm -s /usr/local/Cellar/open-ocd/0.12.0/share/openocd/scripts -f openocd-gpu.cfg
+
+Useful commands:
+
+    flash erase_sector 0 0 last
+
+Set EMPTY bit, so goes into BL:
+
+    > mdw 0x40022000
+    0x40022000: 00040600 
+    > mmw 0x40022000 0x10000 0
+    > mdw 0x40022000          
+    0x40022000: 00050600 
+
+
+
+## In-Circuit Programming
+
+- AN4221 describes the protocol used to load the flash
+- timing is sensitive, but more important is where the i2c start/stops fall:
+
+## First Time Boot
+
+- on a fresh device, there is an `EMPTY` bit set on power-up (only) if flash looks empty
+- this causes bootmode to happen, regardless of subsequent flash contents, resets, and `BOOT0` line
+- so must clear bit 16 of `FLASH_ACR` after loading image: @ `0x40022000`
+- also, main micro has control over `BOOT0` (PE2) which stop main flash from running too
+- and the reset line on E6
+- we use this flag to get into boot mode from working code
+
+## Getting BOOT0 to work
+
+- default config in flash bit (option bytes) is to 
+- see `FLASH_OPTR` bit: `nBOOT_SEL` (bit 24) needs to be zero, default is one
+- `NRST_MODE` should be 0b01 (input only) not default (0b11 = bidirectional)
+- register `FLASH_OPTR` at 0x40022020 => found as 0xfffffeaa
+- loads from 0x1FFF7800 at power up
+- TODO XXX still need this!
+
+## AN4221 / Bootloader Bugs
+
+- command 0x00 - 'get' ... returns 19 bytes, but says v1.1 of protocol; clearly v1.2
+- command 0x02 - 'getid' ... returns 1 byte, but math wrong on length part of response
+- command 0x01 - 'getversion' ... return 1 byte, and doesn't include length prefix byte
+- memory read only works from flash, some parts of SRAM... not IO registers
+- undocumented need for N-1 as length in read/write commands
+- flash writes need to be 256-aligned, or else they do nothing and don't fail
+
+## Resource Sharing
+
+- SPI bus to the display is shared by the GPU and main micro.
+- Main micro configures its pins as pull-up, open-drain outputs (there is no input except TEAR).
+- GPU does the same, but no pull-ups (so open drain).
+- Later turns out we need push-pull I/O to get the SPI speeds involved (rise times too slow
+  with built-in resistors)
+
+## Other References
+
+- Ideas, not code: <https://github.com/rogerclarkmelbourne/Arduino_STM32/blob/341cd894516f747f14108de5da593dad99900ae0/tools/macosx/src/stm32flash_serial/src/stm32.c>
+
+
+
+
+

misc/gpu/barcode.h

@@ -0,0 +1,8 @@
+// autogen file, see make_barcode.py
+
+// in python: b'\x00\x00\x00\x00\x00\x00\x00?\x1c\x0e\x00\x1f\x8e\x00\xe0\x0f\xf8\xff\x8f\xc7\xe3\xfe?\xe3\xf1\xf8\xff\xf1\xf8\x03\xfe8\xfc\x00\x00\x00\x00\x00\x00\x00'
+static const uint8_t test_barcode[40] = {
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x3f, 0x1c, 0x0e, 0x00, 0x1f, 0x8e, 0x00, 0xe0, 0x0f, 0xf8, 0xff, 0x8f, 0xc7, 0xe3, 0xfe, 0x3f, 0xe3, 0xf1, 0xf8, 0xff, 0xf1, 0xf8, 0x03, 0xfe, 0x38, 0xfc, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
+};
+
+// EOF

misc/gpu/basics.h

@@ -0,0 +1,62 @@
+/*
+ * (c) Copyright 2018 by Coinkite Inc. This file is covered by license found in COPYING-CC.
+ */
+#pragma once
+#include <stdint.h>
+#include <stdbool.h>
+
+extern void fatal_error(const char *) __attribute__((noreturn));
+
+// I don't like the ususal assert macro, so here is my replacement,
+// and BTW: "assert()" is actually a macro, so it should
+// always be capitalized.
+//
+#undef assert
+#undef ASSERT
+
+// this does have an impact, but probably doesn't matter.
+#define __unlikely(x)     __builtin_expect((x),0)
+
+#define ASSERT(x) do { if(__unlikely(!(x))) { fatal_error("assert");} } while(0)
+
+// Use anywhere. Will just crash on production, but useful in dev.
+#ifndef RELEASE
+#define BREAKPOINT          asm("BKPT #0") 
+#else
+#define BREAKPOINT          #error
+#endif
+
+// An assertion that we will be checked at *compile* time. Useful GCC feature.
+#define STATIC_ASSERT(cond)		_Static_assert(cond, #cond)
+
+// Similarly: for those times when you want to write ASSERT(False), 
+// use this instead to provide a msg and abort. Altho the msg isn't
+// in the binary, it's still helpful when looking at source via debugger.
+//
+// CAUTION: some security checks end up here, so we want to always crash
+// in those cases.
+//
+#define INCONSISTENT(x)     fatal_error("incon")
+
+// Wait for an interrupt which will never happen (ie. die)
+#define LOCKUP_FOREVER()    while(1) { __WFI(); }
+
+// Like "sizeof()" but works on arrays, and returns the "numberof" elements.
+//
+#define numberof(x)			(sizeof(x)/sizeof((x)[0]))
+
+// This is an old favourite with dangerous programers...
+//
+#ifndef offsetof
+#define offsetof(TYPE, MEMBER) ((size_t) &((TYPE *)0)->MEMBER)
+#endif
+
+#define msizeof(TYPE, MEMBER)	sizeof(((TYPE *)0)->MEMBER)
+
+// Handy macros.
+#define MIN(a,b)		(((a)<(b))?(a):(b))
+#define MAX(a,b)		(((a)>(b))?(a):(b))
+#define CLAMP(x,mn,mx)		(((x)>(mx))?(mx):( ((x)<(mn)) ? (mn) : (x)))
+#define SGN(x)          (((x)<0)?-1:(((x)>0)?1:0))
+#define ABS(x)      	(((x)<0)?-(x):(x))
+

misc/gpu/external/cmsis_device_c0

@@ -0,0 +1 @@
+Subproject commit 7e32bf9d8117ee4c8f6a1d138b814fc24bf4c906

misc/gpu/external/stm32c0xx_hal_driver

@@ -0,0 +1 @@
+Subproject commit 4c5e3e45a8478a33decb1f45d663f485f89c459b