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,
  • Oasis Nexus indexer and Explorer frontend,
  • 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-8548:8544-8548 ghcr.io/oasisprotocol/sapphire-localnet

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

sapphire-localnet 2024-11-29-gite748a1a (oasis-core: 24.3, sapphire-paratime: 0.9.0-testnet, 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......
 * Creating database 'nexus'
 * Waiting for Nexus to start.
 * Waiting for Explorer to start.
 * 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.
 * Nexus API listening on http://localhost:8547.
 * Localnet Explorer available at http://localhost:8548.
 * Container start-up took 69 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

The Oasis GRPC endpoint is exposed on:

  • http://localhost:8544

In addition to these, the Nexus API is available on http://localhost:8547 and an Explorer instance on http://localhost:8548. These can be disabled by passing --no-explorer or setting the environment variable OASIS_DOCKER_START_EXPLORER to no.

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-8548:8544-8548 ghcr.io/oasisprotocol/sapphire-localnet -to "bench remain brave curve frozen verify dream margin alarm world repair innocent" -n3
docker run -it -p8544-8548:8544-8548 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-8548:8544-8548 --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 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_DOCKER_START_EXPLORER: no
        options: >-
          --rm
          --health-cmd="test -f /CONTAINER_READY"
          --health-start-period=90s