add substrate-connect tutorial

content/config/nav.yaml

@@ -198,6 +198,15 @@ tutorials:
           url: /tutorials/smart-contracts/erc20-token/
         - title: Troubleshoot smart contracts
           url: /tutorials/smart-contracts/sc-common-issues/
+    - title: Run a Light Client in your browser
+      url: /tutorials/light-clients/
+      pages:
+        - title: Download the browser extension
+          url: /tutorials/light-clients/substrate-connect/
+        - title: Connect with a well-known relay-chain
+          url: /tutorials/light-clients/production-relays/
+        - title: Connect with a parachain
+          url: /tutorials/light-clients/production-parachains/
 reference:
   title: Reference
   url: /reference/

content/md/en/docs/tutorials/connect-other-chains/parachain.md

@@ -417,7 +417,7 @@ This command is nearly identical to the one we used to start the first collator,
 --ws-port 9946 \
 -- \
 --execution wasm \
---chain <relay-chain chain spec> \
+--chain <relay chain chain spec> \
 --port 30344 \
 --ws-port 9978
 --bootnodes <other relay chain node>
@@ -436,7 +436,7 @@ In this case, simply leave out the `--collator` flag.
   --port <Your chosen libp2p port> \
   --parachain-id <Your ID> \
   -- \
-  --chain <relay-chain chain spec> \
+  --chain <relay chain chain spec> \
   --bootnodes <other relay chain node>
 ```
 

content/md/en/docs/tutorials/index.md

@@ -51,3 +51,11 @@ You'll learn how to:
 - Store, increment, and retrieve simple values using a smart contract.
 - Use maps to store and retrieve values in a smart contract.
 - Build a smart contract for transferring ERC-20 tokens.
+
+## Run a Light Client in your browser
+
+The **Run a Light Client in your browser** tutorials show how you can bypass the need to connect to an RPC node and push decentralization even further. You'll learn how to:
+
+- Download the browser extension
+- Connect with a well-known relay chain
+- Connect with a parachain

content/md/en/docs/tutorials/light-clients/index.md

@@ -0,0 +1,12 @@
+---
+title: Run a Light Client in your browser
+description: Introduces tutorials for running in-browser light clients via Substrate Connect.
+keywords:
+---
+
+The **Run a Light Client in your browser** tutorials show how you can bypass the need to connect to an RPC node and push decentralization even further.
+You'll learn how to:
+
+- [Substrate Connect browser extension](/tutorials/light-clients/browser-extension/) describes why and how to download the Substrate Connect browser extension.
+- [Connect with a production relay chain](/tutorials/light-clients/well-known-relay/) describes how to connect to a well-known relay chain.
+- [Connect to a parachain with a light client](/tutorials/light-clients/parachains/) describes how to connect to any parachain.

content/md/en/docs/tutorials/light-clients/production-parachains.md

@@ -0,0 +1,73 @@
+---
+title: Connect to a parachain with a light client
+description: How to connect to a parachain via Substrate Connect.
+keywords:
+---
+
+## Before you begin
+
+Before you begin, make sure you have installed the [Substrate Connect browser extension](/tutorials/light-clients/substrate-connect/), and that you have learned how to [connect with a production relay chain](/tutorials/light-client/production-relays/)).
+
+## Tutorial objectives
+
+By completing this tutorial, you will accomplish the following objectives:
+
+- Learn how to load a chainspec into the light client.
+- Create a basic webapp that connects to a parachain from the browser.
+
+## Connect to Statemint
+
+This tutorial is very similar to the [connect with a production relay chain](/tutorials/light-client/production-relays/) tutorial, but instead of using a chainspec that's embedded into the Substrate Connect library, we are going to explicitly provide it to our code.
+
+We want to connect to Statemint, a common-goods parachain connected to Polkadot. You can download its chainspec from the [cumulus repository](https://github.com/paritytech/cumulus/blob/master/parachains/chain-specs/statemint.json).
+
+Go ahead and save it into the same directory from the previous tutorial (`empty-webapp`).
+Then, edit the contents of `index.ts` so it looks like the following:
+
+```typescript
+import { ScProvider, WellKnownChain } from "@polkadot/rpc-provider/substrate-connect";
+import { ApiPromise } from "@polkadot/api";
+import jsonParachainSpec from "./statemint.json";
+
+window.onload = () => {
+  void (async () => {
+    try {
+      const relayProvider = new ScProvider(WellKnownChain.polkadot);
+      const parachainSpec = JSON.stringify(jsonParachainSpec);
+      const provider = new ScProvider(parachainSpec, relayProvider);
+
+      await provider.connect();
+      const api = await ApiPromise.create({ provider });
+      await api.rpc.chain.subscribeNewHeads((lastHeader: { number: unknown; hash: unknown }) => {
+        console.log(`New block #${lastHeader.number} has hash ${lastHeader.hash}`);
+      });
+    } catch (error) {
+      console.error(<Error>error);
+    }
+  })();
+};
+```
+
+This code is very similar to the previous one.
+The main differences are:
+
+- we are loading `statemint.json` into the `parachainSpec` variable.
+- `ScProvider` is created for relay chain but without connecting (since we will not be communicating with the relay chain).
+  This is needed as a parameter when creating the Parachain's provider as an extra parameter. Rpc Provider of substrate-connect need this, in order to connect the parachain to the respective relay chain.
+
+In the directory of the webapp, run the following again:
+
+```bash
+yarn
+yarn dev
+```
+
+That should open a browser on `http://localhost:3001/`.
+Open the JavaScript console from your browser and observe the output.
+You should see smoldot (the actual wasm light client) being initialized, followed by the hashes of the incoming blocks of Statemint.
+
+From here onwards, the usage is very similar to what would have been usually done via PolkadotJS.
+All you have to do is follow the [official documentation](https://polkadot.js.org/docs/) and interact with the chain.
+
+One important detail is that we used `@polkadot/rpc-provider/substrate-connect` as our dependency, and that is fine for a fast and easy integration into a simple webapp.
+However, more advanced implementations (e.g.: library authors) should install and use `@substrate-connect` instead.

content/md/en/docs/tutorials/light-clients/production-relays.md

@@ -0,0 +1,104 @@
+---
+title: Connect with a production relay chain
+description: How to connect to a well-known relay chain via Substrate Connect.
+keywords:
+---
+
+## Before you begin
+
+Before you begin, make sure you have installed the [Substrate Connect browser extension](/tutorials/light-clients/substrate-connect/).
+
+## Tutorial objectives
+
+By completing this tutorial, you will accomplish the following objectives:
+
+- Learn why a chainspec is necessary to start a light client.
+
+- Create a basic webapp that loads a light client into the browser.
+
+- Learn how to use an embedded chainspec on Substrate Connect for a well-known relay chain.
+
+## Basics of Chainspec 
+
+In order to connect to some network, a light client needs to be provided with a [chainspec](https://docs.substrate.io/v3/runtime/chain-specs/). It dictates which network the light client will connect to, which entities it will initially communicate with, and what consensus-critical state it must have at genesis.
+
+Connecting with the well-known relay chains is very straightforward, because Substrate Connect already comes with their chainspecs ready for usage out-of-the-box, so you don’t have to worry about them.
+
+Those well-known relay chains are:
+- Polkadot
+- Kusama
+- Rococo
+- Westend
+
+If you eventually want to connect to a different relay chain, then you will need to handle some chainspec file. But that will be explained later on in this tutorial, for now, let’s focus on the well-known chains!
+
+## Connect to Polkadot
+
+First, start by cloning a template for an empty webapp:
+```bash
+git clone https://github.com/bernardoaraujor/empty-webapp
+cd empty-webapp
+```
+
+After that, install the necessary dependencies:
+```bash
+yarn add @polkadot/rpc-provider
+yarn add @polkadot/api
+```
+
+You should notice that `index.ts` is empty. Go ahead and paste the following contents inside of it:
+```typescript
+import {
+  ScProvider,
+  WellKnownChain,
+} from "@polkadot/rpc-provider/substrate-connect";
+import { ApiPromise } from "@polkadot/api";
+
+window.onload = () => {
+  void (async () => {
+    try {
+      const provider = new ScProvider(WellKnownChain.polkadot);
+
+      await provider.connect();
+      const api = await ApiPromise.create({ provider });
+      await api.rpc.chain.subscribeNewHeads(
+        (lastHeader: { number: unknown; hash: unknown }) => {
+          console.log(
+            `New block #${lastHeader.number} has hash ${lastHeader.hash}`
+          );
+        }
+      );
+    } catch (error) {
+      console.error(<Error>error);
+    }
+  })();
+};
+
+```
+
+If you’re familiar with PolkadotJS, you might have noticed this code is very similar to the traditional approach taken there. The only difference is that instead of using a `WsProvider`, we are now using a `ScProvider`.
+
+Also, notice that instead of a WebSocket URL, which would have been the address of a client, we used `WellKnownChain.polkadot`, which represents the chainspec for the Polkadot network.
+
+You can provide any of these network ids:
+- `polkadot`
+- `ksmcc3`
+- `westend2`
+- `rococo_v2_2`
+
+Note that these are the "real" names of the chains rather than the names they are more commonly known as (such as Kusama or Rococo). For example, "ksmcc3" is the name of Kusama. This is important for chains which have been hard forked. For example, “rococo_v2" and "rococo_v2_2" are two different chains. Hopefully, polkadot will never go through a hard fork, but all the other three are subject to change in the future. You can keep track of the current chainspec files provided by Substrate Connect [here](https://bit.ly/3NQl48N).
+
+Now it’s time to see the code in action. In the directory of the webapp, run the following:
+
+```bash
+yarn
+yarn dev
+```
+
+That should open a browser on `http://localhost:3001/`. Open the JavaScript console from your browser and observe the output. You should see smoldot (the actual wasm light client) being initialized, followed by the hashes of the incoming blocks of Polkadot.
+
+Tip: different browsers running on different Operating Systems will have different shortcuts to display the JavaScript  console. [Here](https://webmasters.stackexchange.com/a/77337) is a convenient cheat sheet.
+
+To recap what we achieved so far: we fetched block hashes without using any URL for a RPC node, which is arguably a centralized entry point to the network. And we could have done much more, not only block hashes! The point here is that after `WsProvider` is replaced with `ScProvider`, the code can be written as if it was any other app based on PolkadotJS. From here onwards, you can just follow [PolkadotJS docs](https://polkadot.js.org/docs/) and do much more.
+
+One important detail is that we used `@polkadot/rpc-provider/substrate-connect` as our dependency, and that is fine for a fast and easy integration into a simple webapp. However, more advanced implementations (e.g.: library authors) should install and use `@substrate-connect` instead.

content/md/en/docs/tutorials/light-clients/substrate-connect.md

@@ -0,0 +1,24 @@
+---
+title: Substrate Connect browser extension
+description: Why and how to download the Substrate Connect browser extension.
+keywords:
+---
+
+Substrate connect provides a way to interact with [substrate](https://substrate.dev/) based blockchains in the browser without using an RPC server.
+Substrate connect uses a [smoldot](https://github.com/paritytech/smoldot/) WASM light client to securely connect to the blockchain network without relying on specific 3rd parties.
+
+Due to browser limitations on websockets from https pages, establishing a good number of peers is difficult as many nodes need to be available with TLS.
+Substrate Connect provides a browser extension to overcome this limitation and to keep the chains synced in the background, which makes your apps faster.
+
+When building an app with Substrate Connect, it will detect whether the user has the extension and use it, or create the WASM light client in-page for them.
+Although optional, the extension allows for a few optimizations, namely:
+
+- Better resource usage: multiple browser tabs can share a single connection to the same chain, instead of each opening their own connection.
+- Better synchronization speed: the browser extension automatically starts synchronizing the chain when the browser starts, and holds a cache which lets it do so faster.
+  When a browser tab wants to connect to a chain, and the browser extension is installed, it is frequent that the chain connection and synchronization is instantaneous.
+  Without this browser extension, synchronizing a chain can take from 10 to 30 seconds.
+- Better connectivity, as the extension has the possibility to connect to nodes that don’t have a TLS certificate in front of them.
+
+The first step of the tutorial is to install the extension in either Firefox or Chrome:
+- Chrome: https://chrome.google.com/webstore/detail/substrate-connect-extensi/khccbhhbocaaklceanjginbdheafklai
+- Firefox: https://addons.mozilla.org/en-US/firefox/addon/substrate-connect/