Multi-sig#

Concordium natively supports multi-sig accounts. Each account address on Concordium is controlled by one or several credentials (real-world identities e.g. a private person with a passport or a company with a registration) and each credential has one or several public-private key pairs.

Note

A public-private key pair are related keys used for asymmetric cryptography. The private key is used to sign/authorize an action related to the account. NEVER share your private key with anyone. In contrast, the public key is shared with other entities to verify that a signature is generated by the associated private key.

Each account has an AccountThreshold (number of credentials needed to sign the transaction initiated by that account) and one or several SignatureThresholds (number of signatures needed for a specific credential so that this credential is considered to have signed the transaction initiated by that account).

The concordium-client tool (version 6.3.0 or above) facilitates creating, signing, and sending of multi-sig transactions for multi-sig accounts. This page will go through the main steps as follows:

Create a multi-sig account by adding keys via an on-chain transaction to an account.
Configure the concordium-client tool to use a multi-sig account.
Create a multi-sig transaction with the concordium-client tool.
Add an additional signature to a multi-sig transaction with the concordium-client tool.
Send a multi-sig transaction with the concordium-client tool on-chain.

Create a multi-sig account#

When you create an account in one of the Concordium wallets, it is a basic account by default that has exactly one credential and exactly one public-private key pair for that credential. A default account can be converted into a multi-sig account.

Note

The desktop wallet is the only wallet currently that has its independent flow of creating a multi-sig account via its frontend and generating multi-sig transactions. The two guides multi-sig accounts and multi-sig transactions will explain the flows for the desktop wallet. The multi-sig transaction file, as generated by the desktop wallet, is currently NOT compatible with the file generated by the concordium-client tool. You need to add additional signatures and send the transaction on-chain with the wallet/tool the file was initially generated with. The intention is to use the file format of the concordium-client tool in all Concordium tooling related to multi-sig signing in the future and to replace the desktop wallet’s file format.

To add additional keys to an existing account on Concordium using the concordium-client tool, you can either:

Configure the tool to use a multi-sig account#

To configure the concordium-client tool to use a multi-sig account, you can either:

pass in the signing keys via a file every time you sign a transaction (Option 1).
configure the concordium-client tool once to include the additional keys in its local key directory (Option 2).

To view the key directory path that the concordium-client tool is using, run the following command:

$concordium-client config show

The goal is to add additional keys for your account to the local key directory of the concordium-client tool in this section (Option 2). The guide for the first option is in the following section.

Note

These commands update the keys in the key directory of your local concordium-client tool. No transaction is sent on-chain.

Create a multi-sig transaction#

Multi-sig transactions can be created for all active transaction types which are currently: DeployModule, InitContract, UpdateContract, Transfer(CCD), TransferWithMemo, TransferWithSchedule, TransferWithScheduleAndMemo, ConfigureDelegation, ConfigureBaker, RegisterData, UpdateCredential, and UpdateCredentialsKeys.

To create a multi-sig transaction, execute a transaction-creating command and add an --out flag. This flag will cause concordium-client to output the multi-sig transaction into the specified file instead of sending it on-chain.

If you omit the --signers flag, concordium-client will output a transaction signed with all keys associated with the account as present in the local key directory. If you want to sign with specific keys from the local key directory, you can specify some of them with the --signers flag (e.g. --signers "0:0,0:1").

For example, to create a multi-sig transaction to send 1 CCD to an account on testnet using the local key “0:0” to sign, run the following command:

$concordium-client transaction send \
   --receiver 4bbdAUCDK2D6cUvUeprGr4FaSaHXKuYmYVjyCa4bXSCu3NUXzA \
   --amount 1 \
   --out ./transaction.json \
   --energy 5000 \
   --sender 4jxvYasaPncfmCFCLZCvuL5cZuvR5HAQezCHZH7ZA7AGsRYpix \
   --signers "0:0" \
   --expiry "24h" \
   --grpc-port 20000 \
   --grpc-ip node.testnet.concordium.com

Note

Choose an expiryTime with the --expiry flag for the transaction that takes into account the time it takes to gather all signatures by the different entities. The expiration time of a transaction is specified as a relative duration (e.g. “30s”, “5m”) or a UNIX timestamp. If the expiryTime has passed, the transaction is no longer valid.

The multi-sig transaction is outputted into the transaction.json file and has the following format:

{
   "energy": 5000,
   "expiryTime": 1716995242,
   "nonce": 46,
   "payload": {
      "amount": "1000000",
      "toAddress": "4bbdAUCDK2D6cUvUeprGr4FaSaHXKuYmYVjyCa4bXSCu3NUXzA",
      "transactionType": "transfer"
   },
   "signature": {
      "0": {
         "0": "3099534c5f32daf64dc40b7a0013979b9b74b167d259fc787a363ed2db7f1bcdafdcf06e166b2d915c7f29043186b3015a6064755bf3c3733bca2151b2b19c04"
      }
   },
   "signer": "4jxvYasaPncfmCFCLZCvuL5cZuvR5HAQezCHZH7ZA7AGsRYpix",
   "version": 1
}

If you want to sign the transaction with keys that are not in the local key directory, you need to provide the keys as a separate file with the --keys flag. Keys provided with a flag take precedence and no lookup of local keys in the key directory is performed.

For example, to create a multi-sig transaction to send 1 CCD to an account on testnet using keys for signing from a file, run the following command:

$concordium-client transaction send \
   --keys ./keypair.json \
   --receiver 4bbdAUCDK2D6cUvUeprGr4FaSaHXKuYmYVjyCa4bXSCu3NUXzA \
   --amount 1 \
   --out ./transaction.json \
   --energy 5000 \
   --sender 4jxvYasaPncfmCFCLZCvuL5cZuvR5HAQezCHZH7ZA7AGsRYpix \
   --signers "0:0" \
   --grpc-ip node.testnet.concordium.com

where keypair.json is a file of the following format:

{
   "cidx": {
      "kidx": {
         "encryptedSignKey": {
            "metadata": {
               "encryptionMethod": "AES-256",
               "iterations": ...,
               "salt": ...,
               "initializationVector": ...,
               "keyDerivationMethod": "PBKDF2WithHmacSHA256"
            },
            "cipherText": ...
         },
         "verifyKey": ...,
         "schemeId": "Ed25519"
      },
      ...
   },
   ...
}

Note

You can read up on how to view the key directory of the concordium-client tool here. The format of the keypair.json file is the same as the format of the key files in the local key directory of the concordium-client tool.

If you want to create a multi-sig transaction with no signatures at all, you can use an empty keypair.json file of the following format:

{}

Add an additional signature to a multi-sig transaction#

For example, to sign the multi-sig testnet transaction in the transaction.json file (created in the previous section) on a potentially different device by a different entity, run the following command:

$concordium-client transaction add-signature ./transaction.json \
   --grpc-port 20000 \
   --grpc-ip node.testnet.concordium.com

Note

All keys (as present in the local key directory) associated with the signer account are used to sign the transaction since the --signers flag is omitted in the above command. Check that the signer account in the transaction.json file, is the account you want to look up its keys and sign with.

Note

If you want to sign with specific keys from the local key directory, you can specify some of them with the --signers flag (e.g. --signers "0:0,0:1").

Note

If you want to sign the transaction with keys that are not in the local key directory, you can use the --keys flag as described here.

The additional signatures generated are added to the multi-sig transaction into the transaction.json file and the file will look similar to the following format:

{
   "energy": 5000,
   "expiryTime": 1716995242,
   "nonce": 46,
   "payload": {
      "amount": "1000000",
      "toAddress": "4bbdAUCDK2D6cUvUeprGr4FaSaHXKuYmYVjyCa4bXSCu3NUXzA",
      "transactionType": "transfer"
   },
   "signature": {
      "0": {
         "0": "3099534c5f32daf64dc40b7a0013979b9b74b167d259fc787a363ed2db7f1bcdafdcf06e166b2d915c7f29043186b3015a6064755bf3c3733bca2151b2b19c04",
         "1": "52271842cd8bacf60bcdea0e7226539079574cef512991bb57bbd09bb27fe16008552f4ce926cac16abbf8190a97264d96ad405a35bd35c466ef86c3ba15680c"
      },
   },
   "signer": "4jxvYasaPncfmCFCLZCvuL5cZuvR5HAQezCHZH7ZA7AGsRYpix",
   "version": 1
}

Send a multi-sig transaction on-chain#

For example, to send the multi-sig testnet transaction from the transaction.json file (created in the previous section) on-chain, run the following command:

$concordium-client transaction submit ./transaction.json \
   --grpc-port 20000 \
   --grpc-ip node.testnet.concordium.com

Note

The node will reject the transaction if the threshold of signatures is not met.

Additional resources#

Note

Use multi-sig accounts in the Rust SDK