feat: link external wallet by lwin-kyaw · Pull Request #2437 · Web3Auth/web3auth-web

lwin-kyaw · 2026-04-02T11:04:42Z

Jira Link

https://consensyssoftware.atlassian.net/browse/EMBED-85?atlOrigin=eyJpIjoiM2UxZDY3YTZlOGFkNGU2Nzg0YjFjYjliOTc5N2I1MjAiLCJwIjoiaiJ9

Description

This PR adds external wallet account linking to Web3Auth.

Users authenticated through the AUTH connector can now link and unlink external wallets, retrieve connected account metadata from user info, and access framework-level React/Vue helpers for the flow. The change also updates the demo apps to showcase the new linking UX.

What Changed

Added linkAccount(params) and unlinkAccount(address) to Web3AuthNoModal.
Introduced account-linking types and REST helpers for Citadel-backed /v1/link/wallet and /v1/unlink/wallet requests.
Added dedicated AccountLinkingError error codes and analytics events for linking/unlinking start, success, and failure.
Extended connector interfaces with generateChallengeAndSign() so external wallets can produce proof-of-ownership signatures for linking.
Refactored EVM, Solana, and WalletConnect v2 connectors to support reusable challenge/sign flows.
Implemented isolated connector creation during linking so external wallet proof generation does not mutate the main SDK session state.
Updated AuthConnector.getUserInfo() to include connectedAccounts fetched from Citadel /v1/user.
Added and exported useLinkAccount hooks/composables for:
- @web3auth/modal/react
- @web3auth/modal/vue
- @web3auth/no-modal/react
- @web3auth/no-modal/vue
Updated the Vue and Wagmi React demo apps to:
- display connected wallets from user info
- link external wallets
- unlink linked wallets
- show success/error state for the flow

User-Facing Features

Authenticated users can link an external wallet to their Web3Auth account.
Linked wallets can be unlinked later by address.
User info now includes connected account metadata, including primary account state and linked wallet details.
React and Vue consumers get a simplified useLinkAccount API with loading, error, and linked account state.

Notes

Account linking/unlinking is only supported when the active session is connected with the AUTH connector.
Automatic wallet linking currently supports METAMASK and WALLET_CONNECT_V2.
Linking uses signed wallet challenges and refreshed identity tokens returned from Citadel.

How has this been tested?

Authenticate with the AUTH connector.
Call getUserInfo() and verify connectedAccounts is returned.
Link a MetaMask wallet and confirm the linked account appears in the response.
Link a WalletConnect wallet and confirm the linked account appears in the response.
Unlink a previously linked wallet and confirm it is removed from the returned linked accounts.
Verify React/Vue demo flows show loading, success, and error states correctly.

Screenshots (if appropriate)

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

My code follows the code style of this project. (run lint)
My change requires a change to the documentation.
I have updated the documentation accordingly.
I have added tests to cover my changes.
All new and existing tests passed.

Note

High Risk
High risk because it adds new account-linking and account-switching flows that touch core connector interfaces, modal state management, and WalletConnect session handling, which can affect authentication and connection lifecycle across apps.

Overview
Adds external wallet account linking and active-wallet switching to Web3Auth, including new linkAccount, unlinkAccount, and switchAccount APIs, plus React/Vue hooks/composables and REST helpers for Citadel-backed linking/unlinking requests.

Updates the modal UI/state machine to support a dedicated WalletConnect-based account-linking session (QR flow, status/intent tracking, cleanup/reset on close), and adjusts Wagmi providers to resync on Web3Auth connection changes rather than provider identity.

Demo apps are updated to showcase linking, unlinking, switching between connected wallets, and displaying userInfo.connectedAccounts; dependencies and lockfiles are refreshed (notably MetaMask connect packages).

^{Reviewed by Cursor Bugbot for commit d0c8e95. Bugbot is set up for automated code reviews on this repo. Configure here.}

vercel · 2026-04-02T11:04:48Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
web3auth-web	Ready	Preview, Comment	May 13, 2026 2:45am

tuna1207 · 2026-05-02T05:34:32Z

+      activeAccount: this.activeAccount,
+      currentChainId: this.currentChainId,
+    });
+    if (!switchResult) {


should we log something here if the switch doesn't do anything

There's only one case that authConnector.switchAccount can return empty value, i.e when the target account is already active.

We should not need any log for that, this is not an error. Clients should handle it to prevent switching to same account again.

tuna1207 · 2026-05-02T05:52:54Z

-      if (connector.status === CONNECTOR_STATUS.NOT_READY && this.cachedConnector !== connectorName) {
+      if (
+        connector.status === CONNECTOR_STATUS.NOT_READY &&
+        this.cachedConnector !== connectorName &&


do we need to check both ? what could be the case 1 of cached and current connection match

On load, we init all the connectors (including external wallet connectors) again.
There's a case that user has linked the external wallet (the connector status is Connected) but it's not an active account (not cachedConnector).

tuna1207 · 2026-05-05T03:55:13Z

      status: ACCOUNT_LINKING_STATUS.INITIALIZING,
-    };
+    });
    this.setState({


updateAccountLinkingState already setState i don't think we need this anymore

chaitanyapotti · 2026-05-12T08:10:05Z

+  /** Address of the account */
+  address: string | null;
+  /** Auth connection id of the account */
+  authConnectionId: string | null;


groupedAuthConnectionId?

chaitanyapotti · 2026-05-12T08:10:42Z

+  success: boolean;
+
+  /** Refreshed id token for the user */
+  idToken: string;


do we also get a new access token?

No. We don't store linked account info in the accessToken, only in idToken.

chaitanyapotti · 2026-05-12T08:10:53Z

+  /** Whether the Citadel server accepted the linking request. */
+  success: boolean;
+
+  /** Refreshed id token for the user */


No, we don't refresh the accessToken.

chaitanyapotti · 2026-05-12T08:16:05Z

+ */
+export interface UnlinkAccountPayload {
+  /** Access token to authenticate the request */
+  idToken: string;


isn't all these access token and not idtoken

idToken, if I'm not mistaken.

I've updated the comment for the interfaces.

chaitanyapotti · 2026-05-12T08:16:33Z

+  let result: UnlinkAccountResult;
+
+  try {
+    result = await post<UnlinkAccountResult>(url, payload, {


deduplicate this file

Deduped here, a36472d

chaitanyapotti · 2026-05-12T08:18:08Z

  [CONNECTOR_EVENTS.MFA_ENABLED]: (isMFAEnabled: boolean) => void;
  [CONNECTOR_EVENTS.CONSENT_REQUIRING]: (data: CONNECTED_EVENT_DATA) => void;
  [CONNECTOR_EVENTS.CONSENT_ACCEPTED]: (data: CONNECTED_EVENT_DATA & { loginMode: LoginModeType }) => void;
+  [CONNECTOR_EVENTS.CONNECTION_UPDATED]: () => void;


where's the data?

chaitanyapotti · 2026-05-12T08:29:32Z

  [CONNECTOR_EVENTS.CONSENT_REQUIRING]: () => void;
  [CONNECTOR_EVENTS.CONSENT_ACCEPTED]: (data: SDK_CONSENT_ACCEPTED_EVENT_DATA) => void;
  [CONNECTOR_EVENTS.ERRORED]: (error: Web3AuthError, loginMode: LoginModeType) => void;
+  [CONNECTOR_EVENTS.CONNECTION_UPDATED]: () => void;


chaitanyapotti · 2026-05-12T08:43:40Z

      };

+      const connectionUpdatedListener = () => {
+        status.value = newWeb3Auth.status;


use the ref

chaitanyapotti · 2026-05-12T08:44:47Z

    return this.state.idToken || null;
  }

+  get accessToken(): string | null {


lint warning

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f3f96c9. Configure here.}

chaitanyapotti · 2026-05-12T14:50:41Z

    }
+
+    // attach all event bridges to the new provider
+    this._providerEngineProxy = provider;


we shouldn't ideally re-assign this object.
listeners are already set on this by clients
you're moving listeners to a new obj but depending on client framework used, it may not work correctly

lwin-kyaw added 4 commits March 31, 2026 14:07

feat: initial wallet-link implementation

85f24fd

feat: useLinkAccount hook

8e71146

chore: rebased to ew-session-management branch

6e1b8a0

feat: connect external wallet to auth account

e42e3e1

vercel Bot had a problem deploying to Preview April 2, 2026 11:05 Failure

lwin-kyaw changed the base branch from master to feat/External-wallet-session-management April 2, 2026 12:50

feat: unlink accounts

c0bbebc

vercel Bot had a problem deploying to Preview April 6, 2026 00:35 Failure

feat: get connected accounts from citadel server

1f1611e

vercel Bot had a problem deploying to Preview April 6, 2026 03:25 Failure

chore: removed local citadel server testings

7c6a094

vercel Bot had a problem deploying to Preview April 6, 2026 06:27 Failure

chore: resolved conflicts with base branch

9f46164

Base automatically changed from feat/External-wallet-session-management to master April 6, 2026 08:21

lwin-kyaw added 2 commits April 6, 2026 20:35

Merge remote-tracking branch 'origin/master' into feat/link-ext-wallet

d8ea1e0

chore: rebased with master

9e637e7

vercel Bot had a problem deploying to Preview April 6, 2026 16:40 Failure

chore: resolved conflicts

24591ca

vercel Bot had a problem deploying to Preview April 7, 2026 07:53 Failure

lwin-kyaw marked this pull request as ready for review April 7, 2026 08:39

lwin-kyaw requested review from a team as code owners April 7, 2026 08:39

cursor Bot reviewed Apr 7, 2026

View reviewed changes

Comment thread demo/vue-app-new/src/components/AppDashboard.vue Outdated

Comment thread .npmrc Outdated

lwin-kyaw added 2 commits April 8, 2026 12:51

feat: switch account

e2f3b8f

feat: persist connected account info in state

52a97dd

vercel Bot had a problem deploying to Preview April 8, 2026 08:33 Failure

cursor Bot reviewed Apr 8, 2026

View reviewed changes

Comment thread demo/vue-app-new/src/components/AppDashboard.vue Outdated

feat: updated demo

95ef452

vercel Bot had a problem deploying to Preview April 8, 2026 17:19 Failure

tuna1207 reviewed May 2, 2026

View reviewed changes

chore: addressed comments

213ed47

vercel Bot deployed to Preview May 5, 2026 03:53 View deployment

tuna1207 reviewed May 5, 2026

View reviewed changes

fix: fixed imports

53ee006

vercel Bot deployed to Preview May 5, 2026 03:58 View deployment

tuna1207 previously approved these changes May 5, 2026

View reviewed changes

fix: fixed user logged out from rejecting account linking request

8573cb0

lwin-kyaw dismissed tuna1207’s stale review via 8573cb0 May 5, 2026 08:41

vercel Bot deployed to Preview May 5, 2026 08:42 View deployment

chaitanyapotti reviewed May 12, 2026

View reviewed changes

lwin-kyaw added 2 commits May 12, 2026 16:59

Merge remote-tracking branch 'origin/master' into feat/link-ext-wallet

02b9189

feat: refactor and dedupe account-linking exports/paths

a36472d

vercel Bot deployed to Preview May 12, 2026 10:47 View deployment

cursor Bot reviewed May 12, 2026

View reviewed changes

Comment thread packages/no-modal/src/noModal.ts

fix: fixed lint

f3f96c9

vercel Bot deployed to Preview May 12, 2026 10:56 View deployment

cursor Bot reviewed May 12, 2026

View reviewed changes

Comment thread packages/no-modal/src/noModal.ts

chaitanyapotti reviewed May 12, 2026

View reviewed changes

chore: addressed comments

d0c8e95

vercel Bot deployed to Preview May 13, 2026 02:45 View deployment

Conversation

lwin-kyaw commented Apr 2, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Jira Link

Description

What Changed

User-Facing Features

Notes

How has this been tested?

Screenshots (if appropriate)

Types of changes

Checklist

Uh oh!

vercel Bot commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lwin-kyaw commented Apr 2, 2026 •

edited by cursor Bot

Loading

vercel Bot commented Apr 2, 2026 •

edited

Loading