chore: improve docs (#2380)

Co-authored-by: James Wilson <james@jsdw.me>

Author: ryanleecode

.changeset/plenty-taxis-wait.md

@@ -0,0 +1,8 @@
+---
+"@substrate/connect-discovery": patch
+"@substrate/smoldot-discovery": patch
+"@substrate/discovery": patch
+"@substrate/connect": patch
+---
+
+update docs

README.md

@@ -12,8 +12,9 @@
 
 - [Table of contents](#table-of-contents)
 - [Introduction](#introduction)
-  - [Overcoming Browser Limitations](#overcoming-browser-limitations)
-  - [Seamless Integration](#seamless-integration)
+  - [Write Secure and Effective dApps with the Polkadot Network](#write-secure-and-effective-dapps-with-the-polkadot-network)
+  - [Additional Resources](#additional-resources)
+  - [Why Embed a Light Client in Browser Extensions?](#why-embed-a-light-client-in-browser-extensions)
 - [Comprehensive API Documentation](#comprehensive-api-documentation)
 - [Repository Structure](#repository-structure)
   - [Packages](#packages)
@@ -27,16 +28,33 @@
 
 ## Introduction
 
-Substrate Connect offers an innovative way to interact with [Substrate](https://substrate.dev/)-based blockchains directly in your browser, eliminating the need for an RPC server. By leveraging the [smoldot](https://github.com/smol-dot/smoldot) WASM light client, it ensures a secure and efficient connection to the blockchain network without dependency on specific third parties.
+Substrate Connect provides a groundbreaking method to engage with [Substrate](https://substrate.dev/)-based blockchains directly in your browser, eliminating the need for an RPC server. By utilizing the [smoldot](https://github.com/smol-dot/smoldot) WASM light client, it ensures a secure and efficient connection to the blockchain network without reliance on specific third parties.
 
-### Overcoming Browser Limitations
+### Write Secure and Effective dApps with the Polkadot Network
 
-Browser limitations on websockets from HTTPS pages make establishing a robust number of peers challenging, as many nodes must be available with TLS. 
-Substrate Connect addresses this issue through a powerful browser extension, allowing chains to stay synced in the background, thereby significantly enhancing the performance of your applications.
+The aim of this repository is to offer NPM packages that can be used to:
 
-### Seamless Integration
+- **Provide a secure and efficient connection to the Polkadot network** via [`@substrate/connect`](./packages/connect/), leveraging the excellent [Smoldot](https://github.com/smol-dot/smoldot) WASM light client.
+- **Discover browser extensions** that implement [the discovery protocol](./packages/discovery/), including those which expose a light client via [`@substrate/smoldot-discovery`](./packages/smoldot-discovery/). Substrate Connect will automatically leverage these where possible.
+- **Easily enhance a browser extension with a light client** via [`@substrate/light-client-extension-helpers`](./packages/light-client-extension-helpers).
 
-When building an application with Substrate Connect, it automatically detects whether the user has the extension installed and utilizes it. If not, it seamlessly creates the WASM light client in-page for them. Built on [Polkadot JS](https://polkadot.js.org/docs/api), Substrate Connect ensures that your development experience is as smooth as using a traditional RPC server node.
+We also provide example projects using the above packages, including:
+
+- **[Basic light client demo](./projects/demo)**: a demo using `@substrate/connect` to obtain information about chains on the Polkadot network.
+- **[Light client extension demo](./projects/extension/)**: an example of a browser extension that provides a light client.
+- **[Wallet extension demo](./projects/wallet-template/)**: an example of a browser extension that provides a full Polkadot wallet leveraging a light client.
+
+### Additional Resources
+
+- A [step-by-step guide](./projects/wallet-template/STEP-BY-STEP-GUIDE.md) on how to integrate a light client into a browser extension.
+- Details on [the discovery protocol](./packages/discovery/), including how to implement it on the browser or extension side.
+
+### Why Embed a Light Client in Browser Extensions?
+
+Embedding a light client in browser extensions offers several advantages:
+
+- **Shared Light Client Across Multiple dApps:** By sharing a single light client among various decentralized applications (dApps), the time spent on startup and syncing is reduced. This avoids slowing down individual dApps and enhances overall efficiency.
+- **Overcoming Browser Limitations:** Browser limitations on WebSockets from HTTPS pages make it challenging to establish a robust number of peers, as many nodes must be available with TLS. Substrate Connect addresses this issue through a powerful browser extension, enabling chains to stay synced in the background and significantly improving the performance of your applications. This ensures a more robust connection to the Polkadot ecosystem.
 
 ## Comprehensive API Documentation
 
@@ -45,7 +63,7 @@ For detailed API usage, refer to the [Substrate Connect API documentation](https
 ## Repository Structure
 
 ### [Packages](./packages/README.md)
-   The core implementations of `@subtrate/connect` and `@substrate/discovery`, and some auxiliary packages. 
+   The core implementations of `@subtrate/connect` and `@substrate/discovery`, and some auxiliary packages.
    - **[@substrate/discovery](./packages/discovery/)**
    - **[@substrate/connect](./packages/connect/)**
    - **[@substrate/connect-known-chains](./packages/connect-known-chains/)**
@@ -61,7 +79,7 @@ For detailed API usage, refer to the [Substrate Connect API documentation](https
 
 
 ### [Examples](./examples/)
-   dApp and Extensions example implementations of `@substrate/connect` and `@substrate/discovery`. 
+   dApp and Extensions example implementations of `@substrate/connect` and `@substrate/discovery`.
 
 ## Development
 
@@ -75,22 +93,22 @@ Follow these steps to install everything and launch a demo if you're hacking on
    - Node.js (node) v20.9.0
    - pnpm 9.0.6 (`npm install -g pnpm`)
    - corepack 0.20.0 (bundled with recent Node.js versions)
-   
+
 2. **Clone the Repository**:
    - `git clone https://github.com/paritytech/substrate-connect.git`
    - Navigate to the repository root: `cd substrate-connect`
-   
+
 3. **Install Dependencies**:
    - `corepack pnpm install`
-   
+
 4. **Run the Extension in Development Mode**:
    - In terminal A: `cd projects/extension && corepack pnpm dev`
-   
+
 5. **Launch the Extension**:
    - In terminal B: `cd projects/extension && corepack pnpm start`
-   - This opens a Chrome browser window with the extension pre-loaded. Ensure 
+   - This opens a Chrome browser window with the extension pre-loaded. Ensure
    the extension is running.
-   
+
 6. **Run the Demo Application**:
    - In terminal C: `cd projects/demo && corepack pnpm dev`
    - Navigate to the URL logged in the Chrome browser opened in step 5. You should see the extension activate and the demo app log the latest blocks.
@@ -109,7 +127,7 @@ corepack pnpm deep-clean
 
 ## Releasing
 
-For releasing a new version of the extension, follow the steps outlined in 
+For releasing a new version of the extension, follow the steps outlined in
 [the release doc](./DEPLOY-RELEASE.md).
 
 ## Useful Links

packages/connect-discovery/README.md

@@ -14,6 +14,12 @@
 
 <br /><br />
 
+<div align="center" style="padding: 10px; border: 2px solid red; color: red; font-weight: bold; background-color: #ffe6e6;">
+  ⚠️ WARNING: This interface is currently unstable and is likely to change ⚠️
+</div>
+
+<br /><br />
+
 A TypeScript package extended from the [`@substrate/discovery`](../discovery/README.md) npm module, that allows to discover and filter Substrate Connect Extension providers from a list of providers.
 
 ## Installation

packages/connect/README.md

@@ -19,7 +19,11 @@ The main implementation of the light-client provider for a given substrate-based
 
 ## Using `@substrate/connect` for library authors
 
-Provide a well-known chain name ('polkadot', 'ksmcc3', 'westend2', 'rococo_v2_2'):
+The `connect` package will look for a light client provider via the discovery protocol. If it can't find one, it will spawn a smoldot instance in the user's browser tab.
+
+### Example Usage
+
+To use a well-known chain ('polkadot', 'ksmcc3', 'westend2', 'rococo_v2_2'):
 
 ```js
 import { createScClient, WellKnownChain } from '@substrate/connect';
@@ -37,7 +41,7 @@ chain.sendJsonRpc(
 );
 ```
 
-...or provide your custom substrate chain's name and chainspec:
+To use a custom substrate chain's name and chainspec:
 
 ```js
 import { createScClient } from '@substrate/connect';
@@ -58,10 +62,9 @@ chain.sendJsonRpc(
 );
 ```
 
-In order to connect to a parachain, you must first instantiate the relay chain
-this parachain is connected to, then instantiate the parachain on the same
-relay chain. The following example connects to a parachain of the Westend test
-network:
+### Connecting to a Parachain
+
+To connect to a parachain, you must first instantiate the relay chain this parachain is connected to, and then instantiate the parachain on the same relay chain. The following example connects to a parachain of the Westend test network:
 
 ```js
 import { createScClient, WellKnownChain } from '@substrate/connect';
@@ -70,7 +73,7 @@ import jsonParachainSpec from './myParaChainSpec.json';
 const parachainSpec = JSON.stringify(jsonParachainSpec);
 
 const scClient = createScClient();
-const relayChain = await scClient.addWellKnownChain(WellKnownChain.westend2)
+const relayChain = await scClient.addWellKnownChain(WellKnownChain.westend2);
 const parachain = await relayChain.addChain(
   parachainSpec,
   function jsonRpcCallback(response) {

packages/connect/src/connector/index.ts

@@ -34,6 +34,14 @@ export interface Config {
  * Returns a {@link ScClient} that connects to chains, either through the substrate-connect
  * extension or by executing a light client directly from JavaScript, depending on whether the
  * extension is installed and available.
+ *
+ * The substrate-connect extension is identified via the `@substrate/discovery` protocol.
+ *
+ * It must:
+ *
+ *  1. Be compliant `@substrate/smoldot-discovery` interface
+ *  2. Include an rdns label starting with `io.github.paritytech.SubstrateConnect`
+ *
  */
 export const createScClient = (config?: Config): ScClient => {
   if (config?.forceEmbeddedNode)
@@ -66,6 +74,7 @@ function getSmoldotProviderPromise(): Promise<SmoldotExtensionAPI> | undefined {
   if (typeof document !== "object" || typeof CustomEvent !== "function") return
   const lightClientProvider = getSmoldotExtensionProviders()
     .filter((detail) =>
+      // Filter for Substrate Connect to find the correct provider among multiple providers.
       detail.info.rdns.startsWith("io.github.paritytech.SubstrateConnect"),
     )
     .map((detail) => detail.provider)[0]

packages/discovery/README.md

@@ -22,12 +22,15 @@ The main export is a function called `getProviders`. This function dispatches an
 
 ## How It Works
 
-The extension injects an inpage script that:
+The discovery protocol is quite simple and can be implemented in these steps:
 
-- Registers a listener for the `substrateDiscovery:requestProvider` event and announces the provider by invoking synchronously the `onProvider` callback from the event payload.
-- Optionally, dispatches the `substrateDiscovery:announceProvider` event with the provider details when the script is loaded.
+1. The extension injects an inpage script that registers a listener for the `substrateDiscovery:requestProvider` event.
+2. The listener announces the provider by invoking the `onProvider` callback from the event payload synchronously.
+3. Optionally, the script can dispatch the `substrateDiscovery:announceProvider` event with the provider details when the script is loaded.
 
-## Basic Example
+Refer to `src/index.ts` in this package for an implementation of this protocol.
+
+## Basic Usage Example
 
 ```ts
 import { getProviders } from "@substrate/discovery"
@@ -40,6 +43,8 @@ console.log(firstProvider)
 
 ## Example with rDNS Filter
 
+This example demonstrates how to filter providers based on a specific rDNS value. This approach is useful when you need to target specific extensions rather than all extensions matching a certain interface.
+
 ```ts
 import { getProviders } from "@substrate/discovery"
 

packages/smoldot-discovery/README.md

@@ -14,7 +14,9 @@
 
 <br /><br />
 
-A TypeScript package extended from the [`@substrate/discovery`](../discovery/README.md) NPM package, that allows to discover and filter Smoldot extension providers from a list of providers.
+A TypeScript package extended from the [`@substrate/discovery`](../discovery/README.md) NPM package, which enables the discovery and filtering of Smoldot extension providers from a list of providers.
+
+To be utilized by dApps, extensions should implement the `SmoldotExtensionProviderDetail` interface. This can be achieved by following the extension side of the discovery protocol as detailed [here](../discovery/README.md), and then returning the implemented interface.
 
 ## Installation