Skip to content

Commit

Permalink
chore(docs): update hello-world-template references (#1605)
Browse files Browse the repository at this point in the history
the hello-world-template had a makeover
([here](omni-network/hello-world-template#8))
and references to it need to be updated.

issue: #1596
  • Loading branch information
ttarsi authored Jul 30, 2024
1 parent 216cec3 commit ef9c9f2
Show file tree
Hide file tree
Showing 3 changed files with 46 additions and 57 deletions.
51 changes: 25 additions & 26 deletions docs/site/docs/develop/quickstart/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -38,12 +40,18 @@ Note: this requires [foundry](https://github.com/foundry-rs/foundry) to be insta
<details>
<summary>Test the Contracts with Forge</summary>

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
```

</details>

### Step 3: Run a local devnet
Expand All @@ -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:

<details>
<summary>Obtaining Parameter Values</summary>

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
````

</details>
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

Expand All @@ -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!

<figure align="center">
<img src="/img/cat.png" alt="gg wp" width="350" height="350" />
Expand Down
49 changes: 20 additions & 29 deletions docs/site/docs/develop/xapp/example.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

<GitHubCodeBlock url="https://github.com/omni-network/hello-world-template/blob/f4002e90960e013be18c0be44d07aadb34264489/src/RollupGreeter.sol" />
<GitHubCodeBlock url="https://github.com/omni-network/hello-world-template/blob/48ff2f5277b4c144802c1ffa894a03ac071f02fc/src/Greeter.sol" />

### Walkthrough

Expand All @@ -24,17 +24,17 @@ First, inherit from `XApp`.


```solidity
contract XGreeter is XApp {
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/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
Expand All @@ -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

<GitHubCodeBlock url="https://github.com/omni-network/hello-world-template/blob/1d0ba3c882c47284b1b16bc4b02f68e996a1e4a1/src/GlobalGreeter.sol" />
<GitHubCodeBlock url="https://github.com/omni-network/hello-world-template/blob/48ff2f5277b4c144802c1ffa894a03ac071f02fc/src/GreetingBook.sol" />

### 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) {
Expand All @@ -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.
Expand Down
3 changes: 1 addition & 2 deletions docs/site/docs/tools/contracts/contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down

0 comments on commit ef9c9f2

Please sign in to comment.