Service Worker

ServiceWorkerWallet runs the wallet in a service worker. The wallet’s work moves off the page’s main thread, and every open tab shares one wallet.

Quick Setup

ServiceWorkerWallet.setup registers the worker and returns a ready wallet:

// main.ts
import { MnemonicIdentity, ServiceWorkerWallet } from '@arkade-os/sdk'

// Call with the mnemonic from your app's secure storage
export async function openWallet(mnemonic: string) {
  return ServiceWorkerWallet.setup({
    serviceWorkerPath: '/service-worker.js',
    identity: MnemonicIdentity.fromMnemonic(mnemonic),
  })
}

Service Worker Implementation

Create a service worker file. It runs a MessageBus, which stores the wallet’s data in IndexedDB and handles the wallet calls that ServiceWorkerWallet sends from the page. Bundle this file into a single script before you serve it. The SDK registers the service worker as a classic script, and a classic script can’t use import statements.

// src/service-worker.js
import {
  IndexedDBContractRepository,
  IndexedDBWalletRepository,
  MessageBus,
  WalletMessageHandler,
} from '@arkade-os/sdk'

const bus = new MessageBus(
  new IndexedDBWalletRepository(),
  new IndexedDBContractRepository(),
  { messageHandlers: [new WalletMessageHandler()] },
)

bus.start()

For example, bundle it with esbuild:

npx esbuild src/service-worker.js --bundle --outfile=public/service-worker.js

Serve the bundled file at the serviceWorkerPath you pass to ServiceWorkerWallet.setup.

Storage

The service worker wallet stores its data in IndexedDB. The page and the service worker both open the default database, so ServiceWorkerWallet.setup needs no storage option. IndexedDB works in both contexts. localStorage isn’t available in a service worker. For the other repositories, see Storage Repositories.

Renewal in the Service Worker

The service worker runs the wallet’s automatic renewal while it runs. Get its VtxoManager from the wallet:

const vtxoManager = await wallet.getVtxoManager()

The worker runs send, settle, and renewVtxos one at a time, so a user’s send can’t race automatic renewal for the same outputs.

Advanced: Custom Service Worker

To handle your own messages in the service worker, implement the MessageHandler interface. Then add your handler to messageHandlers, next to WalletMessageHandler.

Best Practices

Storage Selection

Keep the default IndexedDB repositories. The browser stops an idle service worker, and in-memory repositories lose the wallet’s data when it stops.

Error Handling

ServiceWorkerWallet.setup and wallet calls throw ServiceWorkerTimeoutError when the service worker doesn’t answer in time:

import { ServiceWorkerWallet, ServiceWorkerTimeoutError } from '@arkade-os/sdk'

try {
  const wallet = await ServiceWorkerWallet.setup({
    serviceWorkerPath: '/service-worker.js',
    identity
  })
} catch (error) {
  if (error instanceof ServiceWorkerTimeoutError) {
    // The service worker didn't answer in time
    console.error('Service worker timeout:', error.message)
  } else {
    console.error('Wallet setup failed:', error)
  }
}

Troubleshooting

Service Worker Not Registering

If the service worker fails to register:

Ensure the service worker file path (serviceWorkerPath) is correct and accessible
Service workers require HTTPS (or localhost for dev)
Check browser console for registration errors
Verify that the service worker script creates a MessageBus and calls bus.start()
Make sure you serve the bundled service worker file, which has no import statements

IndexedDB Errors

If you encounter IndexedDB errors:

Check browser console for specific error messages
If you pass a database name, make sure the page and the service worker use the same name
Clear browser data if the database schema changed

Message Timeout

If you experience message timeouts:

The SDK pings the service worker before every operation and restarts it if it doesn’t answer, so persistent timeouts usually mean a network issue.
Check that the service worker file calls bus.start()
Verify network connectivity
Check for errors in the service worker console
If using custom error handling, check for ServiceWorkerTimeoutError, which means the service worker didn’t answer in time

Getting Started

Payments

Advanced Features

Quick Setup

Service Worker Implementation

Storage

Renewal in the Service Worker

Advanced: Custom Service Worker

Best Practices

Troubleshooting

​Quick Setup

​Service Worker Implementation

​Storage

​Renewal in the Service Worker

​Advanced: Custom Service Worker

​Best Practices

​Troubleshooting

Quick Setup

Service Worker Implementation

Storage

Renewal in the Service Worker

Advanced: Custom Service Worker

Best Practices

Troubleshooting