Harmony's go-sdk

This is a go layer on top of the Harmony RPC, included is a CLI tool that you can build with a simple invocation of make

See https://docs.harmony.one/sdk-wiki/command-line-interface/using-the-harmony-cli-tool for detailed documentation on how to use the hmy CLI tools

Build

Working directly on this repo can be challenging because of the upstream dependencies. Follow the README in the main repo for an already ready development environment: https://github.com/harmony-one/harmony/blob/master/README.md.

...for the impatient:

$ docker run -it  harmonyone/main:stable /bin/bash
$ cd ../go-sdk
$ git pull -r origin master
$ make

Usage & Examples

hmy implements a fluent API, that is, there is a hierarchy of commands.

bash completions

once built, add hmy to your path and add to your .bashrc

. <(hmy completion)

invoke the following command to see the most command usages of hmy

$ hmy cookbook

Cookbook of Usage

Note:

1) Every subcommand recognizes a '--help' flag
2) If a passphrase is used by a subcommand, one can enter their own passphrase interactively
   with the --passphrase option. Alternatively, one can pass their own passphrase via a file
   using the --passphrase-file option. If no passphrase option is selected, the default
   passphrase of '' is used.
3) These examples use shard 1 of testnet as argument for --node

Examples:

1.  Check account balance on given chain
hmy --node="https://api.s1.p.hmny.io/" balances <SOME_ONE_ADDRESS>

2.  Check sent transaction
hmy --node="https://api.s1.p.hmny.io" blockchain transaction-by-hash <SOME_TX_HASH>

3.  List local account keys
hmy keys list

4.  Sending a transaction (add `--wait-for-confirm=10` to wait 10 seconds for confirmation)
hmy --node="https://api.s1.p.hmny.io/" transfer \
    --from one1yc06ghr2p8xnl2380kpfayweguuhxdtupkhqzw \
    --to one1q6gkzcap0uruuu8r6sldxuu47pd4ww9w9t7tg6 \
    --from-shard 0 --to-shard 1 --amount 200

5.  Sending a batch of transactions as dictated from a file (the `--wait-for-confirm` and `--dry-run` options still apply)
hmy --node="https://api.s1.p.hmny.io/" transfer --file <PATH_TO_JSON_FILE>

    Example of JSON file format:
      [
        {
          "from": "one103q7qe5t2505lypvltkqtddaef5tzfxwsse4z7",
          "to": "one1zksj3evekayy90xt4psrz8h6j2v3hla4qwz4ur",
          "from-shard" : "0",
          "to-shard": "0",
          "amount": "1",
          "passphrase-string": "",
          "nonce": "-1",
          "stop-on-error": true
        },
        {
          "from": "one103q7qe5t2505lypvltkqtddaef5tzfxwsse4z7",
          "to": "one1zksj3evekayy90xt4psrz8h6j2v3hla4qwz4ur",
          "from-shard" : "0",
          "to-shard": "0",
          "amount": "1",
          "passphrase-file": "./pw.txt"
        }
      ]

6.  Check a completed transaction receipt
hmy --node="https://api.s1.p.hmny.io" blockchain transaction-receipt <SOME_TX_HASH>

7.  Import an account using the mnemonic. Prompts the user to give the mnemonic.
hmy keys add --recover

8.  Import an existing keystore file
hmy keys import-ks <PATH_TO_KEYSTORE_JSON>.key

9.  Import a keystore file using a secp256k1 private key
hmy keys import-private-key <secp256k1_PRIVATE_KEY>

10.  Export a keystore file's secp256k1 private key
hmy keys export-private-key <ACCOUNT_ADDRESS> --passphrase

11. Generate a BLS key then encrypt and save the private key to the specified location.
hmy keys generate-bls-key --bls-file-path /tmp/file.key

12. Create a new validator with a list of BLS keys
hmy --node="https://api.s1.p.hmny.io" staking create-validator --amount 10 --validator-addr <SOME_ONE_ADDRESS> \
    --bls-pubkeys <BLS_KEY_1>,<BLS_KEY_2>,<BLS_KEY_3> \
    --identity foo --details bar --name baz --max-change-rate 0.1 --max-rate 0.1 --max-total-delegation 10 \
    --min-self-delegation 10 --rate 0.1 --security-contact Leo  --website harmony.one --passphrase

13. Edit an existing validator
hmy --node="https://api.s1.p.hmny.io" staking edit-validator \
    --validator-addr <SOME_ONE_ADDRESS> --identity foo --details bar \
    --name baz --security-contact EK --website harmony.one \
    --min-self-delegation 0 --max-total-delegation 10 --rate 0.1\
    --add-bls-key <SOME_BLS_KEY> --remove-bls-key <OTHER_BLS_KEY> --passphrase

14. Delegate an amount to a validator
hmy --node="https://api.s1.p.hmny.io" staking delegate \
    --delegator-addr <SOME_ONE_ADDRESS> --validator-addr <VALIDATOR_ONE_ADDRESS> \
    --amount 10 --passphrase

15. Undelegate to a validator
hmy --node="https://api.s1.p.hmny.io" staking undelegate \
    --delegator-addr <SOME_ONE_ADDRESS> --validator-addr <VALIDATOR_ONE_ADDRESS> \
    --amount 10 --passphrase

16. Collect block rewards as a delegator
hmy --node="https://api.s1.p.hmny.io" staking collect-rewards \
    --delegator-addr <SOME_ONE_ADDRESS> --passphrase

17. Check active validators
hmy --node="https://api.s1.p.hmny.io" blockchain validator all-active

18. Check in-memory record of failed staking transactions
hmy failures staking

Sending batched transactions

One may find it useful to send a batch of transaction with 1 instance of the binary. To do this, one can specify a JSON file with the transaction subcommand to dictate a batch of transaction to send off in sequential order.

Example:

hmy --node="https://api.s1.p.hmny.io/" transfer --file ./batchTransactions.json

Note that the --wait-for-confirm and --dry-run options still apply when sending batched transactions

Transfer JSON file format

The JSON file will be a JSON array where each element has the following attributes:

Key	Value-type	Value-description
from	string	[Required] Sender's one address, must have key in keystore.
to	string	[Required] The receivers one address.
amount	string	[Required] The amount to send in $ONE.
from-shard	string	[Required] The source shard.
to-shard	string	[Required] The destination shard.
passphrase-file	string	[Optional] The file path to file containing the passphrase in plain text. If none is provided, check for passphrase string.
passphrase-string	string	[Optional] The passphrase as a string in plain text. If none is provided, passphrase is ''.
nonce	string	[Optional] The nonce of a specific transaction, default uses nonce from blockchain.
gas-price	string	[Optional] The gas price to pay in NANO (1e-9 of $ONE), default is 1.
gas-limit	string	[Optional] The gas limit, default is 21000.
stop-on-error	boolean	[Optional] If true, stop sending transactions if an error occurred, default is false.

Example of JSON file:

[
  {
    "from": "one103q7qe5t2505lypvltkqtddaef5tzfxwsse4z7",
    "to": "one1zksj3evekayy90xt4psrz8h6j2v3hla4qwz4ur",
    "from-shard" : "0",
    "to-shard": "0",
    "amount": "1",
    "passphrase-string": "",
    "nonce": "35",
    "stop-on-error": true
  },
  {
    "from": "one103q7qe5t2505lypvltkqtddaef5tzfxwsse4z7",
    "to": "one1zksj3evekayy90xt4psrz8h6j2v3hla4qwz4ur",
    "from-shard" : "0",
    "to-shard": "0",
    "amount": "1",
    "passphrase-file": "./pw.txt",
    "gas-price": "1",
    "gas-limit": "21000"
  }
]

Batched transaction response format

The return will be a JSON array where each element is a transaction log. The transaction log has the following attributes:

Key	Value-type	Value-description
transaction-receipt	string	The transaction hash/receipt if the CLI signed and sent a transaction, otherwise this key will not exist
transaction	JSON Object	The transaction parameters if --dry-run is toggled, otherwise this key will not exist.
blockchain-receipt	JSON Object	The transaction receipt from the blockchain if wait-for-confirm is > 0, otherwise this key will not exist.
raw-transaction	string	The raw bytes in hex of a sighed transaction if --dry-run is toggled, otherwise this key will not exist
errors	JSON Array	A JSON array of strings describing any error that occurred during the execution of a transaction. If no errors, this key will not exist.
time-signed-utc	string	The time in UTC as a string of roughly when the transaction was signed. If no signed transaction, this key will not exist.

Example of returned JSON Array:

[
  {
    "errors": [
      "[2020-01-22 22:01:10.819406] strconv.ParseUint: parsing \"-1\": invalid syntax"
    ]
  },
  {
    "transaction-receipt": "0xf1706080ea9ac210ee2c12c69fb310be5a5da99582b7c783e2f741a3536abbfd",
    "blockchain-receipt": {
      "blockHash": "0xe6de09f4e0ca351257d301a50b4e2ca82646473dc1c4302b570bfab17d421850",
      "blockNumber": "0xb71",
      "contractAddress": null,
      "cumulativeGasUsed": "0x5208",
      "from": "one103q7qe5t2505lypvltkqtddaef5tzfxwsse4z7",
      "gasUsed": "0x5208",
      "logs": [],
      "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
      "shardID": 0,
      "status": "0x1",
      "to": "one1zksj3evekayy90xt4psrz8h6j2v3hla4qwz4ur",
      "transactionHash": "0xf1706080ea9ac210ee2c12c69fb310be5a5da99582b7c783e2f741a3536abbfd",
      "transactionIndex": "0x0"
    },
    "time-signed-utc": "2020-01-22 22:01:11.468407"
  }
]

Debugging

The go-sdk code respects HMY_RPC_DEBUG HMY_TX_DEBUG as debugging based environment variables.

HMY_RPC_DEBUG=true HMY_TX_DEBUG=true ./hmy blockchain protocol-version