@ocap/statedb-sqlite 1.31.9 → 1.32.1

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/db.d.mts CHANGED
@@ -5,12 +5,50 @@ import { Kysely, Transaction } from "kysely";
5
5
  import { IAccountState, IAssetFactoryState, IAssetState, IBalanceTable, IChainState, IDelegateState, IEvidenceState, IRollupBlock, IRollupTable, IStakeState, IStateDB, IStateTable, ITokenFactoryState, ITokenTable, ITrustedStorage, ITxState } from "@ocap/types";
6
6
 
7
7
  //#region src/db.d.ts
8
+ declare class StateCommitMismatchError extends Error {
9
+ readonly code = "STATE_COMMIT_MISMATCH";
10
+ readonly expectedCommitHash: string;
11
+ readonly actualCommitHash: string;
12
+ readonly seq: number;
13
+ readonly writeSetDigest: string;
14
+ constructor(params: {
15
+ expectedCommitHash: string;
16
+ actualCommitHash: string;
17
+ seq: number;
18
+ writeSetDigest: string;
19
+ });
20
+ }
21
+ interface SqliteBeforeCommitInfo {
22
+ commitHash: string;
23
+ prevHash: string;
24
+ seq: number;
25
+ writeSetDigest: string;
26
+ }
8
27
  interface SqliteRunOptions {
9
28
  retryLimit?: number;
10
29
  verifyHash?: boolean;
11
30
  cleanWorkingSet?: boolean;
12
31
  commitMessage?: string;
13
32
  context?: unknown;
33
+ /**
34
+ * Optional expected post-transaction stateCommitHash (#1710 follower replay safety).
35
+ * Verified inside the SQLite transaction BEFORE updating `_state_commit` or committing,
36
+ * so any mismatch atomically rolls back all pending writes in `statedb.sqlite`.
37
+ */
38
+ expectedCommitHash?: string;
39
+ /**
40
+ * When `true` (#1712 BFT replica speculative verification), computes `commitHash` (and checks
41
+ * `expectedCommitHash` if provided), invokes `onDryRunCommitHash`, and rolls back the SQLite
42
+ * transaction cleanly without persisting any state or updating `_state_commit`.
43
+ */
44
+ dryRun?: boolean;
45
+ onDryRunCommitHash?: (commitHash: string) => void;
46
+ /**
47
+ * Optional pre-commit hook (#1712 BFT leader 1-RTT QC collection) invoked inside the SQLite
48
+ * transaction after `_state_commit` is computed/updated and strictly BEFORE SQLite `COMMIT`.
49
+ * Throwing aborts and rolls back the entire SQLite transaction cleanly.
50
+ */
51
+ beforeCommit?: (info: SqliteBeforeCommitInfo) => void | Promise<void>;
14
52
  onCommit?: (commitHash?: string) => void | Promise<void>;
15
53
  }
16
54
  interface TrustedStorageLike extends ITrustedStorage {
@@ -36,6 +74,7 @@ declare class SqliteStateDB extends StateDB implements IStateDB {
36
74
  private walCheckpointTimer;
37
75
  private walCheckpointPromise;
38
76
  private _activeLambdaCount;
77
+ private activeDryRunSubLambda;
39
78
  private closed;
40
79
  private lastWriteSetDigest?;
41
80
  balance: IBalanceTable;
@@ -128,6 +167,28 @@ declare class SqliteStateDB extends StateDB implements IStateDB {
128
167
  * @returns Result of the transaction function
129
168
  */
130
169
  runAsLambda<T>(fn: (txn: Transaction<Database>) => T | Promise<T>, options?: SqliteRunOptions): Promise<T>;
170
+ /**
171
+ * Execute 1..N sequential steps inside a single rolled-back SQLite transaction (#1712 BFT replica verification),
172
+ * computing each step's exact `_state_commit` hash (and enforcing `expectedCommitHash` when provided) without
173
+ * persisting any writes to `statedb.sqlite` or `trusted.sqlite`.
174
+ */
175
+ runDryRunBatch(steps: Array<{
176
+ commitMessage?: string;
177
+ expectedCommitHash?: string;
178
+ fn: (txn: Transaction<Database>) => unknown | Promise<unknown>;
179
+ }>): Promise<{
180
+ commitHashes: string[];
181
+ finalCommitHash: string;
182
+ }>;
183
+ /**
184
+ * Execute an arbitrary multi-lambda session (supporting nested `OK` -> rollback -> `PERSISTED_FAILED`
185
+ * savepoint transitions) inside a single rolled-back SQLite transaction (#1712 BFT replica dry-run).
186
+ */
187
+ runWithinDryRunSession<T>(sessionFn: (runSubLambda: <R>(fn: (txn: Transaction<Database>) => R | Promise<R>, options?: SqliteRunOptions) => Promise<R>) => Promise<T>): Promise<{
188
+ result: T;
189
+ commitHashes: string[];
190
+ finalCommitHash: string | null;
191
+ }>;
131
192
  private executeRunAsLambda;
132
193
  /**
133
194
  * Reset all tables (for testing)
@@ -141,10 +202,14 @@ declare class SqliteStateDB extends StateDB implements IStateDB {
141
202
  * Get the canonical SHA-256 digest of the write-set from the most recently committed `runAsLambda` transaction.
142
203
  */
143
204
  getLastWriteSetDigest(): string | undefined;
205
+ /**
206
+ * Read the current `_state_commit.current_hash` from SQLite (`'GENESIS'` before first commit).
207
+ */
208
+ getCurrentCommitHash(): Promise<string>;
144
209
  /**
145
210
  * Get the underlying Kysely instance (for advanced operations)
146
211
  */
147
212
  getKysely(): Kysely<Database>;
148
213
  }
149
214
  //#endregion
150
- export { SqliteRunOptions, SqliteStateDB as default };
215
+ export { SqliteBeforeCommitInfo, SqliteRunOptions, StateCommitMismatchError, SqliteStateDB as default };
package/esm/db.mjs CHANGED
@@ -20,6 +20,23 @@ function isSqliteBusyError(err) {
20
20
  const msg = err instanceof Error ? err.message : String(err ?? "");
21
21
  return msg.includes("database is locked") || msg.includes("SQLITE_BUSY") || msg.includes("SQLITE_LOCKED");
22
22
  }
23
+ var StateCommitMismatchError = class extends Error {
24
+ constructor(params) {
25
+ super(`State commit hash mismatch at seq ${params.seq}: expected ${params.expectedCommitHash}, computed ${params.actualCommitHash}`);
26
+ this.code = "STATE_COMMIT_MISMATCH";
27
+ this.name = "StateCommitMismatchError";
28
+ this.expectedCommitHash = params.expectedCommitHash;
29
+ this.actualCommitHash = params.actualCommitHash;
30
+ this.seq = params.seq;
31
+ this.writeSetDigest = params.writeSetDigest;
32
+ }
33
+ };
34
+ var DryRunRollbackSignal = class {
35
+ constructor(result, commitHash) {
36
+ this.result = result;
37
+ this.commitHash = commitHash;
38
+ }
39
+ };
23
40
  /**
24
41
  * SQLite StateDB Implementation
25
42
  * Uses SQLite via Kysely as the storage backend
@@ -51,6 +68,7 @@ var SqliteStateDB = class extends StateDB {
51
68
  this.walCheckpointTimer = null;
52
69
  this.walCheckpointPromise = null;
53
70
  this._activeLambdaCount = 0;
71
+ this.activeDryRunSubLambda = null;
54
72
  this.closed = false;
55
73
  this.name = name;
56
74
  this.version = version;
@@ -417,9 +435,160 @@ var SqliteStateDB = class extends StateDB {
417
435
  * @returns Result of the transaction function
418
436
  */
419
437
  async runAsLambda(fn, options = {}) {
438
+ if (this.activeDryRunSubLambda) return this.activeDryRunSubLambda(fn, options);
420
439
  if (this.trustedStorage) return this.enqueueCommit(() => this.executeRunAsLambda(fn, options));
421
440
  return this.executeRunAsLambda(fn, options);
422
441
  }
442
+ /**
443
+ * Execute 1..N sequential steps inside a single rolled-back SQLite transaction (#1712 BFT replica verification),
444
+ * computing each step's exact `_state_commit` hash (and enforcing `expectedCommitHash` when provided) without
445
+ * persisting any writes to `statedb.sqlite` or `trusted.sqlite`.
446
+ */
447
+ async runDryRunBatch(steps) {
448
+ const run = async () => {
449
+ if (this.config.readonly) throw new Error("Cannot execute runDryRunBatch on a SqliteStateDB opened in readonly mode");
450
+ if (!this.stateCommitTableReady) await this.ensureStateCommitTable();
451
+ if (steps.length === 0) return {
452
+ commitHashes: [],
453
+ finalCommitHash: (await this.getCommitHash()).currentHash
454
+ };
455
+ this._activeLambdaCount++;
456
+ try {
457
+ await this.db.transaction().execute(async (rawTxn) => {
458
+ const initial = await sql`
459
+ SELECT "current_hash", "seq" FROM "_state_commit" WHERE "id" = 1
460
+ `.execute(rawTxn);
461
+ let prevHash = initial.rows[0]?.current_hash || "GENESIS";
462
+ let seq = Number(initial.rows[0]?.seq || 0);
463
+ const commitHashes = [];
464
+ for (const step of steps) {
465
+ const tracker = new WriteSetTracker();
466
+ const trackedTxn = attachWriteSetTracker(rawTxn, tracker);
467
+ const txResult = await step.fn(trackedTxn);
468
+ const nextSeq = seq + 1;
469
+ const msg = step.commitMessage || txResult?.hash || "commit";
470
+ const writeSetDigest = tracker.computeDigest();
471
+ const nextHash = computeStateCommitHash({
472
+ prevHash,
473
+ seq: nextSeq,
474
+ msg,
475
+ writeSetDigest
476
+ });
477
+ if (step.expectedCommitHash !== void 0) {
478
+ const expectedNormalized = step.expectedCommitHash.trim().replace(/^0x/i, "").toLowerCase();
479
+ if (!expectedNormalized || nextHash.toLowerCase() !== expectedNormalized) throw new StateCommitMismatchError({
480
+ expectedCommitHash: step.expectedCommitHash,
481
+ actualCommitHash: nextHash,
482
+ seq: nextSeq,
483
+ writeSetDigest
484
+ });
485
+ }
486
+ prevHash = nextHash;
487
+ seq = nextSeq;
488
+ commitHashes.push(nextHash);
489
+ }
490
+ throw new DryRunRollbackSignal({
491
+ commitHashes,
492
+ finalCommitHash: prevHash
493
+ }, prevHash);
494
+ });
495
+ } catch (err) {
496
+ if (err instanceof DryRunRollbackSignal) return err.result;
497
+ throw err;
498
+ } finally {
499
+ this._activeLambdaCount--;
500
+ }
501
+ throw new Error("Unreachable: runDryRunBatch must exit via DryRunRollbackSignal");
502
+ };
503
+ if (this.trustedStorage) return this.enqueueCommit(run);
504
+ return run();
505
+ }
506
+ /**
507
+ * Execute an arbitrary multi-lambda session (supporting nested `OK` -> rollback -> `PERSISTED_FAILED`
508
+ * savepoint transitions) inside a single rolled-back SQLite transaction (#1712 BFT replica dry-run).
509
+ */
510
+ async runWithinDryRunSession(sessionFn) {
511
+ const run = async () => {
512
+ if (this.config.readonly) throw new Error("Cannot execute runWithinDryRunSession on a SqliteStateDB opened in readonly mode");
513
+ if (!this.stateCommitTableReady) await this.ensureStateCommitTable();
514
+ if (this.trustedStorage) {
515
+ await this.ensureTrustedStorageInitialized();
516
+ await this.verifyTrustedHashInternal(false);
517
+ }
518
+ this._activeLambdaCount++;
519
+ try {
520
+ await this.db.transaction().execute(async (rawTxn) => {
521
+ const commitHashes = [];
522
+ let savepointCounter = 0;
523
+ const runSubLambda = async (innerFn, innerOpts = {}) => {
524
+ const spName = `dry_sp_${++savepointCounter}`;
525
+ await sql.raw(`SAVEPOINT ${spName}`).execute(rawTxn);
526
+ try {
527
+ const tracker = new WriteSetTracker();
528
+ const txResult = await innerFn(attachWriteSetTracker(rawTxn, tracker));
529
+ const row = (await sql`
530
+ SELECT current_hash, seq FROM _state_commit WHERE id = 1
531
+ `.execute(rawTxn)).rows[0];
532
+ const prevHash = row?.current_hash || "GENESIS";
533
+ const nextSeq = Number(row?.seq || 0) + 1;
534
+ const msg = innerOpts.commitMessage || txResult?.hash || "commit";
535
+ const writeSetDigest = tracker.computeDigest();
536
+ const nextHash = computeStateCommitHash({
537
+ prevHash,
538
+ seq: nextSeq,
539
+ msg,
540
+ writeSetDigest
541
+ });
542
+ if (innerOpts.expectedCommitHash !== void 0) {
543
+ const expectedNormalized = innerOpts.expectedCommitHash.trim().replace(/^0x/i, "").toLowerCase();
544
+ if (!expectedNormalized || nextHash.toLowerCase() !== expectedNormalized) throw new StateCommitMismatchError({
545
+ expectedCommitHash: innerOpts.expectedCommitHash,
546
+ actualCommitHash: nextHash,
547
+ seq: nextSeq,
548
+ writeSetDigest
549
+ });
550
+ }
551
+ await sql`
552
+ UPDATE _state_commit
553
+ SET current_hash = ${nextHash}, prev_hash = ${prevHash}, seq = ${nextSeq}, msg = ${msg}
554
+ WHERE id = 1
555
+ `.execute(rawTxn);
556
+ await sql.raw(`RELEASE SAVEPOINT ${spName}`).execute(rawTxn);
557
+ commitHashes.push(nextHash);
558
+ innerOpts.onDryRunCommitHash?.(nextHash);
559
+ if (innerOpts.onCommit) await innerOpts.onCommit(nextHash);
560
+ return txResult;
561
+ } catch (subErr) {
562
+ await sql.raw(`ROLLBACK TO SAVEPOINT ${spName}`).execute(rawTxn).catch(() => void 0);
563
+ await sql.raw(`RELEASE SAVEPOINT ${spName}`).execute(rawTxn).catch(() => void 0);
564
+ throw subErr;
565
+ }
566
+ };
567
+ this.activeDryRunSubLambda = runSubLambda;
568
+ let sessionResult;
569
+ try {
570
+ sessionResult = await sessionFn(runSubLambda);
571
+ } finally {
572
+ this.activeDryRunSubLambda = null;
573
+ }
574
+ const finalCommitHash = commitHashes.length > 0 ? commitHashes[commitHashes.length - 1] : null;
575
+ throw new DryRunRollbackSignal({
576
+ result: sessionResult,
577
+ commitHashes,
578
+ finalCommitHash
579
+ }, finalCommitHash ?? "");
580
+ });
581
+ } catch (err) {
582
+ if (err instanceof DryRunRollbackSignal) return err.result;
583
+ throw err;
584
+ } finally {
585
+ this._activeLambdaCount--;
586
+ }
587
+ throw new Error("Unreachable: runWithinDryRunSession must exit via DryRunRollbackSignal");
588
+ };
589
+ if (this.trustedStorage) return this.enqueueCommit(run);
590
+ return run();
591
+ }
423
592
  async executeRunAsLambda(fn, options = {}) {
424
593
  if (this.config.readonly) throw new Error("Cannot execute runAsLambda on a SqliteStateDB opened in readonly mode");
425
594
  const { retryLimit = 5, verifyHash = false, commitMessage } = options;
@@ -447,27 +616,47 @@ var SqliteStateDB = class extends StateDB {
447
616
  result = await this.db.transaction().execute(async (rawTxn) => {
448
617
  const tracker = new WriteSetTracker();
449
618
  const txResult = await fn(attachWriteSetTracker(rawTxn, tracker));
619
+ const writeSetDigest = tracker.computeDigest();
620
+ committedWriteSetDigest = writeSetDigest;
621
+ if (tracker.isEmpty()) return txResult;
450
622
  const row = (await sql`
451
623
  SELECT "current_hash", "seq" FROM "_state_commit" WHERE "id" = 1
452
624
  `.execute(rawTxn)).rows[0];
453
625
  const prevHash = row?.current_hash || "GENESIS";
454
626
  const nextSeq = Number(row?.seq || 0) + 1;
455
627
  const msg = commitMessage || txResult?.hash || "commit";
456
- const writeSetDigest = tracker.computeDigest();
457
628
  const nextHash = computeStateCommitHash({
458
629
  prevHash,
459
630
  seq: nextSeq,
460
631
  msg,
461
632
  writeSetDigest
462
633
  });
634
+ if (options.expectedCommitHash !== void 0) {
635
+ const expectedNormalized = options.expectedCommitHash.trim().replace(/^0x/i, "").toLowerCase();
636
+ if (!expectedNormalized || nextHash.toLowerCase() !== expectedNormalized) throw new StateCommitMismatchError({
637
+ expectedCommitHash: options.expectedCommitHash,
638
+ actualCommitHash: nextHash,
639
+ seq: nextSeq,
640
+ writeSetDigest
641
+ });
642
+ }
643
+ if (options.dryRun === true) {
644
+ options.onDryRunCommitHash?.(nextHash);
645
+ throw new DryRunRollbackSignal(txResult, nextHash);
646
+ }
463
647
  await sql`
464
648
  UPDATE "_state_commit"
465
649
  SET "current_hash" = ${nextHash}, "prev_hash" = ${prevHash}, "seq" = ${nextSeq}, "msg" = ${msg}
466
650
  WHERE "id" = 1
467
651
  `.execute(rawTxn);
652
+ if (options.beforeCommit) await options.beforeCommit({
653
+ commitHash: nextHash,
654
+ prevHash,
655
+ seq: nextSeq,
656
+ writeSetDigest
657
+ });
468
658
  previousHash = prevHash;
469
659
  committedHash = nextHash;
470
- committedWriteSetDigest = writeSetDigest;
471
660
  return txResult;
472
661
  });
473
662
  } finally {
@@ -481,6 +670,7 @@ var SqliteStateDB = class extends StateDB {
481
670
  opCtx.events.push(...savedEvents);
482
671
  }
483
672
  if (opCtx?.timer?.stateDbCounters && savedTimerCounters !== void 0) Object.assign(opCtx.timer.stateDbCounters, savedTimerCounters);
673
+ if (err instanceof DryRunRollbackSignal) return err.result;
484
674
  lastError = err;
485
675
  if (!isSqliteBusyError(err)) throw err;
486
676
  if (attempt < retryLimit) await new Promise((r) => setTimeout(r, 10 * 2 ** attempt));
@@ -528,6 +718,7 @@ var SqliteStateDB = class extends StateDB {
528
718
  }
529
719
  if (this.walCheckpointPromise) await this.walCheckpointPromise.catch(() => void 0);
530
720
  await this.commitQueue;
721
+ if (this.walEnabled && !this.config.readonly) await sql`PRAGMA wal_checkpoint(PASSIVE)`.execute(this.db).catch(() => void 0);
531
722
  await this.db.destroy();
532
723
  if (this.trustedStorage && typeof this.trustedStorage.destroy === "function" && this.trustedStorage.filename !== ":memory:") await this.trustedStorage.destroy();
533
724
  }
@@ -538,6 +729,19 @@ var SqliteStateDB = class extends StateDB {
538
729
  return this.lastWriteSetDigest;
539
730
  }
540
731
  /**
732
+ * Read the current `_state_commit.current_hash` from SQLite (`'GENESIS'` before first commit).
733
+ */
734
+ async getCurrentCommitHash() {
735
+ if (!this.stateCommitTableReady && !this.config.readonly) await this.ensureStateCommitTable();
736
+ try {
737
+ return (await sql`
738
+ SELECT "current_hash" FROM "_state_commit" WHERE "id" = 1
739
+ `.execute(this.db)).rows[0]?.current_hash || "GENESIS";
740
+ } catch {
741
+ return "GENESIS";
742
+ }
743
+ }
744
+ /**
541
745
  * Get the underlying Kysely instance (for advanced operations)
542
746
  */
543
747
  getKysely() {
@@ -547,4 +751,4 @@ var SqliteStateDB = class extends StateDB {
547
751
  var db_default = SqliteStateDB;
548
752
 
549
753
  //#endregion
550
- export { db_default as default };
754
+ export { StateCommitMismatchError, db_default as default };
package/esm/index.d.mts CHANGED
@@ -1,9 +1,9 @@
1
1
  import { Database, SqliteOperationContext } from "./interfaces.mjs";
2
2
  import { DurableObjectSqliteDialect, DurableObjectSqliteDialectConfig, IDurableObjectSqlStorage, IDurableObjectSqlStorageCursor, SqliteConfig, createKysely, getRawDatabase } from "./kysely.mjs";
3
- import SqliteStateDB from "./db.mjs";
3
+ import SqliteStateDB, { SqliteBeforeCommitInfo, SqliteRunOptions, StateCommitMismatchError } from "./db.mjs";
4
4
  import { ChainStateAuditReport, InvariantSeverity, InvariantViolation, ReconcileAction, ReconcileOptions, ReconcileResult, assertSqliteStateDb, reconcileChainState, verifyChainStateInvariants } from "./reconcile.mjs";
5
5
  import { ApplyTombstoneCleanupOptions, TombstoneBalanceRow, TombstoneCleanupApplyResult, TombstoneCleanupPlan, TombstoneTokenSummary, applyTombstoneBalanceCleanup, compareUpdatedAtTimestamps, computeTombstoneCleanupPlanDigest, extractContextUpdatedAt, isBalanceTimestampNotAfterAccount, planTombstoneBalanceCleanup } from "./tombstone-cleanup.mjs";
6
6
  import { _003_token_charter_assets_d_exports } from "./migrations/003-token-charter-assets.mjs";
7
7
  import { rollbackMigrations, runMigrations } from "./migrations/index.mjs";
8
- import { IStateCommitStepInput, IStateWriteRecord, STATE_COMMIT_DOMAIN_V2, WriteSetTracker, canonicalizeStateJson, canonicalizeStateValue, computeStateCommitHash, computeStateWriteSetDigest, formatCanonicalPrimaryKey, isTrackedRawMutatingSql } from "./write-set.mjs";
9
- export { type ApplyTombstoneCleanupOptions, type ChainStateAuditReport, type Database, DurableObjectSqliteDialect, type DurableObjectSqliteDialectConfig, type IDurableObjectSqlStorage, type IDurableObjectSqlStorageCursor, type IStateCommitStepInput, type IStateWriteRecord, type InvariantSeverity, type InvariantViolation, type ReconcileAction, type ReconcileOptions, type ReconcileResult, STATE_COMMIT_DOMAIN_V2, type SqliteConfig, type SqliteOperationContext, SqliteStateDB, SqliteStateDB as default, type TombstoneBalanceRow, type TombstoneCleanupApplyResult, type TombstoneCleanupPlan, type TombstoneTokenSummary, WriteSetTracker, applyTombstoneBalanceCleanup, assertSqliteStateDb, canonicalizeStateJson, canonicalizeStateValue, compareUpdatedAtTimestamps, computeStateCommitHash, computeStateWriteSetDigest, computeTombstoneCleanupPlanDigest, createKysely, extractContextUpdatedAt, formatCanonicalPrimaryKey, getRawDatabase, isBalanceTimestampNotAfterAccount, isTrackedRawMutatingSql, planTombstoneBalanceCleanup, reconcileChainState, rollbackMigrations, runMigrations, _003_token_charter_assets_d_exports as tokenCharterAssets, verifyChainStateInvariants };
8
+ import { IStateCommitStepInput, IStateWriteRecord, STATE_COMMIT_DOMAIN_V2, WriteSetTracker, canonicalizeStateJson, canonicalizeStateValue, computeStateCommitHash, computeStateWriteSetDigest, formatCanonicalPrimaryKey, getWriteSetTracker, isTrackedRawMutatingSql } from "./write-set.mjs";
9
+ export { type ApplyTombstoneCleanupOptions, type ChainStateAuditReport, type Database, DurableObjectSqliteDialect, type DurableObjectSqliteDialectConfig, type IDurableObjectSqlStorage, type IDurableObjectSqlStorageCursor, type IStateCommitStepInput, type IStateWriteRecord, type InvariantSeverity, type InvariantViolation, type ReconcileAction, type ReconcileOptions, type ReconcileResult, STATE_COMMIT_DOMAIN_V2, type SqliteBeforeCommitInfo, type SqliteConfig, type SqliteOperationContext, type SqliteRunOptions, SqliteStateDB, SqliteStateDB as default, StateCommitMismatchError, type TombstoneBalanceRow, type TombstoneCleanupApplyResult, type TombstoneCleanupPlan, type TombstoneTokenSummary, WriteSetTracker, applyTombstoneBalanceCleanup, assertSqliteStateDb, canonicalizeStateJson, canonicalizeStateValue, compareUpdatedAtTimestamps, computeStateCommitHash, computeStateWriteSetDigest, computeTombstoneCleanupPlanDigest, createKysely, extractContextUpdatedAt, formatCanonicalPrimaryKey, getRawDatabase, getWriteSetTracker, isBalanceTimestampNotAfterAccount, isTrackedRawMutatingSql, planTombstoneBalanceCleanup, reconcileChainState, rollbackMigrations, runMigrations, _003_token_charter_assets_d_exports as tokenCharterAssets, verifyChainStateInvariants };
package/esm/index.mjs CHANGED
@@ -1,8 +1,8 @@
1
1
  import { DurableObjectSqliteDialect, createKysely, getRawDatabase } from "./kysely.mjs";
2
2
  import { _003_token_charter_assets_exports } from "./migrations/003-token-charter-assets.mjs";
3
3
  import { rollbackMigrations, runMigrations } from "./migrations/index.mjs";
4
- import { STATE_COMMIT_DOMAIN_V2, WriteSetTracker, canonicalizeStateJson, canonicalizeStateValue, computeStateCommitHash, computeStateWriteSetDigest, formatCanonicalPrimaryKey, isTrackedRawMutatingSql } from "./write-set.mjs";
5
- import db_default from "./db.mjs";
4
+ import { STATE_COMMIT_DOMAIN_V2, WriteSetTracker, canonicalizeStateJson, canonicalizeStateValue, computeStateCommitHash, computeStateWriteSetDigest, formatCanonicalPrimaryKey, getWriteSetTracker, isTrackedRawMutatingSql } from "./write-set.mjs";
5
+ import db_default, { StateCommitMismatchError } from "./db.mjs";
6
6
  import { assertSqliteStateDb, reconcileChainState, verifyChainStateInvariants } from "./reconcile.mjs";
7
7
  import { applyTombstoneBalanceCleanup, compareUpdatedAtTimestamps, computeTombstoneCleanupPlanDigest, extractContextUpdatedAt, isBalanceTimestampNotAfterAccount, planTombstoneBalanceCleanup } from "./tombstone-cleanup.mjs";
8
8
 
@@ -10,4 +10,4 @@ import { applyTombstoneBalanceCleanup, compareUpdatedAtTimestamps, computeTombst
10
10
  var src_default = db_default;
11
11
 
12
12
  //#endregion
13
- export { DurableObjectSqliteDialect, STATE_COMMIT_DOMAIN_V2, db_default as SqliteStateDB, WriteSetTracker, applyTombstoneBalanceCleanup, assertSqliteStateDb, canonicalizeStateJson, canonicalizeStateValue, compareUpdatedAtTimestamps, computeStateCommitHash, computeStateWriteSetDigest, computeTombstoneCleanupPlanDigest, createKysely, src_default as default, extractContextUpdatedAt, formatCanonicalPrimaryKey, getRawDatabase, isBalanceTimestampNotAfterAccount, isTrackedRawMutatingSql, planTombstoneBalanceCleanup, reconcileChainState, rollbackMigrations, runMigrations, _003_token_charter_assets_exports as tokenCharterAssets, verifyChainStateInvariants };
13
+ export { DurableObjectSqliteDialect, STATE_COMMIT_DOMAIN_V2, db_default as SqliteStateDB, StateCommitMismatchError, WriteSetTracker, applyTombstoneBalanceCleanup, assertSqliteStateDb, canonicalizeStateJson, canonicalizeStateValue, compareUpdatedAtTimestamps, computeStateCommitHash, computeStateWriteSetDigest, computeTombstoneCleanupPlanDigest, createKysely, src_default as default, extractContextUpdatedAt, formatCanonicalPrimaryKey, getRawDatabase, getWriteSetTracker, isBalanceTimestampNotAfterAccount, isTrackedRawMutatingSql, planTombstoneBalanceCleanup, reconcileChainState, rollbackMigrations, runMigrations, _003_token_charter_assets_exports as tokenCharterAssets, verifyChainStateInvariants };
@@ -128,6 +128,7 @@ var SqliteTable = class SqliteTable extends StateDBTable {
128
128
  }
129
129
  delete result.$loki;
130
130
  delete result.meta;
131
+ delete result._retrievedAt;
131
132
  return result;
132
133
  }
133
134
  async _create(key, attrs = {}, context) {
@@ -56,6 +56,7 @@ declare class WriteSetTracker {
56
56
  recordDelete(table: string, key: string): void;
57
57
  recordReset(table: string): void;
58
58
  recordRaw(sqlText: string, parameters?: readonly unknown[]): void;
59
+ isEmpty(): boolean;
59
60
  getWrites(): readonly IStateWriteRecord[];
60
61
  computeDigest(): string;
61
62
  }
package/esm/write-set.mjs CHANGED
@@ -242,7 +242,7 @@ var WriteSetTracker = class {
242
242
  op: "put",
243
243
  table,
244
244
  key,
245
- value
245
+ value: canonicalizeStateValue(value)
246
246
  });
247
247
  }
248
248
  recordDelete(table, key) {
@@ -262,9 +262,12 @@ var WriteSetTracker = class {
262
262
  this.writes.push({
263
263
  op: "raw",
264
264
  sql: sqlText,
265
- parameters
265
+ parameters: Array.isArray(parameters) ? parameters.map((p) => canonicalizeStateValue(p)) : parameters
266
266
  });
267
267
  }
268
+ isEmpty() {
269
+ return this.writes.length === 0;
270
+ }
268
271
  getWrites() {
269
272
  return this.writes;
270
273
  }
package/lib/db.cjs CHANGED
@@ -22,6 +22,23 @@ function isSqliteBusyError(err) {
22
22
  const msg = err instanceof Error ? err.message : String(err ?? "");
23
23
  return msg.includes("database is locked") || msg.includes("SQLITE_BUSY") || msg.includes("SQLITE_LOCKED");
24
24
  }
25
+ var StateCommitMismatchError = class extends Error {
26
+ constructor(params) {
27
+ super(`State commit hash mismatch at seq ${params.seq}: expected ${params.expectedCommitHash}, computed ${params.actualCommitHash}`);
28
+ this.code = "STATE_COMMIT_MISMATCH";
29
+ this.name = "StateCommitMismatchError";
30
+ this.expectedCommitHash = params.expectedCommitHash;
31
+ this.actualCommitHash = params.actualCommitHash;
32
+ this.seq = params.seq;
33
+ this.writeSetDigest = params.writeSetDigest;
34
+ }
35
+ };
36
+ var DryRunRollbackSignal = class {
37
+ constructor(result, commitHash) {
38
+ this.result = result;
39
+ this.commitHash = commitHash;
40
+ }
41
+ };
25
42
  /**
26
43
  * SQLite StateDB Implementation
27
44
  * Uses SQLite via Kysely as the storage backend
@@ -53,6 +70,7 @@ var SqliteStateDB = class extends _ocap_statedb.StateDB {
53
70
  this.walCheckpointTimer = null;
54
71
  this.walCheckpointPromise = null;
55
72
  this._activeLambdaCount = 0;
73
+ this.activeDryRunSubLambda = null;
56
74
  this.closed = false;
57
75
  this.name = name;
58
76
  this.version = version;
@@ -419,9 +437,160 @@ var SqliteStateDB = class extends _ocap_statedb.StateDB {
419
437
  * @returns Result of the transaction function
420
438
  */
421
439
  async runAsLambda(fn, options = {}) {
440
+ if (this.activeDryRunSubLambda) return this.activeDryRunSubLambda(fn, options);
422
441
  if (this.trustedStorage) return this.enqueueCommit(() => this.executeRunAsLambda(fn, options));
423
442
  return this.executeRunAsLambda(fn, options);
424
443
  }
444
+ /**
445
+ * Execute 1..N sequential steps inside a single rolled-back SQLite transaction (#1712 BFT replica verification),
446
+ * computing each step's exact `_state_commit` hash (and enforcing `expectedCommitHash` when provided) without
447
+ * persisting any writes to `statedb.sqlite` or `trusted.sqlite`.
448
+ */
449
+ async runDryRunBatch(steps) {
450
+ const run = async () => {
451
+ if (this.config.readonly) throw new Error("Cannot execute runDryRunBatch on a SqliteStateDB opened in readonly mode");
452
+ if (!this.stateCommitTableReady) await this.ensureStateCommitTable();
453
+ if (steps.length === 0) return {
454
+ commitHashes: [],
455
+ finalCommitHash: (await this.getCommitHash()).currentHash
456
+ };
457
+ this._activeLambdaCount++;
458
+ try {
459
+ await this.db.transaction().execute(async (rawTxn) => {
460
+ const initial = await kysely.sql`
461
+ SELECT "current_hash", "seq" FROM "_state_commit" WHERE "id" = 1
462
+ `.execute(rawTxn);
463
+ let prevHash = initial.rows[0]?.current_hash || "GENESIS";
464
+ let seq = Number(initial.rows[0]?.seq || 0);
465
+ const commitHashes = [];
466
+ for (const step of steps) {
467
+ const tracker = new require_write_set.WriteSetTracker();
468
+ const trackedTxn = require_write_set.attachWriteSetTracker(rawTxn, tracker);
469
+ const txResult = await step.fn(trackedTxn);
470
+ const nextSeq = seq + 1;
471
+ const msg = step.commitMessage || txResult?.hash || "commit";
472
+ const writeSetDigest = tracker.computeDigest();
473
+ const nextHash = require_write_set.computeStateCommitHash({
474
+ prevHash,
475
+ seq: nextSeq,
476
+ msg,
477
+ writeSetDigest
478
+ });
479
+ if (step.expectedCommitHash !== void 0) {
480
+ const expectedNormalized = step.expectedCommitHash.trim().replace(/^0x/i, "").toLowerCase();
481
+ if (!expectedNormalized || nextHash.toLowerCase() !== expectedNormalized) throw new StateCommitMismatchError({
482
+ expectedCommitHash: step.expectedCommitHash,
483
+ actualCommitHash: nextHash,
484
+ seq: nextSeq,
485
+ writeSetDigest
486
+ });
487
+ }
488
+ prevHash = nextHash;
489
+ seq = nextSeq;
490
+ commitHashes.push(nextHash);
491
+ }
492
+ throw new DryRunRollbackSignal({
493
+ commitHashes,
494
+ finalCommitHash: prevHash
495
+ }, prevHash);
496
+ });
497
+ } catch (err) {
498
+ if (err instanceof DryRunRollbackSignal) return err.result;
499
+ throw err;
500
+ } finally {
501
+ this._activeLambdaCount--;
502
+ }
503
+ throw new Error("Unreachable: runDryRunBatch must exit via DryRunRollbackSignal");
504
+ };
505
+ if (this.trustedStorage) return this.enqueueCommit(run);
506
+ return run();
507
+ }
508
+ /**
509
+ * Execute an arbitrary multi-lambda session (supporting nested `OK` -> rollback -> `PERSISTED_FAILED`
510
+ * savepoint transitions) inside a single rolled-back SQLite transaction (#1712 BFT replica dry-run).
511
+ */
512
+ async runWithinDryRunSession(sessionFn) {
513
+ const run = async () => {
514
+ if (this.config.readonly) throw new Error("Cannot execute runWithinDryRunSession on a SqliteStateDB opened in readonly mode");
515
+ if (!this.stateCommitTableReady) await this.ensureStateCommitTable();
516
+ if (this.trustedStorage) {
517
+ await this.ensureTrustedStorageInitialized();
518
+ await this.verifyTrustedHashInternal(false);
519
+ }
520
+ this._activeLambdaCount++;
521
+ try {
522
+ await this.db.transaction().execute(async (rawTxn) => {
523
+ const commitHashes = [];
524
+ let savepointCounter = 0;
525
+ const runSubLambda = async (innerFn, innerOpts = {}) => {
526
+ const spName = `dry_sp_${++savepointCounter}`;
527
+ await kysely.sql.raw(`SAVEPOINT ${spName}`).execute(rawTxn);
528
+ try {
529
+ const tracker = new require_write_set.WriteSetTracker();
530
+ const txResult = await innerFn(require_write_set.attachWriteSetTracker(rawTxn, tracker));
531
+ const row = (await kysely.sql`
532
+ SELECT current_hash, seq FROM _state_commit WHERE id = 1
533
+ `.execute(rawTxn)).rows[0];
534
+ const prevHash = row?.current_hash || "GENESIS";
535
+ const nextSeq = Number(row?.seq || 0) + 1;
536
+ const msg = innerOpts.commitMessage || txResult?.hash || "commit";
537
+ const writeSetDigest = tracker.computeDigest();
538
+ const nextHash = require_write_set.computeStateCommitHash({
539
+ prevHash,
540
+ seq: nextSeq,
541
+ msg,
542
+ writeSetDigest
543
+ });
544
+ if (innerOpts.expectedCommitHash !== void 0) {
545
+ const expectedNormalized = innerOpts.expectedCommitHash.trim().replace(/^0x/i, "").toLowerCase();
546
+ if (!expectedNormalized || nextHash.toLowerCase() !== expectedNormalized) throw new StateCommitMismatchError({
547
+ expectedCommitHash: innerOpts.expectedCommitHash,
548
+ actualCommitHash: nextHash,
549
+ seq: nextSeq,
550
+ writeSetDigest
551
+ });
552
+ }
553
+ await kysely.sql`
554
+ UPDATE _state_commit
555
+ SET current_hash = ${nextHash}, prev_hash = ${prevHash}, seq = ${nextSeq}, msg = ${msg}
556
+ WHERE id = 1
557
+ `.execute(rawTxn);
558
+ await kysely.sql.raw(`RELEASE SAVEPOINT ${spName}`).execute(rawTxn);
559
+ commitHashes.push(nextHash);
560
+ innerOpts.onDryRunCommitHash?.(nextHash);
561
+ if (innerOpts.onCommit) await innerOpts.onCommit(nextHash);
562
+ return txResult;
563
+ } catch (subErr) {
564
+ await kysely.sql.raw(`ROLLBACK TO SAVEPOINT ${spName}`).execute(rawTxn).catch(() => void 0);
565
+ await kysely.sql.raw(`RELEASE SAVEPOINT ${spName}`).execute(rawTxn).catch(() => void 0);
566
+ throw subErr;
567
+ }
568
+ };
569
+ this.activeDryRunSubLambda = runSubLambda;
570
+ let sessionResult;
571
+ try {
572
+ sessionResult = await sessionFn(runSubLambda);
573
+ } finally {
574
+ this.activeDryRunSubLambda = null;
575
+ }
576
+ const finalCommitHash = commitHashes.length > 0 ? commitHashes[commitHashes.length - 1] : null;
577
+ throw new DryRunRollbackSignal({
578
+ result: sessionResult,
579
+ commitHashes,
580
+ finalCommitHash
581
+ }, finalCommitHash ?? "");
582
+ });
583
+ } catch (err) {
584
+ if (err instanceof DryRunRollbackSignal) return err.result;
585
+ throw err;
586
+ } finally {
587
+ this._activeLambdaCount--;
588
+ }
589
+ throw new Error("Unreachable: runWithinDryRunSession must exit via DryRunRollbackSignal");
590
+ };
591
+ if (this.trustedStorage) return this.enqueueCommit(run);
592
+ return run();
593
+ }
425
594
  async executeRunAsLambda(fn, options = {}) {
426
595
  if (this.config.readonly) throw new Error("Cannot execute runAsLambda on a SqliteStateDB opened in readonly mode");
427
596
  const { retryLimit = 5, verifyHash = false, commitMessage } = options;
@@ -449,27 +618,47 @@ var SqliteStateDB = class extends _ocap_statedb.StateDB {
449
618
  result = await this.db.transaction().execute(async (rawTxn) => {
450
619
  const tracker = new require_write_set.WriteSetTracker();
451
620
  const txResult = await fn(require_write_set.attachWriteSetTracker(rawTxn, tracker));
621
+ const writeSetDigest = tracker.computeDigest();
622
+ committedWriteSetDigest = writeSetDigest;
623
+ if (tracker.isEmpty()) return txResult;
452
624
  const row = (await kysely.sql`
453
625
  SELECT "current_hash", "seq" FROM "_state_commit" WHERE "id" = 1
454
626
  `.execute(rawTxn)).rows[0];
455
627
  const prevHash = row?.current_hash || "GENESIS";
456
628
  const nextSeq = Number(row?.seq || 0) + 1;
457
629
  const msg = commitMessage || txResult?.hash || "commit";
458
- const writeSetDigest = tracker.computeDigest();
459
630
  const nextHash = require_write_set.computeStateCommitHash({
460
631
  prevHash,
461
632
  seq: nextSeq,
462
633
  msg,
463
634
  writeSetDigest
464
635
  });
636
+ if (options.expectedCommitHash !== void 0) {
637
+ const expectedNormalized = options.expectedCommitHash.trim().replace(/^0x/i, "").toLowerCase();
638
+ if (!expectedNormalized || nextHash.toLowerCase() !== expectedNormalized) throw new StateCommitMismatchError({
639
+ expectedCommitHash: options.expectedCommitHash,
640
+ actualCommitHash: nextHash,
641
+ seq: nextSeq,
642
+ writeSetDigest
643
+ });
644
+ }
645
+ if (options.dryRun === true) {
646
+ options.onDryRunCommitHash?.(nextHash);
647
+ throw new DryRunRollbackSignal(txResult, nextHash);
648
+ }
465
649
  await kysely.sql`
466
650
  UPDATE "_state_commit"
467
651
  SET "current_hash" = ${nextHash}, "prev_hash" = ${prevHash}, "seq" = ${nextSeq}, "msg" = ${msg}
468
652
  WHERE "id" = 1
469
653
  `.execute(rawTxn);
654
+ if (options.beforeCommit) await options.beforeCommit({
655
+ commitHash: nextHash,
656
+ prevHash,
657
+ seq: nextSeq,
658
+ writeSetDigest
659
+ });
470
660
  previousHash = prevHash;
471
661
  committedHash = nextHash;
472
- committedWriteSetDigest = writeSetDigest;
473
662
  return txResult;
474
663
  });
475
664
  } finally {
@@ -483,6 +672,7 @@ var SqliteStateDB = class extends _ocap_statedb.StateDB {
483
672
  opCtx.events.push(...savedEvents);
484
673
  }
485
674
  if (opCtx?.timer?.stateDbCounters && savedTimerCounters !== void 0) Object.assign(opCtx.timer.stateDbCounters, savedTimerCounters);
675
+ if (err instanceof DryRunRollbackSignal) return err.result;
486
676
  lastError = err;
487
677
  if (!isSqliteBusyError(err)) throw err;
488
678
  if (attempt < retryLimit) await new Promise((r) => setTimeout(r, 10 * 2 ** attempt));
@@ -530,6 +720,7 @@ var SqliteStateDB = class extends _ocap_statedb.StateDB {
530
720
  }
531
721
  if (this.walCheckpointPromise) await this.walCheckpointPromise.catch(() => void 0);
532
722
  await this.commitQueue;
723
+ if (this.walEnabled && !this.config.readonly) await kysely.sql`PRAGMA wal_checkpoint(PASSIVE)`.execute(this.db).catch(() => void 0);
533
724
  await this.db.destroy();
534
725
  if (this.trustedStorage && typeof this.trustedStorage.destroy === "function" && this.trustedStorage.filename !== ":memory:") await this.trustedStorage.destroy();
535
726
  }
@@ -540,6 +731,19 @@ var SqliteStateDB = class extends _ocap_statedb.StateDB {
540
731
  return this.lastWriteSetDigest;
541
732
  }
542
733
  /**
734
+ * Read the current `_state_commit.current_hash` from SQLite (`'GENESIS'` before first commit).
735
+ */
736
+ async getCurrentCommitHash() {
737
+ if (!this.stateCommitTableReady && !this.config.readonly) await this.ensureStateCommitTable();
738
+ try {
739
+ return (await kysely.sql`
740
+ SELECT "current_hash" FROM "_state_commit" WHERE "id" = 1
741
+ `.execute(this.db)).rows[0]?.current_hash || "GENESIS";
742
+ } catch {
743
+ return "GENESIS";
744
+ }
745
+ }
746
+ /**
543
747
  * Get the underlying Kysely instance (for advanced operations)
544
748
  */
545
749
  getKysely() {
@@ -549,4 +753,5 @@ var SqliteStateDB = class extends _ocap_statedb.StateDB {
549
753
  var db_default = SqliteStateDB;
550
754
 
551
755
  //#endregion
756
+ exports.StateCommitMismatchError = StateCommitMismatchError;
552
757
  exports.default = db_default;
package/lib/db.d.cts CHANGED
@@ -5,12 +5,50 @@ import { IAccountState, IAssetFactoryState, IAssetState, IBalanceTable, IChainSt
5
5
  import { Kysely, Transaction } from "kysely";
6
6
 
7
7
  //#region src/db.d.ts
8
+ declare class StateCommitMismatchError extends Error {
9
+ readonly code = "STATE_COMMIT_MISMATCH";
10
+ readonly expectedCommitHash: string;
11
+ readonly actualCommitHash: string;
12
+ readonly seq: number;
13
+ readonly writeSetDigest: string;
14
+ constructor(params: {
15
+ expectedCommitHash: string;
16
+ actualCommitHash: string;
17
+ seq: number;
18
+ writeSetDigest: string;
19
+ });
20
+ }
21
+ interface SqliteBeforeCommitInfo {
22
+ commitHash: string;
23
+ prevHash: string;
24
+ seq: number;
25
+ writeSetDigest: string;
26
+ }
8
27
  interface SqliteRunOptions {
9
28
  retryLimit?: number;
10
29
  verifyHash?: boolean;
11
30
  cleanWorkingSet?: boolean;
12
31
  commitMessage?: string;
13
32
  context?: unknown;
33
+ /**
34
+ * Optional expected post-transaction stateCommitHash (#1710 follower replay safety).
35
+ * Verified inside the SQLite transaction BEFORE updating `_state_commit` or committing,
36
+ * so any mismatch atomically rolls back all pending writes in `statedb.sqlite`.
37
+ */
38
+ expectedCommitHash?: string;
39
+ /**
40
+ * When `true` (#1712 BFT replica speculative verification), computes `commitHash` (and checks
41
+ * `expectedCommitHash` if provided), invokes `onDryRunCommitHash`, and rolls back the SQLite
42
+ * transaction cleanly without persisting any state or updating `_state_commit`.
43
+ */
44
+ dryRun?: boolean;
45
+ onDryRunCommitHash?: (commitHash: string) => void;
46
+ /**
47
+ * Optional pre-commit hook (#1712 BFT leader 1-RTT QC collection) invoked inside the SQLite
48
+ * transaction after `_state_commit` is computed/updated and strictly BEFORE SQLite `COMMIT`.
49
+ * Throwing aborts and rolls back the entire SQLite transaction cleanly.
50
+ */
51
+ beforeCommit?: (info: SqliteBeforeCommitInfo) => void | Promise<void>;
14
52
  onCommit?: (commitHash?: string) => void | Promise<void>;
15
53
  }
16
54
  interface TrustedStorageLike extends ITrustedStorage {
@@ -36,6 +74,7 @@ declare class SqliteStateDB extends StateDB implements IStateDB {
36
74
  private walCheckpointTimer;
37
75
  private walCheckpointPromise;
38
76
  private _activeLambdaCount;
77
+ private activeDryRunSubLambda;
39
78
  private closed;
40
79
  private lastWriteSetDigest?;
41
80
  balance: IBalanceTable;
@@ -128,6 +167,28 @@ declare class SqliteStateDB extends StateDB implements IStateDB {
128
167
  * @returns Result of the transaction function
129
168
  */
130
169
  runAsLambda<T>(fn: (txn: Transaction<Database>) => T | Promise<T>, options?: SqliteRunOptions): Promise<T>;
170
+ /**
171
+ * Execute 1..N sequential steps inside a single rolled-back SQLite transaction (#1712 BFT replica verification),
172
+ * computing each step's exact `_state_commit` hash (and enforcing `expectedCommitHash` when provided) without
173
+ * persisting any writes to `statedb.sqlite` or `trusted.sqlite`.
174
+ */
175
+ runDryRunBatch(steps: Array<{
176
+ commitMessage?: string;
177
+ expectedCommitHash?: string;
178
+ fn: (txn: Transaction<Database>) => unknown | Promise<unknown>;
179
+ }>): Promise<{
180
+ commitHashes: string[];
181
+ finalCommitHash: string;
182
+ }>;
183
+ /**
184
+ * Execute an arbitrary multi-lambda session (supporting nested `OK` -> rollback -> `PERSISTED_FAILED`
185
+ * savepoint transitions) inside a single rolled-back SQLite transaction (#1712 BFT replica dry-run).
186
+ */
187
+ runWithinDryRunSession<T>(sessionFn: (runSubLambda: <R>(fn: (txn: Transaction<Database>) => R | Promise<R>, options?: SqliteRunOptions) => Promise<R>) => Promise<T>): Promise<{
188
+ result: T;
189
+ commitHashes: string[];
190
+ finalCommitHash: string | null;
191
+ }>;
131
192
  private executeRunAsLambda;
132
193
  /**
133
194
  * Reset all tables (for testing)
@@ -141,10 +202,14 @@ declare class SqliteStateDB extends StateDB implements IStateDB {
141
202
  * Get the canonical SHA-256 digest of the write-set from the most recently committed `runAsLambda` transaction.
142
203
  */
143
204
  getLastWriteSetDigest(): string | undefined;
205
+ /**
206
+ * Read the current `_state_commit.current_hash` from SQLite (`'GENESIS'` before first commit).
207
+ */
208
+ getCurrentCommitHash(): Promise<string>;
144
209
  /**
145
210
  * Get the underlying Kysely instance (for advanced operations)
146
211
  */
147
212
  getKysely(): Kysely<Database>;
148
213
  }
149
214
  //#endregion
150
- export { SqliteRunOptions, SqliteStateDB as default };
215
+ export { SqliteBeforeCommitInfo, SqliteRunOptions, StateCommitMismatchError, SqliteStateDB as default };
package/lib/index.cjs CHANGED
@@ -14,6 +14,7 @@ var src_default = require_db.default;
14
14
  exports.DurableObjectSqliteDialect = require_kysely.DurableObjectSqliteDialect;
15
15
  exports.STATE_COMMIT_DOMAIN_V2 = require_write_set.STATE_COMMIT_DOMAIN_V2;
16
16
  exports.SqliteStateDB = require_db.default;
17
+ exports.StateCommitMismatchError = require_db.StateCommitMismatchError;
17
18
  exports.WriteSetTracker = require_write_set.WriteSetTracker;
18
19
  exports.applyTombstoneBalanceCleanup = require_tombstone_cleanup.applyTombstoneBalanceCleanup;
19
20
  exports.assertSqliteStateDb = require_reconcile.assertSqliteStateDb;
@@ -28,6 +29,7 @@ exports.default = src_default;
28
29
  exports.extractContextUpdatedAt = require_tombstone_cleanup.extractContextUpdatedAt;
29
30
  exports.formatCanonicalPrimaryKey = require_write_set.formatCanonicalPrimaryKey;
30
31
  exports.getRawDatabase = require_kysely.getRawDatabase;
32
+ exports.getWriteSetTracker = require_write_set.getWriteSetTracker;
31
33
  exports.isBalanceTimestampNotAfterAccount = require_tombstone_cleanup.isBalanceTimestampNotAfterAccount;
32
34
  exports.isTrackedRawMutatingSql = require_write_set.isTrackedRawMutatingSql;
33
35
  exports.planTombstoneBalanceCleanup = require_tombstone_cleanup.planTombstoneBalanceCleanup;
package/lib/index.d.cts CHANGED
@@ -1,9 +1,9 @@
1
1
  import { Database, SqliteOperationContext } from "./interfaces.cjs";
2
2
  import { DurableObjectSqliteDialect, DurableObjectSqliteDialectConfig, IDurableObjectSqlStorage, IDurableObjectSqlStorageCursor, SqliteConfig, createKysely, getRawDatabase } from "./kysely.cjs";
3
- import SqliteStateDB from "./db.cjs";
3
+ import SqliteStateDB, { SqliteBeforeCommitInfo, SqliteRunOptions, StateCommitMismatchError } from "./db.cjs";
4
4
  import { ChainStateAuditReport, InvariantSeverity, InvariantViolation, ReconcileAction, ReconcileOptions, ReconcileResult, assertSqliteStateDb, reconcileChainState, verifyChainStateInvariants } from "./reconcile.cjs";
5
5
  import { ApplyTombstoneCleanupOptions, TombstoneBalanceRow, TombstoneCleanupApplyResult, TombstoneCleanupPlan, TombstoneTokenSummary, applyTombstoneBalanceCleanup, compareUpdatedAtTimestamps, computeTombstoneCleanupPlanDigest, extractContextUpdatedAt, isBalanceTimestampNotAfterAccount, planTombstoneBalanceCleanup } from "./tombstone-cleanup.cjs";
6
6
  import { _003_token_charter_assets_d_exports } from "./migrations/003-token-charter-assets.cjs";
7
7
  import { rollbackMigrations, runMigrations } from "./migrations/index.cjs";
8
- import { IStateCommitStepInput, IStateWriteRecord, STATE_COMMIT_DOMAIN_V2, WriteSetTracker, canonicalizeStateJson, canonicalizeStateValue, computeStateCommitHash, computeStateWriteSetDigest, formatCanonicalPrimaryKey, isTrackedRawMutatingSql } from "./write-set.cjs";
9
- export { type ApplyTombstoneCleanupOptions, type ChainStateAuditReport, type Database, DurableObjectSqliteDialect, type DurableObjectSqliteDialectConfig, type IDurableObjectSqlStorage, type IDurableObjectSqlStorageCursor, type IStateCommitStepInput, type IStateWriteRecord, type InvariantSeverity, type InvariantViolation, type ReconcileAction, type ReconcileOptions, type ReconcileResult, STATE_COMMIT_DOMAIN_V2, type SqliteConfig, type SqliteOperationContext, SqliteStateDB, SqliteStateDB as default, type TombstoneBalanceRow, type TombstoneCleanupApplyResult, type TombstoneCleanupPlan, type TombstoneTokenSummary, WriteSetTracker, applyTombstoneBalanceCleanup, assertSqliteStateDb, canonicalizeStateJson, canonicalizeStateValue, compareUpdatedAtTimestamps, computeStateCommitHash, computeStateWriteSetDigest, computeTombstoneCleanupPlanDigest, createKysely, extractContextUpdatedAt, formatCanonicalPrimaryKey, getRawDatabase, isBalanceTimestampNotAfterAccount, isTrackedRawMutatingSql, planTombstoneBalanceCleanup, reconcileChainState, rollbackMigrations, runMigrations, _003_token_charter_assets_d_exports as tokenCharterAssets, verifyChainStateInvariants };
8
+ import { IStateCommitStepInput, IStateWriteRecord, STATE_COMMIT_DOMAIN_V2, WriteSetTracker, canonicalizeStateJson, canonicalizeStateValue, computeStateCommitHash, computeStateWriteSetDigest, formatCanonicalPrimaryKey, getWriteSetTracker, isTrackedRawMutatingSql } from "./write-set.cjs";
9
+ export { type ApplyTombstoneCleanupOptions, type ChainStateAuditReport, type Database, DurableObjectSqliteDialect, type DurableObjectSqliteDialectConfig, type IDurableObjectSqlStorage, type IDurableObjectSqlStorageCursor, type IStateCommitStepInput, type IStateWriteRecord, type InvariantSeverity, type InvariantViolation, type ReconcileAction, type ReconcileOptions, type ReconcileResult, STATE_COMMIT_DOMAIN_V2, type SqliteBeforeCommitInfo, type SqliteConfig, type SqliteOperationContext, type SqliteRunOptions, SqliteStateDB, SqliteStateDB as default, StateCommitMismatchError, type TombstoneBalanceRow, type TombstoneCleanupApplyResult, type TombstoneCleanupPlan, type TombstoneTokenSummary, WriteSetTracker, applyTombstoneBalanceCleanup, assertSqliteStateDb, canonicalizeStateJson, canonicalizeStateValue, compareUpdatedAtTimestamps, computeStateCommitHash, computeStateWriteSetDigest, computeTombstoneCleanupPlanDigest, createKysely, extractContextUpdatedAt, formatCanonicalPrimaryKey, getRawDatabase, getWriteSetTracker, isBalanceTimestampNotAfterAccount, isTrackedRawMutatingSql, planTombstoneBalanceCleanup, reconcileChainState, rollbackMigrations, runMigrations, _003_token_charter_assets_d_exports as tokenCharterAssets, verifyChainStateInvariants };
@@ -132,6 +132,7 @@ var SqliteTable = class SqliteTable extends _ocap_statedb.StateDBTable {
132
132
  }
133
133
  delete result.$loki;
134
134
  delete result.meta;
135
+ delete result._retrievedAt;
135
136
  return result;
136
137
  }
137
138
  async _create(key, attrs = {}, context) {
package/lib/write-set.cjs CHANGED
@@ -244,7 +244,7 @@ var WriteSetTracker = class {
244
244
  op: "put",
245
245
  table,
246
246
  key,
247
- value
247
+ value: canonicalizeStateValue(value)
248
248
  });
249
249
  }
250
250
  recordDelete(table, key) {
@@ -264,9 +264,12 @@ var WriteSetTracker = class {
264
264
  this.writes.push({
265
265
  op: "raw",
266
266
  sql: sqlText,
267
- parameters
267
+ parameters: Array.isArray(parameters) ? parameters.map((p) => canonicalizeStateValue(p)) : parameters
268
268
  });
269
269
  }
270
+ isEmpty() {
271
+ return this.writes.length === 0;
272
+ }
270
273
  getWrites() {
271
274
  return this.writes;
272
275
  }
@@ -56,6 +56,7 @@ declare class WriteSetTracker {
56
56
  recordDelete(table: string, key: string): void;
57
57
  recordReset(table: string): void;
58
58
  recordRaw(sqlText: string, parameters?: readonly unknown[]): void;
59
+ isEmpty(): boolean;
59
60
  getWrites(): readonly IStateWriteRecord[];
60
61
  computeDigest(): string;
61
62
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@ocap/statedb-sqlite",
3
3
  "description": "OCAP statedb adapter that uses SQLite as backend",
4
- "version": "1.31.9",
4
+ "version": "1.32.1",
5
5
  "author": "wangshijun <shijun@arcblock.io> (https://www.arcblock.io)",
6
6
  "bugs": {
7
7
  "url": "https://github.com/ArcBlock/blockchain/issues",
@@ -14,7 +14,7 @@
14
14
  "wangshijun <shijun@arcblock.io> (https://www.arcblock.io)"
15
15
  ],
16
16
  "devDependencies": {
17
- "@ocap/statedb-test": "1.31.9"
17
+ "@ocap/statedb-test": "1.32.1"
18
18
  },
19
19
  "homepage": "https://github.com/ArcBlock/blockchain/tree/master/statedb/sqlite",
20
20
  "keywords": [
@@ -63,12 +63,12 @@
63
63
  "clean": "rm -rf lib esm"
64
64
  },
65
65
  "dependencies": {
66
- "@arcblock/did": "1.31.9",
67
- "@arcblock/did-util": "1.31.9",
68
- "@ocap/state": "1.31.9",
69
- "@ocap/statedb": "1.31.9",
70
- "@ocap/types": "1.31.9",
71
- "@ocap/util": "1.31.9",
66
+ "@arcblock/did": "1.32.1",
67
+ "@arcblock/did-util": "1.32.1",
68
+ "@ocap/state": "1.32.1",
69
+ "@ocap/statedb": "1.32.1",
70
+ "@ocap/types": "1.32.1",
71
+ "@ocap/util": "1.32.1",
72
72
  "better-sqlite3": "^11.8.1",
73
73
  "kysely": "^0.28.14",
74
74
  "kysely-bun-sqlite": "^0.4.0",