feat(templates): integrate external wallet into React template

[tash-2s]

Summary

This pull request introduces the ability to use external wallets with the React template. In addition to the existing standalone burner account option, users can now opt for external wallets in the client UI. Regardless of whether they choose the standalone burner account setup or the external wallet with a delegated burner account setup, they can use the app without feeling any difference.

This PR aims to allow developers to integrate external wallets easily, which is necessary for non-development chains. It also maintains the standalone burner account experience to avoid the frictions of using external wallets during local development.

Experience

After the client is launched, users first choose between a standalone burner account and an external wallet with a delegated burner account. Selecting the former allows immediate use of the app, while the latter guides users to connect their external wallets and register delegation to their burner accounts. Afterward, they can start using the app.

When editing App.ts and createSystemCalls.ts, there's no need to account for these differences because the code manages them under the hood.

Structure

Below is the structure of the React components:

mud/templates/react/packages/client/src/index.tsx

Lines 16 to 26 in af147bb

	setup().then(({ network, wagmiConfig }) => {
	root.render(
	<WagmiProvider config={wagmiConfig}>
	<QueryClientProvider client={queryClient}>
	<MUD network={network}>
	<App />
	</MUD>
	</QueryClientProvider>
	</WagmiProvider>,
	);
	});

To explain this, here is the expanded version with comments:

// Configures Wagmi. Wagmi is only used for an external wallet.
// Rerendering of this component is not allowed. So, it is placed at the root level.
// (We cannot mount at the point when an external wallet is selected.)
<WagmiProvider config={wagmiConfig}>

  // Wagmi depends on QueryClient.
  <QueryClientProvider client={queryClient}>

    // Holds an immutable network config (e.g., World address, public client, client store),
    // which is the result of `setupNetwork()`.
    <NetworkProvider network={network}>

      // Waits for the client store's sync before rendering its children.
      // Until then, displays a progress message.
      <StoreSync>

        // Manages wallets. This does not block its children's rendering.
        // This comes after `StoreSync` because this may use the delegation table.
        //
        // Can be in one of three states: unset, external-with-delegated-burner, and standalone-burner.
        //
        // - unset: An initial state. Allows a user to select either external-with-delegated-burner or standalone-burner.
        // - external-with-delegated-burner: Allows a user to connect an external wallet and then
        //   register delegation between the external account and a burner account.
        // - standalone-burner: Uses a burner account without an external wallet.
        //   No additional user interaction is involved. This is only available when in development mode.
        <WalletManager>

          // Holds `burner` that includes a wallet client and a World contract.
          // `burner` is null until the delegated burner is ready or the standalone-burner is selected.
          // The burner account is not created during `setupNetwork()`. Instead, it's created when necessary.
          <BurnerProvider burner={burner}>

            // The main component that users face.
            // When the burner is not available, this works in a read-only mode.
            <App>
              /*
               * E.g.,
               * ```
               * const {
               *   network: { tables, useStore },
               *   burner, // type: Burner | undefined
               * } = useMUD(); // Internally, this utilizes `NetworkContext`, `BurnerContext`, and `createSystemCalls.ts`.
               * ```
               * - `burner?.systemCalls.addTask("something")`
               * - `burner?.walletClient`
               * - `burner?.worldContract`
               */

            // Displays dev-tools for a burner account when in development mode.
            {import.meta.env.DEV && <DevTools />}

Demo

demo.mp4

Misc.

This PR includes the same code as #2366. Once the PR is merged, callFrom.ts and its associated dependencies (protocol-parser and store) can be removed.

• Closes Support for external wallets in templates #2260
  • I changed the approach from the one mentioned in this issue since I realized we should keep the existing standalone burner setup for developer experience.
• Closes feat(examples): add external wallet support example #2306
• Closes feat(examples): upgrade wagmi to v2 and implement viem custom client within example #2307
• Closes feat(examples): support external wallet delegating to burner wallet within example #2309

[changeset-bot]

⚠️ No Changeset found

Latest commit: c8d74c9

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[tash-2s]

This PR is ready for review. I've addressed the previous feedback, organized the structure, and added comments.

@holic I'd appreciate your feedback on this when you're available. I can update the approach and code as needed. Also, please point out anything that may be difficult to understand or requires further explanation. 🙇

[tash-2s]

The CI failed because turbo used the main branch's build cache and did "cache hit" for packages changed on main for some reason. 🤔 I'll merge main at some point.

[tash-2s]

I've removed callFrom since it was merged in #2366. Also, I've added a short README containing instructions for using external wallets.

[holic]

closing as we're taking a different approach for onboarding