Multi-signature

Support for a multiple signature (otherwise known as multisig) addresses is a very useful feature of the existing Bitcoin protocol, though it requires some background knowledge in order to use it.

Most of the existing bitcoin wallets have no problems with sending money to multisig addresses, even if they don't support spending money from such. Gocoin can handle both.

What a multisig address is
A multisig address defines a set of public keys that are authorized to spend money from it and the minimum number of signatures needed to spend the money.
Obviously each of these needed signatures must be made with a different key from the predefined set.
Saying otherwise: multisig address states how many of the keys must sign a specific transaction, in order for it to be valid.
Multisig address looks just like a regular bitcoin address, except that it doesn't start with 1, but (usually) with 3.

Escrow
An example user case for a multisig address would be an escrow transaction.
Alice wants to send some coins to Bob, but only after Bob delivers a certain thing. So they find a third person who would act as the escrow judge - let's call him Carl.
They need a multisig address that requires 2 signatures out of 3 addresses.
So each of the three parties provides a public key from its private wallet: pubA, pubB, pubC - and they make a multisig address out of these 3 keys, that requires 2 signatures.
Now Alice sends coins to this address and waits for Bob to deliver the certain thing...
What is important here is that any two of the three can spend the money from this multisig address.
So if Alice and Bob do not want to bother Carl - they can just finalize the transaction by themselves.
But if either Alice or Bob would not be willing to cooperate any further - the other person can still spend the coins, deposited at the escrow address, if only Carl helps by providing his signature.

Multiple authentications
Another useful feature of the multisig addresses is a possibility to protect coins with several different wallets.
The simplest scenario would be 2 signatures out of 2 addresses - both are needed in order to spend the coins.
You have one wallet on one device (e.g. your PC) and a second wallet on a different device (a smartphone) - to spend the money you must sign the transaction with both your wallets.
So if a wallet on any of the two devices gets stolen, or otherwise compromised, your coins should still be safe because the attacker needs both the wallets to spend the money.
You can also think of combinations like 2 out of of 3, or even 3 out of 5 - making it not only more secure, but also safer for you in case if you'd loose access to one of the wallets.
Multiple authentications can be of course also applied to different people holding the wallets - e.g. employees of a certain organization.

Make multisig address

To create a multisig address you are going to need the public keys which will be entitled to spend a money from it.
Obviously each of the keys would come from a different wallet (otherwise using multisig doesn't make any sense).

Gather the public keys
Below we describe how to extract a public key from a Gocoin wallet, but of course a public key can come from any wallet software, not necessarily the one that is a part of Gocoin.
To fetch a public key from an existing Gocoin wallet, just execute:
    wallet -pub 1EqUmBY4wHQ5TmrPqWRCU5Etf6jo9yLwnu
This will print you a line like this:
    1EqUmBY4wHQ5TmrPqWRCU5Etf6jo9yLwnu => 0361e5c0bff39f18621693da42cd343d60e3e14b4e9eb46b220eb310a484fcebab
(0361e5c0bff39f18621693da42cd343d60e3e14b4e9eb46b220eb310a484fcebab - this is the public key)
Now repeat the "-pub <address>" operation, for each of the wallets that you want to participate in the multisig address, writing down each public key it returned.

Create multisig address
Having all the public keys (each as a hexdump) just bring them all together and use the mkmulti tool (tools/mkmulti.go) to crate the multisig address:
    mkmulti <number_of_sigs_needed_for_spending> <pubkey1> <pubkey2> <pubkey3> ...
(for testnet, just use a negative number)
For example:

    mkmulti 2 0361e5c0bff39f18621693da42cd343d60e3e14b4e9eb46b220eb310a484fcebab 032ff4e2041a4525404ec76bb6f2328f906d28b6222344771c991659d0efc79b58 \

0263e98b52afddeeb81c7e6e0bcb89e1c23c12c809da7f6cb16d899eda8554ec1b
This will create a file named 3DAHwsGVN5wQnhR3Ax9AXw5czZbk83z2CV.json containing all kind of useful info.
Store this file for the future. It doesn't contain big secrets (just the public keys), so you should not need to hide it quite much.
This address (3DAHwsGVN5wQnhR3Ax9AXw5czZbk83z2CV) is an actual bitcoin address and you can send money to it.

Add multisig address to your wallet

You can add multisig addresses to the client's wallets, just like any other address.
To do this use the Edit button on the Wallet page of the WebUI.
Like with the regular addresses you can also append a label to multisig address, after a space.

Note: in order to use Gocoin for spending anything from a multisig address, you will need to have the address added to your currently selected wallet file.

Spend from your multisig address

Make sure that the currently selected wallet has the multisig address in it and the address itself has some unspent coins.
Now go to MakeTx tab of the WebUI.

You will need to pass your transaction through all the parties/wallets that are supposed to sign it. The output transaction from one party/wallet becomes an input transaction for the next one. The output from the last wallet should already be a sufficiently signed transaction that only needs to be sent to the network. Send it out using the same way as for regular (non multisig) transactions.

At any moment when signing your transaction it may be useful to look inside it by executing:
    wallet -d 012345678.txt

Note: Singing of multisig inputs does not require the balance folder. You only need to pass a raw transaction file through the multisig signing wallets.

Select the input you want to spend In MakeTx page. You can select several inputs from the same address, but do not mix different addresses here.
Fill in the payment details as usually and download the payment.zip
What you need at this moment is just the tx2sign.txt from the zip.

Now take the value (the hexdump) of "redeemScript" from the .json file describing the address that you are spending money from (created before with mkmulti).
It doesn't quite matter on which PC you would execute this command:
    wallet -raw tx2sign.txt -p2sh <hexdump_value_of_redeemScript>
This command should produce file multi2sign.txt - that is the file you will need to sing now.

So take multi2sign.txt to your first wallet machine and execute:
    wallet -raw multi2sign.txt
This should create a new raw transaction file (named like 01234567.txt) that already has the fist required signature inside.
If you need more signatures, just keep repeating the "wallet -raw <txfile.txt>" command at other wallets that are entitled to sign it. Remember to always use the most recently created raw transaction file.

Note: You can specify a specific signing key by adding -msign <addr> switch. Otherwise all keys known to the wallet will be used.