diff --git a/README.md b/README.md index 37c45b8..6c166cf 100644 --- a/README.md +++ b/README.md @@ -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 ``` diff --git a/docs/build/networks.md b/docs/build/networks.md index 37c64ae..8363d87 100644 --- a/docs/build/networks.md +++ b/docs/build/networks.md @@ -5,12 +5,35 @@ 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 @@ -18,15 +41,20 @@ The ORMP messaging protocol is available on the following main/test networks, wh ### 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) \ No newline at end of file +- [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) diff --git a/docs/images/msgport-ormp-1.png b/docs/images/msgport-ormp-1.png index bb34187..e525eb5 100644 Binary files a/docs/images/msgport-ormp-1.png and b/docs/images/msgport-ormp-1.png differ diff --git a/docs/learn/messaging-protocols/ormp.md b/docs/learn/messaging-protocols/ormp.md index 92c1e9a..9188592 100644 --- a/docs/learn/messaging-protocols/ormp.md +++ b/docs/learn/messaging-protocols/ormp.md @@ -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 @@ -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 @@ -40,17 +39,13 @@ 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. @@ -58,17 +53,16 @@ Once these two steps are completed, the message sending process is considered fi 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. @@ -99,4 +93,4 @@ $$ $$ PayloadFee = gasPerByte * size * dstGasPriceInWei * dstPriceRatio -$$ \ No newline at end of file +$$