feat(web3): add Web3 services overview pages #2007
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| --- | ||
| title: "Overview" | ||
| --- | ||
|
|
||
| import { Image } from '/snippets/image.jsx'; | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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>` | `--port` | HTTP listening port for browser connections | | ||
| | `-c <port>` | `--client-port` | UDP port for client ADNL queries | | ||
| | `-C <file>` | `--global-config` | Path to the TON global network config file | | ||
| | `-P <YES\|NO>` | `--proxy-all` | Proxy all HTTP requests, not only `.ton`, `.adnl`, `.bag` (default `NO`) | | ||
| | `-S <adnl>` | `--storage-gateway` | ADNL address of a TON Storage gateway for `.bag` resolution | | ||
| | `-D <path>` | `--db` | Database root path | | ||
| | `-d` | `--daemonize` | Daemonize the process | | ||
| | `-l <file>` | `--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 <ip>:3333 -L '*' -C global.config.json -A <adnl-address> -d -l tonsite.log | ||
| ``` | ||
|
|
||
| | Flag | Description | | ||
| |---|---| | ||
| | `-a <ip>:<port>` | Public IP and UDP port for inbound ADNL connections (published to the TON DHT) | | ||
| | `-A <adnl-address>` | ADNL address generated in step 1 | | ||
| | `-L <hostname>[:<ports>]` | Forward requests for `<hostname>` to `127.0.0.1` (default ports: 80, 443) | | ||
| | `-R <hostname>[:<ports>]@<ip>:<port>` | Forward requests for `<hostname>` to a remote HTTP server at `<ip>:<port>` | | ||
| | `-C <file>` | Path to the TON global network configuration file | | ||
| | `-D <path>` | Database root path | | ||
| | `-d` | Daemonize the process | | ||
| | `-l <file>` | 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 <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: <sha>, Date: <date>` | | ||
| | `Ton-Proxy-Entry-Version` | Forward proxy (client-side) | `Commit: <sha>, Date: <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. | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.