Deno version publishing

wasm-node/javascript/dist/mjs/README.md

@@ -0,0 +1,134 @@
+# Light client for Polkadot and Substrate-based chains
+
+This JavaScript library provides a light client for
+[the Polkadot blockchain](https://polkadot.network/) and for chains built
+using [the Substrate blockchain framework](https://substrate.io/).
+
+It is an "actual" light client, in the sense that it is byzantine-resilient.
+It does not rely on the presence of an RPC server, but directly connects to
+the full nodes of the network.
+
+## Example
+
+```
+import * as smoldot from 'smoldot';
+
+// Load a string chain specification.
+const chainSpec = fs.readFileSync('./westend.json', 'utf8');
+
+// A single client can be used to initialize multiple chains.
+const client = smoldot.start();
+
+const chain = await client.addChain({ chainSpec });
+
+chain.sendJsonRpc('{"jsonrpc":"2.0","id":1,"method":"system_name","params":[]}');
+
+// Wait for a JSON-RPC response to come back. This is typically done in a loop in the background.
+const jsonRpcResponse = await chain.nextJsonRpcResponse();
+console.log(jsonRpcResponse)
+
+// Later:
+// chain.remove();
+```
+
+## Usage
+
+The first thing to do is to initialize the client with the `start` function.
+
+Once initialized, the client can be used to connect to one or more chains. Use `addChain` to add
+a new chain that the client must be connected to. `addChain` must be passed the specification of
+the chain (commonly known as "chain spec").
+
+The `addChain` function returns a `Promise` that yields a chain once the chain specification has
+been successfully parsed and basic initialization is finished, but before Internet connections
+are opened towards the chains.
+
+In order to de-initialize a chain, call `chain.remove()`. Any function called afterwards on this
+chain will throw an exception.
+In order to de-initialize a client, call `client.terminate()`. Any function called afterwards on
+any of the chains of the client will throw an exception.
+
+After having obtained a chain, use `sendJsonRpc` to send a JSON-RPC request towards the node.
+The function accepts as parameter a string request. See
+[the specification of the JSON-RPC protocol](https://www.jsonrpc.org/specification),
+and [the list of requests that smoldot is capable of serving](https://polkadot.js.org/docs/substrate/rpc/).
+Smoldot also has experimental support for an extra (still experimental at the time of writing of
+this comment) set of JSON-RPC functions [found here](https://github.com/paritytech/json-rpc-interface-spec/).
+
+If the request is well formatted, the client will generate a response. This response can be pulled
+using the `nextJsonRpcResponse` asynchronous function. Calling this function waits until a response
+is available and returns it.
+
+If the request is a subscription, the notifications will also be sent back using the same mechanism
+and can be pulled using `nextJsonRpcResponse`.
+
+If the chain specification passed to `addChain` is a parachain, then the list of potential relay
+chains must be passed as parameter to `addChain` as well. In situations where the chain
+specifications passed to `addChain` are not trusted, it is important for security reasons to not
+establish a parachain-relay-chain link between two chains that aren't part of the same "trust
+sandbox".
+
+## Usage with a worker
+
+By default, calling `start()` will run smoldot entirely in the current thread. This can cause
+performance issues if other CPU-heavy operations are done in that thread.
+
+In order to help with this, it is possible to use smoldot in conjunction with a worker.
+To do so, you must first create a worker. Since creating a worker has some subtle differences
+depending on the platform, this is outside of the responsibility of smoldot.
+
+Once the worker is created, create two `MessagePort`s using `new MessageChannel`, and send one
+of them to the worker. Then, pass one port to the `ClientOptions.portToWorker` field and the
+other port to the `run()` function of smoldot, which can be imported with
+`import { run } from 'smoldot/worker';` (on Deno, it is found in `worker-deno.ts`).
+
+Another optimization that is orthogonal to but is related to running smoldot in a worker consists
+in also loading the smoldot bytecode in that worker. The smoldot bytecode weights several
+megabytes, and loading it in a worker rather than the main thread makes it possible to load the
+UI while smoldot is still initializing. This is especially important when smoldot is included in
+an application served over the web.
+
+In order to load the smoldot bytecode in a worker, import `compileBytecode` with
+`import { compileBytecode } from 'smoldot/bytecode';` (on Deno: `bytecode-deno.ts`), then call the
+function and send the result to the main thread. From the main thread, rather than using the
+`start` function imported from `smoldot`, use the `startWithBytecode` function that can be imported
+using `import { startWithBytecode } from 'smoldot/no-auto-bytecode';` (on Deno:
+`no-auto-bytecode-deno.ts`). The options provided to `startWithBytecode` are the same as the ones
+passed to `start`, except for an additional `bytecode` field that must be set to the bytecode
+created in the worker.
+
+Here is an example of all this, assuming a browser environment:
+
+```ts
+import * as smoldot from 'smoldot/no-auto-bytecode';
+
+const worker = new Worker(new URL('./worker.js', import.meta.url));
+
+const bytecode = new Promise((resolve) => {
+    worker.onmessage = (event) => resolve(event.data);
+});
+
+const { port1, port2 } = new MessageChannel();
+worker.postMessage(port1, [port1]);
+
+const client = smoldot.startWithBytecode({
+    bytecode,
+    portToWorker: port2,
+});
+
+
+// `worker.ts`
+
+import * as smoldot from 'smoldot/worker';
+import { compileBytecode } from 'smoldot/bytecode';
+
+compileBytecode().then((bytecode) => postMessage(bytecode))
+onmessage = (msg) => smoldot.run(msg.data);
+```
+
+Note that importing sub-paths (for example importing `smoldot/worker`) relies on a relatively
+modern JavaScript feature. If you import a smoldot sub-path from a TypeScript file, you might have
+to configure TypeScript to use `"moduleResolution": "node16"`. [The official TypeScript
+documentation itself recommends setting this configuration option to
+`node`](https://www.typescriptlang.org/docs/handbook/module-resolution.html#module-resolution-strategies),
+and it is likely that `node16` becomes the go-to module resolution scheme in the future.

wasm-node/javascript/dist/mjs/bytecode-browser.d.ts

@@ -0,0 +1,6 @@
+/// <reference lib="dom" />
+import { SmoldotBytecode } from './public-types.js';
+/**
+ * Compiles and returns the smoldot WebAssembly binary.
+ */
+export declare function compileBytecode(): Promise<SmoldotBytecode>;

wasm-node/javascript/dist/mjs/bytecode-browser.js

@@ -0,0 +1,83 @@
+// Smoldot
+// Copyright (C) 2023  Pierre Krieger
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+/// <reference lib="dom" />
+import { default as wasmBase64 } from './internals/bytecode/wasm.js';
+/**
+ * Compiles and returns the smoldot WebAssembly binary.
+ */
+export function compileBytecode() {
+    return __awaiter(this, void 0, void 0, function* () {
+        // The actual Wasm bytecode is base64-decoded then deflate-decoded from a constant found in a
+        // different file.
+        // This is suboptimal compared to using `instantiateStreaming`, but it is the most
+        // cross-platform cross-bundler approach.
+        return WebAssembly.compile(yield zlibInflate(trustedBase64Decode(wasmBase64)))
+            .then((m) => { return { wasm: m }; });
+    });
+}
+/**
+ * Applies the zlib inflate algorithm on the buffer.
+ */
+function zlibInflate(buffer) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // This code has been copy-pasted from the official streams draft specification.
+        // At the moment, it is found here: https://wicg.github.io/compression/#example-deflate-compress
+        const ds = new DecompressionStream('deflate');
+        const writer = ds.writable.getWriter();
+        writer.write(buffer);
+        writer.close();
+        const output = [];
+        const reader = ds.readable.getReader();
+        let totalSize = 0;
+        while (true) {
+            const { value, done } = yield reader.read();
+            if (done)
+                break;
+            output.push(value);
+            totalSize += value.byteLength;
+        }
+        const concatenated = new Uint8Array(totalSize);
+        let offset = 0;
+        for (const array of output) {
+            concatenated.set(array, offset);
+            offset += array.byteLength;
+        }
+        return concatenated;
+    });
+}
+/**
+ * Decodes a base64 string.
+ *
+ * The input is assumed to be correct.
+ */
+function trustedBase64Decode(base64) {
+    // This code is a bit sketchy due to the fact that we decode into a string, but it seems to
+    // work.
+    const binaryString = atob(base64);
+    const size = binaryString.length;
+    const bytes = new Uint8Array(size);
+    for (let i = 0; i < size; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes;
+}

wasm-node/javascript/dist/mjs/bytecode-deno.d.ts

@@ -0,0 +1,5 @@
+import { SmoldotBytecode } from './public-types.js';
+/**
+ * Compiles and returns the smoldot WebAssembly binary.
+ */
+export declare function compileBytecode(): Promise<SmoldotBytecode>;

wasm-node/javascript/dist/mjs/bytecode-deno.js

@@ -0,0 +1,83 @@
+// Smoldot
+// Copyright (C) 2023  Pierre Krieger
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+import { default as wasmBase64 } from './internals/bytecode/wasm.js';
+/**
+ * Compiles and returns the smoldot WebAssembly binary.
+ */
+export function compileBytecode() {
+    return __awaiter(this, void 0, void 0, function* () {
+        // The actual Wasm bytecode is base64-decoded then deflate-decoded from a constant found in a
+        // different file.
+        // This is suboptimal compared to using `instantiateStreaming`, but it is the most
+        // cross-platform cross-bundler approach.
+        return zlibInflate(trustedBase64Decode(wasmBase64))
+            .then(((bytecode) => WebAssembly.compile(bytecode)))
+            .then((m) => { return { wasm: m }; });
+    });
+}
+/**
+ * Applies the zlib inflate algorithm on the buffer.
+ */
+function zlibInflate(buffer) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // This code has been copy-pasted from the official streams draft specification.
+        // At the moment, it is found here: https://wicg.github.io/compression/#example-deflate-compress
+        const ds = new DecompressionStream('deflate');
+        const writer = ds.writable.getWriter();
+        writer.write(buffer);
+        writer.close();
+        const output = [];
+        const reader = ds.readable.getReader();
+        let totalSize = 0;
+        while (true) {
+            const { value, done } = yield reader.read();
+            if (done)
+                break;
+            output.push(value);
+            totalSize += value.byteLength;
+        }
+        const concatenated = new Uint8Array(totalSize);
+        let offset = 0;
+        for (const array of output) {
+            concatenated.set(array, offset);
+            offset += array.byteLength;
+        }
+        return concatenated;
+    });
+}
+/**
+ * Decodes a base64 string.
+ *
+ * The input is assumed to be correct.
+ */
+function trustedBase64Decode(base64) {
+    // This code is a bit sketchy due to the fact that we decode into a string, but it seems to
+    // work.
+    const binaryString = atob(base64);
+    const size = binaryString.length;
+    const bytes = new Uint8Array(size);
+    for (let i = 0; i < size; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes;
+}

wasm-node/javascript/dist/mjs/bytecode-nodejs.d.ts

@@ -0,0 +1,5 @@
+import { SmoldotBytecode } from './public-types.js';
+/**
+ * Compiles and returns the smoldot WebAssembly binary.
+ */
+export declare function compileBytecode(): Promise<SmoldotBytecode>;

wasm-node/javascript/dist/mjs/bytecode-nodejs.js

@@ -0,0 +1,37 @@
+// Smoldot
+// Copyright (C) 2023  Pierre Krieger
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+import { inflateSync } from 'node:zlib';
+import { default as wasmBase64 } from './internals/bytecode/wasm.js';
+/**
+ * Compiles and returns the smoldot WebAssembly binary.
+ */
+export function compileBytecode() {
+    return __awaiter(this, void 0, void 0, function* () {
+        // The actual Wasm bytecode is base64-decoded then deflate-decoded from a constant found in a
+        // different file.
+        // This is suboptimal compared to using `instantiateStreaming`, but it is the most
+        // cross-platform cross-bundler approach.
+        return WebAssembly.compile(inflateSync(Buffer.from(wasmBase64, 'base64')))
+            .then((m) => { return { wasm: m }; });
+    });
+}

wasm-node/javascript/dist/mjs/index-browser.d.ts

@@ -0,0 +1,11 @@
+/// <reference lib="dom" />
+import { Client, ClientOptions } from './public-types.js';
+export { AddChainError, AddChainOptions, AlreadyDestroyedError, Chain, Client, ClientOptions, ClientOptionsWithBytecode, SmoldotBytecode, CrashError, JsonRpcDisabledError, QueueFullError, LogCallback } from './public-types.js';
+/**
+ * Initializes a new client. This is a pre-requisite to connecting to a blockchain.
+ *
+ * Can never fail.
+ *
+ * @param options Configuration of the client. Defaults to `{}`.
+ */
+export declare function start(options?: ClientOptions): Client;

wasm-node/javascript/dist/mjs/index-browser.js

@@ -0,0 +1,17 @@
+// Smoldot
+// Copyright (C) 2019-2022  Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+import { startWithBytecode } from './no-auto-bytecode-browser.js';
+import { compileBytecode } from './bytecode-browser.js';
+export { AddChainError, AlreadyDestroyedError, CrashError, JsonRpcDisabledError, QueueFullError } from './public-types.js';
+/**
+ * Initializes a new client. This is a pre-requisite to connecting to a blockchain.
+ *
+ * Can never fail.
+ *
+ * @param options Configuration of the client. Defaults to `{}`.
+ */
+export function start(options) {
+    options = options || {};
+    return startWithBytecode(Object.assign({ bytecode: compileBytecode() }, options));
+}