@ocap/resolver 1.30.24 → 1.30.25

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/api.mjs CHANGED
@@ -2,6 +2,12 @@ import { getNftBGColorFromDid, getSvg } from "@arcblock/nft-display";
2
2
  import { Router } from "express";
3
3
 
4
4
  //#region src/api.ts
5
+ function sanitizeSvg(svgInput) {
6
+ return svgInput.replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<foreignObject[\s\S]*?<\/foreignObject>/gi, "").replace(/\son[a-z]+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, "").replace(/(?:href|xlink:href)\s*=\s*(?:"\s*javascript:[^"]*"|'\s*javascript:[^']*')/gi, "");
7
+ }
8
+ function escapeXmlText(input) {
9
+ return String(input ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
10
+ }
5
11
  function createAPIHandler({ resolver }) {
6
12
  const router = Router();
7
13
  router.get("/token/display", async (req, res) => {
@@ -13,7 +19,8 @@ function createAPIHandler({ resolver }) {
13
19
  if (token.icon) {
14
20
  let iconWidth = 40;
15
21
  let iconHeight = 40;
16
- const viewBoxMatch = token.icon.match(/viewBox\s*=\s*["']([^"']+)["']/i);
22
+ const sanitizedIcon = sanitizeSvg(token.icon);
23
+ const viewBoxMatch = sanitizedIcon.match(/viewBox\s*=\s*["']([^"']+)["']/i);
17
24
  if (viewBoxMatch) {
18
25
  const viewBoxValues = viewBoxMatch[1].split(/\s+/);
19
26
  if (viewBoxValues.length >= 4) {
@@ -21,10 +28,12 @@ function createAPIHandler({ resolver }) {
21
28
  iconHeight = +viewBoxValues[3] || iconHeight;
22
29
  }
23
30
  }
24
- const fixedSvg = token.icon.replace(/<svg([^>]*)>/, `<svg$1 width="${iconWidth}" height="${iconHeight}">`);
31
+ const fixedSvg = sanitizedIcon.replace(/<svg([^>]*)>/, `<svg$1 width="${iconWidth}" height="${iconHeight}">`);
25
32
  iconUri = `data:image/svg+xml;base64,${Buffer.from(fixedSvg).toString("base64")}`;
26
33
  }
27
- const svg = getSvg({
34
+ const safeSymbol = escapeXmlText(token.symbol);
35
+ const safeName = escapeXmlText(token.name);
36
+ const svg = sanitizeSvg(getSvg({
28
37
  color: getNftBGColorFromDid(address),
29
38
  did: address,
30
39
  variant: "app-passport",
@@ -32,18 +41,20 @@ function createAPIHandler({ resolver }) {
32
41
  chain: "arcblock",
33
42
  header: {
34
43
  icon: iconUri,
35
- name: token.symbol
44
+ name: safeSymbol
36
45
  },
37
46
  issuer: {
38
- name: token.symbol,
47
+ name: safeSymbol,
39
48
  icon: iconUri
40
49
  },
41
50
  extra: {
42
51
  key: "Name",
43
- value: token.name
52
+ value: safeName
44
53
  }
45
- });
54
+ }));
46
55
  res.setHeader("Content-Type", "image/svg+xml");
56
+ res.setHeader("X-Content-Type-Options", "nosniff");
57
+ res.setHeader("Content-Security-Policy", "default-src 'none'; img-src data:; style-src 'unsafe-inline'; sandbox");
47
58
  res.send(svg);
48
59
  });
49
60
  router.get("/health/ledger", async (_req, res) => {
package/esm/index.d.mts CHANGED
@@ -61,6 +61,26 @@ declare class OCAPResolver implements IResolver {
61
61
  getNodeInfo(): Promise<IResolverNodeInfo>;
62
62
  getNetInfo(): Promise<IResolverNetInfo>;
63
63
  getValidatorsInfo(): Promise<IResolverValidatorsInfo>;
64
+ getLatestCheckpoint({
65
+ height
66
+ }?: {
67
+ height?: number;
68
+ }): Promise<unknown>;
69
+ getLedgerEntry({
70
+ hash,
71
+ sequence
72
+ }?: {
73
+ hash?: string;
74
+ sequence?: number;
75
+ }): Promise<unknown>;
76
+ getMerkleProof({
77
+ sequence
78
+ }: {
79
+ sequence: number;
80
+ }): Promise<{
81
+ proof: unknown;
82
+ checkpoint: unknown;
83
+ } | null>;
64
84
  getConfig(): string;
65
85
  getAccountState({
66
86
  address,
@@ -133,7 +153,42 @@ declare class OCAPResolver implements IResolver {
133
153
  getChain(): Promise<Record<string, unknown> | null>;
134
154
  getToken(id: string): Promise<ITokenState | null>;
135
155
  initializeStateDB(): Promise<void>;
156
+ /**
157
+ * Persist a durable trail for a failed indexdb write from connectIndexDB()'s statedb
158
+ * listeners. The write path itself is fire-and-forget (EventEmitter, no retry) — this
159
+ * lets a background drain/retry worker (or manual replay) recover without silently
160
+ * drifting from statedb. Best-effort: a persistence failure only logs, never throws
161
+ * (must not break the happy-path caller). See issue #67.
162
+ */
163
+ private recordIndexFailure;
136
164
  connectIndexDB(): void;
165
+ private listIndexFailureRows;
166
+ private deleteIndexFailureRow;
167
+ private replayIndexFailureRow;
168
+ /**
169
+ * Replay pending records in `indexdb.indexFailure` with exponential backoff and dead-letter cap (#67 Phase 2).
170
+ * - Fetches latest state from `statedb` when available (falling back to recorded `payload`), re-runs the index builder,
171
+ * and removes the row from `indexFailure` once persisted to `indexdb`.
172
+ * - Increments `attempts`, updates `lastError` & `lastAttemptAt` on failure, and stops auto-retrying once
173
+ * `attempts >= maxAttempts` (dead-letter status).
174
+ */
175
+ retryIndexFailures(options?: {
176
+ maxAttempts?: number;
177
+ baseDelayMs?: number;
178
+ now?: number;
179
+ force?: boolean;
180
+ }): Promise<{
181
+ retried: number;
182
+ recovered: number;
183
+ failed: number;
184
+ skippedBackoff: number;
185
+ deadLettered: number;
186
+ }>;
187
+ /**
188
+ * Deterministically rebuild IndexDB from StateDB (`vledger index rebuild`).
189
+ * Also refreshes internal token cache, migration chain, and token distributions.
190
+ */
191
+ rebuildIndex(options?: IRebuildOptions): Promise<IRebuildResult>;
137
192
  _getState<T = Record<string, unknown>>({
138
193
  table,
139
194
  id,
package/esm/index.mjs CHANGED
@@ -8,10 +8,11 @@ import { toStakeAddress } from "@arcblock/did-util";
8
8
  import { BN, fromTokenToUnit, toAddress, toBN } from "@ocap/util";
9
9
  import createDebug from "debug";
10
10
  import pick from "lodash/pick.js";
11
+ import { randomUUID } from "node:crypto";
11
12
  import { fromPublicKey, isValid, toTypeInfo } from "@arcblock/did";
12
13
  import { patterns, v, vDID, vValidate } from "@arcblock/validator";
13
14
  import * as Config from "@ocap/config";
14
- import { formatSearchResult } from "@ocap/indexdb";
15
+ import { formatSearchResult, rebuildIndexFromState } from "@ocap/indexdb";
15
16
  import { types } from "@ocap/mcrypto";
16
17
  import { fromTypeUrl } from "@ocap/message";
17
18
  import * as states from "@ocap/state";
@@ -400,13 +401,33 @@ var OCAPResolver = class {
400
401
  return Promise.resolve({
401
402
  blockHeight: 0,
402
403
  validators: [{
403
- address: fromPublicKey(this.chainAddr),
404
+ address: this.config?.moderator?.address || fromPublicKey(this.chainAddr),
404
405
  name: "",
405
406
  proposerPriority: "0",
406
407
  votingPower: "10"
407
408
  }]
408
409
  });
409
410
  }
411
+ async getLatestCheckpoint({ height } = {}) {
412
+ if (!this.ledger) return null;
413
+ const targetHeight = height !== void 0 && height !== null ? Number(height) : void 0;
414
+ return this.ledger.getCheckpoint(targetHeight);
415
+ }
416
+ async getLedgerEntry({ hash, sequence } = {}) {
417
+ if (!this.ledger) return null;
418
+ if (sequence !== void 0 && sequence !== null) return this.ledger.getBySequence(Number(sequence));
419
+ if (hash) return this.ledger.get(String(hash));
420
+ return null;
421
+ }
422
+ async getMerkleProof({ sequence }) {
423
+ if (!this.ledger || sequence === void 0 || sequence === null) return null;
424
+ const seq = Number(sequence);
425
+ const [proof, checkpoint] = await Promise.all([this.ledger.getMerkleProof(seq), this.ledger.getCheckpointForSequence(seq)]);
426
+ return {
427
+ proof,
428
+ checkpoint
429
+ };
430
+ }
410
431
  getConfig() {
411
432
  return JSON.stringify(this.config);
412
433
  }
@@ -546,14 +567,14 @@ var OCAPResolver = class {
546
567
  onRead: async (state) => {
547
568
  if (state) {
548
569
  const [token, reserveToken] = await Promise.all([this.getTokenState({ address: state.tokenAddress }), this.getTokenState({ address: state.reserveAddress })]);
549
- state.token = {
570
+ state.token = token ? {
550
571
  ...token,
551
- metadata: formatData(token?.metadata)
552
- };
553
- state.reserveToken = {
572
+ metadata: formatData(token.metadata)
573
+ } : null;
574
+ state.reserveToken = reserveToken ? {
554
575
  ...reserveToken,
555
- metadata: formatData(reserveToken?.metadata)
556
- };
576
+ metadata: formatData(reserveToken.metadata)
577
+ } : null;
557
578
  }
558
579
  return state;
559
580
  }
@@ -601,6 +622,7 @@ var OCAPResolver = class {
601
622
  expandContext: false,
602
623
  ctx
603
624
  })))).reduce((acc, x) => {
625
+ if (!x) return acc;
604
626
  acc[x.address] = {
605
627
  symbol: x.symbol,
606
628
  decimal: x.decimal || DEFAULT_TOKEN_DECIMAL,
@@ -802,7 +824,8 @@ var OCAPResolver = class {
802
824
  return { blocks: [] };
803
825
  }
804
826
  validateTokenConfig() {
805
- const { accounts, token } = this.config;
827
+ const { mode, accounts, token } = this.config;
828
+ if (mode === "ledger" && accounts.length === 0) return;
806
829
  const sum = accounts.reduce((acc, x) => acc.add(toBN(x.balance ?? 0)), toBN(0));
807
830
  const initialSupply = toBN(token.initialSupply);
808
831
  if (!sum.eq(initialSupply)) throw new Error("Invalid config, account balance sum does not equal to token supply");
@@ -892,6 +915,42 @@ var OCAPResolver = class {
892
915
  }, { commitMessage: "initialize accounts" });
893
916
  }
894
917
  }
918
+ /**
919
+ * Persist a durable trail for a failed indexdb write from connectIndexDB()'s statedb
920
+ * listeners. The write path itself is fire-and-forget (EventEmitter, no retry) — this
921
+ * lets a background drain/retry worker (or manual replay) recover without silently
922
+ * drifting from statedb. Best-effort: a persistence failure only logs, never throws
923
+ * (must not break the happy-path caller). See issue #67.
924
+ */
925
+ async recordIndexFailure(params) {
926
+ if (!this.indexdb.indexFailure) return;
927
+ try {
928
+ const now = (/* @__PURE__ */ new Date()).toISOString();
929
+ let payload;
930
+ try {
931
+ payload = JSON.stringify(params.payload) ?? "";
932
+ } catch {
933
+ payload = String(params.payload);
934
+ }
935
+ await this.indexdb.indexFailure.insert({
936
+ id: randomUUID(),
937
+ table: params.table,
938
+ event: params.event,
939
+ entityId: typeof params.entityId === "string" ? params.entityId : "",
940
+ payload,
941
+ attempts: 0,
942
+ lastError: params.error instanceof Error ? params.error.message : String(params.error),
943
+ createdAt: now,
944
+ lastAttemptAt: now
945
+ });
946
+ } catch (persistError) {
947
+ this.logger.error("record index failure failed", {
948
+ table: params.table,
949
+ event: params.event,
950
+ error: persistError
951
+ });
952
+ }
953
+ }
895
954
  connectIndexDB() {
896
955
  const getToken = this.getToken.bind(this);
897
956
  this.statedb.tx.on("create", async (x, ctx) => {
@@ -905,6 +964,13 @@ var OCAPResolver = class {
905
964
  account: x,
906
965
  error
907
966
  });
967
+ await this.recordIndexFailure({
968
+ table: "tx",
969
+ event: "create",
970
+ entityId: x?.hash,
971
+ payload: x,
972
+ error
973
+ });
908
974
  }
909
975
  });
910
976
  this.statedb.account.on("create", async (x) => {
@@ -915,6 +981,13 @@ var OCAPResolver = class {
915
981
  account: x,
916
982
  error
917
983
  });
984
+ await this.recordIndexFailure({
985
+ table: "account",
986
+ event: "create",
987
+ entityId: x?.address,
988
+ payload: x,
989
+ error
990
+ });
918
991
  }
919
992
  });
920
993
  this.statedb.account.on("update", async (x) => {
@@ -925,6 +998,13 @@ var OCAPResolver = class {
925
998
  account: x,
926
999
  error
927
1000
  });
1001
+ await this.recordIndexFailure({
1002
+ table: "account",
1003
+ event: "update",
1004
+ entityId: x?.address,
1005
+ payload: x,
1006
+ error
1007
+ });
928
1008
  }
929
1009
  });
930
1010
  const mapping = {
@@ -990,6 +1070,13 @@ var OCAPResolver = class {
990
1070
  [table]: x,
991
1071
  error
992
1072
  });
1073
+ await this.recordIndexFailure({
1074
+ table,
1075
+ event: "create",
1076
+ entityId: x?.[key],
1077
+ payload: x,
1078
+ error
1079
+ });
993
1080
  }
994
1081
  });
995
1082
  this.statedb[table].on("update", async (x, _ctx) => {
@@ -1003,10 +1090,238 @@ var OCAPResolver = class {
1003
1090
  [table]: x,
1004
1091
  error
1005
1092
  });
1093
+ await this.recordIndexFailure({
1094
+ table,
1095
+ event: "update",
1096
+ entityId: x?.[key],
1097
+ payload: x,
1098
+ error
1099
+ });
1006
1100
  }
1007
1101
  });
1008
1102
  });
1009
1103
  }
1104
+ async listIndexFailureRows() {
1105
+ const failureTable = this.indexdb.indexFailure;
1106
+ if (!failureTable) return [];
1107
+ if (failureTable.collection && typeof failureTable.collection.find === "function") return [...failureTable.collection.find({})];
1108
+ if (typeof failureTable.getExecutor === "function") return (await failureTable.getExecutor().selectFrom(failureTable.name).selectAll().execute()).map((r) => typeof failureTable.deserializeFromDb === "function" ? failureTable.deserializeFromDb(r) : r);
1109
+ if (typeof failureTable.search === "function") return ((await failureTable.search({ body: {
1110
+ size: 1e3,
1111
+ query: { match_all: {} }
1112
+ } }))?.hits?.hits || []).map((h) => ({
1113
+ id: h._id,
1114
+ ...h._source || {}
1115
+ }));
1116
+ return [];
1117
+ }
1118
+ async deleteIndexFailureRow(id) {
1119
+ const failureTable = this.indexdb.indexFailure;
1120
+ if (!failureTable || !id) return;
1121
+ if (failureTable.collection && typeof failureTable.collection.findAndRemove === "function") {
1122
+ failureTable.collection.findAndRemove({ id });
1123
+ return;
1124
+ }
1125
+ if (typeof failureTable.getExecutor === "function") {
1126
+ await failureTable.getExecutor().deleteFrom(failureTable.name).where("id", "=", id).execute();
1127
+ return;
1128
+ }
1129
+ const esClient = this.indexdb.client;
1130
+ if (esClient && typeof esClient.delete === "function") await esClient.delete({
1131
+ index: failureTable.name,
1132
+ id
1133
+ });
1134
+ }
1135
+ async replayIndexFailureRow(row) {
1136
+ const table = String(row.table || "");
1137
+ const event = String(row.event || "create");
1138
+ const entityId = typeof row.entityId === "string" ? row.entityId : "";
1139
+ let state = null;
1140
+ const stateTable = this.statedb[table];
1141
+ if (entityId && stateTable && typeof stateTable.get === "function") state = await stateTable.get(entityId);
1142
+ if (!state && typeof row.payload === "string" && row.payload.length > 0) state = JSON.parse(row.payload);
1143
+ if (!state) throw new Error(`Cannot replay index failure ${row.id}: missing state for ${table}:${entityId}`);
1144
+ const getToken = this.getToken.bind(this);
1145
+ if (table === "account") {
1146
+ const doc$1 = await createIndexedAccount(state, getToken);
1147
+ const existing$1 = await this.indexdb.account.get(doc$1.address);
1148
+ if (event === "update" && existing$1) await this.indexdb.account.update(doc$1.address, doc$1);
1149
+ else if (!existing$1) await this.indexdb.account.insert(doc$1);
1150
+ else await this.indexdb.account.update(doc$1.address, doc$1);
1151
+ return;
1152
+ }
1153
+ if (table === "tx") {
1154
+ const ctx$1 = {
1155
+ statedb: this.statedb,
1156
+ indexdb: this.indexdb
1157
+ };
1158
+ const doc$1 = state?.tx && state?.hash && typeof state?.Valid !== "undefined" ? state : await createIndexedTransaction(state, ctx$1, this.indexdb);
1159
+ const existing$1 = await this.indexdb.tx.get(doc$1.hash);
1160
+ if (event === "update" && existing$1) await this.indexdb.tx.update(doc$1.hash, doc$1);
1161
+ else if (!existing$1) await this.indexdb.tx.insert(doc$1);
1162
+ else await this.indexdb.tx.update(doc$1.hash, doc$1);
1163
+ if (event === "create" && typeof onCreateTx === "function") await onCreateTx(doc$1, ctx$1, this);
1164
+ return;
1165
+ }
1166
+ const entry = {
1167
+ asset: [
1168
+ createIndexedAsset,
1169
+ "address",
1170
+ void 0,
1171
+ void 0
1172
+ ],
1173
+ delegation: [
1174
+ createIndexedDelegation,
1175
+ "address",
1176
+ void 0,
1177
+ void 0
1178
+ ],
1179
+ token: [
1180
+ createIndexedToken,
1181
+ "address",
1182
+ null,
1183
+ onUpdateToken
1184
+ ],
1185
+ factory: [
1186
+ createIndexedFactory,
1187
+ "address",
1188
+ void 0,
1189
+ void 0
1190
+ ],
1191
+ stake: [
1192
+ createIndexedStake,
1193
+ "address",
1194
+ void 0,
1195
+ void 0
1196
+ ],
1197
+ rollup: [
1198
+ createIndexedRollup,
1199
+ "address",
1200
+ onCreateRollup,
1201
+ void 0
1202
+ ],
1203
+ rollupBlock: [
1204
+ createIndexedRollupBlock,
1205
+ "hash",
1206
+ onCreateRollupBlock,
1207
+ void 0
1208
+ ],
1209
+ tokenFactory: [
1210
+ createIndexedTokenFactory,
1211
+ "address",
1212
+ void 0,
1213
+ void 0
1214
+ ]
1215
+ }[table];
1216
+ if (!entry) throw new Error(`Unsupported index failure table: ${table}`);
1217
+ const [fn, key, onCreate, onUpdate] = entry;
1218
+ const ctx = this.enrichIndexContext({});
1219
+ const doc = await fn(state, ctx, this.indexdb);
1220
+ const indexTable = this.indexdb[table];
1221
+ const docId = doc[key];
1222
+ const existing = await indexTable.get(docId);
1223
+ if (event === "update" && existing) {
1224
+ await indexTable.update(docId, doc);
1225
+ if (typeof onUpdate === "function") await onUpdate(doc, ctx, this.indexdb, this);
1226
+ } else if (!existing) {
1227
+ await indexTable.insert(doc);
1228
+ if (typeof onCreate === "function") await onCreate(doc, ctx, this.indexdb, this);
1229
+ } else {
1230
+ await indexTable.update(docId, doc);
1231
+ if (typeof onUpdate === "function") await onUpdate(doc, ctx, this.indexdb, this);
1232
+ }
1233
+ }
1234
+ /**
1235
+ * Replay pending records in `indexdb.indexFailure` with exponential backoff and dead-letter cap (#67 Phase 2).
1236
+ * - Fetches latest state from `statedb` when available (falling back to recorded `payload`), re-runs the index builder,
1237
+ * and removes the row from `indexFailure` once persisted to `indexdb`.
1238
+ * - Increments `attempts`, updates `lastError` & `lastAttemptAt` on failure, and stops auto-retrying once
1239
+ * `attempts >= maxAttempts` (dead-letter status).
1240
+ */
1241
+ async retryIndexFailures(options = {}) {
1242
+ const maxAttempts = options.maxAttempts ?? 5;
1243
+ const baseDelayMs = options.baseDelayMs ?? 1e3;
1244
+ const now = options.now ?? Date.now();
1245
+ const force = options.force ?? false;
1246
+ const result = {
1247
+ retried: 0,
1248
+ recovered: 0,
1249
+ failed: 0,
1250
+ skippedBackoff: 0,
1251
+ deadLettered: 0
1252
+ };
1253
+ if (!this.indexdb.indexFailure) return result;
1254
+ const rows = await this.listIndexFailureRows();
1255
+ for (const row of rows) {
1256
+ const attempts = Number(row.attempts ?? 0);
1257
+ if (!force && attempts >= maxAttempts) {
1258
+ result.deadLettered += 1;
1259
+ continue;
1260
+ }
1261
+ if (!force && attempts > 0 && baseDelayMs > 0) {
1262
+ const delayMs = baseDelayMs * 2 ** (attempts - 1);
1263
+ const lastAttemptMs = row.lastAttemptAt ? Date.parse(String(row.lastAttemptAt)) : 0;
1264
+ if (Number.isFinite(lastAttemptMs) && now - lastAttemptMs < delayMs) {
1265
+ result.skippedBackoff += 1;
1266
+ continue;
1267
+ }
1268
+ }
1269
+ result.retried += 1;
1270
+ try {
1271
+ await this.replayIndexFailureRow(row);
1272
+ await this.deleteIndexFailureRow(String(row.id));
1273
+ result.recovered += 1;
1274
+ } catch (error) {
1275
+ const nextAttempts = attempts + 1;
1276
+ const lastError = error instanceof Error ? error.message : String(error);
1277
+ const lastAttemptAt = new Date(now).toISOString();
1278
+ result.failed += 1;
1279
+ if (nextAttempts >= maxAttempts) {
1280
+ result.deadLettered += 1;
1281
+ this.logger.error("index failure reached max attempts (dead-letter)", {
1282
+ id: row.id,
1283
+ table: row.table,
1284
+ event: row.event,
1285
+ entityId: row.entityId,
1286
+ attempts: nextAttempts,
1287
+ lastError
1288
+ });
1289
+ }
1290
+ try {
1291
+ await this.indexdb.indexFailure.update(String(row.id), {
1292
+ attempts: nextAttempts,
1293
+ lastError,
1294
+ lastAttemptAt
1295
+ });
1296
+ } catch (updateErr) {
1297
+ this.logger.error("update index failure attempt failed", {
1298
+ id: row.id,
1299
+ error: updateErr
1300
+ });
1301
+ }
1302
+ }
1303
+ }
1304
+ return result;
1305
+ }
1306
+ /**
1307
+ * Deterministically rebuild IndexDB from StateDB (`vledger index rebuild`).
1308
+ * Also refreshes internal token cache, migration chain, and token distributions.
1309
+ */
1310
+ async rebuildIndex(options) {
1311
+ const chainAddress = options?.chainAddress || this.config?.address;
1312
+ const result = typeof this.indexdb.rebuild === "function" ? await this.indexdb.rebuild(this.statedb, {
1313
+ ...options,
1314
+ chainAddress
1315
+ }) : await rebuildIndexFromState(this.indexdb, this.statedb, {
1316
+ ...options,
1317
+ chainAddress
1318
+ });
1319
+ if (this.tokenCache && typeof this.tokenCache.clear === "function") this.tokenCache.clear();
1320
+ await this.buildMigrationChain();
1321
+ const { tokens } = await this.indexdb.listTokens({ paging: { size: 100 } });
1322
+ for (const token of tokens || []) if (token?.address) await this.tokenDistribution.updateByToken(token.address, true);
1323
+ return result;
1324
+ }
1010
1325
  async _getState({ table, id, dataKey, extraParams = {}, onRead = noop, expandContext = true, ctx }) {
1011
1326
  if (!id) throw new CustomError("INVALID_REQUEST", `Missing required parameter to read ${table} state`);
1012
1327
  const unified = isValid(id) ? toAddress(id) : id;
package/lib/api.cjs CHANGED
@@ -3,6 +3,12 @@ let _arcblock_nft_display = require("@arcblock/nft-display");
3
3
  let express = require("express");
4
4
 
5
5
  //#region src/api.ts
6
+ function sanitizeSvg(svgInput) {
7
+ return svgInput.replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<foreignObject[\s\S]*?<\/foreignObject>/gi, "").replace(/\son[a-z]+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, "").replace(/(?:href|xlink:href)\s*=\s*(?:"\s*javascript:[^"]*"|'\s*javascript:[^']*')/gi, "");
8
+ }
9
+ function escapeXmlText(input) {
10
+ return String(input ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
11
+ }
6
12
  function createAPIHandler({ resolver }) {
7
13
  const router = (0, express.Router)();
8
14
  router.get("/token/display", async (req, res) => {
@@ -14,7 +20,8 @@ function createAPIHandler({ resolver }) {
14
20
  if (token.icon) {
15
21
  let iconWidth = 40;
16
22
  let iconHeight = 40;
17
- const viewBoxMatch = token.icon.match(/viewBox\s*=\s*["']([^"']+)["']/i);
23
+ const sanitizedIcon = sanitizeSvg(token.icon);
24
+ const viewBoxMatch = sanitizedIcon.match(/viewBox\s*=\s*["']([^"']+)["']/i);
18
25
  if (viewBoxMatch) {
19
26
  const viewBoxValues = viewBoxMatch[1].split(/\s+/);
20
27
  if (viewBoxValues.length >= 4) {
@@ -22,10 +29,12 @@ function createAPIHandler({ resolver }) {
22
29
  iconHeight = +viewBoxValues[3] || iconHeight;
23
30
  }
24
31
  }
25
- const fixedSvg = token.icon.replace(/<svg([^>]*)>/, `<svg$1 width="${iconWidth}" height="${iconHeight}">`);
32
+ const fixedSvg = sanitizedIcon.replace(/<svg([^>]*)>/, `<svg$1 width="${iconWidth}" height="${iconHeight}">`);
26
33
  iconUri = `data:image/svg+xml;base64,${Buffer.from(fixedSvg).toString("base64")}`;
27
34
  }
28
- const svg = (0, _arcblock_nft_display.getSvg)({
35
+ const safeSymbol = escapeXmlText(token.symbol);
36
+ const safeName = escapeXmlText(token.name);
37
+ const svg = sanitizeSvg((0, _arcblock_nft_display.getSvg)({
29
38
  color: (0, _arcblock_nft_display.getNftBGColorFromDid)(address),
30
39
  did: address,
31
40
  variant: "app-passport",
@@ -33,18 +42,20 @@ function createAPIHandler({ resolver }) {
33
42
  chain: "arcblock",
34
43
  header: {
35
44
  icon: iconUri,
36
- name: token.symbol
45
+ name: safeSymbol
37
46
  },
38
47
  issuer: {
39
- name: token.symbol,
48
+ name: safeSymbol,
40
49
  icon: iconUri
41
50
  },
42
51
  extra: {
43
52
  key: "Name",
44
- value: token.name
53
+ value: safeName
45
54
  }
46
- });
55
+ }));
47
56
  res.setHeader("Content-Type", "image/svg+xml");
57
+ res.setHeader("X-Content-Type-Options", "nosniff");
58
+ res.setHeader("Content-Security-Policy", "default-src 'none'; img-src data:; style-src 'unsafe-inline'; sandbox");
48
59
  res.send(svg);
49
60
  });
50
61
  router.get("/health/ledger", async (_req, res) => {
package/lib/index.cjs CHANGED
@@ -12,6 +12,7 @@ let debug = require("debug");
12
12
  debug = require_rolldown_runtime.__toESM(debug);
13
13
  let lodash_pick = require("lodash/pick");
14
14
  lodash_pick = require_rolldown_runtime.__toESM(lodash_pick);
15
+ let node_crypto = require("node:crypto");
15
16
  let _arcblock_did = require("@arcblock/did");
16
17
  let _arcblock_validator = require("@arcblock/validator");
17
18
  let _ocap_config = require("@ocap/config");
@@ -414,13 +415,33 @@ var OCAPResolver = class {
414
415
  return Promise.resolve({
415
416
  blockHeight: 0,
416
417
  validators: [{
417
- address: (0, _arcblock_did.fromPublicKey)(this.chainAddr),
418
+ address: this.config?.moderator?.address || (0, _arcblock_did.fromPublicKey)(this.chainAddr),
418
419
  name: "",
419
420
  proposerPriority: "0",
420
421
  votingPower: "10"
421
422
  }]
422
423
  });
423
424
  }
425
+ async getLatestCheckpoint({ height } = {}) {
426
+ if (!this.ledger) return null;
427
+ const targetHeight = height !== void 0 && height !== null ? Number(height) : void 0;
428
+ return this.ledger.getCheckpoint(targetHeight);
429
+ }
430
+ async getLedgerEntry({ hash, sequence } = {}) {
431
+ if (!this.ledger) return null;
432
+ if (sequence !== void 0 && sequence !== null) return this.ledger.getBySequence(Number(sequence));
433
+ if (hash) return this.ledger.get(String(hash));
434
+ return null;
435
+ }
436
+ async getMerkleProof({ sequence }) {
437
+ if (!this.ledger || sequence === void 0 || sequence === null) return null;
438
+ const seq = Number(sequence);
439
+ const [proof, checkpoint] = await Promise.all([this.ledger.getMerkleProof(seq), this.ledger.getCheckpointForSequence(seq)]);
440
+ return {
441
+ proof,
442
+ checkpoint
443
+ };
444
+ }
424
445
  getConfig() {
425
446
  return JSON.stringify(this.config);
426
447
  }
@@ -560,14 +581,14 @@ var OCAPResolver = class {
560
581
  onRead: async (state) => {
561
582
  if (state) {
562
583
  const [token, reserveToken] = await Promise.all([this.getTokenState({ address: state.tokenAddress }), this.getTokenState({ address: state.reserveAddress })]);
563
- state.token = {
584
+ state.token = token ? {
564
585
  ...token,
565
- metadata: formatData(token?.metadata)
566
- };
567
- state.reserveToken = {
586
+ metadata: formatData(token.metadata)
587
+ } : null;
588
+ state.reserveToken = reserveToken ? {
568
589
  ...reserveToken,
569
- metadata: formatData(reserveToken?.metadata)
570
- };
590
+ metadata: formatData(reserveToken.metadata)
591
+ } : null;
571
592
  }
572
593
  return state;
573
594
  }
@@ -615,6 +636,7 @@ var OCAPResolver = class {
615
636
  expandContext: false,
616
637
  ctx
617
638
  })))).reduce((acc, x) => {
639
+ if (!x) return acc;
618
640
  acc[x.address] = {
619
641
  symbol: x.symbol,
620
642
  decimal: x.decimal || _ocap_util_lib_constant.DEFAULT_TOKEN_DECIMAL,
@@ -816,7 +838,8 @@ var OCAPResolver = class {
816
838
  return { blocks: [] };
817
839
  }
818
840
  validateTokenConfig() {
819
- const { accounts, token } = this.config;
841
+ const { mode, accounts, token } = this.config;
842
+ if (mode === "ledger" && accounts.length === 0) return;
820
843
  const sum = accounts.reduce((acc, x) => acc.add((0, _ocap_util.toBN)(x.balance ?? 0)), (0, _ocap_util.toBN)(0));
821
844
  const initialSupply = (0, _ocap_util.toBN)(token.initialSupply);
822
845
  if (!sum.eq(initialSupply)) throw new Error("Invalid config, account balance sum does not equal to token supply");
@@ -906,6 +929,42 @@ var OCAPResolver = class {
906
929
  }, { commitMessage: "initialize accounts" });
907
930
  }
908
931
  }
932
+ /**
933
+ * Persist a durable trail for a failed indexdb write from connectIndexDB()'s statedb
934
+ * listeners. The write path itself is fire-and-forget (EventEmitter, no retry) — this
935
+ * lets a background drain/retry worker (or manual replay) recover without silently
936
+ * drifting from statedb. Best-effort: a persistence failure only logs, never throws
937
+ * (must not break the happy-path caller). See issue #67.
938
+ */
939
+ async recordIndexFailure(params) {
940
+ if (!this.indexdb.indexFailure) return;
941
+ try {
942
+ const now = (/* @__PURE__ */ new Date()).toISOString();
943
+ let payload;
944
+ try {
945
+ payload = JSON.stringify(params.payload) ?? "";
946
+ } catch {
947
+ payload = String(params.payload);
948
+ }
949
+ await this.indexdb.indexFailure.insert({
950
+ id: (0, node_crypto.randomUUID)(),
951
+ table: params.table,
952
+ event: params.event,
953
+ entityId: typeof params.entityId === "string" ? params.entityId : "",
954
+ payload,
955
+ attempts: 0,
956
+ lastError: params.error instanceof Error ? params.error.message : String(params.error),
957
+ createdAt: now,
958
+ lastAttemptAt: now
959
+ });
960
+ } catch (persistError) {
961
+ this.logger.error("record index failure failed", {
962
+ table: params.table,
963
+ event: params.event,
964
+ error: persistError
965
+ });
966
+ }
967
+ }
909
968
  connectIndexDB() {
910
969
  const getToken = this.getToken.bind(this);
911
970
  this.statedb.tx.on("create", async (x, ctx) => {
@@ -919,6 +978,13 @@ var OCAPResolver = class {
919
978
  account: x,
920
979
  error
921
980
  });
981
+ await this.recordIndexFailure({
982
+ table: "tx",
983
+ event: "create",
984
+ entityId: x?.hash,
985
+ payload: x,
986
+ error
987
+ });
922
988
  }
923
989
  });
924
990
  this.statedb.account.on("create", async (x) => {
@@ -929,6 +995,13 @@ var OCAPResolver = class {
929
995
  account: x,
930
996
  error
931
997
  });
998
+ await this.recordIndexFailure({
999
+ table: "account",
1000
+ event: "create",
1001
+ entityId: x?.address,
1002
+ payload: x,
1003
+ error
1004
+ });
932
1005
  }
933
1006
  });
934
1007
  this.statedb.account.on("update", async (x) => {
@@ -939,6 +1012,13 @@ var OCAPResolver = class {
939
1012
  account: x,
940
1013
  error
941
1014
  });
1015
+ await this.recordIndexFailure({
1016
+ table: "account",
1017
+ event: "update",
1018
+ entityId: x?.address,
1019
+ payload: x,
1020
+ error
1021
+ });
942
1022
  }
943
1023
  });
944
1024
  const mapping = {
@@ -1004,6 +1084,13 @@ var OCAPResolver = class {
1004
1084
  [table]: x,
1005
1085
  error
1006
1086
  });
1087
+ await this.recordIndexFailure({
1088
+ table,
1089
+ event: "create",
1090
+ entityId: x?.[key],
1091
+ payload: x,
1092
+ error
1093
+ });
1007
1094
  }
1008
1095
  });
1009
1096
  this.statedb[table].on("update", async (x, _ctx) => {
@@ -1017,10 +1104,238 @@ var OCAPResolver = class {
1017
1104
  [table]: x,
1018
1105
  error
1019
1106
  });
1107
+ await this.recordIndexFailure({
1108
+ table,
1109
+ event: "update",
1110
+ entityId: x?.[key],
1111
+ payload: x,
1112
+ error
1113
+ });
1020
1114
  }
1021
1115
  });
1022
1116
  });
1023
1117
  }
1118
+ async listIndexFailureRows() {
1119
+ const failureTable = this.indexdb.indexFailure;
1120
+ if (!failureTable) return [];
1121
+ if (failureTable.collection && typeof failureTable.collection.find === "function") return [...failureTable.collection.find({})];
1122
+ if (typeof failureTable.getExecutor === "function") return (await failureTable.getExecutor().selectFrom(failureTable.name).selectAll().execute()).map((r) => typeof failureTable.deserializeFromDb === "function" ? failureTable.deserializeFromDb(r) : r);
1123
+ if (typeof failureTable.search === "function") return ((await failureTable.search({ body: {
1124
+ size: 1e3,
1125
+ query: { match_all: {} }
1126
+ } }))?.hits?.hits || []).map((h) => ({
1127
+ id: h._id,
1128
+ ...h._source || {}
1129
+ }));
1130
+ return [];
1131
+ }
1132
+ async deleteIndexFailureRow(id) {
1133
+ const failureTable = this.indexdb.indexFailure;
1134
+ if (!failureTable || !id) return;
1135
+ if (failureTable.collection && typeof failureTable.collection.findAndRemove === "function") {
1136
+ failureTable.collection.findAndRemove({ id });
1137
+ return;
1138
+ }
1139
+ if (typeof failureTable.getExecutor === "function") {
1140
+ await failureTable.getExecutor().deleteFrom(failureTable.name).where("id", "=", id).execute();
1141
+ return;
1142
+ }
1143
+ const esClient = this.indexdb.client;
1144
+ if (esClient && typeof esClient.delete === "function") await esClient.delete({
1145
+ index: failureTable.name,
1146
+ id
1147
+ });
1148
+ }
1149
+ async replayIndexFailureRow(row) {
1150
+ const table = String(row.table || "");
1151
+ const event = String(row.event || "create");
1152
+ const entityId = typeof row.entityId === "string" ? row.entityId : "";
1153
+ let state = null;
1154
+ const stateTable = this.statedb[table];
1155
+ if (entityId && stateTable && typeof stateTable.get === "function") state = await stateTable.get(entityId);
1156
+ if (!state && typeof row.payload === "string" && row.payload.length > 0) state = JSON.parse(row.payload);
1157
+ if (!state) throw new Error(`Cannot replay index failure ${row.id}: missing state for ${table}:${entityId}`);
1158
+ const getToken = this.getToken.bind(this);
1159
+ if (table === "account") {
1160
+ const doc$1 = await (0, _ocap_indexdb_lib_util.createIndexedAccount)(state, getToken);
1161
+ const existing$1 = await this.indexdb.account.get(doc$1.address);
1162
+ if (event === "update" && existing$1) await this.indexdb.account.update(doc$1.address, doc$1);
1163
+ else if (!existing$1) await this.indexdb.account.insert(doc$1);
1164
+ else await this.indexdb.account.update(doc$1.address, doc$1);
1165
+ return;
1166
+ }
1167
+ if (table === "tx") {
1168
+ const ctx$1 = {
1169
+ statedb: this.statedb,
1170
+ indexdb: this.indexdb
1171
+ };
1172
+ const doc$1 = state?.tx && state?.hash && typeof state?.Valid !== "undefined" ? state : await (0, _ocap_indexdb_lib_util.createIndexedTransaction)(state, ctx$1, this.indexdb);
1173
+ const existing$1 = await this.indexdb.tx.get(doc$1.hash);
1174
+ if (event === "update" && existing$1) await this.indexdb.tx.update(doc$1.hash, doc$1);
1175
+ else if (!existing$1) await this.indexdb.tx.insert(doc$1);
1176
+ else await this.indexdb.tx.update(doc$1.hash, doc$1);
1177
+ if (event === "create" && typeof require_hooks.onCreateTx === "function") await require_hooks.onCreateTx(doc$1, ctx$1, this);
1178
+ return;
1179
+ }
1180
+ const entry = {
1181
+ asset: [
1182
+ _ocap_indexdb_lib_util.createIndexedAsset,
1183
+ "address",
1184
+ void 0,
1185
+ void 0
1186
+ ],
1187
+ delegation: [
1188
+ _ocap_indexdb_lib_util.createIndexedDelegation,
1189
+ "address",
1190
+ void 0,
1191
+ void 0
1192
+ ],
1193
+ token: [
1194
+ _ocap_indexdb_lib_util.createIndexedToken,
1195
+ "address",
1196
+ null,
1197
+ require_hooks.onUpdateToken
1198
+ ],
1199
+ factory: [
1200
+ _ocap_indexdb_lib_util.createIndexedFactory,
1201
+ "address",
1202
+ void 0,
1203
+ void 0
1204
+ ],
1205
+ stake: [
1206
+ _ocap_indexdb_lib_util.createIndexedStake,
1207
+ "address",
1208
+ void 0,
1209
+ void 0
1210
+ ],
1211
+ rollup: [
1212
+ _ocap_indexdb_lib_util.createIndexedRollup,
1213
+ "address",
1214
+ require_hooks.onCreateRollup,
1215
+ void 0
1216
+ ],
1217
+ rollupBlock: [
1218
+ _ocap_indexdb_lib_util.createIndexedRollupBlock,
1219
+ "hash",
1220
+ require_hooks.onCreateRollupBlock,
1221
+ void 0
1222
+ ],
1223
+ tokenFactory: [
1224
+ _ocap_indexdb_lib_util.createIndexedTokenFactory,
1225
+ "address",
1226
+ void 0,
1227
+ void 0
1228
+ ]
1229
+ }[table];
1230
+ if (!entry) throw new Error(`Unsupported index failure table: ${table}`);
1231
+ const [fn, key, onCreate, onUpdate] = entry;
1232
+ const ctx = this.enrichIndexContext({});
1233
+ const doc = await fn(state, ctx, this.indexdb);
1234
+ const indexTable = this.indexdb[table];
1235
+ const docId = doc[key];
1236
+ const existing = await indexTable.get(docId);
1237
+ if (event === "update" && existing) {
1238
+ await indexTable.update(docId, doc);
1239
+ if (typeof onUpdate === "function") await onUpdate(doc, ctx, this.indexdb, this);
1240
+ } else if (!existing) {
1241
+ await indexTable.insert(doc);
1242
+ if (typeof onCreate === "function") await onCreate(doc, ctx, this.indexdb, this);
1243
+ } else {
1244
+ await indexTable.update(docId, doc);
1245
+ if (typeof onUpdate === "function") await onUpdate(doc, ctx, this.indexdb, this);
1246
+ }
1247
+ }
1248
+ /**
1249
+ * Replay pending records in `indexdb.indexFailure` with exponential backoff and dead-letter cap (#67 Phase 2).
1250
+ * - Fetches latest state from `statedb` when available (falling back to recorded `payload`), re-runs the index builder,
1251
+ * and removes the row from `indexFailure` once persisted to `indexdb`.
1252
+ * - Increments `attempts`, updates `lastError` & `lastAttemptAt` on failure, and stops auto-retrying once
1253
+ * `attempts >= maxAttempts` (dead-letter status).
1254
+ */
1255
+ async retryIndexFailures(options = {}) {
1256
+ const maxAttempts = options.maxAttempts ?? 5;
1257
+ const baseDelayMs = options.baseDelayMs ?? 1e3;
1258
+ const now = options.now ?? Date.now();
1259
+ const force = options.force ?? false;
1260
+ const result = {
1261
+ retried: 0,
1262
+ recovered: 0,
1263
+ failed: 0,
1264
+ skippedBackoff: 0,
1265
+ deadLettered: 0
1266
+ };
1267
+ if (!this.indexdb.indexFailure) return result;
1268
+ const rows = await this.listIndexFailureRows();
1269
+ for (const row of rows) {
1270
+ const attempts = Number(row.attempts ?? 0);
1271
+ if (!force && attempts >= maxAttempts) {
1272
+ result.deadLettered += 1;
1273
+ continue;
1274
+ }
1275
+ if (!force && attempts > 0 && baseDelayMs > 0) {
1276
+ const delayMs = baseDelayMs * 2 ** (attempts - 1);
1277
+ const lastAttemptMs = row.lastAttemptAt ? Date.parse(String(row.lastAttemptAt)) : 0;
1278
+ if (Number.isFinite(lastAttemptMs) && now - lastAttemptMs < delayMs) {
1279
+ result.skippedBackoff += 1;
1280
+ continue;
1281
+ }
1282
+ }
1283
+ result.retried += 1;
1284
+ try {
1285
+ await this.replayIndexFailureRow(row);
1286
+ await this.deleteIndexFailureRow(String(row.id));
1287
+ result.recovered += 1;
1288
+ } catch (error) {
1289
+ const nextAttempts = attempts + 1;
1290
+ const lastError = error instanceof Error ? error.message : String(error);
1291
+ const lastAttemptAt = new Date(now).toISOString();
1292
+ result.failed += 1;
1293
+ if (nextAttempts >= maxAttempts) {
1294
+ result.deadLettered += 1;
1295
+ this.logger.error("index failure reached max attempts (dead-letter)", {
1296
+ id: row.id,
1297
+ table: row.table,
1298
+ event: row.event,
1299
+ entityId: row.entityId,
1300
+ attempts: nextAttempts,
1301
+ lastError
1302
+ });
1303
+ }
1304
+ try {
1305
+ await this.indexdb.indexFailure.update(String(row.id), {
1306
+ attempts: nextAttempts,
1307
+ lastError,
1308
+ lastAttemptAt
1309
+ });
1310
+ } catch (updateErr) {
1311
+ this.logger.error("update index failure attempt failed", {
1312
+ id: row.id,
1313
+ error: updateErr
1314
+ });
1315
+ }
1316
+ }
1317
+ }
1318
+ return result;
1319
+ }
1320
+ /**
1321
+ * Deterministically rebuild IndexDB from StateDB (`vledger index rebuild`).
1322
+ * Also refreshes internal token cache, migration chain, and token distributions.
1323
+ */
1324
+ async rebuildIndex(options) {
1325
+ const chainAddress = options?.chainAddress || this.config?.address;
1326
+ const result = typeof this.indexdb.rebuild === "function" ? await this.indexdb.rebuild(this.statedb, {
1327
+ ...options,
1328
+ chainAddress
1329
+ }) : await (0, _ocap_indexdb.rebuildIndexFromState)(this.indexdb, this.statedb, {
1330
+ ...options,
1331
+ chainAddress
1332
+ });
1333
+ if (this.tokenCache && typeof this.tokenCache.clear === "function") this.tokenCache.clear();
1334
+ await this.buildMigrationChain();
1335
+ const { tokens } = await this.indexdb.listTokens({ paging: { size: 100 } });
1336
+ for (const token of tokens || []) if (token?.address) await this.tokenDistribution.updateByToken(token.address, true);
1337
+ return result;
1338
+ }
1024
1339
  async _getState({ table, id, dataKey, extraParams = {}, onRead = noop, expandContext = true, ctx }) {
1025
1340
  if (!id) throw new _ocap_util_lib_error.CustomError("INVALID_REQUEST", `Missing required parameter to read ${table} state`);
1026
1341
  const unified = (0, _arcblock_did.isValid)(id) ? (0, _ocap_util.toAddress)(id) : id;
package/lib/index.d.cts CHANGED
@@ -61,6 +61,26 @@ declare class OCAPResolver implements IResolver {
61
61
  getNodeInfo(): Promise<IResolverNodeInfo>;
62
62
  getNetInfo(): Promise<IResolverNetInfo>;
63
63
  getValidatorsInfo(): Promise<IResolverValidatorsInfo>;
64
+ getLatestCheckpoint({
65
+ height
66
+ }?: {
67
+ height?: number;
68
+ }): Promise<unknown>;
69
+ getLedgerEntry({
70
+ hash,
71
+ sequence
72
+ }?: {
73
+ hash?: string;
74
+ sequence?: number;
75
+ }): Promise<unknown>;
76
+ getMerkleProof({
77
+ sequence
78
+ }: {
79
+ sequence: number;
80
+ }): Promise<{
81
+ proof: unknown;
82
+ checkpoint: unknown;
83
+ } | null>;
64
84
  getConfig(): string;
65
85
  getAccountState({
66
86
  address,
@@ -133,7 +153,42 @@ declare class OCAPResolver implements IResolver {
133
153
  getChain(): Promise<Record<string, unknown> | null>;
134
154
  getToken(id: string): Promise<ITokenState | null>;
135
155
  initializeStateDB(): Promise<void>;
156
+ /**
157
+ * Persist a durable trail for a failed indexdb write from connectIndexDB()'s statedb
158
+ * listeners. The write path itself is fire-and-forget (EventEmitter, no retry) — this
159
+ * lets a background drain/retry worker (or manual replay) recover without silently
160
+ * drifting from statedb. Best-effort: a persistence failure only logs, never throws
161
+ * (must not break the happy-path caller). See issue #67.
162
+ */
163
+ private recordIndexFailure;
136
164
  connectIndexDB(): void;
165
+ private listIndexFailureRows;
166
+ private deleteIndexFailureRow;
167
+ private replayIndexFailureRow;
168
+ /**
169
+ * Replay pending records in `indexdb.indexFailure` with exponential backoff and dead-letter cap (#67 Phase 2).
170
+ * - Fetches latest state from `statedb` when available (falling back to recorded `payload`), re-runs the index builder,
171
+ * and removes the row from `indexFailure` once persisted to `indexdb`.
172
+ * - Increments `attempts`, updates `lastError` & `lastAttemptAt` on failure, and stops auto-retrying once
173
+ * `attempts >= maxAttempts` (dead-letter status).
174
+ */
175
+ retryIndexFailures(options?: {
176
+ maxAttempts?: number;
177
+ baseDelayMs?: number;
178
+ now?: number;
179
+ force?: boolean;
180
+ }): Promise<{
181
+ retried: number;
182
+ recovered: number;
183
+ failed: number;
184
+ skippedBackoff: number;
185
+ deadLettered: number;
186
+ }>;
187
+ /**
188
+ * Deterministically rebuild IndexDB from StateDB (`vledger index rebuild`).
189
+ * Also refreshes internal token cache, migration chain, and token distributions.
190
+ */
191
+ rebuildIndex(options?: IRebuildOptions): Promise<IRebuildResult>;
137
192
  _getState<T = Record<string, unknown>>({
138
193
  table,
139
194
  id,
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "publishConfig": {
4
4
  "access": "public"
5
5
  },
6
- "version": "1.30.24",
6
+ "version": "1.30.25",
7
7
  "description": "GraphQL resolver built upon ocap statedb and GQL layer",
8
8
  "type": "module",
9
9
  "main": "./lib/index.cjs",
@@ -49,20 +49,20 @@
49
49
  "tsdown": "^0.18.4"
50
50
  },
51
51
  "dependencies": {
52
- "@arcblock/did": "1.30.24",
53
- "@arcblock/did-ext": "1.30.24",
54
- "@arcblock/did-util": "1.30.24",
52
+ "@arcblock/did": "1.30.25",
53
+ "@arcblock/did-ext": "1.30.25",
54
+ "@arcblock/did-util": "1.30.25",
55
55
  "@arcblock/nft-display": "^3.2.3",
56
- "@arcblock/validator": "1.30.24",
57
- "@ocap/config": "1.30.24",
58
- "@ocap/indexdb": "1.30.24",
59
- "@ocap/mcrypto": "1.30.24",
60
- "@ocap/message": "1.30.24",
61
- "@ocap/state": "1.30.24",
62
- "@ocap/tx-protocols": "1.30.24",
63
- "@ocap/types": "1.30.24",
64
- "@ocap/util": "1.30.24",
65
- "@ocap/wallet": "1.30.24",
56
+ "@arcblock/validator": "1.30.25",
57
+ "@ocap/config": "1.30.25",
58
+ "@ocap/indexdb": "1.30.25",
59
+ "@ocap/mcrypto": "1.30.25",
60
+ "@ocap/message": "1.30.25",
61
+ "@ocap/state": "1.30.25",
62
+ "@ocap/tx-protocols": "1.30.25",
63
+ "@ocap/types": "1.30.25",
64
+ "@ocap/util": "1.30.25",
65
+ "@ocap/wallet": "1.30.25",
66
66
  "debug": "^4.4.3",
67
67
  "express": "^4.22.1",
68
68
  "lodash": "^4.17.23",