Command Line Interface Wallet

The Helium Command Line Interface (CLI) wallet is the most flexible of the wallet options but it also requires more technical knowledge. As such, it is suitable for all types of transactions, but requires more caution on behalf of its users.

Once you've covered the basics here, you can explore more specific use-cases for the wallet:

Installing CLI Wallet

Releases of the CLI wallet are tagged and hosted on Github. Click on "Downloads" for the most recent release and select the appropriate package for your operating system.

Unpack the zip file and place the helium-wallet binary in your $PATH somewhere. This operation differs depending on your operating system, but is a common task and easily searchable.

Usage

At any time, use --help to see the most recent documentation and help for the CLI wallet.

At time of this writing, version 1.6.0 looks like this:

$ helium-wallet --help
helium-wallet 1.6.0
Common options for most wallet commands

USAGE:
    helium-wallet [OPTIONS] <SUBCOMMAND>

FLAGS:
    -h, --help
            Prints help information

    -V, --version
            Prints version information


OPTIONS:
    -f, --file <files>...
            File(s) to use [default: wallet.key]

        --format <format>
            Output format to use [default: table]  [possible values: table, json]


SUBCOMMANDS:
    balance       Get the balance for a wallet. The balance is given in HNT and has a precision of 8 decimals
    burn          Burn HNT to Data Credits (DC) from this wallet to given payees wallet
    create        Create a new wallet
    help          Prints this message or the help of the given subcommand(s)
    hotspots      Display list of hotspots associated with wallet or transfer a hotspot to another wallet
    htlc          Create or Redeem from an HTLC address
    info          Get wallet information
    multisig      Commands multi signature transactions
    oracle        Report an oracle price to the blockchain
    oui           Create or update an OUI
    pay           Send one (or more) payments to given addresses. If an input file is specified for multiple
                  payments, the payee, amount and memo arguments are ignored
    request       Construct various request (like payment) in a QR code
    securities    Work with security tokens
    upgrade       Upgrade a wallet to the latest supported version of the given format. The same password is used to
                  decrypt the old and encrypt the new wallet
    validators    Commands for validators
    vars          Commands for chain variables
    verify        Verify an encypted wallet

Exploring the help menu is always a good way to orient yourself. To learn more about a certain transaction (or subcommand), simply append --help. eg:

helium-wallet pay --help

This documentation will not cover every single command, but we will provide some basic examples to help you get familiar.

Create Wallet

helium-wallet create basic

This command will create a wallet as a single key, stored in wallet.key which gets output in whatever directory you ran this command.

Upon creation, the CLI will prompt you for a password which encrypts the file. A strong password will make it difficult for someone to brute force the file should the file be compromised.

Display Wallet

Displaying information for one or more wallets without needing its password can be done using;

    helium-wallet info

To display a QR code for the public key of the given wallet use:

    helium-wallet info --qr

This is useful for sending tokens to the wallet from the mobile wallet.

Wallet Creation Features

Creating a wallet above is easy, but there's a lot more flexibility you might not know about. It's always recommended to explore the help menu to learn more:

$ helium-wallet create basic --help

helium-wallet-create-basic 1.6.0
Create a new basic wallet

USAGE:
    helium-wallet create basic [FLAGS] [OPTIONS]

FLAGS:
        --force      Overwrite an existing file
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
        --key-type <key-type>    The type of key to generate (ecc_compact/ed25519) [default: ed25519]
        --network <network>      The network to generate the wallet (testnet/mainnet) [default: mainnet]
    -o, --output <output>        Output file to store the key in [default: wallet.key]
        --seed <seed>            Use a BIP39 or mobile app seed phrase to generate the wallet keys [possible values:
                                 bip39, mobile]

We'll go through a few examples next.

Managing Multiple Wallets

You can specify a more precise location or filename when creating a wallet by using the --output flag. eg:

helium-wallet create basic --output ~/my-wallets/wallet-5.key

When using a wallet, you can specify a file other than the default ./wallet.key by using the the global option --file. eg:

helium-wallet -f ~/my-wallets/wallet-5.key pay <AMOUNT> <ADDRESS>

Sharded Wallet

Sharding wallet keys is supported via Shamir's Secret Sharing. A key can be broken into N shards such that recovering the original key needs K distinct shards. This can be done by passing options to create:

    helium-wallet create sharded -n 5 -k 3

This will create wallet.key.1 through wallet.key.5 (the base name of the wallet file can be supplied with the --output parameter).

When keys are sharded using verify will require at least K distinct keys.

The --seed option described above can also be used to construct a sharded wallet.

Implementation details

A ed25519 key is generated via libsodium. The provided password is run through PBKDF2, with a configurable number of iterations and a random salt, and the resulting value is used as an AES key. When sharding is enabled, an additional AES key is randomly generated and the 2 keys are combined using a sha256 HMAC into the final AES key.

The private key is then encrypted with AES256-GCM and stored in the file along with the sharding information, the key share (if applicable), the AES initialization vector, the PBKDF2 salt and iteration count and the AES-GCM authentication tag.

Import Seed

The --seed flag enables you to import a wallet generated elsewhere. For example, you may want to import you key from the mobile wallet, so that you can submit transactions that may not be supported in the mobile wallet.

Enter the command:

$ helium-wallet create basic --seed mobile

After you press enter, you will be prompted for your seed words.

tip

Remember, your seed is your private key. Keep it safe and private. When you import the seed as a CLI wallet, you do not "log yourself out" of your mobile wallet; you've only copied the private key from your mobile wallet into the CLI. Mobile wallet and CLI wallet both have a local copies of the key and can submit transactions to the blockchain API.

Pay Transaction Example

If you explore the pay command, you will see the following:

$ helium-wallet pay --help

helium-wallet-pay 1.6.0
Send one (or more) payments to given addresses.

The payment is not submitted to the system unless the '--commit' option is given.

USAGE:
helium-wallet pay [FLAGS] [OPTIONS] <SUBCOMMAND>

FLAGS:
    --commit
        Commit the payment to the API
    -h, --help
        Prints help information
    -V, --version
        Prints version information

[..]

SUBCOMMANDS:
help     Prints this message or the help of the given subcommand(s)
multi    Multiple payees (requires file input). Check "helium-wallet pay multi --help" for details
one      Single payee

Let's explore the one subcommand to figure out usage for a single payment:

$ helium-wallet pay one --help

helium-wallet-pay-one 1.6.0
Single payee

USAGE:
    helium-wallet pay one [OPTIONS] <address> <amount>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
        --memo <memo>    Memo field to include. Provide as a base64 encoded string [default: AAAAAAAAAAA=]

ARGS:
    <address>    Address to send the tokens to
    <amount>     Amount of HNT to send

The USAGE section is is very helpful: helium-wallet pay one [OPTIONS] <address> <amount>.

For example, if I want to send 5.0 HNT to 14GWyFj9FjLHzoN3aX7Tq7PL6fEg4dfWPY8CrK8b9S5ZrcKDz5S, it would look like this:

helium-wallet pay one 14GWyFj9FjLHzoN3aX7Tq7PL6fEg4dfWPY8CrK8b9S5ZrcKDz5S 5 --commit

The --commit FLAG is a global option to the pay command - you'll recall it was documented at the scope of helium-wallet pay --help. It's critical for all transactions to confirm that you want the transaction to be submitted to the blockchain API.

When you commit a transaction to the API, you will be provided with a transaction hash. This is a unique identifier for your transaction on the blockchain and you can track your transcation status using the API endpoint:

https://api.helium.io/v1/pending_transactions/YOUR_HASH_HERE

Transfer Hotspot from 24-word Wallet

If a Hotspot is transferred to a 24-word wallet, that is ok! However, most Maker Hotspot Management Apps do not currently support 24-word wallets.

To transfer a Hotspot from a 24-word wallet to a 12-word wallet, follow the steps below.

Create a 12-word wallet to receive the Hotspot using the Helium Hotspot App and record the Public Key.
Download and install the Helium Command Line Wallet as outlined above. and navigate to the installation directory.
Import your 24-word seed phrase to the CLI Wallet.

./helium-wallet create basic --seed bip39 --output my-24-word-wallet.key

argument	description
`create basic`	create a wallet with a single key, as opposed to a sharded wallet
`--seed bip39`	import with an existing seed phrase using the `bip39` word list
`--output my-24-word-wallet.key`	output the wallet key file to a location of your choosing, in this case to a file called `my-24-word-wallet.key`

Find the Gateway ID of the Hotspot to be transferred by running

./helium-wallet hotspots list

Perform a Dry Run of the Hotspot transfer

./helium-wallet -f my-24-word-wallet.key hotspots transfer <gateway> <new-owner>

argument	description
`-f my-24-word-wallet.key`	use a file for the Hotspot wallet, in this case `my-24-word-wallet.key`
`hotspots transfer`	run a Hotspot transfer
`<gateway>`	the gateway id you collected from Step 4 above
`<new-owner>`	the public Wallet Address to receive the Hotspot

The above will do a test try and have an output you should verify.
Now it's time to run it for real.

Point of No Return

Including the --commit flag submits the transfer transaction to the blockchain.

There is no going back from this so please take your time and double-check your inputs.

./helium-wallet -f my-24-word-wallet.key hotspots transfer <gateway> <new-owner> --commit

Once the transfer transaction is validated by the blockchain, your Hotspot will appear in the new 12-word wallet.