Skip to content

Commit 10a5072

Browse files
bgravenorstbgravenorst
authored
Update Permissioning tutorials and added upgrade steps. (#615)
* Rename whitelist to allowlist. Signed-off-by: Byron Gravenorst <[email protected]> * Additional updates. Signed-off-by: Byron Gravenorst <[email protected]> * Whitelist renaming. Signed-off-by: Byron Gravenorst <[email protected]> * Address reviewer feedback. Signed-off-by: Byron Gravenorst <[email protected]> * Fix typos. Signed-off-by: Byron Gravenorst <[email protected]> * Update Permissioning tutorials and added upgrade steps. Signed-off-by: Byron Gravenorst <[email protected]> * Address reviewer feedback. Signed-off-by: Byron Gravenorst <[email protected]> * Fix broken link. Signed-off-by: Byron Gravenorst <[email protected]>
1 parent 2978209 commit 10a5072

File tree

4 files changed

+309
-48
lines changed

4 files changed

+309
-48
lines changed

‎docs/HowTo/Limit-Access/Specify-Perm-Version.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,9 @@ Specify the contract interface version that maps to the version of the [Enterpri
1212
the contract interface implements.
1313

1414
| | EEA Client Specification | Contract interface |
15-
|---------|--------------------------|--------------------|
15+
|:--------|:-------------------------|:-------------------|
1616
| Version | 5 | 1 |
1717
| Version | 6 | 2 |
1818

1919
The permissioning contracts in the [`ConsenSys/permissioning-smart-contracts`](https://github.com/ConsenSys/permissioning-smart-contracts)
20-
repository implement the version 1 contract interface.
20+
repository implement the version 2 contract interface.

‎docs/Tutorials/Permissioning/Getting-Started-Onchain-Permissioning.md‎

Lines changed: 184 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -7,22 +7,12 @@ description: Setting up and using Hyperledger Besu onchain permissioning
77
The following steps describe bootstrapping a permissioned network using a Hyperledger Besu
88
node and a development server to run the Permissioning Management Dapp.
99

10+
This tutorial configures permissioning on a [Clique Proof-of-Authority (PoA)] network.
11+
1012
!!! note
1113

1214
Production environments require a webserver to [host the Permissioning Management Dapp](../../HowTo/Deploy/Production.md).
1315

14-
To start a network with onchain permissioning:
15-
16-
1. [Install the prerequisites](#prerequisites)
17-
1. [Add the ingress contracts to the genesis file](#add-the-ingress-contracts-to-the-genesis-file)
18-
1. [Set the environment variables](#set-the-environment-variables)
19-
1. [Start first node with onchain permissioning and the JSON-RPC HTTP service enabled]
20-
1. [Clone the permissioning contracts repository and install dependencies]
21-
1. [Build the project](#build-the-project)
22-
1. [Deploy the permissioning contracts](#deploy-the-contracts)
23-
1. [Start the Web server for the Permissioning Management Dapp]
24-
1. [Add the first node to the nodes allowlist](#add-the-first-node-to-the-allowlist).
25-
2616
## Prerequisites
2717

2818
For the development server to run the dapp:
@@ -33,7 +23,104 @@ For the development server to run the dapp:
3323
* [Yarn](https://yarnpkg.com/en/) v1.15 or later
3424
* Browser with [MetaMask installed](https://metamask.io/).
3525

36-
## Add the ingress contracts to the genesis file
26+
## Steps
27+
28+
Listed on the right-hand side of the page are the steps to create a permissioned network.
29+
30+
### 1. Create folders
31+
32+
Each node requires a data directory for the blockchain data. When the node starts, Besu saves the
33+
[node key](../../Concepts/Node-Keys.md) in this directory.
34+
35+
Create directories for your permissioned network, each of the three nodes, and a data directory for
36+
each node:
37+
38+
```bash
39+
Permissioned-Network/
40+
├── Node-1
41+
│   ├── data
42+
├── Node-2
43+
│   ├── data
44+
└── Node-3
45+
├── data
46+
```
47+
48+
### 2. Get the address of Node-1
49+
50+
In networks using Clique, you must include the address of at least one initial signer in the
51+
genesis file. For this network, we'll use Node-1 as the initial signer. This requires obtaining the
52+
address for Node-1.
53+
54+
To retrieve the address for Node-1, in the `Node-1` directory, use the
55+
[`public-key export-address`](../../Reference/CLI/CLI-Syntax.md#public-key) subcommand to write the
56+
node address to the specified file (`nodeAddress1` in this example).
57+
58+
=== "MacOS"
59+
60+
```bash
61+
besu --data-path=data public-key export-address --to=data/nodeAddress1
62+
```
63+
64+
=== "Windows"
65+
66+
```bash
67+
besu --data-path=data public-key export-address --to=data\nodeAddress1
68+
```
69+
70+
### 3. Create the genesis file
71+
72+
The genesis file defines the genesis block of the blockchain (that is, the start of the
73+
blockchain). The
74+
[Clique genesis file](../../HowTo/Configure/Consensus-Protocols/Clique.md#genesis-file) includes
75+
the address of Node-1 as the initial signer in the `extraData` field.
76+
77+
All nodes in a network must use the same genesis file.
78+
79+
Copy the following genesis definition to a file called `cliqueGenesis.json` and save it in the
80+
`Permissioned-Network` directory:
81+
82+
```json
83+
{
84+
"config":{
85+
"chainId":1981,
86+
"constantinoplefixblock": 0,
87+
"clique":{
88+
"blockperiodseconds":15,
89+
"epochlength":30000
90+
}
91+
},
92+
"coinbase":"0x0000000000000000000000000000000000000000",
93+
"difficulty":"0x1",
94+
95+
"extraData":"0x0000000000000000000000000000000000000000000000000000000000000000<Node 1 Address>0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
96+
"gasLimit":"0xa00000",
97+
"mixHash":"0x0000000000000000000000000000000000000000000000000000000000000000",
98+
"nonce":"0x0",
99+
"timestamp":"0x5c51a607",
100+
"alloc": {
101+
"fe3b557e8fb62b89f4916b721be55ceb828dbd73": {
102+
"privateKey": "8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63",
103+
"comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored",
104+
"balance": "0xad78ebc5ac6200000"
105+
},
106+
"627306090abaB3A6e1400e9345bC60c78a8BEf57": {
107+
"privateKey": "c87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3",
108+
"comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored",
109+
"balance": "90000000000000000000000"
110+
},
111+
"f17f52151EbEF6C7334FAD080c5704D77216b732": {
112+
"privateKey": "ae6ae8e5ccbfb04590405997ee2d52d2b330726137b875053c36d94e974d162f",
113+
"comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored",
114+
"balance": "90000000000000000000000"
115+
}
116+
},
117+
"number":"0x0",
118+
"gasUsed":"0x0",
119+
"parentHash":"0x0000000000000000000000000000000000000000000000000000000000000000"
120+
}
121+
```
122+
123+
### 4. Add the ingress contracts to the genesis file
37124

38125
!!! tip
39126

@@ -42,7 +129,8 @@ For the development server to run the dapp:
42129

43130
Add the Ingress contracts to the genesis file for your network by copying them from
44131
[`genesis.json`](https://github.com/PegaSysEng/permissioning-smart-contracts/blob/master/genesis.json)
45-
in the [`permissioning-smart-contracts` repository](https://github.com/PegaSysEng/permissioning-smart-contracts):
132+
in the [`permissioning-smart-contracts` repository](https://github.com/PegaSysEng/permissioning-smart-contracts) to
133+
the `alloc` section of the contract:
46134

47135
```json
48136
"0x0000000000000000000000000000000000008888": {
@@ -68,13 +156,13 @@ in the [`permissioning-smart-contracts` repository](https://github.com/PegaSysEn
68156

69157
To support the permissioning contracts, ensure your genesis file includes at least the
70158
`constantinopleFixBlock` milestone.
71-
159+
72160
The permissioning contract has multiple interfaces, and each interface maps to a specific
73161
version of the Enterprise [Ethereum Alliance Client Specification](https://entethalliance.org/technical-specifications/).
74162
Ensure that you specify the [permissioning contract interface](../../HowTo/Limit-Access/Specify-Perm-Version.md)
75163
being used when starting Besu.
76164

77-
## Set the environment variables
165+
### 5. Set the environment variables
78166

79167
Create the following environment variables and set to the specified values:
80168

@@ -100,7 +188,7 @@ Create the following environment variables and set to the specified values:
100188
CHAIN_ID=2018
101189
```
102190

103-
## Onchain permissioning command line options
191+
### 6. Start Node-1
104192

105193
!!! important
106194

@@ -111,37 +199,46 @@ Create the following environment variables and set to the specified values:
111199
If your network is not a [free gas network](../../HowTo/Configure/FreeGas.md), the account used
112200
to interact with the permissioning contracts must have a balance.
113201

114-
To enable account and node permissioning, all nodes participating in a permissioned network must
115-
include the command line options:
116-
117-
* [`--permissions-accounts-contract-enabled`](../../Reference/CLI/CLI-Syntax.md#permissions-accounts-contract-enabled)
118-
to enable onchain accounts permissioning
119-
* [`--permissions-accounts-contract-address`](../../Reference/CLI/CLI-Syntax.md#permissions-accounts-contract-address)
120-
set to the address of the Account Ingress contract in the genesis file
121-
(`"0x0000000000000000000000000000000000008888"`)
122-
* [`--permissions-nodes-contract-enabled`](../../Reference/CLI/CLI-Syntax.md#permissions-nodes-contract-enabled)
123-
to enable onchain nodes permissioning
124-
* [`--permissions-nodes-contract-address`](../../Reference/CLI/CLI-Syntax.md#permissions-nodes-contract-address)
125-
set to the address of the Node Ingress contract in the genesis file
126-
(`"0x0000000000000000000000000000000000009999"`). Start your first node with command line options
127-
to enable onchain permissioning and the JSON-RPC HTTP host and port matching environment variable
128-
`BESU_NODE_PERM_ENDPOINT`.
129-
* [`--permissions-nodes-contract-version=2`](../../Reference/CLI/CLI-Syntax.md#permissions-nodes-contract-version)
130-
to set the version of the [permissioning contract interface](../../HowTo/Limit-Access/Specify-Perm-Version.md)
131-
being used.
132-
133-
example command line:
202+
Start the first node with command line options to enable onchain permissioning and the location of
203+
the **data** folder and genesis file:
134204

135205
```cmd
136-
besu --permissions-accounts-contract-enabled --permissions-accounts-contract-address "0x0000000000000000000000000000000000008888" --permissions-nodes-contract-enabled --permissions-nodes-contract-address "0x0000000000000000000000000000000000009999" --genesis-file=genesis.json --rpc-http-enabled --rpc-http-cors-origins="*" --miner-enabled --miner-coinbase=fe3b557e8fb62b89f4916b721be55ceb828dbd73 --permissions-nodes-contract-version=2
206+
besu --data-path=data --genesis-file=../cliqueGenesis.json --permissions-accounts-contract-enabled --permissions-accounts-contract-address "0x0000000000000000000000000000000000008888" --permissions-nodes-contract-enabled --permissions-nodes-contract-address "0x0000000000000000000000000000000000009999" --permissions-nodes-contract-version=2 --rpc-http-enabled --rpc-http-cors-origins="*" --rpc-http-api=ADMIN,ETH,NET,PERM,CLIQUE --host-allowlist="*"
137207
```
138208

139-
## Clone the contracts and install dependencies
209+
In the command line:
210+
211+
* Enable onchain accounts permissioning using the
212+
[`--permissions-accounts-contract-enabled`](../../Reference/CLI/CLI-Syntax.md#permissions-accounts-contract-enabled)
213+
option
214+
* Set the address of the Account Ingress contract in the genesis file using
215+
[`--permissions-accounts-contract-address`](../../Reference/CLI/CLI-Syntax.md#permissions-accounts-contract-address)
216+
* Enable onchain nodes permissioning using the
217+
[`--permissions-nodes-contract-enabled`](../../Reference/CLI/CLI-Syntax.md#permissions-nodes-contract-enabled)
218+
option
219+
* Set the address of the Node Ingress contract in the genesis file using
220+
[`--permissions-nodes-contract-address`](../../Reference/CLI/CLI-Syntax.md#permissions-nodes-contract-address)
221+
* Set the version of the [permissioning contract interface](../../HowTo/Limit-Access/Specify-Perm-Version.md)
222+
being used with the [`--permissions-nodes-contract-version`](../../Reference/CLI/CLI-Syntax.md#permissions-nodes-contract-version)
223+
option
224+
* Enable the JSON-RPC API using the
225+
[`--rpc-http-enabled`](../../Reference/CLI/CLI-Syntax.md#rpc-http-enabled) option
226+
* Enable the ADMIN, ETH, NET, PERM, and CLIQUE APIs using the
227+
[`--rpc-http-api`](../../Reference/CLI/CLI-Syntax.md#rpc-http-api) option
228+
* Allow all-host access to the HTTP JSON-RPC API using the
229+
[`--host-allowlist`](../../Reference/CLI/CLI-Syntax.md#host-allowlist) option
230+
* Allow all-domain access to the node through the HTTP JSON-RPC API using the
231+
[`--rpc-http-cors-origins`](../../Reference/CLI/CLI-Syntax.md#rpc-http-cors-origins) option.
232+
233+
When the node starts, the [enode URL](../../Concepts/Node-Keys.md#enode-url) displays. Copy the
234+
enode URL because it's required when starting Node-2 and Node-3.
235+
236+
### 7. Clone the contracts and install dependencies
140237

141238
1. Clone the `permissioning-smart-contracts` repository:
142239

143240
```bash
144-
git clone https://github.com/PegaSysEng/permissioning-smart-contracts.git
241+
git clone https://github.com/ConsenSys/permissioning-smart-contracts.git
145242
```
146243

147244
1. Change into the `permissioning-smart-contracts` directory and run:
@@ -150,15 +247,18 @@ besu --permissions-accounts-contract-enabled --permissions-accounts-contract-add
150247
yarn install
151248
```
152249

153-
## Build the project
250+
### 8. Build the project
154251

155252
In the `permissioning-smart-contracts` directory, build the project:
156253

157254
```bash
158255
yarn run build
159256
```
160257

161-
## Deploy the contracts
258+
### 9. Deploy the contracts
259+
260+
If using a `.env` file to configure [environment variables](#5-set-the-environment-variables), then
261+
copy the file to the `permissioning-smart-contracts` directory.
162262

163263
In the `permissioning-smart-contracts` directory, deploy the Admin and Rules contracts:
164264

@@ -173,7 +273,7 @@ The migration logs the addresses of the Admin and Rules contracts.
173273

174274
The account that deploys the contracts is automatically an [admin account].
175275

176-
## Start the Web server for the Permissioning Management Dapp
276+
### 9. Start the Permissioning Management Dapp
177277

178278
!!! note
179279

@@ -202,13 +302,51 @@ The migration logs the addresses of the Admin and Rules contracts.
202302

203303
Only an [admin account] can add or remove nodes from the allowlist.
204304

205-
## Add the first node to the allowlist
305+
### 10. Start Node-2
306+
307+
Use the following command to start Node-2:
308+
309+
```cmd
310+
besu --data-path=data --genesis-file=../cliqueGenesis.json --bootnodes=<Node-1 Enode URL> --permissions-accounts-contract-enabled --permissions-accounts-contract-address "0x0000000000000000000000000000000000008888" --permissions-nodes-contract-enabled --permissions-nodes-contract-address "0x0000000000000000000000000000000000009999" --permissions-nodes-contract-version=2 --rpc-http-enabled --rpc-http-cors-origins="*" --rpc-http-api=ADMIN,ETH,NET,PERM,CLIQUE --host-allowlist="*" --p2p-port=30304 --rpc-http-port=8546
311+
```
312+
313+
The command line specifies:
314+
315+
* A Different port to Node-1 for P2P discovery using the
316+
[`--p2p-port`](../../Reference/CLI/CLI-Syntax.md#p2p-port) option.
317+
* A Different port to Node-1 for HTTP JSON-RPC using the
318+
[`--rpc-http-port`](../../Reference/CLI/CLI-Syntax.md#rpc-http-port) option.
319+
* The enode URL of Node-1 using the
320+
[`--bootnodes`](../../Reference/CLI/CLI-Syntax.md#bootnodes) option.
321+
* Other options as for [Node-1](#6-start-node-1)
322+
323+
### 11. Start Node-3
324+
325+
Use the following command to start Node-3:
326+
327+
```cmd
328+
besu --data-path=data --genesis-file=../cliqueGenesis.json --bootnodes=<Node-1 Enode URL> --permissions-accounts-contract-enabled --permissions-accounts-contract-address "0x0000000000000000000000000000000000008888" --permissions-nodes-contract-enabled --permissions-nodes-contract-address "0x0000000000000000000000000000000000009999" --permissions-nodes-contract-version=2 --rpc-http-enabled --rpc-http-cors-origins="*" --rpc-http-api=ADMIN,ETH,NET,PERM,CLIQUE --host-allowlist="*" --p2p-port=30305 --rpc-http-port=8547
329+
```
330+
331+
The command line specifies:
332+
333+
* A Different port to Node-1 and Node-2 for P2P discovery using the
334+
[`--p2p-port`](../../Reference/CLI/CLI-Syntax.md#p2p-port) option.
335+
* A Different port to Node-1 and Node-2 for HTTP JSON-RPC using the
336+
[`--rpc-http-port`](../../Reference/CLI/CLI-Syntax.md#rpc-http-port) option.
337+
* The enode URL of Node-1 using the
338+
[`--bootnodes`](../../Reference/CLI/CLI-Syntax.md#bootnodes) option.
339+
* Other options as for [Node-1](#6-start-node-1)
340+
341+
### 12. Add nodes to the allowlist
206342

207-
The first node must [add itself to the allowlist] before adding other nodes.
343+
In the [Permissioning Management Dapp started earlier](#9-start-the-permissioning-management-dapp)
344+
add [Node-1, Node-2, and Node-3 to the allowlist].
208345

209346
<!-- Links -->
210347
[Start first node with onchain permissioning and the JSON-RPC HTTP service enabled]: #onchain-permissioning-command-line-options
211348
[Clone the permissioning contracts repository and install dependencies]: #clone-the-contracts-and-install-dependencies
212349
[Start the webserver for the Permissioning Management Dapp]: #start-the-webserver-for-the-permissioning-management-dapp
213-
[add itself to the allowlist]: ../../HowTo/Limit-Access/Updating-Permission-Lists.md#update-nodes-allowlist
350+
[Node-1, Node-2, and Node-3 to the allowlist]: ../../HowTo/Limit-Access/Updating-Permission-Lists.md#update-nodes-allowlist
214351
[admin account]: ../../HowTo/Limit-Access/Updating-Permission-Lists.md#update-nodes-allowlist
352+
[Clique Proof-of-Authority (PoA)]: ../../HowTo/Configure/Consensus-Protocols/Clique.md

0 commit comments

Comments
 (0)