Add generate_bls_to_execution_change

.gitignore

@@ -1,4 +1,5 @@
 validator_keys
+bls_to_execution_changes
 
 # Python testing & linting:
 build/

README.md

@@ -18,6 +18,7 @@
         - [`new-mnemonic` Arguments](#new-mnemonic-arguments)
         - [`existing-mnemonic` Arguments](#existing-mnemonic-arguments)
         - [Successful message](#successful-message)
+        - [`generate-bls-to-execution-change` Arguments](#generate-bls-to-execution-change-arguments)
     - [Option 2. Build `deposit-cli` with native Python](#option-2-build-deposit-cli-with-native-python)
       - [Step 0. Python version checking](#step-0-python-version-checking)
       - [Step 1. Installation](#step-1-installation-1)
@@ -128,6 +129,7 @@ The CLI offers different commands depending on what you want to do with the tool
 | ------- | ----------- |
 | `new-mnemonic` | (Recommended) This command is used to generate keystores with a new mnemonic. |
 | `existing-mnemonic` | This command is used to re-generate or derive new keys from your existing mnemonic. Use this command, if (i) you have already generated keys with this CLI before, (ii) you want to reuse your mnemonic that you know is secure that you generated elsewhere (reusing your eth1 mnemonic .etc), or (iii) you lost your keystores and need to recover your keys. |
+| ``
 
 ###### `new-mnemonic` Arguments
 
@@ -168,6 +170,22 @@ Success!
 Your keys can be found at: <YOUR_FOLDER_PATH>
 ```
 
+###### `generate-bls-to-execution-change` Arguments 
+
+You can use `bls-to-execution-change --help` to see all arguments. Note that if there are missing arguments that the CLI needs, it will ask you for them.
+
+| Argument | Type | Description |
+| -------- | -------- | -------- |
+| `--bls_to_execution_changes_folder` | String. Pointing to `./bls_to_execution_changes` by default | The folder path for the `bls_to_execution_change-*` JSON file(s) |
+| `--chain` | String. `mainnet` by default | The chain setting for the signing domain. |
+| `--mnemonic` | String. mnemonic split by space.  | The mnemonic you used to create withdrawal credentials. |
+| `--mnemonic_password` | Optional string. Empty by default. | The mnemonic password you used in your key generation. Note: It's not the keystore password. |
+| `--validator_start_index` | Non-negative integer | The index of the first validator's keys you generated withdrawal credentials with the mnemonic. |
+| `--validator_indices` | String of integer(s) | A list of the index number of your validator(s) in beacon chain state. Split multiple items with whitespaces or commas. |
+| `--bls_withdrawal_credentials_list` | String of hexstring(s). | A list of the old BLS withdrawal credentials of the given validator(s). It is for confirming you are using the correct keys. Split multiple items with whitespaces or commas. |
+| `--execution_address` | String. 20-byte Execution (Eth1) address in hexadecimal encoded form | The execution (Eth1) address you want to change to for withdrawals. |
+| `--devnet_chain_setting` | String. JSON string `'{"network_name": "<NETWORK_NAME>", "genesis_fork_version": "<GENESIS_FORK_VERSION>", "genesis_validator_root": "<GENESIS_VALIDATOR_ROOT>"}'` | The custom chain setting of a devnet or testnet. Note that it will override your `--chain` choice. |
+
 #### Option 2. Build `deposit-cli` with native Python
 
 ##### Step 0. Python version checking
@@ -228,6 +246,7 @@ See [here](#commands)
 
 See [here](#new-mnemonic-arguments) for `new-mnemonic` arguments
 See [here](#existing-mnemonic-arguments) for `existing-mnemonic` arguments
+See [here](#generate-bls-to-execution-change-arguments) for `generate-bls-to-execution-change` arguments
 
 ###### Successful message
 See [here](#successful-message)
@@ -295,6 +314,7 @@ See [here](#commands)
 
 See [here](#new-mnemonic-arguments) for `new-mnemonic` arguments
 See [here](#existing-mnemonic-arguments) for `existing-mnemonic` arguments
+See [here](#generate-bls-to-execution-change-arguments) for `generate-bls-to-execution-change` arguments
 
 #### Option 4. Use Docker image
 
@@ -378,6 +398,7 @@ See [here](#commands)
 
 See [here](#new-mnemonic-arguments) for `new-mnemonic` arguments
 See [here](#existing-mnemonic-arguments) for `existing-mnemonic` arguments
+See [here](#generate-bls-to-execution-change-arguments) for `generate-bls-to-execution-change` arguments
 
 #### Option 2. Build `deposit-cli` with native Python
 
@@ -440,6 +461,7 @@ See [here](#commands)
 
 See [here](#new-mnemonic-arguments) for `new-mnemonic` arguments
 See [here](#existing-mnemonic-arguments) for `existing-mnemonic` arguments
+See [here](#generate-bls-to-execution-change-arguments) for `generate-bls-to-execution-change` arguments
 
 #### Option 3. Build `deposit-cli` with `virtualenv`
 
@@ -504,6 +526,7 @@ See [here](#commands)
 
 See [here](#new-mnemonic-arguments) for `new-mnemonic` arguments
 See [here](#existing-mnemonic-arguments) for `existing-mnemonic` arguments
+See [here](#generate-bls-to-execution-change-arguments) for `generate-bls-to-execution-change` arguments
 
 ## Development
 

staking_deposit/cli/existing_mnemonic.py

@@ -1,6 +1,7 @@
 import click
 from typing import (
     Any,
+    Callable,
 )
 
 from staking_deposit.exceptions import ValidationError
@@ -22,6 +23,39 @@
 )
 
 
+def load_mnemonic_arguments_decorator(function: Callable[..., Any]) -> Callable[..., Any]:
+    '''
+    This is a decorator that, when applied to a parent-command, implements the
+    to obtain the necessary arguments for the generate_keys() subcommand.
+    '''
+    decorators = [
+        jit_option(
+            callback=validate_mnemonic,
+            help=lambda: load_text(['arg_mnemonic', 'help'], func='existing_mnemonic'),
+            param_decls='--mnemonic',
+            prompt=lambda: load_text(['arg_mnemonic', 'prompt'], func='existing_mnemonic'),
+            type=str,
+        ),
+        jit_option(
+            callback=captive_prompt_callback(
+                lambda x: x,
+                lambda: load_text(['arg_mnemonic_password', 'prompt'], func='existing_mnemonic'),
+                lambda: load_text(['arg_mnemonic_password', 'confirm'], func='existing_mnemonic'),
+                lambda: load_text(['arg_mnemonic_password', 'mismatch'], func='existing_mnemonic'),
+                True,
+            ),
+            default='',
+            help=lambda: load_text(['arg_mnemonic_password', 'help'], func='existing_mnemonic'),
+            hidden=True,
+            param_decls='--mnemonic-password',
+            prompt=False,
+        ),
+    ]
+    for decorator in reversed(decorators):
+        function = decorator(function)
+    return function
+
+
 def validate_mnemonic(ctx: click.Context, param: Any, mnemonic: str) -> str:
     mnemonic = reconstruct_mnemonic(mnemonic, WORD_LISTS_PATH)
     if mnemonic is not None:
@@ -33,27 +67,7 @@ def validate_mnemonic(ctx: click.Context, param: Any, mnemonic: str) -> str:
 @click.command(
     help=load_text(['arg_existing_mnemonic', 'help'], func='existing_mnemonic'),
 )
-@jit_option(
-    callback=validate_mnemonic,
-    help=lambda: load_text(['arg_mnemonic', 'help'], func='existing_mnemonic'),
-    param_decls='--mnemonic',
-    prompt=lambda: load_text(['arg_mnemonic', 'prompt'], func='existing_mnemonic'),
-    type=str,
-)
-@jit_option(
-    callback=captive_prompt_callback(
-        lambda x: x,
-        lambda: load_text(['arg_mnemonic_password', 'prompt'], func='existing_mnemonic'),
-        lambda: load_text(['arg_mnemonic_password', 'confirm'], func='existing_mnemonic'),
-        lambda: load_text(['arg_mnemonic_password', 'mismatch'], func='existing_mnemonic'),
-        True,
-    ),
-    default='',
-    help=lambda: load_text(['arg_mnemonic_password', 'help'], func='existing_mnemonic'),
-    hidden=True,
-    param_decls='--mnemonic-password',
-    prompt=False,
-)
+@load_mnemonic_arguments_decorator
 @jit_option(
     callback=captive_prompt_callback(
         lambda num: validate_int_range(num, 0, 2**32),

staking_deposit/cli/generate_bls_to_execution_change.py

@@ -0,0 +1,196 @@
+import os
+import click
+import json
+from typing import (
+    Any,
+    Sequence,
+)
+
+from eth_typing import HexAddress
+
+from staking_deposit.credentials import (
+    CredentialList,
+)
+from staking_deposit.utils.validation import (
+    validate_bls_withdrawal_credentials_list,
+    validate_bls_withdrawal_credentials_matching,
+    validate_eth1_withdrawal_address,
+    validate_int_range,
+    verify_bls_to_execution_change_json,
+    validate_validator_indices,
+)
+from staking_deposit.utils.constants import (
+    DEFAULT_BLS_TO_EXECUTION_CHANGES_FOLDER_NAME,
+    MAX_DEPOSIT_AMOUNT,
+)
+from staking_deposit.utils.click import (
+    captive_prompt_callback,
+    choice_prompt_func,
+    jit_option,
+)
+from staking_deposit.exceptions import ValidationError
+from staking_deposit.utils.intl import (
+    closest_match,
+    load_text,
+)
+from staking_deposit.settings import (
+    ALL_CHAINS,
+    MAINNET,
+    PRATER,
+    get_chain_setting,
+    get_devnet_chain_setting,
+)
+from .existing_mnemonic import (
+    load_mnemonic_arguments_decorator,
+)
+
+
+def get_password(text: str) -> str:
+    return click.prompt(text, hide_input=True, show_default=False, type=str)
+
+
+FUNC_NAME = 'generate_bls_to_execution_change'
+
+
+@click.command()
+@jit_option(
+    default=os.getcwd(),
+    help=lambda: load_text(['arg_bls_to_execution_changes_folder', 'help'], func=FUNC_NAME),
+    param_decls='--bls_to_execution_changes_folder',
+    type=click.Path(exists=True, file_okay=False, dir_okay=True),
+)
+@jit_option(
+    callback=captive_prompt_callback(
+        lambda x: closest_match(x, list(ALL_CHAINS.keys())),
+        choice_prompt_func(
+            lambda: load_text(['arg_chain', 'prompt'], func=FUNC_NAME),
+            list(ALL_CHAINS.keys())
+        ),
+    ),
+    default=MAINNET,
+    help=lambda: load_text(['arg_chain', 'help'], func=FUNC_NAME),
+    param_decls='--chain',
+    prompt=choice_prompt_func(
+        lambda: load_text(['arg_chain', 'prompt'], func=FUNC_NAME),
+        # Since `prater` is alias of `goerli`, do not show `prater` in the prompt message.
+        list(key for key in ALL_CHAINS.keys() if key != PRATER)
+    ),
+)
+@load_mnemonic_arguments_decorator
+@jit_option(
+    callback=captive_prompt_callback(
+        lambda num: validate_int_range(num, 0, 2**32),
+        lambda: load_text(['arg_validator_start_index', 'prompt'], func=FUNC_NAME),
+    ),
+    default=0,
+    help=lambda: load_text(['arg_validator_start_index', 'help'], func=FUNC_NAME),
+    param_decls="--validator_start_index",
+    prompt=lambda: load_text(['arg_validator_start_index', 'prompt'], func=FUNC_NAME),
+)
+@jit_option(
+    callback=captive_prompt_callback(
+        lambda validator_indices: validate_validator_indices(validator_indices),
+        lambda: load_text(['arg_validator_indices', 'prompt'], func=FUNC_NAME),
+    ),
+    help=lambda: load_text(['arg_validator_indices', 'help'], func=FUNC_NAME),
+    param_decls='--validator_indices',
+    prompt=lambda: load_text(['arg_validator_indices', 'prompt'], func=FUNC_NAME),
+)
+@jit_option(
+    callback=captive_prompt_callback(
+        lambda bls_withdrawal_credentials_list:
+            validate_bls_withdrawal_credentials_list(bls_withdrawal_credentials_list),
+        lambda: load_text(['arg_bls_withdrawal_credentials_list', 'prompt'], func=FUNC_NAME),
+    ),
+    help=lambda: load_text(['arg_bls_withdrawal_credentials_list', 'help'], func=FUNC_NAME),
+    param_decls='--bls_withdrawal_credentials_list',
+    prompt=lambda: load_text(['arg_bls_withdrawal_credentials_list', 'prompt'], func=FUNC_NAME),
+)
+@jit_option(
+    callback=captive_prompt_callback(
+        lambda address: validate_eth1_withdrawal_address(None, None, address),
+        lambda: load_text(['arg_execution_address', 'prompt'], func=FUNC_NAME),
+        lambda: load_text(['arg_execution_address', 'confirm'], func=FUNC_NAME),
+        lambda: load_text(['arg_execution_address', 'mismatch'], func=FUNC_NAME),
+    ),
+    help=lambda: load_text(['arg_execution_address', 'help'], func=FUNC_NAME),
+    param_decls='--execution_address',
+    prompt=lambda: load_text(['arg_execution_address', 'prompt'], func=FUNC_NAME),
+)
+@jit_option(
+    # Only for devnet tests
+    default=None,
+    help="[DEVNET ONLY] Set specific GENESIS_FORK_VERSION value",
+    param_decls='--devnet_chain_setting',
+)
+@click.pass_context
+def generate_bls_to_execution_change(
+        ctx: click.Context,
+        bls_to_execution_changes_folder: str,
+        chain: str,
+        mnemonic: str,
+        mnemonic_password: str,
+        validator_start_index: int,
+        validator_indices: Sequence[int],
+        bls_withdrawal_credentials_list: Sequence[bytes],
+        execution_address: HexAddress,
+        devnet_chain_setting: str,
+        **kwargs: Any) -> None:
+    # Generate folder
+    bls_to_execution_changes_folder = os.path.join(
+        bls_to_execution_changes_folder,
+        DEFAULT_BLS_TO_EXECUTION_CHANGES_FOLDER_NAME,
+    )
+    if not os.path.exists(bls_to_execution_changes_folder):
+        os.mkdir(bls_to_execution_changes_folder)
+
+    # Get chain setting
+    chain_setting = get_chain_setting(chain)
+
+    if devnet_chain_setting is not None:
+        click.echo('\n%s\n' % '**[Warning] Using devnet chain setting to generate the SignedBLSToExecutionChange.**\t')
+        devnet_chain_setting_dict = json.loads(devnet_chain_setting)
+        chain_setting = get_devnet_chain_setting(
+            network_name=devnet_chain_setting_dict['network_name'],
+            genesis_fork_version=devnet_chain_setting_dict['genesis_fork_version'],
+            genesis_validator_root=devnet_chain_setting_dict['genesis_validator_root'],
+        )
+
+    if len(validator_indices) != len(bls_withdrawal_credentials_list):
+        raise ValueError(
+            "The size of `validator_indices` (%d) should be as same as `bls_withdrawal_credentials_list` (%d)."
+            % (len(validator_indices), len(bls_withdrawal_credentials_list))
+        )
+
+    num_validators = len(validator_indices)
+    amounts = [MAX_DEPOSIT_AMOUNT] * num_validators
+
+    credentials = CredentialList.from_mnemonic(
+        mnemonic=mnemonic,
+        mnemonic_password=mnemonic_password,
+        num_keys=num_validators,
+        amounts=amounts,
+        chain_setting=chain_setting,
+        start_index=validator_start_index,
+        hex_eth1_withdrawal_address=execution_address,
+    )
+
+    # Check if the given old bls_withdrawal_credentials is as same as the mnemonic generated
+    for i, credential in enumerate(credentials.credentials):
+        validate_bls_withdrawal_credentials_matching(bls_withdrawal_credentials_list[i], credential)
+
+    btec_file = credentials.export_bls_to_execution_change_json(bls_to_execution_changes_folder, validator_indices)
+
+    json_file_validation_result = verify_bls_to_execution_change_json(
+        btec_file,
+        credentials.credentials,
+        input_validator_indices=validator_indices,
+        input_execution_address=execution_address,
+        chain_setting=chain_setting,
+    )
+    if not json_file_validation_result:
+        raise ValidationError(load_text(['err_verify_btec']))
+
+    click.echo(load_text(['msg_creation_success']) + str(bls_to_execution_changes_folder))
+
+    click.pause(load_text(['msg_pause']))

staking_deposit/cli/generate_keys.py

@@ -6,7 +6,6 @@
 )
 
 from eth_typing import HexAddress
-from eth_utils import is_hex_address, to_normalized_address
 
 from staking_deposit.credentials import (
     CredentialList,
@@ -16,6 +15,7 @@
     verify_deposit_data_json,
     validate_int_range,
     validate_password_strength,
+    validate_eth1_withdrawal_address,
 )
 from staking_deposit.utils.constants import (
     MAX_DEPOSIT_AMOUNT,
@@ -43,17 +43,6 @@ def get_password(text: str) -> str:
     return click.prompt(text, hide_input=True, show_default=False, type=str)
 
 
-def validate_eth1_withdrawal_address(cts: click.Context, param: Any, address: str) -> HexAddress:
-    if address is None:
-        return None
-    if not is_hex_address(address):
-        raise ValueError(load_text(['err_invalid_ECDSA_hex_addr']))
-
-    normalized_address = to_normalized_address(address)
-    click.echo('\n%s\n' % load_text(['msg_ECDSA_addr_withdrawal']))
-    return normalized_address
-
-
 def generate_keys_arguments_decorator(function: Callable[..., Any]) -> Callable[..., Any]:
     '''
     This is a decorator that, when applied to a parent-command, implements the