Skip to content

Multisig Features

(new in v2.1.0, major changes in v3.2.1)

What is Multisig?#

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.

Setup Your Multisig Wallet#

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:

  1. How many co-signers are there? This is the N value.
  2. How many are required to approve spends? This is M.
  3. The COLDCARD needs to know the XPUB of all co-signers, to be able display addresses and to verify change outputs.
  4. The XFP (extended fingerprint) of all cosigner keys. In some limited cases this can be determined from the cosigner's XPUB, but in general it cannot.
  5. The address format: traditional P2SH, P2WSH (segwit) or P2WSH wrapped in P2SH (transitional).
  6. The key derivation path is needed. In versions before 3.2.1 this was optional.
  7. A wallet name, limited to 20 characters.

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).

Multisig Wallets Menu#

Mk4 multisig menu Q multisig menu

There is a dedicated menu, Settings > Multisig Wallets, which lists all established multisig wallets and contains related functions and settings.

Multisig Wallets Menu Options

  • 2/4: MeMyself

    Your multisig wallets will be listed here by name at the top of the menu. This example is a 2-of-4 wallet entitled "MeMyself". Choose the name of your wallet to see more details about it, and perform a number of operations. (See Multisig Wallet Detail View section.)

  • Import from File

    Read a new wallet setup file from MicroSD card and import it (details are confirmed).

  • Import from QR (Q only)

    This feature is exclusive to the COLDCARD Q.

    Read a new wallet setup file from a QR code. The format of the file must be COLDCARD export or BIP-380 descriptor.

  • Import via NFC (if enabled)

    This option is only available if the NFC hardware is enabled.

    Read a new wallet setup file by tapping an NFC enabled device to the COLDCARD. The format of the file must be COLDCARD export or BIP-380 descriptor.

  • Export XPUB

    Creates a file on the MicroSD file that has a few possible XPUB keys for this COLDCARD. The resulting file is used in the next command, Create Airgapped.

  • Create Airgapped

    Creates a new multisig wallet based on the contents of the MicroSD. You have a chance to pick M value, and see details of the wallet.

  • Trust PSBT?

    A setting related to how we should treat the data relating to Multisig wallets in PSBT files.

  • Skip Checks?

    Temporarily disables some more rigorous checks during PSBT signing.

  • Full Address View

    With this setting enabled, full multisig addresses will be shown in the Address Explorer. The default setting is to show only partial addresses. You should always cross-verify multisig addresses with your coordinator software.

  • Unsorted Multisig

    This setting will allow you to import and operate "multi(...)" unsorted multisig wallets that do not follow BIP-67.

Setting: Trust PSBT?#

Mk4 trust psbt Q trust psbt

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:

  • Verify Only

    Do not import the xpubs found, but do verify the correct wallet already exists on the COLDCARD.

  • Offer Import

    If it's a new multisig wallet, offer to import the details and store them as a new wallet in the COLDCARD.

  • Trust PSBT

    Use the wallet data in the PSBT as a temporary, multisig wallet, and do not import it. This permits some deniability and additional privacy.

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 Import unless at least one multisig wallet already exists, in which case the default becomes Verify Only.

Setting: Skip Checks?#

With this setting, 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.

Multisig Wallet Detail View#

Mk4 multisig wallet Q multisig wallet

Choose the existing wallet, by name, from the top of the Multisig Wallets Menu and you can view the details about your wallet.

Existing Multisig Wallet Options

  • MeMyself

    The first line is the name: "MeMyself".

  • View Details

    Select this to the signing policy, XPUBs, and all other details. It will look something like this:

    Mk4 view details Q view details

  • Delete

    Forget this wallet.

  • Coldcard Export

    Create the text file other COLDCARDs would need to work with this wallet.

  • Electrum Wallet

    Export a skeleton Electrum wallet file to support this wallet.

  • Descriptors

    Export multisig wallet as a BIP-380 descriptor.

Configuration Text File for Multisig#

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 0F056943)
#
Name: MeMyself
Policy: 2 of 4
Format: P2WSH

Derivation: m/48h/0h/0h/2h

3E43D16E: xpub6E3BHfxkPx3frToeeeUUMUQtmFrPBeQtHm84AWVSiCdYEWarHpkiLYYkFmQUScRCzdHES6CHExULKA9vmBDJfkGBRgrjSw91BLsFp2nwQz6
69206D28: xpub6En3943qPHsxgzCjJr8anvVSHciyvk4FFVB9RPwfhzTrwY8oyuDqVCECrzG8S3mNkTfC2EP6U5JHSGH83DjG88QsVarckRWLPkFd64BBXGa
B219DEC3: xpub6EjC7ni4V9ek8gadsoBDSvJNxycq3V3KDub9jreJjGsrQXdtuzESGdZzhn3E66zMvLT6m9AEyWAZLRKg6Xmm9U4baFbEFZTxJVGbrvysbRH
0F056943: xpub6FQgdFZAHcAeAhQX2VvQ42CW2fDdKDhgwzhzXuUhWb4yfArmaZXkLbGS9W1UcgHwNxVESCS1b8BK8tgNYEF8cgmc9zkmsE45QSEvbwdp6Kr
  • Comments start with # and go the end of the line. Blank lines are okay.
  • Values and labels are case insensitive.
  • All lines are optional, but most users will want to specify the Policy and Name lines, and the derivation value is required in almost all cases.
  • The Derivation value can be repeated and will apply to all XPUB's lower in the file.
  • The colon is required.
Multisig File Values and Formats

  • Name

    Up to 20 characters. Shown on menus and on-screen during transaction approval.

  • Policy

    Defines M and N values. Can be written "M of N", or just "M/N".

  • Format

    Address format. Must be one of these values: p2sh, p2wsh, or p2sh-p2wsh.

  • Derivation

    Specify the derivation of the XPUBs. Applies to all subsequent XPUBs and may be repeated. Must use single quote or h for hardened keys, and start with m/ (master).

  • XFP (8 digits of hex)

    The fingerprint of the XPUB is used to label it in this file. The rest of the line, after the colon is the XPUB for that signer. It should be the XPUB at the derivation path, not the master key. SLIP-132 format keys can be used, but they will be converted and stored in BIP-32 format internally (and in future exports).

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.

If any field is missing, these defaults will be used:

  • Name

    Set to "M-of-N" with M and N values filled-in.

  • Derivation

    Optional, but no default can be provided unless it can be deduced from all XPUBs, which would require tree depth of one, which is very rare.

  • Format

    Default: P2SH

  • Missing XFP

    Calculated when possible, for example if XPUB is derived based on BIP-45 as m/45'.

  • Policy

    Default is M==N. Number of keys as detected in file.

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.

Create a Multisig Wallet Using Electrum#

Electrum is one possible software to use as a multisig coordinator. A coordinator can be used to create multisig wallets involving one or more COLDCARDs.

To create a multisig wallet using only the COLDCARD, see the Airgap Multisig guide.

Steps to Create Multisig Wallet Using Electrum
  1. Choose: File > New/Restore from menu.
  2. Pick a new file.
  3. Under Create new wallet, choose: Multi-signature wallet
  4. Use sliders to pick M and N values.
  5. Under Keystore choose Use a hardware device for each co-signer which will be a COLDCARD.
  6. Under Hardware Keystore pick your COLDCARD.
  7. Pick desired address format.
  8. The Master Public Key can be ignored.
  9. Repeat for all co-signers.

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.

Descriptors#

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/*.

Examples of Descriptor Exports

Below is an example descriptor text file in pretty human-readable format. To export descriptor in pretty format, go to: Settings > Multisig Wallets > [wallet name] > Descriptors > View Descriptor, and 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
  • Comments start with # 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 > [wallet name] > 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 > [wallet name] > 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, or QR code on the Q.

Notes and Comments#

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