From 2acd632f6d624957bf8c2b8b8daea8ed908f1b7d Mon Sep 17 00:00:00 2001
From: Conor Schaefer <conor@penumbralabs.xyz>
Date: Mon, 11 Mar 2024 15:43:02 -0700
Subject: [PATCH] docs: update deimos ibc channel for osmosis

We had a few chain halts on the `v0.68.x` release series. As of
`v0.69.0`, "channel-0" is the correct value for relaying to Osmosis
testnet. Added mention of the slick new `pcli query ibc channels` to the
docs.

Also overhauled the dev docs for how to test IBC functionality
interactively, since that knowledge has mostly been communicated via
pairing session, but not yet fully written down. We no longer use `rly`,
neither for running relayer instances nor for ad-hoc CLI transfers.
Instead, we can use `hermes` for both roles.

Linked out to wiki docs on the high-churn hermes relayer config steps,
since we're updating those frequently.
---
 docs/guide/book.toml               |   3 +
 docs/guide/src/dev/ibc.md          | 109 +++++++++++++++--------------
 docs/guide/src/pcli/transaction.md |  39 ++++-------
 3 files changed, 72 insertions(+), 79 deletions(-)

diff --git a/docs/guide/book.toml b/docs/guide/book.toml
index 7909dbded2..f2652f8691 100644
--- a/docs/guide/book.toml
+++ b/docs/guide/book.toml
@@ -24,3 +24,6 @@ additional-js =["theme/js/mermaid.min.js", "theme/js/mermaid-init.js"]
 # [output.linkcheck]
 # follow-web-links = false
 # warning-policy = "ignore"
+#
+# The buf.build website doesn't support HTTP HEAD calls, returning 405.
+# exclude = ['buf\.build']
diff --git a/docs/guide/src/dev/ibc.md b/docs/guide/src/dev/ibc.md
index 04f6807911..894cce65e3 100644
--- a/docs/guide/src/dev/ibc.md
+++ b/docs/guide/src/dev/ibc.md
@@ -3,6 +3,61 @@
 This guide explains how to work with IBC functionality
 while developing Penumbra.
 
+## Making Penumbra -> Osmosis outbound transfers, via pcli
+See the [IBC user docs](../pcli/transaction.md#ibc-withdrawals) for how to use
+`pcli` to make an outbound IBC withdrawal, to a different testnet.
+
+## Making Osmosis -> Penumbra inbound transfers, via hermes
+
+Transferring from Osmosis to Penumbra requires making an Osmosis transaction.
+The `osmosisd` CLI tooling unfortunately does not work for IBC transfers.
+To move funds from a Penumbra chain to an Osmosis testnet, use the `hermes` binary
+from the [Penumbra fork](https://github.com/penumbra-zone/hermes). What you'll need:
+
+* a local checkout of Hermes
+* your own osmosis wallet, with funds from the testnet faucet
+* channel info for both chains (consult `pcli query ibc channels`)
+* a penumbra address
+
+You should use your own Osmosis wallet, with funds from the testnet faucet,
+and configure Hermes locally on your workstation with key material. Do *not*
+reuse the Hermes relayer instance, as sending transactions from its wallets
+while it's relaying can break things.
+
+```bash
+# Hop into the hermes repo and build it:
+cargo build --release
+
+# Edit `config-penumbra-osmosis.toml` with your Penumbra wallet SpendKey,
+# and make sure the Penumbra chain id is correct.
+# Add your osmosis seed phrase to the file `mnemonic-osmosis-transfer`,
+# then import it:
+cargo run --release --bin hermes -- \
+    --config config-penumbra-osmosis.toml keys add \
+    --chain osmo-test-5 --mnemonic-file ./mnemonic-osmosis-transfer
+
+# Then run a one-off command to trigger an outbound IBC transfer,
+# from Osmosis to Penumbra:
+cargo run --release --bin hermes -- \
+    --config ./config-penumbra-osmosis.toml tx ft-transfer \
+    --dst-chain <PENUMBRA_CHAIN_ID> --src-chain osmo-test-5 --src-port transfer \
+    --src-channel <CHANNEL_ID_ON_OSMOSIS_CHAIN> --denom uosmo --amount 100 \
+    --timeout-height-offset 10000000 --timeout-seconds 10000000 \
+    --receiver <PENUMBRA_ADDRESS>
+```
+
+You can view account history for the shared Osmosis testnet account here:
+[https://www.mintscan.io/osmosis-testnet/account/osmo1kh0fwkdy05yp579d8vczgharkcexfw582zj488](https://www.mintscan.io/osmosis-testnet/account/osmo1kh0fwkdy05yp579d8vczgharkcexfw582zj488).
+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.
+
+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
+channel to the IBC docs guide, so community members can use it.
+
 ## Working with a local devnet
 
 <!--
@@ -70,57 +125,3 @@ cargo run --release --bin pcli -- -n http://localhost:8080 tx withdraw --to osmo
 ```
 
 See the [IBC pcli docs](../pcli/transaction.md#ibc-withdrawals) for more details.
-
-## Making Osmosis -> Penumbra transfers, via rly
-
-Transferring from Osmosis to Penumbra requires making an Osmosis transaction.
-The `osmosisd` CLI tooling unfortunately does not work for IBC transfers.
-To move funds from a Penumbra chain to an Osmosis testnet, use the `rly` binary
-from the [cosmos/relayer repo](https://github.com/cosmos/relayer). Then run:
-
-```
-# inside the penumbra repo:
-cd deployments/relayer
-# refresh the chain id for local devnet:
-./generate-configs local
-rly config init --memo "PenumbraIBC"
-rly chains add -f configs/penumbra-local.json
-rly chains add -f configs/osmosis-testnet.json
-# use the seed phrase from 1password for the osmosis key:
-rly keys restore osmosis-testnet default "SEED PHRASE"
-rly keys add penumbra-local default
-# create an IBC path between the two chains
-rly paths add $PENUMBRA_DEVNET_CHAIN_ID osmo-test-5 penumbra-osmosis-dev
-
-# finally, make the transfer
-rly transact transfer osmosis-testnet penumbra-local 100uosmo penumbrav2t1jp4pryqqmh65pq8e7zwk6k2674vwhn4qqphxjk0vukxln0crmp2tdld0mhavuyrspwuajnsk5t5t33u2auxvheunr7qde4l068ez0euvtu08z7rwj6shlh64ndz0wvz7mfqdcd channel-1675 -y 10000 -c 2h
-2023-09-17T20:19:47.510916Z	info	Successfully sent a transfer	{"src_chain_id": "osmo-test-5", "dst_chain_id": "penumbra-testnet-tethys-8777cb20", "send_result": {"successful_src_batches": 1, "successful_dst_batches": 0, "src_send_errors": "<nil>", "dst_send_errors": "<nil>"}}
-2023-09-17T20:19:47.510938Z	info	Successful transaction	{"provider_type": "cosmos", "chain_id": "osmo-test-5", "packet_src_channel": "channel-1675", "packet_dst_channel": "channel-0", "gas_used": 117670, "fees": "3717uosmo", "fee_payer": "osmo1kh0fwkdy05yp579d8vczgharkcexfw582zj488", "height": 2720869, "msg_types": ["/ibc.applications.transfer.v1.MsgTransfer"], "tx_hash": "67C55AD4FC6855579C2B4B421F8F02B2B2BFE6BA0D5C1553C13BBB7DFFAD781D"}
-```
-
-You can view account history for the shared Osmosis testnet account here:
-[https://testnet.mintscan.io/osmosis-testnet/account/osmo1kh0fwkdy05yp579d8vczgharkcexfw582zj488](https://testnet.mintscan.io/osmosis-testnet/account/osmo1kh0fwkdy05yp579d8vczgharkcexfw582zj488)
-
-## Updating Hermes config for a new testnet
-On every release of a new Penumbra testnet, we must update the Hermes relayer to establish
-a channel between it and target counterparty test chains.
-
-1. [Checkout the Penumbra fork of Hermes](https://github.com/penumbra-zone/hermes),
-and build it with `cargo build --release`.
-3. Edit the `config-osmosis-testnet.toml` file to use the chain id of the new Penumbra testnet, e.g. `penumbra-testnet-dione`.
-4. Add Osmosis key material to Hermes. Look up the Osmosis recovery phrase
-stored in shared 1Password, then:
-```bash
-echo "SEED PHRASE" > ./mnemonic
-cargo run --release --bin hermes -- --config config-osmosis-testnet.toml keys add --chain osmo-test-5 --mnemonic-file ./mnemonic
-```
-5. Create a new channel for this testnet:
-```bash
-cargo run --release --bin hermes -- --config config-osmosis-testnet.toml create channel --a-chain $PENUMBRA_TESTNET_CHAIN_ID --b-chain osmo-test-5 --a-port transfer --b-port transfer --new-client-connection
-```
-Hermes will run for a while, emit channel info, and then exit.
-6. Run Hermes: `cargo run --release --bin hermes -- --config config-osmosis-testnet.toml start`
-
-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
-channel to the IBC docs guide, so community members can use it.
diff --git a/docs/guide/src/pcli/transaction.md b/docs/guide/src/pcli/transaction.md
index c078dc4ddb..99dc27811a 100644
--- a/docs/guide/src/pcli/transaction.md
+++ b/docs/guide/src/pcli/transaction.md
@@ -181,44 +181,33 @@ has been configured between the Osmosis testnet and the *current* Penumbra testn
 
 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 64 Titan, the channel information is:
+For Testnet 69 Deimos, the channel is `0`:
 
 <!--
 To update the information below, update the Hermes config, then run:
-`pcli q ibc channels | jq '.[0]'` and confirm that output matches what Hermes emitted
+`pcli q ibc channels` and confirm that output matches what Hermes emitted
 during setup.
 -->
 
 ```
-{
-  "state": 3,
-  "ordering": 1,
-  "counterparty": {
-    "port_id": "transfer",
-    "channel_id": "channel-5077"
-  },
-  "connection_hops": [
-    "connection-6"
-  ],
-  "version": "ics20-1",
-  "port_id": "transfer",
-  "channel_id": "channel-2"
-}
-```
-
-The output above shows that the IBC channel id on Penumbra is 2, and on Osmosis it's 5077.
-There's one more piece of information we need to make an IBC withdrawal: the appropriate IBC
-timeout height, which is composed of two values: `<counterparty_chain_id_revision>-<counterparty_chain_block_height>`.
-For the Osmosis testnet, as of 2023Q4, the chain id is `osmo-test-5`, meaning the chain id revision is `5`.
-So a value like `5-5000000` (i.e. revision 5 at height 5 million) will work.
++------------+----------+--------------+-------------------------+-------+-----------------+---------------+
+| Channel ID | Port     | Counterparty | Counterparty Channel ID | State | Client ID       | Client Height |
++==========================================================================================================+
+| 0          | transfer | osmo-test-5  | channel-6105            | OPEN  | 07-tendermint-4 | 5-5937586     |
++------------+----------+--------------+-------------------------+-------+-----------------+---------------+
+```
+
+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.
 
+The output above shows that the IBC channel id on Penumbra is 0, and on Osmosis it's 6105.
 To initiate an IBC withdrawal from Penumbra testnet to Osmosis testnet:
 
 ```bash
-pcli tx withdraw --to <OSMOSIS_ADDRESS> --channel <CHANNEL_ID> 5gm --timeout-height 5-5000000
+pcli tx withdraw --to <OSMOSIS_ADDRESS> --channel <CHANNEL_ID> 5gm
 ```
 
-Unfortunately the CLI tooling for Osmosis is cumbersome. For now, use `rly` as a user agent
+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).
 
 [Osmosis testnet]: https://docs.osmosis.zone/overview/endpoints#testnet-networks