ravenclaw/research
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add Glossary

Browse Source
This commit is contained in:
Raven Scott
2026-02-19 21:51:45 -05:00
parent 73a56aad24
commit 953ec3618a
5 changed files with 1439 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Glossary/README.md
+580
View File
@@ -0,0 +1,580 @@
# Holepunch/Hypercore Ecosystem Glossary
A comprehensive glossary of terms, concepts, and technologies in the Holepunch peer-to-peer ecosystem.
---
## Table of Contents
1. [Core Data Structures](#1-core-data-structures)
2. [Networking & Protocol](#2-networking--protocol)
3. [Security & Cryptography](#3-security--cryptography)
4. [Runtime & Platform](#4-runtime--platform)
5. [Storage & Database](#5-storage--database)
6. [Replication & Sync](#6-replication--sync)
7. [Applications & Projects](#7-applications--projects)
8. [Development Tools](#8-development-tools)
9. [Infrastructure](#9-infrastructure)
10. [Advanced Concepts](#10-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:**
1. Both peers announce to DHT
2. Peers lookup each other's addresses
3. Both send SYN packets (blocked by NAT)
4. NATs see outgoing traffic, allow return
5. 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:**
```javascript
const core = new Hypercore('./local')
await core.append(data) // Works offline
swarm.on('connection', conn => core.replicate(conn)) // Sync later
```
**Multi-Device Sync:**
```javascript
const drive = new Hyperdrive(store, knownKey)
// Same key = same files on all devices
```
**Peer-to-Peer Identity:**
```javascript
const keyPair = Hypercore.generateKeyPair()
// Your identity is your key pair
```
---
## Related Documentation
- [Core Concepts](../core-concepts/) - Detailed concept explanations
- [Architecture](../architecture/) - System architecture
- [Interconnections](../interconnections/) - How components compose
- [Building Tools](../building-tools/) - Development tools
- [Existing Projects](../existing-projects/) - Real-world examples
---
*Last Updated: 2026-02-19*
Glossary/api-reference.md
+229
View File
@@ -0,0 +1,229 @@
# API Reference Glossary
Quick reference for key APIs and methods in the Holepunch ecosystem.
---
## Hypercore API
### Constructor
```javascript
new Hypercore(storage, key?, options?)
```
### Core Methods
| Method | Description |
|--------|-------------|
| `core.append(data)` | Append data to the feed |
| `core.get(index)` | Get block at index |
| `core.getBatch(start, end)` | Get range of blocks |
| `core.ready()` | Wait for feed to be ready |
| `core.replicate(isInitiator)` | Create replication stream |
### Properties
| Property | Description |
|----------|-------------|
| `core.length` | Number of blocks |
| `core.byteLength` | Total bytes |
| `core.key` | Public key (discovery) |
| `core.discoveryKey` | Hashed key for DHT |
| `core.signingKey` | Signing key pair |
### Events
| Event | Description |
|-------|-------------|
| `'append'` | New block added |
| `'ready'` | Feed ready |
| `'close'` | Feed closed |
| `'sync'` | Synced with peer |
---
## Hyperbee API
### Constructor
```javascript
new Hyperbee(core, options?)
```
### Core Methods
| Method | Description |
|--------|-------------|
| `db.put(key, value)` | Store key-value |
| `db.get(key)` | Retrieve value |
| `db.del(key)` | Delete key |
| `db.createReadStream()` | Iterate all keys |
| `db.createRangeStream()` | Range query |
### Options
| Option | Description |
|--------|-------------|
| `keyEncoding` | Key encoding (utf8, buffer, etc.) |
| `valueEncoding` | Value encoding (utf8, json, etc.) |
---
## Hyperdrive API
### Constructor
```javascript
new Hyperdrive(storage, key?)
```
### Core Methods
| Method | Description |
|--------|-------------|
| `drive.put(path, data)` | Write file |
| `drive.get(path)` | Read file |
| `drive.delete(path)` | Delete file |
| `drive.mkdir(path)` | Create directory |
| `drive.readdir(path)` | List directory |
| `drive.stat(path)` | Get file stats |
| `drive.diff(otherDrive)` | Compare drives |
### Properties
| Property | Description |
|----------|-------------|
| `drive.key` | Drive public key |
| `drive.version` | Current version |
| `drive.discoveryKey` | For swarm discovery |
---
## Hyperswarm API
### Constructor
```javascript
new Hyperswarm(options?)
```
### Core Methods
| Method | Description |
|--------|-------------|
| `swarm.join(topic, options?)` | Join topic |
| `swarm.leave(topic)` | Leave topic |
| `swarm.on('connection', fn)` | Handle connections |
### Options
| Option | Description |
|--------|-------------|
| `server` | Act as server for topic |
| `client` | Act as client for topic |
| `localOnly` | Only discover local peers |
### Events
| Event | Description |
|-------|-------------|
| `'connection'` | New peer connected |
| `'peer-found'` | Discovered new peer |
| `'update'` | Network updated |
### Connection Info
| Property | Description |
|----------|-------------|
| `info.peer` | Peer public key |
| `info.direct` | Is direct connection |
| `info.relayed` | Is relayed connection |
| `info.rate` | Connection rate |
| `info.latency` | Connection latency |
---
## Autobase API
### Constructor
```javascript
new Autobase(options)
```
### Options
| Option | Description |
|--------|-------------|
| `inputs` | Array of Hypercores |
| `localInput` | Local writer Hypercore |
| `view` | View implementation |
### Core Methods
| Method | Description |
|--------|-------------|
| `base.append(data)` | Append to local feed |
| `base.get(index)` | Get from merged view |
| `base.createReadStream()` | Stream merged view |
| `base.createLinearView()` | Linearized stream |
### Events
| Event | Description |
|-------|-------------|
| `'update'` | View updated |
| `'append'` | New entry added |
---
## Corestore API
### Constructor
```javascript
new Corestore(storage)
```
### Core Methods
| Method | Description |
|--------|-------------|
| `store.get(name)` | Get/create named core |
| `store.getCore(key)` | Get by key |
| `store.ready()` | Wait for ready |
| `store Namespace(name)` | Create namespace |
---
## HyperDHT API
### Constructor
```javascript
new DHT(options?)
```
### Core Methods
| Method | Description |
|--------|-------------|
| `dht.announce(key, address)` | Announce address |
| `dht.lookup(key)` | Find peers |
| `dht.unannounce(key)` | Remove announcement |
| `dht.query(target)` | Find nearby nodes |
---
## Protomux API
### Constructor
```javascript
new Protomux(connection)
```
### Core Methods
| Method | Description |
|--------|-------------|
| `mux.associate(protocol, handler)` | Add protocol |
| `mux.open(channel)` | Open channel |
| `mux.once('connection')` | Handle incoming |
---
*See [API Documentation](https://docs.pears.com/) for complete reference.*
Glossary/commands.md
+241
View File
@@ -0,0 +1,241 @@
# Command Reference
Quick reference for CLI commands in the Holepunch ecosystem.
---
## Pear Commands
### Installation
```bash
# Install Pear
npm install -g pear
# Check version
pear --version
```
### Application Management
```bash
# Create new app
pear init my-app
cd my-app
# Run app locally
pear run
# Build for platform
pear build ios
pear build android
pear build macos
pear build linux
pear build windows
# Package app
pear package
# Update Pear
pear update
```
### Project Commands
```bash
# Install dependencies
pear install
# List installed apps
pear list
# Uninstall app
pear uninstall <app-name>
```
---
## Hypershell Commands
### Server
```bash
# Start server
hypershell-server
# Start with custom port
hypershell-server --port 2222
```
### Client
```bash
# Connect to server
hypershell <server-public-key>
# File transfer
hypershell-copy <server-key>:/remote/file ./local/
# Port forwarding
hypershell-forward <server-key> 8080:localhost:80
```
---
## Hyperssh Commands
### Configuration
```bash
# Add to SSH config
# ~/.ssh/config
Host *.hyperssh
ProxyCommand hyperssh-proxy %h
```
### Connection
```bash
# Connect via P2P
ssh [email protected]
```
---
## Hyperbeam Commands
### File Transfer
```bash
# Send file
hyperbeam send ./large-file.zip
# Output: Key: abc123...
# Receive file
hyperbeam receive abc123... ./received.zip
# Send directory
hyperbeam send ./my-folder/
# With custom timeout
hyperbeam send --timeout 60 ./file.zip
```
---
## Simple Seeder Commands
### Basic Usage
```bash
# Seed a drive
simple-seeder hyper://abc123...
# Seed multiple drives
simple-seeder hyper://abc... hyper://def... hyper://ghi...
# Daemon mode
simple-seeder --daemon hyper://abc...
# With custom port
simple-seeder --port 3000 hyper://abc...
# Verbose output
simple-seeder --verbose hyper://abc...
```
---
## Hypercore CLI
### Create Feed
```bash
# Create new feed
hypercore create ./my-feed
# Open existing
hypercore open ./my-feed
# Append data
hypercore append ./my-feed "Hello World"
# Read all
hypercore read ./my-feed
# Read specific block
hypercore read ./my-feed 0
```
---
## DHT Commands
### Bootstrap
```bash
# Start DHT bootstrap node
hyperdht-bootstrap
# With custom port
hyperdht-bootstrap --port 10000
```
---
## Build Commands
### CMake Build
```bash
# Create build directory
mkdir build && cd build
# Configure
cmake ..
# Build
cmake --build .
# Install
cmake --install .
```
### Platform Builds
```bash
# iOS
cmake -G Xcode -DCMAKE_TOOLCHAIN_FILE=../cmake/ios.toolchain ...
# Android
cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/android.toolchain ...
# macOS
cmake -G Xcode ..
```
---
## NPM Scripts (Common)
```bash
# Install dependencies
npm install
# Run tests
npm test
# Run linter
npm run lint
# Build
npm run build
# Start dev server
npm run dev
# Package for Pear
npm run package
```
---
## Environment Variables
| Variable | Description |
|----------|-------------|
| `HYPERCORE_STORAGE` | Default storage path |
| `HYPERSWARM_BOOTSTRAP` | Bootstrap nodes |
| `DEBUG` | Enable debug output |
| `NODE_ENV` | Environment (development/production) |
---
*See [Building Tools](../building-tools/) for detailed tutorials.*
Glossary/index.md
+50
View File
@@ -0,0 +1,50 @@
# Glossary Directory
Comprehensive glossary and reference documentation for the Holepunch/Hypercore ecosystem.
## Contents
| File | Description |
|------|-------------|
| [README.md](README.md) | Main glossary with all terms and definitions |
| [api-reference.md](api-reference.md) | API method quick reference |
| [troubleshooting.md](troubleshooting.md) | Common issues and solutions |
| [commands.md](commands.md) | CLI command reference |
---
## Quick Links
### Core Terms
- **Hypercore**: Append-only log, the foundation of the ecosystem
- **Hyperbee**: Key-value database built on Hypercore
- **Hyperdrive**: Distributed filesystem
- **Autobase**: Multi-writer data structure
- **Hyperswarm**: P2P networking stack
- **HyperDHT**: Distributed Hash Table for peer discovery
### Key Concepts
- **Append-only log**: Data structure that can only be appended to
- **Merkle DAG**: Cryptographic tree for verification
- **Hole punching**: NAT traversal technique
- **CRDT**: Conflict-free Replicated Data Type
- **Causal ordering**: Ordering based on causality
### Getting Started
1. Read [README.md](README.md) for full glossary
2. Check [api-reference.md](api-reference.md) for method signatures
3. See [troubleshooting.md](troubleshooting.md) for common issues
4. Use [commands.md](commands.md) for CLI reference
---
## Related Documentation
- [Core Concepts](../core-concepts/) - Detailed concept explanations
- [Architecture](../architecture/) - System architecture
- [Interconnections](../interconnections/) - How components compose
- [Building Tools](../building-tools/) - Development tools
---
*Last Updated: 2026-02-19*
Glossary/troubleshooting.md
+339
View File
@@ -0,0 +1,339 @@
# Troubleshooting Guide
Common issues and solutions in the Holepunch/Hypercore ecosystem.
---
## Connection Issues
### Can't Find Peers
**Symptoms:**
- `swarm.on('connection')` never fires
- Peers not discovered
**Solutions:**
1. Check bootstrap nodes are running
2. Verify firewall allows outbound connections
3. Ensure correct discovery key
4. Try with `localOnly: false`
5. Check DHT bootstrap servers
```javascript
// Debug peer discovery
swarm.on('peer-found', console.log)
swarm.on('connection', (conn, info) => {
console.log('Connected:', info.peer.publicKey.toString('hex').slice(0, 8))
})
```
### Connection Drops
**Symptoms:**
- Connections close unexpectedly
- Frequent disconnects
**Solutions:**
1. Implement retry logic
2. Check network stability
3. Add keep-alive
4. Use relay fallback
```javascript
// Reconnection logic
swarm.on('connection', (conn) => {
conn.once('close', () => {
setTimeout(() => swarm.join(topic), 1000)
})
})
```
### NAT Traversal Fails
**Symptoms:**
- Can't connect directly
- Always relayed
**Solutions:**
1. Check NAT type (symmetric NAT is problematic)
2. Ensure UPnP enabled on router
3. Use relay servers as fallback
4. Consider TURN servers for enterprise networks
---
## Performance Issues
### Slow Sync
**Symptoms:**
- Initial sync takes very long
- High latency between peers
**Solutions:**
1. Increase `maxConnections`
2. Enable eager replication
3. Use batch operations
```javascript
const swarm = new Hyperswarm({
maxConnections: 64,
tcp: true,
utp: true
})
```
### Memory Growth
**Symptoms:**
- Memory usage increases over time
- Large feed causes crashes
**Solutions:**
1. Use sparse replication
2. Implement block eviction
3. Clear old peers
```javascript
// Sparse replication
const core = new Hypercore('./storage', key, {
sparse: true
})
// Only fetch blocks on demand
```
### Large Files Slow
**Symptoms:**
- File operations hang
- Transfer speed low
**Solutions:**
1. Use Hyperblobs with chunking
2. Enable compression
3. Increase buffer sizes
```javascript
// Chunk large files
const chunkSize = 64 * 1024 // 64KB chunks
```
---
## Data Issues
### Verification Fails
**Symptoms:**
- `Invalid signature` errors
- Data corruption detected
**Solutions:**
1. Check public key is correct
2. Verify Merkle proofs
3. Re-download from trusted peers
```javascript
const { block, proof } = await core.get(2, { value: true, proof: true })
const verified = Hypercore.verifyProof(proof, block, core.key)
```
### Feed Conflicts
**Symptoms:**
- Multiple forks detected
- Inconsistent state
**Solutions:**
1. Use single writer per feed
2. Use Autobase for multi-writer
3. Implement conflict resolution
### Replication Stuck
**Symptoms:**
- Peers connected but no data transfer
- Bitfields don't converge
**Solutions:**
1. Check network connectivity
2. Verify both peers have data
3. Restart replication
```javascript
const stream = core.replicate(true)
stream.on('data', () => console.log('Syncing...'))
```
---
## Cryptography Issues
### Key Not Found
**Symptoms:**
- Cannot open encrypted feed
- `Key not found` error
**Solutions:**
1. Backup encryption keys
2. Use key derivation correctly
3. Store keys securely
```javascript
const encryptionKey = crypto.randomBytes(32)
// Store this key securely!
const core = new Hypercore('./storage', { encryptionKey })
```
### Signature Invalid
**Symptoms:**
- Write operations fail
- Verification errors
**Solutions:**
1. Check signing key is valid
2. Verify key pair matches
3. Ensure proper key loading
---
## Storage Issues
### Corrupted Storage
**Symptoms:**
- Feed won't open
- Read errors
**Solutions:**
1. Delete and re-sync
2. Use storage validation
3. Implement backups
```javascript
// Backup before operations
await core.backup('./backup')
```
### Storage Full
**Symptoms:**
- Write operations fail
- No space left errors
**Solutions:**
1. Implement storage limits
2. Use block eviction
3. Archive old data
---
## Platform Issues
### Native Module Failures
**Symptoms:**
- `Module not found` errors
- Binary incompatible
**Solutions:**
1. Rebuild native modules
2. Check Node.js version compatibility
3. Use prebuilt binaries
```bash
npm rebuild
# Or for Bare
pear rebuild
```
### Mobile Issues
**Symptoms:**
- App crashes on iOS/Android
- Performance issues
**Solutions:**
1. Use Pear for mobile packaging
2. Check React Native compatibility
3. Test on physical devices
---
## Debug Mode
### Enable Debug Logging
```javascript
const swarm = new Hyperswarm({
localOnly: false,
debug: true
})
swarm.on('peer-found', console.log)
swarm.on('connection', (conn, info) => {
console.log('Connected:', info.peer.publicKey.toString('hex').slice(0, 8))
console.log('Direct:', info.direct)
console.log('NAT type:', info.nat)
})
```
### Network Debugging
```javascript
const dht = new DHT({ debug: true })
dht.on('lookup', console.log)
dht.on('announce', console.log)
```
### Core Debugging
```javascript
const core = new Hypercore('./storage', {
onwait: (index) => console.log('Waiting for block', index),
ondownload: (index) => console.log('Downloaded block', index),
onupload: (index) => console.log('Uploaded block', index)
})
```
---
## Common Error Codes
| Error | Description | Solution |
|-------|-------------|----------|
| `EKEYNOTFOUND` | Key not found | Check encryption key |
| `ESIGNATURE` | Invalid signature | Verify public key |
| `ENOENT` | No such entry | Check index |
| `ECONNRESET` | Connection reset | Retry connection |
| `ETIMEDOUT` | Connection timeout | Check network |
| `ENOPEERS` | No peers found | Check DHT |
---
## Best Practices Checklist
### Development
- [ ] Use debug logging in development
- [ ] Handle all error events
- [ ] Implement reconnection logic
- [ ] Test with multiple peers
### Production
- [ ] Backup encryption keys
- [ ] Monitor memory usage
- [ ] Set connection limits
- [ ] Use sparse replication for large feeds
- [ ] Implement health checks
### Security
- [ ] Verify all signatures
- [ ] Use encrypted connections
- [ ] Validate all input
- [ ] Rotate keys periodically
---
*See [Core Concepts](../core-concepts/) for detailed explanations.*