smoldot 1.0.4 → 1.0.6

package/README.md

@@ -67,3 +67,61 @@ chains must be passed as parameter to `addChain` as well. In situations where th
 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 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);
+```

package/dist/cjs/bytecode-browser.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>;

package/dist/cjs/bytecode-browser.js

@@ -0,0 +1,42 @@
+"use strict";
+// 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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileBytecode = void 0;
+// 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/>.
+const wasm_js_1 = require("./internals/bytecode/wasm.js");
+const base64_js_1 = require("./internals/base64.js");
+const pako_1 = require("pako");
+/**
+ * Compiles and returns the smoldot WebAssembly binary.
+ */
+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((0, pako_1.inflate)((0, base64_js_1.classicDecode)(wasm_js_1.default)))
+            .then((m) => { return { wasm: m }; });
+    });
+}
+exports.compileBytecode = compileBytecode;

package/dist/cjs/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>;

package/dist/cjs/bytecode-deno.js

@@ -0,0 +1,87 @@
+"use strict";
+// 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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileBytecode = void 0;
+// 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/>.
+const wasm_js_1 = require("./internals/bytecode/wasm.js");
+/**
+ * Compiles and returns the smoldot WebAssembly binary.
+ */
+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(wasm_js_1.default))
+            .then(((bytecode) => WebAssembly.compile(bytecode)))
+            .then((m) => { return { wasm: m }; });
+    });
+}
+exports.compileBytecode = compileBytecode;
+/**
+ * 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;
+}

package/dist/cjs/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>;

package/dist/cjs/bytecode-nodejs.js

@@ -0,0 +1,41 @@
+"use strict";
+// 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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileBytecode = void 0;
+// 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/>.
+const wasm_js_1 = require("./internals/bytecode/wasm.js");
+const pako_1 = require("pako");
+/**
+ * Compiles and returns the smoldot WebAssembly binary.
+ */
+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((0, pako_1.inflate)(Buffer.from(wasm_js_1.default, 'base64')))
+            .then((m) => { return { wasm: m }; });
+    });
+}
+exports.compileBytecode = compileBytecode;

package/dist/cjs/index-browser.d.ts

@@ -1,6 +1,6 @@
 /// <reference lib="dom" />
-import { Client, ClientOptions } from './client.js';
-export { AddChainError, AddChainOptions, AlreadyDestroyedError, Chain, Client, ClientOptions, CrashError, JsonRpcDisabledError, MalformedJsonRpcError, QueueFullError, LogCallback } from './client.js';
+import { Client, ClientOptions } from './public-types.js';
+export { AddChainError, AddChainOptions, AlreadyDestroyedError, Chain, Client, ClientOptions, ClientOptionsWithBytecode, SmoldotBytecode, CrashError, JsonRpcDisabledError, MalformedJsonRpcError, QueueFullError, LogCallback } from './public-types.js';
 /**
  * Initializes a new client. This is a pre-requisite to connecting to a blockchain.
  *