> For the complete documentation index, see [llms.txt](https://docs.bosonnetwork.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bosonnetwork.io/reference/glossary.md).

# Glossary

Alphabetical definitions for every key term used across the Boson Network documentation.

***

## A

**Active Proxy** A Boson Layer-2 service that provides NAT traversal by exposing a private service as a publicly reachable TCP endpoint. The client opens an outbound encrypted tunnel to a Super Node; the Super Node allocates a public port and forwards inbound connections through the tunnel. Transport encryption uses NaCl CryptoBox (X25519 + XSalsa20-Poly1305). See [Configuration - active-proxy](/reference/configuration.md#active-proxy).

**ANNOUNCE\_PEER** A DHT RPC method (`method = 3`). Registers a service endpoint (a `PeerInfo` record) with a node. Requires a write token from a prior `FIND_PEER` or `FIND_NODE` lookup. See [DHT Protocol - ANNOUNCE\_PEER](/reference/dht-protocol.md#announce_peer-3).

**Authenticated Peer** A `PeerInfo` record that includes the hosting DHT node's ID (`o`) and the node's Ed25519 signature (`os`) over the peer record, in addition to the peer owner's own signature. Provides a verifiable binding between the service endpoint and the hosting node.

***

## B

**Base58** The encoding used for Boson `Id` values in JSON contexts. Boson uses Bitcoin-style Base58 (not Base58Check). The alphabet excludes visually ambiguous characters (0, O, I, l).

**bnr://** URI scheme used for internal avatar references in the Director. Format: `bnr://<nodeId>/api/v1/client/avatar/<userId>`.

**Bootstrap Node** A well-known DHT node used as the initial entry point for a new node joining the network. Listed in `node.yaml` under `bootstraps`. Only needed at startup; the routing table is populated from the bootstrap and then maintained by the DHT protocol.

**Boson Identity** The Android app that holds a user's Boson key and approves what acts in its name: new devices, web sign-ins, account security and node administration. The key never leaves the phone unless the user sends it. See [Manage Your Identity](/getting-started/identity-app.md).

**boson-node** The DHT node command line tool: runs a node, writes and checks its configuration, inspects a saved routing table, and opens an interactive shell for exploring a live node (`boson-node shell`), with commands for `find node`, `find value`, `store value`, `find peer`, `announce peer`, `subscribe` and `unsubscribe`, and routing table inspection. Replaces `dht-shell` and the `boson-dht-runner` artifact in 3.1.2. See [CLI - boson-node](/reference/cli.md#boson-node).

***

## C

**CAS (Compare-And-Swap)** The `cas` field in `STORE_VALUE` and `ANNOUNCE_PEER` requests. The node only stores the new value if the currently stored sequence number equals the `cas` value. Enables optimistic concurrency control for mutable values.

**CBOR** Concise Binary Object Representation - the binary wire format used for DHT protocol messages. All DHT messages are CBOR by default; JSON is available for debugging. See [DHT Protocol](/reference/dht-protocol.md).

**Content Id** The SHA-256 hash of an Ion Store object's bytes. Used for integrity verification and deduplication. Returned in the `Ion-Content-Id` response header and in object metadata as `contentId`. Distinct from the object's reference id (`id`).

**COSE** CBOR Object Signing and Encryption (RFC 8152). The envelope format used for CWT tokens. Boson uses `COSE_Sign1` with Ed25519 (`EdDSA`).

**CryptoBox** NaCl/libsodium's authenticated encryption primitive. Uses X25519 key exchange (Curve25519 Diffie-Hellman) and XSalsa20-Poly1305 for symmetric encryption. Used for encrypted DHT values and the Active Proxy tunnel.

**CryptoIdentity** The Java class (`io.bosonnetwork.crypto.CryptoIdentity`) that holds a 64-byte libsodium-style Ed25519 private key (seed || public key). Provides `sign`, `verify`, `encrypt`, and `decrypt` operations. See [Java API](/reference/java-api.md).

**CWT (CBOR Web Token)** The authentication token format used by all Boson HTTP services. Defined in [RFC 8392](https://www.rfc-editor.org/info/rfc8392/) (with claims-in-COSE-headers per [RFC 9597](https://www.rfc-editor.org/info/rfc9597/)). Boson CWTs are `COSE_Sign1` structures containing an integer-keyed CBOR claim map, signed with Ed25519. Transported as `Authorization: Bearer <base64url>`. See [Identity & CWT Format](/reference/identity-cwt-format.md).

***

## D

**dataDir** The root directory under which a service or node stores its runtime data (routing tables, database files, object blobs, etc.). Each component has a `dataDir` configuration key. See [Configuration](/reference/configuration.md).

**DHT (Distributed Hash Table)** The peer-to-peer key-value store that forms Boson's Layer 1. Based on Kademlia with XOR distance metric. Provides the `FIND_NODE`, `FIND_VALUE`, `STORE_VALUE`, `FIND_PEER` and `ANNOUNCE_PEER` operations, and since 3.2.0 `SUBSCRIBE` with its notifications. See [DHT Protocol](/reference/dht-protocol.md).

**Director** The supervisor process for a Boson Super Node. It owns the lifecycle of the DHT node (`KadNode`) and all Layer-2 services, manages user identities, handles federation, and exposes the Client, Admin, and Federation HTTP APIs. Configured via `director.yaml`. See [Configuration - director.yaml](/reference/configuration.md#director).

***

## E

**Ed25519** The elliptic-curve signature algorithm used throughout Boson. Every identity (node, service, user, device) is an Ed25519 key pair. The public key (32 bytes) is the `Id`; the private key is stored in 64-byte libsodium format (seed || public key).

**Encrypted Value** A DHT value that is mutable and additionally has a `rec` (recipient) field. The payload (`v`) is encrypted using NaCl CryptoBox for the recipient's public key. Can only be decrypted by the holder of the recipient's private key. See [Data Types - Value](/reference/data-types.md#value).

***

## F

**Federation** The mechanism by which two Super Nodes establish a trust relationship with each other, enabling cross-node service delivery (e.g., messaging between users on different Super Nodes). Uses a synchronous propose-and-confirm handshake over the Federation HTTP API. See [Director - Federation API](/reference/http-api/director-federation.md).

**FIND\_NODE** A DHT RPC method (`method = 2`). Returns the K closest nodes to a target ID. The `w` bitmask controls whether IPv4 nodes, IPv6 nodes, and/or a write token are requested. See [DHT Protocol - FIND\_NODE](/reference/dht-protocol.md#find_node-2).

**FIND\_PEER** A DHT RPC method (`method = 4`). Discovers service peer records registered under a service ID. Returns matching peers, or the closest nodes if none are found. See [DHT Protocol - FIND\_PEER](/reference/dht-protocol.md#find_peer-4).

**FIND\_VALUE** A DHT RPC method (`method = 6`). Retrieves a stored value by its ID. Returns the value when found, or the closest nodes otherwise. Always includes a write token. See [DHT Protocol - FIND\_VALUE](/reference/dht-protocol.md#find_value-6).

**Fingerprint** A `uint64` value (`f` field in `PeerInfo`) that uniquely distinguishes peer instances with the same public key. A service instance should set a stable fingerprint at startup to survive restarts without invalidating existing peer references. Set to zero (or omit) to use a random value.

***

## H

**HiggsNode** The Java Light Node client (`io.bosonnetwork.higgs.HiggsNode`). Implements the full `Node` interface but forwards all DHT operations over HTTPS to a Web Gateway instead of running a native UDP DHT stack. The gateway's certificate is verified as a public certificate, or against the expected identity when self-signed. See [Java API - HiggsNode](/reference/java-api.md#clients).

***

## I

**Id** The 256-bit identifier at the heart of the Boson network. Derived from an Ed25519 public key. Uniquely identifies nodes, values (for mutable values), and peers. In JSON: Base58 string or `did:boson:<base58>`. In CBOR: 32-byte binary. In the DHT XOR metric, the distance between two `Id` values is their bitwise XOR. See [Data Types - Id](/reference/data-types.md#id).

**Identity** The Java interface (`io.bosonnetwork.Identity`) representing any entity with an Ed25519 keypair. Provides `getId()`, `sign()`, `verify()`, `encrypt()`, and `decrypt()`. Extended by `Node` and implemented by `CryptoIdentity`. See [Java API](/reference/java-api.md).

**Immutable Value** A DHT value that contains only a `v` (data) field. Its ID is the SHA-256 hash of the data. Once stored, the content is fixed - attempting to store a different payload under the same ID returns error 303. See [Data Types - Value](/reference/data-types.md#value).

**Ion Object** An arbitrary binary blob stored in the Ion Store service. Each object has two identifiers: a random **reference id** (used in API paths and `ions://` URIs) and a **content id** (the SHA-256 of the bytes). See [Ion Store HTTP API](/reference/http-api/ion-store.md).

**Ion Store** A Boson Layer-2 service providing distributed binary object storage over HTTPS. Features content addressing, deduplication, per-user quota, TTL, custom metadata (via `Ion-*` headers), and cross-node federation proxying. See [Configuration - ion-store](/reference/configuration.md#ion-store).

**ions\://** URI scheme for Ion Store objects. Format: `ions://<peerId>/<referenceId>`. The `peerId` identifies which Ion Store node holds the object; clients use this to route retrieval requests.

***

## K

**Kademlia** The distributed hash table algorithm on which Boson DHT Layer 1 is based. Uses XOR as the distance metric. Organises nodes in a binary tree of k-buckets; lookups are iterative and converge in O(log n) hops. See [concepts/kademlia-dht](/core-concepts/kademlia-dht.md).

***

## L

**Layer 1 / Layer 2** Boson uses a two-layer architecture. Layer 1 is the Kademlia DHT (UDP, CBOR, port 39001). Layer 2 services (Web Gateway, messaging, Ion Store, Active Proxy) run on Super Nodes and use Layer 1 for service discovery, while exposing application-level protocols over TCP.

**Light Node** A Boson node type that does not run a native DHT stack. Instead, it delegates all DHT operations to a Web Gateway service over HTTPS, using `HiggsNode`. Suitable for browser-based or resource-constrained clients. See [concepts/node-types](/core-concepts/node-types.md).

**LookupOption** An enum (`io.bosonnetwork.LookupOption`) controlling the DHT query strategy: `LOCAL`, `ARBITRARY`, `OPTIMISTIC` (default), `CONSERVATIVE`. See [Java API - LookupOption](/reference/java-api.md#lookupoption).

***

## M

**Messaging (Photon Messaging)** The Boson Layer-2 service providing federated, end-to-end encrypted instant messaging over MQTTS. Message payloads are encrypted by clients; the server routes and stores opaque ciphertext. Supports multi-device delivery, offline storage, and group channels. See [Configuration - messaging](/reference/configuration.md#photon-messaging).

**Mutable Value** A DHT value with an owner public key (`k`), nonce (`n`), sequence number (`seq`), and Ed25519 signature (`sig`). The owner can update the value by publishing a new version with a higher sequence number. The value ID equals the owner's public key `Id`. See [Data Types - Value](/reference/data-types.md#value).

***

## N

**nameAccess** An optional feature of the Active Proxy service: a session is reachable at `<device id>.<domain>` instead of by address and port. The operator configures a `supernode` or `ddns` provider, and the user's plan must include it. See [Active Proxy Name Access](/configure-a-node/name-access.md).

**NodeInfo** A compact 3-element array `[id, host, port]` carrying network reachability information for a DHT node. Serialized as an array (not a map) on the wire. See [Data Types - NodeInfo](/reference/data-types.md#nodeinfo).

**NOTIFY\_VALUE / NOTIFY\_PEER** DHT RPC methods (`method = 8` and `9`), sent by a storing node to a subscriber when a watched record changes. One record per message, never batched. See [DHT Protocol - Subscriptions](/reference/dht-protocol.md#subscriptions).

***

## P

**Passphrase** A secret string set by users during account creation. Used by the Director to authenticate destructive operations such as device addition, profile deactivation, and the device-registration approval flow. Not stored in plaintext.

**Peer** In DHT terms: a `PeerInfo` record registered under a service ID. Clients discover services by calling `FIND_PEER` or the Web Gateway equivalent. In Director terms: a user's device or client connection.

**PeerInfo** The data structure describing a service published over the DHT. Contains a peer ID, endpoint URI, nonce, sequence number, signature, and fingerprint. Optionally includes origin node information for authenticated peers. See [Data Types - PeerInfo](/reference/data-types.md#peerinfo).

**PING** A DHT RPC method (`method = 1`). The simplest message: verifies that a node is alive. Both request and response have empty bodies. See [DHT Protocol - PING](/reference/dht-protocol.md#ping-1).

***

## R

**Reference Id** The random, per-object identifier assigned by Ion Store at upload time. Used in API paths (`/v1/objects/:ionId`) and in `ions://` URIs. Distinct from the content id. See [Ion Store HTTP API](/reference/http-api/ion-store.md).

**Regular Node** A Boson node type that participates fully in the DHT (UDP, port 39001) and can consume Layer-2 services. Typically a native desktop or mobile app. See [concepts/node-types](/core-concepts/node-types.md).

***

## S

**scope** The authorization level encoded in a CWT. Boson scopes: `client` (user/device access), `admin` (admin API access), `federation` (inter-node federation access). See [Identity & CWT Format - Scopes](/reference/identity-cwt-format.md#scopes-and-roles).

**Sequence Number (`seq`)** A monotonically increasing integer on mutable and encrypted DHT values and peer records. Must increase with each update. The DHT rejects updates where the new `seq` is not strictly greater than the stored value (error 302).

**`sid` (session\_id)** A Boson-specific CWT claim (CBOR key `13`). Identifies a particular session within a user who may hold multiple linked identities. Used for session-scoped lookups so that `sub` (the user Id) is not overloaded. See [Identity & CWT Format - Subject vs. sid](/reference/identity-cwt-format.md#subject-sid-and-client_id).

**STORE\_VALUE** A DHT RPC method (`method = 5`). Publishes a value to a node. Requires a write token. Supports CAS (`cas`) for atomic updates of mutable values. See [DHT Protocol - STORE\_VALUE](/reference/dht-protocol.md#store_value-5).

**SUBSCRIBE** A DHT RPC method (`method = 7`). Asks a node storing a value or peer records to push changes to the sender. Requires a write token for the target, verified against the address the request came from. Renewed by repeating it, cancelled with a lease of `0`. Implemented from Orca 2. See [DHT Protocol - Subscriptions](/reference/dht-protocol.md#subscriptions).

**Subscription** Two unrelated things, by the same name:

1. **DHT subscription** (3.2.0) - a standing request to the nodes storing a value or peer records to notify this node of each change, instead of polling. See [Kademlia DHT - Subscriptions](/core-concepts/kademlia-dht.md#subscriptions).
2. **Plan subscription** - a user's subscription to one of the node's plans, until an end time. A user without an active one is on the free plan. See [Users, Devices & Subscriptions](/operate-a-node/users-devices-subscriptions.md#subscriptions).

**Super Node** The most capable Boson node type. Runs a full DHT node (Layer 1) and hosts Layer-2 services (Web Gateway, messaging, Ion Store, Active Proxy). Supervised by the Director process. See [concepts/node-types](/core-concepts/node-types.md).

***

## T

**TLS** A super node serves TLS with either a certificate from a public authority or a self-signed certificate bound to the node's Ed25519 identity. Boson clients accept a self-signed certificate only when it matches the identity they expect, so no certificate authority is needed. See [HTTP APIs - TLS](/reference/http-api.md#tls).

***

## V

**Value** Data stored in the Boson DHT. Three types: immutable (content-addressed by SHA-256 hash), mutable (owned, versioned), and encrypted (mutable with CryptoBox-encrypted payload for a specific recipient). See [Data Types - Value](/reference/data-types.md#value).

***

## W

**Web Gateway** A Boson Layer-2 service that exposes the DHT as an authenticated HTTPS API, enabling Light Nodes to participate without a native UDP implementation. All DHT operations are available over HTTP: finding a node, finding and storing a value, and finding and announcing a peer. Also provides persistent value and peer storage. See [Web Gateway HTTP API](/reference/http-api/web-gateway.md).

**Write Token (`tok`)** A short-lived opaque integer issued by DHT nodes. Required to publish data via `STORE_VALUE` or `ANNOUNCE_PEER`. Acquired from `FIND_VALUE`, `FIND_PEER`, or `FIND_NODE` (with `wantToken` bit set) responses. Prevents unsolicited writes. See [DHT Protocol - Write Tokens](/reference/dht-protocol.md#write-tokens).

***

## X

**XOR Distance** The Kademlia distance metric. The distance between two node IDs is their bitwise XOR interpreted as a 256-bit integer. Nodes maintain contacts closest to themselves in a tree of k-buckets. Lookups converge in O(log n) steps.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bosonnetwork.io/reference/glossary.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.