TezEdge

The purpose of this project is to implement a secure, trustworthy and open-source Tezos node in Rust.

In addition to implementing a new node, the project seeks to maintain and improve the Tezos ecosystem wherever possible.

Table of Contents

• Build status
• Quick demo
  • Prerequisites
  • Run demo
• Documentation
• How to build
  • Supported OS distributions
  • Prerequisites installation
  • Build from source code
• How to run
  • From source with cargo run
  • Using simplified script run.sh
  • Run docker image
  • Graceful shutdown
• How to use
  • Call RPC
  • Baking
  • Prearranged-docker-compose-files
    • Mainnet - node + explorer
    • Mainnet - node + explorer + debugger (eBPF)
    • Mainnet - nodes with irmin vs memory storage + explorer

Build status

CI / branch	master	develop
GitHub Actions
Drone

Quick demo

This demo launches two items:

• The TezEdge node (p2p application), which connects to the Tezos Mainnet network.
• The TezEdge explorer (web application), which connects to the TezEdge node and can be accessed from a browser to see what is going on inside the TezEdge node

Prerequisites

If you want to run this demo, you need to first install the following:

• Git (client)
• Docker

Run demo

1. Download the TezEdge source code

   # Open shell and type this code into the command line and then press Enter:
   git clone https://github.com/tezedge/tezedge
   cd tezedge
   

2. Run docker (compose)

   # Open shell and type this code into the command line and then press Enter:
   docker-compose pull
   docker-compose up
   

   
3. Open your web browser by entering this address into your browser's URL bar: http://localhost:8080

Docker for Windows

The images use the hostname localhost to access running services. When using docker for windows, please check:

docker-machine ip

and make sure that port forwarding is set up correctly for docker or use docker-machine resolved ip instead of http://localhost:8080

TCP ports (<host_port>:<docker_port>):
    - "80:80"
    - "4927:4927"
    - "18732:18732"
    - "19732:9732"

Documentation

Detailed project's documentation can be found here Documentation

How to build

Supported OS distributions

We are linking Rust code with a pre-compiled Tezos shared library. For your convenience, we have created pre-compiled binary files for most of the more popular Linux distributions:

If you are missing support for your favorite Linux distribution, please submit a request with the tezos-opam-builder project.

To build from source please follow these instructions.

Prerequisites installation

If you want to build from source code, you need to install this before:

1. Install Git (client)
2. Install Rust command (We recommend installing Rust through rustup.)

   # Run the following in your terminal, then follow the onscreen instructions.
   curl https://sh.rustup.rs -sSf | sh
   

3. Install Rust toolchain (Our releases are built with 1.58.1.)

   rustup toolchain install 1.58.1
   rustup default 1.58.1
   

4. Install required OS libs
   • OpenSSL and Zlib

   sudo apt install openssl libssl-dev zlib1g
   

   • Sodiumoxide package:

   sudo apt install pkg-config libsodium-dev
   

   • RocksDB package:

   sudo apt install clang libclang-dev llvm llvm-dev linux-kernel-headers libev-dev
   

   • In macOS, using Homebrew:

   brew install pkg-config gmp libev libsodium hidapi libffi
   

   • Sandbox/wallet requirements:

   sudo apt install libhidapi-dev
   

Build from source code

1. Download TezEdge source code

   # Open shell, type this code into the command line and then press Enter:
   git clone https://github.com/tezedge/tezedge
   cd tezedge
   

2. Build

   export SODIUM_USE_PKG_CONFIG=1
   cargo build --release
   

   The node can built through the cargo build or cargo build --release, be aware, release build can take much longer to compile.

3. Test

   export SODIUM_USE_PKG_CONFIG=1
   export DYLD_LIBRARY_PATH=$(pwd)/tezos/sys/lib_tezos/artifacts # currently needed for macOS
   cargo test --release
   

How to run

Running node with cargo run

To run the node manually, you need to first build it from the source code. When put together, the node can be run, for example, like this:

cargo build --release
cargo run --release --bin light-node -- --config-file ./light_node/etc/tezedge/tezedge.config --protocol-runner=./target/release/protocol-runner --network=mainnet

All parameters can also be provided as command line arguments in the same format as in the config file, in which case they have a higher priority than the ones in the config file. For example, we can use the default config and change the log file path:

cargo build --release
cargo run --release --bin light-node -- --config-file ./light_node/etc/tezedge/tezedge.config --log-file /tmp/logs/tezdge.log --protocol-runner=./target/release/protocol-runner --network=mainnet

Full description of all arguments is in the light_node README file.

Running node with run.sh script

For Linux systems, we have prepared a convenience script to run the node. It will automatically set all the necessary environmnent variables and then build and run the TezEdge node. All arguments can be provided to the run.sh script in the same manner as described in the previous section.

To run the node in release mode, execute the following:

KEEP_DATA - this flag controls, if all the target directories should be cleaned on the startup, 1 means do not clean

KEEP_DATA=1 ./run.sh release --network=mainnet

The following command will execute the node in debug node:

KEEP_DATA=1 ./run.sh node --network=mainnet

To run the node in debug mode with an address sanitizer, execute the following:

KEEP_DATA=1 ./run.sh node-saddr --network=mainnet

You can use the docker version to build and run node from the actual source code.

• you can experiment and change source code without installing all requirements, just docker.
• you can build/run node on Windows/OSX
• this is just for development, because docker is based on full Linux (pre-build docker images are Distroless)

If you do not need to build from souce code, just use our pre-build docker images

./run.sh docker --network=mainnet

Listening for updates. Node emits statistics on the websocket server, which can be changed by --websocket-address argument, for example:

KEEP_DATA=1  ./run.sh node --network=mainnet --websocket-address 0.0.0.0:12345

Full description of all arguments is in the light_node README file.

Running node from binaries

Note: This cmd runs from the main git sources directory

LD_LIBRARY_PATH=./tezos/sys/lib_tezos/artifacts ./target/release/light-node \
    --network "mainnet" \
    --identity-file "/tmp/data-dir-mainnet/identity.json" \
    --identity-expected-pow 26.0 \
    --tezos-data-dir "/tmp/data-dir-mainnet/context_data" \
    --bootstrap-db-path "/tmp/data-dir-mainnet/tezedge_data" \
    --peer-thresh-low 30 --peer-thresh-high 45 \
    --protocol-runner "./target/release/protocol-runner" \
    --init-sapling-spend-params-file "./tezos/sys/lib_tezos/artifacts/sapling-spend.params" \
    --init-sapling-output-params-file "./tezos/sys/lib_tezos/artifacts/sapling-output.params" \
    --p2p-port 9732 --rpc-port 18732 \
    --tokio-threads 0 \
    --ocaml-log-enabled false \
    --tezos-context-storage=irmin \
    --log terminal \
    --log file \
    --log-level info \
    --log-format simple

Running node from docker images

We provide automatically built images that can be downloaded from our Docker hub. For instance, this can be useful when you want to run the TezEdge node in your test CI pipelines.

Images (distroless)

• tezedge/tezedge:vX.Y.Z - last versioned stable released version
• tezedge/tezedge:latest-release - last stable released version
• tezedge/tezedge:latest - actual stable development version
• tezedge/tezedge:sandbox-vX.Y.Z - last versioned stable released version for sandbox launcher
• tezedge/tezedge:sandbox-latest-release - last stable released version for sandbox launcher
• tezedge/tezedge:sandbox-latest - last stable released version for sandbox launcher

More about building TezEdge docker images see here.

Run image

docker run -i -p 9732:9732 -p 18732:18732 -p 4927:4927 -t tezedge/tezedge:v3.1.1 --network=mainnet --p2p-port 9732 --rpc-port 18732

A full description of all arguments can be found in the light_node README file.

Shutdown running node gracefully

Just press Ctrl-c, works for e.g. cargo run or run.sh script.

Or you can send a signal to a running process, the dedicated signal is SIGINT, e.g.:

kill -s SIGINT <PID-of-running-process-with-light-node>

How to use

Example of how to call the RPC

Open shell, type this code into the command line and then press Enter:

curl localhost:18732/chains/main/blocks/head

For a more detailed description of the RPCs, see the shell and the protocol endpoints.

Baking

• Using Tezedge external baker
• Using Tezedge embedded baker
• Baking in the Ithaca testnet
• Baking in the mainnet

Prearranged docker-compose files

Mainnet - light-node + tezedge explorer

Last released version:

docker-compose -f docker-compose.yml pull
docker-compose -f docker-compose.yml up

(optional) Environment configuration:

# (default: irmin) - choose context implementation, possible values: [irmin, tezedge, both]
TEZOS_CONTEXT_STORAGE=<possible-value>

# explorer accesses node/debugger on 'localhost' by default, you can change it like,
NODE_HOSTNAME_OR_IP=<hostname-or-ip>

e.g.:
TEZOS_CONTEXT_STORAGE=irmin NODE_HOSTNAME_OR_IP=123.123.123.123 docker-compose -f docker-compose.yml up

Mainnet - light-node + tezedge explorer + tezedge debugger

Last released version with TezEdge Debugger with integrated eBPF

This requires Linux kernel at least 5.11

docker-compose -f docker-compose.debug.yml pull
docker-compose -f docker-compose.debug.yml up

(optional) Environment configuration:

# (default: irmin) - choose context implementation, possible values: [irmin, tezedge, both]
TEZOS_CONTEXT_STORAGE=<possible-value>

# explorer accesses node/debugger on 'localhost' by default, you can change it like,
NODE_HOSTNAME_OR_IP=<hostname-or-ip>

e.g.:
TEZOS_CONTEXT_STORAGE=irmin NODE_HOSTNAME_OR_IP=123.123.123.123 docker-compose -f docker-compose.debug.yml up

Mainnet - light-node with irmin context + light-node with memory context + light-node with persistent context + tezedge-explorer

This runs two explorers:

• http://localhost:8181 - with Irmin storage
• http://localhost:8282 - with Memory storage
• http://localhost:8383 - with Persistent storage

# Irmin context
docker-compose -f docker-compose.storage.irmin.yml pull
docker-compose -f docker-compose.storage.irmin.yml up

# TezEdge in-memory context
docker-compose -f docker-compose.storage.memory.yml pull
docker-compose -f docker-compose.storage.memory.yml up

# TezEdge persistent context
docker-compose -f docker-compose.storage.persistent.yml pull
docker-compose -f docker-compose.storage.persistent.yml up

(optional) Environment configuration:

# explorer accesses node on 'localhost' by default, you can change it like,
NODE_HOSTNAME_OR_IP=<hostname-or-ip>