Architecture
Heartwood separates its Rust packages and test tools in a Cargo workspace. Applications read and present the resulting records.
Source layout
Section titled “Source layout”| Path | Responsibility |
|---|---|
packages/crypto/ | Keys, addresses, signatures, transaction and block codecs, milestones |
packages/state/ and packages/transactions/ | Account and round state, transaction handlers, block application and reversal |
packages/database/, packages/blockchain/, and packages/pool/ | SQLite storage, commit and restart paths, transaction admission |
packages/kernel/ and packages/logger/ | Configuration, shared node utilities, and logging |
packages/p2p-wire/ | Reference-compatible peer message codecs |
packages/p2p/ | Peer client: sessions with reference peers, peer acceptance and the network monitor; with its node feature, the relay’s server |
packages/forger/ | The forger: the slot loop its relay drives, the relay client with failover and call deadlines, block assembly and signing through a persisted signing record, the key file and the status attester |
packages/cli/ | The commands’ library: the colon aliases, a built-in process supervisor, the role commands, the files of network generate and a local devnet |
packages/api/ | Node API server: the reference’s block, node, peer, transaction and wallet routes, with its envelope and error bodies |
packages/core/ | The heartwood binary: the relay and forger roles, network generate and devnet, with their configuration, process locks, signals and shutdown |
tools/difftest/ | Differential-test harness and command-line driver |
tools/oracle/ | Pinned reference image and vector generation |
packages/*/tests/vectors/ | Committed reference vectors and integrity manifests for the component crates |
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
Section titled “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
Section titled “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
Section titled “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
Section titled “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 provides a relay with its peer-to-peer server and a forger, each its own process. It has no indexer yet, and a relay attests only a forger on its own host.
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. See Validator hardening.
Diagnostics
Section titled “Diagnostics”Development builds include the doctor, heartwood doctor, a subcommand of the node binary that runs as its own process. It runs deterministic checks of a node’s configuration and state and exports a report with keys, secrets, and IP addresses removed. Its read-only Model Context Protocol interface, heartwood doctor mcp, 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.