smoldot 2.0.5 → 2.0.7

package/dist/cjs/internals/client.d.ts

@@ -7,6 +7,9 @@ export interface PlatformBindings {
     /**
      * Tries to open a new connection using the given configuration.
      *
+     * In case of a multistream connection, `onMultistreamHandshakeInfo` should be called as soon
+     * as possible.
+     *
      * @see Connection
      */
     connect(config: ConnectionConfig): Connection;
@@ -22,19 +25,14 @@ export interface PlatformBindings {
 /**
  * Connection to a remote node.
  *
- * At any time, a connection can be in one of the three following states:
+ * At any time, a connection can be in one of the following states:
  *
- * - `Opening` (initial state)
- * - `Open`
+ * - `Open` (initial state)
  * - `Reset`
  *
- * When in the `Opening` or `Open` state, the connection can transition to the `Reset` state
- * if the remote closes the connection or refuses the connection altogether. When that
- * happens, `config.onReset` is called. Once in the `Reset` state, the connection cannot
- * transition back to another state.
- *
- * Initially in the `Opening` state, the connection can transition to the `Open` state if the
- * remote accepts the connection. When that happens, `config.onOpen` is called.
+ * When in the `Open` state, the connection can transition to the `Reset` state if the remote
+ * closes the connection or refuses the connection altogether. When that happens, `config.onReset`
+ * is called. Once in the `Reset` state, the connection cannot transition back to `Open`.
  *
  * When in the `Open` state, the connection can receive messages. When a message is received,
  * `config.onMessage` is called.
@@ -112,16 +110,14 @@ export interface ConnectionConfig {
      */
     address: instance.ParsedMultiaddr;
     /**
-     * Callback called when the connection transitions from the `Opening` to the `Open` state.
+     * Callback called when a multistream connection knows information about its handshake. Should
+     * be called as soon as possible.
+     *
+     * Can only happen while the connection is in the `Open` state.
      *
      * Must only be called once per connection.
      */
-    onOpen: (info: {
-        type: 'single-stream';
-        handshake: 'multistream-select-noise-yamux';
-        initialWritableBytes: number;
-    } | {
-        type: 'multi-stream';
+    onMultistreamHandshakeInfo: (info: {
         handshake: 'webrtc';
         localTlsCertificateSha256: Uint8Array;
         remoteTlsCertificateSha256: Uint8Array;
@@ -137,7 +133,7 @@ export interface ConnectionConfig {
      *
      * This function must only be called for connections of type "multi-stream".
      */
-    onStreamOpened: (streamId: number, direction: 'inbound' | 'outbound', initialWritableBytes: number) => void;
+    onStreamOpened: (streamId: number, direction: 'inbound' | 'outbound') => void;
     /**
      * Callback called when a stream transitions to the `Reset` state.
      *
@@ -151,14 +147,14 @@ export interface ConnectionConfig {
      * written on the stream, meaning that some buffer space is now free.
      *
      * Can only happen while the connection is in the `Open` state.
-     *
      * This callback must not be called after `closeSend` has been called.
      *
+     * The total of writable bytes must not go beyond reasonable values (e.g. a few megabytes). It
+     * is not legal to provide a dummy implementation that simply passes an exceedingly large
+     * value.
+     *
      * The `streamId` parameter must be provided if and only if the connection is of type
      * "multi-stream".
-     *
-     * Only a number of bytes equal to the size of the data provided to {@link Connection.send}
-     * must be reported. In other words, the `initialWritableBytes` must never be exceeded.
      */
     onWritableBytes: (numExtra: number, streamId?: number) => void;
     /**

package/dist/cjs/internals/client.js

@@ -138,15 +138,15 @@ function start(options, wasmModule, platformBindings) {
                             throw new Error();
                         state.instance.instance.streamMessage(connectionId, message, streamId);
                     },
-                    onStreamOpened(streamId, direction, initialWritableBytes) {
+                    onStreamOpened(streamId, direction) {
                         if (state.instance.status !== "ready")
                             throw new Error();
-                        state.instance.instance.streamOpened(connectionId, streamId, direction, initialWritableBytes);
+                        state.instance.instance.streamOpened(connectionId, streamId, direction);
                     },
-                    onOpen(info) {
+                    onMultistreamHandshakeInfo(info) {
                         if (state.instance.status !== "ready")
                             throw new Error();
-                        state.instance.instance.connectionOpened(connectionId, info);
+                        state.instance.instance.connectionMultiStreamSetHandshakeInfo(connectionId, info);
                     },
                     onWritableBytes(numExtra, streamId) {
                         if (state.instance.status !== "ready")

package/dist/cjs/internals/local-instance.d.ts

@@ -103,12 +103,7 @@ export interface Instance {
      * all connections.
      */
     shutdownExecutor: () => void;
-    connectionOpened: (connectionId: number, info: {
-        type: 'single-stream';
-        handshake: 'multistream-select-noise-yamux';
-        initialWritableBytes: number;
-    } | {
-        type: 'multi-stream';
+    connectionMultiStreamSetHandshakeInfo: (connectionId: number, info: {
         handshake: 'webrtc';
         localTlsCertificateSha256: Uint8Array;
         remoteTlsCertificateSha256: Uint8Array;
@@ -116,7 +111,7 @@ export interface Instance {
     connectionReset: (connectionId: number, message: string) => void;
     streamWritableBytes: (connectionId: number, numExtra: number, streamId?: number) => void;
     streamMessage: (connectionId: number, message: Uint8Array, streamId?: number) => void;
-    streamOpened: (connectionId: number, streamId: number, direction: 'inbound' | 'outbound', initialWritableBytes: number) => void;
+    streamOpened: (connectionId: number, streamId: number, direction: 'inbound' | 'outbound') => void;
     streamReset: (connectionId: number, streamId: number) => void;
 }
 /**

package/dist/cjs/internals/local-instance.js

@@ -404,25 +404,16 @@ function startLocalInstance(config, wasmModule, eventCallback) {
                 state.onShutdownExecutorOrWasmPanic = () => { };
                 cb();
             },
-            connectionOpened: (connectionId, info) => {
+            connectionMultiStreamSetHandshakeInfo: (connectionId, info) => {
                 if (!state.instance)
                     return;
-                switch (info.type) {
-                    case 'single-stream': {
-                        state.instance.exports.connection_open_single_stream(connectionId, info.initialWritableBytes);
-                        break;
-                    }
-                    case 'multi-stream': {
-                        const handshakeTy = new Uint8Array(1 + info.localTlsCertificateSha256.length + info.remoteTlsCertificateSha256.length);
-                        buffer.writeUInt8(handshakeTy, 0, 0);
-                        handshakeTy.set(info.localTlsCertificateSha256, 1);
-                        handshakeTy.set(info.remoteTlsCertificateSha256, 1 + info.localTlsCertificateSha256.length);
-                        state.bufferIndices[0] = handshakeTy;
-                        state.instance.exports.connection_open_multi_stream(connectionId, 0);
-                        delete state.bufferIndices[0];
-                        break;
-                    }
-                }
+                const handshakeTy = new Uint8Array(1 + info.localTlsCertificateSha256.length + info.remoteTlsCertificateSha256.length);
+                buffer.writeUInt8(handshakeTy, 0, 0);
+                handshakeTy.set(info.localTlsCertificateSha256, 1);
+                handshakeTy.set(info.remoteTlsCertificateSha256, 1 + info.localTlsCertificateSha256.length);
+                state.bufferIndices[0] = handshakeTy;
+                state.instance.exports.connection_multi_stream_set_handshake_info(connectionId, 0);
+                delete state.bufferIndices[0];
             },
             connectionReset: (connectionId, message) => {
                 if (!state.instance)
@@ -443,10 +434,10 @@ function startLocalInstance(config, wasmModule, eventCallback) {
                 state.instance.exports.stream_message(connectionId, streamId || 0, 0);
                 delete state.bufferIndices[0];
             },
-            streamOpened: (connectionId, streamId, direction, initialWritableBytes) => {
+            streamOpened: (connectionId, streamId, direction) => {
                 if (!state.instance)
                     return;
-                state.instance.exports.connection_stream_opened(connectionId, streamId, direction === 'outbound' ? 1 : 0, initialWritableBytes);
+                state.instance.exports.connection_stream_opened(connectionId, streamId, direction === 'outbound' ? 1 : 0);
             },
             streamReset: (connectionId, streamId) => {
                 if (!state.instance)

package/dist/cjs/internals/remote-instance.js

@@ -179,17 +179,17 @@ function connectToInstanceServer(config) {
                 const msg = { ty: "connection-reset", connectionId, message };
                 portToServer.postMessage(msg);
             },
-            connectionOpened(connectionId, info) {
-                const msg = { ty: "connection-opened", connectionId, info };
+            connectionMultiStreamSetHandshakeInfo(connectionId, info) {
+                const msg = { ty: "connection-multistream-set-info", connectionId, info };
                 portToServer.postMessage(msg);
             },
             streamMessage(connectionId, message, streamId) {
                 const msg = { ty: "stream-message", connectionId, message, streamId };
                 portToServer.postMessage(msg);
             },
-            streamOpened(connectionId, streamId, direction, initialWritableBytes) {
+            streamOpened(connectionId, streamId, direction) {
                 state.connections.get(connectionId).add(streamId);
-                const msg = { ty: "stream-opened", connectionId, streamId, direction, initialWritableBytes };
+                const msg = { ty: "stream-opened", connectionId, streamId, direction };
                 portToServer.postMessage(msg);
             },
             streamWritableBytes(connectionId, numExtra, streamId) {
@@ -321,11 +321,11 @@ function startInstanceServer(config, initPortToClient) {
                     state.instance.connectionReset(message.connectionId, message.message);
                     break;
                 }
-                case "connection-opened": {
+                case "connection-multistream-set-info": {
                     // The connection might have been reset locally in the past.
                     if (!state.connections.has(message.connectionId))
                         return;
-                    state.instance.connectionOpened(message.connectionId, message.info);
+                    state.instance.connectionMultiStreamSetHandshakeInfo(message.connectionId, message.info);
                     break;
                 }
                 case "stream-message": {
@@ -343,7 +343,7 @@ function startInstanceServer(config, initPortToClient) {
                     if (!state.connections.has(message.connectionId))
                         return;
                     state.connections.get(message.connectionId).add(message.streamId);
-                    state.instance.streamOpened(message.connectionId, message.streamId, message.direction, message.initialWritableBytes);
+                    state.instance.streamOpened(message.connectionId, message.streamId, message.direction);
                     break;
                 }
                 case "stream-writable-bytes": {

package/dist/cjs/no-auto-bytecode-browser.js

@@ -58,7 +58,7 @@ exports.startWithBytecode = startWithBytecode;
  * Tries to open a new connection using the given configuration.
  *
  * @see Connection
- * @throws {@link ConnectionError} If the multiaddress couldn't be parsed or contains an invalid protocol.
+ * @throws any If the multiaddress couldn't be parsed or contains an invalid protocol.
  */
 function connect(config) {
     if (config.address.ty === "websocket") {
@@ -103,10 +103,7 @@ function connect(config) {
         if (connection instanceof WebSocket) {
             connection.binaryType = 'arraybuffer';
             connection.onopen = () => {
-                config.onOpen({
-                    type: 'single-stream', handshake: 'multistream-select-noise-yamux',
-                    initialWritableBytes: 1024 * 1024
-                });
+                config.onWritableBytes(1024 * 1024);
             };
             connection.onclose = (event) => {
                 const message = "Error code " + event.code + (!!event.reason ? (": " + event.reason) : "");
@@ -167,10 +164,6 @@ function connect(config) {
         let pc = undefined;
         // Contains the data channels that are open and have been reported to smoldot.
         const dataChannels = new Map();
-        // For various reasons explained below, we open a data channel in advance without reporting it
-        // to smoldot. This data channel is stored in this variable. Once it is reported to smoldot,
-        // it is inserted in `dataChannels`.
-        let handshakeDataChannel;
         // SHA256 hash of the DTLS certificate of the local node. Unknown as long as it hasn't been
         // generated.
         // TODO: could be merged with `pc` in one variable, and maybe even the other fields as well
@@ -182,7 +175,7 @@ function connect(config) {
             // The `RTCPeerConnection` is created pretty quickly. It is however still possible for
             // smoldot to cancel the opening, in which case `pc` will still be undefined.
             if (!pc) {
-                console.assert(dataChannels.size === 0 && !handshakeDataChannel, "substreams exist while pc is undef");
+                console.assert(dataChannels.size === 0, "substreams exist while pc is undef");
                 pc = null;
                 return;
             }
@@ -197,14 +190,6 @@ function connect(config) {
                 channel.channel.onmessage = null;
             }
             dataChannels.clear();
-            if (handshakeDataChannel) {
-                handshakeDataChannel.onopen = null;
-                handshakeDataChannel.onerror = null;
-                handshakeDataChannel.onclose = null;
-                handshakeDataChannel.onbufferedamountlow = null;
-                handshakeDataChannel.onmessage = null;
-            }
-            handshakeDataChannel = undefined;
             pc.close(); // Not necessarily necessary, but it doesn't hurt to do so.
         };
         // Function that configures a newly-opened channel and adds it to the map. Used for both
@@ -212,54 +197,19 @@ function connect(config) {
         const addChannel = (dataChannel, direction) => {
             const dataChannelId = dataChannel.id;
             dataChannel.binaryType = 'arraybuffer';
-            let isOpen = false;
+            let isOpen = { value: false };
             dataChannel.onopen = () => {
-                console.assert(!isOpen, "substream opened twice");
-                isOpen = true;
-                if (direction === 'first-outbound') {
-                    console.assert(dataChannels.size === 0, "dataChannels not empty when opening");
-                    console.assert(handshakeDataChannel === dataChannel, "handshake substream mismatch");
-                    config.onOpen({
-                        type: 'multi-stream',
-                        handshake: 'webrtc',
-                        // `addChannel` can never be called before the local certificate is generated, so this
-                        // value is always defined.
-                        localTlsCertificateSha256: localTlsCertificateSha256,
-                        remoteTlsCertificateSha256,
-                    });
-                }
-                else {
-                    console.assert(direction !== 'outbound' || !handshakeDataChannel, "handshakeDataChannel still defined");
-                    config.onStreamOpened(dataChannelId, direction, 65536);
-                }
+                console.assert(!isOpen.value, "substream opened twice");
+                isOpen.value = true;
+                config.onStreamOpened(dataChannelId, direction);
+                config.onWritableBytes(65536, dataChannelId);
             };
             dataChannel.onerror = dataChannel.onclose = (_error) => {
-                // A couple of different things could be happening here.
-                if (handshakeDataChannel === dataChannel && !isOpen) {
-                    // The handshake data channel that we have opened ahead of time failed to open. As this
-                    // happens before we have reported the WebRTC connection as a whole as being open, we
-                    // need to report that the connection has failed to open.
-                    killAllJs();
-                    // Note that the event doesn't give any additional reason for the failure.
-                    config.onConnectionReset("handshake data channel failed to open");
-                }
-                else if (handshakeDataChannel === dataChannel) {
-                    // The handshake data channel has been closed before we reported it to smoldot. This
-                    // isn't really a problem. We just update the state and continue running. If smoldot
-                    // requests a substream, another one will be opened. It could be a valid implementation
-                    // to also just kill the entire connection, however doing so is a bit too intrusive and
-                    // punches through abstraction layers.
-                    handshakeDataChannel.onopen = null;
-                    handshakeDataChannel.onerror = null;
-                    handshakeDataChannel.onclose = null;
-                    handshakeDataChannel.onbufferedamountlow = null;
-                    handshakeDataChannel.onmessage = null;
-                    handshakeDataChannel = undefined;
-                }
-                else if (!isOpen) {
-                    // Substream wasn't opened yet and thus has failed to open. The API has no mechanism to
-                    // report substream openings failures. We could try opening it again, but given that
-                    // it's unlikely to succeed, we simply opt to kill the entire connection.
+                if (!isOpen.value) {
+                    // Substream wasn't opened yet and thus has failed to open. The API has no
+                    // mechanism to report substream openings failures. We could try opening it
+                    // again, but given that it's unlikely to succeed, we simply opt to kill the
+                    // entire connection.
                     killAllJs();
                     // Note that the event doesn't give any additional reason for the failure.
                     config.onConnectionReset("data channel failed to open");
@@ -279,10 +229,7 @@ function connect(config) {
                 // The `data` field is an `ArrayBuffer`.
                 config.onMessage(new Uint8Array(m.data), dataChannelId);
             };
-            if (direction !== 'first-outbound')
-                dataChannels.set(dataChannelId, { channel: dataChannel, bufferedBytes: 0 });
-            else
-                handshakeDataChannel = dataChannel;
+            dataChannels.set(dataChannelId, { channel: dataChannel, bufferedBytes: 0 });
         };
         // It is possible for the browser to use multiple different certificates.
         // In order for our local certificate to be deterministic, we need to generate it manually and
@@ -432,16 +379,11 @@ function connect(config) {
                 // TODO: is the substream maybe already open? according to the Internet it seems that no but it's unclear
                 addChannel(channel, 'inbound');
             };
-            // Creating a `RTCPeerConnection` doesn't actually do anything before `createDataChannel` is
-            // called. Smoldot's API, however, requires you to treat entire connections as open or
-            // closed. We know, according to the libp2p WebRTC specification, that every connection
-            // always starts with a substream where a handshake is performed. After we've reported that
-            // the connection is open, smoldot will open a substream in order to perform the handshake.
-            // Instead of following this API, we open this substream in advance, and will notify smoldot
-            // that the connection is open when the substream is open.
-            // Note that the label passed to `createDataChannel` is required to be empty as per the
-            // libp2p WebRTC specification.
-            addChannel(pc.createDataChannel("", { id: 0, negotiated: true }), 'first-outbound');
+            config.onMultistreamHandshakeInfo({
+                handshake: 'webrtc',
+                localTlsCertificateSha256,
+                remoteTlsCertificateSha256,
+            });
         }));
         return {
             reset: (streamId) => {
@@ -467,27 +409,11 @@ function connect(config) {
             },
             closeSend: () => { throw new Error('Wrong connection type'); },
             openOutSubstream: () => {
-                // `openOutSubstream` can only be called after we have called `config.onOpen`, therefore
-                // `pc` is guaranteed to be non-null.
-                // As explained above, we open a data channel ahead of time. If this data channel is still
-                // there, we report it.
-                if (handshakeDataChannel) {
-                    // Do this asynchronously because calling callbacks within callbacks is error-prone.
-                    (() => __awaiter(this, void 0, void 0, function* () {
-                        // We need to check again if `handshakeDataChannel` is still defined, as the
-                        // connection might have been closed.
-                        if (handshakeDataChannel) {
-                            config.onStreamOpened(handshakeDataChannel.id, 'outbound', 1024 * 1024);
-                            dataChannels.set(handshakeDataChannel.id, { channel: handshakeDataChannel, bufferedBytes: 0 });
-                            handshakeDataChannel = undefined;
-                        }
-                    }))();
-                }
-                else {
-                    // Note that the label passed to `createDataChannel` is required to be empty as per the
-                    // libp2p WebRTC specification.
-                    addChannel(pc.createDataChannel(""), 'outbound');
-                }
+                // `openOutSubstream` can only be called after we have called `config.onOpen`,
+                // therefore `pc` is guaranteed to be non-null.
+                // Note that the label passed to `createDataChannel` is required to be empty as
+                // per the libp2p WebRTC specification.
+                addChannel(pc.createDataChannel(""), 'outbound');
             }
         };
     }

package/dist/cjs/no-auto-bytecode-deno.js

@@ -79,7 +79,7 @@ function connect(config) {
                 config.onWritableBytes(wasSent);
         };
         socket.onopen = () => {
-            config.onOpen({ type: 'single-stream', handshake: 'multistream-select-noise-yamux', initialWritableBytes: 1024 * 1024 });
+            config.onWritableBytes(1024 * 1024);
         };
         socket.onclose = (event) => {
             const message = "Error code " + event.code + (!!event.reason ? (": " + event.reason) : "");
@@ -134,7 +134,7 @@ function connect(config) {
             if (socket.destroyed)
                 return established;
             established === null || established === void 0 ? void 0 : established.setNoDelay();
-            config.onOpen({ type: 'single-stream', handshake: 'multistream-select-noise-yamux', initialWritableBytes: 1024 * 1024 });
+            config.onWritableBytes(1024 * 1024);
             // Spawns an asynchronous task that continuously reads from the socket.
             // Every time data is read, the task re-executes itself in order to continue reading.
             // The task ends automatically if an EOF or error is detected, which should also happen

package/dist/cjs/no-auto-bytecode-nodejs.js

@@ -75,7 +75,7 @@ function connect(config) {
                 config.onWritableBytes(wasSent);
         };
         socket.onopen = () => {
-            config.onOpen({ type: 'single-stream', handshake: 'multistream-select-noise-yamux', initialWritableBytes: 1024 * 1024 });
+            config.onWritableBytes(1024 * 1024);
         };
         socket.onclose = (event) => {
             const message = "Error code " + event.code + (!!event.reason ? (": " + event.reason) : "");
@@ -128,10 +128,7 @@ function connect(config) {
         socket.on('connect', () => {
             if (socket.destroyed)
                 return;
-            config.onOpen({
-                type: 'single-stream', handshake: 'multistream-select-noise-yamux',
-                initialWritableBytes: socket.writableHighWaterMark
-            });
+            config.onWritableBytes(socket.writableHighWaterMark);
         });
         socket.on('close', (hasError) => {
             if (socket.destroyed)

package/dist/cjs/public-types.d.ts

@@ -90,19 +90,19 @@ 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.
+     * The response can be pulled by calling {@link Chain.nextJsonRpcResponse}.
      *
      * 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.
+     * Be aware that some requests will cause notifications to be sent back through
+     * {@link Chain.nextJsonRpcResponse}.
      *
      * If the request is not a valid JSON-RPC request, then a JSON-RPC error response is later
      * generated with an `id` equal to `null`, in accordance with the JSON-RPC 2.0 specification.
      *
      * If, however, the request is a valid JSON-RPC request but that concerns an unknown method, or
      * if for example some parameters are missing, an error response is properly generated and
-     * yielded through the JSON-RPC callback.
+     * yielded through {@link Chain.nextJsonRpcResponse}.
      *
      * Two JSON-RPC APIs are supported by smoldot:
      *
@@ -121,9 +121,10 @@ export interface Chain {
      * Waits for a JSON-RPC response or notification to be generated.
      *
      * 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 the buffer will eventually become full, at which point calling
-     * {@link Chain.sendJsonRpc} will throw an exception.
+     * pulls one element from the buffer. If this function is called at a slower rate than
+     * responses are generated, then the buffer will eventually become full, at which point calling
+     * {@link Chain.sendJsonRpc} will throw an exception. The size of this buffer can be configured
+     * through {@link AddChainOptions.jsonRpcMaxPendingRequests}.
      *
      * If this function is called multiple times "simultaneously" (generating multiple different
      * `Promise`s), each `Promise` will return a different JSON-RPC response or notification. In
@@ -139,11 +140,11 @@ export interface Chain {
     /**
      * Disconnects from the blockchain.
      *
-     * The JSON-RPC callback will no longer be called. This is the case immediately after this
-     * function is called. Any on-going JSON-RPC request is instantaneously aborted.
+     * Any on-going call to {@link Chain.nextJsonRpcResponse} is instantaneously aborted and will
+     * throw a {@link AlreadyDestroyedError}.
      *
-     * Trying to use the chain again will lead to a {@link AlreadyDestroyedError} exception
-     * being thrown.
+     * Trying to use the chain again after this function has returned will lead to a
+     * {@link AlreadyDestroyedError} exception being thrown.
      *
      * While the chain instantaneously disappears from the public API as soon as this function is
      * called, its shutdown process actually happens asynchronously in the background. This means
@@ -369,7 +370,7 @@ export interface AddChainOptions {
      *
      * This field is ignored if {@link AddChainOptions.disableJsonRpc} is `true`.
      *
-     * A zero, negative or NaN value is invalid.
+     * A zero, negative or NaN value is invalid and will generate a {@link AddChainError}.
      *
      * If this value is not set, it means that there is no maximum.
      */
@@ -379,7 +380,7 @@ export interface AddChainOptions {
      *
      * This field is ignored if {@link AddChainOptions.disableJsonRpc} is `true`.
      *
-     * A negative or NaN value is invalid.
+     * A negative or NaN value is invalid and will generate a {@link AddChainError}.
      *
      * If this value is not set, it means that there is no maximum.
      */