Holepunch/Hypercore Ecosystem Glossary
A comprehensive glossary of terms, concepts, and technologies in the Holepunch peer-to-peer ecosystem.
Table of Contents
- Core Data Structures
- Networking & Protocol
- Security & Cryptography
- Runtime & Platform
- Storage & Database
- Replication & Sync
- Applications & Projects
- Development Tools
- Infrastructure
- Advanced Concepts
1. Core Data Structures
Hypercore
The fundamental distributed append-only log in the Holepunch ecosystem. Hypercore is an authenticated data structure that maintains a cryptographically signed chain of data blocks. Each block is linked to the previous via Merkle tree roots, ensuring integrity and enabling efficient replication.
Key Properties:
- Append-only: Data can only be added, never modified or deleted
- Signed: Each root is signed with Ed25519
- Verifiable: Merkle tree enables integrity verification
- Replicated: Bitfield-based synchronization between peers
- Encrypted: Optional per-block encryption
Use Cases: Event streams, chat messages, audit trails, simple databases
Merkle DAG (Merkle Directed Acyclic Graph)
A tree structure where each leaf is a data block and each parent is the cryptographic hash of its children. The Merkle DAG enables efficient verification of data integrity without downloading entire datasets.
Structure:
Root Hash (signed)
│
┌─────┴─────┐
│ │
┌───┴───┐ ┌───┴───┐
│ │ │ │
┌─┴─┐ ┌─┴─┐ ┌─┴─┐ x
│ │ │ │ │ │
B0 B1 B2 B3 B4
Append-Only Log
A data structure where data can only be added to the end, never modified or deleted from the middle. This provides integrity guarantees because historical data cannot be altered.
Benefits:
- Integrity: History cannot be altered
- Replication: Simple sync protocol
- Verification: Cryptographic proof of contents
- Caching: Blocks can be cached indefinitely
- Conflict-free: No merge conflicts
Hyperbee
A key-value database built on Hypercore using a B-tree index. Hyperbee provides sorted key-value storage with efficient range queries and indexing capabilities.
Features:
- Structure: Sorted key-value store
- Index: B-tree over Hypercore
- Diffing: Via hyperbee-diff-stream
- Use case: Database indices, file trees
Hyperdrive
A distributed filesystem built on Hypercore. Hyperdrive combines Hyperbee for metadata and Hyperblobs for content, providing versioned file storage with complete history.
Features:
- Structure: Hyperbee (metadata) + Hyperblobs (content)
- Blobs: Separate blob storage for large files
- Versioning: Complete history of changes
- Diffing: Drive-to-drive comparisons
Autobase
A multi-writer data structure that merges multiple Hypercore feeds into a single causal stream. Autobase uses Lamport timestamps to ensure causal ordering and provides automatic view merging for collaborative applications.
Features:
- Ordering: Causal via Lamport timestamps
- Merge: Automatic view merging
- Use case: Collaborative editing, CRDTs
Hyperblobs
Binary large object storage built on Hypercore. Hyperblobs handles large binary files efficiently by chunking content into smaller pieces.
Use Cases: Media files, large datasets, images, videos
Corestore
A storage manager for multiple Hypercores. Corestore provides deduplicated core storage with key namespacing and batch operations.
Features:
- Storage: Deduplicated core storage
- Namespacing: Key namespaces
- Efficiency: Batch operations
Feed
A synonym for Hypercore - an append-only log that forms the basis of data storage in the ecosystem. Each feed has a unique public key used for discovery and verification.
2. Networking & Protocol
Hyperswarm
The high-level P2P networking API in the Holepunch ecosystem. Hyperswarm provides topic-based peer discovery, automatic hole punching for NAT traversal, connection encryption via Noise protocol, and connection pooling.
Features:
- Discovery: Topic-based peer discovery
- Hole punching: NAT traversal
- Encryption: Noise protocol
- Pooling: Connection management
HyperDHT
The Distributed Hash Table implementation using the Kademlia protocol. HyperDHT enables decentralized peer discovery by storing and retrieving peer addresses associated with public keys.
Features:
- Structure: Kademlia DHT
- Keys: Ed25519 public keys
- Persistence: Persistent node IDs
- Queries: Find peers by key
DHT (Distributed Hash Table)
A distributed system for peer discovery. The DHT allows peers to find each other without centralized servers by maintaining a mapping of keys to peer addresses across the network.
Kademlia
The specific DHT algorithm implemented by HyperDHT. Kademlia uses XOR distance to organize nodes into a binary tree structure, enabling efficient lookups in O(log n) time.
Hole Punching
A NAT traversal technique where two peers behind NATs simultaneously attempt to connect to each other, causing the NATs to create mappings that allow the return traffic.
Process:
- Both peers announce to DHT
- Peers lookup each other's addresses
- Both send SYN packets (blocked by NAT)
- NATs see outgoing traffic, allow return
- Direct connection established
NAT (Network Address Translation)
A technique where a router hides private IP addresses behind a public IP. NAT enables multiple devices to share one public IP but complicates P2P connections.
NAT Types:
| Type | Behavior | Punchable? |
|---|---|---|
| Full Cone | Any external can connect | ✅ Yes |
| Restricted Cone | Must send first | ✅ Yes |
| Port Restricted | Must send to specific port | ✅ Yes |
| Symmetric | Random ports per peer | ❌ Hard |
Protomux
Protocol multiplexing layer that enables multiple protocols to run over a single encrypted stream. Protomux provides length-prefixed message framing and backpressure/flow control.
Features:
- Multiplexing: Multiple protocols over single stream
- Framing: Length-prefixed messages
- Backpressure: Flow control
HRPC (Hyper RPC)
A remote procedure call protocol built on Protomux. HRPC provides a simple way to define and invoke procedures between peers.
UDX (UDP Datagram Extensions)
A high-performance UDP-based data transfer library. UDX provides reliable UDP transmission with congestion control, similar to TCP but more efficient for P2P scenarios.
Features:
- Reliable UDP: TCP-like reliability
- Congestion Control: Modern CC algorithms
- Zero-Copy: Efficient memory use
- Cross-Platform: All major platforms
Noise Protocol
A framework for secure key exchange and encrypted communication. Hyperswarm uses Noise_XX for connection encryption.
Handshake Pattern (Noise_XX):
Initiator Responder
──────── ─────────
│ │
├── e ---------------------> │ (ephemeral key)
│ │
│<── e, ee, s, es ---------│ (ephemeral + static)
│ │
├── s, se ---------------->│ (static key)
│ │
│<── [encrypted data]──────│ (secure channel)
Relay
A fallback connection method when direct hole punching fails. Relays forward traffic between peers that cannot connect directly.
3. Security & Cryptography
Ed25519
An elliptic curve digital signature algorithm used for signing Hypercore feeds. Ed25519 provides fast signing and verification with strong security guarantees.
Use in Ecosystem:
- Feed signing
- Key authentication
- Identity verification
XSalsa20
A stream cipher used for per-block encryption in Hypercore. XSalsa20 provides fast, symmetric encryption for content privacy.
Blake2b
A cryptographic hash function used for deriving discovery keys from public keys. Blake2b is faster than SHA-256 while providing similar security.
Discovery Key
A hashed version of a Hypercore's public key used for DHT lookups. The discovery key is derived using Blake2b to allow public peer discovery while keeping the actual public key private.
Signature
A cryptographic proof that authenticates data as being created by the holder of a specific private key. Hypercore uses Ed25519 signatures for authentication.
Capability-Based Security
A security model where access is granted through capabilities (tokens) that specify allowed operations. Capabilities can be scoped, time-limited, and revoked.
Merkle Proof
A cryptographic proof that verifies a specific block exists in a Merkle tree. Merkle proofs enable efficient verification without downloading entire datasets.
Forward Secrecy
A security property where compromising one key does not compromise past communications. The Noise protocol provides forward secrecy through ephemeral key exchanges.
4. Runtime & Platform
Bare
A minimal, cross-platform JavaScript runtime designed for embedding and P2P applications. Bare provides the core APIs needed for P2P applications while maintaining a small footprint.
Size: ~30MB Startup: Fast Platforms: iOS, Android, Desktop, WebKit
Core I/O Modules:
| Module | Purpose | Node.js Equivalent |
|---|---|---|
| bare-fs | File system | fs |
| bare-path | Path utilities | path |
| bare-os | OS interfaces | os |
| bare-stream | Streams | stream |
| bare-buffer | Buffers | buffer |
| bare-events | Event emitters | events |
| bare-timers | Timers | timers |
Network Modules:
| Module | Purpose |
|---|---|
| bare-tcp | TCP sockets |
| bare-udp | UDP sockets |
| bare-tls | TLS/SSL |
| bare-http1 | HTTP/1.1 |
| bare-fetch | Fetch API |
Pear
The flagship application runtime for building and distributing P2P applications. Pear extends Bare with application lifecycle management, IPC, sidecar services, and automatic updates.
Components:
- pear: Main platform (CLI, sidecar, subsystems)
- pear-api: Runtime API interface
- pear-cli: Command-line interface
- pear-sidecar: Background service
- pear-bridge: IPC bridge
- pear-desktop: Desktop UI runtime
- pear-terminal: Terminal UI runtime
- pear-electron: Electron integration
- pear-bundle: Application bundling
- pear-pack: Package creation
- pear-updater: Update system
Bare Runtime
See "Bare" above.
Pear Platform
See "Pear" above.
React Native
A framework for building mobile apps using React. Holepunch provides Bare integration for React Native via bare-kit and react-native-bare-kit.
Node.js Compatibility
While Holepunch modules are designed for Bare, many work in Node.js with some limitations. The hyper* modules are Node.js compatible.
5. Storage & Database
Hypercore Storage
The underlying storage system using RocksDB. Hypercore uses RocksDB for efficient persistent storage of append-only logs.
RocksDB
An embedded key-value store optimized for fast storage. Hypercore uses RocksDB as its default storage backend.
B-tree Index
A sorted tree data structure that maintains sorted key-value pairs. Hyperbee uses B-trees over Hypercore for efficient range queries.
Key-Value Store
A database that stores data as key-value pairs. Hyperbee provides key-value storage with sorting and range queries.
Blob Storage
Storage for binary large objects. Hyperblobs provides chunked storage for files that are too large for Hypercore blocks.
Encryption Key
A key used to encrypt Hypercore blocks. Per-block encryption ensures content privacy even if the underlying storage is compromised.
6. Replication & Sync
Bitfield Synchronization
An efficient replication protocol where peers exchange bitfields indicating which blocks they have. This allows precise determination of what data needs to be transferred.
Peer A bitfield: [1, 1, 1, 1, 0, 0, 0] (has blocks 0-3)
Peer B bitfield: [1, 1, 0, 0, 1, 1, 0] (has blocks 0-1, 4-5)
Missing:
- Peer A needs: 4, 5
- Peer B needs: 2, 3
Sparse Replication
A replication mode where only specific blocks are downloaded on demand, rather than the entire feed. Useful for large datasets.
Linear Replication
Sequential replication from the start of a feed. Used for initial full synchronization.
Live Replication
Continuous replication where new blocks are automatically synced as they are appended.
Eager Replication
Pre-fetching blocks ahead of requests to minimize latency.
Replication Stream
A stream-based interface for replicating Hypercore data between peers.
7. Applications & Projects
Keet
The flagship P2P video conferencing and messaging application by Holepunch. Keet provides end-to-end encrypted video calls, persistent chat, and file sharing.
Website: keet.io
Technologies:
- Video Calls: WebRTC + P2P
- Messaging: Hypercore
- File Sharing: Hyperdrive
- Payments: Bitcoin Lightning Network
- Mobile: React Native
Hypershell
A P2P remote shell and SSH alternative built on Hyperswarm. Hypershell enables direct terminal access without servers.
Features:
- P2P Shell: Remote terminal access
- No Servers: Direct peer connections
- Key Auth: Ed25519 key authentication
- File Transfer: Built-in SCP-like functionality
- Port Forwarding: TCP tunneling
Hyperssh
SSH over Hyperswarm - a bridge between traditional SSH and P2P networking.
Features:
- SSH over P2P: Connect via Hyperswarm
- Proxy Command: Drop-in SSH replacement
- Key Management: Automatic key exchange
- Fallback: Relay if direct fails
Autopass
A P2P password manager with secure sharing capabilities built on Hyperdrive.
Features:
- Password Vault: Hyperdrive encrypted storage
- Sync: Hyperswarm multi-device sync
- Sharing: Autobase for secure credential sharing
- Mobile: React Native iOS/Android apps
- Generator: Secure password generation
Hyperbeam
A P2P data transfer tool for moving files between devices without cloud intermediaries.
Features:
- P2P Transfer: Direct device-to-device
- No Cloud: No intermediary servers
- End-to-End: Encrypted transfer
- Simple CLI: Easy command-line usage
- Resume: Interrupted transfer recovery
Simple Seeder
A lightweight tool for seeding Hyperdrive content, keeping files available on the network.
Features:
- Seed Drives: Keep Hyperdrives available
- Persistent: Run as daemon
- Multiple: Seed many drives
- Stats: Track seeding metrics
Pear Radio
A music streaming component built on Pear platform.
Gitea
Self-hosted Git service. Holepunch provides integration for P2P Git operations.
8. Development Tools
CMake
A cross-platform build system used for building native components. Holepunch provides CMake modules for various platforms.
CMake Modules:
- cmake-ios: iOS builds
- cmake-macos: macOS builds
- cmake-windows: Windows builds
- cmake-android: Android builds
- cmake-bare: Bare runtime builds
- cmake-pear: Pear builds
- cmake-napi: Native addon builds
Compact Encoding
A compact binary serialization format with schema definitions and cross-language bindings.
Features:
- Format: Compact binary
- Schema: Type definitions
- Cross-language: Multiple bindings
HRPC Server
A server implementation for HRPC (Hyper RPC) protocol.
Drive Mirror
A tool for mirroring Hyperdrive content to/from local filesystems.
UDX Chat
A chat application built using UDX for reliable UDP communication.
Swarm Chat
A chat application built using Hyperswarm for peer discovery.
CMake Addon
A template for creating native addons with CMake.
9. Infrastructure
Bootstrap Nodes
Nodes that help new peers join the network by providing initial peer addresses. Bootstrap nodes are hardcoded in the software.
Relay Servers
Servers that relay traffic between peers that cannot connect directly. Used as fallback when hole punching fails.
DHT Relay
See "Relay" above.
Seeding
The process of making Hypercore/Hyperdrive content available to other peers on the network.
Discovery
The process of finding peers that have a specific Hypercore or topic.
Topic
A public key used for peer discovery. Topics allow groups of peers to find each other.
10. Advanced Concepts
CRDT (Conflict-free Replicated Data Type)
Data structures that merge consistently without coordination. CRDTs enable collaborative editing without conflicts.
Types:
| Type | Examples | Merge Strategy |
|---|---|---|
| State-based | G-Set, LWW-Register | Union, last-writer-wins |
| Op-based | Counter, Set | Operation replay |
| Delta-state | All types | Delta synchronization |
Lamport Timestamp
A logical clock used to track causality in distributed systems. Autobase uses Lamport timestamps to order operations.
Causal Ordering
Ensuring that if operation A happened before operation B, then A appears before B in the final order. Causal ordering is weaker than total ordering but sufficient for most applications.
Total Ordering
A strict ordering where all peers see operations in exactly the same order. Autobase provides total ordering through deterministic tie-breaking.
Multi-Writer
A scenario where multiple users can append to the same logical data structure. Autobase enables multi-writer scenarios.
Offline-First
An application architecture where operations work offline and sync when connectivity is restored. Hypercore's append-only nature enables offline-first design.
Capability
A token that grants specific permissions. Capabilities in Hyperswarm can specify read/write access with optional expiration.
Sparse Replication
Only downloading portions of data on demand, rather than the entire dataset.
Delta-State
A CRDT variant that synchronizes only the changes (deltas) rather than full state.
State-Based CRDT
A CRDT that merges by taking the union of states. Examples include G-Set (Grow-only Set) and LWW-Register (Last-Writer-Wins Register).
Operation-Based CRDT
A CRDT that replicates operations rather than state. Examples include counters and sets.
Quick Reference
Choosing the Right Data Structure
| Need | Solution |
|---|---|
| Simple event/message log | Hypercore |
| Key-value storage with queries | Hyperbee |
| File sharing/distribution | Hyperdrive |
| Multiple writers collaborating | Autobase |
| Large binary files | Hyperblobs |
| Complex database needs | Hyperbee + Autobase |
Key Modules by Category
Data Layer:
- hypercore: Append-only log
- hyperbee: Key-value database
- hyperdrive: Distributed filesystem
- autobase: Multi-writer
- hyperblobs: Binary storage
Network Layer:
- hyperswarm: P2P networking
- hyperdht: Distributed hash table
- protomux: Protocol multiplexing
- hyperswarm-secret-stream: Encrypted streams
Runtime:
- bare: Minimal JS runtime
- pear: Application platform
Common Patterns
Offline-First:
const core = new Hypercore('./local')
await core.append(data) // Works offline
swarm.on('connection', conn => core.replicate(conn)) // Sync later
Multi-Device Sync:
const drive = new Hyperdrive(store, knownKey)
// Same key = same files on all devices
Peer-to-Peer Identity:
const keyPair = Hypercore.generateKeyPair()
// Your identity is your key pair
Related Documentation
- Core Concepts - Detailed concept explanations
- Architecture - System architecture
- Interconnections - How components compose
- Building Tools - Development tools
- Existing Projects - Real-world examples
Last Updated: 2026-02-19