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
Adds new account linking/unlinking and active-wallet switching flows that touch authentication state, connector lifecycle, and WalletConnect modal behavior; regressions could break login/connect or leave connectors in a bad state. Also introduces new Citadel API calls and token refresh handling that must be correct to avoid linking the wrong account or failing silently.

Overview
Adds external wallet account linking to the SDK: new linkAccount, unlinkAccount, and switchAccount APIs, Citadel REST helpers (/v1/link/wallet, /v1/unlink), new AccountLinkingError codes, analytics events, and a connectedAccounts shape on userInfo.

Extends connector contracts to support proof generation via generateChallengeAndSign and introduces a connection_updated event so apps (notably Wagmi providers) resync when the active account changes without a full reconnect.

Updates the modal UI to run a dedicated WalletConnect-driven account-linking/session screen (QR + status states), and exports new account-linking entrypoints for React/Vue; demo apps add linking/switching UI (Vue adds a full AccountLinkingSection, React demo adds a basic link flow) and bumps MetaMask connect package versions.

^{Reviewed by Cursor Bugbot for commit 71af882. 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 15, 2026 3:48am

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

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

fix hook reference

71af882

vercel Bot deployed to Preview May 15, 2026 03:48 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!

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