Problem: Command line options for upsert-validator can be generalized to manage any type of election

Solution: Refactored the CLI to manage generalized elections

bigchaindb/commands/bigchaindb.py

@@ -28,7 +28,8 @@ from bigchaindb.commands import utils
 from bigchaindb.commands.utils import (configure_bigchaindb,
                                        input_on_stderr)
 from bigchaindb.log import setup_logging
-from bigchaindb.tendermint_utils import public_key_from_base64, public_key_to_base64
+from bigchaindb.tendermint_utils import public_key_from_base64
+from bigchaindb.commands.election_types import elections
 
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
@@ -101,16 +102,20 @@ def run_configure(args):
 
 
 @configure_bigchaindb
-def run_upsert_validator(args):
+def run_election(args):
-    """Initiate and manage elections to change the validator set"""
+    """Initiate and manage elections"""
 
     b = BigchainDB()
 
     # Call the function specified by args.action, as defined above
-    globals()[f'run_upsert_validator_{args.action}'](args, b)
+    globals()[f'run_election_{args.action}'](args, b)
 
 
-def run_upsert_validator_new(args, bigchain):
+def run_election_new(args, bigchain):
+    globals()[f'run_election_new_{args.election_type}'](args, bigchain)
+
+
+def run_election_new_upsert_validator(args, bigchain):
     """Initiates an election to add/update/remove a validator to an existing BigchainDB network
 
     :param args: dict
@@ -153,8 +158,8 @@ def run_upsert_validator_new(args, bigchain):
         return False
 
 
-def run_upsert_validator_approve(args, bigchain):
+def run_election_approve(args, bigchain):
-    """Approve an election to add/update/remove a validator to an existing BigchainDB network
+    """Approve an election
 
     :param args: dict
         args = {
@@ -191,8 +196,8 @@ def run_upsert_validator_approve(args, bigchain):
         return False
 
 
-def run_upsert_validator_show(args, bigchain):
+def run_election_show(args, bigchain):
-    """Retrieves information about an upsert-validator election
+    """Retrieves information about an election
 
     :param args: dict
         args = {
@@ -206,14 +211,7 @@ def run_upsert_validator_show(args, bigchain):
         logger.error(f'No election found with election_id {args.election_id}')
         return
 
-    new_validator = election.asset['data']
+    response = election.show_election(bigchain)
-
-    public_key = public_key_to_base64(new_validator['public_key'])
-    power = new_validator['power']
-    node_id = new_validator['node_id']
-    status = election.get_status(bigchain)
-
-    response = f'public_key={public_key}\npower={power}\nnode_id={node_id}\nstatus={status}'
 
     logger.info(response)
 
@@ -316,32 +314,29 @@ def create_parser():
                                help='The backend to use. It can only be '
                                '"localmongodb", currently.')
 
-    # parser for managing validator elections
+    # parser for managing elections
-    validator_parser = subparsers.add_parser('upsert-validator',
+    election_parser = subparsers.add_parser('election',
                                             help='Add/update/delete a validator.')
 
-    validator_subparser = validator_parser.add_subparsers(title='Action',
+    election_subparser = election_parser.add_subparsers(title='Action',
                                                         dest='action')
 
-    new_election_parser = validator_subparser.add_parser('new',
+    new_election_parser = election_subparser.add_parser('new',
                                                         help='Calls a new election.')
 
-    new_election_parser.add_argument('public_key',
+    new_election_subparser = new_election_parser.add_subparsers(title='Election_Type',
-                                     help='Public key of the validator to be added/updated/removed.')
+                                                                dest='election_type')
 
-    new_election_parser.add_argument('power',
+    # Parser factory for each type of new election, so we get a bunch of commands that look like this:
-                                     type=int,
+    # election new <some_election_type> <args>...
-                                     help='The proposed power for the validator. '
+    for name, data in elections.items():
-                                          'Setting to 0 will remove the validator.')
+        help = data['help']
+        args = data['args']
+        generic_parser = new_election_subparser.add_parser(name, help=help)
+        for arg, kwargs in args.items():
+            generic_parser.add_argument(arg, **kwargs)
 
-    new_election_parser.add_argument('node_id',
+    approve_election_parser = election_subparser.add_parser('approve',
-                                     help='The node_id of the validator.')
-
-    new_election_parser.add_argument('--private-key',
-                                     dest='sk',
-                                     help='Path to the private key of the election initiator.')
-
-    approve_election_parser = validator_subparser.add_parser('approve',
                                                             help='Approve the election.')
     approve_election_parser.add_argument('election_id',
                                          help='The election_id of the election.')
@@ -349,7 +344,7 @@ def create_parser():
                                          dest='sk',
                                          help='Path to the private key of the election initiator.')
 
-    show_election_parser = validator_subparser.add_parser('show',
+    show_election_parser = election_subparser.add_parser('show',
                                                          help='Provides information about an election.')
 
     show_election_parser.add_argument('election_id',

bigchaindb/commands/election_types.py

@@ -0,0 +1,20 @@
+elections = {
+    'upsert-validator': {
+        'help': 'Propose a change to the validator set',
+        'args': {
+            'public_key': {
+                'help': 'Public key of the validator to be added/updated/removed.'
+            },
+            'power': {
+                'type': int,
+                'help': 'The proposed power for the validator. Setting to 0 will remove the validator.'},
+            'node_id': {
+                'help': 'The node_id of the validator.'
+            },
+            '--private-key': {
+                'dest': 'sk',
+                'help': 'Path to the private key of the election initiator.'
+            }
+        }
+    }
+}

bigchaindb/common/election.py

@@ -247,3 +247,6 @@ class Election(Transaction):
     @classmethod
     def on_approval(cls, bigchain, election, new_height):
         raise NotImplementedError
+
+    def show_election(self, bigchain):
+        raise NotImplementedError

bigchaindb/upsert_validator/validator_election.py

@@ -6,6 +6,7 @@ from bigchaindb.common.exceptions import InvalidPowerChange
 from bigchaindb.common.election import Election
 from bigchaindb.common.schema import (_validate_schema,
                                       TX_SCHEMA_VALIDATOR_ELECTION)
+from bigchaindb.tendermint_utils import public_key_to_base64
 from .validator_utils import (new_validator_set, encode_validator)
 
 
@@ -52,3 +53,16 @@ class ValidatorElection(Election):
         updated_validator_set = [v for v in updated_validator_set if v['voting_power'] > 0]
         bigchain.store_validator_set(new_height+1, updated_validator_set, election.id)
         return [encode_validator(election.asset['data'])]
+
+    def show_election(self, bigchain):
+
+        new_validator = self.asset['data']
+
+        public_key = public_key_to_base64(new_validator['public_key'])
+        power = new_validator['power']
+        node_id = new_validator['node_id']
+        status = self.get_status(bigchain)
+
+        response = f'public_key={public_key}\npower={power}\nnode_id={node_id}\nstatus={status}'
+
+        return response

docs/server/source/server-reference/bigchaindb-cli.md

@@ -81,20 +81,25 @@ configuration file as documented under
 [Configuration Settings](configuration.html).
 
 
-## bigchaindb upsert-validator
+## bigchaindb election
 
-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 it for more details.
+Manage elections to manage the BigChainDB network. The specifics of the election process are defined in [BEP-21](https://github.com/bigchaindb/BEPs/tree/master/21), please refer it for more details.
 
 Election management is broken into several subcommands. Below is the command line syntax for each,
 
-#### upsert-validator new
+#### election new
 
-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.
+Create a new election which proposes a change to your BigChainDB network.
+
+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.
+
+###### election new upsert-validator
+
+Call an election 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
+$ 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>
 ```
 
@@ -109,7 +114,7 @@ NOTE: A change to the validator set can only be proposed by one of the exisitng
 Example usage,
 
 ```bash
-$ bigchaindb upsert-validator new HHG0IQRybpT6nJMIWWFWhMczCLHt6xcm7eP52GnGuPY= 1 fb7140f03a4ffad899fabbbf655b97e0321add66 --private-key /home/user/.tendermint/config/priv_validator.json
+$ bigchaindb election new upsert-validator HHG0IQRybpT6nJMIWWFWhMczCLHt6xcm7eP52GnGuPY= 1 fb7140f03a4ffad899fabbbf655b97e0321add66 --private-key /home/user/.tendermint/config/priv_validator.json
 [SUCCESS] Submitted proposal with id: 04a067582cf03eba2b53b82e4adb5ece424474cbd4f7183780855a93ac5e3caa
 ```
 
@@ -119,13 +124,14 @@ If the command succeeds, it will create an election and return an `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 change to the validator set by spending their vote tokens.
 
 
-#### upsert-validator approve
+#### election approve
+
+Approve an election by voting for it. The propsal generated by executing `bigchaindb election new ...` 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.
 
-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 <election_id> --private-key PATH_TO_YOUR_PRIVATE_KEY
+$ bigchaindb election approve <election_id> --private-key PATH_TO_YOUR_PRIVATE_KEY
 [SUCCESS] Your vote has been submitted
 ```
 
@@ -134,24 +140,22 @@ $ bigchaindb upsert-validator approve <election_id> --private-key PATH_TO_YOUR_P
 
  Example usage,
  ```bash
-$ bigchaindb upsert-validator approve 04a067582cf03eba2b53b82e4adb5ece424474cbd4f7183780855a93ac5e3caa --private-key /home/user/.tendermint/config/priv_validator.json
+$ 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 applied only after `60` (`2/3 * 90`) have been received.
+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.
 
-#### upsert-validator show
+#### election show
 
-Retrieves information about an election initiated by `upsert-validator new`.
+Retrieves information about an election initiated by `election new`.
 
 Below is the command line syntax and the return value,
 
 ```bash
-$ bigchaindb upsert-validator show ELECTION_ID
+$ bigchaindb election show ELECTION_ID
-public_key=<e_pub_key>
+<election_data>
-power=<e_power>
-node_id=<e_node_id>
 status=<status>
 ```
 
-The `public_key`, `power`, and `node_id` are the same values used in the `upsert-validator 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.
+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.

tests/commands/test_commands.py

@@ -26,11 +26,11 @@ def test_make_sure_we_dont_remove_any_command():
     assert parser.parse_args(['init']).command
     assert parser.parse_args(['drop']).command
     assert parser.parse_args(['start']).command
-    assert parser.parse_args(['upsert-validator', 'new', 'TEMP_PUB_KEYPAIR', '10', 'TEMP_NODE_ID',
+    assert parser.parse_args(['election', 'new', 'upsert-validator', 'TEMP_PUB_KEYPAIR', '10', 'TEMP_NODE_ID',
                               '--private-key', 'TEMP_PATH_TO_PRIVATE_KEY']).command
-    assert parser.parse_args(['upsert-validator', 'approve', 'ELECTION_ID', '--private-key',
+    assert parser.parse_args(['election', 'approve', 'ELECTION_ID', '--private-key',
                               'TEMP_PATH_TO_PRIVATE_KEY']).command
-    assert parser.parse_args(['upsert-validator', 'show', 'ELECTION_ID']).command
+    assert parser.parse_args(['election', 'show', 'ELECTION_ID']).command
 
 
 @pytest.mark.tendermint
@@ -349,25 +349,26 @@ class MockResponse():
 
 
 @pytest.mark.abci
-def test_upsert_validator_new_with_tendermint(b, priv_validator_path, user_sk, validators):
+def test_election_new_upsert_validator_with_tendermint(b, priv_validator_path, user_sk, validators):
-    from bigchaindb.commands.bigchaindb import run_upsert_validator_new
+    from bigchaindb.commands.bigchaindb import run_election_new_upsert_validator
 
     new_args = Namespace(action='new',
+                         election_type='upsert_validator',
                          public_key='8eJ8q9ZQpReWyQT5aFCiwtZ5wDZC4eDnCen88p3tQ6ie',
                          power=1,
                          node_id='unique_node_id_for_test_upsert_validator_new_with_tendermint',
                          sk=priv_validator_path,
                          config={})
 
-    election_id = run_upsert_validator_new(new_args, b)
+    election_id = run_election_new_upsert_validator(new_args, b)
 
     assert b.get_transaction(election_id)
 
 
 @pytest.mark.tendermint
 @pytest.mark.bdb
-def test_upsert_validator_new_without_tendermint(caplog, b, priv_validator_path, user_sk):
+def test_election_new_upsert_validator_without_tendermint(caplog, b, priv_validator_path, user_sk):
-    from bigchaindb.commands.bigchaindb import run_upsert_validator_new
+    from bigchaindb.commands.bigchaindb import run_election_new_upsert_validator
 
     def mock_write(tx, mode):
         b.store_bulk_transactions([tx])
@@ -377,6 +378,7 @@ def test_upsert_validator_new_without_tendermint(caplog, b, priv_validator_path,
     b.write_transaction = mock_write
 
     args = Namespace(action='new',
+                     election_type='upsert_validator',
                      public_key='CJxdItf4lz2PwEf4SmYNAu/c/VpmX39JEgC5YpH7fxg=',
                      power=1,
                      node_id='fb7140f03a4ffad899fabbbf655b97e0321add66',
@@ -384,17 +386,18 @@ def test_upsert_validator_new_without_tendermint(caplog, b, priv_validator_path,
                      config={})
 
     with caplog.at_level(logging.INFO):
-        election_id = run_upsert_validator_new(args, b)
+        election_id = run_election_new_upsert_validator(args, b)
         assert caplog.records[0].msg == '[SUCCESS] Submitted proposal with id: ' + election_id
         assert b.get_transaction(election_id)
 
 
 @pytest.mark.tendermint
 @pytest.mark.bdb
-def test_upsert_validator_new_invalid_election(caplog, b, priv_validator_path, user_sk):
+def test_election_new_upsert_validator_invalid_election(caplog, b, priv_validator_path, user_sk):
-    from bigchaindb.commands.bigchaindb import run_upsert_validator_new
+    from bigchaindb.commands.bigchaindb import run_election_new_upsert_validator
 
     args = Namespace(action='new',
+                     election_type='upsert_validator',
                      public_key='CJxdItf4lz2PwEf4SmYNAu/c/VpmX39JEgC5YpH7fxg=',
                      power=10,
                      node_id='fb7140f03a4ffad899fabbbf655b97e0321add66',
@@ -402,14 +405,14 @@ def test_upsert_validator_new_invalid_election(caplog, b, priv_validator_path, u
                      config={})
 
     with caplog.at_level(logging.ERROR):
-        assert not run_upsert_validator_new(args, b)
+        assert not run_election_new_upsert_validator(args, b)
         assert caplog.records[0].msg.__class__ == FileNotFoundError
 
 
 @pytest.mark.tendermint
 @pytest.mark.bdb
-def test_upsert_validator_new_election_invalid_power(caplog, b, priv_validator_path, user_sk):
+def test_election_new_upsert_validator_invalid_power(caplog, b, priv_validator_path, user_sk):
-    from bigchaindb.commands.bigchaindb import run_upsert_validator_new
+    from bigchaindb.commands.bigchaindb import run_election_new_upsert_validator
     from bigchaindb.common.exceptions import InvalidPowerChange
 
     def mock_write(tx, mode):
@@ -419,6 +422,7 @@ def test_upsert_validator_new_election_invalid_power(caplog, b, priv_validator_p
     b.write_transaction = mock_write
     b.get_validators = mock_get_validators
     args = Namespace(action='new',
+                     election_type='upsert_validator',
                      public_key='CJxdItf4lz2PwEf4SmYNAu/c/VpmX39JEgC5YpH7fxg=',
                      power=10,
                      node_id='fb7140f03a4ffad899fabbbf655b97e0321add66',
@@ -426,38 +430,39 @@ def test_upsert_validator_new_election_invalid_power(caplog, b, priv_validator_p
                      config={})
 
     with caplog.at_level(logging.ERROR):
-        assert not run_upsert_validator_new(args, b)
+        assert not run_election_new_upsert_validator(args, b)
         assert caplog.records[0].msg.__class__ == InvalidPowerChange
 
 
 @pytest.mark.abci
-def test_upsert_validator_approve_with_tendermint(b, priv_validator_path, user_sk, validators):
+def test_election_approve_with_tendermint(b, priv_validator_path, user_sk, validators):
-    from bigchaindb.commands.bigchaindb import (run_upsert_validator_new,
+    from bigchaindb.commands.bigchaindb import (run_election_new_upsert_validator,
-                                                run_upsert_validator_approve)
+                                                run_election_approve)
 
     public_key = 'CJxdItf4lz2PwEf4SmYNAu/c/VpmX39JEgC5YpH7fxg='
     new_args = Namespace(action='new',
+                         election_type='upsert_validator',
                          public_key=public_key,
                          power=1,
                          node_id='fb7140f03a4ffad899fabbbf655b97e0321add66',
                          sk=priv_validator_path,
                          config={})
 
-    election_id = run_upsert_validator_new(new_args, b)
+    election_id = run_election_new_upsert_validator(new_args, b)
 
     args = Namespace(action='approve',
                      election_id=election_id,
                      sk=priv_validator_path,
                      config={})
-    approve = run_upsert_validator_approve(args, b)
+    approve = run_election_approve(args, b)
 
     assert b.get_transaction(approve)
 
 
 @pytest.mark.bdb
 @pytest.mark.tendermint
-def test_upsert_validator_approve_without_tendermint(caplog, b, priv_validator_path, new_validator, node_key):
+def test_election_approve_without_tendermint(caplog, b, priv_validator_path, new_validator, node_key):
-    from bigchaindb.commands.bigchaindb import run_upsert_validator_approve
+    from bigchaindb.commands.bigchaindb import run_election_approve
     from argparse import Namespace
 
     b, election_id = call_election(b, new_validator, node_key)
@@ -470,15 +475,15 @@ def test_upsert_validator_approve_without_tendermint(caplog, b, priv_validator_p
 
     # assert returned id is in the db
     with caplog.at_level(logging.INFO):
-        approval_id = run_upsert_validator_approve(args, b)
+        approval_id = run_election_approve(args, b)
         assert caplog.records[0].msg == '[SUCCESS] Your vote has been submitted'
         assert b.get_transaction(approval_id)
 
 
 @pytest.mark.tendermint
 @pytest.mark.bdb
-def test_upsert_validator_approve_failure(caplog, b, priv_validator_path, new_validator, node_key):
+def test_election_approve_failure(caplog, b, priv_validator_path, new_validator, node_key):
-    from bigchaindb.commands.bigchaindb import run_upsert_validator_approve
+    from bigchaindb.commands.bigchaindb import run_election_approve
     from argparse import Namespace
 
     b, election_id = call_election(b, new_validator, node_key)
@@ -496,14 +501,14 @@ def test_upsert_validator_approve_failure(caplog, b, priv_validator_path, new_va
                      config={})
 
     with caplog.at_level(logging.ERROR):
-        assert not run_upsert_validator_approve(args, b)
+        assert not run_election_approve(args, b)
         assert caplog.records[0].msg == 'Failed to commit vote'
 
 
 @pytest.mark.tendermint
 @pytest.mark.bdb
-def test_upsert_validator_approve_called_with_bad_key(caplog, b, bad_validator_path, new_validator, node_key):
+def test_election_approve_called_with_bad_key(caplog, b, bad_validator_path, new_validator, node_key):
-    from bigchaindb.commands.bigchaindb import run_upsert_validator_approve
+    from bigchaindb.commands.bigchaindb import run_election_approve
     from argparse import Namespace
 
     b, election_id = call_election(b, new_validator, node_key)
@@ -515,7 +520,7 @@ def test_upsert_validator_approve_called_with_bad_key(caplog, b, bad_validator_p
                      config={})
 
     with caplog.at_level(logging.ERROR):
-        assert not run_upsert_validator_approve(args, b)
+        assert not run_election_approve(args, b)
         assert caplog.records[0].msg == 'The key you provided does not match any of '\
             'the eligible voters in this election.'
 

tests/upsert_validator/test_validator_election.py

@@ -144,7 +144,7 @@ def test_get_status_inconclusive(b, inconclusive_election, new_validator):
 
 
 def test_upsert_validator_show(caplog, ongoing_election, b):
-    from bigchaindb.commands.bigchaindb import run_upsert_validator_show
+    from bigchaindb.commands.bigchaindb import run_election_show
 
     election_id = ongoing_election.id
     public_key = public_key_to_base64(ongoing_election.asset['data']['public_key'])
@@ -155,6 +155,6 @@ def test_upsert_validator_show(caplog, ongoing_election, b):
     show_args = Namespace(action='show',
                           election_id=election_id)
 
-    msg = run_upsert_validator_show(show_args, b)
+    msg = run_election_show(show_args, b)
 
     assert msg == f'public_key={public_key}\npower={power}\nnode_id={node_id}\nstatus={status}'