Archived: Run a Local Development Network
Basic understanding of Linux shell and compilation is necessary to follow this tutorial. Linux Fundamentals may help.
Overview
In this tutorial, we’re going to set up a development environment. We are going to deploy a full stack of the core blockchain and connect the Web UI to the blockchain. By the end of the tutorial, you will be able to:
- Send confidential Commands and Queries
- Get a ready-to-hack version of Phala Network for building your confidential DApps
A full Phala Network stack has three components, with an optional Javascript SDK. The core components are available at Phala-Network/phala-blockchain:
phala-node
: The Substrate blockchain nodepRuntime
: The TEE runtime. Contracts run inpRuntime
pherry
: The Substrate-TEE bridge relayer. Connects the blockchain andpRuntime

(Phala architecture overview)
The Javascript SDK is at Phala-Network/js-sdk. The Web UI based on our SDK needs to connect to both the blockchain and the pRuntime
to send Commands and Queries.
Environment
The development environment of Phala Network requires Linux because it relies on Linux Intel SGX SDK. Virtual machines should generally work. Phala Network does work on Windows with some configuration changes, but does not work on macOS natively (sorry, Mac lovers).
In this tutorial, we assume the operating system is Ubuntu 20.04. Though not tested yet, it should work with Ubuntu 18.04 out-of-box. Other Linux distributions should also work, but the instructions or commands may vary. It’s required to have at least 4 cores and 8GB RAM to build the project including the core blockchain and the Web UI. Less than 4GB RAM may fail to build the Web UI.
Follow the commands below to prepare the environment. Some can be skipped if already installed.
Ubuntu
Install dependencies via script for Ubuntu
- Run the script to install and check required dependencies for Phala
Download the script (successfully tested on Ubuntu 20.04):
wget https://raw.githubusercontent.com/hauni97/phala_quick_run/main/phala_quick_install.sh
Make it executable:
chmod +x phala_quick_install.sh
Excute it to automate the next three manual steps to get the environment ready:
sudo ./phala_quick_install.sh
Expand for details on manual system dependency installation for Ubuntu
Install the system level dependencies manually for Ubuntu
sudo apt update
sudo apt install -y build-essential pkg-config ca-certificates git autoconf libtool libssl-dev libclang-10-dev clang-10
Ensure clang
exists in your $PATH by executing
which clang
# /usr/bin/clang
# by default, the clang executable is installed as "clang-10"
# if you got `clang not found`, you need to link the clang-10 to clang
sudo ln -sf /usr/bin/clang-10 /usr/bin/clang
Notes on LLVM: We require at least LLVM-9, but higher versions are also supported. An older version like LLVM 6.0 breaks the core blockchain compilation.
Install Rust. Please choose the default toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
Install Intel SGX SDK
wget https://download.01.org/intel-sgx/sgx-linux/2.15/distro/ubuntu20.04-server/sgx_linux_x64_sdk_2.15.100.3.bin
chmod +x sgx_linux_x64_sdk_2.15.100.3.bin
echo -e 'no\n/opt/intel' | sudo ./sgx_linux_x64_sdk_2.15.100.3.bin
source /opt/intel/sgxsdk/environment
You can add
source /opt/sgxsdk/environment
to your~/.bashrc
(or~/.zshrc
, depends on which shell you’re using).
Install Node.js (>= v12) & yarn
curl -sL https://deb.nodesource.com/setup_current.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo npm install -g yarn
Fedora
Install the system level dependencies for Fedora
sudo dnf update
sudo dnf install make automake gcc gcc-c++ kernel-devel ocaml autoconf automake libtool wget python openssl-devel git cmake perl pkg-config curl
Ensure clang
exists in your $PATH by executing
which clang
# /usr/bin/clang
# by default, the clang executable is installed as "clang-10"
# if you got `clang not found`, you need to link the clang-10 to clang
sudo ln -sf /usr/bin/clang-10 /usr/bin/clang
Notes on LLVM: We require at least LLVM-9, but higher versions are also supported. An older version like LLVM 6.0 breaks the core blockchain compilation.
Install Rust. Please choose the default toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
Install Intel SGX SDK
wget https://download.01.org/intel-sgx/sgx-linux/2.14/distro/fedora31-server/sgx_linux_x64_sdk_2.14.100.2.bin
chmod +x sgx_linux_x64_sdk_2.14.100.2.bin
echo -e 'no\n/opt/intel' | sudo ./sgx_linux_x64_sdk_2.14.100.2.bin
source /opt/intel/sgxsdk/environment
You can add
source /opt/sgxsdk/environment
to your~/.bashrc
(or~/.zshrc
, depends on which shell you’re using).
Install Node.js (>= v12) & yarn
curl -sL https://rpm.nodesource.com/setup_16.x | sudo -E bash -
sudo dnf install -y nodejs
sudo npm install -g yarn
Windows WSL
Instructions for (but not limited to) a relatively clean Windows11/WSL2 environment (Ubuntu 20.04LTS, and git correctly installed) are preceded by the mention “For WSL2”
Install WSL2 (Windows 10 version 2004 and higher for Build 19041 and higher or Windows 11) in PowerShell or Windows Command Prompt
wsl --install
Ubuntu is the OS installed by default. Restart your machine, and in Powershell set WSL 2 as your default by doing the following
wsl --set-default-version 2
Install the system level dependencies
For WSL2:
curl -fsSL https://deb.nodesource.com/setup_current.x | sudo -E bash -
sudo apt install ca-certificates
sudo apt update
sudo apt install -y build-essential pkg-config ca-certificates git autoconf libtool libssl-dev libclang-10-dev clang-10
Ensure clang
exists in your $PATH by executing
which clang
# /usr/bin/clang
# by default, the clang executable is installed as "clang-10"
# if you got `clang not found`, you need to link the clang-10 to clang
sudo ln -sf /usr/bin/clang-10 /usr/bin/clang
Notes on LLVM: We require at least LLVM-9, but higher versions are also supported. An older version like LLVM 6.0 breaks the core blockchain compilation.
Install Rust. Please choose the default toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
Install Intel SGX SDK
wget https://download.01.org/intel-sgx/sgx-linux/2.15/distro/ubuntu20.04-server/sgx_linux_x64_sdk_2.15.100.3.bin
chmod +x sgx_linux_x64_sdk_2.15.100.3.bin
echo -e 'no\n/opt/intel' | sudo ./sgx_linux_x64_sdk_2.15.100.3.bin
source /opt/intel/sgxsdk/environment
You can add
source /opt/sgxsdk/environment
to your~/.bashrc
(or~/.zshrc
, depends on which shell you’re using).
Install Node.js (>= v12) & yarn
curl -sL https://deb.nodesource.com/setup_current.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo npm install -g yarn
MacOS
Currently, Mac is not supported. However, if you wish to run a simulated Phala environment for this tutorial, you may create a Virtual Machine (VM) with OS Ubuntu 20.04. Furthermore, MacOS is a UNIX-based Operating System; you may easily use SSH to connect to your VM without additional tools. A free resource is Amazon Web Services AWS.
You can test the installation by running the following commands. The output should match the sample outputs, or with a slightly higher version.
rustup --version
# rustup 1.24.3 (ce5817a94 2021-05-31)
cargo --version
# cargo 1.55.0 (32da73ab1 2021-08-23)
echo $SGX_SDK
# /opt/intel/sgxsdk
# LLVM-9 or higher versions are fine
clang --version
# clang version 10.0.0-4ubuntu1
# Target: x86_64-pc-linux-gnu
# Thread model: posix
# InstalledDir: /usr/bin
node --version
# v16.10.0
yarn --version
# 1.22.15
Finally, let’s clone the code. Notice that the entire tutorial is on the encode-hackathon-2021
branch for the blockchain.
# Clone the core blockchain repo
git clone --recursive --branch encode-hackathon-2021 https://github.com/Phala-Network/phala-blockchain.git
# Clone the JS SDK repo
git clone https://github.com/Phala-Network/js-sdk
Build the Core Blockchain
Now we have both repos phala-blockchain
and js-sdk
in the working directory. Let’s start to build the core blockchain first.
# Build the core blockchain
cargo build --release
Finally you can proceed with pruntime:
# Build pRuntime (TEE Enclave)
cd ./standalone/pruntime/
SGX_MODE=SW make
The compilation takes from 20 mins to 60 mins depending on your internet connection and CPU performance. After building, you will get the three binary files:
./target/release/phala-node
: The Substrate node./target/release/pherry
: The Substrate-to-TEE bridge relayer./standalone/pruntime/bin/app
: The TEE worker
Notes on
SGX_MODE
The SGX SDK supports software simulation mode and hardware mode.
SGX_MODE=SW
enables the simulation mode. The software mode is for easy development, where the hardware enclave is not required. You can even run it on a virtual machine or a computer with an AMD CPU. However, only the hardware mode can guarantee the security and the confidentiality of the trusted execution. To enable the hardware mode, you have to install Intel SGX DCAP Driver and the platform software shipped with the driver, and passSGX_MODE=HW
to the toolchain.
The three core blockchain components work together to bring the full functionalities. Among them, phala-node
and pruntime
should be launched first, and pherry
follows:
# In terminal window 1: phala-node
./target/release/phala-node --dev --tmp
# In terminal window 2: pruntime
cd standalone/pruntime/bin
./app -c 0
cd ../../..
# In terminal window 3: pherry
./target/release/pherry --dev --no-wait
Once they are launched successfully, they should output logs. Notice that we pass the --dev
flag to phala-node
and pherry
to indicate we are in the development network. This is important since for now, smart contract functionalities are only enabled under development mode.
The three core blockchain components are connected via TCP (WebSocket and HTTP). Please ensure your system have the TCP ports not occupied by other programs. By default they use the following ports:
phala-node
- 9944: Substrate WebSocket RPC port
- 30333: Substrate P2P network port
pruntime
- 8000: HTTP Restful RPC port
pherry
doesn’t listen to any ports but connects to phala-node
’s WebSocket port and pruntime
’s HTTP RPC port. You can change the default ports of phala-node
and pherry
with command line arguments (check the latest argument list with --help
). And for pruntime
, just edit the Rocket.toml
config file under pruntime/bin
and restart it.
You can safely shut down the three programs by Ctrl + C. Since --tmp
is specified for phala-node
, no database will be left after you shut it down. So a fresh start every time you run it!
Build the Web UI
The Web UI frontend is developed with node.js
and managed by yarn
. It provides the frontend you need to interact with our GuessNumber
and BtcPriceBot
demo contracts. Just give it a try!
cd js-sdk/packages/example
# you need to set the `NEXT_PUBLIC_BASE_URL` to the port of `pruntime`
# and `NEXT_PUBLIC_WS_ENDPOINT` to `phala-node` ws port
cp .env .env.local
yarn
yarn dev
It may take a few minutes to download the dependencies and build the frontend. By default, the page is served at http://localhost:3000. So make sure the port 3000 is available. Then it should produce some logs like below:
ready - started server on 0.0.0.0:3000, url: http://localhost:3000
info - Loaded env from /home/user/phala-network/js-sdk/packages/example/.env.local
info - Loaded env from /home/user/phala-network/js-sdk/packages/example/.env
info - Using webpack 5. Reason: Enabled by default https://nextjs.org/docs/messages/webpack5
event - compiled successfully
Notes for Remote Access
In a case where you run your blockchain and WEB UI on your REMOTE_SERVER and try to access them elsewhere, you can forward the ports with
ssh
command. For example,ssh -N -f [email protected]_SERVER -L 3000:localhost:3000 -L 9944:localhost:9944 -L 8000:localhost:8000
This forwards all the necessary ports:
- 3000: HTTP port of Web UI
- 9944: Substrate WebSocket RPC port of
phala-node
- 8000: HTTP Restful RPC port of
pruntime
and you can visit the Web UI at http://localhost:3000.
The main page of Web UI looks like this:
To experience the demo contracts, you will need an account. For development, we recommend not to use your real Substrate account with funds. A good choice is for development to import Alice
to your Polkadot.js extension since she is the pre-defined root account and is allowed to invoke privileged operations. DO NOT transfer real funds to your Alice
account.
You can get the secret seed of Alice
with the following command
# in phala-blockchain folder
./target/release/phala-node key inspect //Alice
# Secret Key URI `//Alice` is account:
# Secret seed: 0xe5be9a5092b81bca64be81d212e7f2f9eba183bb7a90954f7b76361f6edb5c0a
# Public key (hex): 0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d
# Public key (SS58): 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
# Account ID: 0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d
# SS58 Address: 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
Then import the secret seed into your Polkadot.js extension
and paste the secret seed regardless of the mnemonic hint
Now you are good to go.
Play the GuessNumber
Authorization
Now let’s play with a contract. Recall the knowledge about Commands and Queries in previous chapter. The first thing our contract propose is to sign a certificate. Such a temporary certificate is used to encrypt all the Queries. While every time you try to send a Command, the Polkadot.js extension will ask for your signature (since Commands can change the state, it is more critical than Queries).
Don’t miss the prompt since there are not always pop-ups.
Play with it
By default, the random number is 0. Click Reset Number
, sign the Command, and start the game. If you log in as the root account or contract owner, there is a cheat button for you to peek at the secret. So no more spoiling, just play with it.
If you are curious about how this contract is implemented, the following chapter will walk you through it.
Conclusion
Congratulations! Finally, you have followed the tutorial to:
- Prepare a ready-to-hack development environment
- Download, build and started a full-stack development-mode Phala Network
- Connect to the network via the Web UI and try the DApps
Now you are familiar with building and running a development network. Hold tight! In the next chapter, we are going to build the first confidential contract together!
Join our Discord server and feel free to ask for help!