Programmatic Wallet Control

Relevant source files

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

• src/lib/SuiModule/SuiModule.svelte
• [src/lib/index.js](https://github.com
  /teededung/sui-svelte-wallet-kit/blob/main/src/lib/index.js)
• src/lib/SuiModule/types.ts
• README.md
• src/routes/+page.svelte
• src/lib/ConnectModal/ConnectModal.svelte
• src/lib/index.d.ts
• package.json

The sui-svelte-wallet-kit provides a comprehensive set of exported functions and reactive stores (runes) that allow developers to manage wallet connections, accounts, and actions directly from their application's logic. This programmatic control goes beyond the basic UI components like ConnectButton, enabling the creation of custom user experiences, automated workflows, and deeper integration with the wallet's state.

These utilities, exported from the main package entrypoint, give you full control over the wallet lifecycle, from discovering and connecting wallets to signing transactions and messages. The system is built around the central SuiModule component, which manages the underlying state and exposes these control functions for use anywhere in your Svelte application.

Sources: src/lib/index.js, README.md:100-113

Core API Functions

The library exposes several key functions for managing the wallet's connection state and performing actions. These functions can be imported directly from sui-svelte-wallet-kit.

Sources: src/lib/SuiModule/index.js, src/lib/index.d.ts

Function	Description
connect(wallet)	Connects to a specific wallet adapter instance.
disconnect()	Disconnects the current wallet, clearing all session data.
connectWithModal(onSelection?)	Opens the connection modal and awaits user selection to connect.
switchWallet(options?)	Opens the connection modal to allow switching to a different wallet. Provides extensive callbacks for a custom UX.
switchAccount(selector)	Switches the active account to another one from the list of available accounts for the current wallet.
signAndExecuteTransaction(tx)	Signs and executes a transaction using the connected wallet.
signMessage(message)	Signs a personal message with the connected wallet.
refreshSuiBalance(address, options?)	Manually triggers a refresh of the SUI balance for a given address.

Sources: src/lib/SuiModule/SuiModule.svelte:816-1025, README.md:100-113

Connection Management

Programmatic connection management allows you to control the wallet connection lifecycle from your code.

Connecting a Wallet

There are two primary ways to initiate a connection programmatically:

1. connect(wallet): Use this when you already have a WalletWithStatus object and want to connect directly without user interaction. This is useful for custom wallet selection UIs.
2. connectWithModal(onSelection?): This function opens the pre-built ConnectModal, allowing the user to select a wallet. It returns a promise that resolves when the user selects an installed wallet or cancels.

The diagram below illustrates the flow for connectWithModal.

This diagram shows the sequence of events when a dApp calls connectWithModal, leading to the modal display and eventual connection.

Sources: src/lib/SuiModule/SuiModule.svelte:816-843, src/lib/ConnectModal/ConnectModal.svelte:112-123

Switching Wallets

The switchWallet(options?) function provides a powerful way to let users change their connected wallet. It opens the ConnectModal and provides a set of callbacks to control the flow.

The SwitchWalletOptions object allows for fine-grained control over the switching process.

Option	Type	Description
onSelection	function	Callback invoked every time the user picks a wallet in the modal.
shouldConnect	function	A predicate to decide if the connection process should proceed after selection.
onBeforeDisconnect	function	Callback invoked just before the current wallet is disconnected.
onConnected	function	Callback invoked after the new wallet is successfully connected.
onCancel	function	Callback invoked if the user closes the modal without making a selection.

Sources: src/lib/SuiModule/types.ts:145-164, README.md:520-553

The following flowchart visualizes the logic within the switchWallet function.

This flowchart shows the decision points and callback executions during the wallet switching process.

Sources: src/lib/SuiModule/SuiModulesvelte:967-1025, src/routes/+page.svelte:220-237

Disconnecting

To disconnect, simply call disconnect(). This function will:

1. Call the wallet adapter's disconnect method.
2. Remove the current account and wallet state from the module.
3. Clear the connection data from localStorage.
4. Reset all related reactive stores (suiNames, suiBalance, etc.).

Sources: src/lib/SuiModule/SuiModule.svelte:925-965

Account Management

Once connected, you can programmatically manage the user's accounts.

Accessing Account Data

The kit provides Svelte 5 runes to reactively access account information:

• useCurrentAccount(): Returns the currently active SuiAccount object or undefined.
• useAccounts(): Returns an array of all accounts provided by the connected wallet.
• activeAccountIndex: A readable store (.value) containing the index of the current account in the useAccounts array.

Sources: src/lib/SuiModule/SuiModule.svelte:702-705, 745-751, README.md:115-125

Switching the Active Account

The switchAccount(selector) function changes the active account. The selector can be:

• A number (the index of the account in the useAccounts() array).
• A string (the address of the account to switch to).

When an account is switched, the useCurrentAccount store is updated, and the new selection is persisted to localStorage to be restored in future sessions.

Sources: src/lib/SuiModule/SuiModule.svelte:753-788

Signing Actions

Programmatic control is essential for performing on-chain actions.

Signing and Executing Transactions

The signAndExecuteTransaction(transaction) function is the primary method for submitting transactions.

This diagram shows that the kit function acts as a wrapper, validating state before passing the request to the underlying wallet adapter. The function intelligently checks for sui:signAndExecuteTransaction and sui:signAndExecuteTransactionBlock features on the adapter.

Sources: src/lib/SuiModule/SuiModule.svelte:1027-1059

Signing Messages

To sign an arbitrary string or byte array, use signMessage(message).

• The message can be a string or a Uint8Array.
• It returns a promise that resolves to { signature: string, messageBytes: string }.
• The function first tries the sui:signMessage standard feature, then falls back to sui:signPersonalMessage or legacy adapter methods.

You can check if the connected wallet supports this feature by calling canSignMessage(), which returns a boolean. This is useful for conditionally rendering UI elements for message signing.

Sources: src/lib/SuiModule/SuiModule.svelte:1061-1123, README.md:239-242

zkLogin (Enoki) Specific Controls

For wallets connected via Enoki's zkLogin (e.g., "Sign in with Google"), there are special functions to access session data.

• isZkLoginWallet(): Returns true if the current wallet is a zkLogin wallet by checking for the enoki:getSession feature.
• getZkLoginInfo(): Asynchronously retrieves the session and metadata from the Enoki wallet adapter. It returns an object { session: any, metadata: any } or null.

These functions allow dApps to access provider-specific information, such as the user's Google profile details, if available in the session metadata.

Sources: src/lib/SuiModule/SuiModule.svelte:1138-1161, src/routes/+page.svelte:165-176

Summary

The programmatic control layer of sui-svelte-wallet-kit offers a robust and flexible API for developers. By exporting functions for connection management, account switching, and signing actions, the library empowers developers to build custom, deeply integrated wallet experiences. The use of reactive stores for state access ensures that the UI automatically updates in response to programmatic changes, aligning perfectly with the Svelte 5 paradigm. This combination of imperative functions and reactive state management provides a complete toolkit for any Sui dApp.