# Vola Smart Nodes (Storage)

**Vola Smart Nodes (VSNs) are the heart of Vola's decentralized cloud infrastructure.**

VSNs are the machines that physically store user files, serve retrieval requests, and continuously prove to the chain that the data they hold remains intact and available.

When users upload files through [**Nuvola Drive**](https://drive.nuvoladigital.io/) or any application that's powered by Vola, the files land on a VSN. When users want to download their files, a VSN serves it directly to the user.

> ***Running a Storage Node means becoming a direct provider for Vola's cloud infrastructure and earning $VOLA rewards for doing so.***

**If you would like to dive straight into storage node setup:**

{% content-ref url="/pages/wq17BzqQ5GpIuf0D76NV" %}
[Setting Up a VSN (Storage)](/docs/vola-node-economy/vola-nodes-overview/vola-smart-nodes-storage/setting-up-vsn-storage-nodes.md)
{% endcontent-ref %}

#### Functions of Vola Smart Nodes

<details>

<summary><strong>Store User Files</strong></summary>

VSNs physically store files uploaded by users across the network. [Files are broken into chunks](#user-content-fn-1)[^1], each assigned a unique hash, and distributed across the node's disk storage.

</details>

<details>

<summary><strong>Serve File Requests</strong></summary>

VSNs respond to upload, download, renewal, and removal requests from users via a REST API gateway. Interactions are verified against the chain before being processed.

</details>

<details>

<summary><strong>Submit Availability Proofs</strong></summary>

At specific time intervals, each VSN must submit cryptographic proof that the files it holds are still intact and retrievable. Failing to do so consistently results in reduced rewards.

</details>

<details>

<summary><strong>Listen to Chain Events</strong></summary>

VSNs maintain a live connection to Vola Network, listening for events like file uploads, file commitments, renewals, removals, actively updating their local state accordingly in real time.

</details>

### Storage Components

Each Storage Node manages three distinct layers of storage internally:

<table><thead><tr><th width="190.111083984375">Component</th><th width="190.22216796875">Type</th><th>What It Stores</th></tr></thead><tbody><tr><td><strong>Disk Storage</strong></td><td>Physical</td><td>Raw file data, the actual file chunks uploaded by users</td></tr><tr><td><strong>In-Memory Storage</strong></td><td>RAM Hashmap</td><td>File metadata, file ID, chunk ID, and chunk hash for fast access</td></tr><tr><td><strong>Database Indexer</strong></td><td>SQLite</td><td>File lifecycle records: created, updated, deleted timestamps and file status</td></tr></tbody></table>

These three layers work together to ensure files are stored efficiently, retrievable quickly, and properly tracked throughout their lifetime on the node.

### File Lifecycle

Every file on a VSN moves through four distinct states from the moment a user requests an upload to the moment the file is removed:

{% stepper %}
{% step %}

#### Initialized

A file enters the Initialized state when a user requests an upload session with the VSN. The file slot is created and reserved, but no data has been received yet.
{% endstep %}

{% step %}

#### **Owner Committed**

Once the user submits their commitment hash to the chain and it is verified, the file moves to Owner Committed status. The VSN now knows the file is being actively uploaded and begins processing incoming chunks.
{% endstep %}

{% step %}

#### **Provider Committed**

After the upload is complete and the node has verified the file data matches the commitment hash, the node submits its own provider commitment to the chain.

**The file is now fully stored and active. Escrow funds are released to the node.**
{% endstep %}

{% step %}

#### **Deleted/Expired**

When a file expires or is removed by the user, the garbage collector confirms with the chain that deletion is appropriate and removes the file and all its metadata from the VSN.

The file slot is freed.

{% hint style="info" icon="trash-can-xmark" %}
**Garbage Collection.**

Each Storage Node runs a configurable garbage collector every 6 hours to clean up expired and orphaned files, remove stale metadata, and free up storage capacity. Node operators can set a custom cron schedule or use the default.
{% endhint %}
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**File limits.**\
Currently each owner account can hold metadata for a maximum of **40,000 files** at any given time.
{% endhint %}

#### Availability Proofs

Storing files is only half the job. Storage Nodes must continuously prove to the chain that the files they hold are still available, this is what makes Vola's storage verifiable rather than trust-based.

There are two types of proof a Storage Node must submit:

<details>

<summary><strong>Proof of Upload (Provider Commitment)</strong></summary>

Submitted during the file upload process. The VSN generates a commitment hash made up of two components: a commitment token provided by the user during upload, and the CID (content identifier) of the file itself. The user independently submits the same hash from their side. If both hashes match, the upload is confirmed.

This prevents nodes from claiming to have received a file without actually storing it.

</details>

<details>

<summary><strong>Proof of Downloadability (DOP)</strong></summary>

Submitted once per checkpoint (every day). The chain generates random values that correspond to specific chunks of files stored across the network. Each Storage Node must listen for these values, locate the relevant chunk, generate a Merkle proof of that chunk's inclusion in the file, and submit a DOP proof within the checkpoint window.

Failing to submit a valid proof within the required timeframe results in the node being flagged, and flags accumulate to affect reward distribution through the slashing mechanism.

</details>

#### On-chain Node Monitoring & Performance

A Storage Node's performance is continuously tracked and translated into a DOP Score, which is the primary metric used to calculate rewards and apply slashing.

For a good node score, both current DOP and historical DOP is important.

**DOP Score is calculated using:**

$$
D\_{curr} = \frac{P}{T}
$$

Where:

* P = Valid proofs submitted
* T = Total proofs expected per epoch

**Historical DOP is calculated using:**

$$
D\_{hist} = (1 - \alpha) \cdot D\_{hist,prev} + \alpha \cdot D\_{curr}
$$

Where:

* α = 20%

{% hint style="info" icon="rectangle-history-circle-user" %}
**Historical performance matters.**

Your current epoch DOP score carries 20% weight in your historical score. The remaining 80% comes from past performance. This means a single bad epoch won't destroy your score, but consistent underperformance will catch up with you over time.
{% endhint %}

#### Telemetry & Observability

Every Storage Node includes a built-in telemetry system for monitoring and debugging. Performance data, traces, and spans generated within the node are pushed to an OpenTelemetry collector and visualized in Grafana, giving operators full visibility into their node's behaviour in real time.

This is particularly useful for diagnosing proof submission failures, identifying storage bottlenecks, and tracking uptime across checkpoints.

### Hardware Requirements

<table><thead><tr><th width="211.77783203125">Component</th><th>Minimum Requirement (Recommended)</th></tr></thead><tbody><tr><td><strong>RAM</strong></td><td>8 GB</td></tr><tr><td><strong>CPU</strong></td><td>4 Core</td></tr><tr><td><strong>Storage</strong></td><td>500 GB minimum (committed to the network)</td></tr><tr><td><strong>Network Speed</strong></td><td>Refer HDD vs Network Chart</td></tr><tr><td><strong>OS</strong></td><td>Linux (recommended)</td></tr><tr><td><strong>Other</strong></td><td>Docker, Docker Compose, Public Domain, SSL Certificate</td></tr></tbody></table>

{% hint style="info" %}
These requirements apply to the testnet phase. Requirements may evolve as the network transitions to mainnet.
{% endhint %}

{% hint style="success" icon="dove" %}
**Vola Provides Public Domains (subdomains)**

A public domain is required for VSNs. Unlike Validation Nodes, VSNs must be reachable by users and the chain over the public internet via HTTPS. If you don't have your own domain, we will provide you a subdomain during node registration. SSL is handled automatically during setup via Let's Encrypt.
{% endhint %}

### Setting Up a Vola Smart Node

Now that you know all about our storage nodes, lets jump straight into setting up your Vola Smart Node

{% content-ref url="/pages/wq17BzqQ5GpIuf0D76NV" %}
[Setting Up a VSN (Storage)](/docs/vola-node-economy/vola-nodes-overview/vola-smart-nodes-storage/setting-up-vsn-storage-nodes.md)
{% endcontent-ref %}

### What's Next?

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Node Staking Requirements</strong></td><td><em>Understand the staking formula and how your stake affects your position in the network.</em></td><td><a href="/pages/1Z3WvSS7obhDHKQnv0JD">/pages/1Z3WvSS7obhDHKQnv0JD</a></td></tr><tr><td><strong>Node Rewards</strong></td><td><em>How validator rewards are calculated and when they are distributed.</em></td><td><a href="/pages/3Xr3L81JEkDpfquNCjaW">/pages/3Xr3L81JEkDpfquNCjaW</a></td></tr><tr><td><strong>Delegated Staking</strong></td><td><em>Open your node to delegators or delegate your $VOLA to an existing node.</em></td><td><a href="/pages/fVlYeLokMGmMT7LtveKj#delagated-staking">/pages/fVlYeLokMGmMT7LtveKj#delagated-staking</a></td></tr></tbody></table>

[^1]: Depending on client side implementation, Nuvola Drive dynamically chunks larger files.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wp.vola.network/docs/vola-node-economy/vola-nodes-overview/vola-smart-nodes-storage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.