From 24c5b43b767b666ce34c2a2005dabf111ec8687f Mon Sep 17 00:00:00 2001 From: Mohammed Patla Date: Fri, 9 Oct 2020 22:47:32 -0400 Subject: [PATCH] Documentation for strcli Forked documentation for CLI, that might be helpful. --- straightedgecli.md | 549 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 549 insertions(+) create mode 100644 straightedgecli.md diff --git a/straightedgecli.md b/straightedgecli.md new file mode 100644 index 0000000..a7e843e --- /dev/null +++ b/straightedgecli.md @@ -0,0 +1,549 @@ +# Straightedge Network Light Client + +## Straightedge CLI + +`strcli` is the command-line interface tool that enables you to interact with a node that runs on the Straightedge Network. + +### Keys + +#### Key Types + +There are three types of key representations that are used: + +- `str` + - Derived from account keys generated by `./strcli keys add` + - Used to receive funds + - e.g. `str15h6vd5f0wqps26zjlwrc6chah08ryu4hzzdwhc` + +* `strvaloper` + - Used to associate a validator to it's operator + - Used to invoke staking commands + - e.g. `strvaloper1carzvgq3e6y3z5kz5y6gxp3wpy3qdrv928vyah` + +- `strpub` + + - Derived from account keys generated by `./strcli keys add` + - e.g. `strpub1zcjduc3q7fu03jnlu2xpl75s2nkt7krm6grh4cc5aqth73v0zwmea25wj2hsqhlqzm` + +- `strvalconspub` + - Generated when the node is created with `strd init`. + - Get this value with `strd tendermint show-validator` + - e.g. `strvalconspub1zcjduepq0ms2738680y72v44tfyqm3c9ppduku8fs6sr73fx7m666sjztznqzp2emf` + +#### Generate Keys + +You'll need an account private and public key pair \(a.k.a. `sk, pk` respectively\) to be able to receive funds, send txs, bond tx, etc. + +To generate a new _secp256k1_ key: + +```bash +./strcli keys add +``` + +The output of the above command will contain a _seed phrase_. It is recommended to save the _seed phrase_ in a safe place so that in case you forget the password of the operating system's credentials store, you could eventually regenerate the key from the seed phrase with the following command: + +```bash +./strcli keys add --recover +``` + +You can also backup your key using `export`, which outputs to _stderr_: + +_(copy and paste to a ``)_ + +```bash +./strcli keys export +``` + +and import it with: + +```bash +./strcli keys import +``` + +If you check your private keys, you'll now see ``: + +```bash +./strcli keys show +``` + +If you want to just see your str address: + +```bash +./strcli keys show -a +``` + +View the validator operator's address via: + +```bash +./strcli keys show --bech=val +``` + +You can see all your available keys by typing: + +```bash +./strcli keys list +``` + +View the validator pubkey for your node by typing: + +```bash +strd tendermint show-validator +``` + +Note that this is the Tendermint signing key, _not_ the operator key you will use in delegation transactions. + +::: danger Warning +We strongly recommend _NOT_ using the same passphrase for multiple keys. The Tendermint team and the Interchain Foundation will not be responsible for the loss of funds. +::: + +#### Generate Multisig Public Keys + +You can generate and print a multisig public key by typing: + +```bash +./strcli keys add --multisig=name1,name2,name3[...] --multisig-threshold=K +``` + +`K` is the minimum number of private keys that must have signed the +transactions that carry the public key's address as signer. + +The `--multisig` flag must contain the name of public keys that will be combined into a +public key that will be generated and stored as `new-key-alias` in the local database. +All names supplied through `--multisig` must already exist in the local database. Unless +the flag `--nosort` is set, the order in which the keys are supplied on the command line +does not matter, i.e. the following commands generate two identical keys: + +```bash +./strcli keys add --multisig=foo,bar,baz --multisig-threshold=2 +./strcli keys add --multisig=baz,foo,bar --multisig-threshold=2 +``` + +Multisig addresses can also be generated on-the-fly and printed through the which command: + +```bash +./strcli keys show --multisig-threshold K name1 name2 name3 [...] +``` + +For more information regarding how to generate, sign and broadcast transactions with a multi-signature account see [Multisig Transactions](#multisig-transactions). + +### Tx Broadcasting + +When broadcasting transactions, `strcli` accepts a `--broadcast-mode` flag. This +flag can have a value of `sync` (default), `async`, or `block`, where `sync` makes +the client return a CheckTx response, `async` makes the client return immediately, +and `block` makes the client wait for the tx to be committed (or timing out). + +It is important to note that the `block` mode should **not** be used in most +circumstances. This is because broadcasting can timeout but the tx may still be +included in a block. This can result in many undesirable situations. Therefore, it +is best to use `sync` or `async` and query by tx hash to determine when the tx +is included in a block. + +### Fees & Gas + +Each transaction may either supply fees or gas prices, but not both. + +Validator's have a minimum gas price (multi-denom) configuration and they use +this value when when determining if they should include the transaction in a block during `CheckTx`, where `gasPrices >= minGasPrices`. Note, your transaction must supply fees that are greater than or equal to **any** of the denominations the validator requires. + +**Note**: With such a mechanism in place, validators may start to prioritize +txs by `gasPrice` in the mempool, so providing higher fees or gas prices may yield higher tx priority. + +e.g. + +```bash +./strcli tx send ... --fees=50000astr +``` + +or + +```bash +./strcli tx send ... --gas-prices=0.025astr +``` + +### Account + +#### Get Tokens + +On a testnet, getting tokens is usually done via a faucet. + +#### Query Account Balance + +After receiving tokens to your address, you can view your account's balance by typing: + +```bash +./strcli q account +``` + +Get your `` using: + +```bash +./strcli keys show -a +``` + +(the _-a_ flag is used to display the address only) + +Optionally, you can supply your address within the command as: + +```bash +./strcli q account $(./strcli keys show -a ) +``` + +::: warning Note +When you query an account balance with zero tokens, you will get this error: `No account with address was found in the state.` This can also happen if you fund the account before your node has fully synced with the chain. These are both normal. + +### Send Tokens + +The following command could be used to send coins from one account to another: + +```bash +./strcli tx send 10astr \ + --memo \ + --chain-id= +``` + +::: warning Note +The `amount` argument accepts the format ``. +::: + +::: tip Note +You may want to cap the maximum gas that can be consumed by the transaction via the `--gas` flag. + +If you pass `--gas=auto`, the gas supply will be automatically estimated before executing the transaction. + +Gas estimate might be inaccurate as state changes could occur in between the end of the simulation and the actual execution of a transaction, thus an adjustment is applied on top of the original estimate in order to ensure the transaction is broadcasted successfully. The adjustment can be controlled via the `--gas-adjustment` flag, whose default value is 1.0. +::: + +Now, view the updated balances of the origin and destination accounts: + +```bash +./strcli q account +./strcli q account +``` + +You can also check your balance at a given block by using the `--block` flag: + +```bash +./strcli q account --block= +``` + +You can simulate a transaction without actually broadcasting it by appending the +`--dry-run` flag to the command line: + +```bash +./strcli tx send 10astr \ + --chain-id= \ + --dry-run +``` + +Furthermore, you can build a transaction and print its JSON format to STDOUT by +appending `--generate-only` to the list of the command line arguments: + +```bash +./strcli tx send 10astr \ + --chain-id= \ + --generate-only > unsignedSendTx.json +``` + +```bash +./strcli tx sign \ + --chain-id= \ + --from= \ + unsignedSendTx.json > signedSendTx.json +``` + +::: tip Note +The `--generate-only` flag prevents `strcli` from accessing the local keybase. +Thus when such flag is supplied `` must be an address. +::: + +You can validate the transaction's signatures by typing the following: + +```bash +./strcli tx sign --validate-signatures --from= signedSendTx.json +``` + +You can broadcast the signed transaction to a node by providing the JSON file to the following command: + +```bash +./strcli tx broadcast --node= signedSendTx.json +``` + +### Query Transactions + +#### Matching a Set of Events + +You can use the transaction search command to query for transactions that match a specific set of `events`, which are added on every transaction. + +Each event is composed by a key-value pair in the form of `{eventType}.{eventAttribute}={value}`. + +Events can also be combined to query for a more specific result using the `&` symbol. + +You can query transactions by `events` as follows: + +```bash +./strcli q txs --events='message.sender=str1...' +``` + +And for using multiple `events`: + +```bash +./strcli q txs --events='message.sender=str1...&message.action=withdraw_delegator_reward' +``` + +The pagination is supported as well via `page` and `limit`: + +```bash +./strcli q txs --events='message.sender=str1...' --page=1 --limit=20 +``` + +::: tip Note + +The action tag always equals the message type returned by the `Type()` function of the relevant message. + +You can find a list of available `events` on each of the SDK modules: + +- [Staking events](https://github.com/cosmos/cosmos-sdk/blob/master/x/staking/spec/07_events.md) +- [Governance events](https://github.com/cosmos/cosmos-sdk/blob/master/x/gov/spec/04_events.md) +- [Slashing events](https://github.com/cosmos/cosmos-sdk/blob/master/x/slashing/spec/06_events.md) +- [Distribution events](https://github.com/cosmos/cosmos-sdk/blob/master/x/distribution/spec/06_events.md) +- [Bank events](https://github.com/cosmos/cosmos-sdk/blob/master/x/bank/spec/04_events.md) + ::: + +#### Matching a Transaction's Hash + +You can also query a single transaction by its hash using the following command: + +```bash +./strcli q tx [hash] +``` + +### Slashing + +::: tip Note +You can find Slashing related CLI commands under +[Validators/Slashing](join-validator-mainnet.md#Slashing). +::: + +### Minting + +You can query for the minting/inflation parameters via: + +```bash +./strcli q mint params +``` + +To query for the current inflation value: + +```bash +./strcli q mint inflation +``` + +To query for the current annual provisions value: + +```bash +./strcli q mint annual-provisions +``` + +### Staking + +::: tip Note +You can find CLI commands related to delegating under +[Delegate](delegating-mainnet.md). +::: + +### Nodes + +If you are running a full node or a validator node, view the status by typing: + +```bash +./strcli status +``` + +[How to run a full node on mainnet](run-full-node-mainnet.md). + +### Governance + +Governance is the process from which users in the Straightedge Network can come to consensus +on software upgrades, parameters of the mainnet or signaling mechanisms through +text proposals. This is done through voting on proposals, which will be submitted +by `STR` holders on the mainnet. + +[How to participate in on-chain governance](../protocol/governance.md). + +### Fee Distribution + +#### Query Distribution Parameters + +To check the current distribution parameters, run: + +```bash +./strcli q distribution params +``` + +#### Query distribution Community Pool + +To query all coins in the community pool which is under Governance control: + +```bash +./strcli q distribution community-pool +``` + +#### Query Outstanding Validator rewards + +To check the current outstanding (un-withdrawn) rewards, run: + +```bash +./strcli q distribution validator-outstanding-rewards +``` + +#### Query Validator Commission + +To check the current outstanding commission for a validator, run: + +```bash +./strcli q distribution commission +``` + +#### Query Validator Slashes + +To check historical slashes for a validator, run: + +```bash +./strcli q distribution slashes +``` + +#### Query Delegator Rewards + +To check current rewards for a delegation (were they to be withdrawn), run: + +```bash +./strcli q distribution rewards +``` + +#### Query All Delegator Rewards + +To check all current rewards for a delegation (were they to be withdrawn), run: + +```bash +./strcli q distribution rewards +``` + +### Multisig Transactions + +Multisig transactions require signatures of multiple private keys. Thus, generating and signing a transaction from a multisig account involve cooperation among the parties involved. A multisig transaction can be initiated by any of the key holders, and at least one of them would need to import other parties' public keys into their Keybase and generate a multisig public key in order to finalize and broadcast the transaction. + +For example, given a multisig key comprising the keys `p1`, `p2`, and `p3`, each of which is held by a distinct party, the user holding `p1` would require to import both `p2` and `p3` in order to generate the multisig account public key: + +```bash +./strcli keys add \ + p2 \ + --pubkey=strpub1addwnpepqtd28uwa0yxtwal5223qqr5aqf5y57tc7kk7z8qd4zplrdlk5ez5kdnlrj4 + +./strcli keys add \ + p3 \ + --pubkey=strpub1addwnpepqgj04jpm9wrdml5qnss9kjxkmxzywuklnkj0g3a3f8l5wx9z4ennz84ym5t + +./strcli keys add \ + p1p2p3 \ + --multisig-threshold=2 \ + --multisig=p1,p2,p3 +``` + +A new multisig public key `p1p2p3` has been stored, and its address will be +used as signer of multisig transactions: + +```bash +./strcli keys show p1p2p3 -a +``` + +You may also view multisig threshold, pubkey constituents and respective weights +by viewing the JSON output of the key or passing the `--show-multisig` flag: + +```bash +./strcli keys show p1p2p3 -o json + +./strcli keys show p1p2p3 --show-multisig +``` + +The first step to create a multisig transaction is to initiate it on behalf +of the multisig address created above: + +```bash +./strcli tx send str1570v2fq3twt0f0x02vhxpuzc9jc4yl30q2qned 1000000astr \ + --from= \ + --generate-only > unsignedTx.json +``` + +The file `unsignedTx.json` contains the unsigned transaction encoded in JSON. +`p1` can now sign the transaction with its own private key: + +```bash +./strcli tx sign \ + unsignedTx.json \ + --multisig= \ + --from=p1 \ + --output-document=p1signature.json +``` + +Once the signature is generated, `p1` transmits both `unsignedTx.json` and +`p1signature.json` to `p2` or `p3`, which in turn will generate their +respective signature: + +```bash +./strcli tx sign \ + unsignedTx.json \ + --multisig= \ + --from=p2 \ + --output-document=p2signature.json +``` + +`p1p2p3` is a 2-of-3 multisig key, therefore one additional signature +is sufficient. Any the key holders can now generate the multisig +transaction by combining the required signature files: + +```bash +./strcli tx multisign \ + unsignedTx.json \ + p1p2p3 \ + p1signature.json p2signature.json > signedTx.json +``` + +The transaction can now be sent to the node: + +```bash +./strcli tx broadcast signedTx.json +``` + +## Shells Completion Scripts + +Completion scripts for popular UNIX shell interpreters such as `Bash` and `Zsh` +can be generated through the `completion` command, which is available for both +`strd` and `strcli`. + +If you want to generate `Bash` completion scripts run the following command: + +```bash +strd completion > strd_completion +./strcli completion > strcli_completion +``` + +If you want to generate `Zsh` completion scripts run the following command: + +```bash +strd completion --zsh > strd_completion +./strcli completion --zsh > strcli_completion +``` + +::: tip Note +On most UNIX systems, such scripts may be loaded in `.bashrc` or +`.bash_profile` to enable Bash autocompletion: + +```bash +echo '. strd_completion' >> ~/.bashrc +echo '. strcli_completion' >> ~/.bashrc +``` + +Refer to the user's manual of your interpreter provided by your +operating system for information on how to enable shell autocompletion. +:::