Skip to content

Commit

Permalink
Update elections documentation (#2563)
Browse files Browse the repository at this point in the history 
* Improve election docs. Reference relevant BEPs.

* Fix typos and headings (election docs).

* Enumerate supported election types (election docs).

* Clarify the BEP-42 ref (election docs).
  • Loading branch information
@ldmberman @kansi
ldmberman authored and kansi committed Sep 25, 2018
1 parent 24ca0b3 commit 40ea961
Showing 1 changed file with 50 additions and 44 deletions.
94 changes: 50 additions & 44 deletions docs/server/source/server-reference/bigchaindb-cli.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -83,107 +83,113 @@ configuration file as documented under

## bigchaindb election

Manage elections to manage the BigChainDB network. The specifics of the election process are defined in [BEP-18](https://github.com/bigchaindb/BEPs/tree/master/18), please refer it for more details.
Manage elections to govern the BigchainDB network. The specifics of the election process are defined in [BEP-18](https://github.com/bigchaindb/BEPs/tree/master/18).

Election management is broken into several subcommands. Below is the command line syntax for each,
Election management is broken into several subcommands. Below is the command line syntax for each of them.

#### election new
### election new

Create a new election which proposes a change to your BigChainDB network.
Create a new election which proposes a change to the BigchainDB network.

If the command succeeds, it will create an election and return an `election_id`.
If the command succeeds, it will post an election transaction and output `election_id`.

**NOTE**: The election proposal consists of vote tokens allocated to each current validator as per their voting power. Validators then cast their votes to approve the election by spending their vote tokens, (see the documentation on `election approve`).
The election proposal consists of vote tokens allocated to every current validator proportional to his voting power. Validators spend their votes to approve the election using the [election-approve command](#election-approve).

There are multiple types of election, which each take different parameters. Below is a short description of each type of election, as well as their command line syntax and the return value.
Every election has a type. Currently supported types are `upsert-validator` and `chain-migration`. Their transaction operations are `VALIDATOR_ELECTION` and `CHAIN_MIGRATION` accordingly. See below for how to create an election of a particular type.

###### election new upsert-validator
Note that elections can only be proposed and approved by existing validators.

Create an election to add/update/remove a validator from the validator set.
#### election new upsert-validator

Create an election to add, update, or remove a validator.


```bash
$ bigchaindb election new upsert-validator E_PUBKEY E_POWER E_NODE_ID --private-key PATH_TO_YOUR_PRIVATE_KEY
[SUCCESS] Submitted proposal with id: <election_id>
$ bigchaindb election new upsert-validator <public-key> <power> <node-id> --private-key <path-to-the-private-key>
```

- `E_PUBKEY`: Public key of the node to be added/updated/removed.
- `E_POWER`: The new power for the `E_PUBKEY`. NOTE, if power is set to `0` then `E_PUBKEY` will be removed from the validator set when the election concludes.
- `E_NODE_ID`: Node id of `E_PUBKEY`. The node operator of `E_PUBKEY` can generate the node id via `tendermint show_node_id`.
- `--private-key`: The path to Tendermint's private key which can be generally found at `/home/user/.tendermint/config/priv_validator.json`.

For example, to add a new validator, provide the public key and node id for some node not already in the validator set, along with whatever voting power you'd like them to have. To remove an existing validator, provide their public key and node id, and set `E_POWER` to `0`. Please note that the private key provided here is of the node which is generating this election i.e.

- `<public-key>` is the public key of the node to be added/updated/removed. The encoding and type of the key have to match those specified in `genesis.json` in the supported Tendermint version.
- `<power>` is the new power for the validator. To remove the validator, set the power to `0`.
- `<node-id>` is the node identifier from Tendermint. A node operator can learn his node identifier by executing `tendermint show_node_id`.
- `<path-to-the-private-key>` is the path to the private key of the validator who proposes the election. Tendermint places it at `.tendermint/config/priv_validator.json`.

NOTE: A change to the validator set can only be proposed by one of the exisitng validators.

Example usage,
Example:

```bash
$ bigchaindb election new upsert-validator HHG0IQRybpT6nJMIWWFWhMczCLHt6xcm7eP52GnGuPY= 1 fb7140f03a4ffad899fabbbf655b97e0321add66 --private-key /home/user/.tendermint/config/priv_validator.json
[SUCCESS] Submitted proposal with id: 04a067582cf03eba2b53b82e4adb5ece424474cbd4f7183780855a93ac5e3caa
```

A successful execution of the above command **doesn't** imply that the validator set will be immediately updated but rather it means the proposal has been succcessfully accepted by the network. Once the `election_id` has been generated the node operator should share this `election_id` with other validators in the network and urge them to approve the proposal. Note that the node operator should themsleves also approve the proposal.
A successful execution of the above command does not imply the validator set has been updated but rather the proposal has been accepted by the network.
Once `election_id` has been generated, the proposer should share it with other validators of the network (e.g. via email) and ask them to approve the proposal.

Note that election proposers do not automatically approve elections by proposing them.

For more details about how validator set changes work, refer to [BEP-21](https://github.com/bigchaindb/BEPs/tree/master/21).

###### election new migration
#### election new chain-migration

Create an election to halt block production, to allow for a version change across breaking changes.
Create an election to halt block production, to coordinate on making a Tendermint upgrade with a backwards-incompatible chain.


```bash
$ bigchaindb election new migration --private-key PATH_TO_YOUR_PRIVATE_KEY
[SUCCESS] Submitted proposal with id: <election_id>
$ bigchaindb election new chain-migration --private-key <path-to-the-private-key>
```

- `--private-key`: The path to Tendermint's private key which can be generally found at `/home/user/.tendermint/config/priv_validator.json`.
- `<path-to-the-private-key>` is the path to the private key of the validator who proposes the election. Tendermint places it at `.tendermint/config/priv_validator.json`.


Example usage,
Example:

```bash
$ bigchaindb election new migration --private-key /home/user/.tendermint/config/priv_validator.json
[SUCCESS] Submitted proposal with id: 04a067582cf03eba2b53b82e4adb5ece424474cbd4f7183780855a93ac5e3caa
```

**NOTE** `migration` elections will halt block production at whichever blockheight they are approved. Once the election is concluded, the validators will need to restart their systems with a new `chain_id` to resume normal operations.
Concluded chain migration elections halt block production at whichever block height they are approved.
Afterwards, validators are supposed to upgrade Tendermint, set new `chain_id`, `app_hash`, and `validators` (to learn these values, use the [election show](#election-show) command) in `genesis.json`, make and save a MongoDB dump, and restart the system.


#### election approve
For more details about how chain migrations work, refer to [Type 3 scenarios in BEP-42](https://github.com/bigchaindb/BEPs/tree/master/42).

Approve an election by voting for it. The proposal generated by executing `bigchaindb election new ...` can be approved by the validators using this command. The validator who is approving the proposal will spend all their votes i.e. if the validator has a network power of `10` then they will cast `10` votes for the proposal.
### election approve

Approve an election by voting for it. The command places a `VOTE` transaction, spending all of the validator's vote tokens to the election address.

Below is the command line syntax and the return value,

```bash
$ bigchaindb election approve <election_id> --private-key PATH_TO_YOUR_PRIVATE_KEY
[SUCCESS] Your vote has been submitted
$ bigchaindb election approve <election-id> --private-key <path-to-the-private-key>
```

- `election_id` is the transaction id of the election the approval should be given for.
- `--private-key` should be the path to Tendermint's private key which can be generally found at `/home/user/.tendermint/config/priv_validator.json`.
- `election-id` is the election identifier the approval is given for.
- `<path-to-the-private-key>` is the path to the private key of the validator who votes for the election. Tendermint places it at `.tendermint/config/priv_validator.json`.

Example usage,
Example:
```bash
$ bigchaindb election approve 04a067582cf03eba2b53b82e4adb5ece424474cbd4f7183780855a93ac5e3caa --private-key /home/user/.tendermint/config/priv_validator.json
[SUCCESS] Your vote has been submitted
```

If the command succeeds a message will be returned stating that the vote was submitted successfully. Once a proposal has been approved by sufficent validators (more than `2/3` of the total voting power) then the proposed change is applied to the network. For example, consider a network wherein the total power is `90` then the proposed changed is applied only after `60` (`2/3 * 90`) have been received.
Once a proposal has been approved by the sufficient amount of validators (contributing more than `2/3` of the total voting power), the proposed change is applied to the network.

#### election show
### election show

Retrieves information about an election initiated by `election new`.
Retrieves the information about elections.

Below is the command line syntax and the return value,

```bash
$ bigchaindb election show ELECTION_ID
<election_data>
$ bigchaindb election show <election-id>

status=<status>
```

The election data is the same set of arguments used in the `election new` command that originally triggered the election. `status` takes three possible values, `ongoing`, if the election has not yet reached a 2/3 majority, `concluded`, if the election reached the 2/3 majority needed to pass, or `inconclusive`, if the validator set changed while the election was in process, rendering it undecidable.
`status` has three possible values:

- `ongoing`, if the election can be concluded but has not yet collected enough votes,
- `concluded`, if the election has been concluded,
- `inconclusive`, if the validator set changed while the election was in process, rendering it undecidable.

After a chain migration is concluded, the `show` command also outputs `chain_id`, `app_hash`, and `validators` for `genesis.json` of the new chain.

## bigchaindb tendermint-version

Expand Down

0 comments on commit 40ea961

Please sign in to comment.