smoldot 0.3.6 → 0.7.10

package/README.md

@@ -2,7 +2,7 @@
 
 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.dev/).
+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
@@ -17,19 +17,16 @@ import * as smoldot from 'smoldot';
 const chainSpec = fs.readFileSync('./westend.json', 'utf8');
 
 // A single client can be used to initialize multiple chains.
-const client = await smoldot.start();
+const client = smoldot.start();
 
-const chain = await client.addChain({
-  chainSpec,
-  jsonRpcCallback: (jsonRpcResponse) => {
-      // Called whenever the client emits a response to a JSON-RPC request,
-      // or a JSON-RPC pub-sub notification.
-      console.log(jsonRpcResponse)
-  }
-});
+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();
 ```
@@ -55,18 +52,18 @@ After having obtained a chain, use `sendJsonRpc` to send a JSON-RPC request towa
 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 send a response using the `jsonRpcCallback`
-callback that was passed to `addChain`. This callback takes as parameter the string JSON-RPC
-response.
-
-If the request is a subscription, the notifications will also be sent back using the same
-`jsonRpcCallback`.
+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 no `jsonRpcCallback` was passed to `addChain`, then this chain won't be capable of serving
-any JSON-RPC request at all. This can be used to save resources.
+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. For security reasons, it is important
-to not establish a parachain-relay-chain link between two chains that weren't created by the same
-user.
+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".

package/dist/cjs/base64.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Decodes a multibase-encoded string.
+ *
+ * Throws an exception if the encoding isn't base64 or one of its variants.
+ */
+export declare function multibaseBase64Decode(input: string): Uint8Array;
+/**
+ * Decodes a base64-encoded string into bytes using the original alphabet from RFC4648.
+ *
+ * See <https://datatracker.ietf.org/doc/html/rfc4648#section-4>.
+ */
+export declare function classicDecode(input: string): Uint8Array;
+/**
+ * Decodes a base64-encoded string into bytes using the URL-safe alphabet.
+ *
+ * See <https://datatracker.ietf.org/doc/html/rfc4648#section-5>.
+ */
+export declare function urlSafeDecode(input: string): Uint8Array;
+/**
+ * Decodes a base64-encoded string into bytes using the given alphabet.
+ */
+export declare function base64Decode(input: string, alphabet: Map<string, number>): Uint8Array;

package/dist/cjs/base64.js

@@ -0,0 +1,104 @@
+"use strict";
+// Smoldot
+// Copyright (C) 2019-2022  Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.base64Decode = exports.urlSafeDecode = exports.classicDecode = exports.multibaseBase64Decode = 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/>.
+let rfc4648Alphabet = new Map();
+const rfc4648AlphabetAsStr = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+for (let i = 0; i < rfc4648AlphabetAsStr.length; ++i) {
+    rfc4648Alphabet.set(rfc4648AlphabetAsStr[i], i);
+}
+let urlSafeAlphabet = new Map();
+const urlSafeAlphabetAsStr = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+for (let i = 0; i < urlSafeAlphabetAsStr.length; ++i) {
+    urlSafeAlphabet.set(urlSafeAlphabetAsStr[i], i);
+}
+/**
+ * Decodes a multibase-encoded string.
+ *
+ * Throws an exception if the encoding isn't base64 or one of its variants.
+ */
+function multibaseBase64Decode(input) {
+    if (input.length === 0)
+        throw new Error("Invalid multibase");
+    switch (input[0]) {
+        case 'm':
+        case 'M':
+            return classicDecode(input.slice(1));
+        case 'u':
+        case 'U':
+            return urlSafeDecode(input.slice(1));
+        default:
+            throw new Error('Unknown multibase prefix: ' + input[0]);
+    }
+}
+exports.multibaseBase64Decode = multibaseBase64Decode;
+/**
+ * Decodes a base64-encoded string into bytes using the original alphabet from RFC4648.
+ *
+ * See <https://datatracker.ietf.org/doc/html/rfc4648#section-4>.
+ */
+function classicDecode(input) {
+    return base64Decode(input, rfc4648Alphabet);
+}
+exports.classicDecode = classicDecode;
+/**
+ * Decodes a base64-encoded string into bytes using the URL-safe alphabet.
+ *
+ * See <https://datatracker.ietf.org/doc/html/rfc4648#section-5>.
+ */
+function urlSafeDecode(input) {
+    return base64Decode(input, urlSafeAlphabet);
+}
+exports.urlSafeDecode = urlSafeDecode;
+/**
+ * Decodes a base64-encoded string into bytes using the given alphabet.
+ */
+function base64Decode(input, alphabet) {
+    // Remove the padding bytes at the end of the string. We don't check whether the padding is
+    // accurate.
+    while (input.length !== 0 && input[input.length - 1] === '=')
+        input = input.slice(0, -1);
+    // Contains the output data.
+    const out = new Uint8Array(Math.floor(input.length * 6 / 8));
+    // Position within `out` of the next byte to write.
+    let outPos = 0;
+    // The bits decoded from the input are added to the right of this value.
+    let currentByte = 0;
+    // The left-most `validBitsInCurrentByte` bits of `currentByte` must be written out.
+    let validBitsInCurrentByte = 0;
+    for (let i = 0; i < input.length; ++i) {
+        const inputChr = input[i];
+        const bitsToAppend = alphabet.get(inputChr);
+        if (bitsToAppend === undefined)
+            throw new Error('Invalid base64 character: ' + inputChr);
+        console.assert(bitsToAppend < (1 << 6));
+        currentByte = (currentByte << 6) | bitsToAppend;
+        validBitsInCurrentByte += 6;
+        if (validBitsInCurrentByte >= 8) {
+            let outByte = currentByte >> (validBitsInCurrentByte - 8);
+            out[outPos] = outByte;
+            outPos += 1;
+            validBitsInCurrentByte -= 8;
+        }
+        console.assert(validBitsInCurrentByte < 8);
+        currentByte &= 0xff;
+    }
+    if ((currentByte & ((1 << validBitsInCurrentByte) - 1)) !== 0)
+        throw new Error("Unexpected EOF");
+    if (validBitsInCurrentByte >= 6)
+        throw new Error("Unexpected EOF");
+    return out;
+}
+exports.base64Decode = base64Decode;

package/dist/cjs/client.d.ts

@@ -0,0 +1,287 @@
+import { PlatformBindings } from './instance/instance.js';
+export { MalformedJsonRpcError, QueueFullError, CrashError } from './instance/instance.js';
+/**
+ * Thrown in case of a problem when initializing the chain.
+ */
+export declare class AddChainError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown in case the API user tries to use a chain or client that has already been destroyed.
+ */
+export declare class AlreadyDestroyedError extends Error {
+    constructor();
+}
+/**
+ * Thrown when trying to send a JSON-RPC message to a chain whose JSON-RPC system hasn't been
+ * enabled.
+ */
+export declare class JsonRpcDisabledError extends Error {
+    constructor();
+}
+/**
+ * Client with zero or more active connections to blockchains.
+ */
+export interface Client {
+    /**
+     * Connects to a chain.
+     *
+     * Throws an exception if the chain specification isn't valid, or if the chain specification
+     * concerns a parachain but no corresponding relay chain can be found.
+     *
+     * Smoldot will automatically de-duplicate chains if multiple identical chains are added, in
+     * order to save resources. In other words, it is not a problem to call `addChain` multiple
+     * times with the same chain specifications and obtain multiple `Chain`.
+     * When the same client is used for multiple different purposes, you are in fact strongly
+     * encouraged to trust smoldot and not attempt to de-duplicate chains yourself, as determining
+     * whether two chains are identical is complicated and might have security implications.
+     *
+     * Smoldot tries to distribute CPU resources equally between all active `Chain` objects.
+     *
+     * @param options Configuration of the chain to add.
+     *
+     * @throws {@link AddChainError} If the chain can't be added.
+     * @throws {@link AlreadyDestroyedError} If the client has been terminated earlier.
+     * @throws {@link CrashError} If the background client has crashed.
+     */
+    addChain(options: AddChainOptions): Promise<Chain>;
+    /**
+     * Terminates the client.
+     *
+     * Afterwards, trying to use the client or any of its chains again will lead to an exception
+     * being thrown.
+     *
+     * @throws {@link AlreadyDestroyedError} If the client has already been terminated earlier.
+     * @throws {@link CrashError} If the background client has crashed.
+     */
+    terminate(): Promise<void>;
+}
+/**
+ * Active connection to a blockchain.
+ */
+export interface Chain {
+    /**
+     * Enqueues a JSON-RPC request that the client will process as soon as possible.
+     *
+     * The response will be sent back using the callback passed when adding the chain.
+     *
+     * See <https://www.jsonrpc.org/specification> for a specification of the JSON-RPC format. Only
+     * version 2 is supported.
+     * Be aware that some requests will cause notifications to be sent back using the same callback
+     * as the responses.
+     *
+     * A {@link MalformedJsonRpcError} is thrown if the request isn't a valid JSON-RPC request or
+     * if the request is unreasonably large (64 MiB at the time of writing of this comment).
+     * If, however, the request is a valid JSON-RPC request but that concerns an unknown method, a
+     * error response is properly generated.
+     *
+     * Two JSON-RPC APIs are supported by smoldot:
+     *
+     * - The "legacy" one, documented here: <https://polkadot.js.org/docs/substrate/rpc>
+     * - The more recent one: <https://github.com/paritytech/json-rpc-interface-spec>
+     *
+     * @param rpc JSON-encoded RPC request.
+     *
+     * @throws {@link MalformedJsonRpcError} If the payload isn't valid JSON-RPC.
+     * @throws {@link QueueFullError} If the queue of JSON-RPC requests of the chain is full.
+     * @throws {@link AlreadyDestroyedError} If the chain has been removed or the client has been terminated.
+     * @throws {@link JsonRpcDisabledError} If the JSON-RPC system was disabled in the options of the chain.
+     * @throws {@link CrashError} If the background client has crashed.
+     */
+    sendJsonRpc(rpc: string): void;
+    /**
+     * Waits for a JSON-RPC response or notification to be generated.
+     *
+     * If this function is called multiple times "simultaneously" (generating multiple different
+     * `Promise`s), each `Promise` will return a different JSON-RPC response or notification.
+     *
+     * Each chain contains a buffer of the responses waiting to be sent out. Calling this function
+     * pulls one element from the buffer. If this function is called at a slower rate than responses
+     * are generated, then buffer will eventually become full, at which point calling
+     * {@link Chain.sendJsonRpc} will throw an exception.
+     *
+     * @throws {@link AlreadyDestroyedError} If the chain has been removed or the client has been terminated.
+     * @throws {@link JsonRpcDisabledError} If the JSON-RPC system was disabled in the options of the chain.
+     * @throws {@link CrashError} If the background client has crashed.
+     */
+    nextJsonRpcResponse(): Promise<string>;
+    /**
+     * Disconnects from the blockchain.
+     *
+     * The JSON-RPC callback will no longer be called.
+     *
+     * Trying to use the chain again will lead to an exception being thrown.
+     *
+     * If this chain is a relay chain, then all parachains that use it will continue to work. Smoldot
+     * automatically keeps alive all relay chains that have an active parachains. There is no need
+     * to track parachains and relaychains, or to destroy them in the correct order, as this is
+     * handled automatically.
+     *
+     * @throws {@link AlreadyDestroyedError} If the chain has already been removed or the client has been terminated.
+     * @throws {@link CrashError} If the background client has crashed.
+     */
+    remove(): void;
+}
+/**
+ * @param level How important this message is. 1 = Error, 2 = Warn, 3 = Info, 4 = Debug, 5 = Trace
+ * @param target Name of the sub-system that the message concerns.
+ * @param message Human-readable message that developers can use to figure out what is happening.
+ */
+export type LogCallback = (level: number, target: string, message: string) => void;
+/**
+ * Configuration of a client.
+ */
+export interface ClientOptions {
+    /**
+     * Callback that the client will invoke in order to report a log event.
+     *
+     * By default, prints the log on the `console`. If you want to disable logging altogether,
+     * please pass an empty callback function.
+     */
+    logCallback?: LogCallback;
+    /**
+     * The client will never call the callback with a value of `level` superior to this value.
+     * Defaults to 3.
+     *
+     * While this filtering could be done directly by the `logCallback`, passing a maximum log level
+     * leads to better performances as the client doesn't even need to generate a `message` when it
+     * knows that this message isn't interesting.
+     */
+    maxLogLevel?: number;
+    /**
+     * Maximum amount of CPU that the client should consume on average.
+     *
+     * This must be a number between `0.0` and `1.0`. For example, passing `0.25` bounds the client
+     * to 25% of CPU power.
+     * Defaults to `1.0` if no value is provided.
+     *
+     * Note that this is implemented by sleeping for certain amounts of time in order for the average
+     * CPU consumption to not go beyond the given limit. It is therefore still possible for the
+     * client to use high amounts of CPU for short amounts of time.
+     */
+    cpuRateLimit?: number;
+    /**
+     * If `true`, then the client will never open any TCP connection.
+     * Defaults to `false`.
+     *
+     * This option can be used in order to mimic an environment where the TCP protocol isn't
+     * supported (e.g. browsers) from an environment where TCP is supported (e.g. NodeJS).
+     *
+     * This option has no effect in environments where the TCP protocol isn't supported anyway.
+     */
+    forbidTcp?: boolean;
+    /**
+     * If `true`, then the client will never open any non-secure WebSocket connection.
+     * Defaults to `false`.
+     *
+     * This option can be used in order to mimic an environment where non-secure WebSocket
+     * connections aren't supported (e.g. web pages) from an environment where they are supported
+     * (e.g. NodeJS).
+     *
+     * This option has no effect in environments where non-secure WebSocket connections aren't
+     * supported anyway.
+     */
+    forbidWs?: boolean;
+    /**
+     * If `true`, then the client will never open any non-secure WebSocket connection to addresses
+     * other than `localhost` or `127.0.0.1`.
+     * Defaults to `false`.
+     *
+     * This option is similar to `forbidWs`, except that connections to `localhost` and `127.0.0.1`
+     * do not take the value of this option into account.
+     *
+     * This option can be used in order to mimic an environment where non-secure WebSocket
+     * connections aren't supported (e.g. web pages) from an environment where they are supported
+     * (e.g. NodeJS).
+     *
+     * This option has no effect in environments where non-secure WebSocket connections aren't
+     * supported anyway.
+     */
+    forbidNonLocalWs?: boolean;
+    /**
+     * If `true`, then the client will never open any secure WebSocket connection.
+     * Defaults to `false`.
+     *
+     * This option exists of the sake of completeness. All environments support secure WebSocket
+     * connections.
+     */
+    forbidWss?: boolean;
+    /**
+     * If `true`, then the client will never open any WebRTC connection.
+     * Defaults to `false`.
+     *
+     * This option has no effect in environments where non-secure WebSocket connections aren't
+     * supported anyway.
+     */
+    forbidWebRtc?: boolean;
+}
+/**
+ * Configuration of a blockchain.
+ */
+export interface AddChainOptions {
+    /**
+     * JSON-encoded specification of the chain.
+     *
+     * The specification of the chain can be generated from a Substrate node by calling
+     * `<client> build-spec --raw > spec.json`. Only "raw" chain specifications are supported by
+     * smoldot at the moment.
+     *
+     * If the chain specification contains a `relay_chain` field, then smoldot will try to match
+     * the value in `relay_chain` with the value in `id` of the chains in `potentialRelayChains`.
+     */
+    chainSpec: string;
+    /**
+     * Content of the database of this chain. Can be obtained by using the
+     * `chainHead_unstable_finalizedDatabase` JSON-RPC function.
+     *
+     * Smoldot reserves the right to change its database format, making previous databases
+     * incompatible. For this reason, no error is generated if the content of the database is invalid
+     * and/or can't be decoded.
+     *
+     * Important: please note that using a malicious database content can lead to a security
+     * vulnerability. This database content is considered by smoldot as trusted input. It is the
+     * responsibility of the API user to make sure that the value passed in this field comes from
+     * the same source of trust as the chain specification that was used when retrieving this
+     * database content.
+     */
+    databaseContent?: string;
+    /**
+     * If `chainSpec` concerns a parachain, contains the list of chains whose `id` smoldot will try
+     * to match with the parachain's `relay_chain`.
+     * Defaults to `[]`.
+     *
+     * Must contain exactly the objects that were returned by previous calls to `addChain`. The
+     * library uses a `WeakMap` in its implementation in order to identify chains.
+     *
+     * The primary way smoldot determines which relay chain is associated to a parachain is by
+     * inspecting the chain specification of that parachain (i.e. the `chainSpec` field).
+     *
+     * This poses a problem in situations where the same client is shared between multiple different
+     * applications: multiple applications could add mutiple different chains with the same `id`,
+     * creating an ambiguity, or an application could register malicious chains with small variations
+     * of a popular chain's `id` and try to benefit from a typo in a legitimate application's
+     * `relay_chain`.
+     *
+     * These problems can be solved by using this parameter to segregate multiple different uses of
+     * the same client. To use it, pass the list of all chains that the same application has
+     * previously added to the client. By doing so, you are guaranteed that the chains of multiple
+     * different applications can't interact in any way (good or bad), while still benefiting from
+     * the de-duplication of resources that smoldot performs in `addChain`.
+     *
+     * When multiple different parachains use the same relay chain, it is important to be sure that
+     * they are indeed using the same relay chain, and not accidentally using different ones. For
+     * this reason, this parameter is a list of potential relay chains in which only one chain
+     * should match, rather than a single `Chain` corresponding to the relay chain.
+     */
+    potentialRelayChains?: Chain[];
+    /**
+     * Disables the JSON-RPC system of the chain.
+     *
+     * This option can be used in order to save up some resources.
+     *
+     * It will be illegal to call {@link Chain.sendJsonRpc} and {@link Chain.nextJsonRpcResponse} on
+     * this chain.
+     */
+    disableJsonRpc?: boolean;
+}
+export declare function start(options: ClientOptions, platformBindings: PlatformBindings): Client;

package/dist/cjs/client.js

@@ -0,0 +1,175 @@
+"use strict";
+// Smoldot
+// Copyright (C) 2019-2022  Parity Technologies (UK) Ltd.
+// 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.start = exports.JsonRpcDisabledError = exports.AlreadyDestroyedError = exports.AddChainError = exports.CrashError = exports.QueueFullError = exports.MalformedJsonRpcError = 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 instance_js_1 = require("./instance/instance.js");
+var instance_js_2 = require("./instance/instance.js");
+Object.defineProperty(exports, "MalformedJsonRpcError", { enumerable: true, get: function () { return instance_js_2.MalformedJsonRpcError; } });
+Object.defineProperty(exports, "QueueFullError", { enumerable: true, get: function () { return instance_js_2.QueueFullError; } });
+Object.defineProperty(exports, "CrashError", { enumerable: true, get: function () { return instance_js_2.CrashError; } });
+/**
+ * Thrown in case of a problem when initializing the chain.
+ */
+class AddChainError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AddChainError";
+    }
+}
+exports.AddChainError = AddChainError;
+/**
+ * Thrown in case the API user tries to use a chain or client that has already been destroyed.
+ */
+class AlreadyDestroyedError extends Error {
+    constructor() {
+        super();
+        this.name = "AlreadyDestroyedError";
+    }
+}
+exports.AlreadyDestroyedError = AlreadyDestroyedError;
+/**
+ * Thrown when trying to send a JSON-RPC message to a chain whose JSON-RPC system hasn't been
+ * enabled.
+ */
+class JsonRpcDisabledError extends Error {
+    constructor() {
+        super();
+        this.name = "JsonRpcDisabledError";
+    }
+}
+exports.JsonRpcDisabledError = JsonRpcDisabledError;
+// This function is similar to the `start` function found in `index.ts`, except with an extra
+// parameter containing the platform-specific bindings.
+// Contrary to the one within `index.js`, this function is not supposed to be directly used.
+function start(options, platformBindings) {
+    const logCallback = options.logCallback || ((level, target, message) => {
+        // The first parameter of the methods of `console` has some printf-like substitution
+        // capabilities. We don't really need to use this, but not using it means that the logs might
+        // not get printed correctly if they contain `%`.
+        if (level <= 1) {
+            console.error("[%s] %s", target, message);
+        }
+        else if (level == 2) {
+            console.warn("[%s] %s", target, message);
+        }
+        else if (level == 3) {
+            console.info("[%s] %s", target, message);
+        }
+        else if (level == 4) {
+            console.debug("[%s] %s", target, message);
+        }
+        else {
+            console.trace("[%s] %s", target, message);
+        }
+    });
+    // For each chain object returned by `addChain`, the associated internal chain id.
+    //
+    // Immediately cleared when `remove()` is called on a chain.
+    let chainIds = new WeakMap();
+    // If `Client.terminate()̀  is called, this error is set to a value.
+    // All the functions of the public API check if this contains a value.
+    let alreadyDestroyedError = null;
+    const instance = (0, instance_js_1.start)({
+        // Maximum level of log entries sent by the client.
+        // 0 = Logging disabled, 1 = Error, 2 = Warn, 3 = Info, 4 = Debug, 5 = Trace
+        maxLogLevel: options.maxLogLevel || 3,
+        logCallback,
+        // `enableCurrentTask` adds a small performance hit, but adds some additional information to
+        // crash reports. Whether this should be enabled is very opiniated and not that important. At
+        // the moment, we enable it all the time, except if the user has logging disabled altogether.
+        enableCurrentTask: options.maxLogLevel ? options.maxLogLevel >= 1 : true,
+        cpuRateLimit: options.cpuRateLimit || 1.0,
+    }, platformBindings);
+    return {
+        addChain: (options) => __awaiter(this, void 0, void 0, function* () {
+            if (alreadyDestroyedError)
+                throw alreadyDestroyedError;
+            // Passing a JSON object for the chain spec is an easy mistake, so we provide a more
+            // readable error.
+            if (!(typeof options.chainSpec === 'string'))
+                throw new Error("Chain specification must be a string");
+            let potentialRelayChainsIds = [];
+            if (!!options.potentialRelayChains) {
+                for (const chain of options.potentialRelayChains) {
+                    // The content of `options.potentialRelayChains` are supposed to be chains earlier
+                    // returned by `addChain`.
+                    const id = chainIds.get(chain);
+                    if (id === undefined) // It is possible for `id` to be missing if it has earlier been removed.
+                        continue;
+                    potentialRelayChainsIds.push(id);
+                }
+            }
+            const outcome = yield instance.addChain(options.chainSpec, typeof options.databaseContent === 'string' ? options.databaseContent : "", potentialRelayChainsIds, !!options.disableJsonRpc);
+            if (!outcome.success)
+                throw new AddChainError(outcome.error);
+            const chainId = outcome.chainId;
+            const wasDestroyed = { destroyed: false };
+            // `expected` was pushed by the `addChain` method.
+            // Resolve the promise that `addChain` returned to the user.
+            const newChain = {
+                sendJsonRpc: (request) => {
+                    if (alreadyDestroyedError)
+                        throw alreadyDestroyedError;
+                    if (wasDestroyed.destroyed)
+                        throw new AlreadyDestroyedError();
+                    if (options.disableJsonRpc)
+                        throw new JsonRpcDisabledError();
+                    if (request.length >= 64 * 1024 * 1024) {
+                        throw new instance_js_1.MalformedJsonRpcError();
+                    }
+                    ;
+                    instance.request(request, chainId);
+                },
+                nextJsonRpcResponse: () => {
+                    if (alreadyDestroyedError)
+                        return Promise.reject(alreadyDestroyedError);
+                    if (wasDestroyed.destroyed)
+                        return Promise.reject(new AlreadyDestroyedError());
+                    if (options.disableJsonRpc)
+                        return Promise.reject(new JsonRpcDisabledError());
+                    return instance.nextJsonRpcResponse(chainId);
+                },
+                remove: () => {
+                    if (alreadyDestroyedError)
+                        throw alreadyDestroyedError;
+                    if (wasDestroyed.destroyed)
+                        throw new AlreadyDestroyedError();
+                    wasDestroyed.destroyed = true;
+                    console.assert(chainIds.has(newChain));
+                    chainIds.delete(newChain);
+                    instance.removeChain(chainId);
+                },
+            };
+            chainIds.set(newChain, chainId);
+            return newChain;
+        }),
+        terminate: () => __awaiter(this, void 0, void 0, function* () {
+            if (alreadyDestroyedError)
+                throw alreadyDestroyedError;
+            alreadyDestroyedError = new AlreadyDestroyedError();
+            instance.startShutdown();
+        })
+    };
+}
+exports.start = start;

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

@@ -0,0 +1,11 @@
+/// <reference lib="dom" />
+import { Client, ClientOptions } from './client.js';
+export { AddChainError, AddChainOptions, AlreadyDestroyedError, Chain, Client, ClientOptions, CrashError, JsonRpcDisabledError, MalformedJsonRpcError, QueueFullError, LogCallback } from './client.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;