HNChain documentation is organized as a specification-first system.
The whitepaper explains direction and motivation. ADRs record architectural decisions. RFCs and specifications define implementable protocol behavior. HNIPs define long-term change proposals. Developer docs explain how to build on top of accepted protocol interfaces.
docs/
whitepaper/
HNChain-Whitepaper-v0.1-draft.md
adr/
ADR-0000-protocol-invariants.md
ADR-0001-account-state-model.md
ADR-0002-cryptographic-identity.md
ADR-0003-address-format.md
ADR-0004-canonical-serialization.md
ADR-0005-hash-algorithms.md
ADR-0006-transaction-format.md
ADR-0007-state-tree.md
ADR-0008-block-format.md
ADR-0009-consensus-architecture.md
ADR-0010-validator-set-model.md
ADR-0011-leader-election.md
ADR-0012-vote-messages-and-quorum-certificates.md
ADR-0013-finality-rules.md
ADR-0014-fork-choice-rules.md
ADR-0015-slashing-and-accountability.md
ADR-0016-synchronization-checkpoints.md
ADR-0017-light-client-finality-proofs.md
ADR-0018-p2p-protocol-messages.md
ADR-0019-storage-state-interfaces.md
ADR-0020-implementation-language.md
ADR-0021-rust-workspace-policy.md
ADR-0022-protocol-versioning.md
ADR-0023-tokenomics-and-economic-model.md
ADR-0024-hncoin-monetary-policy.md
ADR-0025-governance-model.md
ADR-0026-threshold-and-multisignature-authorization.md
ADR-0027-identity-state-and-account-key-bootstrap.md
ADR-0028-account-level-key-rotation.md
ADR-0029-multisig-deactivation.md
ADR-0030-transaction-and-block-application.md
ADR-0031-write-set-values-and-overlay-state-reader.md
ADR-0032-governance-chamber-weight-query-and-propose-vote-wiring.md
ADR-0033-atomic-write-set-commit.md
ADR-0034-consensus-state-machine-skeleton.md
ADR-0035-wiring-the-consensus-engine-to-hn-state.md
ADR-0036-basic-p2p-networking.md
ADR-0037-multi-node-consensus-wiring.md
ADR-0038-genesis-format-and-node-daemon-bootstrap.md
ADR-0039-devnet-restart-recovery.md
ADR-0040-real-block-hash-in-hn-node.md
ADR-0041-genesis-document-commitments-via-extra-data.md
specs/
core/
account-state.md
cryptographic-identity.md
address-format.md
canonical-serialization.md
hash-algorithms.md
genesis.md
genesis-security.md
transaction-format.md
state-tree.md
block-format.md
rfc/
core/
README.md
primitive-types.md
consensus/
consensus-architecture.md
validator-set.md
leader-selection.md
vote-messages-and-quorum-certificates.md
finality-rules.md
fork-choice-rules.md
slashing-and-accountability.md
synchronization-checkpoints.md
light-client-finality-proofs.md
networking/
p2p-protocol-messages.md
storage/
storage-state-interfaces.md
rpc/
wallet/
explorer/
sdk/
cli/
api/
interoperability/
hnvm/
README.md
hnip/
README.md
governance/
constitution.md
standards/
README.md
performance/
README.md
roadmap/
README.md
ecosystem/
README.md
security/
README.md
developer/
README.md
hn-core/
hn-crypto/
hn-hncs/
hn-state/
hn-storage/
hn-consensus/
hn-network/
hn-node/
hn-rpc/
hn-cli/
tests/
conformance/
core/
primitive-types-v0.1.json
integration/
Purpose:
- mission
- philosophy
- economic direction
- consensus direction
- major trade-offs
- roadmap
The whitepaper is not sufficient for implementation.
Purpose:
- record architectural decisions
- explain rationale and alternatives
- capture consequences and risks
- define dependency order between decisions
ADR documents are decision records, not full protocol specifications.
Purpose:
- define exact protocol objects
- define deterministic behavior
- define canonical formats
- define compatibility rules
- define security requirements
Specifications are normative once accepted.
Purpose:
- define subsystem-level implementable behavior
- define network packets, RPC methods, storage layouts, and protocol APIs
- provide test vectors and interoperability requirements
RFCs should reference ADRs and specifications instead of redefining them.
Purpose:
- define virtual machine semantics
- define bytecode and execution model
- define resource metering
- define contract ABI
- define host functions and safety rules
Purpose:
- propose protocol and ecosystem changes
- document motivation, specification, compatibility, and activation rules
- coordinate long-term governance
Purpose:
- define protocol evolution principles
- define constitutional constraints
- define governance process boundaries
- document compatibility and activation expectations
Purpose:
- define threat models
- define security review requirements
- define audit and bug bounty expectations
- define incident response
- document residual risks
Purpose:
- define ecosystem interfaces
- define asset standards
- define metadata and event expectations
- define conformance tests for interoperable applications
Standards describe behavior and compatibility. They do not define consensus truth unless explicitly accepted by protocol specifications.
Purpose:
- define benchmark methodology
- define standard performance profiles
- define reporting requirements
- define regression tracking
- document measured trade-offs
Performance documents must report conditions, not only headline numbers.
Purpose:
- define development phases
- define release readiness criteria
- define upgrade and deprecation policy
- define long-term support expectations
- document success metrics
Roadmap documents define strategy and criteria, not calendar promises.
Purpose:
- document official tools
- document ecosystem services
- define compatibility expectations
- define voluntary certification concepts
- keep protocol and tooling boundaries clear
Ecosystem tools must not define hidden protocol behavior.
Purpose:
- explain how to build applications
- explain SDK usage
- explain wallet integration
- explain RPC usage
- provide tutorials after protocols are specified
Developer docs must not define consensus truth.
Document status values:
Draft: early document, not acceptedProposed: reviewed direction, still open for approvalAccepted: normative decision or specificationDeprecated: retained for history, no longer recommendedSuperseded: replaced by a newer document
Production implementation must not rely on Draft or Proposed documents as final protocol truth.