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..934650d548 100644 --- a/docs/dapp/emerald/writing-dapps-on-emerald.mdx +++ b/docs/dapp/emerald/writing-dapps-on-emerald.mdx @@ -79,91 +79,9 @@ ParaTime. [Emerald Mainnet]: ./network.mdx [Emerald Testnet]: ./network.mdx -## Running a Private Oasis Network Locally +#### For development and testing, you can run a local [instance][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: - -- 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 diff --git a/docs/dapp/tools/README.md b/docs/dapp/tools/README.md index 2f2b5ebbbc..8cfb40cded 100644 --- a/docs/dapp/tools/README.md +++ b/docs/dapp/tools/README.md @@ -7,5 +7,5 @@ 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 +[localnet]: /dapp/tools/localnet [discord]: https://oasis.io/discord diff --git a/docs/dapp/tools/localnet.md b/docs/dapp/tools/localnet.md new file mode 100644 index 0000000000..04ca4d9370 --- /dev/null +++ b/docs/dapp/tools/localnet.md @@ -0,0 +1,118 @@ +# Local Development + +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, +- 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: You will need at least 16GB of memory.* + +To run the image, execute: + +```sh +docker run -it -p8545:8545 -p8546:8546 ghcr.io/oasisprotocol/sapphire-localnet +``` + +or substitute "sapphire" for "emerald" + +```sh +docker run -it -p8545:8545 -p8546:8546 ghcr.io/oasisprotocol/emerald-localnet +``` + +After a while, the tool will show you something like this: + +``` +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. [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 -p8545:8545 -p8546:8546 ghcr.io/oasisprotocol/sapphire-localnet -to "bench remain brave curve frozen verify dream margin alarm world repair innocent" -n3 +docker run -it -p8545:8545 -p8546:8546 ghcr.io/oasisprotocol/sapphire-localnet -to "0x75eCF0d4496C2f10e4e9aF3D4d174576Ee9010E2,0xbDA5747bFD65F08deb54cb465eB87D40e51B197E" +docker run -it -p8545:8545 -p8546:8546 ghcr.io/oasisprotocol/sapphire-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 -p8545:8545 -p8546:8546 --platform linux/x86_64 ghcr.io/oasisprotocol/sapphire-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! + +::: + +[emerald-localnet]: https://github.com/oasisprotocol/oasis-web3-gateway/pkgs/container/emerald-localnet +[sapphire-localnet]: https://github.com/oasisprotocol/oasis-web3-gateway/pkgs/container/sapphire-localnet \ No newline at end of file diff --git a/sidebarDapp.ts b/sidebarDapp.ts index 3b62b9a88f..765122e833 100644 --- a/sidebarDapp.ts +++ b/sidebarDapp.ts @@ -93,6 +93,7 @@ export const sidebarDapp: SidebarsConfig = { }, items: [ 'dapp/tools/band', + 'dapp/tools/localnet', ], }, ],