diff --git a/bigchaindb/commands/bigchaindb.py b/bigchaindb/commands/bigchaindb.py index 9bca14e8..93abfdd1 100644 --- a/bigchaindb/commands/bigchaindb.py +++ b/bigchaindb/commands/bigchaindb.py @@ -121,8 +121,7 @@ def run_upsert_validator_new(args, bigchain): 'sk': the path to the private key of the node calling the election (str) } :param bigchain: an instance of BigchainDB - :return: election_id (tx_id) - :raises: OperationError if the write transaction fails for any reason + :return: election_id or `False` in case of failure """ new_validator = { @@ -163,8 +162,7 @@ def run_upsert_validator_approve(args, bigchain): 'sk': the path to the private key of the signer (str) } :param bigchain: an instance of BigchainDB - :return: a success message - :raises: OperationError if the write transaction fails for any reason + :return: success log message or `False` in case of error """ key = load_node_key(args.sk) diff --git a/docs/server/source/server-reference/bigchaindb-cli.md b/docs/server/source/server-reference/bigchaindb-cli.md index 49a16f96..813234d9 100644 --- a/docs/server/source/server-reference/bigchaindb-cli.md +++ b/docs/server/source/server-reference/bigchaindb-cli.md @@ -83,44 +83,59 @@ configuration file as documented under ## bigchaindb upsert-validator -**This is an experimental feature. Users are advised not to use it in production.** - - -Manage elections to add, update, or remove a validator from the validators set of the local node. The upsert-validator subcommands implement [BEP-21](https://github.com/bigchaindb/BEPs/tree/master/21). Check it out if you need more details on how this is orchestrated. +Manage elections to add, update, or remove a validator from the validators set. The upsert-validator subcommands implement [BEP-21](https://github.com/bigchaindb/BEPs/tree/master/21), please refer the BEP for more details. Election management is broken into several subcommands. Below is the command line syntax for each, #### upsert-validator new -Calls a new election, proposing a change to the validator set. +Create a new election which proposes a change to the validator set. An election can be used to add/update/remove a validator from the validator set. Below is the command line syntax and the return value, ```bash $ bigchaindb upsert-validator new E_PUBKEY E_POWER E_NODE_ID --private-key PATH_TO_YOUR_PRIVATE_KEY - +[SUCCESS] Submitted proposal with id: ``` -Here, `E_PUBKEY`, `E_POWER`, and `E_NODE_ID` are the public key, proposed power, and node id of the validator being voted on. `--private-key` should be the path to wherever the private key for your validator node is stored, (*not* the private key itself.). 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`. +- `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. + + +NOTE: A change to the validator set can only be proposed by one of the exisitng validators. Example usage, ```bash $ bigchaindb upsert-validator new HHG0IQRybpT6nJMIWWFWhMczCLHt6xcm7eP52GnGuPY= 1 fb7140f03a4ffad899fabbbf655b97e0321add66 --private-key /home/user/.tendermint/config/priv_validator.json +[SUCCESS] Submitted proposal with id: 04a067582cf03eba2b53b82e4adb5ece424474cbd4f7183780855a93ac5e3caa ``` -If the command succeeds, it will create an election and return an `election_id`. Elections consist of one vote token per voting power, issued to the members of the validator set. Validators can cast their votes to approve the change to the validator set by spending their vote tokens. The status of the election can be monitored by providing the `election_id` to the `show` subcommand. +If the command succeeds, it will create an election and return an `election_id`. 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. + + +**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 change to the validator set by spending their vote tokens. + #### upsert-validator approve - Approve an election by voting for it. - Below is the command line syntax and the return value, + +Approve an election by voting for it. The propsal generated by executing `bigchaindb upsert-valdiator approve ...` can 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.` +Below is the command line syntax and the return value, + ```bash $ bigchaindb upsert-validator approve --private-key PATH_TO_YOUR_PRIVATE_KEY +[SUCCESS] Your vote has been submitted ``` - Here, `` 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 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`. Example usage, ```bash $ bigchaindb upsert-validator 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, that the vote was submitted successfully. + +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 applied only after `60` (`2/3 * 90`) have been received.