diff --git a/docs.json b/docs.json index ea7350a15..4092e8dc1 100644 --- a/docs.json +++ b/docs.json @@ -692,7 +692,16 @@ "foundations/shards", "foundations/limits", "foundations/config", - "foundations/services", + { + "group": "Web3 services", + "pages": [ + "foundations/web3/overview", + "foundations/web3/ton-dns", + "foundations/web3/ton-storage", + "foundations/web3/ton-proxy", + "foundations/web3/ton-sites" + ] + }, { "group": "Merkle proofs", "pages": [ @@ -774,12 +783,12 @@ }, { "source": "/v3/concepts/dive-into-ton/ton-ecosystem/blockchain-tech", - "destination": "/foundations/services", + "destination": "/foundations/web3/overview", "permanent": true }, { "source": "/v3/concepts/dive-into-ton/go-from-ethereum/blockchain-services", - "destination": "/foundations/services", + "destination": "/foundations/web3/overview", "permanent": true }, { @@ -1254,7 +1263,7 @@ }, { "source": "/v3/documentation/dapps/defi/ton-payments", - "destination": "/foundations/services", + "destination": "/foundations/web3/overview", "permanent": true }, { @@ -2214,42 +2223,42 @@ }, { "source": "/guidelines/web3-guidelines", - "destination": "/foundations/services", + "destination": "/foundations/web3/overview", "permanent": true }, { "source": "/v3/guidelines/web3/overview", - "destination": "/foundations/services", + "destination": "/foundations/web3/overview", "permanent": true }, { "source": "/guidelines/ton-dns", - "destination": "https://old-docs.ton.org/guidelines/ton-dns", + "destination": "/foundations/web3/ton-dns", "permanent": true }, { "source": "/v3/guidelines/web3/ton-dns/dns", - "destination": "https://old-docs.ton.org/v3/guidelines/web3/ton-dns/dns", + "destination": "/foundations/web3/ton-dns", "permanent": true }, { "source": "/v3/guidelines/web3/ton-dns/subresolvers", - "destination": "https://old-docs.ton.org/v3/guidelines/web3/ton-dns/subresolvers", + "destination": "/foundations/web3/ton-dns", "permanent": true }, { "source": "/guidelines/proxy-and-sites", - "destination": "https://old-docs.ton.org/guidelines/proxy-and-sites", + "destination": "/foundations/web3/ton-proxy", "permanent": true }, { "source": "/v3/guidelines/web3/ton-proxy-sites/how-to-run-ton-site", - "destination": "https://old-docs.ton.org/v3/guidelines/web3/ton-proxy-sites/how-to-run-ton-site", + "destination": "/foundations/web3/ton-sites", "permanent": true }, { "source": "/v3/guidelines/web3/ton-proxy-sites/ton-sites-for-applications", - "destination": "https://old-docs.ton.org/v3/guidelines/web3/ton-proxy-sites/ton-sites-for-applications", + "destination": "/foundations/web3/ton-sites", "permanent": true }, { @@ -2269,22 +2278,22 @@ }, { "source": "/v3/guidelines/web3/ton-proxy-sites/running-your-own-ton-proxy", - "destination": "https://old-docs.ton.org/v3/guidelines/web3/ton-proxy-sites/running-your-own-ton-proxy", + "destination": "/foundations/web3/ton-proxy", "permanent": true }, { "source": "/guidelines/ton-storage", - "destination": "https://old-docs.ton.org/guidelines/ton-storage", + "destination": "/foundations/web3/ton-storage", "permanent": true }, { "source": "/v3/guidelines/web3/ton-storage/storage-daemon", - "destination": "https://old-docs.ton.org/v3/guidelines/web3/ton-storage/storage-daemon", + "destination": "/foundations/web3/ton-storage", "permanent": true }, { "source": "/v3/guidelines/web3/ton-storage/storage-provider", - "destination": "https://old-docs.ton.org/v3/guidelines/web3/ton-storage/storage-provider", + "destination": "/foundations/web3/ton-storage", "permanent": true }, { @@ -3466,6 +3475,11 @@ "source": "/ecosystem/tma/mate/hosting", "destination": "/ecosystem/tma/overview", "permanent": true + }, + { + "source": "/foundations/services", + "destination": "/foundations/web3/overview", + "permanent": true } ] } diff --git a/foundations/services.mdx b/foundations/web3/overview.mdx similarity index 64% rename from foundations/services.mdx rename to foundations/web3/overview.mdx index 0920aff44..249d12d09 100644 --- a/foundations/services.mdx +++ b/foundations/web3/overview.mdx @@ -1,5 +1,6 @@ --- title: "Web3 services" +sidebarTitle: "Overview" --- import { Image } from '/snippets/image.jsx'; @@ -30,17 +31,17 @@ The TON Distributed Hash Table (DHT) plays a crucial role in the networking comp ## TON Storage -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. +[TON Storage](/foundations/web3/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. ## 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. +[TON Proxy](/foundations/web3/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. -Running TON Proxy allows you to visit TON Sites (HTTP over ADNL). This can be combined with TON DNS and other TON Services, forming together what is called "Open Network". +Running TON Proxy allows you to visit [TON Sites](/foundations/web3/ton-sites) (HTTP over ADNL). This can be combined with TON DNS and other TON Services, forming together what is called "Open Network". ## TON DNS -TON DNS is a service that translates human-readable domain names like `test.ton` or `mysite.temp.ton` into TON smart contract addresses, ADNL addresses used by services on the TON Network such as TON Sites, and more. The standard is implemented using smart contracts and config parameters. +[TON DNS](/foundations/web3/ton-dns) is a service that translates human-readable domain names like `test.ton` or `mysite.temp.ton` into TON smart contract addresses, ADNL addresses used by services on the TON Network such as TON Sites, and more. The standard is implemented using smart contracts and config parameters. TON Domain names are well-established in the ecosystem - various wallet applications and explorers recognize them. diff --git a/foundations/web3/ton-dns.mdx b/foundations/web3/ton-dns.mdx new file mode 100644 index 000000000..8730a0f00 --- /dev/null +++ b/foundations/web3/ton-dns.mdx @@ -0,0 +1,93 @@ +--- +title: "TON DNS" +description: "On-chain hierarchical domain name service for TON Network" +--- + +TON DNS is a service for translating human-readable domain names (such as `example.ton` or `mysite.temp.ton`) into TON smart contract addresses, ADNL addresses used by services on the TON Network, and other network entities. + +## What TON DNS resolves + +TON DNS records can point to several types of addresses: + +- **Wallet addresses**: on-chain smart contract addresses stored under the `wallet` category, allowing users to send cryptocurrency directly to a human-readable domain name instead of a raw address. +- **ADNL addresses**: used to locate TON Sites running on the TON Network. +- **TON Storage Bag IDs**: identifiers for files and data stored via TON Storage. +- **Next resolver references**: delegation of subdomains to another DNS smart contract. +- **Text records**: arbitrary UTF-8 text associated with a domain name. + +## Implementation + +TON DNS is built as a tree of DNS smart contracts. The root contract lives on the masterchain; its address is stored in blockchain configuration parameter #4. `.ton` is the only first-level domain. Each `.ton` domain is an NFT following the TEP-0081 standard: the resolver contract acts as an NFT collection and each registered domain is an NFT item, making domains transferable through any NFT-compatible wallet or marketplace. + +The `.t.me` namespace operates as a delegated sub-resolver on the same infrastructure, implementing the same `dnsresolve` interface and supporting the same record types as `.ton` domains. + +Every DNS smart contract exposes a `dnsresolve` get-method: + +```func +(int, cell) dnsresolve(slice subdomain, int category) +``` + +`subdomain` is the portion of the domain name remaining to be resolved. `category` is the SHA-256 hash of the record category name, or `0` to retrieve all records. The method returns the number of bits consumed and a cell containing the DNS record. If fewer bits were consumed than the full subdomain length, the returned cell is a `dns_next_resolver` pointing to the contract that handles the remainder. + +## DNS record types + +DNS record values are described by TL-B schemas. The following record types are defined: + +- `dns_adnl_address`: stores a 256-bit ADNL address for network services such as TON Sites. An optional protocol list describes supported protocols. + + ```tlb + dns_adnl_address#ad01 adnl_addr:bits256 flags:(## 8) { flags <= 1 } + proto_list:flags . 0?ProtoList = DNSRecord; + ``` + +- `dns_smc_address`: stores any smart contract address on the TON Blockchain, including wallets. An optional capability list describes the capabilities of the contract. Under the standard `wallet` category, this record enables sending funds to a domain name. + + ```tlb + dns_smc_address#9fd3 smc_addr:MsgAddressInt flags:(## 8) { flags <= 1 } + cap_list:flags . 0?SmcCapList = DNSRecord; + ``` + +- `dns_next_resolver`: delegates resolution of subdomains to another DNS smart contract at the specified address. + + ```tlb + dns_next_resolver#ba93 resolver:MsgAddressInt = DNSRecord; + ``` + +- `dns_storage_address`: stores a 256-bit TON Storage Bag ID, allowing domain names to be assigned to files stored via TON Storage. + + ```tlb + dns_storage_address#7473 bag_id:bits256 = DNSRecord; + ``` + +- `dns_text`: stores arbitrary UTF-8 text using the `Text` chunked encoding defined in the block layout specification. + + ```tlb + dns_text#1eda _:Text = DNSRecord; + ``` + +### Record categories + +When querying a DNS contract, the caller specifies a category to select which record type to retrieve. Categories are identified by the SHA-256 hash of a UTF-8 category name string. The standard categories defined by TEP-0081 are: + +| Category name | Purpose | +| ------------------- | ------------------------------------------ | +| `wallet` | Default wallet address (`dns_smc_address`) | +| `site` | TON Site ADNL address (`dns_adnl_address`) | +| `dns_next_resolver` | Subdomain delegation (`dns_next_resolver`) | +| `storage` | TON Storage Bag ID (`dns_storage_address`) | + +Passing category `0` retrieves all records stored for the domain. + +## Domain lifecycle + +Registered domains must be renewed annually by sending 0.015 TON to the domain contract. There is no grace period: once a domain has gone more than one year without renewal, anyone can trigger its release by calling `dns_balance_release` on the contract with a minimum payment. The domain then re-enters auction for one week, with the caller as the initial bidder. + +## Ecosystem integration + +TON domain names such as `.ton` domains are recognized by wallet applications and explorers in the TON ecosystem. Users can send cryptocurrency to a TON DNS domain name instead of copying a 256-bit account identifier. + +TON DNS also integrates with other TON services: + +- [TON Sites](/foundations/web3/ton-sites): a `dns_adnl_address` record pointing to an ADNL address gives a site a human-readable `.ton` domain. +- [TON Storage](/foundations/web3/ton-storage): a `dns_storage_address` record maps a domain name to a Bag ID, making stored files addressable by name. +- [TON Proxy](/foundations/web3/ton-proxy): resolves `.ton` domains to ADNL addresses before routing HTTP traffic to the target site. diff --git a/foundations/web3/ton-proxy.mdx b/foundations/web3/ton-proxy.mdx new file mode 100644 index 000000000..c56750575 --- /dev/null +++ b/foundations/web3/ton-proxy.mdx @@ -0,0 +1,136 @@ +--- +title: "TON Proxy" +description: "HTTP-to-ADNL bridge for accessing and hosting TON Sites from a conventional browser" +--- + +TON Proxy is an HTTP-to-ADNL bridge that allows ordinary web browsers to access TON Sites. It is implemented by the `rldp-http-proxy` binary, which operates as a forward proxy for clients and as a reverse proxy for servers hosting TON Sites. + +## How TON Proxy works + +`rldp-http-proxy` runs locally and listens for HTTP requests from a web browser. When a request arrives for a `.ton` domain, the proxy resolves it via TON DNS to an ADNL address, then forwards the HTTP request over RLDP to the target TON Site. + +By default the forward proxy only intercepts requests for `.ton`, `.adnl`, and `.bag` hostnames; all other requests pass through unchanged. Setting `-P YES` makes the proxy intercept all HTTP requests regardless of suffix. + +### Forward proxy (client-side) + +To start a local forward proxy: + +```bash +rldp-http-proxy -p 8080 -c 3333 -C global.config.json +``` + +Configure the browser to use `127.0.0.1:8080` as an HTTP proxy. TON Sites are then reachable by their `.ton` domain names. + +| Flag | Long form | Description | +| -------------- | ------------------- | ------------------------------------------------------------------------ | +| `-p ` | `--port` | HTTP listening port for browser connections | +| `-c ` | `--client-port` | UDP port for client ADNL queries | +| `-C ` | `--global-config` | Path to the TON global network config file | +| `-P ` | `--proxy-all` | Proxy all HTTP requests, not only `.ton`, `.adnl`, `.bag` (default `NO`) | +| `-S ` | `--storage-gateway` | ADNL address of a TON Storage gateway for `.bag` resolution | +| `-D ` | `--db` | Database root path | +| `-d` | `--daemonize` | Daemonize the process | +| `-l ` | `--logname` | Log file path | + +## Reverse proxy mode + +`rldp-http-proxy` also operates as a reverse proxy for servers hosting TON Sites. In this mode it accepts inbound ADNL connections and forwards HTTP requests to a local or remote web server. Two implementations are available. + +### Use rldp-http-proxy + +`rldp-http-proxy` is the reverse proxy from the official TON monorepo. Key generation is manual. + +**Step 1.** Generate a persistent ADNL address: + +```bash +mkdir keyring +utils/generate-random-id -m adnlid +``` + +The command prints two values to stdout: the hex address and its user-friendly form: + +```text +45061C1D4EC44A937D0318589E13C73D151D1CEF5D3C0E53AFBCF56A6C2FE2BD vcqmha5j3ceve35ammfrhqty46rkhi455otydstv66pk2tmf7rl25f3 +``` + +It also writes the private key to a file named after the hex address. Move it into the keyring directory: + +```bash +mv 45061C1D* keyring/ +``` + +**Step 2.** Start the reverse proxy, using the user-friendly ADNL address from step 1: + +```bash +rldp-http-proxy -a :3333 -L '*' -C global.config.json -A -d -l tonsite.log +``` + +| Flag | Description | +| ------------------------------------- | ------------------------------------------------------------------------------ | +| `-a :` | Public IP and UDP port for inbound ADNL connections (published to the TON DHT) | +| `-A ` | ADNL address generated in step 1 | +| `-L [:]` | Forward requests for `` to `127.0.0.1` (default ports: 80, 443) | +| `-R [:]@:` | Forward requests for `` to a remote HTTP server at `:` | +| `-C ` | Path to the TON global network configuration file | +| `-D ` | Database root path | +| `-d` | Daemonize the process | +| `-l ` | Log file path | + +### Use `tonutils-reverse-proxy` + +`tonutils-reverse-proxy` is a Go implementation that handles key generation and domain linking automatically. + +**Install on Linux:** + +```bash +wget https://github.com/tonutils/reverse-proxy/releases/latest/download/tonutils-reverse-proxy-linux-amd64 +chmod +x tonutils-reverse-proxy-linux-amd64 +``` + +To build from source: + +```bash +git clone https://github.com/tonutils/reverse-proxy +cd reverse-proxy && make build +``` + +Run with the target `.ton` domain: + +```bash +./tonutils-reverse-proxy --domain .ton +``` + +On first run, the proxy generates a persistent ADNL key pair and displays a QR code. Scan it with a compatible TON wallet (such as Tonkeeper) to confirm domain ownership and link the ADNL address to the domain. + +The web server must listen on `http://127.0.0.1:80`. The proxy adds two headers to each forwarded request: + +- `X-Adnl-Ip`: the IP address of the connecting client as seen by the ADNL network. +- `X-Adnl-Id`: the ADNL node ID of the connecting client. + +### Domain assignment + +To assign the ADNL address to a `.ton` domain, open the domain in the TON DNS management interface, paste the ADNL address into the "Site" field, and confirm the transaction with the domain owner's wallet. For record types and domain assignment context, see [TON DNS](/foundations/web3/ton-dns). + +## Security and privacy + +All traffic between the proxy and the TON Site is encrypted at the ADNL layer. The server is authenticated by its ADNL address, derived from its public key. + +The server IP is published to the TON DHT for ADNL routing but is not exposed at the HTTP layer. The proxy does not forward client network information to the upstream web server. + +## Response headers + +The proxy adds version headers to all responses. + +| Header | Added by | Value format | +| ------------------------- | --------------------------- | ----------------------------- | +| `Ton-Proxy-Site-Version` | Reverse proxy (server-side) | `Commit: , Date: ` | +| `Ton-Proxy-Entry-Version` | Forward proxy (client-side) | `Commit: , Date: ` | + +The proxy also supports the HTTP `CONNECT` method, which enables WebSocket connections and other TCP-based protocols to be tunneled over ADNL. + +## Related components + +- **ADNL**: the abstract datagram network layer used to reach TON Sites by their abstract address. +- **RLDP**: the reliable large datagram protocol over ADNL that carries HTTP requests and responses. +- [TON Sites](/foundations/web3/ton-sites): web services accessible through TON Proxy. +- [TON DNS](/foundations/web3/ton-dns): resolves `.ton` domain names to ADNL addresses for request routing. diff --git a/foundations/web3/ton-sites.mdx b/foundations/web3/ton-sites.mdx new file mode 100644 index 000000000..cfe9897cf --- /dev/null +++ b/foundations/web3/ton-sites.mdx @@ -0,0 +1,115 @@ +--- +title: "TON Sites" +description: "Web services accessible through TON Network via ADNL and RLDP" +--- + +TON Sites are web services that support an HTTP interface. They use RLDP datagrams over the ADNL protocol to transfer HTTP queries and responses, residing entirely within the TON Network. A TON Site is identified by its ADNL address rather than an IP address, so no IP address appears in the URL or at the HTTP layer. + +## How TON Sites work + +When a user visits a TON Site: + +1. The TON Proxy client accepts an HTTP request from an ordinary web browser. +1. The proxy resolves the target address, either through TON DNS (for human-readable `.ton` domains) or directly from a known ADNL address. +1. The HTTP request is encapsulated in RLDP datagrams and sent through the ADNL network to the TON Site's abstract address. +1. The TON Site processes the request and returns an HTTP response. + +## ADNL address as identity + +Every TON Site is identified by a 256-bit ADNL abstract address derived from its public key. Because the ADNL address is independent of the server's IP address, a site is not tied to any particular server location. + +## Host a TON Site + +A TON Site requires a reverse proxy that accepts inbound ADNL connections and forwards them to a local web server. Two implementations are available. + +### Use `rldp-http-proxy` + +`rldp-http-proxy` is the reverse proxy from the official TON monorepo. Key generation is manual. + +**Step 1.** Generate a persistent ADNL address: + +```bash +mkdir keyring +utils/generate-random-id -m adnlid +``` + +The command prints two values to stdout: the hex address and its user-friendly form: + +```text +45061C1D4EC44A937D0318589E13C73D151D1CEF5D3C0E53AFBCF56A6C2FE2BD vcqmha5j3ceve35ammfrhqty46rkhi455otydstv66pk2tmf7rl25f3 +``` + +It also writes the private key to a file named after the hex address. Move it into the keyring directory: + +```bash +mv 45061C1D* keyring/ +``` + +**Step 2.** Start the reverse proxy, using the user-friendly ADNL address from step 1: + +```bash +rldp-http-proxy -a :3333 -L '*' -C global.config.json -A -d -l tonsite.log +``` + +| Flag | Description | +| ------------------------------------- | ------------------------------------------------------------------------------ | +| `-a :` | Public IP and UDP port for inbound ADNL connections (published to the TON DHT) | +| `-A ` | ADNL address generated in step 1 | +| `-L [:]` | Forward requests for `` to `127.0.0.1` (default ports: 80, 443) | +| `-R [:]@:` | Forward requests for `` to a remote HTTP server at `:` | +| `-C ` | Path to the TON global network configuration file | +| `-D ` | Database root path | +| `-d` | Daemonize the process | +| `-l ` | Log file path | + +### Use `tonutils-reverse-proxy` + +`tonutils-reverse-proxy` is a Go implementation that handles key generation and domain linking automatically. + +**Install on Linux:** + +```bash +wget https://github.com/tonutils/reverse-proxy/releases/latest/download/tonutils-reverse-proxy-linux-amd64 +chmod +x tonutils-reverse-proxy-linux-amd64 +``` + +To build from source: + +```bash +git clone https://github.com/tonutils/reverse-proxy +cd reverse-proxy && make build +``` + +Run with the target `.ton` domain: + +```bash +./tonutils-reverse-proxy --domain .ton +``` + +On first run, the proxy generates a persistent ADNL key pair and displays a QR code. Scan it with a compatible TON wallet (such as Tonkeeper) to confirm domain ownership and link the ADNL address to the domain. + +The web server must listen on `http://127.0.0.1:80`. The proxy adds two headers to each forwarded request: + +- `X-Adnl-Ip`: the IP address of the connecting client as seen by the ADNL network. +- `X-Adnl-Id`: the ADNL node ID of the connecting client. + +### Domain assignment + +To assign the ADNL address to a `.ton` domain, open the domain in the TON DNS management interface, paste the ADNL address into the "Site" field, and confirm the transaction with the domain owner's wallet. For record types and resolution details, see [TON DNS](/foundations/web3/ton-dns). + +## Domain name resolution + +### TON DNS + +A `dns_adnl_address` record in TON DNS maps a `.ton` domain name to the ADNL address of the TON Site. The proxy client resolves this record and connects to the correct ADNL address. See [TON DNS](/foundations/web3/ton-dns) for the full record type specification. + +### Direct access via ADNL address + +TON Sites can also be accessed directly by their ADNL address, without DNS resolution. + +## Related components + +- **ADNL**: the abstract datagram network layer providing transport for TON Sites. +- **RLDP**: the reliable large datagram protocol over ADNL for HTTP transfer. +- [TON Proxy](/foundations/web3/ton-proxy): bridges HTTP requests from a conventional browser to the ADNL network. +- [TON DNS](/foundations/web3/ton-dns): maps `.ton` domains to ADNL addresses. diff --git a/foundations/web3/ton-storage.mdx b/foundations/web3/ton-storage.mdx new file mode 100644 index 000000000..f877c326e --- /dev/null +++ b/foundations/web3/ton-storage.mdx @@ -0,0 +1,81 @@ +--- +title: "TON Storage" +description: "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 +storage-daemon -v 3 -C global.config.json -I :3333 -p 5555 -D storage-db +``` + +### Manage bags + +| Command | Description | +| ---------------------------------- | ---------------------------------------------------------- | +| `create -d "description"` | Create a new bag from a file or directory | +| `add-by-hash -d ` | Add a bag by its `BagID` | +| `add-by-meta -d ` | Add a bag from a metafile | +| `list` | List all bags | +| `list --hashes` | List bags with their `BagID`s | +| `get ` | Show full bag information | +| `get-peers ` | Show peers connected for a bag | +| `get-meta ` | Export the bag metafile | +| `download-pause ` | Pause a download | +| `download-resume ` | Resume a download | +| `priority-name ` | 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 +add-by-hash --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. +1. A client creates a bag and sends a storage request to the provider contract. +1. The provider contract deploys a per-bag storage contract and notifies the client. +1. The provider downloads the bag and activates the per-bag contract. +1. The client transfers payment. The provider submits periodic Merkle proofs to prove data possession. +1. 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 +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:///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). diff --git a/from-ethereum.mdx b/from-ethereum.mdx index 3cd740746..c47f6e0da 100644 --- a/from-ethereum.mdx +++ b/from-ethereum.mdx @@ -108,6 +108,6 @@ Due to significant differences in execution models, most of the standards in TON | Non-fungible token standard | ERC-721 | [NFT standard (TEP-0062)](/standard/tokens/nft/overview) | | Token metadata | ERC-4955 (Not exactly, but close match) | [Token Data Standard (TEP-0064)](/standard/tokens/metadata) | | NFT royalty standard | EIP-2981 | [NFT Royalty Standard (TEP-0066)](/standard/tokens/nft/comparison) | -| DNS-like registry | ENS (EIP-137) | [DNS Standard (TEP-0081)](/foundations/services) | +| DNS-like registry | ENS (EIP-137) | [DNS Standard (TEP-0081)](/foundations/web3/overview) | | Soulbound / account-bound token concept | EIP-4973 | [SBT Standard (TEP-0085)](/standard/tokens/nft/comparison#sbt) | | Wallet connection protocol | WalletConnect / EIP-1193 | [TonConnect (TEP-0115)](/ecosystem/ton-connect/overview) | diff --git a/resources/dictionaries/custom.txt b/resources/dictionaries/custom.txt index b314f0a4b..adb7f34df 100644 --- a/resources/dictionaries/custom.txt +++ b/resources/dictionaries/custom.txt @@ -607,6 +607,7 @@ Revm RIST Ristretto RLDP +rldp rollup Rollup RPCs @@ -743,6 +744,7 @@ Tonscan tonscan.com tonscan.org Tonstakers +tonutils Tonviewer tonviewer.com toolchain