Service Worker

Service Worker support is a new feature in v0.3. It enables your wallet to run in the background, providing persistent connectivity and event handling.

Overview

Running your wallet in a service worker enables:

Background Processing: Keep your wallet active even when the main application is closed
Persistent Storage: Use IndexedDB for reliable data persistence
Event Handling: Process incoming payments and settlements in the background
Improved UX: Faster response times and better reliability

Quick Setup

The v0.3 SDK provides ultra-simplified service worker setup with automatic registration and identity management:

// main.js
import { ServiceWorkerWallet, SingleKey } from '@arkade-os/sdk'

// Create your identity
const identity = SingleKey.fromHex('your_private_key_hex')
// Or generate a new one:
// const identity = SingleKey.fromRandomBytes()

const wallet = await ServiceWorkerWallet.setup({
  serviceWorkerPath: '/service-worker.js',
  arkServerUrl: 'https://mutinynet.arkade.sh',
  identity
})

// That's it! Ready to use immediately:
const address = await wallet.getAddress()
const balance = await wallet.getBalance()

Service Worker Implementation

Create a service worker file that handles communication:

// service-worker.js
import { Worker } from '@arkade-os/sdk'

// Worker handles communication between the main thread and service worker
new Worker().start()

That’s all you need! The Worker class automatically:

Handles message routing
Manages wallet state
Processes events
Handles cleanup

Example: Storage and Identity Management

Here’s a complete example with storage and identity management:

// main.js
import { ServiceWorkerWallet, SingleKey } from '@arkade-os/sdk'
import { LocalStorageAdapter } from '@arkade-os/sdk/adapters/localStorage'

const storage = new LocalStorageAdapter()

// Load or create identity
let privateKeyHex = await storage.getItem('private-key')
if (!privateKeyHex) {
  const newIdentity = SingleKey.fromRandomBytes()
  privateKeyHex = newIdentity.toHex()
  await storage.setItem('private-key', privateKeyHex)
}

const identity = SingleKey.fromHex(privateKeyHex)

// Setup service worker wallet
const wallet = await ServiceWorkerWallet.setup({
  serviceWorkerPath: '/service-worker.js',
  arkServerUrl: 'https://mutinynet.arkade.sh',
  identity
})

// Use wallet normally
const address = await wallet.getAddress()
console.log('Wallet address:', address)

const balance = await wallet.getBalance()
console.log('Balance:', balance.total)

Using IndexedDB Storage

For service workers, IndexedDB is recommended over LocalStorage:

import { ServiceWorkerWallet, SingleKey } from '@arkade-os/sdk'
import { IndexedDBStorageAdapter } from '@arkade-os/sdk/adapters/indexedDB'

const storage = new IndexedDBStorageAdapter('wallet-db', 1)

let privateKeyHex = await storage.getItem('private-key')
if (!privateKeyHex) {
  const newIdentity = SingleKey.fromRandomBytes()
  privateKeyHex = newIdentity.toHex()
  await storage.setItem('private-key', privateKeyHex)
}

const identity = SingleKey.fromHex(privateKeyHex)

const wallet = await ServiceWorkerWallet.setup({
  serviceWorkerPath: '/service-worker.js',
  arkServerUrl: 'https://mutinynet.arkade.sh',
  identity,
  storage // IndexedDB storage
})

IndexedDB is recommended for service workers because it’s accessible from both the main thread and service worker context, and can store larger amounts of data.

Handling Events

Service workers can process wallet events in the background:

// main.js
import { waitForIncomingFunds } from '@arkade-os/sdk'

// Listen for incoming funds
const incomingFunds = await waitForIncomingFunds(wallet)

if (incomingFunds.type === "vtxo") {
  console.log("VTXOs received:", incomingFunds.vtxos)
  // Show notification or update UI
} else if (incomingFunds.type === "utxo") {
  console.log("UTXOs received:", incomingFunds.coins)
  // Show notification or update UI
}

Advanced: Custom Service Worker

If you need custom service worker logic, you can extend the Worker class:

// service-worker.js
import { Worker } from '@arkade-os/sdk'

class CustomWorker extends Worker {
  async onMessage(event) {
    // Custom message handling
    console.log('Received message:', event.data)

    // Call parent handler
    await super.onMessage(event)
  }

  async onInstall(event) {
    console.log('Service worker installed')
  }

  async onActivate(event) {
    console.log('Service worker activated')
  }
}

new CustomWorker().start()

Best Practices

Storage Selection

Always use IndexedDB for service worker wallets:

// ✅ Good - IndexedDB works in service worker context
const storage = new IndexedDBStorageAdapter('wallet-db', 1)

// ❌ Bad - LocalStorage not available in service workers
const storage = new LocalStorageAdapter()

Identity Management

Store your identity securely and load it on initialization:

const storage = new IndexedDBStorageAdapter('wallet-db', 1)

// Always check if identity exists before creating new one
let privateKeyHex = await storage.getItem('private-key')
if (!privateKeyHex) {
  privateKeyHex = SingleKey.fromRandomBytes().toHex()
  await storage.setItem('private-key', privateKeyHex)
}

Error Handling

Implement proper error handling for service worker operations:

try {
  const wallet = await ServiceWorkerWallet.setup({
    serviceWorkerPath: '/service-worker.js',
    arkServerUrl: 'https://mutinynet.arkade.sh',
    identity
  })
} catch (error) {
  console.error('Failed to setup service worker wallet:', error)
  // Fallback to regular wallet
}

Troubleshooting

Service Worker Not Registering

If you encounter IndexedDB errors:

Check browser console for specific error messages
Ensure the database name and version are consistent
Clear browser data if the database schema changed

IndexedDB Errors

If you encounter IndexedDB errors:

Check browser console for specific error messages
Ensure the database name and version are consistent
Clear browser data if the database schema changed

Message Timeout

If you experience message timeouts:

Check that the Worker is properly started in the service worker
Verify network connectivity
Check for errors in the service worker console

Next Steps

Storage Adapters - Explore different storage options
Expo/React Native - Set up Arkade in React Native applications

Getting Started

Wallet Operations

Advanced Features

Overview

Quick Setup

Service Worker Implementation

Example: Storage and Identity Management

Using IndexedDB Storage

Handling Events

Advanced: Custom Service Worker

Best Practices

Troubleshooting

Next Steps

​Overview

​Quick Setup

​Service Worker Implementation

​Example: Storage and Identity Management

​Using IndexedDB Storage

​Handling Events

​Advanced: Custom Service Worker

​Best Practices

​Troubleshooting

​Next Steps

Overview

Quick Setup

Service Worker Implementation

Example: Storage and Identity Management

Using IndexedDB Storage

Handling Events

Advanced: Custom Service Worker

Best Practices

Troubleshooting

Next Steps