(new in v2.1.0, major changes in v3.2.1)
Normal Bitcoin transactions presume a single "owner" of the coins. With Multisig transactions, there are up to 15 possible owners (signers) and between 1 to 15 of them are needed to approve any spending.
This is called an M-of-N wallet or "Multisig P2SH" (pay to script hash) wallet.
Coldcard supports M-of-N wallets with up 15 co-signers. This is an optional, advanced, feature and does not affect normal "single signer" operations.
The transaction approval and signing process is not significantly different from single signer mode, but in multisig cases the "wallet" needs to be defined before use. A typical PSBT file does not carry enough information to encode all the details of the signatures required, and to properly secure change outputs the parameters of the multisig wallet should be established before the PSBT is examined.
Before the Coldcard can sign transactions involving multiple signatures, it must learn about the configuration of the wallet and the keys of other co-signers. The following details are required:
These details can be imported either from a simple text file, or thanks to recent changes to BIP-174, the PSBT file can carry all these details (except the wallet name).
There is a dedicated menu, "Settings > Multisig Wallets", which lists all established multisig wallets and contains related functions and settings.
This setting controls what the Coldcard does with the co-signer public keys (XPUB) that may be provided inside a PSBT file. There are three choices:
When the XPUB data is not provided in the PSBT, regardless of the above, we require the appropriate multisig wallet to already exist on the Coldcard. The default is to 'Offer' unless at least one multisig wallet already exists, in which case the default becomes 'Verify'.
With this settings, after a warning screen is shown, you may disable some of the checks involved in multisig PSBT processing. This permits PSBTs to be signed that may be generated with less-than-perfect software but which you know are not security hazards. This settings is not preserved between power cycles, and must be re-confirmed each time.
Here is the text of the warning:
With many different wallet vendors and implementors involved, it
can be hard to create a PSBT consistent with the many keys involved.
With this setting, you can disable the more stringent verification
checks your Coldcard normally provides.
USE AT YOUR OWN RISK. These checks exist for good reason! Signed
txn may not be accepted by network.
This settings lasts only until power down.
The additional checks introduced in version 3.2.1 of the firmware are mostly disabled by this check so if you have a setup that worked in earlier Coldcard versions, this setting should allow you to continue until the PSBT generating software is updated.
Choose the existing wallet, by name, from the top of the Multisig menu and you can view the details about your wallet. Here is an example of the sub-menu shown:
The details needed to define a multisig wallet on the Coldcard can be provided as a simple human-readable text file. The Coldcard can export this file and you edit it to update values, or it can be exported from Electrum or another Coldcard involved in the wallet.
Here is an example file:
# Coldcard Multisig setup file (exported from 4369050F)
#
Name: MeMyself
Policy: 2 of 4
Derivation: m/45'
Format: P2WSH
D0CFA66B: tpubD9429UXFGCTKJ9NdiNK4rC5...DdP9
8E697B74: tpubD97nVL37v5tWyMf9ofh5rzn...XgSc
BE26B07B: tpubD9ArfXowvGHnuECKdGXVKDM...FxPa
4369050F: tpubD8NXmKsmWp3a3DXhbihAYbY...9C8n
#
and go the end of the line. Blank lines are okay.Here are the values and the expected values:
p2sh
, p2wsh
, or p2sh-p2wsh
.All details that can be verified by the Coldcard are checked. For example, if the XPUB reports a child depth (aka. tree depth) of one, the XFP provided and the parent key fingerprint need to match. Generally, it is important the tree depth of the XPUB is accurate because the derivation paths provided in PSBT files will be masked-out to that depth. One of the keys provided must have a XFP equal to the Coldcard's fingerprint, indicating that this Coldcard is one of the co-signers.
Default values are provided as follows:
m/45'
.As a result of these defaults, in some very limited cases, it is possible to just provide the XPUB values. However, if the derivation is not BIP-45, that will not work as XFP values are required and there is no way to calculate them from the XPUB itself if it's child-depth is not one. Name and Policy cannot be edited on the Coldcard itself, so you will usually want to set those as well.
As the next two sections discuss, you may not need to create this config file, since you can create a wallet on the Coldcard itself, using just one MicroSD card, or by using the Electrum plugin to build the multisig wallet. It's also possible to import a wallet from a PSBT file.
To create a multisig wallet on Electrum, involving one or more Coldcards, proceed as follows:
At this point, the wallet should be functional. To sign transactions or to show addresses, however, the details must be imported into the Coldcard (or Coldcards), so The final step is to export the setup file. Use Electrum to create the file by choosing "Wallet > Information" and then "Export for Coldcard" button. You'll be prompted for a file name where the text file will be made.
Here is an example:
# Exported from Electrum
Name: wallet_3
Policy: 2 of 2
Format: P2SH-PW2SH
Derivation: m/48'/1'/0'/1'
4369050F: Upub5T4XUooQzDXL58NC...8B2fuBvtSa6
Derivation: m
EB5B9686: Upub5TJpKgtw4cBcaAom...GRSP43VHvGm
This wallet consists of a Coldcard and a key held by Electrum (a BIP-39 Seed in this case) with 2-of-2 signing policy.
Import that file onto the Coldcard using "Settings > Multisig Wallets > Import from file". You'll have a chance to view the details of the wallet before accepting it.
From version 5.0.5 Coldcard can import/export multisig wallets as descriptor. Import/export
consumes/produces external descriptor only (besides Bitcoin Core export).
As we only support sorted, ranged descriptors with standard non-hardened sub-derivation path 0/*
.
Internal descriptor is then implied as 1/*
.
Below is an example descriptor text file in pretty human-readable format. You can export descriptor in pretty format with Settings -> Multisig Wallets -> MeMyself > Descriptors > View Descriptor > Press 1
# Coldcard descriptor export
# order of keys in the descriptor does not matter, will be sorted before creating script (BIP67)
# native segwit - p2wsh
wsh(sortedmulti(
# 2 of 2 (requires all participants to sign)
2,
[0f056943/48h/1h/0h/2h]tpubDF2rnouQaaYrXF4noGTv6rQ...CvkP/0/*,
[122b6f56/44h/1h/0h]tpubDCmC5bJAfQxjCFrRCG9qzBm...Yzfc/0/*
))#zyueunr0
#
and go the end of the line. Blank lines are okay.Below is an example raw descriptor import/export text file. You can export raw descriptor with Settings > Multisig Wallets > MeMyself > Descriptors > Export
wsh(sortedmulti(2,[0f056943/48h/1h/0h/2h]tpubDF2rnouQaaYrXF4noGTv6rQYmx87cQ4GrUdhpvXkhtChwQPbdGTi8GA88NUaSrwZBwNsTkC9bFkkC8vDyGBVVAQTZ2AS6gs68RQXtXcCvkP/0/*,[122b6f56/44h/1h/0h]tpubDCmC5bJAfQxjCFrRCG9qzBmz4FDy6SVieb4KZaPD5D8AFx5vYjngiRfJSCds4LzKcpy9Mx3he4uSdfdkJHGZBG2gJqz63ndKj9miiVbYzfc/0/*))#zyueunr0
Bitcoin Core descriptor export generates text file with importdescriptors
command ready to be executed with bitcoind
or bitcoin-qt
You can export Bitcoin Core importdescriptors
command with Settings > Multisig Wallets > MeMyself > Descriptors > Bitcoin Core
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"}]'
Coldcard is able to import descriptor from file in both pretty and raw formats. To import multisig wallet from descriptor file use standard import path Settings > Multisig Wallets > Import from file
Descriptors can be also exported via NFC.
Descriptor tutorials: tutorial 0 tutorial 1
We support air-gapped creation of multisig wallets, so that you never need to directly connect the Coldcard to a computer. The steps are as follows:
Insert SD card with exported XPUB files
from at least one other Coldcard. A multisig
wallet will be constructed using those
keys and this device.
Default is P2WSH addresses (segwit), but
press (1) for P2SH-P2WSH or (2) for P2SH
(legacy) instead.
Press either OK, (1), or (2) based on your preference for address formats, and the next screen will be similar to this:
Now you may press (7) or (9) to change the M value. The N value (number of keys) is determined by the number of "ccxp" files found on the MicroSD card.
Press OK, and you'll see the usual preview of the new wallet to be imported. Confirm that, and the Coldcard will record it and then export two files back onto the MicroSD: a coldcard multisig wallet config file (for importing into the other Coldcards involved), and also an electrum skeleton wallet file.
(Both those files can be re-exported later using the various menus on the Coldcard, if need be.)
At this point, you should return the MicroSD to the other cosigning Coldcards, and import the multisig wallet into each. You are now ready to sign transactions.
BIP-39 passwords can be used to create multiple co-signers from a single Coldcard.
Details of the multisig wallets are saved up as part of the normal encrypted backup. Multisig wallets can be reconstructed from the seed words, but the M-of-N policy, co-signer xfp/xpubs, derivation path and address type must be known.
BIP-67 is used to define the ordering of public keys in all redeem scripts. It is an error to provide a redeem script in another order. Therefore, it doesn't matter what order the co-signers are listed when importing a wallet.
Due to limited encrypted memory, the Coldcard can only store the details of up to eight M-of-3 wallets, or a single M-of-15 wallet. If this is a problem, consider using "Trust PSBT" setting.
We've found relevant search results.