Storage Repositories

The wallet stores its data in two repositories:

The wallet repository stores virtual outputs, onchain outputs, transaction history, and wallet settings.
The contract repository stores the contracts that the wallet watches.

Pass both repositories to Wallet.create in the storage option. If you omit storage, the wallet uses IndexedDB. Node.js and React Native don’t provide IndexedDB, so pass storage there.

Repositories don’t store the wallet identity. Keep the mnemonic or seed in your platform’s secure storage.

Choose a repository

Repository	Environment	Import from
IndexedDB	Browsers and service workers (the default)	`@arkade-os/sdk`
SQLite	Node.js and React Native, with any SQLite driver	`@arkade-os/sdk/repositories/sqlite`
Realm	React Native apps that use Realm	`@arkade-os/sdk/repositories/realm`
In-memory	Tests and short-lived scripts	`@arkade-os/sdk`

The examples on this page assume that you set up identity and the providers as in Create your Wallet, or as in Expo/React Native for React Native apps. storage also accepts intentRepository, which tracks your batch registration requests, and virtualTxRepository. Both are optional and experimental.

IndexedDB

The IndexedDB repositories use a database named arkade-service-worker by default. To use a different database, pass its name to each repository:

import {
  IndexedDBContractRepository,
  IndexedDBWalletRepository,
  Wallet,
} from '@arkade-os/sdk'

const wallet = await Wallet.create({
  identity,
  arkProvider,
  storage: {
    walletRepository: new IndexedDBWalletRepository('my-app'),
    contractRepository: new IndexedDBContractRepository('my-app'),
  },
})

SQLite

The SQLite repositories work with any SQLite driver. You connect your driver through a SQLExecutor: an object with three async methods, run, get, and all. The SDK creates its tables on first use. You own the database connection, and the SDK never closes it. The Node.js example uses the built-in node:sqlite module, which is stable from Node.js 22.13.0. The Expo example uses expo-sqlite.

import { Wallet } from '@arkade-os/sdk'
import {
  SQLiteContractRepository,
  SQLiteWalletRepository,
  type SQLExecutor,
} from '@arkade-os/sdk/repositories/sqlite'
import { DatabaseSync, type SQLInputValue } from 'node:sqlite'

const db = new DatabaseSync('wallet.sqlite')
db.exec('PRAGMA journal_mode = WAL')
const bind = (params?: unknown[]) => (params ?? []) as SQLInputValue[]

const executor: SQLExecutor = {
  run: async (sql, params) => { db.prepare(sql).run(...bind(params)) },
  get: async (sql, params) => db.prepare(sql).get(...bind(params)) as any,
  all: async (sql, params) => db.prepare(sql).all(...bind(params)) as any,
}

const wallet = await Wallet.create({
  identity,
  arkProvider,
  storage: {
    walletRepository: new SQLiteWalletRepository(executor),
    contractRepository: new SQLiteContractRepository(executor),
  },
})

import { Wallet } from '@arkade-os/sdk'
import {
  SQLiteContractRepository,
  SQLiteWalletRepository,
  type SQLExecutor,
} from '@arkade-os/sdk/repositories/sqlite'
import * as SQLite from 'expo-sqlite'

const db = SQLite.openDatabaseSync('wallet.db')
const bind = (params?: unknown[]) => (params ?? []) as SQLite.SQLiteBindValue[]

const executor: SQLExecutor = {
  run: async (sql, params) => { await db.runAsync(sql, bind(params)) },
  get: async (sql, params) => (await db.getFirstAsync(sql, bind(params))) ?? undefined,
  all: (sql, params) => db.getAllAsync(sql, bind(params)),
}

const wallet = await Wallet.create({
  identity,
  arkProvider,
  indexerProvider,
  storage: {
    walletRepository: new SQLiteWalletRepository(executor),
    contractRepository: new SQLiteContractRepository(executor),
  },
})

Table prefix

The SQLite repositories add the prefix ark_ to every table name. To keep more than one wallet in the same database, give each wallet its own prefix. A prefix can contain only letters, digits, and underscores, and it can’t start with a digit.

const storage = {
  walletRepository: new SQLiteWalletRepository(executor, { prefix: 'alice_' }),
  contractRepository: new SQLiteContractRepository(executor, { prefix: 'alice_' }),
}

Realm

The Realm repositories take an open Realm instance. When you open the Realm:

Add ArkRealmSchemas to the schema list.
Set schemaVersion to ARK_REALM_SCHEMA_VERSION or higher.
Call runArkRealmMigrations in onMigration.

import { Wallet } from '@arkade-os/sdk'
import {
  ARK_REALM_SCHEMA_VERSION,
  ArkRealmSchemas,
  RealmContractRepository,
  RealmWalletRepository,
  runArkRealmMigrations,
} from '@arkade-os/sdk/repositories/realm'
import Realm from 'realm'

const realm = await Realm.open({
  schema: [...ArkRealmSchemas, ...yourSchemas],
  schemaVersion: Math.max(ARK_REALM_SCHEMA_VERSION, yourSchemaVersion),
  onMigration: (oldRealm, newRealm) => {
    runArkRealmMigrations(oldRealm, newRealm)
    // Your own migrations
  },
})

const wallet = await Wallet.create({
  identity,
  arkProvider,
  indexerProvider,
  storage: {
    walletRepository: new RealmWalletRepository(realm),
    contractRepository: new RealmContractRepository(realm),
  },
})

In-memory

The in-memory repositories keep data only in memory. The data is lost when the process exits. Use them for tests and short-lived scripts.

import {
  InMemoryContractRepository,
  InMemoryWalletRepository,
  Wallet,
} from '@arkade-os/sdk'

const wallet = await Wallet.create({
  identity,
  arkProvider,
  storage: {
    walletRepository: new InMemoryWalletRepository(),
    contractRepository: new InMemoryContractRepository(),
  },
})

Migrate from storage adapters

SDK 0.4 deprecates the storage adapters, and SDK 0.5 removes them. Move to repositories before you upgrade to 0.5.

Replace each storage adapter with a repository:

Storage adapter	Repository
`LocalStorageAdapter`	IndexedDB
`IndexedDBStorageAdapter`	IndexedDB
`AsyncStorageAdapter`	SQLite with `expo-sqlite`, or Realm
`FileSystemStorageAdapter`	SQLite
`InMemoryStorageAdapter`	In-memory

To keep the data that an adapter stored, copy it to the new wallet repository with migrateWalletRepository. Give it the addresses to copy: boarding addresses in onchain, and Arkade addresses in offchain. The function does nothing if there is no data to migrate or if the migration is already done. It never deletes the old data.

import {
  IndexedDBWalletRepository,
  migrateWalletRepository,
  rollbackMigration,
} from '@arkade-os/sdk'
import { IndexedDBStorageAdapter } from '@arkade-os/sdk/adapters/indexedDB'

// The database name and version that your app gave the adapter
const oldStorage = new IndexedDBStorageAdapter('legacy-wallet', 1)
const walletRepository = new IndexedDBWalletRepository('my-app')

try {
  await migrateWalletRepository(oldStorage, walletRepository, {
    onchain: [boardingAddress],
    offchain: [arkadeAddress],
  })
} catch (err) {
  // Clear the migration flag, so that the next attempt starts again
  await rollbackMigration('wallet', oldStorage)
  throw err
}

migrateWalletRepository copies wallet data only. Packages that store their own contract data supply their own migration, for example migrateToSwapRepository in @arkade-os/boltz-swap.

Next Steps

Service Worker - Run your wallet in a background service worker
Expo/React Native - Set up Arkade in React Native applications

Getting Started

Payments

Advanced Features

Choose a repository

IndexedDB

SQLite

Table prefix

Realm

In-memory

Migrate from storage adapters

Next Steps

​Choose a repository

​IndexedDB

​SQLite

​Table prefix

​Realm

​In-memory

​Migrate from storage adapters

​Next Steps

Choose a repository

IndexedDB

SQLite

Table prefix

Realm

In-memory

Migrate from storage adapters

Next Steps