COLDCARD Co-Signing

New in firmware versions Mk4: v5.4.2, Q: v1.3.2Q

COLDCARD^® Co-Signing (CCC) is a powerful feature that enhances your security and control over your Bitcoin by creating automated multisig wallets, protected by user defined spending policies.

Why use COLDCARD Co-Signing?#

When CCC is enabled, a second seed is added to the COLDCARD, known as the Spending Policy Key (Key C). This new seed is used along with the Main Seed of the device, and one or more additional XPUBs (Backup Keys), to create 2-of-N multisig wallets.

The spending policy acts like a hardware security module (HSM), enforcing spending rules to protect your funds while still giving you flexibility and control. Any time the Spending Policy Key is used for signing, the policy is enforced. The rules in the policy include:

Magnitude Limits: Caps the amount of Bitcoin that can be spent in a single transaction.
Velocity Limits: Restricts how fast transactions can occur, requiring a minimum number of blocks between spends.
Whitelisted Addresses: Only allows to send to pre-approved Bitcoin addresses. Change addresses are automatically whitelisted.
2FA Authentication: Requires confirmations from a mobile 2FA application (TOTP RFC 6238) on an NFC-enabled phone with Internet access.

When all the spending conditions are met, the COLDCARD automatically signs the PSBT with the Main Seed and the Spending Policy Key, giving you access to the funds using just the two keys on your COLDCARD. You can override the spending policy at any time by signing with either a Backup Key and the Main Seed or two Backup Keys, depending on the number of keys (N) in the multisig.

Once the spending policy is configured, the COLDCARD cannot view or change it without knowledge of the Spending Policy Key. To prevent adversaries from learning info about your policy, any policy violations found in a PSBT are not explained, just denied.

mk4 refuse sign q refuse sign

Setup COLDCARD Co-Signing#

To get started with CCC, first enable the feature by creating or importing a Spending Policy Key. Then, configure the policy that determines when this key will be used to sign transactions. Next, import at least one Backup Key from a separate device, and finally, set up a 2-of-N multisig wallet.

Enable CCC#

The first part of the process of setting up COLDCARD Co-Signing is to create a Spending Policy Key, or import an existing one.

Steps to Enable COLDCARD Co-Signing

Begin by navigating to: Advanced/Tools > Coldcard Co-Signing.
Read the information, to move on press OK/ENTER.
Create or import a seed to use as the Spending Policy Key (Key C).

Steps to Create a Seed for the Spending Policy Key (Key C)

To create a new 12 word seed to use as the Spending Policy Key, press OK/ENTER.
- If you want to add your own entropy using dice rolls, press 4.
- To view the seed words as a QR code, press the QR key on the Q, or 1 on the Mk4.
Write down the new seed words as a backup. Without knowledge of this seed, you will not be able to view or edit your spending policy.
Complete the test to prove you backed the words up.

Steps to Import a Seed for the Spending Policy Key (Key C)

To import an existing seed to use as the Spending Policy Key, press 1 for a 12 word seed, 2 for a 24 word seed, or 6 to import from the Seed Vault if enabled.
Enter the seed words on the COLDCARD, or select the seed you would like to use in the Seed Vault.
- When importing a 12 or 24 words seed to the COLDCARD Q, you can press the QR key to scan as a QR code.
Make sure to keep a backup of the imported seed words. Without knowledge of this seed, you will not be able to view or edit your spending policy.

4. After the Spending Policy Key has been created or imported, you will be taken to the COLDCARD Co-Signing Menu.

mk4 ccc seed created q ccc seed created

COLDCARD Co-Signing Menu Options

CCC [XFP]: When selected, the XFP and Master Extended Public Key of the Spending Policy Key (Key C) is displayed on screen.
Last Violation: Only appears once a policy violation is detected in a PSBT. Shows the warning code of the last policy violation. Press 4 to clear it.

Policy Violation Codes

has warnings: Any warning from the PSBT, even unrelated to the spending policy, will be rejected.
magnitude: Sent more than the maximum amount of Bitcoin allowed per transaction.
no nLockTime: The PSBT didn't include the nLockTime value and there is a velocity limit in the policy.
nLockTime not height: Can't use a Unix timestamp for nLockTime, must be blocks.
rewound: The block height of the current PSBT is lower than the last signed PSBT.
velocity: The PSBT is too recent for the velocity limit, compared to the last signed PSBT.
whitelist: A destination address was not in the whitelist.
2FA fail: Web 2FA was not completed successfully.

Spending Policy: Contains settings for the policy that control when the Spending Policy Key will sign a PSBT. Options are described in the next section.
Export CCC XPUBs: Create a multisig COLDCARD XPUBs export of the Spending Policy Key.
Multisig Wallets: Lists existing multisig wallets, and an option to build a new one.
- 2/3: Coldcard Co-Sign: Any existing multisig wallets that include the Spending Policy Key are list here. Selecting one will bring you to a menu where you can interact with that wallet. From here you can view details of the wallet, delete it, or export it in various ways.
- Build 2-of-N: Create a new multisig wallet with the Spending Policy Key. Must have the XPUBs of the other signers on the SD card, or ready to be scanned as a QR code (Q only).
Load Key C: Loads the Spending Policy Key (Key C) as a Temporary Seed for easy use of all COLDCARD features on that key. If enabled, you will be given the option to save the key in the Seed Vault.

Saving the Key C to the Seed Vault will allow you to quickly access to the CCC settings without having to enter the seed words. This is helpful during the setup phase, but during normal use of CCC, Key C should NOT be saved in the Seed Vault. If Key C is left in the Seed Vault, you will receive the following warning as a reminder to remove it each time you exit the COLDCARD Co-Signing Menu.
Remove CCC: The Spending Policy Key will be lost, and all of your current policy settings forgotten. You will still be able to sign transactions from the CCC multisig wallet using your Main Seed and a Backup Key, or 2 Backup Keys.

To remove any CCC multisig wallets, head to: Settings > Multisig Wallets. From the Multisig Wallets Menu, select the wallet you would like to delete from the list, and choose Delete.

Set Spending Policy#

Now that CCC is enabled, you can take a look at the spending policy and decide if you would like to make any modifications. This section explains what your policy choices are, and how to use them.

Spending Policy Options

From the COLDCARD Co-Signing Menu, select Spending Policy to view the policy or make adjustments. The default policy settings are one Bitcoin per transaction, and one transaction every 144 blocks (about one day).

These are your options:

Max Magnitude: Maximum amount of Bitcoin that can be sent in a single transaction. Values below 1000 are treated as whole Bitcoin, values over or equal to 1000 are treated as Satoshis. The default setting is one Bitcoin. To disable, leave the input blank and press OK/ENTER.
Limit Velocity: Sets a minimum number of blocks that you must wait between transactions. Default is 144 blocks (about a day). Cannot be used without Max Magnitude.

If Limit Velocity is in use, the PSBT creator must include the nLockTime value (most do to avoid fee sniping). Previous block height is determined by the nLockTime value of the last signed transaction, even if the last transaction has not been broadcasted.
Whitelist Addresses: Import a list of up to 25 addresses that the PSBT can send to. Addresses can be imported from a file on the SD card, Virtual Disk, via NFC, or QR code (Q only). Change addresses are automatically whitelisted.
Web 2FA: If enabled, requires the use of a mobile 2FA application to sign. You will not be able to sign transactions if you do not have a phone with NFC and Internet access.

Before signing a transaction you will have to tap your 2FA enabled phone to the COLDCARD. That will take you to a page on coldcard.com where you will enter the 6 digit code from your authenticator app. If you entered the code correctly you'll be presented with an 8 digit code (MK4) or a QR code (Q). On the COLDCARD, scan the QR code (Q), or enter the digits (Mk4), and transaction signing will proceed.

Once enabled, new options will appear:
- Test 2FA: Takes you through the process of trying to pass 2FA authentication. This test is part of initially setting up Web 2FA.
- Enroll More: Multiple devices can be enrolled in 2FA, but they will all have the same shared-secret.

Create CCC Multisig Wallet#

The next step is to import one or more Backup Keys to be used as signers in the multisig. The Backup Keys should be from an external COLDCARD, or third party wallet. Backup Keys can be used to recover funds from the CCC multisig in any situation where the Spending Policy Key cannot sign.

Once all the Backup Keys are exported to the SD card, or ready to be scanned as a QR code (Q only), you can create the CCC multisig wallet.

Steps to Create CCC Multisig Wallet

The first step is to export the XPUBs of all the Backup Keys that you would like to add as signers to the CCC multisig wallet to an SD card, or have them ready to scan as QR codes (Q only). Only one Backup Key is required.
When you have the XPUBs of the Backup Keys on the SD card, or ready to be scanned, select Build 2-of-N from the COLDCARD Co-Signing Menu.
Read the information, and press OK/ENTER.
The next step is to import the XPUBs of the Backup Keys.
- If you are using a COLDCARD Q with QR codes, press the QR key. Choose the address type, tap ENTER for the default (P2WSH, segwit) or 1 for P2SH-P2WSH.
  
  Scan the QR code of a Backup Key's XPUB. Once successfully scanned, repeat the process for all the Backup Keys. After all the keys are scanned, press CANCEL to stop scanning and move on to the next step.
- If you are using an SD card to import the XPUBs, press ENTER on the Q to chooose that method. The Mk4 can only use the SD card method.
  
  Make sure the SD card with the exported XPUBs is inserted in the COLDCARD, and choose the address type. Press OK/ENTER for the default address type (P2WSH, segwit) or 1 for P2SH-P2WSH.
Choose an account number. To select the default (0), or if you don't know what this is, leave blank and hit OK/ENTER.
Review the details of the new multisig wallet. Press 1 to see the XPUBs of the signers. If you find any issues in the multisig setup, press CANCEL to abort.
If everything is to your expectations, tap OK/ENTER to create the multisig wallet.
A new wallet with the name 2/3: Coldcard Co-sign has been created and listed in the COLDCARD Co-Signing Menu.

Signing PSBTs with CCC#

To receive funds to your newly created CCC multisig wallet, you can use the Address Explorer on the COLDCARD (if Full Address View is allowed), or export the multisig wallet to an external wallet like Sparrow or Nunchuk. Note that to use this feature, you must send funds to the newly created multisig wallet—only funds in this wallet are covered by policy checking. Always verify address ownership before sending funds!

In order to spend from the CCC multisig wallet, you will need to have Internet access on the external wallet to create PSBTs. Once a PSBT has been created, it can then be passed to the COLDCARD for signing. If the spending policy is satisfied, the COLDCARD will sign with both the Main Seed and the Spending Policy Key.

After the PSBT has been signed by both keys, it can be broadcasted by passing the signed PSBT back to the external wallet.

Guides for Creating PSBTs With Various Wallets

Steps to Sign PSBTs With CCC

Prepare your PSBT for transfer to the COLDCARD using an SD card, the Virtual Disk, NFC, or QR code (Q only). If using an SD card, have it inserted in the COLDCARD.
The next step is to initiate signing the PSBT by importing it to the COLDCARD, the process is slightly different for the Mk4 and Q:
- For the Mk4, select Ready To Sign from the Main Menu. If your PSBT is the only one on the SD card, the process will begin automatically, you can move on to step 3.
  - If there are multiple PSBT files on your SD card, you will be prompted to select the correct file or choose [Sign All] to batch sign all of the PSBTs. Once selected hit OK and move on to the next step.
  - In order to use the Virtual Disk, it must first be enabled. Select Ready To Sign when there are no PSBTs on an inserted SD card, and then press 2 to import the PSBTs from the Virtual Disk. In case you have more than one PSBT file on the Virtual Disk, you will have to choose the correct one, or pick [Sign All] to batch sign all of them. Press OK and move on to the next step.
  - To import the PSBT via NFC, the hardware must first be turned on. Then you can select Ready To Sign as long as you don't have any PSBTs on an inserted SD card, then hit 3 to import via NFC. Now you can now tap your external wallet to the COLDCARD to pass the PSBT and start the signing routine. You can move on from this step.
- On the Q, choose Ready To Sign from the Main Menu if using the SD card. If your PSBT is the only one on the card the signing process will begin, you can move on to step 3.
  - When there are more than one PSBT files on the SD card you will have to choose the correct file. Next select the file, or choose [Sign All] to batch sign all of the PSBTs. Then tap ENTER and move on to the next step.
  - If you would like to use the Virtual Disk, you must first enable it. Then select Ready To Sign when there are no PSBTs on an inserted SD card, and tap 2. If you have multiple PSBTs on the Virtual Disk, choose the correct one or select [Sign All] to batch sign all of them. Hit ENTER and move to the following step.
  - To use NFC, first turn on the feature. Then press the NFC key and select Sign PSBT. Finally, tap the external wallet to the COLDCARD, and that will start the signing operation. You can move on to step 3.
  - For QR codes, hit the QR key and scan the QR code of the PSBT. The COLDCARD will initiate the signing process.
Since the Spending Policy Key is included in this PSBT, the spending policy is checked before the PSBT summary is shown to the user.
- If any part of the spending policy is violated, or there are any other warnings from the PSBT, the COLDCARD will not sign with the Spending Policy Key. The COLDCARD will still sign with the Main Seed if you hit OK/ENTER, however you need two signatures to broadcast the transaction. You can use a Backup Key to add a second signature to this PSBT and then broadcast it, if you want to circumvent to policy completely.
- No violation details will be shared here to prevent potential attackers from learning your policy rules. To debug policy violations, select the option Last Violation from the COLDCARD Co-Signing Menu.

Policy Violation Codes

has warnings: Any warning from the PSBT, even unrelated to the spending policy, will be rejected.
magnitude: Sent more than the maximum amount of Bitcoin allowed per transaction.
no nLockTime: The PSBT didn't include the nLockTime value and there is a velocity limit in the policy.
nLockTime not height: Can't use a Unix timestamp for nLockTime, must be blocks.
rewound: The block height of the current PSBT is lower than the last signed PSBT.
velocity: The PSBT is too recent for the velocity limit, compared to the last signed PSBT.
whitelist: A destination address was not in the whitelist.
2FA fail: Web 2FA was not completed successfully.

4. Review the details of the transaction. If everything is correct, and there are no warnings (except the warning that shows when Web 2FA is enabled), you can press OK/ENTER to sign the transaction with your Main Seed and Spending Policy Key.

If Web 2FA is enabled you will be prompted to begin the authentication process at this point:
- Tap your mobile device to the COLDCARD, you will be taken to a page on coldcard.com to authenticate.
- Open your 2FA app to get the authentication code, and enter that into the website.
- You will be given an 8 digit code if using the Mk4, or a QR code if using the Q.
- Enter the digits on the Mk4, or scan the QR code with the Q, to complete authentication and sign the PSBT.

5. Pass the signed PSBT back to the external wallet for broadcasting. Depending on the capabilities of the external wallet, you can use the SD card, NFC, or QR codes to transfer the signed PSBT.

Limit Velocity & `nLockTime`#

When using a Velocity Limit in policy, it is up to the user to provide "correct" nLockTime value in PSBT. For proper functioning of Limit Velocity policy, COLDCARD expects nLockTime to be set to current best block height. Issues like missing nLockTime, using timestamp instead of block height, setting nLockTime to past values COLDCARD have already seen, or just failing to wait necessary amount of blocks from last transaction will cause the Spending Policy Key to refuse signing.

Transaction nLockTime value depends on the external wallet you use to create the PSBT. The table below outlines nLockTime behavior for common wallets, along with recommendation of which to use with COLDCARD Co-Signing:

Wallet Name	nLockTime Value	Recommended
Sparrow Wallet	Current block height	YES
Nunchuk	0	coming soon...
Blue Wallet	0	NO
Electrum	Current block height*	YES*
Wasabi Wallet	Current block height*	YES*
Bitcoin Core	Current block height*	YES*
Bitcoin Keeper	0	NO
Specter Desktop	Current block height	YES

* Some wallets like Bitcoin Core and Electrum implemented nLockTime randomization to combat wallet fingerprinting. These wallets generate ~10% transactions that do not provide current best block height as nLockTime, but instead use formula nLockTime=block_height - randint(100). This constitutes a problem for frequent spenders using CCC as nLockTime in transaction B can be smaller than nLockTime in transaction A, which was signed first on COLDCARD. Transaction B would be rejected as "rewound" because COLDCARD has already saved block height from transaction A, which nLockTime is higher.

Users are recommended to use wallets with "correct" nLocktime behavior (ones marked with YES in table above) if they set up Limit Velocity policy in COLDCARD Co-Signing. For those that need to use different wallets, nLockTime can be adjusted manually after PSBT has been created. Follow these steps to do it in Sparrow:

Steps to Fix Locktime Errors in PSBTs

Use Sparrow to open the transaction. The wallet does not need to be known by Sparrow. You can open the transaction from a file, by pasting the transaction details from your clipboard, or by scanning a QR code.

Select File > Open Transaction from the menu bar, and then choose the method you would like to use to import the PSBT.
The transaction overview is shown first.
Select the Details tab from the right side of the window. You can see that the Absolute Locktime field is set to Disabled.
Select the Block tab under the Absolute Locktime field.
Click Set current height.
The last step is to get the fixed PSBT back to the COLDCARD for signing. You can do that by saving the PSBT to a file on your SD card, or sharing it as a BBQr code (Q only).
- To save as a file, select File > Save PSBT from the menu bar. Then you are free to choose As Binary... or As Base64....
  
  Make sure to save the file to your SD card, insert it back in the COLDCARD, and then retry to sign the PSBT.
- If you are using the COLDCARD Q, you can simply scan a BBQr code to begin signing. Head to File > Show PSBT as QR... from the menu bar. Then click Show BBQr at the bottom of the QR screen.
  
  Hit the QR button on the Q and scan the BBQr code to initiate signing the modified PSBT.

Limitations#

Only a 12 or 24 word seed (not an XPRV) will be accepted for the Spending Policy Key.
Velocity Limit:
- Takes into account the Max Magnitude set per transaction, and the required minimum block height gap.
- Previous block height is determined by the nLockTime value of the last signed PSBT.
- If a PSBT is signed, but never broadcast, you will still have wait for the number of blocks set in the velocity policy.
- If the velocity is not set to Unlimited, your PSBT creator must include the nLockTime value (most do to avoid fee sniping).
A maximum of 25 whitelisted addresses can be stored.
Any number of mobile devices can be enrolled for Web 2FA, but they will all share the same secret.
Any warning at all, not just policy violations, from the PSBT will prevent CCC from signing.