[PAN-2881] [PAN-2885] Updated onchain permissioning to include accounts and dapp #1652
Conversation
MadelineMurray
changed the title
| # Onchain Permissioning | ||
|
|
||
| Onchain permissioning uses smart contracts to store and maintain the node, account, and admin account whitelists. | ||
| Using onchain permissioning enables all nodes to read the whitelists from one location. |
There was a problem hiding this comment.
maybe 'source' is better than 'location'?
|
|
||
| * 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 |
There was a problem hiding this comment.
| * Admin - stores the list of admin accounts and admin list operations (for example, add and remove) There is | |
| * Admin - stores the list of admin accounts and admin list operations (for example, add and remove). There is |
missing a full stop
|
|
||
| ## Pre-requisites | ||
|
|
||
| For the first node and nodes with an admin account: |
There was a problem hiding this comment.
| For the first node and nodes with an admin account: | |
| For the first node, and other nodes with an admin account: |
There was a problem hiding this comment.
There are a couple of things here that I don't know if we should care (might be nitpicking)
- The concept "nodes with an admin account" doesn't make sense to me... The account doesn't belong to one node.
- You don't need to run the scripts and the dapp in the same server that you are running the node.
I think we need to make clear that this is the way to bootstrap the network. Hence why you need one dapp running.
There was a problem hiding this comment.
I think we can remove the whole If nodes are going to maintain whitelists part.
There was a problem hiding this comment.
Have updated throughout to make clearer.
|
|
||
| For the first node and nodes with an admin account: | ||
|
|
||
| * [NodeJS](https://nodejs.org/en/) v8.9.4 or later QUESTION: confirm |
There was a problem hiding this comment.
yes we still need this. Chris says 10 or later ideally
There was a problem hiding this comment.
10.16.0 or greater would be good. This is the latest LTS version.
| ## Deploy Contracts | ||
|
|
||
| !!! important | ||
| Only the first node deploys the admin and rules contracts. Subsequent nodes do not migrate the contracts. |
There was a problem hiding this comment.
| Only the first node deploys the admin and rules contracts. Subsequent nodes do not migrate the contracts. | |
| Only the first node deploys the admin and rules contracts. Subsequent nodes do not deploy the contracts. |
There was a problem hiding this comment.
Removed this part due to other changes
|
|
||
| 1. Ensure MetaMask is connected to your local node (by default `http://localhost:8545`). | ||
|
|
||
| A MeteMask notification is displayed requesting permission for Pantheon Permissioning to |
There was a problem hiding this comment.
| A MeteMask notification is displayed requesting permission for Pantheon Permissioning to | |
| A MetaMask notification is displayed requesting permission for Pantheon Permissioning to |
| peer discovery is run on node startup. | ||
|
|
||
| ## Update Accounts or Admin Accounts Whitelists | ||
|
|
There was a problem hiding this comment.
would it make more sense to describe the process for updating account whitelist, and then say "for admin accounts it is the same" rather than jamming them both together?
| permissions-accounts-contract-enabled=true | ||
| ``` | ||
|
|
||
| Enables contract-based [onchain accounts permissioning](../Permissions/Onchain-Permissioning/Onchain-Permissioning.md). Default is `false`. |
There was a problem hiding this comment.
| Enables contract-based [onchain accounts permissioning](../Permissions/Onchain-Permissioning/Onchain-Permissioning.md). Default is `false`. | |
| Enables contract-based [onchain account permissioning](../Permissions/Onchain-Permissioning/Onchain-Permissioning.md). Default is `false`. |
| permissions-accounts-contract-address=xyz | ||
| ``` | ||
|
|
||
| Specifies the contract address for [onchain accounts permissioning](../Permissions/Onchain-Permissioning/Onchain-Permissioning.md). |
There was a problem hiding this comment.
| Specifies the contract address for [onchain accounts permissioning](../Permissions/Onchain-Permissioning/Onchain-Permissioning.md). | |
| Specifies the contract address for [onchain account permissioning](../Permissions/Onchain-Permissioning/Onchain-Permissioning.md). |
There was a problem hiding this comment.
Not sure which way you want to go but further down you have [onchain node permissioning]
docs/Resources/Resources.md
Outdated
| @@ -17,6 +17,8 @@ description: Pantheon resources including blog posts, webinars, and meetup recor | |||
|
|
|||
| ## Webinars | |||
|
|
|||
| [Permissioning in Blockcahin: A Technical Look at Benefits and Best Practices](https://pegasys.wistia.com/medias/3px9eo2sf5) | |||
There was a problem hiding this comment.
| [Permissioning in Blockcahin: A Technical Look at Benefits and Best Practices](https://pegasys.wistia.com/medias/3px9eo2sf5) | |
| [Permissioning in Blockchain: A Technical Look at Benefits and Best Practices](https://pegasys.wistia.com/medias/3px9eo2sf5) |
mkdocs.yml
Outdated
| - Local Permissioning: Permissions/Local-Permissioning.md | ||
| - Onchain Permissioning: | ||
| - Overview: Permissions/Onchain-Permissioning/Onchain-Permissioning.md | ||
| - Using Onchain Permissions: Permissions/Onchain-Permissioning/Using-Onchain-Permissioning.md |
There was a problem hiding this comment.
| - Using Onchain Permissions: Permissions/Onchain-Permissioning/Using-Onchain-Permissioning.md | |
| - Using Onchain Permissions: Permissioning/Onchain-Permissioning/Using-Onchain-Permissioning.md |
There was a problem hiding this comment.
or maybe "Getting Started" or "Tutorial" is better?
There was a problem hiding this comment.
Changed to Getting Started
|
|
||
| The permissioning smart contracts are provided in the [PegaSysEng/permissioning-smart-contracts](https://github.com/PegaSysEng/permissioning-smart-contracts) repository: | ||
|
|
||
| * Ingress contracts for nodes and accounts - simple contracts functioning as gateways to the Admin, Node Rules, |
There was a problem hiding this comment.
I wouldn't use the words simple contract here...
Maybe:
proxy contracts that defer the permissioning logic to the Node and Account rules contracts.
btw: the ingress contract doen't know anything about the admins :)
|
|
||
| * [Nodes](Using-Onchain-Permissioning.md#update-nodes-whitelist) can participate in the network | ||
|
|
||
| * [Admin Accounts](Using-Onchain-Permissioning.md#update-accounts-or-admin-accounts-whitelists) |
There was a problem hiding this comment.
Can we use Admins instead of Admin Accounts? we can mention the accounts in the description
(Ethereum accounts that can update the accounts and nodes whitelists)
|
|
||
| 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 are applied and connections to bootnodes are dropped if not permitted by node | ||
| permissions. |
There was a problem hiding this comment.
and connections to bootnodes are dropped if not permitted by node permissions
Feels like too low level to be here. I would've ended with Once in sync, the permissioning rules in the Account Rules and Node Rules smart contracts are applied.
|
|
||
| If a sychronized node loses all peer connections (that is, it has 0 peers), it reconnects to the bootnodes regardless of node | ||
| permissions. When the node has connected to 1 or more non-bootnodes, connections to bootnodes are dropped if not permitted by node | ||
| permissions. |
There was a problem hiding this comment.
Again, I would avoid adding too much information about the implementation. We could just say that if we loose all our peers, we reach out to our bootnodes.
|
|
||
| * `NODE_INGRESS_CONTRACT_ADDRESS` - address of the Node Ingress contract in the genesis file. | ||
|
|
||
| * `PANTHEON_NODE_PERM_ENDPOINT` - required only if your node is not using the default JSON-RPC host and port (`http://127.0.0.1:8545`). |
There was a problem hiding this comment.
We should probably make it clear that this needs to point to the node that we will deploy the contracts to. During the bootstrap process, this is the first node of the network.
| For the first node (that is, the node that will deploy the contracts), create the following environment variables | ||
| and set to the specified values: | ||
|
|
||
| * `PANTHEON_NODE_PERM_ACCOUNT` - address of account used to interact with the permissioning contracts. |
There was a problem hiding this comment.
Maybe we should mention that this is the account that will deploy the contracts and become the first admin of the network.
| !!! note | ||
| Only [admin accounts](#update-accounts-or-admin-accounts-whitelists) can add or remove nodes from the whitelist. | ||
|
|
||
| The first node (that is, the node that deployed the permissioning contracts) must add itself to the whitelist before |
There was a problem hiding this comment.
This is not true. But we should keep it to make it sound simple :)
What needs to be in the whitelist are all nodes allowed to participate in the network. It is not a requirement that the "first" node has to be in the whitelist (only if you want this node to join the network - probably 99% of the time)
There was a problem hiding this comment.
Good point but leaving as is to keep things simple.
|
|
||
| # Onchain Permissioning | ||
|
|
||
| Onchain permissioning uses smart contracts to store and maintain the node, account, and admin account whitelists. |
There was a problem hiding this comment.
The second 'account' makes this sentence confusing. What about:
Onchain permissioning uses smart contracts to store and maintain the node, account, and admin whitelists.
There was a problem hiding this comment.
I agree - we've stopped using "Admin account" elsewhere, so this suggestion keeps things consistent. 👍
| # Onchain Permissioning | ||
|
|
||
| Onchain permissioning uses smart contracts to store and maintain the node, account, and admin account whitelists. | ||
| Using onchain permissioning enables all nodes to read the whitelists from one source. |
There was a problem hiding this comment.
I'd replace "read the whitelists from one source." with:
"... read the permissioning rules from a single source of truth, the blockchain."
| The permissioning smart contracts are provided in the [PegaSysEng/permissioning-smart-contracts](https://github.com/PegaSysEng/permissioning-smart-contracts) repository: | ||
|
|
||
| * Ingress contracts for nodes and accounts - proxy contracts that defer the permissioning logic to the | ||
| Node Rules and Account Rules contracts. The Ingress contracts are deployed to static addresses. |
There was a problem hiding this comment.
Should we mention that they are in the genesis file?
| @@ -16,13 +16,10 @@ A permissioned network allows only specified nodes and accounts to participate b | |||
|
|
|||
| ## Local | |||
|
|
|||
| [Local permissioning](Local-Permissioning.md) are specified at the node level. Each node in the network has a [permissions configuration file](#permissions-configuration-file). | |||
| [Local permissioning](Local-Permissioning.md) are specified at the node level. Each node in the network has a [permissions configuration file](Local-Permissioning.md#permissions-configuration-file). | |||
There was a problem hiding this comment.
Local permissioning is specified
| Updates to local permissioning must be made to the configuration file for each node. | ||
|
|
||
| ## Onchain | ||
|
|
||
| [Onchain permissioning](Onchain-Permissioning.md) is specified in a smart contract on the network. Specifying permissioning onchain | ||
| [Onchain permissioning](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 in one location. |
There was a problem hiding this comment.
"...enables all nodes to read and update permissioning configuration at a single location"
|
|
||
| # Onchain Permissioning | ||
|
|
||
| Onchain permissioning uses smart contracts to store and maintain the node, account, and admin account whitelists. |
There was a problem hiding this comment.
I agree - we've stopped using "Admin account" elsewhere, so this suggestion keeps things consistent. 👍
|
|
||
| !!! tip | ||
| Before v1.2, we provided a [management interface using Truffle](https://docs.pantheon.pegasys.tech/en/1.1.4/Permissions/Onchain-Permissioning/). | ||
| The management interface using Truffle is deprecated and we recommend using the Dapp for an improved user experience. |
There was a problem hiding this comment.
Can we add emphasis to deprecated?
There was a problem hiding this comment.
We don't typically add emphasis unless it's a button, tab, etc. Too much emphasis makes the text harder to scan/read.
|
|
||
| # Getting Started with Onchain Permissioning | ||
|
|
||
| The following steps describe bootstrapping a permissioned network using a Pantheon node and a development server |
There was a problem hiding this comment.
Feels a bit longwinded. Does something like "The following steps describe bootstrapping a local permissioned network using a Pantheon node and a development server to run the Permissioning Management Dapp." feel better?
|
|
||
| ## Update Admins | ||
|
|
||
| Admins accounts are added or removed in the same way as accounts except on the _Admin Accounts_ tab. |
There was a problem hiding this comment.
Admins accounts -> Admins ?
"...in the Admin Accounts tab" ?
MadelineMurray
changed the title
Updated onchain permissioning to include accounts and dapp