Alephium Desktop Wallet

The Alephium Desktop Wallet is the flagship desktop wallet for the Alephium blockchain. It is a security-critical, long-lived product that has been in active development for more than five years and is used daily by thousands of users to manage assets, interact with dApps, and sign transactions safely.

I worked on the wallet as a core frontend engineer, contributing both to product features and to foundational architectural decisions together with my colleague Mikael Vraivre. The project was at its infancy when I joined and over time it evolved from a relatively simple Electron app into a highly modular, performance-sensitive system that balances UX, security, and scalability.

Engineering decisions

Process boundary: Electron main vs renderer

The Electron main process focuses on OS integration (window lifecycle, deep links, updater, native theme) whereas the product logic runs in the React renderer. This is the recommended choice for Electron apps so that UI logic stays web-native and OS privileges are centralized and easier to audit. Only a curated API is exposed via the contextBridge to reduces accidental privilege escalation. It enforces a security boundary with the cost of additional boilerplate code for IPC (Inter-Process Communication) surface design.

Renderer state model: Redux Toolkit + TanStack Query

The app has evolved over the last 5 years. The UI state as well as server-derived data state was initially stored in React.Context while API requests were made using fetch in simple React hooks. This proved to be very limiting regarding performance and reasoning so soon after I joined the team I initiated a project to migrate it to Redux using Redux Toolkit. Redux Toolkit was chosen due to its wide use and available resources and documentation. It turned out to be a success. The async logic was moved into Redux thunks, while the state now lived in Redux slices. Each component could request the data they needed through selectors and avoid lots of the performance issues we had with React.Context.

The current architecture includes Redux for UI state and Tanstack Query for server state. We migrated the server state from Redux to Tanstack Query to benefit from several feature such an async library provides such as a request retry mechanism and caching. This has improved the performance of the app even further. It also disentangled the logic of how and when API requests are fired, something that it was quite challenging to achieve with Redux thunks. On the downside, the developer now has to maintain two mental modals and two debugging interfaces. All read-flows are now declarative through the Tanstack Query hooks, but the write flows remain imperative.

Persistence strategy: localStorage for durable user config, IndexedDB for query cache

Settings and wallet metadata are stored in localStorage to benefit from persistence and synchronicity, whereas the query cache is stored in IndexedDB to overcome the storage size limits of localStorage. This allowed us to achieve simple and dependency-light data persistence. Having a per-wallet query cache enables fast rehydration without re-fetching everything. The challenge with caching has always been cache invalidation. We chose a pragmatic approach to keep the cache between app unlocks, but completely clear it on app updates. This “invalidate-everything” approach is safer than partial migrations, but it sacrifices cached performance after upgrades.

Wallet security posture: decrypt in memory, clear on lock

We decided to treat decrypted secrets as in-memory only, by clearing on lock and on idle. This aligns with desktop thread modal (walk-away/background exposure). It also simplifies UX: The user enters their password to unlock their wallet. For as long as the wallet is unlocked, the user does not need to re-enter their password to sign transactions. When the user locks their wallet (or when the app detects an idle state), the secrets are cleared from memory, and the user needs to re-enter their password to decrypt them. Ideally, the user would need to confirm with their password every time they would have to send a transaction (a feature that can be enabled through the app settings) so that no secrets would need to be kept in-memory. This is a UX/security trade-off.

Address management: metadata-first restore + network-driven discovery

The app persists minimal address metadata (such as index, key type, settings) and it deterministically regenerates addresses on unlock. This creates a small persistent footprint. The drawback is additional computation at unlock to regenerate addresses.

Passphrase-enabled wallets

Address metadata such as the index (used for deterministic regeneration) as well as name and color are stored in persisted storage. This allows for a better UX: the user can tag their addresses so they can identify them easier. It also allows persisting the generated addresses between app unlocks. An exception to this is passphrase-enabled wallets. Those wallets do not store anything in persisted storage. This decision was taken for security reasons in order to achieve plausible deniability: An attacker will have no way of knowing whether you have funds in passphrase-enabled wallets and no way to prove it since there are no evidence in the storage of the app. The cost for this security feature is, once again, UX: Passphrase wallet users need to regenerate their addresses on every unlock, and they cannot persist metadata such as name and color for each address. This is an acceptable trade-off considering that it is an advanced feature.

Challenges & lessons learned

This project has its fair share of challenges and lessons learned. From secrets management in process memory to API rate limiting, throttling and caching, there was and still is a lot to learn from this project. I am planning to write a series of blog posts to cover the challenges and lessons learned.

Early misuse of React Context

Storing API data in React Context led to excessive re-renders. The defined Map object deemed to be not the appropiate data structure to store the remote addresses data, since a new object would be defined for every data change of any address of the wallet, causing components to re-render even though they didn’t have to. The solution was to migrate the data layer to Redux.

Blocking auto-update due to GitHub API rate limiting

The app uses the GitHub API to check for updates. The GitHub API has a rate limit. To avoid it, we would only check for updates once a day, or on every start-up. Due to a mistake in the dependency array of a useEffect hook, however, the app spammed the GitHub API with requests, causing it to temporarily block the app’s auto-update pipeline. It was a painful but formative lesson in how easy it is to overload both the frontend and external services. The solution came with using a proper async library for making API requests instead of a simple hook.

Scaling API usage

As Alephium grew, the naive “poll everything” strategy collapsed:

• Too many endpoints.
• Too many addresses.
• Too many tokens and NFTs.

The solution came in many stages, each of which deserves its own blog post:

• Backend and frontend rate limiting.
• Smarter retry handling.
• Proper caching with TanStack Query.
• A “latest transaction” sentinel query to control when other queries should refresh.
• Limiting background refreshes to the most active addresses.
• Persisting query caches across sessions.

Each step reduced load and improved UX, especially for power users with large wallets.

Startup performance

Persisted caches solved cold-start slowness, but introduced new problems: constantly syncing the cache caused rendering stalls, blocking the UI thread. The final solution was to persist the cache only at well-defined lifecycle points (before quit), rather than continuously.