Merge pull request #974 from oasisprotocol/rube/router-newsection

New section for Router Protocol

docs/dapp/diagrams/opl-router-pingpong-flow.mmd

@@ -0,0 +1,16 @@
+sequenceDiagram
+    participant User
+    participant P-A as PingPong.sol<br/>(Chain A)
+    participant G-A as Gateway<br/>(Chain A)
+    participant Relayer as Router Chain<br/>& Relayer
+    participant G-B as Gateway<br/>(Chain B)
+    participant P-B as PingPong.sol<br/>(Chain B)
+    User->>+P-A: iPing()
+    P-A->>+G-A: iSend()
+    G-A-->>Relayer: Listens to event
+    Relayer-->>+G-B: Relays message
+    G-B->>+P-B: iReceive()
+    P-B->>-G-B: Response from<br/>iReceive()
+    G-B-->>-Relayer: Listens to event
+    Relayer-->>G-A: Relays message
+    G-A->>-P-A: iAck()

docs/dapp/opl/router-protocol/README.md

@@ -0,0 +1,94 @@
+---
+description: Cross-chain dApps with Router Protocol
+---
+
+# Router Protocol
+
+Router Protocol offers two frameworks for cross-chain interactions:
+
+- **Router CrossTalk**: Enables stateless and stateful cross-chain messaging
+- **Router Nitro**: Facilitates native cross-chain asset transfers
+
+For guidance on choosing the appropriate framework, refer to Router's [guide].
+
+This documentation focuses on **Router CrossTalk**. If you're primarily
+interested in asset transfers, please consult the [Router Nitro documentation].
+
+[Router Nitro documentation]: https://docs.routerprotocol.com/develop/category/asset-transfer-via-nitro
+[guide]: https://docs.routerprotocol.com/overview/choosing-the-right-framework
+
+## Router CrossTalk
+
+Router CrossTalk is designed to enable cross-chain interactions, allowing
+developers to create decentralized applications (dApps) that operate across
+multiple blockchain networks. This framework supports both stateless and
+stateful operations, providing flexible and efficient communication between
+contracts on different chains.
+
+### Architecture
+
+![Router Architecture](../../images/opl/router-architecture.png)
+*High-level architecture diagram for Router CrossTalk[^1]*
+
+[^1]: The CrossTalk high-level architecture diagram is courtesy of [Router documentation][router-architecture].
+
+[router-architecture]: https://docs.routerprotocol.com/develop/message-transfer-via-crosstalk/key-concepts/high-level-architecture
+
+The **CrossTalk** infrastructure consists of three main components:
+
+- **Gateway** contracts on source and destination chains
+- **Orchestrators** on the Router chain
+- **Relayers** that forward messages to the Router Gateway contracts
+
+The process flow is as follows:
+
+1. The dApp contract calls the iSend function on the source chain's Gateway
+   contract.
+2. Orchestrators monitor events emitted by the Gateway contract.
+3. A Relayer picks up the transaction signed by the orchestrator and forwards
+   the message to the destination chain's Router Gateway contract.
+4. Gateway contract on the destination chain calls the dApp contract's
+   `iReceive` function.
+5. For acknowledgment, the process is reversed, and the Relayer calls the
+   `iAck` function on the dApp contract on the source chain.
+
+### Fees
+
+Fees in the cross-chain messaging process are paid by two parties:
+
+- The dApp **user** pays when initiating the transaction on the source chain.
+- The dApp **fee payer** pre-pays the Relayers for calling the Router Gateway
+  contract.
+
+To ensure the correct **fee payer** is used, the dApp's contract must register
+the fee payer address as metadata with the Router Gateway. Additionally, the
+**fee payer** needs to approve the conntract on the Router chain, which can be
+done through the [Router Explorer].
+
+For more info about the [fee management], consult the Router documentation.
+
+[Router Explorer]: https://testnet.routerscan.io/feePayer
+[fee management]: https://docs.routerprotocol.com/develop/message-transfer-via-crosstalk/key-concepts/fee-management
+
+
+### Examples
+
+:::note Example: PingPong
+
+Explore our [PingPong example] to see Router CrossTalk in action.
+
+:::
+
+[PingPong example]: ./pingpong-example.md
+
+For more examples, refer to the  [Router Protocol documentation]:
+
+- [Cross-Chain NFT]
+- [Cross-Chain Read Request]
+
+and in the Router Protocol [CrossTalk sample repository].
+
+[Router Protocol documentation]: https://docs.routerprotocol.com/develop/message-transfer-via-crosstalk
+[Cross-Chain NFT]: https://docs.routerprotocol.com/develop/message-transfer-via-crosstalk/evm-guides/your-first-crosschain-nft-contract
+[Cross-Chain Read Request]: https://docs.routerprotocol.com/develop/message-transfer-via-crosstalk/evm-guides/cross-chain-read-requests
+[CrossTalk sample repository]: https://github.com/router-protocol/new-crosstalk-sample/

docs/dapp/opl/router-protocol/approve.md

@@ -0,0 +1,60 @@
+---
+description: Approving fee payer in Router Protcol
+---
+
+# Approving the Fee Payer
+
+According to Router Protocol's [fee management] system, cross-chain requests
+initiated by a dApp are paid for by the dApp's corresponding fee payer account
+on the Router Chain. This fee payer is registered by calling the
+`setDappMetadata` function on the gateway contract.
+
+## Obtaining Test Tokens
+
+To interact with the Router Protocol testnet, you'll need `ROUTE` test tokens.
+Follow these steps to obtain them from the Router Faucet:
+
+1. Visit the [Router Faucet] website.
+2. Connect your MetaMask wallet.
+3. Add the Router Test Network to your MetaMask if prompted.
+4. Enter your account address in the provided field.
+5. Click the `Get Test Tokens` button.
+
+![Router Test Faucet](../../images/opl/router-faucet.png)
+
+## Approving Contracts in Router Explorer
+
+After deploying your contracts, you need to approve the fee payer for each of
+them. Here's how to do it using the Router Explorer:
+
+1. Navigate to the [Router Explorer].
+2. Connect your wallet by clicking the "Connect Wallet" button.
+3. Once connected, you'll see a list of pending approvals for your deployed
+contracts.
+
+![Router Approvals](../../images/opl/router-approve.png)
+
+4. For each contract listed, click the `Approve` button.
+5. Follow the prompts in your wallet to sign the approval message.
+
+:::info
+
+If you don't see your deployed contracts in the list, it's possible you used an
+incorrect gateway address for the chain during deployment. Verify the current
+gateway addresses in the [Router Protocol documentation].
+
+:::
+
+## Troubleshooting
+
+If you encounter any issues during the approval process, consider the following:
+
+- Ensure you have sufficient ROUTE test tokens in your wallet.
+- Verify that you're connected to the correct network in MetaMask.
+- Double-check that the contracts were deployed with the correct gateway
+  addresses.
+
+[fee management]: https://docs.routerprotocol.com/develop/message-transfer-via-crosstalk/key-concepts/fee-management
+[Router Faucet]: https://faucet.routerprotocol.com/
+[Router Explorer]: https://testnet.routerscan.io/feePayer
+[Router Protocol documentation]: https://docs.routerprotocol.com/networks/supported-chains#for-testnet

docs/dapp/opl/router-protocol/interface.md

@@ -0,0 +1,164 @@
+---
+description: Router Protocol Interfaces
+---
+
+# Router Interfaces
+
+Router Protocol provides the `evm-gateway-contracts` library to facilitate the
+development of cross-chain dApps.
+
+## Installation
+
+### Using Remix
+
+If you're using [Remix], you can import the contracts directly as shown in the
+examples below.
+
+[Remix]: https://remix.ethereum.org/
+
+### Using Hardhat
+
+For Hardhat projects, install the package via npm, yarn or pnpm:
+
+```shell npm2yarn
+npm install @routerprotocol/evm-gateway-contracts
+```
+
+## Gateway
+
+The Router Gateway is deployed on all chains supported by Router Protocol and
+serves as the central communication point between chains.
+
+### IGateway
+
+```solidity
+import "@routerprotocol/evm-gateway-contracts/contracts/IGateway.sol";
+```
+To develop cross-chain contracts, you should generally:
+
+1. Import the `IGateway.sol` interface into all cross-chain contracts
+2. Create a variable to store the Gateway contract address
+3. Initialize it with the corresponding Gateway address of the given chain
+
+This setup will be used later to call the `iSend` function.
+
+### iSend()
+
+```solidity
+function iSend(
+  uint256 version,
+  uint256 routeAmount,
+  string calldata routeRecipient,
+  string calldata destChainId,
+  bytes calldata requestMetadata,
+  bytes calldata requestPacket
+) external payable returns (uint256);
+```
+
+`iSend` is the function you'll call on the Gateway of the source chain to
+initiate a cross-chain message. Every contract that wants to make a cross-chain
+call needs to call it.
+
+For a detailed description of each parameter, refer to the Router Protocol
+[iSend documentation].
+
+[iSend documentation]: https://docs.routerprotocol.com/develop/message-transfer-via-crosstalk/evm-guides/iDapp-functions/iSend
+
+### getRequestMetaData()
+
+```solidity
+    function getRequestMetadata(
+    uint64 destGasLimit,
+    uint64 destGasPrice,
+    uint64 ackGasLimit,
+    uint64 ackGasPrice,
+    uint128 relayerFees,
+    uint8 ackType,
+    bool isReadCall,
+    string memory asmAddress
+) public pure returns (bytes memory) {
+    bytes memory requestMetadata = abi.encodePacked(
+    destGasLimit,
+    destGasPrice,
+    ackGasLimit,
+    ackGasPrice,
+    relayerFees,
+    ackType,
+    isReadCall,
+    asmAddress
+    );
+    return requestMetadata;
+}
+```
+The `getRequestMetadata` function helps create the `requestMetadata` bytes
+object required for the `iSend` function call.
+
+Here's an overview of the arguments:
+
+| Argument     | Example Value | Description                                |
+| ------------ | ------------- | ------------------------------------------ |
+| destGasLimit | 300000        | Gas limit on destination chain             |
+| destGasPrice | 100000000000  | Gas price on destination chain             |
+| ackGasLimit  | 300000        | Gas limit on source chain for ack          |
+| ackGasPrice  | 100000000000  | Gas price on source chain for ack          |
+| relayerFees  | 10000000000   | Relayer fees on Router chain               |
+| ackType      | 3             | Acknowledge type                           |
+| isReadCall   | false         | If the call is read-only                   |
+| asmAddress   | "0x"          | Address for the additional security module |
+
+Alternatively, you can use `ethers.js` to encode the metadata:
+```js
+const metadata = ethers.utils.solidityPack(
+    ['uint64', 'uint64', 'uint64', 'uint64', 'uint128', 'uint8', 'bool', 'string'],
+    [destGasLimit, destGasPrice, ackGasLimit, ackGasPrice, relayerFees, ackType, isReadCall, asmAddress]
+);
+```
+
+For more information about encoding and the request metadata, see the Router
+[metadata documentation].
+
+[metadata documentation]: https://docs.routerprotocol.com/develop/message-transfer-via-crosstalk/evm-guides/iDapp-functions/iSend#5-requestmetadata
+
+## IDapp
+
+```solidity
+import "@routerprotocol/evm-gateway-contracts/contracts/IDapp.sol";
+```
+
+The IDapp interface consists of two main functions:
+
+1. `iReceive`: The entry point for the cross-chain message on the destination
+   chain
+2. `iAck`: The entry point on the source chain to receive the acknowledgment
+
+### iReceive()
+
+```solidity
+function iReceive(
+    string memory requestSender,
+    bytes memory packet,
+    string memory srcChainId
+  ) external returns (bytes memory)
+```
+
+`iReceive` is called by the Gateway on the destination chain.
+
+For more information about `iReceive`, see the Router [iReceive documentation].
+
+[iReceive documentation]: https://docs.routerprotocol.com/develop/message-transfer-via-crosstalk/evm-guides/iDapp-functions/iReceive
+
+### iAck()
+
+```solidity
+function iAck(
+    uint256 requestIdentifier,
+    bool execFlag,
+    bytes memory execData
+  ) external
+```
+
+`iAck` is called by the Gateway on the source chain.
+
+For more information about `iAck`, see the Router [iAck documentation].
+
+[iAck documentation]: https://docs.routerprotocol.com/develop/message-transfer-via-crosstalk/evm-guides/iDapp-functions/iAck