Skip to content

Quick Start: Wagmi Apps

Estimated time to read: 2 minutes

Follow this guide to onboard users in a 'Wagmi' app and enable them to quickly sign blockchain transactions using the in-app Arcana wallet.

Prerequisites

1. Install SDKs

npm install --save @arcana/auth-wagmi @arcana/auth

yarn add @arcana/auth-wagmi @arcana/auth

Wagmi Compatibility

You need to install both auth and auth-wagmi packages. Note the version compatibility:

  • For wagmi < 1.0.0 use @arcana/auth-wagmi@1.y.z
  • For wagmi >= 1.0.0, use @arcana/auth-wagmi@2.y.z
  • For wagmi >= 2.0.0, use @arcana/auth-wagmi@3.y.z

2. Integrate

import { AuthProvider } from '@arcana/auth'

Copy Client ID of the format xar_abc_alphanumeric from the app dashboard settings and create a new AuthProvider.

utils/newArcanaAuth.js
import { AuthProvider } from "@arcana/auth";

let auth: AuthProvider | null;

const newAuthProvider = () => {
  if (!auth) {
    auth = new AuthProvider(
      "xar_test_b2ddxxxxxxxxxxxxxxxxxxxxxxxx78b1fa3f"
    );
  }
  return auth;
};

export { newAuthProvider };
...
AuthProvider Optional Parameters

Besides Client ID input parameter, you can optionally customize these settings in the AuthProvider constructor:

position: wallet position within the app context - left|right

theme: wallet theme - light|dark

connectOptions: built-in login UI compact mode - true|false

See AuthProvider constructor parameters for details.

Next, use the AuthProvider to create a new ArcanaConnector instance from the auth-wagmi package.

auth-examples/sample-auth-wagmi-2/src/wagmi.ts
//
// For apps using Wagmi versions v2.a.b and auth-wagmi v3.x.y
//

import { http, createConfig } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'
import { coinbaseWallet, injected, walletConnect } from 'wagmi/connectors'
import { AuthProvider } from '@arcana/auth';
import { ArcanaConnector } from "@arcana/auth-wagmi"

let auth: AuthProvider | null;

if (!auth) {
  auth = new AuthProvider(
    "xar_dev_c2fb7be163754e57d384e24257ea2c8d2a5dd31a"
  );
}

export const connector = () => {
  return new ArcanaConnector({auth,})
};

export const config = createConfig({
  chains: [mainnet, sepolia],
  connectors: [
    injected(),
    coinbaseWallet({ appName: 'Create Wagmi' }),
    walletConnect({ projectId: import.meta.env.VITE_WC_PROJECT_ID }),
    connector(),
  ],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

declare module 'wagmi' {
  interface Register {
    config: typeof config
  }
}
...
auth-examples/sample-auth-wagmi-viem/src/App.js
//   
// For apps using Wagmi versions v1.x.y and auth-wagmi v2.a.b
//
import { configureChains, createConfig, WagmiConfig } from "wagmi";
import { publicProvider } from "wagmi/providers/public";
import { ArcanaConnector } from "@arcana/auth-wagmi";
import { polygon, polygonAmoy } from "wagmi/chains";
import { newAuthProvider } from "./utils/newArcanaAuth";
import { useAccount, useConnect, useDisconnect, useBalance } from 'wagmi'
import "../styles/globals.css";

const { chains, provider, webSocketProvider } = configureChains(
  [mainnet, polygon, polygonAmoy],
  [publicProvider()],
  { targetQuorum: 1 }
);

export const connector = (chains: Chain[]) => {
  return new ArcanaConnector({
    chains,
    options: {
      auth: newAuthProvider(),
    },
  });
};

const { chains, publicClient } = configureChains(
  [polygon, polygonAmoy],
  [publicProvider()]
);

export const wagmiEntity = createConfig({
  autoConnect: true,
  connectors: [connector(chains)],
  publicClient,
});
...
auth-examples/sample-auth-wagmi/pages/_app.tsx
//
// For apps using Wagmi versions  v0.x.y and auth-wagmi  v1.a.b
//
import { WagmiConfig, configureChains, createClient, Chain } from "wagmi";
import { goerli, mainnet, polygon, polygonAmoy } from "wagmi/chains";
import { InjectedConnector } from "wagmi/connectors/injected";
import { publicProvider } from "wagmi/providers/public";
import { ArcanaConnector } from "@arcana/auth-wagmi";
import { newAuthProvider } from "../utils/newArcanaAuth";

import "../styles/globals.css";
import type { AppProps } from "next/app";

const { chains, provider, webSocketProvider } = configureChains(
  [mainnet, goerli, polygon, polygonAmoy],
  [publicProvider()],
  { targetQuorum: 1 }
);

const connectors = [
  new ArcanaConnector({
    chains,
    options: {
      auth: newAuthProvider(),
    },
  }),
  new InjectedConnector({
    chains,
    options: {
      name: "Browser Wallet",
      shimDisconnect: true,
    },
  }),
];

const wagmiEntity = createClient({
  autoConnect: true,
  connectors,
  provider,
  webSocketProvider,
});
...

Onboard Users

To onboard users via the built-in plug-and-play login UI, use the ArcanaConnector to set up the Wagmi. Choose one of the createClient or createConfig Wagmi methods, depending upon whether you are using the Wagmi version prior to v1.0.0 or post v2.x.y.

WagmiProvider/WagmiConfig, createClient/configClient

createClient, configClient, WagmiConfig were part of older Wagmi libraries.

For details, see Wagmi Getting Started Guide and Wagmi 1.x.y Migration Guide.

auth-examples/sample-auth-wagmi-2/src/wagmi.ts
//
// For apps using Wagmi versions v2.a.b and auth-wagmi v3.x.y
//

import { http, createConfig } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'
import { coinbaseWallet, injected, walletConnect } from 'wagmi/connectors'
import { AuthProvider } from '@arcana/auth';
import { ArcanaConnector } from "@arcana/auth-wagmi"

let auth: AuthProvider | null;

if (!auth) {
  auth = new AuthProvider(
    "xar_dev_c2fb7be163754e57d384e24257ea2c8d2a5dd31a"
  );
}

export const connector = () => {
  return new ArcanaConnector({auth,})
};

export const config = createConfig({
  chains: [mainnet, sepolia],
  connectors: [
    injected(),
    coinbaseWallet({ appName: 'Create Wagmi' }),
    walletConnect({ projectId: import.meta.env.VITE_WC_PROJECT_ID }),
    connector(),
  ],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

declare module 'wagmi' {
  interface Register {
    config: typeof config
  }
}
...
auth-examples/sample-auth-wagmi-viem/src/App.js
//   
// For apps using Wagmi versions v1.x.y and auth-wagmi v2.a.b
//
import { configureChains, createConfig, WagmiConfig } from "wagmi";
import { publicProvider } from "wagmi/providers/public";
import { ArcanaConnector } from "@arcana/auth-wagmi";
import { polygon, polygonAmoy } from "wagmi/chains";
import { newAuthProvider } from "./utils/newArcanaAuth";
import { useAccount, useConnect, useDisconnect, useBalance } from 'wagmi'
import "../styles/globals.css";

const { chains, provider, webSocketProvider } = configureChains(
  [mainnet, polygon, polygonAmoy],
  [publicProvider()],
  { targetQuorum: 1 }
);

export const connector = (chains: Chain[]) => {
  return new ArcanaConnector({
    chains,
    options: {
      auth: newAuthProvider(),
    },
  });
};

const { chains, publicClient } = configureChains(
  [polygon, polygonAmoy],
  [publicProvider()]
);

export const wagmiEntity = createConfig({
  autoConnect: true,
  connectors: [connector(chains)],
  publicClient,
});
...
auth-examples/sample-auth-wagmi/pages/_app.tsx
//
// For apps using Wagmi versions  v0.x.y and auth-wagmi  v1.a.b
//
import { WagmiConfig, configureChains, createClient, Chain } from "wagmi";
import { goerli, mainnet, polygon, polygonAmoy } from "wagmi/chains";
import { InjectedConnector } from "wagmi/connectors/injected";
import { publicProvider } from "wagmi/providers/public";
import { ArcanaConnector } from "@arcana/auth-wagmi";
import { newAuthProvider } from "../utils/newArcanaAuth";

import "../styles/globals.css";
import type { AppProps } from "next/app";

const { chains, provider, webSocketProvider } = configureChains(
  [mainnet, goerli, polygon, polygonAmoy],
  [publicProvider()],
  { targetQuorum: 1 }
);

const connectors = [
  new ArcanaConnector({
    chains,
    options: {
      auth: newAuthProvider(),
    },
  }),
  new InjectedConnector({
    chains,
    options: {
      name: "Browser Wallet",
      shimDisconnect: true,
    },
  }),
];

const wagmiEntity = createClient({
  autoConnect: true,
  connectors,
  provider,
  webSocketProvider,
});
...

Initialize WagmiConfig component to bring up the built-in login UI with configured providers for social login.

auth-examples/sample-auth-wagmi-2/src/main.tsx
//
// For apps using Wagmi versions v2.a.b and auth-wagmi v3.x.y
//
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { Buffer } from 'buffer'
import React from 'react'
import ReactDOM from 'react-dom/client'
import { WagmiProvider } from 'wagmi'

import App from './App.tsx'
import { config } from './wagmi.ts'

import './index.css'

globalThis.Buffer = Buffer

const queryClient = new QueryClient()

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <App />
      </QueryClientProvider>
    </WagmiProvider>
  </React.StrictMode>,
)
auth-examples/sample-auth-wagmi-viem/app.js
//
// For apps using Wagmi versions v1.a.b and auth-wagmi v2.x.y
//
function App({ Component, pageProps }: AppProps) {
  return (
    <WagmiConfig config={wagmiEntity}>
      <Component {...pageProps} />
    </WagmiConfig>
  );
}
auth-examples/sample-auth-wagmi/pages/_app.tsx
//
// For apps using Wagmi versions v0.a.b and auth-wagmi v1.x.y
//
function App({ Component, pageProps }: AppProps) {
  return (
    <WagmiConfig client={wagmiEntity}>
      <Component {...pageProps} />
    </WagmiConfig>
  );
}
Custom Login UI

You can onboard users through a custom login UI instead of the built-in plug-and-play one. See how to use custom login UI for onboarding users in a 'Wagmi' app for details.

Arcana JWT Token

Upon successful authentication, Arcana Auth SDK returns a unique JWT token to the app called the Arcana JWT Token. App developers can access this token via getUser() method and refer to the loginToken field of the UserInfo object.

Developers can use this token to verify the user and subsequently generate another token for app use if required.

In the future, the Arcana JWT Token will be deprecated. Use userDIDToken to verify user.

Upon successful authentication, Arcana Auth SDK returns a unique DID token to the app called the Arcana DID Token. App developers can access this token via getUser() method and refer to the userDIDToken field of the UserInfo object.

Developers can use this token to verify the user and subsequently generate another token for app use.

Sign Transactions

Use the standard JSON RPC Web3 wallet operations supported by the AuthProvider. See Web3 Wallet Operations for details.

Wallet Customization

Besides theme and branding, developers can manage the user experience for signing blockchain transactions by choosing the default, built-in Arcana wallet UI and tinkering with the wallet visibility or selecting a custom wallet UI.

That's all!

Your 'Wagmi' app is now powered by Arcana Auth SDK and Arcana Auth Wagmi SDK to onboard users and allow authenticated users to sign blockchain transactions.

See Also

Arcana Auth SDK Quick Links

Arcana Auth Wagmi SDK Quick Links

Last update: May 27, 2024 by shaloo