wavesplatform/Waves: running a node from the release jar or SBT

What the Waves node is responsible for on the network

A Waves node is a host connected to the Waves blockchain network. The project lists its functions plainly: processing and validation of transactions, generation and storage of blocks, network communication with other nodes, a REST API, and extensions management. That list is the whole scope. The node does not offer a wallet interface, a block explorer or a trading front end, and it is not a light client that only follows headers.

The code base is Scala, and the project calls itself a reference implementation of the protocol. Waves itself is described as an open source blockchain protocol that can be used to build decentralized applications, and the ecosystem includes a smart contract language called RIDE. The repository therefore serves two audiences: node operators who want to take part in the network, and developers who want a readable reference for how transactions, blocks and extensions fit together.

The runtime footprint follows from that choice. The node is a JVM application, the build uses SBT, and the repository is large enough to include separate modules for the language implementation, a REPL, a ride runner, a gRPC server, benchmarking code and an integration test suite. A reader looking for a single small binary will not find one here. The repository is licensed under MIT, so the code can be read, modified and redistributed under that license, with the usual obligation to keep the license notice.

The module layout behind one deployable jar

The top level of the repository is where the architecture becomes visible. Directories include `node/`, `lang/`, `repl/`, `ride-runner/`, `grpc-server/`, `node-it/`, `benchmark/`, `node-generator/`, `project/` and `docker/`, alongside `build.sbt`, `version.sbt`, `.sbtopts`, `.scalafmt.conf` and `scalastyle-config.xml`.

`node/` is the deployable part. It is the module that produces the fat jar, the configuration resources and the deb package. `lang/` holds the language side of the chain, `repl/` and `ride-runner/` provide interactive and command line ways to work with RIDE code, and `grpc-server/` exposes the node over gRPC alongside the REST API. `node-it/` contains the integration tests that talk to a real node over a network, which is why the integration test step needs a Docker image.

The build tooling around those directories is worth noting for a reader who plans to modify the code. `.sbtopts` and `project/` hold SBT settings, `version.sbt` carries the project version, and `.scalafmt.conf` with `scalastyle-config.xml` define the Scala formatting and static style rules that the project applies to its own sources. The default branch is `version-1.6.x`, and the packaged releases follow the same 1.6 line, which tells you that the 1.6 series is the maintained line in this repository rather than a legacy one.

Starting a node from a release jar on Linux, Mac or Windows

Two things are needed before the node starts: a configuration file for the network you intend to join, taken from the `node` directory in the repository, and a `waves-all*.jar` file from the releases. On Linux the prerequisites are installed with the package manager:

sudo apt-get update
sudo apt-get install openjdk-17-jre

The node is then launched by pointing the jar at a configuration file:

java -jar node/target/waves-all*.jar path/to/config/waves-{network}.conf

The `{network}` placeholder is replaced with the network whose configuration you downloaded, so the argument becomes a concrete path to a mainnet or testnet configuration file. The same launch line applies on Mac and Windows. The Mac path assumes Homebrew is present:

brew cask install adoptopenjdk/openjdk/adoptopenjdk17
java -jar node/target/waves-all*.jar path/to/config/waves-{network}.conf

On Windows the project assumes OpenJDK 17 is already installed, and the only command needed is the same `java -jar` invocation. Note what is not in these instructions. There is no service unit, no container orchestration file and no guidance on log rotation, so a first run is a foreground process you stop by hand. Anyone planning an unattended deployment has to design that part themselves, or use the published Docker image instead, which the project points at the official image documentation for.

Configuration defaults and what the node expects at startup

Configuration is file based, and the project steers newcomers to the default files rather than to a settings UI. The defaults for the different networks live in `node/src/main/resources/network-defaults.conf`, and the project's own guidance calls them the easiest way to start playing around with configurations. The parameters available in total are described in a separate configuration article in the documentation, and logging levels and parameters have their own page in the same documentation set.

That structure is a real strength for reproducibility. A node operator can read the defaults that ship with the version they downloaded, compare them with the file that was actually used, and see every key the node understands. It also means the launch command is not enough on its own: a node started with a wrong or missing configuration file will not reach the network, so the configuration file argument is the part to check first when a node starts and then does nothing.

Extensions are part of the node's job rather than a separate service, and they are managed by the node itself. The project keeps a dedicated documentation page for extensions, which suggests extension configuration is expected to travel with the node configuration rather than be bolted on afterwards. The repository does not list the available extensions or describe how a failing extension is isolated, so treat the extension documentation as the authoritative reference and the repository as the source for the core configuration defaults only.

Building from source with SBT and the test suites that guard it

Building the node from source assumes Java for your platform and SBT. The environment setup is short:

sudo apt-get update
sudo apt-get install openjdk-17-jre                     # Ubuntu
# or
# brew cask install adoptopenjdk/openjdk/adoptopenjdk17 # Mac

Then the repository is cloned and the checks are run:

git clone https://github.com/wavesplatform/Waves.git
cd Waves

sbt checkPR

`checkPR` is the entry point for the pull request checks, and the project lists it as the step for compiling and testing. Integration tests are optional and have an extra prerequisite: a Docker image has to be created first, which is what `sbt node-it/docker` does.

sbt node-it/docker

The number of suites running in parallel is controlled by a system property, and the project shows both the serial and the selective form:

sbt -Dwaves.it.max-parallel-suites=1 node-it/test

sbt node-it/testOnly *.TestClassName
# or
bash node-it/testOnly full.package.TestClassName

Packaging is a separate step, and the network is chosen with a property rather than with a different command:

sbt packageAll
sbt -Dnetwork=testnet packageAll

The first line builds the mainnet packages, the second the testnet ones. A useful detail is what `sbt packageAll` actually produces: only a deb package alongside the fat jar. Installing the deb is a single command:

sudo dpkg -i node/target/*.deb

The deb is therefore a convenience wrapper around the jar rather than a separate runtime. Anyone expecting a systemd service, a data directory layout with migration tooling, or an unattended upgrade path will not find one described here.

Where the Waves node is the wrong choice

The clearest case against this project is scale of effort. This is a full node implementation of a blockchain protocol in Scala, built with SBT, and the build and test steps assume a working JVM, a Docker daemon for integration tests and a checkout of a large multi module repository. A team that only needs to read chain data through an API should look at the REST API documentation instead of operating a node.

The second limitation is operational opacity. The documentation is split across the repository and a separate documentation site, and the repository itself does not describe how to stop a node cleanly, how to upgrade from one 1.6 release to the next without a fresh state directory, or how to roll back a bad configuration. The release list shows `v1.6.4` dated 2026-08-27, `v1.6.3` dated 2026-06-03 and `v1.6.2` dated 2026-04-14, so a new release arrives every couple of months, and the last push was on 2026-09-02. That is a project with recent activity, but the repository does not promise a support window for any particular release line.

Third, the node is tied to the protocol as it stands. RIDE smart contracts, the REST API and the extension model are all Waves specific, so the reference implementation is the right thing to study when you are building on Waves and the wrong thing to reach for when you want a generic blockchain node. Developers who only want to evaluate RIDE expressions can use the `repl/` and `ride-runner/` modules or the `extension-module/run` command without taking on a full network deployment.

Editorial conclusion

Adopt the Waves node when you need a reference implementation of the protocol that you can start from a release jar, a deb package or the published Docker image, and when you accept Scala and JVM memory requirements. Do not adopt it as a lightweight client or as a source of documented rollback procedures, since neither the repository nor its configuration guides describe them. Before the first run, confirm the OpenJDK 17 requirement, the network specific configuration file you copied, and the exact release artifact you downloaded.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. wavesplatform/Waves on GitHub