diff --git a/docs/dapp/diagrams/opl-contract-flow.mmd b/docs/dapp/diagrams/opl-contract-flow.mmd
index 9b40c259e1..aa394bea2a 100644
--- a/docs/dapp/diagrams/opl-contract-flow.mmd
+++ b/docs/dapp/diagrams/opl-contract-flow.mmd
@@ -1,5 +1,10 @@
sequenceDiagram
- User ->> Home Contract: Transaction
- Home Contract -->> SGN: SGN Watches Events
+ participant User
+ participant Home as Home Contract (Host)
+ participant SGN
+ participant Executor
+ participant Sapphire as Sapphire Contract (Enclave)
+ User ->> Home: Transaction
+ Home -->> SGN: SGN Watches Events
SGN -->> Executor: Waits for SGN Approval
- Executor ->> Sapphire Contract: Submit Proof Tx
+ Executor ->> Sapphire: Submit Proof Tx
diff --git a/docs/dapp/diagrams/opl-contract-flow.mmd.svg b/docs/dapp/diagrams/opl-contract-flow.mmd.svg
index 81940a489e..8f0461a148 100644
--- a/docs/dapp/diagrams/opl-contract-flow.mmd.svg
+++ b/docs/dapp/diagrams/opl-contract-flow.mmd.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/docs/dapp/opl/README.md b/docs/dapp/opl/README.md
deleted file mode 100644
index 7901fe16bc..0000000000
--- a/docs/dapp/opl/README.md
+++ /dev/null
@@ -1,162 +0,0 @@
-# Oasis Privacy Layer
-
-The Oasis Privacy Layer (OPL) is an EVM-compatible privacy solution that
-empowers developers to add new functionality to smart contracts on the most
-popular EVM networks like Ethereum, BNB Chain, and Polygon with encrypted
-transactions and confidential state.
-
-By using [a Solidity library][sapphire-contracts]
-that integrates [Sapphire] into your existing and future Web3 applications,
-developers on any supported network can seamlessly add confidential state and
-selective disclosures to their dApps when using contract a deployed on Sapphire
-without leaving their existing networks.
-
-For more information about OPL and to catch the latest news, please visit the
-[official OPL page].
-
-
-
-The user submits a transaction on the Home network to a contract which uses
-`postMessage` to notify the SGN that it should approve the cross-chain message.
-The Executor waits, when the SGN approves the message the Executor submits a
-transaction to the target contract on Sapphire.
-
-
-
-The Home Contract pays the SGN to watch and approve the message, but the
-Executor needs to be run by somebody willing to pay for the gas to submit
-transactions to the destination chain.
-
-[sapphire-contracts]: https://www.npmjs.com/package/@oasisprotocol/sapphire-contracts
-[Sapphire]: https://oasisprotocol.org/sapphire
-[official OPL page]: https://oasisprotocol.org/opl
-
-## Quickstart
-
-A pair of contracts are linked bidirectionally 1-1 to each other across chains,
-with one end on Sapphire and the other on a supported EVM-compatible chain (the
-Home Network). They can post and receive messages to & from each other using the
-message-passing bridge, but must register endpoints to define which messages
-they handle from each other.
-
-Start by adding the [`@oasisprotocol/sapphire-contracts`] NPM package to your
-Hardhat project so you can import `OPL.sol`:
-
-```shell npm2yarn
-npm install @oasisprotocol/sapphire-contracts
-```
-
-[`@oasisprotocol/sapphire-contracts`]: http://npmjs.com/package/@oasisprotocol/sapphire-contracts
-
-Then define the two contracts, starting with a contract on Sapphire which runs
-inside the confidential enclave and can be called via the `secretExample`
-handler. Use the constructor to provide the Sapphire contract with the location
-(address and chain) of the contract on the Home network:
-
-```solidity
-import {Enclave, Result, autoswitch} from "@oasisprotocol/sapphire-contracts/contracts/OPL.sol";
-
-contract SapphireContract is Enclave {
- constructor(address otherEnd, string chain) Enclave(otherEnd, autoswitch(chain)) {
- registerEndpoint("secretExample", on_example);
- }
- function on_example(bytes calldata _args) internal returns (Result) {
- (uint256 a, bool b) = abi.decode(args, (uint256, bool));
- // TODO: do confidential things here
- return Result.Success;
- }
-}
-```
-
-Then on the other chain, define your contract which can be called via
-`triggerExample` to send a message to the contract on Sapphire using the
-`postMessage` interface.
-
-```solidity
-import {Host, Result} from "@oasisprotocol/sapphire-contracts/contracts/OPL.sol";
-
-contract HomeContract is Host {
- constructor(address otherEnd) Host(otherEnd) {
- }
- function triggerExample (uint256 a, bool b) external payable {
- postMessage("secretExample", abi.encode(a, b));
- }
-}
-```
-
-After a few minutes the bridge will detect and then the executor will invoke the
-`SapphireContract.on_example` method.
-
-## Monitoring
-
-The Celer IM Scan API can be used to retrieve status and message details by
-providing the globally unique transaction ID from the chain which originated the
-message.
-
- https://api.celerscan.com/scan/searchByTxHash?tx=0x...
-
-For details of the response format, see the [Query IM Tx Status] page of the
-Celer Inter-Chain Message (IM) documentation. Using this API lets you to check
-if messages have been delivered.
-
-[Query IM Tx Status]: https://im-docs.celer.network/developer/development-guide/query-im-tx-status
-
-## Mainnet Deployment
-
-It is necessary to run a [Message Executor] which monitors the Celer *State
-Guardian Network* (SGN) for cross-chain messages and then submits the proof
-on-chain to deliver them to the target contract.
-
-If you are participating in a Hackathon or Grant, [please fill out the relay
-request form](https://form.typeform.com/to/RsiUR9Xz) to be allowed to use the
-shared Message Executor.
-
-[Message Executor]: https://im-docs.celer.network/developer/development-guide/message-executor
-
-## Supported Networks
-
-### Mainnets
-
-| Name | Int ID | Hex ID | autoswitch name |
-| ---- | ------ | ------ | --------------- |
-| Ape | 16350 | 0x3fde | ape |
-| Arbitrum Nova | 42170 | 0xa4ba | arbitrum-nova |
-| Arbitrum One | 42161 | a4b1 | arbitrum-one |
-| Astar | 592 | 0x250 | astar |
-| Aurora | 1313161554 | 0x4e454152 | aurora |
-| Avalanche | 43114 | 0xa86a | avalanche |
-| Binance Smart Chain | 56 | 0x38 | bsc |
-| Ethereum | 1 | 0x1 | ethereum |
-| Fantom | 250 | 0xfa | fantom |
-| Filecoin | 314 | 0x13a | filecoin |
-| Milkomeda C1 | 2001 | 0x7d1 | milkomeda |
-| Moonriver | 1285 | 0x505 | moonriver |
-| Polygon | 137 | 0x89 | polygon |
-| Sapphire | 23294 | 0x5afe | sapphire |
-| Syscoin | 57 | 0x39 | syscoin |
-| Polygon zkEVM | 1101 | 0x44d | polygon-zkevm |
-| Optimism | 10 | 0xa | optimism |
-| zkSync Era | 324 | 0x144 | zksync-era |
-
-### Testnets
-
-| Name | Int ID | Hex ID | autoswitch name |
-| ---- | ------ | ------ | --------------- |
-| Arbitrum Testnet | 421611 | 0x66eeb | arbitrum-testnet |
-| Avalanche C-Chain Fuji Testnet | 43113 | 0xa869 | avalanche-fuji |
-| BSC Testnet | 97 | 0x61 | bsc-testnet |
-| ConsenSys zkEVM Testnet | 59140 | 0xe704 | zkevm-testnet |
-| Dexalot Testnet | 432201 | 0x69849 | dexalot-testnet |
-| Fantom Testnet | 4002 | 0xfa2 | fantom-testnet |
-| Filecoin Hyperspace Testnet | 3141 | 0xc45 | filecoin-testnet |
-| FNCY Testnet | 923018 | 0xe158a | fncy-testnet |
-| Godwoken Testnet | 71401 | 0x116e9 | godwoken-testnet |
-| Goerli Testnet | 5 | 0x5 | goerli |
-| Polygon Mumbai Testnet | 80001 | 0x13881 | polygon-mumbai |
-| Polygon zkEVM Testnet | 1442 | 0x5a2 | zkevm-testnet |
-| Sapphire Testnet | 23295 | 0x5aff | sapphire-testnet |
-| Scroll Alpha Testnet | 534353 | 0x82751 | scroll-testnet |
-| Shibuya Testnet | 81 | 0x51 | shibuya-testnet |
-
-In the following sections we will look at a concrete example on how to build a
-confidential, cross-chain DAO-voting dApp from scratch using the Oasis Privacy Layer!
diff --git a/docs/dapp/opl/README.mdx b/docs/dapp/opl/README.mdx
new file mode 100644
index 0000000000..d3b5c74a6d
--- /dev/null
+++ b/docs/dapp/opl/README.mdx
@@ -0,0 +1,55 @@
+---
+description: Integrating privacy into dApps on other blockchains
+---
+
+import DocCard from '@theme/DocCard';
+import DocCardList from '@theme/DocCardList';
+import {findSidebarItem} from '@site/src/sidebarUtils';
+
+# Oasis Privacy Layer (OPL)
+
+The Oasis Privacy Layer (OPL) is a powerful solution that enables developers
+to integrate privacy features into their decentralized applications (dApps)
+across multiple EVM-compatible networks.
+
+- **Privacy-First**: OPL leverages the [Sapphire]'s privacy features to ensure
+that data remains confidential and transactions are encrypted end-to-end.
+- **Cross-Chain Compatibility**: OPL is compatible with multiple blockchains
+through message bridging protocols, making it easy to integrate privacy
+regardless of the chain your dApp is built on.
+
+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
+
+## How OPL Works
+
+The OPL is made possible through message bridges, which enable secure
+communication between OPL-enabled contracts on Sapphire and smart contracts on
+other chains. This allows dApps to access privacy-preserving capabilities while
+keeping their main logic on their primary chain.
+
+
+
+### Message Bridges
+
+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.
+
+
+
+## Examples
+
+
diff --git a/docs/dapp/opl/celer/README.md b/docs/dapp/opl/celer/README.md
new file mode 100644
index 0000000000..bb2bf0e419
--- /dev/null
+++ b/docs/dapp/opl/celer/README.md
@@ -0,0 +1,89 @@
+---
+description: A message bridge by Celer
+---
+
+# Celer Inter-Chain Messaging (IM)
+
+
+## Monitoring
+
+The Celer IM Scan API can be used to retrieve status and message details by
+providing the globally unique transaction ID from the chain which originated the
+message.
+
+ https://api.celerscan.com/scan/searchByTxHash?tx=0x...
+
+For details of the response format, see the [Query IM Tx Status] page of the
+Celer-IM documentation. Using this API lets you to check if messages have been
+delivered.
+
+[Query IM Tx Status]: https://im-docs.celer.network/developer/development-guide/query-im-tx-status
+
+## Executor
+
+The Executor is an essential part of the Celer IM framework. The Executor monitors the Celer *State Guardian Network*(SGN) for messages ready to be submitted (with enough validator signatures) and submits the message execution transactions to the MessageBus contract.
+
+It is necessary to run a [Message Executor] which monitors the Celer SGN for cross-chain messages and then submits the proof on-chain to deliver them to the target contract.
+
+To set up an executor, you can either follow this [documentation] to set up your own, or fill out this [form][celer-form] for Celer to set up a hosted executor service for you.
+
+If you are participating in a Hackathon or Grant, [please fill out the relay
+request form](https://form.typeform.com/to/RsiUR9Xz) to be allowed to use the
+shared Message Executor.
+
+In most cases, we recommend dApp developers use the shared executor services provided by the Celer Network team so that you do not need to worry about the executor server configuration and operation.
+
+[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
+
+## Supported Networks
+
+### Mainnets
+
+| Name | Int ID | Hex ID | autoswitch name |
+| ---- | ------ | ------ | --------------- |
+| Ape | 16350 | 0x3fde | ape |
+| Arbitrum Nova | 42170 | 0xa4ba | arbitrum-nova |
+| Arbitrum One | 42161 | a4b1 | arbitrum-one |
+| Astar | 592 | 0x250 | astar |
+| Aurora | 1313161554 | 0x4e454152 | aurora |
+| Avalanche | 43114 | 0xa86a | avalanche |
+| Binance Smart Chain | 56 | 0x38 | bsc |
+| Ethereum | 1 | 0x1 | ethereum |
+| Fantom | 250 | 0xfa | fantom |
+| Filecoin | 314 | 0x13a | filecoin |
+| Milkomeda C1 | 2001 | 0x7d1 | milkomeda |
+| Moonriver | 1285 | 0x505 | moonriver |
+| Polygon | 137 | 0x89 | polygon |
+| Sapphire | 23294 | 0x5afe | sapphire |
+| Syscoin | 57 | 0x39 | syscoin |
+| Polygon zkEVM | 1101 | 0x44d | polygon-zkevm |
+| Optimism | 10 | 0xa | optimism |
+| zkSync Era | 324 | 0x144 | zksync-era |
+
+### Testnets
+
+| Name | Int ID | Hex ID | autoswitch name |
+| ---- | ------ | ------ | --------------- |
+| Arbitrum Testnet | 421611 | 0x66eeb | arbitrum-testnet |
+| Avalanche C-Chain Fuji Testnet | 43113 | 0xa869 | avalanche-fuji |
+| BSC Testnet | 97 | 0x61 | bsc-testnet |
+| ConsenSys zkEVM Testnet | 59140 | 0xe704 | zkevm-testnet |
+| Dexalot Testnet | 432201 | 0x69849 | dexalot-testnet |
+| Fantom Testnet | 4002 | 0xfa2 | fantom-testnet |
+| Filecoin Hyperspace Testnet | 3141 | 0xc45 | filecoin-testnet |
+| FNCY Testnet | 923018 | 0xe158a | fncy-testnet |
+| Godwoken Testnet | 71401 | 0x116e9 | godwoken-testnet |
+| Goerli Testnet | 5 | 0x5 | goerli |
+| Polygon Mumbai Testnet | 80001 | 0x13881 | polygon-mumbai |
+| Polygon zkEVM Testnet | 1442 | 0x5a2 | zkevm-testnet |
+| Sapphire Testnet | 23295 | 0x5aff | sapphire-testnet |
+| Scroll Alpha Testnet | 534353 | 0x82751 | scroll-testnet |
+| Shibuya Testnet | 81 | 0x51 | shibuya-testnet |
+
+In the following sections we will look at a concrete example on how to build a
+confidential, cross-chain DAO-voting dApp from scratch using the Oasis Privacy Layer!
+
+
+
diff --git a/docs/dapp/opl/opl-sdk/README.md b/docs/dapp/opl/opl-sdk/README.md
new file mode 100644
index 0000000000..73f2e70fa2
--- /dev/null
+++ b/docs/dapp/opl/opl-sdk/README.md
@@ -0,0 +1,110 @@
+---
+description: OPL sdk
+---
+
+# OPL SDK
+
+
+The OPL SDK is available in our [Solidity library][sapphire-contracts].
+The SDK wraps the Celer Inter-Chain Message (IM) and makes it easy and straight
+forward to integrate [Sapphire] and its privacy features into your existing or
+future Web3 applications.
+
+[sapphire-contracts]: https://www.npmjs.com/package/@oasisprotocol/sapphire-contracts
+[Sapphire]: https://oasisprotocol.org/sapphire
+
+## Overview
+
+
+
+1. The **user** submits a transaction on the Home network to a contract which uses
+ `postMessage` to emit an event about a the cross-chain message.
+2. The **Celer *State Guardian Network* (SGN)** monitors for transactions which
+ trigger a cross-chain message event and create attestation.
+3. The **Executor** waits, when the SGN approves the message the Executor submits a
+ transaction to the target contract on Sapphire.
+
+## Fees
+
+The Home Contract pays the SGN to watch and approve the message, but the
+Executor needs to be run by somebody willing to pay for the gas to submit
+transactions to the destination chain.
+
+More details to the Celer Executor you can find [here][celer-executor].
+
+
+## Quickstart
+
+A pair of contracts are linked bidirectionally 1-1 to each other across chains,
+with one end on Sapphire and the other on a supported EVM-compatible chain (the
+Home Network). They can post and receive messages to & from each other using the
+message-passing bridge, but must register endpoints to define which messages
+they handle from each other.
+
+### Setup
+
+Start by adding the [`@oasisprotocol/sapphire-contracts`] NPM package to your
+Hardhat project so you can import `OPL.sol`:
+
+```shell npm2yarn
+npm install @oasisprotocol/sapphire-contracts
+```
+
+[`@oasisprotocol/sapphire-contracts`]: http://npmjs.com/package/@oasisprotocol/sapphire-contracts
+
+Now define the two contracts:
+
+- A contract on **Sapphire** which runs inside the confidential `enclave`
+- A contract on the **home chain** as a `host` which triggers the example
+
+### Sapphire Contract
+
+On Sapphire use the constructor to provide the Sapphire contract with the
+location (address and chain) of the contract on the Home chain and register an
+endpoint called `secretExample`.
+
+```solidity
+import {Enclave, Result, autoswitch} from "@oasisprotocol/sapphire-contracts/contracts/OPL.sol";
+
+contract SapphireContract is Enclave {
+ constructor(address otherEnd, string chain) Enclave(otherEnd, autoswitch(chain)) {
+ registerEndpoint("secretExample", on_example);
+ }
+ function on_example(bytes calldata _args) internal returns (Result) {
+ (uint256 a, bool b) = abi.decode(args, (uint256, bool));
+ // TODO: do confidential things here
+ return Result.Success;
+ }
+}
+```
+
+### Host Contract
+
+On the other chain, define your contract which can be called via
+`triggerExample` to send a message to the contract on Sapphire using the
+`postMessage` interface.
+
+```solidity
+import {Host, Result} from "@oasisprotocol/sapphire-contracts/contracts/OPL.sol";
+
+contract HomeContract is Host {
+ constructor(address otherEnd) Host(otherEnd) {
+ }
+ function triggerExample (uint256 a, bool b) external payable {
+ postMessage("secretExample", abi.encode(a, b));
+ }
+}
+```
+
+After a few minutes the bridge will detect and then the executor will invoke the
+`SapphireContract.on_example` method.
+
+:::info
+
+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.
+
+:::
+
+[celer-executor]: ../celer/README.md#executor
\ No newline at end of file
diff --git a/docs/dapp/opl/secret-ballot-example/README.md b/docs/dapp/opl/secret-ballot-example/README.md
index 92726cb797..41ece083a4 100644
--- a/docs/dapp/opl/secret-ballot-example/README.md
+++ b/docs/dapp/opl/secret-ballot-example/README.md
@@ -4,6 +4,10 @@ description: How to build your first dApp on OPL
# Secret Ballot Example
+This example is an extensive tutorial on how to use [OPL] for confidential voting.
+
+[OPL]: ../opl-sdk/README.md
+
## Overview
On-chain voting is the basis for any decentralized autonomous organization
diff --git a/sidebarDapp.ts b/sidebarDapp.ts
index 7f8b137e19..c172f00e58 100644
--- a/sidebarDapp.ts
+++ b/sidebarDapp.ts
@@ -47,30 +47,50 @@ export const sidebarDapp: SidebarsConfig = {
items: [
{
type: 'category',
- label: 'Router Protocol',
+ label: 'OPL SDK',
link: {
type: 'doc',
- id: 'dapp/opl/router-protocol/README',
+ id: 'dapp/opl/opl-sdk/README',
+ },
+ items: [
+ {
+ type: 'category',
+ label: 'Secret Ballot Example',
+ link: {
+ type: 'doc',
+ id: 'dapp/opl/secret-ballot-example/README',
+ },
+ items: [
+ 'dapp/opl/secret-ballot-example/setup',
+ 'dapp/opl/secret-ballot-example/host',
+ 'dapp/opl/secret-ballot-example/enclave',
+ 'dapp/opl/secret-ballot-example/build',
+ 'dapp/opl/secret-ballot-example/frontend',
+ ],
+ }
+ ],
+ },
+ {
+ type: 'category',
+ label: 'Celer Inter-Chain Messaging',
+ link: {
+ type: 'doc',
+ id: 'dapp/opl/celer/README',
},
items: [
- 'dapp/opl/router-protocol/pingpong-example',
- 'dapp/opl/router-protocol/interface',
- 'dapp/opl/router-protocol/approve',
],
},
{
type: 'category',
- label: 'Secret Ballot Example',
+ label: 'Router Protocol',
link: {
type: 'doc',
- id: 'dapp/opl/secret-ballot-example/README',
+ id: 'dapp/opl/router-protocol/README',
},
items: [
- 'dapp/opl/secret-ballot-example/setup',
- 'dapp/opl/secret-ballot-example/host',
- 'dapp/opl/secret-ballot-example/enclave',
- 'dapp/opl/secret-ballot-example/build',
- 'dapp/opl/secret-ballot-example/frontend',
+ 'dapp/opl/router-protocol/pingpong-example',
+ 'dapp/opl/router-protocol/interface',
+ 'dapp/opl/router-protocol/approve',
],
},
],