Ergo's reference node is a Scala codebase with three ways to sync the chain

What the repository actually is

Ergo is a Proof-of-Work cryptocurrency protocol that has been designed to offer a secure environment for new kinds of money, peer-to-peer interactions, trust-minimized financial tooling and derivatives. This repository is the reference client, also known as the node, for Ergo.

The reference client is primarily written in Scala, and while certain components of the protocol are implemented in other languages, for instance sigma-rust as a Rust-based implementation of the ErgoScript cryptocurrency scripting language, the reference client provides the most complete and comprehensive implementation of the protocol at the moment.

That last clause is the important one for anyone deciding what to read. If you want to know what Ergo actually does rather than what the whitepaper says, this Scala codebase is where the answer is.

The repository is organised as a set of sbt modules so that only the parts an application needs can be used. The avldb module is the implementation of the authenticated AVL+ tree used in Ergo, with persistence. The ergo-core module holds the functionality needed for an SPV client, including P2P messages and block section structures. There is an ergo-wallet module, and a src/ directory for the node itself.

The licence is CC0-1.0, which is worth noting for a blockchain reference implementation, since it places the code in the public domain rather than requiring attribution. The protocol documentation sits at ergoplatform.org and the papers/ directory holds the protocol documents alongside the whitepaper and the ErgoScript whitepaper.

The default branch is master, the last push was on 2026-10-20, and the listed releases are the reference client versions v6.0.8 from 2026-10-13, v6.1.7 from 2026-09-29 and v6.1.6 from 2026-09-21. The two version series running in parallel is a reminder that the client and the protocol version are not the same thing.

The design choices that separate Ergo from Bitcoin

The README lists five features, and each one exists to solve a problem Bitcoin's design does not address.

ErgoScript is a powerful contract language in the multi-stage extended UTXO model, and it is the piece that supports the noninteractive zero-knowledge proofs the ErgoScript whitepaper describes.

Autolykos2 is a memory-hard Proof-of-Work function, which is the answer to the ASIC and GPU specialised hardware problem that has followed Bitcoin's original SHA-256 design. Memory-hard means the work cannot be parallelised cheaply, so ordinary hardware stays competitive.

Support for stateless clients comes next, based on asymmetric stateless clients, and it includes features like NiPoPoWs and hybrid modes. This is the part that lets a light client verify a block without holding the whole UTXO set, and it is the foundation of the sync modes the README describes later.

The advanced transactional language is an alternative transactional language that is more powerful than Bitcoin Script and is designed to be safe against heavy validation attacks. It is a separate implementation, the sigmastate-interpreter, rather than a change to the ErgoScript layer.

The innovative fee model is an alternative fee model with a mandatory storage-rent component, also known as demurrage. The stated benefits are truly fixed supply in the long-term, protection from UTXO dust bloating, and an additional rewards stream for miners.

That fee model is the one with visible consequences for users, because it means holding coins in the chain has a running cost rather than being free, and it is the reason the storage-rent discussion is a recurring topic in the protocol's design.

Three ways to sync a chain you cannot afford to hold

By default the node processes all blocks from the genesis block, and the README describes three alternatives for hardware with limited resources.

The first is bootstrapping with a UTXO set snapshot, which works similarly to Ethereum's snap-sync. The node first downloads a UTXO set snapshot from a secure point in the past, then downloads blocks following the snapshot and applies them to the set. The configuration is a single flag.

ergo {
  ...
  node.utxo.utxoBootstrap = true
  ...
}

The second combines that with NiPoPoW, Non-Interactive Proofs of Proof-of-Work, which allows syncing the headers chain in logarithmic time as opposed to the linear time required by the standard SPV sync for headers.

ergo{
  ...
  node.nipopow.nipopowBootstrap = true
  node.utxo.utxoBootstrap = true
  ...
}

The third is stateless mode, which provides full-node security without the need to hold the entire UTXO set, using the methods detailed in the authenticated dynamic dictionaries paper. In this mode it is possible to download and validate an arbitrary-sized suffix of the blockchain.

ergo {
   ...
   node.stateType = "digest"
   node.blocksToKeep = 2160 # store and process last three days only
   node.nipopow.nipopowBootstrap = true   # compatible with NiPoPoWs 
   ...
}

The stateless configuration is the one to look at first, because the stateType of digest and a blocksToKeep of 2160 means the node stores and processes only the last three days. That is a node that keeps a security assumption about the rest of the chain rather than verifying it, which is a trade the README is explicit about.

More detail on the modes is at docs.ergoplatform.com/node/modes.

The security assumptions, which are the honest part of the README

There is a short section on the security assumptions the client operates under, and it is worth reading in full because it is more candid than most.

The execution environment is trusted. Although the seed is stored in an encrypted file, and the client's wallet attempts to purge the secret key from memory as soon as it is no longer needed, the client does not have defenses against side-channel attacks, memory scans, and similar.

Clocks are expected to be synchronized to a reasonable degree. If a block's timestamp is more than 20 minutes into the future, the block will be temporarily rejected. The client does not utilize NTP or other time synchronization protocols.

The second one is operationally interesting. A node with a clock that drifts more than twenty minutes ahead rejects blocks as temporarily invalid, and the node does nothing to correct its own clock. On a machine with a badly synchronised clock, or one running in a container with a drifting clock, the symptom is a node that rejects the chain.

Neither assumption is a flaw in the protocol. They are statements about the environment the client expects to run in, and they are the kind of thing that should shape how you deploy and monitor a node rather than how you should trust the protocol's cryptography.

The README also links the protocol's specifications: the white paper as a brief description of the protocol, the ErgoScript white paper describing the scripting language supporting noninteractive zero-knowledge proofs, and further papers at docs.ergoplatform.com/documents.

Building, testing and running the node

The build instructions are for the official documentation at docs.ergoplatform.com/node/install/, and the Dockerfile shows how the artefact is produced.

The builder stage starts from an sbt image on Temurin 11, copies the build.sbt and the per-module project directories, runs sbt update, copies the source and runs sbt assembly, then moves the assembled jar out of the target tree.

The runtime stage is a JRE on Ubuntu Jammy with curl and jq installed, and it creates a non-root user named ergo with a fixed uid of 9052, switches to it, exposes a set of ports and declares a volume for the data directory.

EXPOSE 9020 9021 9022 9052 9030 9053
WORKDIR /home/ergo
VOLUME ["/home/ergo/.ergo"]
ENV MAX_HEAP 3G
ENV _JAVA_OPTIONS "-Xms${MAX_HEAP} -Xmx${MAX_HEAP}"

The heap is pinned to 3G in both directions, which means the container will not grow past it and will not start below it, and that is a deliberate choice for a node with a predictable working set rather than a default.

There is also an ergo-installer.sh script at the repository root for installing on a machine directly.

The test suite comes in three flavours, and the split is by cost.

Unit and property tests run with the `sbt test` command. Integration tests require Docker and run with `sudo sbt it:test`. Bootstrapping tests are described as time-consuming because they verify that the node is syncing with the main network in various modes, also requiring Docker, run with `sudo sbt it2:test`.

So there is a fast inner loop, a slower container-based layer, and a very slow layer that checks the node against the real network. A contributor is expected to run the first two before submitting a patch.

Working on it in an IDE, and where the code lives

You can use either IntelliJ IDEA, Community or Ultimate edition, or VSCode with the Metals extension.

The instruction that catches people is to ensure that the project can be built with sbt before opening it in an IDE, since you may need to resolve any dependency errors first. The IDE import is not a substitute for a working sbt build, because the import reads the build definition rather than executing it.

In IntelliJ, you select File and Open and navigate to the project folder, which initiates the Project Import Wizard using the SBT configuration in the build.sbt file to generate the project configuration files. The generated configuration is visible in the File and Project Structure dialog, and if the import succeeded you should be able to compile the project in the IDE.

Beyond that, the repository carries the ordinary artefacts of a long-lived Scala project. There is a .scalafmt.conf for formatting, a scalastyle-config.xml for static analysis, a findbugs-exclude.xml, a ci/ directory, a do-release.sh script for cutting a release, a .travis.yml from the earlier CI era alongside the .github/ directory, an AGENTS.md, a FAQ.md, a Dockerfile and a .editorconfig.

The FAQ.md and papers/ directory are worth knowing about, since the papers directory holds the protocol documents locally alongside the links in the README.

The release history is dense and the two version series are the thing to understand. The listed releases are the reference client versions, so v6.1.7 and v6.0.8 are different lines of the client rather than a version regression, and the README's own description of them as Ergo protocol reference client releases confirms that the numbering tracks the client.

Where Ergo is the wrong choice

Four cases argue against it.

The first is if you want a library rather than a node. This is a full node, a Scala codebase with a JVM dependency, a 3G heap and a data directory. If you want to sign a transaction or query a balance from an application, the wallet and ergo-core modules are the relevant parts, not the node application, and the node is a much heavier thing to depend on.

The second is if you need to hold and verify the entire chain. The stateless mode with stateType digest and blocksToKeep of 2160 deliberately stores and processes only the last three days, and the whole point of the UTXO snapshot modes is to avoid holding the set. Those are the right trade for a laptop, and the wrong one for an archival node whose job is to be the archive.

The third is if you want a cryptocurrency without a storage rent. The mandatory storage-rent component means balances decay over time by design, and any application that treats a balance as a static amount of value has to account for that. The same applies to the alternative fee model, which has consequences for transaction fees and for any long-term holding assumption.

The alternative in the same direction is to work with ErgoScript contracts through the sigma-rust implementation, which is the Rust-based implementation of the scripting language, if your interest is in writing contracts rather than in running a chain. The difference in approach is that the Scala reference client is the complete protocol, including the node, the wallet, the peer-to-peer layer and the authenticated AVL+ tree, while sigma-rust targets the scripting language specifically, in a language with a much smaller dependency footprint and a correspondingly smaller surface. For auditing the protocol or running a node, this repository is the reference. For scripting, sigma-rust is the smaller thing to look at first.

Editorial conclusion

Ergo fits a developer who needs the most complete implementation of the protocol to build against or to audit, since the reference client is the specification in executable form, and it fits an operator with limited hardware who needs to sync without holding the whole UTXO set. It does not fit someone who wants a light client library, since this is a node, and the stateless mode still downloads and validates a suffix of the chain. Build it with the sbt assembly flow the Dockerfile performs, configure `node.utxo.utxoBootstrap` and `node.nipopow.nipopowBootstrap` for a faster sync, and read the security assumptions about the trusted execution environment and unsynchronised clocks before you treat it as production infrastructure.

Frequently asked questions

Official sources

1. ergoplatform/ergo on GitHub
2. License: CC0-1.0
3. Project website
4. README
5. Releases