Architecture

Heartwood separates its Rust packages and test tools in a Cargo workspace. Applications read and present the resulting records.

Source layout

Path	Responsibility
packages/crypto/	Keys, addresses, signatures, transaction and block codecs, milestones
tools/difftest/	Differential-test harness and command-line driver
tools/oracle/	Pinned reference image and vector generation
packages/crypto/tests/vectors/	Committed reference vectors and integrity manifest
fuzz/	Decoder fuzz targets in a separate workspace

The crypto crate is the byte-exact foundation. New components can add differential-test subjects against the same reference records.

Responsibilities

Component	Responsibility
Heartwood Core	Apply network rules and maintain chain state
Wallet	Present accounts and prepare authorized actions
Explorer API	Present queryable network records
Explorer interface	Turn those records into search, pages, and visuals
Validator portal	Publish proposals and contribution history

One record, several views

The explorer’s pages and visual scenes share one API snapshot. A selected block and its detail page therefore refer to the same transactions.

• Explorer: Next.js proxies the snapshot from a Rust/Axum service.
• Validator portal: Next.js and Axum, with SQLite for proposals and sessions.
• Desktop and mobile wallets: React interfaces in Tauri applications.
• Browser wallet: a static web application and Chromium extension.

Protocol versions

The current portal signing adapter uses Heartwood devnet’s BIP340 identity format. The draft protocol specifies post-quantum authentication for mainnet.

Treat the selected Heartwood release and its network configuration as authoritative for an integration. Do not combine address formats, signature schemes, or transaction encodings from different revisions.

Proposed node roles

The draft assigns each process a separate job:

• Relay: communicate with peers and API clients.
• Validator signing process: hold the consensus key and sign blocks.
• Indexer: serve history queries.
• IceRoot Connector: read source chains and sign migration attestations, on a machine or service separate from the relay and the signing process.

The validator’s account key stays off those servers.

This separation limits which keys each process can reach. Runtime commands should come from the release that implements those roles; the current development workspace does not provide a complete node service.

The draft also plans:

• Network defense: optional public sentry relays in front of a validator’s own relay, peer scoring, diverse outbound peers, and public APIs on separate API nodes rather than on a validator’s relay.
• Diagnostics: a separate doctor tool that runs deterministic checks of a node’s configuration and state. It exports a report with keys, secrets, and IP addresses removed. Its read-only Model Context Protocol interface, which the operator’s own client starts over SSH, can run the checks and read the report, but has no network listener, no tool that writes or runs commands, and no key access.

No node process loads or calls a language model or other machine-learning model.