How TON Storage Works
TON Storage runs on top of The Open Network and uses decentralized protocols for storing, distributing, and verifying files. It’s similar to torrent-based file sharing but integrated with blockchain logic and cryptography. Let’s break down how it works from a technical and practical point of view.
Torrent-Based Architecture
TON Storage is often described as "Torrents 3.0." It uses similar peer-to-peer distribution logic — but replaces centralized trackers with a distributed hash table (DHT) and adds encryption, Bag IDs, and smart contract integration.
When you upload a file, it gets packed into a container called a Bag. This Bag is then broadcast to the network using the storage-daemon. You don’t need to pay fees, and the file remains on your local machine — but others can now access it globally. The Bag is referenced by a unique hash called BagID, which works as a file fingerprint and access key.
Files stored via TON Storage are immutable. If the content changes, a new BagID is generated.
The BagID System
BagID is a 64-character hexadecimal string (or base64 hash) generated from the contents and metadata of the file or folder. Anyone with the BagID can download the file. Once they do, they also begin to "seed" it, just like in torrent systems.
Files are distributed across the network automatically. The more people download the Bag, the more copies exist, increasing availability and redundancy.
Example download URL (for public bags):
http://storage.ton/gateway/<BagID>/filename.png
Storage-Daemon: Uploading Files
The TON Storage Daemon is the core utility that handles file uploads and sharing. As of late 2025, the node requirements have remained lightweight for basic storage, though full validation requires more power.
Minimum storage node requirements (2025-2026):
- CPU: 2 cores @ 1GHz
- RAM: 2GB (8GB+ recommended for high-load nodes)
- Disk: 2GB SSD for system (plus storage space for files)
- Network: 10Mbps+ with a static IP
- OS: Linux (Ubuntu 22.04+ recommended), Windows, macOS
- GitHub repo: https://github.com/ton-blockchain/storage-daemon
Basic upload command:
bash storage-daemon -v 3 -C global.config.json -I :3333 -p 5555 -D storage-db
This starts the daemon, sets the working directory ( storage-db), and opens the node to the network. All Bags and files are stored in structured folders under storage-db/torrent/torrent-files.
Using TON CLI to Control the Node
To manage the node, you use storage-daemon-cli with the generated client and server keys:
bash
CopyEdit
storage-daemon-cli -I 127.0.0.1:5555 \
-k storage-db/cli-keys/client \
-p storage-db/cli-keys/server.pub
Sample commands:
-
create <file> – Generate a BagID;
-
add-by-hash <BagID> – Download file by BagID;
-
get-peers <BagID> – List seeding peers;
-
upload-resume <BagID> – Restart upload;
-
download-resume <BagID> – Resume download;
-
remove <BagID> – Remove Bag and files;
-
priority-idx <BagID> <idx> <priority> – Set download priority per file;
For the full command list, see: https://github.com/ton-blockchain/storage-gateway?tab=readme-ov-file#download-storage-daemon-and-storage-daemon-cli
ADNL: The Underlying Data Transport
TON uses a custom protocol called
ADNL (Abstract Datagram Network Layer)
to send and receive data. It’s built over UDP but supports TCP as fallback. Each node has a unique ADNL address, which is a SHA256 hash of a serialized ECC public key.
ADNL ensures:
- End-to-end encryption.
- Sender signing.
- Node discovery.
- Stateless data transfer.
DHT: Finding Files in the Network
TON DHT is a distributed hash table based on Kademlia. It maps BagIDs to IP addresses and ports of nodes that are sharing the files.
When a user wants to download a Bag:
- They send a DHT request using the BagID.
- They receive a list of available nodes.
- They start downloading the file from multiple peers at once.
By default, nodes are not anonymous — each one is tied to an IP address.
Public Gateways
If you don’t want to run the daemon yourself, you can access public files via browser:
text
CopyEdit
http://storage.ton/gateway/<BagID>/<filename>
This is useful for integrations with dApps, especially when you don’t want to install any local tools.
Using TON Storage on Raspberry Pi or VPS
You can run a TON Storage node on devices like Raspberry Pi or any basic VPS, as long as they meet the minimum specs. The only limitation is the need for a static IP, which home ISPs often don’t provide. VPS hosting solves this problem.
DevOps Testing with GitHub Actions
For developers building dApps or integrating storage in CI/CD, GitHub Actions can automate test deployments.
Basic .github/workflows/tests.yaml example:
yaml
CopyEdit
name: TON Storage CI
on:
push:
branches: [ main ]
pull_request:
branches: [ "**" ]
jobs:
test:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v2
- name: Set up QEMU
uses: docker/setup-qemu-action@v1
- name: Build Docker image
uses: docker/build-push-action@v2
with:
context: .
platforms: linux/arm64
load: true
tags: ton-storage:latest
- name: Run Storage Daemon
run: |
./app/ton/storage-daemon-linux-arm64 -v 5 \
-C ./app/ton/global.config.json \
-I localhost:3333 \
-p 5555 \
-D ./app/ton/storage-db > /dev/null 2>&1 &
sleep 5 && npm run test
This is just a starting point, but it’s enough to test the full upload/download flow inside a CI pipeline.
File Verification and Redundancy
One of the core features of TON Storage is that it ensures file integrity using cryptographic verification. Every file that enters the network is hashed and signed. When other nodes download it, they check these signatures to confirm that the file is intact and untampered.
Files are immutable. If the content changes, the system will generate a completely new BagID. This prevents accidental overwrites and ensures long-term consistency for things like NFTs, dApps, or document hosting.
As more users download the same file, more nodes in the network start storing pieces of it. This improves reliability and speeds up distribution. You don’t need centralized infrastructure like a CDN — TON Storage turns every participant into a potential provider.
Earning with TON Storage: Becoming a Provider
If you're running a stable node with decent uptime, you can offer storage as a service. This works using smart contracts between you (the storage provider) and the file owner (the client). Here's how:
- The provider launches the daemon and deploys a smart contract on the TON blockchain.
- The client generates a Bag and sends a special internal message to the contract.
- The contract creates a storage commitment — a promise that the provider will store the Bag.
- The provider downloads the Bag and proves they have it using Merkle proofs.
- The client sends a payment in Toncoin through the contract.
- The provider continues showing proof of storage to keep receiving rewards.
If the file is lost or not verified, the contract is broken and the provider doesn’t get paid. This system encourages uptime and data integrity without requiring constant manual work.
Official smart contract repo: https://github.com/xssnick/tonutils-storage.
Note: There’s no large-scale storage marketplace on TON yet. You’ll need to find users manually or run your own use case. But the protocol and contracts are ready to use.
