@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.
- package/esm/db.d.mts +2 -0
- package/esm/db.mjs +52 -36
- package/esm/index.d.mts +3 -1
- package/esm/index.mjs +3 -1
- package/esm/migrations/003-token-charter-assets.d.mts +14 -0
- package/esm/migrations/003-token-charter-assets.mjs +116 -0
- package/esm/migrations/index.d.mts +2 -1
- package/esm/migrations/index.mjs +6 -3
- package/esm/package.mjs +2 -0
- package/esm/reconcile.d.mts +82 -0
- package/esm/reconcile.mjs +833 -0
- package/esm/table/balance.mjs +35 -16
- package/esm/table/base.mjs +24 -17
- package/esm/tombstone-cleanup.d.mts +59 -0
- package/esm/tombstone-cleanup.mjs +207 -0
- package/lib/db.cjs +52 -36
- package/lib/db.d.cts +2 -0
- package/lib/index.cjs +12 -1
- package/lib/index.d.cts +3 -1
- package/lib/migrations/003-token-charter-assets.cjs +123 -0
- package/lib/migrations/003-token-charter-assets.d.cts +14 -0
- package/lib/migrations/index.cjs +12 -3
- package/lib/migrations/index.d.cts +2 -1
- package/lib/package.cjs +2 -0
- package/lib/reconcile.cjs +836 -0
- package/lib/reconcile.d.cts +82 -0
- package/lib/table/balance.cjs +35 -16
- package/lib/table/base.cjs +24 -17
- package/lib/tombstone-cleanup.cjs +213 -0
- package/lib/tombstone-cleanup.d.cts +59 -0
- package/package.json +8 -6
|
@@ -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 };
|
package/lib/table/balance.cjs
CHANGED
|
@@ -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
|
-
|
|
105
|
-
|
|
106
|
-
|
|
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
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
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;
|
package/lib/table/base.cjs
CHANGED
|
@@ -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
|
|
132
|
-
|
|
133
|
-
tokens
|
|
134
|
-
|
|
135
|
-
|
|
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
|
|
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)
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
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.
|
|
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.
|
|
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
|
-
"@
|
|
67
|
-
"@
|
|
68
|
-
"@ocap/
|
|
69
|
-
"@ocap/
|
|
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",
|