create_block_keeper_wallet.sh

Overview

This shell script automates the creation and deployment of a Block Keeper wallet within the Acki Nacki blockchain ecosystem. It generates or reads cryptographic keys, deploys a wallet smart contract, and associates license numbers with the wallet. The script utilizes the tvm-cli command-line tool for interacting with the blockchain, including generating keys, deploying contracts, and querying contract state.

Key features include:

• Generating node owner keys if not already present.

• Validating and reading license numbers to whitelist them in the wallet.

• Deploying the Block Keeper node wallet contract using a root contract.

• Retrieving and displaying deployed wallet and license information.

• Checking wallet balance and outputting node identifiers.

This script primarily interfaces with smart contracts related to the Block Keeper system and license management, using ABI files and contract addresses.

Usage

create_block_keeper_wallet.sh [options]

Options

• -nk, --node-owner-keys: Path to the node owner keys file.

• -l, --license-numbers: Comma-separated list of license numbers to whitelist (e.g., 1,2,3).

• -h, --help: Show usage information.

Example:

./create_block_keeper_wallet.sh -nk ./node_owner.json -l 1,2,3

Detailed Description

Global Variables

• NODE_OWNER_KEY_FILE_OUTPUT_PATH: Path to the node owner key file.

• LICENSE_NUMBERS: Comma-separated string with license numbers to whitelist.

• MAX_LICENSES_PER_WALLET: Maximum allowed license numbers per wallet (20).

• Paths to ABI files and contract root addresses for:

  • Block Keeper contract root

  • Block Keeper node wallet

  • License root

  • License contract

• Wallet initialization parameters and ECC key identifier.

Functions

print_usage

Prints the usage instructions and describes required options for the script.

• Parameters: None

• Returns: None

• Usage: Called when -h or unknown options are provided or when argument count is invalid.

get_options

Parses command-line options and assigns values to global variables.

• Parameters:

  • $@ - All command line arguments.

• Returns: None, but sets:

  • NODE_OWNER_KEY_FILE_OUTPUT_PATH

  • LICENSE_NUMBERS

• Behavior: Exits with error on unknown options.

gen_key

Generates node owner keys using tvm-cli if the specified key file does not exist.

• Parameters: None (relies on global NODE_OWNER_KEY_FILE_OUTPUT_PATH)

• Returns: None

• Behavior: If key file is missing, runs key generation and saves output.

read_key

Reads the public key from the node owner key file and constructs JSON objects needed for wallet deployment.

• Parameters: None (relies on global variables)

• Returns: None, but sets:

  • NODE_OWNER_PUB_KEY: JSON string with public key.

  • NODE_OWNER_PUB_KEY_LICENSE: JSON string with public key and license whitelist.

• Implementation Details:

  • License numbers string is converted to a JSON map with keys as license numbers and boolean true values.

  • Validates that the number of licenses does not exceed MAX_LICENSES_PER_WALLET.

  • Uses jq for JSON manipulation.

• Errors: Exits if license number count exceeds limit.

Main Execution Flow

1. Option Parsing: Calls get_options with command line arguments.

2. Input Validation: Checks argument count to ensure proper usage.

3. Dependency Check: Verifies that tvm-cli is installed; exits if missing.

4. Key Generation: Calls gen_key to create node owner keys if needed.

5. Key Reading: Calls read_key to prepare public key JSONs.

6. Wallet Deployment: Uses tvm-cli callx command to deploy the Block Keeper node wallet contract on the blockchain, passing the public key and license whitelist.

7. Wallet Address Retrieval: Queries the deployed wallet address by calling the root contract with the public key.

8. License Address Lookup: Iterates over each license number, fetching its contract address using the LicenseRoot contract.

9. Wallet Balance Check: Queries the deployed wallet contract to get wallet details, including the current balance.

10. Output: Displays wallet address, node ID, license addresses, and balance information.

Important Implementation Details

• Uses JSON manipulation extensively with jq to convert shell variables into properly formatted JSON strings for blockchain calls.

• Limits license number whitelist size to avoid contract or transaction issues.

• Relies on predefined ABI files and root contract addresses, which must correspond to deployed contracts.

• Some commented-out code suggests planned or optional features like sponsoring tokens to the wallet and checking account status.

• Wallet deployment uses the deployAckiNackiBlockKeeperNodeWallet method on the root contract.

• License contract addresses are retrieved individually for each license number.

• Outputs node ID by extracting part of the wallet address.

Interaction with Other System Components

• tvm-cli: Core command-line interface for interacting with the blockchain and contracts.

• Block Keeper Contracts:

  • BlockKeeperContractRoot (root contract deploying wallets)

  • AckiNackiBlockKeeperNodeWallet (wallet contract ABI)

• License Contracts:

  • LicenseRoot (contract to get license addresses)

  • License (individual license contract ABI)

• Key Files: Node owner key files generated or provided to authenticate wallet ownership.

• License Numbers: Used to whitelist licenses within the deployed wallet, linking wallet functionality to licenses.

Visual Diagram

flowchart TD
Start[Start Script]
ParseOpts[get_options]
ValidateOpts[Validate Options]
CheckTVMCLI{Is tvm-cli installed?}
GenKey[gen_key: Generate Node Owner Keys]
ReadKey[read_key: Read and Prepare Keys]
DeployWallet[Deploy Block Keeper Wallet Contract]
GetWalletAddr[Get Wallet Address]
GetLicenseAddr[Get License Addresses]
CheckBalance[Check Wallet Balance]
OutputInfo[Output Wallet and Node Info]
End[End Script]
Start --> ParseOpts --> ValidateOpts --> CheckTVMCLI
CheckTVMCLI -- No --> End
CheckTVMCLI -- Yes --> GenKey --> ReadKey --> DeployWallet --> GetWalletAddr --> GetLicenseAddr --> CheckBalance --> OutputInfo --> End

This flowchart illustrates the main execution steps of the script from option parsing to final output.

Notes on Script Structure and Algorithms

• Uses standard shell scripting with strict error handling (set -eu).

• Options parsing is implemented with a while loop and case statement.

• JSON manipulation in shell is handled by jq to maintain correct formatting for contract calls.

• The script uses contract method calls and queries to deploy wallets and retrieve data, which requires ABI files and addresses to be correctly set.

• The license whitelist is constructed as a JSON map with license numbers as keys and boolean true as values, then embedded in the deployment call.

• The script outputs key information to the console for further manual processing by users.

References

• For details on wallet creation and deployment process, see How to Deploy a Sponsor Wallet.

• For interaction with the blockchain using tvm-cli, see TVM Command Line Interface Usage.

• For license management and contract interfaces, see License Contracts.

• For Block Keeper system contract design and details, see Block Keeper System.