feat: add Create your messaging protocol content #24
Conversation
✅ Deploy Preview for toposware-docs-platform ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
@wyhaines This is still WIP, that's why I had not set any reviewer (but I should have created the PR as a draft). |
|
I assumed that it was simply going to be iterative content. Get something released now, and then build on it. Regardless, what you wrote reads fine to me, so I really am in favor of publishing sooner rather than later. |
|
|
||
| 1. The **ToposCore** smart contract can be used to store certificates on-chain. Although not compulsory, it makes sense for a subnet to have a single instance of such a certificate-storing smart contract. | ||
| 2. The **ToposMessaging** smart contract makes use of ToposCore. It has functions to verify proofs of inclusion and to mark completed messages as used, thereby preventing replay. It is not meant to be deployed directly, but instead to be used as an inherited smart contract for the messaging protocol proper. | ||
| 2. The **ToposMessaging** smart contract gathers functionalities that are core to messaging protocols. It has functions to verify proofs of inclusion and to mark completed messages as used, thereby preventing replay. To ease the development of new messaging protocols, these functionalities can be obtained for free by creating a messaging protocol smart contract that inherits ToposMessaging. |
There was a problem hiding this comment.
The two core features mentioned here, inclusion proofs and replay attack resistance, are not very well motivated. Why would I want a "messaging protocol"? Can we emphasize that such protocols are for cross-subnet apps? And that the approach is that each dApp develops their own such protocol. Once motivated, the idea and advantage of using a ToposMessaging contract as the basis is easier to convey imo.
There was a problem hiding this comment.
Would it be fair to say that this is part of a different piece work, a rework of B9's content?
This PR contains changes in the first module because a few things were unclear. Now, adding things that make sense like what you said would require re-working a greater piece of the content, notably the way we introduce messaging protocols in the whole portal, which sounds like something much bigger than a simple PR comment suggestion application, no?
There was a problem hiding this comment.
That is a fair POV. I think it would be reasonable to create a ticket to follow this PR up with some additional work that clarifies those other areas more.
Otherwise, yes, there is the risk that the scope creeps too much on this set of changes. I'd rather see the content live soon, even if there are things that can be adjusted and improved later.
|
|
||
| 1. The **ToposCore** smart contract can be used to store certificates on-chain. Although not compulsory, it makes sense for a subnet to have a single instance of such a certificate-storing smart contract. | ||
| 2. The **ToposMessaging** smart contract makes use of ToposCore. It has functions to verify proofs of inclusion and to mark completed messages as used, thereby preventing replay. It is not meant to be deployed directly, but instead to be used as an inherited smart contract for the messaging protocol proper. | ||
| 2. The **ToposMessaging** smart contract gathers functionalities that are core to messaging protocols. It has functions to verify proofs of inclusion and to mark completed messages as used, thereby preventing replay. To ease the development of new messaging protocols, these functionalities can be obtained for free by creating a messaging protocol smart contract that inherits ToposMessaging. |
There was a problem hiding this comment.
| 2. The **ToposMessaging** smart contract gathers functionalities that are core to messaging protocols. It has functions to verify proofs of inclusion and to mark completed messages as used, thereby preventing replay. To ease the development of new messaging protocols, these functionalities can be obtained for free by creating a messaging protocol smart contract that inherits ToposMessaging. | |
| 2. The **ToposMessaging** smart contract gathers features that are core to messaging protocols. It has functions to verify proofs of inclusion and to mark completed messages as used, thereby preventing replay. To ease the development of new messaging protocols, such features can be had for free by creating a messaging protocol smart contract that inherits ToposMessaging. |
|
|
||
| # Create your messaging protocol | ||
|
|
||
| Developing a custom messaging protocol is in essence about writing a smart contract, in the fashion of **ERC20Messaging**, that 1. inherits **ToposMessaging** to get set and ready with the core functionalities needed for cross-subnet messaging (e.g., emitting a special event to announce a cross-subnet message, verifying a proof of receipt inclusion) on a sending and a receiving subnet, and 2. adds the custom business logic that governs the cross-subnet message execution (e.g., burning and minting an internal ERC20 token in **ERC20Messaging**). |
There was a problem hiding this comment.
| Developing a custom messaging protocol is in essence about writing a smart contract, in the fashion of **ERC20Messaging**, that 1. inherits **ToposMessaging** to get set and ready with the core functionalities needed for cross-subnet messaging (e.g., emitting a special event to announce a cross-subnet message, verifying a proof of receipt inclusion) on a sending and a receiving subnet, and 2. adds the custom business logic that governs the cross-subnet message execution (e.g., burning and minting an internal ERC20 token in **ERC20Messaging**). | |
| Developing a custom cross-subnet messaging protocol is in essence about writing a pair of smart contracts, in the fashion of **ERC20Messaging**, that 1. inherits **ToposMessaging** for the core features needed for cross-subnet messaging (e.g., emitting a special event to announce a message, or verifying a proof of receipt inclusion) on a sending and a receiving subnet, and 2. adds the custom business logic that governs the cross-subnet message execution (e.g., burning and minting an internal ERC20 token in **ERC20Messaging**). |
There was a problem hiding this comment.
I will apply it except the "cross-subnet" addition to "messaging protocol" ("messaging protocol" is a term that's been used as is in the rest of the doc), and the "pair of" (there's only one contract to develop)
|
|
||
| From start to end, a messaging protocol walks the following path: | ||
|
|
||
| 1- An arbitrary business logic is executed on the sending subnet |
There was a problem hiding this comment.
| 1- An arbitrary business logic is executed on the sending subnet | |
| 1- An arbitrary piece of business logic is executed on the sending subnet |
|
|
||
| 3- A specific transaction is sent to the receiving subnet in order to validate and execute the cross-subnet message | ||
|
|
||
| 4- An arbitary business logic is executed on the receiving subnet |
There was a problem hiding this comment.
| 4- An arbitary business logic is executed on the receiving subnet | |
| 4- An arbitrary piece of business logic is executed on the receiving subnet |
…or perhaps just "Some business logic is executed…"
|
|
||
| 1- Burn the amount that the caller requested to send to another subnet | ||
|
|
||
| 4- Verify that the address of the **ERC20Messaging** contract on the sending subnet corresponds to the current one (i.e., on the receiving subnet), verify that the requested receiving subnet is the correct one, retrieve the requested ERC20 token, and finally mint the right amount to the right recipient |
There was a problem hiding this comment.
Verify that the address…
Is it obvious to readers why the sending and receiving contract addresses must match? I think not?
There was a problem hiding this comment.
It isn't but I don't think it should as it is introduced as an arbitrary check that ERC20 got its design built upon. But you still think it should come with a reason?
|
|
||
| </HighlightBox> | ||
|
|
||
| Now, we will detail the ToposMessaging interface and its relevant methods for you to start leveraging its power. |
There was a problem hiding this comment.
| Now, we will detail the ToposMessaging interface and its relevant methods for you to start leveraging its power. | |
| Now, we will detail the ToposMessaging interface and its relevant methods for you to use it. |
|
|
||
| ## ToposMessaging | ||
|
|
||
| Like messaging protocol contracts inheriting it, **ToposMessaging** exposes functionalities that relate either to the sending subnet or the receiving subnet in a cross-subnet messaging flow. |
There was a problem hiding this comment.
| Like messaging protocol contracts inheriting it, **ToposMessaging** exposes functionalities that relate either to the sending subnet or the receiving subnet in a cross-subnet messaging flow. | |
| Like messaging protocol contracts inheriting it, **ToposMessaging** exposes features that relate either to the sending subnet or the receiving subnet in a cross-subnet messaging flow. |
|
|
||
| ### Sending subnet (1) | ||
|
|
||
| - `_emitMessageSentEvent(SubnetId targetSubnetId)`: This function expects a target subnet id which is the id of the receiving subnet, and takes care of emitting the specific event mentioned in Messaging protocol flow, point 2. This event is **ToposCore**'s **CrossSubnetMessageSent** event, which is not defined in **ToposMessaging**, hence the `_emitMessageSentEvent` helper function. |
There was a problem hiding this comment.
It would be good to link to the CrossSubnetMessageSent docs&code here.
|
I built locally, and some things aren't rendering right. I haven't gone back through yet to try to figure out what, but I wanted to verify that others are seeing it this way, too? |
| @@ -1,6 +1,7 @@ | |||
| .highlightbox { | |||
| * { | |||
| @apply text-inherit; | |||
| overflow: scroll; | |||
There was a problem hiding this comment.
This is causing a poor visual experience with the highlight boxes:
There was a problem hiding this comment.
So, additional context, I see why you did this.
This (without the overflow: scroll) is being caused by an interaction with the highlight box. The code boxes, either the flavor that one gets with the markdown syntax, or by explicitly using a CodeBox component, do not behave properly with regard to scroll and their overflow boundaries when they are inside of a HighlightBox.
The best thing here would be to solve why the highlightbox is breaking things. I can try to figure that out, as it has repercussions across multiple sites, and update here.
|
|
||
| You now should have a deep understanding of what messaging protocols are in the Topos ecosystem and how they work. You got to see what **ToposMessaging** is and what functionalities it offers to messaging protocol developers ready to jump into the world of cross-subnet messaging. **ERC20Messaging**, the messaging protocol that we developed and deployed on our different networks, was mentioned many times to illustrate with a concrete example the steps that compose the development and use of a messaging protocol. | ||
|
|
||
| The next steps after writing your messaging protocol will be to create a dapp-frontend, if needed, to let your users start using your dApp, and start, if needed too, interacting with the Executor Service to delegate that `execute` function call to it (and prevent your users from paying transaction fees twice). |
There was a problem hiding this comment.
| The next steps after writing your messaging protocol will be to create a dapp-frontend, if needed, to let your users start using your dApp, and start, if needed too, interacting with the Executor Service to delegate that `execute` function call to it (and prevent your users from paying transaction fees twice). | |
| The next steps after writing your messaging protocol will be to create a dapp-frontend, if needed, to let your users start using your dApp, and to start, if needed, interacting with the Executor Service to delegate the `execute` function call to it (and prevent your users from paying transaction fees twice). |
|
|
||
| **ERC20Messaging** emits, on a sending subnet, the following `TokenSent` event to detail which cross-subnet ERC20 transfer was requested: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
| ``` | |
| ```solidity |
The syntax highlighter that we use handles Solidity.
There was a problem hiding this comment.
Nice, I didn't expect the syntax highlighter to work on the dev portal (thought this was github only).
|
|
||
| 3- Emits the **CrossSubnetMessageSent** core event to announce the cross-subnet message | ||
|
|
||
| ``` |
There was a problem hiding this comment.
| ``` | |
| ```solidity |
|
|
||
| Only the last line that emits the **CrossSubnetMessageEvent** is a requirement for all messaging protocols. So if we were to name the first function of **CustomMessaging** `doSomething`, `doSomething` would have the following structure: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
| ``` | |
| ```solidity |
|
|
||
| Now that you have retrieved the right log index, you can retrieve the rest of the log's data you are interested in: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
| ``` | |
| ```solidity |
| <br/> | ||
| As we can see, it starts by retrieving the expected index of the `TokenSent` event. | ||
|
|
||
| ``` |
There was a problem hiding this comment.
| ``` | |
| ```solidity |
| <br/> | ||
| Then, from the right index, the address of the contract that emitted the `TokenSent` event is retrieved and compared to the current address (the address of the **ERC20Messaging** smart contract instance being used). This is because **ERC20Messaging** expects all instances of its contract to be deployed at the same address on all subnets. | ||
|
|
||
| ``` |
There was a problem hiding this comment.
| ``` | |
| ```solidity |
| <br/> | ||
| Next, from the right index and the corresponding array of topics, the target subnet id is retrieved. Index `1` is used because the first topic of an EVM event is the event signature, and the next are the indexed arguments of the event and `targetSubnetId` is the first and only indexed argument of the `TokenSent` event. | ||
|
|
||
| ``` |
There was a problem hiding this comment.
| ``` | |
| ```solidity |
| <br/> | ||
| Finally, the data field is decoded and the data to be used to execute the cross-subnet ERC20 transfer is retrieved (token symbol, receiver address, and amount), before the transfer gets executed by minting the token. | ||
|
|
||
| ``` |
There was a problem hiding this comment.
| ``` | |
| ```solidity |
Co-authored-by: Jawad <38837406+JDawg287@users.noreply.github.com>
Co-authored-by: Jawad <38837406+JDawg287@users.noreply.github.com>
@wyhaines I think this is windows only (overflow scroll shows invisible scrolling bars on mac). I will find another fix to replace the |
Description
This PR adds new content about creating one's own messaging protocol.
Fixes TOO-414
PR Checklist: