Interacting with Gaiad (CLI)

Gaia 守护进程

gaiad 是一个工具，使你能够与运行在 Cosmos Hub 网络上的节点交互，无论该节点是否由你自己运行。下面我们来正确完成它的配置。要安装它，请按照安装流程进行操作。

配置 gaiad

用于配置 gaiad 的主要命令如下：

gaiad config <flag> <value>

它允许你为每个指定的 flag 设置默认值。首先，设置你想要连接的全节点地址：

gaiad config node <host>:<port>

如果你运行的是自己的全节点，只需将地址设为 tcp://localhost:26657。最后，设置你要交互的区块链的 chain-id：

gaiad config chain-id cosmoshub-2

密钥

密钥环

密钥环保存了与节点交互所需的私钥/公钥对。例如，在运行区块链节点之前，需要先配置好验证者密钥，以便能够正确对区块进行签名。私钥可以存储在不同的位置，这些位置称为“后端”，例如文件或操作系统自带的密钥存储。对于无头环境，建议使用 file 或 pass 后端。更多信息请参见 SDK 文档页面。

密钥类型

使用的密钥表示形式共有三种：

cosmos
- 由通过 gaiad keys add 生成的账户密钥派生
- 用于接收资金
- 例如：cosmos15h6vd5f0wqps26zjlwrc6chah08ryu4hzzdwhc
cosmosvaloper
- 用于将验证者与其操作员关联
- 用于调用质押命令
- 例如：cosmosvaloper1carzvgq3e6y3z5kz5y6gxp3wpy3qdrv928vyah
cosmospub
- 由通过 gaiad keys add 生成的账户密钥派生
- 例如：cosmospub1zcjduc3q7fu03jnlu2xpl75s2nkt7krm6grh4cc5aqth73v0zwmea25wj2hsqhlqzm
cosmosvalconspub
- 在使用 gaiad init 创建节点时生成。
- 使用 gaiad tendermint show-validator 获取该值
- 例如：cosmosvalconspub1zcjduepq0ms2738680y72v44tfyqm3c9ppduku8fs6sr73fx7m666sjztznqzp2emf

将密钥从旧版磁盘 Keybase 迁移到操作系统内置密钥存储

旧版本的 gaiad 会将密钥存储在用户主目录中。如果你正在从旧版本的 gaiad 迁移，则需要通过运行以下命令，将旧密钥迁移到操作系统的凭据存储中：

gaiad keys migrate

该命令会为每个口令短语进行提示。如果某个口令短语不正确，则会跳过对应的密钥。

生成密钥

你需要一对账户私钥和公钥（分别也称为 sk 和 pk），才能接收资金、发送交易、绑定交易等。要生成一个新的 secp256k1 密钥：

gaiad keys add <account_name>

上述命令的输出会包含一个助记词。建议将该助记词保存在安全的地方，这样如果你忘记了操作系统凭据存储的密码，最终仍可以通过以下命令使用助记词重新生成密钥：

gaiad keys add --recover

如果你查看私钥，现在会看到 <account_name>：

gaiad keys show <account_name>

通过以下命令查看验证者操作员地址：

gaiad keys show <account_name> --bech=val

你可以输入以下命令查看所有可用密钥：

gaiad keys list

输入以下命令查看你节点的验证者公钥：

gaiad tendermint show-validator

请注意，这是 Tendermint 的签名密钥，不是你在委托交易中使用的操作员密钥。

生成多签公钥

你可以通过输入以下命令生成并打印一个多签公钥：

gaiad keys add --multisig=name1,name2,name3[...] --multisig-threshold=K new_key_name

K 是必须对交易进行签名的最小私钥数量，这些交易会将该公钥的地址作为签名者。 --multisig flag 必须包含那些公钥的名称，这些公钥将被组合成一个公钥，并在本地数据库中以 new_key_name 的名称生成和存储。通过 --multisig 提供的所有名称都必须已存在于本地数据库中。除非设置了 --nosort flag，否则命令行中提供密钥的顺序无关紧要，也就是说，以下命令会生成两个完全相同的密钥：

gaiad keys add --multisig=foo,bar,baz --multisig-threshold=2 multisig_address
gaiad keys add --multisig=baz,foo,bar --multisig-threshold=2 multisig_address

多签地址也可以通过以下命令即时生成并打印：

gaiad keys show --multisig-threshold K name1 name2 name3 [...]

有关如何使用多重签名账户生成、签名和广播交易的更多信息，请参见多签交易。

交易广播

在广播交易时，gaiad 接受一个 --broadcast-mode flag。该 flag 可以取值 sync（默认）、async 或 block，其中 sync 会让客户端返回一个 CheckTx 响应，async 会让客户端立即返回，而 block 会让客户端等待交易被提交（或超时）。需要特别注意的是，在大多数情况下都不应使用 block 模式。这是因为广播可能会超时，但交易仍然可能被打包进区块。这会导致许多不理想的情况。因此，最好使用 sync 或 async，并通过交易哈希查询来确定交易何时被打包进区块。

费用与 Gas

Cosmos Hub 使用 x/feemarket 模块根据需求动态调整 gas 价格。你需要指定足够的 gas 价格或总费用，以确保你的交易能够被打包进区块，例如：

gaiad tx bank send ... --fees=50000uatom

或

gaiad tx bank send ... --gas-prices=0.0025uatom

要了解当前的最小 gas 价格，你可以查询 feemarket 模块：

gaiad q feemarket gas-prices

或

gaiad q feemarket gas-prices uatom

输出结果会类似于：

price:
  amount: "0.005"
  denom: uatom

更多信息请参阅如何查询 feemarket，或查看 feemarket 集成指南。

账户

获取代币

在测试网上，获取代币通常是通过水龙头完成的。

查询账户余额

当你的地址收到代币后，可以输入以下命令查看账户余额：

gaiad query account account_cosmos

注意当你查询一个余额为零的账户时，会收到如下错误：No account with address <account_cosmos> was found in the state. 如果你在节点尚未与链完全同步之前就向该账户转入资金，也可能出现这种情况。这两种情况都属于正常现象。

发送代币

以下命令可用于将代币从一个账户发送到另一个账户：

gaiad tx bank send sender_key_name_or_address recipient_address 10faucetToken \
  --chain-id=chain_id

amount 参数接受 value|coin_name 格式。

你可能希望通过 --gas flag 限制交易可消耗的最大 gas。如果传入 --gas=auto，系统会在执行交易前自动估算 gas 用量。 Gas 估算可能并不精确，因为在模拟结束到交易实际执行之间，状态可能发生变化，因此会在原始估算值之上应用一个调整值，以确保交易能够成功广播。该调整值可通过 --gas-adjustment flag 控制，其默认值为 1.0。

现在，查看源账户和目标账户更新后的余额：

gaiad query account account_cosmos
gaiad query account destination_cosmos

你也可以使用 --block flag 查询某个指定区块时的余额：

gaiad query account account_cosmos --block=<block_height>

你可以通过在命令行后附加 --dry-run flag 来模拟一笔交易，而不实际广播它：

gaiad tx bank send <sender_key_name_or_address> <destination_cosmosaccaddr> 10faucetToken \
  --chain-id=<chain_id> \
  --dry-run

此外，你还可以构建一笔交易，并通过在命令行参数中附加 --generate-only，将其 JSON 格式输出到 STDOUT：

gaiad tx bank send <sender_address> <recipient_address> 10faucetToken \
  --chain-id=<chain_id> \
  --generate-only > unsignedSendTx.json

gaiad tx sign \
  --chain-id=<chain_id> \
  --from=<key_name> \
  unsignedSendTx.json > signedSendTx.json

--generate-only flag 会阻止 gaiad 访问本地 keybase。因此，当提供该 flag 时，sender_key_name_or_address 必须是一个地址。

你可以通过输入以下命令来验证交易签名：

gaiad tx sign --validate-signatures signedSendTx.json

你可以通过将 JSON 文件提供给以下命令，将已签名的交易广播到某个节点：

gaiad tx broadcast --node=<node> signedSendTx.json

查询交易

匹配一组事件

你可以使用交易搜索命令查询与特定 events 集合匹配的交易，这些事件会附加到每一笔交易上。每个事件都由一个键值对组成，格式为 {eventType}.{eventAttribute}={value}。事件还可以使用 & 符号组合，以查询更具体的结果。你可以按如下方式通过 events 查询交易：

gaiad query txs --events='message.sender=cosmos1...'

如果要使用多个 events：

gaiad query txs --events='message.sender=cosmos1...&message.action=withdraw_delegator_reward'

也支持通过 page 和 limit 进行分页：

gaiad query txs --events='message.sender=cosmos1...' --page=1 --limit=20

action 标签始终等于相关消息的 Type() 函数返回的消息类型。你可以在各个 SDK 模块中找到可用 events 的列表：

按交易哈希匹配

你也可以使用以下命令通过哈希查询单笔交易：

gaiad query tx [hash]

罚没

解除监禁

解除被监禁的验证者：

gaiad tx slashing unjail --from <validator-operator-addr>

签名信息

获取验证者的签名信息：

gaiad query slashing signing-info <validator-pubkey>

查询参数

你可以通过以下命令获取当前的罚没参数：

gaiad query slashing params

铸币

你可以通过以下命令查询铸币/通胀参数：

gaiad query mint params

查询当前通胀值：

gaiad query mint inflation

查询当前年度增发值：

gaiad query mint annual-provisions

质押

设置验证者

有关如何设置验证者候选的更完整指南，请参见验证者设置部分。

向验证者委托

在即将到来的主网上，你可以将 atom 委托给验证者。这些委托人可以获得验证者手续费收入的一部分。更多信息请参阅 Cosmos 代币模型。

查询验证者

你可以查询某条链上的全部验证者列表：

gaiad query staking validators

如果你想获取单个验证者的信息，可以使用以下命令查看：

gaiad query staking validator <account_cosmosval>

绑定代币

在 Cosmos Hub 主网上，我们委托的是 uatom，其中 1atom = 1000000uatom。以下是如何将代币绑定到测试网验证者（即进行委托）：

gaiad tx staking delegate \
  --amount=10000000uatom \
  --validator=<validator> \
  --from=<key_name> \
  --chain-id=<chain_id>

<validator> 是你打算委托给它的验证者的操作员地址。如果你运行的是本地测试网，可以通过以下命令找到它：

gaiad keys show [name] --bech val

其中 [name] 是你初始化 gaiad 时指定的密钥名称。当代币被绑定后，它们会与网络中所有其他已绑定代币汇集在一起。验证者和委托人会获得相应比例的份额，该比例等于他们在该池中的质押占比。

查询委托

向某个验证者提交委托后，你可以使用以下命令查看其信息：

gaiad query staking delegation <delegator_addr> <validator_addr>

或者，如果你想查看当前对不同验证者的全部委托：

gaiad query staking delegations <delegator_addr>

解绑代币

如果验证者由于某种原因行为不当，或者你只是想解绑一定数量的代币，请使用以下命令。

gaiad tx staking unbond \
  <validator_addr> \
  10atom \
  --from=<key_name> \
  --chain-id=<chain_id>

当解绑期结束后，解绑将自动完成。

查询解绑委托

开始解绑委托后，你可以使用以下命令查看其信息：

gaiad query staking unbonding-delegation <delegator_addr> <validator_addr>

或者，如果你想查看当前对不同验证者的全部解绑委托：

gaiad query staking unbonding-delegations <account_cosmos>

此外，你还可以获取某个特定验证者的全部解绑委托：

gaiad query staking unbonding-delegations-from <account_cosmosval>

重新委托代币

重新委托是一种委托形式，允许你将缺乏流动性的已绑定代币从一个验证者转移到另一个验证者：

gaiad tx staking redelegate \
  <src-validator-operator-addr> \
  <dst-validator-operator-addr> \
  10atom \
  --from=<key_name> \
  --chain-id=<chain_id>

你也可以通过对应的标志重新委托特定的 shares-amount 或 shares-fraction。当解绑期结束后，重新委托将自动完成。

查询重新委托

开始重新委托后，你可以使用以下命令查看其信息：

gaiad query staking redelegation <delegator_addr> <src_val_addr> <dst_val_addr>

或者，如果你想查看当前对不同验证者的全部解绑委托：

gaiad query staking redelegations <account_cosmos>

此外，你还可以获取某个特定验证者发起的全部转出重新委托：

  gaiad query staking redelegations-from <account_cosmosval>

查询参数

参数定义了质押的高级设置。你可以使用以下命令获取当前值：

gaiad query staking params

通过以上命令，你将获得以下值：

解绑时间
验证者最大数量
用于质押的代币面额

所有这些值都可以通过 governance 流程中的 ParameterChange 提案进行更新。

查询资金池

质押 Pool 定义了当前状态的动态参数。你可以使用以下命令查询：

gaiad query staking pool

使用 pool 命令，你将获得以下值：

未绑定和已绑定的代币
代币供应量
当前年化通胀率，以及上一次处理通胀所在的区块
最近记录的已绑定份额

查询向验证者的委托

你也可以查询委托给某个特定验证者的全部委托：

  gaiad query delegations-to <account_cosmosval>

治理

治理是 Cosmos Hub 用户就软件升级、主网参数或通过文本提案进行信号表达等事项达成共识的过程。这是通过对提案进行投票来完成的，这些提案将由主网上的 ATOM 持有者提交。关于投票流程，有以下几点需要注意：

投票由已绑定的 ATOM 持有者按 1 个已绑定 ATOM 对应 1 票的原则进行
如果委托人不投票，则会继承其验证者的投票
投票在投票期结束时统计（主网上为 2 周），在此期间每个地址可以多次投票以更新其 Option 值（每次都需支付交易手续费），只有最近一次投出的票会被计为有效
投票者可以在 Yes、No、NoWithVeto 和 Abstain 这些选项中选择
在投票期结束时，提案仅在满足以下条件时才会通过：
- (YesVotes / (YesVotes+NoVotes+NoWithVetoVotes)) > 1/2
- (NoWithVetoVotes / (YesVotes+NoVotes+NoWithVetoVotes)) < 1/3
- ((YesVotes+NoVotes+NoWithVetoVotes) / totalBondedStake) >= quorum

如需进一步了解治理流程及其工作方式，请参阅治理模块的规范。

创建治理提案

要创建治理提案，你必须提交初始押金，以及标题和描述。治理之外的各个模块可以实现自己的提案类型和处理器（例如参数变更），而治理模块本身支持 Text 提案。所有治理之外模块的命令都挂载在 submit-proposal 之上。提交 Text 提案：

gaiad tx gov submit-proposal \
  --title=<title> \
  --description=<description> \
  --type="Text" \
  --deposit="1000000uatom" \
  --from=<name> \
  --chain-id=<chain_id>

你也可以通过 --proposal 标志直接提供提案，该标志指向一个包含提案内容的 JSON 文件。要提交参数变更提案，你必须提供提案文件，因为其内容不太适合通过 CLI 直接输入：

gaiad tx gov submit-proposal param-change <path/to/proposal.json> \
  --from=<name> \
  --chain-id=<chain_id>

其中 proposal.json 包含以下内容：

{
  "title": "Param Change",
  "description": "Update max validators",
  "changes": [
    {
      "subspace": "staking",
      "key": "MaxValidators",
      "value": 105
    }
  ],
  "deposit": [
    {
      "denom": "stake",
      "amount": "10000000"
    }
  ]
}

SoftwareUpgrade 目前尚不受支持，因为它尚未实现，并且当前在语义上与 Text 提案没有区别。

查询提案

创建完成后，你现在可以查询该提案的信息：

gaiad query gov proposal <proposal_id>

或者查询所有可用提案：

gaiad query gov proposals

你还可以使用相应标志，按 voter 或 depositor 过滤查询提案。要查询某个治理提案的提案人：

gaiad query gov proposer <proposal_id>

增加押金

为了让提案能够广播到网络，存入的金额必须高于 minDeposit 值（初始值：512000000uatom）。如果你之前创建的提案没有达到这个要求，你仍然可以增加总押金额以激活它。一旦达到最小押金要求，提案就会进入投票期：

gaiad tx gov deposit <proposal_id> "10000000uatom" \
  --from=<name> \
  --chain-id=<chain_id>

注意：未满足此要求的提案会在达到 MaxDepositPeriod 后被删除。

查询押金

创建新提案后，你可以查询提交给它的全部押金：

gaiad query gov deposits <proposal_id>

你也可以查询某个特定地址提交的押金：

gaiad query gov deposit <proposal_id> <depositor_address>

对提案投票

当提案押金达到 MinDeposit 值后，投票期就会开启。已绑定的 Atom 持有者随后可以对其投票：

gaiad tx gov vote <proposal_id> <Yes/No/NoWithVeto/Abstain> \
  --from=<name> \
  --chain-id=<chain_id>

查询投票

检查你刚刚提交选项的投票：

gaiad query gov vote <proposal_id> <voter_address>

你也可以使用以下命令获取该提案此前提交的所有投票：

gaiad query gov votes <proposal_id>

查询提案计票结果

要查看某个提案当前的计票结果，可以使用 tally 命令：

gaiad query gov tally <proposal_id>

查询治理参数

要查看当前治理参数，请运行：

gaiad query gov params

要查询治理参数的各个子集，请运行：

gaiad query gov param voting
gaiad query gov param tallying
gaiad query gov param deposit

手续费分配

查询分配参数

要检查当前分配参数，请运行：

gaiad query distribution params

查询分配社区池

要查询受治理控制的社区池中的全部代币：

gaiad query distribution community-pool

查询未提取奖励

要检查当前未提取的奖励，请运行：

gaiad query distribution outstanding-rewards

查询验证者佣金

要检查某个验证者当前未提取的佣金，请运行：

gaiad query distribution commission <validator_address>

查询验证者惩罚记录

要检查某个验证者的历史惩罚记录，请运行：

gaiad query distribution slashes <validator_address> <start_height> <end_height>

查询委托人奖励

要检查某笔委托当前的奖励（如果此时提取的话），请运行：

gaiad query distribution rewards <delegator_address> <validator_address>

查询委托人的全部奖励

要检查某位委托人的当前全部奖励（如果此时提取的话），请运行：

gaiad query distribution rewards <delegator_address>

多重签名交易

多重签名交易需要多个私钥的签名。因此，从多签账户生成并签署一笔交易需要相关各方协作完成。多签交易可以由任意一个密钥持有者发起，并且其中至少有一人需要

Gaia Daemon

gaiad is the tool that enables you to interact with the node that runs on the Cosmos Hub network, whether you run it yourself or not. Let us set it up properly. In order to install it, follow the installation procedure.

Setting up gaiad

The main command used to set up gaiad is the following:

gaiad config <flag> <value>

It allows you to set a default value for each given flag. First, set up the address of the full-node you want to connect to:

gaiad config node <host>:<port>

If you run your own full-node, just use tcp://localhost:26657 as the address. Finally, let us set the chain-id of the blockchain we want to interact with:

gaiad config chain-id cosmoshub-2

Keys

Keyring

The keyring holds the private/public keypairs used to interact with a node. For instance, a validator key needs to be set up before running the blockchain node, so that blocks can be correctly signed. The private key can be stored in different locations, called “backends”, such as a file or the operating system’s own key storage. Headless environments are recommended to use either the file or pass backends. More information is available at the SDK documentation page.

Key Types

There are three types of key representations that are used:

cosmos
- Derived from account keys generated by gaiad keys add
- Used to receive funds
- e.g. cosmos15h6vd5f0wqps26zjlwrc6chah08ryu4hzzdwhc
cosmosvaloper
- Used to associate a validator to its operator
- Used to invoke staking commands
- e.g. cosmosvaloper1carzvgq3e6y3z5kz5y6gxp3wpy3qdrv928vyah
cosmospub
- Derived from account keys generated by gaiad keys add
- e.g. cosmospub1zcjduc3q7fu03jnlu2xpl75s2nkt7krm6grh4cc5aqth73v0zwmea25wj2hsqhlqzm
cosmosvalconspub
- Generated when the node is created with gaiad init.
- Get this value with gaiad tendermint show-validator
- e.g. cosmosvalconspub1zcjduepq0ms2738680y72v44tfyqm3c9ppduku8fs6sr73fx7m666sjztznqzp2emf

Migrate Keys From Legacy On-Disk Keybase To OS Built-in Secret Store

Older versions of gaiad used store keys in the user’s home directory. If you are migrating from an old version of gaiad you will need to migrate your old keys into your operating system’s credentials storage by running the following command:

gaiad keys migrate

The command will prompt for every passphrase. If a passphrase is incorrect, it will skip the respective key.

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:

gaiad keys add <account_name>

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:

gaiad keys add --recover

If you check your private keys, you’ll now see <account_name>:

gaiad keys show <account_name>

View the validator operator’s address via:

gaiad keys show <account_name> --bech=val

You can see all your available keys by typing:

gaiad keys list

View the validator pubkey for your node by typing:

gaiad tendermint show-validator

Note that this is the Tendermint signing key, not the operator key you will use in delegation transactions.

Generate Multisig Public Keys

You can generate and print a multisig public key by typing:

gaiad keys add --multisig=name1,name2,name3[...] --multisig-threshold=K new_key_name

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_name 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:

gaiad keys add --multisig=foo,bar,baz --multisig-threshold=2 multisig_address
gaiad keys add --multisig=baz,foo,bar --multisig-threshold=2 multisig_address

Multisig addresses can also be generated on-the-fly and printed through the which command:

gaiad 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.

Tx Broadcasting

When broadcasting transactions, gaiad 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

The Cosmos Hub uses the x/feemarket module to dynamically vary the gas price based on demand. You need to specify a sufficient gas price or total fees to ensure that your transaction is included in a block, e.g.

gaiad tx bank send ... --fees=50000uatom

gaiad tx bank send ... --gas-prices=0.0025uatom

To find out more about the current minimal gas price, you can query the feemarket module:

gaiad q feemarket gas-prices

gaiad q feemarket gas-prices uatom

which will output the current gas price similar to this:

price:
  amount: "0.005"
  denom: uatom

For more information, check out how to query the feemarket, or check out the feemarket integration guide.

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:

gaiad query account account_cosmos

Note When you query an account balance with zero tokens, you will get this error: No account with address <account_cosmos> 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:

gaiad tx bank send sender_key_name_or_address recipient_address 10faucetToken \
  --chain-id=chain_id

The amount argument accepts the format value|coin_name.

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:

gaiad query account account_cosmos
gaiad query account destination_cosmos

You can also check your balance at a given block by using the --block flag:

gaiad query account account_cosmos --block=<block_height>

You can simulate a transaction without actually broadcasting it by appending the --dry-run flag to the command line:

gaiad tx bank send <sender_key_name_or_address> <destination_cosmosaccaddr> 10faucetToken \
  --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 the command line arguments:

gaiad tx bank send <sender_address> <recipient_address> 10faucetToken \
  --chain-id=<chain_id> \
  --generate-only > unsignedSendTx.json

gaiad tx sign \
  --chain-id=<chain_id> \
  --from=<key_name> \
  unsignedSendTx.json > signedSendTx.json

The --generate-only flag prevents gaiad from accessing the local keybase. Thus when such flag is supplied sender_key_name_or_address must be an address.

You can validate the transaction’s signatures by typing the following:

gaiad tx sign --validate-signatures signedSendTx.json

You can broadcast the signed transaction to a node by providing the JSON file to the following command:

gaiad tx broadcast --node=<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:

gaiad query txs --events='message.sender=cosmos1...'

And for using multiple events:

gaiad query txs --events='message.sender=cosmos1...&message.action=withdraw_delegator_reward'

The pagination is supported as well via page and limit:

gaiad query txs --events='message.sender=cosmos1...' --page=1 --limit=20

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:

Matching a Transaction’s Hash

You can also query a single transaction by its hash using the following command:

gaiad query tx [hash]

Slashing

Unjailing

To unjail your jailed validator

gaiad tx slashing unjail --from <validator-operator-addr>

Signing Info

To retrieve a validator’s signing info:

gaiad query slashing signing-info <validator-pubkey>

Query Parameters

You can get the current slashing parameters via:

gaiad query slashing params

Minting

You can query for the minting/inflation parameters via:

gaiad query mint params

To query for the current inflation value:

gaiad query mint inflation

To query for the current annual provisions value:

gaiad query mint annual-provisions

Staking

Set up a Validator

Please refer to the Validator Setup section for a more complete guide on how to set up a validator-candidate.

Delegate to a Validator

On the upcoming mainnet, you can delegate atom to a validator. These delegators can receive part of the validator’s fee revenue. Read more about the Cosmos Token Model.

Query Validators

You can query the list of all validators of a specific chain:

gaiad query staking validators

If you want to get the information of a single validator you can check it with:

gaiad query staking validator <account_cosmosval>

Bond Tokens

On the Cosmos Hub mainnet, we delegate uatom, where 1atom = 1000000uatom. Here’s how you can bond tokens to a testnet validator (i.e. delegate):

gaiad tx staking delegate \
  --amount=10000000uatom \
  --validator=<validator> \
  --from=<key_name> \
  --chain-id=<chain_id>

<validator> is the operator address of the validator to which you intend to delegate. If you are running a local testnet, you can find this with:

gaiad keys show [name] --bech val

where [name] is the name of the key you specified when you initialized gaiad. While tokens are bonded, they are pooled with all the other bonded tokens in the network. Validators and delegators obtain a percentage of shares that equal their stake in this pool.

Query Delegations

Once submitted a delegation to a validator, you can see its information by using the following command:

gaiad query staking delegation <delegator_addr> <validator_addr>

Or if you want to check all your current delegations with distinct validators:

gaiad query staking delegations <delegator_addr>

Unbond Tokens

If for any reason the validator misbehaves, or you just want to unbond a certain amount of tokens, use the following command.

gaiad tx staking unbond \
  <validator_addr> \
  10atom \
  --from=<key_name> \
  --chain-id=<chain_id>

The unbonding will be automatically completed when the unbonding period has passed.

Query Unbonding-Delegations

Once you begin an unbonding-delegation, you can see it’s information by using the following command:

gaiad query staking unbonding-delegation <delegator_addr> <validator_addr>

Or if you want to check all your current unbonding-delegations with distinct validators:

gaiad query staking unbonding-delegations <account_cosmos>

Additionally, as you can get all the unbonding-delegations from a particular validator:

gaiad query staking unbonding-delegations-from <account_cosmosval>

Redelegate Tokens

A redelegation is a type delegation that allows you to bond illiquid tokens from one validator to another:

gaiad tx staking redelegate \
  <src-validator-operator-addr> \
  <dst-validator-operator-addr> \
  10atom \
  --from=<key_name> \
  --chain-id=<chain_id>

Here you can also redelegate a specific shares-amount or a shares-fraction with the corresponding flags. The redelegation will be automatically completed when the unbonding period has passed.

Query Redelegations

Once you begin a redelegation, you can see its information by using the following command:

gaiad query staking redelegation <delegator_addr> <src_val_addr> <dst_val_addr>

Or if you want to check all your current unbonding-delegations with distinct validators:

gaiad query staking redelegations <account_cosmos>

Additionally, as you can get all the outgoing redelegations from a particular validator:

  gaiad query staking redelegations-from <account_cosmosval>

Query Parameters

Parameters define high level settings for staking. You can get the current values by using:

gaiad query staking params

With the above command you will get the values for:

Unbonding time
Maximum numbers of validators
Coin denomination for staking

All these values will be subject to updates through a governance process by ParameterChange proposals.

Query Pool

A staking Pool defines the dynamic parameters of the current state. You can query them with the following command:

gaiad query staking pool

With the pool command you will get the values for:

Not-bonded and bonded tokens
Token supply
Current annual inflation and the block in which the last inflation was processed
Last recorded bonded shares

Query Delegations To Validator

You can also query all of the delegations to a particular validator:

  gaiad query delegations-to <account_cosmosval>

Governance

Governance is the process from which users in the Cosmos Hub 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 ATOM holders on the mainnet. Some considerations about the voting process:

Voting is done by bonded ATOM holders on a 1 bonded ATOM 1 vote basis
Delegators inherit the vote of their validator if they don’t vote
Votes are tallied at the end of the voting period (2 weeks on mainnet) where each address can vote multiple times to update its Option value (paying the transaction fee each time), only the most recently cast vote will count as valid
Voters can choose between options Yes, No, NoWithVeto and Abstain
At the end of the voting period, a proposal is accepted iff:
- (YesVotes / (YesVotes+NoVotes+NoWithVetoVotes)) > 1/2
- (NoWithVetoVotes / (YesVotes+NoVotes+NoWithVetoVotes)) < 1/3
- ((YesVotes+NoVotes+NoWithVetoVotes) / totalBondedStake) >= quorum

For more information about the governance process and how it works, please check out the Governance module specification.

Create a Governance Proposal

In order to create a governance proposal, you must submit an initial deposit along with a title and description. Various modules outside of governance may implement their own proposal types and handlers (eg. parameter changes), where the governance module itself supports Text proposals. Any module outside of governance has its command mounted on top of submit-proposal. To submit a Text proposal:

gaiad tx gov submit-proposal \
  --title=<title> \
  --description=<description> \
  --type="Text" \
  --deposit="1000000uatom" \
  --from=<name> \
  --chain-id=<chain_id>

You may also provide the proposal directly through the --proposal flag which points to a JSON file containing the proposal. To submit a parameter change proposal, you must provide a proposal file as its contents are less friendly to CLI input:

gaiad tx gov submit-proposal param-change <path/to/proposal.json> \
  --from=<name> \
  --chain-id=<chain_id>

Where proposal.json contains the following:

{
  "title": "Param Change",
  "description": "Update max validators",
  "changes": [
    {
      "subspace": "staking",
      "key": "MaxValidators",
      "value": 105
    }
  ],
  "deposit": [
    {
      "denom": "stake",
      "amount": "10000000"
    }
  ]
}

The SoftwareUpgrade is currently not supported as it’s not implemented and currently does not differ from the semantics of a Text proposal.

Query Proposals

Once created, you can now query information of the proposal:

gaiad query gov proposal <proposal_id>

Or query all available proposals:

gaiad query gov proposals

You can also query proposals filtered by voter or depositor by using the corresponding flags. To query for the proposer of a given governance proposal:

gaiad query gov proposer <proposal_id>

Increase Deposit

In order for a proposal to be broadcasted to the network, the amount deposited must be above a minDeposit value (initial value: 512000000uatom). If the proposal you previously created didn’t meet this requirement, you can still increase the total amount deposited to activate it. Once the minimum deposit is reached, the proposal enters voting period:

gaiad tx gov deposit <proposal_id> "10000000uatom" \
  --from=<name> \
  --chain-id=<chain_id>

NOTE: Proposals that don’t meet this requirement will be deleted after MaxDepositPeriod is reached.

Query Deposits

Once a new proposal is created, you can query all the deposits submitted to it:

gaiad query gov deposits <proposal_id>

You can also query a deposit submitted by a specific address:

gaiad query gov deposit <proposal_id> <depositor_address>

Vote on a Proposal

After a proposal’s deposit reaches the MinDeposit value, the voting period opens. Bonded Atom holders can then cast vote on it:

gaiad tx gov vote <proposal_id> <Yes/No/NoWithVeto/Abstain> \
  --from=<name> \
  --chain-id=<chain_id>

Query Votes

Check the vote with the option you just submitted:

gaiad query gov vote <proposal_id> <voter_address>

You can also get all the previous votes submitted to the proposal with:

gaiad query gov votes <proposal_id>

Query proposal tally results

To check the current tally of a given proposal you can use the tally command:

gaiad query gov tally <proposal_id>

Query Governance Parameters

To check the current governance parameters run:

gaiad query gov params

To query subsets of the governance parameters run:

gaiad query gov param voting
gaiad query gov param tallying
gaiad query gov param deposit

Fee Distribution

Query Distribution Parameters

To check the current distribution parameters, run:

gaiad query distribution params

Query distribution Community Pool

To query all coins in the community pool which is under Governance control:

gaiad query distribution community-pool

Query outstanding rewards

To check the current outstanding (un-withdrawn) rewards, run:

gaiad query distribution outstanding-rewards

Query Validator Commission

To check the current outstanding commission for a validator, run:

gaiad query distribution commission <validator_address>

Query Validator Slashes

To check historical slashes for a validator, run:

gaiad query distribution slashes <validator_address> <start_height> <end_height>

Query Delegator Rewards

To check current rewards for a delegation (were they to be withdrawn), run:

gaiad query distribution rewards <delegator_address> <validator_address>

Query All Delegator Rewards

To check all current rewards for a delegation (were they to be withdrawn), run:

gaiad query distribution rewards <delegator_address>

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

​Gaia 守护进程

​配置 gaiad

​密钥

​密钥环

​密钥类型

​将密钥从旧版磁盘 Keybase 迁移到操作系统内置密钥存储

​生成密钥

​生成多签公钥

​交易广播

​费用与 Gas

​账户

​获取代币

​查询账户余额

​发送代币

​查询交易

​匹配一组事件

​按交易哈希匹配

​罚没

​解除监禁

​签名信息

​查询参数

​铸币

​质押

​设置验证者

​向验证者委托

查询验证者

​绑定代币

查询委托

​解绑代币

查询解绑委托

​重新委托代币

查询重新委托

​查询参数

​查询资金池

查询向验证者的委托

​治理

​创建治理提案

查询提案

​增加押金

查询押金

​对提案投票

查询投票

​查询提案计票结果

​查询治理参数

​手续费分配

​查询分配参数

​查询分配社区池

​查询未提取奖励

​查询验证者佣金

​查询验证者惩罚记录

​查询委托人奖励

​查询委托人的全部奖励

​多重签名交易

​Gaia Daemon

​Setting up gaiad

​Keys

​Keyring

​Key Types

​Migrate Keys From Legacy On-Disk Keybase To OS Built-in Secret Store

​Generate Keys

​Generate Multisig Public Keys

​Tx Broadcasting

​Fees & Gas

​Account

​Get Tokens

​Query Account Balance

​Send Tokens

​Query Transactions

​Matching a Set of Events

​Matching a Transaction’s Hash

​Slashing

​Unjailing

​Signing Info

​Query Parameters

​Minting

​Staking

​Set up a Validator

​Delegate to a Validator

Query Validators

​Bond Tokens

Gaia 守护进程

配置 gaiad

密钥

密钥环

密钥类型

将密钥从旧版磁盘 Keybase 迁移到操作系统内置密钥存储

生成密钥

生成多签公钥

交易广播

费用与 Gas

账户

获取代币

查询账户余额

发送代币

查询交易

匹配一组事件

按交易哈希匹配

罚没

解除监禁

签名信息

查询参数

铸币

质押

设置验证者

向验证者委托

绑定代币

解绑代币

重新委托代币

查询参数

查询资金池

治理

创建治理提案

增加押金

对提案投票

查询提案计票结果

查询治理参数

手续费分配

查询分配参数

查询分配社区池

查询未提取奖励

查询验证者佣金

查询验证者惩罚记录

查询委托人奖励

查询委托人的全部奖励

多重签名交易

Gaia Daemon

Setting up gaiad

Keys

Keyring

Key Types

Migrate Keys From Legacy On-Disk Keybase To OS Built-in Secret Store

Generate Keys

Generate Multisig Public Keys

Tx Broadcasting

Fees & Gas

Account

Get Tokens

Query Account Balance

Send Tokens

Query Transactions

Matching a Set of Events

Matching a Transaction’s Hash

Slashing

Unjailing

Signing Info

Query Parameters

Minting

Staking

Set up a Validator

Delegate to a Validator

Bond Tokens

Unbond Tokens

Redelegate Tokens

Query Parameters

Query Pool

Governance

Create a Governance Proposal

Increase Deposit

Vote on a Proposal

Query proposal tally results