Skip to content

Commit

Permalink
Update ORMP Page (#38)
Browse files Browse the repository at this point in the history 
* Add deps

* Update addresses

* update ormp protocol v2

* Revert "update ormp protocol v2"

This reverts commit e4ce744.

* update ormp protocol v2

* Update networks

* Update supported networks

* Update to the latest changes

---------

Co-authored-by: Guantong <i@gt.email>
Co-authored-by: bear <boundless.forest@outlook.com>
  • Loading branch information
@hujw77 @jiguantong @boundless-forest
3 people authored Jun 13, 2024
1 parent fab989e commit 619d2a8
Show file tree
Hide file tree
Showing 4 changed files with 51 additions and 29 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ To build the documentation on your local machine, ensure you have Python and pip
# Clone the repository.
git clone https://github.com/msgport/docs.git && docs
# Install necessary dependencies.
pip install mkdocs-material mkdocs-git-authors-plugin mkdocs-git-revision-date-localized-plugin
pip install mkdocs-material mkdocs-git-authors-plugin mkdocs-git-revision-date-localized-plugin mkdocs-meta-descriptions-plugin mkdocs-redirects
# View the documentation in your browser at `http://127.0.0.1:8000`.
mkdocs serve
```
Expand Down
54 changes: 41 additions & 13 deletions docs/build/networks.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,28 +5,56 @@ The [Msgport Protocol](./../index.md) is a robust and reliable cross-chain messa
## Canonical Cross-chain Contract

The Msgport protocol is a set of contracts that defines the [core interfaces](./interfaces.md) for sending and receiving cross-chain messages. You can think of it as an abstract class in programming, with `Msgport` as its name.
This abstract class can have multiple subclasses, known as messaging protocols, which extend its functionality. Each of these subclasses must adhere to the interfaces defined in the Msgport protocol. To be user-friendly, each messaging protocol has
This abstract class can have multiple subclasses, known as messaging protocols, which extend its functionality. Each of these subclasses must adhere to the interfaces defined in the Msgport protocol. To be user-friendly, most of the messaging protocol has
its unique contract address across all the networks it supports. The table below shows the canonical cross-chain contract address for each supported network.

| Name | Canonical Cross-chain Contract Address |
|------------|--------------------------------------------|
| [ORMP](../learn/messaging-protocols/ormp.md) | 0x0000000005d961F950adA391C1511c92bbc64D9F |
| Contract | Canonical Cross-chain Deployment Address |
|------------------------|--------------------------------------------|
| SubAPIMultiSig | 0x22117Db68370590c1031f52a6D1aDE3DCe0cCf9a |
| [ORMP](../learn/messaging-protocols/ormp.md) | 0x13b2211a7cA45Db2808F6dB05557ce5347e3634e |
| Oracle | 0xBE01B76AB454aE2497aE43168b1F70C92Ac1C726 |
| Relayer | 0x114890eB7386F94eae410186F20968bFAf66142a |
| ORMPUpgradeablePort | 0x2cd1867Fb8016f93710B6386f7f9F1D540A60812 |
| MsgDeployer | 0x040f331774Ed6BB161412B4cEDb1358B382aF3A5 |

However, the Tron network and it's testnet(Shasta) have its their canonical cross-chain contract address due to its special design, list below:

| Contract | Canonical Cross-chain Deployment Address |
|--------------------------|--------------------------------------------|
| Tron SUBAPIMultiSig | TMP3K1GjRgsXAUHX1jkBaBwaordRi9gHRH |
| [Tron ORMP](../learn/messaging-protocols/ormp.md) | TJPZeFEdc4TBEcNbku5xVZLQ6B2Q1oGnd1 |
| Tron Oracle | TV9FgX1jHSg1k6kEaZtYR2ZH4AdqnMCDak |
| Tron Relayer | TSZgvR9xTGeG3RXcUKnWWcUAAAEskXdCHj |
| Tron ORMPUpgradeablePort | TFRF7t9m7pGLnwwX8TFsZvj85EvQ6gSBCm |

| Contract | Canonical Cross-chain Deployment Address |
|---------------------------|--------------------------------------------|
| Shasta SUBAPIMultiSig | TEYbMKVNpumbN5myf5uN6VgFStckj9DGe5 |
| [Shasta ORMP](../learn/messaging-protocols/ormp.md) | TPJifBA5MvFf918VYnajd2XmEept4iBX55 |
| Shasta Oracle | TDULRJrJ2bbsvW3KKtEnnq9moPn5PyUWpd |
| Shasta Relayer | TZGjiJcoqUo6JSZeYvrwN6qvpEcLm21QbG |
| Shasta ORMPUpgradeablePort | TSZCvXyP618r4AxYmVD15Zu46VB3AFeAyd |

## Supported Networks

The ORMP messaging protocol is available on the following main/test networks, which means you can integrate cross-chain capabilities into your application without needing to deploy the underlying messaging protocol yourself. If your desired network is not listed, please feel free to reach out to our team for support and we will be happy to assist you.

### For Mainnet

- [Ethereum](https://etherscan.io/address/0x0000000005d961F950adA391C1511c92bbc64D9F) ⇋ [Arbitrum](https://arbiscan.io/address/0x0000000005d961F950adA391C1511c92bbc64D9F)
- [Ethereum](https://etherscan.io/address/0x0000000005d961F950adA391C1511c92bbc64D9F) ⇋ [Darwinia](https://darwinia.subscan.io/account/0x0000000005d961F950adA391C1511c92bbc64D9F)
- [Arbitrum](https://arbiscan.io/address/0x0000000005d961F950adA391C1511c92bbc64D9F) ⇋ [Darwinia](https://darwinia.subscan.io/account/0x0000000005d961F950adA391C1511c92bbc64D9F)
- [Arbitrum](https://arbiscan.io/address/0x0000000005d961F950adA391C1511c92bbc64D9F) ⇋ [Blast](https://blastscan.io/address/0x0000000005d961F950adA391C1511c92bbc64D9F)
- [Polygon](https://polygonscan.com/address/0x0000000005d961F950adA391C1511c92bbc64D9F) ⇋ [Darwinia](https://darwinia.subscan.io/account/0x0000000005d961F950adA391C1511c92bbc64D9F)
- [Crab](https://crab.subscan.io/account/0x0000000005d961F950adA391C1511c92bbc64D9F) ⇋ [Darwinia](https://darwinia.subscan.io/account/0x0000000005d961F950adA391C1511c92bbc64D9F)
- [Darwinia](https://darwinia.subscan.io/account/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e) ⇋ [Crab](https://crab.subscan.io/account/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e)
- [Darwinia](https://darwinia.subscan.io/account/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e) ⇋ [Arbitrum](https://arbiscan.io/address/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e)
- [Darwinia](https://darwinia.subscan.io/account/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e) ⇋ [Ethereum](https://etherscan.io/address/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e)
- [Darwinia](https://darwinia.subscan.io/account/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e) ⇋ [Polygon](https://polygonscan.com/address/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e)
- [Darwinia](https://darwinia.subscan.io/account/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e) ⇋ [Moonbeam](https://moonscan.io/address/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e)
- [Darwinia](https://darwinia.subscan.io/account/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e) ⇋ [Tron](https://tronscan.org/#/contract/TJPZeFEdc4TBEcNbku5xVZLQ6B2Q1oGnd1)
- [Arbitrum](https://arbiscan.io/address/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e) ⇋ [Blast](https://blastscan.io/address/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e)
- [Ethereum](https://etherscan.io/address/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e) ⇋ [Arbitrum](https://arbiscan.io/address/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e)

### For Testnet

- [Sepolia](https://sepolia.etherscan.io/address/0x0000000005d961F950adA391C1511c92bbc64D9F) ⇋ [Arbitrum Sepolia](https://sepolia.arbiscan.io/address/0x0000000005d961F950adA391C1511c92bbc64D9F)
- [Sepolia](https://sepolia.etherscan.io/address/0x0000000005d961F950adA391C1511c92bbc64D9F) ⇋ [Pangolin](https://pangolin.subscan.io/account/0x0000000005d961F950adA391C1511c92bbc64D9F)
- [Arbitrum Sepolia](https://sepolia.arbiscan.io/address/0x0000000005d961F950adA391C1511c92bbc64D9F) ⇋ [Pangolin](https://pangolin.subscan.io/account/0x0000000005d961F950adA391C1511c92bbc64D9F)
- [Darwinia Koi](https://koi-scan.darwinia.network/address/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e) ⇋ [Arbitrum Sepolia](https://sepolia.arbiscan.io/address/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e)
- [Darwinia Koi](https://koi-scan.darwinia.network/address/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e) ⇋ [Tron Shasta](https://shasta.tronscan.org/#/contract/TPJifBA5MvFf918VYnajd2XmEept4iBX55)
- [Darwinia Koi](https://koi-scan.darwinia.network/address/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e) ⇋ [Sepolia](https://sepolia.etherscan.io/address/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e)
- [Sepolia](https://sepolia.etherscan.io/address/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e) ⇋ [Arbitrum Sepolia](https://sepolia.arbiscan.io/address/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e)
- [Sepolia](https://sepolia.etherscan.io/address/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e) ⇋ [Tron Shasta](https://shasta.tronscan.org/#/contract/TPJifBA5MvFf918VYnajd2XmEept4iBX55)
- [Arbitrum Sepolia](https://sepolia.arbiscan.io/address/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e) ⇋ [Taiko Hekla](https://explorer.hekla.taiko.xyz/address/0x13b2211a7cA45Db2808F6dB05557ce5347e3634e)
Binary file modified docs/images/msgport-ormp-1.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
24 changes: 9 additions & 15 deletions docs/learn/messaging-protocols/ormp.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ ORMP stands for Oracle Relayer Messaging Protocol. It is an omni-chain messaging

- The Oracle

In this context refers to any source of credible off-chain data. In ORMP, this data refers specifically to the root of an incremental merkle tree composed of cross-chain messages. We refer to this as the `message root` or `msgroot` for short. The message root is used to verify the authenticity of the cross-chain messages. The Oracle can either be a traditional off-chain data service, or a data feed based on the light client. Both of these methods can be used to provide the message root of another chain.
In this context refers to any source of credible off-chain data. In ORMP, this data refers specifically to the hash of cross-chain message, we refer to this as the `message hash`. The message hash is used to verify the authenticity of the cross-chain messages. The Oracle can either be a traditional off-chain data service, or a data feed based on the light client. Both of these methods can be used to provide the message root of another chain.

- The Relayer

Expand All @@ -15,8 +15,7 @@ These two roles play a vital role in the entire process of sending, verifying, a

## Highlight Features

- The cross-chain application provides the option to choose a different Oracle and Relayer if the user does not trust the ones provided by the official team.
- Messages are stored in an incremental Merkle tree, and the target chain relies on the tree root to validate the legitimacy of the received message.
- The cross-chain application provides the option to choose a different Oracle and Relayer if the user does not trust the ones provided by the official team.
- The protocol does not guarantee the ordering of messages. However, the application has the option to maintain a nonce or a unique identifier to ensure that messages are received in the correct order, if ordering is necessary. This allows for ordered delivery of messages, even if the protocol itself doesn't provide that guarantee.

## Message Flow Design
Expand All @@ -40,35 +39,30 @@ struct Message {
}
```

Please be aware that within the channel, all messages are organized in an incremental Merkle tree. The channel is also tasked with receiving and distributing messages, as well as overseeing the management of the message root and its status.

!!! note
An [incremental Merkle Tree](https://arxiv.org/abs/2105.06009) is a [Merkle Tree](https://en.wikipedia.org/wiki/Merkle_tree) of fixed depth where each leaf start as a zero value, and non-zero values are added by replacing the zero leaves starting from the left-most leaf to the right-most leaf one-by-one.
**The Incremental Merkle Tree is a gas efficient Merkle Tree.**
Please be aware that the channel is tasked to store, receive and distribute messages, as well as overseeing the management of the message hash and its status.

### Message Sending Flow

1. The cross-chain application, built on the msgport interface **[IMessagePort](../../build/interfaces.md#imessageport)**, invokes the **`send(from, toChainId, to, gasLimit, encoded_call)`** method of the ORMP. This method is a payable method, meaning it requires the payment of a specific fee to execute. The fee structure is further explained below.
2. Upon receiving the message, the ORMP contracts store it in an Incremental Merkle Tree, emit the `MessageAccepted` event and return msgHash to the sender as the an identifier for that message.
3. The ORMP contracts then invoke the specified relayer and oracle that have been previously registered with the protocol, emitting the `OracleAssigned` and `RelayerAssigned` event to signal the start of their respective tasks.
2. Upon receiving the message, the ORMP contracts emit the `MessageAccepted` event and return msgHash to the sender as the an identifier for that message.
3. The ORMP contracts then invoke the specified relayer and oracle that have been previously registered with the protocol, emitting the `MessageAssigned` to signal the start of their respective tasks.

Once these two steps are completed, the message sending process is considered finished.

### Message Relaying Flow

The message relaying consists of two crucial roles: the relayer and the oracle service. These components continuously monitor the on-chain ORMP events to determine if there are new tasks assigned to them.

- When the relayer detects a new event, it retrieves the corresponding MessageAccepted event and extracts detailed information about the message from the ORMP contract. It then constructs a message proof using the incremental tree in the corresponding channel of the ORMP. The relayer invokes the `relay(Message calldata message, bytes calldata proof)` method on the relayer contract on the target chain, completing the relay of the message and its proof.
- When the oracle detects a new event, the oracle nodes fetch the corresponding `msg_root` which contains the message. They sign the `msg_root` and send it to a specific multisig contract, which collects all the oracle node signatures. Once the multisig contract gathers enough signatures (typically 3/5), the oracle network triggers the setting of the `msg_root` to the oracle component in the ORMP contracts, completing the relay of the `msg_root`.
- When the relayer detects a new event, it retrieves the corresponding `MessageAccepted` event and extracts detailed information about the message from the ORMP contract. It then invokes the `relay(Message calldata message)` method on the relayer contract on the target chain, completing the relay of the message and its proof.
- When the oracle detects a new event, the oracle nodes fetch the corresponding `msg_hash` of the message. They sign the `msg_hash` and send it to a specific multisig contract, which collects all the oracle node signatures. Once the multisig contract gathers enough signatures (typically 3/5), the oracle network triggers the setting of the `msg_hash` to the oracle component in the ORMP contracts, completing the relay of the `msg_hash`.

For the message to be executed in the ORMP target chain contracts, it requires both the message payload, proof, and a valid oracle `msg_root`.
For the message to be executed in the ORMP target chain contracts, it requires both the message payload, proof, and a valid oracle `msg_hash`.

### Message Receiving Flow

When the `relay` method of the target chain contract is invoked, it performs the following validations:

- Verifies that the sender (relayer) is registered.
- Ensures the proof corresponds with the `msg_root`.
- Confirms that the message's `to` field matches the destination `chainId`.
- Checks whether the message has already been dispatched.

Expand Down Expand Up @@ -99,4 +93,4 @@ $$

$$
PayloadFee = gasPerByte * size * dstGasPriceInWei * dstPriceRatio
$$
$$

0 comments on commit 619d2a8

Please sign in to comment.