Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
@substrate/connect
Advanced tools
@substrate/connect - npm Package Compare versions
Comparing version 0.7.0-alpha.0 to 0.7.0
| # Changelog | ||
| ## [Unreleased] | ||
| - Remove `createPolkadotJsScClient` and polkadotjs dependencies. | ||
| ## 0.7.0 - 2022-04-06 | ||
| ### Breaking | ||
| - Removed `createPolkadotJsScClient` from the API, as the `ScProvider` has been upstreamed to `@polkadot/rpc-provider`. ([#909](https://github.com/paritytech/substrate-connect/pull/909)) | ||
| ### Fixed | ||
| - Fixed an issue when calling `chain.remove()` where it would throw an `AlreadyDestroyedError`. | ||
| ### Changed | ||
| - Update @substrate/smoldot-light to [version 0.6.13](https://github.com/paritytech/smoldot/blob/315c3683d3beee1c8f5884261f761530ddf7ef53/bin/wasm-node/CHANGELOG.md#0613---2022-04-05) ([#919](https://github.com/paritytech/substrate-connect/pull/919)) | ||
| - The smoldot background worker will now bound its CPU usage to 50% of one CPU on average. ([#900](https://github.com/paritytech/substrate-connect/pull/900)) | ||
| ## 0.6.4, 0.6.5 - 2022-03-25 | ||
| ### Changed | ||
| - Update @substrate/smoldot-light to [version 0.6.9](https://github.com/paritytech/smoldot/blob/main/bin/wasm-node/CHANGELOG.md#069---2022-03-25) ([#901](https://github.com/paritytech/substrate-connect/pull/901)) | ||
| ## 0.6.3 - 2022-03-23 | ||
@@ -7,0 +27,0 @@ |
@@ -21,2 +21,3 @@ import { getSpec } from "./specs/index.js"; | ||
| maxLogLevel: 4 /* no debug/trace messages */, | ||
| cpuRateLimit: 0.5, // Politely limit the CPU usage of the smoldot background worker. | ||
| })); | ||
@@ -70,2 +71,3 @@ clientNumReferences += 1; | ||
| client.terminate(); | ||
| return; | ||
| } | ||
@@ -72,0 +74,0 @@ } |
@@ -6,27 +6,14 @@ /** | ||
| * | ||
| * 1. Call {createScClient} or {createPolkadotJsScClient}, which gives you a so-called *client*. | ||
| * 1. Call {createScClient}, which gives you a so-called *client*. | ||
| * 2. Call `addChain` or `addWellKnownChain` on this client. | ||
| * | ||
| * Use {createPolkadotJsScClient} if you want to bind the PolkadotJS library to substrate-connect. | ||
| * This client will provide chains that implement the `ProviderInterface` interface defined in the | ||
| * `@polkadot/api` NPM package. These chains can be passed to `ApiPromise.create`, and you can | ||
| * then use the PolkadotJS library as you normally would. See <https://polkadot.js.org/docs>. | ||
| * Note that this library is a low-level library where you directly send JSON-RPC requests and | ||
| * receive responses. | ||
| * For a high-level library build on top of `substrate-connect` you can use | ||
| * {@polkadot/rpc-provider/substrate-connect}. | ||
| * | ||
| * Use {createScClient} if you are interested in a lower-level experience where you directly | ||
| * send JSON-RPC requests and receive responses. | ||
| * In the library's internals, {createPolkadotJsScClient} is implemented on top of | ||
| * {createScClient}. | ||
| * | ||
| * If you use {createPolkadotJsScClient}, be aware that the PolkadotJS library and its API are | ||
| * fundamentally built around full nodes functionnalities, while substrate-connect is a light | ||
| * client. Some functionnalities of PolkadotJS will not work properly, and/or not as well as they | ||
| * could. This is fundamentally not fixable, and, while {createPolkadotJsScClient} is acceptable | ||
| * for demos and prototypes, it is not possible to achieve the best user experience by using | ||
| * PolkadotJS. Proper light-client-oriented high-level libraries built on top of | ||
| * {createScClient} are currently in development. | ||
| * | ||
| * # Adding parachains | ||
| * | ||
| * Connecting to a parachain is done the same way as connecting to a standalone chain: obtaining | ||
| * a client (with {createScClient} or {createPolkadotJsScClient}) then calling `addChain`. | ||
| * a client then calling `addChain`. | ||
| * | ||
@@ -57,5 +44,5 @@ * However, if you call `addChain` with a parachain chain specification, you **must** have | ||
| * | ||
| * While calling {createScClient} or {createPolkadotJsScClient} multiple times leads to a | ||
| * different observable behaviour when it comes to parachains (see previous section), internally | ||
| * resources are shared between all the clients. | ||
| * While calling {createScClient} multiple times leads to a different observable behaviour | ||
| * when it comes to parachains (see previous section), internally resources are shared | ||
| * between all the clients. | ||
| * | ||
@@ -74,4 +61,4 @@ * In order words, it is not a problem to do this: | ||
| * | ||
| * This means that there is no problem in calling {createScClient} or | ||
| * {createPolkadotJsScClient} from within a library for example. | ||
| * This means that there is no problem in calling {createScClient} from within a library for | ||
| * example. | ||
| * | ||
@@ -78,0 +65,0 @@ * # Well-known chains |
@@ -6,27 +6,14 @@ /** | ||
| * | ||
| * 1. Call {createScClient} or {createPolkadotJsScClient}, which gives you a so-called *client*. | ||
| * 1. Call {createScClient}, which gives you a so-called *client*. | ||
| * 2. Call `addChain` or `addWellKnownChain` on this client. | ||
| * | ||
| * Use {createPolkadotJsScClient} if you want to bind the PolkadotJS library to substrate-connect. | ||
| * This client will provide chains that implement the `ProviderInterface` interface defined in the | ||
| * `@polkadot/api` NPM package. These chains can be passed to `ApiPromise.create`, and you can | ||
| * then use the PolkadotJS library as you normally would. See <https://polkadot.js.org/docs>. | ||
| * Note that this library is a low-level library where you directly send JSON-RPC requests and | ||
| * receive responses. | ||
| * For a high-level library build on top of `substrate-connect` you can use | ||
| * {@polkadot/rpc-provider/substrate-connect}. | ||
| * | ||
| * Use {createScClient} if you are interested in a lower-level experience where you directly | ||
| * send JSON-RPC requests and receive responses. | ||
| * In the library's internals, {createPolkadotJsScClient} is implemented on top of | ||
| * {createScClient}. | ||
| * | ||
| * If you use {createPolkadotJsScClient}, be aware that the PolkadotJS library and its API are | ||
| * fundamentally built around full nodes functionnalities, while substrate-connect is a light | ||
| * client. Some functionnalities of PolkadotJS will not work properly, and/or not as well as they | ||
| * could. This is fundamentally not fixable, and, while {createPolkadotJsScClient} is acceptable | ||
| * for demos and prototypes, it is not possible to achieve the best user experience by using | ||
| * PolkadotJS. Proper light-client-oriented high-level libraries built on top of | ||
| * {createScClient} are currently in development. | ||
| * | ||
| * # Adding parachains | ||
| * | ||
| * Connecting to a parachain is done the same way as connecting to a standalone chain: obtaining | ||
| * a client (with {createScClient} or {createPolkadotJsScClient}) then calling `addChain`. | ||
| * a client then calling `addChain`. | ||
| * | ||
@@ -57,5 +44,5 @@ * However, if you call `addChain` with a parachain chain specification, you **must** have | ||
| * | ||
| * While calling {createScClient} or {createPolkadotJsScClient} multiple times leads to a | ||
| * different observable behaviour when it comes to parachains (see previous section), internally | ||
| * resources are shared between all the clients. | ||
| * While calling {createScClient} multiple times leads to a different observable behaviour | ||
| * when it comes to parachains (see previous section), internally resources are shared | ||
| * between all the clients. | ||
| * | ||
@@ -74,4 +61,4 @@ * In order words, it is not a problem to do this: | ||
| * | ||
| * This means that there is no problem in calling {createScClient} or | ||
| * {createPolkadotJsScClient} from within a library for example. | ||
| * This means that there is no problem in calling {createScClient} from within a library for | ||
| * example. | ||
| * | ||
@@ -78,0 +65,0 @@ * # Well-known chains |
| { | ||
| "name": "@substrate/connect", | ||
| "version": "0.7.0-alpha.0", | ||
| "version": "0.7.0", | ||
| "description": "Substrate-connect to Smoldot clients. Using either substrate extension with predefined clients or an internal smoldot client based on chainSpecs provided.", | ||
@@ -32,5 +32,5 @@ "author": "Parity Team <admin@parity.io>", | ||
| "@substrate/connect-extension-protocol": "^1.0.0", | ||
| "@substrate/smoldot-light": "0.6.8", | ||
| "@substrate/smoldot-light": "0.6.13", | ||
| "eventemitter3": "^4.0.7" | ||
| } | ||
| } |
148
README.md
@@ -1,52 +0,136 @@ | ||
| # Polkadot JS Provider for Smoldot Light Client | ||
| # @substrate/connect | ||
| This is a prototype for using [@polkadot/api](https://polkadot.js.org/docs/api/start) | ||
| with the [smoldot](https://npmjs.com/package/smoldot) WASM light client either by | ||
| passing chainspecs or using the extension by predefined chains (e.g. westend2, ksmcc3). | ||
| ## Using `@substrate/connect` through the PolkadotJS RPC Provider | ||
| ScProvider check existence of substrate extension. If it is installed and activated then | ||
| smoldot clients of extension will be used. If not, a new smoldot client will start and | ||
| sync with given chainspecs. | ||
| ## Usage | ||
| Provide a known Chain Name ('polkadot', 'ksmcc3', 'westend2', 'rococo_v2_1'): | ||
| The recommended way to use `@substrate/connect` is to use PolkadotJS, | ||
| which provides a higher-level API built on top of it. | ||
| Unless you are writting your own library, you probably want to use the | ||
| PolkadotJS RPC provider. | ||
| Provide a well-known chain name ('polkadot', 'ksmcc3', 'westend2', 'rococo_v2_1'): | ||
| ```js | ||
| import { ApiPromise } from '@polkadot/api'; | ||
| import { createPolkadotJsScClient, SupportedChains } from '@substrate/connect'; | ||
| import { ApiPromise } from "@polkadot/api"; | ||
| import { | ||
| ScProvider, | ||
| WellKnownChain, | ||
| } from "@polkadot/rpc-provider/substrate-connect"; | ||
| const scClient = createPolkadotJsScClient(); | ||
| const provider = await scClient.addWellKnownChain(SupportedChains.westend2); | ||
| const api = await ApiPromise.create({ provider }); | ||
| const provider = new ScProvider(WellKnownChain.polkadot); | ||
| await provider.connect(); | ||
| const polkadotApi = await ApiPromise.create({ provider }); | ||
| await polkadotApi.rpc.chain.subscribeNewHeads((lastHeader) => { | ||
| console.log(lastHeader.number.toString()); | ||
| }); | ||
| ``` | ||
| or provide your custom substrate chain's name and chainspec: | ||
| ...or provide your custom Substrate chain's specification: | ||
| ```js | ||
| import { ApiPromise } from '@polkadot/api'; | ||
| import { createPolkadotJsScClient } from '@substrate/connect'; | ||
| import mySubstrateChainSpec from './mySubstrateChainSpec.json'; | ||
| import { ApiPromise } from "@polkadot/api"; | ||
| import { ScProvider } from "@polkadot/rpc-provider/substrate-connect"; | ||
| import myJsonSubstrateChainSpec from './mySubstrateChainSpec.json'; | ||
| const myChainSpec = JSON.stringify(mySubstrateChainSpec); | ||
| const mySubstrateChainSpec = JSON.stringify(myJsonSubstrateChainSpec); | ||
| const scClient = createPolkadotJsScClient(); | ||
| const provider = await scClient.addChain(myChainSpec); | ||
| const api = await ApiPromise.create({ provider }); | ||
| const provider = new ScProvider(mySubstrateChainSpec); | ||
| await provider.connect(); | ||
| const polkadotApi = await ApiPromise.create({ provider }); | ||
| await polkadotApi.rpc.chain.subscribeNewHeads((lastHeader) => { | ||
| console.log(lastHeader.number.toString()); | ||
| }); | ||
| ``` | ||
| In order to connect to a parachain, you must first instantiate the `ScProvider` | ||
| corresponding to the relay chain, then pass this `ScProvider` as the second | ||
| argument of the constructor of the parachain `ScProvider`. The following example | ||
| connects to a parachain of the Westend test network: | ||
| ### Parachain support | ||
| ```js | ||
| import { ApiPromise } from "@polkadot/api"; | ||
| import { | ||
| ScProvider, | ||
| WellKnownChain, | ||
| } from "@polkadot/rpc-provider/substrate-connect"; | ||
| import jsonParachainSpec from './myParaChainSpec.json'; | ||
| For parachain support, you can providethe parachain's specs | ||
| const parachainSpec = JSON.stringify(jsonParachainSpec); | ||
| const relayProvider = new ScProvider(WellKnownChain.westend2); | ||
| const provider = new ScProvider(parachainSpec, relayProvider); | ||
| await provider.connect(); | ||
| const polkadotApi = await ApiPromise.create({ provider }); | ||
| await polkadotApi.rpc.chain.subscribeNewHeads((lastHeader) => { | ||
| console.log(lastHeader.number.toString()); | ||
| }); | ||
| ``` | ||
| ## Using `@substrate/connect` for library authors | ||
| Provide a well-known chain name ('polkadot', 'ksmcc3', 'westend2', 'rococo_v2_1'): | ||
| ```js | ||
| import { ApiPromise } from '@polkadot/api'; | ||
| import { createPolkadotJsScClient, SupportedChains } from '@substrate/connect'; | ||
| import myParaChainSpec from './myParaChainSpec.json'; | ||
| import { createScClient, WellKnownChain } from '@substrate/connect'; | ||
| const parachainSpec = JSON.stringify(myParaChainSpec); | ||
| const scClient = createScClient(); | ||
| const chain = await scClient.addWellKnownChain( | ||
| WellKnownChain.westend2, | ||
| function jsonRpcCallback(response) { | ||
| console.log("response", response); | ||
| } | ||
| ); | ||
| const scClient = createPolkadotJsScClient(); | ||
| await scClient.addWellKnownChain(SupportedChains.westend2) | ||
| const provider = await scClient.addChain(parachainSpec); | ||
| const api = await ApiPromise.create({ provider }); | ||
| chain.sendJsonRpc( | ||
| '{"jsonrpc":"2.0","id":"1","method":"system_health","params":[]}' | ||
| ); | ||
| ``` | ||
| ...or provide your custom substrate chain's name and chainspec: | ||
| ```js | ||
| import { createScClient } from '@substrate/connect'; | ||
| import myJsonChainSpec from './mySubstrateChainSpec.json'; | ||
| const myChainSpec = JSON.stringify(myJsonChainSpec); | ||
| const scClient = createScClient(); | ||
| const chain = await scClient.addChain( | ||
| myChainSpec, | ||
| function jsonRpcCallback(response) { | ||
| console.log("response", response); | ||
| } | ||
| ); | ||
| chain.sendJsonRpc( | ||
| '{"jsonrpc":"2.0","id":"1","method":"system_health","params":[]}' | ||
| ); | ||
| ``` | ||
| 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 | ||
| `ScClient`. The following example connects to a parachain of the Westend test | ||
| network: | ||
| ```js | ||
| import { createScClient, WellKnownChain } from '@substrate/connect'; | ||
| import jsonParachainSpec from './myParaChainSpec.json'; | ||
| const parachainSpec = JSON.stringify(jsonParachainSpec); | ||
| const scClient = createScClient(); | ||
| await scClient.addWellKnownChain(WellKnownChain.westend2) | ||
| const parachain = await scClient.addChain( | ||
| parachainSpec, | ||
| function jsonRpcCallback(response) { | ||
| console.log("response", response); | ||
| } | ||
| ); | ||
| parachain.sendJsonRpc( | ||
| '{"jsonrpc":"2.0","id":"1","method":"system_health","params":[]}' | ||
| ); | ||
| ``` | ||
| ## Scripts | ||
@@ -53,0 +137,0 @@ |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by0.02%
5040407
- Number of lines in readme file
- increased by147.37%
141
Worsened metrics
- Lines of code
- decreased by-0.23%
10561
Dependency changes
+ Added@substrate/smoldot-light@0.6.13(transitive)
- Removed@substrate/smoldot-light@0.6.8(transitive)