@ocap/statedb-sqlite 1.30.26 → 1.31.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.
@@ -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
  }
@@ -0,0 +1,213 @@
1
+ const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
2
+ let node_crypto = require("node:crypto");
3
+ let kysely = require("kysely");
4
+ let _ocap_util = require("@ocap/util");
5
+
6
+ //#region src/tombstone-cleanup.ts
7
+ const CANONICAL_UINT_REGEX = /^(?:0|[1-9]\d*)$/;
8
+ const SHA256_HEX_REGEX = /^[a-f0-9]{64}$/i;
9
+ function parseJsonValue(raw, fallback) {
10
+ if (raw === null || raw === void 0 || raw === "") return fallback;
11
+ if (typeof raw === "object") return raw;
12
+ if (typeof raw !== "string") return fallback;
13
+ try {
14
+ return JSON.parse(raw) ?? fallback;
15
+ } catch {
16
+ return fallback;
17
+ }
18
+ }
19
+ function extractContextUpdatedAt(rawContext) {
20
+ const ctx = parseJsonValue(rawContext, {});
21
+ if (!ctx || typeof ctx !== "object") return "";
22
+ const candidate = ctx.renaissanceTime || ctx.updatedAt || ctx.genesisTime || "";
23
+ return typeof candidate === "string" ? candidate.trim() : String(candidate ?? "").trim();
24
+ }
25
+ function compareUpdatedAtTimestamps(a, b) {
26
+ const normA = a.trim();
27
+ const normB = b.trim();
28
+ if (normA === normB) return 0;
29
+ if (!normA) return -1;
30
+ if (!normB) return 1;
31
+ if (/^-?\d+(?:\.\d+)?$/.test(normA) && /^-?\d+(?:\.\d+)?$/.test(normB)) {
32
+ const numA = Number(normA);
33
+ const numB = Number(normB);
34
+ if (Number.isFinite(numA) && Number.isFinite(numB) && numA !== numB) return numA < numB ? -1 : 1;
35
+ }
36
+ const msA = Date.parse(normA);
37
+ const msB = Date.parse(normB);
38
+ if (Number.isFinite(msA) && Number.isFinite(msB)) {
39
+ if (msA !== msB) return msA < msB ? -1 : 1;
40
+ return 0;
41
+ }
42
+ return normA < normB ? -1 : 1;
43
+ }
44
+ function isBalanceTimestampNotAfterAccount(balanceUpdatedAt, accountUpdatedAt) {
45
+ const balTs = balanceUpdatedAt.trim();
46
+ const accTs = accountUpdatedAt.trim();
47
+ if (!balTs) return true;
48
+ if (!accTs) return false;
49
+ return compareUpdatedAtTimestamps(balTs, accTs) <= 0;
50
+ }
51
+ function compareTombstoneRows(a, b) {
52
+ if (a.accountAddress !== b.accountAddress) return a.accountAddress < b.accountAddress ? -1 : 1;
53
+ if (a.tokenAddress !== b.tokenAddress) return a.tokenAddress < b.tokenAddress ? -1 : 1;
54
+ return 0;
55
+ }
56
+ function computeTombstoneCleanupPlanDigest(rows) {
57
+ const canonical = [...rows].sort(compareTombstoneRows).map((r) => [
58
+ r.accountAddress,
59
+ r.tokenAddress,
60
+ r.balance,
61
+ r.balanceUpdatedAt
62
+ ]);
63
+ return (0, node_crypto.createHash)("sha256").update(JSON.stringify(canonical)).digest("hex");
64
+ }
65
+ function buildPerTokenSummaries(rows) {
66
+ const byToken = /* @__PURE__ */ new Map();
67
+ for (const row of rows) {
68
+ const balBn = CANONICAL_UINT_REGEX.test(row.balance) ? new _ocap_util.BN(row.balance, 10) : new _ocap_util.BN(0);
69
+ const existing = byToken.get(row.tokenAddress);
70
+ if (existing) {
71
+ existing.sum = existing.sum.add(balBn);
72
+ existing.rowCount += 1;
73
+ existing.accounts.add(row.accountAddress);
74
+ } else byToken.set(row.tokenAddress, {
75
+ sum: balBn,
76
+ rowCount: 1,
77
+ accounts: new Set([row.accountAddress])
78
+ });
79
+ }
80
+ const sortedTokenAddresses = Array.from(byToken.keys()).sort();
81
+ const result = {};
82
+ for (const tokenAddress of sortedTokenAddresses) {
83
+ const entry = byToken.get(tokenAddress);
84
+ result[tokenAddress] = {
85
+ tokenAddress,
86
+ staleBalanceSum: entry.sum.toString(10),
87
+ rowCount: entry.rowCount,
88
+ accountCount: entry.accounts.size
89
+ };
90
+ }
91
+ return result;
92
+ }
93
+ function isSqliteStateDB(dbOrKysely) {
94
+ const candidate = dbOrKysely;
95
+ return Boolean(candidate && typeof candidate === "object" && typeof candidate.getKysely === "function" && typeof candidate.runAsLambda === "function");
96
+ }
97
+ function resolveKyselyExecutor(dbOrKysely) {
98
+ if (isSqliteStateDB(dbOrKysely)) return dbOrKysely.getKysely();
99
+ return dbOrKysely;
100
+ }
101
+ /**
102
+ * Produce a read-only, deterministic cleanup plan for stale `balance` rows attached to
103
+ * migrated tombstone accounts (`json_array_length(account.migratedTo) > 0` and `balance.updatedAt <= account.updatedAt`).
104
+ */
105
+ async function planTombstoneBalanceCleanup(dbOrKysely) {
106
+ const rawRows = await resolveKyselyExecutor(dbOrKysely).selectFrom("balance as b").innerJoin("account as a", "b.address", "a.address").where("a.migratedTo", "is not", null).where(kysely.sql`CASE WHEN json_valid(a.migratedTo) THEN json_array_length(a.migratedTo) > 0 ELSE 0 END`).select([
107
+ "b.address as accountAddress",
108
+ "b.tokenAddress as tokenAddress",
109
+ "b.balance as balance",
110
+ "b.context as balanceContext",
111
+ "a.migratedTo as migratedTo",
112
+ "a.context as accountContext"
113
+ ]).execute();
114
+ const eligibleRows = [];
115
+ const skippedPostMigrationRows = [];
116
+ for (const raw of rawRows) {
117
+ const migratedToRaw = parseJsonValue(raw.migratedTo, []);
118
+ if (!Array.isArray(migratedToRaw)) continue;
119
+ const migratedTo = migratedToRaw.map((x) => String(x ?? "").trim()).filter((x) => x.length > 0);
120
+ if (migratedTo.length === 0) continue;
121
+ const accountAddress = String(raw.accountAddress ?? "");
122
+ const tokenAddress = String(raw.tokenAddress ?? "");
123
+ const balance = String(raw.balance ?? "0");
124
+ const balanceUpdatedAt = extractContextUpdatedAt(raw.balanceContext);
125
+ const accountUpdatedAt = extractContextUpdatedAt(raw.accountContext);
126
+ const row = {
127
+ accountAddress,
128
+ tokenAddress,
129
+ balance,
130
+ balanceUpdatedAt,
131
+ accountUpdatedAt,
132
+ migratedTo
133
+ };
134
+ if (isBalanceTimestampNotAfterAccount(balanceUpdatedAt, accountUpdatedAt)) eligibleRows.push(row);
135
+ else skippedPostMigrationRows.push(row);
136
+ }
137
+ eligibleRows.sort(compareTombstoneRows);
138
+ skippedPostMigrationRows.sort(compareTombstoneRows);
139
+ const perTokenTotals = buildPerTokenSummaries(eligibleRows);
140
+ const uniqueAccounts = new Set(eligibleRows.map((r) => r.accountAddress));
141
+ const planDigest = computeTombstoneCleanupPlanDigest(eligibleRows);
142
+ return {
143
+ mode: "plan",
144
+ totalRows: eligibleRows.length,
145
+ totalAccounts: uniqueAccounts.size,
146
+ totalTokens: Object.keys(perTokenTotals).length,
147
+ perTokenTotals,
148
+ rows: eligibleRows,
149
+ skippedPostMigrationRows,
150
+ planDigest
151
+ };
152
+ }
153
+ /**
154
+ * Execute digest-guarded deletion of stale tombstone `balance` rows inside an atomic transaction.
155
+ * Recomputes the plan inside the transaction and aborts if `planDigest !== expectedPlanDigest`.
156
+ */
157
+ async function applyTombstoneBalanceCleanup(dbOrKysely, options) {
158
+ if (!options || options.apply !== true) throw new Error("applyTombstoneBalanceCleanup requires explicit { apply: true }");
159
+ const expectedDigest = String(options.expectedPlanDigest ?? "").trim().toLowerCase();
160
+ if (!SHA256_HEX_REGEX.test(expectedDigest)) throw new Error("applyTombstoneBalanceCleanup requires a valid 64-character SHA-256 expectedPlanDigest");
161
+ const executeInTxn = async (txn) => {
162
+ const freshPlan = await planTombstoneBalanceCleanup(txn);
163
+ if (freshPlan.planDigest.toLowerCase() !== expectedDigest) throw new Error(`PLAN_DIGEST_MISMATCH: expected planDigest "${options.expectedPlanDigest}", but current state produced "${freshPlan.planDigest}"`);
164
+ if (freshPlan.rows.length === 0) return {
165
+ mode: "apply",
166
+ applied: false,
167
+ deletedRows: 0,
168
+ deletedAccounts: 0,
169
+ perTokenDeletedTotals: {},
170
+ rows: [],
171
+ planDigest: freshPlan.planDigest
172
+ };
173
+ let deletedRows = 0;
174
+ const deletedAccountSet = /* @__PURE__ */ new Set();
175
+ for (const row of freshPlan.rows) {
176
+ const accountRow = await txn.selectFrom("account").where("address", "=", row.accountAddress).where("migratedTo", "is not", null).where(kysely.sql`CASE WHEN json_valid(migratedTo) THEN json_array_length(migratedTo) > 0 ELSE 0 END`).select([
177
+ "address",
178
+ "context",
179
+ "tokens"
180
+ ]).executeTakeFirst();
181
+ if (!accountRow) throw new Error(`TOMBSTONE_STATE_CHANGED: account "${row.accountAddress}" is no longer a migrated tombstone during apply`);
182
+ const currentAccountUpdatedAt = extractContextUpdatedAt(accountRow.context);
183
+ if (!isBalanceTimestampNotAfterAccount(row.balanceUpdatedAt, currentAccountUpdatedAt)) throw new Error(`TOMBSTONE_TIMESTAMP_CHANGED: balance row (${row.accountAddress}, ${row.tokenAddress}) post-dates account timestamp during apply`);
184
+ const delResult = await txn.deleteFrom("balance").where("address", "=", row.accountAddress).where("tokenAddress", "=", row.tokenAddress).where("balance", "=", row.balance).executeTakeFirst();
185
+ const count = Number(delResult.numDeletedRows ?? 0n);
186
+ if (count !== 1) throw new Error(`TOMBSTONE_ROW_CONCURRENT_MODIFICATION: expected to delete 1 balance row for (${row.accountAddress}, ${row.tokenAddress}), deleted ${count}`);
187
+ deletedRows += count;
188
+ deletedAccountSet.add(row.accountAddress);
189
+ if (accountRow.tokens !== null && accountRow.tokens !== void 0 && accountRow.tokens !== "{}") await txn.updateTable("account").set({ tokens: "{}" }).where("address", "=", row.accountAddress).execute();
190
+ }
191
+ return {
192
+ mode: "apply",
193
+ applied: deletedRows > 0,
194
+ deletedRows,
195
+ deletedAccounts: deletedAccountSet.size,
196
+ perTokenDeletedTotals: freshPlan.perTokenTotals,
197
+ rows: freshPlan.rows,
198
+ planDigest: freshPlan.planDigest
199
+ };
200
+ };
201
+ if (isSqliteStateDB(dbOrKysely)) return dbOrKysely.runAsLambda((txn) => executeInTxn(txn));
202
+ const kysely$1 = resolveKyselyExecutor(dbOrKysely);
203
+ if ("transaction" in kysely$1 && typeof kysely$1.transaction === "function") return kysely$1.transaction().execute((txn) => executeInTxn(txn));
204
+ return executeInTxn(kysely$1);
205
+ }
206
+
207
+ //#endregion
208
+ exports.applyTombstoneBalanceCleanup = applyTombstoneBalanceCleanup;
209
+ exports.compareUpdatedAtTimestamps = compareUpdatedAtTimestamps;
210
+ exports.computeTombstoneCleanupPlanDigest = computeTombstoneCleanupPlanDigest;
211
+ exports.extractContextUpdatedAt = extractContextUpdatedAt;
212
+ exports.isBalanceTimestampNotAfterAccount = isBalanceTimestampNotAfterAccount;
213
+ exports.planTombstoneBalanceCleanup = planTombstoneBalanceCleanup;
@@ -0,0 +1,59 @@
1
+ import { Database } from "./interfaces.cjs";
2
+ import SqliteStateDB from "./db.cjs";
3
+ import { Kysely, Transaction } from "kysely";
4
+
5
+ //#region src/tombstone-cleanup.d.ts
6
+ interface TombstoneBalanceRow {
7
+ accountAddress: string;
8
+ tokenAddress: string;
9
+ balance: string;
10
+ balanceUpdatedAt: string;
11
+ accountUpdatedAt: string;
12
+ migratedTo: string[];
13
+ }
14
+ interface TombstoneTokenSummary {
15
+ tokenAddress: string;
16
+ staleBalanceSum: string;
17
+ rowCount: number;
18
+ accountCount: number;
19
+ }
20
+ interface TombstoneCleanupPlan {
21
+ mode: 'plan';
22
+ totalRows: number;
23
+ totalAccounts: number;
24
+ totalTokens: number;
25
+ perTokenTotals: Record<string, TombstoneTokenSummary>;
26
+ rows: TombstoneBalanceRow[];
27
+ skippedPostMigrationRows: TombstoneBalanceRow[];
28
+ planDigest: string;
29
+ }
30
+ interface ApplyTombstoneCleanupOptions {
31
+ apply: boolean;
32
+ expectedPlanDigest: string;
33
+ }
34
+ interface TombstoneCleanupApplyResult {
35
+ mode: 'apply';
36
+ applied: boolean;
37
+ deletedRows: number;
38
+ deletedAccounts: number;
39
+ perTokenDeletedTotals: Record<string, TombstoneTokenSummary>;
40
+ rows: TombstoneBalanceRow[];
41
+ planDigest: string;
42
+ }
43
+ declare function extractContextUpdatedAt(rawContext: unknown): string;
44
+ declare function compareUpdatedAtTimestamps(a: string, b: string): number;
45
+ declare function isBalanceTimestampNotAfterAccount(balanceUpdatedAt: string, accountUpdatedAt: string): boolean;
46
+ declare function computeTombstoneCleanupPlanDigest(rows: ReadonlyArray<Pick<TombstoneBalanceRow, 'accountAddress' | 'tokenAddress' | 'balance' | 'balanceUpdatedAt'>>): string;
47
+ type KyselyExecutor = Kysely<Database> | Transaction<Database>;
48
+ /**
49
+ * Produce a read-only, deterministic cleanup plan for stale `balance` rows attached to
50
+ * migrated tombstone accounts (`json_array_length(account.migratedTo) > 0` and `balance.updatedAt <= account.updatedAt`).
51
+ */
52
+ declare function planTombstoneBalanceCleanup(dbOrKysely: SqliteStateDB | KyselyExecutor): Promise<TombstoneCleanupPlan>;
53
+ /**
54
+ * Execute digest-guarded deletion of stale tombstone `balance` rows inside an atomic transaction.
55
+ * Recomputes the plan inside the transaction and aborts if `planDigest !== expectedPlanDigest`.
56
+ */
57
+ declare function applyTombstoneBalanceCleanup(dbOrKysely: SqliteStateDB | KyselyExecutor, options: ApplyTombstoneCleanupOptions): Promise<TombstoneCleanupApplyResult>;
58
+ //#endregion
59
+ export { ApplyTombstoneCleanupOptions, TombstoneBalanceRow, TombstoneCleanupApplyResult, TombstoneCleanupPlan, TombstoneTokenSummary, applyTombstoneBalanceCleanup, compareUpdatedAtTimestamps, computeTombstoneCleanupPlanDigest, extractContextUpdatedAt, isBalanceTimestampNotAfterAccount, planTombstoneBalanceCleanup };
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.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.30.26"
17
+ "@ocap/statedb-test": "1.31.1"
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.1",
67
+ "@arcblock/did-util": "1.31.1",
68
+ "@ocap/state": "1.31.1",
69
+ "@ocap/statedb": "1.31.1",
70
+ "@ocap/types": "1.31.1",
71
+ "@ocap/util": "1.31.1",
70
72
  "better-sqlite3": "^11.8.1",
71
73
  "kysely": "^0.28.14",
72
74
  "kysely-bun-sqlite": "^0.4.0",