@ocap/statedb-sqlite 1.30.24 → 1.30.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/esm/package.mjs CHANGED
@@ -10,7 +10,7 @@ var package_default = {
10
10
  },
11
11
  publishConfig: { "access": "public" },
12
12
  contributors: ["wangshijun <shijun@arcblock.io> (https://www.arcblock.io)"],
13
- devDependencies: {},
13
+ devDependencies: { "@ocap/statedb-test": "workspace:*" },
14
14
  homepage: "https://github.com/ArcBlock/blockchain/tree/master/statedb/sqlite",
15
15
  keywords: [
16
16
  "ocap",
@@ -9,6 +9,10 @@ import { IBalanceState, IOperationContext } from "@ocap/types";
9
9
  */
10
10
  declare class BalanceTable extends SqliteTable<IBalanceState> {
11
11
  constructor(config: Omit<SqliteTableConfig, 'name' | 'uniqIndex' | 'schema'>);
12
+ generatePrimaryKey(doc: string | Record<string, unknown>): string;
13
+ protected formatKeyToQuery(key: unknown): Record<string, unknown>;
14
+ _create(key: string | Record<string, unknown>, attrs?: Partial<IBalanceState>, context?: IOperationContext): Promise<IBalanceState>;
15
+ _update(key: string | Record<string, unknown>, updates: Partial<IBalanceState>, context?: IOperationContext): Promise<IBalanceState>;
12
16
  /**
13
17
  * Get all token balances for an address
14
18
  *
@@ -19,7 +23,7 @@ declare class BalanceTable extends SqliteTable<IBalanceState> {
19
23
  getBalance(address: string, _context?: IOperationContext): Promise<Record<string, string>>;
20
24
  /**
21
25
  * Update token balances for an address
22
- * Creates new records for new tokens, updates existing ones
26
+ * Creates new records for new tokens, updates existing ones via batched SQLite UPSERT
23
27
  *
24
28
  * @param params - Update parameters
25
29
  * @param ctx - Operation context
@@ -2,6 +2,8 @@ import base_default from "./base.mjs";
2
2
  import { ensureChecksumAddress } from "@ocap/state/lib/states/account";
3
3
 
4
4
  //#region src/table/balance.ts
5
+ const BATCH_COLLECTOR = Symbol.for("@ocap/statedb-sqlite.balanceBatchCollector");
6
+ const UPSERT_BATCH_SIZE = 200;
5
7
  /**
6
8
  * Balance Table
7
9
  * Manages token balances with composite primary key (address, tokenAddress)
@@ -15,6 +17,42 @@ var BalanceTable = class extends base_default {
15
17
  schema: { jsonFields: ["context"] }
16
18
  });
17
19
  }
20
+ generatePrimaryKey(doc) {
21
+ if (typeof doc === "object" && doc !== null && typeof doc.address === "string") return super.generatePrimaryKey({
22
+ ...doc,
23
+ address: ensureChecksumAddress(doc.address)
24
+ });
25
+ return super.generatePrimaryKey(doc);
26
+ }
27
+ formatKeyToQuery(key) {
28
+ const query = super.formatKeyToQuery(key);
29
+ if (typeof query.address === "string") query.address = ensureChecksumAddress(query.address);
30
+ return query;
31
+ }
32
+ async _create(key, attrs = {}, context) {
33
+ const collector = attrs?.[BATCH_COLLECTOR];
34
+ if (collector) {
35
+ const insertAttrs = {
36
+ ...attrs,
37
+ ...typeof key === "object" ? key : {}
38
+ };
39
+ collector.push(this.serializeForDb(insertAttrs));
40
+ return insertAttrs;
41
+ }
42
+ return super._create(key, attrs, context);
43
+ }
44
+ async _update(key, updates, context) {
45
+ const collector = updates?.[BATCH_COLLECTOR];
46
+ if (collector) {
47
+ const merged = {
48
+ ...updates,
49
+ ...typeof key === "object" ? key : {}
50
+ };
51
+ collector.push(this.serializeForDb(merged));
52
+ return merged;
53
+ }
54
+ return super._update(key, updates, context);
55
+ }
18
56
  /**
19
57
  * Get all token balances for an address
20
58
  *
@@ -33,7 +71,7 @@ var BalanceTable = class extends base_default {
33
71
  }
34
72
  /**
35
73
  * Update token balances for an address
36
- * Creates new records for new tokens, updates existing ones
74
+ * Creates new records for new tokens, updates existing ones via batched SQLite UPSERT
37
75
  *
38
76
  * @param params - Update parameters
39
77
  * @param ctx - Operation context
@@ -41,25 +79,41 @@ var BalanceTable = class extends base_default {
41
79
  */
42
80
  async updateBalance({ address, tokens, context = {} }, ctx) {
43
81
  if (!Object.keys(tokens).length) return {};
44
- const tokenBalances = await this.getBalance(address, ctx);
82
+ const normalizedAddress = ensureChecksumAddress(address);
83
+ const tokenBalances = await this.getBalance(normalizedAddress, ctx);
45
84
  const updatedTokens = Object.keys(tokens).filter((token) => tokenBalances[token] && tokenBalances[token] !== "0" || tokens[token] && tokens[token] !== "0").filter((token) => tokenBalances[token] !== tokens[token]);
46
- await Promise.all(updatedTokens.map(async (tokenAddress) => {
85
+ if (updatedTokens.length === 0) return tokens;
86
+ const batchRows = [];
87
+ for (const tokenAddress of updatedTokens) {
47
88
  const key = {
48
- address,
89
+ address: normalizedAddress,
49
90
  tokenAddress
50
91
  };
51
- if (tokenBalances[tokenAddress]) await this.update(key, {
52
- ...key,
53
- balance: tokens[tokenAddress],
54
- context
55
- }, ctx);
56
- else await this.create(key, {
92
+ const payload = {
57
93
  ...key,
58
94
  balance: tokens[tokenAddress],
59
95
  context
60
- }, ctx);
96
+ };
97
+ Object.defineProperty(payload, BATCH_COLLECTOR, {
98
+ value: batchRows,
99
+ enumerable: false,
100
+ configurable: true
101
+ });
102
+ if (tokenBalances[tokenAddress]) await this.update(key, payload, ctx);
103
+ else await this.create(key, payload, ctx);
61
104
  tokenBalances[tokenAddress] = tokens[tokenAddress];
62
- }));
105
+ }
106
+ if (batchRows.length > 0) {
107
+ const sqlContext = ctx;
108
+ const executor = this.getExecutor(sqlContext);
109
+ for (let i = 0; i < batchRows.length; i += UPSERT_BATCH_SIZE) {
110
+ const batch = batchRows.slice(i, i + UPSERT_BATCH_SIZE);
111
+ await executor.insertInto("balance").values(batch).onConflict((oc) => oc.columns(["address", "tokenAddress"]).doUpdateSet((eb) => ({
112
+ balance: eb.ref("excluded.balance"),
113
+ context: eb.ref("excluded.context")
114
+ }))).execute();
115
+ }
116
+ }
63
117
  return tokens;
64
118
  }
65
119
  };
@@ -1,5 +1,5 @@
1
- import { StateDBTable } from "@ocap/statedb";
2
1
  import crypto from "node:crypto";
2
+ import { StateDBTable } from "@ocap/statedb";
3
3
  import omit from "lodash/omit.js";
4
4
 
5
5
  //#region src/table/base.ts
@@ -31,7 +31,7 @@ var SqliteTable = class SqliteTable extends StateDBTable {
31
31
  generatePrimaryKey(doc) {
32
32
  if (typeof doc === "string") return doc;
33
33
  if (Array.isArray(this.uniqIndex)) {
34
- const key = this.uniqIndex.map((id) => doc[id]).map((item) => typeof item === "object" ? JSON.stringify(item) : item).join("-");
34
+ const key = this.uniqIndex.map((id) => doc[id]).map((item) => typeof item === "object" ? JSON.stringify(item) : String(item ?? "")).map((item) => item.replace(/\\/g, "\\\\").replace(/-/g, "\\-")).join("-");
35
35
  return crypto.createHash("md5").update(key).digest("hex");
36
36
  }
37
37
  return doc[this.uniqIndex];
@@ -136,10 +136,8 @@ var SqliteTable = class SqliteTable extends StateDBTable {
136
136
  const sqlContext = context;
137
137
  const executor = this.getExecutor(sqlContext);
138
138
  let query;
139
- if (Array.isArray(this.uniqIndex)) if (typeof key === "object") {
140
- const keyObj = key;
141
- query = Object.fromEntries(this.uniqIndex.map((k) => [this.mapColumnName(k), keyObj[k]]));
142
- } else return null;
139
+ if (Array.isArray(this.uniqIndex)) if (typeof key === "object") query = this.formatKeyToQuery(key);
140
+ else return null;
143
141
  else query = this.formatKeyToQuery(key);
144
142
  let qb = executor.selectFrom(this.name).selectAll();
145
143
  for (const [k, v] of Object.entries(query)) {
@@ -168,17 +166,14 @@ var SqliteTable = class SqliteTable extends StateDBTable {
168
166
  const updatesObj = updates;
169
167
  lookupKey = Object.fromEntries(this.uniqIndex.map((k) => [k, updatesObj[k]]));
170
168
  }
171
- const existing = await SqliteTable.prototype._get.call(this, lookupKey, context);
172
- if (!existing) throw new Error(`${this.name} does not exist: ${JSON.stringify(key)}`);
173
169
  let query;
174
- if (Array.isArray(this.uniqIndex)) {
175
- const keyObj = typeof lookupKey === "object" ? lookupKey : existing;
176
- query = Object.fromEntries(this.uniqIndex.map((k) => [this.mapColumnName(k), keyObj[k]]));
177
- } else query = this.formatKeyToQuery(key);
170
+ if (Array.isArray(this.uniqIndex)) query = this.formatKeyToQuery(lookupKey);
171
+ else query = this.formatKeyToQuery(key);
178
172
  const updateAttrs = { ...updates };
179
173
  if (Array.isArray(this.uniqIndex)) for (const k of this.uniqIndex) delete updateAttrs[k];
180
174
  else delete updateAttrs[this.primaryKey];
181
175
  if (this.syncBalance) delete updateAttrs.tokens;
176
+ let merged;
182
177
  if (Object.keys(updateAttrs).length > 0) {
183
178
  const serialized = this.serializeForDb(updateAttrs);
184
179
  let qb = executor.updateTable(this.name).set(serialized);
@@ -186,17 +181,34 @@ var SqliteTable = class SqliteTable extends StateDBTable {
186
181
  if (v === void 0) continue;
187
182
  qb = qb.where(k, "=", v);
188
183
  }
189
- await qb.execute();
184
+ const updatedRow = await qb.returningAll().executeTakeFirst();
185
+ if (!updatedRow) throw new Error(`${this.name} does not exist: ${JSON.stringify(key)}`);
186
+ merged = {
187
+ ...this.deserializeFromDb(updatedRow),
188
+ ...updateAttrs
189
+ };
190
+ } else {
191
+ let qb = executor.selectFrom(this.name).selectAll();
192
+ for (const [k, v] of Object.entries(query)) {
193
+ if (v === void 0) continue;
194
+ qb = qb.where(k, "=", v);
195
+ }
196
+ const existingRow = await qb.executeTakeFirst();
197
+ if (!existingRow) throw new Error(`${this.name} does not exist: ${JSON.stringify(key)}`);
198
+ merged = this.deserializeFromDb(existingRow);
190
199
  }
191
- const merged = {
192
- ...existing,
193
- ...updateAttrs
194
- };
195
- if (this.syncBalance && updates.tokens) merged.tokens = await this.balanceTable.updateBalance({
200
+ if (this.syncBalance) if (updates.tokens) merged.tokens = await this.balanceTable.updateBalance({
196
201
  address: merged.address,
197
202
  tokens: updates.tokens,
198
203
  context: updates.context
199
204
  }, context);
205
+ else {
206
+ const balance = await this.balanceTable.getBalance(merged.address, context);
207
+ merged.tokens = {
208
+ ...merged.tokens || {},
209
+ ...balance
210
+ };
211
+ }
200
212
  return merged;
201
213
  }
202
214
  async _reset(_context) {
package/lib/db.cjs CHANGED
@@ -8,7 +8,10 @@ const require_table_balance = require('./table/balance.cjs');
8
8
  const require_table_rollup = require('./table/rollup.cjs');
9
9
  const require_table_token = require('./table/token.cjs');
10
10
  const require_package = require('./package.cjs');
11
+ let node_crypto = require("node:crypto");
12
+ node_crypto = require_rolldown_runtime.__toESM(node_crypto);
11
13
  let _ocap_statedb = require("@ocap/statedb");
14
+ let kysely = require("kysely");
12
15
 
13
16
  //#region src/db.ts
14
17
  const { name, version } = require_package.default;
@@ -37,9 +40,18 @@ var SqliteStateDB = class extends _ocap_statedb.StateDB {
37
40
  constructor(config = { filename: ":memory:" }) {
38
41
  super();
39
42
  this.initialized = false;
43
+ this.stateCommitTableReady = false;
44
+ this.trustedInitialized = false;
45
+ this.commitQueue = Promise.resolve();
46
+ this.walEnabled = false;
47
+ this.walCheckpointTimer = null;
48
+ this.walCheckpointPromise = null;
49
+ this._activeLambdaCount = 0;
50
+ this.closed = false;
40
51
  this.name = name;
41
52
  this.version = version;
42
53
  this.config = config;
54
+ this.trustedStorage = config.trustedStorage;
43
55
  this.initSync();
44
56
  }
45
57
  /**
@@ -48,6 +60,9 @@ var SqliteStateDB = class extends _ocap_statedb.StateDB {
48
60
  */
49
61
  initSync() {
50
62
  this.db = require_kysely.createKysely(this.config);
63
+ const filename = this.config.filename || ":memory:";
64
+ this.walEnabled = !this.config.doStorage && !this.config.dialect && this.config.walMode !== false && !this.config.readonly && filename !== ":memory:";
65
+ this.walCheckpointIntervalMs = require_kysely.resolveWalCheckpointIntervalMs(this.config);
51
66
  this.balance = new require_table_balance.default({ db: this.db });
52
67
  this.account = new require_table_account.default({
53
68
  db: this.db,
@@ -192,48 +207,206 @@ var SqliteStateDB = class extends _ocap_statedb.StateDB {
192
207
  this.attachReadyListeners();
193
208
  }
194
209
  /**
195
- * Async initialization - runs migrations
210
+ * Async initialization - runs migrations and initializes trustedStorage if configured
196
211
  * Call this after constructor to ensure database schema is ready
197
212
  */
198
213
  async initialize() {
199
- if (this.initialized) return;
214
+ this.closed = false;
215
+ if (this.initialized) {
216
+ if (this.trustedStorage && !this.trustedInitialized) await this.ensureTrustedStorageInitialized();
217
+ this.startWalCheckpointWorker();
218
+ return;
219
+ }
200
220
  await require_migrations_index.runMigrations(this.db);
201
221
  this.initialized = true;
222
+ if (this.trustedStorage) await this.ensureTrustedStorageInitialized();
223
+ this.startWalCheckpointWorker();
224
+ }
225
+ /**
226
+ * Run a WAL checkpoint (`PRAGMA wal_checkpoint(<mode>)`) against the SQLite database.
227
+ * No-op returning `{ busy: 0, log: 0, checkpointed: 0 }` when WAL mode is disabled.
228
+ */
229
+ async runWalCheckpoint(mode = "PASSIVE") {
230
+ if (!this.walEnabled || this.closed) return {
231
+ busy: 0,
232
+ log: 0,
233
+ checkpointed: 0
234
+ };
235
+ const safeMode = mode === "FULL" || mode === "RESTART" || mode === "TRUNCATE" ? mode : "PASSIVE";
236
+ if (this.walCheckpointPromise) {
237
+ if (safeMode === "PASSIVE") return this.walCheckpointPromise;
238
+ while (this.walCheckpointPromise) try {
239
+ await this.walCheckpointPromise;
240
+ } catch {}
241
+ if (!this.walEnabled || this.closed) return {
242
+ busy: 0,
243
+ log: 0,
244
+ checkpointed: 0
245
+ };
246
+ }
247
+ const run = (async () => {
248
+ try {
249
+ const row = (await kysely.sql`
250
+ ${kysely.sql.raw(`PRAGMA wal_checkpoint(${safeMode})`)}
251
+ `.execute(this.db)).rows[0];
252
+ return {
253
+ busy: Number(row?.busy ?? 0),
254
+ log: Number(row?.log ?? 0),
255
+ checkpointed: Number(row?.checkpointed ?? 0)
256
+ };
257
+ } finally {
258
+ if (this.walCheckpointPromise === run) this.walCheckpointPromise = null;
259
+ }
260
+ })();
261
+ this.walCheckpointPromise = run;
262
+ return run;
263
+ }
264
+ startWalCheckpointWorker() {
265
+ if (!this.walEnabled || !this.walCheckpointIntervalMs || this.walCheckpointTimer || this.closed) return;
266
+ this.walCheckpointTimer = setInterval(() => {
267
+ if (this.closed || this._activeLambdaCount > 0 || this.walCheckpointPromise) return;
268
+ this.runWalCheckpoint("PASSIVE").catch(() => {});
269
+ }, this.walCheckpointIntervalMs);
270
+ if (typeof this.walCheckpointTimer.unref === "function") this.walCheckpointTimer.unref();
271
+ }
272
+ async ensureStateCommitTable() {
273
+ if (this.stateCommitTableReady) return;
274
+ await kysely.sql`
275
+ CREATE TABLE IF NOT EXISTS "_state_commit" (
276
+ "id" INTEGER PRIMARY KEY CHECK ("id" = 1),
277
+ "current_hash" TEXT NOT NULL,
278
+ "prev_hash" TEXT NOT NULL,
279
+ "seq" INTEGER NOT NULL DEFAULT 0,
280
+ "msg" TEXT NOT NULL DEFAULT ''
281
+ )
282
+ `.execute(this.db);
283
+ await kysely.sql`
284
+ INSERT OR IGNORE INTO "_state_commit" ("id", "current_hash", "prev_hash", "seq", "msg")
285
+ VALUES (1, 'GENESIS', '', 0, '')
286
+ `.execute(this.db);
287
+ this.stateCommitTableReady = true;
288
+ }
289
+ async ensureTrustedStorageInitialized() {
290
+ if (!this.trustedStorage || this.trustedInitialized) return;
291
+ await this.ensureStateCommitTable();
292
+ if (typeof this.trustedStorage.initStorage === "function") await this.trustedStorage.initStorage();
293
+ if (!await this.trustedStorage.getHash()) {
294
+ const { currentHash } = await this.getCommitHash();
295
+ const newTrustedHash = await this.trustedStorage.createHash(currentHash);
296
+ await this.trustedStorage.writeHash(newTrustedHash);
297
+ } else await this.verifyTrustedHashInternal();
298
+ this.trustedInitialized = true;
299
+ }
300
+ /**
301
+ * Get the current and previous state commit hash tracked in SQLite StateDB.
302
+ *
303
+ * Note on threat model & performance:
304
+ * SQLite StateDB maintains an O(1) incremental commit-chain head (`_state_commit`)
305
+ * to detect snapshot rollback or crash desynchronization between `statedb` and
306
+ * `trustedStorage` without O(N) full-table scans on every transaction.
307
+ * End-to-end Data Availability, Merkle inclusion proofs, and corruption detection
308
+ * for RPC, Light Wallet, and Archive nodes are enforced by `@arcblock/ledger`
309
+ * checkpoints and self-verifying segments.
310
+ */
311
+ async getCommitHash(executor = this.db) {
312
+ if (!this.stateCommitTableReady) await this.ensureStateCommitTable();
313
+ const row = (await kysely.sql`
314
+ SELECT "current_hash", "prev_hash" FROM "_state_commit" WHERE "id" = 1
315
+ `.execute(executor)).rows[0];
316
+ return {
317
+ currentHash: row?.current_hash || "GENESIS",
318
+ prevHash: row?.prev_hash || ""
319
+ };
320
+ }
321
+ async verifyTrustedHashInternal() {
322
+ if (!this.trustedStorage) return;
323
+ const { currentHash } = await this.getCommitHash();
324
+ if (!await this.trustedStorage.compare(currentHash)) {
325
+ const err = /* @__PURE__ */ new Error("Trusted hash verification failed");
326
+ err.code = "INVALID_HASH";
327
+ throw err;
328
+ }
329
+ }
330
+ /**
331
+ * Verify that the current SQLite state commit hash matches the trusted storage record.
332
+ */
333
+ async verifyTrustedHash() {
334
+ if (!this.trustedStorage) return;
335
+ await this.enqueueCommit(async () => {
336
+ await this.ensureTrustedStorageInitialized();
337
+ await this.verifyTrustedHashInternal();
338
+ });
339
+ }
340
+ enqueueCommit(task) {
341
+ const next = this.commitQueue.then(task, task);
342
+ this.commitQueue = next.then(() => void 0, () => void 0);
343
+ return next;
202
344
  }
203
345
  /**
204
346
  * Execute multiple operations within a database transaction
205
347
  * Provides retry logic for SQLite BUSY errors (lock conflicts)
206
348
  *
207
349
  * @param fn - Function receiving Kysely transaction object
208
- * @param options - Optional retry configuration
350
+ * @param options - Optional retry and trusted-hash verification configuration
209
351
  * @returns Result of the transaction function
210
- *
211
- * @example
212
- * ```typescript
213
- * await db.runAsLambda(async (txn) => {
214
- * await txn.insertInto('account').values({ ... }).execute();
215
- * await txn.updateTable('balance').set({ ... }).execute();
216
- * });
217
- * ```
218
352
  */
219
353
  async runAsLambda(fn, options = {}) {
220
- const { retryLimit = 2 } = options;
354
+ if (this.trustedStorage) return this.enqueueCommit(() => this.executeRunAsLambda(fn, options));
355
+ return this.executeRunAsLambda(fn, options);
356
+ }
357
+ async executeRunAsLambda(fn, options = {}) {
358
+ const { retryLimit = 2, verifyHash = false, commitMessage } = options;
359
+ if (this.trustedStorage) {
360
+ await this.ensureTrustedStorageInitialized();
361
+ if (verifyHash) await this.verifyTrustedHashInternal();
362
+ }
363
+ let result;
364
+ let committedHash;
365
+ let previousHash;
221
366
  let lastError;
367
+ let committed = false;
222
368
  for (let attempt = 0; attempt <= retryLimit; attempt++) try {
223
- const result = await this.db.transaction().execute(async (txn) => {
224
- return await fn(txn);
225
- });
226
- if (options.onCommit) try {
227
- await options.onCommit();
228
- } catch (_err) {}
229
- return result;
369
+ committedHash = void 0;
370
+ previousHash = void 0;
371
+ this._activeLambdaCount++;
372
+ try {
373
+ result = await this.db.transaction().execute(async (txn) => {
374
+ const txResult = await fn(txn);
375
+ if (this.trustedStorage) {
376
+ const row = (await kysely.sql`
377
+ SELECT "current_hash", "seq" FROM "_state_commit" WHERE "id" = 1
378
+ `.execute(txn)).rows[0];
379
+ const prevHash = row?.current_hash || "GENESIS";
380
+ const nextSeq = Number(row?.seq || 0) + 1;
381
+ const msg = commitMessage || txResult?.hash || "commit";
382
+ const nextHash = node_crypto.default.createHash("sha256").update(`${prevHash}:${nextSeq}:${msg}`).digest("hex");
383
+ await kysely.sql`
384
+ UPDATE "_state_commit"
385
+ SET "current_hash" = ${nextHash}, "prev_hash" = ${prevHash}, "seq" = ${nextSeq}, "msg" = ${msg}
386
+ WHERE "id" = 1
387
+ `.execute(txn);
388
+ previousHash = prevHash;
389
+ committedHash = nextHash;
390
+ }
391
+ return txResult;
392
+ });
393
+ } finally {
394
+ this._activeLambdaCount--;
395
+ }
396
+ committed = true;
397
+ break;
230
398
  } catch (err) {
231
399
  lastError = err;
232
400
  const code = err?.code;
233
401
  if (!SQLITE_BUSY_CODES.includes(code)) throw err;
234
402
  if (attempt < retryLimit) await new Promise((r) => setTimeout(r, 10 * 2 ** attempt));
235
403
  }
236
- throw lastError;
404
+ if (!committed) throw lastError;
405
+ if (this.trustedStorage && committedHash) await this.trustedStorage.updateHash(committedHash, previousHash);
406
+ if (options.onCommit) try {
407
+ await options.onCommit(committedHash);
408
+ } catch (_err) {}
409
+ return result;
237
410
  }
238
411
  /**
239
412
  * Reset all tables (for testing)
@@ -244,12 +417,31 @@ var SqliteStateDB = class extends _ocap_statedb.StateDB {
244
417
  const tableInstance = this[table];
245
418
  if (tableInstance?.reset) await tableInstance.reset();
246
419
  }
420
+ if (this.stateCommitTableReady) {
421
+ await kysely.sql`
422
+ UPDATE "_state_commit"
423
+ SET "current_hash" = 'GENESIS', "prev_hash" = '', "seq" = 0, "msg" = ''
424
+ WHERE "id" = 1
425
+ `.execute(this.db);
426
+ if (this.trustedStorage) {
427
+ const genesisHash = await this.trustedStorage.createHash("GENESIS");
428
+ await this.trustedStorage.writeHash(genesisHash);
429
+ }
430
+ }
247
431
  }
248
432
  /**
249
433
  * Close database connection
250
434
  */
251
435
  async close() {
436
+ this.closed = true;
437
+ if (this.walCheckpointTimer) {
438
+ clearInterval(this.walCheckpointTimer);
439
+ this.walCheckpointTimer = null;
440
+ }
441
+ if (this.walCheckpointPromise) await this.walCheckpointPromise.catch(() => void 0);
442
+ await this.commitQueue;
252
443
  await this.db.destroy();
444
+ if (this.trustedStorage && typeof this.trustedStorage.destroy === "function") await this.trustedStorage.destroy();
253
445
  }
254
446
  /**
255
447
  * Get the underlying Kysely instance (for advanced operations)
package/lib/db.d.cts CHANGED
@@ -1,11 +1,22 @@
1
1
  import { Database } from "./interfaces.cjs";
2
2
  import { SqliteConfig } from "./kysely.cjs";
3
3
  import { StateDB } from "@ocap/statedb";
4
- import { IAccountState, IAssetFactoryState, IAssetState, IBalanceTable, IChainState, IDelegateState, IEvidenceState, IRollupBlock, IRollupTable, IStakeState, IStateDB, IStateTable, ITokenFactoryState, ITokenTable, ITxState } from "@ocap/types";
4
+ import { IAccountState, IAssetFactoryState, IAssetState, IBalanceTable, IChainState, IDelegateState, IEvidenceState, IRollupBlock, IRollupTable, IStakeState, IStateDB, IStateTable, ITokenFactoryState, ITokenTable, ITrustedStorage, ITxState } from "@ocap/types";
5
5
  import { Kysely, Transaction } from "kysely";
6
6
 
7
7
  //#region src/db.d.ts
8
-
8
+ interface SqliteRunOptions {
9
+ retryLimit?: number;
10
+ verifyHash?: boolean;
11
+ cleanWorkingSet?: boolean;
12
+ commitMessage?: string;
13
+ context?: unknown;
14
+ onCommit?: (commitHash?: string) => void | Promise<void>;
15
+ }
16
+ interface TrustedStorageLike extends ITrustedStorage {
17
+ initStorage?: () => Promise<void>;
18
+ destroy?: () => Promise<void>;
19
+ }
9
20
  /**
10
21
  * SQLite StateDB Implementation
11
22
  * Uses SQLite via Kysely as the storage backend
@@ -13,9 +24,19 @@ import { Kysely, Transaction } from "kysely";
13
24
  declare class SqliteStateDB extends StateDB implements IStateDB {
14
25
  name: string;
15
26
  version: string;
27
+ trustedStorage?: TrustedStorageLike;
16
28
  private db;
17
29
  private config;
18
30
  private initialized;
31
+ private stateCommitTableReady;
32
+ private trustedInitialized;
33
+ private commitQueue;
34
+ private walEnabled;
35
+ private walCheckpointIntervalMs?;
36
+ private walCheckpointTimer;
37
+ private walCheckpointPromise;
38
+ private _activeLambdaCount;
39
+ private closed;
19
40
  balance: IBalanceTable;
20
41
  account: IStateTable<IAccountState>;
21
42
  factory: IStateTable<IAssetFactoryState>;
@@ -52,30 +73,53 @@ declare class SqliteStateDB extends StateDB implements IStateDB {
52
73
  */
53
74
  private initSync;
54
75
  /**
55
- * Async initialization - runs migrations
76
+ * Async initialization - runs migrations and initializes trustedStorage if configured
56
77
  * Call this after constructor to ensure database schema is ready
57
78
  */
58
79
  initialize(): Promise<void>;
80
+ /**
81
+ * Run a WAL checkpoint (`PRAGMA wal_checkpoint(<mode>)`) against the SQLite database.
82
+ * No-op returning `{ busy: 0, log: 0, checkpointed: 0 }` when WAL mode is disabled.
83
+ */
84
+ runWalCheckpoint(mode?: 'PASSIVE' | 'FULL' | 'RESTART' | 'TRUNCATE'): Promise<{
85
+ busy: number;
86
+ log: number;
87
+ checkpointed: number;
88
+ }>;
89
+ private startWalCheckpointWorker;
90
+ private ensureStateCommitTable;
91
+ private ensureTrustedStorageInitialized;
92
+ /**
93
+ * Get the current and previous state commit hash tracked in SQLite StateDB.
94
+ *
95
+ * Note on threat model & performance:
96
+ * SQLite StateDB maintains an O(1) incremental commit-chain head (`_state_commit`)
97
+ * to detect snapshot rollback or crash desynchronization between `statedb` and
98
+ * `trustedStorage` without O(N) full-table scans on every transaction.
99
+ * End-to-end Data Availability, Merkle inclusion proofs, and corruption detection
100
+ * for RPC, Light Wallet, and Archive nodes are enforced by `@arcblock/ledger`
101
+ * checkpoints and self-verifying segments.
102
+ */
103
+ getCommitHash(executor?: Kysely<Database> | Transaction<Database>): Promise<{
104
+ currentHash: string;
105
+ prevHash: string;
106
+ }>;
107
+ private verifyTrustedHashInternal;
108
+ /**
109
+ * Verify that the current SQLite state commit hash matches the trusted storage record.
110
+ */
111
+ verifyTrustedHash(): Promise<void>;
112
+ private enqueueCommit;
59
113
  /**
60
114
  * Execute multiple operations within a database transaction
61
115
  * Provides retry logic for SQLite BUSY errors (lock conflicts)
62
116
  *
63
117
  * @param fn - Function receiving Kysely transaction object
64
- * @param options - Optional retry configuration
118
+ * @param options - Optional retry and trusted-hash verification configuration
65
119
  * @returns Result of the transaction function
66
- *
67
- * @example
68
- * ```typescript
69
- * await db.runAsLambda(async (txn) => {
70
- * await txn.insertInto('account').values({ ... }).execute();
71
- * await txn.updateTable('balance').set({ ... }).execute();
72
- * });
73
- * ```
74
120
  */
75
- runAsLambda<T>(fn: (txn: Transaction<Database>) => T | Promise<T>, options?: {
76
- retryLimit?: number;
77
- onCommit?: (commitHash?: string) => void | Promise<void>;
78
- }): Promise<T>;
121
+ runAsLambda<T>(fn: (txn: Transaction<Database>) => T | Promise<T>, options?: SqliteRunOptions): Promise<T>;
122
+ private executeRunAsLambda;
79
123
  /**
80
124
  * Reset all tables (for testing)
81
125
  */
@@ -90,4 +134,4 @@ declare class SqliteStateDB extends StateDB implements IStateDB {
90
134
  getKysely(): Kysely<Database>;
91
135
  }
92
136
  //#endregion
93
- export { SqliteStateDB as default };
137
+ export { SqliteRunOptions, SqliteStateDB as default };
package/lib/index.cjs CHANGED
@@ -6,6 +6,8 @@ const require_db = require('./db.cjs');
6
6
  var src_default = require_db.default;
7
7
 
8
8
  //#endregion
9
+ exports.DurableObjectSqliteDialect = require_kysely.DurableObjectSqliteDialect;
9
10
  exports.SqliteStateDB = require_db.default;
11
+ exports.createKysely = require_kysely.createKysely;
10
12
  exports.default = src_default;
11
13
  exports.getRawDatabase = require_kysely.getRawDatabase;
package/lib/index.d.cts CHANGED
@@ -1,4 +1,4 @@
1
1
  import { Database, SqliteOperationContext } from "./interfaces.cjs";
2
- import { SqliteConfig, getRawDatabase } from "./kysely.cjs";
2
+ import { DurableObjectSqliteDialect, DurableObjectSqliteDialectConfig, IDurableObjectSqlStorage, IDurableObjectSqlStorageCursor, SqliteConfig, createKysely, getRawDatabase } from "./kysely.cjs";
3
3
  import SqliteStateDB from "./db.cjs";
4
- export { type Database, type SqliteConfig, type SqliteOperationContext, SqliteStateDB, SqliteStateDB as default, getRawDatabase };
4
+ export { type Database, DurableObjectSqliteDialect, type DurableObjectSqliteDialectConfig, type IDurableObjectSqlStorage, type IDurableObjectSqlStorageCursor, type SqliteConfig, type SqliteOperationContext, SqliteStateDB, SqliteStateDB as default, createKysely, getRawDatabase };