#

Keycard Shell is the UI and transport layer around the Keycard applet. The Keycard stores and signs keys; the Shell handles QR and USB workflows.

#

Keycard holds the keys. Shell talks to the Keycard over the ISO-7816 smartcard interface and never stores private keys.
User confirmation is required. Requests coming from QR or USB are displayed on-device and require explicit approval.
Air-gapped by default. QR workflows are fully offline. USB data transfer is optional and can be disabled in settings.

#

Keycard Shell uses the EIP-4527 animated QR format and the Blockchain Commons UR encoding for sign requests and responses.

References:

Supported UR payloads are defined in the CDDL file:

UR CDDL definitions

Examples of UR types used by Shell include:

Ethereum sign requests and responses (eth-sign-request, eth-signature)
Bitcoin PSBT sign requests (crypto-psbt)
Bitcoin message sign requests and responses (btc-sign-request, btc-signature)
Multi-account exports (crypto-multi-accounts) for wallet integrations

#

When USB data is enabled, Shell enumerates as a USB HID device (VID 0x1209, PID 0x21f7) and speaks an APDU-like protocol.

Full protocol details and command list live here:

Keycard Shell USB protocol

Highlights:

C-APDU format: CLA(0xe0) + INS + P1 + P2 + Lc + Data.
Command chaining is used for payloads over 255 bytes.
GET RESPONSE is used for multi-chunk responses (SW=0x61XX).
Commands include GET DEVICE INFO, GET PUBLIC, SIGN ETH TX, SIGN EIP-712, SIGN PSBT, and firmware/database updates.

#

Clear signing for contract calls uses an on-device database containing chains, ERC-20 metadata, and Ethereum ABIs.

Primary sources and tooling:

Database format and flash layout: FLASHMAP.md
Database build tooling: shell-db.md
ABI source list and build pipeline: eth-abi-repo

You can reproduce database builds from source JSON inputs and verify the hash (signature excluded) with tools/database-hash.py.

#

Keycard Shell firmware images are signed. The bootloader verifies a secp256k1 signature with an embedded public key before booting:

Bootloader verification code

Official devices only accept signed firmware updates. To run custom firmware you must build your own device (or a dev unit) with a bootloader key you control.

Build notes:

Keycard Shell build notes
Use STM32CubeIDE and GNU Tools for STM32 (13.3.rel1)
Provide deployment/bootloader-pubkey.txt and deployment/fw-test-key.txt
Use tools/firmware-hash.py to verify a build against a release tag
Use tools/create-image.py to generate a full flashable image

There is no separate "bitcoin-only" firmware. You can use Keycard Shell with Bitcoin-only wallets (QR/UR PSBT flows or USB SIGN PSBT) and simply avoid Ethereum features. Advanced builders can compile custom firmware or databases that omit ETH chain/token/ABI data.