Wallet Connection Flow

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/SuiModule/SuiModule.svelte
• src/lib/ConnectModal/ConnectModal.svelte
• src/lib/SuiModule/types.ts
• src/routes/+page.svelte
• README.md
• src/lib/SuiModule/index.js
• package.json

The Wallet Connection Flow is a core feature of the sui-svelte-wallet-kit, designed to streamline how Svelte 5 applications interact with the Sui blockchain. It provides a comprehensive solution for wallet discovery, connection, session management, and multi-account handling. The system is built around a primary SuiModule component that manages state and orchestrates the connection process, a ConnectButton for user interaction, and a ConnectModal for wallet selection.

This flow is designed to be both simple for developers to integrate and intuitive for end-users. It supports standard browser extension wallets, auto-connection persistence via localStorage, and integration with Enoki for zkLogin with providers like Google. All state is managed reactively using Svelte 5 runes.

Sources: README.md, src/lib/SuiModule/SuiModule.svelte

Core Components

The connection flow is orchestrated by three main Svelte components.

Component	Description	Source File
SuiModule	The main wrapper component that manages global state, wallet discovery, connection logic, and provides context to all other components and functions. It must wrap the application or relevant parts of it.	src/lib/SuiModule/SuiModule.svelte
ConnectButton	A UI button that displays the connection status. When clicked, it opens the ConnectModal if disconnected or can be configured to trigger other actions.	src/lib/index.d.ts:2
ConnectModal	A dialog component that lists available wallets for the user to select. It distinguishes between installed and not-installed wallets and handles the selection process.	src/lib/ConnectModal/ConnectModal.svelte

This diagram shows the relationship between the core components.

Wallet Discovery

Before a user can connect, the kit must discover which wallets are available in the user's browser. This process is handled by the initWalletDiscovery function within SuiModule.

The discovery process involves:

1. Using @suiet/wallet-sdk's WalletRadar to detect injected wallet browser extensions.
2. Querying the @wallet-standard/core registry (getWallets().get()) to find wallets that comply with the standard, such as Enoki zkLogin providers.
3. Merging and de-duplicating the list of detected wallets by name.
4. Applying custom configurations from the walletConfig prop, such as custom names and ordering.
5. The final list of availableWallets is stored as a reactive state variable and passed to the ConnectModal.

This process runs multiple times on initialization with increasing delays to catch wallets that may be injected late.

Sources: src/lib/SuiModule/SuiModule.svelte:1191-1250, package.json:67-71

The following diagram illustrates the wallet discovery flow.

Connection Process

The connection process is initiated by the user and can be broken down into initial connection, auto-connection, and wallet switching.

Initial Connection

This flow occurs when a user connects for the first time or after explicitly disconnecting.

1. User clicks the ConnectButton.
2. The ConnectButton triggers the connectWithModal function (or opens the modal directly).
3. The ConnectModal is displayed, showing a list of discovered wallets. Installed wallets are prioritized.
4. The user selects an installed wallet from the modal.
5. The modal's onSelected handler calls the connect function in SuiModule with the selected wallet adapter.
6. The connect function sets the connection status to CONNECTING, calls the wallet adapter's connect method, and fetches the user's accounts.
7. Upon success, the status becomes CONNECTED, the active account and wallet information are stored in the state, and connection data is saved to localStorage if autoConnect is enabled.
8. The onConnect callback prop is fired.

Sources: src/lib/SuiModule/SuiModule.svelte:850-870, src/lib/ConnectModal/ConnectModal.svelte:124-136, README.md:31-34

This sequence diagram shows the initial connection flow.

Auto-Connection

If the autoConnect prop on SuiModule is true, the kit will attempt to automatically reconnect the user on subsequent visits.

1. On component mount, SuiModule checks if autoConnect is enabled.
2. It calls getConnectionData() to retrieve the last used wallet's name from localStorage.
3. It searches the list of availableWallets for a matching installed wallet.
4. If a match is found, it automatically calls the connect(wallet) function to restore the session without user interaction.

Sources: src/lib/SuiModule/SuiModule.svelte:404-419, 1313-1324

The auto-connection logic is shown below.

Wallet Switching

The switchWallet function allows a connected user to change to a different wallet.

1. The application calls switchWallet().
2. The ConnectModal is opened.
3. The user selects a new wallet.
4. The switchWallet function logic calls disconnect() to clear the current session.
5. It then immediately calls connect() with the newly selected wallet.
6. Callbacks like onSelection, onBeforeDisconnect, and onConnected can be used to manage the UX during the switch.

Sources: src/lib/SuiModule/SuiModule.svelte:963-1014, README.md:290-317

Disconnection

The disconnect function terminates the wallet session.

• It calls the wallet adapter's disconnect method.
• It clears all reactive state related to the account, balance, and wallet.
• It removes the session data from localStorage by calling clearConnectionData().

Sources: src/lib/SuiModule/SuiModule.svelte:923-961

State Management

Connection state is managed within SuiModule.svelte using Svelte 5 runes, primarily $state.

State Variable	Type	Description	Source
status	ConnectionStatus	The current connection status (DISCONNECTED, CONNECTING, CONNECTED).	src/lib/SuiModule/SuiModule.svelte:14
_account	SuiAccount	Information about the currently active user account.	src/lib/SuiModule/SuiModule.svelte:15
_wallet	WalletWithStatus	Information about the currently connected wallet.	src/lib/SuiModule/SuiModule.svelte:16
_lastWalletSelection	object	The last wallet the user picked from the modal, regardless of connection success.	src/lib/SuiModule/SuiModule.svelte:44
_accountsSnapshot	SuiAccount[]	A snapshot of all accounts available from the connected wallet.	src/lib/SuiModule/SuiModule.svelte:36

These state variables are exposed to the application through exported "hook-style" functions like useCurrentAccount and useCurrentWallet.

Sources: src/lib/SuiModule/SuiModule.svelte:13-50, src/lib/SuiModule/index.js:5-29

Data Structures

The connection flow relies on several key data structures defined in types.ts.

ConnectionData

This interface defines the structure of the data stored in localStorage to enable auto-connection.

Field	Type	Description
walletName	string	The name of the last successfully connected wallet.
autoConnect	boolean	A flag indicating if auto-connect was enabled for the session.
selectedAccountAddress	string	The address of the last active account.
selectedChain	string	The chain ID of the last active network.

Sources: src/lib/SuiModule/types.ts:100-106, src/lib/SuiModule/SuiModule.svelte:218-225

WalletWithStatus

This interface extends the standard Wallet type with additional metadata used by the UI.

Field	Type	Description
name	string	The official name of the wallet.
installed	boolean	true if the wallet's adapter was detected in the browser.
displayName	string	A custom display name, if configured via walletConfig.
originalName	string	The original name, preserved if a displayName is used.
adapter	SuiWalletAdapter	The wallet adapter instance used for interactions.
iconUrl	string	URL for the wallet's icon.

Sources: src/lib/SuiModule/types.ts:118-127

zkLogin (Enoki) Integration

The kit supports "Sign in with Google" via Enoki's zkLogin. This is treated as a special type of wallet.

• Configuration: It is enabled by passing a zkLoginGoogle configuration object to SuiModule. This object must contain an apiKey from the Enoki Portal and a googleClientId.
• Discovery: If zkLoginGoogle is configured and passes basic validation, "Sign in with Google" appears in the ConnectModal as an available wallet option. The kit performs an API probe to https://api.enoki.mystenlabs.com/v1/app to provide early feedback on API key validity.
• Connection: When a user selects Google, the kit uses the @mysten/enoki package to handle the OAuth redirect flow. The registerEnokiWallets function is called internally to make the Enoki provider available to the Wallet Standard registry.

Sources: src/lib/SuiModule/SuiModule.svelte:150-198, 1252-1279, src/lib/SuiModule/types.ts:92-98, src/routes/+page.svelte:260-264