> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ton.org/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.ton.org/feedback

```json
{
  "path": "/foundations/web3/ton-storage",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# TON Storage

> Distributed file storage for the TON Blockchain using torrent-like technology and on-chain payment contracts

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:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
storage-daemon -v 3 -C global.config.json -I <ip>:3333 -p 5555 -D storage-db
```

### Manage bags

| Command                            | Description                                                |
| ---------------------------------- | ---------------------------------------------------------- |
| `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                                  |
| `list`                             | List all bags                                              |
| `list --hashes`                    | List bags with their `BagID`s                              |
| `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:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
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:

```tlb theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
dns_storage_address#7473 bag_id:bits256 = DNSRecord;
```

See [TON DNS](/foundations/web3/ton-dns#dns-record-types) 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](/foundations/web3/ton-sites): a bag containing HTML and static assets can be served as a TON Site by combining TON Storage, [TON DNS](/foundations/web3/ton-dns), and [TON Proxy](/foundations/web3/ton-proxy).