diff --git a/docs/Concepts/Permissioning/Onchain-Permissioning.md b/docs/Concepts/Permissioning/Onchain-Permissioning.md index 4ea6ef9d8e4..fb2ec36e299 100644 --- a/docs/Concepts/Permissioning/Onchain-Permissioning.md +++ b/docs/Concepts/Permissioning/Onchain-Permissioning.md @@ -1,65 +1,75 @@ -description: Onchain Permissioning +description: Onchain permissioning -# Onchain Permissioning +# Onchain permissioning -Onchain permissioning uses smart contracts to store and maintain the node, account, and admin whitelists. -Using onchain permissioning enables all nodes to read the whitelists from a single source, the blockchain. +Onchain permissioning uses smart contracts to store and administer the node, account, and admin +whitelists. Using onchain permissioning enables all nodes to read the whitelists from a single +source, the blockchain. -!!! note - The permissioning smart contracts and Permissioning Management Dapp are a separate product to Hyperledger Besu - and are provided in the [PegaSysEng/permissioning-smart-contracts](https://github.com/PegaSysEng/permissioning-smart-contracts) repository. +!!! note - Custom smart contracts and dapps can be implemented to work with onchain permissioning. + The permissioning smart contracts and Permissioning Management Dapp are a separate product to + Hyperledger Besu, located in the [PegaSysEng/permissioning-smart-contracts] repository. -## Permissioning Contracts + Custom smart contracts and dapps can be implemented to work with onchain permissioning. -The permissioning smart contracts provided in the [PegaSysEng/permissioning-smart-contracts](https://github.com/PegaSysEng/permissioning-smart-contracts) -repository are: +## Permissioning contracts -* Ingress contracts for nodes and accounts - proxy contracts defined in the genesis file that defer the permissioning logic to the -Node Rules and Account Rules contracts. The Ingress contracts are deployed to static addresses. +The permissioning smart contracts provided in the [PegaSysEng/permissioning-smart-contracts] +repository are: -* Node Rules - stores the node whitelist and node whitelist operations (for example, add and remove). +* Ingress contracts for nodes and accounts - proxy contracts defined in the genesis file to defer +the permissioning logic to the Node Rules and Account Rules contracts. The Ingress contracts deploy +to static addresses. +* Node Rules - stores the node whitelist and node whitelist operations (for example, add and +remove). +* Account Rules - stores the accounts whitelist and account whitelist operations (for example, add +and remove). +* Admin - stores the list of admin accounts and admin list operations (for example, add and +remove). There is one list of admin accounts for node and accounts. -* Account Rules - stores the accounts whitelist and account whitelist operations (for example, add and remove). +## Permissioning management Dapp -* Admin - stores the list of admin accounts and admin list operations (for example, add and remove). There is -one list of admin accounts for node and accounts. +The [Permissioning Management Dapp] provides view and maintain access to the whitelists. -## Permissioning Management Dapp +!!! tip -The [Permissioning Management Dapp](../../Tutorials/Permissioning/Getting-Started-Onchain-Permissioning.md) is provided to view -and maintain the whitelists. + Before v1.2, the management interface used Truffle, now deprecated. For an improved user + experience, use the Dapp. -!!! tip - Before v1.2, we provided a management interface using Truffle. - The management interface using Truffle is deprecated and we recommend using the Dapp for an improved user experience. +### Whitelists -### Whitelists +Permissioning implements three whitelists: -Permissioning implements three whitelists: +* Accounts, which can submit transactions to the network. +* Nodes, which can participate in the network. +* Admins, which are accounts that can update the accounts and nodes whitelists. -* Accounts can submit transactions to the network +!!! caution "Using account permissioning and privacy" -* Nodes can participate in the network + Account permissioning is incompatible with + [random key signing](../../HowTo/Use-Privacy/Sign-Privacy-Marker-Transactions.md) for + [privacy marker transactions](../Privacy/Private-Transaction-Processing.md). -* Admins are accounts that can update the accounts and nodes whitelists - -!!! caution "Using account permissioning and privacy" - Account permissioning cannot be used with [random key signing](../../HowTo/Use-Privacy/Sign-Privacy-Marker-Transactions.md) - for [privacy marker transactions](../Privacy/Private-Transaction-Processing.md). - - If using account permissioning and privacy, a signing key must be specified using the [`--privacy-marker-transaction-signing-key-file`](../../Reference/CLI/CLI-Syntax.md#privacy-marker-transaction-signing-key-file) - command line option and the signing key included in the accounts whitelist. + If using account permissioning and privacy, a signing key must be specified using the + [`--privacy-marker-transaction-signing-key-file`] command line option and the signing key + included in the accounts whitelist. ## Bootnodes -When a node is added to the network, it connects to the bootnodes until it synchronizes to the chain head regardless of -node permissions. Once in sync, the permissioning rules in the Account Rules and Node Rules smart contracts are applied. +When a node is added to the network, the node connects to the bootnodes until it synchronizes to the chain +head, regardless of node permissions. After synchronization, the Account Rules and Node Rules smart +contracts apply the permissioning rules. -If a sychronized node loses all peer connections (that is, it has 0 peers), it reconnects to the bootnodes to -rediscover peers. +If a sychronized node loses all peer connections (that is, it has zero peers), it reconnects to the +bootnodes to rediscover peers. !!! important - All bootnodes must be on the nodes whitelist. \ No newline at end of file + + All bootnodes must be on the nodes whitelist. + + +[PegaSysEng/permissioning-smart-contracts]: https://github.com/PegaSysEng/permissioning-smart-contracts +[Permissioning Management Dapp]: ../../Tutorials/Permissioning/Getting-Started-Onchain-Permissioning.md +[`--privacy-marker-transaction-signing-key-file`]: ../../Reference/CLI/CLI-Syntax.md#privacy-marker-transaction-signing-key-file \ No newline at end of file diff --git a/docs/Concepts/Permissioning/Permissioning-Overview.md b/docs/Concepts/Permissioning/Permissioning-Overview.md index 6437a6a4e7b..2596b246e8d 100644 --- a/docs/Concepts/Permissioning/Permissioning-Overview.md +++ b/docs/Concepts/Permissioning/Permissioning-Overview.md @@ -1,62 +1,68 @@ -description: Besu Permissioning feature +description: Besu permissioning feature -# Permissioning +# Permissioning -A permissioned network allows only specified nodes and accounts to participate by enabling node permissioning and/or -account permissioning on the network. +A permissioned network permits only specified nodes and accounts to participate by enabling +node permissioning and account permissioning on the network. !!! important "Permissioning is not Privacy" - In peer-to-peer networks, node permissioning enforces rules on nodes you control. + + In peer-to-peer networks, node permissioning enforces rules on nodes you control. - Permissioning requires a distributed network of trust across the network where participants agree to - follow the rules. A single bad actor can decide not to follow the rules. Nodes can take action - to prevent the bad actor adding to the chain but they cannot prevent the bad actor from allowing access to the chain. + Permissioning requires a distributed network of trust across the network where participants + agree to follow the rules. One bad actor can decide not to follow the rules. Nodes can take + action to prevent the bad actor adding to the chain but they cannot prevent the bad actor from + allowing access to the chain. Besu also implements [privacy](../Privacy/Privacy-Overview.md). -## Node Permissioning +## Node permissioning -Use node permissioning to restrict access to known participants only. +Use node permissioning to restrict access to known participants only. ![Node Permissioning](../../images/node-permissioning-bad-actor.png) -## Account Permissioning +## Account permissioning -Use account permissioning: +Use account permissioning to: * Enforce onboarding or identity requirements * Suspend accounts -* Blacklist broken contracts -* Restrict the actions an account can perform +* Blacklist broken contracts +* Restrict the actions an account can perform. ![Account Permissioning](../../images/account-permissioning.png) -## Specifying Permissioning +## Specifying permissioning -Permissioning is [local](#local) or [onchain](#onchain). +You can specify permissioning [locally](#local) or [onchain](#onchain). -### Local +### Local -[Local permissioning](../../HowTo/Limit-Access/Local-Permissioning.md) is specified at the node level. Each node in the network has a [permissions configuration file](#permissions-configuration-file). +[Local permissioning](../../HowTo/Limit-Access/Local-Permissioning.md) works at the node level. +Each node in the network has a [permissions configuration file](#permissions-configuration-file). -Local permissioning affects your node but not the rest of the network. Use local permissioning to restrict use -of your node (that is, the resources under your control). For example, customers that can access your node. +Local permissioning affects your node but not the rest of the network. Use local permissioning to +restrict use of your node (that is, the resources under your control). For example, customers able +to access your node. -Local permissioning doesn't require co-ordination with the rest of the network and you can act immediately to -protect your node. Your rules are not enforced in blocks produced by other nodes. +Local permissioning does not require co-ordination with the rest of the network and you can act +immediately to protect your node. Your rules are not enforced in blocks produced by other nodes. -### Onchain +### Onchain -[Onchain permissioning](Onchain-Permissioning.md) is specified in a smart contract on the network. Specifying permissioning onchain -enables all nodes to read and update permissioning configuration from one location. +[Onchain permissioning](Onchain-Permissioning.md) works through a smart contract on the network. +Specifying permissioning onchain enables all nodes to read and update permissioning configuration +from one location. -Onchain permissioning requires co-ordination to update rules. The network may not be able to act immediately -(for example, the smart contract may enforce a minimum of votes before changing permissioning rules). +Onchain permissioning requires co-ordination to update the rules. The network might not be able to +act immediately (for example, the smart contract might enforce a minimum of number of votes before +changing permissioning rules). -When onchain permissioning is updated, the update is applied across the network and new blocks abide by the updated rules. -For example, blocked accounts can no longer add transactions to the chain. +When you update onchain permissioning, the update applies across the network and new blocks abide +by the updated rules. For example, blocked accounts can no longer add transactions to the chain. -The diagram illustrates when local and onchain permissioning rules are applied. +The following diagram illustrates applying local and onchain permissioning rules. -![Permissioning Flow](../../images/PermissioningFlow.png) \ No newline at end of file +![Permissioning Flow](../../images/PermissioningFlow.png) \ No newline at end of file