Skip to content
Documentations

TON Storage

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

Section titled “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

Section titled “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. When only some chunks have seeders, the client downloads available chunks from those seeders while leaving the rest pending; download resumes automatically when new seeders appear.

Integration with TON DNS

Section titled “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;

Record types are documented in the TON DNS overview and the TON DNS reference.

Section titled “Paid storage contracts”

The provider contract stores a microchunk_hash (the root of a microchunk Merkle tree derived from the bag) and requires periodic Merkle proof submissions from the provider. A successful proof submission guarantees that the provider held at least the challenged chunk at proof time; it does not guarantee availability of the full bag between challenges. A provider could withhold unchallenged chunks or delete data after submitting a valid proof. The worst case is that a client pays for storage of data the provider no longer holds by the time the next challenge window opens. The challenge period (max_span) limits this exposure: a shorter span means more frequent proofs and a smaller window of unverifiable absence. Per-bag storage contracts self-destruct and return the remaining client balance when either party closes the contract.

Ecosystem use cases

Section titled “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.
Section titled “Related components”