besu/docs/Permissions/Permissioning.md

description: Pantheon Permissions feature
<!--- END of page meta data -->

# Permissions 

A permissioned network is a network where only specified nodes and accounts (participants) can participate. 
Nodes and accounts outside those specified are prevented from participating. Permissioned networks can have node permissions enabled, 
account permissions enabled, or both. 

## Node Whitelisting 

Node whitelisting is specified by the nodes whitelist in the [`permissions_config.toml`](#permissions-configuration-file) file. 
A node with node whitelisting enabled communicates only with nodes in the nodes whitelist. 

!!! example "Nodes Whitelist in `permissons_config.toml`"
    `nodes-whitelist=["enode://6f8a80d14311c39f35f516fa664deaaaa13e85b2f7493f37f6144d86991ec012937307647bd3b9a82abe2974e1407241d54947bbb39763a4cac9f77166ad92a0@192.168.0.9:4567","enode://6f8a80d14311c39f35f516fa664deaaaa13e85b2f7493f37f6144d86991ec012937307647bd3b9a82abe2974e1407241d54947bbb39763a4cac9f77166ad92a0@192.169.0.9:4568"]`

Node whitelisting is at the node level. That is, each node in the network has a [`permissions_config.toml`](#permissions-configuration-file)
file in the [data directory](../Reference/Pantheon-CLI-Syntax.md#data-path) for the node.  

To update the nodes whitelist when the node is running, use the JSON-RPC API methods:
 
* [perm_addNodesToWhitelist](../Reference/JSON-RPC-API-Methods.md#perm__addnodestowhitelist)
* [perm_removeNodesFromWhitelist](../Reference/JSON-RPC-API-Methods.md#perm_removeNodesFromWhiteList)

Alternatively, update the [`permissions_config.toml`](#permissions-configuration-file) file directly and use the 
[`perm_reloadPermissionsFromFile`](../Reference/JSON-RPC-API-Methods.md#perm_reloadpermissionsfromfile) method 
to update the whitelists. 

To view the nodes whitelist, use the [perm_getNodesWhitelist](../Reference/JSON-RPC-API-Methods.md#perm_getNodesWhiteList) method. 

!!! note
    Each node has a `permissions_config.toml` file which means nodes can have different nodes whitelists. 
    This means nodes may be participating in the network that are not on the whitelist of other nodes in the network. 
    We recommend each node in the network has the same nodes whitelist. 
    
    On-chain permissioning is under development. On-chain permissioning will use one on-chain 
    nodes whitelist. 
    
!!! example "Example Different Node Whitelists" 

    Node 1 Whitelist = [Node 2, Node 3] 
    
    Node 2 Whitelist = [Node 3, Node 5] 
    
    Node 5 is participating in the same network as Node 1 even though Node 1 does not have Node 5 on their whitelist.

### Bootnodes

The bootnodes must be included in the nodes whitelist or Pantheon does not start when node permissions are enabled. 

!!! example 
    If you start Pantheon with:
    
     ```bash
     --bootnodes="enode://7e4ef30e9ec683f26ad76ffca5b5148fa7a6575f4cfad4eb0f52f9c3d8335f4a9b6f9e66fcc73ef95ed7a2a52784d4f372e7750ac8ae0b544309a5b391a23dd7@127.0.0.1:30303","enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304","enode://7b61d5ee4b44335873e6912cb5dd3e3877c860ba21417c9b9ef1f7e500a82213737d4b269046d0669fb2299a234ca03443f25fe5f706b693b3669e5c92478ade@127.0.0.1:30305" 
     ```
    
    The `nodes-whitelist` in [`permissions_config.toml`](#permissions-configuration-file) must contain the specified bootnodes. 

### Enabling Node Whitelisting     

To enable node whitelisting, specify the [`--permissions-nodes-enabled`](../Reference/Pantheon-CLI-Syntax.md#permissions-nodes-enabled) option 
when starting Pantheon. 

The `PERM` API methods are not enabled by default. Use the [`--rpc-http-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-api) 
or [`--rpc-ws-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-api) options to enable the `PERM` API methods.

## Account Whitelisting 

Account whitelisting is specified by the accounts whitelist in the [`permissions_config.toml`](#permissions-configuration-file) file.
A node with account permissions accepts transactions only from accounts in the accounts whitelist. 

!!! example "Accounts Whitelist in `permissons_config.toml`"
    `accounts-whitelist=["0x0000000000000000000000000000000000000009"]`
    
Account whitelisting is at the node level. That is, each node in the network has a [`permissions_config.toml`](#permissions-configuration-file)
file in the [data directory](../Reference/Pantheon-CLI-Syntax.md#data-path) for the node.    
    
Transactions are validated against the accounts whitelist at the following points: 

1. Submitted by JSON-RPC API method [`eth_sendRawTransaction`](../Reference/JSON-RPC-API-Methods.md#eth_sendrawtransaction) 
1. Received via propagation from another node 
1. Added to a block by a mining node 

Once added to a block, the transactions are not validated against the whitelist when received by another node. That is, a node 
can synchronise and add blocks containing transactions from accounts that are not on the accounts whitelist of that node.      
    
!!! example "Example Different Account Whitelists"
    Node 1 Whitelist = [Account A, Account B]
    
    Node 2 Whitelist = [Account B, Account C]
    
    Mining Node Whitelist = [Account A, Account B]
    
    Account A submits a transaction on Node 1. Node 1 validates and propagates the transaction. The Mining Node receives the transaction, 
    validates it is from an account in the Mining Node accounts whitelist, and includes the transaction in the block. Node 2 receives and 
    adds the block created by the Mining Node.
     
    Node 2 now has a transaction in the blockchain from Account A which is not on the accounts whitelist for Node 2.   

!!! note
    Each node has a [`permissions_config.toml`](#permissions-configuration-file) file which means nodes in the network can have different accounts whitelists. 
    This means a transaction can be successfully submitted by Node A from an account in the Node A whitelist but rejected by 
    Node B to which it is propagated if the account is not in the Node B whitelist. 
    We recommend each node in the network has the same accounts whitelist. 
        
    On-chain permissioning is under development. On-chain permissioning will use one on-chain 
    nodes whitelist. 

To update the accounts whitelist when the node is running, use the JSON-RPC API methods: 

* [`perm_addAccountsToWhitelist`](../Reference/JSON-RPC-API-Methods.md#perm_addAccountsToWhitelist)
* [`perm_removeAccountsFromWhitelist`](../Reference/JSON-RPC-API-Methods.md#perm_removeAccountsFromWhitelist)

Alternatively, update the [`permissions_config.toml`](#permissions-configuration-file) file directly and use the 
[`perm_reloadPermissionsFromFile`](../Reference/JSON-RPC-API-Methods.md#perm_reloadpermissionsfromfile) method 
to update the whitelists.

To view the accounts whitelist, use the [`perm_getAccountsWhitelist`](../Reference/JSON-RPC-API-Methods.md#perm_getAccountsWhitelist) method.

### Enabling Account Whitelisting 

To enable account whitelisting, specify the [`--permissions-accounts-enabled`](../Reference/Pantheon-CLI-Syntax.md#permissions-accounts-enabled) option 
when starting Pantheon. 

The `PERM` API methods are not enabled by default. Use the [`--rpc-http-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-api) 
or [`--rpc-ws-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-api) options to enable the `PERM` API methods.

## Permissions Configuration File 

The `permissions_config.toml` file contains the nodes and accounts whitelists. The `permissions_config.toml` 
must be in the [data directory](../Reference/Pantheon-CLI-Syntax.md#data-path) for the node.

!!! example "Example permissions_config.toml"  
    ```toml 
    accounts-whitelist=["0xb9b81ee349c3807e46bc71aa2632203c5b462032", "0xb9b81ee349c3807e46bc71aa2632203c5b462034"]
    
    nodes-whitelist=["enode://7e4ef30e9ec683f26ad76ffca5b5148fa7a6575f4cfad4eb0f52f9c3d8335f4a9b6f9e66fcc73ef95ed7a2a52784d4f372e7750ac8ae0b544309a5b391a23dd7@127.0.0.1:30303","enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304","enode://7b61d5ee4b44335873e6912cb5dd3e3877c860ba21417c9b9ef1f7e500a82213737d4b269046d0669fb2299a234ca03443f25fe5f706b693b3669e5c92478ade@127.0.0.1:30305"]
    ```