Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: Move Localnet development to separate page #977

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: Move Localnet development to separate page #977

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
80db33b
docs: Move localnet development to separate page
aefhm Oct 8, 2024
84e30a8
Apply suggestions from code review
aefhm Oct 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/dapp/emerald/network.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ import {AddEmeraldToMetaMask as E, AddEmeraldTestnetToMetaMask as ET} from '@sit
| Tools | | [Testing token Faucet][faucet] | [Local development Docker image][localnet]

[faucet]: https://faucet.testnet.oasis.io/
[localnet]: https://github.com/oasisprotocol/oasis-web3-gateway/tree/main/docker
[localnet]: /dapp/tools/localnet
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please use paths to the .md files instead.

Suggested change
[localnet]: /dapp/tools/localnet
[localnet]: ../tools/localnet.mdx


## RPC Endpoints

Expand Down
101 changes: 11 additions & 90 deletions docs/dapp/emerald/writing-dapps-on-emerald.mdx
View file
Open in desktop
aefhm marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -79,91 +79,12 @@ ParaTime.
[Emerald Mainnet]: ./network.mdx
[Emerald Testnet]: ./network.mdx

## Running a Private Oasis Network Locally
## Localnet

For convenient development and testing of your dApps the Oasis team prepared
the [ghcr.io/oasisprotocol/emerald-localnet][emerald-localnet] Docker image which brings you a complete Oasis
stack to your desktop. This network is isolated from the Mainnet or Testnet and
consists of:
For development and testing, you can run a local [instance][localnet] of the
entire Emerald stack.

- single Oasis validator node with 1-second block time and 30-second epoch,
- single Oasis client node,
- three compute nodes running Oasis Emerald,
- PostgreSQL instance,
- Oasis Web3 gateway with transaction indexer,
- helper script which populates initial test accounts for you.

To run the image, execute:

```sh
docker run -it -p8545:8545 -p8546:8546 ghcr.io/oasisprotocol/emerald-localnet
```

After a while, the tool will show you something like this:

```
emerald-localnet 2023-02-28-git84730b2 (oasis-core: 22.2.6, emerald-paratime: 10.0.0, oasis-web3-gateway: 3.2.0-git84730b2)

Starting oasis-net-runner with emerald...
Starting postgresql...
Starting oasis-web3-gateway...
Bootstrapping network and populating account(s) (this might take a minute)...

Available Accounts
==================
(0) 0x75eCF0d4496C2f10e4e9aF3D4d174576Ee9010E2 (100 ROSE)
(1) 0x903a7dce5a26a3f4DE2d157606c2191740Bc4BC9 (100 ROSE)
(2) 0xF149ad5CBFfD92ba84F5784106f6Cb071A32a1b8 (100 ROSE)
(3) 0x2315F40C1122400Df55483743B051D2997ef0a62 (100 ROSE)
(4) 0xf6FdcacbA93A428A07d27dacEf1fBF25E2C65B0F (100 ROSE)

Private Keys
==================
(0) 0x160f52faa5c0aecfa26c793424a04d53cbf23dcad5901ce15b50c2e85b9d6ca7
(1) 0x0ba685723b47d8e744b1b70a9bea9d4d968f60205385ae9de99865174c1af110
(2) 0xfa990cf0c22af455d2734c879a2a844ff99bd779b400bb0e2919758d1be284b5
(3) 0x3bf225ef73b1b56b03ceec8bb4dfb4830b662b073b312beb7e7fec3159b1bb4f
(4) 0xad0dd7ceb896fd5f5ddc76d56e54ee6d5c2a3ffeac7714d3ef544d3d6262512c

HD Wallet
==================
Mnemonic: bench remain brave curve frozen verify dream margin alarm world repair innocent
Base HD Path: m/44'/60'/0'/0/%d

WARNING: The chain is running in ephemeral mode. State will be lost after restart!

Listening on http://localhost:8545 and ws://localhost:8546
```

Those familiar with local dApp environments will find the output above similar
to `geth --dev` or `ganache-cli` commands or the `geth-dev-assistant` npm
package. [emerald-localnet] will spin up a private Oasis Network locally, generate
and populate test accounts and make the following Web3 endpoints available for
you to use:
- `http://localhost:8545`
- `ws://localhost:8546`

:::tip

If you prefer using the same mnemonics each time (e.g. for testing purposes)
or to populate just a single wallet, use `-to` flag and pass the mnemonics or
the wallet addresses. For example

```sh
docker run -it -p8545:8545 -p8546:8546 ghcr.io/oasisprotocol/emerald-localnet -to "bench remain brave curve frozen verify dream margin alarm world repair innocent"
docker run -it -p8545:8545 -p8546:8546 ghcr.io/oasisprotocol/emerald-localnet -to "0x75eCF0d4496C2f10e4e9aF3D4d174576Ee9010E2,0xbDA5747bFD65F08deb54cb465eB87D40e51B197E"
```

:::

:::danger

[emerald-localnet] runs in ephemeral mode. Any smart contract and wallet balance
will be lost after you quit the Docker container!

:::

[emerald-localnet]: https://github.com/oasisprotocol/oasis-web3-gateway/pkgs/container/emerald-localnet
[localnet]: /dapp/tools/localnet

## Create dApp on Emerald with Hardhat

Expand Down Expand Up @@ -213,7 +134,7 @@ ETH and registers them to the [ethers.js] instance used in the tests.
Next, let's look at how to configure Hardhat for Emerald. For convenience, we
assign the `PRIVATE_KEY` environment variable a hex-encoded private key of your
Emerald wallet containing tokens to pay for gas fees. If you are running
[emerald-localnet], use any of the five generated private keys.
[localnet], use any of the five generated private keys.

```
export PRIVATE_KEY="YOUR_0x_EMERALD_PRIVATE_KEY"
Expand Down Expand Up @@ -245,7 +166,7 @@ networks: {

Next, we increase the default timeout for mocha tests from 20 seconds to 60
seconds. This step is not needed, if you will test your contracts solely on
[emerald-localnet], but is required for Testnet to avoid timeouts. Append the
[localnet], but is required for Testnet to avoid timeouts. Append the
following block to the `config` object:

```
Expand All @@ -258,14 +179,14 @@ mocha: {

`geth --dev` and `ganache-cli` tools use a so-called "instant mining" mode.
In this mode, a new block is mined immediately when a new transaction occurs in
the mempool. Neither Oasis Mainnet and Testnet Networks nor [emerald-localnet]
the mempool. Neither Oasis Mainnet and Testnet Networks nor [localnet]
support such mode and the new block will always be mined at least after the 1
second block time elapsed.

:::

Now deploy the contract to the local [emerald-localnet] Docker container by
selecting the `emerald_local` network we configured above and run the tests:
Now deploy the contract to the [localnet] Docker container by selecting the
`emerald_local` network we configured above and run the tests:

```
$ npx hardhat run scripts/deploy.ts --network emerald_local
Expand Down Expand Up @@ -336,8 +257,8 @@ transactions.

If you haven't done it yet, first [install the MetaMask extension for your
browser][metamask]. Import your wallet and configure Emerald Testnet and
Mainnet Networks. If you wish to connect to [emerald-localnet] container, configure
the local network as well.
Mainnet Networks. If you wish to connect to the Emerald [localnet] container,
configure the local network as well.

When you open Remix for the first time, it automatically creates an example
project. Let's open one of the contracts and compile it in the "Solidity
Expand Down
11 changes: 0 additions & 11 deletions docs/dapp/tools/README.md
View file
Open in desktop
aefhm marked this conversation as resolved.
Outdated Show resolved Hide resolved

This file was deleted.

24 changes: 24 additions & 0 deletions docs/dapp/tools/README.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
import DocCardList from '@theme/DocCardList';
import {findSidebarItem} from '@site/src/sidebarUtils';

# Tools & Services

Oasis integrates with a number of services and provides tooling support for
developers using [Remix] (*unencrypted transactions only*), [Sourcify],
[Docker images][localnet], [Band], and more. Please reach out to us on
[Discord][discord] if you are using a tool that has problems integrating with
Oasis.

[Remix]: https://remix.run/docs/en/main
[Sourcify]: /dapp/sapphire/verification
[localnet]: /dapp/tools/localnet
[Band]: /dapp/tools/band
[discord]: https://oasis.io/discord

## See also

<DocCardList items={[
findSidebarItem('/dapp/sapphire/verification'),
findSidebarItem('/dapp/tools/localnet'),
findSidebarItem('/dapp/tools/band'),
]} />
162 changes: 162 additions & 0 deletions docs/dapp/tools/localnet.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Localnet

For convenient development and testing of your dApps the Oasis team prepared
both [ghcr.io/oasisprotocol/sapphire-localnet][sapphire-localnet] and
[ghcr.io/oasisprotocol/emerald-localnet][emerald-localnet] Docker images.
They will bring you a complete Oasis network stack to your desktop. The
aefhm marked this conversation as resolved.
Show resolved Hide resolved
Localnet Sapphire instance **mimics confidential transactions**, but it does
not run in a trusted execution environment nor does it require Intel's SGX on
your computer. The network is isolated from the Mainnet or Testnet and consists
of a:

- single Oasis validator node with 1-second block time and 30-second epoch,
- single Oasis client node,
- single compute node running Oasis Sapphire or Emerald,
- single key manager node,
- PostgreSQL instance,
- Oasis Web3 gateway with transaction indexer and enabled Oasis RPCs,
- helper script which populates the account(s) for you.

:::note Hardware requirements

You will need at least 16GB of RAM to run the Docker images in addition to your
machine's OS.

:::

To run the image, execute:

<Tabs>
<TabItem value="Sapphire">

```sh
docker run -it -p8544-8546:8544-8546 ghcr.io/oasisprotocol/sapphire-localnet
```

</TabItem>
<TabItem value="Emerald">

```sh
docker run -it -p8544-8546:8544-8546 ghcr.io/oasisprotocol/emerald-localnet
```

</TabItem>
</Tabs>

After a while, running the `sapphire-localnet` will show you something like:

```
sapphire-localnet 2024-05-28-git37b7166 (oasis-core: 24.0-gitfb49717, sapphire-paratime: 0.7.3-testnet, oasis-web3-gateway: 5.1.0)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think devs need duplicated info for Emerald.


* Starting oasis-net-runner with sapphire...
* Waiting for Postgres to start...
* Waiting for Oasis node to start.....
* Starting oasis-web3-gateway...
* Bootstrapping network (this might take a minute)...
* Waiting for key manager......
* Populating accounts...

Available Accounts
==================
(0) 0x41b0C13e747F8Cb1c4E980712504437cb1792327 (10000 TEST)
(1) 0xa521f94f8a38b1d027D526017EB229327B9D6cA0 (10000 TEST)
(2) 0x1e0f8369215D6C5Af5E14eD6A0D6ae7372776A79 (10000 TEST)
(3) 0xB60cA28B491747a27C057AdBF3E71F3CCC52332C (10000 TEST)
(4) 0x88D7d924e521a6d07008a373D5b33281148ffEDc (10000 TEST)

Private Keys
==================
(0) 0x617346c545d62b8213ea907acf1b570a7405683e2c6dcaf963fc21fd677e0c56
(1) 0xf82d6e09208b0bd44a397f7e73b05c564e6c9f70b151ee7677e2bb8d6ce5d882
(2) 0xeb2f21d20086f3dd6bfe7184dad1cb8b0fb802f27b1334e836a19eda0a43a1c2
(3) 0x82b0203d6063992b1052004b90411c45d4f3afab696346f006e74c6abd8f855e
(4) 0x7179c6e1add3a2993822653b9c98fe606f47fb6d4c0d0d81b31b067cf6bb5f83

HD Wallet
==================
Mnemonic: coach genre beach child crunch champion tell adult critic peace canoe stable
Base HD Path: m/44'/60'/0'/0/%d

WARNING: The chain is running in ephemeral mode. State will be lost after restart!

* Listening on http://localhost:8545 and ws://localhost:8546. Chain ID: 0x5afd
* Container start-up took 66 seconds, node log level is set to warn.
```

Those familiar with local dApp environments will find the output above similar
to `geth --dev` or `ganache-cli` commands or the `geth-dev-assistant` npm
package. The [sapphire-localnet] will spin up a private Oasis Network locally,
generate and populate test accounts and make the following Web3 endpoints
available for you to use:

- `http://localhost:8545`
- `ws://localhost:8546`

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Additionally, the [Oasis GRPC](https://github.com/oasisprotocol/oasis-core/blob/master/docs/oasis-node/rpc.md) endpoint is exposed on:
- `http://localhost:8544`

:::tip

If you prefer using the same mnemonics each time (e.g. for testing purposes)
or to populate just a single account, use `-to` flag and pass the mnemonics or
the wallet addresses. By passing the `-test-mnemonic` flag you can fund the
standard test accounts provided by the `hardhat node` commmand and that are
typically used for solidity unit tests.

aefhm marked this conversation as resolved.
Show resolved Hide resolved

<Tabs>
<TabItem value="Sapphire">

```sh
docker run -it -p8544-8546:8544-8546 ghcr.io/oasisprotocol/sapphire-localnet -to "bench remain brave curve frozen verify dream margin alarm world repair innocent" -n3
docker run -it -p8544-8546:8544-8546 ghcr.io/oasisprotocol/sapphire-localnet -to "0x75eCF0d4496C2f10e4e9aF3D4d174576Ee9010E2,0xbDA5747bFD65F08deb54cb465eB87D40e51B197E"
docker run -it -p8544-8546:8544-8546 ghcr.io/oasisprotocol/sapphire-localnet -test-mnemonic
```

</TabItem>
<TabItem value="Emerald">

```sh
docker run -it -p8544-8546:8544-8546 ghcr.io/oasisprotocol/emerald-localnet -to "bench remain brave curve frozen verify dream margin alarm world repair innocent" -n3
docker run -it -p8544-8546:8544-8546 ghcr.io/oasisprotocol/emerald-localnet -to "0x75eCF0d4496C2f10e4e9aF3D4d174576Ee9010E2,0xbDA5747bFD65F08deb54cb465eB87D40e51B197E"
docker run -it -p8544-8546:8544-8546 ghcr.io/oasisprotocol/emerald-localnet -test-mnemonic
```

</TabItem>
</Tabs>

:::

:::note Running on Apple M chips

There is currently no `arm64` build available for M Macs, so you will need to
force the docker image to use the `linux/x86_64` platform, like this:

<Tabs>
<TabItem value="Sapphire">

```sh
docker run -it -p8544-8546:8544-8546 --platform linux/x86_64 ghcr.io/oasisprotocol/sapphire-localnet
```

</TabItem>
<TabItem value="Emerald">

```sh
docker run -it -p8544-8546:8544-8546 --platform linux/x86_64 ghcr.io/oasisprotocol/emerald-localnet
```

</TabItem>
</Tabs>

:::

:::danger

[sapphire-localnet] and [emerald-localnet] run in ephemeral mode. Any smart
contract and wallet balance will be lost after you quit the Docker container!

:::

[sapphire-localnet]: https://github.com/oasisprotocol/oasis-web3-gateway/pkgs/container/sapphire-localnet
[emerald-localnet]: https://github.com/oasisprotocol/oasis-web3-gateway/pkgs/container/emerald-localnet
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please also add a section on how to run Localnet with github actions. For example:

  jobs:
    services:
      sapphire-localnet-ci:
        image: ghcr.io/oasisprotocol/sapphire-localnet
        ports:
          - 8544:8544
          - 8545:8545
          - 8546:8546
        env:
          OASIS_DEPOSIT_BINARY: /oasis-deposit -n 2
        options: >-
          --rm
          --health-cmd="test -f /CONTAINER_READY"
          --health-start-period=90s

1 change: 1 addition & 0 deletions sidebarDapp.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,7 @@ export const sidebarDapp: SidebarsConfig = {
},
items: [
'dapp/tools/band',
'dapp/tools/localnet',
],
},
],
Expand Down