Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation on relaying for consumer chains to the Hermes guide #3407

Merged
merged 7 commits into from
Jun 8, 2023
2 changes: 1 addition & 1 deletion guide/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@
- [Commands Reference](./documentation/commands/index.md)
- [Global options and JSON output](./documentation/commands/global.md)
- [Keys](./documentation/commands/keys/index.md)
- [Genearting and Validating Config Files](./documentation/commands/config.md)
- [Generating and Validating Config Files](./documentation/commands/config.md)
- [Path setup](./documentation/commands/path-setup/index.md)
- [Clients](./documentation/commands/path-setup/clients.md)
- [Connections](./documentation/commands/path-setup/connections.md)
Expand Down
17 changes: 17 additions & 0 deletions guide/src/advanced/troubleshooting/cross-comp-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -262,3 +262,20 @@ Depending on how old the missing events are:
- if state-sync is used, specify an initial state with a height that is smaller than the height at which the event occurred.
- in order to find out the height of the missing events, use an archive node or a node with bigger pruning window and do the same queries as above
- restart the node

## Unimplemented gRPC for Cosmos Staking Service

When relaying for a consumer chain, the `ccv_consumer_chain` parameter in `config.toml` *must* be set to `true`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When relaying for a consumer chain, the `ccv_consumer_chain` parameter in `config.toml` *must* be set to `true`.
When relaying for a consumer chain, the `ccv_consumer_chain` parameter *must* be set to `true` under its `[[chains]]` section in the `config.toml` file.

If it is not, then when Hermes attempts to relay for a consumer chain, it will typically report an error related
to a gRPC endpoint being unimplemented for the staking service:

```
ERROR error raised while creating client for chain: failed when building client state: gRPC call failed with status: status: Unimplemented, message: "unknown service cosmos.staking.v1beta1.Query", details: [], metadata: MetadataMap { headers: {"content-type": "application/grpc", "content-length": "0", "date": "Thu, 16 Feb 2023 10:42:14 GMT", "server": "Caddy"} }
```

This error occurs because consumer chains do not utilize the same staking module as sovereign chains. The `ccv_consumer_chain`
parameter must be set to `true` so that Hermes knows to query a different gRPC endpoint for the relevant `ccvconsumer` parameters
that it needs in order to relay on behalf of a consumer chain.

### Fix
Set `ccv_consumer_chain = true` in `config.toml`.
20 changes: 20 additions & 0 deletions guide/src/documentation/configuration/configure-hermes.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,24 @@ list = [
]
```

## Configuring Support for Consumer Chains that Utilize Cross-Chain Validation

As of version 1.4.1, Hermes supports relaying for consumer chains that utilize [cross-chain validation][ccv] (CCV).

> **Note:** A consumer chain is essentially a regular Cosmos-SDK based chain that uses the interchain security
module to achieve economic security by stake deposited on a provider chain instead of on the consumer chain
itself. Consumer chains are bound to their provider chains by the provider's validator set. By being bound
together in this way, consumer chains inherit the economic security guarantees of the provider chain.
>
> You can read more about consumer chains, and Interchain Security more generally, at [https://cosmos.github.io/interchain-security][cosmos-github-io].

If you are configuring Hermes in order to relay for a consumer chain, set `ccv_consumer_chain = true` in the `config.toml` file.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If you are configuring Hermes in order to relay for a consumer chain, set `ccv_consumer_chain = true` in the `config.toml` file.
If you are configuring Hermes in order to relay for a consumer chain, set `ccv_consumer_chain = true` under its `[[chains]]` section in the `config.toml` file.

By default, this option is set to `false`. It should *ONLY* be toggled on for CCV consumer chains, *NOT* for sovereign chains.

This parameter is required because consumer chains do not utilize the same staking module as sovereign chains.
Consumer chains must query a different gRPC endpoint in order to fetch the relevant `ccvconsumer` parameters that Hermes
needs in order to relay on behalf of consumer chains.

## Connecting to a full node protected by HTTP Basic Authentication

To connect to a full node protected by [HTTP Basic Authentication][http-basic-auth],
Expand Down Expand Up @@ -165,6 +183,8 @@ be receiving, such as when relaying for CosmWasm-enabled blockchains which emit
`message` attribute. Without this attribute, the WebSocket is not able to catch these events to stream
to Hermes, so the `/block_results` RPC endpoint must be used instead.

[ccv]: https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/README.md
[cosmos-github-io]: https://cosmos.github.io/interchain-security
[http-basic-auth]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication
[ica]: https://github.com/cosmos/ibc/blob/master/spec/app/ics-027-interchain-accounts/README.md
[chain-registry]: https://github.com/cosmos/chain-registry
Expand Down