Hypercore: a signed append-only log for peer-to-peer data

The problem Hypercore solves: one writer, many readers, no full copy

A conventional database assumes every reader can reach the same server and that the server holds the whole dataset. Hypercore takes the opposite position. It models data as an append-only log owned by a key pair, where the holder of the secret key can append and anyone holding the public key can read and verify. The README describes it as "a secure, distributed append-only log" built for "sharing large datasets and streams of real time data".

The intended user is a JavaScript developer building a peer-to-peer application who needs a log primitive underneath. The README is explicit that the project is modular and aims "to do one thing and one thing well". There is no query engine, no schema, no server process. If you want to publish a feed that a thousand peers can each read a slice of, and you want each peer to be able to prove the slice was not tampered with, that is the case Hypercore is designed for. If you want a database with indexes, it is not.

The sparse replication feature is the part that changes the economics. A reader does not download the whole log before it can use it. The README lists sparse replication first among the features: "Only download the data you are interested in." That matters when the log is large and each consumer only needs a subset.

How the log verifies itself: signed merkle trees and the manifest

Every block appended to a Hypercore is committed into a merkle tree, and the tree root is signed. The README states the project uses "signed merkle trees to verify log integrity in real time". Verification does not require trusting the peer that served the block, because a reader can check the block against a tree hash that chains back to the signed root.

The key that identifies a Hypercore is not a plain public key. The README says the key "is a hash of Hypercore's internal auth manifest, describing how to validate the Hypercore". The manifest is a structured object with fields including version, hash (only blake2b is supported currently), allowPatch, quorum, signers, prologue, linked and userData. Signers are objects carrying a signature method (ed25519), a cryptographic namespace, and a public key. The default is a single signer, and quorum is computed as half the signers plus one.

Two manifest fields deserve attention because they have consequences. The linked field references other Hypercore keys associated with the current core; the README notes that autobase loads its encryption view from the linked property of the system view core. The userData field is an arbitrary buffer integral to the core. Both are version 2 manifest features. The README warns that changing linked changes the core's key, which means a reader's stored key stops matching. That is a design decision with a real cost: association between cores is baked into identity rather than tracked separately.

Installing Hypercore and appending your first block

The README gives a single install command. It is a standard npm package, published as hypercore, and the current package.json lists version 11.37.0.

npm install hypercore

The constructor takes a storage directory, an optional key, and an options object. Passing a path creates or loads a log stored in that directory. If no key is supplied and nothing is stored, the README says a new auth manifest is generated, which gives the local process write access.

const Hypercore = require('hypercore')

const core = new Hypercore('./directory') // store data in ./directory

Appending is a call to core.append, which accepts a single block or an array of blocks and returns the new length and byte length. The README shows both forms.

// simple call append with a new block of data
await core.append(Buffer.from('I am a block of data'))

// pass an array to append multiple blocks as a batch
await core.append([Buffer.from('batch block 1'), Buffer.from('batch block 2')])

By default blocks are stored as binary. Setting valueEncoding to 'json', 'utf-8' or 'binary' changes how individual blocks are encoded, and the README notes that valueEncoding applies to individual blocks even when you append a batch. If you need batch-level control, encodeBatch is a function that takes a batch and returns a binary-encoded batch. The README states that a custom valueEncoding is not applied before encodeBatch, so the two options do not compose the way a reader might first assume.

The repository ships an examples directory containing basic.js, announce.js, http.js, lookup.js and mark-n-sweep.js. Those files are the closest thing to a worked end-to-end path in the repository, and reading basic.js is a faster way to see the intended shape than reading the API list.

Storage is not interchangeable between version 9 and version 10

The README makes one compatibility statement that should govern any adoption decision: "Note that the latest release is Hypercore 10, which adds support for truncate and many other things. Version 10 is not compatible with earlier versions (9 and earlier), but is considered LTS, meaning the storage format and wire protocol is forward compatible with future versions."

The claim is asymmetric. Forward compatibility means data written by version 10 can be read by later versions. It does not mean version 10 can read data written by version 9. There is an UPGRADE.md file at the top level of the repository, which is the place to look for the migration path, but the README itself does not document rollback. Anyone holding a large log written under version 9 should treat the upgrade as a one-way move until they have read UPGRADE.md.

There is a second storage constraint in the README: random-access-storage is no longer supported. The supported paths are a Hypercore Storage instance or a Corestore when you want many Hypercores efficiently. Code written against the older random-access-storage interface will need rework, not just a version bump. The README does not describe a shim.

A third constraint is the manifest version. The linked and userData manifest fields are only supported in versions 2 and above, so a core with a version 1 manifest cannot carry linked cores. Nothing in the README suggests automatic manifest upgrading.

What Hypercore deliberately does not do

Hypercore is a log. It has no notion of deleting a block in the middle, no secondary index, and no query interface. Truncation exists as of version 10, but truncation removes the tail; it is not a way to edit history. A block that has been appended and replicated to peers cannot be un-replicated, because a peer that already holds the block holds it independently of the writer.

The project also does not provide peer discovery or transport in the README's install and API sections. The dependency list includes @hyperswarm/secret-stream, which handles the encrypted stream, but the README's guidance for connecting cores is not present. The examples directory contains announce.js and lookup.js, which by their names suggest the discovery path, but the README does not walk through them. A developer expecting a batteries-included sync layer will find that the log is the batteries and the wiring is theirs to write.

Sparse replication has a cost that the README does not quantify. A reader that wants one block still needs the tree path to verify it, and the README does not describe how much of the tree must be fetched. The inflightRange option, described as an advanced option setting the minimum and maximum inflight blocks per peer, is the only tuning knob mentioned for download behavior. The README does not give guidance on choosing those values.

Finally, writable: true is the default and the option can be set to false to disable appends and truncates. That is a local guard, not a cryptographic one. The manifest's signers are what actually determine who can produce valid blocks.

Hypercore compared with a content-addressed store

A content-addressed store such as a plain IPFS-style block store identifies each piece of data by its own hash and lets any node hold any block. Hypercore identifies the whole log by a key derived from its auth manifest, and blocks are ordered positions in that log. The difference shows up in what you can prove and what you can update.

In a content-addressed store, a reader who fetches a block can verify it immediately against its own hash, with no context. In Hypercore, a reader verifies a block against a merkle tree whose root is signed by the log's signer, which means the reader must know the log's key and must fetch enough tree nodes to connect the block to the root. The README's sparse replication feature is built on exactly this: fetch the block, fetch the path, check against the signed root.

The second difference is mutability of the head. A content-addressed store has no head; the set of blocks is whatever has been published. A Hypercore has a length, and append returns the new length and byte length. Consumers follow a moving head, and the README lists realtime updates as a feature: "Get the latest updates to the log fast and securely." If your problem is publishing immutable artifacts, the content-addressed model is simpler because there is no signer to manage and no head to follow. If your problem is a feed that grows over time with one authoritative writer, Hypercore's ordering and signing are the point.

Licence and the cost of keeping up

Hypercore is MIT licensed, per both the README's repository metadata and the LICENSE file at the top level. MIT permits use, modification and redistribution with the licence and copyright notice retained. That is permissive and imposes no copyleft obligation on your application. This is a description of the licence text, not legal advice; if you are redistributing modified source, read the LICENSE file.

The maintenance picture from the repository facts: the last push was on 2026-09-23, and the most recent release is v11.37.0 from 2026-09-23, with v11.36.1 and v11.36.0 both on 2026-09-10. The repository is not archived. The README's own statement that version 10 is LTS and forward compatible with future versions is the strongest signal about upgrade cost: the storage format and wire protocol are intended not to break again. The major version is now 11, which means at least one major bump has happened since that LTS statement was written, and the README does not explain what changed between 10 and 11. UPGRADE.md is the file to read before a major-version jump.

Dependency surface is worth counting. The package.json lists around twenty runtime dependencies, including sodium-universal for cryptography, compact-encoding, hypercore-storage, protomux and streamx. Each is a moving part in a security-sensitive path. Pinning and auditing them is part of the operating cost, and the README does not provide a supported-versions matrix for the dependency set.

Editorial conclusion

Adopt Hypercore when you need an append-only log that a peer can replicate sparsely and verify block by block, and you are willing to write the peer discovery and transport layer yourself, since the README points at a Hypercore Storage instance or a Corestore rather than a running network. Do not adopt it if you need a general database, a query language, or a drop-in sync server; the README describes the project as doing one thing, distributing a stream of data, and the API is a log, not a store. Before committing, verify which storage format your existing data uses, because the README states version 10 is not compatible with 9 and earlier, and check the UPGRADE.md file in the repository for the migration path rather than assuming an in-place upgrade.

Frequently asked questions

Official sources

1. holepunchto/hypercore on GitHub
2. License: MIT
3. Project website
4. README
5. Releases