Skip to content

Commit

Permalink
docs: add ping example for OPL
Browse files Browse the repository at this point in the history
  • Loading branch information
@rube-de
rube-de committed Oct 24, 2024
1 parent 0318a17 commit 0297be8
Show file tree
Hide file tree
Showing 7 changed files with 143 additions and 96 deletions.
38 changes: 25 additions & 13 deletions docs/dapp/opl/README.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ For more information about OPL and to catch the latest news, please visit the
[official OPL page].

[official OPL page]: https://oasisprotocol.org/opl
[Sapphire]: https://oasisprotocol.org/sapphire
[Sapphire]: ../sapphire/README.mdx

## How OPL Works

Expand All @@ -36,29 +36,41 @@ keeping their main logic on their primary chain.
:::info

For how to use use signed messages with the GSN to trigger a cross-chain
messages, please visit our [Gasless Transactions chatper].
messages, please visit our [Gasless Transactions chapter].

:::

[Gasless Transactions chatper]: ../sapphire/gasless.md
[Gasless Transactions chapter]: ../sapphire/gasless.md

### Message Bridges
## Message Bridges

You can integrate message bridges into your dApps using one of these three methods:
You can integrate message bridges into your dApps using one of these three
methods:

- **OPL-SDK**: A wrapper provided by the Oasis Protocol that simplifies the integration of message bridging with Oasis’s privacy features.
- **Celer Inter-Chain Messaging (IM)**: A generalized message bridging solution by Celer, which lets you build more complex solutions.
- **Router Protocol CrossTalk**: An extensible cross-chain framework that enables seamless state transitions across multiple chains.
- **[OPL SDK]**: A wrapper provided by the Oasis Protocol that simplifies the
integration of message bridging with Oasis’s privacy features.
- **[Celer Inter-Chain Messaging (IM)][celer]**: A generalized message bridging solution
by Celer, which lets you build more complex solutions.
- **[Router Protocol CrossTalk][router]**: An extensible cross-chain framework that
enables seamless state transitions across multiple chains.

<DocCardList items={[
findSidebarItem('/dapp/opl/opl-sdk/'),
findSidebarItem('/dapp/opl/celer/'),
findSidebarItem('/dapp/opl/router-protocol/')
]} />
### Comparison

| Protocol | Validator Network | Relayer | Fees |
| --------------- | ----------------- | ------ | ------ |
| **[OPL SDK]** | SGN (Celer) | Executor (self-hosted or hosted service by Celer) | SGN Fee: Paid via `msg.value` <br/> Executor Fee: Charged externally (Free on testnet) |
| **[Celer IM][celer]** | SGN (Celer) | Executor (self-hosted or hosted service by Celer) | SGN Fee: Paid via `msg.value` <br/> Executor Fee: Charged externally (Free on testnet) |
| **[Router Protocol][router]** | Orchestrators (Router Chain) | Relayer (run by 3rd party) | Paid by the approved feepayer on the Routerchain |

## Examples

<DocCardList items={[
findSidebarItem('/dapp/opl/secret-ballot-example/'),
findSidebarItem('/dapp/opl/opl-sdk/ping-example'),
findSidebarItem('/dapp/opl/celer/ping-example'),
findSidebarItem('/dapp/opl/router-protocol/pingpong-example'),
]} />

[OPL SDK]: ./opl-sdk/README.md
[celer]: ./celer/README.md
[router]: ./router-protocol/README.md
11 changes: 10 additions & 1 deletion docs/dapp/opl/celer/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,8 @@ It performs two main functions:

- Monitors the Celer State Guardian Network (SGN) for messages ready to be
submitted (with sufficient validator signatures).
- Submits message execution transactions to the MessageBus contract.
- Submits message execution transactions to the MessageBus contract on the
destination chain.

It is necessary a [Message Executor] runs for you dapp. To set up an executor,
you have two options
Expand All @@ -70,6 +71,14 @@ In most cases, Celer advises dApp developers to use the shared executor
services provided by the Celer Network team to avoid server configuration and
operation concerns.

:::info

Oasis is running an executor for the Sapphire Testnet, which is okay to rely on
for a test, for a faster execution it's recommended to run your own or use the
hosted service.

:::

[Message Executor]: https://im-docs.celer.network/developer/development-guide/message-executor
[documentation]: https://im-docs.celer.network/developer/development-guide/message-executor/integration-guide
[celer-form]:https://form.typeform.com/to/RsiUR9Xz
Expand Down
36 changes: 16 additions & 20 deletions docs/dapp/opl/celer/ping-example.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,10 @@ If you're new to Remix, follow our basic guide for using Remix
## Overview Ping

In this example, you'll deploy the same contract on two different chains.
You'll then send a `ping` from chain A to chain B, facilitated by Celer-IM.
The contract on chain B will receive the `ping` and emits an event with the
message which was received.
You'll then send a `ping` from *BSC Testnet* to *Saphhire Testnet*, facilitated
by Celer-IM.
The contract on *Sapphire Testnet* will receive the `ping` and emits an event
with the message which was received.

## Contract Setup

Expand Down Expand Up @@ -115,12 +116,12 @@ message which was received.

## Compiling the Contract

For compatibility with Sapphire, compile the contract using Solidity version
**`0.8.24`** or older.
For compatibility with Sapphire, compile the contract using compiler version
**`0.8.24`** and evm version **`paris`** (under advanced configuration).

:::info

You can also use Celer's framework contracts and interfaces by importing them
You can also use Celer's framework contracts and interfaces by importing them

```solidity
import "sgn-v2-contracts/contracts/message/framework/MessageBusAddress.sol";
Expand All @@ -132,12 +133,12 @@ but this will limit you to use only Solidity version **`0.8.9`**.

:::

### Deploying the Contract
## Deploying the Contract

Deploy the Ping contract on two different chains: `BSC Testnet` and
`Sapphire Testnet`.

#### Deploying on BSC Testnet
### Deploying on BSC Testnet

1. Obtain BNB test token for `BSC Testnet` from the [BNB faucet] or their
discord.
Expand All @@ -150,7 +151,7 @@ Deploy the Ping contract on two different chains: `BSC Testnet` and

[BNB faucet]: https://www.bnbchain.org/en/testnet-faucet

#### Deploying on Sapphire Testnet
### Deploying on Sapphire Testnet

1. Obtain TEST tokens for `Sapphire Testnet` from the [Oasis faucet].
2. In Metamask, switch to the `Sapphire Testnet` network and select
Expand All @@ -176,27 +177,22 @@ You'll need the following three parameters:
`0x48656c6c6f2066726f6d20425343000000000000000000000000000000000000`.

Additionally you'll have to pay a fee which you send as value. For sending the
ping 0.001 tBNB will be enough.
ping 0.001 tBNB (1000000 gwei) will be enough.

:::info

For the `Sapphire Testnet` an executor is running to relay the messages every
few mintues. If you deploy on mainnet please refer to the [Executor chapter]
on how to run an executor.
few mintues. If you deploy on mainnet please refer to the [Executor chapter].
:::

[Executor chapter]: ./README.md#executor

:::info

//TODO: add statement about encrypting the message for real use cases

:::

## Checking execution

To see if you successfully send a ping message cross-chain you can watch for
new transactions at the [MessageBus address] from Celer or your deployed
contract Sapphire Testnet
contract Sapphire Testnet.

[MessageBus address]: https://explorer.oasis.io/testnet/sapphire/address/0x9Bb46D5100d2Db4608112026951c9C965b233f4D

[MessageBus address]: https://explorer.oasis.io/testnet/sapphire/address/0x9Bb46D5100d2Db4608112026951c9C965b233f4D
[Remix]: https://remix.ethereum.org/
2 changes: 1 addition & 1 deletion docs/dapp/opl/opl-sdk/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ After a few minutes the bridge will detect and then the executor will invoke the

As noted in the [fees](#fees) section, an exectuor needs to relay your messages.
Please refer to the Celer [Executor][celer-executor] section on how to get on
the shared Message Executor on Testnet or how to set up your own executor.
the shared Message Executor or how to set up your own executor.

:::

Expand Down
135 changes: 82 additions & 53 deletions docs/dapp/opl/opl-sdk/ping-example.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ message which was received.
(bytes memory message) = abi.decode((_args), (bytes));
emit MessageReceived(message);
return Result.Success;
}
}
}
```
</details>
Expand All @@ -85,7 +85,7 @@ message which was received.
contract Pong is Enclave {
event MessageReceived(bytes message);

constructor(address ping, bytes32 chain) Enclave(ping, autoswitch(chain)) {
constructor(uint nonce, bytes32 chain) Enclave(computeAddress(msg.sender, nonce), autoswitch(chain)) {
registerEndpoint("ping", _pingMessage);
}

Expand All @@ -94,101 +94,130 @@ message which was received.
emit MessageReceived(message);
return Result.Success;
}

function computeAddress(address _origin, uint _nonce) public pure returns (address) {
if (_nonce == 0x00) {
return address(uint160(uint256(keccak256(abi.encodePacked(
bytes1(0xd6), bytes1(0x94), _origin, bytes1(0x80)
)))));
}
if (_nonce <= 0x7f) {
return address(uint160(uint256(keccak256(abi.encodePacked(
bytes1(0xd6), bytes1(0x94), _origin, bytes1(uint8(_nonce))
)))));
}
if (_nonce <= 0xff) {
return address(uint160(uint256(keccak256(abi.encodePacked(
bytes1(0xd7), bytes1(0x94), _origin, bytes1(0x81), uint8(_nonce)
)))));
}
if (_nonce <= 0xffff) {
return address(uint160(uint256(keccak256(abi.encodePacked(
bytes1(0xd8), bytes1(0x94), _origin, bytes1(0x82), uint16(_nonce)
)))));
}
if (_nonce <= 0xffffff) {
return address(uint160(uint256(keccak256(abi.encodePacked(
bytes1(0xd9), bytes1(0x94), _origin, bytes1(0x83), uint24(_nonce)
)))));
}
return address(uint160(uint256(keccak256(abi.encodePacked(
bytes1(0xda), bytes1(0x94), _origin, bytes1(0x84), uint32(_nonce)
)))));
}
}
```
</details>

### Key points

- `Host`: Celer's MessageBus contract on the respective chain.
- `sendPing`: Initiates the cross-chain my calling Celers MessageBus.
- `executeMessage`: Called by Celer's MessageBus on the destination chian.
- `Host`: OPL wrapper for outside contract.
- `Enclave`: OPL wrapper for the contract on Sapphire side.
- `registerEndpoint`: Registers endpoints in an OPL managed map.
- `postMessage`: Call registered endpoints.
- `autoswitch`: Finds correct MessageBus address via chain name.

## Compiling the Contract

For compatibility with Sapphire, compile the contract using Solidity version
**`0.8.24`** or older.
For compatibility with Sapphire, compile the contract using compiler version
**`0.8.24`** and evm version **`paris`** (under advanced configuration).

:::info
## Deploying the Contract

You can also use Celer's framework contracts and interfaces by importing them
Deploy the Ping contract on `BSC Testnet` and the Pong.sol contract on
`Sapphire Testnet`.

```solidity
import "sgn-v2-contracts/contracts/message/framework/MessageBusAddress.sol";
import "sgn-v2-contracts/contracts/message/framework/MessageReceiverApp.sol";
import "sgn-v2-contracts/contracts/message/interfaces/IMessageBus.sol";
```
### Deploying Pong.sol on Sapphire Testnet

but this will limit you to use only Solidity version **`0.8.9`**.
You'll deploy the contract on `Sapphire Testnet` first to avoid switching chains
back and forth.

:::
1. Obtain TEST tokens for `Sapphire Testnet` from the [Oasis faucet].
2. Get next nonce of your account from `BSC Testnet`
1. If you didn't do anything on *BSC Testnet* yet this will `0`.
2. Else you need to get your last nonce, e.g. by checking your account
address on [bscscan](https://testnet.bscscan.com/) and and inspect the details
of your latest transaction, and then add 1.
3. In Metamask, switch to the `Sapphire Testnet` network and select
`Injected Provider - MetaMask` as the environment in Remix.
4. Select the `Pong.sol` contract.
5. Fill in the deployment parameters:

### Deploying the Contract
- **`nonce`**: `0` (or next nonce as written above)
- **`chain`**: `0x6273630000000000000000000000000000000000000000000000000000000000`
(bytes encoded `"bsc"`)

Deploy the Ping contract on two different chains: `BSC Testnet` and
`Sapphire Testnet`.
6. Deploy the contract on `Sapphire Testnet`

:::info

Copy the address of the deployed contract, you'll need it for the next step as
Remix will remove the contract from the UI if you change the chain.

:::

#### Deploying on BSC Testnet
[Oasis Faucet]: https://faucet.testnet.oasis.io/

### Deploying Ping.sol on BSC Testnet

1. Obtain BNB test token for `BSC Testnet` from the [BNB faucet] or their
discord.
2. In MetaMask, switch to the `BSC Testnet` network and select
`Injected Provider - MetaMask` as the environment in Remix.
3. Fill in the messageBus address for BSC Testnet:
`0xAd204986D6cB67A5Bc76a3CB8974823F43Cb9AAA`.
4. Deploy the contract on `BSC Testnet`.

3. Select the `Ping.sol` contract.
4. Fill in the contract addess you just have deployed on `Sapphire Testnet`.
5. Deploy the contract on `BSC Testnet`.

[BNB faucet]: https://www.bnbchain.org/en/testnet-faucet

#### Deploying on Sapphire Testnet

1. Obtain TEST tokens for `Sapphire Testnet` from the [Oasis faucet].
2. In Metamask, switch to the `Sapphire Testnet` network and select
`Injected Provider - MetaMask` as the environment in Remix
3. Fill in the messageBus address for BSC Testnet:
`0x9Bb46D5100d2Db4608112026951c9C965b233f4D`.
4. Deploy the contract on Sapphire Testnet

[Oasis Faucet]: https://faucet.testnet.oasis.io/

## Executing Ping

Now that you've deployed the contacts, you can send the ping message
cross-chain.

You'll need the following three parameters:
You'll need the following parameter for `startPing`:

- `_dstContract`: The contract address of the reveiving contract on the
destination chain which you just deployed.
- `_dstChainId`: The chain id of the the destination chain. Which is in our
example `Sapphire Testnet` - `23295`.
- `message`: The encoded message. e.g. "Hello from BSC" -
- `_message`: The encoded message. e.g. "Hello from BSC" -
`0x48656c6c6f2066726f6d20425343000000000000000000000000000000000000`.

Additionally you'll have to pay a fee which you send as value. For sending the
ping 0.001 tBNB will be enough.
Additionally you'll have to pay a fee which you send as `value`. For sending the
ping 0.001 tBNB (1000000 gwei) will be enough.

Finally execute the function `startPing`.

:::info

For the `Sapphire Testnet` an executor is running to relay the messages every
few mintues. If you deploy on mainnet please refer to the [Executor chapter]
on how to run an executor.
few mintues. If you deploy on mainnet please refer to the [Executor chapter].
:::

[Executor chapter]: ./README.md#executor

:::info

//TODO: add statement about encrypting the message for real use cases

:::
[Executor chapter]: ../celer/README.md#executor

## Checking execution

To see if you successfully send a ping message cross-chain you can watch for
new transactions at the [MessageBus address] from Celer or your deployed
contract Sapphire Testnet
contract on `Sapphire Testnet`.

[MessageBus address]: https://explorer.oasis.io/testnet/sapphire/address/0x9Bb46D5100d2Db4608112026951c9C965b233f4D

Expand Down
Loading

0 comments on commit 0297be8

Please sign in to comment.