create_block_manager_wallet.sh

Overview

This script automates the deployment of a Block Manager wallet in a blockchain system. It handles key generation, configuration of the TVM (TON Virtual Machine) CLI endpoint, and invokes contract calls to deploy and verify the wallet. The script also validates license numbers associated with the wallet and retrieves addresses for each license. It is intended for use by developers or operators who are managing multisig wallets and licenses within the system.

Detailed Explanation

Script Purpose

• Generate or use existing keys for the Block Manager wallet owner and signing authority.

• Configure the tvm-cli tool with a specified endpoint.

• Deploy a Block Manager wallet on the blockchain using the contract ABI and keys.

• Retrieve and display the deployed wallet address.

• Fetch and display license addresses corresponding to user-supplied license numbers.

• Verify and output details of the deployed wallet.

Environment Variables & Constants

Functions

gen_key

gen_key () {
  if [ ! -e $1 ]; then
    echo File $1 not found. Generating block manager keys...
    tvm-cli -j genphrase --dump $1 > $1.phrase
  fi
}

• Purpose: Checks if a key file exists at the specified path; if not, generates a new key pair using tvm-cli.

• Parameters:

  • $1 - Path to the key file.

• Behavior: Generates a key phrase and saves it to a .phrase file alongside the key file.

• Usage Example:

gen_key "./owner_key.json"

read_key

read_key () {
  local BM_OWNER_PUB_KEY_JSON=$(jq -r .public $BM_OWNER_KEY_FILE_OUTPUT_PATH)
  local BM_SIGNING_PUB_KEY_JSON=$(jq -r .public $BM_SIGNING_KEY_FILE_OUTPUT_PATH)
  local WHITELISTPARAMS=$(echo "$LICENSE_NUMBERS" | jq -R 'split(",") | map({(.): true}) | add')
  
  [ "$(echo $WHITELISTPARAMS | jq -r '. | length')" -gt $MAX_LICENSES_PER_WALLET ] && { echo "License numbers couldn't be greater than $MAX_LICENSES_PER_WALLET" ; exit 1 ; }

  BM_OWNER_PUB_KEY=$(echo '{"pubkey": "0x{public}"}' | sed -e "s/{public}/$BM_OWNER_PUB_KEY_JSON/g")  
  BM_OWNER_PUB_KEY_PARAMS=$(echo "{\"pubkey\": \"0x{public}\", \"signerPubkey\": \"0x{signer_public}\", \"whiteListLicense\": $WHITELISTPARAMS}" | sed -e "s/{public}/$BM_OWNER_PUB_KEY_JSON/g" | sed -e "s/{signer_public}/$BM_SIGNING_PUB_KEY_JSON/g")
}

• Purpose: Reads public keys from the key files and prepares JSON parameters for the wallet deployment call, including the whitelist of license numbers.

• Parameters: None (uses global variables).

• Details:

  • Extracts public keys from JSON key files using jq.

  • Converts the comma-separated license numbers into a JSON object with license numbers as keys and true as values.

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

  • Constructs two JSON strings:

    • BM_OWNER_PUB_KEY: Contains only the owner's public key.

    • BM_OWNER_PUB_KEY_PARAMS: Contains owner's public key, signer public key, and license whitelist.

• Usage Example:

read_key
echo "$BM_OWNER_PUB_KEY_PARAMS"

Main Execution Flow

1. Dependency Check: Verifies tvm-cli is installed and available in the environment.

2. Argument Parsing: Accepts four arguments:

   • Block Manager owner key file path

   • Signing key file path

   • Comma-separated license numbers

   • TVM endpoint URL

3. TVM CLI Configuration: Sets the TVM CLI endpoint URL using tvm-cli config.

4. Key Generation: Calls gen_key for owner and signing keys if files do not exist.

5. Reading Keys and Preparing Parameters: Calls read_key.

6. Deployment:

   • Calls the deployAckiNackiBlockManagerNodeWallet method on the Block Manager System root contract with the prepared parameters.

   • Waits 3 seconds to allow deployment to complete.

7. Wallet Address Retrieval: Queries the deployed wallet address using getAckiNackiBlockManagerNodeWalletAddress.

8. License Address Retrieval:

   • Iterates over each license number.

   • Calls getLicenseBMAddress on the LicenseRoot contract to get the license address.

9. Wallet Details Check: Retrieves and prints wallet details using getDetails method on the deployed wallet contract.

Important Implementation Details

• Strict Bash Options: The script uses set -euo pipefail to enforce strict error handling, undefined variable checks, and pipeline failure detection.

• License Whitelist as JSON Object: License numbers are converted into a JSON dictionary of {license_number: true}, which simplifies lookup and validation in the smart contract.

• Key Generation Using tvm-cli: The script depends on the tvm-cli tool for generating key pairs and interacting with smart contracts.

• Sleep after Deployment: A fixed sleep of 3 seconds is used to allow async deployment processes to complete before querying the wallet address.

• Use of jq for JSON: The script uses jq extensively for parsing and constructing JSON data, critical for preparing parameters and reading responses.

Interaction with Other System Components

• Contracts:

  • BlockManagerContractRoot (ABI at ../../contracts/bksystem/BlockManagerContractRoot.abi.json): The root contract responsible for deploying Block Manager wallets.

  • AckiNackiBlockManagerNodeWallet (ABI at ../../contracts/bksystem/AckiNackiBlockManagerNodeWallet.abi.json): The deployed wallet contract.

  • LicenseRoot (ABI at ../../contracts/bksystem/LicenseRoot.abi.json): Used to resolve license addresses by license number.

  • License (ABI at ../../contracts/bksystem/License.abi.json): (Referenced but not directly interacted with in this script.)

• TVM CLI: The tool used to interact with the blockchain, perform contract calls, and generate keys.

• Key Files: The script reads and writes key files for owner and signing keys, which are critical for wallet ownership and signing transactions.

• License System: The wallet is linked to a whitelist of licenses, validated and retrieved from the LicenseRoot contract.

Usage Example

./create_block_manager_wallet.sh ./owner_key.json ./signing_key.json "101,102,103" "https://tvm.example.com"

• Generates keys if missing.

• Deploys a Block Manager wallet with licenses 101, 102, and 103.

• Prints the deployed wallet address and license addresses.

• Outputs wallet details.

Mermaid Flowchart

flowchart TD
A[tvm-cli dependency check] --> B[Parse script arguments]
B --> C[Configure TVM CLI endpoint]
C --> D[Generate owner key if missing]
C --> E[Generate signing key if missing]
D --> F[Read keys and prepare JSON params]
E --> F
F --> G[Deploy Block Manager wallet contract]
G --> H["Wait for deployment (sleep 3s)"]
H --> I[Retrieve deployed wallet address]
I --> J[For each license number]
J --> K[Get license address from LicenseRoot contract]
J --> L[Print license addresses]
I --> M[Query wallet details]
M --> N[Print wallet details]

This file is a critical utility for deploying and managing Block Manager wallets and their associated licenses, bridging key management, contract deployment, and license validation workflows. It relies on contract ABIs and blockchain interaction through tvm-cli and integrates with license contracts to maintain wallet-license relationships. For related concepts, see the topics on Smart Contract Deployment and Key Management.