@gzeoneth/gov-tracker 0.3.0 → 0.4.0-alpha.addr-feedback.e1dac80

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 (204) hide show
  1. package/README.md +1 -5
  2. package/dist/calldata/decoder.d.ts.map +1 -1
  3. package/dist/calldata/decoder.js +35 -76
  4. package/dist/calldata/decoder.js.map +1 -1
  5. package/dist/calldata/parameter-decoder.d.ts +21 -1
  6. package/dist/calldata/parameter-decoder.d.ts.map +1 -1
  7. package/dist/calldata/parameter-decoder.js +30 -0
  8. package/dist/calldata/parameter-decoder.js.map +1 -1
  9. package/dist/calldata/retryable-ticket.d.ts +2 -2
  10. package/dist/calldata/retryable-ticket.d.ts.map +1 -1
  11. package/dist/calldata/retryable-ticket.js +17 -12
  12. package/dist/calldata/retryable-ticket.js.map +1 -1
  13. package/dist/calldata/signature-lookup.js +5 -4
  14. package/dist/calldata/signature-lookup.js.map +1 -1
  15. package/dist/cli/cli.js +39 -19
  16. package/dist/cli/cli.js.map +1 -1
  17. package/dist/cli/lib/cli.d.ts +4 -2
  18. package/dist/cli/lib/cli.d.ts.map +1 -1
  19. package/dist/cli/lib/cli.js +61 -58
  20. package/dist/cli/lib/cli.js.map +1 -1
  21. package/dist/cli/lib/json-state.js +1 -1
  22. package/dist/cli/lib/json-state.js.map +1 -1
  23. package/dist/cli/tui/components/StageProgress.js +1 -1
  24. package/dist/cli/tui/components/StageProgress.js.map +1 -1
  25. package/dist/cli/tui/components/StageRow.d.ts.map +1 -1
  26. package/dist/cli/tui/components/StageRow.js +15 -20
  27. package/dist/cli/tui/components/StageRow.js.map +1 -1
  28. package/dist/cli/tui/hooks/useCache.d.ts.map +1 -1
  29. package/dist/cli/tui/hooks/useCache.js +2 -1
  30. package/dist/cli/tui/hooks/useCache.js.map +1 -1
  31. package/dist/cli/tui/hooks/useElectionData.d.ts.map +1 -1
  32. package/dist/cli/tui/hooks/useElectionData.js +3 -2
  33. package/dist/cli/tui/hooks/useElectionData.js.map +1 -1
  34. package/dist/cli/tui/hooks/useProposals.d.ts.map +1 -1
  35. package/dist/cli/tui/hooks/useProposals.js +24 -34
  36. package/dist/cli/tui/hooks/useProposals.js.map +1 -1
  37. package/dist/cli/tui/hooks/useStageCalldata.d.ts.map +1 -1
  38. package/dist/cli/tui/hooks/useStageCalldata.js +2 -1
  39. package/dist/cli/tui/hooks/useStageCalldata.js.map +1 -1
  40. package/dist/cli/tui/utils/index.d.ts +6 -6
  41. package/dist/cli/tui/utils/index.d.ts.map +1 -1
  42. package/dist/cli/tui/utils/index.js +14 -14
  43. package/dist/cli/tui/utils/index.js.map +1 -1
  44. package/dist/cli/tui/utils/markdown-parser.d.ts +5 -0
  45. package/dist/cli/tui/utils/markdown-parser.d.ts.map +1 -1
  46. package/dist/cli/tui/utils/markdown-parser.js +16 -0
  47. package/dist/cli/tui/utils/markdown-parser.js.map +1 -1
  48. package/dist/cli/tui/utils/navigation.d.ts.map +1 -1
  49. package/dist/cli/tui/utils/navigation.js +5 -1
  50. package/dist/cli/tui/utils/navigation.js.map +1 -1
  51. package/dist/cli/tui/utils/proposal-detail-helpers.js +6 -6
  52. package/dist/cli/tui/utils/proposal-detail-helpers.js.map +1 -1
  53. package/dist/cli/tui/utils/time.d.ts +4 -4
  54. package/dist/cli/tui/utils/time.d.ts.map +1 -1
  55. package/dist/cli/tui/utils/time.js +13 -11
  56. package/dist/cli/tui/utils/time.js.map +1 -1
  57. package/dist/cli/tui/views/DescriptionView.d.ts.map +1 -1
  58. package/dist/cli/tui/views/DescriptionView.js +4 -2
  59. package/dist/cli/tui/views/DescriptionView.js.map +1 -1
  60. package/dist/cli/tui/views/ElectionView.d.ts.map +1 -1
  61. package/dist/cli/tui/views/ElectionView.js +3 -3
  62. package/dist/cli/tui/views/ElectionView.js.map +1 -1
  63. package/dist/cli/tui/views/StageView.d.ts.map +1 -1
  64. package/dist/cli/tui/views/StageView.js +1 -1
  65. package/dist/cli/tui/views/StageView.js.map +1 -1
  66. package/dist/constants.d.ts +11 -1
  67. package/dist/constants.d.ts.map +1 -1
  68. package/dist/constants.js +16 -4
  69. package/dist/constants.js.map +1 -1
  70. package/dist/data/bundled-cache.json +21513 -22619
  71. package/dist/deduplication.d.ts.map +1 -1
  72. package/dist/deduplication.js +36 -33
  73. package/dist/deduplication.js.map +1 -1
  74. package/dist/discovery/governor-discovery.d.ts.map +1 -1
  75. package/dist/discovery/governor-discovery.js +44 -49
  76. package/dist/discovery/governor-discovery.js.map +1 -1
  77. package/dist/discovery/security-council.d.ts +15 -0
  78. package/dist/discovery/security-council.d.ts.map +1 -1
  79. package/dist/discovery/security-council.js +42 -19
  80. package/dist/discovery/security-council.js.map +1 -1
  81. package/dist/discovery/timelock-discovery.d.ts.map +1 -1
  82. package/dist/discovery/timelock-discovery.js +62 -84
  83. package/dist/discovery/timelock-discovery.js.map +1 -1
  84. package/dist/election/contracts.d.ts.map +1 -1
  85. package/dist/election/contracts.js +4 -1
  86. package/dist/election/contracts.js.map +1 -1
  87. package/dist/election/details.d.ts.map +1 -1
  88. package/dist/election/details.js +35 -33
  89. package/dist/election/details.js.map +1 -1
  90. package/dist/election/index.d.ts +3 -6
  91. package/dist/election/index.d.ts.map +1 -1
  92. package/dist/election/index.js +7 -14
  93. package/dist/election/index.js.map +1 -1
  94. package/dist/election/params.d.ts +8 -1
  95. package/dist/election/params.d.ts.map +1 -1
  96. package/dist/election/params.js +48 -13
  97. package/dist/election/params.js.map +1 -1
  98. package/dist/election/participants.d.ts.map +1 -1
  99. package/dist/election/participants.js +19 -27
  100. package/dist/election/participants.js.map +1 -1
  101. package/dist/election/proposal-ids.d.ts +10 -0
  102. package/dist/election/proposal-ids.d.ts.map +1 -1
  103. package/dist/election/proposal-ids.js +42 -5
  104. package/dist/election/proposal-ids.js.map +1 -1
  105. package/dist/election/status.d.ts.map +1 -1
  106. package/dist/election/status.js +6 -0
  107. package/dist/election/status.js.map +1 -1
  108. package/dist/index.d.ts +9 -6
  109. package/dist/index.d.ts.map +1 -1
  110. package/dist/index.js +17 -10
  111. package/dist/index.js.map +1 -1
  112. package/dist/simulation/simulation-data.d.ts +2 -2
  113. package/dist/simulation/simulation-data.d.ts.map +1 -1
  114. package/dist/simulation/simulation-data.js +36 -26
  115. package/dist/simulation/simulation-data.js.map +1 -1
  116. package/dist/stages/builder.js +1 -1
  117. package/dist/stages/builder.js.map +1 -1
  118. package/dist/stages/l2-to-l1-message.d.ts.map +1 -1
  119. package/dist/stages/l2-to-l1-message.js +5 -11
  120. package/dist/stages/l2-to-l1-message.js.map +1 -1
  121. package/dist/stages/proposal-queued.d.ts.map +1 -1
  122. package/dist/stages/proposal-queued.js +4 -1
  123. package/dist/stages/proposal-queued.js.map +1 -1
  124. package/dist/stages/retryables.d.ts +4 -3
  125. package/dist/stages/retryables.d.ts.map +1 -1
  126. package/dist/stages/retryables.js +35 -57
  127. package/dist/stages/retryables.js.map +1 -1
  128. package/dist/stages/timelock.d.ts +4 -1
  129. package/dist/stages/timelock.d.ts.map +1 -1
  130. package/dist/stages/timelock.js +59 -67
  131. package/dist/stages/timelock.js.map +1 -1
  132. package/dist/stages/utils.d.ts +67 -5
  133. package/dist/stages/utils.d.ts.map +1 -1
  134. package/dist/stages/utils.js +183 -42
  135. package/dist/stages/utils.js.map +1 -1
  136. package/dist/tracker/checkpoint-helpers.d.ts +2 -1
  137. package/dist/tracker/checkpoint-helpers.d.ts.map +1 -1
  138. package/dist/tracker/checkpoint-helpers.js +4 -7
  139. package/dist/tracker/checkpoint-helpers.js.map +1 -1
  140. package/dist/tracker/discovery.d.ts.map +1 -1
  141. package/dist/tracker/discovery.js +60 -43
  142. package/dist/tracker/discovery.js.map +1 -1
  143. package/dist/tracker/pipeline.d.ts +25 -6
  144. package/dist/tracker/pipeline.d.ts.map +1 -1
  145. package/dist/tracker/pipeline.js +428 -211
  146. package/dist/tracker/pipeline.js.map +1 -1
  147. package/dist/tracker/query.d.ts +21 -0
  148. package/dist/tracker/query.d.ts.map +1 -1
  149. package/dist/tracker/query.js +86 -9
  150. package/dist/tracker/query.js.map +1 -1
  151. package/dist/tracker/stage-runner.d.ts +62 -0
  152. package/dist/tracker/stage-runner.d.ts.map +1 -0
  153. package/dist/tracker/stage-runner.js +80 -0
  154. package/dist/tracker/stage-runner.js.map +1 -0
  155. package/dist/tracker/state.d.ts +65 -0
  156. package/dist/tracker/state.d.ts.map +1 -1
  157. package/dist/tracker/state.js +194 -14
  158. package/dist/tracker/state.js.map +1 -1
  159. package/dist/tracker.d.ts +36 -8
  160. package/dist/tracker.d.ts.map +1 -1
  161. package/dist/tracker.js +246 -193
  162. package/dist/tracker.js.map +1 -1
  163. package/dist/types/core.d.ts +3 -2
  164. package/dist/types/core.d.ts.map +1 -1
  165. package/dist/types/core.js +3 -2
  166. package/dist/types/core.js.map +1 -1
  167. package/dist/types/simulation.d.ts +2 -2
  168. package/dist/types/simulation.d.ts.map +1 -1
  169. package/dist/types/tracking.d.ts +11 -0
  170. package/dist/types/tracking.d.ts.map +1 -1
  171. package/dist/utils/log-filters.d.ts.map +1 -1
  172. package/dist/utils/log-filters.js +5 -9
  173. package/dist/utils/log-filters.js.map +1 -1
  174. package/dist/utils/multicall.d.ts +0 -1
  175. package/dist/utils/multicall.d.ts.map +1 -1
  176. package/dist/utils/rpc-utils.d.ts +11 -0
  177. package/dist/utils/rpc-utils.d.ts.map +1 -1
  178. package/dist/utils/rpc-utils.js +18 -1
  179. package/dist/utils/rpc-utils.js.map +1 -1
  180. package/dist/utils/timing.d.ts +11 -4
  181. package/dist/utils/timing.d.ts.map +1 -1
  182. package/dist/utils/timing.js +45 -15
  183. package/dist/utils/timing.js.map +1 -1
  184. package/package.json +7 -6
  185. package/dist/cli/tui/utils/calldata-formatter.d.ts +0 -7
  186. package/dist/cli/tui/utils/calldata-formatter.d.ts.map +0 -1
  187. package/dist/cli/tui/utils/calldata-formatter.js +0 -14
  188. package/dist/cli/tui/utils/calldata-formatter.js.map +0 -1
  189. package/dist/cli/tui/utils/stage-formatter.d.ts +0 -7
  190. package/dist/cli/tui/utils/stage-formatter.d.ts.map +0 -1
  191. package/dist/cli/tui/utils/stage-formatter.js +0 -14
  192. package/dist/cli/tui/utils/stage-formatter.js.map +0 -1
  193. package/dist/cli/tui/utils/text.d.ts +0 -7
  194. package/dist/cli/tui/utils/text.d.ts.map +0 -1
  195. package/dist/cli/tui/utils/text.js +0 -12
  196. package/dist/cli/tui/utils/text.js.map +0 -1
  197. package/dist/election/prepare.d.ts +0 -10
  198. package/dist/election/prepare.d.ts.map +0 -1
  199. package/dist/election/prepare.js +0 -52
  200. package/dist/election/prepare.js.map +0 -1
  201. package/dist/election/tracking.d.ts +0 -28
  202. package/dist/election/tracking.d.ts.map +0 -1
  203. package/dist/election/tracking.js +0 -412
  204. package/dist/election/tracking.js.map +0 -1
package/dist/tracker.js CHANGED
@@ -27,74 +27,85 @@ const governor_discovery_1 = require("./discovery/governor-discovery");
27
27
  const timelock_discovery_1 = require("./discovery/timelock-discovery");
28
28
  const utils_1 = require("./stages/utils");
29
29
  const { tracker: logTracker, discovery: logDiscovery } = logger_1.loggers;
30
- /**
31
- * Build a TrackingContext with current block numbers and timestamp.
32
- * Called once at the start of a tracking session for consistent state.
33
- */
34
- async function buildTrackingContext(options) {
35
- const { l2Provider, l1Provider, novaProvider, chunkSize, skipCache } = options;
36
- const l2BlockInfo = await (0, timing_1.getCurrentBlockInfo)(l2Provider);
37
- const context = {
38
- l2BlockNumber: l2BlockInfo.blockNumber,
39
- timestamp: l2BlockInfo.timestamp,
40
- chunkSize,
41
- skipCache,
42
- };
43
- logTracker("buildTrackingContext: l2Block=%d timestamp=%d", context.l2BlockNumber, context.timestamp);
44
- if (l1Provider) {
45
- try {
46
- const l1Block = await (0, timing_1.getL1BlockNumberFromL2)(l2Provider);
47
- context.l1BlockNumber = l1Block.toNumber();
48
- logTracker("buildTrackingContext: l1Block=%d", context.l1BlockNumber);
49
- }
50
- catch (err) {
51
- logTracker("buildTrackingContext: failed to get L1 block: %s", err.message);
52
- }
53
- }
54
- if (novaProvider) {
55
- try {
56
- const novaBlockInfo = await (0, timing_1.getCurrentBlockInfo)(novaProvider);
57
- context.novaBlockNumber = novaBlockInfo.blockNumber;
58
- logTracker("buildTrackingContext: novaBlock=%d", context.novaBlockNumber);
59
- }
60
- catch (err) {
61
- logTracker("buildTrackingContext: failed to get Nova block: %s", err.message);
62
- }
63
- }
64
- return context;
65
- }
66
30
  // Import context and pipeline from tracker modules
67
31
  const state_1 = require("./tracker/state");
68
32
  const pipeline_1 = require("./tracker/pipeline");
33
+ const status_1 = require("./election/status");
34
+ const constants_2 = require("./constants");
69
35
  // Import from focused modules
70
36
  const cache_1 = require("./tracker/cache");
71
37
  const discovery_1 = require("./tracker/discovery");
72
38
  const discovery_2 = require("./tracker/discovery");
73
39
  const query_1 = require("./tracker/query");
74
40
  const execute_1 = require("./tracker/execute");
41
+ /**
42
+ * Build ElectionProposalStatus from TrackingState.
43
+ * This bridges the unified pipeline approach with the existing election API.
44
+ */
45
+ function buildElectionStatusFromState(state) {
46
+ // Extract basic state with defaults
47
+ const electionIndex = (0, state_1.getElectionIndex)(state) ?? 0;
48
+ const nomineeProposalId = (0, state_1.getNomineeProposalId)(state) ?? null;
49
+ const memberProposalId = (0, state_1.getMemberProposalId)(state) ?? null;
50
+ const cohort = (0, state_1.getElectionCohort)(state) ?? 0;
51
+ const compliantNomineeCount = (0, state_1.getCompliantNomineeCount)(state) ?? 0;
52
+ const targetNomineeCount = (0, state_1.getTargetNomineeCount)(state) ?? constants_2.TIMING.SECURITY_COUNCIL_TARGET_NOMINEES;
53
+ const vettingDeadline = (0, state_1.getVettingDeadline)(state) ?? null;
54
+ // Stage lookups (typed for data access)
55
+ const createStage = (0, utils_1.findStage)(state.stages, "CREATE_ELECTION");
56
+ const nomineeStage = (0, utils_1.findStage)(state.stages, "NOMINEE_ELECTION");
57
+ const vettingStage = (0, utils_1.findStage)(state.stages, "NOMINEE_VETTING");
58
+ const memberStage = (0, utils_1.findStage)(state.stages, "MEMBER_ELECTION");
59
+ // Extract proposal states from typed stages
60
+ const nomineeProposalState = nomineeStage?.data
61
+ ?.proposalState ?? null;
62
+ const memberProposalState = memberStage?.data
63
+ ?.proposalState ?? null;
64
+ const isInVettingPeriod = vettingStage?.status === "PENDING";
65
+ // Determine failure from any failed stage using Map for O(1) lookup
66
+ const stageFailureReasons = new Map([
67
+ [nomineeStage, "Nominee election failed"],
68
+ [vettingStage, "Not enough compliant nominees"],
69
+ [memberStage, "Member election failed"],
70
+ ]);
71
+ const failedStage = [nomineeStage, vettingStage, memberStage].find((s) => s?.status === "FAILED");
72
+ const failureReason = failedStage ? stageFailureReasons.get(failedStage) : undefined;
73
+ return {
74
+ electionIndex,
75
+ phase: (0, status_1.determineElectionPhase)(nomineeProposalState, memberProposalId, memberProposalState, isInVettingPeriod),
76
+ cohort,
77
+ nomineeProposalId,
78
+ memberProposalId,
79
+ nomineeProposalState,
80
+ memberProposalState,
81
+ compliantNomineeCount,
82
+ targetNomineeCount,
83
+ vettingDeadline,
84
+ isInVettingPeriod,
85
+ canProceedToMemberPhase: vettingStage?.status === "READY",
86
+ canExecuteMember: memberStage?.status === "READY",
87
+ stages: state.stages,
88
+ isFailed: failedStage ? true : undefined,
89
+ failureReason,
90
+ timelockOperationId: (0, state_1.getElectionTimelockOperationId)(state),
91
+ creationTxHash: createStage?.transactions?.[0]?.hash,
92
+ nomineeExecuteTxHash: vettingStage?.transactions?.[0]?.hash,
93
+ memberExecuteTxHash: memberStage?.transactions?.find((t) => t.description === "executed")?.hash,
94
+ };
95
+ }
75
96
  /**
76
97
  * Extract TimelockLink from stages if PROPOSAL_QUEUED is completed
77
98
  */
78
99
  function extractTimelockLink(stages) {
79
100
  const queuedStage = (0, utils_1.findStage)(stages, "PROPOSAL_QUEUED");
80
- if (!queuedStage ||
81
- queuedStage.type !== "PROPOSAL_QUEUED" ||
82
- queuedStage.status !== "COMPLETED") {
83
- return undefined;
84
- }
85
- const txHash = queuedStage.transactions[0]?.hash;
86
- const operationId = queuedStage.data.operationId;
87
- const timelockAddress = queuedStage.data.timelockAddress;
88
- const queueBlockNumber = queuedStage.transactions[0]?.blockNumber;
89
- if (!txHash || !operationId || !timelockAddress || !queueBlockNumber) {
101
+ if (queuedStage?.status !== "COMPLETED" || queuedStage.type !== "PROPOSAL_QUEUED") {
90
102
  return undefined;
91
103
  }
92
- return {
93
- txHash,
94
- operationId,
95
- timelockAddress,
96
- queueBlockNumber,
97
- };
104
+ const tx = queuedStage.transactions[0];
105
+ const { operationId, timelockAddress } = queuedStage.data;
106
+ return tx?.hash && operationId && timelockAddress && tx.blockNumber
107
+ ? { txHash: tx.hash, operationId, timelockAddress, queueBlockNumber: tx.blockNumber }
108
+ : undefined;
98
109
  }
99
110
  /**
100
111
  * Main proposal stage tracker class
@@ -182,16 +193,15 @@ class ProposalStageTracker {
182
193
  logTracker("cleared cache entry: %s", baseCacheKey);
183
194
  cleared++;
184
195
  }
185
- // Clear all operation-specific keys for this tx
196
+ // Clear all operation-specific keys for this tx in parallel
186
197
  const allKeys = await this.cache.keys(prefix);
187
198
  const keys = Array.isArray(allKeys) ? allKeys : Array.from(allKeys);
188
- for (const key of keys) {
189
- if (key.startsWith(prefix)) {
190
- await this.cache.delete(key);
191
- logTracker("cleared cache entry: %s", key);
192
- cleared++;
193
- }
194
- }
199
+ const keysToDelete = keys.filter((key) => key.startsWith(prefix));
200
+ await Promise.all(keysToDelete.map(async (key) => {
201
+ await this.cache.delete(key);
202
+ logTracker("cleared cache entry: %s", key);
203
+ }));
204
+ cleared += keysToDelete.length;
195
205
  return cleared;
196
206
  }
197
207
  // Watermark Management
@@ -221,7 +231,7 @@ class ProposalStageTracker {
221
231
  * For COMPLETED elections, automatically fetches and caches nominee/member
222
232
  * election details to enable zero-RPC reads for historical elections.
223
233
  *
224
- * @param electionStatus - Election status from trackElectionProposal
234
+ * @param electionStatus - Election status from trackElection()
225
235
  * @param options.nomineeDetails - Pre-fetched nominee details (skips RPC fetch)
226
236
  * @param options.memberDetails - Pre-fetched member details (skips RPC fetch)
227
237
  */
@@ -369,6 +379,17 @@ class ProposalStageTracker {
369
379
  async getStats(maxErrorCount = 5) {
370
380
  return (0, query_1.getStats)(this.cache, maxErrorCount);
371
381
  }
382
+ /**
383
+ * Get the highest Security Council nonce from incomplete checkpoints.
384
+ *
385
+ * Used to determine if lower-nonce SC operations should be skipped
386
+ * (superseded by higher nonce operations).
387
+ *
388
+ * @returns The highest SC nonce found, or null if no SC operations exist
389
+ */
390
+ async getHighestScNonce() {
391
+ return (0, query_1.getHighestScNonceFromCheckpoints)(this.cache);
392
+ }
372
393
  // Main Tracking Entry Points
373
394
  /**
374
395
  * Track from transaction hash (primary tracking entry point)
@@ -412,7 +433,7 @@ class ProposalStageTracker {
412
433
  logTracker("loaded checkpoint from cache: %s", opCacheKey);
413
434
  }
414
435
  }
415
- // Fall back to base cache key (for governor proposals or legacy checkpoints)
436
+ // Fall back to base cache key (governor proposals or pre-modular cache entries)
416
437
  if (!checkpoint) {
417
438
  checkpoint = (await this.cache.get(baseCacheKey)) ?? undefined;
418
439
  if (checkpoint) {
@@ -516,31 +537,85 @@ class ProposalStageTracker {
516
537
  logTracker("no proposal or timelock operations found in tx");
517
538
  return [];
518
539
  }
540
+ // ============================================================================
541
+ // Unified Pipeline Tracking
542
+ // ============================================================================
519
543
  /**
520
- * Track governor proposal using TrackingState (stateful tracking)
544
+ * Unified pipeline tracking method.
545
+ * Handles all common tracking patterns: state creation, pipeline execution,
546
+ * checkpoint management, and timelockOpKey derivation.
521
547
  */
522
- async trackGovernorWithPipeline(governorAddress, proposalId, creationTxHash, checkpoint, cacheKey) {
523
- const input = {
524
- type: "governor",
525
- governorAddress,
526
- proposalId,
527
- creationTxHash,
528
- };
529
- // Create tracking context
548
+ async runTrackingPipeline(config) {
549
+ // Load linked timelock checkpoint if configured and available
550
+ let linkedTimelockCheckpoint;
551
+ if (config.loadLinkedTimelock && this.cache && config.checkpoint?.metadata?.timelockOpKey) {
552
+ linkedTimelockCheckpoint =
553
+ (await this.cache.get(config.checkpoint.metadata.timelockOpKey)) ??
554
+ undefined;
555
+ if (linkedTimelockCheckpoint) {
556
+ logTracker("loaded linked timelock checkpoint: %s", config.checkpoint.metadata.timelockOpKey);
557
+ }
558
+ }
559
+ // Create tracking state
530
560
  const initialState = (0, state_1.createTrackingState)({
531
561
  providers: {
532
562
  l2: this.l2Provider,
533
563
  l1: this.l1Provider,
534
564
  nova: this.novaProvider,
535
565
  },
536
- input,
566
+ input: config.input,
537
567
  onProgress: this.onProgress,
538
568
  chunkingConfig: this.chunkingConfig,
569
+ checkpoint: config.checkpoint,
570
+ linkedTimelockCheckpoint,
571
+ cacheKey: config.cacheKey,
572
+ callScheduledData: config.callScheduledData,
573
+ });
574
+ // Run the pipeline
575
+ let finalState = await config.pipeline(initialState);
576
+ // Derive and set timelockOpKey if configured
577
+ if (config.timelockKeySource && !finalState.timelockOpKey) {
578
+ const { stageType, txDescription } = config.timelockKeySource;
579
+ const operationId = stageType === "MEMBER_ELECTION"
580
+ ? (0, state_1.getElectionTimelockOperationId)(finalState)
581
+ : (0, state_1.getOperationId)(finalState);
582
+ const stage = finalState.stages.find((s) => s.type === stageType);
583
+ const txHash = stage?.transactions?.find((t) => t.description === txDescription)?.hash;
584
+ if (operationId && txHash) {
585
+ const timelockOpKey = (0, checkpoint_helpers_1.timelockOpCacheKey)(txHash, operationId);
586
+ finalState = (0, state_1.setTimelockOpKey)(finalState, timelockOpKey);
587
+ }
588
+ }
589
+ // Save checkpoints (unless caller handles caching)
590
+ if (!config.skipCaching && this.cache && config.cacheKey) {
591
+ if (config.modularCaching) {
592
+ await this.saveModularCheckpoints(finalState, config.cacheKey);
593
+ }
594
+ else {
595
+ const checkpoint = (0, state_1.createCheckpoint)(finalState);
596
+ checkpoint.metadata = { errorCount: 0, lastTrackedAt: Date.now() };
597
+ await this.cache.set(config.cacheKey, checkpoint);
598
+ logTracker("saved checkpoint to cache: %s", config.cacheKey);
599
+ }
600
+ }
601
+ return finalState;
602
+ }
603
+ /**
604
+ * Track governor proposal using TrackingState (stateful tracking)
605
+ * Uses modular caching: parent stages saved separately from timelock stages.
606
+ */
607
+ async trackGovernorWithPipeline(governorAddress, proposalId, creationTxHash, checkpoint, cacheKey) {
608
+ // Run unified pipeline (with skipCaching - we handle election case specially)
609
+ const finalState = await this.runTrackingPipeline({
610
+ input: { type: "governor", governorAddress, proposalId, creationTxHash },
539
611
  checkpoint,
540
612
  cacheKey,
613
+ pipeline: pipeline_1.trackGovernorPipeline,
614
+ loadLinkedTimelock: true,
615
+ modularCaching: true,
616
+ skipCaching: true,
617
+ timelockKeySource: { stageType: "PROPOSAL_QUEUED", txDescription: "queued" },
541
618
  });
542
- // Run the governor pipeline (stages 1-7)
543
- const finalState = await (0, pipeline_1.trackGovernorPipeline)(initialState);
544
619
  // Build result from state
545
620
  const result = this.buildResultFromState(finalState);
546
621
  // Track election status if this is an election governor proposal
@@ -556,14 +631,11 @@ class ProposalStageTracker {
556
631
  }
557
632
  return result;
558
633
  }
559
- // If election tracking failed, fall through to save tx:* checkpoint for retry
560
634
  logTracker("election tracking failed, saving tx:* checkpoint for retry");
561
635
  }
562
- // Save checkpoint to cache (non-elections and failed election tracking)
636
+ // Save checkpoints using modular caching
563
637
  if (this.cache && cacheKey) {
564
- result.checkpoint.metadata = { errorCount: 0, lastTrackedAt: Date.now() };
565
- await this.cache.set(cacheKey, result.checkpoint);
566
- logTracker("saved checkpoint to cache: %s", cacheKey);
638
+ await this.saveModularCheckpoints(finalState, cacheKey);
567
639
  }
568
640
  return result;
569
641
  }
@@ -571,37 +643,55 @@ class ProposalStageTracker {
571
643
  * Track timelock operation using TrackingState (stateful tracking)
572
644
  */
573
645
  async trackTimelockWithPipeline(timelockAddress, operationId, scheduledTxHash, checkpoint, cacheKey, callScheduledEvent) {
574
- const input = {
575
- type: "timelock",
576
- timelockAddress,
577
- operationId,
578
- scheduledTxHash,
579
- };
580
- // Create tracking context with bootstrap data
581
- const initialState = (0, state_1.createTrackingState)({
582
- providers: {
583
- l2: this.l2Provider,
584
- l1: this.l1Provider,
585
- nova: this.novaProvider,
586
- },
587
- input,
588
- onProgress: this.onProgress,
589
- chunkingConfig: this.chunkingConfig,
646
+ // Run unified pipeline
647
+ const finalState = await this.runTrackingPipeline({
648
+ input: { type: "timelock", timelockAddress, operationId, scheduledTxHash },
590
649
  checkpoint,
591
650
  cacheKey,
651
+ pipeline: pipeline_1.trackTimelockPipeline,
652
+ loadLinkedTimelock: false,
653
+ modularCaching: false,
592
654
  callScheduledData: callScheduledEvent ? [callScheduledEvent] : undefined,
593
655
  });
594
- // Run the timelock pipeline (stages 4-7)
595
- const finalState = await (0, pipeline_1.trackTimelockPipeline)(initialState);
596
- // Build result from state
597
- const result = this.buildResultFromState(finalState);
598
- // Save checkpoint to cache
599
- if (this.cache && cacheKey) {
600
- result.checkpoint.metadata = { errorCount: 0, lastTrackedAt: Date.now() };
601
- await this.cache.set(cacheKey, result.checkpoint);
602
- logTracker("saved checkpoint to cache: %s", cacheKey);
656
+ return this.buildResultFromState(finalState);
657
+ }
658
+ /**
659
+ * Track election using TrackingState (stateful tracking)
660
+ *
661
+ * This is the unified pipeline version that tracks elections through the
662
+ * same stage-based approach as proposals and timelock operations.
663
+ * Uses modular caching: election stages saved separately from timelock stages.
664
+ */
665
+ async trackElectionWithPipeline(electionIndex, checkpoint, cacheKey) {
666
+ // Run unified pipeline (caller handles caching)
667
+ const finalState = await this.runTrackingPipeline({
668
+ input: { type: "election", electionIndex },
669
+ checkpoint,
670
+ cacheKey,
671
+ pipeline: pipeline_1.trackElectionPipeline,
672
+ loadLinkedTimelock: true,
673
+ modularCaching: true,
674
+ skipCaching: true,
675
+ timelockKeySource: { stageType: "MEMBER_ELECTION", txDescription: "executed" },
676
+ });
677
+ return { status: buildElectionStatusFromState(finalState), finalState };
678
+ }
679
+ /**
680
+ * Save checkpoints using modular caching.
681
+ * Saves parent stages and timelock stages in separate checkpoints.
682
+ */
683
+ async saveModularCheckpoints(state, parentCacheKey) {
684
+ if (!this.cache)
685
+ return;
686
+ const { parentCheckpoint, timelockCheckpoint, timelockOpKey } = (0, state_1.createModularCheckpoints)(state, parentCacheKey);
687
+ // Save parent checkpoint
688
+ await this.cache.set(parentCacheKey, parentCheckpoint);
689
+ logTracker("saved parent checkpoint: %s", parentCacheKey);
690
+ // Save timelock checkpoint if we have one
691
+ if (timelockCheckpoint && timelockOpKey) {
692
+ await this.cache.set(timelockOpKey, timelockCheckpoint);
693
+ logTracker("saved linked timelock checkpoint: %s", timelockOpKey);
603
694
  }
604
- return result;
605
695
  }
606
696
  /**
607
697
  * Build TrackingResult from TrackingState
@@ -639,38 +729,29 @@ class ProposalStageTracker {
639
729
  * ```
640
730
  */
641
731
  async trackFromCheckpoint(checkpoint) {
642
- const input = checkpoint.input;
643
- if (input.type === "governor") {
644
- if (!input.creationTxHash) {
645
- throw new Error("Governor checkpoint missing creationTxHash");
646
- }
647
- const results = await this.trackByTxHash(input.creationTxHash);
732
+ const { input } = checkpoint;
733
+ const trackAndWarn = async (txHash, entityType) => {
734
+ const results = await this.trackByTxHash(txHash);
648
735
  if (results.length === 0) {
649
- throw new Error(`No proposal found in tx ${input.creationTxHash}`);
736
+ throw new Error(`No ${entityType} found in tx ${txHash}`);
650
737
  }
651
738
  if (results.length > 1) {
652
739
  logTracker("WARNING: trackFromCheckpoint found %d results in tx %s, returning first only. " +
653
- "Use trackByTxHash() to get all results.", results.length, input.creationTxHash);
740
+ "Use trackByTxHash() to get all results.", results.length, txHash);
654
741
  }
655
742
  return results[0];
743
+ };
744
+ if (input.type === "governor") {
745
+ if (!input.creationTxHash)
746
+ throw new Error("Governor checkpoint missing creationTxHash");
747
+ return trackAndWarn(input.creationTxHash, "proposal");
656
748
  }
657
- else if (input.type === "timelock") {
658
- if (!input.scheduledTxHash) {
749
+ if (input.type === "timelock") {
750
+ if (!input.scheduledTxHash)
659
751
  throw new Error("Timelock checkpoint missing scheduledTxHash");
660
- }
661
- const results = await this.trackByTxHash(input.scheduledTxHash);
662
- if (results.length === 0) {
663
- throw new Error(`No timelock operation found in tx ${input.scheduledTxHash}`);
664
- }
665
- if (results.length > 1) {
666
- logTracker("WARNING: trackFromCheckpoint found %d results in tx %s, returning first only. " +
667
- "Use trackByTxHash() to get all results.", results.length, input.scheduledTxHash);
668
- }
669
- return results[0];
670
- }
671
- else {
672
- throw new Error(`Unsupported checkpoint input type: ${input.type}`);
752
+ return trackAndWarn(input.scheduledTxHash, "timelock operation");
673
753
  }
754
+ throw new Error(`Unsupported checkpoint input type: ${input.type}`);
674
755
  }
675
756
  // Transaction Preparation
676
757
  /**
@@ -728,7 +809,7 @@ class ProposalStageTracker {
728
809
  * Track election status for a given proposal ID.
729
810
  *
730
811
  * Searches through elections to find the one containing this proposal,
731
- * then tracks the full election lifecycle.
812
+ * then tracks the full election lifecycle using the unified pipeline.
732
813
  */
733
814
  async trackElectionStatus(proposalId) {
734
815
  logTracker("trackElectionStatus for proposal %s", proposalId);
@@ -741,9 +822,8 @@ class ProposalStageTracker {
741
822
  return null;
742
823
  }
743
824
  logTracker("found election index %d for proposal %s", electionIndex, proposalId);
744
- return (0, election_1.trackElectionProposal)(electionIndex, this.l2Provider, this.l1Provider, {
745
- novaProvider: this.novaProvider,
746
- });
825
+ // Use unified pipeline via trackElection
826
+ return this.trackElection(electionIndex);
747
827
  }
748
828
  catch (error) {
749
829
  // Election tracking is non-critical - log and return null
@@ -763,35 +843,36 @@ class ProposalStageTracker {
763
843
  * - Incomplete elections: Makes fresh RPC calls and updates cache
764
844
  * - No cache: Always makes fresh RPC calls
765
845
  *
846
+ * To force fresh tracking, clear the cache before calling this method.
847
+ *
766
848
  * @param electionIndex - Election index (0-based)
767
- * @param options.force - Force fresh tracking even for completed elections
768
849
  * @returns Election status
769
850
  */
770
- async trackElection(electionIndex, options = {}) {
771
- logTracker("trackElection for index %d (force=%s)", electionIndex, options.force ?? false);
851
+ async trackElection(electionIndex) {
852
+ logTracker("trackElection for index %d", electionIndex);
853
+ const cacheKey = `election:${electionIndex}`;
772
854
  // Check cache first for completed elections (skip RPC calls)
773
- if (this.cache && !options.force) {
855
+ if (this.cache) {
774
856
  const cached = await this.getElectionCheckpoint(electionIndex);
775
857
  if (cached && cached.status.phase === "COMPLETED") {
776
858
  logTracker("returning cached COMPLETED election %d (0 RPC calls)", electionIndex);
777
859
  return cached.status;
778
860
  }
779
861
  }
780
- // Build full tracking context for consistent state across all calls
781
- const context = await buildTrackingContext({
782
- l2Provider: this.l2Provider,
783
- l1Provider: this.l1Provider,
784
- novaProvider: this.novaProvider,
785
- skipCache: options.force,
786
- });
787
- // Track fresh for incomplete elections or cache miss
788
- const status = await (0, election_1.trackElectionProposal)(electionIndex, this.l2Provider, this.l1Provider, {
789
- novaProvider: this.novaProvider,
790
- l2BlockNumber: context.l2BlockNumber,
791
- timestamp: context.timestamp,
792
- skipCache: context.skipCache,
793
- });
862
+ // Load checkpoint from cache for resume
863
+ let checkpoint;
794
864
  if (this.cache) {
865
+ checkpoint = (await this.cache.get(cacheKey)) ?? undefined;
866
+ if (checkpoint) {
867
+ logTracker("loaded election checkpoint from cache: %s", cacheKey);
868
+ }
869
+ }
870
+ // Track using the unified pipeline
871
+ const { status, finalState } = await this.trackElectionWithPipeline(electionIndex, checkpoint, cacheKey);
872
+ // Save checkpoints using modular caching
873
+ if (this.cache) {
874
+ await this.saveModularCheckpoints(finalState, cacheKey);
875
+ // Also save election-specific data
795
876
  await this.saveElectionCheckpoint(status);
796
877
  }
797
878
  return status;
@@ -803,59 +884,31 @@ class ProposalStageTracker {
803
884
  * - COMPLETED elections: Returns cached data immediately (0 RPC calls)
804
885
  * - Incomplete elections: Makes fresh RPC calls and updates cache
805
886
  *
887
+ * To force fresh tracking, clear the cache before calling this method.
888
+ *
806
889
  * @param options.includeNext - Include the "next" election slot (default: true)
807
- * @param options.force - Force fresh tracking for all elections
808
890
  * @returns Array of election statuses
809
891
  */
810
892
  async trackAllElections(options = {}) {
811
- logTracker("trackAllElections (includeNext=%s, force=%s)", options.includeNext ?? true, options.force ?? false);
812
- // Build context once at the start for consistent state across all elections
813
- const context = await buildTrackingContext({
814
- l2Provider: this.l2Provider,
815
- l1Provider: this.l1Provider,
816
- novaProvider: this.novaProvider,
817
- skipCache: options.force,
818
- });
893
+ logTracker("trackAllElections (includeNext=%s)", options.includeNext ?? true);
819
894
  const status = await (0, election_1.checkElectionStatus)(this.l2Provider, this.l1Provider);
820
895
  const electionCount = status.electionCount;
821
896
  const results = [];
822
- // Track existing elections (indices 0 to electionCount-1)
823
- for (let i = 0; i < electionCount; i++) {
824
- try {
825
- // Check cache first for completed elections (skip RPC calls)
826
- if (this.cache && !options.force) {
827
- const cached = await this.getElectionCheckpoint(i);
828
- if (cached && cached.status.phase === "COMPLETED") {
829
- logTracker("returning cached COMPLETED election %d (0 RPC calls)", i);
830
- results.push(cached.status);
831
- continue;
832
- }
833
- }
834
- // Track with shared context
835
- const electionStatus = await (0, election_1.trackElectionProposal)(i, this.l2Provider, this.l1Provider, {
836
- novaProvider: this.novaProvider,
837
- l2BlockNumber: context.l2BlockNumber,
838
- timestamp: context.timestamp,
839
- skipCache: context.skipCache,
840
- });
841
- results.push(electionStatus);
842
- if (this.cache) {
843
- await this.saveElectionCheckpoint(electionStatus);
844
- }
845
- }
846
- catch (err) {
847
- logTracker("Failed to track election %d: %s", i, err);
848
- }
897
+ // Track existing elections in parallel (indices 0 to electionCount-1)
898
+ const electionPromises = Array.from({ length: electionCount }, (_, i) => this.trackElection(i).catch((err) => {
899
+ logTracker("Failed to track election %d: %s", i, (0, rpc_utils_1.getErrorMessage)(err));
900
+ return null;
901
+ }));
902
+ const electionResults = await Promise.all(electionPromises);
903
+ for (const result of electionResults) {
904
+ if (result)
905
+ results.push(result);
849
906
  }
850
907
  // Optionally track the next election (not yet created) for createElection preparation
851
908
  if (options.includeNext ?? true) {
852
909
  try {
853
- // Next election always needs fresh RPC calls since it doesn't exist yet
854
- const nextElectionStatus = await (0, election_1.trackElectionProposal)(electionCount, this.l2Provider, this.l1Provider, {
855
- novaProvider: this.novaProvider,
856
- l2BlockNumber: context.l2BlockNumber,
857
- timestamp: context.timestamp,
858
- });
910
+ // Next election won't have cache data since it doesn't exist yet
911
+ const nextElectionStatus = await this.trackElection(electionCount);
859
912
  results.push({
860
913
  ...nextElectionStatus,
861
914
  canCreateElection: status.canCreateElection,
@@ -865,7 +918,7 @@ class ProposalStageTracker {
865
918
  // Don't cache the "next" election since it doesn't exist yet
866
919
  }
867
920
  catch (err) {
868
- logTracker("Failed to track next election %d: %s", electionCount, err);
921
+ logTracker("Failed to track next election %d: %s", electionCount, (0, rpc_utils_1.getErrorMessage)(err));
869
922
  }
870
923
  }
871
924
  logTracker("Tracked %d elections", results.length);