@ocap/statedb-sqlite 1.29.5

package/esm/kysely.mjs

@@ -0,0 +1,62 @@
+import { __require } from "./_virtual/rolldown_runtime.mjs";
+import { Kysely, SqliteDialect } from "kysely";
+
+//#region src/kysely.ts
+function isBunRuntime() {
+	return typeof globalThis.Bun !== "undefined";
+}
+/**
+* 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' });
+* ```
+*/
+function createKysely(config) {
+	if (isBunRuntime()) {
+		const { BunSqliteDialect } = import.meta.require("kysely-bun-sqlite");
+		const { Database: BunDatabase } = import.meta.require("bun:sqlite");
+		const sqlite$1 = new BunDatabase(config.filename, {
+			create: config.create !== false,
+			readonly: config.readonly === true
+		});
+		if (config.walMode !== false && !config.readonly && config.filename !== ":memory:") {
+			sqlite$1.exec("PRAGMA journal_mode = WAL");
+			sqlite$1.exec("PRAGMA synchronous = NORMAL");
+		}
+		sqlite$1.exec("PRAGMA foreign_keys = ON");
+		sqlite$1.exec("PRAGMA busy_timeout = 5000");
+		return new Kysely({ dialect: new BunSqliteDialect({ database: sqlite$1 }) });
+	}
+	const sqlite = new (__require("better-sqlite3"))(config.filename, {
+		readonly: config.readonly === true,
+		fileMustExist: config.create === false
+	});
+	if (config.walMode !== false && !config.readonly && config.filename !== ":memory:") {
+		sqlite.pragma("journal_mode = WAL");
+		sqlite.pragma("synchronous = NORMAL");
+	}
+	sqlite.pragma("foreign_keys = ON");
+	sqlite.pragma("busy_timeout = 5000");
+	return new Kysely({ dialect: new SqliteDialect({ database: sqlite }) });
+}
+/**
+* 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
+*/
+function getRawDatabase(db) {
+	return db.getExecutor().adapter.db;
+}
+
+//#endregion
+export { createKysely, getRawDatabase };

package/esm/migrations/001-genesis.d.mts

@@ -0,0 +1,14 @@
+import { Kysely } from "kysely";
+
+//#region src/migrations/001-genesis.d.ts
+
+/**
+ * Genesis migration - creates all StateDB tables
+ */
+declare function up(db: Kysely<unknown>): Promise<void>;
+/**
+ * Rollback migration - drops all tables
+ */
+declare function down(db: Kysely<unknown>): Promise<void>;
+//#endregion
+export { down, up };

package/esm/migrations/001-genesis.mjs

@@ -0,0 +1,52 @@
+import { __exportAll } from "../_virtual/rolldown_runtime.mjs";
+import { sql } from "kysely";
+
+//#region src/migrations/001-genesis.ts
+var _001_genesis_exports = /* @__PURE__ */ __exportAll({
+	down: () => down,
+	up: () => up
+});
+/**
+* Genesis migration - creates all StateDB tables
+*/
+async function up(db) {
+	await db.schema.createTable("account").ifNotExists().addColumn("address", "text", (col) => col.primaryKey()).addColumn("balance", "text", (col) => col.notNull().defaultTo("0")).addColumn("gasBalance", "text", (col) => col.defaultTo("0")).addColumn("moniker", "text").addColumn("pk", "text").addColumn("nonce", "integer", (col) => col.defaultTo(0)).addColumn("numTxs", "integer", (col) => col.defaultTo(0)).addColumn("numAssets", "integer", (col) => col.defaultTo(0)).addColumn("issuer", "text").addColumn("migratedTo", "text").addColumn("migratedFrom", "text").addColumn("stake", "text").addColumn("tokens", "text").addColumn("data", "text").addColumn("context", "text").addColumn("poke", "text").addColumn("_retrievedAt", "text").execute();
+	await db.schema.createTable("balance").ifNotExists().addColumn("address", "text", (col) => col.notNull()).addColumn("tokenAddress", "text", (col) => col.notNull()).addColumn("balance", "text", (col) => col.notNull().defaultTo("0")).addColumn("context", "text").addPrimaryKeyConstraint("balance_pk", ["address", "tokenAddress"]).execute();
+	await db.schema.createTable("chain").ifNotExists().addColumn("address", "text", (col) => col.primaryKey()).addColumn("chainId", "text").addColumn("version", "text").addColumn("accounts", "text").addColumn("moderator", "text").addColumn("token", "text").addColumn("transaction", "text").addColumn("vaults", "text").addColumn("context", "text").execute();
+	await db.schema.createTable("tx").ifNotExists().addColumn("hash", "text", (col) => col.primaryKey()).addColumn("code", "text").addColumn("height", "integer").addColumn("index_", "integer").addColumn("receipts", "text").addColumn("receiptsVerified", "integer").addColumn("receiver", "text").addColumn("sender", "text").addColumn("time", "text").addColumn("tx", "text").addColumn("type", "text").addColumn("finalized", "integer").addColumn("valid", "integer").execute();
+	await db.schema.createTable("asset").ifNotExists().addColumn("address", "text", (col) => col.primaryKey()).addColumn("owner", "text").addColumn("moniker", "text").addColumn("readonly", "integer").addColumn("transferrable", "integer").addColumn("issuer", "text").addColumn("parent", "text").addColumn("ttl", "integer").addColumn("consumedTime", "text").addColumn("endpoint", "text").addColumn("display", "text").addColumn("tags", "text").addColumn("stake", "text").addColumn("data", "text").addColumn("context", "text").execute();
+	await db.schema.createTable("token").ifNotExists().addColumn("address", "text", (col) => col.primaryKey()).addColumn("symbol", "text").addColumn("name", "text").addColumn("decimal", "integer").addColumn("unit", "text").addColumn("description", "text").addColumn("icon", "text").addColumn("totalSupply", "text").addColumn("initialSupply", "text").addColumn("maxTotalSupply", "text").addColumn("foreignToken", "text").addColumn("issuer", "text").addColumn("website", "text").addColumn("metadata", "text").addColumn("tokenFactoryAddress", "text").addColumn("spenders", "text").addColumn("minters", "text").addColumn("type", "text").addColumn("data", "text").addColumn("context", "text").execute();
+	await sql`CREATE UNIQUE INDEX IF NOT EXISTS idx_token_symbol ON token(symbol) WHERE symbol IS NOT NULL`.execute(db);
+	await db.schema.createTable("factory").ifNotExists().addColumn("address", "text", (col) => col.primaryKey()).addColumn("owner", "text").addColumn("name", "text").addColumn("description", "text").addColumn("settlement", "text").addColumn("limit", "integer").addColumn("trustedIssuers", "text").addColumn("tokens", "text").addColumn("numMinted", "integer").addColumn("lastSettlement", "text").addColumn("input", "text").addColumn("output", "text").addColumn("display", "text").addColumn("hooks", "text").addColumn("data", "text").addColumn("context", "text").addColumn("balance", "text").addColumn("stake", "text").execute();
+	await db.schema.createTable("tokenFactory").ifNotExists().addColumn("address", "text", (col) => col.primaryKey()).addColumn("owner", "text").addColumn("name", "text").addColumn("description", "text").addColumn("moniker", "text").addColumn("tokenAddress", "text").addColumn("reserveAddress", "text").addColumn("currentSupply", "text").addColumn("reserveBalance", "text").addColumn("feeRate", "integer").addColumn("status", "text").addColumn("curve", "text").addColumn("input", "text").addColumn("output", "text").addColumn("data", "text").addColumn("context", "text").execute();
+	await db.schema.createTable("stake").ifNotExists().addColumn("address", "text", (col) => col.primaryKey()).addColumn("sender", "text").addColumn("receiver", "text").addColumn("tokens", "text").addColumn("assets", "text").addColumn("slashers", "text").addColumn("revocable", "integer").addColumn("message", "text").addColumn("revokeWaitingPeriod", "integer").addColumn("revokedTokens", "text").addColumn("revokedAssets", "text").addColumn("nonce", "text").addColumn("data", "text").addColumn("context", "text").execute();
+	await db.schema.createTable("delegation").ifNotExists().addColumn("address", "text", (col) => col.primaryKey()).addColumn("from_", "text").addColumn("to_", "text").addColumn("ops", "text").addColumn("data", "text").addColumn("context", "text").execute();
+	await db.schema.createTable("rollup").ifNotExists().addColumn("address", "text", (col) => col.primaryKey()).addColumn("tokenAddress", "text").addColumn("vaultAddress", "text").addColumn("contractAddress", "text").addColumn("paused", "integer").addColumn("closed", "integer").addColumn("seedValidators", "text").addColumn("validators", "text").addColumn("minStakeAmount", "text").addColumn("maxStakeAmount", "text").addColumn("minSignerCount", "integer").addColumn("maxSignerCount", "integer").addColumn("minBlockSize", "integer").addColumn("maxBlockSize", "integer").addColumn("minBlockInterval", "integer").addColumn("minBlockConfirmation", "integer").addColumn("minDepositAmount", "text").addColumn("maxDepositAmount", "text").addColumn("minWithdrawAmount", "text").addColumn("maxWithdrawAmount", "text").addColumn("depositFeeRate", "integer").addColumn("withdrawFeeRate", "integer").addColumn("proposerFeeShare", "integer").addColumn("publisherFeeShare", "integer").addColumn("minDepositFee", "text").addColumn("maxDepositFee", "text").addColumn("minWithdrawFee", "text").addColumn("maxWithdrawFee", "text").addColumn("issuer", "text").addColumn("blockHeight", "integer").addColumn("blockHash", "text").addColumn("leaveWaitingPeriod", "integer").addColumn("publishWaitingPeriod", "integer").addColumn("publishSlashRate", "integer").addColumn("revokeWaitingPeriod", "integer").addColumn("erc20TokenAddress", "text").addColumn("foreignChainId", "text").addColumn("foreignChainType", "text").addColumn("migrateHistory", "text").addColumn("vaultHistory", "text").addColumn("data", "text").addColumn("context", "text").execute();
+	await sql`DROP INDEX IF EXISTS idx_rollup_token`.execute(db);
+	await sql`CREATE INDEX IF NOT EXISTS idx_rollup_token ON rollup(tokenAddress) WHERE tokenAddress IS NOT NULL`.execute(db);
+	await db.schema.createTable("rollupBlock").ifNotExists().addColumn("hash", "text", (col) => col.primaryKey()).addColumn("rollup", "text").addColumn("height", "integer").addColumn("merkleRoot", "text").addColumn("previousHash", "text").addColumn("txsHash", "text").addColumn("txs", "text").addColumn("proposer", "text").addColumn("mintedAmount", "text").addColumn("burnedAmount", "text").addColumn("rewardAmount", "text").addColumn("minReward", "text").addColumn("blockReward", "text").addColumn("governance", "integer").addColumn("checkpoint", "text").addColumn("txHash", "text").addColumn("signatures", "text").addColumn("data", "text").addColumn("context", "text").execute();
+	await db.schema.createTable("evidence").ifNotExists().addColumn("hash", "text", (col) => col.primaryKey()).addColumn("type", "text").addColumn("data", "text").addColumn("context", "text").execute();
+}
+/**
+* Rollback migration - drops all tables
+*/
+async function down(db) {
+	for (const table of [
+		"evidence",
+		"rollupBlock",
+		"rollup",
+		"delegation",
+		"stake",
+		"tokenFactory",
+		"factory",
+		"token",
+		"asset",
+		"tx",
+		"chain",
+		"balance",
+		"account"
+	]) await db.schema.dropTable(table).ifExists().execute();
+}
+
+//#endregion
+export { _001_genesis_exports, down, up };

package/esm/migrations/index.d.mts

@@ -0,0 +1,24 @@
+import { Kysely } from "kysely";
+
+//#region src/migrations/index.d.ts
+
+/**
+ * Run all pending migrations
+ *
+ * @param db - Kysely database instance
+ * @throws Error if any migration fails
+ *
+ * @example
+ * ```typescript
+ * const db = createKysely({ filename: ':memory:' });
+ * await runMigrations(db);
+ * ```
+ */
+declare function runMigrations(db: Kysely<unknown>): Promise<void>;
+/**
+ * Roll back all migrations
+ * WARNING: This will drop all tables and data
+ */
+declare function rollbackMigrations(db: Kysely<unknown>): Promise<void>;
+//#endregion
+export { rollbackMigrations, runMigrations };

package/esm/migrations/index.mjs

@@ -0,0 +1,60 @@
+import { _001_genesis_exports } from "./001-genesis.mjs";
+import { Migrator } from "kysely";
+
+//#region src/migrations/index.ts
+/**
+* In-memory migration provider
+* Provides migrations directly without filesystem access
+*/
+var InMemoryMigrationProvider = class {
+	constructor(migrations) {
+		this.migrations = migrations;
+	}
+	async getMigrations() {
+		return this.migrations;
+	}
+};
+/**
+* Run all pending migrations
+*
+* @param db - Kysely database instance
+* @throws Error if any migration fails
+*
+* @example
+* ```typescript
+* const db = createKysely({ filename: ':memory:' });
+* await runMigrations(db);
+* ```
+*/
+async function runMigrations(db) {
+	const { error, results } = await new Migrator({
+		db,
+		provider: new InMemoryMigrationProvider({ "001-genesis": _001_genesis_exports })
+	}).migrateToLatest();
+	results?.forEach((it) => {
+		if (it.status === "Success") {} else if (it.status === "Error") console.error(`Migration "${it.migrationName}" failed`);
+	});
+	if (error) {
+		console.error("Migration failed:", error);
+		throw error;
+	}
+}
+/**
+* Roll back all migrations
+* WARNING: This will drop all tables and data
+*/
+async function rollbackMigrations(db) {
+	const migrator = new Migrator({
+		db,
+		provider: new InMemoryMigrationProvider({ "001-genesis": _001_genesis_exports })
+	});
+	let hasMore = true;
+	while (hasMore) {
+		const { error, results } = await migrator.migrateDown();
+		if (error) throw error;
+		hasMore = results !== void 0 && results.length > 0;
+	}
+}
+
+//#endregion
+export { rollbackMigrations, runMigrations };

package/esm/package.mjs

@@ -0,0 +1,70 @@
+//#region package.json
+var package_default = {
+	name: "@ocap/statedb-sqlite",
+	description: "OCAP statedb adapter that uses SQLite as backend",
+	version: "1.0.0",
+	author: "wangshijun <shijun@arcblock.io> (https://www.arcblock.io)",
+	bugs: {
+		"url": "https://github.com/ArcBlock/blockchain/issues",
+		"email": "shijun@arcblock.io"
+	},
+	publishConfig: { "access": "public" },
+	contributors: ["wangshijun <shijun@arcblock.io> (https://www.arcblock.io)"],
+	devDependencies: { "@ocap/statedb-test": "workspace:*" },
+	homepage: "https://github.com/ArcBlock/blockchain/tree/master/statedb/sqlite",
+	keywords: [
+		"ocap",
+		"statedb",
+		"sqlite",
+		"kysely"
+	],
+	license: "Apache-2.0",
+	type: "module",
+	main: "./lib/index.cjs",
+	module: "./esm/index.mjs",
+	types: "./esm/index.d.mts",
+	exports: {
+		".": {
+			"types": "./esm/index.d.mts",
+			"import": "./esm/index.mjs",
+			"default": "./lib/index.cjs"
+		},
+		"./lib/*.js": {
+			"types": "./esm/*.d.mts",
+			"import": "./esm/*.mjs",
+			"default": "./lib/*.cjs"
+		},
+		"./lib/*": {
+			"types": "./esm/*.d.mts",
+			"import": "./esm/*.mjs",
+			"default": "./lib/*.cjs"
+		}
+	},
+	files: ["lib", "esm"],
+	repository: {
+		"type": "git",
+		"url": "https://github.com/ArcBlock/blockchain/tree/master/statedb/sqlite"
+	},
+	scripts: {
+		"build": "tsdown",
+		"prebuild": "rm -rf lib esm",
+		"lint": "biome check",
+		"lint:fix": "biome check --write",
+		"test": "bun test",
+		"coverage": "npm run test -- --coverage"
+	},
+	dependencies: {
+		"@ocap/state": "workspace:*",
+		"@ocap/statedb": "workspace:*",
+		"@ocap/types": "workspace:*",
+		"@ocap/util": "workspace:*",
+		"debug": "^4.4.3",
+		"better-sqlite3": "^11.8.1",
+		"kysely": "^0.27.0",
+		"kysely-bun-sqlite": "^0.4.0",
+		"lodash": "^4.17.23"
+	}
+};
+
+//#endregion
+export { package_default as default };

package/esm/table/account.d.mts

@@ -0,0 +1,40 @@
+import SqliteTable, { SqliteTableConfig } from "./base.mjs";
+import { IAccountState, IOperationContext } from "@ocap/types";
+
+//#region src/table/account.d.ts
+interface AccountOperationContext extends IOperationContext {
+  traceMigration?: boolean;
+  /** Internal: tracks visited addresses to detect circular migrations */
+  _visitedAddresses?: Set<string>;
+}
+/**
+ * Account Table
+ * Standard account state with balance sync support
+ * Includes migration chain following and circular migration detection
+ */
+declare class AccountTable extends SqliteTable<IAccountState> {
+  constructor(config: Omit<SqliteTableConfig, 'name' | 'uniqIndex' | 'schema'>);
+  /**
+   * Check if adding migration targets would create a cycle
+   * @param sourceAddress - The address that will have migratedTo set
+   * @param targets - The migration targets to check
+   * @param context - Operation context with transaction
+   * @returns true if a cycle would be created
+   */
+  private wouldCreateCycle;
+  /**
+   * Get account with migration chain following
+   * When an account has migratedTo set, follows the chain to get the final account
+   */
+  _get(address: string, context?: AccountOperationContext): Promise<IAccountState | null>;
+  /**
+   * Create account with address normalization and circular migration detection
+   */
+  _create(key: string, attrs?: Partial<IAccountState>, context?: IOperationContext): Promise<IAccountState>;
+  /**
+   * Update account with circular migration detection
+   */
+  _update(key: string, updates: Partial<IAccountState>, context?: IOperationContext): Promise<IAccountState>;
+}
+//#endregion
+export { AccountTable as default };

package/esm/table/account.mjs

@@ -0,0 +1,99 @@
+import base_default from "./base.mjs";
+import { ensureChecksumAddress } from "@ocap/state/lib/states/account";
+
+//#region src/table/account.ts
+/**
+* Account Table
+* Standard account state with balance sync support
+* Includes migration chain following and circular migration detection
+*/
+var AccountTable = class extends base_default {
+	constructor(config) {
+		super({
+			...config,
+			name: "account",
+			uniqIndex: "address",
+			schema: { jsonFields: [
+				"migratedTo",
+				"migratedFrom",
+				"stake",
+				"tokens",
+				"data",
+				"context",
+				"poke"
+			] }
+		});
+	}
+	/**
+	* Check if adding migration targets would create a cycle
+	* @param sourceAddress - The address that will have migratedTo set
+	* @param targets - The migration targets to check
+	* @param context - Operation context with transaction
+	* @returns true if a cycle would be created
+	*/
+	async wouldCreateCycle(sourceAddress, targets, context) {
+		const visited = /* @__PURE__ */ new Set();
+		visited.add(sourceAddress);
+		const checkTarget = async (target) => {
+			const normalizedTarget = ensureChecksumAddress(target);
+			if (normalizedTarget === sourceAddress) return true;
+			if (visited.has(normalizedTarget)) return false;
+			visited.add(normalizedTarget);
+			const targetAccount = await super._get(normalizedTarget, context);
+			if (targetAccount?.migratedTo?.length) {
+				for (const nextTarget of targetAccount.migratedTo) if (await checkTarget(nextTarget)) return true;
+			}
+			return false;
+		};
+		for (const target of targets) if (await checkTarget(target)) return true;
+		return false;
+	}
+	/**
+	* Get account with migration chain following
+	* When an account has migratedTo set, follows the chain to get the final account
+	*/
+	async _get(address, context = {}) {
+		const { traceMigration = true, ...restContext } = context;
+		const normalizedAddress = ensureChecksumAddress(address);
+		const current = await super._get(normalizedAddress, restContext);
+		if (current && traceMigration && Array.isArray(current.migratedTo) && current.migratedTo.length) {
+			const visitedAddresses = context._visitedAddresses || /* @__PURE__ */ new Set();
+			if (visitedAddresses.has(normalizedAddress)) return null;
+			visitedAddresses.add(normalizedAddress);
+			return this._get(current.migratedTo[0], {
+				...context,
+				_visitedAddresses: visitedAddresses
+			});
+		}
+		return current;
+	}
+	/**
+	* Create account with address normalization and circular migration detection
+	*/
+	async _create(key, attrs = {}, context) {
+		const address = ensureChecksumAddress(key);
+		const attrsWithMigration = attrs;
+		if (attrsWithMigration.migratedTo?.length) {
+			if (await this.wouldCreateCycle(address, attrsWithMigration.migratedTo, context)) throw new Error(`Circular migration detected: ${address} -> ${attrsWithMigration.migratedTo.join(", ")}`);
+		}
+		return super._create(address, {
+			...attrs,
+			[this.uniqIndex]: address
+		}, context);
+	}
+	/**
+	* Update account with circular migration detection
+	*/
+	async _update(key, updates, context) {
+		const address = ensureChecksumAddress(key);
+		const updatesWithMigration = updates;
+		if (updatesWithMigration.migratedTo?.length) {
+			if (await this.wouldCreateCycle(address, updatesWithMigration.migratedTo, context)) throw new Error(`Circular migration detected: ${address} -> ${updatesWithMigration.migratedTo.join(", ")}`);
+		}
+		return super._update(address, updates, context);
+	}
+};
+var account_default = AccountTable;
+
+//#endregion
+export { account_default as default };

package/esm/table/balance.d.mts

@@ -0,0 +1,39 @@
+import SqliteTable, { SqliteTableConfig } from "./base.mjs";
+import { IBalanceState, IOperationContext } from "@ocap/types";
+
+//#region src/table/balance.d.ts
+
+/**
+ * Balance Table
+ * Manages token balances with composite primary key (address, tokenAddress)
+ */
+declare class BalanceTable extends SqliteTable<IBalanceState> {
+  constructor(config: Omit<SqliteTableConfig, 'name' | 'uniqIndex' | 'schema'>);
+  /**
+   * Get all token balances for an address
+   *
+   * @param address - Account address
+   * @param _context - Operation context
+   * @returns Object mapping tokenAddress to balance
+   */
+  getBalance(address: string, _context?: IOperationContext): Promise<Record<string, string>>;
+  /**
+   * Update token balances for an address
+   * Creates new records for new tokens, updates existing ones
+   *
+   * @param params - Update parameters
+   * @param ctx - Operation context
+   * @returns Updated token balances
+   */
+  updateBalance({
+    address,
+    tokens,
+    context
+  }: {
+    address: string;
+    tokens: Record<string, string>;
+    context?: unknown;
+  }, ctx?: IOperationContext): Promise<Record<string, string>>;
+}
+//#endregion
+export { BalanceTable as default };

package/esm/table/balance.mjs

@@ -0,0 +1,69 @@
+import base_default from "./base.mjs";
+import { ensureChecksumAddress } from "@ocap/state/lib/states/account";
+
+//#region src/table/balance.ts
+/**
+* Balance Table
+* Manages token balances with composite primary key (address, tokenAddress)
+*/
+var BalanceTable = class extends base_default {
+	constructor(config) {
+		super({
+			...config,
+			name: "balance",
+			uniqIndex: ["address", "tokenAddress"],
+			schema: { jsonFields: ["context"] }
+		});
+	}
+	/**
+	* Get all token balances for an address
+	*
+	* @param address - Account address
+	* @param _context - Operation context
+	* @returns Object mapping tokenAddress to balance
+	*/
+	async getBalance(address, _context) {
+		const sqlContext = _context;
+		const executor = this.getExecutor(sqlContext);
+		const normalizedAddress = ensureChecksumAddress(address);
+		return (await executor.selectFrom("balance").selectAll().where("address", "=", normalizedAddress).execute() || []).reduce((acc, token) => {
+			acc[token.tokenAddress] = token.balance;
+			return acc;
+		}, {});
+	}
+	/**
+	* Update token balances for an address
+	* Creates new records for new tokens, updates existing ones
+	*
+	* @param params - Update parameters
+	* @param ctx - Operation context
+	* @returns Updated token balances
+	*/
+	async updateBalance({ address, tokens, context = {} }, ctx) {
+		if (!Object.keys(tokens).length) return {};
+		const tokenBalances = await this.getBalance(address, ctx);
+		const updatedTokens = Object.keys(tokens).filter((token) => tokenBalances[token] && tokenBalances[token] !== "0" || tokens[token] && tokens[token] !== "0").filter((token) => tokenBalances[token] !== tokens[token]);
+		await Promise.all(updatedTokens.map(async (tokenAddress) => {
+			const key = {
+				address,
+				tokenAddress
+			};
+			if (tokenBalances[tokenAddress]) await this.update(key, {
+				...key,
+				balance: tokens[tokenAddress],
+				context
+			}, ctx);
+			else await this.create(key, {
+				...key,
+				balance: tokens[tokenAddress],
+				context
+			}, ctx);
+			tokenBalances[tokenAddress] = tokens[tokenAddress];
+		}));
+		return tokens;
+	}
+};
+var balance_default = BalanceTable;
+
+//#endregion
+export { balance_default as default };

package/esm/table/base.d.mts

@@ -0,0 +1,84 @@
+import { Database, SqliteOperationContext } from "../interfaces.mjs";
+import { StateDBTable } from "@ocap/statedb";
+import { Kysely, Transaction } from "kysely";
+import { IBalanceTable, IOperationContext } from "@ocap/types";
+
+//#region src/table/base.d.ts
+
+/**
+ * Table schema configuration
+ */
+interface TableSchema {
+  /** Column names that contain JSON data */
+  jsonFields?: string[];
+  /** Column names that contain boolean data (stored as integer 0/1 in SQLite) */
+  booleanFields?: string[];
+  /** Column name mapping (e.g., 'from' -> 'from_' for reserved keywords) */
+  columnMapping?: Record<string, string>;
+}
+/**
+ * Table configuration
+ */
+interface SqliteTableConfig {
+  name: string;
+  uniqIndex: string | string[];
+  db: Kysely<Database>;
+  schema?: TableSchema;
+  syncBalance?: boolean;
+  balanceTable?: IBalanceTable;
+}
+/**
+ * SQLite State Table base class
+ * Extends StateDBTable to provide SQLite-specific implementation
+ */
+declare class SqliteTable<T = unknown> extends StateDBTable<T> {
+  name: string;
+  db: Kysely<Database>;
+  schema: TableSchema;
+  balanceTable?: IBalanceTable;
+  syncBalance: boolean;
+  constructor(config: SqliteTableConfig);
+  /**
+   * Get the Kysely executor (use transaction if available)
+   */
+  protected getExecutor(context?: SqliteOperationContext): Kysely<Database> | Transaction<Database>;
+  /**
+   * Generate primary key from document
+   * Handles both simple string keys and composite keys
+   */
+  generatePrimaryKey(doc: string | Record<string, unknown>): string;
+  /**
+   * Convert a key to a query object
+   */
+  protected formatKeyToQuery(key: unknown): Record<string, unknown>;
+  /**
+   * Map column name for reserved keywords
+   */
+  protected mapColumnName(name: string): string;
+  /**
+   * Reverse map column name
+   */
+  protected unmapColumnName(name: string): string;
+  /**
+   * Serialize data for database insert
+   * - Converts objects/arrays to JSON strings
+   * - Converts booleans to integers (0/1) for SQLite
+   * - Maps column names for reserved keywords
+   */
+  protected serializeForDb(data: Record<string, unknown>): Record<string, unknown>;
+  /**
+   * Deserialize data from database read
+   * - Parses JSON strings back to objects
+   * - Converts integers (0/1) back to booleans
+   * - Unmaps column names
+   */
+  protected deserializeFromDb(data: Record<string, unknown> | undefined | null): Record<string, unknown> | null;
+  _create(key: string | Record<string, unknown>, attrs?: Partial<T>, context?: IOperationContext): Promise<T>;
+  _get(key: string | Record<string, unknown>, context?: IOperationContext): Promise<T | null>;
+  _history(_key?: string, _context?: IOperationContext): T[];
+  _update(key: string | Record<string, unknown>, updates: Partial<T>, context?: IOperationContext): Promise<T>;
+  _reset(_context?: IOperationContext): Promise<void>;
+  updateOrCreate(exist: unknown, state: Partial<T>, ctx?: IOperationContext): Promise<T>;
+}
+//#endregion
+export { SqliteTableConfig, TableSchema, SqliteTable as default };