Add guide on multi-sig feature in concordium-client

Author: DOBEN

source/mainnet/net/references/concordium-client.rst

@@ -354,3 +354,4 @@ structure of ``concordium-client`` for more details.
 
    transactions
    query-node
+   multi-sig

source/mainnet/net/references/multi-sig.rst

@@ -0,0 +1,151 @@
+.. _multi-sig-concordium-client:
+
+=========
+Multi-sig
+=========
+
+Concordium supports natively multi-sig accounts. Each account address on
+Concordium is controlled by one or several credential(s) (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 pair(s).
+
+.. note::
+
+   A public-private key pair are related keys used for asymmetric cryptography.
+   The private key is used to sign/authorize an action relatd 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 with the ``concordium-client`` tool 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 own independent flow of creating a multi-sig account via its front end and
+   generating multi-sig transactions. The two guides :ref:`multi-sig accounts<overview-shared-accounts>` and
+   :ref:`multi-sig transactions<create-multisig>` will cover the flows in the Desktop wallet.
+   The partially-signed transaction file as generated by
+   the Desktop wallet is currently NOT compatible with 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.
+
+To add additional keys to an existing account on Concordium using the ``concordium-client`` tool, you can either:
+
+.. dropdown:: Add an additional public-private key pair to your current credential
+
+   - Step 1: Create an additional Ed25519 public-private key pair as you feel safe.
+
+   For testing purposes we recommend, the `front-end <https://cyphr.me/ed25519_tool/ed.html>`_ to generate an un-safe additional key pair.
+
+   - Step 2: Find the credential registration ID of your account that we are updating keys for.
+
+   Run the following command where you replace ``<account-name-or-account-address>`` with your account.
+
+   .. code-block:: console
+
+      $concordium-client account show <account-name-or-account-address>
+
+   This will output something like:
+
+   .. code-block:: console
+
+      Address:                3G5srtaeRvy2uzyaiheY3ZZ6nqTkDg1kRm59xWVnFo8CoEiZ6Y
+      Balance:                1001736.135182 CCD
+      Nonce:                  16
+      Encryption public key:  b14cbfe44a02c6b1f78711176d5f437295367aa4f2a8c2551ee10d25a03adc69d61a332a058971919dad7312e1fc94c5a411f21ab3b0962c6fb664212e41769e83c82288515f16ca72c86f8a03e87531cae46394bffc63ab6168432903d79fb0
+
+      Baking or delegating stake: no
+
+      Credentials:
+      * <credential-registration-id>:
+         - Index: 0
+         - Expiration: Jun 2023
+         - Type: normal
+         - Revealed attributes: none
+
+   We require the ``<credential-registration-id>`` output for the next step.
+
+   - Step 3: Send a transaction to update the keys of your account on-chain.
+
+   .. code-block:: console
+
+      $concordium-client account update-keys --credId <credential-registration-id> --sender <account-name-or-address> ./update-keys.json
+
+   where ``update-keys.json`` is a file of the following format:
+
+   .. code-block:: json
+      :force:
+
+      {
+         "keys": {
+            "0": {
+               "verifyKey": "<Hex encoding without '0x' of the public key already on chain>"
+            },
+            "1": {
+               "verifyKey": "<Hex encoding without '0x' of the public key from your newly generated key pair>"
+            }
+         },
+         "threshold": 2
+      }
+
+   This will replace the current key tied to the account with the keys in the ``update-keys.json`` file.
+   The above example file adds two keys to your account and sets the ``threshold`` (the number of keys you want
+   to have to sign the transaction) to 2. The above example generates a 2-out-of-2 multi-sig account.
+
+   The above file specifies all keys that are associated with your account after the update and the threshold can be set
+   accordingly to a number between 1 and the number of keys.
+
+.. dropdown:: Add an additional credential with at least one public-private key pair
+
+   - Step 1: Create an additional credential.
+
+   We recommend to use the flow in the Desktop wallet to :ref:`create a credential file<create-credentials-file>`.
+   Alternativley, you can `clone the project <https://github.com/Concordium/concordium-base/blob/main/rust-bins/src/bin/user_cli.rs>`_
+   and run its command locally to generate a credential file.
+
+   - Step 2: Send a transaction to add an credential to your account on-chain.
+
+   .. code-block:: console
+
+      $concordium-client account update-credentials --new-credentials new-credential.json --new-threshold <number-of-credential-to-sign> --sender <account-name-or-address>
+
+   where ``new-credential.json`` is the file from the previous step.
+
+   This will add an additional credential to your account.
+   The ``<number-of-credential-to-sign>`` specifies the minimum number of credentials that need to sign the transaction after the update.
+
+Configure the tool to use a multi-sig account
+=============================================
+Create a multi-sig transaction
+==============================
+Add an additional signature to a multi-sig transaction
+======================================================
+Send a multi-sig transaction on-chain
+=====================================
+
+
+.. note::
+
+   Additional resources:
+
+   - `Use multi-sig accounts in the Rust SDK <https://gist.github.com/DOBEN/683fe1a7c82a0551546a7ec242d30cc0>`_
+