# stellar-core: the C++ node that runs the Stellar network

> stellar-core is the reference implementation of the peer-to-peer agent that keeps a copy of the Stellar ledger and agrees on transaction order with its peers. It is infrastructure software, not an application, and the README points elsewhere for the install steps.

**stellar/stellar-core** — Reference implementation for the peer-to-peer agent that manages the Stellar network.

- Repository: https://github.com/stellar/stellar-core
- Website: https://www.stellar.org
- Stars: 3,302 · Forks: 1,080
- Language: C++
- License: NOASSERTION
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/stellar-stellar-core

## What stellar-core is for, and who ends up running it

The README describes stellar-core as a replicated state machine that maintains a local copy of a cryptographic ledger and processes transactions against it, in consensus with a set of peers. That sentence is the whole product. There is no wallet, no REST API for end users, no dashboard. The program joins a peer set, keeps its own copy of the ledger on disk, and votes on which transactions to apply and in what order.

The audience follows from that. Validators run it because consensus membership is defined by the node's configuration, not by a hosted service. Exchanges, anchors and infrastructure teams run it because they need a ledger view they control rather than one they query from someone else. Engineers evaluating the network run it to read the source and watch the protocol work. If you want to send a payment from an application, this is the wrong layer: the README does not present stellar-core as a client library, and the repository layout (src/, docs/, lib/) is a node, not an SDK.

## Federated consensus instead of a global vote

stellar-core implements the Stellar Consensus Protocol, which the README labels a federated consensus protocol. The distinction matters. Rather than every node agreeing with every other node, each participant declares which other participants it trusts, and agreement is reached through overlapping sets of those declarations. The protocol has its own README under src/scp/, which is where the message flow and the quorum logic are documented.

Architecturally the repository shows a C++20 codebase with a Rust workspace bolted alongside it. Cargo.toml declares a workspace whose only member is src/rust, so the Rust side is a sub-crate compiled into the same binary rather than a separate service. The release profile sets codegen-units to 1 and turns on link-time optimization, which is what you would expect for a consensus binary where the hot path should not be split across translation units. A fastdev profile exists that inherits from release but turns LTO off and raises codegen-units to 16, so contributors can rebuild without paying the full optimization cost.

The data flow is the ordinary one for a replicated state machine: transactions arrive, peers exchange protocol messages, agreed transactions are applied to the local ledger, and the resulting state is persisted. What is unusual is that the trust graph is configuration, not code. Two nodes running identical binaries can disagree about whom they listen to.

## Installing stellar-core: where to start and what to expect

The README does not carry install instructions. It points at INSTALL.md, and there is a separate INSTALL-Windows.md for the Windows path. The README states that the project is written in C++20 and runs on Linux, OSX and Windows. Because the build is autotools-based, the repository ships autogen.sh, configure.ac and Makefile.am, and there is a docker/ directory for container builds.

Start by cloning the repository and generating the configure script:

```bash
./autogen.sh
```

The script exists at the repository root and is what turns configure.ac into a runnable configure. After it completes you should see a configure script appear next to it.

The Rust workspace is part of the build, so the toolchain has to be present. The repository provides install-rust.sh and a rust-toolchain.toml that pins the expected version:

```bash
./install-rust.sh
```

If you prefer to manage the toolchain yourself, rust-toolchain.toml at the root records which version the project builds against. Once the toolchain is in place, the standard autotools sequence follows, and the Makefile drives the Rust build through the Cargo workspace declared in Cargo.toml. For a faster developer build, the Cargo profile comment mentions `make RUST_PROFILE=dev`, which builds the Rust crates with debug information and no optimization.

What you should not expect from the README is a configuration file, a genesis procedure or a list of peers to join. Those are all in the files the README links to, and the README itself stays deliberately short.

## The build is the hard part, and the docs know it

The honest limitation of stellar-core is that it is a large C++ project with a Rust workspace inside it, and the README does not soften that. The install instructions are a separate document for a reason. You need autotools, a C++20 compiler, and a Rust toolchain whose version is pinned by rust-toolchain.toml. The release profile in Cargo.toml enables LTO across the whole binary, which makes a full release build slow; the fastdev profile exists precisely because that cost is real.

There is a second limitation that is not about compilation. Running the binary is not the same as participating usefully. Consensus membership depends on configuration that the README does not describe, and the README does not document rollback, recovery from a corrupted ledger, or what happens if your node falls far behind its peers. The docs directory is where the code's layout and abstractions are described, and that is where you would look. If your goal is to read ledger data, running a full consensus node is the wrong tool: it is more machinery and more operational surface than the task needs.

A third point is the licence. The repository carries LICENSE-APACHE.txt and the metadata reports the licence as NOASSERTION, which means the GitHub classifier could not reduce it to a single identifier. Read both the COPYING file and LICENSE-APACHE.txt before you redistribute anything.

## How it compares to Horizon and the SDKs

The natural alternative is not another consensus implementation; it is Horizon, the query layer that sits in front of the network, or one of the Stellar SDKs. The difference in approach is architectural. stellar-core holds the ledger and decides what goes into it. Horizon and the SDKs read the ledger and build transactions against it, and they do not ask you to run a consensus participant or maintain a peer configuration.

That split is why stellar-core is the wrong first stop for most developers. If you are writing an application, the SDK gives you the transaction-building and submission path without the operational weight of a node. If you are running infrastructure that must not depend on someone else's view of the ledger, the node is the point. The two are not competing for the same user, and the README does not pretend otherwise: it describes a replicated state machine and points to the overview document for the rest.

## Maintenance, releases and what upgrading costs

The repository is not archived and the last push was on 2026-09-22, two days before this writing, so the codebase is being changed. Releases are frequent and versioned in the v27 and v28 series: v28.0.1 on 2026-09-01, v28.0.0 on 2026-08-13, and v27.1.0 on 2026-06-25. The NEWS file at the repository root is the changelog to read before an upgrade.

The upgrade cost is not only the binary. The repository ships test-lcm-current and test-lcm-next directories alongside test-tx-meta-baseline-current and test-tx-meta-baseline-next. The current and next pairs indicate that behaviour is validated against two protocol versions at once, which is what you would expect from software that has to stay compatible with the network during a transition. There is also a soroban-settings directory, and the Cargo workspace builds Rust code into the binary, so a release can change both the C++ and the Rust side at the same time.

On licensing, the repository contains LICENSE-APACHE.txt and COPYING, and the metadata reports NOASSERTION. If you redistribute stellar-core or a build of it, read those files rather than relying on the metadata field. This is not legal advice; it is a pointer to the files that govern the question.

## Conclusion

stellar-core is for operators who need to take part in Stellar consensus or run a validator, and for engineers building against the network who want to see how the ledger is actually maintained. It is not for anyone who wants a wallet, an SDK or a hosted API: the README describes a replicated state machine, and the repository ships no application layer. Before you commit, read INSTALL.md and CONTRIBUTING.md, check which of the two licence files applies to the code you redistribute, and confirm the platform you plan to run on is one the project claims to support.

## FAQ

### What is stellar-core, in the Stellar network sense?

It is the reference implementation of the peer-to-peer agent that manages the Stellar network, described in the README as a replicated state machine that keeps a local copy of a cryptographic ledger and processes transactions against it in consensus with peers.

### Where do I find the stellar-core installation instructions?

The README does not include them; it links to INSTALL.md, with a separate INSTALL-Windows.md for Windows. The repository also provides autogen.sh, configure.ac and install-rust.sh for the build.

### Does stellar-core run on Windows and macOS?

The README states that it is written in C++20 and runs on Linux, OSX and Windows. INSTALL-Windows.md is the platform-specific document in the repository.

### What consensus protocol does stellar-core implement?

The Stellar Consensus Protocol, which the README calls a federated consensus protocol. Its documentation lives in src/scp/README.md inside the repository.

### Is stellar-core the same as the Stellar SDK or Horizon?

No. stellar-core maintains the ledger and participates in consensus, while Horizon and the SDKs are the layers applications use to read the ledger and submit transactions. The README describes only the node.

## Sources

- [Issues](https://github.com/stellar/stellar-core/issues)
- [Project website](https://www.stellar.org)
- [README](https://github.com/stellar/stellar-core/blob/master/README.md)
- [Releases](https://github.com/stellar/stellar-core/releases)
- [stellar/stellar-core on GitHub](https://github.com/stellar/stellar-core)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/stellar-stellar-core