From d037b6db4e7147ac877b1f38b26059f7780e2bde Mon Sep 17 00:00:00 2001 From: kaladin <335095@niuitmo.ru> Date: Wed, 10 Dec 2025 16:34:12 +0300 Subject: [PATCH 1/8] add web3 services and storage --- docs.json | 24 +++- .../services.mdx => services/overview.mdx | 3 + services/storage/daemon.mdx | 115 +++++++++++++++ services/storage/faq.mdx | 46 ++++++ services/storage/overview.mdx | 38 +++++ services/storage/provider.mdx | 132 ++++++++++++++++++ 6 files changed, 353 insertions(+), 5 deletions(-) rename foundations/services.mdx => services/overview.mdx (98%) create mode 100644 services/storage/daemon.mdx create mode 100644 services/storage/faq.mdx create mode 100644 services/storage/overview.mdx create mode 100644 services/storage/provider.mdx diff --git a/docs.json b/docs.json index efe98fa1a..7255ad593 100644 --- a/docs.json +++ b/docs.json @@ -599,7 +599,6 @@ "foundations/shards", "foundations/limits", "foundations/config", - "foundations/services", { "group": "Merkle proofs", "pages": [ @@ -622,6 +621,21 @@ "foundations/glossary" ] }, + { + "group": "Open network", + "pages": [ + "services/overview", + { + "group": "TON Storage", + "pages": [ + "services/storage/overview", + "services/storage/daemon", + "services/storage/provider", + "services/storage/faq" + ] + } + ] + }, { "group": "Contribute", "pages": [ @@ -2176,22 +2190,22 @@ }, { "source": "/guidelines/ton-storage", - "destination": "https://old-docs.ton.org/guidelines/ton-storage", + "destination": "/services/storage/overview", "permanent": true }, { "source": "/v3/guidelines/web3/ton-storage/storage-daemon", - "destination": "https://old-docs.ton.org/v3/guidelines/web3/ton-storage/storage-daemon", + "destination": "/services/storage/daemon", "permanent": true }, { "source": "/v3/guidelines/web3/ton-storage/storage-provider", - "destination": "https://old-docs.ton.org/v3/guidelines/web3/ton-storage/storage-provider", + "destination": "/services/storage/provider", "permanent": true }, { "source": "/v3/guidelines/web3/ton-storage/storage-faq", - "destination": "https://old-docs.ton.org/v3/guidelines/web3/ton-storage/storage-faq", + "destination": "/services/storage/faq", "permanent": true }, { diff --git a/foundations/services.mdx b/services/overview.mdx similarity index 98% rename from foundations/services.mdx rename to services/overview.mdx index 0920aff44..66795226b 100644 --- a/foundations/services.mdx +++ b/services/overview.mdx @@ -1,5 +1,6 @@ --- title: "Web3 services" +sidebarTitle: "Overview" --- import { Image } from '/snippets/image.jsx'; @@ -32,6 +33,8 @@ The TON Distributed Hash Table (DHT) plays a crucial role in the networking comp TON Storage allows users to share and store files using _The Open Network_. Since storing files on-chain isn't practical, TON Storage only stores Merkle proofs for file content on-chain. It uses TON DHT to find the nodes that have a copy of a required file (e.g., a snapshot of the state of a shardchain, or an old block). Then, one might essentially create a torrent for this file and use TON DHT as a "distributed torrent tracker" for this torrent. +Read more: [TON Storage](/services/storage/overview) + ## TON Proxy TON Proxy provides a protocol where nodes wishing to offer their services (with or without compensation) as tunnels for ADNL network traffic can register. Those needing them can then choose one of these nodes based on the price, latency, and bandwidth offered. Since ADNL traffic is encrypted, Proxy can't access tunneled data, meaning that this protocol is secure. diff --git a/services/storage/daemon.mdx b/services/storage/daemon.mdx new file mode 100644 index 000000000..d8d063945 --- /dev/null +++ b/services/storage/daemon.mdx @@ -0,0 +1,115 @@ +--- +title: "Run storage daemon" +sidebarTitle: "Storage daemon" +--- + +import { Aside } from "/snippets/aside.jsx"; + +`storage-daemon` downloads and shares TON Storage bags. `storage-daemon-cli` is the console client used to control it. + +## Prerequisites + +- Linux, macOS, or Windows host with at least a dual-core 1 GHz CPU, 2 GB RAM, 2 GB SSD (plus space for bags), and stable 10 Mb/s bandwidth with a public/static IP +- Global network config file, for example `global.config.json` from the [TON configs](https://ton-blockchain.github.io/) + +## Install storage-daemon + +- Download prebuilt `storage-daemon` and `storage-daemon-cli` binaries from [TON auto builds](https://github.com/ton-blockchain/ton/releases/latest) (built from the `testnet` branch). +- Or build from source in the [`ton-blockchain/ton`](https://github.com/ton-blockchain/ton/tree/testnet) repository (target: `storage-daemon` and `storage-daemon-cli`). + +## Start the daemon + +Run the daemon with explicit ports and a data directory: + +```bash +storage-daemon -v 3 -C global.config.json -I :3333 -p 5555 -D storage-db +``` + +- `-v` — log verbosity (`3` = INFO) +- `-C` — path to the global network config +- `-I` — ADNL IP and port +- `-p` — TCP port for the console interface +- `-D` — path to the daemon database; CLI keys are generated inside `/cli-keys/` on first start + + + +## Connect with storage-daemon-cli + +Point the CLI at the console port and keypair generated by the daemon: + +```bash +storage-daemon-cli -I 127.0.0.1:5555 -k storage-db/cli-keys/client -p storage-db/cli-keys/server.pub +``` + +- `-I` — daemon host and console port +- `-k` — client private key path +- `-p` — server public key path (CLI option, not a port) + +`storage-daemon-cli` can also run non-interactively: + +```bash +storage-daemon-cli ... -c "add-by-meta bag-meta.bag" -c "list --hashes" +``` + +## Add bags for download + +Download by bag ID hash or by meta file: + +```bash +add-by-hash -d +add-by-meta -d +``` + +- `BAG_ID` — 64-character hex bag ID +- If `-d` is omitted, files are saved to the daemon's default storage directory. + +`list` shows added bags; `list --hashes` prints full IDs. Use either the numeric ordinal from `list` (valid only for the current session) or the full ID in other commands. + +### Inspect and control transfers + +- `get ` — show description, size, speed, and file list +- `get-peers ` — list connected peers +- `download-pause ` / `download-resume ` — control downloads +- `upload-pause ` / `upload-resume ` — control uploads +- `remove ` — remove the bag +- `remove --remove-files ` — remove the bag and files (files are always removed if stored in the daemon's internal directory) + +## Partial downloads and priorities + +Download only selected files by setting priorities: + +```bash +add-by-hash -d --partial file1 file2 +add-by-meta -d --partial file1 file2 +``` + +Each file has a priority `0–255`; `0` disables download. `--partial` sets listed files to `1` and all others to `0`. + +Update priorities after adding the bag: + +- `priority-all ` — set the same priority for every file +- `priority-idx ` — set by file index from `get` +- `priority-name ` — set by file name + +Priorities can be set before the full file list loads. + +## Create and share a bag + +Create a bag from a file or directory and start seeding: + +```bash +create -d "Description of the bag" +``` + +Options: + +- `--no-upload` — create the bag without uploading; enable later with `upload-resume` +- `--copy` — copy files into the daemon's internal directory before seeding + +After creation the CLI prints the bag ID. Share the meta file if others need a `.torrent`-like descriptor: + +```bash +get-meta +``` diff --git a/services/storage/faq.mdx b/services/storage/faq.mdx new file mode 100644 index 000000000..f5ff42bd4 --- /dev/null +++ b/services/storage/faq.mdx @@ -0,0 +1,46 @@ +--- +title: "TON Storage FAQ" +sidebarTitle: "FAQ" +--- + +## Assign a TON domain to a TON Storage bag + +1. [Create and upload a bag](/services/storage/daemon#create-and-share-a-bag) and copy its bag ID `` (64-character hex). +2. Open Google Chrome. +3. Install a wallet browser extension: + - [TON Wallet](https://chrome.google.com/webstore/detail/ton-wallet/nphplpgoakhhjchkkhmiggakijnkhfnd) + - [MyTonWallet](https://chrome.google.com/webstore/detail/mytonwallet/fldfpgipfncgndfolcbkdeeknbbbnhcc) +4. Import the wallet that owns the domain using the recovery phrase. +5. Go to [dns.ton.org](https://dns.ton.org), open the domain, and select **Edit**. +6. Paste `` into the **Storage** field and save. + +## Host a static TON Site from TON Storage + +1. Place your static site files in a folder that includes `index.html`. +2. [Create a bag](/services/storage/daemon#create-and-share-a-bag) from the folder and upload it. Copy the bag ID. +3. Install TON Wallet or MyTonWallet in Chrome and import the domain owner's wallet. +4. Go to [dns.ton.org](https://dns.ton.org), open the domain, and select **Edit**. +5. Paste `` into the **Site** field, choose **Host in TON Storage**, and save. + +## Migrate NFT content to TON Storage + +For the [standard NFT collection contract](https://github.com/ton-blockchain/token-contract/blob/main/nft/nft-collection-editable.fc), update the content prefix by sending a message from the collection owner's wallet to the collection contract. + +- Old prefix example: `https://mysite/my_collection/` +- New prefix format: `tonstorage:///` + +After updating the prefix, upload refreshed metadata to TON Storage using the new bag ID. + +## Low-level DNS records for TON Storage + +Assign a bag to the DNS record with key `sha256("storage")`: + +```tlb +dns_storage_address#7473 bag_id:uint256 = DNSRecord; +``` + +Assign a static site bag directly to the DNS record with key `sha256("site")`: + +```tlb +dns_storage_address#7473 bag_id:uint256 = DNSRecord; +``` diff --git a/services/storage/overview.mdx b/services/storage/overview.mdx new file mode 100644 index 000000000..682be3fda --- /dev/null +++ b/services/storage/overview.mdx @@ -0,0 +1,38 @@ +--- +title: "TON Storage overview" +sidebarTitle: "Overview" +--- + +import { Aside } from "/snippets/aside.jsx"; + +TON Storage is TON's distributed file storage layer. It lets services and users publish **bags of files** and retrieve them over [ADNL and RLDP](/foundations/whitepapers/ton#3-1-abstract-datagram-network-layer) with verifiable [Merkle proofs](/foundations/serialization/merkle). Bags stay off-chain; only proofs and coordination data touch the blockchain. + +## What TON Storage delivers + +- Distribute large files without placing data on-chain +- Prove that a storage provider still holds a bag through on-chain proofs +- Attach bags to TON DNS domains for human-readable access and TON Sites +- Run private or public providers that charge for storage + +## Core pieces + +- **Bag of files**: a torrent-like package. Its Merkle root (the **bag ID**) uniquely identifies the bag. The meta file (`.bag` equivalent) contains torrent info and header data. +- **storage-daemon** and **storage-daemon-cli**: download, seed, and manage bags. The CLI controls a running daemon. +- **Storage provider contracts**: smart contracts that accept paid storage requests, manage balances, and verify proofs. +- **Networking**: data travels over ADNL using RLDP. Each bag uses its own overlay network, and peers are discovered through TON DHT. + + + +## When to use TON Storage + +- Host static TON Sites directly from TON Storage +- Distribute application assets, media, or snapshots with verifiable integrity +- Operate a paid storage service with proof-of-storage guarantees + +## Next steps + +- Run the daemon and work with bags: [Storage daemon](/services/storage/daemon) +- Operate or consume paid storage: [Storage provider](/services/storage/provider) +- Common flows and DNS records: [TON Storage FAQ](/services/storage/faq) diff --git a/services/storage/provider.mdx b/services/storage/provider.mdx new file mode 100644 index 000000000..b466225dc --- /dev/null +++ b/services/storage/provider.mdx @@ -0,0 +1,132 @@ +--- +title: "Operate a storage provider" +sidebarTitle: "Storage provider" +--- + +import { Aside } from "/snippets/aside.jsx"; + +A storage provider is a paid TON Storage service. It combines a smart contract that holds client balances with a `storage-daemon` that downloads bags, keeps them available, and submits storage proofs. + +## Prerequisites + +- `storage-daemon` running with network connectivity and persistent storage +- Wallet with at least 1 TON to deploy and fund the provider contract +- Global network config file and access to the TON blockchain (mainnet or testnet) + +## How the provider flow works + +1. The provider owner starts `storage-daemon`, deploys the provider contract, and configures limits and rates. +2. A client packages files into a bag and generates a storage request message for the provider contract. +3. The contract creates a dedicated storage contract for that bag. +4. The daemon detects the request, downloads the bag, and activates the storage contract. +5. The client tops up the storage contract balance. The provider submits periodic proofs to continue earning payments. +6. When the balance drains or the provider declines the request, the contract deactivates and the obligation to store the bag ends. + + + +## Use an existing provider (client side) + +1. Fetch provider parameters to confirm limits and rates: + + ```bash + get-provider-params + ``` + + The output includes whether new contracts are accepted, min/max bag size (bytes), storage rate (nanoTON per MB per day), and max proof interval. + +2. Create a bag and generate the storage request body: + + ```bash + new-contract-message --query-id 0 --provider + ``` + + - Large bags can take time to process. + - The message body is saved to ``; it is not a full internal message. + - Query ID can be any `0` to `2^64-1`. The provider will echo it back. + - The generated body embeds the provider's current rate and max span. Regenerate the message if the provider changes these before sending. + +3. Send the generated body as an internal message to `` from any wallet. On success the storage contract returns a message with `op=0xbf7bd0c1`. After the provider downloads the bag it sends `op=0xd4caedcd`. + +### Track balance and close a contract + +- The storage contract balance decreases over time according to the provider's rate and the bag size. +- Top up at any time by transferring TON to the storage contract address. +- Read the current balance with the `get_storage_contract_data` getter (`balance` is the second value). +- Close voluntarily by sending a message with `op=0x79f937ea` from the client's wallet; reuse any query ID. + +## Run a provider (operator side) + +1. Start `storage-daemon` with provider mode enabled: + + ```bash + storage-daemon ... -P + ``` + +2. Deploy the provider contract from `storage-daemon-cli`: + + ```bash + deploy-provider + ``` + + + +3. Set local limits to control daemon behavior: + + ```bash + set-provider-config --max-contracts 100 --max-total-size 100000000000 + ``` + + - `max contracts` — maximum concurrent storage contracts + - `max total size` — total size of bags the provider accepts + +4. Set on-chain parameters before accepting clients: + + ```bash + set-provider-params --accept 1 --rate 1000000000 --max-span 86400 --min-file-size 1024 --max-file-size 1000000000 + ``` + + - Omit any flag to keep its current value. + - Avoid running several `set-provider-params` commands back to back; wait for on-chain updates to finalize. + - Fund the provider contract with more than 1 TON to cover future transactions, but avoid large deposits during initial non-bounceable setup. + +After `accept` is set to `1`, the provider contract starts creating storage contracts for incoming requests. The daemon automatically downloads bags, seeds them, and submits proofs. + +## Operate and withdraw + +- List active contracts and balances: + + ```bash + get-provider-info --contracts --balances + ``` + + `Client$` shows client-provided funds; `Contract$` shows total contract funds. The difference is the provider's earnings. + +- Withdraw earnings: + + ```bash + withdraw
+ withdraw-all + ``` + +- Close a contract explicitly: + + ```bash + close-contract + ``` + + Closing transfers available funds to the main provider contract. Bags are deleted unless shared by other active contracts. + +- Send TON from the provider contract to any address: + + ```bash + send-coins
+ send-coins
--message "optional note" + ``` + + From a6435ca5abf0b96b647a98fc1d5db58b895e32f3 Mon Sep 17 00:00:00 2001 From: kaladin <335095@niuitmo.ru> Date: Wed, 10 Dec 2025 16:38:13 +0300 Subject: [PATCH 2/8] fixes --- services/storage/faq.mdx | 18 +++++++++--------- services/storage/provider.mdx | 28 ++++++++++++++++------------ 2 files changed, 25 insertions(+), 21 deletions(-) diff --git a/services/storage/faq.mdx b/services/storage/faq.mdx index f5ff42bd4..dd955c1f2 100644 --- a/services/storage/faq.mdx +++ b/services/storage/faq.mdx @@ -6,21 +6,21 @@ sidebarTitle: "FAQ" ## Assign a TON domain to a TON Storage bag 1. [Create and upload a bag](/services/storage/daemon#create-and-share-a-bag) and copy its bag ID `` (64-character hex). -2. Open Google Chrome. -3. Install a wallet browser extension: +1. Open Google Chrome. +1. Install a wallet browser extension: - [TON Wallet](https://chrome.google.com/webstore/detail/ton-wallet/nphplpgoakhhjchkkhmiggakijnkhfnd) - [MyTonWallet](https://chrome.google.com/webstore/detail/mytonwallet/fldfpgipfncgndfolcbkdeeknbbbnhcc) -4. Import the wallet that owns the domain using the recovery phrase. -5. Go to [dns.ton.org](https://dns.ton.org), open the domain, and select **Edit**. -6. Paste `` into the **Storage** field and save. +1. Import the wallet that owns the domain using the recovery phrase. +1. Go to [dns.ton.org](https://dns.ton.org), open the domain, and select **Edit**. +1. Paste `` into the **Storage** field and save. ## Host a static TON Site from TON Storage 1. Place your static site files in a folder that includes `index.html`. -2. [Create a bag](/services/storage/daemon#create-and-share-a-bag) from the folder and upload it. Copy the bag ID. -3. Install TON Wallet or MyTonWallet in Chrome and import the domain owner's wallet. -4. Go to [dns.ton.org](https://dns.ton.org), open the domain, and select **Edit**. -5. Paste `` into the **Site** field, choose **Host in TON Storage**, and save. +1. [Create a bag](/services/storage/daemon#create-and-share-a-bag) from the folder and upload it. Copy the bag ID. +1. Install TON Wallet or MyTonWallet in Chrome and import the domain owner's wallet. +1. Go to [dns.ton.org](https://dns.ton.org), open the domain, and select **Edit**. +1. Paste `` into the **Site** field, choose **Host in TON Storage**, and save. ## Migrate NFT content to TON Storage diff --git a/services/storage/provider.mdx b/services/storage/provider.mdx index b466225dc..f3e5c875c 100644 --- a/services/storage/provider.mdx +++ b/services/storage/provider.mdx @@ -16,11 +16,11 @@ A storage provider is a paid TON Storage service. It combines a smart contract t ## How the provider flow works 1. The provider owner starts `storage-daemon`, deploys the provider contract, and configures limits and rates. -2. A client packages files into a bag and generates a storage request message for the provider contract. -3. The contract creates a dedicated storage contract for that bag. -4. The daemon detects the request, downloads the bag, and activates the storage contract. -5. The client tops up the storage contract balance. The provider submits periodic proofs to continue earning payments. -6. When the balance drains or the provider declines the request, the contract deactivates and the obligation to store the bag ends. +1. A client packages files into a bag and generates a storage request message for the provider contract. +1. The contract creates a dedicated storage contract for that bag. +1. The daemon detects the request, downloads the bag, and activates the storage contract. +1. The client tops up the storage contract balance. The provider submits periodic proofs to continue earning payments. +1. When the balance drains or the provider declines the request, the contract deactivates and the obligation to store the bag ends.