From f2c03facc3de71a959556d73afaa589daee32333 Mon Sep 17 00:00:00 2001 From: Kevin Halliday Date: Mon, 26 Aug 2024 18:10:08 -0400 Subject: [PATCH] chore(docs): rewrite build docs --- docs/content/.gitignore | 1 + docs/content/build-xdapp/quickstart.md | 130 ------------- docs/content/build-xdapp/showcase-dapps.md | 91 --------- docs/content/build-xdapp/walkthrough.md | 117 ------------ .../{build-xdapp => build}/_category_.json | 0 .../testnet-omega.md => build/omega.md} | 8 +- docs/content/build/quickstart.md | 174 ++++++++++++++++++ docs/content/build/walkthrough.md | 17 ++ docs/website/sidebars.ts | 7 +- 9 files changed, 198 insertions(+), 347 deletions(-) create mode 100644 docs/content/.gitignore delete mode 100644 docs/content/build-xdapp/quickstart.md delete mode 100644 docs/content/build-xdapp/showcase-dapps.md delete mode 100644 docs/content/build-xdapp/walkthrough.md rename docs/content/{build-xdapp => build}/_category_.json (100%) rename docs/content/{build-xdapp/testnet-omega.md => build/omega.md} (76%) create mode 100644 docs/content/build/quickstart.md create mode 100644 docs/content/build/walkthrough.md diff --git a/docs/content/.gitignore b/docs/content/.gitignore new file mode 100644 index 000000000..71860a75d --- /dev/null +++ b/docs/content/.gitignore @@ -0,0 +1 @@ +!build diff --git a/docs/content/build-xdapp/quickstart.md b/docs/content/build-xdapp/quickstart.md deleted file mode 100644 index 0a77b6ccd..000000000 --- a/docs/content/build-xdapp/quickstart.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -sidebar_position: 1 -slug: / ---- - -# My First XDapp - -This QuickStart guide will run through how to start an Omni XDApp (cross-chain decentralized app) in 5 minutes. - -In this guide you will: - -- Install the Omni CLI -- Scaffold a new project -- Run a local devnet, including Omni and multiple rollups -- Deploy contracts using foundry to the local devnet and test their functionality - -## Steps - -### Step 1: Install the Omni CLI - -First, install the Omni CLI by running the following command: - -```bash -curl -sSfL https://raw.githubusercontent.com/omni-network/omni/main/scripts/install_omni_cli.sh | sh -s -``` - -### Step 2: Scaffold a new project - -Next, create a new directory for your project and scaffold a new project using the Omni CLI: - -```bash -mkdir my-omni-dapp -cd my-omni-dapp -omni developer new -``` - -Note: this requires [foundry](https://github.com/foundry-rs/foundry) to be installed on your machine. - -
-Test the Contracts with Forge - -You can test the contracts with Forge by running: - -```bash -forge test -``` - -or - -```bash -make test -``` - -
- -### Step 3: Run a local devnet - -Start a local devnet by running the following command: - -```bash -omni devnet start -``` - -Note: this requires [Docker](https://docs.docker.com/get-docker/) to be installed on your machine. - -### Step 4: Deploy contracts - -First, copy `.env.example` to `.env`. You shouldn't need to modify any parameters, but this stores some important info, so you should check it out. - -```bash -cp .env.example .env -``` - -If you'd like to know where some of these values came from - -```bash -# For devnet RPC data and portal addresses -omni devnet info - -# For the private key that's prefunded locally: -anvil -```` - -Deploy the contracts to the local devnet using foundry: - -```bash -make deploy -``` - -Note: we know the address the `GreetingBook` will be deployed to as a new network is started and the nonce for the account used to deploy is always the same (0). The `Greeter` contract is deployed to the same address on both the mock chains, since these are also new networks and the account has no actions on that account. - -### Step 5: Perform a Cross-Chain Greet - -You can now perform a cross-rollup greet by running the following command: - -
-Obtaining Deployment Addresses - -You can obtain the XGreeter deployment addresses from the output of the previous forge script deployment. - -Because the devnet has just been started, the addresses will be the same as the ones shown below: - -```bash -omni_evm: 0x8464135c8F25Da09e49BC8782676a84730C318bC -mock_op: 0x8464135c8F25Da09e49BC8782676a84730C318bC -mock_arb: 0x8464135c8F25Da09e49BC8782676a84730C318bC -``` - -
- -```bash -cast send 0x8464135c8F25Da09e49BC8782676a84730C318bC 'greet(string)' 'Yay in 5 minutes!' --private-key 0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d --rpc-url http://localhost:8001 --value 1ether -``` - -### Step 6: Check the Greet - -You can check the greet has been saved on the Omni EVM `GreetingBook` by running the following command: - -```bash -cast call 0x8464135c8F25Da09e49BC8782676a84730C318bC "lastGreet():(address,string,uint64,uint256)" --rpc-url http://localhost:8000 -``` - -### πŸŽ‰ Done πŸŽ‰ - -You have successfully deployed and interacted with an Omni XApp in less than five minutes! - -
- gg wp -
-
diff --git a/docs/content/build-xdapp/showcase-dapps.md b/docs/content/build-xdapp/showcase-dapps.md deleted file mode 100644 index 8e1bcbd6d..000000000 --- a/docs/content/build-xdapp/showcase-dapps.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -sidebar_position: 3 ---- - -import GitHubCodeBlock from '@site/src/components/GitHubCodeBlock/GitHubCodeBlock'; - -# Showcase - - - -## xstake - - An [example xchain staking app](https://github.com/omni-netwpr/xstake) that allows ERC20 deposits on multiple chains. - - - - -## Ethereum to Omni bridge - -OMNI is an ERC-20 token on Layer 1, and we understand that developers and users need a seamless way to transfer it to the Omni EVM for gas payments. To address this, we've developed a bridge that utilizes the Omni protocol, ensuring smooth and secure token transfers. - - -### Omni to Ethereum - - -### Ethereum to Omni - - - -## What else? - -:::tip -Get inspired by the following ideas. Looking forward to seeing your PRs on https://github.com/omni-network/awesome-omni -::: - -
-
-
- ### NFT Community Backed Stablecoin - Take a heavily community / social-backed asset and use it as a stablecoin. $CULT (Remelia NFT family) or other strong NFT community-backed token could be used as initial collateral source. -
-
- ### Real Estate Index Synthetics / Perps - GMX-style perps that track commercial and residential real estate indices from major global cities. Pooled collateral model. -
-
- ### TikTok Perps - GMX-style perps that track hashtags, sounds, follower counts on TikTok clone (or pulled from actual TikTok API) application. -
-
- ### Twitch Livestream Spot / Perps Betting - Betting markets for Twitch livestreams – i.e., Fortnite already allows players to bet on their own number of kills in a match. Could create live lines / markets, revenue share / portion of total pool goes back to streamer. -
-
- ### Weather Betting - Spot / leverage / perps trading on weather – i.e., will it rain in X city on Y day (futures), will it rain in X and Y cities on the same day (parlay), over/under on temperatures, will temperature be above/below X on Y day of the week. -
-
- ### Rocket Game - Game which displays an ascending rocket that explodes at a β€œrandom” point in time with an increasing multiplier / reward until explosion. Allow for social live betting on the side for greater social coordination. -
-
- ### Synthetic Asset Management - GMX-style spot / perps on commonly traded ETFs and mutual funds or foreign stocks / commodities. -
-
- ### Google Search Predictions - Trending search markets on Google, binary predictions on if X or Y word/phrase will have more searches on Z day, week, month. -
-
- ### VC / Angel Perps - Perps / synthetics that bucket VC-portfolio tokens or angel allocations – i.e., Paradigm = $UNI, $DYDX, Panterra = $INJ, $OMNI, Multicoin = $SOL, $SEI. -
-
- ### Frictionless NFTs - Launchpad for [xERC-721s](https://www.openliquidity.org/research-eips/eip-7611) as mechanism to most easily create chain-agnostic NFTs / POAPs, SBTs, in-game assets. -
-
- ### Universal Launchpad - Chain-agnostic crowdfunding launchpad platform that pulls deposits from any L2 and creates tokens that can be traded across all L2s. -
-
- ### Chain-Agnostic Casino - Chain-agnostic casino games that allow users to deposit collateral and participate in on-chain games from any Ethereum L2 without the need to bridge, manage multiple assets, wallets, etc. -
-
- ### Ultra Simple Binary Markets - Single-market app that pulls deposits from every chain – best suited for one massive event (i.e., presidential election). Painfully simple frontend with deposit contracts. -
-
-
diff --git a/docs/content/build-xdapp/walkthrough.md b/docs/content/build-xdapp/walkthrough.md deleted file mode 100644 index 9774d2e00..000000000 --- a/docs/content/build-xdapp/walkthrough.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -sidebar_position: 2 ---- - -import GitHubCodeBlock from '@site/src/components/GitHubCodeBlock/GitHubCodeBlock'; - -# XDapp walkthrough - -Let's see what's happening under the hood. This contract lets you send greetings from a rollup chain to a global storage contract deployed on Omni. Two main contracts are used in this example: - -1. `Greeter` - A contract deployed on a rollup that sends greetings to the Omni EVM. -2. `GreetingBook` - A contract deployed on the Omni EVM that stores greetings from all supported chains. - -## `Greeter` Contract - - - -Let's walk through this step by step. - -First, inherit from `XApp`. - - -```solidity -contract Greeter is XApp { - // ... -} -``` - -You may also specify the confirmation level for the cross-chain message. This is the level of finalisation of the transaction containing the message you want to wait for. In this example, we set it to `Latest`, meaning the message is relayed on block creation at source. You can see the supported confirmation levels [here](https://github.com/omni-network/omni/blob/main/contracts/core/src/libraries/ConfLevel.sol). - -```solidity -constructor(address portal, address _greetingBook) XApp(portal, ConfLevel.Latest) { - greetingBook = _greetingBook; - } -``` - -### Perform a Cross Chain Call - -To call a contract on another chain, use `xcall`. - -```solidity -function greet(string calldata greeting) external payable { - uint256 fee = xcall( - // params for xcall - ); -} - -``` - -## `GreetingBook` Contract - - - -Similar to `Greeter`, we inherit from `XApp`. - -```solidity -contract GreetingBook is XApp { - // ... -} -``` - -Similiar to `Greeter`, we can specify the confirmation level for the cross-chain message. - -```solidity -constructor(address portal) XApp(portal, ConfLevel.Latest) { -} -``` - -### Receive a Cross Chain Call - -When receiving an `xcall`, you can read its context via `omni.xmsg()`, which is shortened by `XAapp` to `xmsg` for convenience. - -```solidity -xmsg.sourceChainId // where this xcall came from -xmsg.sender // who sent it -``` - -With this context, we can have our `GreetingBook` extract the source chain and sender of the `xcall` to store the greeting in a struct. - -```solidity -function greet(address user, string calldata _greeting) external xrecv { - // ... - - lastGreet = Greeting(user, _greeting, xmsg.sourceChainId, block.timestamp); - } -``` - -For convenience, `XApp` defines the `xrecv` modifier. This modifier reads the current xmsg into storage, and deletes after its function's execution. - -```solidity -modifier xrecv() { - xmsg = omni.xmsg(); - _; - delete xmsg; -} -``` - -It also visually marks a function as the target of an `xcall`. Though, the `xrecv` modifier is not required to receive an `xcall`. Using this modifier, we can simplify our `XGreeter` a bit further. - -### Checking for Cross Chain Calls - -Note that not every call is an `xcall`. In these cases, `xmsg` will be its zero value. - -```solidity -xmsg.sourceChainId // 0 -xmsg.sender // address(0) -``` - -You can check if the current call is an `xcall`, and the sender is the portal, with `isXCall()`. - -```solidity -function greet(address user, string calldata _greeting) external xrecv { - require(isXCall(), "GreetingBook: only xcalls"); - - // ... - } -``` diff --git a/docs/content/build-xdapp/_category_.json b/docs/content/build/_category_.json similarity index 100% rename from docs/content/build-xdapp/_category_.json rename to docs/content/build/_category_.json diff --git a/docs/content/build-xdapp/testnet-omega.md b/docs/content/build/omega.md similarity index 76% rename from docs/content/build-xdapp/testnet-omega.md rename to docs/content/build/omega.md index 500cc6d44..6d37d0fff 100644 --- a/docs/content/build-xdapp/testnet-omega.md +++ b/docs/content/build/omega.md @@ -2,7 +2,7 @@ sidebar_position: 4 --- -# Omni Omega Testnet +# Omega Testnet ### Have Questions? @@ -13,9 +13,7 @@ Join our developer Telegram channel [here](https://t.me/+zDWsRVjLXzZkOTIx)! This document lays out relevant developer resources for the Omni Omega testnet. Please read below for necessary RPC URLs, Explorers, Tools, Libraries and Documentation. -### General Information - -Contracts can be deployed to the Omni EVM RPC listed below. This will require having some testnet **$OMNI**. To obtain some either join the Telegram group or reach out to the team. +To get testnet **$OMNI**, use our [faucet](https://faucet.omni.network), or reach out to the team. ### RPC URLs @@ -41,4 +39,4 @@ Contracts can be deployed to the Omni EVM RPC listed below. This will require ha | Contract | Address | Note | | --- | --- | --- | -| Portal | `0xcB60A0451831E4865bC49f41F9C67665Fc9b75C3` | Our Portal contracts have a single, unified contract address across the Omni EVM and all supported rollups. | +| OmniPortal | `0xcB60A0451831E4865bC49f41F9C67665Fc9b75C3` | Our portal contracts have the same address on all chains. | diff --git a/docs/content/build/quickstart.md b/docs/content/build/quickstart.md new file mode 100644 index 000000000..a350f8d3f --- /dev/null +++ b/docs/content/build/quickstart.md @@ -0,0 +1,174 @@ +--- +sidebar_position: 1 +slug: / +--- + +# Getting Started + +This guide will walk you through deploying and interacting with +**[xstake](https://github.com/omni-network/xstake) - a simple chain-abstracted staking +app**. This is an example application that demonstrates how to accept deposits on multiple chains, and maintain global accounting on Omni. + +In this guide you will: + +- Run a devnet +- Deploy the contracts +- Stake! + +
+ +### Components + +The app has two contracts: + +- [`XStaker`](https://github.com/omni-network/xstake/blob/main/src/XStaker.sol) - deployed on multiple chains, accepts ERC20 deposits. +- [`XStakeController`](https://github.com/omni-network/xstake/blob/main/src/XStakeController.sol) - tracks stake across all chains. + +This is all the context you need for this guide. For a full explanation of how the contracts work, see [Walkthrough](/build/walkthrough). + +
+ +### Requirements + +You'll need the following installed: + +- [docker](https://docs.docker.com/get-started/get-docker/) +- [foundry](https://book.getfoundry.sh/getting-started/installation) + + +And the Omni CLI: + + +```bash +# install +curl -sSfL https://raw.githubusercontent.com/omni-network/omni/main/scripts/install_omni_cli.sh | sh -s + +# check installation +omni version +``` + +
+ + +### Setup + + +Create a new directory, and scaffold a new xstake project. + +```bash +mkdir my-xstake +forge init --template https://github.com/omni-network/xstake +``` + +
+ + +### Run a devnet + +Start a local devnet by running the following command: + +```bash +omni devnet start + +``` + +You should have a devnet running with three chains: `omni_evm`, `mock_op`, and `mock_arb`. Run `omni devnet info` to check. + +```bash +omni devnet info + +[ + { + "chain_id": 1655, + "chain_name": "mock_op", + "portal_address": "0xb835dc695c6bfc8373c0d56973b5d9e9b083e97b", + "rpc_url": "http://127.0.0.1:8001" + }, + { + "chain_id": 1656, + "chain_name": "mock_arb", + "portal_address": "0xb835dc695c6bfc8373c0d56973b5d9e9b083e97b", + "rpc_url": "http://127.0.0.1:8002" + }, + { + "chain_id": 1651, + "chain_name": "omni_evm", + "portal_address": "0xb835dc695c6bfc8373c0d56973b5d9e9b083e97b", + "rpc_url": "http://127.0.0.1:8000" + } +] + +``` + + +### Deploy contracts + + +```bash +make devnet-deploy +``` + +This outputs `deployments.sh` with addresses, RPCs and chain IDs - for your convenience :handshake:. + +```bash +source deployments.sh + +# rpcs +echo $OMNI_RPC # Omni EVM RPC +echo $OP_RPC # Mock OP RPC +echo $ARB_RPC # Mock Arb RPC + +# chain ids +echo $OMNI_CHAINID # Omni EVM chain ID +echo $OP_CHAINID # Mock OP chain ID +echo $ARB_CHAINID # Mock Arb chain ID + +# addresses +echo $OP_TOKEN # ERC20 token address on Mock OP +echo $ARB_TOKEN # ERC20 token address on Mock Arb +echo $OP_XSTAKER # XStaker contract address on Mock OP +echo $ARB_XSTAKER # XStaker contract address on Mock Arb +echo $CONTROLLER # XStakeController contract address on Omni EVM +``` + +
+ +### Stake! + +Mint yourself some tokens and stake them on Mock OP. + + +```bash +source deployments.sh + +# prefunded dev account +DEV_ACCOUNT=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 +DEV_PRIVKEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 + +# mint tokens +cast send $OP_TOKEN "mint(address,uint256)" $DEV_ACCOUNT 100 --rpc-url $OP_RPC --private-key $DEV_PRIVKEY + +# approve xstaker +cast send $OP_TOKEN "approve(address,uint256)" $OP_XSTAKER 100 --rpc-url $OP_RPC --private-key $DEV_PRIVKEY + +# check stake fee (use as --value in next step to cover xcall fee) +cast call $OP_XSTAKER "stakeFee(uint256)(uint256)" 100 --rpc-url $OP_RCP + +# stake! +cast send $OP_XSTAKER "stake(uint256)" 100 --rpc-url $OP_RPC --private-key $DEV_PRIVKEY --value 500000000 + +# check stake on omni +cast call $CONTROLLER "stakeOn(address,uint64)(uint256)" $DEV_ACCOUNT $OP_CHAINID --rpc-url $OMNI_RPC +``` + +
+ + +### πŸŽ‰ Done πŸŽ‰ + +That's it! You've deployed and used your first chain-abstacted application on Omni. Continue to [Walkthrough](/build/walkthrough) to learn more about how the contracts work. + +
+ gg wp +
+
diff --git a/docs/content/build/walkthrough.md b/docs/content/build/walkthrough.md new file mode 100644 index 000000000..d5cc73c8f --- /dev/null +++ b/docs/content/build/walkthrough.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 2 +--- + +import GitHubCodeBlock from '@site/src/components/GitHubCodeBlock/GitHubCodeBlock'; + +# Walkthrough + + +In this guide we'll take a deeper look at the contracts that make up **[xstake](https://github.com/omni-network/xstake) - the simple chain-abstracted staking app** we deployed in the [Getting Started](/). + +### Components + +The app has two contracts: + +- [`XStaker`](https://github.com/omni-network/xstake/blob/main/src/XStaker.sol) - deployed on multiple chains, accepts ERC20 deposits. +- [`XStakeController`](https://github.com/omni-network/xstake/blob/main/src/XStakeController.sol) - tracks stake across all chains. diff --git a/docs/website/sidebars.ts b/docs/website/sidebars.ts index 442ebeb1e..286f6332f 100644 --- a/docs/website/sidebars.ts +++ b/docs/website/sidebars.ts @@ -20,10 +20,9 @@ const sidebars: SidebarsConfig = { type: 'category', label: 'Build', items: [ - 'build-xdapp/quickstart', - 'build-xdapp/walkthrough', - 'build-xdapp/showcase-dapps', - 'build-xdapp/testnet-omega', + 'build/quickstart', + 'build/walkthrough', + 'build/omega', ], collapsed: true, },