diff --git a/docs/site/docs/develop/quickstart/quickstart.md b/docs/site/docs/develop/quickstart/quickstart.md index 26a273654..2de8902e9 100644 --- a/docs/site/docs/develop/quickstart/quickstart.md +++ b/docs/site/docs/develop/quickstart/quickstart.md @@ -4,11 +4,13 @@ sidebar_position: 1 # 3-Minute Cross-Chain dApp -This QuickStart guide will run through how to start an Omni cross chain dApp in less than three minutes. +This QuickStart guide will run through how to start an Omni XApp in less than 3 minutes. In this guide you will: -- Install the Omni CLI, scaffold a new project and run a local devnet +- 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 @@ -38,12 +40,18 @@ Note: this requires [foundry](https://github.com/foundry-rs/foundry) to be insta
Test the Contracts with Forge -You can test the contracts with Forge by running the following command: +You can test the contracts with Forge by running: ```bash forge test ``` +or + +```bash +make test +``` +
### Step 3: Run a local devnet @@ -58,38 +66,29 @@ Note: this requires [Docker](https://docs.docker.com/get-docker/) to be installe ### Step 4: Deploy contracts -Deploy the contracts to the local devnet using foundry: - -
-Obtaining Parameter Values - -You can obtain RPC URL values and portal addresses for the running devnet chains by running the following command: +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 -omni devnet info +cp .env.example .env ``` -And the private key value is the second listed anvil private key, found by running: +If you'd like to know where some of these values came from ```bash -anvil -``` - -These values are found in `./script/bash/.env.example` and are used to deploy the contracts. You can rename the file to `.env` and fill in the values for other networks. You don't have to run any of these commands or update the `.env` file if you are following the tutorial steps. +# For devnet RPC data and portal addresses +omni devnet info -This `.env` file is used by the bash `deploy.sh` script to deploy the contracts. You can otherwise choose to deploy the contracts using only forge on your terminal as shown in this tutorial. +# For the private key that's prefunded locally: +anvil +```` -
+Deploy the contracts to the local devnet using foundry: ```bash -export PORTAL_ADDRESS=0xb835dc695c6bfc8373c0d56973b5d9e9b083e97b -export GLOBAL_GREETER_ADDRESS=0x8464135c8F25Da09e49BC8782676a84730C318bC -forge script DeployGlobalGreeter --broadcast --rpc-url http://localhost:8000 --private-key 0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d -forge script DeployRollupGreeter --broadcast --rpc-url http://localhost:8001 --private-key 0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d -forge script DeployRollupGreeter --broadcast --rpc-url http://localhost:8002 --private-key 0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d +make deploy ``` -Note: we know the address the `GlobalGreeter` 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 `RollupGreeter` 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. +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 @@ -116,15 +115,15 @@ cast send 0x8464135c8F25Da09e49BC8782676a84730C318bC 'greet(string)' 'Yay in 3 m ### Step 6: Check the Greet -You can check the greet has been saved on the Omni EVM global state by running the following command: +You can check the greet has been saved on the Omni EVM `GreetingBook` by running the following command: ```bash -cast call 0x8464135c8F25Da09e49BC8782676a84730C318bC "lastGreet():(uint64,uint256,address,string)" --rpc-url http://localhost:8000 +cast call 0x8464135c8F25Da09e49BC8782676a84730C318bC "lastGreet():(address,string,uint64,uint256)" --rpc-url http://localhost:8000 ``` ### 🎉 Done 🎉 -You have successfully deployed and interacted with an Omni cross-chain dApp in less than three minutes! +You have successfully deployed and interacted with an Omni XApp in less than three minutes!
gg wp diff --git a/docs/site/docs/develop/xapp/example.md b/docs/site/docs/develop/xapp/example.md index 86b09239c..d533e3397 100644 --- a/docs/site/docs/develop/xapp/example.md +++ b/docs/site/docs/develop/xapp/example.md @@ -9,12 +9,12 @@ import GitHubCodeBlock from '@site/src/components/GitHubCodeBlock/GitHubCodeBloc Here's an example of a simple cross-chain contract set for setting and getting a string. 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. `RollupGreeter` - A contract deployed on a rollup chain that sends greetings to the Omni chain. -2. `GlobalGreeter` - A contract deployed on the Omni chain that stores greetings. +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. -## `RollupGreeter` Contract +## `Greeter` Contract - + ### Walkthrough @@ -24,7 +24,7 @@ First, inherit from `XApp`. ```solidity -contract XGreeter is XApp { +contract Greeter is XApp { // ... } ``` @@ -32,9 +32,9 @@ contract XGreeter 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/src/libraries/ConfLevel.sol). ```solidity -constructor(address portal, address _omniChainGreeter) XApp(portal, ConfLevel.Latest) { - omniChainGreeter = _omniChainGreeter; -} +constructor(address portal, address _greetingBook) XApp(portal, ConfLevel.Latest) { + greetingBook = _greetingBook; + } ``` ### Perform a Cross Chain Call @@ -43,27 +43,28 @@ To call a contract on another chain, use `xcall`. ```solidity function greet(string calldata greeting) external payable { - xcall( + uint256 fee = xcall( // params for xcall ); } + ``` ## `GlobalGreeter` Contract - + ### Walkthrough -Similar to `RollupGreeter`, we inherit from `XApp`. +Similar to `Greeter`, we inherit from `XApp`. ```solidity -contract GlobalGreeter is XApp { +contract GreetingBook is XApp { // ... } ``` -Similiar to `RollupGreeter`, we can specify the confirmation level for the cross-chain message. +Similiar to `Greeter`, we can specify the confirmation level for the cross-chain message. ```solidity constructor(address portal) XApp(portal, ConfLevel.Latest) { @@ -72,31 +73,21 @@ constructor(address portal) XApp(portal, ConfLevel.Latest) { ### Receive a Cross Chain Call -When receiving an `xcall`, you can read its context via `omni.xmsg()`. +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 `XGreeter` extract the source chain and sender of the `xcall` to store the greeting in a struct. +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(string calldata _greeting) external xrecv { - // Initialize the fee to 0, for local calls - uint256 fee = 0; - if (isXCall() && xmsg.sourceChainId != omni.chainId()) { - // Calculate the fee for the cross-chain call - fee = feeFor(xmsg.sourceChainId, abi.encodeWithSelector(this.greet.selector, _greeting), DEST_TX_GAS_LIMIT); - } +function greet(address user, string calldata _greeting) external xrecv { + require(omni.isXCall(), "GreetingBook: only xcalls"); - // Create a Greeting struct to store information about the received greeting - Greeting memory greeting = - Greeting(xmsg.sourceChainId, block.timestamp, fee, msg.sender, xmsg.sender, _greeting); - - // Update the lastGreet variable with the information about the received greeting - lastGreet = greeting; -} + 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. diff --git a/docs/site/docs/tools/contracts/contracts.md b/docs/site/docs/tools/contracts/contracts.md index 020ec80d0..4a9210575 100644 --- a/docs/site/docs/tools/contracts/contracts.md +++ b/docs/site/docs/tools/contracts/contracts.md @@ -8,8 +8,7 @@ Omni includes the following Solidity helpers to help you develop your Omni proje - [`XApp`](../../develop/xapp/installation.md) - A base contract that provides a set of common functions and variables for your contracts. - [`XGreeter`](../../develop/xapp/example.md) - A simple contract that demonstrates how to use the `XApp` contract. -- [`XGreeter Template`](https://github.com/omni/omni-forge-template) - A template that you can use to scaffold a new project with an `XGreeter` contract. Used by the Omni CLI `developer new` command. -- [`XRegistry`](https://github.com/omni-network/omni/blob/main/contracts/src/protocol/XRegistry.sol) - A contract that provides a registry for contracts to register themselves. +- [`XGreeter Template`](https://github.com/omni/hello-world-template) - A template that you can use to scaffold a new project with a `Greeter` and `GreetingBook` contract. Used by the Omni CLI `developer new` command. ## Awesome Omni Examples and Templates