Merge branch 'main' into CedarMist/celer-im-status-api

oasisprotocol · Jul 25, 2023 · 927dda3 · 927dda3
2 parents d3d1851 + 0b4dbd4
commit 927dda3
Show file tree

Hide file tree

Showing 32 changed files with 1,793 additions and 389 deletions.
diff --git a/docs/README.mdx b/docs/README.mdx
@@ -1,18 +1,45 @@
+import DocCard from '@theme/DocCard';
 import DocCardList from '@theme/DocCardList';
 import {findSidebarItem} from '@site/src/sidebarUtils';
 
 # Getting Started
 
 ## Use Oasis
 
-These guides provide general overview of the Oasis Network and introduce basic
-tools for you to get started.
+The introductory section contains general overview of the Oasis Network such as
+the distinction between the consensus layer and different ParaTimes. It
+also covers wallets and other tools for managing your assets across the Oasis
+chains and how to use unique Oasis features.
 
 <DocCardList items={[
     findSidebarItem('/general/oasis-network/'),
     findSidebarItem('/general/manage-tokens/'),
 ]} />
 
+## Create dApp
+
+Contains learning material for the smart contract developers. Since the Oasis
+platform is best known for confidentiality, the most notable ParaTime is
+[Oasis Sapphire], an **EVM-compatible** ParaTime with **built-in contract state
+encryption**. The Oasis team also prepared a set of libraries called the
+[Oasis Privacy Layer] to **bridge existing dApps running on other chains** to
+use the unique Sapphire's confidentiality.
+
+The section also covers other ParaTimes such as the non-confidential
+[Oasis Emerald] and Wasm-compatible, confidential [Oasis Cipher].
+
+<DocCardList items={[
+    findSidebarItem('/dapp/sapphire/'),
+    findSidebarItem('/dapp/opl/'),
+    findSidebarItem('/dapp/emerald/'),
+    findSidebarItem('/dapp/cipher/'),
+]} />
+
+[Oasis Sapphire]: dapp/sapphire/README.mdx
+[Oasis Privacy Layer]: dapp/opl/README.md
+[Oasis Emerald]: dapp/emerald/README.mdx
+[Oasis Cipher]: dapp/emerald/README.mdx
+
 ## Get Involved
 
 Contains information on official channels to get in touch with the Oasis Network
@@ -25,7 +52,7 @@ developers and how to contribute to the network.
     findSidebarItem('/get-involved/oasis-core'),
 ]} />
 
-## Run your own Node
+## Run Node
 
 If you want to run your own Oasis node, the following section will provide you
 with guides on the current Mainnet and Testnet network parameters and how to
@@ -40,28 +67,24 @@ queries on the network.
     findSidebarItem('/node/run-your-node'),
 ]} />
 
-## DApps and ParaTime Developers
+## Build ParaTimes
 
-These two sections are focused on developers building applications on top of
-the Oasis Network. Smart contract developers will be interested in the
-EVM-compatible Emerald and confidential Sapphire ParaTimes. For maximum
-security and confidentiality, the Oasis team designed a novel Cipher ParaTime
-executing Wasm smart contracts and which allows you to develop smart contracts
-in Rust using the Oasis Contract SDK. Finally, developers can learn how to
-build their own ParaTime running on the Oasis Network.
+Apart from Emerald, Cipher, Sapphire and the Key manager ParaTimes, developers
+can learn how to write, compile, sign and deploy their own ParaTimes on the
+Oasis Network.
 
-<DocCardList items={[
-    findSidebarItem('/dapp/emerald/'),
-    findSidebarItem('/dapp/sapphire/'),
-    findSidebarItem('/dapp/cipher/'),
-    findSidebarItem('/paratime/'),
-]} />
+<DocCard item={findSidebarItem('/paratime/')} />
 
-## Oasis Core Contributors
+## Develop Core
 
 Whether you want to contribute your code to the core components of the Oasis
 Network or just learn more about the Oasis core, this is the place for you.
 
-<DocCardList items={[
-    findSidebarItem('/core/'),
-]} />
+<DocCard item={ findSidebarItem('/core/') } />
+
+Development of interoperable Oasis network components are made by consensus.
+Similar to the Ethereum's ERC/EIP mechanism, Oasis follows Architectural
+Decision Records (ADRs) which are first proposed, voted on and can then be
+implemented, if accepted.
+
+<DocCard item={ findSidebarItem('/adrs') } />
diff --git a/docs/dapp/README.mdx b/docs/dapp/README.mdx
@@ -6,7 +6,7 @@ import DocCard from '@theme/DocCard';
 import DocCardList from '@theme/DocCardList';
 import {findSidebarItem} from '@site/src/sidebarUtils';
 
-# Overview
+# Create dApp
 
 ![Oasis architectural design including ParaTime and consensus layers](../general/images/architecture/technology_scalability.svg)
 

diff --git a/docs/dapp/emerald/writing-dapps-on-emerald.mdx b/docs/dapp/emerald/writing-dapps-on-emerald.mdx
@@ -616,7 +616,7 @@ share them with us on the [#emerald-paratime Discord channel][discord].
 
 [Remix]: https://remix.ethereum.org
 [metamask]: ../../general/manage-tokens/how-to-transfer-rose-into-paratime.mdx#verifying-rose-balance-on-paratime
-[discord]: https://discord.gg/oasisprotocol
+[discord]: https://oasis.io/discord
 
 ## Troubleshooting
 

diff --git a/docs/dapp/images/opl/confirm-new-poll.png b/docs/dapp/images/opl/confirm-new-poll.png
diff --git a/docs/dapp/images/opl/create-poll.png b/docs/dapp/images/opl/create-poll.png
diff --git a/docs/dapp/images/opl/past-dao-proposals.png b/docs/dapp/images/opl/past-dao-proposals.png
diff --git a/docs/dapp/images/opl/vote-on-ballot.png b/docs/dapp/images/opl/vote-on-ballot.png
diff --git a/docs/dapp/opl/README.md b/docs/dapp/opl/README.md
@@ -1,14 +1,15 @@
 # Oasis Privacy Layer
 
-The Oasis Privacy Layer (OPL) is an EVM-compatible privacy solution that opens
-new frontiers for confidential smart contracts in Web3 applications on the
-most popular EVM networks like Ethereum, BNB Chain, and Polygon.
+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.
 
 ## DApp Development
 
 The Oasis Privacy Layer contains a set of [smart contracts](https://github.com/oasisprotocol/sapphire-paratime/tree/main/contracts/contracts/opl)
 that integrate [Sapphire](../sapphire/README.mdx) into your existing and future
-Web3 applications and introduce confidentiality.
+Web3 applications, introducing confidentiality.
 
 Application developers on [any supported network](https://im-docs.celer.network/developer/contract-addresses-and-rpc-info) can add confidential state
 and selective disclosures to their applications through the usage of a smart

diff --git a/docs/dapp/opl/build.md b/docs/dapp/opl/build.md
@@ -15,7 +15,7 @@ npx hardhat compile
 We can make deployments easier by using [Hardhat deploy](https://github.com/wighawag/hardhat-deploy).
 
 ```sh
-npm install -D hardhat-deploy
+pnpm install -D hardhat-deploy
 ```
 
 
@@ -127,7 +127,8 @@ We will use these addresses in our frontend application.
 
 #### Testnet
 
-We can likewise deploy to OPL [Testnet](../../dapp/sapphire/guide#testnet-and-mainnet) with Sapphire.
+We can likewise deploy to [Testnet](../../dapp/sapphire/guide#testnet-and-mainnet)
+with Sapphire.
 
 In this case, we should prepare a wallet with Testnet tokens on both BNB Smart
 Chain [Faucet](https://testnet.bnbchain.org/faucet-smart) and Sapphire [faucet](https://faucet.testnet.oasis.dev).

diff --git a/docs/dapp/opl/frontend.md b/docs/dapp/opl/frontend.md
@@ -12,10 +12,9 @@ simply apply a sparse checkout of the complete frontend repo. Inside your
 
 ```sh
 git init .
-git remote add -f origin https://github.com/oasisprotocol/playground;
-git config core.sparseCheckout true;
-echo "opl-secret-ballot/frontend/" >> .git/info/sparse-checkout;
-git pull origin main
+git remote add -f origin https://github.com/oasisprotocol/playground
+git checkout origin/main opl-secret-ballot/frontend
+mv opl-secret-ballot/frontend/ .
 ```
 
 Next, update the `@oasislabs/secret-ballot-backend` package name in

diff --git a/docs/dapp/opl/host.md b/docs/dapp/opl/host.md
@@ -1,8 +1,13 @@
 # DAO Contract
 
-Let's start with a `DAOV1.sol` smart contract that describes a basic DAO with a
-mapping of proposals. Place it inside your `contracts/` directory. We will
-deploy this contract to your home network such as BNB or Polygon.
+Let's start with a smart contract that describes a basic DAO, `DAOV1.sol`, with a
+mapping of proposals before we consider the OPL differences.
+
+## Base Contract
+
+Inside your `contracts/` directory, create a `DAOV1.sol` file. You may have
+already deployed a similar contract to your home network such as BNB or
+Polygon.
 
 ```solidity
 // SPDX-License-Identifier: MIT
@@ -88,8 +93,8 @@ contract DAOV1 {
 ```
 
 Instead of storing complete ballot proposals on the network, we will use
-[IPFS](https://ipfs.tech). Our smart contract will refer to a pinned [IPFS file](https://docs.ipfs.tech/concepts/lifecycle/#_1-content-addressable-representation)
-by its [hash](https://docs.ipfs.tech/concepts/hashing/).
+[IPFS](https://ipfs.tech). Our smart contract will refer to a pinned
+[IPFS file] by its [hash](https://docs.ipfs.tech/concepts/hashing/).
 
 ```solidity
 struct ProposalParams {
@@ -100,15 +105,104 @@ struct ProposalParams {
 ```
 
 Our very simple DAO contract creates proposals and manages them, allowing
-both active (`getActiveProposals`) and past proposals (`getPastProposals`) to
-be queried externally.
+both active and past proposals to be queried externally through methods
+`getActiveProposals` and `getPastProposals`. This would be sufficient on a
+single chain, and it is possible to develop confidential applications without
+bridges, relying solely on [Sapphire](../sapphire/README.mdx). However, we will proceed
+to demonstrate the cross-chain capabilities of OPL.
+
+## What is different with OPL?
+
+OPL leverages [Celer](https://celer.network)'s inter-chain [messaging]
+capabilities in order to connect smart contracts deployed on a home network
+such as Polygon, or BNB, with the privacy preserving smart contracts deployed
+on Sapphire.
+
+You will not need to learn how Celer Inter-chain Message (IM) works in order to
+use OPL, but if you would like to learn more, you can see that OPL realizes
+the Celer IM interface through the abstraction of an [Endpoint]:
+
+```solidity
+interface ICelerMessageBus {
+    function feeBase() external view returns (uint256);
+
+    function feePerByte() external view returns (uint256);
+
+    function sendMessage(
+        address _host,
+        uint256 _hostChainId,
+        bytes calldata _message
+    ) external payable;
+}
+```
+
+which allows us to use this bridge [function]:
+
+```solidity
+function sendMessage(
+    address _receiver,
+    uint64 _dstChainId,
+    bytes memory _message,
+    uint256 _fee
+) internal
+```
 
-### OPL Differences
+In production, you can see the deployed [cBridge contract] and
+[MessageBus contract].
 
-A *host contract* refers to a smart contract on a home network such as BNB or
-Polygon. We will extend the `Host` contract provided by OPL and add our own
-implementation of event handling to process cross-chain messages. Let's make
-the following changes to `DAOV1.sol`.
+### How does OPL do this?
+
+We can [register] functions with endpoints in order to simplify our code.
+Endpoints are effectively callbacks which listen to messages from the enclaved
+smart contract.
+
+```solidity
+function registerEndpoint(
+    bytes memory _method,
+    function(bytes calldata) returns (Result) _cb
+) internal {
+    // This is a waste of an SLOAD, but the alternative before immutable arrays
+    // (https://github.com/ethereum/solidity/issues/12587) land is terribly verbose.
+    // This can be fixed once gas usage becomes a problem.
+    endpoints[bytes4(keccak256(_method))] = _cb;
+}
+```
+
+Under the hood, a `postMessage` function [sends] the message using the Celer
+Message Bus. If you would prefer using a different bridging partner, this
+pattern will provide you a place to start that integration.
+
+```solidity
+    ICelerMessageBus(messageBus).sendMessage{value: fee}(
+        remote,
+        remoteChainId,
+        envelope
+    );
+```
+
+### Endpoints? Why not Solidity events?
+
+Events in Solidity are non-confidential and do not allow cross-chain
+communication. For this reason, OPL uses *endpoints* for passing messages
+cross-chain. For example, this function below will listen to such a message and
+ close the proposal.
+
+```solidity
+    function _oplBallotClosed(bytes calldata _args) internal returns (Result) {
+        (ProposalId proposalId, uint16 topChoice) = abi.decode(_args, (ProposalId, uint16));
+        proposals[proposalId].topChoice = topChoice;
+        proposals[proposalId].active = false;
+        activeProposals.remove(ProposalId.unwrap(proposalId));
+        pastProposals.push(proposalId);
+        emit ProposalClosed(proposalId, topChoice);
+        return Result.Success;
+    }
+```
+
+### Let's see the code
+
+Let's see OPL at work. We can add our own implementation of event handling to
+process cross-chain messages. Let's make the following changes to `DAOV1.sol`.
 
 ```diff
 diff --git a/backend/contracts/DAOV1.sol b/backend/contracts/DAOV1.sol
@@ -168,6 +262,13 @@ index 21ea93e..827d80a 100644
  }
 ```
 
+#### Host
+
+A _host_ contract in our terminology is just a smart contract that extends the
+`Host` contract [provided] and deployed on a home network such as BNB or
+Polygon with a reference to the Sapphire network where our _enclave_
+(privacy-preserving) smart contract will reside.
+
 #### Constructor
 
 We provide the address of the confidential (also known as *enclave*) smart
@@ -180,22 +281,12 @@ contract deployed on the Oasis Sapphire as a constructor parameter to the
     }
 ```
 
-#### Endpoints
-
-Events in Solidity are non-confidential and do not allow cross-chain
-communication. For this reason, OPL uses *endpoints* for passing messages
-cross-chain. Endpoints are effectively callbacks which listen to messages
-from the Enclaved smart contract. The function below will listen to such a
-message and close the proposal.
-
-```solidity
-    function _oplBallotClosed(bytes calldata _args) internal returns (Result) {
-        (ProposalId proposalId, uint16 topChoice) = abi.decode(_args, (ProposalId, uint16));
-        proposals[proposalId].topChoice = topChoice;
-        proposals[proposalId].active = false;
-        activeProposals.remove(ProposalId.unwrap(proposalId));
-        pastProposals.push(proposalId);
-        emit ProposalClosed(proposalId, topChoice);
-        return Result.Success;
-    }
-```
+[messaging]: https://im-docs.celer.network/developer/celer-im-overview
+[IPFS file]: https://docs.ipfs.tech/concepts/lifecycle/#_1-content-addressable-representation
+[function]: https://im-docs.celer.network/developer/development-guide/contract-framework#send-message
+[cBridge contract]: https://explorer.sapphire.oasis.io/address/0x9B36f165baB9ebe611d491180418d8De4b8f3a1f/transactions
+[MessageBus contract]: https://explorer.sapphire.oasis.io/address/0x9Bb46D5100d2Db4608112026951c9C965b233f4D/transactions
+[register]: https://github.com/oasisprotocol/sapphire-paratime/blob/9a74e57e72b06ba86ec8454062b8c0a5281edb97/contracts/contracts/opl/Endpoint.sol#L76-L84
+[sends]: https://github.com/oasisprotocol/sapphire-paratime/blob/9a74e57e72b06ba86ec8454062b8c0a5281edb97/contracts/contracts/opl/Endpoint.sol#L91-L119
+[provided]: https://github.com/oasisprotocol/sapphire-paratime/blob/main/contracts/contracts/opl/Host.sol
+[Endpoint]: https://github.com/oasisprotocol/sapphire-paratime/blob/9a74e57e72b06ba86ec8454062b8c0a5281edb97/contracts/contracts/opl/Endpoint.sol#L35-L45
diff --git a/docs/dapp/opl/introduction.md b/docs/dapp/opl/introduction.md
@@ -9,10 +9,11 @@ On-chain voting is the basis for any decentralized autonomous organization
 In this tutorial, you will create a [secret ballot](https://en.wikipedia.org/wiki/Secret_ballot)
 dApp that can only be built with the Oasis Privacy Layer.
 
-Why is this important? Privacy protects the voter (DAO token holder) from intimidation
-and bullying when exercising their right of participation on a protocol.
-Vote organizers can encourage participation with ballots not only by
-protecting the identity of voters but also by sealing the results of an ongoing
+Why is this important? [Privacy](https://en.wikipedia.org/wiki/Secret_ballot)
+protects the voter (DAO token holder) from intimidation and bullying when
+exercising their right of participation, such as on a protocol.
+Vote organizers can encourage participation with ballots not only by protecting
+the identity of voters, but also by sealing the results of an ongoing
 vote, giving the same weight to the first and last votes.
 
 ## Getting Started
@@ -23,11 +24,13 @@ you should still keep going! We will do this together.
 
 By the end of this tutorial, we will have:
 
-- used [Hardhat](https://hardhat.org/docs) to write the smart contracts for an
-OPL dApp
+- written smart contracts using the OPL [library](https://github.com/oasisprotocol/sapphire-paratime/blob/main/contracts/contracts/OPL.sol)
+- used [Hardhat](https://hardhat.org/docs) development environment for OPL
 - used [Hardhat Deploy](https://github.com/wighawag/hardhat-deploy) to deploy
-our smart contracts
+smarts contracts to a testnet.
 - used [Pinata](https://docs.pinata.cloud/what-can-i-learn-here/what-is-pinata)
 to store simple JSON data. Not everything has to go on a blockchain.
+- used [Celer](https://im-docs.celer.network/developer/celer-im-overview) to
+pass messages cross multiple chains
 - built a simple [Vue.JS](https://vuejs.org/guide/introduction.html)
 app to interact with our dApp through [MetaMask](https://docs.metamask.io/wallet).