Skip to content

Quick Start: Wagmi Apps

Web3 apps using the 'Wagmi' framework can easily onboard users via social login by integrating with the Arcana Auth Wagmi SDK!

Prerequisites

Use latest SDKs

Use the latest Arcana Auth SDK release: v1.0.10. Migrate from Arcana Auth SDK v1.0.9 -> v1.0.10.

Versions older than Arcana Auth SDK v1.0.9 may encounter potential breaking changes that require app reconfiguration, integration code updates, and redeployment. Refer to the Migration Guides and Release Notes.

Use the latest Arcana Auth Wagmi SDK release: v2.0.0

1. Register & Configure

Log into the Arcana Developer Dashboard:

https://dashboard.arcana.network

In the Manage Apps dashboard screen, click the first card and create a new app entry to register app. Each app is assigned a unique Client ID at registration. The Client ID is required for integrating the app with the Arcana Auth SDK.

A default Testnet configuration profile is associated with the registered app. In the Manage Apps dashboard screen, select the registered app card and click 'Testnet' configuration settings. Choose Social Auth to configure user onboarding providers. Optionally enable gasless transactions in Arcana wallet to incentivize app users.

2. Install SDKs

Install the following SDKs:

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

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

<script src="https://cdn.jsdelivr.net/npm/@arcana/auth"></script>
<script src="https://unpkg.com/@arcana/auth"></script>
<script src="https://cdn.jsdelivr.net/npm/@arcana/auth-wagmi"></script>
<script src="https://unpkg.com/@arcana/auth-wagmi"></script>

Viem, Wagmi v2.0 or above

Apps using Viem, Wagmi v2.0 or higher must use the latest Arcana Auth Wagmi SDK v2.x.

3. Integrate

const { AuthProvider } = window.arcana.auth // From CDN
//or
import { AuthProvider } from '@arcana/auth' //From npm

Create a new AuthProvider instance. Specify the unique Client ID assigned to the app after registration.

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

You can optionally customize the following settings in the AuthProvider constructor:

alwaysVisible: Arcana wallet visibility mode - always visible in the app context or only if a blockchain transaction is triggered by the app

chainConfig: use chainId to specify the chain identifier for the active chain in the wallet and rpcUrl for specifying the RPC Url for that chain identifier

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

theme: wallet theme - light|dark

setWindowProvider: set window.ethereum in the app context with the standard EIP-1193 Ethereum provider value

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

See AuthProvider constructor parameters for details.

Next, import the ArcanaConnector from the auth-wagmi package. Create a new instance of ArcanaConnector and specify the AuthProvider instantiated earlier.

App.js
// Note:  
// This sample code is for 
// wagmi versions <1.x.x and auth-wagmi <2.0.0

import { WagmiConfig, configureChains, createClient, Chain } from "wagmi";
import { goerli, mainnet, polygon, polygonMumbai } 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, polygonMumbai],
  [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,
});
...
App.js
// Note:  
// This sample code is for 
// wagmi versions 1.x.x and auth-wagmi 2.0.0
import { configureChains, createConfig, WagmiConfig } from "wagmi";
import { publicProvider } from "wagmi/providers/public";
import { ArcanaConnector } from "@arcana/auth-wagmi";
import { polygon, polygonMumbai } 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, polygonMumbai],
  [publicProvider()],
  { targetQuorum: 1 }
);

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

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

export const wagmiEntity = createConfig({
  autoConnect: true,
  connectors: [connector(chains)],
  publicClient,
});
...

Onboard Users

To use the built-in [onboard-wagmi-app-pnp-ui|plug-and-play login UI], for onboarding users quickly, set up the Wagmi connector through the ArcanaConnector. Use createClient or createConfig, depending upon whether you are using Wagmi version v1.x or v2.x. Refer to the appropriate sample code in the tabs below.

App.js
// Note:  
// This sample code is for 
// wagmi versions <1.x.x and auth-wagmi <2.0.0

import { WagmiConfig, configureChains, createClient, Chain } from "wagmi";
import { goerli, mainnet, polygon, polygonMumbai } 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, polygonMumbai],
  [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,
});
...
App.js
// Note:  
// This sample code is for 
// wagmi versions 1.x.x and auth-wagmi 2.0.0
import { configureChains, createConfig, WagmiConfig } from "wagmi";
import { publicProvider } from "wagmi/providers/public";
import { ArcanaConnector } from "@arcana/auth-wagmi";
import { polygon, polygonMumbai } 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, polygonMumbai],
  [publicProvider()],
  { targetQuorum: 1 }
);

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

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

export const wagmiEntity = createConfig({
  autoConnect: true,
  connectors: [connector(chains)],
  publicClient,
});
...

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

app.tsx
function App({ Component, pageProps }: AppProps) {
  return (
    <WagmiConfig client={wagmiEntity}>
      <Component {...pageProps} />
    </WagmiConfig>
  );
}
app.tsx
function App({ Component, pageProps }: AppProps) {
  return (
    <WagmiConfig config={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 use this token to verify user login and subsequently generate another token for app use. Learn more about how to verify the Arcana JWT Token for apps deployed on Testnet and Mainnet.

Sign Transactions

Use the standard JSON RPC Web3 wallet operations supported by the AuthProvider.

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.

4. Deploy

Finally, deploy the app on Testnet (default). For Mainnet deployment, see Testnet > Mainnet Migration Guide.

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.

createClient vs. creatConfig usage

See Wagmi Getting Started Guide and Wagmi 1.x.y Migration Guide.

See Also

Arcana Auth SDK Quicklinks

Arcana Auth Wagmi SDK Quicklinks

Last update: April 12, 2024 by shaloo