Multisig accounts and multisig transactions

Account concept

This section describes the use of multisig accounts, including how to create multisig accounts on-chain via the CLI, and how to initiate multisig transactions. For the principle and implementation of multi-signature accounts, please refer to the multi-signature account section of the account concept.

Pre-preparation

Multi-signature transactions involve multiple participants. Here we use three participants, alice, bob and tom, to illustrate the process of multi-signature transactions.

1. First, you need to start three Starcoin dev nodes locally, corresponding to alice, bob and tom respectively, and connect to the console at the same time. The --discover-local option allows nodes to discover other nodes in the local area network, and then connect into a network.

% starcoin -n dev -d alice --discover-local true console
% starcoin -n dev -d bob --discover-local true console
% starcoin -n dev -d tom --discover-local true console

We use the default accounts provided by the three nodes as the personal accounts of alice, bob and tom respectively.

Personal account addresses of alice, bob and tom:

alice: 0x31515d36fa0b9e01bbdb1638d7c79e51
bob: 0x991c2f856a1e32985d9793b449c0f9d3
tom: 0x17183867a6142e821ee8a2dc6bb4d69d

2. Use the following commands to generate a new public-private key pair for each:

starcoin% account generate-keypair

# As follow:
{
  "ok": [
    {
      "address": "0xb6b67729f9ed83f3cf542952fbded752",
      "auth_key": "0x459381118ed14d42097b977aae5fe1d4b6b67729f9ed83f3cf542952fbded752",
      "private_key": "0xa530797cfb5fad79fe5ebf6add24dafbc141021a7d9c164840db0e29d944593d",
      "public_key": "0xf423c3d02ac400037a40e8dbbf8b3c3e4545548ff71332737bbfe1abbef97cb5",
      "receipt_identifier": "stc1pk6m8w20eakpl8n6599f0hhkh2gg3czy9"
    }
  ]
}

The generated key pair has 5 fields of information:

address -> Generate address (in this demo, useless)
auth_key -> authentication key
private_key -> private key
public_key -> public key
receipt_identifier -> receipt identifier

Note: Do not confuse the personal account address with the address generated by generate-keypair!

Here, it is assumed that the three of them generate pair key information (for example only, do not use it in the official network) are:

• alice:

  • pubkey: 0xf423c3d02ac400037a40e8dbbf8b3c3e4545548ff71332737bbfe1abbef97cb5
  • prikey: 0xa530797cfb5fad79fe5ebf6add24dafbc141021a7d9c164840db0e29d944593d

• bob:

  • pubkey: 0x3639b4d6bc2d6588a6517f82ae1ff7fa1e64eb994a4d8ee6d6f948e1997b97d0
  • prikey: 0x163e272560e53b75c087bc424fc7ff8cdbc0608ce4695f9bf69c8bd430a2bfeb

• tom:

  • pubkey: 0x7315e22ea8bd4aaa8bdfe65b4a3c9334d726e12c21881cbbe9a79f57538c6301
  • prikey: 0xe38bfd1510a24c54d966dcbe13a4d06a798606f4b557823845156857b4dfb0b1

3. Each console gets 10,000 STC for the default account through the dev get-coin -v 10000STC command.

After completing the above preparations, let's start our multi-signature transaction process. The main steps are as follows:

1. First we create a multi-signature account locally.
2. Then ask alice to transfer an STC to this multi-signature account.
3. Finally, initiate a multi-signature transaction in the name of this multi-signature account: transfer money from the multi-signature account to bob.

Generate multisig account

It is assumed here that the reader understands the basic concepts of multi-signature accounts.

In this section, we will create a multi-signature account maintained by three participants, and transactions only require the signatures of two of them (threshold=2). We use the public-private key pair generated above and threshold=2 to generate a multi-signature account.

First, a multi-signature account jointly maintained by three people is generated in the nodes of alice, bob and tom.

Execute in alice's console:

# --pubkey specifies the generated public key of bob and tom, --prikey specifies the generated private key of alice
starcoin% account import-multisig --pubkey 0x3639b4d6bc2d6588a6517f82ae1ff7fa1e64eb994a4d8ee6d6f948e1997b97d0 --pubkey 0x7315e22ea8bd4aaa8bdfe65b4a3c9334d726e12c21881cbbe9a79f57538c6301 --prikey 0xa530797cfb5fad79fe5ebf6add24dafbc141021a7d9c164840db0e29d944593d -t 2

Execute in bob's console:

# --pubkey specifies the generated public key of alice and tom, --prikey specifies the generated private key of bob
starcoin% account import-multisig --pubkey 0xf423c3d02ac400037a40e8dbbf8b3c3e4545548ff71332737bbfe1abbef97cb5 --pubkey 0x7315e22ea8bd4aaa8bdfe65b4a3c9334d726e12c21881cbbe9a79f57538c6301 --prikey 0x163e272560e53b75c087bc424fc7ff8cdbc0608ce4695f9bf69c8bd430a2bfeb -t 2

Execute in tom's console:

# --pubkey specifies the generated public key of alice and bob, --prikey specifies the generated private key of tom
starcoin% account import-multisig --pubkey 0xf423c3d02ac400037a40e8dbbf8b3c3e4545548ff71332737bbfe1abbef97cb5 --pubkey 0x3639b4d6bc2d6588a6517f82ae1ff7fa1e64eb994a4d8ee6d6f948e1997b97d0 --prikey 0xe38bfd1510a24c54d966dcbe13a4d06a798606f4b557823845156857b4dfb0b1 -t 2

The --pubkey option specifies that generate-keypair generates a public key instead of the personal account's public key, the --prikey option specifies the private key generated by generate-keypair instead of the personal account's private key, and the -t option specifies the number of signatures required, ie threshold.

After executing the above commands on the three consoles, you will find that the three commands all generate the same multi-signature account information (Causion: priv_key of the three multi-sig account is different, see the next section):

{
  "ok": {
    "address": "0x8afd731146fbc206d56265adedb4b50a",
    "is_default": false,
    "is_readonly": false,
    "public_key": "0x3639b4d6bc2d6588a6517f82ae1ff7fa1e64eb994a4d8ee6d6f948e1997b97d07315e22ea8bd4aaa8bdfe65b4a3c9334d726e12c21881cbbe9a79f57538c6301f423c3d02ac400037a40e8dbbf8b3c3e4545548ff71332737bbfe1abbef97cb502",
    "receipt_identifier": "stc1p3t7hxy2xl0pqd4tzvkk7md94pgvvpcut"
  }
}

Understand the public and private keys of multi-signature accounts:

public key: You can see that the public key of this multi-signature account is very long. It is the combination of the public keys generated by multiple single-signature private keys. Everyone holds the same multisig public key.

private key: The private key of a multi-signature account is the combination of multiple single-signature private keys, each of which holds 1/n. Run account export 0x8afd731146fbc206d56265adedb4b50a in three consoles separately, to check private keys and compare them.

View multi-signature accounts:

starcoin% account show 0x8afd731146fbc206d56265adedb4b50a
{
  "ok": {
    "account": {
      "address": "0x8afd731146fbc206d56265adedb4b50a",
      "is_default": false,
      "is_readonly": false,
      "public_key": "0x3639b4d6bc2d6588a6517f82ae1ff7fa1e64eb994a4d8ee6d6f948e1997b97d07315e22ea8bd4aaa8bdfe65b4a3c9334d726e12c21881cbbe9a79f57538c6301f423c3d02ac400037a40e8dbbf8b3c3e4545548ff71332737bbfe1abbef97cb502",
      "receipt_identifier": "stc1p3t7hxy2xl0pqd4tzvkk7md94pgvvpcut"
    },
    "auth_key": "0xf112c676ef1a7bfbd29699f14a6260c88afd731146fbc206d56265adedb4b50a",
    "balances": {},
    "sequence_number": null
  }
}

Transfer money to a multisig account

In this section, we transfer 1000 STC from tom's account to this multi-signature account.

Executed in tom's Starcoin console:

starcoin% account transfer -r 0x8afd731146fbc206d56265adedb4b50a -v 1000000000000 -b

Then check the information of the multi-signature account:

starcoin% account show 0x8afd731146fbc206d56265adedb4b50a
{
  "ok": {
    "account": {
      "address": "0x8afd731146fbc206d56265adedb4b50a",
      "is_default": false,
      "is_readonly": false,
      "public_key": "0x3639b4d6bc2d6588a6517f82ae1ff7fa1e64eb994a4d8ee6d6f948e1997b97d07315e22ea8bd4aaa8bdfe65b4a3c9334d726e12c21881cbbe9a79f57538c6301f423c3d02ac400037a40e8dbbf8b3c3e4545548ff71332737bbfe1abbef97cb502",
      "receipt_identifier": "stc1p3t7hxy2xl0pqd4tzvkk7md94pgvvpcut"
    },
    "auth_key": "0xf112c676ef1a7bfbd29699f14a6260c88afd731146fbc206d56265adedb4b50a",
    "balances": {
      "0x00000000000000000000000000000001::STC::STC": 1000000000000
    },
    "sequence_number": 0
  }
}

Pay attention to the balances field: the multi-signature account already has 1000 STC at this point.

Initiate a multisig transaction

Now the multi-signature account has 1000 STC.

Let's initiate a multi-signature transaction: transfer 1 STC from the multi-signature account to bob.

Execute in tom's Starcoin console:

starcoin% account sign-multisig-txn -s 0x8afd731146fbc206d56265adedb4b50a --function 0x1::TransferScripts::peer_to_peer_v2 -t 0x1::STC::STC --arg 0x991c2f856a1e32985d9793b449c0f9d3 --arg 1000000000u128

where peer_to_peer_v2 script parameters:

• 0x991c2f856a1e32985d9793b449c0f9d3 is bob's personal account address.
• 1000000000u128 is the number of tokens to send.

After a while, you should see the last few lines of output:

mutlisig txn(address: 0x8afd731146fbc206d56265adedb4b50a, threshold: 2): 1 signatures collected
still require 1 signatures
{
  "ok": "/94713c208ff452d4d02c5446eb18f5ab538b72976e08a84cada4b08be68583ab.multisig-txn"
}

This command will generate the original transaction and sign it with tom's multi-signature account private key. The generated transaction will be saved as a file in the current directory, and the file name is the hash of the transaction.

Note: The file path will vary slightly according to different operating systems and usage methods.

Command line prompt: One signature has been collected for this multi-signature transaction, and another signature is required. At this point, the generated transaction file needs to be distributed to other participants of the multi-signature account for signature.

Signatures of other participants

After alice gets the above transaction file, she signs it in her Starcoin console:

starcoin% account sign-multisig-txn /94713c208ff452d4d02c5446eb18f5ab538b72976e08a84cada4b08be68583ab.multisig-txn

After a while, you should see the last few lines of output:

mutlisig txn(address: 0x8afd731146fbc206d56265adedb4b50a, threshold: 2): 2 signatures collected
enough signatures collected for the multisig txn, txn can be submitted now
{
  "ok": "/root/f93382dc60d1f518e313202cc6f0b86116ba81e25b554b174537bfae18987837.multisig-txn"
}

This command will generate another multi-signature transaction signature file, which contains the signatures of tom's multi-signature private key and alice's multi-signature private key. The returned information prompts the user that the multi-signature transaction has collected enough signatures and can be submitted to the chain for execution.

Submit a multi-signature transaction

After the multi-signature transaction is fully generated, anyone can submit it to the chain. Here we submit the multisig transaction from bob's Starcoin console.

starcoin% account submit-multisig-txn f93382dc60d1f518e313202cc6f0b86116ba81e25b554b174537bfae18987837.multisig-txn

txn 0xf93382dc60d1f518e313202cc6f0b86116ba81e25b554b174537bfae18987837 submitted.
{
  "ok": {
    "events": null,
    "txn_hash": "0xf93382dc60d1f518e313202cc6f0b86116ba81e25b554b174537bfae18987837",
    "txn_info": null
  }
}

After waiting for the execution, check the information of the multi-signature account, and you will find that the balance of the multi-signature account has been reduced (gas fee and 1 STC transferred out), and the sequence_number of the account has also become 1, indicating that the transaction has been successfully executed.

starcoin% account show 0x8afd731146fbc206d56265adedb4b50a
{
  "ok": {
    "account": {
      "address": "0x8afd731146fbc206d56265adedb4b50a",
      "is_default": false,
      "is_readonly": false,
      "public_key": "0x3639b4d6bc2d6588a6517f82ae1ff7fa1e64eb994a4d8ee6d6f948e1997b97d07315e22ea8bd4aaa8bdfe65b4a3c9334d726e12c21881cbbe9a79f57538c6301f423c3d02ac400037a40e8dbbf8b3c3e4545548ff71332737bbfe1abbef97cb502",
      "receipt_identifier": "stc1p3t7hxy2xl0pqd4tzvkk7md94pgvvpcut"
    },
    "auth_key": "0xf112c676ef1a7bfbd29699f14a6260c88afd731146fbc206d56265adedb4b50a",
    "balances": {
      "0x00000000000000000000000000000001::STC::STC": 998999894453
    },
    "sequence_number": 1
  }
}

So far, you have completed the creation of a multi-signature account and the generation and on-chain execution of multi-signature transactions.

Other multisig management methods

• Manage Multisig via StarMask (Youtube)
• A multi-signature management tool based on NodeJs provided by WenWen