Storage Repositories

Upgrading from SDK 0.4? Read Upgrade Storage to SDK 0.5 first. SDK 0.5 removes the storage adapters, and its IndexedDB upgrade is one way.

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. Only one wallet instance may settle with an intent repository. When the wallet reconciles its requests, it deletes from the operator every pending batch registration that this instance did not submit.

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. Give both repositories the same executor object: the SDK runs one transaction at a time for each executor, and SQLite can’t nest transactions on one connection. 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. In Node.js, also do these two steps, whichever repository you use:

Call configureEventSource before Wallet.create. Node.js has no EventSource by default. Without one, boarding, renewal, and offboarding throw EventSourceUnavailableError. The example gets an EventSource from the eventsource package (pnpm add eventsource).
Call await wallet.dispose() when you are done with the wallet. It stops the wallet’s background work, so the process can exit.

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

// Set the EventSource before you create the wallet
configureEventSource((url) => new EventSource(url))

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),
  },
})

// When you are done with the wallet, stop its background work
await wallet.dispose()

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(),
  },
})

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

Next Steps

​Choose a repository

​IndexedDB

​SQLite

​Table prefix

​Realm

​In-memory

​Next Steps

Choose a repository

IndexedDB

SQLite

Table prefix

Realm

In-memory

Next Steps