> 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/core-concepts/services/ion-store.md).

# Ion Store

**Ion Store** is a Boson Layer-2 service that runs on a super node and provides distributed binary object storage over a plain HTTPS API. It stores arbitrary blobs - files, attachments, encrypted payloads - with per-object metadata, an optional TTL, and a per-user quota, and announces itself to the DHT so clients can locate it via `FIND_PEER` without any hard-coded address.

Every object is identified two ways at once: by a random **reference ID** that clients use to address and share it (the value embedded in `ions://<peerId>/<id>` URIs), and by a **content ID** - the SHA-256 of the bytes - used for integrity verification and server-side deduplication. Because addressing is decoupled from content, two uploads of the same bytes get distinct reference IDs but share a single blob on disk. Retrieval is permissionless; uploading, listing, and deleting require a valid CWT.

A typical workflow: a client `POST`s bytes and receives a reference ID and `ions://` URI; it shares that URI; any recipient - even on a different super node - fetches the object, with cross-peer requests transparently proxied and cached by the local node.

***

## Features

* **Binary object storage** - store and retrieve arbitrary binary payloads over a standard HTTPS API, with streaming uploads and downloads for large objects.
* **Content-addressed & deduplicated** - every object carries a random reference ID (for `ions://` URIs) and a SHA-256 content ID (for integrity and deduplication). Identical payloads share one blob on disk via reference counting.
* **Per-object metadata** - attach custom `Ion-*` headers and control flags to each object at upload time; they are returned on retrieval.
* **TTL and lifecycle** - objects carry an optional expiry time (`Ion-TTL`); a background eviction task removes expired objects automatically.
* **Per-user quota** - total storage per authenticated user is bounded. Uploads that would exceed the quota are rejected with `507 Insufficient Storage`.
* **Public retrieval** - retrieval is permissionless: any client that knows the reference ID can fetch the object. Write, delete, and list operations require a valid CWT.
* **Cross-node federation** - requests for objects stored on a different Ion Store peer are transparently proxied, integrity-verified against the peer's `Ion-Content-Id`, and cached locally.
* **Dual storage backend** - payloads live on the local filesystem; metadata is persisted in SQLite (embedded, for lightweight nodes) or PostgreSQL (for production).

***

## Dual IDs

| ID               | Field in response | Meaning                                                            |
| ---------------- | ----------------- | ------------------------------------------------------------------ |
| **Reference ID** | `id`              | Random per-reference ID. Used in `ions://<peerId>/<id>` URIs.      |
| **Content ID**   | `contentId`       | SHA-256 of the bytes. Used for integrity checks and deduplication. |

The reference ID is what clients store and share. Multiple references (from different users, or the same user at different times) may point to the same content ID if the uploaded bytes are identical.

***

## Configuration

The service type is `io.bosonnetwork.ionstore`. As shipped:

```yaml
host: 0.0.0.0
port: 9080
ssl: true

evictionInterval: 1h
maxObjectSize: 1G          # node-wide ceiling
maxObjectLifetime: 90d     # node-wide ceiling

limits:
  user:
    quota: 500M
    maxObjectSize: 128M
    maxObjectLifetime: 7d
```

The node-wide ceilings bound what any plan can allow; the `limits.user` values are the defaults that plans override. See [Configuring Services](/configure-a-node/services-config.md#ion-store) and the [Configuration Reference](/reference/configuration.md#ion-store).

***

## HTTP API

Uploading, downloading, listing, deleting and fetching from other nodes, with their headers, pagination and error codes, are specified in the [Ion Store API reference](/reference/http-api/ion-store.md).

***

## Deduplication

When a client uploads bytes whose SHA-256 matches an existing content ID, the service creates a new reference record pointing to the existing blob rather than storing a duplicate. The caller gets back a fresh reference ID (different from any existing one) but the same content ID.

Reference counting ensures the blob is retained on disk as long as at least one reference exists. Deleting a reference decrements the count; when the count reaches zero the blob is removed.

***

## Federation

When a client (or another Ion Store peer) requests an object that is not stored locally, the service:

1. Performs a DHT `FIND_PEER` lookup for the provided `peerId`.
2. Fetches the object from that peer's Ion Store endpoint.
3. Verifies integrity against the peer's `Ion-Content-Id` response header.
4. Caches the object locally.
5. Returns it to the original caller.

A remote peer must emit the `Ion-Content-Id` header for the response to be cacheable. Peers running older versions that do not emit this header cannot be cached.

***

## What to read next

* [Build Apps: Ion Store Client](/build-applications/services/ion-store-client.md)
* [Reference: HTTP API - Ion Store](/reference/http-api/ion-store.md)
* [Service Federation](/build-services/service-federation.md)


---

# 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/core-concepts/services/ion-store.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.