Localnet
For convenient development and testing of your dApps the Oasis team prepared both ghcr.io/oasisprotocol/sapphire-localnet and ghcr.io/oasisprotocol/emerald-localnet Docker images. They will bring you a complete Oasis network stack to your workspace. 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.
You will need at least 16GB of RAM to run the Docker images in addition to your machine's OS.
Installation and Setup
To run the image, execute:
- Sapphire
- Emerald
docker run -it -p8544-8546:8544-8546 ghcr.io/oasisprotocol/sapphire-localnet
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-10-03-gitbad082f (oasis-core: 24.2, sapphire-paratime: 0.8.2, oasis-web3-gateway: 5.1.0)
* No ROFLs detected.
* Starting oasis-net-runner with sapphire...
* Waiting for Postgres to start.
* Waiting for Oasis node to start........
* Waiting for Envoy proxy to start.
* Starting oasis-web3-gateway...
* Bootstrapping network (this might take a minute)...
* Waiting for key manager......
* Populating accounts...
Available Accounts
==================
(0) 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 (10000 TEST)
(1) 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 (10000 TEST)
(2) 0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC (10000 TEST)
(3) 0x90F79bf6EB2c4f870365E785982E1f101E93b906 (10000 TEST)
(4) 0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65 (10000 TEST)
Private Keys
==================
(0) 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
(1) 0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d
(2) 0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a
(3) 0x7c852118294e51e653712a81e05800f419141751be58f605c371e15141b007a6
(4) 0x47e179ec197488593b187f80a00eb0da91f1b9d0b13f8733639f19c30a34926a
HD Wallet
==================
Mnemonic: test test test test test test test test test test test junk
Base HD Path: m/44'/60'/0'/0/%d
WARNING: The chain is running in ephemeral mode. State will be lost after restart!
* GRPC listening on http://localhost:8544.
* Web3 RPC listening on http://localhost:8545 and ws://localhost:8546. Chain ID: 0x5afd.
* Container start-up took 313 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
Additionally, the Oasis GRPC endpoint is exposed on:
http://localhost:8544
By default, the Localnet docker image will populate the first five accounts
derived from the standard test mnemonic, compatible with hardhat node
.
These accounts are typically used for Solidity unit tests. If you prefer
populating different accounts, use -to
flag and pass the mnemonics seed
phrases or wallet addresses. Use the -n
parameter to define the number of
derived addresses to fund.
- Sapphire
- Emerald
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/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"
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:
- Sapphire
- Emerald
docker run -it -p8544-8546:8544-8546 --platform linux/x86_64 ghcr.io/oasisprotocol/sapphire-localnet
docker run -it -p8544-8546:8544-8546 --platform linux/x86_64 ghcr.io/oasisprotocol/emerald-localnet
sapphire-localnet and emerald-localnet run in ephemeral mode. Any smart contract and wallet balance will be lost after you quit the Docker container!
GitHub Actions
You can easily integrate localnet into your CI/CD workflow. Use the example GitHub Action configuration to start a Sapphire or Emerald stack, fund the first two test accounts, and expose the necessary ports for testing.
- Sapphire
- Emerald
jobs:
example-test:
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
jobs:
example-test:
services:
emerald-localnet-ci:
image: ghcr.io/oasisprotocol/emerald-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