Add documentation for crosschain message passing #31
+311
−67
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
✅ Deploy Preview for community-contracts ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Amxx
reviewed
Dec 3, 2024
Amxx
reviewed
Dec 3, 2024
Amxx
reviewed
Dec 3, 2024
Amxx
reviewed
Dec 3, 2024
Amxx
reviewed
Dec 3, 2024
Amxx
reviewed
Dec 3, 2024
|
|
||
| The variety of these bridges is outlined in https://x.com/norswap[@norswap]'s https://github.com/0xFableOrg/xchain/blob/master/README.md[Cross-Chain Interoperability Report] that proposes https://github.com/0xFableOrg/xchain/blob/master/README.md#bridge-taxonomy[a taxonomy of 7 bridge categories]. This diversity makes it difficult for developers to design cross-chain applications given the lack of portability. | ||
|
|
||
| This guide will teach you how to follow ERC-7786 to establish messaging gateways across chains regardless of the underlying bridge. Developers can implement gateway contracts that process cross-chain messages and connect any crosschain protocol they want (or implement themselves). |
There was a problem hiding this comment.
This part makes me wonder who is this guide for ? Devs that will build cross-chain apps or devs that will implement the gateway / gateway adatpers ?
There was a problem hiding this comment.
I'd say for devs building cross-chain apps. However, I think it's normal for both to think about connecting an underlying crosschain protocol. I wanted the guide to show how cross-chain communication is built from the ground up and then provide an out-of-the-box adapter like Axelar's
There was a problem hiding this comment.
IMO the whole point of 7786 is that the devs of apps taht perform crosschain operation don't have to implement anything that is specific to underlying protocol. in 95% of the case, they should not be implementing the gateway contracts themselves.
There was a problem hiding this comment.
Would you mind making a suggestion? I don't see how the current code is avoiding the use case you mention. If it's about how it's written, a suggestion would make sense. If it's related to the content, I don't understand if the current formulation is an issue.
Co-authored-by: Hadrien Croubois <[email protected]>
Co-authored-by: Hadrien Croubois <[email protected]>
Co-authored-by: Hadrien Croubois <[email protected]>
Amxx
reviewed
Dec 3, 2024
Amxx
reviewed
Dec 3, 2024
Co-authored-by: Hadrien Croubois <[email protected]>
arr00
reviewed
Jan 8, 2025
Co-authored-by: Arr00 <[email protected]>
arr00
reviewed
Jan 8, 2025
|
|
||
| * {ERC7786Receiver}: ERC-7786 cross-chain message receiver. | ||
|
|
||
| Given ERC-7786 could be enabled natively or via adapters. Developers can access interoperability protocols through gateway adapters. The library includes the following gateway adapters: |
| Gateways are contracts that enable cross-chain communication. These can either be a message source or a destination according to ERC-7786, which defines the following interfaces: | ||
|
|
||
| * {IERC7786GatewaySource}: A contract interface to send a message to another contract on a different chain. | ||
| * {IERC7786Receiver}: An interface that allows an smart contract to receive a crosschain message provided by a trusted destination gateway. |
There was a problem hiding this comment.
Couldn't the gateway itself implement IERC7786Receiver in which case it wouldn't be provided by a trusted destination gateway? Just a nit edge case.
| @@ -33,7 +33,7 @@ abstract contract ERC7786Receiver is IERC7786Receiver { | |||
| } | |||
|
|
|||
| /// @dev Virtual getter that returns whether an address is a valid ERC-7786 gateway. | |||
| function _isKnownGateway(address instance) internal view virtual returns (bool); | |||
Comment on lines
+1
to
+3
| // SPDX-License-Identifier: MIT | ||
|
|
||
| pragma solidity ^0.8.0; |
There was a problem hiding this comment.
Would it be possible to do a git mv here to maintain history?
| @@ -0,0 +1,85 @@ | |||
| = Cross-chain messaging | |||
|
|
|||
| Developers building contracts may require cross-chain functionality. To accomplish it, multiple protocols have implemented their own ways to process operations across chains. | |||
There was a problem hiding this comment.
Suggested change
| Developers building contracts may require cross-chain functionality. To accomplish it, multiple protocols have implemented their own ways to process operations across chains. | |
| Developers building contracts may require cross-chain functionality. To accomplish this, multiple protocols have implemented their own ways to process operations across chains. |
| [.readme-notice] | ||
| NOTE: This document is better viewed at https://docs.openzeppelin.com/community-contracts/api/crosschain | ||
|
|
||
| Gateways are contracts that enable cross-chain communication. These can either be a message source or a destination according to ERC-7786, which defines the following interfaces: |
|
|
||
| This guide will teach you how to follow ERC-7786 to establish messaging gateways across chains regardless of the underlying bridge. Developers can implement gateway contracts that process cross-chain messages and connect any crosschain protocol they want (or implement themselves). | ||
|
|
||
| == ERC-7786 gateway |
There was a problem hiding this comment.
Suggested change
| == ERC-7786 gateway | |
| == ERC-7786 Gateway |
|
|
||
| == ERC-7786 gateway | ||
|
|
||
| To address the lack of composability in a simple and unopinionated way, ERC-7786 proposes a standard to implement a gateway that relays messages to other chains. This generalized approach is expressive enough to enable new types of applications and can be adapted to any bridge taxonomy or specific bridge interface with standardized attributes. |
There was a problem hiding this comment.
Suggested change
| To address the lack of composability in a simple and unopinionated way, ERC-7786 proposes a standard to implement a gateway that relays messages to other chains. This generalized approach is expressive enough to enable new types of applications and can be adapted to any bridge taxonomy or specific bridge interface with standardized attributes. | |
| To address the lack of composability in a simple and unopinionated way, ERC-7786 proposes a standard for implementing gateways that relay messages to other chains. This generalized approach is expressive enough to enable new types of applications and can be adapted to any bridge taxonomy or specific bridge interface with standardized attributes. |
This seems to me like there is one canonical gateway as opposed to each protocol having its own gateway which adheres to the gateway.
|
|
||
| * On the **source chain**, the contract implements a standard xref:api:crosschain.adoc#IERC7786GatewaySource-sendMessage-string-string-bytes-bytes---[`sendMessage`] function and emits a xref:api:crosschain.adoc#IERC7786GatewaySource-MessagePosted-bytes32-string-string-bytes-bytes---[`MessagePosted`] event to signal that the message should be relayed by the underlying protocol. | ||
|
|
||
| * On the **destination chain**, the gateway that receives the message and passes it to the contract receiver by calling the xref:api:crosschain.adoc#IERC7786Receiver-executeMessage-string-string-bytes-bytes---[`executeMessage`] function. |
There was a problem hiding this comment.
Suggested change
| * On the **destination chain**, the gateway that receives the message and passes it to the contract receiver by calling the xref:api:crosschain.adoc#IERC7786Receiver-executeMessage-string-string-bytes-bytes---[`executeMessage`] function. | |
| * On the **destination chain**, the gateway receives the message and passes it to the receiver contract by calling the xref:api:crosschain.adoc#IERC7786Receiver-executeMessage-string-string-bytes-bytes---[`executeMessage`] function. |
|
|
||
| === Getting started with Axelar Network | ||
|
|
||
| To start sending cross-chain messages, developers can get started with a duplex gateway powered by Axelar Network. This will allow a contract to send a receive cross-chain messages from other applications or users leveraging automated execution by Axelar relayers on the destination chain. |
There was a problem hiding this comment.
Suggested change
| To start sending cross-chain messages, developers can get started with a duplex gateway powered by Axelar Network. This will allow a contract to send a receive cross-chain messages from other applications or users leveraging automated execution by Axelar relayers on the destination chain. | |
| To start sending cross-chain messages, developers can get started with a duplex gateway powered by Axelar Network. This will allow a contract to send or receive cross-chain messages from other applications or users leveraging automated execution by Axelar relayers on the destination chain. |
There was a problem hiding this comment.
Not 100% sure what from other applications or users adds.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Adding documentation about how to use our crosschain contracts and how Axelar network can be used as the underlying protocol