Multichain API for Web (#5143) (#5157)

## Motivation

We have several internal and external use cases for dealing with more
than one chain at once.

## Proposal

Add chain-specific API, and have `Client` only initialize the client
rather than creating a default chain. This provides a place to put the
(currently hardcoded) client options, which I do, closing
#4740.

## Test Plan

Tested locally on all our Web examples.

## Release Plan

- These changes should be backported to the latest `testnet` branch,
then
    - be released in a new SDK,

## Links

- [reviewer
checklist](https://github.com/linera-io/linera-protocol/blob/main/CONTRIBUTING.md#reviewer-checklist)

Author: Twey

CLI.md

@@ -121,9 +121,6 @@ Client implementation and command-line tool for the Linera blockchain
 
 ###### **Options:**
 
-* `--wallet <WALLET_STATE_PATH>` — Sets the file storing the private state of user chains (an empty one will be created if missing)
-* `--keystore <KEYSTORE_PATH>` — Sets the file storing the keystore state
-* `-w`, `--with-wallet <WITH_WALLET>` — Given an ASCII alphanumeric parameter `X`, read the wallet state and the wallet storage config from the environment variables `LINERA_WALLET_{X}` and `LINERA_STORAGE_{X}` instead of `LINERA_WALLET` and `LINERA_STORAGE`
 * `--send-timeout-ms <SEND_TIMEOUT>` — Timeout for sending queries (milliseconds)
 
   Default value: `4000`
@@ -145,9 +142,6 @@ Client implementation and command-line tool for the Linera blockchain
 * `--max-retries <MAX_RETRIES>` — Number of times to retry connecting to a validator
 
   Default value: `10`
-* `--chrome-trace-exporter` — Enable OpenTelemetry Chrome JSON exporter for trace data analysis
-* `--chrome-trace-file <CHROME_TRACE_FILE>` — Output file path for Chrome trace JSON format. Can be visualized in chrome://tracing or Perfetto UI
-* `--otlp-exporter-endpoint <OTLP_EXPORTER_ENDPOINT>` — OpenTelemetry OTLP exporter endpoint (requires opentelemetry feature)
 * `--wait-for-outgoing-messages` — Whether to wait until a quorum of validators has confirmed that all sent cross-chain messages have been delivered
 * `--long-lived-services` — (EXPERIMENTAL) Whether application services can persist in some cases between queries
 * `--blanket-message-policy <BLANKET_MESSAGE_POLICY>` — The policy for handling incoming messages
@@ -205,6 +199,19 @@ Client implementation and command-line tool for the Linera blockchain
 * `--alternative-peers-retry-delay-ms <ALTERNATIVE_PEERS_RETRY_DELAY_MS>` — Delay in milliseconds between starting requests to different peers. This helps to stagger requests and avoid overwhelming the network
 
   Default value: `150`
+* `--listener-skip-process-inbox` — Do not create blocks automatically to receive incoming messages. Instead, wait for an explicit mutation `processInbox`
+* `--listener-delay-before-ms <DELAY_BEFORE_MS>` — Wait before processing any notification (useful for testing)
+
+  Default value: `0`
+* `--listener-delay-after-ms <DELAY_AFTER_MS>` — Wait after processing any notification (useful for rate limiting)
+
+  Default value: `0`
+* `--wallet <WALLET_STATE_PATH>` — Sets the file storing the private state of user chains (an empty one will be created if missing)
+* `--keystore <KEYSTORE_PATH>` — Sets the file storing the keystore state
+* `-w`, `--with-wallet <WITH_WALLET>` — Given an ASCII alphanumeric parameter `X`, read the wallet state and the wallet storage config from the environment variables `LINERA_WALLET_{X}` and `LINERA_STORAGE_{X}` instead of `LINERA_WALLET` and `LINERA_STORAGE`
+* `--chrome-trace-exporter` — Enable OpenTelemetry Chrome JSON exporter for trace data analysis
+* `--chrome-trace-file <CHROME_TRACE_FILE>` — Output file path for Chrome trace JSON format. Can be visualized in chrome://tracing or Perfetto UI
+* `--otlp-exporter-endpoint <OTLP_EXPORTER_ENDPOINT>` — OpenTelemetry OTLP exporter endpoint (requires opentelemetry feature)
 * `--storage <STORAGE_CONFIG>` — Storage configuration for the blockchain history
 * `--storage-max-concurrent-queries <STORAGE_MAX_CONCURRENT_QUERIES>` — The maximal number of simultaneous queries to the database
 * `--storage-max-stream-queries <STORAGE_MAX_STREAM_QUERIES>` — The maximal number of simultaneous stream queries to the database

Cargo.lock

@@ -275,6 +275,7 @@ tracing-subscriber = { version = "0.3.18", default-features = false, features =
 tracing-web = "0.1.3"
 trait-set = "0.3.0"
 trait-variant = "0.1.1"
+tsify-next = { version = "0.5.6", default-features = false, features = ["js"] }
 url = "2.4"
 wasm-bindgen = "0.2.92"
 wasm-bindgen-futures = "0.4.42"

Cargo.toml

@@ -48,67 +48,53 @@ <h2>Chain history for <code id="chain-id" class="hex">requesting chain…</code>
       </div>
     </div>
 
-    <script type="importmap">
-      {
-          "imports": {
-              "@linera/client": "./js/@linera/client/index.js"
-          }
-      }
-    </script>
-
     <script type="module">
-      import * as linera from '@linera/client';
-      import { ethers } from 'ethers';
+     import * as linera from '@linera/client';
+     import { ethers } from 'ethers';
 
-     async function run() {
-         console.log(linera);
-          await linera.initialize();
-          const faucet = await new linera.Faucet(import.meta.env.LINERA_FAUCET_URL);
-          const signer = linera.signer.PrivateKey.createRandom();
-          const wallet = await faucet.createWallet();
-          const owner = await signer.address();
-          document.getElementById('owner').innerText = owner;
-          document.getElementById('chain-id').innerText = await faucet.claimChain(wallet, owner);
-          const client = await new linera.Client(wallet, signer);
-          const counter = await client.application(import.meta.env.LINERA_APPLICATION_ID);
-          const logs = document.getElementById('logs');
-          const incrementButton = document.getElementById('increment-btn');
-          const blockTemplate = document.getElementById('block-template');
+     await linera.initialize();
+     const faucet = await new linera.Faucet(import.meta.env.LINERA_FAUCET_URL);
+     const signer = linera.signer.PrivateKey.createRandom();
+     const wallet = await faucet.createWallet();
+     const owner = await signer.address();
+     const chainId = await faucet.claimChain(wallet, owner);
+     document.getElementById('owner').innerText = owner;
+     document.getElementById('chain-id').innerText = chainId;
+     const client = await new linera.Client(wallet, signer);
+     let chain = await client.chain(chainId);
+     const counter = await chain.application(import.meta.env.LINERA_APPLICATION_ID);
+     const logs = document.getElementById('logs');
+     const incrementButton = document.getElementById('increment-btn');
+     const blockTemplate = document.getElementById('block-template');
 
-          function addLogEntry(block) {
-              const entry = logs.getElementsByTagName('template')[0].content.cloneNode(true);
-              entry.querySelector('.height').textContent = block.height;
-              entry.querySelector('.hash').textContent = block.hash;
-              logs.insertBefore(entry, logs.firstChild);
-          }
+     function addLogEntry(block) {
+         const entry = logs.getElementsByTagName('template')[0].content.cloneNode(true);
+         entry.querySelector('.height').textContent = block.height;
+         entry.querySelector('.hash').textContent = block.hash;
+         logs.insertBefore(entry, logs.firstChild);
+     }
 
-          async function updateCount(blockHash) {
-              const response = await counter.query('{ "query": "query { value }" }', { blockHash });
-              document.getElementById('count').innerText
-                  = JSON.parse(response).data.value;
-          }
+     async function updateCount(blockHash) {
+         const response = await counter.query('{ "query": "query { value }" }', { blockHash });
+         document.getElementById('count').innerText
+             = JSON.parse(response).data.value;
+     }
 
-          updateCount();
-          client.onNotification(notification => {
-              let newBlock = notification.reason.NewBlock;
-              if (notification.reason.BlockExecuted) {
-                let hash = notification.reason.BlockExecuted.hash;
-                updateCount(hash);
-              } else if (newBlock) {
-                addLogEntry(newBlock);
-                updateCount(null);
-              }
-          });
-
-          incrementButton.addEventListener('click', () => {
-              counter.query('{ "query": "mutation { increment(value: 1) }" }');
-          });
-      }
+     updateCount();
+     chain.onNotification(notification => {
+         let newBlock = notification.reason.NewBlock;
+         if (notification.reason.BlockExecuted) {
+             let hash = notification.reason.BlockExecuted.hash;
+             updateCount(hash);
+         } else if (newBlock) {
+             addLogEntry(newBlock);
+             updateCount(null);
+         }
+     });
 
-      if (document.readyState === 'loading')
-          document.addEventListener('DOMContentLoaded', run);
-      else
-          run();
+     incrementButton.addEventListener('click', () => {
+         counter.query('{ "query": "mutation { increment(value: 1) }" }');
+     });
     </script>
   </body>
 </html>

examples/Cargo.lock

@@ -65,20 +65,23 @@ <h2>Chain history for <code id="chain-id" class="hex">requesting chain…</code>
      const signer = await new linera_metamask.Signer();
      const wallet = await faucet.createWallet();
      const owner = await signer.address();
-     const chain = await faucet.claimChain(wallet, owner);
+     const chainId = await faucet.claimChain(wallet, owner);
      document.getElementById('owner').innerText = owner;
-     document.getElementById('chain-id').innerText = chain;
+     document.getElementById('chain-id').innerText = chainId;
 
      // For autosigning: first we set up a local (in-memory) signer, and provide it to the
      // client along with the MetaMask signer
      const autosigner = linera.signer.PrivateKey.createRandom();
      const client = await new linera.Client(wallet, new linera.signer.Composite(autosigner, signer));
 
-     // Connect to the counter application.
-     const counter = await client.application(import.meta.env.LINERA_APPLICATION_ID);
+     // Connect to our user chain.
+     const chain = await client.chain(chainId);
+
+     // Connect to the counter application on the chain.
+     const counter = await chain.application(import.meta.env.LINERA_APPLICATION_ID);
 
      // When we get a new block, show it in the UI and update the counter from the chain state.
-     client.onNotification(notification => {
+     chain.onNotification(notification => {
          let newBlock = notification.reason.NewBlock;
          if (!newBlock) return;
          addLogEntry(newBlock);
@@ -88,8 +91,8 @@ <h2>Chain history for <code id="chain-id" class="hex">requesting chain…</code>
      // For autosigning: we then add the in-memory signer as an owner of the chain in the
      // wallet, and set it as the default owner (so it will be used to process messages and
      // events).
-     await client.addOwner(autosigner.address());
-     wallet.setOwner(chain, autosigner.address());
+     await chain.addOwner(autosigner.address());
+     wallet.setOwner(chainId, autosigner.address());
 
      function addLogEntry(block) {
          const entry = logs.getElementsByTagName('template')[0].content.cloneNode(true);