@ocap/statedb-sqlite 1.31.1 → 1.31.3

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.
Files changed (41) hide show
  1. package/esm/db.d.mts +11 -0
  2. package/esm/db.mjs +45 -9
  3. package/esm/index.d.mts +4 -1
  4. package/esm/index.mjs +4 -1
  5. package/esm/migrations/002-delegation-extensions.mjs +9 -2
  6. package/esm/migrations/004-rollup-reserves.d.mts +20 -0
  7. package/esm/migrations/004-rollup-reserves.mjs +39 -0
  8. package/esm/migrations/index.mjs +30 -15
  9. package/esm/table/account.d.mts +4 -3
  10. package/esm/table/account.mjs +31 -7
  11. package/esm/table/balance.mjs +31 -4
  12. package/esm/table/base.d.mts +8 -1
  13. package/esm/table/base.mjs +72 -28
  14. package/esm/table/rollup.d.mts +5 -2
  15. package/esm/table/rollup.mjs +38 -5
  16. package/esm/table/token.d.mts +9 -0
  17. package/esm/table/token.mjs +14 -0
  18. package/esm/tombstone-cleanup.mjs +1 -1
  19. package/esm/write-set.d.mts +66 -0
  20. package/esm/write-set.mjs +339 -0
  21. package/lib/db.cjs +45 -10
  22. package/lib/db.d.cts +11 -0
  23. package/lib/index.cjs +19 -0
  24. package/lib/index.d.cts +4 -1
  25. package/lib/migrations/002-delegation-extensions.cjs +9 -2
  26. package/lib/migrations/004-rollup-reserves.cjs +47 -0
  27. package/lib/migrations/004-rollup-reserves.d.cts +20 -0
  28. package/lib/migrations/index.cjs +30 -15
  29. package/lib/table/account.cjs +31 -7
  30. package/lib/table/account.d.cts +4 -3
  31. package/lib/table/balance.cjs +31 -4
  32. package/lib/table/base.cjs +72 -28
  33. package/lib/table/base.d.cts +8 -1
  34. package/lib/table/rollup.cjs +38 -5
  35. package/lib/table/rollup.d.cts +5 -2
  36. package/lib/table/token.cjs +14 -0
  37. package/lib/table/token.d.cts +9 -0
  38. package/lib/tombstone-cleanup.cjs +1 -1
  39. package/lib/write-set.cjs +351 -0
  40. package/lib/write-set.d.cts +66 -0
  41. package/package.json +8 -8
@@ -1,5 +1,6 @@
1
- import crypto from "node:crypto";
1
+ import { formatCanonicalPrimaryKey, getWriteSetTracker, unwrapTableTransaction } from "../write-set.mjs";
2
2
  import { StateDBTable } from "@ocap/statedb";
3
+ import crypto from "node:crypto";
3
4
  import omit from "lodash/omit.js";
4
5
 
5
6
  //#region src/table/base.ts
@@ -19,10 +20,21 @@ var SqliteTable = class SqliteTable extends StateDBTable {
19
20
  this.markReady();
20
21
  }
21
22
  /**
22
- * Get the Kysely executor (use transaction if available)
23
+ * Get the Kysely executor (use unwrapped transaction if available so ORM queries
24
+ * record structured row writes rather than raw-DML fallback)
23
25
  */
24
26
  getExecutor(context) {
25
- return context?.txn || this.db;
27
+ if (context?.txn) return unwrapTableTransaction(context.txn);
28
+ return this.db;
29
+ }
30
+ recordCommittedRowPut(context, lookupKey, deserializedRow) {
31
+ const tracker = getWriteSetTracker(context?.txn);
32
+ if (!tracker) return;
33
+ const canonicalKey = formatCanonicalPrimaryKey(this.uniqIndex, lookupKey);
34
+ if (this.syncBalance) {
35
+ const { tokens: _omitTokens, ...rowWithoutTokens } = deserializedRow;
36
+ tracker.recordPut(this.name, canonicalKey, rowWithoutTokens);
37
+ } else tracker.recordPut(this.name, canonicalKey, deserializedRow);
26
38
  }
27
39
  /**
28
40
  * Generate primary key from document
@@ -51,6 +63,15 @@ var SqliteTable = class SqliteTable extends StateDBTable {
51
63
  return { [this.mapColumnName(this.primaryKey)]: key };
52
64
  }
53
65
  /**
66
+ * Check that a primary-key column value is a non-empty string or finite number.
67
+ * Prevents `undefined`/`null`/`''` key fields from silently dropping SQL WHERE clauses (#1438).
68
+ */
69
+ isValidPrimaryKeyValue(v) {
70
+ if (typeof v === "string") return v.length > 0;
71
+ if (typeof v === "number") return Number.isFinite(v);
72
+ return false;
73
+ }
74
+ /**
54
75
  * Map column name for reserved keywords
55
76
  */
56
77
  mapColumnName(name) {
@@ -97,7 +118,7 @@ var SqliteTable = class SqliteTable extends StateDBTable {
97
118
  const booleanFields = new Set(this.schema.booleanFields || []);
98
119
  for (const [key, value] of Object.entries(data)) {
99
120
  const unmappedKey = this.unmapColumnName(key);
100
- if (booleanFields.has(unmappedKey) && typeof value === "number") result[unmappedKey] = value === 1;
121
+ if (booleanFields.has(unmappedKey) && (typeof value === "number" || value === null)) result[unmappedKey] = value === null ? false : value !== 0;
101
122
  else if (jsonFields.has(unmappedKey) && typeof value === "string") try {
102
123
  result[unmappedKey] = JSON.parse(value);
103
124
  } catch {
@@ -120,10 +141,15 @@ var SqliteTable = class SqliteTable extends StateDBTable {
120
141
  insertAttrs[this.primaryKey] = id;
121
142
  }
122
143
  const lookupKey = Array.isArray(this.uniqIndex) ? Object.fromEntries(this.uniqIndex.map((k) => [k, insertAttrs[k]])) : insertAttrs[this.primaryKey];
144
+ const lookupQuery = this.formatKeyToQuery(lookupKey);
145
+ const lookupEntries = Object.entries(lookupQuery);
146
+ if (lookupEntries.length === 0 || lookupEntries.some(([, v]) => !this.isValidPrimaryKeyValue(v))) throw new Error(`Invalid or incomplete primary key for ${this.name} create: ${JSON.stringify(key)}`);
123
147
  if (await SqliteTable.prototype._get.call(this, lookupKey, context)) throw new Error(`${this.name} already exists: ${JSON.stringify(key)}`);
124
148
  if (this.syncBalance) delete insertAttrs.tokens;
125
149
  const serialized = this.serializeForDb(insertAttrs);
126
- await executor.insertInto(this.name).values(serialized).execute();
150
+ const insertedRow = await executor.insertInto(this.name).values(serialized).returningAll().executeTakeFirst();
151
+ const deserializedInserted = this.deserializeFromDb(insertedRow ?? serialized) ?? insertAttrs;
152
+ this.recordCommittedRowPut(sqlContext, lookupKey, deserializedInserted);
127
153
  if (this.syncBalance && attrs.tokens !== void 0) {
128
154
  const rawTokens = attrs.tokens || {};
129
155
  insertAttrs.tokens = Object.keys(rawTokens).length ? await this.balanceTable.updateBalance({
@@ -142,11 +168,10 @@ var SqliteTable = class SqliteTable extends StateDBTable {
142
168
  if (Array.isArray(this.uniqIndex)) if (typeof key === "object") query = this.formatKeyToQuery(key);
143
169
  else return null;
144
170
  else query = this.formatKeyToQuery(key);
171
+ const queryEntries = Object.entries(query);
172
+ if (queryEntries.length === 0 || queryEntries.some(([, v]) => !this.isValidPrimaryKeyValue(v))) return null;
145
173
  let qb = executor.selectFrom(this.name).selectAll();
146
- for (const [k, v] of Object.entries(query)) {
147
- if (v === void 0) continue;
148
- qb = qb.where(k, "=", v);
149
- }
174
+ for (const [k, v] of queryEntries) qb = qb.where(k, "=", v);
150
175
  const result = await qb.executeTakeFirst();
151
176
  const deserialized = this.deserializeFromDb(result);
152
177
  if (deserialized && this.syncBalance) {
@@ -165,38 +190,48 @@ var SqliteTable = class SqliteTable extends StateDBTable {
165
190
  async _update(key, updates, context) {
166
191
  const sqlContext = context;
167
192
  const executor = this.getExecutor(sqlContext);
168
- let lookupKey = key;
169
- if (Array.isArray(this.uniqIndex) && typeof key !== "object") {
170
- const updatesObj = updates;
171
- lookupKey = Object.fromEntries(this.uniqIndex.map((k) => [k, updatesObj[k]]));
172
- }
173
193
  let query;
174
- if (Array.isArray(this.uniqIndex)) query = this.formatKeyToQuery(lookupKey);
175
- else query = this.formatKeyToQuery(key);
194
+ let lookupKey;
195
+ if (Array.isArray(this.uniqIndex)) if (typeof key === "object" && key !== null) {
196
+ const keyObj = key;
197
+ lookupKey = Object.fromEntries(this.uniqIndex.map((k) => [k, keyObj[k]]));
198
+ query = this.formatKeyToQuery(key);
199
+ } else if (typeof key === "string" && this.isValidPrimaryKeyValue(key)) {
200
+ const updatesObj = updates || {};
201
+ const candidateKey = Object.fromEntries(this.uniqIndex.map((k, idx) => [k, updatesObj[k] !== void 0 ? updatesObj[k] : idx === 0 ? key : void 0]));
202
+ if (this.uniqIndex.every((k) => this.isValidPrimaryKeyValue(candidateKey[k]))) {
203
+ lookupKey = candidateKey;
204
+ query = this.formatKeyToQuery(candidateKey);
205
+ } else throw new Error(`Invalid or incomplete primary key for ${this.name} update: ${JSON.stringify(key)}`);
206
+ } else throw new Error(`Invalid or incomplete primary key for ${this.name} update: ${JSON.stringify(key)}`);
207
+ else {
208
+ if (!key || typeof key === "object" && key === null) throw new Error(`Invalid or incomplete primary key for ${this.name} update: ${JSON.stringify(key)}`);
209
+ lookupKey = typeof key === "object" ? key[this.primaryKey] : key;
210
+ query = this.formatKeyToQuery(key);
211
+ }
212
+ const queryEntries = Object.entries(query);
213
+ if (queryEntries.length === 0 || queryEntries.some(([, v]) => !this.isValidPrimaryKeyValue(v))) throw new Error(`Invalid or incomplete primary key for ${this.name} update: ${JSON.stringify(key)}`);
176
214
  const updateAttrs = { ...updates };
177
215
  if (Array.isArray(this.uniqIndex)) for (const k of this.uniqIndex) delete updateAttrs[k];
178
216
  else delete updateAttrs[this.primaryKey];
179
- if (this.syncBalance) delete updateAttrs.tokens;
217
+ if (this.syncBalance) if (updates.tokens !== void 0) updateAttrs.tokens = null;
218
+ else delete updateAttrs.tokens;
180
219
  let merged;
181
220
  if (Object.keys(updateAttrs).length > 0) {
182
221
  const serialized = this.serializeForDb(updateAttrs);
183
222
  let qb = executor.updateTable(this.name).set(serialized);
184
- for (const [k, v] of Object.entries(query)) {
185
- if (v === void 0) continue;
186
- qb = qb.where(k, "=", v);
187
- }
223
+ for (const [k, v] of queryEntries) qb = qb.where(k, "=", v);
188
224
  const updatedRow = await qb.returningAll().executeTakeFirst();
189
225
  if (!updatedRow) throw new Error(`${this.name} does not exist: ${JSON.stringify(key)}`);
226
+ const deserialized = this.deserializeFromDb(updatedRow);
227
+ this.recordCommittedRowPut(sqlContext, lookupKey, deserialized);
190
228
  merged = {
191
- ...this.deserializeFromDb(updatedRow),
229
+ ...deserialized,
192
230
  ...updateAttrs
193
231
  };
194
232
  } else {
195
233
  let qb = executor.selectFrom(this.name).selectAll();
196
- for (const [k, v] of Object.entries(query)) {
197
- if (v === void 0) continue;
198
- qb = qb.where(k, "=", v);
199
- }
234
+ for (const [k, v] of queryEntries) qb = qb.where(k, "=", v);
200
235
  const existingRow = await qb.executeTakeFirst();
201
236
  if (!existingRow) throw new Error(`${this.name} does not exist: ${JSON.stringify(key)}`);
202
237
  merged = this.deserializeFromDb(existingRow);
@@ -221,10 +256,19 @@ var SqliteTable = class SqliteTable extends StateDBTable {
221
256
  async _reset(_context) {
222
257
  const sqlContext = _context;
223
258
  await this.getExecutor(sqlContext).deleteFrom(this.name).execute();
259
+ getWriteSetTracker(sqlContext?.txn)?.recordReset(this.name);
224
260
  }
225
261
  async updateOrCreate(exist, state, ctx) {
226
- const id = this.generatePrimaryKey(state);
227
- const attrs = omit(state, Array.isArray(this.uniqIndex) ? this.uniqIndex : [this.uniqIndex]);
262
+ const stateObj = state || {};
263
+ if (Array.isArray(this.uniqIndex)) {
264
+ const compositeKey = Object.fromEntries(this.uniqIndex.map((k) => [k, stateObj[k]]));
265
+ if (this.uniqIndex.some((k) => !this.isValidPrimaryKeyValue(compositeKey[k]))) throw new Error("Cannot update or create without uniq index");
266
+ const attrs$1 = omit(state, this.uniqIndex);
267
+ if (exist) return this.update(compositeKey, attrs$1, ctx);
268
+ return this.create(compositeKey, { ...state }, ctx);
269
+ }
270
+ const id = this.generatePrimaryKey(stateObj);
271
+ const attrs = omit(state, [this.uniqIndex]);
228
272
  if (!id) throw new Error("Cannot update or create without uniq index");
229
273
  if (exist) return this.update(id, attrs, ctx);
230
274
  return this.create(id, attrs, ctx);
@@ -9,12 +9,15 @@ import { IOperationContext, IRollupState } from "@ocap/types";
9
9
  */
10
10
  declare class RollupTable extends SqliteTable<IRollupState> {
11
11
  constructor(config: Omit<SqliteTableConfig, 'name' | 'uniqIndex' | 'schema'>);
12
+ protected deserializeFromDb(data: Record<string, unknown> | undefined | null): Record<string, unknown> | null;
12
13
  /**
13
- * Check if an active (non-paused) rollup with the given tokenAddress exists
14
+ * Check if a rollup that is not closed exists for the given tokenAddress (#1411).
15
+ * A paused rollup still owns the token: it can be resumed, and migrate_rollup requires it to be paused. Only
16
+ * close_rollup is terminal, so only a closed rollup frees the token for a new one.
14
17
  *
15
18
  * @param tokenAddress - Token address to check
16
19
  * @param context - Operation context with optional transaction
17
- * @returns true if active rollup with tokenAddress exists, false if tokenAddress is empty/undefined or rollup is paused
20
+ * @returns true if a non-closed rollup with tokenAddress exists, false if tokenAddress is empty/undefined
18
21
  */
19
22
  existByToken(tokenAddress: string, context?: IOperationContext): Promise<boolean>;
20
23
  }
@@ -2,6 +2,21 @@ import base_default from "./base.mjs";
2
2
 
3
3
  //#region src/table/rollup.ts
4
4
  /**
5
+ * Columns added by migration 004-rollup-reserves (#1548), mirroring Dolt's 20261109-rollup-reserves.
6
+ * Legacy rows read back NULL; those keys must stay ABSENT, not null/false: `hasRollupReserveTracking` treats
7
+ * `reserves !== undefined` as "tracking on", the boolean coercion would turn NULL into `false` and shadow the
8
+ * `data.value.*` fallbacks, and the state schema rejects null for these optional fields. Same as the Dolt
9
+ * RollupTable's `stripNullOptional`.
10
+ */
11
+ const OPTIONAL_NULLABLE_COLUMNS = [
12
+ "reserves",
13
+ "targetType",
14
+ "targetChainId",
15
+ "supportedTokens",
16
+ "allowProposerSponsor",
17
+ "enforceReserveWatermark"
18
+ ];
19
+ /**
5
20
  * Rollup Table
6
21
  * Extends base table with tokenAddress-based existence check
7
22
  */
@@ -18,24 +33,42 @@ var RollupTable = class extends base_default {
18
33
  "migrateHistory",
19
34
  "vaultHistory",
20
35
  "data",
21
- "context"
36
+ "context",
37
+ "reserves",
38
+ "supportedTokens"
22
39
  ],
23
- booleanFields: ["paused", "closed"]
40
+ booleanFields: [
41
+ "paused",
42
+ "closed",
43
+ "allowProposerSponsor",
44
+ "enforceReserveWatermark"
45
+ ]
24
46
  }
25
47
  });
26
48
  }
49
+ deserializeFromDb(data) {
50
+ const nullKeys = data ? OPTIONAL_NULLABLE_COLUMNS.filter((key) => data[key] === null || data[key] === void 0) : [];
51
+ const result = super.deserializeFromDb(data);
52
+ if (result) {
53
+ for (const key of nullKeys) delete result[key];
54
+ for (const key of OPTIONAL_NULLABLE_COLUMNS) if (result[key] === null) delete result[key];
55
+ }
56
+ return result;
57
+ }
27
58
  /**
28
- * Check if an active (non-paused) rollup with the given tokenAddress exists
59
+ * Check if a rollup that is not closed exists for the given tokenAddress (#1411).
60
+ * A paused rollup still owns the token: it can be resumed, and migrate_rollup requires it to be paused. Only
61
+ * close_rollup is terminal, so only a closed rollup frees the token for a new one.
29
62
  *
30
63
  * @param tokenAddress - Token address to check
31
64
  * @param context - Operation context with optional transaction
32
- * @returns true if active rollup with tokenAddress exists, false if tokenAddress is empty/undefined or rollup is paused
65
+ * @returns true if a non-closed rollup with tokenAddress exists, false if tokenAddress is empty/undefined
33
66
  */
34
67
  async existByToken(tokenAddress, context) {
35
68
  if (!tokenAddress) return false;
36
69
  const sqlContext = context;
37
70
  const executor = this.getExecutor(sqlContext);
38
- return ((await executor.selectFrom("rollup").select(executor.fn.count("address").as("count")).where("tokenAddress", "=", tokenAddress).where("paused", "=", 0).executeTakeFirst())?.count ?? 0) > 0;
71
+ return ((await executor.selectFrom("rollup").select(executor.fn.count("address").as("count")).where("tokenAddress", "=", tokenAddress).where((eb) => eb.or([eb("closed", "is", null), eb("closed", "=", 0)])).executeTakeFirst())?.count ?? 0) > 0;
39
72
  }
40
73
  };
41
74
  var rollup_default = RollupTable;
@@ -18,6 +18,15 @@ declare class TokenTable extends SqliteTable<ITokenState> {
18
18
  * @throws Error if symbol is empty
19
19
  */
20
20
  existBySymbol(symbol: string, context?: IOperationContext): Promise<boolean>;
21
+ /**
22
+ * Address of the token that owns the given symbol
23
+ *
24
+ * @param symbol - Token symbol to look up
25
+ * @param context - Operation context with optional transaction
26
+ * @returns token address, or null when no token uses the symbol
27
+ * @throws Error if symbol is empty
28
+ */
29
+ getAddressBySymbol(symbol: string, context?: IOperationContext): Promise<string | null>;
21
30
  }
22
31
  //#endregion
23
32
  export { TokenTable as default };
@@ -35,6 +35,20 @@ var TokenTable = class extends base_default {
35
35
  const executor = this.getExecutor(sqlContext);
36
36
  return ((await executor.selectFrom("token").select(executor.fn.count("address").as("count")).where("symbol", "=", symbol).executeTakeFirst())?.count ?? 0) > 0;
37
37
  }
38
+ /**
39
+ * Address of the token that owns the given symbol
40
+ *
41
+ * @param symbol - Token symbol to look up
42
+ * @param context - Operation context with optional transaction
43
+ * @returns token address, or null when no token uses the symbol
44
+ * @throws Error if symbol is empty
45
+ */
46
+ async getAddressBySymbol(symbol, context) {
47
+ if (!symbol) throw new Error("param symbol is required");
48
+ const sqlContext = context;
49
+ const result = await this.getExecutor(sqlContext).selectFrom("token").select("address").where("symbol", "=", symbol).orderBy("address").executeTakeFirst();
50
+ return result?.address ? String(result.address) : null;
51
+ }
38
52
  };
39
53
  var token_default = TokenTable;
40
54
 
@@ -1,6 +1,6 @@
1
- import { createHash } from "node:crypto";
2
1
  import { sql } from "kysely";
3
2
  import { BN } from "@ocap/util";
3
+ import { createHash } from "node:crypto";
4
4
 
5
5
  //#region src/tombstone-cleanup.ts
6
6
  const CANONICAL_UINT_REGEX = /^(?:0|[1-9]\d*)$/;
@@ -0,0 +1,66 @@
1
+ import { Database } from "./interfaces.mjs";
2
+ import { Transaction } from "kysely";
3
+
4
+ //#region src/write-set.d.ts
5
+ declare const STATE_COMMIT_DOMAIN_V2 = "ocap:state-commit:v2:";
6
+ type IStateWriteRecord = {
7
+ op: 'put';
8
+ table: string;
9
+ key: string;
10
+ value: unknown;
11
+ } | {
12
+ op: 'delete';
13
+ table: string;
14
+ key: string;
15
+ } | {
16
+ op: 'reset';
17
+ table: string;
18
+ } | {
19
+ op: 'raw';
20
+ sql: string;
21
+ parameters?: readonly unknown[];
22
+ };
23
+ interface IStateCommitStepInput {
24
+ prevHash: string;
25
+ seq: number;
26
+ msg: string;
27
+ writeSetDigest: string;
28
+ }
29
+ /**
30
+ * Recursively normalize an arbitrary JS value into a deterministic JSON-serializable structure
31
+ * with lexicographically sorted object keys (code-unit order).
32
+ * Bit-for-bit identical to `@arcblock/ledger-core` `canonicalizeStateValue`.
33
+ */
34
+ declare function canonicalizeStateValue(value: unknown, seen?: WeakSet<object>): unknown;
35
+ declare function canonicalizeStateJson(value: unknown): string;
36
+ /**
37
+ * Collapse an ordered sequence of intra-transaction state writes into a canonical, deterministic tuple array
38
+ * and hash it with SHA-256 (64 lowercase hex chars).
39
+ * Bit-for-bit identical to `@arcblock/ledger-core` `computeStateWriteSetDigest`.
40
+ */
41
+ declare function computeStateWriteSetDigest(writes: Iterable<IStateWriteRecord>): string;
42
+ /**
43
+ * Compute v2 state commit hash binding `(prevHash, seq, msg, writeSetDigest)` with unambiguous JSON framing.
44
+ * Bit-for-bit identical to `@arcblock/ledger-core` `computeStateCommitHash`.
45
+ */
46
+ declare function computeStateCommitHash(params: IStateCommitStepInput): string;
47
+ /**
48
+ * Format a table's primary key into an unambiguous canonical string key.
49
+ * Single-column PKs serialize as `String(val)`; composite PKs serialize as a JSON string tuple.
50
+ */
51
+ declare function formatCanonicalPrimaryKey(uniqIndex: string | string[], keyOrDoc: unknown): string;
52
+ declare function isTrackedRawMutatingSql(sqlText: string): boolean;
53
+ declare class WriteSetTracker {
54
+ private readonly writes;
55
+ recordPut(table: string, key: string, value: unknown): void;
56
+ recordDelete(table: string, key: string): void;
57
+ recordReset(table: string): void;
58
+ recordRaw(sqlText: string, parameters?: readonly unknown[]): void;
59
+ getWrites(): readonly IStateWriteRecord[];
60
+ computeDigest(): string;
61
+ }
62
+ declare function attachWriteSetTracker(rawTxn: Transaction<Database>, tracker: WriteSetTracker): Transaction<Database>;
63
+ declare function getWriteSetTracker(txn: Transaction<Database> | undefined): WriteSetTracker | undefined;
64
+ declare function unwrapTableTransaction(txn: Transaction<Database>): Transaction<Database>;
65
+ //#endregion
66
+ export { IStateCommitStepInput, IStateWriteRecord, STATE_COMMIT_DOMAIN_V2, WriteSetTracker, attachWriteSetTracker, canonicalizeStateJson, canonicalizeStateValue, computeStateCommitHash, computeStateWriteSetDigest, formatCanonicalPrimaryKey, getWriteSetTracker, isTrackedRawMutatingSql, unwrapTableTransaction };