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