Test a shared Bitcoin payment that needs two keys

Rehearse a two-of-three payment on Bitcoin Core's local test network. Check that one signature falls short and that a second member's signature completes the payment.

Before you start

Computer tools, KeySigner on iPhone and Bitcoin Core regtest

  • Use a shared Bitcoin wallet with an explicit threshold and its matching wallet descriptor. Each input needs signatures from the required number of members. Use a new regtest wallet and test coins.

Data and access

Shared or checked
Wallet participants pass the PSBT and add signatures for its inputs. Bitcoin Core checks the finalized two-signature spend.
Check separately
Coins at the original address remain governed by its original keys and threshold when you change the member set.

Who does what

Setup administrator
Configures the three test keys and two-key rule. The group records the descriptor and verifies the funded address.
Payment preparer
Builds the PSBT for that address and records the intended recipient, amount, fee and change.
Member signers
Use two distinct eligible keys to sign every input in the same PSBT, then combine the signatures for finalization.
Original key holders
Keep the original descriptor and enough original keys to spend the funded outputs. A replacement configuration has a different address.
  1. Check the shared wallet's rule

    In your KeySigner test deployment, have the administrator configure a Bitcoin account with three test keys and two required for payment. Run keysigner-btc multisig ACCOUNT --network regtest with your test account name. Compare the descriptor, address and threshold with your test configuration.

    Check. The output shows a 2-of-3 descriptor and the expected regtest address. Compare all three public keys with your test configuration.

  2. Prepare a payment from the shared address

    Fund the shared address with regtest coins. Use Bitcoin Core to prepare payment.psbt with the shared wallet descriptor and the amounts for its inputs. Check that your change returns to the shared address.

    Check. Decode the PSBT in Bitcoin Core and check the funded inputs, recipient amount, fee and shared-address change.

  3. Try the payment with one member

    Run keysigner-btc sign-psbt --network regtest --key PUBLIC_KEY payment.psbt with the first member's public key. Review and approve on that member's device. Save the partially signed file and check that keysigner-btc finalize-multisig refuses to finalize it.

    Check. The first signature is present in the PSBT. Finalization with that file alone fails.

  4. Add a second member and verify

    Have a second member sign the same proposal with their wallet after comparing the recipient, amount and fee. Combine the signatures if the wallet returned a separate PSBT. Run keysigner-btc finalize-multisig on the file containing both signatures and check the result with Bitcoin Core on regtest.

    Check. The finalized transaction has the reviewed outputs. Bitcoin Core accepts it on regtest.

Check your result

One member's signature cannot complete this payment. With two valid member signatures for each input, Bitcoin Core accepts the finalized transaction. Changing the members creates a different wallet address. Coins at the old address still require its original keys.

What we tested

Tested on . A local Bitcoin Core 32.1 regtest run used a simulated phone for the first signature and an independent test key for the second. Finalization failed with one signature. With both, Bitcoin Core accepted the resulting transaction on regtest.

How to verify your setup

If you get stuck

The wallet cannot finalize after two members approved

Confirm that both signatures are on the same unsigned transaction and apply to each input being spent. Compare the current proposal's descriptor with the descriptor that funded the coins.

Report a problem with this guide

Explore all setup guides →