firmware/docs/limitations.md

BIP-39 Import

• there must be 12, 18 or 24 words in your mnemonic
• we have only the English word list
• we support BIP-39 passwords during import

XPRV Import

• 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

PIN Codes

• 2-2 through 6-6 in size, numeric digits only
• 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

• cards up to 32G are supported
• we do not guarantee to support all cards ever made, or yet to be made
• we recommend 8G cards or smaller, since our storage needs are very modest

Signing / Wallet Types

• 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
• we don't support signing coinbase transactions, so don't mine directly into a Coldcard wallet

Max Transaction Size

• mk3:
  • 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/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.

• 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 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 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

• 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 only supports sortedmulti(...) multisig according to BIP-67. To import multisig wallet with multi(...) use descriptor import format
• 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

• 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

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'.
• Fees over 5% (was 1%) are shown as warnings.

Developer / Source Code

• source code can probably only be compiled and developed on Mac OS and Linux
• we have very limited time to support other devs getting their setups working

Change Outputs

We will summarize transaction outputs as "change" back into same wallet, however:

• 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 correct, ie: 0x00 + 0x20 + sha256(witnessScript)
• the witnessScript in a p2wsh-p2sh is not optional.
• depending on the address type of the output, different values are required in the corresponding output section, as follows
  • p2pkh: no redeemScript, no witnessScript
  • p2wpkh-p2sh: only redeemScript (which will be: 0x00 + 0x14 + HASH160(key))
  • p2wpkh: no redeemScript, no witnessScript
  • p2sh: redeemScript that contains the a multisig script, ending in 0xAE
  • p2wsh-p2sh: redeemScript (which is: 0x00 + 0x20 + sha256(witnessScript)), and witnessScript (which contains the multisig script)
  • p2wsh: only witnessScript (which contains the actual multisig script)
  • p2tr(keypath singlesig): no redeemScript, no witnessScript and output key MUST commit to an unspendable script path as follows Q = P + int(hashTapTweak(bytes(P)))G
  • p2tr(scriptpath multisig): taproot_merkle_root and leaf_script more info in docs/taproot.md

Derivation Paths

• key derivatation paths must be 12 or less in depth (MAX_PATH_DEPTH)

Pay-to-Pubkey

• 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

• 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

• "deltamode" PIN must be same length as true pin, and differ only in final 4 positions.
• 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

• 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