> 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/resources/changelog.md). # Release Notes This page summarizes the version history and notable changes for each Boson Network release, from the perspective of someone building on Boson or running a node. The authoritative record is [`CHANGELOG.md`](https://github.com/bosonnetwork/Boson.Releases/blob/master/CHANGELOG.md) in Boson.Releases, alongside the downloadable packages on its [releases](https://github.com/bosonnetwork/Boson.Releases/releases) page. The open-source modules ([Boson.Core](https://github.com/bosonnetwork/Boson.Core), [Boson.Tools](https://github.com/bosonnetwork/Boson.Tools) and the client libraries) carry their own release tags, and the Java libraries are published to Maven Central under [`io.bosonnetwork`](https://central.sonatype.com/namespace/io.bosonnetwork). *** ## 3.x line The 3.x line is the current stable release series. It includes the full four-service super-node stack (web-gateway, messaging, ion-store, active-proxy), the Director supervisor, the `boson-node`, `boson-cli` and `boson-director-cli` command line tools, and platform packages for macOS, Linux, and Windows. The line reached **general availability with 3.1.0**, concluding the Community Technical Preview series that ran through 3.0.x. ### 3.2.0 - 2026-10-16 Feature release focused on accounts and sign-in: passkeys, passphrase recovery, the Boson Identity app, and sign-in for community apps. It also adds subscriptions to the DHT, moves to Vert.x 5.1, and makes super node updates safer. {% hint style="warning" %} The Director database schema changes in this release and is migrated on the first start of 3.2.0. A node on 3.1.x cannot go back to a migrated database, so back it up before upgrading - the SQLite file, or a `pg_dump` of PostgreSQL. The super node setup tool's `--update` dumps the database for you before installing a release that migrates it. See [Backups, Upgrades & Hardening](/operate-a-node/operations.md). {% endhint %} {% hint style="warning" %} OAuth sign-ins now return only to the node's own site and to the apps listed in `oauth.allowedRedirects`, which defaults to the Boson Identity and Photon app links. On a node with OAuth configured, the Debian packages add those two links and `communityApps: true` to `/etc/boson/director.yaml` on upgrade, keeping any entries already listed; elsewhere run the setup wizard with `--migrate`. See [Configuring the Director](/configure-a-node/director-config.md#oauth-sign-in). {% endhint %} **What's new** * DHT subscriptions: a node asks the nodes storing a value or peer records to push changes to it, instead of polling with lookups, and this works from behind NAT. `Node.subscribeValue` and `Node.subscribePeer` in the Java API, `subscribe` and `unsubscribe` in the `boson-node` shell. Only nodes running Orca 2 or later answer a subscription. See [Kademlia DHT](/core-concepts/kademlia-dht.md#subscriptions) and [Values and Peers](/build-applications/java-sdk/values-and-peers.md#watching-for-changes). * The [Boson Identity](https://github.com/bosonnetwork/BosonIdentity) Android app, which holds a user key on the phone and approves what acts in its name: new devices, web sign-ins and node administration. See [Manage Your Identity](/getting-started/identity-app.md). * Passkey sign-in on the Director, the User Portal and the Admin Dashboard. * Passphrase recovery with recovery codes, a passkey, or a linked OAuth account - never with the user key alone. * Sign-in for community apps that are not listed in the node's configuration, using an OAuth client ID metadata document, PKCE and a consent page on the node. Such an app gets client scope only. * Web sign-in through Boson Identity, device approval that uses the user key only when asked, and administrator enrollment by QR code with `boson-director-cli user enroll-admin`. See [Operator CLI Tools](/operate-a-node/cli-tools.md#enrolling-an-administrator). * A security log of account events, kept for 90 days or each user's newest 200 events, whichever is larger. * Device rename, and management of a user's linked sign-ins. * A profile revision, so a profile or avatar change made meanwhile on another device is detected rather than overwritten. * Database migration detection in the super node setup tool's `--update`: it dumps the database before a release that migrates it, and prints the restore commands if the update fails afterwards. `--backup-database` and `--no-backup-database` override when the dump is taken. **Changes** * `Resolver` is merged into `Registry` in the Boson API: publish, look up and unpublish cards with a choice of version, with a bounded card cache built in. The Caffeine and persistent resolution caches are gone. See [Decentralized Identity (DID)](/core-concepts/decentralized-identity.md#publishing-and-resolving). * Vert.x 5.1.10, Netty 4.2.19 and Jackson 2.21.7. Under Vert.x 5.1 an HTTP client resolves host names on the calling thread, so the Boson clients now issue their requests from a Vert.x thread - which is what makes them usable from an Android main thread. See [Best Practices](/build-applications/best-practices.md#threads-and-contexts). * An OAuth sign-in hands a web page its token in the URL fragment. * Linking or unlinking an OAuth sign-in requires the passphrase; repeated wrong passphrases are slowed down; a new passphrase is checked for strength, with a minimum length of 8. * Direct device registration is signed with the user key, and finishing a registration is repeatable, so a lost approval answer can be fetched again. * Photon Messaging publishes a channel card when the channel is created, renamed or changes its announcement, rather than hourly, and unpublishes it when announcing stops or the channel is deleted. * Sign-in methods are listed on the User Portal and the Admin Dashboard as passkey, Boson Identity, then OAuth providers. **Fixes** * A Web Gateway store or announcement, or an Ion Store upload, no longer loses its request body while the Director checks the caller's plan. * A user record cached by the Director no longer moves a hosted service onto the Director's thread, which lost request bodies. * The MQTT and federation servers of Photon Messaging no longer publish to a session from each other's thread. * The client libraries no longer resolve host names on the caller's thread, which Android refuses on its main thread. * A race in the messaging client loading a channel's members, and the home node profile lookup for messaging recipients. * The device admin flag in Director JSON, and duplicate and clashing paths in the Director OpenAPI specification. ### 3.1.2 - 2026-09-27 Maintenance release that publishes the Java SDK to Maven Central, replaces the Rust command line tools with Java ones, and signs the release assets. {% hint style="warning" %} The admin CLI configuration key `rootUserKey` is renamed to `privateKey`. The Debian packages migrate `/etc/boson/director-cli.yaml` on upgrade; elsewhere run the setup wizard with `--migrate` to bring an existing file up to date. See [Operator CLI Tools](/operate-a-node/cli-tools.md). {% endhint %} **What's new** * The Java SDK on Maven Central, under the group id `io.bosonnetwork`: `boson-api`, `boson-dht`, `boson-higgs`, `boson-director-client`, `boson-messaging-client`, `boson-ion-store-client` and `boson-active-proxy-client`, with `boson-dependencies` as the BOM. See [Java SDK Setup](/build-applications/java-sdk.md). * Java command line tools, replacing the Rust ones of the same names: `boson-cli`, `boson-director-cli`, and `boson-node`, which takes over from `dht-shell` and the `boson-dht-runner` artifact. The tools are shipped in the distribution packages rather than published to Maven Central. * `boson-cli` reaches a super node's Ion Store, DHT and Active Proxy directly, finding each service through the node's Director. * `boson-director-client`, a Java client for a super node's account API: proof-of-work registration, devices, passphrase, profile and avatar, node status and plan, plus OAuth sign-in, device pairing and the admin API. * Public endpoint discovery in the DHT: a node learns its own endpoint from what replying nodes observe, announces a change with a self-lookup, and gives up an endpoint that has gone stale. * A signed `SHA256SUMS` file over every release asset, verified by the super node installer and by `--update` before anything is installed. See [Installation](/deploy-a-node/installation.md). * In-place super node updates, with `setup.sh --update`, and Debian support in the installer alongside Ubuntu. * The distribution builds every platform - macOS, Linux and Windows - from one macOS or Linux machine, using `jlink` against the target platform's `jmods`. Neither Docker nor a Rust toolchain is needed any more. macOS Intel packages are no longer produced. * A portable archive, `boson--any.zip`: every jar, no bundled runtime, nothing platform-specific. For the platforms the others do not cover - Linux on riscv64, ppc64 or musl, FreeBSD, macOS on Intel, Windows on ARM - and for containers. Needs Java 17 or later, and uses Java NIO rather than a native transport. * User blocking in the messaging client, which drops friend requests and direct messages from a blocked user. * A `Date` header on every Director, service and federation answer, so a client with a skewed clock can correct itself and sign its own access tokens. **Changes** * The light node artifact is renamed from `higgs-java` to `boson-higgs`. * The public client APIs return `CompletableFuture`. * The libraries and services carry no Netty native transport dependencies; an application that wants one adds the jars for its own platform. See [Native Transport](/build-applications/java-sdk/native-transport.md). * Active Proxy advertises session endpoints at the node's public address rather than its listening address, with the correct scheme for each endpoint, and name access is limited to HTTP upstreams. * The Active Proxy client takes its service endpoint and upstream as URIs, and its standalone launcher is replaced by `boson-cli`. * Friend request rules are applied consistently across the messaging service and client, and a received request is dated by both its send and arrival time. * The admin dashboard, portal and home page carry the official Boson mark. **Fixes** * Ion Store no longer loses part of an upload while resolving the caller's plan, which stored a truncated object. * Contact synchronization no longer loses changes when a device reconnects with a backlog, and two messages sent in the same millisecond no longer share an id. * The DHT evicts dead routing table entries even when no replacement is available, reads the RPC transaction id as an unsigned 32-bit value, and applies the correct minimum inbound packet size. * Active Proxy caps packet padding so the length never overflows its field, no longer reconnects or reports a disconnect after a session has been stopped, and keeps a client configured with a user id only. * The admin API fixes list ordering, stale plan data, avatar replacement and malformed input answered with HTTP 500. * The admin dashboard no longer flashes the wrong theme on load. ### 3.1.1 - 2026-09-03 Maintenance release focused on super node deployment: running services behind a TLS-terminating reverse proxy, name access without a DNS update per connection, and a default home page for the node. {% hint style="warning" %} The Ion Store database schema changed in this release. An Ion Store database created by 3.1.0 will fail to start under 3.1.1 with a schema version mismatch and has to be recreated. {% endhint %} **What's new** * A default super node home page, served at the root, reporting node identity, status, and hosted services. * Name access to Active Proxy through a reverse proxy and wildcard DNS, removing the DNS update per connection. * RFC 2136 DNS UPDATE support in the Active Proxy dynamic DNS provider. * An independently configurable listen interface and announced public endpoint for the Photon Messaging federation interface. * Service-defined extra values in service configuration, announced alongside the service endpoint. * A tool to reconcile the Ion Store blob directory against its database. * Tunable heap size and file descriptor limits via `/etc/default/boson`. **Changes** * The public Boson Network bootstrap nodes now ship as the default in the bootstrap and super node configuration templates. * A service may announce a public endpoint whose scheme differs from its own listener, so services can serve plaintext behind a TLS-terminating reverse proxy. * Super node status is served without authentication, so the node home page can report availability to any visitor. * The Ion Store local and cache stores are merged into a single store separated by origin, so cached objects are never served as locally hosted content. * The User Portal and Admin Dashboard sign-in pages were redesigned to match the node home page. **Bug fixes** * Web Gateway returned HTTP 500 instead of the resolved status when a failure carried no message. * The Web Gateway client ignored the path prefix in the gateway URL when building requests. * Active Proxy client sessions cancelled their periodic check on a successful start, producing duplicate and stale peer announcements. * Service base path derivation in the Ion Store client. *** ### 3.1.0 - 2026-08-23 First general availability release, concluding the Community Technical Preview series. {% hint style="warning" %} The configuration syntax was reworked in this release and is **not backward compatible with 3.0.x**. Existing configuration files must be regenerated or updated before upgrading. {% endhint %} **What's new** * Per-node announce results, reporting which nodes accepted a value or peer and why others refused. * Kademlia tuning options in node configuration, including lookup, routing table, and bootstrap parameters. * A common rate limiting API across the Director and Layer-2 services, supporting per-second through per-day limits. * Service-wide, per-address, per-user, and concurrency-based rate limiting in Web Gateway, Ion Store, and Photon Messaging. * Per-API request budgets, costs, and concurrency limits on Director APIs. * Plan-based service quotas for Ion Store, Photon Messaging, and Active Proxy. * Dedicated client exceptions for gateway errors, rate limits, and channel limits, with retry hints where applicable. * Security considerations added to the protocol specification. **Changes** * Hardened the DHT against malformed and abusive traffic with bounded packet decoding, routing-table contributions, lookup responses, and improved abuse throttling. * Improved DHT lookup and announce tasks with bounded runtime and effort, more accurate timeout and loss tracking, and proper cancellation of outstanding calls. * Improved bootstrap reliability with warm starts, bounded bucket fan-out, and reduced interference with application lookups. * Moved per-packet cryptographic operations off the event loop to improve throughput under load. * Unified service configuration across the Director and Layer-2 services and finalized the configuration syntax. * Retuned default user limits, rate limits, and concurrency settings. * Removed internal DHT instances from the public API and routed all sends through the node. * Restricted key-bearing configuration files to their owning account. * Removed bundled logging configuration from library JARs so applications can manage their own logging. **Bug fixes** * RPC socket binding to the wrong protocol family, which prevented IPv6 nodes from starting. * Messages and payloads that could exceed a single datagram. * Conditions that could permanently block bootstrapping. * Routing-table maintenance and warm-start sweeps skipping entries that required refresh. * Bootstrap node identity being overwritten or accessed by other accounts. * Stale channel membership after invalidation or early removal notifications in the messaging client. *** ### 3.0.2 - 2026-07-27 Community Technical Preview 3. **What's new** * A pluggable `CryptoProvider` SPI with Bouncy Castle as the default implementation. * libsodium-compatible `crypto_secretstream_xchacha20poly1305` streaming encryption. * Equihash-based asymmetric proof-of-work primitives supporting permissionless registration. * A permissionless registration proof-of-work gate in the Director, providing Sybil resistance without requiring mandatory OAuth-based registration. * `crypto_kdf`-compatible key derivation, and raw key bytes via `CryptoBox.keyBytes()`. * Built-in on-the-fly encryption and decryption in the Ion Store client. * Object integrity verification when uploading data to Ion Store. *** ### 3.0.1 - 2026-06-21 Community Technical Preview 2. **What's new** * CBOR Web Token (COSE\_Sign1) support, now used as the bearer token for Web authentication. * New Ion Store client library. * User Portal and Admin Dashboard web apps for the super node, with GitHub and Google OAuth login. * Server-side persistent store and announcement support in the Web Gateway service. **Changes** * Refined the common API ahead of freezing the public API surface, with JSpecify nullness annotations applied across it. * Simplified super-node setup: each node now uses a single private key, and the Layer-2 services derive their keys from it. * Reworked the Layer-2 service loading mechanism to be native-image friendly. * Aligned the HiggsNode (Light Node) with the updated Web Gateway service, making it more lightweight. **Bug fixes** * Stability improvements and minor bug fixes. *** ### 3.0.0 - 2026-05-15 Initial Community Technical Preview release of the 3.x series. **What's new** * **Super Node** (Boson Director) bundling the built-in Layer-2 services: Web Gateway, Ion Store, Active Proxy, and Photon Messaging. * **Bootstrap Node** - a lightweight, DHT-only seed and discovery node. * **Client libraries** for Web Gateway (HiggsNode / Light Node), Active Proxy, and Photon Messaging. *** {% hint style="info" %} For the most up-to-date release notes, see the [Boson.Releases](https://github.com/bosonnetwork/Boson.Releases/releases) page. {% endhint %} --- # 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/resources/changelog.md?ask=&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.