Build from source
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 is public. To follow the public lab devnet, use Run a devnet node. It has no value and may reset at any time. Follow Network status for updates.
Requirements
Section titled “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, formake 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
Section titled “Get the source”Clone the public source, then run the checks from its root:
git clone --branch prod https://github.com/iceroot-network/heartwood-core.gitcd heartwood-coremake checkmake 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
Section titled “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.
cargo build --release --locked -p heartwood-coretarget/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
Section titled “Run a forger”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
Section titled “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
Section titled “Run a local devnet”target/release/heartwood devnet --dir <dir> init --validators 5target/release/heartwood devnet --dir <dir> starttarget/release/heartwood devnet --dir <dir> statustarget/release/heartwood devnet --dir <dir> stopThe 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
Section titled “Run the crypto tests”cargo test -p heartwood-crypto --lockedcargo test -p heartwood-crypto --locked --all-featuresThe first checks the ordinary build. The second enables the test features needed for every vector class.
Reference setup
Section titled “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.
make oracle-imageBuilding 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.