Permissions consensus

Creating a consensual governance model

As described in the permissions management page, there are eight types of permissions in MultiChain blockchains. Three of these (connect, send and receive) can be considered as low risk – users who obtain them can only connect to the blockchain and transact on their own behalf. Three more (issue, create and activate) are medium risk, because users who obtain them can respectively issue assets, create streams, and manage other user’s low risk permissions. Two final permissions (mine and admin) can be considered as high risk – nodes with mine permissions participate in the consensus algorithm, while those with admin permissions can modify all other permissions for users.

The purpose of a blockchain is to create decentralized databases, which are not under the control of any individual party. Therefore it is natural and necessary to extend this philosophy to the administration of permissions. For all medium risk and high risk permissions, a MultiChain blockchain can be configured so that individual administrators are unable to change those permissions on their own. Instead, a certain proportion of the administrators have to agree before the permissions change takes place, with the proportions defined by the admin-consensus-* blockchain parameters.

This tutorial requires MultiChain running on Linux. Although in reality multiple administrators would be spread across multiple organizations (and therefore nodes), we can simulate the process by creating multiple addresses on a single node, and using the grantfrom command to control which address performs each permissions change.

Setting up the blockchain

We will start by creating a new blockchain from the command line, with specific values for certain blockchain parameters, then launching the chain and entering interactive command mode:

multichain-util create chain0 -setup-first-blocks=1 -admin-consensus-admin=0.6 -admin-consensus-create=0.8
multichaind chain0 -daemon
multichain-cli chain0

The interactive prompt chain0: should be displayed. Now enter this command:

getblockchainparams

This is a full list of all the parameters which define the chain’s behavior. Among the list you should see the following lines:

"setup-first-blocks" : 1
"admin-consensus-admin" : 0.60000000
"admin-consensus-create" : 0.80000000

These match the parameter values that were provided to multichain-util above. The setup-first-blocks parameter defines how long the initial “setup period” of the blockchain lasts, in blocks. During the setup period, the usual rules on administrator consensus are not applied. For this tutorial we deliberately make the setup period as short as possible, so we can see permissions consensus in action.

Administrator consensus

Let’s start by finding out the address of the current administrator:

listpermissions admin

Copy and paste the shown address here:

This is the address embedded in the genesis block which started off the blockchain, and which automatically receives all permissions. Now let’s get a new address for adding as another administrator:

getnewaddress

Copy and paste the new address here:

Now let’s use the existing administrator to assign admin privileges to this new address:

grantfrom admin

A 64-character hexadecimal transaction ID should be shown for the transaction that made this permissions change. Now let’s check the result:

listpermissions admin

The new address should now be shown with admin permissions, with the maximum block range of 0 to 4294967295. It is possible to restrict permissions to specific block numbers, but we won’t be doing so in this tutorial. Now let’s create a third administrator:

getnewaddress

Copy and paste the new address here:

grantfrom admin
listpermissions admin

Only two administrators should be shown, with the new address excluded. This is because the consensus administration model has kicked in. Since admin-consensus-admin=0.6, any change to the admin privileges of an address must be approved by at least 0.6 * (the current number of administrators), rounded up. Since we already have two administrators, and 0.6 * 2 rounded up is 2, this means that both existing administrators must agree on any new one. So the new address is in an intermediate state, which can be seen by running:

listpermissions admin true

Note the pending structure, which indicates the administrators which have approved the permission change so far, and how many more are required. Let’s complete the permission change by granting admin privileges from the second administrator:

grantfrom admin
listpermissions admin

Now three administrators should be shown.

Consensus for other permissions

The same logic applies for the issue, create, activate and mine permissions, each of which has a corresponding admin-consensus-* blockchain parameter. Let’s see another example with create permissions, which we’ll assign to a new address:

getnewaddress

Copy and paste the shown address here:

Let’s grant the permission to this address by one administrator and see the results:

grantfrom create
listpermissions *

As before, this address does not yet have create permissions, due to the need for admin consensus. Let’s check the pending permission:

listpermissions * true

Note that admin-consensus-create=0.8, we now have three administrators, and 0.8 * 3 rounded up makes 3. Therefore all three administrators must agree on a create permissions change. So let’s assign it from another administrator and check the status:

grantfrom create
listpermissions * true

Two administrators should now be shown in the pending structure, with one more required. So let’s use the third administrator:

grantfrom create

Now the permission should be fully granted:

listpermissions *

We can still see which administrators granted these permissions in the admins structure here:

listpermissions * true

Where to go from here

This tutorial provided an overview of how multiple addresses with admin permissions must reach consensus for certain other permissions changes. Below are some other advanced topics relating to permissions:

  • Multisignatures which allow assets and more to be secured under the signatures from multiple blockchain participants.
  • Raw transactions which enable permissions to be assigned to multiple addresses in a single transaction.
  • Per-stream and per-asset permissions which can also be modified using the grant(from) and revoke(from) API commands.
  • The grantwithdata(from) API which allows metadata (either raw or as a stream item) to be included in permission change transactions.

It is also worth reading the permissions management page to gain a detailed understanding of how permissions are applied.