Home > Engineering > Infrastructure > P2P building blocks > Hypercore

Hypercore

Hypercore is a secure, distributed, append-only log — the foundational primitive the whole Hypercore family is built on. Blocks are cryptographically verifiable (a Merkle tree over blake2b hashes), replication is sparse (peers fetch only the blocks they need) and realtime.

A core is identified by its public key. Peers find and announce each other on the discoveryKey (a hash of the key) — so you can locate a swarm without leaking the key itself.

Everything else in the family builds on Hypercore: Hyperbee and Hyperblobs each run on a single core; Corestore manages many; Hyperdrive and Autobase build on Corestore.

Core API

The load-bearing surface. See the README for exhaustive detail.

Create

const core = new Hypercore(storage, [key], [options])

storage is a directory path or a hypercore-storage instance.

const core = new Hypercore('./storage')
await core.append(Buffer.from('hello'))
const block = await core.get(0)

Read & write

• await core.append(block) — append block(s).
• await core.get(index, [opts]) — read a block (waits for download if sparse).
• await core.has(start, [end]) — is a block range present locally.
• await core.update([opts]) — wait for proof of a new length from peers.
• await core.truncate(newLength, [opts]) — shrink / fork the log.

Replication & sessions

• const stream = core.replicate(isInitiatorOrStream, [opts]) — replication.
• core.session([opts]) — shared session over the same core.
• core.snapshot() — read-only point-in-time view.

Properties

key, discoveryKey, length, byteLength, fork, writable, readable, signedLength.

Events

append, truncate, peer-add, peer-remove, upload, download.

Options worth knowing

Gotchas

Storage is RocksDB-backed now. As of v11, the old random-access-storage abstraction is no longer accepted — passing random-access-memory or random-access-file fails with TypeError: db.columnFamily is not a function. Storage is now hypercore-storage. Path-based storage auto-migrates to the new backend on open.

All cores are sparse. The sparse option was removed in v11; sparse is the only mode. “I have the length but not all the blocks” is a normal state.

signedLength (renamed from indexedLength in v11) is the length verified by the core’s signer(s). Multi-signer manifests (signers, quorum, hash algo) are what make multi-writer trust and signedLength meaningful.

Two encryption layers, distinct. Replication is always Noise-encrypted on the wire; block encryption (at-rest, content-private) is separate and opt-in via the encryption option (encryptionKey is deprecated in v11).

discoveryKey vs key. Announce and look up on the discoveryKey (a hash); the capability key is not exposed to the DHT.

Version

Current release is hypercore@11 (the RocksDB / hypercore-storage line). Across the Hypercore family the npm dist-tags are not a uniform “latest = newest major” — pin deliberately and check the registry before depending.

Sources

• Docs: docs.pears.com/building-blocks/hypercore
• Repo: github.com/holepunchto/hypercore (README + UPGRADE.md = the authoritative API reference)
• npm: hypercore