feat: expand TON Web3 documentation

content/foundations/meta.json

@@ -17,7 +17,6 @@
     "limits",
     "config",
     "network",
-    "web3",
     "proofs",
     "system",
     "precompiled",

content/foundations/web3/meta.json

@@ -6,6 +6,8 @@
     "ton-dns",
     "ton-storage",
     "ton-proxy",
-    "ton-sites"
+    "ton-tunnel",
+    "ton-sites",
+    "payment-network"
   ]
 }

content/foundations/web3/overview.mdx

@@ -3,52 +3,63 @@ title: "Web3 services"
 sidebarTitle: "Overview"
 ---
 
-Although many people refer to TON only as a blockchain, _The Open Network_ is a combination of the following components:
+The Open Network (TON) combines a blockchain with a peer-to-peer network and services for naming, file storage, web access, and off-chain payments. Applications can use these components together or select the ones they need.
 
-- A flexible multi-blockchain platform with Turing-complete smart contracts (TON Blockchain)
-- A peer-to-peer network used by Blockchain Nodes (TON Network)
-- A distributed file storage technology (TON Storage)
-- A network proxy/anonymizer layer (TON Proxy)
-- A Kademlia-like distributed hash table (TON DHT)
-- 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.
+Smart contracts manage on-chain state and enforce contract rules. Files, HTTP requests, and application processing can remain off-chain. For example, a website can serve its content over the TON network, use an on-chain domain record, and accept payments through payment channels.
 
 ## 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 network carries communication between blockchain nodes and supports services beyond the blockchain.
+
+The [Abstract Datagram Network Layer (ADNL)](/foundations/network/adnl) identifies peers by cryptographic addresses and provides encrypted communication. The [distributed hash table (DHT)](/foundations/network/dht) helps locate peers and discover nodes participating in services such as TON Storage.
 
-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.
+These networking components let applications exchange data without recording each exchange as a blockchain transaction.
 
 <Image
   src="/images/open-network/adnl.png"
   darkSrc="/images/open-network/adnl.png"
-  alt="adnl"
+  alt="TON network stack with ADNL over UDP and DHT, RLDP, and overlay networks above ADNL"
 />
 
+## TON DNS
+
+[TON DNS](/foundations/web3/ton-dns) associates human-readable domain names with addresses and services. Records stored in smart contracts can identify payment recipients, TON Sites, files on TON Storage, or another resolver responsible for subdomains.
+
+A domain such as `example.ton` can have several records for different purposes. Applications request the record they need, then use the returned address or content identifier to access the destination.
+
 ## TON Storage
 
-[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 Storage](/foundations/web3/ton-storage) distributes files between peers. Files are grouped into a bag, identified by a BagID, which allows recipients to verify the downloaded content. The files remain on peers' disks.
+
+Sharing files does not require an on-chain transaction. Optional storage contracts let clients pay providers to retain data and submit storage proofs. File availability still depends on peers retaining and serving the content.
 
 ## TON Proxy
 
-[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.
+[TON Proxy](/foundations/web3/ton-proxy) connects HTTP clients and servers through the TON 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".
+A forward proxy accepts requests from a browser or another HTTP client and sends them over the Reliable Large Datagram Protocol (RLDP), which runs over ADNL. A reverse proxy receives these requests and forwards them to an HTTP server.
 
-## TON DNS
+Compatible forward proxies also provide access to files on TON Storage.
+
+## TON Tunnel
+
+[TON Tunnel](/foundations/web3/ton-tunnel) routes ADNL traffic through intermediate nodes. Applications with tunnel support can use relays instead of communicating directly from their own network endpoints.
+
+Relays can forward traffic for free or charge through TON Payment Network. Tunnel routing applies to the traffic sent through the application's integration.
+
+## TON Sites
 
-[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 Sites](/foundations/web3/ton-sites) are websites and HTTP applications accessible through the TON network. They can be published in two ways:
 
-TON Domain names are well-established in the ecosystem - various wallet applications and explorers recognize them.
+- Connect an HTTP server through a reverse proxy to serve static files or dynamically generated responses.
+- Publish static files as a bag on TON Storage.
 
-TON Domains can be assigned to any ADNL address, meaning that it is possible to assign names to TON Storage files (bags).
+TON DNS can associate a domain with either the reverse proxy's ADNL address or the storage BagID. Visitors access the site through a compatible client or a browser configured with a forward proxy.
 
 ## TON Payments
 
-TON Payments platform enables "instant payments" - a way to transfer monetary values without the need to commit all transactions to the blockchain. This protocol is built on top of TON Blockchain, using a system of smart contracts.
+[TON Payment Network](/foundations/web3/payment-network) supports off-chain payments through interconnected payment channels.
 
-The core idea for such a "lightning network" is point-to-point **payment channels**. Two parties create a shared "money pool" and then update the balance inside it.
+Participants fund channels on-chain, then exchange signed state updates without submitting each payment to the blockchain. Smart contracts provide settlement and dispute procedures. Payments can also pass through intermediate nodes when a route has sufficient capacity.
 
-The overall overhead of such instant payments is so small that one can use them for micro-payments. For example, a TON file-storing service might charge the user for every 128 KiB of downloaded data, or a paid TON Proxy might require some tiny micro-payment for every 128 KiB of traffic relayed.
+Applications can use these channels for repeated small payments, including payments to TON Tunnel relays.

content/foundations/web3/payment-network/browser.mdx

@@ -0,0 +1,90 @@
+---
+title: "How to run Payment Network in a browser"
+sidebarTitle: "Run in a browser"
+description: "Build the supplied WebAssembly example and connect it to a payment node"
+---
+
+Build the browser example included in TON Payment Network v1.3.2 and connect it to a payment node. The example includes wallet callbacks, browser storage, and channel controls.
+
+## Prerequisites
+
+- The v1.3.2 repository and a configured mainnet node from [Run a payment node](/foundations/web3/payment-network/run-node)
+- [Go 1.26.1](https://go.dev/dl/), [Node.js 22.23.2](https://nodejs.org/en/download), and npm 10.9.8 for the build below
+- A mainnet wallet compatible with [TON Connect](/applications/ton-connect/how-to/connect) for the interactive channel workflow
+
+The commands require a POSIX shell. The build below uses the standard Go compiler and its matching JavaScript runtime. The repository also provides TinyGo build targets; do not mix their runtime files with this build.
+
+<Callout
+  type="caution"
+  title="Browser keys and channel state"
+>
+  The client stores configuration and private keys in localStorage and channel state in IndexedDB, associated with the wallet address. Preserve the browser profile and origin while channels are active. Clearing site data can remove state needed to continue or settle channels; connecting the same wallet in another browser does not restore it.
+</Callout>
+
+## Enable the node's web transport
+
+Stop the payment node and set [`WebTransportListenAddr`](/foundations/web3/payment-network/reference#configuration-fields) to `127.0.0.1:7161` in its existing configuration. Preserve its keys, network, and database settings, then restart it.
+
+From the repository root, print its public browser initializer with [`-web-conn-info`](/foundations/web3/payment-network/reference#cli-options):
+
+```bash
+./build/payment-node -config payment-network-config.json -web-conn-info
+```
+
+Copy the two public keys into the `window.startPaymentNetwork(...)` call in `cmd/web/web-payments-frontend/src/App.tsx`, replacing the bundled demonstration keys. The first key identifies the node's [Abstract Datagram Network Layer (ADNL) transport](/foundations/network/adnl-udp); the second identifies its payment node.
+
+The supplied `src/setupProxy.js` forwards `/web-channel/api/` requests to `http://localhost:7161`. This is the node's web transport, not its administration API.
+
+## Run the example locally
+
+From the repository root:
+
+```bash
+GOOS=js GOARCH=wasm go build -o cmd/web/web-payments-frontend/public/web.wasm ./cmd/web
+cp "$(go env GOROOT)/lib/wasm/wasm_exec.js" cmd/web/web-payments-frontend/public/wasm_exec.js
+cd cmd/web/web-payments-frontend
+npm ci --legacy-peer-deps
+```
+
+Set the URLs in `public/tonconnect-manifest.json` to match the served application, then start the local development server with its API forwarding:
+
+```bash
+PORT=3001 npm start
+```
+
+Open `http://localhost:3001`. For a wallet on another device, use a reachable deployment and manifest URL following the [TON Connect setup guide](/applications/ton-connect/how-to/connect); that wallet cannot reach the development computer through its own `localhost`.
+
+The example also contains demonstration asset and trading settings. Review them before enabling assets or deploying the application; they are not a list of supported mainnet assets for the node.
+
+## Build for production (optional)
+
+<span
+  id="optional-production-build"
+/>
+
+After setting the deployment URLs in `public/tonconnect-manifest.json`, run from the frontend directory:
+
+```bash
+npm run build
+```
+
+The output is written to `build/`. The static build does not include `src/setupProxy.js`; configure `/web-channel/api/` forwarding to the node's web transport separately on the deployment.
+
+## Verify
+
+Check that `web.wasm` and `wasm_exec.js` load successfully. With a connected wallet, the page starts the payment node and displays channel information. Ensure that the wallet and backend node use mainnet before requesting an on-chain action.
+
+<Callout type="caution">
+  Mainnet transactions are irreversible. Verify the destination and amount before confirming in the wallet.
+</Callout>
+
+Use the example's channel controls to open and fund a channel and send a payment. Check wallet transaction details before confirming, then inspect the resulting channel balances.
+
+## Troubleshoot
+
+| Problem                                    | Check                                                                   |
+| ------------------------------------------ | ----------------------------------------------------------------------- |
+| WebAssembly fails to load                  | Build `web.wasm` and copy `wasm_exec.js` from the same Go installation. |
+| Browser cannot reach the payment node      | Check the web transport listener and `/web-channel/api/` forwarding.    |
+| Peer authentication or channel setup fails | Replace both bundled keys with values from the node's initializer.      |
+| Wallet rejects the application manifest    | Check that its URLs match a deployment reachable by the wallet.         |