chore: update substrate connect readme

[kratico]

No description provided.

[wirednkod]

How does, removing all previous documentation without adding new one, helps explaining how to use Substrate connect with either PAPI or polkadotJS?

[josepot]

Thanks!

[kratico]

How does, removing all previous documentation without adding new one, helps explaining how to use Substrate connect with either PAPI or polkadotJS?

Thanks for your concern @wirednkod
As discussed offline, it might not scale well to add documentation for each library that might use @substrate/connect.
Instead, we could add examples in the projects/ folder or open PRs in https://github.com/paritytech/polkadot-api or https://github.com/polkadot-js/api or other libraries with @substrate/connect examples,

[josepot]

How does, removing all previous documentation without adding new one, helps explaining how to use Substrate connect with either PAPI or polkadotJS?

It's the responsibility of those libraries to explain to their users how to build light-client dApps. In the case of PJS, it probably would make sense to improve this section of their docs.

@substrate/connect is a fairly low-level library that provides a basic interface to interact with smoldot. So, its docs should document that interface. The libraries/frameworks building on top of it are responsible for educating its consumers on how to build light-client dApps.

[wirednkod]

we could add examples in the projects/ folder or open PRs in paritytech/polkadot-api or polkadot-js/api or other libraries with @substrate/connect examples,

This is what I try to explain offline as well for long. No need to remove docs and alter demos.
Just add new docs for the PAPI versions, and create new demos, clarifying the support for these 2 APIs. IMO the repo at this point is super confusing.

[kratico]

@wirednkod @substrate/connect docs should not be coupled to any dependent library.

PolkadotAPI or PolkadotJS or any other, may chose to support the latest (or an specific) version for @substrate/connect like any other library that depends on a package.

Also, once polkadot-js/api#5776 is merged, a new PolkadotJS example with parachains could be added, for example

import { ApiPromise } from "@polkadot/api"
import { ScProvider } from "@polkadot/rpc-provider"
import * as Sc from "@substrate/connect"
import jsonParachainSpec from "./src/assets/asset-hub-westend.json" assert { type: "json" }

const parachainSpec = JSON.stringify(jsonParachainSpec)

const relayProvider = new ScProvider(Sc, Sc.WellKnownChain.westend2)
const provider = new ScProvider(Sc, parachainSpec, relayProvider)

await provider.connect()

const polkadotApi = await ApiPromise.create({ provider })
await polkadotApi.rpc.chain.subscribeNewHeads((lastHeader) => {
  console.log(lastHeader.number.toString())
})

[josepot]

we could add examples in the projects/ folder or open PRs in paritytech/polkadot-api or polkadot-js/api or other libraries with @substrate/connect examples,

This is what I try to explain offline as well for long. No need to remove docs and alter demos. Just add new docs for the PAPI versions, and create new demos, clarifying the support for these 2 APIs. IMO the repo at this point is super confusing.

We are of the opinion that it's not a good idea to document in the README of @substrate/connect how it can be used with PJS and/or PAPI. The reason why we think that it's not a good idea is double-fold:

• On one end because the APIs of those libraries could change, and if they did then this README would be providing outdated information. This is something that has already happened in the past.
• Also, consider the current situation: we just made a breaking change and we just don't know (as of right now), how these 2 different libraries will be leveraging this breaking change. It's very possible that this could result in a different API on PJS, actually, but we don't know it yet, so we just can't document it. Also, with regards of PAPI: currently all of those APIs are highly experimental, they will get stabilized during Q1. However, again, what it makes sense is for each library to document their own API.

Also, it's worth pointing out that in an ideal world the average dApp developer wouldn't know about the existence of this library, since this library should just be an internal implementation detail of a more developer-friend API that abstracts all this complexity away. So, I'm afraid that we see things quite differently.

All that being said, we will try our best to explain and document all these things as soon as we have the bandwidth to do so 🙂.

[wirednkod]

Feel free to proceed as you wish. This is not my project nor have any saying on the roadmap.