Skip to content

Commit dac0e58

Browse files
bryanchriswhitebryanchriswhite
committed
wip: IBC docs
1 parent 25ca218 commit dac0e58

File tree

4 files changed

+184
-0
lines changed

4 files changed

+184
-0
lines changed

‎docusaurus/docs/4_develop/ibc/_category_.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "IBC",
3+
"position": 9,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "Pocket IBC interoperability documentation."
7+
}
8+
}

‎docusaurus/docs/4_develop/ibc/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Pocket IBC Interoperability
2+
3+
## Localnet
4+

‎docusaurus/docs/4_develop/ibc/localnet.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# Localnet IBC Environment
2+
3+
## Quickstart
4+
5+
1.
6+
2. Wait for pocket and counterparty validators to be producing blocks
7+
3. Click the manual trigger arrow on the `🏗️ pocket-<counterparty>` tilt service
8+
4. Wait for IBC setup for that pair to complete
9+
5. Once setup has completed successfully, click the manual trigger arrow on the `🔁 <counterparty>-pocket` tilt service to restart the corresponding relayer.
10+
11+
:::warning
12+
13+
DO NOT initiate multiple IBC setup operations simultaneously unless you know what you are doing or you trust hermes retry logic!
14+
15+
Until and unless hermes can be configured to use unordered tx feature, the sequence number of the account used for setup matters.
16+
17+
:::
18+
19+
## IBC Setup
20+
21+
For each pair of chains, the IBC protocol requires an `Client`, `Connection`, and `Channel` be created between those chains.
22+
23+
The tilt localnet environment exposes this setup as a manually triggered service, prefixed with `🏗️`. The following uses the `pocket-axelar` pair as an example.
24+
25+
![ibc_setup.png](../../../static/img/ibc_setup.png)
26+
27+
Once the counterparty chain is climbing (producing blocks), the setup can be triggered by clicking the arrow in the corresponding service.
28+
29+
Example setup log output:
30+
31+
<details>
32+
<summary>
33+
34+
```
35+
2025-06-26T11:40:41.166006Z INFO ThreadId(01) running Hermes v1.13.1+5e403dd
36+
2025-06-26T11:40:45.211899Z INFO ThreadId(01) Creating new clients, new connection, and a new channel with order ORDER_UNORDERED
37+
2025-06-26T11:40:50.240782Z INFO ThreadId(01) foreign_client.create{client=axelar->pocket:07-tendermint-0}: 🍭 client was created successfully id=07-tendermint-0
38+
2025-06-26T11:41:06.131924Z INFO ThreadId(01) foreign_client.create{client=pocket->axelar:07-tendermint-0}: 🍭 client was created successfully id=07-tendermint-0
39+
2025-06-26T11:41:09.671319Z INFO ThreadId(01) 🥂 pocket => OpenInitConnection(OpenInit { Attributes { connection_id: connection-0, client_id: 07-tendermint-0, counterparty_connection_id: None, counterparty_client_id: 07-tendermint-0 } }) at height 0-22
40+
2025-06-26T11:41:56.934211Z INFO ThreadId(01) 🥂 axelar => OpenTryConnection(OpenTry { Attributes { connection_id: connection-0, client_id: 07-tendermint-0, counterparty_connection_id: connection-0, counterparty_client_id: 07-tendermint-0 } }) at height 0-19
41+
2025-06-26T11:42:23.508663Z INFO ThreadId(01) 🥂 pocket => OpenAckConnection(OpenAck { Attributes { connection_id: connection-0, client_id: 07-tendermint-0, counterparty_connection_id: connection-0, counterparty_client_id: 07-tendermint-0 } }) at height 0-58
42+
2025-06-26T11:42:58.297181Z INFO ThreadId(01) 🥂 axelar => OpenConfirmConnection(OpenConfirm { Attributes { connection_id: connection-0, client_id: 07-tendermint-0, counterparty_connection_id: connection-0, counterparty_client_id: 07-tendermint-0 } }) at height 0-31
43+
2025-06-26T11:43:06.326874Z INFO ThreadId(01) connection handshake already finished for Connection { delay_period: 0ns, a_side: ConnectionSide { chain: BaseChainHandle { chain_id: pocket }, client_id: 07-tendermint-0, connection_id: connection-0 }, b_side: ConnectionSide { chain: BaseChainHandle { chain_id: axelar }, client_id: 07-tendermint-0, connection_id: connection-0 } }
44+
2025-06-26T11:43:08.162131Z INFO ThreadId(01) 🎊 pocket => OpenInitChannel(OpenInit { port_id: transfer, channel_id: channel-0, connection_id: None, counterparty_port_id: transfer, counterparty_channel_id: None }) at height 0-79
45+
2025-06-26T11:43:19.232828Z INFO ThreadId(01) 🎊 axelar => OpenTryChannel(OpenTry { port_id: transfer, channel_id: channel-0, connection_id: connection-0, counterparty_port_id: transfer, counterparty_channel_id: channel-0 }) at height 0-35
46+
2025-06-26T11:43:53.673647Z INFO ThreadId(01) 🎊 pocket => OpenAckChannel(OpenAck { port_id: transfer, channel_id: channel-0, connection_id: connection-0, counterparty_port_id: transfer, counterparty_channel_id: channel-0 }) at height 0-100
47+
2025-06-26T11:44:11.728489Z INFO ThreadId(01) 🎊 axelar => OpenConfirmChannel(OpenConfirm { port_id: transfer, channel_id: channel-0, connection_id: connection-0, counterparty_port_id: transfer, counterparty_channel_id: channel-0 }) at height 0-45
48+
2025-06-26T11:44:19.747405Z INFO ThreadId(01) channel handshake already finished for Channel { ordering: ORDER_UNORDERED, a_side: ChannelSide { chain: BaseChainHandle { chain_id: pocket }, client_id: 07-tendermint-0, connection_id: connection-0, port_id: transfer, channel_id: channel-0, version: None }, b_side: ChannelSide { chain: BaseChainHandle { chain_id: axelar }, client_id: 07-tendermint-0, connection_id: connection-0, port_id: transfer, channel_id: channel-0, version: None }, connection_delay: 0ns }
49+
```
50+
51+
</summary>
52+
53+
```
54+
SUCCESS Channel {
55+
ordering: Unordered,
56+
a_side: ChannelSide {
57+
chain: BaseChainHandle {
58+
chain_id: ChainId {
59+
id: "pocket",
60+
version: 0,
61+
},
62+
runtime_sender: Sender { .. },
63+
},
64+
client_id: ClientId(
65+
"07-tendermint-0",
66+
),
67+
connection_id: ConnectionId(
68+
"connection-0",
69+
),
70+
port_id: PortId(
71+
"transfer",
72+
),
73+
channel_id: Some(
74+
ChannelId(
75+
"channel-0",
76+
),
77+
),
78+
version: None,
79+
},
80+
b_side: ChannelSide {
81+
chain: BaseChainHandle {
82+
chain_id: ChainId {
83+
id: "axelar",
84+
version: 0,
85+
},
86+
runtime_sender: Sender { .. },
87+
},
88+
client_id: ClientId(
89+
"07-tendermint-0",
90+
),
91+
connection_id: ConnectionId(
92+
"connection-0",
93+
),
94+
port_id: PortId(
95+
"transfer",
96+
),
97+
channel_id: Some(
98+
ChannelId(
99+
"channel-0",
100+
),
101+
),
102+
version: None,
103+
},
104+
connection_delay: 0ns,
105+
}
106+
```
107+
108+
</details>
109+
110+
111+
## Onchain IBC State
112+
113+
### Clients
114+
115+
```shell
116+
# List pocket clients
117+
make ibc_list_pocket_clients NETWORK=local
118+
119+
# List axelar clients
120+
make ibc_list_axelar_clients NETWORK=local
121+
```
122+
123+
### Connections
124+
125+
```shell
126+
# List pocket connections
127+
make ibc_list_pocket_connections NETWORK=local
128+
129+
# List axelar connections
130+
make ibc_list_axelar_connections NETWORK=local
131+
```
132+
133+
### Channels
134+
135+
```shell
136+
# List pocket channels
137+
make ibc_list_pocket_channels NETWORK=local
138+
139+
# List axelar channels
140+
make ibc_list_axelar_channels NETWORK=local
141+
```
142+
143+
## Transfers
144+
145+
...
146+
147+
```shell
148+
# NOTE: Test transfer targets assume ONLY two chains are running.
149+
# Otherwise, the channels used in the transfer command MAY need to be adjusted according to the current onchain state.
150+
151+
# Transfer upokt from pocket to axelar
152+
$ make ibc_test_transfer_pocket_to_axelar
153+
{"height":"602","txhash":"CF21D72E1F8A1587E45D7F806037BE788C44EABEB86030E680CA39879DF14AED","codespace":"","code":0,"data":...
154+
155+
# Check the destination account balance
156+
$ make acc_balance_query ACC=pokt1mrqt5f7qh8uxs27cjm9t7v9e74a9vvdnq5jva4
157+
~ Balances ~
158+
balances:
159+
- amount: "100000000"
160+
denom: upokt
161+
pagination:
162+
total: "1"
163+
...
164+
165+
# Transfer uaxl from axelar to pocket
166+
$ make ibc_test_transfer_axelar_to_pocket
167+
```
168+
169+
## Interchain Accounts
170+
171+
...
172+

‎docusaurus/static/img/ibc_setup.png‎

23 KB
Loading

0 commit comments

Comments
 (0)