@aztec/archiver 0.0.1-commit.f295ac2 → 0.0.1-commit.f504929

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 (95) hide show
  1. package/README.md +9 -0
  2. package/dest/archiver.d.ts +10 -6
  3. package/dest/archiver.d.ts.map +1 -1
  4. package/dest/archiver.js +50 -111
  5. package/dest/errors.d.ts +6 -1
  6. package/dest/errors.d.ts.map +1 -1
  7. package/dest/errors.js +8 -0
  8. package/dest/factory.d.ts +5 -2
  9. package/dest/factory.d.ts.map +1 -1
  10. package/dest/factory.js +16 -13
  11. package/dest/index.d.ts +2 -1
  12. package/dest/index.d.ts.map +1 -1
  13. package/dest/index.js +1 -0
  14. package/dest/l1/bin/retrieve-calldata.js +35 -32
  15. package/dest/l1/calldata_retriever.d.ts +73 -50
  16. package/dest/l1/calldata_retriever.d.ts.map +1 -1
  17. package/dest/l1/calldata_retriever.js +190 -259
  18. package/dest/l1/data_retrieval.d.ts +9 -9
  19. package/dest/l1/data_retrieval.d.ts.map +1 -1
  20. package/dest/l1/data_retrieval.js +24 -22
  21. package/dest/l1/spire_proposer.d.ts +5 -5
  22. package/dest/l1/spire_proposer.d.ts.map +1 -1
  23. package/dest/l1/spire_proposer.js +9 -17
  24. package/dest/l1/validate_trace.d.ts +6 -3
  25. package/dest/l1/validate_trace.d.ts.map +1 -1
  26. package/dest/l1/validate_trace.js +13 -9
  27. package/dest/modules/data_source_base.d.ts +25 -21
  28. package/dest/modules/data_source_base.d.ts.map +1 -1
  29. package/dest/modules/data_source_base.js +48 -123
  30. package/dest/modules/data_store_updater.d.ts +31 -20
  31. package/dest/modules/data_store_updater.d.ts.map +1 -1
  32. package/dest/modules/data_store_updater.js +79 -60
  33. package/dest/modules/instrumentation.d.ts +17 -4
  34. package/dest/modules/instrumentation.d.ts.map +1 -1
  35. package/dest/modules/instrumentation.js +36 -12
  36. package/dest/modules/l1_synchronizer.d.ts +4 -8
  37. package/dest/modules/l1_synchronizer.d.ts.map +1 -1
  38. package/dest/modules/l1_synchronizer.js +23 -19
  39. package/dest/store/block_store.d.ts +50 -32
  40. package/dest/store/block_store.d.ts.map +1 -1
  41. package/dest/store/block_store.js +147 -54
  42. package/dest/store/contract_class_store.d.ts +1 -1
  43. package/dest/store/contract_class_store.d.ts.map +1 -1
  44. package/dest/store/contract_class_store.js +11 -7
  45. package/dest/store/kv_archiver_store.d.ts +52 -29
  46. package/dest/store/kv_archiver_store.d.ts.map +1 -1
  47. package/dest/store/kv_archiver_store.js +49 -23
  48. package/dest/store/l2_tips_cache.d.ts +19 -0
  49. package/dest/store/l2_tips_cache.d.ts.map +1 -0
  50. package/dest/store/l2_tips_cache.js +89 -0
  51. package/dest/store/log_store.d.ts +17 -8
  52. package/dest/store/log_store.d.ts.map +1 -1
  53. package/dest/store/log_store.js +77 -43
  54. package/dest/test/fake_l1_state.d.ts +9 -4
  55. package/dest/test/fake_l1_state.d.ts.map +1 -1
  56. package/dest/test/fake_l1_state.js +56 -18
  57. package/dest/test/index.js +3 -1
  58. package/dest/test/mock_archiver.d.ts +1 -1
  59. package/dest/test/mock_archiver.d.ts.map +1 -1
  60. package/dest/test/mock_archiver.js +3 -2
  61. package/dest/test/mock_l2_block_source.d.ts +36 -21
  62. package/dest/test/mock_l2_block_source.d.ts.map +1 -1
  63. package/dest/test/mock_l2_block_source.js +151 -109
  64. package/dest/test/mock_structs.d.ts +3 -2
  65. package/dest/test/mock_structs.d.ts.map +1 -1
  66. package/dest/test/mock_structs.js +11 -9
  67. package/dest/test/noop_l1_archiver.d.ts +23 -0
  68. package/dest/test/noop_l1_archiver.d.ts.map +1 -0
  69. package/dest/test/noop_l1_archiver.js +68 -0
  70. package/package.json +14 -13
  71. package/src/archiver.ts +71 -136
  72. package/src/errors.ts +12 -0
  73. package/src/factory.ts +30 -14
  74. package/src/index.ts +1 -0
  75. package/src/l1/README.md +25 -68
  76. package/src/l1/bin/retrieve-calldata.ts +45 -33
  77. package/src/l1/calldata_retriever.ts +249 -379
  78. package/src/l1/data_retrieval.ts +27 -29
  79. package/src/l1/spire_proposer.ts +7 -15
  80. package/src/l1/validate_trace.ts +24 -6
  81. package/src/modules/data_source_base.ts +81 -167
  82. package/src/modules/data_store_updater.ts +92 -63
  83. package/src/modules/instrumentation.ts +46 -14
  84. package/src/modules/l1_synchronizer.ts +26 -24
  85. package/src/store/block_store.ts +188 -92
  86. package/src/store/contract_class_store.ts +11 -7
  87. package/src/store/kv_archiver_store.ts +85 -36
  88. package/src/store/l2_tips_cache.ts +89 -0
  89. package/src/store/log_store.ts +134 -49
  90. package/src/test/fake_l1_state.ts +77 -19
  91. package/src/test/index.ts +3 -0
  92. package/src/test/mock_archiver.ts +3 -2
  93. package/src/test/mock_l2_block_source.ts +196 -126
  94. package/src/test/mock_structs.ts +26 -10
  95. package/src/test/noop_l1_archiver.ts +109 -0
@@ -3,15 +3,8 @@ import type { ViemPublicClient, ViemPublicDebugClient } from '@aztec/ethereum/ty
3
3
  import { CheckpointNumber } from '@aztec/foundation/branded-types';
4
4
  import { Fr } from '@aztec/foundation/curves/bn254';
5
5
  import { EthAddress } from '@aztec/foundation/eth-address';
6
- import type { ViemSignature } from '@aztec/foundation/eth-signature';
7
6
  import type { Logger } from '@aztec/foundation/log';
8
- import {
9
- EmpireSlashingProposerAbi,
10
- GovernanceProposerAbi,
11
- RollupAbi,
12
- SlashFactoryAbi,
13
- TallySlashingProposerAbi,
14
- } from '@aztec/l1-artifacts';
7
+ import { RollupAbi } from '@aztec/l1-artifacts';
15
8
  import { CommitteeAttestation } from '@aztec/stdlib/block';
16
9
  import { ConsensusPayload, SignatureDomainSeparator } from '@aztec/stdlib/p2p';
17
10
  import { CheckpointHeader } from '@aztec/stdlib/rollup';
@@ -30,19 +23,33 @@ import {
30
23
 
31
24
  import type { ArchiverInstrumentation } from '../modules/instrumentation.js';
32
25
  import { getSuccessfulCallsFromDebug } from './debug_tx.js';
33
- import { getCallFromSpireProposer } from './spire_proposer.js';
26
+ import { getCallsFromSpireProposer } from './spire_proposer.js';
34
27
  import { getSuccessfulCallsFromTrace } from './trace_tx.js';
35
28
  import type { CallInfo } from './types.js';
36
29
 
30
+ /** Decoded checkpoint data from a propose calldata. */
31
+ type CheckpointData = {
32
+ checkpointNumber: CheckpointNumber;
33
+ archiveRoot: Fr;
34
+ header: CheckpointHeader;
35
+ attestations: CommitteeAttestation[];
36
+ blockHash: string;
37
+ feeAssetPriceModifier: bigint;
38
+ };
39
+
37
40
  /**
38
41
  * Extracts calldata to the `propose` method of the rollup contract from an L1 transaction
39
- * in order to reconstruct an L2 block header.
42
+ * in order to reconstruct an L2 block header. Uses hash matching against expected hashes
43
+ * from the CheckpointProposed event to verify the correct propose calldata.
40
44
  */
41
45
  export class CalldataRetriever {
42
- /** Pre-computed valid contract calls for validation */
43
- private readonly validContractCalls: ValidContractCall[];
46
+ /** Tx hashes we've already logged for trace+debug failure (log once per tx per process). */
47
+ private static readonly traceFailureWarnedTxHashes = new Set<string>();
44
48
 
45
- private readonly rollupAddress: EthAddress;
49
+ /** Clears the trace-failure warned set. For testing only. */
50
+ static resetTraceFailureWarnedForTesting(): void {
51
+ CalldataRetriever.traceFailureWarnedTxHashes.clear();
52
+ }
46
53
 
47
54
  constructor(
48
55
  private readonly publicClient: ViemPublicClient,
@@ -50,16 +57,8 @@ export class CalldataRetriever {
50
57
  private readonly targetCommitteeSize: number,
51
58
  private readonly instrumentation: ArchiverInstrumentation | undefined,
52
59
  private readonly logger: Logger,
53
- contractAddresses: {
54
- rollupAddress: EthAddress;
55
- governanceProposerAddress: EthAddress;
56
- slashingProposerAddress: EthAddress;
57
- slashFactoryAddress?: EthAddress;
58
- },
59
- ) {
60
- this.rollupAddress = contractAddresses.rollupAddress;
61
- this.validContractCalls = computeValidContractCalls(contractAddresses);
62
- }
60
+ private readonly rollupAddress: EthAddress,
61
+ ) {}
63
62
 
64
63
  /**
65
64
  * Gets checkpoint header and metadata from the calldata of an L1 transaction.
@@ -67,7 +66,7 @@ export class CalldataRetriever {
67
66
  * @param txHash - Hash of the tx that published it.
68
67
  * @param blobHashes - Blob hashes for the checkpoint.
69
68
  * @param checkpointNumber - Checkpoint number.
70
- * @param expectedHashes - Optional expected hashes from the CheckpointProposed event for validation
69
+ * @param expectedHashes - Expected hashes from the CheckpointProposed event for validation
71
70
  * @returns Checkpoint header and metadata from the calldata, deserialized
72
71
  */
73
72
  async getCheckpointFromRollupTx(
@@ -75,50 +74,43 @@ export class CalldataRetriever {
75
74
  _blobHashes: Buffer[],
76
75
  checkpointNumber: CheckpointNumber,
77
76
  expectedHashes: {
78
- attestationsHash?: Hex;
79
- payloadDigest?: Hex;
77
+ attestationsHash: Hex;
78
+ payloadDigest: Hex;
80
79
  },
81
- ): Promise<{
82
- checkpointNumber: CheckpointNumber;
83
- archiveRoot: Fr;
84
- header: CheckpointHeader;
85
- attestations: CommitteeAttestation[];
86
- blockHash: string;
87
- }> {
88
- this.logger.trace(`Fetching checkpoint ${checkpointNumber} from rollup tx ${txHash}`, {
89
- willValidateHashes: !!expectedHashes.attestationsHash || !!expectedHashes.payloadDigest,
90
- hasAttestationsHash: !!expectedHashes.attestationsHash,
91
- hasPayloadDigest: !!expectedHashes.payloadDigest,
92
- });
80
+ ): Promise<CheckpointData> {
81
+ this.logger.trace(`Fetching checkpoint ${checkpointNumber} from rollup tx ${txHash}`);
93
82
  const tx = await this.publicClient.getTransaction({ hash: txHash });
94
- const proposeCalldata = await this.getProposeCallData(tx, checkpointNumber);
95
- return this.decodeAndBuildCheckpoint(proposeCalldata, tx.blockHash!, checkpointNumber, expectedHashes);
83
+ return this.getCheckpointFromTx(tx, checkpointNumber, expectedHashes);
96
84
  }
97
85
 
98
- /** Gets rollup propose calldata from a transaction */
99
- protected async getProposeCallData(tx: Transaction, checkpointNumber: CheckpointNumber): Promise<Hex> {
100
- // Try to decode as multicall3 with validation
101
- const proposeCalldata = this.tryDecodeMulticall3(tx);
102
- if (proposeCalldata) {
86
+ /** Gets checkpoint data from a transaction by trying decode strategies then falling back to trace. */
87
+ protected async getCheckpointFromTx(
88
+ tx: Transaction,
89
+ checkpointNumber: CheckpointNumber,
90
+ expectedHashes: { attestationsHash: Hex; payloadDigest: Hex },
91
+ ): Promise<CheckpointData> {
92
+ // Try to decode as multicall3 with hash-verified matching
93
+ const multicall3Result = this.tryDecodeMulticall3(tx, expectedHashes, checkpointNumber, tx.blockHash!);
94
+ if (multicall3Result) {
103
95
  this.logger.trace(`Decoded propose calldata from multicall3 for tx ${tx.hash}`);
104
96
  this.instrumentation?.recordBlockProposalTxTarget(tx.to!, false);
105
- return proposeCalldata;
97
+ return multicall3Result;
106
98
  }
107
99
 
108
100
  // Try to decode as direct propose call
109
- const directProposeCalldata = this.tryDecodeDirectPropose(tx);
110
- if (directProposeCalldata) {
101
+ const directResult = this.tryDecodeDirectPropose(tx, expectedHashes, checkpointNumber, tx.blockHash!);
102
+ if (directResult) {
111
103
  this.logger.trace(`Decoded propose calldata from direct call for tx ${tx.hash}`);
112
104
  this.instrumentation?.recordBlockProposalTxTarget(tx.to!, false);
113
- return directProposeCalldata;
105
+ return directResult;
114
106
  }
115
107
 
116
108
  // Try to decode as Spire Proposer multicall wrapper
117
- const spireProposeCalldata = await this.tryDecodeSpireProposer(tx);
118
- if (spireProposeCalldata) {
109
+ const spireResult = await this.tryDecodeSpireProposer(tx, expectedHashes, checkpointNumber, tx.blockHash!);
110
+ if (spireResult) {
119
111
  this.logger.trace(`Decoded propose calldata from Spire Proposer for tx ${tx.hash}`);
120
112
  this.instrumentation?.recordBlockProposalTxTarget(tx.to!, false);
121
- return spireProposeCalldata;
113
+ return spireResult;
122
114
  }
123
115
 
124
116
  // Fall back to trace-based extraction
@@ -126,52 +118,82 @@ export class CalldataRetriever {
126
118
  `Failed to decode multicall3, direct propose, or Spire proposer for L1 tx ${tx.hash}, falling back to trace for checkpoint ${checkpointNumber}`,
127
119
  );
128
120
  this.instrumentation?.recordBlockProposalTxTarget(tx.to ?? EthAddress.ZERO.toString(), true);
129
- return await this.extractCalldataViaTrace(tx.hash);
121
+ const tracedCalldata = await this.extractCalldataViaTrace(tx.hash);
122
+ const tracedResult = this.tryDecodeAndVerifyPropose(
123
+ tracedCalldata,
124
+ expectedHashes,
125
+ checkpointNumber,
126
+ tx.blockHash!,
127
+ );
128
+ if (!tracedResult) {
129
+ throw new Error(`Hash mismatch for traced propose calldata in tx ${tx.hash} for checkpoint ${checkpointNumber}`);
130
+ }
131
+ return tracedResult;
130
132
  }
131
133
 
132
134
  /**
133
135
  * Attempts to decode a transaction as a Spire Proposer multicall wrapper.
134
- * If successful, extracts the wrapped call and validates it as either multicall3 or direct propose.
136
+ * If successful, iterates all wrapped calls and validates each as either multicall3
137
+ * or direct propose, verifying against expected hashes.
135
138
  * @param tx - The transaction to decode
136
- * @returns The propose calldata if successfully decoded and validated, undefined otherwise
139
+ * @param expectedHashes - Expected hashes for hash-verified matching
140
+ * @param checkpointNumber - The checkpoint number
141
+ * @param blockHash - The L1 block hash
142
+ * @returns The checkpoint data if successfully decoded and validated, undefined otherwise
137
143
  */
138
- protected async tryDecodeSpireProposer(tx: Transaction): Promise<Hex | undefined> {
139
- // Try to decode as Spire Proposer multicall (extracts the wrapped call)
140
- const spireWrappedCall = await getCallFromSpireProposer(tx, this.publicClient, this.logger);
141
- if (!spireWrappedCall) {
144
+ protected async tryDecodeSpireProposer(
145
+ tx: Transaction,
146
+ expectedHashes: { attestationsHash: Hex; payloadDigest: Hex },
147
+ checkpointNumber: CheckpointNumber,
148
+ blockHash: Hex,
149
+ ): Promise<CheckpointData | undefined> {
150
+ // Try to decode as Spire Proposer multicall (extracts all wrapped calls)
151
+ const spireWrappedCalls = await getCallsFromSpireProposer(tx, this.publicClient, this.logger);
152
+ if (!spireWrappedCalls) {
142
153
  return undefined;
143
154
  }
144
155
 
145
- this.logger.trace(`Decoded Spire Proposer wrapping for tx ${tx.hash}, inner call to ${spireWrappedCall.to}`);
156
+ this.logger.trace(`Decoded Spire Proposer wrapping for tx ${tx.hash}, ${spireWrappedCalls.length} inner call(s)`);
146
157
 
147
- // Now try to decode the wrapped call as either multicall3 or direct propose
148
- const wrappedTx = { to: spireWrappedCall.to, input: spireWrappedCall.data, hash: tx.hash };
158
+ // Try each wrapped call as either multicall3 or direct propose
159
+ for (const spireWrappedCall of spireWrappedCalls) {
160
+ const wrappedTx = { to: spireWrappedCall.to, input: spireWrappedCall.data, hash: tx.hash };
149
161
 
150
- const multicall3Calldata = this.tryDecodeMulticall3(wrappedTx);
151
- if (multicall3Calldata) {
152
- this.logger.trace(`Decoded propose calldata from Spire Proposer to multicall3 for tx ${tx.hash}`);
153
- return multicall3Calldata;
154
- }
162
+ const multicall3Result = this.tryDecodeMulticall3(wrappedTx, expectedHashes, checkpointNumber, blockHash);
163
+ if (multicall3Result) {
164
+ this.logger.trace(`Decoded propose calldata from Spire Proposer to multicall3 for tx ${tx.hash}`);
165
+ return multicall3Result;
166
+ }
155
167
 
156
- const directProposeCalldata = this.tryDecodeDirectPropose(wrappedTx);
157
- if (directProposeCalldata) {
158
- this.logger.trace(`Decoded propose calldata from Spire Proposer to direct propose for tx ${tx.hash}`);
159
- return directProposeCalldata;
168
+ const directResult = this.tryDecodeDirectPropose(wrappedTx, expectedHashes, checkpointNumber, blockHash);
169
+ if (directResult) {
170
+ this.logger.trace(`Decoded propose calldata from Spire Proposer to direct propose for tx ${tx.hash}`);
171
+ return directResult;
172
+ }
160
173
  }
161
174
 
162
175
  this.logger.warn(
163
- `Spire Proposer wrapped call could not be decoded as multicall3 or direct propose for tx ${tx.hash}`,
176
+ `Spire Proposer wrapped calls could not be decoded as multicall3 or direct propose for tx ${tx.hash}`,
164
177
  );
165
178
  return undefined;
166
179
  }
167
180
 
168
181
  /**
169
182
  * Attempts to decode transaction input as multicall3 and extract propose calldata.
170
- * Returns undefined if validation fails.
183
+ * Finds all calls matching the rollup address and propose selector, then decodes
184
+ * and verifies each candidate against expected hashes from the CheckpointProposed event.
171
185
  * @param tx - The transaction-like object with to, input, and hash
172
- * @returns The propose calldata if successfully validated, undefined otherwise
186
+ * @param expectedHashes - Expected hashes from CheckpointProposed event
187
+ * @param checkpointNumber - The checkpoint number
188
+ * @param blockHash - The L1 block hash
189
+ * @returns The checkpoint data if successfully validated, undefined otherwise
173
190
  */
174
- protected tryDecodeMulticall3(tx: { to: Hex | null | undefined; input: Hex; hash: Hex }): Hex | undefined {
191
+ protected tryDecodeMulticall3(
192
+ tx: { to: Hex | null | undefined; input: Hex; hash: Hex },
193
+ expectedHashes: { attestationsHash: Hex; payloadDigest: Hex },
194
+ checkpointNumber: CheckpointNumber,
195
+ blockHash: Hex,
196
+ ): CheckpointData | undefined {
175
197
  const txHash = tx.hash;
176
198
 
177
199
  try {
@@ -200,59 +222,54 @@ export class CalldataRetriever {
200
222
 
201
223
  const [calls] = multicall3Args;
202
224
 
203
- // Validate all calls and find propose calls
225
+ // Find all calls matching rollup address + propose selector
204
226
  const rollupAddressLower = this.rollupAddress.toString().toLowerCase();
205
- const proposeCalls: Hex[] = [];
227
+ const proposeSelectorLower = PROPOSE_SELECTOR.toLowerCase();
228
+ const candidates: Hex[] = [];
206
229
 
207
- for (let i = 0; i < calls.length; i++) {
208
- const addr = calls[i].target.toLowerCase();
209
- const callData = calls[i].callData;
230
+ for (const call of calls) {
231
+ const addr = call.target.toLowerCase();
232
+ const callData = call.callData;
210
233
 
211
- // Extract function selector (first 4 bytes)
212
234
  if (callData.length < 10) {
213
- // "0x" + 8 hex chars = 10 chars minimum for a valid function call
214
- this.logger.warn(`Invalid calldata length at index ${i} (${callData.length})`, { txHash });
215
- return undefined;
235
+ continue;
216
236
  }
217
- const functionSelector = callData.slice(0, 10) as Hex;
218
-
219
- // Validate this call is allowed by searching through valid calls
220
- const validCall = this.validContractCalls.find(
221
- vc => vc.address === addr && vc.functionSelector === functionSelector,
222
- );
223
237
 
224
- if (!validCall) {
225
- this.logger.warn(`Invalid contract call detected in multicall3`, {
226
- index: i,
227
- targetAddress: addr,
228
- functionSelector,
229
- validCalls: this.validContractCalls.map(c => ({ address: c.address, selector: c.functionSelector })),
230
- txHash,
231
- });
232
- return undefined;
238
+ const selector = callData.slice(0, 10).toLowerCase();
239
+ if (addr === rollupAddressLower && selector === proposeSelectorLower) {
240
+ candidates.push(callData);
233
241
  }
242
+ }
234
243
 
235
- this.logger.trace(`Valid call found to ${addr}`, { validCall });
244
+ if (candidates.length === 0) {
245
+ this.logger.debug(`No propose candidates found in multicall3`, { txHash });
246
+ return undefined;
247
+ }
236
248
 
237
- // Collect propose calls specifically
238
- if (addr === rollupAddressLower && validCall.functionName === 'propose') {
239
- proposeCalls.push(callData);
249
+ // Decode, verify, and build for each candidate
250
+ const verified: CheckpointData[] = [];
251
+ for (const candidate of candidates) {
252
+ const result = this.tryDecodeAndVerifyPropose(candidate, expectedHashes, checkpointNumber, blockHash);
253
+ if (result) {
254
+ verified.push(result);
240
255
  }
241
256
  }
242
257
 
243
- // Validate exactly ONE propose call
244
- if (proposeCalls.length === 0) {
245
- this.logger.warn(`No propose calls found in multicall3`, { txHash });
246
- return undefined;
258
+ if (verified.length === 1) {
259
+ this.logger.trace(`Verified single propose candidate via hash matching`, { txHash });
260
+ return verified[0];
247
261
  }
248
262
 
249
- if (proposeCalls.length > 1) {
250
- this.logger.warn(`Multiple propose calls found in multicall3 (${proposeCalls.length})`, { txHash });
251
- return undefined;
263
+ if (verified.length > 1) {
264
+ this.logger.warn(
265
+ `Multiple propose candidates verified (${verified.length}), returning first (identical data)`,
266
+ { txHash },
267
+ );
268
+ return verified[0];
252
269
  }
253
270
 
254
- // Successfully extracted single propose call
255
- return proposeCalls[0];
271
+ this.logger.debug(`No candidates verified against expected hashes`, { txHash });
272
+ return undefined;
256
273
  } catch (err) {
257
274
  // Any decoding error triggers fallback to trace
258
275
  this.logger.warn(`Failed to decode multicall3: ${err}`, { txHash });
@@ -262,11 +279,19 @@ export class CalldataRetriever {
262
279
 
263
280
  /**
264
281
  * Attempts to decode transaction as a direct propose call to the rollup contract.
265
- * Returns undefined if validation fails.
282
+ * Decodes, verifies hashes, and builds checkpoint data in a single pass.
266
283
  * @param tx - The transaction-like object with to, input, and hash
267
- * @returns The propose calldata if successfully validated, undefined otherwise
284
+ * @param expectedHashes - Expected hashes from CheckpointProposed event
285
+ * @param checkpointNumber - The checkpoint number
286
+ * @param blockHash - The L1 block hash
287
+ * @returns The checkpoint data if successfully validated, undefined otherwise
268
288
  */
269
- protected tryDecodeDirectPropose(tx: { to: Hex | null | undefined; input: Hex; hash: Hex }): Hex | undefined {
289
+ protected tryDecodeDirectPropose(
290
+ tx: { to: Hex | null | undefined; input: Hex; hash: Hex },
291
+ expectedHashes: { attestationsHash: Hex; payloadDigest: Hex },
292
+ checkpointNumber: CheckpointNumber,
293
+ blockHash: Hex,
294
+ ): CheckpointData | undefined {
270
295
  const txHash = tx.hash;
271
296
  try {
272
297
  // Check if transaction is to the rollup address
@@ -275,18 +300,16 @@ export class CalldataRetriever {
275
300
  return undefined;
276
301
  }
277
302
 
278
- // Try to decode as propose call
303
+ // Validate it's a propose call before full decode+verify
279
304
  const { functionName } = decodeFunctionData({ abi: RollupAbi, data: tx.input });
280
-
281
- // If not propose, return undefined
282
305
  if (functionName !== 'propose') {
283
306
  this.logger.warn(`Transaction to rollup is not propose (got ${functionName})`, { txHash });
284
307
  return undefined;
285
308
  }
286
309
 
287
- // Successfully validated direct propose call
310
+ // Decode, verify hashes, and build checkpoint data
288
311
  this.logger.trace(`Validated direct propose call to rollup`, { txHash });
289
- return tx.input;
312
+ return this.tryDecodeAndVerifyPropose(tx.input, expectedHashes, checkpointNumber, blockHash);
290
313
  } catch (err) {
291
314
  // Any decoding error means it's not a valid propose call
292
315
  this.logger.warn(`Failed to decode as direct propose: ${err}`, { txHash });
@@ -313,7 +336,8 @@ export class CalldataRetriever {
313
336
  this.logger.debug(`Successfully traced using trace_transaction, found ${calls.length} calls`);
314
337
  } catch (err) {
315
338
  const traceError = err instanceof Error ? err : new Error(String(err));
316
- this.logger.verbose(`Failed trace_transaction for ${txHash}`, { traceError });
339
+ this.logger.verbose(`Failed trace_transaction for ${txHash}: ${traceError.message}`);
340
+ this.logger.debug(`Trace failure details for ${txHash}`, { traceError });
317
341
 
318
342
  try {
319
343
  // Fall back to debug_traceTransaction (Geth RPC)
@@ -322,7 +346,16 @@ export class CalldataRetriever {
322
346
  this.logger.debug(`Successfully traced using debug_traceTransaction, found ${calls.length} calls`);
323
347
  } catch (debugErr) {
324
348
  const debugError = debugErr instanceof Error ? debugErr : new Error(String(debugErr));
325
- this.logger.warn(`All tracing methods failed for tx ${txHash}`, {
349
+ // Log once per tx so we don't spam on every sync cycle when sync point doesn't advance
350
+ if (!CalldataRetriever.traceFailureWarnedTxHashes.has(txHash)) {
351
+ CalldataRetriever.traceFailureWarnedTxHashes.add(txHash);
352
+ this.logger.warn(
353
+ `Cannot decode L1 tx ${txHash}: trace and debug RPC failed or unavailable. ` +
354
+ `trace_transaction: ${traceError.message}; debug_traceTransaction: ${debugError.message}`,
355
+ );
356
+ }
357
+ // Full error objects can be very long; keep at debug only
358
+ this.logger.debug(`Trace/debug failure details for tx ${txHash}`, {
326
359
  traceError,
327
360
  debugError,
328
361
  txHash,
@@ -344,10 +377,102 @@ export class CalldataRetriever {
344
377
  return calls[0].input;
345
378
  }
346
379
 
380
+ /**
381
+ * Decodes propose calldata, verifies against expected hashes, and builds checkpoint data.
382
+ * Returns undefined on decode errors or hash mismatches (soft failure for try-based callers).
383
+ * @param proposeCalldata - The propose function calldata
384
+ * @param expectedHashes - Expected hashes from the CheckpointProposed event
385
+ * @param checkpointNumber - The checkpoint number
386
+ * @param blockHash - The L1 block hash
387
+ * @returns The decoded checkpoint data, or undefined on failure
388
+ */
389
+ protected tryDecodeAndVerifyPropose(
390
+ proposeCalldata: Hex,
391
+ expectedHashes: { attestationsHash: Hex; payloadDigest: Hex },
392
+ checkpointNumber: CheckpointNumber,
393
+ blockHash: Hex,
394
+ ): CheckpointData | undefined {
395
+ try {
396
+ const { functionName, args } = decodeFunctionData({ abi: RollupAbi, data: proposeCalldata });
397
+ if (functionName !== 'propose') {
398
+ return undefined;
399
+ }
400
+
401
+ const [decodedArgs, packedAttestations] = args! as readonly [
402
+ { archive: Hex; oracleInput: { feeAssetPriceModifier: bigint }; header: ViemHeader },
403
+ ViemCommitteeAttestations,
404
+ ...unknown[],
405
+ ];
406
+
407
+ // Verify attestationsHash
408
+ const computedAttestationsHash = this.computeAttestationsHash(packedAttestations);
409
+ if (
410
+ !Buffer.from(hexToBytes(computedAttestationsHash)).equals(
411
+ Buffer.from(hexToBytes(expectedHashes.attestationsHash)),
412
+ )
413
+ ) {
414
+ this.logger.warn(`Attestations hash mismatch during verification`, {
415
+ computed: computedAttestationsHash,
416
+ expected: expectedHashes.attestationsHash,
417
+ });
418
+ return undefined;
419
+ }
420
+
421
+ // Verify payloadDigest
422
+ const header = CheckpointHeader.fromViem(decodedArgs.header);
423
+ const archiveRoot = new Fr(Buffer.from(hexToBytes(decodedArgs.archive)));
424
+ const feeAssetPriceModifier = decodedArgs.oracleInput.feeAssetPriceModifier;
425
+ const computedPayloadDigest = this.computePayloadDigest(header, archiveRoot, feeAssetPriceModifier);
426
+ if (
427
+ !Buffer.from(hexToBytes(computedPayloadDigest)).equals(Buffer.from(hexToBytes(expectedHashes.payloadDigest)))
428
+ ) {
429
+ this.logger.warn(`Payload digest mismatch during verification`, {
430
+ computed: computedPayloadDigest,
431
+ expected: expectedHashes.payloadDigest,
432
+ });
433
+ return undefined;
434
+ }
435
+
436
+ const attestations = CommitteeAttestation.fromPacked(packedAttestations, this.targetCommitteeSize);
437
+
438
+ this.logger.trace(`Validated and decoded propose calldata for checkpoint ${checkpointNumber}`, {
439
+ checkpointNumber,
440
+ archive: decodedArgs.archive,
441
+ header: decodedArgs.header,
442
+ l1BlockHash: blockHash,
443
+ attestations,
444
+ packedAttestations,
445
+ targetCommitteeSize: this.targetCommitteeSize,
446
+ });
447
+
448
+ return {
449
+ checkpointNumber,
450
+ archiveRoot,
451
+ header,
452
+ attestations,
453
+ blockHash,
454
+ feeAssetPriceModifier,
455
+ };
456
+ } catch {
457
+ return undefined;
458
+ }
459
+ }
460
+
461
+ /** Computes the keccak256 hash of ABI-encoded CommitteeAttestations. */
462
+ private computeAttestationsHash(packedAttestations: ViemCommitteeAttestations): Hex {
463
+ return keccak256(encodeAbiParameters([this.getCommitteeAttestationsStructDef()], [packedAttestations]));
464
+ }
465
+
466
+ /** Computes the keccak256 payload digest from the checkpoint header, archive root, and fee asset price modifier. */
467
+ private computePayloadDigest(header: CheckpointHeader, archiveRoot: Fr, feeAssetPriceModifier: bigint): Hex {
468
+ const consensusPayload = new ConsensusPayload(header, archiveRoot, feeAssetPriceModifier);
469
+ const payloadToSign = consensusPayload.getPayloadToSign(SignatureDomainSeparator.checkpointAttestation);
470
+ return keccak256(payloadToSign);
471
+ }
472
+
347
473
  /**
348
474
  * Extracts the CommitteeAttestations struct definition from RollupAbi.
349
475
  * Finds the _attestations parameter by name in the propose function.
350
- * Lazy-loaded to avoid issues during module initialization.
351
476
  */
352
477
  private getCommitteeAttestationsStructDef(): AbiParameter {
353
478
  const proposeFunction = RollupAbi.find(item => item.type === 'function' && item.name === 'propose') as
@@ -380,262 +505,7 @@ export class CalldataRetriever {
380
505
  components: tupleParam.components || [],
381
506
  } as AbiParameter;
382
507
  }
383
-
384
- /**
385
- * Decodes propose calldata and builds the checkpoint header structure.
386
- * @param proposeCalldata - The propose function calldata
387
- * @param blockHash - The L1 block hash containing this transaction
388
- * @param checkpointNumber - The checkpoint number
389
- * @param expectedHashes - Optional expected hashes from the CheckpointProposed event for validation
390
- * @returns The decoded checkpoint header and metadata
391
- */
392
- protected decodeAndBuildCheckpoint(
393
- proposeCalldata: Hex,
394
- blockHash: Hex,
395
- checkpointNumber: CheckpointNumber,
396
- expectedHashes: {
397
- attestationsHash?: Hex;
398
- payloadDigest?: Hex;
399
- },
400
- ): {
401
- checkpointNumber: CheckpointNumber;
402
- archiveRoot: Fr;
403
- header: CheckpointHeader;
404
- attestations: CommitteeAttestation[];
405
- blockHash: string;
406
- } {
407
- const { functionName: rollupFunctionName, args: rollupArgs } = decodeFunctionData({
408
- abi: RollupAbi,
409
- data: proposeCalldata,
410
- });
411
-
412
- if (rollupFunctionName !== 'propose') {
413
- throw new Error(`Unexpected rollup method called ${rollupFunctionName}`);
414
- }
415
-
416
- const [decodedArgs, packedAttestations, _signers, _attestationsAndSignersSignature, _blobInput] =
417
- rollupArgs! as readonly [
418
- {
419
- archive: Hex;
420
- oracleInput: { feeAssetPriceModifier: bigint };
421
- header: ViemHeader;
422
- },
423
- ViemCommitteeAttestations,
424
- Hex[],
425
- ViemSignature,
426
- Hex,
427
- ];
428
-
429
- const attestations = CommitteeAttestation.fromPacked(packedAttestations, this.targetCommitteeSize);
430
- const header = CheckpointHeader.fromViem(decodedArgs.header);
431
- const archiveRoot = new Fr(Buffer.from(hexToBytes(decodedArgs.archive)));
432
-
433
- // Validate attestationsHash if provided (skip for backwards compatibility with older events)
434
- if (expectedHashes.attestationsHash) {
435
- // Compute attestationsHash: keccak256(abi.encode(CommitteeAttestations))
436
- const computedAttestationsHash = keccak256(
437
- encodeAbiParameters([this.getCommitteeAttestationsStructDef()], [packedAttestations]),
438
- );
439
-
440
- // Compare as buffers to avoid case-sensitivity and string comparison issues
441
- const computedBuffer = Buffer.from(hexToBytes(computedAttestationsHash));
442
- const expectedBuffer = Buffer.from(hexToBytes(expectedHashes.attestationsHash));
443
-
444
- if (!computedBuffer.equals(expectedBuffer)) {
445
- throw new Error(
446
- `Attestations hash mismatch for checkpoint ${checkpointNumber}: ` +
447
- `computed=${computedAttestationsHash}, expected=${expectedHashes.attestationsHash}`,
448
- );
449
- }
450
-
451
- this.logger.trace(`Validated attestationsHash for checkpoint ${checkpointNumber}`, {
452
- computedAttestationsHash,
453
- expectedAttestationsHash: expectedHashes.attestationsHash,
454
- });
455
- }
456
-
457
- // Validate payloadDigest if provided (skip for backwards compatibility with older events)
458
- if (expectedHashes.payloadDigest) {
459
- // Use ConsensusPayload to compute the digest - this ensures we match the exact logic
460
- // used by the network for signing and verification
461
- const consensusPayload = new ConsensusPayload(header, archiveRoot);
462
- const payloadToSign = consensusPayload.getPayloadToSign(SignatureDomainSeparator.checkpointAttestation);
463
- const computedPayloadDigest = keccak256(payloadToSign);
464
-
465
- // Compare as buffers to avoid case-sensitivity and string comparison issues
466
- const computedBuffer = Buffer.from(hexToBytes(computedPayloadDigest));
467
- const expectedBuffer = Buffer.from(hexToBytes(expectedHashes.payloadDigest));
468
-
469
- if (!computedBuffer.equals(expectedBuffer)) {
470
- throw new Error(
471
- `Payload digest mismatch for checkpoint ${checkpointNumber}: ` +
472
- `computed=${computedPayloadDigest}, expected=${expectedHashes.payloadDigest}`,
473
- );
474
- }
475
-
476
- this.logger.trace(`Validated payloadDigest for checkpoint ${checkpointNumber}`, {
477
- computedPayloadDigest,
478
- expectedPayloadDigest: expectedHashes.payloadDigest,
479
- });
480
- }
481
-
482
- this.logger.trace(`Decoded propose calldata`, {
483
- checkpointNumber,
484
- archive: decodedArgs.archive,
485
- header: decodedArgs.header,
486
- l1BlockHash: blockHash,
487
- attestations,
488
- packedAttestations,
489
- targetCommitteeSize: this.targetCommitteeSize,
490
- });
491
-
492
- return {
493
- checkpointNumber,
494
- archiveRoot,
495
- header,
496
- attestations,
497
- blockHash,
498
- };
499
- }
500
508
  }
501
509
 
502
- /**
503
- * Pre-computed function selectors for all valid contract calls.
504
- * These are computed once at module load time from the ABIs.
505
- * Based on analysis of sequencer-client/src/publisher/sequencer-publisher.ts
506
- */
507
-
508
- // Rollup contract function selectors (always valid)
510
+ /** Function selector for the `propose` method of the rollup contract. */
509
511
  const PROPOSE_SELECTOR = toFunctionSelector(RollupAbi.find(x => x.type === 'function' && x.name === 'propose')!);
510
- const INVALIDATE_BAD_ATTESTATION_SELECTOR = toFunctionSelector(
511
- RollupAbi.find(x => x.type === 'function' && x.name === 'invalidateBadAttestation')!,
512
- );
513
- const INVALIDATE_INSUFFICIENT_ATTESTATIONS_SELECTOR = toFunctionSelector(
514
- RollupAbi.find(x => x.type === 'function' && x.name === 'invalidateInsufficientAttestations')!,
515
- );
516
-
517
- // Governance proposer function selectors
518
- const GOVERNANCE_SIGNAL_WITH_SIG_SELECTOR = toFunctionSelector(
519
- GovernanceProposerAbi.find(x => x.type === 'function' && x.name === 'signalWithSig')!,
520
- );
521
-
522
- // Slash factory function selectors
523
- const CREATE_SLASH_PAYLOAD_SELECTOR = toFunctionSelector(
524
- SlashFactoryAbi.find(x => x.type === 'function' && x.name === 'createSlashPayload')!,
525
- );
526
-
527
- // Empire slashing proposer function selectors
528
- const EMPIRE_SIGNAL_WITH_SIG_SELECTOR = toFunctionSelector(
529
- EmpireSlashingProposerAbi.find(x => x.type === 'function' && x.name === 'signalWithSig')!,
530
- );
531
- const EMPIRE_SUBMIT_ROUND_WINNER_SELECTOR = toFunctionSelector(
532
- EmpireSlashingProposerAbi.find(x => x.type === 'function' && x.name === 'submitRoundWinner')!,
533
- );
534
-
535
- // Tally slashing proposer function selectors
536
- const TALLY_VOTE_SELECTOR = toFunctionSelector(
537
- TallySlashingProposerAbi.find(x => x.type === 'function' && x.name === 'vote')!,
538
- );
539
- const TALLY_EXECUTE_ROUND_SELECTOR = toFunctionSelector(
540
- TallySlashingProposerAbi.find(x => x.type === 'function' && x.name === 'executeRound')!,
541
- );
542
-
543
- /**
544
- * Defines a valid contract call that can appear in a sequencer publisher transaction
545
- */
546
- interface ValidContractCall {
547
- /** Contract address (lowercase for comparison) */
548
- address: string;
549
- /** Function selector (4 bytes) */
550
- functionSelector: Hex;
551
- /** Human-readable function name for logging */
552
- functionName: string;
553
- }
554
-
555
- /**
556
- * All valid contract calls that the sequencer publisher can make.
557
- * Builds the list of valid (address, selector) pairs for validation.
558
- *
559
- * Alternatively, if we are absolutely sure that no code path from any of these
560
- * contracts can eventually land on another call to `propose`, we can remove the
561
- * function selectors.
562
- */
563
- function computeValidContractCalls(addresses: {
564
- rollupAddress: EthAddress;
565
- governanceProposerAddress?: EthAddress;
566
- slashFactoryAddress?: EthAddress;
567
- slashingProposerAddress?: EthAddress;
568
- }): ValidContractCall[] {
569
- const { rollupAddress, governanceProposerAddress, slashFactoryAddress, slashingProposerAddress } = addresses;
570
- const calls: ValidContractCall[] = [];
571
-
572
- // Rollup contract calls (always present)
573
- calls.push(
574
- {
575
- address: rollupAddress.toString().toLowerCase(),
576
- functionSelector: PROPOSE_SELECTOR,
577
- functionName: 'propose',
578
- },
579
- {
580
- address: rollupAddress.toString().toLowerCase(),
581
- functionSelector: INVALIDATE_BAD_ATTESTATION_SELECTOR,
582
- functionName: 'invalidateBadAttestation',
583
- },
584
- {
585
- address: rollupAddress.toString().toLowerCase(),
586
- functionSelector: INVALIDATE_INSUFFICIENT_ATTESTATIONS_SELECTOR,
587
- functionName: 'invalidateInsufficientAttestations',
588
- },
589
- );
590
-
591
- // Governance proposer calls (optional)
592
- if (governanceProposerAddress && !governanceProposerAddress.isZero()) {
593
- calls.push({
594
- address: governanceProposerAddress.toString().toLowerCase(),
595
- functionSelector: GOVERNANCE_SIGNAL_WITH_SIG_SELECTOR,
596
- functionName: 'signalWithSig',
597
- });
598
- }
599
-
600
- // Slash factory calls (optional)
601
- if (slashFactoryAddress && !slashFactoryAddress.isZero()) {
602
- calls.push({
603
- address: slashFactoryAddress.toString().toLowerCase(),
604
- functionSelector: CREATE_SLASH_PAYLOAD_SELECTOR,
605
- functionName: 'createSlashPayload',
606
- });
607
- }
608
-
609
- // Slashing proposer calls (optional, can be either Empire or Tally)
610
- if (slashingProposerAddress && !slashingProposerAddress.isZero()) {
611
- // Empire calls
612
- calls.push(
613
- {
614
- address: slashingProposerAddress.toString().toLowerCase(),
615
- functionSelector: EMPIRE_SIGNAL_WITH_SIG_SELECTOR,
616
- functionName: 'signalWithSig (empire)',
617
- },
618
- {
619
- address: slashingProposerAddress.toString().toLowerCase(),
620
- functionSelector: EMPIRE_SUBMIT_ROUND_WINNER_SELECTOR,
621
- functionName: 'submitRoundWinner',
622
- },
623
- );
624
-
625
- // Tally calls
626
- calls.push(
627
- {
628
- address: slashingProposerAddress.toString().toLowerCase(),
629
- functionSelector: TALLY_VOTE_SELECTOR,
630
- functionName: 'vote',
631
- },
632
- {
633
- address: slashingProposerAddress.toString().toLowerCase(),
634
- functionSelector: TALLY_EXECUTE_ROUND_SELECTOR,
635
- functionName: 'executeRound',
636
- },
637
- );
638
- }
639
-
640
- return calls;
641
- }