@ocap/statedb-sqlite 1.30.26 → 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.
@@ -0,0 +1,82 @@
1
+ import SqliteStateDB from "./db.cjs";
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 };
@@ -80,12 +80,13 @@ var BalanceTable = class extends require_table_base.default {
80
80
  * @returns Updated token balances
81
81
  */
82
82
  async updateBalance({ address, tokens, context = {} }, ctx) {
83
- if (!Object.keys(tokens).length) return {};
84
83
  const normalizedAddress = (0, _ocap_state_lib_states_account.ensureChecksumAddress)(address);
85
84
  const tokenBalances = await this.getBalance(normalizedAddress, ctx);
85
+ const removedTokens = Object.keys(tokenBalances).filter((token) => !(token in tokens));
86
86
  const updatedTokens = Object.keys(tokens).filter((token) => tokenBalances[token] && tokenBalances[token] !== "0" || tokens[token] && tokens[token] !== "0").filter((token) => tokenBalances[token] !== tokens[token]);
87
- if (updatedTokens.length === 0) return tokens;
87
+ if (updatedTokens.length === 0 && removedTokens.length === 0) return { ...tokens };
88
88
  const batchRows = [];
89
+ const pendingOps = [];
89
90
  for (const tokenAddress of updatedTokens) {
90
91
  const key = {
91
92
  address: normalizedAddress,
@@ -101,22 +102,40 @@ var BalanceTable = class extends require_table_base.default {
101
102
  enumerable: false,
102
103
  configurable: true
103
104
  });
104
- if (tokenBalances[tokenAddress]) await this.update(key, payload, ctx);
105
- else await this.create(key, payload, ctx);
106
- tokenBalances[tokenAddress] = tokens[tokenAddress];
105
+ const insertAttrs = {
106
+ ...payload,
107
+ ...key
108
+ };
109
+ batchRows.push(this.serializeForDb(insertAttrs));
110
+ pendingOps.push({
111
+ isUpdate: Boolean(tokenBalances[tokenAddress]),
112
+ key,
113
+ payload,
114
+ tokenAddress
115
+ });
107
116
  }
108
- if (batchRows.length > 0) {
109
- const sqlContext = ctx;
110
- const executor = this.getExecutor(sqlContext);
111
- for (let i = 0; i < batchRows.length; i += UPSERT_BATCH_SIZE) {
112
- const batch = batchRows.slice(i, i + UPSERT_BATCH_SIZE);
113
- await executor.insertInto("balance").values(batch).onConflict((oc) => oc.columns(["address", "tokenAddress"]).doUpdateSet((eb) => ({
114
- balance: eb.ref("excluded.balance"),
115
- context: eb.ref("excluded.context")
116
- }))).execute();
117
- }
117
+ const sqlContext = ctx;
118
+ const executor = this.getExecutor(sqlContext);
119
+ if (removedTokens.length > 0) await executor.deleteFrom("balance").where("address", "=", normalizedAddress).where("tokenAddress", "in", removedTokens).execute();
120
+ if (batchRows.length > 0) for (let i = 0; i < batchRows.length; i += UPSERT_BATCH_SIZE) {
121
+ const batch = batchRows.slice(i, i + UPSERT_BATCH_SIZE);
122
+ await executor.insertInto("balance").values(batch).onConflict((oc) => oc.columns(["address", "tokenAddress"]).doUpdateSet((eb) => ({
123
+ balance: eb.ref("excluded.balance"),
124
+ context: eb.ref("excluded.context")
125
+ }))).execute();
126
+ }
127
+ const noopCollector = [];
128
+ for (const op of pendingOps) {
129
+ Object.defineProperty(op.payload, BATCH_COLLECTOR, {
130
+ value: noopCollector,
131
+ enumerable: false,
132
+ configurable: true
133
+ });
134
+ if (op.isUpdate) await this.update(op.key, op.payload, ctx);
135
+ else await this.create(op.key, op.payload, ctx);
136
+ tokenBalances[op.tokenAddress] = tokens[op.tokenAddress];
118
137
  }
119
- return tokens;
138
+ return { ...tokens };
120
139
  }
121
140
  };
122
141
  var balance_default = BalanceTable;
@@ -128,11 +128,14 @@ var SqliteTable = class SqliteTable extends _ocap_statedb.StateDBTable {
128
128
  if (this.syncBalance) delete insertAttrs.tokens;
129
129
  const serialized = this.serializeForDb(insertAttrs);
130
130
  await executor.insertInto(this.name).values(serialized).execute();
131
- if (this.syncBalance && attrs.tokens) insertAttrs.tokens = await this.balanceTable.updateBalance({
132
- address: insertAttrs.address,
133
- tokens: attrs.tokens,
134
- context: attrs.context
135
- }, context);
131
+ if (this.syncBalance && attrs.tokens !== void 0) {
132
+ const rawTokens = attrs.tokens || {};
133
+ insertAttrs.tokens = Object.keys(rawTokens).length ? await this.balanceTable.updateBalance({
134
+ address: insertAttrs.address || (typeof key === "string" ? key : ""),
135
+ tokens: rawTokens,
136
+ context: attrs.context
137
+ }, context) : {};
138
+ }
136
139
  return insertAttrs;
137
140
  }
138
141
  async _get(key, context) {
@@ -151,7 +154,8 @@ var SqliteTable = class SqliteTable extends _ocap_statedb.StateDBTable {
151
154
  const result = await qb.executeTakeFirst();
152
155
  const deserialized = this.deserializeFromDb(result);
153
156
  if (deserialized && this.syncBalance) {
154
- const balance = await this.balanceTable.getBalance(deserialized.address, context);
157
+ const balanceAddr = deserialized.address || (typeof key === "string" ? key : "");
158
+ const balance = await this.balanceTable.getBalance(balanceAddr, context);
155
159
  deserialized.tokens = {
156
160
  ...deserialized.tokens || {},
157
161
  ...balance
@@ -201,17 +205,20 @@ var SqliteTable = class SqliteTable extends _ocap_statedb.StateDBTable {
201
205
  if (!existingRow) throw new Error(`${this.name} does not exist: ${JSON.stringify(key)}`);
202
206
  merged = this.deserializeFromDb(existingRow);
203
207
  }
204
- if (this.syncBalance) if (updates.tokens) merged.tokens = await this.balanceTable.updateBalance({
205
- address: merged.address,
206
- tokens: updates.tokens,
207
- context: updates.context
208
- }, context);
209
- else {
210
- const balance = await this.balanceTable.getBalance(merged.address, context);
211
- merged.tokens = {
212
- ...merged.tokens || {},
213
- ...balance
214
- };
208
+ if (this.syncBalance) {
209
+ const balanceAddr = merged.address || (typeof key === "string" ? key : "");
210
+ if (updates.tokens !== void 0) merged.tokens = await this.balanceTable.updateBalance({
211
+ address: balanceAddr,
212
+ tokens: updates.tokens || {},
213
+ context: updates.context
214
+ }, context);
215
+ else {
216
+ const balance = await this.balanceTable.getBalance(balanceAddr, context);
217
+ merged.tokens = {
218
+ ...merged.tokens || {},
219
+ ...balance
220
+ };
221
+ }
215
222
  }
216
223
  return merged;
217
224
  }
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.30.26",
4
+ "version": "1.31.0",
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.30.26"
17
+ "@ocap/statedb-test": "1.31.0"
18
18
  },
19
19
  "homepage": "https://github.com/ArcBlock/blockchain/tree/master/statedb/sqlite",
20
20
  "keywords": [
@@ -63,10 +63,12 @@
63
63
  "clean": "rm -rf lib esm"
64
64
  },
65
65
  "dependencies": {
66
- "@ocap/state": "1.30.26",
67
- "@ocap/statedb": "1.30.26",
68
- "@ocap/types": "1.30.26",
69
- "@ocap/util": "1.30.26",
66
+ "@arcblock/did": "1.31.0",
67
+ "@arcblock/did-util": "1.31.0",
68
+ "@ocap/state": "1.31.0",
69
+ "@ocap/statedb": "1.31.0",
70
+ "@ocap/types": "1.31.0",
71
+ "@ocap/util": "1.31.0",
70
72
  "better-sqlite3": "^11.8.1",
71
73
  "kysely": "^0.28.14",
72
74
  "kysely-bun-sqlite": "^0.4.0",