description: Pantheon Create a Permissioned network # Creating a Permissioned Network The following steps set up a permissioned network with node and account permissions. The network uses the [Clique Proof of Authority consensus protocol](../Consensus-Protocols/Clique.md). !!!important A permissioned Ethereum network as described here is not protected against all attack vectors. We recommend applying defense in depth to protect your infrastructure. ## Prerequisites [Pantheon](../Installation/Install-Binaries.md) [Curl (or similar web service client)](https://curl.haxx.se/download.html) ## Steps To create a permissoned network: 1. [Create Folders](#1-create-folders) 1. [Get Node Public Keys](#2-get-node-public-keys) 1. [Get Address of Node-1](#3-get-address-of-node-1) 1. [Create Genesis File](#4-create-genesis-file) 1. [Create Permissions Configuration File](#5-create-permissions-configuration-file) 1. [Delete Database Directories](#6-delete-database-directories) 1. [Start First Node as Bootnode](#7-start-first-node-as-bootnode) 1. [Start Node-2](#8-start-node-2) 1. [Start Node-3](#9-start-node-3) 1. [Confirm Permissioned Network is Working](#10-confirm-permissioned-network-is-working) ### 1. Create Folders Each node requires a data directory for the blockchain data. When the node is started, the [node key](../Configuring-Pantheon/Node-Keys.md) is saved in this directory. Create directories for your permissioned network, each of the three nodes, and a data directory for each node: ```bash Permissioned-Network/ ├── Node-1 │   ├── Node-1-data-path ├── Node-2 │   ├── Node-2-data-path └── Node-3 ├── Node-3-data-path ``` ### 2. Get Node Public Keys The [enode URL](../Configuring-Pantheon/Node-Keys.md#enode-url) of each node is needed for the nodes whitelist. In the `Node-1` directory, use the [`public-key`](../Reference/Pantheon-CLI-Syntax.md#public-key) subcommand to write the [node public key](../Configuring-Pantheon/Node-Keys.md) to the specified file (`publicKeyNode1` in this example): ```bash tab="MacOS" pantheon --data-path=Node-1-data-path public-key export --to=Node-1-data-path/publicKeyNode1 ``` ```bash tab="Windows" pantheon --data-path=Node-1-data-path public-key export --to=Node-1-data-path\publicKeyNode1 ``` Your node 1 directory now contains: ```bash ├── Node-1    ├── Node-1-data-path ├── database       ├── key       ├── publicKeyNode1 ``` The `database` directory contains the blockchain data. Repeat this for Node-2 and Node-3 in the `Node-2` and `Node-3` directories: ```bash tab="MacOS" pantheon --data-path=Node-2-data-path public-key export --to=Node-2-data-path/publicKeyNode2 pantheon --data-path=Node-3-data-path public-key export --to=Node-3-data-path/publicKeyNode3 ``` ```bash tab="Windows" pantheon --data-path=Node-2-data-path public-key export --to=Node-2-data-path\publicKeyNode2 pantheon --data-path=Node-3-data-path public-key export --to=Node-3-data-path\publicKeyNode3 ``` ### 3. Get Address of Node-1 In networks using Clique, the address of at least one initial signer must be included in the genesis file. For this network, we will use Node-1 as the initial signer. This requires obtaining the address for Node-1. To obtain the address for Node-1, do one of the following with the private key in the `key` file in the `Node-1-data-path` directory: * Import the private key into [MetaMask](https://metamask.io/) and click the **Copy to clipboard** button displayed when hovering over the account name and address. * Use the [ethereumjs-util](https://github.com/ethereumjs/ethereumjs-util) library and [node](https://nodejs.org/en/) to execute the following where `` is replaced by the private key for Node-1 without the 0x prefix. ```js var ethUtil = require('ethereumjs-util') const privKey = Buffer.from('', 'hex') var address = ethUtil.privateToAddress(privKey).toString('hex') console.log("Address=" + address) ``` ### 4. Create Genesis File The genesis file defines the genesis block of the blockchain (that is, the start of the blockchain). The [Clique genesis file](../Consensus-Protocols/Clique.md#genesis-file) includes the address of Node-1 as the initial signer in the `extraData` field. All nodes in a network must use the same genesis file. Copy the following genesis definition to a file called `cliqueGenesis.json` and save it in the `Permissioned-Network` directory: ```json { "config":{ "chainId":1981, "constantinoplefixblock": 0, "clique":{ "blockperiodseconds":15, "epochlength":30000 } }, "coinbase":"0x0000000000000000000000000000000000000000", "difficulty":"0x1", "extraData":"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", "gasLimit":"0xa00000", "mixHash":"0x0000000000000000000000000000000000000000000000000000000000000000", "nonce":"0x0", "timestamp":"0x5c51a607", "alloc": { "fe3b557e8fb62b89f4916b721be55ceb828dbd73": { "privateKey": "8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63", "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", "balance": "0xad78ebc5ac6200000" }, "627306090abaB3A6e1400e9345bC60c78a8BEf57": { "privateKey": "c87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3", "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", "balance": "90000000000000000000000" }, "f17f52151EbEF6C7334FAD080c5704D77216b732": { "privateKey": "ae6ae8e5ccbfb04590405997ee2d52d2b330726137b875053c36d94e974d162f", "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", "balance": "90000000000000000000000" } }, "number":"0x0", "gasUsed":"0x0", "parentHash":"0x0000000000000000000000000000000000000000000000000000000000000000" } ``` In `extraData`, replace `` with the [address for Node-1](#3-get-address-for-node-1) excluding the 0x prefix. !!! example ```json { ... "extraData":"0x0000000000000000000000000000000000000000000000000000000000000000b9b81ee349c3807e46bc71aa2632203c5b4620340000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", ... } ``` !!! warning Do not use the accounts in the genesis file on MainNet or any public network except for testing. The private keys are displayed which means the accounts are not secure. ### 5. Create Permissions Configuration File The permissions configuration file defines the nodes and accounts whitelists. Copy the following permissions configuration to a file called `permissions_config.toml` and save a copy in the `Node-1-data-path`, `Node-2-data-path`, and `Node-3-data-path` directories: !!! example "permissions_config.toml" ```toml accounts-whitelist=["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", "0x627306090abaB3A6e1400e9345bC60c78a8BEf57"] nodes-whitelist=["enode://@127.0.0.1:30303","enode://@127.0.0.1:30304","enode://@127.0.0.1:30305"] ``` Replace the public key as indicated for each enode URL with the [node public keys](#2-get-node-public-keys). The permissions configuration file includes: * First two accounts from the genesis file. * Enode URLs for each node. !!! note Permissions are specified at the node level. The [`permissions_config.toml`](../Permissions/Permissioning.md#permissions-configuration-file) file must be saved in the data directory for each node. On-chain permissioning is under development. On-chain permissioning will use one on-chain nodes whitelist and accounts whitelist. ### 6. Delete Database Directories Delete the `database` directories created when [getting the public keys for each node](#2-get-public-keys). The nodes cannot be started while the previously generated data is in the `database` directory. ### 7. Start First Node as Bootnode Start Node-1: ```bash tab="MacOS" pantheon --data-path=Node-1-data-path --genesis-file=../cliqueGenesis.json --permissions-nodes-enabled --permissions-accounts-enabled --rpc-http-enabled --rpc-http-api=ADMIN,ETH,NET,PERM,CLIQUE --host-whitelist=* --rpc-http-cors-origins=* ``` ```bash tab="Windows" pantheon --data-path=Node-1-data-path --genesis-file=..\cliqueGenesis.json --permissions-nodes-enabled --permissions-accounts-enabled --rpc-http-enabled --rpc-http-api=ADMIN,ETH,NET,PERM,CLIQUE --host-whitelist=* --rpc-http-cors-origins=* ``` The command line specifies: * Nodes and accounts permissions are enabled using the [`--permissions-nodes-enabled`](../Reference/Pantheon-CLI-Syntax.md#permissions-nodes-enabled) and [`--permissions-accounts-enabled`](../Reference/Pantheon-CLI-Syntax.md#permissions-accounts-enabled) * JSON-RPC API is enabled using the [`--rpc-http-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-enabled) option * ADMIN,ETH,NET,PERM, and CLIQUE APIs are enabled using the [`--rpc-http-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-api) option * All hosts can access the HTTP JSON-RPC API using the [`--host-whitelist`](../Reference/Pantheon-CLI-Syntax.md#host-whitelist) option * All domains can access the node using the HTTP JSON-RPC API using the [`--rpc-http-cors-origins`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-cors-origins) option. ### 8. Start Node-2 You need the [enode URL](../Configuring-Pantheon/Node-Keys.md#enode-url) for Node-1 to specify Node-1 as a bootnode. Start another terminal, change to the `Node-2` directory and start Node-2 replacing the public key in the enode URL with your bootonde: ```bash tab="MacOS" pantheon --data-path=Node-2-data-path --bootnodes="enode://@127.0.0.1:30303" --genesis-file=../cliqueGenesis.json --permissions-nodes-enabled --permissions-accounts-enabled --rpc-http-enabled --rpc-http-api=ADMIN,ETH,NET,PERM,CLIQUE --host-whitelist=* --rpc-http-cors-origins=* --p2p-port=30304 --rpc-http-port=8546 ``` ```bash tab="Windows" pantheon --data-path=Node-2-data-path --bootnodes="enode://@127.0.0.1:30303" --genesis-file=..\cliqueGenesis.json --permissions-nodes-enabled --permissions-accounts-enabled --rpc-http-enabled --rpc-http-api=ADMIN,ETH,NET,PERM,CLIQUE --host-whitelist=* --rpc-http-cors-origins=* --p2p-port=30304 --rpc-http-port=8546 ``` The command line specifies: * Different port to Node-1 for P2P peer discovery using the [`--p2p-port`](../Reference/Pantheon-CLI-Syntax.md#p2p-port) option * Different port to Node-1 for HTTP JSON-RPC using the [`--rpc-http-port`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-port) option * Enode URL for Node-1 using the [`--bootnodes`](../Reference/Pantheon-CLI-Syntax.md#bootnodes) option * Data directory for Node-2 using the [`--data-path`](../Reference/Pantheon-CLI-Syntax.md#data-path) option * Other options as for as for Node-1. ### 9. Start Node-3 Start another terminal, change to the `Node-3` directory and start Node-3 replacing the public key in the enode URL with your bootonde: ```bash tab="MacOS" pantheon --data-path=Node-3-data-path --bootnodes="enode://@127.0.0.1:30303" --genesis-file=../cliqueGenesis.json --permissions-nodes-enabled --permissions-accounts-enabled --rpc-http-enabled --rpc-http-api=ADMIN,ETH,NET,PERM,CLIQUE --host-whitelist=* --rpc-http-cors-origins=* --p2p-port=30305 --rpc-http-port=8547 ``` ```bash tab="Windows" pantheon --data-path=Node-3-data-path --bootnodes="enode://@127.0.0.1:30303" --genesis-file=..\cliqueGenesis.json --permissions-nodes-enabled --permissions-accounts-enabled --rpc-http-enabled --rpc-http-api=ADMIN,ETH,NET,PERM,CLIQUE --host-whitelist=* --rpc-http-cors-origins=* --p2p-port=30305 --rpc-http-port=8547 ``` The command line specifies: * Different port to Node-1 and Node-2 for P2P peer discovery using the [`--p2p-port`](../Reference/Pantheon-CLI-Syntax.md#p2p-port) option * Different port to Node-1 and Node-2 for HTTP JSON-RPC using the [`--rpc-http-port`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-port) option * Enode URL for Node-1 using the [`--bootnodes`](../Reference/Pantheon-CLI-Syntax.md#bootnodes) option * Data directory for Node-3 using the [`--data-path`](../Reference/Pantheon-CLI-Syntax.md#data-path) option * Other options as for as for Node-1. ### 10. Confirm Permissioned Network is Working #### Check Peer Count Start another terminal, use curl to call the JSON-RPC API [`net_peerCount`](../Reference/JSON-RPC-API-Methods.md#net_peercount) method and confirm the nodes are functioning as peers: ```bash curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' 127.0.0.1:8545 ``` The result confirms Node-1 (the node running the JSON-RPC service) has two peers (Node-2 and Node-3): ```json { "jsonrpc" : "2.0", "id" : 1, "result" : "0x2" } ``` #### Send a Transaction from an Account in the Whitelist Import the first account from the genesis file into MetaMask and send transactions as described in the [Private Network Quickstart Tutorial](Private-Network-Quickstart.md#creating-a-transaction-using-metamask): !!! example "Account 1 (Miner Coinbase Account)" * Address: `0xfe3b557e8fb62b89f4916b721be55ceb828dbd73` * Private key : `0x8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63` * Initial balance : `0xad78ebc5ac6200000` (200000000000000000000 in decimal) !!! info Pantheon does not implement [private key management](../Using-Pantheon/Account-Management.md). ### Try Sending a Transaction from an Account Not in the Accounts Whitelist Import the last account from the genesis file into MetaMask and try to send a transactions as described in the [Private Network Quickstart Tutorial](Private-Network-Quickstart.md#creating-a-transaction-using-metamask): !!! example "Account 3" * Address: `0xf17f52151EbEF6C7334FAD080c5704D77216b732` * Private key : `0xae6ae8e5ccbfb04590405997ee2d52d2b330726137b875053c36d94e974d162f` * Initial balance : `0x90000000000000000000000` (2785365088392105618523029504 in decimal) ### Start a Node Not on the Nodes Whitelist In your `Permissioned-Network` directory, create a `Node-4` directory and `Node-4-data-path` directory inside it. Change to the `Node-4` directory and start Node-4 replacing the public key in the enode URL with your bootnode as when starting Node-1 and Node-2: ```bash tab="MacOS" pantheon --data-path=Node-4-data-path --bootnodes="enode://@127.0.0.1:30303" --genesis-file=../cliqueGenesis.json --rpc-http-enabled --rpc-http-api=ADMIN,ETH,NET,PERM,CLIQUE --host-whitelist=* --rpc-http-cors-origins=* --p2p-port=30306 --rpc-http-port=8548 ``` ```bash tab="Windows" pantheon --data-path=Node-4-data-path --bootnodes="enode://@127.0.0.1:30303" --genesis-file=..\cliqueGenesis.json --rpc-http-enabled --rpc-http-api=ADMIN,ETH,NET,PERM,CLIQUE --host-whitelist=* --rpc-http-cors-origins=* --p2p-port=30306 --rpc-http-port=8548 ``` Start another terminal, use curl to call the JSON-RPC API [`net_peerCount`](../Reference/JSON-RPC-API-Methods.md#net_peercount) method: ```bash curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' 127.0.0.1:8548 ``` The result confirms Node-4 has no peers even though it specifies Node-1 as a bootnode: ```json { "jsonrpc" : "2.0", "id" : 1, "result" : "0x0" } ``` ## Stop Nodes When finished using the permissioned network, stop all nodes using ++ctrl+c++ in each terminal window. !!!tip To restart the permissioned network in the future, start from [7. Start First Node as Bootnode](#7-restart-first-node-as-bootnode).