@dynamic-labs-sdk/wallet-connect 0.1.0-alpha.17 → 0.1.0-alpha.19

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.1.0-alpha.19 (2025-10-10)
+
+This was a version bump only, there were no code changes.
+
+## 0.1.0-alpha.18 (2025-10-08)
+
+### 🚀 Features
+
+- Add TypeDoc for JavaScript SDK API Reference Documentation ([#512](https://github.com/dynamic-labs/dynamic-sdk/pull/512))
+
 ## 0.1.0-alpha.17 (2025-10-02)
 
 ### 🩹 Fixes

package/README.md

@@ -5,8 +5,8 @@ This package contains the WalletConnect integration for the Dynamic SDK.
 ## Usage
 
 ```ts
-import { addWalletConnectEvmExtension } from '@dynamic-labs-sdk/wallet-connect/evm';
-import { addWalletConnectSolanaExtension } from '@dynamic-labs-sdk/wallet-connect/solana';
+import { addWalletConnectEvmExtension } from '@dynamic-labs-sdk/evm/wallet-connect';
+import { addWalletConnectSolanaExtension } from '@dynamic-labs-sdk/solana/wallet-connect';
 import { createDynamicClient } from '@dynamic-labs-sdk/client';
 
 const dynamicClient = createDynamicClient({

package/core.cjs.js

@@ -1,6 +1,505 @@
 'use strict';
 
 var assertPackageVersion = require('@dynamic-labs-sdk/assert-package-version');
-var _package = require('./package.cjs.js');
+var isWalletConnectWalletProvider = require('./isWalletConnectWalletProvider.cjs.js');
+var client = require('@dynamic-labs-sdk/client');
+var core = require('@dynamic-labs-sdk/client/core');
+var z = require('zod/mini');
+var SignClient = require('@walletconnect/sign-client');
+var sdkApiCore = require('@dynamic-labs/sdk-api-core');
 
-assertPackageVersion.assertPackageVersion(_package.name, _package.version);
+function _interopNamespaceDefault(e) {
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n.default = e;
+    return Object.freeze(n);
+}
+
+var z__namespace = /*#__PURE__*/_interopNamespaceDefault(z);
+
+function _extends() {
+    _extends = Object.assign || function assign(target) {
+        for(var i = 1; i < arguments.length; i++){
+            var source = arguments[i];
+            for(var key in source)if (Object.prototype.hasOwnProperty.call(source, key)) target[key] = source[key];
+        }
+        return target;
+    };
+    return _extends.apply(this, arguments);
+}
+
+/**
+ * An account in WalletConnect follows the CAIP-10 standard
+ * and is formatted as follows:
+ *
+ * `<namespace>:<chain>:<address>`
+ *
+ * Where:
+ * - `<namespace>` is the namespace key (e.g. "eip155")
+ * - `<chain>` is what we refer to as a network ID (e.g. "1")
+ * - `<address>` is the address of the account (e.g. "0x1234567890")
+ *
+ * See docs: https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-10.md
+ *
+ * @returns An object with the address, namespace key, and network id
+ */ const splitCaip10Token = (caip10Token)=>{
+    const [namespaceKey, networkId, address] = caip10Token.split(':');
+    return {
+        address,
+        namespaceKey,
+        networkId
+    };
+};
+
+const createWalletAccountsForWalletConnectWalletProvider = ({ walletProvider })=>{
+    /**
+   * Since each session can have multiple namespaces, we need to find the namespace
+   * that corresponds to this specific wallet provider.
+   *
+   * A WalletConnect namespace is the equivalent of what we refer to as a chain in the SDK,
+   * and they have attributed to them the methods, events and networks that are expected
+   * to be supported by the wallet application, as well as which accounts are connected.
+   */ const namespace = walletProvider.session.namespaces[walletProvider.namespaceKey];
+    core.assertDefined(namespace, `Namespace key ${walletProvider.namespaceKey} of wallet provider ${walletProvider.key} not found in its session ${walletProvider.topic}`);
+    const accountAddresses = core.filterDuplicates(namespace.accounts.map((account)=>splitCaip10Token(account).address));
+    var _walletProvider_formatWalletAddress;
+    const formatAddress = (_walletProvider_formatWalletAddress = walletProvider.formatWalletAddress) != null ? _walletProvider_formatWalletAddress : ({ address })=>address;
+    return accountAddresses.map((address)=>({
+            address: formatAddress({
+                address
+            }),
+            chain: walletProvider.chain,
+            id: core.formatWalletAccountId({
+                address,
+                chain: walletProvider.chain,
+                walletProviderKey: walletProvider.key
+            }),
+            lastSelectedAt: null,
+            verifiedCredentialId: null,
+            walletProviderKey: walletProvider.key
+        }));
+};
+
+const sessionTopicsStorageKeySchema = core.createStorageKeySchema({
+    key: 'sessionTopics',
+    schema: z__namespace.record(/**
+     * The session topic that identifies this session.
+     */ z__namespace.string(), /**
+     * The session data.
+     */ z__namespace.object({
+        /**
+       * Whether this session's wallet accounts should be added to the dynamic's wallet accounts.
+       * When a customer connects a session with addToDynamicWalletAccounts set to false, the resulting session
+       * should not produce wallet accounts to be added to the dynamic's wallet accounts.
+       * When that happens, we cannot clear them until the page is refreshed or the wallet account is removed
+       * by the external owner by calling removeWalletAccount.
+       */ shouldAddToDynamicWalletAccounts: z__namespace.boolean()
+    }))
+});
+
+/**
+ * Sets the session topics data.
+ *
+ * Read more about it in the sessionTopicsData.types.ts file.
+ *
+ * @param update - The function to update the session topics data.
+ * @param client - The client instance.
+ */ const setSessionTopicsData = async ({ update }, client)=>{
+    const { storage } = core.getCore(client);
+    const sessionTopicsData = await storage.getItem(sessionTopicsStorageKeySchema);
+    const newSessionTopicsData = update(sessionTopicsData != null ? sessionTopicsData : {});
+    if (Object.keys(newSessionTopicsData).length === 0) {
+        return storage.removeItem(sessionTopicsStorageKeySchema);
+    }
+    return storage.setItem(sessionTopicsStorageKeySchema, newSessionTopicsData);
+};
+
+/**
+ * Gets the session topics data.
+ *
+ * Read more about it in the sessionTopicsData.types.ts file.
+ * @param client - The client instance.
+ */ const getSessionTopicsData = async (client)=>{
+    const { storage } = core.getCore(client);
+    const sessionTopicsData = await storage.getItem(sessionTopicsStorageKeySchema);
+    return sessionTopicsData != null ? sessionTopicsData : {};
+};
+
+/**
+ * Reason for disconnection when the user disconnects from a WalletConnect session.
+ *
+ * Source: https://github.com/WalletConnect/walletconnect-monorepo/blob/cc3a9d26dcbd05c92d5ded935b29dc3b6063d147/packages/utils/src/errors.ts#L87
+ */ const USER_DISCONNECTED_REASON = {
+    code: 6000,
+    message: 'User disconnected.'
+};
+
+const createSignClient = async (client)=>{
+    var _client_projectSettings_sdk_walletConnect, _core_metadata, _core_metadata1;
+    const core$1 = core.getCore(client);
+    core.assertDefined(client.projectSettings, 'Project settings not available');
+    const generalSettings = client.projectSettings.general;
+    core.assertDefined(generalSettings.displayName, 'Please configure an app name in dashboard to use WalletConnect');
+    const projectId = (_client_projectSettings_sdk_walletConnect = client.projectSettings.sdk.walletConnect) == null ? void 0 : _client_projectSettings_sdk_walletConnect.projectId;
+    core.assertDefined(projectId, 'Please configure a project ID for WalletConnect in dashboard');
+    const customStoragePrefix = `dynamic_${core$1.environmentId}_walletconnect`;
+    var _core_metadata_name;
+    const displayName = (_core_metadata_name = (_core_metadata = core$1.metadata) == null ? void 0 : _core_metadata.name) != null ? _core_metadata_name : generalSettings.displayName;
+    var _core_metadata_iconUrl;
+    const appLogo = (_core_metadata_iconUrl = (_core_metadata1 = core$1.metadata) == null ? void 0 : _core_metadata1.iconUrl) != null ? _core_metadata_iconUrl : generalSettings.appLogo;
+    return SignClient.init({
+        customStoragePrefix,
+        metadata: {
+            description: '',
+            icons: appLogo ? [
+                appLogo
+            ] : [],
+            name: displayName,
+            url: ''
+        },
+        projectId
+    });
+};
+
+const getSignClient = core.createRuntimeServiceAccessKey('walletConnectSignClient', (client)=>createSignClient(client));
+
+const createNamespaceRegistry = ()=>{
+    const walletProviderBuilderMap = new Map();
+    return {
+        getWalletProviderBuilder: (key)=>walletProviderBuilderMap.get(key),
+        registerNamespace: ({ createWalletProviderFromSession, namespaceKey })=>{
+            walletProviderBuilderMap.set(namespaceKey, createWalletProviderFromSession);
+        }
+    };
+};
+
+const getNamespaceRegistry = core.createRuntimeServiceAccessKey('walletConnectNamespaceRegistry', createNamespaceRegistry);
+
+const addMissingWalletProvidersForSessions = async ({ sessions, allowOverridingWalletProviders }, client$1)=>{
+    const namespaceRegistry = getNamespaceRegistry(client$1);
+    const walletProviderRegistry = core.getWalletProviderRegistry(client$1);
+    const sessionTopicsData = await getSessionTopicsData(client$1);
+    const currentWalletAccounts = client.getWalletAccounts(client$1);
+    // Sort so the oldest sessions are first and the newer sessions will
+    // override the older ones' wallet accounts (if there is any overlap).
+    sessions.sort((sessionA, sessionB)=>sessionA.expiry - sessionB.expiry);
+    /**
+   * All the WC wallet providers that are currently registered
+   */ const currentWalletProviders = walletProviderRegistry.listProviders().filter(isWalletConnectWalletProvider.isWalletConnectWalletProvider);
+    /**
+   * Keep record on which walletProviders are tied to active sessions
+   */ const walletProvidersWithActiveSession = [];
+    /**
+   * Maps the ID of the created wallet accounts to the wallet accounts themselves.
+   */ const createdWalletAccounts = {};
+    /**
+   * Keep record on which wallet account IDs were not in the current wallet accounts
+   * and are therefore brand new.
+   */ const brandNewWalletAccounts = new Set();
+    /**
+   * Keep record on which wallet account IDs already exist but will have
+   * their wallet provider keys overridden to use the new WC wallet provider key.
+   */ const walletAccountsToOverride = new Set();
+    for (const session of sessions){
+        const namespaceKeys = Object.keys(session.namespaces);
+        for (const namespaceKey of namespaceKeys){
+            const existingWalletProvider = currentWalletProviders.find((walletProvider)=>walletProvider.namespaceKey === namespaceKey && walletProvider.topic === session.topic);
+            if (existingWalletProvider) {
+                walletProvidersWithActiveSession.push(existingWalletProvider);
+                continue;
+            }
+            const walletProviderBuilder = namespaceRegistry.getWalletProviderBuilder(namespaceKey);
+            if (!walletProviderBuilder) {
+                continue;
+            }
+            const walletProvider = await walletProviderBuilder({
+                session
+            }, client$1);
+            walletProviderRegistry.register({
+                priority: core.WalletProviderPriority.WALLET_SDK,
+                walletProvider
+            });
+            walletProvidersWithActiveSession.push(walletProvider);
+            const sessionData = sessionTopicsData[session.topic];
+            if (!sessionData.shouldAddToDynamicWalletAccounts) {
+                continue;
+            }
+            const namespaceWalletAccounts = createWalletAccountsForWalletConnectWalletProvider({
+                walletProvider
+            });
+            if (namespaceWalletAccounts.length === 0) {
+                continue;
+            }
+            for (const createdWalletAccount of namespaceWalletAccounts){
+                const isBrandNew = !currentWalletAccounts.some((existingAccount)=>existingAccount.id === createdWalletAccount.id);
+                if (isBrandNew) {
+                    createdWalletAccounts[createdWalletAccount.id] = createdWalletAccount;
+                    brandNewWalletAccounts.add(createdWalletAccount.id);
+                    continue;
+                }
+                const existingAccount = currentWalletAccounts.find((existingAccount)=>existingAccount.id === createdWalletAccount.id);
+                const isOverrideCandidate = existingAccount && existingAccount.walletProviderKey !== createdWalletAccount.walletProviderKey;
+                if (!isOverrideCandidate) {
+                    continue;
+                }
+                // If overriding wallet providers is not allowed, we can still override
+                // as long as the wallet account being overridden is also a wallet connect wallet account.
+                const existingWalletIsWalletConnect = core.splitWalletProviderKey(existingAccount.walletProviderKey).walletProviderType === sdkApiCore.WalletProviderEnum.WalletConnect;
+                if (allowOverridingWalletProviders || existingWalletIsWalletConnect) {
+                    createdWalletAccounts[createdWalletAccount.id] = createdWalletAccount;
+                    walletAccountsToOverride.add(createdWalletAccount.id);
+                }
+            }
+        }
+    }
+    if (walletAccountsToOverride.size === 0 && brandNewWalletAccounts.size === 0) {
+        return {
+            walletProvidersWithActiveSession
+        };
+    }
+    // For now we only support connect only, so we only need to worry about unverified wallet accounts.
+    core.setUnverifiedWalletAccounts({
+        unverifiedWalletAccountsToUpdate: Object.values(createdWalletAccounts)
+    }, client$1);
+    if (brandNewWalletAccounts.size > 0) {
+        for (const walletAccountId of brandNewWalletAccounts){
+            void core.createVisit({
+                walletAccount: createdWalletAccounts[walletAccountId]
+            }, client$1);
+        }
+    }
+    core.emitWalletAccountsChangedEvent(client$1);
+    return {
+        walletProvidersWithActiveSession
+    };
+};
+
+const doSyncSessionsToWalletProviders = async ({ allowOverridingWalletProviders }, client$1)=>{
+    await core.waitForProjectSettings(client$1);
+    const signClient = await getSignClient(client$1);
+    const walletProviderRegistry = core.getWalletProviderRegistry(client$1);
+    const sessionTopicsData = await getSessionTopicsData(client$1);
+    const sessions = signClient.session.getAll().filter((session)=>{
+        if (sessionTopicsData[session.topic]) {
+            return true;
+        }
+        // If we don't have data for this session, it is corrupted and we need to disconnect
+        void signClient.disconnect({
+            reason: USER_DISCONNECTED_REASON,
+            topic: session.topic
+        });
+        return false;
+    });
+    /**
+   * All the WC wallet providers that are currently registered
+   */ const currentWalletProviders = walletProviderRegistry.listProviders().filter(isWalletConnectWalletProvider.isWalletConnectWalletProvider);
+    // Step 1: remove wallet providers whose sessions have been cleared
+    for (const walletProvider of currentWalletProviders){
+        const hasSession = sessions.some((session)=>session.topic === walletProvider.topic && walletProvider.namespaceKey in session.namespaces);
+        if (!hasSession) {
+            walletProviderRegistry.unregister(walletProvider.key);
+        }
+    }
+    // Step 2: add wallet providers that are missing for current sessions
+    const { walletProvidersWithActiveSession: updatedWalletProviders } = await addMissingWalletProvidersForSessions({
+        allowOverridingWalletProviders,
+        sessions
+    }, client$1);
+    // Step 3: identify which sessions have no more associated wallet accounts for clean up
+    const currentWalletAccounts = client.getWalletAccounts(client$1);
+    /**
+   * Maps which sessions have wallet accounts associated with them
+   */ const sessionTopicHasWalletAccountMap = new Map();
+    for (const walletProvider of updatedWalletProviders){
+        const sessionTopic = walletProvider.topic;
+        if (!sessionTopicHasWalletAccountMap.has(sessionTopic)) {
+            sessionTopicHasWalletAccountMap.set(sessionTopic, false);
+        }
+        // Early return if we already know this session has wallet accounts associated with it
+        if (sessionTopicHasWalletAccountMap.get(sessionTopic)) {
+            continue;
+        }
+        const walletProviderWalletAccounts = currentWalletAccounts.filter((walletAccount)=>walletAccount.walletProviderKey === walletProvider.key);
+        if (walletProviderWalletAccounts.length > 0) {
+            sessionTopicHasWalletAccountMap.set(sessionTopic, true);
+        }
+    }
+    // Step 4: kill sessions and their wallet providers if they have no more wallet accounts
+    for (const [sessionTopic, hasWalletAccount] of sessionTopicHasWalletAccountMap){
+        if (hasWalletAccount) {
+            continue;
+        }
+        const session = sessions.find((session)=>session.topic === sessionTopic);
+        if (session) {
+            void signClient.disconnect({
+                reason: USER_DISCONNECTED_REASON,
+                topic: session.topic
+            });
+        }
+        for (const walletProvider of updatedWalletProviders){
+            if (walletProvider.topic === sessionTopic) {
+                walletProviderRegistry.unregister(walletProvider.key);
+            }
+        }
+    }
+    // Step 5: compile which session topics are active to clean up stale session data
+    // We do session.getAll() again here to catch any sessions that might have been disconnected from other steps or even externally.
+    const activeSessionTopics = new Set(signClient.session.getAll().map((session)=>session.topic));
+    await setSessionTopicsData({
+        update: (sessionTopicsData)=>{
+            return Object.fromEntries(Object.entries(sessionTopicsData).filter(([topic])=>activeSessionTopics.has(topic)));
+        }
+    }, client$1);
+};
+const syncSessionsToWalletProviders = async ({ debounceTime = 0, allowOverridingWalletProviders }, client)=>{
+    const core$1 = core.getCore(client);
+    // This is called on adding WC extensions, which could be many in quick succession, so let's debounce
+    // the syncSessionsToWalletProviders call to ensure it only runs once and avoid race conditions.
+    return core$1.debouncedMutex({
+        callback: async ()=>doSyncSessionsToWalletProviders({
+                allowOverridingWalletProviders
+            }, client),
+        debounceTime,
+        lockKey: 'wallet-connect-sync-sessions-to-wallet-providers'
+    });
+};
+
+/**
+ * This is a lower level function that is used to connect a WalletConnect session to the Dynamic SDK.
+ * It will generate the wallet providers and wallet accounts for all accounts in the session.
+ *
+ * @param session - The session object created from the approval promise of the signClient.connect method.
+ * @param addToDynamicWalletAccounts - Whether to add the wallet accounts to the dynamic's wallet accounts.
+ * @param client - The Dynamic client instance. Only required when using multiple Dynamic clients.
+ * @returns The wallet accounts.
+ */ const connectWalletConnectSession = async ({ addToDynamicWalletAccounts = true, session }, client$1)=>{
+    /**
+   * You would normally get the session from the signClient.connect method. It takes the optionalNamespaces as an argument.
+   *
+   * Each chain should build its own "connectWithWalletConnect<chain-name>" function.
+   * Understand how to build the optionalNamespaces object:
+   *
+   * The namespace configurations are used at the time a wallet application receives the connection URI.
+   * It will use the configurations we supply to understand which methods, events and networks it should provide.
+   *
+   * The wallet application will then accept the connection request and, in the session`object, provide its own namespace object
+   * in return, which will contain the methods, events and networks it does in fact support, as well as
+   * which accounts are available.
+   *
+   * WalletConnect expects namespaces defined in the following format:
+   * ```typescript
+   * {
+   *   <namespaceKey>: {
+   *     "accounts": ["<account1>", "<account2>", "<account3>", ...],
+   *     "events": ["accountsChanged", "chainChanged", "disconnected"],
+   *     "methods": ["personal_sign", "eth_sendTransaction", "eth_accounts", ...],
+   *     "chains": ["<chain1>", "<chain2>", "<chain3>", ...]
+   *   },
+   *   ...
+   * }
+   * ```
+   *
+   * Where each account is a CAIP-10 formatted string, for example: "eip155:1:0x1234567890"
+   * — see docs: https://chainagnostic.org/CAIPs/caip-10
+   *
+   * Where each chain is a CAIP-2 formatted string, for example: "eip155:1"
+   * — see docs: https://chainagnostic.org/CAIPs/caip-2
+   */ const sessionData = {
+        shouldAddToDynamicWalletAccounts: addToDynamicWalletAccounts
+    };
+    await setSessionTopicsData({
+        update: (sessionTopicsData)=>_extends({}, sessionTopicsData, {
+                [session.topic]: sessionData
+            })
+    }, client$1);
+    /**
+   * Once the connection is established, we ensure that all active connections (aka sessions)
+   * are synced to our WalletConnect wallet providers.
+   * Each session can be uniquely identified by its topic (a random string generated by WalletConnect).
+   *
+   * Each session may have multiple wallet providers, one for each namespace (aka our SDK chains)
+   */ await syncSessionsToWalletProviders({
+        allowOverridingWalletProviders: true
+    }, client$1);
+    const sessionWalletProviders = core.getWalletProviders(client$1).filter(isWalletConnectWalletProvider.isWalletConnectWalletProvider).filter((provider)=>provider.topic === session.topic);
+    /**
+   * Upon setting the session data to NOT externally owned, syncSessionsToWalletProviders will have
+   * already created the wallet accounts for each of this session's wallet providers — so all we need
+   * to do is retrieve them.
+   */ if (addToDynamicWalletAccounts) {
+        const sessionWalletProviderKeys = sessionWalletProviders.map((provider)=>provider.key);
+        const walletAccounts = client.getWalletAccounts(client$1).filter((walletAccount)=>sessionWalletProviderKeys.includes(walletAccount.walletProviderKey));
+        return {
+            walletAccounts
+        };
+    }
+    /**
+   * If we didn't add the wallet accounts to the dynamic's wallet accounts,
+   * we never created them at all, so we need to create them now and provide
+   * them to the caller, which will become their [external] owner.
+   */ const walletAccounts = sessionWalletProviders.map((walletProvider)=>createWalletAccountsForWalletConnectWalletProvider({
+            walletProvider
+        })).flat();
+    return {
+        walletAccounts
+    };
+};
+
+/**
+ * Clears all temporary sessions and disconnects from them.
+ *
+ * External sessions are for WC sessions whose accounts are not supposed to be saved in
+ * the current dynamic's wallet accounts.
+ * Since we don't own the created wallet accounts, we must keep their corresponding WC sessions alive
+ * until the page is refreshed or the customer removes the wallet account.
+ *
+ * @param client - The client instance.
+ */ const clearTemporarySessions = async (client)=>{
+    const signClient = await getSignClient(client);
+    const sessionTopicsData = await getSessionTopicsData(client);
+    const temporarySessionTopics = Object.keys(sessionTopicsData).filter((topic)=>!sessionTopicsData[topic].shouldAddToDynamicWalletAccounts);
+    if (temporarySessionTopics.length === 0) {
+        return;
+    }
+    for (const topic of temporarySessionTopics){
+        await signClient.disconnect({
+            reason: USER_DISCONNECTED_REASON,
+            topic
+        });
+    }
+    const newSessionTopicsData = Object.fromEntries(Object.entries(sessionTopicsData).filter(([, { shouldAddToDynamicWalletAccounts: isPermanentSession }])=>isPermanentSession));
+    await setSessionTopicsData({
+        update: ()=>newSessionTopicsData
+    }, client);
+};
+
+const initializeWalletConnectExtension = async (client)=>{
+    // Clear external session topics that were created in previous browser sessions
+    // Read more in the clearTemporarySessions function.
+    await clearTemporarySessions(client);
+    // Add debounce to account for multiple WC extension additions in quick succession
+    await syncSessionsToWalletProviders({
+        allowOverridingWalletProviders: false,
+        debounceTime: 200
+    }, client);
+};
+
+assertPackageVersion.assertPackageVersion(isWalletConnectWalletProvider.name, isWalletConnectWalletProvider.version);
+
+exports.USER_DISCONNECTED_REASON = USER_DISCONNECTED_REASON;
+exports.connectWalletConnectSession = connectWalletConnectSession;
+exports.getNamespaceRegistry = getNamespaceRegistry;
+exports.getSignClient = getSignClient;
+exports.initializeWalletConnectExtension = initializeWalletConnectExtension;
+exports.splitCaip10Token = splitCaip10Token;
+exports.syncSessionsToWalletProviders = syncSessionsToWalletProviders;