Simplifying Integration for Wallet Developers with the New Web3Wallet SDK

Last year, WalletConnect achieved several milestones, among them the final release of the WalletConnect Sign and WalletConnect Auth APIs.

Along the way, we realized that there was a need to simplify the integration process for wallet developers, who already have so much on their plate. We also observed the reality that certain apps, such as those offering basic NFT profile picture features, will only seek to authenticate wallets, instead of opting for full transaction capabilities. With the growing popularity of these features, we need to help future-proof wallets so as to ensure compatibility, at all times, with any WalletConnect-enabled app.

That’s why we’ve taken the decision to bundle both the WalletConnect Sign and WalletConnect Auth APIs into a single package — the Web3Wallet SDK. It streamlines the integration process, making it easier for wallet developers to include the authentication and transaction signing features necessary for their users to connect and interact with all sorts of apps — now and in the future.

If you’re new to WalletConnect, you can get started immediately with the Web3Wallet SDK by heading over to our docs. If you’ve already integrated WalletConnect Sign and WalletConnect Auth, you’re all set and there is no action to take!

If you’re a wallet that has already integrated either WalletConnect Sign or WalletConnect Auth, you will absolutely be able to continue with your existing set-up. Nonetheless, we strongly encourage you to upgrade to the Web3Wallet SDK to future-proof against emerging use cases.

To demonstrate the simplicity of this new change, we will cover three basic actions (initialization, pairing, and responding to events) across two scenarios: for wallet developers who are currently using WalletConnect Sign and for wallet developers who are currently using WalletConnect Auth.

If you are a wallet that is currently using WalletConnect Sign…

1. Initialization

To get started with Web3Wallet, you’ll need to import the Core class and pass an instance of it as a parameter to the Web3Wallet.init() method. This should look familiar if you’ve previously implemented WalletConnect Sign or WalletConnect Auth.

// metadata of your app
const metadata = {
   name: "Holdstation",
   description: "Simple way to manage your investment",
   url: "https://holdstation.com/",
   icons: [],
};
  
/* old */
import { SignClient } from "@walletconnect/sign-client";

const signClient = await SignClient.init({
   projectId: PROJECT_ID,
   metadata,
})

/* new */
import { Core } from "@walletconnect/core";
import { Web3Wallet } from "@walletconnect/web3wallet";

const core = new Core({
   projectId: PROJECT_ID,
})

const web3wallet = await Web3Wallet.init({
 core, // <- pass the shared `core` instance
 metadata: `${metaData}`
})

2. Pairing

To pair your wallet with a dapp using Web3Wallet, you’ll need to set the session to the promise that approveSession returns. This is a small change from the previous version, but it makes the process much easier.

/* old */
signClient.on("session_proposal", async (proposal) => {
 const { acknowledged } = await signClient.approve({
     id: proposal.id,
     namespaces,
 });
 const session = await acknowledged();
});

await signClient.pair({ uri });

/* new */
web3wallet.on("session_proposal", async (proposal) => {
 const session = await web3wallet.approveSession({
     id: proposal.id,
     namespaces,
 });
});

await core.pairing.pair({ uri })

3. Responding to session requests

Previously you would be able to respond to a session request by calling respond. Change it to respondSessionRequest and pass in the same object as before, the topic and response.

/* old */ 
await signClient.respond({
  topic,
  response
})

/* new */ 
await web3wallet.respondSessionRequest({
  topic,
  response
})

If you are a wallet that is currently using WalletConnect Auth…

Let’s go through the same three scenarios from above.

1. Initialization

For wallets using only WalletConnect Auth, see the following. Note that now you are importing the Core class and passing the instance as a parameter to Web3Wallet.init() method.

// metadata of your app
const metadata = {
   name: "Holdstation",
   description: "Simple way to manage your investment",
   url: "https://holdstation.com/",
   icons: [],
};

/* old */
import { AuthClient } from "@walletconnect/auth-client";

const authClient = await AuthClient.init({
   projectId: process.env.NEXT_PUBLIC_PROJECT_ID,
   metadata,
})

/* new */
import { Core } from "@walletconnect/core";
import { Web3Wallet } from "@walletconnect/web3wallet";

const core = new Core({
   projectId: process.env.NEXT_PUBLIC_PROJECT_ID,
})

const web3wallet = await Web3Wallet.init({
   core, // <- pass the shared `core` instance
   metadata: `${metaData}`
})

2. Authentication

Two differences here. The first is that respond is now respondAuthRequest. Secondly, when you await core.pairing.pair() method, you’ll be passing in uri as uri: request.uri.

/* old */
const iss = `did:pkh:eip155:1:${address}`;
authClient.on("auth_request", async (event) => {
   // format the payload
   const message = authClient.formatMessage(event.params.cacaoPayload, iss);
   // prompt the user to sign the message
   const signature = await wallet.signMessage(message);
   // respond
   await authClient.respond(
       {
           id: args.id,
           signature: {
               s: signature,
               t: "eip191",
           },
       },
       iss,
   );
});

await authClient.core.pairing.pair({ uri, activatePairing: true });

/* new */
const iss = `did:pkh:eip155:1:${address}`;
web3wallet.on("auth_request", async (event) => {
   // format the payload
   const message = web3wallet.formatMessage(event.params.cacaoPayload, iss);
   // prompt the user to sign the message
   const signature = await wallet.signMessage(message);
   // respond
   await web3wallet.respondAuthRequest(
       {
           id: args.id,
           signature: {
               s: signature,
               t: "eip191",
           },
       },
       iss,
   );
})

await web3wallet.core.pairing.pair({ uri: request.uri, activatePairing: true })

3. Responding to authentication requests

There are no changes to how you respond to authentication requests with Web3Wallet. Hooray!

/* old */
authClient.on("auth_request", handler)

/* new */
web3wallet.on("auth_request", handler)

If you’re interested in learning more about how to use Web3Wallet, check out our example pages for JavaScript, Kotlin, and Swift, where you can view and interact with our SDKs. As always, reach out to the team with any questions or suggestions — we’re here to make things easier for you.

To keep up with our announcements, join our Discord and follow us on Twitter. If you are a wallet or an app that is interested in integrating WalletConnect, head over to our website and explore our documentation.