Feature Overview
Relevant source files
The following files were used as context for generating this wiki page:sui-svelte-wallet-kit is a toolkit for Svelte 5 applications to integrate with the Sui blockchain. It provides a comprehensive solution for wallet connectivity, account management, transaction signing, and data fetching. Built with Svelte 5 runes, it offers a reactive and fully-typed API for building Sui dApps. The kit includes pre-built UI components for a streamlined user experience, supports popular Sui wallets, and offers integration with Enoki for zkLogin via Google.
The core of the library is the SuiModule component, which acts as a provider, managing the wallet connection state and exposing reactive stores and functions to the rest of the application. This allows developers to easily access wallet information, sign transactions, and interact with the Sui network.
Sources: README.md:5-12, package.json:3, src/lib/SuiModule/SuiModule.svelte:1124-1126
Core Architecture
The library's architecture is centered around the SuiModule Svelte component, which encapsulates all wallet-related logic and state. It uses other components like ConnectButton and ConnectModal to provide the user interface for wallet interactions.
Sources: README.md:80, src/lib/SuiModule/SuiModule.svelte
Components
The library exports three main Svelte components:
| Component | Description | Source File |
|---|---|---|
SuiModule | The main provider component that wraps the application. It manages state, handles wallet discovery, and provides context for all other functions and components. | src/lib/SuiModule/SuiModule.svelte |
ConnectButton | A UI button that toggles between "Connect" and "Disconnect" states. Clicking it opens the ConnectModal. It can be customized with CSS classes and styles. | src/lib/index.d.ts:2 |
ConnectModal | A modal dialog used internally by SuiModule to display a list of available wallets for the user to select. It separates installed wallets from others for better UX. | src/lib/ConnectModal/ConnectModal.svelte, src/lib/SuiModule/SuiModule.svelte:12, 1229-1239 |
Sources: README.md:80-99, package.json:40-55
The following diagram illustrates the relationship between the core components.
State Management and API
The kit is built for Svelte 5 and uses runes for state management. All core data, such as the current account, wallet, and balance, are exposed as reactive stores or "hook-style" functions.
Key exported functions and stores include:
| Export | Type | Description |
|---|---|---|
useCurrentAccount() | Function | Returns the currently connected SuiAccount. |
useAccounts() | Function | Returns an array of all accounts available from the connected wallet. |
useCurrentWallet() | Function | Returns information about the currently connected SuiWallet. |
useSuiClient() | Function | Returns an instance of the SuiClient for the active network. |
suiBalance | Store | A readable store containing the SUI balance of the current account as a string. |
suiNames | Store | A readable store containing an array of SuiNS names for the current account. |
connect() | Function | Programmatically connect to a specific wallet. |
disconnect() | Function | Disconnects the current wallet and clears session data. |
switchWallet() | Function | Opens the connection modal to allow the user to switch to a different wallet. |
switchAccount() | Function | Switches the active account to another one from the list of available accounts. |
signAndExecuteTransaction() | Function | Signs and executes a transaction using the connected wallet. |
signMessage() | Function | Signs a personal message using the connected wallet. |
refreshSuiBalance() | Function | Manually triggers a refresh of the SUI balance for a given address, with caching options. |
Sources: src/lib/SuiModule/index.js:5-32, README.md:143-157, src/lib/SuiModule/SuiModule.svelte:692-700, 894-901, 959-962.
Wallet Connection and Discovery
The wallet connection process is designed to be seamless, with automatic discovery and an intuitive modal interface.
Wallet Discovery
On initialization, SuiModule performs wallet discovery.
- It uses
@suiet/wallet-sdk'sWalletRadarand@wallet-standard/core'sgetWallets()to detect all available wallet extensions and injected providers in the browser. - The detected wallets are merged and deduplicated.
- The list is then processed with the user-provided
walletConfigto apply custom names and ordering. - This process runs multiple times on startup to catch wallets that initialize late. It also listens for
registerevents from the Wallet Standard registry to dynamically update the list.
Sources: src/lib/SuiModule/SuiModule.svelte:1003-1014, 1089-1121
Connection Flow
The following sequence diagram shows a typical user connection flow.
This diagram illustrates the interaction between the user, UI components, the core module, and the browser wallet extension to establish a connection.
Sources: src/lib/SuiModule/SuiModule.svelte:810-827, 856-892, src/lib/ConnectModal/ConnectModal.svelte:121-136, README.md:89-92
Auto-Connect
The kit supports an autoConnect feature. When enabled, it saves the name of the last successfully connected wallet to localStorage. On subsequent page loads, SuiModule reads this data and attempts to automatically reconnect to that wallet if it's still installed.
Sources: src/lib/SuiModule/SuiModule.svelte:145-154, 401-414, 1198-1208, README.md:82
zkLogin (Enoki) Integration
The library provides built-in support for social logins on Sui using Enoki's zkLogin. Currently, "Sign in with Google" is supported.
Configuration
To enable zkLogin, the zkLoginGoogle prop must be passed to SuiModule with the necessary credentials.
| Property | Type | Description |
|---|---|---|
apiKey | string | The API key from the Enoki Portal. |
googleClientId | string | The Google OAuth Client ID. |
network | string | Optional. The Sui network to use (mainnet, testnet, devnet). |
redirectUrl | string | Optional. A single redirect URL for the OAuth flow. |
redirectUrls | string[] | Optional. A list of allowed redirect URLs. |
Sources: src/lib/SuiModule/types.ts:79-85, README.md:121-127
Initialization Flow
The following diagram shows how zkLogin is initialized and validated.
This flow ensures that the "Sign in with Google" option is only shown if the configuration is present and the API key is likely valid, providing early feedback to developers.
Sources: src/lib/SuiModule/SuiModule.svelte:177-217, 1100-1119, 1215-1224, README.md:133-138
Data Fetching and Caching
The kit automates the fetching of essential on-chain data like SUI balance and SuiNS names.
SuiNS and Balance Fetching
autoSuiNS: Whentrue(default), the kit automatically fetches SuiNS names for the connected account(s) usingresolveAddressToSuiNSNames. On the first connection, it fetches for all available accounts; on subsequent account switches, it fetches only for the active one.autoSuiBalance: Whentrue(default), the SUI balance is fetched automatically whenever the active account or network changes.
Sources: src/lib/SuiModule/SuiModule.svelte:418-446, 1209-1214, 1130-1134, README.md:83-84
Balance Caching
To prevent excessive network requests, the SUI balance is cached.
- A default TTL of 2000ms is used. This can be changed globally via
setSuiBalanceCacheTTL(). - The
refreshSuiBalance(address, options)function can be called to manually refetch the balance. Theforce: trueoption bypasses the cache TTL. - Concurrent requests for the same balance are deduplicated; only one network request is made.
Sources: src/lib/SuiModule/SuiModule.svelte:452-494, 500-504
Transaction and Message Signing
The library provides a consistent API for signing transactions and messages across different wallets.
Signing a Transaction
The signAndExecuteTransaction(transaction) function is the primary method for submitting transactions.
- It ensures a wallet is connected and an account is active.
- It automatically sets the sender on the transaction object if the
setSendermethod exists. - It calls the appropriate method on the wallet adapter, checking for
sui:signAndExecuteTransactionor the legacysui:signAndExecuteTransactionBlockfeature.
The flow is depicted below:
Signing a Message
The signMessage(message) function handles personal message signing. It intelligently checks for wallet support in the following order:
sui:signMessage(standard)sui:signPersonalMessage(common alternative, used by Enoki)- Adapter-specific
signPersonalMessagemethod (legacy)
The canSignMessage() utility function returns a boolean indicating if the currently connected wallet supports any of these signing methods.
Sources: src/lib/SuiModule/SuiModule.svelte:991-1043, 1045-1062, README.md:426-451
TypeScript Support
The package is written in TypeScript and exports comprehensive type definitions for all its components, functions, and data structures. This enables full IntelliSense, type-checking, and improved developer experience in TypeScript-enabled Svelte projects.
Core Data Types
Key types are defined in src/lib/SuiModule/types.ts and re-exported for public use.
This diagram shows some of the main configuration and data model types available to developers.
Sources: src/lib/SuiModule/types.ts, src/lib/index.d.ts, README.md:213-315