Skip to content

Commit

Permalink
HRMP Channel Setup Documentation (#34)
Browse files Browse the repository at this point in the history
* Init asset-transfer-api docs

* Add overview

* wip: add params & result types

* Add types

* Add examples

* Add support info and add notes

* Improve example

* Update docs/build-on-polkadot/xcm/asset-transfer-api.md

Co-authored-by: Nicolás Hussein <[email protected]>

* Update docs/build-on-polkadot/xcm/asset-transfer-api.md

Co-authored-by: Nicolás Hussein <[email protected]>

* Improve setup docs

* Fix note

* Replace assetId with asset ID

* Add sentence before terminal output

* demo api docs

* Remove spaces

* Add API Reference and improve overview

* Update docs/build-on-polkadot/xcm/asset-transfer-api/reference.md

Co-authored-by: Nicolás Hussein <[email protected]>

* Update docs/.snippets/code/build-on-polkadot/xcm/asset-transfer-api/reference/tx-result.md

Co-authored-by: Nicolás Hussein <[email protected]>

* Replace js with ts in code snippet

* Add decodeExtrinsic and fetchFeeInfo

* Update docs/build-on-polkadot/xcm/asset-transfer-api/overview.md

Co-authored-by: Dawn Kelly <[email protected]>

* Add ts project setup

* Fix termynal output

* Update docs/build-on-polkadot/xcm/asset-transfer-api.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/asset-transfer-api/reference.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/asset-transfer-api/reference.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/asset-transfer-api/reference.md

Co-authored-by: Erin Shaben <[email protected]>

* Update docs/build-on-polkadot/xcm/asset-transfer-api/overview.md

Co-authored-by: Erin Shaben <[email protected]>

* Update docs/build-on-polkadot/xcm/asset-transfer-api/overview.md

Co-authored-by: Erin Shaben <[email protected]>

* Update docs/build-on-polkadot/xcm/asset-transfer-api/reference.md

Co-authored-by: Erin Shaben <[email protected]>

* Update docs/build-on-polkadot/xcm/asset-transfer-api/overview.md

Co-authored-by: Erin Shaben <[email protected]>

* Update docs/build-on-polkadot/xcm/asset-transfer-api/overview.md

Co-authored-by: Erin Shaben <[email protected]>

* Remove comment

* Update description

* Fix whitespaces and periods

* Update headers

* Update createTransferTransaction description

* Fix descriptions

* Update docs/build-on-polkadot/xcm/asset-transfer-api/reference.md

Co-authored-by: Erin Shaben <[email protected]>

* Add transfer to headers

* Move setup script to snippets

* Fix code format

* Add missing {target=_blank}

* Delete unused file

* Fix variables for asset_transfer_api

* Update docs/build-on-polkadot/xcm/asset-transfer-api/overview.md

Co-authored-by: Dawn Kelly <[email protected]>

* wip: hrmp channels

* wip: channel btw parachains

* Fix titles

* wip: craft xcm

* Add steps

* Update docs/build-on-polkadot/xcm/hrmp-channels/overview.md

Co-authored-by: Nicolás Hussein <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/overview.md

Co-authored-by: Nicolás Hussein <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/overview.md

Co-authored-by: Nicolás Hussein <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/overview.md

Co-authored-by: Nicolás Hussein <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/overview.md

Co-authored-by: Nicolás Hussein <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/overview.md

Co-authored-by: Nicolás Hussein <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/overview.md

Co-authored-by: Nicolás Hussein <[email protected]>

* Add improvements

* Update images and steps

* Fix call field

* Improve header names

* Update last image

* Split pages

* Add para-to-system, rename images and add snippet

* Fix list

* Update docs/build-on-polkadot/xcm/hrmp-channels/para-to-para.md

Co-authored-by: Nicolás Hussein <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/overview.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/overview.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/overview.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/para-to-system.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/para-to-system.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/para-to-system.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/para-to-system.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/para-to-system.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/overview.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/para-to-para.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/para-to-para.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/para-to-para.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/para-to-para.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/para-to-para.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/para-to-para.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/para-to-para.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/para-to-para.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/para-to-para.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/para-to-para.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/para-to-para.md

Co-authored-by: Dawn Kelly <[email protected]>

* Update docs/build-on-polkadot/xcm/hrmp-channels/para-to-para.md

Co-authored-by: Dawn Kelly <[email protected]>

* Apply suggestions from code review

Co-authored-by: Dawn Kelly <[email protected]>

* Add link to Polkadot.js Apps

---------

Co-authored-by: Nicolás Hussein <[email protected]>
Co-authored-by: Erin Shaben <[email protected]>
Co-authored-by: Dawn Kelly <[email protected]>
  • Loading branch information
4 people authored Sep 23, 2024
1 parent 6015725 commit 73bc539
Show file tree
Hide file tree
Showing 22 changed files with 396 additions and 1 deletion.
Original file line number Diff line number Diff line change
Expand Up @@ -145,4 +145,4 @@ A promise containing the result of constructing the transaction.

??? child "Type `ConstructedFormat<T>`"

--8<-- 'code/build-on-polkadot/xcm/asset-transfer-api/reference/constructed-format.md'
--8<-- 'code/build-on-polkadot/xcm/asset-transfer-api/reference/constructed-format.md'
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
[
[
[
{
"sender": 1000,
"recipient": 2500
}
],
{
"maxCapacity": 8,
"maxTotalSize": 8192,
"maxMessageSize": 1048576,
"msgCount": 0,
"totalSize": 0,
"mqcHead": null,
"senderDeposit": 0,
"recipientDeposit": 0
}
],
[
[
{
"sender": 2500,
"recipient": 1000
}
],
{
"maxCapacity": 8,
"maxTotalSize": 8192,
"maxMessageSize": 1048576,
"msgCount": 0,
"totalSize": 0,
"mqcHead": null,
"senderDeposit": 0,
"recipientDeposit": 0
}
]
]
1 change: 1 addition & 0 deletions docs/build-on-polkadot/xcm/.pages
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,4 @@ hide: false
nav:
- index.md
- asset-transfer-api
- hrmp-channels
7 changes: 7 additions & 0 deletions docs/build-on-polkadot/xcm/hrmp-channels/.pages
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
title: HRMP Channels
hide: false
nav:
- index.md
- 'Overview': 'overview.md'
- 'Opening HRMP Channels Between Parachains': 'para-to-para.md'
- 'Opening HRMP Channels with System Parachains': 'para-to-system.md'
7 changes: 7 additions & 0 deletions docs/build-on-polkadot/xcm/hrmp-channels/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
title: HRMP Channels
description: HRMP channels enable cross-chain communication in Polkadot, a temporary solution before the more efficient XCMP protocol is implemented.
template: subsection-index-page.html
hide:
- feedback
---
56 changes: 56 additions & 0 deletions docs/build-on-polkadot/xcm/hrmp-channels/overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
title: HRMP Channels
description: Discover Horizontal Relay-routed Message Passing (HRMP) channels in Polkadot. Learn how parachains establish and use these channels for interoperability.
---

# HRMP Channels

## Introduction

Polkadot is designed to enable seamless interoperability between its connected parachains. At the core of this interoperability is the [Cross-Consensus Message Format (XCM)](https://wiki.polkadot.network/docs/learn-xcm), a standard language that allows parachains to communicate and interact with each other.

The network-layer protocol responsible for delivering XCM-formatted messages between parachains is the Cross-Chain Message Passing (XCMP) protocol. XCMP maintains messaging queues on the relay chain, serving as a bridge to facilitate cross-chain interactions.

As XCMP is still under development, Polkadot has implemented a temporary alternative called Horizontal Relay-routed Message Passing (HRMP). HRMP offers the same interface and functionality as the planned XCMP but it has a crucial difference, it stores all messages directly in the relay chain’s storage, which is more resource-intensive.

Once XCMP is fully implemented, HRMP will be deprecated in favor of the native XCMP protocol. XCMP will offer a more efficient and scalable solution for cross-chain message passing, as it will not require the relay chain to store all the messages.

## Establishing HRMP Channels

To enable communication between parachains using the HRMP protocol, the parachains must explicitly establish communication channels by registering them on the relay chain.

Downward and upward channels from and to the relay chain are implicitly available, meaning they do not need to be explicitly opened.

Opening an HRMP channel requires the parachains involved to make a deposit on the relay chain. This deposit serves a specific purpose, it covers the costs associated with using the relay chain's storage for the message queues linked to the channel. The amount of this deposit varies based on parameters defined by the specific relay chain being used.

### Relay Chain Parameters

Each Polkadot relay chain has a set of configurable parameters that control the behavior of the message channels between parachains. These parameters include `hrmpSenderDeposit`, `hrmpRecipientDeposit`, `hrmpChannelMaxMessageSize`, `hrmpChannelMaxCapacity`, and more.

When a parachain wants to open a new channel, it must consider these parameter values to ensure the channel is configured correctly.

To view the current values of these parameters in the Polkadot network:

1. Visit [Polkadot.js Apps](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fpolkadot.api.onfinality.io%2Fpublic-ws#/explorer), navigate to the **Developer** dropdown and select the **Chain state** option

![](/polkadot-ecosystem-docs-draft/images/build-on-polkadot/hrmp-channels/overview/hrmp-overview-1.webp)

2. Query the chain configuration parameters. The result will display the current settings for all the Polkadot network parameters, including the HRMP channel settings
1. Select **configuration**
2. Choose the **activeConfig()** call
3. Click the **+** button to execute the query
4. Check the chain configuration

![](/polkadot-ecosystem-docs-draft/images/build-on-polkadot/hrmp-channels/overview/hrmp-overview-2.webp)

### Dispatching Extrinsics

Establishing new HRMP channels between parachains requires dispatching specific extrinsic calls on the Polkadot relay chain from the parachain's origin.

The most straightforward approach is to implement the channel opening logic off-chain, then use the XCM pallet's `send` extrinsic to submit the necessary instructions to the relay chain. However, the ability to send arbitrary programs through the `Transact` instruction in XCM is typically restricted to privileged origins, such as the `sudo` pallet or governance mechanisms.

Parachain developers have a few options for triggering the required extrinsic calls from their parachain's origin, depending on the configuration and access controls defined:

- **Sudo** - if the parachain has a `sudo` pallet configured, the sudo key holder can use the sudo extrinsic to dispatch the necessary channel opening calls
- **Governance** - the parachain's governance system, such as a council or OpenGov, can be used to authorize the channel opening calls
- **Privileged Accounts** - the parachain may have other designated privileged accounts that are allowed to dispatch the HRMP channel opening extrinsics
181 changes: 181 additions & 0 deletions docs/build-on-polkadot/xcm/hrmp-channels/para-to-para.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,181 @@
---
title: Opening HRMP Channels Between Parachains
description: Learn how to open HRMP channels between parachains on Polkadot. Discover the step-by-step process for establishing uni- and bidirectional communication.
---

# Opening HRMP Channels Between Parachains

## Introduction

For establishing communication channels between parachains on the Polkadot network using the Horizontal Relay-routed Message Passing (HRMP) protocol, the following steps are required:

1. **Channel request** - the parachain that wants to open an HRMP channel must make a request to the parachain it wishes to have an open channel with
2. **Channel acceptance** - the other parachain must then accept this request to complete the channel establishment

This process results in a unidirectional HRMP channel, where messages can flow in only one direction between the two parachains.

An additional HRMP channel must be established in the opposite direction to enable bidirectional communication. This requires repeating the request and acceptance process but with the parachains reversing their roles.

Once both unidirectional channels are established, the parachains can send messages back and forth freely through the bidirectional HRMP communication channel.

## Prerequisites

Before proceeding, ensure you meet the following requirements:

- Blockchain network with a relay chain and at least two connected parachains
- Wallet with sufficient funds to execute transactions on the participant chains

## Procedure for Initiating HRMP Channel Setup

This example will demonstrate how to open a channel between parachain 2500 and parachain 2600, using Rococo Local as the relay chain.

### Step 1 - Fund Sender Sovereign Account
<!-- This content will be moved to a new page because it is used in multiple places -->
The [sovereign account](https://github.com/polkadot-fellows/xcm-format/blob/10726875bd3016c5e528c85ed6e82415e4b847d7/README.md?plain=1#L50){target=_blank} for parachain 2500 on the relay chain must be funded so it can take care of any XCM transact fees.

Use [Polkadot.js Apps](https://polkadot.js.org/apps/#/explorer){target=\_blank} UI to connect to the relay chain and transfer funds from your account to the parachain 2500 sovereign account.
![](/polkadot-ecosystem-docs-draft/images/build-on-polkadot/hrmp-channels/hrmp-channels-2.webp)

??? note "Calculating Parachain Sovereign Account"
To generate the sovereign account address for a parachain, you'll need to follow these steps:

1. Determine if the parachain is an "up/down" chain (parent or child) or a "sibling" chain:

- Up/down chains use the prefix `0x70617261` (which decodes to `b"para"`)

- Sibling chains use the prefix `0x7369626c` (which decodes to `b"sibl"`)

2. Calculate the u32 scale encoded value of the parachain ID:
- Parachain 2500 would be encoded as `c4090000`

3. Combine the prefix and parachain ID encoding to form the full sovereign account address:

The sovereign account of parachain 2500 in relay chain will be `0x70617261c4090000000000000000000000000000000000000000000000000000`
and the SS58 format of this address is `5Ec4AhPSY2GEE4VoHUVheqv5wwq2C1HMKa7c9fVJ1WKivX1Y`

To perform this conversion, you can also use the **"Para ID" to Address** section in [Substrate Utilities](https://www.shawntabrizi.com/substrate-js-utilities/).

### Step 2 - Create Channel Opening Extrinsic

1. In Polkadot.js Apps, connect to the relay chain, navigate to the **Developer** dropdown and select the **Extrinsics** option

![](/polkadot-ecosystem-docs-draft/images/build-on-polkadot/hrmp-channels/para-to-para/hrmp-para-to-para-1.webp)

2. Construct an `hrmpInitOpenChannel` extrinsic call

1. Select the **`hrmp`** pallet
2. Choose the **`hrmpInitOpenChannel`** extrinsic
3. Fill in the parameters
- **`recipient`** - parachain ID of the target chain (in this case, 2600)
- **`proposedMaxCapacity`** - max number of messages that can be pending in the channel at once
- **`proposedMaxMessageSize`** - max message size that could be put into the channel
4. Copy the encoded call data
![](/polkadot-ecosystem-docs-draft/images/build-on-polkadot/hrmp-channels/para-to-para/hrmp-para-to-para-2.webp)
The encoded call data for opening a channel with parachain 2600 is `0x3c00280a00000800000000001000`.

### Step 3 - Crafting and Submitting the XCM Message from the Sender

To initiate the HRMP channel opening process, you need to create an XCM message that includes the encoded `hrmpInitOpenChannel` call data from the previous step. This message will be sent from your parachain to the relay chain.

This example uses the `sudo` pallet to dispatch the extrinsic. Verify the XCM configuration of the parachain you're working with and ensure you're using an origin with the necessary privileges to execute the `polkadotXcm.send` extrinsic.

The XCM message should contain the following instructions:

- **`WithdrawAsset`** - withdraws assets from the origin's ownership and places them in the Holding Register
- **`BuyExecution`** - pays for the execution of the current message using the assets in the Holding Register
- **`Transact`** - execute the encoded transaction call
- **`RefundSurplus`** - increases the Refunded Weight Register to the value of the Surplus Weight Register, attempting to reclaim any excess fees paid via BuyExecution
- **`DepositAsset`** - subtracts assets from the Holding Register and deposits equivalent on-chain assets under the specified beneficiary's ownership

!!!note
For more detailed information about XCM's functionality, complexities, and instruction set, refer to the [xcm-format](https://github.com/polkadot-fellows/xcm-format){target=_blank} documentation.

In essence, this process withdraws funds from the parachain's sovereign account to the XCVM Holding Register, then uses these funds to purchase execution time for the XCM `Transact` instruction, executes `Transact`, refunds any unused execution time and deposits any remaining funds into a specified account.

To send the XCM message to the relay chain, connect to parachain 2500 in Polkadot.js Apps. Fill in the required parameters as shown in the image below, ensuring that you:

1. Replace the **`call`** field with your encoded `hrmpInitOpenChannel` call data from the previous step
2. Use the correct beneficiary information
3. Click the **Submit Transaction** button to dispatch the XCM message to the relay chain

![](/polkadot-ecosystem-docs-draft/images/build-on-polkadot/hrmp-channels/para-to-para/hrmp-para-to-para-3.webp)

!!! note
The exact process and parameters for submitting this XCM message may vary depending on your specific parachain and relay chain configurations. Always refer to the most current documentation for your particular network setup.

After submitting the XCM message to initiate the HRMP channel opening, you should verify that the request was successful. Follow these steps to check the status of your channel request:

1. Using Polkadot.js Apps, connect to the relay chain and navigate to the **Developer** dropdown, then select the **Chain state** option

![](/polkadot-ecosystem-docs-draft/images/build-on-polkadot/hrmp-channels/hrmp-channels-1.webp)

2. Query the HRMP open channel requests
1. Select **`hrmp`**
2. Choose the **`hrmpOpenChannelRequests`** call
3. Click the **+** button to execute the query
4. Check the status of all pending channel requests

![](/polkadot-ecosystem-docs-draft/images/build-on-polkadot/hrmp-channels/para-to-para/hrmp-para-to-para-4.webp)

If your channel request was successful, you should see an entry for your parachain ID in the list of open channel requests. This confirms that your request has been properly registered on the relay chain and is awaiting acceptance by the target parachain.

## Procedure for Accepting HRMP Channel

For the channel to be fully established, the target parachain must accept the channel request by submitting an XCM message to the relay chain.

### Step 1 - Fund Receiver Sovereign Account

Before proceeding, ensure that the sovereign account of parachain 2600 on the relay chain is funded. This account will be responsible for covering any XCM transact fees.
To fund the account, follow the same process described in the previous section [Step 1 - Fund Sovereign Account](#step-1---fund-sender-sovereign-account).

### Step 2 - Create Channel Accepting Extrinsic

1. In Polkadot.js Apps, connect to the relay chain, navigate to the **Developer** dropdown and select the **Extrinsics** option

![](/polkadot-ecosystem-docs-draft/images/build-on-polkadot/hrmp-channels/para-to-para/hrmp-para-to-para-1.webp)

2. Construct an `hrmpAcceptOpenChannel` extrinsic call

1. Select the **`hrmp`** pallet
2. Choose the **`hrmpAcceptOpenChannel`** extrinsic
3. Fill in the parameters:
- **`sender`** - parachain ID of the requesting chain (in this case, 2500)
4. Copy the encoded call data
![](/polkadot-ecosystem-docs-draft/images/build-on-polkadot/hrmp-channels/para-to-para/hrmp-para-to-para-5.webp)
The encoded call data for accepting a channel with parachain 2500 should be `0x3c01c4090000`

### Step 3 - Crafting and Submitting the XCM Message from the Receiver

To accept the HRMP channel opening, you need to create and submit an XCM message that includes the encoded `hrmpAcceptOpenChannel` call data from the previous step. This process is similar to the one described in the previous section's [Step 3 - Crafting and Submitting the XCM Message](#step-3---crafting-and-submitting-the-xcm-message-from-the-sender), with a few key differences:

- Use the encoded call data for `hrmpAcceptOpenChannel` obtained in Step 2 of this section
- In the last XCM instruction (DepositAsset), set the beneficiary to parachain 2600's sovereign account to receive any surplus funds

To send the XCM message to the relay chain, connect to parachain 2600 in Polkadot.js Apps. Fill in the required parameters as shown in the image below, ensuring that you:

1. Replace the **`call`** field with your encoded `hrmpAcceptOpenChannel` call data from the previous step
2. Use the correct beneficiary information
3. Click the **Submit Transaction** button to dispatch the XCM message to the relay chain

![](/polkadot-ecosystem-docs-draft/images/build-on-polkadot/hrmp-channels/para-to-para/hrmp-para-to-para-6.webp)

After submitting the XCM message to accept the HRMP channel opening, verify that the channel has been set up correctly.

1. Using Polkadot.js Apps, connect to the relay chain and navigate to the **Developer** dropdown, then select the **Chain state** option

![](/polkadot-ecosystem-docs-draft/images/build-on-polkadot/hrmp-channels/hrmp-channels-1.webp)

2. Query the HRMP channels
1. Select **`hrmp`**
2. Choose the **`hrmpChannels`** call
3. Click the **+** button to execute the query
4. Check the status of the opened channel

![](/polkadot-ecosystem-docs-draft/images/build-on-polkadot/hrmp-channels/para-to-para/hrmp-para-to-para-7.webp)

If the channel has been successfully established, you should see the channel details in the query results.

By following these steps, you will have successfully accepted the HRMP channel request and established a unidirectional channel between the two parachains.

!!! note
Remember that for full bidirectional communication, you'll need to repeat this process in the opposite direction, with parachain 2600 initiating a channel request to parachain 2500.
Loading

0 comments on commit 73bc539

Please sign in to comment.