# Build from source

> Set up the Heartwood development workspace and verify its current Rust baseline.

Source: https://docs.iceroot.com/core/installation/

These commands build and check Heartwood’s current development workspace. They do not start a mainnet or testnet node. The relay, the forger and the local devnet described below run development networks only.

The [Heartwood Core repository](https://github.com/iceroot-network/heartwood-core) is public. To follow the public lab devnet, use [Run a devnet node](https://docs.iceroot.com/network/run-a-node/index.md). It has no value and may reset at any time. Follow [Network status](https://docs.iceroot.com/network/status/index.md) for updates.

## Requirements

- A checkout of the public Heartwood Core repository.
- Rust 1.98 or later, with Clippy and rustfmt.
- Git and Make.
- Linux is the only supported platform for Heartwood nodes and operator tooling. The local devnet puts each node on its own loopback address. This restriction does not apply to the wallets or SDKs.
- Optional: `cargo-deny`, for `make deny`.

The ordinary checks use committed test vectors and need only the Rust toolchain. Regenerating the reference vectors also needs Docker and the reference setup described below.

## Get the source

Clone the public source, then run the checks from its root:

```sh
git clone --branch prod https://github.com/iceroot-network/heartwood-core.git
cd heartwood-core
make check
```

`make check` builds the workspace, runs Clippy with warnings treated as errors, checks formatting, runs tests, and checks release feature isolation.

Use `make help` to see the targets supplied by your checkout. Follow the repository’s toolchain requirement if it changes.

To check the licences, advisories and sources of every dependency, install `cargo-deny` and run `make deny`. It needs network access to fetch the advisory database, so `make check` does not run it.

## Run a relay

A development build includes a relay. It runs in the foreground and follows a reference network. Do not point it at a mainnet or testnet node.

```sh
cargo build --release --locked -p heartwood-core
target/release/heartwood relay run --network <name>
```

It reads the reference’s configuration files for that network: `app.json`, `peers.json`, `.env` and the four `crypto/*.json` files in the node’s configuration directory. It keeps its store in its data directory. It listens for peers on `CORE_P2P_PORT` and serves the node API on `CORE_API_PORT`, as that `.env` sets them; without them it uses the reference’s defaults, 4002 and 4003. Its peer-to-peer server takes the blocks and transactions its peers push and serves its own forger. SIGINT or SIGTERM stops it after the current job. Take the other flags from `target/release/heartwood relay run --help`.

## Run a forger

```sh
target/release/heartwood forger run --network <name>
```

The forger holds the delegates’ private keys and forges their blocks through its relays. It opens no listening socket. It reads the same configuration directory as the relay. The forger’s section of `app.json` lists its relays in `hosts`, in order; by default it uses the relay on the same host. The file `delegates.json` holds the delegates’ keys, and the forger refuses to start if group or others have any permission on it.

Each relay must list the forger’s address in its `remoteAccess` setting. A relay serves a forger only from addresses on that list, which holds exact addresses, not patterns, and an empty list admits none. In this development build a relay attests only a forger on its own host. A signing record in the data directory keeps the forger from signing two different blocks for one slot, across restarts too. Never delete it or restore an old copy.

## Manage the processes

`heartwood relay start` and `heartwood forger start` run a role under the built-in supervisor, as a background daemon unless you pass `--daemon false`. The commands `stop`, `restart`, `status` and `log` manage it, and the supervisor restarts a role that crashes. `heartwood network generate --network <name> --seed <text> --out <dir>` writes a new development network’s crypto files, its keys and one node’s configuration.

## Run a local devnet

```sh
target/release/heartwood devnet --dir <dir> init --validators 5
target/release/heartwood devnet --dir <dir> start
target/release/heartwood devnet --dir <dir> status
target/release/heartwood devnet --dir <dir> stop
```

The devnet runs on one Linux host. Each validator node is a relay and a forger, each under its own supervisor, and each node has its own loopback address, with peer-to-peer on port 6002 and the API on port 6003. `init` generates the chain from a seed and writes each node’s configuration and its share of the delegates’ keys. The default seed is public, so use the devnet for testing only. `status` shows the processes, their heights and whether every relay has the same chain. The commands `stop-node`, `start-node`, `restart-node`, `reset`, `wait`, `logs` and `env` act on single nodes. A node refuses to start in a network not named `devnet`, or on an address that is not a loopback address.

## Run the crypto tests

```sh
cargo test -p heartwood-crypto --locked
cargo test -p heartwood-crypto --locked --all-features
```

The first checks the ordinary build. The second enables the test features needed for every vector class.

## Reference setup

The oracle uses `iceroot-network/solar-core-ref` at the configured tag, currently `s1-ref-v2`. The default checkout location is `../solar-core-ref`.

```sh
make oracle-image
```

Building the image needs network access. The reference runtime runs without network access. Local oracle comparison additionally requires Node 18.20.8, pnpm 6.32.11, and Python 3.10 for the reference’s native dependencies; use the repository’s exact recipe.

Do not copy those legacy reference requirements into the website or wallet toolchain. They belong to the compatibility oracle.

[Testing and compatibility →](https://docs.iceroot.com/core/testing/index.md)
