aeternity node: an Erlang blockchain with state channels

What the aeternity node is and who it is for

The aeternity node is the node software of the aeternity blockchain, written in Erlang. The project describes itself as a new blockchain for decentralised applications, optimised for scalability via smart contracts inside state channels. It also includes a built-in oracle for integration with real-world data and a naming system intended to improve developerability. The audience is developers building applications on the network, not end users looking for a lightweight client. The licence is ISC, and the documentation lives at docs.aeternity.io, with protocol, API and research specifications kept in a separate protocol repository.

How state channels, oracles and names fit together

The README gives only a high-level picture, but the core idea is clear. Smart contracts run inside state channels, which moves execution off the main chain and is the mechanism behind the scalability claim. A built-in oracle provides integration with real-world data. The naming system gives developers human-readable names instead of raw addresses. Protocol details, APIs and research are maintained separately in the aeternity/protocol repository, so the node repository itself focuses on implementation and operation. The node stores its chain data in a Mnesia database, and the Docker image exposes ports 3013, 3014, 3015, 3113, 3213 and 3413 for the various services.

Installing and running a node

The project publishes packages for major platforms on GitHub and asks users to prefer the latest stable release over the master branch, which tracks ongoing work and is not guaranteed to be stable. For Linux and Mac there is an installer:

bash <(curl -s https://install.aeternity.io/install.sh)

Alternatively the node runs as a Docker container:

mkdir -p ~/.aeternity/maindb
docker pull aeternity/aeternity
docker run -p 3013:3013 -p 3015:3015 \
    -v ~/.aeternity/maindb:/home/aeternity/node/data/mnesia \
    aeternity/aeternity

On Windows the equivalent Docker invocation uses a different volume path:

mkdir %APPDATA%\aeternity\maindb
docker pull aeternity/aeternity
docker run -p 3013:3013 -p 3015:3015 -v %APPDATA%/aeternity/maindb:/home/aeternity/node/data/mnesia aeternity/aeternity

After starting, see the documentation for how to start and configure the node. Configuration examples are linked from the docs rather than shipped in the README.

Restoring from a snapshot to skip initial sync

Initial blockchain synchronisation can be slow, so the node supports restoring the database from a snapshot. The container must be stopped before replacing the database. The documented procedure deletes the existing database directory, downloads a compressed snapshot, verifies its checksum, and extracts it:

rm -rf ~/.aeternity/maindb/ && mkdir -p ~/.aeternity/maindb/
curl -o ~/.aeternity/mnesia_main_v-1_latest.tar.zst https://aeternity-database-backups.s3.eu-central-1.amazonaws.com/main_backup_v1_full_latest.tar.zst
CHECKSUM=$(curl https://aeternity-database-backups.s3.eu-central-1.amazonaws.com/main_backup_v1_full_latest.tar.zst.md5)
diff -qs <(echo $CHECKSUM) <(openssl md5 -r ~/.aeternity/mnesia_main_v-1_latest.tar.zst | awk '{ print $1; }')
test $? -eq 0 && tar --use-compress-program=unzstd -xf ~/.aeternity/mnesia_main_v-1_latest.tar.zst -C ~/.aeternity/maindb/

This is a destructive, manual procedure. If the checksum does not match, the extraction step should not run, and the operator is responsible for confirming the database path and stopping the container first.

Docker versus native installation

The two supported approaches differ in what you own afterwards. The installer puts a native package on Linux or Mac. Docker gives an isolated container with the data directory mounted from the host, which makes upgrades and resets easier but adds container runtime operations to your checklist. Building from source is also possible using the Makefile and rebar3, with targets such as prod-build, but that path is aimed at contributors rather than operators. For most adopters the choice is between the installer for a simple host install and Docker for a reproducible, replaceable data directory.

Limitations and failure modes

The master branch is explicitly not guaranteed to be stable, so running it in production is a real risk. The Dockerfile notes that the node will not run as root inside Docker, which matters for volume permissions. Snapshot restore is manual and requires stopping the container, deleting data and verifying checksums, so a mistake there can cost the whole chain state. The project publishes a threat model in a separate repository. Finally, because the node is an Erlang application built with rebar3 and RocksDB, operating it requires more familiarity with that stack than a simpler stack.

Maintenance, build tooling and licence

The repository is not archived, and its last push was on 2026-09-15. Recent releases include v7.3.0 on 2026-09-06, v7.3.0-rc11 on 2026-08-31 and v7.3.0-rc10 on 2026-08-26. The build tool is rebar3, with CircleCI for continuous integration and a Dockerfile based on Ubuntu 20.04 and OTP 26. The licence is ISC. Bug and security reports are handled through [email protected], and the Aeternity Crypto Foundation pays bug bounties up to 100.000 AE Tokens for critical vulnerabilities.

Editorial conclusion

Adopt the aeternity node if you are building on the aeternity network and need state-channel smart contracts, an oracle and a naming system in one Erlang node. Skip it if you only need a wallet or a general-purpose chain, or if you cannot operate the exposed ports and a RocksDB-backed data directory. Before adopting, verify you are on the latest stable release rather than master, that ports 3013, 3014, 3015, 3113, 3213 and 3413 are available, and that you have a restore plan for the Mnesia database.

Frequently asked questions

Official sources

1. aeternity/aeternity on GitHub
2. License: ISC
3. Project website
4. README
5. Releases