From 80db33bdb4ace6956f11e7fcdaa09aa8dc85ec83 Mon Sep 17 00:00:00 2001 From: Xi Zhang Date: Tue, 8 Oct 2024 13:17:44 +0300 Subject: [PATCH] docs: Move localnet development to separate page --- docs/dapp/emerald/network.mdx | 2 +- .../dapp/emerald/writing-dapps-on-emerald.mdx | 101 ++--------- docs/dapp/tools/README.md | 11 -- docs/dapp/tools/README.mdx | 24 +++ docs/dapp/tools/localnet.mdx | 162 ++++++++++++++++++ sidebarDapp.ts | 1 + 6 files changed, 199 insertions(+), 102 deletions(-) delete mode 100644 docs/dapp/tools/README.md create mode 100644 docs/dapp/tools/README.mdx create mode 100644 docs/dapp/tools/localnet.mdx diff --git a/docs/dapp/emerald/network.mdx b/docs/dapp/emerald/network.mdx index 032bc783ea..2534065529 100644 --- a/docs/dapp/emerald/network.mdx +++ b/docs/dapp/emerald/network.mdx @@ -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 ## RPC Endpoints diff --git a/docs/dapp/emerald/writing-dapps-on-emerald.mdx b/docs/dapp/emerald/writing-dapps-on-emerald.mdx index be7896e490..173b0cf5f4 100644 --- a/docs/dapp/emerald/writing-dapps-on-emerald.mdx +++ b/docs/dapp/emerald/writing-dapps-on-emerald.mdx @@ -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 @@ -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" @@ -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: ``` @@ -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 @@ -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 diff --git a/docs/dapp/tools/README.md b/docs/dapp/tools/README.md deleted file mode 100644 index 2f2b5ebbbc..0000000000 --- a/docs/dapp/tools/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# Tools & Services - -Oasis integrates with a number of services and provides tooling support for -developers using [Remix] (*unencrypted transactions only*), [Sourcify], -[Docker][localnet], 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/sapphire/guide#running-a-private-oasis-network-locally -[discord]: https://oasis.io/discord diff --git a/docs/dapp/tools/README.mdx b/docs/dapp/tools/README.mdx new file mode 100644 index 0000000000..bf6c8b308a --- /dev/null +++ b/docs/dapp/tools/README.mdx @@ -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 + + \ No newline at end of file diff --git a/docs/dapp/tools/localnet.mdx b/docs/dapp/tools/localnet.mdx new file mode 100644 index 0000000000..3eae6dc1b3 --- /dev/null +++ b/docs/dapp/tools/localnet.mdx @@ -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 +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: + + + + +```sh +docker run -it -p8544-8546:8544-8546 ghcr.io/oasisprotocol/sapphire-localnet +``` + + + + +```sh +docker run -it -p8544-8546:8544-8546 ghcr.io/oasisprotocol/emerald-localnet +``` + + + + +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) + + * 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` + +:::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. + + + + + +```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 +``` + + + + +```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 +``` + + + + +::: + +:::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: + + + + +```sh +docker run -it -p8544-8546:8544-8546 --platform linux/x86_64 ghcr.io/oasisprotocol/sapphire-localnet +``` + + + + +```sh +docker run -it -p8544-8546:8544-8546 --platform linux/x86_64 ghcr.io/oasisprotocol/emerald-localnet +``` + + + + +::: + +:::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 diff --git a/sidebarDapp.ts b/sidebarDapp.ts index 0d7a1ef282..7f8b137e19 100644 --- a/sidebarDapp.ts +++ b/sidebarDapp.ts @@ -115,6 +115,7 @@ export const sidebarDapp: SidebarsConfig = { }, items: [ 'dapp/tools/band', + 'dapp/tools/localnet', ], }, ],