diff --git a/docs/content/README.md b/docs/content/README.md index 2ef83d802..8e335cfd7 100644 --- a/docs/content/README.md +++ b/docs/content/README.md @@ -5,3 +5,4 @@ These are a few useful notes on the content directory here - This content is used in the `docs/website` directory. - The source of truth for ordering is `website/sidebars.ts`. - There are some files included in the repo that are not added to `website/sidebars.ts`. These are not accessible via the standard navigation flow, but are still hosted in our public docs. They are used for various other purposes, like interviews. +- The default page is the markdown page that contains `slug: /` diff --git a/docs/content/build/_category_.json b/docs/content/build/_category_.json deleted file mode 100644 index 0d8446a60..000000000 --- a/docs/content/build/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Build", - "position": 1, - "link": { - "type": "generated-index", - "description": "Build your first xdapp and get inspired" - } -} diff --git a/docs/content/build/faq.md b/docs/content/build/faq.md deleted file mode 100644 index b28891bb9..000000000 --- a/docs/content/build/faq.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -sidebar_position: 4 ---- - -# FAQ - -### Which chains does Omni support? - -**Mainnet**: Ethereum, Omni, Arbitrum One, Optimism, Base - -**Omega testnet**: Ethereum Holesky, Omni Omega, Arbitrum Sepolia, Optimism Sepolia, Base Sepolia - -More chains will be added overtime. - -### How fast is a message delivered? - -Rollup to rollup messages are roughly 5-10s for "latest" messages and 12 minutes for "finalized" messages. - -### How should I use finalized vs. latest? - -It depends on the use case, but we generally recommend using `finalized` for high value transactions where exactly once delivery semantics is critical. `latest` can be used for smaller magnitude transactions where delivery guarantees can be loosened. - -### How much does an xcall cost? - -The cost of an `xcall` is a function of: - -- destination chain: since an xcall is actually a function execution on a remote chain, we must consider the gas prices on that chain. -- calldata size: impacts gas fee on the destination -- gas limit: max gas you're willing to spend on the destination - -### If xcall is successfully sent on the source chain but the tx on the destination fails, what will happen? - -An xcall will only revert on the destination if there is logic in your smart contract on the destination that reverts. Generally, we recommend not reverting when receiving an xcall, rather reverting on the source before sending the xcall if possible. - -### What happens if a rollup reorgs? - -Reorgs have no impact on a `finalized` stream, as these streams wait for the rollup to be finalized on Ethereum before validating an XMsg. - -### Why doesn’t Omni wait for the 7-day challenge period for rollups? - -Rollups are actually finalized once transaction calldata is posted to L1. The 7 Day period is only from the perspective of L1 – because it takes smart contracts on L1 7 Days to confirm the state of a rollup. But anyone can compute what the current state of the rollup is before the 7 Day window by running an node for that rollup. Omni's validators each run L2 nodes for integrated rollups, and attest to the state of the rollup once txn calldata is posted. - -### What are Confirmation Levels? - -Omni's xchain message protocol currently offers 2 confirmation strategies. You can specify your confirmation strategy with each xcall. - -You may choose to use the same confirmation strategy for every `xcall` in your dapp. If this is the case, you can just hardcode a confirmation strategy. - -Or, you may want to adjust the `xcall`'s confirmation strategy based on the transaction's associated "value". For example, you may choose to implement logic that says: - -- `if a user is depositing > 1000 USDC, use "finalized"; else use "latest"` - -Here are the details of each type: - -#### `finalized` - -Finalized xmsgs are attested to and delivered only after the rollup's transaction data containing this xmsg finalizes on Ethereum Layer 1. This requires 2 beacon chain epochs, which typically takes about 12 minutes. However, this strategy offer strong benefits around delivery guarantees – a delivered message can only be "reorg'd out" if Ethereum itself reorgs, which is highly unlikely and requires 2/3 of Ethereum's validators to be slashed. - -Summary: - -- exactly once delivery guarantees -- ~12 minute delivery - -#### `latest` - -Latest xmsgs are attested to and delivered as soon as the transaction with the xmsg is included by the L2 sequencer in a block. This provides a much lower latency for message delivery – roughly 5-10s. However, it does come with an associated risk: the xmsg has a higher risk of being reorg'd out if the L2 sequencer misbehaves or fails. This may result in unintended consequences, and you should decide how much you're willing to trust L2 sequencers. - -- an xmsg is delivered on a destination chain, but the txn that initiated the xmsg gets reorged out of the source chain -- an xmsg is included in a txn on a source chain, but not delivered on the destination -- an xmsg is included in a txn on a source chain, and delivered multiple times on the destination - -Summary - -- low latency: ~5-10s -- no delivery guarantees - -Note that these risks are possible with all xchain messaging protocols. - -### Is Omni a bridging protocol? - -Please note that Omni does not bridge native tokens. - -The `msg.value` in an `xcall` is for fees, not for bridging native tokens. - -Omni's xchain messaging system allows contracts to send and receive function calls across chains. It is a simple and secure way to interact with contracts on other chains. - -However, Omni is not a bridge for canonical or native tokens. If you believe you need a bridge, we invite you to consider building a "chain-agnostic", rather than a cross-chain, application. Chat with the team if you're curious about this mental model! We believe the future of smart contract development should not force users to bridge – it should meet users where they are! - -### Does the Omni EVM support pre-EIP-155 transactions? - -Our public RPCs do not support pre-EIP-155 transactions. If you'd like to submit a pre-155 transaction, you can run a full node (see [relevant page](../operate/run-full-node.md)), enable [AllowUnprotectedTxs](https://github.com/ethereum/go-ethereum/blob/e67d5f8c441d5c85cfa69317db8d85794645af14/node/config.go#L199), and submit the transaction to your own endpoint. diff --git a/docs/content/build/quickstart.md b/docs/content/build/quickstart.md deleted file mode 100644 index c353661eb..000000000 --- a/docs/content/build/quickstart.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -slug: / ---- - -# Getting Started - -Omni makes it easy to create chain-abstracted applications. - - -This guide will walk you through deploying and interacting with -**[xstake](https://github.com/omni-network/xstake) - a simple chain-abstracted staking -app**. It's an example application that demonstrates how to accept deposits on multiple chains, while maintaining global accounting on Omni. - -In this guide you will: - -- Run an Omni devnet -- Deploy and use a chain-abstracted application - -#### Quick Overview - -The app has two contracts: - -- [`XStaker`](https://github.com/omni-network/xstake/blob/ad4cbb/src/XStaker.sol) - deployed on multiple chains, accepts ERC20 deposits. -- [`XStakeController`](https://github.com/omni-network/xstake/blob/ad4cbb/src/XStakeController.sol) - deployed on Omni, 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). - -### 1. 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 | bash -s - -# check installation -omni version -``` - - -### 2. Setup - - -Create a new directory, and scaffold a new xstake project. - -```bash -mkdir my-xstake -forge init --template https://github.com/omni-network/xstake -``` - - -### 3. 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" - } -] - -``` - - -### 4. 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 -``` - -### 5. Try it out - -Setup environment. -```bash -source deployments.sh - -# prefunded dev account -DEV_ACCOUNT=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 -DEV_PRIVKEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 -``` - -Mint and approve tokens. -```bash -cast send $OP_TOKEN "mint(address,uint256)" $DEV_ACCOUNT 100 --rpc-url $OP_RPC --private-key $DEV_PRIVKEY -cast send $OP_TOKEN "approve(address,uint256)" $OP_XSTAKER 100 --rpc-url $OP_RPC --private-key $DEV_PRIVKEY -``` - -Calculate xcall fee. -```bash -cast call $OP_XSTAKER "stakeFee(uint256)(uint256)" 100 --rpc-url $OP_RPC -``` - - -Stake! -```bash -# using --value from step above -cast send $OP_XSTAKER "stake(uint256)" 100 --rpc-url $OP_RPC --private-key $DEV_PRIVKEY --value 500000000 -``` - -Verify stake: -```bash -cast call $CONTROLLER "stakeOn(address,uint64)(uint256)" $DEV_ACCOUNT $OP_CHAINID --rpc-url $OMNI_RPC -``` - -Note that we made our deposit on `mock_op`, but our stake is tracked on Omni. You can follow the same steps to deposit on `mock_arb`, substituting rpcs / addresses as needed. - - -### 6. 🎉 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 deleted file mode 100644 index 026711df8..000000000 --- a/docs/content/build/walkthrough.md +++ /dev/null @@ -1,156 +0,0 @@ -# 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](/). - - -The app has two contracts: - -- [`XStaker`](https://github.com/omni-network/xstake/blob/ad4cbb/src/XStaker.sol) - deployed on multiple chains, accepts ERC20 deposits. -- [`XStakeController`](https://github.com/omni-network/xstake/blob/ad4cbb/src/XStakeController.sol) - deployed on Omni, tracks stake across all chains. - - -### XApp - -Both inherit from Omni's `XApp` utility base contract. - -```solidity -contract XStaker is XApp { - // ... -} -``` - -`XApp` makes it easy to send & receive cross-chain calls. Together, simple cross-chain calls + chain-aware global state compose the core of chain-abstracted applications built on Omni. - - -Using the xstake example, we'll walk through how to: - -- Inform global state via cross-chain call (`xcall`) -- Read the context of an xcall when it's received (`xmsg`) - - -### xcall - - -Our [`XStaker`](https://github.com/omni-network/xstake/blob/ad4cbb/src/XStaker.sol) contracts needs to accept ERC20 deposits. Let's start with a simple function that does just that. - -```solidity -function stake(uint256 amount) public payable { - require(amount > 0, "XStaker: insufficient amount"); - require(token.transferFrom(msg.sender, address(this), amount), "XStaker: transfer failed"); - - // now what? -} -``` - -If our app only lived on one chain, we'd track the user's deposit and be done. But our app spans multiple chains, with global state managed by the `XStakeController` on Omni. To update it, we'll use an `xcall`. - - -```solidity -// make a cross-chain call -xcall({ - to: controller, // to the XStakeController - destChainId: omniChainId(), // on Omni - data: ? // calling which function? - gasLimit: ? // with what gas limit? -}); -``` - - -### xmsg - - -We need a function to call on `XStakeController` that updates the global state. This function needs to be _aware_ of the cross-chain context in which it's called. This context is available in the `xmsg`. - -```solidity -xmsg.sourceChainId // where the xcall originated -xmsg.sender // who sent it -``` - -To read this context, mark your receiving function with the `xrecv` modifier. - - -```solidity -function recordStake(address user, uint256 amount) public xrecv { - // now read xmsg as needed -} -``` - -Using `xmsg`, we can authorize cross-chain calls to known `XStaker` deployments. - - -```solidity -// register XStaker deployments by chain id -mapping(uint64 => address) public xstakerOn; - -function recordStake(address user, uint256 amount) external xrecv { - require(xstakerOn[xmsg.sourceChainId] != address(0), "Controller: unsupported chain"); - require(xstakerOn[xmsg.sourceChainId] == xmsg.sender, "Controller: only xstaker"); - - stakeOn[user][xmsg.sourceChainId] += amount; -} -``` - - -### Putting it all together - - -With `XStakeController.recordStake` we have a function for our `XStaker` to call when a user makes a deposit. - -```solidity -// XSaker.sol -function stake(uint256 amount) public payable { - require(amount > 0, "XStaker: insufficient amount"); - require(token.transferFrom(msg.sender, address(this), amount), "XStaker: transfer failed"); - - xcall({ - destChainId: omniChainId(), - to: controller, - data: abi.encodeCall(XStakeController.recordStake, (msg.sender, amount)), - gasLimit: 100_000 - }); -} - -// XStakeController.sol -function recordStake(address user, uint256 amount) external xrecv { - require(xstakerOn[xmsg.sourceChainId] != address(0), "Controller: unsupported chain"); - require(xstakerOn[xmsg.sourceChainId] == xmsg.sender, "Controller: only xstaker"); - - stakeOn[user][xmsg.sourceChainId] += amount; -} -``` - -### Fees - - -Omni charge fees for each `xcall`. The `xcall(...)` utility will pay the fees if funds are avaible - either in the contract or sent with the call. -To make sure sufficient fees are sent with the call, add the following check: - -```solidity -uint256 fee = xcall(...) -require(msg.value >= fee); -``` - -It's often useful to know the fee beforehand, so you can set the proper `msg.value`. For this, the `XStaker` contract has a `stakeFee` function, using the `feeFor` utility. - -```solidity -function stakeFee(uint256 amount) public view returns (uint256) { - return feeFor({ - destChainId: omniChainId(), - data: abi.encodeCall(XStakeController.recordStake, (msg.sender, amount)), - gasLimit: 100_000 - }); -} -``` - -This is a useful pattern. For each `xcall` your contract makes, have a corresponding fee getter. This way, frontends, or other contracts, can set the correct `msg.value` with each call. - - -### Next Steps - -This walkthrough uses code snippets without context, and omits some flows / concepts. Notably: - -- unstaking -- xcall confirmation levels - -The full code is available and generously commented [here](https://github.com/omni-network/xstake/tree/ad4cbb). diff --git a/docs/content/learn/resources.md b/docs/content/learn/resources.md index e623833b4..03508d733 100644 --- a/docs/content/learn/resources.md +++ b/docs/content/learn/resources.md @@ -1,4 +1,4 @@ -# Resources +# Additional info Below is a list of resources that may be helpful as you explore Omni: diff --git a/docs/content/learn/what-is-omni.md b/docs/content/learn/what-is-omni.md index b693ca604..0a88518bf 100644 --- a/docs/content/learn/what-is-omni.md +++ b/docs/content/learn/what-is-omni.md @@ -1,3 +1,7 @@ +--- +slug: / +--- + # Overview ## Why does Omni exist? diff --git a/docs/content/operate/validator.md b/docs/content/operate/validator.md index 57dd7f6db..e2a387094 100644 --- a/docs/content/operate/validator.md +++ b/docs/content/operate/validator.md @@ -9,7 +9,7 @@ This guide describes the process to configure and register a validator on **main ## Pre-requisites - Synced Omni full node (`halo`+ `geth` ) on the [latest release](https://github.com/omni-network/omni/releases/latest). Otherwise follow the [Run a Full Node](./run-full-node.md) guide first. -- Ethereum L1 and multiple L2 RPC endpoints, required for cross-chain validation duties. See [Mainnet](../build/mainnet.md) and [Omega Testnet](../build/omega.md) for more details. +- Ethereum L1 and multiple L2 RPC endpoints, required for cross-chain validation duties. See [Mainnet](../resources/mainnet.md) and [Omega Testnet](../resources/omega.md) for more details. ## Summary diff --git a/docs/content/build/mainnet.md b/docs/content/resources/mainnet.md similarity index 76% rename from docs/content/build/mainnet.md rename to docs/content/resources/mainnet.md index 862b06d85..4377706f9 100644 --- a/docs/content/build/mainnet.md +++ b/docs/content/resources/mainnet.md @@ -2,20 +2,12 @@ **🚧 COMING SOON** +## Which chains does Omni’s mainnet support? -### Have Questions? +Omni’s mainnet deployment supports Ethereum L1, Arbitrum One, Optimism, and Base. More chains will be added over time. -Join our developer Telegram channel [here](https://t.me/omnidevsupport)! - -### Overview - -This document lays out relevant developer resources for the Omni mainnet. Please read below for necessary RPC URLs, Explorers, Tools, Libraries and Documentation. - - -### General Information - -### RPC URLs +## RPC URLs | **Chain Name** | **Chain ID** | RPC URL | | --- | --- | --- | @@ -25,7 +17,7 @@ This document lays out relevant developer resources for the Omni mainnet. Please | Optimism | 10 | [See on ChainList](https://chainlist.org/chain/10) | | Base | 8453 | [See on ChainList](https://chainlist.org/chain/8453) | -### Resources +## Resources | **Resource** | **Address** | | --- | --- | @@ -34,8 +26,13 @@ This document lays out relevant developer resources for the Omni mainnet. Please | Omni status page | [https://status.omni.network](https://status.omni.network/) | -### Contract addresses +## Contract addresses | Contract | Address | Note | | --- | --- | --- | | OmniPortal | TBD | Our portal contracts have the same address on all chains. | + + +## Have questions? + +Join our developer Telegram channel [here](https://t.me/omnidevsupport)! diff --git a/docs/content/build/omega.md b/docs/content/resources/omega.md similarity index 77% rename from docs/content/build/omega.md rename to docs/content/resources/omega.md index b25316409..1ff25feb3 100644 --- a/docs/content/build/omega.md +++ b/docs/content/resources/omega.md @@ -1,22 +1,17 @@ # Testnet -The current testnet network is called **Omega** (chain id [164](https://chainlist.org/chain/164)). +## Which chains does Omni’s testnet support? -### Have Questions? +Omni’s testnet deployment, **Omega** (chain id [164](https://chainlist.org/chain/164)), supports Ethereum Holesky, Arbitrum Sepolia, Optimism Sepolia, and Base Sepolia. More chains will be added over time. -Join our developer Telegram channel [here](https://t.me/omnidevsupport)! - -### Overview - -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 +## General Information Contracts can be deployed on the Omni EVM using the RPC below. To get started, you can request $OMNI tokens via our [faucet](https://faucet.omni.network/). -### RPC URLs +## RPC URLs | **Chain Name** | **Chain ID** | RPC URL | | --- | --- | --- | @@ -26,7 +21,7 @@ Contracts can be deployed on the Omni EVM using the RPC below. To get started, y | Optimism Sepolia | 11155420 | [See on ChainList](https://chainlist.org/chain/11155420) | | Base Sepolia | 84532 | [See on ChainList](https://chainlist.org/chain/84532) | -### Resources +## Resources | **Resource** | **Address** | | --- | --- | @@ -36,8 +31,12 @@ Contracts can be deployed on the Omni EVM using the RPC below. To get started, y | Omni status page | [https://status.omni.network](https://status.omni.network/) | -### Contract addresses +## Contract addresses | Contract | Address | Note | | --- | --- | --- | | OmniPortal | `0xcB60A0451831E4865bC49f41F9C67665Fc9b75C3` | Our portal contracts have the same address on all chains. | + +## Have questions? + +Join our developer Telegram channel [here](https://t.me/omnidevsupport)! diff --git a/docs/website/sidebars.ts b/docs/website/sidebars.ts index f52b84410..a917b1b58 100644 --- a/docs/website/sidebars.ts +++ b/docs/website/sidebars.ts @@ -16,18 +16,6 @@ const sidebars: SidebarsConfig = { // But you can create a sidebar manually tutorialSidebar: [ - { - type: 'category', - label: 'Build', - items: [ - 'build/quickstart', - 'build/walkthrough', - 'build/mainnet', - 'build/omega', - 'build/faq', - ], - collapsed: true, - }, { type: 'category', label: 'Learn', @@ -52,6 +40,15 @@ const sidebars: SidebarsConfig = { ], collapsed: true, }, + { + type: 'category', + label: 'Resources', + items: [ + 'resources/mainnet', + 'resources/omega', + ], + collapsed: true, + }, ], };