13 KiB
P2NS Glossary
This glossary defines key terms and concepts used throughout P2NS documentation.
P2NS Core Concepts
P2NS (Peer-to-Peer Name System)
A decentralized DNS alternative that resolves domain names to IP addresses using peer-to-peer consensus rather than centralized DNS servers. Enables users to claim domains, share them across a P2P network, and resolve them locally.
Domain Claim
A record in the distributed ledger asserting ownership of a domain. Claims are stored as claim:{domain}:{claimant} entries containing the Holesail hash, timestamp, service clients, and SSL flag. Multiple peers can claim the same domain; consensus determines the winner. Note: Internal domains (automatically discovered from plugin-sites/{domain}/config.json files) cannot be claimed and are reserved for local use only.
Vote
A record supporting a specific domain claimant. Votes are stored as vote:{domain}:{claimant}:{voter} entries. Peers vote to support claims they trust, and consensus uses vote counts to resolve ownership disputes.
Auto-Vote
Automatic voting performed by P2NS when certain conditions are met. The system automatically votes for claims when a peer joins the network or when new claims are discovered, based on configured rules.
Consensus
The process of determining which claimant owns a domain when multiple claims exist. Uses quorum-based voting over an Autobase apply view; Autopass KV remains the durable write store. See CONSENSUS.md and RFC 0001.
Consensus Sidecar
The consensus Autobase instance (p2ns-consensus Corestore namespace) that replays typed claim/vote events and maintains the in-memory view used by getConsensusState. Bootstrapped from dnsPass on first run; joiners replicate via consensusAutobaseKey in the network manifest.
Quorum
The minimum number of votes required for consensus to be valid. Calculated as max(MIN_VOTES, ceil(activePeers * THRESHOLD)). Prevents decisions from being made with insufficient participation.
Internal Domain
A domain served locally by a P2NS plugin. Internal domains are automatically discovered from plugin-sites/{domain}/config.json files. Examples: p2ns.admin, peer.directory, global.profile.
P2P Domain
A domain resolved through the P2P network via consensus. P2P domains are claimed by peers and resolved to Holesail connections that tunnel traffic to the domain owner's server.
Version Preference
When a domain exists both as a P2P claim and in public DNS, users can choose which version to resolve. Preferences are stored in selector_cache.json and can be set to p2p or public.
DNS Conflict
A domain that has both a P2P claim and a public DNS record. P2NS detects these conflicts and allows users to choose which version to use via the admin interface.
P2P Domain Conflict
A domain where multiple users have P2P claims, and consensus resolved to a different claimant than the local user. Users can choose between using their local claim hash or the consensus-resolved hash.
Hash Preference
For domains with P2P consensus conflicts, users can choose whether to use their local claim hash ('local') or the consensus-resolved hash ('resolved'). Stored in selector_cache.json alongside version preferences. Automatically cleaned up when conflicts resolve or local claims are removed.
Claim Ownership
The principle that only the peer that created a claim can modify or remove it. Ownership is verified by matching the claimant ID in the claim key (claim:domain:claimant) before any operation. Prevents unauthorized claim overwriting or deletion.
Conflict Claim Removal
When removing a domain where you have a claim but aren't the resolved claimant, only your own claim and votes are removed. A removeConflictDomainClaim: notification is broadcast to other peers, who update their consensus state but preserve their own claims.
Resolved Claimant Removal
When removing a domain where you are the resolved claimant, all claims and votes for the domain are removed. A consensus.removeDomain RPC event is broadcast to trigger other peers to clean up their own claims as well.
Hybrid DNS
P2NS's approach to DNS resolution that combines P2P domain resolution with fallback to public DNS servers. Local DNS records take priority, followed by P2P consensus, then public DNS.
Holepunch Ecosystem
P2NS is built on the Holepunch ecosystem of P2P technologies.
Hyperswarm
The P2P networking layer that enables peer discovery and connection. Uses DHT (Distributed Hash Table) for peer discovery and handles NAT traversal. P2NS uses Hyperswarm to connect peers and replicate data.
Hypercore
An append-only log data structure that forms the foundation of Holepunch storage. Each entry is cryptographically signed and linked, creating a tamper-proof history. Used internally by Hyperbee, HyperDB, and Hyperdrive.
Hyperbee
A key-value store built on Hypercore. Provides B-tree indexing for efficient lookups. P2NS uses Hyperbee (via Autopass) to store domain claims and votes.
HyperDB
A document database for P2NS plugins. Supports schemas, collections, indexes, and queries. Enables plugins to store and replicate structured data across peers. See plugins/HYPERDB.md.
Hyperdrive
A distributed file system built on Hypercore. Enables plugins to store and share files across the P2P network. Supports file operations, directory structures, and replication. See plugins/HYPERDRIVE.md.
Autopass
A distributed ledger built on Hyperbee used for storing domain claims and votes. Provides the durable write store for P2NS consensus; claim/vote mutations dual-append events to the consensus Autobase sidecar for deterministic reads.
Autobase
Holepunch's multi-writer log with an apply function. P2NS uses a dedicated Autobase sidecar to linearize claim/vote events and maintain the consensus read view. See RFC 0001.
Corestore
Storage management for multiple Hypercores. Handles persistence, caching, and lifecycle of cores. P2NS uses Corestore to manage storage for Autopass, HyperDB, and Hyperdrive instances.
Plugin RPC
The only peer-to-peer transport for plugin protocols. Each plugin registers named JSON methods on {pluginDomain}-{protocol}-rpc. Distinct from legacy protomux message channels (removed). See plugins/PLUGIN_CHANNELS.md.
Core request RPC
Control-plane RPC on p2ns.core-request-rpc for invites (invite.request, invite.deliver, invite.ack, …) and consensus events. Joiner lifecycle uses registerPluginProtocol for the request protocol (RPC open triggers invite flow).
Genesis master
The first node that creates a network's Autopass (--master --genesis). Writes cache/network.json with the network identity (networkId from Autopass discovery key). Only one genesis per network.
Secondary master
A node running --master without --genesis on empty storage. Pairs into the existing network via invite instead of creating a new Autopass. Has the same invite and reconnect behavior as genesis masters after pairing.
Network manifest
File (default cache/network.json) recording networkId, topicSeed, consensusAutobaseKey, and genesis metadata so all nodes on a network share one Autopass universe and consensus sidecar. Admin diagnostics warn if peers report mismatched networkId values.
Holesail
Holesail provides UDP hole-punching for P2P tunneling.
Holesail
A library for creating encrypted P2P tunnels through firewalls and NATs using UDP hole-punching. Enables direct connections between peers without requiring port forwarding or public IP addresses.
Holesail Server
A Holesail instance that exposes a local service (HTTP, TCP, UDP) to the P2P network. Generates a connection hash that clients use to connect. Created via the admin interface or SDK.
Holesail Client
A Holesail instance that connects to a remote server using its connection hash. Creates a local port that tunnels traffic to the remote service. Used to access P2P domains.
Connection Hash
A unique identifier for a Holesail server, formatted as hs://{hash}. The hash is derived from cryptographic keys and enables peers to discover and connect to the server. Example: hs://s00084bf87dfa89a3048fb081c0e6207eb5a.
Service
A named endpoint within a domain claim. Services allow a single domain to expose multiple Holesail connections on different ports. Each service has a serviceName, key (hash), port, and protocol.
Service Subscription
Automatic connection to services published by domain owners. When subscribed, P2NS creates Holesail clients for the domain's services. "Subscribe All" automatically subscribes to all current and future services.
Networking
Virtual Interface
An IP alias created on the loopback interface (lo0/lo) to give each domain a unique local IP address. Enables the system to route traffic to the correct domain based on destination IP. Managed automatically by P2NS.
Subnet
A range of IP addresses used for allocating virtual interface IPs. Configured via SUBNETS environment variable. Default: 192.168.3.0/24. Multiple subnets can be configured for large deployments.
Loopback Interface
The network interface used for local communication (127.0.0.1). P2NS creates IP aliases on the loopback interface to assign unique IPs to each domain without affecting external networking.
SNI (Server Name Indication)
A TLS extension that allows the client to specify which hostname it's connecting to. P2NS uses SNI to route HTTPS requests to the correct domain handler based on the requested hostname.
Plugin System
Plugin
A self-contained module that extends P2NS functionality. Plugins are stored in plugin-sites/{domain}/ and can serve static files, handle dynamic requests, and access the full SDK. See plugins/README.md.
Plugin SDK
The API provided to plugins for accessing P2NS functionality. Includes modules for state access, DNS operations, domain management, Holesail control, peer management, and more. See plugins/PLUGIN_SDK.md.
Split logging
Core and subsystem logs are written to separate files under LOG_DIR (default ./logs/): core.log, proxy.log, http-proxy.log, dns.log, plugins.log, holesail.log. The admin Logs tab tails these via subscribe-log / file-log. Plugin sdk.log output goes to plugins.log and per-plugin app.log.
Admin Panel Actions
Custom operations that plugins can register to appear in the admin interface. Actions are async functions that can be triggered from the Plugins tab. Registered via sdk.admin.registerAction().
Admin Panel Settings
Configuration options that plugins can register for user customization. Settings appear as forms in the admin interface and persist to cache/plugin-settings/{domain}.json. Registered via sdk.admin.registerSetting().
Security
Certificate Authority (CA)
P2NS includes a local CA for generating TLS certificates. The root CA can be installed in the system trust store to enable HTTPS for all P2NS domains without browser warnings.
Ed25519
The elliptic curve signature algorithm used for authentication tokens. Plugins use Ed25519-signed tokens to verify that requests come from the local peer.
Authentication Token
A signed token used to authenticate write operations in plugins. Contains the peer ID, timestamp, expiration, and cryptographic signature. Generated via /api/token endpoint.
Data Storage
domains.json
Configuration file storing the list of domains claimed by the local peer. Each entry contains the domain name, Holesail hash, and optional SSL flag.
local_dns.json
Custom DNS records that take priority over P2P and public DNS. Supports all standard record types (A, AAAA, MX, TXT, SRV, etc.).
selector_cache.json
Stores version preferences for domains with both P2P and public DNS records, and hash preferences for domains with P2P consensus conflicts. Contains versionPreferences (mapping domains to p2p or public) and hashPreferences (mapping domains to local or resolved).
holesail_servers.json / holesail_clients.json
Persisted configuration for Holesail servers and clients. Automatically restored on P2NS startup.
Related Documentation
- README.md - Main P2NS documentation
- ARCHITECTURE.md - Internal module documentation
- CONSENSUS.md - Consensus mechanism deep dive
- plugins/README.md - Plugin system guide
- plugins/PLUGIN_SDK.md - Plugin SDK reference
- RESTAPI.md - Admin API documentation