Skip to main content
TON Storage is a distributed file storage system on the TON Network. Files are shared using a torrent-like protocol, with optional on-chain smart contracts for paid storage guarantees. The TON Blockchain uses TON Storage to distribute archive copies of blocks and state snapshots.

​
Bags

Files are organized into bags, each identified by a unique 256-bit BagID (the hash of the torrent info cell). A bag can contain a single file or a directory. Files in a bag are split into 128 KiB chunks. A Merkle tree built from SHA-256 hashes allows verification of individual chunks without downloading the full bag. Bag metadata can be exported as a metafile.

​
Peer discovery

Nodes that store a bag register in the TON DHT under a key derived from the BagID. Clients query the DHT to find seeder addresses for a given bag.

​
Storage daemon

storage-daemon is the official implementation, distributed as part of the TON software suite. To start: 
storage-daemon -v 3 -C global.config.json -I <ip>:3333 -p 5555 -D storage-db

​
Manage bags

CommandDescription
create <path> -d "description"Create a new bag from a file or directory
add-by-hash <hash> -d <dir>Add a bag by its BagID
add-by-meta <metafile> -d <dir>Add a bag from a metafile
listList all bags
list --hashesList bags with their BagIDs
get <BagID>Show full bag information
get-peers <BagID>Show peers connected for a bag
get-meta <BagID> <file>Export the bag metafile
download-pause <BagID>Pause a download
download-resume <BagID>Resume a download
priority-name <BagID> <name> <N>Set download priority for a file (0 = skip, 255 = highest)
To download only specific files from a bag, use the --partial flag when adding: 
add-by-hash <BagID> --partial file1.txt file2.txt
Files not listed are assigned priority 0 and are not downloaded.

​
Storage providers

A storage provider is a node that stores bags for a fee, backed by an on-chain smart contract. The provider system has two components:
  • Smart contract: deployed on the TON Blockchain, stores the Merkle tree hash of each bag, issues proof challenges, and manages client payments.
  • storage-daemon: runs on the provider’s machine, downloads bags, serves data to peers, and submits storage proofs to the contract.

​
Provider workflow

  1. The provider deploys a main smart contract and shares its address with clients.
  2. A client creates a bag and sends a storage request to the provider contract.
  3. The provider contract deploys a per-bag storage contract and notifies the client.
  4. The provider downloads the bag and activates the per-bag contract.
  5. The client transfers payment. The provider submits periodic Merkle proofs to prove data possession.
  6. When the client balance reaches zero or either party closes the contract, remaining funds return to the client and the contract self-destructs.
Storage pricing is expressed in nanoTON per megabyte per day.

​
Integration with TON DNS

A .ton domain can point to a bag using the dns_storage_address record: 
dns_storage_address#7473 bag_id:bits256 = DNSRecord;
See TON DNS for all record types.

​
Ecosystem use cases

  • NFT metadata: NFT collections can reference off-chain media and metadata stored as bags, using the BagID as a stable content identifier. Individual files within a bag are addressed using the tonstorage://<BagID>/path URI scheme.
  • Static TON Sites: a bag containing HTML and static assets can be served as a TON Site by combining TON Storage, TON DNS, and TON Proxy.