From 8cc933d2c0444adfadd6c0a9cebeb5f64f9e26b9 Mon Sep 17 00:00:00 2001 From: mpoke Date: Fri, 13 Sep 2024 14:24:19 +0200 Subject: [PATCH] add IBC channel handshake --- .gitignore | 2 +- docs/docs/build/modules/02-provider.md | 54 ++++++++++++++++++++++- docs/docs/build/modules/03-consumer.md | 60 +++++++++++++++++++++++++- 3 files changed, 113 insertions(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index d93ff09e5a..5575d76998 100644 --- a/.gitignore +++ b/.gitignore @@ -5,7 +5,7 @@ release/ docs/tla/states/ *.out vendor/ -build/ +/build/ .vscode .idea __debug_* diff --git a/docs/docs/build/modules/02-provider.md b/docs/docs/build/modules/02-provider.md index 70a3b62d90..f95139aeff 100644 --- a/docs/docs/build/modules/02-provider.md +++ b/docs/docs/build/modules/02-provider.md @@ -29,6 +29,48 @@ The following diagram describes the phases of a consumer chain from the perspect ![Phases of a consumer chain](../../adrs/figures/adr19_phases_of_a_consumer_chain.png) +## IBC Callbacks + +The consumer module is an IBC application that implements the [IBC module callback](https://ibc.cosmos.network/v8/ibc/apps/apps/#create-a-custom-ibc-application-module). + +### OnChanOpenInit + +`OnChanOpenInit` returns an error. `MsgChannelOpenInit` should be sent to the consumer. + +### OnChanOpenTry + +`OnChanOpenTry` validates the parameters of the _CCV channel_ -- an ordered IBC channel connected on the `provider` port +and with the counterparty port set to `consumer` -- and asserts that the counterparty version matches the expected version +(only verions `1` is supported). + +If the validation passes, the provider module verifies that the underlying client is the expected client of the consumer chain +(i.e., the client created during the consumer chain launch) and that no other CCV channel exists for this consumer chain. + +Finally, it sets the [ProviderFeePoolAddr](./03-consumer.md#providerfeepooladdrstr) as part of the metadata. + +### OnChanOpenAck + +`OnChanOpenAck` returns an error. `MsgChannelOpenAck` should be sent to the consumer. + +### OnChanOpenConfirm + +`OnChanOpenConfirm` first verifies that no other CCV channel exists for this consumer chain. Note that this is a sanity check. +Then, it sets the channel mapping in the state. + +### OnChanCloseInit + +`OnChanCloseInit` returns an error. `MsgChannelCloseInit` should be sent to the consumer. + +### OnChanCloseConfirm + +`OnChanCloseConfirm` is a no-op. + +### OnRecvPacket + +### OnAcknowledgementPacket + +### OnTimeoutPacket + ## Messages ### MsgUpdateParams @@ -401,8 +443,12 @@ message MsgSubmitConsumerDoubleVoting { ## Hooks +> TBA + ## Events +> TBA + ## Parameters The provider module contains the following parameters. @@ -502,4 +548,10 @@ As a result, the provider chain can differentiate between _bonded validators_, i.e., validators that have stake locked on the provider chain, and _active validator_, i.e., validators that participate actively in the provider chain's consensus. -## Client \ No newline at end of file +## Client + +### CLI + +### gRPC + +### REST \ No newline at end of file diff --git a/docs/docs/build/modules/03-consumer.md b/docs/docs/build/modules/03-consumer.md index 4af0b3d0cc..5e89941ca9 100644 --- a/docs/docs/build/modules/03-consumer.md +++ b/docs/docs/build/modules/03-consumer.md @@ -25,6 +25,54 @@ As a result, the misbehaving validator is punished on the provider chain. ## State Transitions +## IBC Callbacks + +The consumer module is an IBC application that implements the [IBC module callback](https://ibc.cosmos.network/v8/ibc/apps/apps/#create-a-custom-ibc-application-module). + +### OnChanOpenInit + +`OnChanOpenInit` first verifies that the CCV channel was not already created. +Then, it validates the channel parameters -- an ordered IBC channel connected on the `consumer` port +and with the counterparty port set to `provider` -- and asserts that the version matches the expected version +(only verions `1` is supported). + +Finally, it verifies that the underlying client is the expected client of the provider chain +(i.e., provided in the consumer module genesis state). + +### OnChanOpenTry + +`OnChanOpenTry` returns an error. `MsgChannelOpenTry` should be sent to the provider. + +### OnChanOpenAck + +`OnChanOpenAck` first verifies that the CCV channel was not already created. +Then it verifies that the counterparty version matches the expected version +(only verions `1` is supported). + +If the verification passes, it stores the [ProviderFeePoolAddr](#providerfeepooladdrstr) in the state. + +Finally, if the [DistributionTransmissionChannel](#distributiontransmissionchannel) parameter is not set, +it initiate the opening handshake for a token transfer channel over the same connection as the CCV channel +by calling the `ChannelOpenInit` method of the IBC module. + +### OnChanOpenConfirm + +`OnChanOpenConfirm` returns an error. `MsgChanOpenConfirm` should be sent to the provider. + +### OnChanCloseInit + +`OnChanCloseInit` allow relayers to close duplicate OPEN channels, if the channel handshake is completed. + +### OnChanCloseConfirm + +`OnChanCloseConfirm` is a no-op. + +### OnRecvPacket + +### OnAcknowledgementPacket + +### OnTimeoutPacket + ## Messages ### MsgUpdateParams @@ -50,8 +98,12 @@ message MsgUpdateParams { ## Hooks +> TBA + ## Events +> TBA + ## Parameters :::warning @@ -169,4 +221,10 @@ It is recommended that every consumer chain set and unbonding period shorter tha `RetryDelayPeriod` is the period at which the consumer retries to send a `SlashPacket` that was rejected by the provider. For more details, see [ADR-008](../adrs/adr-008-throttle-retries.md). -## Client \ No newline at end of file +## Client + +### CLI + +### gRPC + +### REST \ No newline at end of file