secretcli
is the Secret Network light client, a command-line interface tool for interacting with nodes running on the Secret Network.
How to install and use secretcli
.
- Using Secret CLI
There are four types of key representations:
-
secret
- Derived from account keys generated by
secretcli keys add
- Used to receive funds
- e.g.
secret15h6vd5f0wqps26zjlwrc6chah08ryu4hzzdwhc
- Derived from account keys generated by
-
secretvaloper
- Used to associate a validator to it's operator
- Used to invoke staking commands
- e.g.
secretvaloper1carzvgq3e6y3z5kz5y6gxp3wpy3qdrv928vyah
-
secretpub
- Derived from account keys generated by
secretcli keys add
- e.g.
secretpub1zcjduc3q7fu03jnlu2xpl75s2nkt7krm6grh4cc5aqth73v0zwmea25wj2hsqhlqzm
- Derived from account keys generated by
-
secretvalconspub
- Generated when the node is created with
secretd init
. - Get this value with
secretd tendermint show-validator
- e.g.
secretvalconspub1zcjduepq0ms2738680y72v44tfyqm3c9ppduku8fs6sr73fx7m666sjztznqzp2emf
- Generated when the node is created with
You'll need a private account and public key pair (a.k.a. sk, pk
respectively)\ to be able to receive funds, send txs, bond txs, etc.
To generate a new secp256k1 key:
secretcli keys add <key-alias>
The output of the above command contains a seed phrase. It's recommended to save the seed phrase in a safe place in case you forget the password of the operating system's credentials store.
You can regenerate the key from the seed phrase with the following command:
secretcli keys add --recover <key-alias>
You can also backup your key using export
— which outputs to stderr:
(copy and paste to a <key-export-file>
)
secretcli keys export <key-alias>
and import it with:
secretcli keys import <key-alias> <key-export-file>
If you check your private keys, you'll now see <key-alias>
:
secretcli keys show <key-alias>
If you want to just see your secret address:
secretcli keys show <key-alias> -a
View the validator operator's address via:
secretcli keys show <key-alias> --bech=val
You can see all your available keys by typing:
secretcli keys list
View the validator pubkey for your node by typing:
secretd tendermint show-validator
Note: 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. :::
You can generate and print a multisig public key by typing:
secretcli keys add --multisig=name1,name2,name3[...] --multisig-threshold=K <new-key-alias>
K
is the minimum number of private keys that must have signed the
transactions carrying the public key's address as a signer.
The --multisig
flag must contain the name of public keys to 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 of the supplied keys on the command line
does not matter, i.e. the following commands generate two identical keys:
secretcli keys add --multisig=foo,bar,baz --multisig-threshold=2 <multisig-address>
secretcli keys add --multisig=baz,foo,bar --multisig-threshold=2 <multisig-address>
Multisig addresses can also be generated on-the-fly and printed by typing:
secretcli keys show --multisig-threshold K name1 name2 name3 [...]
For more information on generating, signing and broadcasting transactions using multiple signatures see Multisig Transactions.
When broadcasting transactions, secretcli
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 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.
Each transaction supplies fees or gas prices, but never both.
Validator's have a minimum gas price (multi-denom) configuration used to determine if they should include a transaction in a block during CheckTx
, where gasPrices >= minGasPrices
.
Note: Transactions must supply fees greater than or equal to any fees set by validators. Validators may start to prioritize txs by gasPrice
in the mempool, increasing tx priority based on fees or gas prices.
e.g.
# secretcli tx bank send [from_key_or_address] [to_address] [amount] [flags]
secretcli tx bank send ... --fees=50000uscrt
or
secretcli tx bank send ... --gas-prices=0.0125uscrt
On a testnet, getting tokens is usually done via a faucet. You can get tokens for testing purposes using the Secret Network faucet HERE
After receiving tokens to your address, you can view your account's balance by typing:
secretcli query bank balances <secret-address>
Get your <secret-address>
using:
secretcli keys show -a <key-alias>
(the -a flag is used to display the address only)
You can also supply your address with the following command:
secretcli query bank balances $(secretcli keys show -a <key-alias>)
::: warning Note
When querying an account balance with zero tokens, you will get the error: No account with address <secret-address> was found in the state.
This can also happen if you fund the account before your node is fully synced. These are both normal.
Use the following command to send tokens from one account to another:
secretcli tx bank send <sender-key-alias-or-address> <recipient-address> 10uscrt \
--memo <tx-memo> \
--chain-id=<chain-id>
::: warning Note
The amount
argument accepts the format <value|coin_name>
.
:::
::: tip Note
You may want to cap the maximum gas consumed by transactions via the --gas
flag.
If you pass --gas=auto
, the gas supply is automatically estimated before transaction execution.
Innacurrate gas estimates may occur inbetween the end of the simulation and the actual execution of a transaction. An adjustment needs to be applied on top of the original estimate for the transaction to be broadcasted successfully. Adjustment are controlled via the --gas-adjustment
flag, with a default value of 1.0.
:::
To view updated balances of origin and destination accounts use:
secretcli query bank balances <secret-address>
secretcli query bank balances <recipient-address>
You can also check balances at any block using the --block
flag:
secretcli query bank balances <secret-address> --block=<block_height>
You can simulate a transaction without actually broadcasting it by appending the
--dry-run
flag:
secretcli tx bank send <sender-key-alias-or-address> <recipient-address> 10uscrt \
--chain-id=<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 arguments:
secretcli tx bank send <sender-key-alias-or-address> <recipient-address> 10uscrt \
--chain-id=<chain-id> \
--generate-only > unsignedSendTx.json
secretcli tx sign \
--chain-id=<chain-id> \
--from=<key-alias> \
unsignedSendTx.json > signedSendTx.json
::: tip Note
The --generate-only
flag prevents secretcli
from accessing the local keybase.
When the flag is supplied <sender-key-alias-or-address>
must be an address.
:::
You can validate transaction signatures by typing the following:
secretcli tx sign --validate-signatures --from=<key-alias> signedSendTx.json
You can broadcast the signed transaction to a node by providing the JSON file using:
secretcli tx broadcast --node=<node> signedSendTx.json
Use the transaction search command to query for transactions matching a specific set of events
, which are added on every transaction.
Each event contains a key-value pair in the form of {eventType}.{eventAttribute}={value}
.
Events can be combined to query for more specific results using the &
symbol.
You can query transactions by events
as follows:
secretcli q txs --events='message.sender=secret1...'
And for using multiple events
:
secretcli q txs --events='message.sender=secret1...&message.action=withdraw_delegator_reward'
The pagination is supported as well via page
and limit
:
secretcli q txs --events='message.sender=secret1...' --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:
You can query a single transaction by its hash using the following command:
secretcli q tx [hash]
To upload a contract:
secretcli tx compute store ./contract.wasm.gz --from mykey --source "https://github.com/<username>/<repo>/tarball/<version>" --builder "enigmampc/secret-contract-optimizer:1.0.2"
--source
: Optional tarball of the source code, so your contract will be verifiable.--builder
: Optional docker image used to compile./contract.wasm.gz
, so that your contract will be verifiable. This is important for reproducible builds so you should figure out the exact version ofenigmampc/secret-contract-optimizer
that you were using.
To get the contract's code ID:
secretcli q tx [hash]
secretcli tx compute instantiate $CODE_ID "$INIT_INPUT_MSG" --from mykey --label "$UNIQUE_LABEL"
To get the contract's address:
secretcli q tx [hash]
secretcli tx compute execute $CONTRACT_ADDRESS "$EXEC_INPUT_MSG"
Or:
secretcli tx compute execute --label "$UNIQUE_LABEL" "$EXEC_INPUT_MSG"
secretcli q compute tx [hash]
secretcli q compute query $CONTRACT_ADDRESS "$QUERY_INPUT_MSG"
::: tip Note You can find slashing related CLI commands under Validators/Slashing. :::
You can query for minting/inflation parameters via:
secretcli q mint params
To query for current inflation value:
secretcli q mint inflation
To query for current annual provisions value:
secretcli q mint annual-provisions
::: tip Note You can find CLI commands related to delegating under Delegate. :::
If you are running a full node or a validator node, view the status by typing:
secretcli status
How to run a full node on mainnet.
Governance is the process of Secret Network users coming 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 SCRT
holders on the mainnet.
How to participate in on-chain governance.
To check current distribution parameters, run:
secretcli q distribution params
To query all coins in the community pool under Governance control:
secretcli q distribution community-pool
To check current outstanding (un-withdrawn) rewards, run:
secretcli q distribution validator-outstanding-rewards <validator-address>
To check current outstanding commission for a validator, run:
secretcli q distribution commission <validator-operator-address>
To check historical slashes for a validator, run:
secretcli q distribution slashes <validator-operator-address> <start-height> <end-height>
To check current rewards for a delegation (were they to be withdrawn), run:
secretcli q distribution rewards <delegator-address> <validator-address>
To check all current rewards for a delegation (were they to be withdrawn), run:
secretcli q distribution rewards <delegator-address>
Multisig transactions require signatures of multiple private keys. Generating and signing a transaction from a multisig account involves multiple parties. A multisig transaction is initiated by any key holder, and at least one of them would need to import other parties' public keys into their Keybase and generate a multisig public key to finalize and broadcast the multisig 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
will need to import both p2
and p3
to generate the multisig account public key:
secretcli keys add \
p2 \
--pubkey=secretpub1addwnpepqtd28uwa0yxtwal5223qqr5aqf5y57tc7kk7z8qd4zplrdlk5ez5kdnlrj4
secretcli keys add \
p3 \
--pubkey=secretpub1addwnpepqgj04jpm9wrdml5qnss9kjxkmxzywuklnkj0g3a3f8l5wx9z4ennz84ym5t
secretcli keys add \
p1p2p3 \
--multisig-threshold=2 \
--multisig=p1,p2,p3
When a new multisig public key p1p2p3
has been stored its address will be
used as signer of multisig transactions:
secretcli 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:
secretcli keys show p1p2p3 -o json
secretcli 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 using the following command:
secretcli tx bank send secret1570v2fq3twt0f0x02vhxpuzc9jc4yl30q2qned 1000000uscrt \
--from=<multisig-address> \
--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:
secretcli tx sign \
unsignedTx.json \
--multisig=<multisig-address> \
--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:
secretcli tx sign \
unsignedTx.json \
--multisig=<multisig-address> \
--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:
secretcli tx multisign \
unsignedTx.json \
p1p2p3 \
p1signature.json p2signature.json > signedTx.json
The transaction can now be sent to the node:
secretcli tx broadcast signedTx.json