202 lines
13 KiB
Markdown
202 lines
13 KiB
Markdown
# 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](CONSENSUS.md) and [RFC 0001](rfcs/0001-autobase-consensus.md).
|
|
|
|
### 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](https://holepunch.to/) 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](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](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](rfcs/0001-autobase-consensus.md).
|
|
|
|
### 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](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](https://holesail.io/) 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](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](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](../README.md) - Main P2NS documentation
|
|
- [ARCHITECTURE.md](ARCHITECTURE.md) - Internal module documentation
|
|
- [CONSENSUS.md](CONSENSUS.md) - Consensus mechanism deep dive
|
|
- [plugins/README.md](plugins/README.md) - Plugin system guide
|
|
- [plugins/PLUGIN_SDK.md](plugins/PLUGIN_SDK.md) - Plugin SDK reference
|
|
- [RESTAPI.md](RESTAPI.md) - Admin API documentation
|
|
|