Merge pull request #321 from arkade-os/node-sqlite-example

Node sqlite example

Author: pietro909

README.md

@@ -707,25 +707,69 @@ class MyWalletRepository implements WalletRepository {
 }
 ```
 
-Note: `IndexedDB*Repository` requires [indexeddbshim](https://github.com/indexeddbshim/indexeddbshim) in Node or other
-**non-browser environments**. It is a dev dependency of the SDK, so you must
-install and initialize it in your app before using the repositories. This
-also applies when you rely on the default storage behavior (no `storage`).
+#### SQLite Repository (Node.js / React Native)
 
-Please see the working example in [examples/node/multiple-wallets.ts](examples/node/multiple-wallets.ts).
+For Node.js or React Native environments, use the SQLite repository with any
+SQLite driver. The SDK accepts a `SQLExecutor` interface — you provide the
+driver, the SDK handles the schema.
+
+See [examples/node/multiple-wallets.ts](examples/node/multiple-wallets.ts) for
+a full working example using `better-sqlite3`.
 
 ```typescript
 import { SingleKey, Wallet } from '@arkade-os/sdk'
-import setGlobalVars from 'indexeddbshim'
+import { SQLiteWalletRepository, SQLiteContractRepository, SQLExecutor } from '@arkade-os/sdk/repositories/sqlite'
+import Database from 'better-sqlite3'
 
-setGlobalVars()
+const db = new Database('my-wallet.sqlite')
+db.pragma('journal_mode = WAL')
 
-const identity = SingleKey.fromHex('your_private_key_hex')
+const executor: SQLExecutor = {
+  run: async (sql, params) => { db.prepare(sql).run(...(params ?? [])) },
+  get: async (sql, params) => db.prepare(sql).get(...(params ?? [])) as any,
+  all: async (sql, params) => db.prepare(sql).all(...(params ?? [])) as any,
+}
 
-// Create wallet with default IndexedDB storage
+const wallet = await Wallet.create({
+  identity: SingleKey.fromHex('your_private_key_hex'),
+  arkServerUrl: 'https://mutinynet.arkade.sh',
+  storage: {
+    walletRepository: new SQLiteWalletRepository(executor),
+    contractRepository: new SQLiteContractRepository(executor),
+  },
+})
+```
+
+#### Realm Repository (React Native)
+
+For React Native apps using Realm, pass your Realm instance directly:
+
+```typescript
+import { RealmWalletRepository, RealmContractRepository, ArkRealmSchemas } from '@arkade-os/sdk/repositories/realm'
+
+const realm = await Realm.open({ schema: [...ArkRealmSchemas, ...yourSchemas] })
 const wallet = await Wallet.create({
   identity,
   arkServerUrl: 'https://mutinynet.arkade.sh',
+  storage: {
+    walletRepository: new RealmWalletRepository(realm),
+    contractRepository: new RealmContractRepository(realm),
+  },
+})
+```
+
+#### IndexedDB Repository (Browser)
+
+In the browser, the SDK defaults to IndexedDB repositories when no `storage`
+is provided:
+
+```typescript
+import { SingleKey, Wallet } from '@arkade-os/sdk'
+
+const wallet = await Wallet.create({
+  identity: SingleKey.fromHex('your_private_key_hex'),
+  arkServerUrl: 'https://mutinynet.arkade.sh',
+  // Uses IndexedDB by default in the browser
 })
 ```
 
@@ -813,26 +857,31 @@ Both ExpoArkProvider and ExpoIndexerProvider are available as adapters following
 - **ExpoArkProvider**: Handles settlement events and transaction streaming using expo/fetch for Server-Sent Events
 - **ExpoIndexerProvider**: Handles address subscriptions and VTXO updates using expo/fetch for JSON streaming
 
-To use IndexedDB repositories in Expo/React Native, call `setupExpoDb()` before any SDK import.
-This sets up `indexeddbshim` backed by expo-sqlite under the hood:
+For persistence in Expo/React Native, use the SQLite repository with `expo-sqlite`:
 
 ```typescript
-import { setupExpoDb } from '@arkade-os/sdk/adapters/expo-db';
+import { SQLiteWalletRepository, SQLiteContractRepository } from '@arkade-os/sdk/repositories/sqlite'
+import * as SQLite from 'expo-sqlite'
+
+const db = SQLite.openDatabaseSync('my-wallet.db')
+const executor = {
+  run: (sql, params) => db.runAsync(sql, params ?? []),
+  get: (sql, params) => db.getFirstAsync(sql, params ?? []),
+  all: (sql, params) => db.getAllAsync(sql, params ?? []),
+}
 
-setupExpoDb();
+const wallet = await Wallet.create({
+  identity,
+  arkServerUrl: 'https://mutinynet.arkade.sh',
+  arkProvider: new ExpoArkProvider('https://mutinynet.arkade.sh'),
+  indexerProvider: new ExpoIndexerProvider('https://mutinynet.arkade.sh'),
+  storage: {
+    walletRepository: new SQLiteWalletRepository(executor),
+    contractRepository: new SQLiteContractRepository(executor),
+  },
+})
 ```
 
-> **Note:** `setupExpoDb` accepts an optional `SetupExpoDbOptions` object to
-> customise `origin`, `checkOrigin`, and `cacheDatabaseInstances`.
-
-> **Note:** `expo-sqlite` and `indexeddbshim` are optional peer dependencies,
-> only required when importing from `@arkade-os/sdk/adapters/expo-db`. The
-> streaming providers (`@arkade-os/sdk/adapters/expo`) have no expo-sqlite
-> dependency. Install them with:
-> ```bash
-> npx expo install expo-sqlite && npm install indexeddbshim
-> ```
-
 #### Crypto Polyfill Requirement
 
 Install `expo-crypto` and polyfill `crypto.getRandomValues()` at the top of your app entry point:

examples/node/multiple-wallets.ts

@@ -1,53 +1,61 @@
 /**
- * This example shows how to create two wallets using the SDK and onboard
- * Alice's wallet into the Ark protocol.
+ * This example shows how to create two wallets using the SDK.
+ * Alice's wallet will be persisted in SQLite, while Bob's wallet will be in-memory.
  *
- * It demonstrates:
- * - Creating in-memory and IndexedDB-backed wallets
- * - Funding a boarding address via nigiri faucet
- * - Settling (onboarding) into the Ark protocol using Ramps
- *
- * Requires a local regtest environment (nigiri + Ark server on localhost:7070).
+ * By inspecting the `alice-wallet.sqlite` file created upon running the code,
+ * you can see the persisted data for Alice's wallet.
  *
  * To run it:
  * ```
  * $ npx tsx examples/node/multiple-wallets.ts
  * ```
+ *
+ * Requires `better-sqlite3` (included as a devDependency).
  */
 
 import {
-    IndexedDBContractRepository,
-    IndexedDBWalletRepository,
     InMemoryContractRepository,
     InMemoryWalletRepository,
-    Ramps,
     SingleKey,
     Wallet,
+    Ramps,
 } from "../../src";
+import { WalletState } from "../../src/repositories";
+import {
+    SQLiteWalletRepository,
+    SQLiteContractRepository,
+    SQLExecutor,
+} from "../../src/repositories/sqlite";
+import Database from "better-sqlite3";
+import { execSync } from "child_process";
 
 // EventSource is used internally by the SDK for settlement events (SSE).
 // It is not available in Node.js by default, so we need to polyfill it.
 import { EventSource } from "eventsource";
 (globalThis as any).EventSource = EventSource;
 
-// Must define `self` BEFORE calling setGlobalVars
-if (typeof self === "undefined") {
-    (globalThis as any).self = globalThis;
-}
-import setGlobalVars from "indexeddbshim/src/node-UnicodeIdentifiers";
-import { execSync } from "child_process";
-
-(globalThis as any).window = globalThis;
+function createSQLExecutor(dbPath: string): SQLExecutor {
+    const db = new Database(dbPath);
+    db.pragma("journal_mode = WAL");
 
-setGlobalVars(null, { checkOrigin: false });
+    return {
+        run: async (sql, params) => {
+            db.prepare(sql).run(...(params ?? []));
+        },
+        get: async <T>(sql: string, params?: unknown[]) =>
+            db.prepare(sql).get(...(params ?? [])) as T | undefined,
+        all: async <T>(sql: string, params?: unknown[]) =>
+            db.prepare(sql).all(...(params ?? [])) as T[],
+    };
+}
 
 async function main() {
     console.log("Starting Ark SDK NodeJS Example...");
 
     const bob = SingleKey.fromRandomBytes();
     const alice = SingleKey.fromRandomBytes();
 
-    // in-memory wallet
+    // In-memory wallet
     const bobWallet = await Wallet.create({
         identity: bob,
         arkServerUrl: "http://localhost:7070",
@@ -61,20 +69,30 @@ async function main() {
     console.log("[Bob]\tWallet created successfully!");
     console.log("[Bob]\tArk Address:", bobWallet.arkAddress.encode());
 
-    // IndexedDB-backed wallet (persisted)
+    // SQLite-persisted wallet
+    const executor = createSQLExecutor("alice-wallet.sqlite");
+
     const aliceWallet = await Wallet.create({
         identity: alice,
         arkServerUrl: "http://localhost:7070",
         esploraUrl: "http://localhost:3000",
         storage: {
-            walletRepository: new IndexedDBWalletRepository(),
-            contractRepository: new IndexedDBContractRepository(),
+            walletRepository: new SQLiteWalletRepository(executor),
+            contractRepository: new SQLiteContractRepository(executor),
         },
     });
 
     console.log("[Alice]\tWallet created successfully!");
     console.log("[Alice]\tArk Address:", aliceWallet.arkAddress.encode());
 
+    const state: WalletState = {
+        lastSyncTime: Date.now(),
+        settings: { theme: "dark" },
+    };
+
+    await aliceWallet.walletRepository.saveWalletState(state);
+    await bobWallet.walletRepository.saveWalletState(state);
+
     // Fund Alice's boarding address
     const boardingAddress = await aliceWallet.getBoardingAddress();
     console.log("[Alice]\tBoarding Address:", boardingAddress);
@@ -110,7 +128,7 @@ async function main() {
 
     console.log("[Alice]\tBalance:", await aliceWallet.getBalance());
     console.log("[Bob]\tBalance:", await bobWallet.getBalance());
-    console.log("Only Alice's data is persisted in IndexedDB");
+    console.log("Only Alice's data is persisted on disk");
 }
 
 main().catch(console.error);

package.json

@@ -126,8 +126,10 @@
         "bip68": "1.0.4"
     },
     "devDependencies": {
+        "@types/better-sqlite3": "7.6.13",
         "@types/node": "24.3.1",
         "@vitest/coverage-v8": "3.2.4",
+        "better-sqlite3": "12.6.2",
         "esbuild": "^0.27.3",
         "eventsource": "4.0.0",
         "glob": "11.1.0",
@@ -140,11 +142,11 @@
         "vitest": "3.2.4"
     },
     "peerDependencies": {
+        "@react-native-async-storage/async-storage": ">=1.0.0",
         "expo": ">=54.0.0",
-        "expo-sqlite": "~16.0.10",
         "expo-background-task": "~1.0.10",
-        "expo-task-manager": "~14.0.9",
-        "@react-native-async-storage/async-storage": ">=1.0.0"
+        "expo-sqlite": "~16.0.10",
+        "expo-task-manager": "~14.0.9"
     },
     "peerDependenciesMeta": {
         "expo": {
@@ -186,7 +188,8 @@
         },
         "onlyBuiltDependencies": [
             "canvas",
-            "sqlite3"
+            "sqlite3",
+            "better-sqlite3"
         ]
     }
 }