Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The Harmony CLI tool is used to interact with the Harmony blockchain.
Throughout this guide, we will use the following syntax:
./hmy: This is the CLI program
./hmy.sh -- : This is the command to use the CLI with a shell wrapper (for macOS)
<argument>: This is a required argument
[argument]: This is an optional argument
/ : This is a line break, used to break up a line while writing a command
Enter the following command into your shell of choice:
If you have permission issues, enter the commands with "sudo" at the beginning, i.e. "sudo curl -LO https://harmony.one/hmycli && mv hmycli hmy && chmod +x hmy"
hmy depends on some dynamic libraries, hence we recommend using the shell wrapper. Enter there commands into your terminal:
Now you can use hmy.sh as a wrapper over hmy and you should assume that all references to hmy in these documents refer to hmy.sh. For example, the command ./hmy becomes ./hmy.sh -- .
Note that since hmy is not statically linked, you cannot arbitrarily move hmy.sh to anywhere on your filesystem like you could with a single binary.
If you are interested in compiling from source, then the process is more involved.
Steps:
Clone the repository at the same level as the main Harmony repo:
Then setup the build flags:
Call make in the go-sdk repo. This builds a binary named hmy:
Congratulations! You can now use the binary to run the CLI.
hmy is the official Command Line Interface (CLI) provided by Harmony. You can use it as a local wallet and as a way to interact with your Ledger Nano device. The hmy CLI is completely open-source. You can track its development and post any issues encountered and your feature suggestions .
With the hmy CLI you can create a wallet, check your balance, send signed transactions to the Harmony blockchain, look up previous transactions, recover keys from previous mnemonics, create new keystores, and create new BLS keys.
OSX: main development platform
Linux: tested
Windows: tested/working under Windows Subsystem for Linux (WSL)
We will always upload the latest production release on and announce future uploads in pre-production releases.
Perhaps the most important feature of the hmy CLI is the ability to create and send signed transactions to the Harmony blockchain.
Check for finality of the transaction by using the transaction hash like so:
Let's first check what chain-ids are available for us to use, we can do that easily with:
Notice that the output is pretty printed JSON, most outputs of hmy are JSON encoded and hmy defaults to showing it nicely indented. Sometimes though you might want to turn that off, you can do that for any command with the flag --no-pretty.
By default, hmy assumes the testnet chain-id; override that with the --chain-id flag
We'll use the transfer subcommand of hmy to send a transaction.
Notice that simply invoking the transfer subcommand gave us an error message about certain flags not being set. We'll need to provide legitimate values for these flags for our transaction to proceed successfully. Reading off the flags in the error message from left to right, the semantic meanings are as follows:
amount: The quantity of Harmony One token to transfer from the senders to the receiver
from: The sender's one address
from-shard: Shard from which sender's balance will be drawn from
to: Receiver's ONE address
to-shard: Shard in which receiver will receive the amount sent by the sender
passphrase: your wallet passphrase, which is prompted when you hit enter (or you can use a txt file with password and add it: --passphrase file.txt)
A sharded blockchain is a new kind of blockchain architecture where the network is partitioned into sub-networks called shards. Sharding is one of the distinguishing features of Harmony and it is key to solving the traditional scalability problems encountered in other blockchain protocols.
Note: The same ONE address will have a different balance in each shard. Currently Harmony mainnet has four shards while testnet has three shards. Sending a transaction from one shard to another is called a "cross-shard transaction."
Thus, a correct usage of transfer looks like:
hmy assumes that the private keys needed for signing the transaction on behalf of the sender (one1yc06ghr2p8xnl2380kpfayweguuhxdtupkhqzw in this example) exist in the local keystore or in the hardware wallet if the --ledger flag was used.
The sender's account must have enough of a balance on the from-shard to send a transaction. In our example,one1yc06ghr2p8xnl2380kpfayweguuhxdtupkhqzw must have an amount balance of at least 10 in shard 0.
Try out your transaction with the flag --dry-run, this flag tells hmy to create, cryptographically sign the transaction but not actually send it off. Sender's balances are checked and the output is a JSON dump of the signed transaction.
Signing and sending a transaction is very quick, about 2 seconds maximum. The actual sending of the transaction is done via an RPC (Remote Procedure Call), you'll notice that we did not explicitly say where to send the transaction to. This is because the default destination of the RPC call goes to http://localhost:9500, the default HTTP RPC server running when you start a local harmony blockchain. For real world usage though, you'll want a different location. You can control that with the --node flag (see the top of this page for an example).
Once an RPC machine receives a transaction, it sends you back a transaction hash. This transaction hash is the key identifier used when querying the blockchain for transactions.
Simply having a transaction hash does NOT imply that the transaction was successfully accepted by the blockchain. A transaction is successfully accepted once it has been added to the blockchain. In the case of cross-shard transactions (when the from-shard, to-shard values are different), this means each shard has added the transaction to their blockchain.
We can pull down details of the finalized transaction with ./hmy blockchain transaction-receipt as well:
If the transaction has not finalized then the "result" key in the JSON output will have value of null.
You can tell hmy to wait until transaction confirmation by providing a positive integer value to flag --wait-for-confirm. For example, --wait-for-confirm=10 will try checking the receipt of the transaction for 10 seconds.
You should set the value of --node to the same shard that sent the transaction, notice that the URL we used, https://api.s0.t.hmny.io contained s0, this means that this URL is targeting shard 0. For further information, see .
if you want a full list of commands the hmy tool knows in markdown format, please run the following command:
Then in the same directory, hmy creates a directory named hmy-docs in which you can find all markdown files for the commands and subcommands.
Deletion of a one account is possible by issuing the below command
Be sure to have saved your private keys before if you had fund in that account. Deleting the account without backing it up means you'll lose it forever.
hmy provides several subcommands under the blockchain subcommand which let you query the blockchain.
The Harmony blockchain is a sharded blockchain, therefore some commands depend on which shard you target. The shard you target when querying is controlled by the --node flag. For example, if a transaction is made between shard 0 and shard 1, the transaction receipt must be queried from whichever shard sent the funds - in this case shard 0, so the --node flag would look like this:
For other shards, please replace the s0 with the appropriate shard number - eg. s1 for shard 1, s2 for shard 2 etc.
By using ./hmy blockchain help command we can see that the following options are available:
block-by-number - get a harmony blockchain block by block number
current-nonce - current nonce of an account delegation information about delegations
known-chains - print out the known chain-ids
latest-header - get the latest header
median-stake - median stake of top 320 validators with delegations applied stake (pre-epos processing)
protocol-version - the version of the Harmony Protocol
transaction-by-hash - get transaction by hash
transaction-receipt - get information about a finalized transaction validator information about validators
pool - get transaction pool information
Here are some examples of the above commands that you will use frequently:
Checking the hash of your transaction to see the transaction data and if the transaction has been completed
Get information about a finalized transaction:
Checking the network status, last block, epoch, leaders, based on the shard number:
Note the block-number provided must be in hex with a 0x prefix.
For example if you call latest-header and get a result of 10657 you convert this to hex which is 29A1 and then use the value 0x29A1 for block-number. This can be done using
printf '0x%x\n' 10617 #0X29a1
The easiest way to get detailed help is to use the cli itself. For example below is the cookbook which gives an overview of various commands.
By default, cookbook will show the mainnet shard 0 (https://api.s0.t.hmny.io) RPC endpoint. Use the parameter --node="<RPC>" so the example would show the s0 in the targeted network, example ./hmy cookbook --node="https://api.s1.os.hmny.io" would show s0 in OSTN
Here is the list of failed transaction messages which can be checked by querying your transaction hash, checking the transaction hash on explorer or checking the blockchain pool transactions.
Here is how with the hmy cli :
failed messages are network and shard specifics, please use the shard you were sending the transaction from and change the --node value accordingly. Mainnet example on shard 1 would be : https://api.s1.t.hmny.io
You can delegate tokens to a validator using the following command:
The CLI will ask for the passphrase for the delegator-addr keystore file.
--delegator-addr is the ONE address of the delegator (string)
--validator-addr is the ONE address of the validator (string)
--amount is the number of ONE tokens to delegate to the validator (float)
As a validator, if you want to increase your stake, you will have to delegate to yourself. For delegating to your own validator, delegator-addr and validator-addr will be the same.
You can un-delegate tokens from a validator using the following command:
The CLI will ask for the passphrase for the delegator-addr keystore file.
--delegator-addr is the ONE address of the delegator (string)
--validator-addr is the ONE address of the validator (string)
--amount is the number of ONE tokens to un-delegate (float)
As a validator, for un-delegating from your own validator, delegator-addr and validator-addr will be the same.
You can collect your block rewards with the following command:
The CLI will prompt your for the passphrase of the delegation account.
--delegator-addr is the account to collect rewards for
You can only collect ALL of your block rewards at once, not partially.
When we mention the binary, we are referencing the ./hmy binary from the .
When we mention the shell scripts, we are referencing the ./hmy.sh shell script from the
Creation of a new account is done as a function of a generated bip39 mnemonic with 256 bits of entropy. You must provide an account alias name.
Write/store this seed phrase in a safe place. it is the only way to recover your account if you ever forget your password.
This creates a keystore at the following directory:(hmy keys location)/account-name1/UTC--2019-09-16T21-25-35.297331000Z--678e7ea3dcb5f4e9724c0e761843572f10c49b73
When creating keys this way, hmy will ask you to provide a passphrase. Make sure you keep track of this passphrase for future use because the passphrase is used to decrypt the keystore when signing transactions. Also make sure you save the seed phrase, also called a mnemonic.
If you don't provide a passphrase using the --passphrase flag, the default passphrase is an empty string "". The passphrase is used to decrypt the keystore when signing transactions.
To know where your wallet file has been created, run the following command:
You can check the list of wallets (local accounts) with the following command:
You might have an existing keystore made by Harmony's old wallet.sh program that ends with ".key" in the file name (example):
one16qsd5ant9v94jrs89mruzx62h7ekcfxmduh2rx.key
Or that starts with "UTC" in the file name (example):
UTC--2020-01-15T01-02-06.606670000Z--9689a0711642bf08ea92ed98d552f0c1b8c8cefb
Both these files can be imported into hmy using the command import-ks as shown below.
Note that the --passphrase flag only enables a password prompt after the command is entered, there are no other arguments necessary here (if you dont put --passphrase flag in the command it will assume no password needed and will not prompt you for one, which basically means that your wallet keyfile will not be password protected!).
Keep in mind that you should know the passphrase associated with the imported keystore and pass it as a parameter as shown in the commands above. For keystores created by Harmony's wallet.sh, the default passphrase is an empty string; this matters for signing transactions.
Sometimes you might have a secp256k1 private key, such as the one generated from the following command:
You can import the key with an optional name and passphrase
If no account name is provided, a random word concatenated with -imported will be used. If no passphrase is provided, the default passphrase will be used (which is blank). Note that the CLI currently only supports importing secp256k1 private keys.
You can recover lost wallet keys by entering the mnemonic words you received (and hopefully saved) when creating it:
Message
Notes
transaction size is <tx size in Bytes>: oversized data
A transaction cannot be more than 32KB to prevent DDOS attacks
transaction value is <tx value>: negative value
Transaction value is negative
transaction gas is <tx gas-limit>: exceeds block gas limit
Assumed to be hardcoded / config
transaction sender is <tx from addr>: invalid sender
Transaction sent from an invalid account
transaction gas-price is <tx gas-price> ONE: transaction underpriced
Too low transaction fee
transaction nonce is <tx nonce>: nonce too low
Occurs when the nonce associated with that transaction is too lower than the actual nonce
insufficient funds for gas * price + value
Usually when not enough holdings to pay for gas
transaction gas is <tx gas-limit>: intrinsic gas too low
Intrinsic gas is based on the size of the transaction including data
transaction gas-price is <tx gas-price> ONE in full transaction pool: transaction underpriced
Transactions can get dropped if tx pool is full and tx has lowest gas
existing transaction price was not bumped enough: replacement transaction underpriced
If a transaction attempts to replace another with less gas than the original, it will get dropped
old transaction, nonce <tx nonce> is too low
During promotion (from 'future' txs to pending txs in pool) the nonce is checked again
unpayable transaction, out of gas or balance of <acc bal in ONE >cannot pay cost of <cost on ONE>
During promotion (from 'future' txs to pending txs in pool) balance is checked again
exceeds cap for queued transactions for account <one1... address>
Each account has a limit in the number of txs it can put into the tx pool
fairness-exceeding pending transaction
If tx pool is full, txs from accounts with highest number of total transactions in pool will be dropped
exceeds global cap for queued transactions
Occurs when the tx can´t be queued because global cap for queued tx pool exceeds the max
old transaction, nonce <tx nonce> is too low
During demote (from pending txs in pool to 'future' txs) the nonce is checked again
unpayable transaction, out of gas or balance of <acc bal in ONE > cannot pay cost of <cost in ONE>
During demote (from pending txs in pool to 'future' txs) balance is checked again
demoting pending transaction
Tx was not added to the pool and move to queue of 'future' txs