Skip to main content

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.
Hardware requirements

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:

docker run -it -p8544-8546:8544-8546 ghcr.io/oasisprotocol/sapphire-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.

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"
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:

docker run -it -p8544-8546:8544-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!

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.

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