From 4d2fe9e09f34e4f0ece903d310c056014407121c Mon Sep 17 00:00:00 2001 From: Conor Schaefer Date: Mon, 22 Jul 2024 14:28:29 -0700 Subject: [PATCH] docs: add hermes setup steps to guide (#4732) ## Describe your changes Ported the contents from the old wiki page (since cleaned up) on configuring Hermes to the proper dev guide, beside the other node operator docs. Most of the advice is "use this fork" and "add these specific" options, but at least now there's a single URL to collect that info. We can revise once the relevant Penumbra-compatibility changes in the fork are upstreamed. ## Issue ticket number and link N/A ## Checklist before requesting a review - [x] If this code contains consensus-breaking changes, I have added the "consensus-breaking" label. Otherwise, I declare my belief that there are not consensus-breaking changes, for the following reason: > docs-only Co-authored-by: Conor Schaefer --- docs/guide/src/SUMMARY.md | 2 + docs/guide/src/dev/ibc.md | 3 +- docs/guide/src/node/relayer.md | 17 ++++++ docs/guide/src/node/relayer/hermes.md | 74 +++++++++++++++++++++++++++ docs/guide/src/pcli/transaction.md | 21 +++----- docs/guide/src/web.md | 4 -- 6 files changed, 100 insertions(+), 21 deletions(-) create mode 100644 docs/guide/src/node/relayer.md create mode 100644 docs/guide/src/node/relayer/hermes.md diff --git a/docs/guide/src/SUMMARY.md b/docs/guide/src/SUMMARY.md index 04ca3089ce..211d06d874 100644 --- a/docs/guide/src/SUMMARY.md +++ b/docs/guide/src/SUMMARY.md @@ -22,6 +22,8 @@ - [Configuring `pclientd`](./node/pclientd/configure.md) - [Making RPC requests](./node/pclientd/rpc.md) - [Building Transactions](./node/pclientd/build_transaction.md) + - [IBC relayer](./node/relayer.md) + - [Hermes](./node/relayer/hermes.md) - [Development](./dev.md) - [Developer environment](./dev/dev-env.md) - [Devnet quickstart](./dev/devnet-quickstart.md) diff --git a/docs/guide/src/dev/ibc.md b/docs/guide/src/dev/ibc.md index 894cce65e3..c9b86d1058 100644 --- a/docs/guide/src/dev/ibc.md +++ b/docs/guide/src/dev/ibc.md @@ -51,8 +51,7 @@ You can view account history for the shared Osmosis testnet account here: Change the address at the end of the URL to your account to confirm that your test transfer worked. ## Updating Hermes config for a new testnet -See the [procedure in the wiki](https://github.com/penumbra-zone/penumbra/wiki/Updating-Hermes) -for up to date information. +See the [relayer config guide](../node/relayer/hermes.md) for up to date information. Use the [IBC user docs](../pcli/transaction.md#ibc-withdrawals) to make a test transaction, to ensure that relaying is working. In the future, we should consider posting the newly created diff --git a/docs/guide/src/node/relayer.md b/docs/guide/src/node/relayer.md new file mode 100644 index 0000000000..038573e2d2 --- /dev/null +++ b/docs/guide/src/node/relayer.md @@ -0,0 +1,17 @@ +# IBC relayer + +In order for Penumbra to interact with the broader [Cosmos] ecosystem, the community must +run [IBC] relaying software, to transmit packets between chains. Relaying is by design +permissionless. Some examples of relayer software are: + + * [hermes], maintained by [Informal Systems] + * [relayer], maintained by [Strangelove] + +This guide provides a tutorial for [setting up Hermes for use with Penumbra](relayer/hermes.md). + +[Cosmos]: https://cosmos.network +[IBC]: https://ibc.cosmos.network +[hermes]: https://hermes.informal.systems +[relayer]: https://github.com/cosmos/relayer +[Informal Systems]: https://informal.systems +[Strangelove]: https://strange.love diff --git a/docs/guide/src/node/relayer/hermes.md b/docs/guide/src/node/relayer/hermes.md new file mode 100644 index 0000000000..82b9308031 --- /dev/null +++ b/docs/guide/src/node/relayer/hermes.md @@ -0,0 +1,74 @@ +# Hermes and Penumbra + +## Using a compatible Hermes version +Penumbra-compatibility exists in a fork of the Hermes software, available at: +[https://github.com/penumbra-zone/hermes](https://github.com/penumbra-zone/hermes). + +```shell +git clone https://github.com/penumbra-zone/hermes +cd hermes +cargo build --release +cp -v ./target/release/hermes /usr/local/bin/hermes +``` + +Use the latest commit in that repo. +Eventually the necessary changes will be upstreamed to the parent repo. +Until that happens, use the forked version. + +## Prerequisites + +In order to run a Hermes instance for Penumbra, you'll need to prepare the following: + +* The chain ID of the Penumbra network +* The chain ID of the counterparty network +* A funded Penumbra wallet, to pay fees on Penumbra (the host chain) +* A funded counterparty wallet, to pay fees on the counterparty chain +* Two (2) API endpoints for Penumbra node, `pd` gRPC and CometBFT JSON-RPC +* Two (2) API endpoints for counterparty node, app gRPC and CometBFT JSON-RPC +* A compatible version of `hermes`, built as described above. + +Crucially, the wallets should be unique, dedicated solely to this instance of Hermes, +and not used by any other clients. When you have the above information, you're ready to proceed. + +## Configuring Hermes + +For the most part, you can follow the [official Hermes docs on configuration](https://hermes.informal.systems/documentation/configuration/configure-hermes.html). +There are two Penumbra-specific exceptions: 1) key support; and 2) on-disk view database support. + +### Penumbra spend keys +The Penumbra integration does Hermes does not support the [`hermes keys add`](https://hermes.informal.systems/documentation/commands/keys/index.html) +flow for Penumbra chains. Instead, you should add the Penumbra wallet spendkey directly to the generated `config.toml` file, like so: + +```toml +# Replace "XXXXXXXX" with the spend key for the Penumbra wallet. +kms_config = { spend_key = "XXXXXXXX" } +``` + +To find the wallet's spend key, you can view `~/.local/share/pcli/config.toml`. + +### Penumbra view database +Then, to configure on-disk persistence of the Penumbra view database, add this line to your config: + +```toml +# Update the path below as appropriate for your system, +# and make sure to create the directory before starting Hermes. +view_service_storage_dir = "/home/hermes/.local/share/pcli-hermes-1" +``` + +Consider naming the directory `pcli-hermes-`, where counterparty is the name of the counterparty chain. +If you do not set this option, `hermes` will still work, but it will need to resync with the chain on startup, +which can take a long time, depending on how many blocks exist. + +## Path setup + +Again, see the [official Hermes docs on path setup](https://hermes.informal.systems/documentation/commands/path-setup/index.html). +In order to validate that the channels are visible on host chain, use `pcli query ibc channels` and confirm they match +what was output from the `hermes create` commands. + +## Best practices + +Consult the official Hermes docs for [running in production](https://hermes.informal.systems/tutorials/production/index.html), +as well as the [telemetry guide](https://hermes.informal.systems/documentation/telemetry/index.html). +You'll need to communicate the channels that you maintain to the community. How you do so is up to you. + +[hermes]: https://hermes.informal.systems diff --git a/docs/guide/src/pcli/transaction.md b/docs/guide/src/pcli/transaction.md index 99dc27811a..46af90b86c 100644 --- a/docs/guide/src/pcli/transaction.md +++ b/docs/guide/src/pcli/transaction.md @@ -176,18 +176,11 @@ There are other pairs available that you can try this tool on, for example `gm:g -Penumbra aims to implement full IBC support for cross-chain asset transfers. For now, however, -we're only running a relayer between the Penumbra testnet and the [Osmosis testnet] chains. -For Testnet 69 Deimos, the channel is `0`: - - +Penumbra aims to implement full IBC support for cross-chain asset transfers. You can use a command +like `pcli query ibc channels` to view the available channels: ``` +------------+----------+--------------+-------------------------+-------+-----------------+---------------+ @@ -197,17 +190,15 @@ during setup. +------------+----------+--------------+-------------------------+-------+-----------------+---------------+ ``` -You can see this yourself by running `pcli query ibc channels` and comparing the output you see -with what's shown above. It's possible the output will include mention of other chains. +You should see something comparable to the example output above. It's possible the output will include mention of other chains. -The output above shows that the IBC channel id on Penumbra is 0, and on Osmosis it's 6105. +The output above shows that the IBC channel id on Penumbra is 0, and on the [Osmosis testnet] it's 6105. To initiate an IBC withdrawal from Penumbra testnet to Osmosis testnet: ```bash pcli tx withdraw --to --channel 5gm ``` -Unfortunately the CLI tooling for Osmosis is cumbersome. For now, use `hermes` as a user agent -for the Osmosis testnet, as described in the [IBC dev docs](../dev/ibc.md). +You should only use channels that you trust, otherwise transfers could fail, leading to loss of funds. [Osmosis testnet]: https://docs.osmosis.zone/overview/endpoints#testnet-networks diff --git a/docs/guide/src/web.md b/docs/guide/src/web.md index 6d164e77e6..adbd939049 100644 --- a/docs/guide/src/web.md +++ b/docs/guide/src/web.md @@ -66,10 +66,6 @@ click **Connect**, then authorize the extension to work with the site. After doing so, you'll see buttons for actions such as **Receive**, **Send**, and **Exchange**. -As of Testnet 53, only the **Send** action is supported. Check back on -subsequent versions to follow progress as we implement more advanced -functionality in the web wallet. - ## Upgrading to a new testnet When a new testnet is released, you'll need to clear the existing state