diff --git a/docs.json b/docs.json index c70236fbf..3e6d2a0c0 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": [ @@ -676,12 +690,12 @@ }, { "source": "/v3/concepts/dive-into-ton/ton-ecosystem/blockchain-tech", - "destination": "/foundations/services", + "destination": "/services/overview", "permanent": true }, { "source": "/v3/concepts/dive-into-ton/go-from-ethereum/blockchain-services", - "destination": "/foundations/services", + "destination": "/services/overview", "permanent": true }, { @@ -1156,7 +1170,7 @@ }, { "source": "/v3/documentation/dapps/defi/ton-payments", - "destination": "/foundations/services", + "destination": "/services/overview", "permanent": true }, { @@ -2116,12 +2130,12 @@ }, { "source": "/guidelines/web3-guidelines", - "destination": "/foundations/services", + "destination": "/services/overview", "permanent": true }, { "source": "/v3/guidelines/web3/overview", - "destination": "/foundations/services", + "destination": "/services/overview", "permanent": true }, { @@ -2174,24 +2188,29 @@ "destination": "https://old-docs.ton.org/v3/guidelines/web3/ton-proxy-sites/running-your-own-ton-proxy", "permanent": true }, + { + "source": "/foundations/services", + "destination": "/services/overview", + "permanent": true + }, { "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 84% rename from foundations/services.mdx rename to services/overview.mdx index 0920aff44..e94b85b70 100644 --- a/foundations/services.mdx +++ b/services/overview.mdx @@ -1,5 +1,6 @@ --- title: "Web3 services" +sidebarTitle: "Overview" --- import { Image } from '/snippets/image.jsx'; @@ -14,13 +15,11 @@ Although many people refer to TON only as a blockchain, _The Open Network_ is a - A service for assigning human-readable names to accounts, smart contracts, services, and network nodes (TON DNS) - A platform for micro-payments (TON Payments) -This article provides a general overview of TON Services, beyond the blockchain. - ## TON Network TON Network is a peer-to-peer network used for accessing the TON Blockchain, sending transactions, and receiving updates. Also, it can support arbitrary distributed services, blockchain-related or not. The cornerstone in TON networking is the ADNL protocol, built on top of the TCP/UDP stack. -The TON Distributed Hash Table (DHT) plays a crucial role in the networking component of the TON Project, as it is used to locate other nodes in the network. You can think of it as a big, persistent key-value data storage. The keys of the TON DHT are simply 256-bit integers. In most cases, they are computed as sha256 hashes of a TL-serialized objects. The values assigned to these 256-bit keys are essentially arbitrary byte strings of limited length. +The TON Distributed Hash Table (DHT) plays a crucial role in the networking component of the TON Project, as it is used to locate other nodes in the network. It acts as a persistent key-value data storage. The keys of the TON DHT are simply 256-bit integers. In most cases, they are computed as sha256 hashes of a TL-serialized objects. The values assigned to these 256-bit keys are essentially arbitrary byte strings of limited length. :3333 -p 5555 -D storage-db +``` + +- `-v` — log verbosity (`3` = INFO) +- `-C` — path to the global network config +- `-I` — ADNL listen IP and port (`` is the public or reachable address of the host) +- `-p` — TCP port for the console interface +- `-D` — path to the daemon database; CLI keys are generated inside the `cli-keys/` subdirectory 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 +``` + +- `` — 64-character hex bag ID +- `` — target directory for downloaded files +- `` — path to the bag meta file +- 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. + +- `` — integer priority from `0` (do not download) to `255` (highest) +- `` — file index from the `get` output +- `` — file name from the `get` output + +## Create and share a bag + +Create a bag from a file or directory and start seeding: + +```bash +create -d "Description of the bag" +``` + +- `` — file or directory to include in 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 +``` + +- `` — path to save the generated meta file diff --git a/services/storage/faq.mdx b/services/storage/faq.mdx new file mode 100644 index 000000000..8fff9683a --- /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). +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) +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 the static site files in a folder that includes `index.html`. +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 + +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..dec0de7fc --- /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 torrent-like 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; Merkle proofs let storage flows pair with smart contracts, such as storage providers, when enforceable on-chain terms are needed. + +## 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..5c56478fa --- /dev/null +++ b/services/storage/provider.mdx @@ -0,0 +1,152 @@ +--- +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. +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. + + + +## 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. + + - `` — address of the provider's smart contract + +1. Create a bag and generate the storage request body: + + ```bash + new-contract-message --query-id 0 --provider + ``` + + - `` — 64-character hex bag ID + - `` — file path to write the generated message body + - 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. + +1. 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 + ``` + +1. Deploy the provider contract from `storage-daemon-cli`: + + ```bash + deploy-provider + ``` + + + +1. 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 + +1. 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 + ``` + +- `
` — destination TON account to receive funds + +- Close a contract explicitly: + + ```bash + close-contract + ``` + +- `` — address of the storage contract to close + + 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" + ``` + +- `` — amount in nanotons to transfer + + + + diff --git a/start-here.mdx b/start-here.mdx index ac87d1b0e..2eaabfe49 100644 --- a/start-here.mdx +++ b/start-here.mdx @@ -17,6 +17,7 @@ The documentation is organized by layers of detail, with lower-level details app | Languages | Reference documentation for TON-specific languages. | | TON Virtual Machine | Description of the low-level language that runs smart-contracts, and details of the runtime. | | Blockchain foundations | Comprehensive description of the blockchain. Includes web version of whitepapers. | +| The Open Network | Description of TON web3 services, like TON Storage or TON Payments | | Contribute | Documentation on writing this documentation. |