add Glossary
This commit is contained in:
Raven Scott
@@ -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*
|
||||
@@ -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.*
|
||||
@@ -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.*
|
||||
@@ -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*
|
||||
@@ -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.*
|
||||
Reference in New Issue
Block a user