Skip to content
Ergo protocol description & reference client implementation
Scala TeX JavaScript Shell HTML Gnuplot Other
Branch: master
Clone or download
kushti Merge pull request #952 from ergoplatform/v3.1.3
Candidate for version 3.1.3
Latest commit 9a5a17f Oct 29, 2019


This repository contains the reference implementation of the Ergo Platform protocol, which is an alternative to the Bitcoin protocol.

Ergo Platform website:

Differences from Bitcoin


A White Paper with a brief description is available. A Yellow Paper with detailed specification is underway and will be available shortly. At the moment, there are drafts of the Yellow Paper available, and currently the reference implementation code should be considered as the specification.


You can check our Wiki page for node installation and configuration guide.

Also, reference with Node Configuration File wiki page for creating your own configuration file.

Build from sources

In order to build the Ergo node from sources you need JDK (>= 1.8) and SBT to be installed on your machine.

In order to simply get a single jar run: sbt assembly - assembly would appear in target/scala-2.12/ directory.

If you want to create a package for a specific platform with launching scripts the one of the following packager commands could be chosen (depending on desired system type you want to build for):

  • universal:packageBin - Generates a universal zip file
  • universal:packageZipTarball - Generates a universal tgz file
  • debian:packageBin - Generates a deb
  • docker:publishLocal - Builds a Docker image using the local Docker server
  • rpm:packageBin - Generates an rpm
  • universal:packageOsxDmg - Generates a DMG file with the same contents as the universal zip/tgz.
  • windows:packageBin - Generates an MSI

The final build command should look like: sbt <packager_command>, example: sbt universal:packageBin. A resulted package could be found in the target/scala-2.12/<platform_type> directory.

Running the node

The node could be started in a few different ways:

  • In case you have only a jar: java -jar /path/to/ergo-<version>.jar --<networkId> -c /path/to/local.conf
  • Using start script from sbt-native-packager: sh /path/to/bin/ergo --<networkId> -c /path/to/local.conf

Available networkId options: mainnet, testnet, devnet.


Node UI (graphical interface) could be accessed at <node_ip>:<api_port>/panel in your browser.

Docker Quick Start

Ergo has officially supported Docker package. To run last Ergo version in mainnet as a console application with logs printed to console:

sudo docker run --rm -p 9030:9030 -p 9053:9053 -v /path/on/host/to/ergo/data:/home/ergo/.ergo ergoplatform/ergo --mainnet

This will connect to Ergo mainnet with default config and open ports 9030 and 9053 on host system. All data will be stored in your host directory /path/on/host/to/ergo/data.

To run specific Ergo version <VERSION> as a service with custom config /path/on/host/system/to/myergo.conf:

sudo docker run -d \
    -p 9030:9030 \
    -p 9053:9053 \
    -v /path/on/host/to/ergo/data:/home/ergo/.ergo \
    -v /path/on/host/system/to/myergo.conf:/etc/myergo.conf \
    ergoplatform/ergo:<VERSION> --<networkId> -c /etc/myergo.conf

Available versions can be found on Ergo Docker image page, for example, v3.1.0.

This will connect to Ergo mainnet or testnet respecting your configuration passed in myergo.conf and network flag --<networkId>. Every default config value would be overwritten with corresponding value in myergo.conf.

This command also would store your data in /path/on/host/to/ergo/data on host system, and open ports 9030 (node communication) and 9053 (REST API) on host system. The /path/on/host/to/ergo/data directory must has 777 permissions or has owner/group numeric id equal to 9052 to be writable by container, as ergo user inside Docker image (please refer to Dockerfile).

Ergo node works normally behind NAT, so you can keep closed your 9030 port, hence other nodes could not discover and connect to yours one, only your node could initiate connections.

It is also a good practice to keep closed REST API port 9053, and connect to your node from inside another container in the same Docker network (this case not covered by this short quick start manual).

Open project in IDE

Your can use IntelliJ IDEA (Community or Ultimate edition) or VSCode + Metals. Before opening the project in IDE make sure it can be built with sbt as described above. You can also run tests using sbt test command. You may need to fix dependency resolution errors first.

After that you can open the project folder in Idea (File / Open) which will run Project Import Wizard. The wizard will use SBT configuration (build.sbt file) to generate Idea's project configuration files. You can open File / Project Structure... dialog to see project configuration. If everything is successful you can compile the project in IDE.


Frequently Asked Questions


YourKit supports open source projects with its full-featured Java Profiler. YourKit, LLC is the creator of YourKit Java Profiler and YourKit .NET Profiler, innovative and intelligent tools for profiling Java and .NET applications.

You can’t perform that action at this time.