@ocap/statedb-sqlite 1.30.25 → 1.31.0

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
@@ -103,6 +103,8 @@ declare class SqliteStateDB extends StateDB implements IStateDB {
103
103
  getCommitHash(executor?: Kysely<Database> | Transaction<Database>): Promise<{
104
104
  currentHash: string;
105
105
  prevHash: string;
106
+ seq?: number;
107
+ msg?: string;
106
108
  }>;
107
109
  private verifyTrustedHashInternal;
108
110
  /**
package/esm/db.mjs CHANGED
@@ -210,13 +210,13 @@ var SqliteStateDB = class extends StateDB {
210
210
  async initialize() {
211
211
  this.closed = false;
212
212
  if (this.initialized) {
213
- if (this.trustedStorage && !this.trustedInitialized) await this.ensureTrustedStorageInitialized();
213
+ if (this.trustedStorage && !this.trustedInitialized) await this.ensureTrustedStorageInitialized(true);
214
214
  this.startWalCheckpointWorker();
215
215
  return;
216
216
  }
217
217
  await runMigrations(this.db);
218
218
  this.initialized = true;
219
- if (this.trustedStorage) await this.ensureTrustedStorageInitialized();
219
+ if (this.trustedStorage) await this.ensureTrustedStorageInitialized(true);
220
220
  this.startWalCheckpointWorker();
221
221
  }
222
222
  /**
@@ -283,7 +283,7 @@ var SqliteStateDB = class extends StateDB {
283
283
  `.execute(this.db);
284
284
  this.stateCommitTableReady = true;
285
285
  }
286
- async ensureTrustedStorageInitialized() {
286
+ async ensureTrustedStorageInitialized(allowForwardRecovery = false) {
287
287
  if (!this.trustedStorage || this.trustedInitialized) return;
288
288
  await this.ensureStateCommitTable();
289
289
  if (typeof this.trustedStorage.initStorage === "function") await this.trustedStorage.initStorage();
@@ -291,7 +291,7 @@ var SqliteStateDB = class extends StateDB {
291
291
  const { currentHash } = await this.getCommitHash();
292
292
  const newTrustedHash = await this.trustedStorage.createHash(currentHash);
293
293
  await this.trustedStorage.writeHash(newTrustedHash);
294
- } else await this.verifyTrustedHashInternal();
294
+ } else await this.verifyTrustedHashInternal(allowForwardRecovery);
295
295
  this.trustedInitialized = true;
296
296
  }
297
297
  /**
@@ -308,17 +308,24 @@ var SqliteStateDB = class extends StateDB {
308
308
  async getCommitHash(executor = this.db) {
309
309
  if (!this.stateCommitTableReady) await this.ensureStateCommitTable();
310
310
  const row = (await sql`
311
- SELECT "current_hash", "prev_hash" FROM "_state_commit" WHERE "id" = 1
311
+ SELECT "current_hash", "prev_hash", "seq", "msg" FROM "_state_commit" WHERE "id" = 1
312
312
  `.execute(executor)).rows[0];
313
313
  return {
314
314
  currentHash: row?.current_hash || "GENESIS",
315
- prevHash: row?.prev_hash || ""
315
+ prevHash: row?.prev_hash || "",
316
+ seq: Number(row?.seq || 0),
317
+ msg: row?.msg || ""
316
318
  };
317
319
  }
318
- async verifyTrustedHashInternal() {
320
+ async verifyTrustedHashInternal(allowForwardRecovery = false) {
319
321
  if (!this.trustedStorage) return;
320
- const { currentHash } = await this.getCommitHash();
322
+ const { currentHash, prevHash, seq = 0 } = await this.getCommitHash();
321
323
  if (!await this.trustedStorage.compare(currentHash)) {
324
+ const isValidSha256Hex = /^[0-9a-f]{64}$/i.test(currentHash);
325
+ if (allowForwardRecovery && prevHash && seq > 0 && currentHash !== prevHash && isValidSha256Hex && await this.trustedStorage.compare(prevHash)) {
326
+ await this.trustedStorage.updateHash(currentHash, prevHash);
327
+ return;
328
+ }
322
329
  const err = /* @__PURE__ */ new Error("Trusted hash verification failed");
323
330
  err.code = "INVALID_HASH";
324
331
  throw err;
@@ -330,8 +337,8 @@ var SqliteStateDB = class extends StateDB {
330
337
  async verifyTrustedHash() {
331
338
  if (!this.trustedStorage) return;
332
339
  await this.enqueueCommit(async () => {
333
- await this.ensureTrustedStorageInitialized();
334
- await this.verifyTrustedHashInternal();
340
+ await this.ensureTrustedStorageInitialized(true);
341
+ await this.verifyTrustedHashInternal(true);
335
342
  });
336
343
  }
337
344
  enqueueCommit(task) {
@@ -353,50 +360,59 @@ var SqliteStateDB = class extends StateDB {
353
360
  }
354
361
  async executeRunAsLambda(fn, options = {}) {
355
362
  const { retryLimit = 2, verifyHash = false, commitMessage } = options;
363
+ if (!this.stateCommitTableReady) await this.ensureStateCommitTable();
356
364
  if (this.trustedStorage) {
357
365
  await this.ensureTrustedStorageInitialized();
358
- if (verifyHash) await this.verifyTrustedHashInternal();
366
+ if (verifyHash) await this.verifyTrustedHashInternal(false);
359
367
  }
360
368
  let result;
361
369
  let committedHash;
362
370
  let previousHash;
363
371
  let lastError;
364
372
  let committed = false;
365
- for (let attempt = 0; attempt <= retryLimit; attempt++) try {
366
- committedHash = void 0;
367
- previousHash = void 0;
368
- this._activeLambdaCount++;
373
+ const opCtx = options.context;
374
+ for (let attempt = 0; attempt <= retryLimit; attempt++) {
375
+ const savedEvents = Array.isArray(opCtx?.events) ? [...opCtx.events] : void 0;
376
+ const savedTimerCounters = opCtx?.timer?.stateDbCounters && typeof opCtx.timer.stateDbCounters === "object" ? { ...opCtx.timer.stateDbCounters } : void 0;
369
377
  try {
370
- result = await this.db.transaction().execute(async (txn) => {
371
- const txResult = await fn(txn);
372
- if (this.trustedStorage) {
378
+ committedHash = void 0;
379
+ previousHash = void 0;
380
+ this._activeLambdaCount++;
381
+ try {
382
+ result = await this.db.transaction().execute(async (txn) => {
383
+ const txResult = await fn(txn);
373
384
  const row = (await sql`
374
- SELECT "current_hash", "seq" FROM "_state_commit" WHERE "id" = 1
375
- `.execute(txn)).rows[0];
385
+ SELECT "current_hash", "seq" FROM "_state_commit" WHERE "id" = 1
386
+ `.execute(txn)).rows[0];
376
387
  const prevHash = row?.current_hash || "GENESIS";
377
388
  const nextSeq = Number(row?.seq || 0) + 1;
378
389
  const msg = commitMessage || txResult?.hash || "commit";
379
390
  const nextHash = crypto.createHash("sha256").update(`${prevHash}:${nextSeq}:${msg}`).digest("hex");
380
391
  await sql`
381
- UPDATE "_state_commit"
382
- SET "current_hash" = ${nextHash}, "prev_hash" = ${prevHash}, "seq" = ${nextSeq}, "msg" = ${msg}
383
- WHERE "id" = 1
384
- `.execute(txn);
392
+ UPDATE "_state_commit"
393
+ SET "current_hash" = ${nextHash}, "prev_hash" = ${prevHash}, "seq" = ${nextSeq}, "msg" = ${msg}
394
+ WHERE "id" = 1
395
+ `.execute(txn);
385
396
  previousHash = prevHash;
386
397
  committedHash = nextHash;
387
- }
388
- return txResult;
389
- });
390
- } finally {
391
- this._activeLambdaCount--;
398
+ return txResult;
399
+ });
400
+ } finally {
401
+ this._activeLambdaCount--;
402
+ }
403
+ committed = true;
404
+ break;
405
+ } catch (err) {
406
+ if (opCtx && savedEvents !== void 0 && Array.isArray(opCtx.events)) {
407
+ opCtx.events.length = 0;
408
+ opCtx.events.push(...savedEvents);
409
+ }
410
+ if (opCtx?.timer?.stateDbCounters && savedTimerCounters !== void 0) Object.assign(opCtx.timer.stateDbCounters, savedTimerCounters);
411
+ lastError = err;
412
+ const code = err?.code;
413
+ if (!SQLITE_BUSY_CODES.includes(code)) throw err;
414
+ if (attempt < retryLimit) await new Promise((r) => setTimeout(r, 10 * 2 ** attempt));
392
415
  }
393
- committed = true;
394
- break;
395
- } catch (err) {
396
- lastError = err;
397
- const code = err?.code;
398
- if (!SQLITE_BUSY_CODES.includes(code)) throw err;
399
- if (attempt < retryLimit) await new Promise((r) => setTimeout(r, 10 * 2 ** attempt));
400
416
  }
401
417
  if (!committed) throw lastError;
402
418
  if (this.trustedStorage && committedHash) await this.trustedStorage.updateHash(committedHash, previousHash);
package/esm/index.d.mts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { Database, SqliteOperationContext } from "./interfaces.mjs";
2
2
  import { DurableObjectSqliteDialect, DurableObjectSqliteDialectConfig, IDurableObjectSqlStorage, IDurableObjectSqlStorageCursor, SqliteConfig, createKysely, getRawDatabase } from "./kysely.mjs";
3
3
  import SqliteStateDB from "./db.mjs";
4
- export { type Database, DurableObjectSqliteDialect, type DurableObjectSqliteDialectConfig, type IDurableObjectSqlStorage, type IDurableObjectSqlStorageCursor, type SqliteConfig, type SqliteOperationContext, SqliteStateDB, SqliteStateDB as default, createKysely, getRawDatabase };
4
+ import { ChainStateAuditReport, InvariantSeverity, InvariantViolation, ReconcileAction, ReconcileOptions, ReconcileResult, assertSqliteStateDb, reconcileChainState, verifyChainStateInvariants } from "./reconcile.mjs";
5
+ export { type ChainStateAuditReport, type Database, DurableObjectSqliteDialect, type DurableObjectSqliteDialectConfig, type IDurableObjectSqlStorage, type IDurableObjectSqlStorageCursor, type InvariantSeverity, type InvariantViolation, type ReconcileAction, type ReconcileOptions, type ReconcileResult, type SqliteConfig, type SqliteOperationContext, SqliteStateDB, SqliteStateDB as default, assertSqliteStateDb, createKysely, getRawDatabase, reconcileChainState, verifyChainStateInvariants };
package/esm/index.mjs CHANGED
@@ -1,8 +1,9 @@
1
1
  import { DurableObjectSqliteDialect, createKysely, getRawDatabase } from "./kysely.mjs";
2
2
  import db_default from "./db.mjs";
3
+ import { assertSqliteStateDb, reconcileChainState, verifyChainStateInvariants } from "./reconcile.mjs";
3
4
 
4
5
  //#region src/index.ts
5
6
  var src_default = db_default;
6
7
 
7
8
  //#endregion
8
- export { DurableObjectSqliteDialect, db_default as SqliteStateDB, createKysely, src_default as default, getRawDatabase };
9
+ export { DurableObjectSqliteDialect, db_default as SqliteStateDB, assertSqliteStateDb, createKysely, src_default as default, getRawDatabase, reconcileChainState, verifyChainStateInvariants };
@@ -0,0 +1,14 @@
1
+ import { Kysely } from "kysely";
2
+
3
+ //#region src/migrations/003-token-charter-assets.d.ts
4
+ declare namespace _003_token_charter_assets_d_exports {
5
+ export { down, up };
6
+ }
7
+ /**
8
+ * Migration 003: Backfill companion Master Charter `AssetState` rows in `asset`
9
+ * for all existing Fungible Tokens in `token` (Token-as-an-Asset unification).
10
+ */
11
+ declare function up(db: Kysely<unknown>): Promise<void>;
12
+ declare function down(db: Kysely<unknown>): Promise<void>;
13
+ //#endregion
14
+ export { _003_token_charter_assets_d_exports, down, up };
@@ -0,0 +1,116 @@
1
+ import { __exportAll } from "../_virtual/rolldown_runtime.mjs";
2
+ import { sql } from "kysely";
3
+ import { isValid } from "@arcblock/did";
4
+ import { buildTokenCharterAssetState, normalizeLegacyTokenStateForUpdate } from "@ocap/state";
5
+ import { toAddress } from "@ocap/util";
6
+
7
+ //#region src/migrations/003-token-charter-assets.ts
8
+ var _003_token_charter_assets_exports = /* @__PURE__ */ __exportAll({
9
+ down: () => down,
10
+ up: () => up
11
+ });
12
+ function parseJsonField(val, fallback) {
13
+ if (val === null || val === void 0 || val === "") return fallback;
14
+ if (typeof val === "object") return val;
15
+ if (typeof val === "string") try {
16
+ return JSON.parse(val);
17
+ } catch {
18
+ return fallback;
19
+ }
20
+ return fallback;
21
+ }
22
+ /**
23
+ * Migration 003: Backfill companion Master Charter `AssetState` rows in `asset`
24
+ * for all existing Fungible Tokens in `token` (Token-as-an-Asset unification).
25
+ */
26
+ async function up(db) {
27
+ const tokenRows = (await sql`SELECT * FROM "token"`.execute(db)).rows || [];
28
+ if (tokenRows.length === 0) return;
29
+ const factoryOwnerMap = /* @__PURE__ */ new Map();
30
+ try {
31
+ const factoryRowsResult = await sql`
32
+ SELECT "address", "owner" FROM "tokenFactory"
33
+ `.execute(db);
34
+ for (const row of factoryRowsResult.rows || []) if (row?.address && row?.owner) factoryOwnerMap.set(row.address, row.owner);
35
+ } catch {}
36
+ for (const row of tokenRows) {
37
+ const rawAddress = String(row.address || "").trim();
38
+ if (!rawAddress) continue;
39
+ const address = toAddress(rawAddress);
40
+ if (!isValid(address)) continue;
41
+ const tokenFactoryAddress = String(row.tokenFactoryAddress || "");
42
+ const tokenState = normalizeLegacyTokenStateForUpdate({
43
+ address,
44
+ name: String(row.name || row.symbol || "Token"),
45
+ description: String(row.description || "Fungible token charter state"),
46
+ symbol: String(row.symbol || "TKN"),
47
+ unit: String(row.unit || "unit"),
48
+ decimal: Number(row.decimal ?? 18),
49
+ icon: row.icon ? String(row.icon) : "",
50
+ totalSupply: String(row.totalSupply || "0"),
51
+ initialSupply: String(row.initialSupply || "0"),
52
+ maxTotalSupply: row.maxTotalSupply ? String(row.maxTotalSupply) : "",
53
+ foreignToken: parseJsonField(row.foreignToken, null),
54
+ issuer: row.issuer ? String(row.issuer) : "",
55
+ website: row.website ? String(row.website) : "",
56
+ metadata: parseJsonField(row.metadata, null),
57
+ tokenFactoryAddress,
58
+ spenders: parseJsonField(row.spenders, null),
59
+ minters: parseJsonField(row.minters, null),
60
+ type: row.type ? String(row.type) : "Token",
61
+ data: parseJsonField(row.data, null),
62
+ context: parseJsonField(row.context, {
63
+ genesisTime: "2020-01-15T00:00:00.000Z",
64
+ genesisTx: "",
65
+ renaissanceTime: "2020-01-15T00:00:00.000Z",
66
+ renaissanceTx: ""
67
+ })
68
+ });
69
+ const ownerOverride = tokenFactoryAddress ? factoryOwnerMap.get(tokenFactoryAddress) : void 0;
70
+ let charter;
71
+ try {
72
+ charter = buildTokenCharterAssetState(tokenState, void 0, ownerOverride);
73
+ } catch {
74
+ continue;
75
+ }
76
+ await sql`
77
+ INSERT OR IGNORE INTO "asset" (
78
+ "address",
79
+ "owner",
80
+ "moniker",
81
+ "readonly",
82
+ "transferrable",
83
+ "ttl",
84
+ "consumedTime",
85
+ "issuer",
86
+ "parent",
87
+ "endpoint",
88
+ "display",
89
+ "tags",
90
+ "data",
91
+ "context"
92
+ ) VALUES (
93
+ ${charter.address},
94
+ ${charter.owner},
95
+ ${charter.moniker},
96
+ ${charter.readonly ? 1 : 0},
97
+ ${charter.transferrable ? 1 : 0},
98
+ ${charter.ttl ?? 0},
99
+ ${charter.consumedTime || ""},
100
+ ${charter.issuer || ""},
101
+ ${charter.parent || ""},
102
+ ${charter.endpoint ? JSON.stringify(charter.endpoint) : null},
103
+ ${charter.display ? JSON.stringify(charter.display) : null},
104
+ ${JSON.stringify(charter.tags || [])},
105
+ ${JSON.stringify(charter.data ?? null)},
106
+ ${JSON.stringify(charter.context ?? null)}
107
+ )
108
+ `.execute(db);
109
+ }
110
+ }
111
+ async function down(db) {
112
+ await sql`DELETE FROM "asset" WHERE "tags" LIKE '%"token:charter"%'`.execute(db);
113
+ }
114
+
115
+ //#endregion
116
+ export { _003_token_charter_assets_exports, down, up };
@@ -1,3 +1,4 @@
1
+ import { _003_token_charter_assets_d_exports } from "./003-token-charter-assets.mjs";
1
2
  import { Kysely } from "kysely";
2
3
 
3
4
  //#region src/migrations/index.d.ts
@@ -21,4 +22,4 @@ declare function runMigrations(db: Kysely<unknown>): Promise<void>;
21
22
  */
22
23
  declare function rollbackMigrations(db: Kysely<unknown>): Promise<void>;
23
24
  //#endregion
24
- export { rollbackMigrations, runMigrations };
25
+ export { rollbackMigrations, runMigrations, _003_token_charter_assets_d_exports as tokenCharterAssets };
@@ -1,5 +1,6 @@
1
1
  import { _001_genesis_exports } from "./001-genesis.mjs";
2
2
  import { _002_delegation_extensions_exports } from "./002-delegation-extensions.mjs";
3
+ import { _003_token_charter_assets_exports } from "./003-token-charter-assets.mjs";
3
4
  import { Migrator } from "kysely";
4
5
 
5
6
  //#region src/migrations/index.ts
@@ -32,7 +33,8 @@ async function runMigrations(db) {
32
33
  db,
33
34
  provider: new InMemoryMigrationProvider({
34
35
  "001-genesis": _001_genesis_exports,
35
- "002-delegation-extensions": _002_delegation_extensions_exports
36
+ "002-delegation-extensions": _002_delegation_extensions_exports,
37
+ "003-token-charter-assets": _003_token_charter_assets_exports
36
38
  })
37
39
  }).migrateToLatest();
38
40
  results?.forEach((it) => {
@@ -52,7 +54,8 @@ async function rollbackMigrations(db) {
52
54
  db,
53
55
  provider: new InMemoryMigrationProvider({
54
56
  "001-genesis": _001_genesis_exports,
55
- "002-delegation-extensions": _002_delegation_extensions_exports
57
+ "002-delegation-extensions": _002_delegation_extensions_exports,
58
+ "003-token-charter-assets": _003_token_charter_assets_exports
56
59
  })
57
60
  });
58
61
  let hasMore = true;
@@ -64,4 +67,4 @@ async function rollbackMigrations(db) {
64
67
  }
65
68
 
66
69
  //#endregion
67
- export { rollbackMigrations, runMigrations };
70
+ export { rollbackMigrations, runMigrations, _003_token_charter_assets_exports as tokenCharterAssets };
package/esm/package.mjs CHANGED
@@ -55,6 +55,8 @@ var package_default = {
55
55
  "clean": "rm -rf lib esm"
56
56
  },
57
57
  dependencies: {
58
+ "@arcblock/did": "workspace:*",
59
+ "@arcblock/did-util": "workspace:*",
58
60
  "@ocap/state": "workspace:*",
59
61
  "@ocap/statedb": "workspace:*",
60
62
  "@ocap/types": "workspace:*",
@@ -0,0 +1,82 @@
1
+ import SqliteStateDB from "./db.mjs";
2
+
3
+ //#region src/reconcile.d.ts
4
+ type InvariantSeverity = 'CRITICAL' | 'HIGH' | 'MEDIUM';
5
+ interface InvariantViolation {
6
+ code: 'I-BAL-1' | 'I-BAL-2' | 'I-BAL-3' | 'I-TOK-1' | 'I-TOK-2' | 'I-TOK-3' | 'I-TOK-4' | 'I-STK-1' | 'I-AST-1' | 'I-MIG-1' | 'I-LDG-1' | 'I-LDG-2';
7
+ severity: InvariantSeverity;
8
+ table: string;
9
+ key: string;
10
+ message: string;
11
+ details?: Record<string, unknown>;
12
+ reconcilable: boolean;
13
+ }
14
+ interface ChainStateAuditReport {
15
+ valid: boolean;
16
+ checkedAt: string;
17
+ counts: {
18
+ accounts: number;
19
+ assets: number;
20
+ balances: number;
21
+ tokens: number;
22
+ tokenFactories: number;
23
+ stakes: number;
24
+ violations: number;
25
+ critical: number;
26
+ high: number;
27
+ medium: number;
28
+ };
29
+ violations: InvariantViolation[];
30
+ }
31
+ interface ReconcileAction {
32
+ code: InvariantViolation['code'];
33
+ table: string;
34
+ key: string;
35
+ action: string;
36
+ before?: unknown;
37
+ after?: unknown;
38
+ }
39
+ interface ReconcileOptions {
40
+ /** Default true (preview only). Set to false to apply repairs atomically inside db.runAsLambda(). */
41
+ dryRun?: boolean;
42
+ /**
43
+ * Required when `dryRun: false`. Reconcile `--apply` writes SQLite rows directly and bypasses all protocol
44
+ * validation (no tx, no ledger entry), so it must be an explicit operator decision. Never use on a chain
45
+ * whose authoritative statedb is Dolt (production main/beta): it cannot reach Dolt and would diverge it.
46
+ */
47
+ allowProtocolBypass?: boolean;
48
+ /** Reconcile token.totalSupply (and active tokenFactory.currentSupply) to match authoritative holder + revoked balances. */
49
+ reconcileTokenSupply?: boolean;
50
+ /** Optional ledger storage instance supporting verifyChain() for end-to-end ledger continuity verification. */
51
+ ledger?: {
52
+ verifyChain?: () => Promise<{
53
+ valid: boolean;
54
+ totalEntries?: number;
55
+ error?: string;
56
+ }>;
57
+ };
58
+ }
59
+ interface ReconcileResult {
60
+ dryRun: boolean;
61
+ reconciled: boolean;
62
+ beforeReport: ChainStateAuditReport;
63
+ afterReport: ChainStateAuditReport;
64
+ actions: ReconcileAction[];
65
+ }
66
+ /**
67
+ * Verification and reconcile are SQLite-only (they query SQLite tables through kysely). Fail loudly when given
68
+ * any other backend (e.g. statedb-dolt, statedb-memory) instead of crashing midway or silently skipping.
69
+ */
70
+ declare function assertSqliteStateDb(db: unknown): void;
71
+ /**
72
+ * Verifies all chain state & ledger invariants across `SqliteStateDB` (and optional `ledger`).
73
+ */
74
+ declare function verifyChainStateInvariants(db: SqliteStateDB, options?: Pick<ReconcileOptions, 'ledger'>): Promise<ChainStateAuditReport>;
75
+ /**
76
+ * Reconciles deterministically repairable state anomalies in `SqliteStateDB`.
77
+ * By default runs in `dryRun: true` preview mode; when `dryRun: false` is passed,
78
+ * executes all repairs atomically inside `db.runAsLambda()`.
79
+ */
80
+ declare function reconcileChainState(db: SqliteStateDB, options?: ReconcileOptions): Promise<ReconcileResult>;
81
+ //#endregion
82
+ export { ChainStateAuditReport, InvariantSeverity, InvariantViolation, ReconcileAction, ReconcileOptions, ReconcileResult, assertSqliteStateDb, reconcileChainState, verifyChainStateInvariants };