KiChain: How to use multi-signatures

Published in

Ki Foundation

6 min readMay 1, 2020

Welcome to the Ki-steps series, a sequence of how-to posts where we explain the detailed steps to perform more or less advanced tasks on the KiChain. In this post, we will tackle the creation and usage of multi-signature accounts. Multi-signatures are natively supported in the Cosmos SDK, they allow a secure and distributed governance of personal or shared funds.

If you've received two keys for your car when you bought it, if you've ever used two-factor authentication to secure your gmail account and if you've already watched a movie where the US president asks the pentagon for the challenge code to initiate a nuclear attack, then understanding multi-signature accounts should be a piece of cake for you.

A multi-signature account distributes the access (i.e., transfer, delegation, … ) to its fund over multiple keys and sets the minimal number of keys required to allow this access. By doing so it can achieve different security goals. Let's suppose that for an account the access is distributed over m>1 keys and that a number n<m of keys is required to achieve this access, then the following security goals can be achieved:

Redundancy : let's assume that one person holds all of the m account keys. If any of these keys is set to be sufficient to access the account's funds, i.e. n=1, loosing up to m-1 keys is not equivalent to loosing the access to the account. Think about it as having two keys for your car.
Security : again, let’s assume that one person holds all of the m account keys. If multiple keys are required at the same time to access the account's fund, i.e., n>2, compromising up to n-1 keys is not enough to compromise the access to the funds. Think about it as the signature and stamp on legal documents. both of them are required for the document to be valid. The higher the value of n is, the higher the security is. Indeed, this supposes that the keys are stored separately.
Shared responsibility : now, assuming that each key is held by a different party, the governance of the account is then shared between these parties. Setting n, defines the consensus level needed to be reached, between the holders, in order to allow the access to the funds. The higher the value of n is, the higher the consensus threshold is.

3D printed multi-signature. Picture source: https://www.youtube.com/watch?v=kbeD1shCNYA

In the remainder of this post we will explain how to use multi-signature in the KiChain using ki-tools. We will create a scenario where three wallets signer-1, signer-2 and signer-3, share the responsibility of a multi-signature account wallet-ms. Then, we will send 1 TKI from wallet-ms to a recipient wallet wallet-rc.

🔏 Create the multi-signature account

Open a machine with ki-tools installed, navigate to your node folder, and create a testing folder ms:

mkdir ms

Now let's create the participant wallets:

kicli keys add signer-1 --home kicli/

We will enter a passphrase to secure the account when asked and save the generated mnemonic and account details. Then we will repeat this procedure for the other accounts.

kicli keys add signer-2 --home kicli/
...kicli keys add signer-3 --home kicli/
...

Now that the participant wallets are created we can generate the multi-signature account. As explained earlier, we need to indicate the key holders (i.e., signer-1, signer-2 and signer-3) and the minimal number of signatures required to allow the access to the account's funds. The former can be done by passing the --multisig flag to the kicli keys add command and the latter with the --multisig-threshold flag.

kicli keys add wallet-ms —-multisig signer-1,signer-2,signer-3 
--multisig-threshold 2 --home ./kicli/

A multi-signature account does not have a private key. Thus, the previous command will not result in a passphrase as for non multi-signature accounts. It is worth noting that the order of the signers does not count in the created multi-signature address. However, this behaviour can be suppressed by adding the no-sort flag to the command.

📨 Generate a multi-signature transaction

Now that we have a multi-signature account, let's generate a multi-signature transaction. This step can be performed by any key holder as it does not require any verification or signature:

kicli tx send <address-wallet-ms> <address-wallet-rc> 1000000tki \
--home kicli/ --chain-id KiChain-t-1 --generate-only >> ms/tx.json

This will generate a file named tx.json that looks like :

{
  "type": "cosmos-sdk/StdTx",
  "value": {
    "msg": [{
      "type": "cosmos-sdk/MsgSend",
      "value": {
        "from_address": <address-wallet-ms>,
        "to_address": <address-wallet-rc>,
        "amount": [{
          "denom": "tki",
          "amount": "1000000"
        }]
      }
    }],
    "fee": {
      "amount": [],
      "gas": "200000"
    },
    "signatures": null,
    "memo": ""
  }
}

In a real world situation, this file is generated by any key holder and distributed to the other key holders by any communication channel (e.g., per mail). Those needs to read the transaction and ensure that it contains an agreed on transfer, in which case they proceed to the signature generation.

🖋️ Sign the transaction

Each signer needs now to sign the transaction and generate the signature file. To do so we will run the following command:

kicli tx sign —-from signer-1 —-multisig wallet-ms ms/tx.json 
—-home kicli/ —-chain-id KiChain-t-1 >> ms/tx_signer-1.json

We will enter the encryption passphrase for the current account when asked and proceed by generating the other signatures:

kicli tx sign —-from signer-2 —-multisig wallet-ms ms/tx.json 
—-home kicli/ —-chain-id KiChain-t-1 >> ms/tx_signer-2.json...kicli tx sign —-from signer-2 —-multisig wallet-ms ms/tx.json 
—-home kicli/ —-chain-id KiChain-t-1 >> ms/tx_signer-2.json

In a real world situation, the generated signature files are sent to one party by any communication channel (e.g., per mail). Which allows him to generate the final multi-signature and to broadcast the transaction.

📡 Multisign and broadcast

Since we set the signature threshold to 2, only 2 of the generated signature files are sufficient to complete the final multisignature and to broadcast the message. Using 2 or 3 of the signature files will result into 2 valid, yet different, final signatures. This allows to keep a signing record of how participated in signing this particular transaction.

To generate the file multi signature, let's run the following command:

kicli tx multisign --from wallet-ms  ms/tx.json wallet-ms \
ms/tx_signer-1.json ms/tx_signer-2.json ms/tx_signer-3.json \ 
--home kicli/ --chain-id KiChain-t-1 >> ms/tx_ms.json

Here we used all of the 3 individual signatures. Finally, let's broadcast the transaction using :

kicli tx broadcast ms/tx_ms.json \
--home kicli/ --chain-id KiChain-t-1

It is clear that signing transaction in the terminal is not the cup of tea of many people. Therefore, we are currently working on a simple tool that allows to accomplish the described steps in a nicely polished user interface.

In a future post, we will provide an in-depth technical discussion on how multi-signatures are generated and managed under the hood in the Cosmos SDK.

KiChain: How to use multi-signatures

🔏 Create the multi-signature account

📨 Generate a multi-signature transaction

🖋️ Sign the transaction

📡 Multisign and broadcast

Written by Tarek Awwad