How Permissions Work in EOS

5 min readOct 30, 2018

In EOS, a permission consists of 3 parts:

1. Permission name
2. Permission parent
3. Required authorization

Every account by default comes with the 2 permissions named owner and active. These permissions cannot be deleted.

Parent permissions can change the permission structure for any of their children. The owner permission is the parent of the active permission. New permissions may specify owner, active or any other existing permission as their parent.

Required Authorization

The required authorization for each permission consists of 4parts:

Threshold
Keys
Accounts
Waits

Example:

'required_auth': {    'threshold': 2,    'keys': [{
     'key': 'EOS6ZhCK4F2ErGTcTzrTdm3MigsDuUPvj5jA2nzgjwPdz9wEzdiLh',
     'weight': 1
    }],    'accounts': [{
      'permission': {
        'actor': 'eoscafeblock',
        'permission': 'claimrewards'
      },
      'weight': 1
    }],    'waits': [{
      'wait_sec': '3600',
      'weight': 1
    }]}

1. Threshold

An authorization object must specify a positive integer threshold (1, 2, 3…) for the permission to be satisfied. When executing an action, the weights of the provided keys, accounts and waits must be equal to or greater than the threshold specified to satisfy the permission.

In the example above, the threshold is set to 2 , with each of the keys, accounts and waits carrying a weight of 1 . When a user attempts to satisfy this permission, they must provide a minimum of two out of the three keys, accounts and waits.

2. Keys

EOS Keys come in pairs of public and private keys. Private keys are meant to be stored securely and not shared with anyone. Public keys can be shared openly, as only your secret private key can sign and derive your public key.

Public Key (54 chars): EOS6ZhCK4F2ErGTcTzrTdm3MigsDuUPvj5jA2nzgjwPdz9wEzdiLhPrivate Key (51 chars): 5Hs36geqNbJGXdPPJQ3Svrimxd1UBW3D92dPWB6BymUUyqAWGzv```

When using keys in the required authorization of each permission, you must provide the public key and weight of the key. In the required authorization object, we see:

'keys': [{
  'key': 'EOS6ZhCK4F2ErGTcTzrTdm3MigsDuUPvj5jA2nzgjwPdz9wEzdiLh',
  'weight': 1
}]

When executing an action that requires this permission, a user may sign with the correct private key for the public key provided to contribute a weight of 1 towards meeting the required authorization threshold of 2 .

If this key is the only key, account or weight provided, only 1/2 of the required threshold will be met, and the action will not be executed.

3. Accounts

EOS Accounts specified in the required authorization object come as a pair of actor and permission.

Take for example an account eoscafeblock with the permissions owner , active and claimrewards. The actor will be eoscafeblock and the permission may be owner, active or claimrewards.

In the required authorization object, this is specified as:

'accounts': [{
   'permission': {
       'actor': 'eoscafeblock',
       'permission': 'claimrewards'
   },
   'weight': 1
}]

A user specifying accounts in the authorization object leads to nesting of permissions. When executing an action that requires this permission, a user may provide keys, accounts or waits that satisfy the eoscafeblock@claimrewards requirement to contribute a weight of 1 towards meeting the required authorization threshold of 2 .

Account permissions are typically satisfied through multi-sig transactions. For more information on multi-sig, have a look at GenerEOS’ tutorial: https://helpdesk.eostoolkit.io/hc/en-us/articles/360013508332-How-to-use-Multi-signature-transactions

4. Waits

Specifying waits allows a user to ensure that transaction may not be executed without a required delay. To specify a wait in EOS, you must provide a wait_sec and weight of the delay.

wait_sec is an integer value in seconds of the transaction delay required to meet the requirement.

weight is an integer value similar to the one provided for keys and accounts, which specifies the weight added towards the threshold when the wait is satisfied.

In the required authorization object, this is specified as:

'waits': [{
   'wait_sec': '3600',
   'weight': 1
}]

This specific wait specifies a minimum transaction delay of 3600 seconds (1 hour). By default, every transaction has a delay of 0 seconds, and this can be increased to meet specified waits.

Ways to satisfy the permission

Lets have a look at the full permission object of the permissions discussed:

{ 
 'perm_name': 'test',
 'parent': 'active',
 'required_auth': {
    'threshold': 2,
    'keys': [{
     'key': 'EOS6ZhCK4F2ErGTcTzrTdm3MigsDuUPvj5jA2nzgjwPdz9wEzdiLh',
     'weight': 1
    }],
    'accounts': [{
      'permission': {
        'actor': 'eoscafeblock',
        'permission': 'claimrewards'
      },
      'weight': 1
    }],
    'waits': [{
      'wait_sec': '3600',
      'weight': 1
    }]
 }
}

Here, we specify a new permission named test which has the parent permission active and a threshold of 2 . There are 3 ways to satisfy this permission:

Schedule the transaction to be delayed by 1 hour and provide authorization for the key EOS6ZhCK4F2ErGTcTzrTdm3MigsDuUPvj5jA2nzgjwPdz9wEzdiLh
Schedule the transaction to be delayed by 1 hour and provide authorization for the permission eoscafeblock@claimrewards
Provide authorization for the key EOS6ZhCK4F2ErGTcTzrTdm3MigsDuUPvj5jA2nzgjwPdz9wEzdiLh and the permission eoscafeblock@claimrewards

Instead of satisfying the permission, the user may also use their active permission, which is the parent of this new test permission to change the permission structure at any time.

Managing Permissions and Delaying Transactions

It is important for users to fully understand permission structures before attempting to change owner and active permissions. For example, setting a delay on your owner permission is unlikely to be useful, as any actions taken to mitigate a potential hack of your owner key will be subject to the same delay.

Users may use https://bloks.io/wallet/permissions-manager to modify and add thresholds, keys, accounts and waits to their permission structure.

https://bloks.io/wallet now also provides a TX Delay option (with a default of 0) at the top of the page to delay your actions as required to meet any waits on your permission structure

To cancel a delayed transactions, users can call canceldelay using the TX ID of the scheduling transaction at: https://bloks.io/wallet/cancel-deferred

Twitter — @eoscafeblock
Medium — @eoscafeblock
Steemit — @eoscafeblock
Website — www.eoscafeblock.com

For any comments or questions, please reach out to us on telegram: https://t.me/eoscafeblock