@ocap/statedb-sqlite 1.29.5

package/README.md

@@ -0,0 +1,66 @@
+# [**@ocap/statedb-sqlite**](https://github.com/arcblock/blockchain)
+
+> OCAP statedb adapter that uses SQLite as backend via [Kysely](https://kysely.dev/)
+
+## Install
+
+```sh
+npm install @ocap/statedb-sqlite
+// or
+bun install @ocap/statedb-sqlite
+```
+
+## Usage
+
+### In-Memory Mode
+
+For testing or ephemeral data:
+
+```js
+const SqliteStateDB = require('@ocap/statedb-sqlite').default;
+
+const statedb = new SqliteStateDB({ filename: ':memory:' });
+await statedb.initialize();
+
+// Use statedb...
+await statedb.account.create('z1abc...', { balance: '1000' });
+
+// Close when done
+await statedb.close();
+```
+
+### File Mode
+
+For persistent storage:
+
+```js
+const SqliteStateDB = require('@ocap/statedb-sqlite').default;
+
+const statedb = new SqliteStateDB({ filename: '/path/to/statedb.sqlite' });
+await statedb.initialize();
+
+// Data persists across restarts
+```
+
+## Features
+
+- WAL mode enabled by default for better concurrent read performance
+- Automatic migrations on initialization
+- Transaction support via `runAsLambda()`
+- All 13 state tables: account, asset, token, factory, stake, delegation, rollup, etc.
+
+## API
+
+### Constructor Options
+
+```typescript
+interface SqliteStateDBOptions {
+  filename: string;  // ':memory:' or file path
+}
+```
+
+### Methods
+
+- `initialize()` - Run migrations and prepare database
+- `close()` - Close database connection
+- `runAsLambda(fn)` - Execute function within a transaction

package/esm/_virtual/rolldown_runtime.mjs

@@ -0,0 +1,21 @@
+import { createRequire } from "node:module";
+
+//#region rolldown:runtime
+var __defProp = Object.defineProperty;
+var __exportAll = (all, symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+//#endregion
+export { __exportAll, __require };

package/esm/db.d.mts

@@ -0,0 +1,92 @@
+import { Database } from "./interfaces.mjs";
+import { SqliteConfig } from "./kysely.mjs";
+import { StateDB } from "@ocap/statedb";
+import { Kysely, Transaction } from "kysely";
+import { IAccountState, IAssetFactoryState, IAssetState, IBalanceTable, IChainState, IDelegateState, IEvidenceState, IRollupBlock, IRollupTable, IStakeState, IStateDB, IStateTable, ITokenFactoryState, ITokenTable, ITxState } from "@ocap/types";
+
+//#region src/db.d.ts
+
+/**
+ * SQLite StateDB Implementation
+ * Uses SQLite via Kysely as the storage backend
+ */
+declare class SqliteStateDB extends StateDB implements IStateDB {
+  name: string;
+  version: string;
+  private db;
+  private config;
+  private initialized;
+  balance: IBalanceTable;
+  account: IStateTable<IAccountState>;
+  factory: IStateTable<IAssetFactoryState>;
+  stake: IStateTable<IStakeState>;
+  asset: IStateTable<IAssetState>;
+  delegation: IStateTable<IDelegateState>;
+  tx: IStateTable<ITxState>;
+  token: ITokenTable;
+  chain: IStateTable<IChainState>;
+  rollup: IRollupTable;
+  rollupBlock: IStateTable<IRollupBlock>;
+  evidence: IStateTable<IEvidenceState>;
+  tokenFactory: IStateTable<ITokenFactoryState>;
+  /**
+   * Creates an instance of SqliteStateDB
+   *
+   * @param config - SQLite configuration (defaults to in-memory)
+   *
+   * @example
+   * ```typescript
+   * // In-memory database for testing
+   * const db = new SqliteStateDB();
+   * await db.initialize();
+   *
+   * // File-based database for production
+   * const db = new SqliteStateDB({ filename: './data/state.sqlite' });
+   * await db.initialize();
+   * ```
+   */
+  constructor(config?: SqliteConfig);
+  /**
+   * Synchronous initialization
+   * Called from constructor for immediate table availability
+   */
+  private initSync;
+  /**
+   * Async initialization - runs migrations
+   * Call this after constructor to ensure database schema is ready
+   */
+  initialize(): Promise<void>;
+  /**
+   * Execute multiple operations within a database transaction
+   * Provides retry logic for SQLite BUSY errors (lock conflicts)
+   *
+   * @param fn - Function receiving Kysely transaction object
+   * @param options - Optional retry configuration
+   * @returns Result of the transaction function
+   *
+   * @example
+   * ```typescript
+   * await db.runAsLambda(async (txn) => {
+   *   await txn.insertInto('account').values({ ... }).execute();
+   *   await txn.updateTable('balance').set({ ... }).execute();
+   * });
+   * ```
+   */
+  runAsLambda<T>(fn: (txn: Transaction<Database>) => T | Promise<T>, options?: {
+    retryLimit?: number;
+  }): Promise<T>;
+  /**
+   * Reset all tables (for testing)
+   */
+  reset(): Promise<void>;
+  /**
+   * Close database connection
+   */
+  close(): Promise<void>;
+  /**
+   * Get the underlying Kysely instance (for advanced operations)
+   */
+  getKysely(): Kysely<Database>;
+}
+//#endregion
+export { SqliteStateDB as default };

package/esm/db.mjs

@@ -0,0 +1,257 @@
+import { createKysely } from "./kysely.mjs";
+import { runMigrations } from "./migrations/index.mjs";
+import base_default from "./table/base.mjs";
+import account_default from "./table/account.mjs";
+import balance_default from "./table/balance.mjs";
+import rollup_default from "./table/rollup.mjs";
+import token_default from "./table/token.mjs";
+import package_default from "./package.mjs";
+import { StateDB } from "@ocap/statedb";
+
+//#region src/db.ts
+const { name, version } = package_default;
+const SQLITE_BUSY_CODES = ["SQLITE_BUSY", "SQLITE_LOCKED"];
+/**
+* SQLite StateDB Implementation
+* Uses SQLite via Kysely as the storage backend
+*/
+var SqliteStateDB = class extends StateDB {
+	/**
+	* Creates an instance of SqliteStateDB
+	*
+	* @param config - SQLite configuration (defaults to in-memory)
+	*
+	* @example
+	* ```typescript
+	* // In-memory database for testing
+	* const db = new SqliteStateDB();
+	* await db.initialize();
+	*
+	* // File-based database for production
+	* const db = new SqliteStateDB({ filename: './data/state.sqlite' });
+	* await db.initialize();
+	* ```
+	*/
+	constructor(config = { filename: ":memory:" }) {
+		super();
+		this.initialized = false;
+		this.name = name;
+		this.version = version;
+		this.config = config;
+		this.initSync();
+	}
+	/**
+	* Synchronous initialization
+	* Called from constructor for immediate table availability
+	*/
+	initSync() {
+		this.db = createKysely(this.config);
+		this.balance = new balance_default({ db: this.db });
+		this.account = new account_default({
+			db: this.db,
+			syncBalance: true,
+			balanceTable: this.balance
+		});
+		this.factory = new base_default({
+			name: "factory",
+			uniqIndex: "address",
+			db: this.db,
+			syncBalance: true,
+			balanceTable: this.balance,
+			schema: { jsonFields: [
+				"trustedIssuers",
+				"tokens",
+				"input",
+				"output",
+				"display",
+				"hooks",
+				"data",
+				"context",
+				"stake"
+			] }
+		});
+		this.stake = new base_default({
+			name: "stake",
+			uniqIndex: "address",
+			db: this.db,
+			syncBalance: true,
+			balanceTable: this.balance,
+			schema: {
+				jsonFields: [
+					"tokens",
+					"assets",
+					"slashers",
+					"revokedTokens",
+					"revokedAssets",
+					"data",
+					"context"
+				],
+				booleanFields: ["revocable"]
+			}
+		});
+		this.asset = new base_default({
+			name: "asset",
+			uniqIndex: "address",
+			db: this.db,
+			schema: {
+				jsonFields: [
+					"endpoint",
+					"display",
+					"tags",
+					"stake",
+					"data",
+					"context"
+				],
+				booleanFields: ["readonly", "transferrable"]
+			}
+		});
+		this.delegation = new base_default({
+			name: "delegation",
+			uniqIndex: "address",
+			db: this.db,
+			schema: {
+				jsonFields: [
+					"ops",
+					"data",
+					"context"
+				],
+				columnMapping: {
+					from: "from_",
+					to: "to_"
+				}
+			}
+		});
+		this.tx = new base_default({
+			name: "tx",
+			uniqIndex: "hash",
+			db: this.db,
+			schema: {
+				jsonFields: [
+					"receipts",
+					"tx",
+					"context"
+				],
+				columnMapping: { index: "index_" },
+				booleanFields: [
+					"receiptsVerified",
+					"finalized",
+					"valid"
+				]
+			}
+		});
+		this.token = new token_default({ db: this.db });
+		this.chain = new base_default({
+			name: "chain",
+			uniqIndex: "address",
+			db: this.db,
+			schema: { jsonFields: [
+				"accounts",
+				"moderator",
+				"token",
+				"transaction",
+				"vaults",
+				"context"
+			] }
+		});
+		this.rollup = new rollup_default({ db: this.db });
+		this.rollupBlock = new base_default({
+			name: "rollupBlock",
+			uniqIndex: "hash",
+			db: this.db,
+			schema: {
+				jsonFields: [
+					"txs",
+					"signatures",
+					"data",
+					"context"
+				],
+				booleanFields: ["governance"]
+			}
+		});
+		this.evidence = new base_default({
+			name: "evidence",
+			uniqIndex: "hash",
+			db: this.db,
+			schema: { jsonFields: ["data", "context"] }
+		});
+		this.tokenFactory = new base_default({
+			name: "tokenFactory",
+			uniqIndex: "address",
+			db: this.db,
+			schema: { jsonFields: [
+				"curve",
+				"input",
+				"output",
+				"data",
+				"context"
+			] }
+		});
+		this.attachReadyListeners();
+	}
+	/**
+	* Async initialization - runs migrations
+	* Call this after constructor to ensure database schema is ready
+	*/
+	async initialize() {
+		if (this.initialized) return;
+		await runMigrations(this.db);
+		this.initialized = true;
+	}
+	/**
+	* Execute multiple operations within a database transaction
+	* Provides retry logic for SQLite BUSY errors (lock conflicts)
+	*
+	* @param fn - Function receiving Kysely transaction object
+	* @param options - Optional retry configuration
+	* @returns Result of the transaction function
+	*
+	* @example
+	* ```typescript
+	* await db.runAsLambda(async (txn) => {
+	*   await txn.insertInto('account').values({ ... }).execute();
+	*   await txn.updateTable('balance').set({ ... }).execute();
+	* });
+	* ```
+	*/
+	async runAsLambda(fn, options = {}) {
+		const { retryLimit = 2 } = options;
+		let lastError;
+		for (let attempt = 0; attempt <= retryLimit; attempt++) try {
+			return await this.db.transaction().execute(async (txn) => {
+				return await fn(txn);
+			});
+		} catch (err) {
+			lastError = err;
+			const code = err?.code;
+			if (!SQLITE_BUSY_CODES.includes(code)) throw err;
+			if (attempt < retryLimit) await new Promise((r) => setTimeout(r, 10 * 2 ** attempt));
+		}
+		throw lastError;
+	}
+	/**
+	* Reset all tables (for testing)
+	*/
+	async reset() {
+		const tables = Object.keys(this.readyMarks);
+		for (const table of tables) {
+			const tableInstance = this[table];
+			if (tableInstance?.reset) await tableInstance.reset();
+		}
+	}
+	/**
+	* Close database connection
+	*/
+	async close() {
+		await this.db.destroy();
+	}
+	/**
+	* Get the underlying Kysely instance (for advanced operations)
+	*/
+	getKysely() {
+		return this.db;
+	}
+};
+var db_default = SqliteStateDB;
+
+//#endregion
+export { db_default as default };

package/esm/index.d.mts

@@ -0,0 +1,4 @@
+import { Database, SqliteOperationContext } from "./interfaces.mjs";
+import { SqliteConfig } from "./kysely.mjs";
+import SqliteStateDB from "./db.mjs";
+export { type Database, type SqliteConfig, type SqliteOperationContext, SqliteStateDB, SqliteStateDB as default };

package/esm/index.mjs

@@ -0,0 +1,7 @@
+import db_default from "./db.mjs";
+
+//#region src/index.ts
+var src_default = db_default;
+
+//#endregion
+export { db_default as SqliteStateDB, src_default as default };

package/esm/interfaces.d.mts

@@ -0,0 +1,201 @@
+import { Transaction } from "kysely";
+import { IOperationContext } from "@ocap/types";
+
+//#region src/interfaces.d.ts
+
+/**
+ * SQLite-specific operation context
+ * Extends base operation context with optional transaction
+ */
+interface SqliteOperationContext extends IOperationContext {
+  txn?: Transaction<Database>;
+}
+/**
+ * Database schema types for Kysely
+ * Each table is defined with its column types
+ */
+interface Database {
+  account: AccountTable;
+  balance: BalanceTable;
+  chain: ChainTable;
+  tx: TxTable;
+  asset: AssetTable;
+  token: TokenTable;
+  factory: FactoryTable;
+  tokenFactory: TokenFactoryTable;
+  stake: StakeTable;
+  delegation: DelegationTable;
+  rollup: RollupTable;
+  rollupBlock: RollupBlockTable;
+  evidence: EvidenceTable;
+}
+interface AccountTable {
+  address: string;
+  balance: string;
+  gasBalance: string | null;
+  moniker: string | null;
+  pk: string | null;
+  nonce: number;
+  numTxs: number;
+  numAssets: number;
+  issuer: string | null;
+  migratedTo: string | null;
+  migratedFrom: string | null;
+  stake: string | null;
+  tokens: string | null;
+  data: string | null;
+  context: string | null;
+  _retrievedAt: string | null;
+}
+interface BalanceTable {
+  address: string;
+  tokenAddress: string;
+  balance: string;
+  context: string | null;
+}
+interface ChainTable {
+  address: string;
+  chainId: string | null;
+  version: string | null;
+  accounts: string | null;
+  moderator: string | null;
+  token: string | null;
+  transaction: string | null;
+  vaults: string | null;
+  context: string | null;
+}
+interface TxTable {
+  hash: string;
+  code: string | null;
+  height: number | null;
+  index_: number | null;
+  receipts: string | null;
+  receiptsVerified: number | null;
+  receiver: string | null;
+  sender: string | null;
+  time: string | null;
+  tx: string | null;
+  type: string | null;
+  finalized: number | null;
+  valid: number | null;
+}
+interface AssetTable {
+  address: string;
+  owner: string | null;
+  moniker: string | null;
+  readonly: number | null;
+  transferrable: number | null;
+  issuer: string | null;
+  parent: string | null;
+  ttl: number | null;
+  consumedTime: string | null;
+  endpoint: string | null;
+  display: string | null;
+  tags: string | null;
+  stake: string | null;
+  data: string | null;
+  context: string | null;
+}
+interface TokenTable {
+  address: string;
+  symbol: string | null;
+  name: string | null;
+  decimal: number | null;
+  unit: string | null;
+  description: string | null;
+  icon: string | null;
+  totalSupply: string | null;
+  initialSupply: string | null;
+  maxTotalSupply: string | null;
+  foreignToken: string | null;
+  issuer: string | null;
+  website: string | null;
+  metadata: string | null;
+  tokenFactoryAddress: string | null;
+  spenders: string | null;
+  minters: string | null;
+  type: string | null;
+  data: string | null;
+  context: string | null;
+}
+interface FactoryTable {
+  address: string;
+  owner: string | null;
+  name: string | null;
+  description: string | null;
+  settlement: string | null;
+  limit: number | null;
+  trustedIssuers: string | null;
+  tokens: string | null;
+  numMinted: number | null;
+  lastSettlement: string | null;
+  input: string | null;
+  output: string | null;
+  display: string | null;
+  hooks: string | null;
+  data: string | null;
+  context: string | null;
+}
+interface TokenFactoryTable {
+  address: string;
+  owner: string | null;
+  name: string | null;
+  description: string | null;
+  moniker: string | null;
+  status: string | null;
+  curve: string | null;
+  input: string | null;
+  output: string | null;
+  data: string | null;
+  context: string | null;
+}
+interface StakeTable {
+  address: string;
+  sender: string | null;
+  receiver: string | null;
+  tokens: string | null;
+  revokedTokens: string | null;
+  message: string | null;
+  data: string | null;
+  context: string | null;
+}
+interface DelegationTable {
+  address: string;
+  from_: string | null;
+  to_: string | null;
+  ops: string | null;
+  data: string | null;
+  context: string | null;
+}
+interface RollupTable {
+  address: string;
+  tokenAddress: string | null;
+  paused: number | null;
+  seedValidators: string | null;
+  validators: string | null;
+  vaultAddress: string | null;
+  blockHash: string | null;
+  issuer: string | null;
+  data: string | null;
+  context: string | null;
+}
+interface RollupBlockTable {
+  hash: string;
+  rollup: string | null;
+  height: number | null;
+  previousHash: string | null;
+  mintedAmount: string | null;
+  burnedAmount: string | null;
+  rewardAmount: string | null;
+  signatures: string | null;
+  data: string | null;
+  context: string | null;
+}
+interface EvidenceTable {
+  hash: string;
+  type: string | null;
+  data: string | null;
+  context: string | null;
+}
+//#endregion
+export { AccountTable, AssetTable, BalanceTable, ChainTable, Database, DelegationTable, EvidenceTable, FactoryTable, RollupBlockTable, RollupTable, SqliteOperationContext, StakeTable, TokenFactoryTable, TokenTable, TxTable };

package/esm/interfaces.mjs

@@ -0,0 +1 @@
+export {  };

package/esm/kysely.d.mts

@@ -0,0 +1,43 @@
+import { Database } from "./interfaces.mjs";
+import { Kysely } from "kysely";
+
+//#region src/kysely.d.ts
+
+/**
+ * SQLite configuration options
+ */
+interface SqliteConfig {
+  /** Database file path. Use ':memory:' for in-memory database */
+  filename: string;
+  /** Open database in readonly mode */
+  readonly?: boolean;
+  /** Throw error if file doesn't exist (default: false, creates new file) */
+  create?: boolean;
+  /** Enable WAL mode (default: true) */
+  walMode?: boolean;
+}
+/**
+ * Create a Kysely instance with SQLite dialect
+ * Automatically uses kysely-bun-sqlite in Bun or better-sqlite3 in Node.js
+ *
+ * @param config - SQLite configuration
+ * @returns Kysely instance configured for the database
+ *
+ * @example
+ * ```typescript
+ * // In-memory database for testing
+ * const db = createKysely({ filename: ':memory:' });
+ *
+ * // File-based database for production
+ * const db = createKysely({ filename: './data/state.sqlite' });
+ * ```
+ */
+declare function createKysely(config: SqliteConfig): Kysely<Database>;
+/**
+ * Get the underlying SQLite database instance from Kysely
+ * Useful for executing raw SQL or pragmas
+ * Returns either bun:sqlite Database or better-sqlite3 Database depending on runtime
+ */
+declare function getRawDatabase(db: Kysely<Database>): any;
+//#endregion
+export { SqliteConfig, createKysely, getRawDatabase };