@aztec/validator-client 0.0.1-commit.24de95ac → 0.0.1-commit.2606882

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 (61) hide show
  1. package/README.md +325 -0
  2. package/dest/checkpoint_builder.d.ts +79 -0
  3. package/dest/checkpoint_builder.d.ts.map +1 -0
  4. package/dest/checkpoint_builder.js +251 -0
  5. package/dest/config.d.ts +1 -1
  6. package/dest/config.d.ts.map +1 -1
  7. package/dest/config.js +52 -13
  8. package/dest/duties/validation_service.d.ts +44 -16
  9. package/dest/duties/validation_service.d.ts.map +1 -1
  10. package/dest/duties/validation_service.js +104 -34
  11. package/dest/factory.d.ts +22 -11
  12. package/dest/factory.d.ts.map +1 -1
  13. package/dest/factory.js +11 -5
  14. package/dest/index.d.ts +3 -2
  15. package/dest/index.d.ts.map +1 -1
  16. package/dest/index.js +2 -1
  17. package/dest/key_store/ha_key_store.d.ts +99 -0
  18. package/dest/key_store/ha_key_store.d.ts.map +1 -0
  19. package/dest/key_store/ha_key_store.js +208 -0
  20. package/dest/key_store/index.d.ts +2 -1
  21. package/dest/key_store/index.d.ts.map +1 -1
  22. package/dest/key_store/index.js +1 -0
  23. package/dest/key_store/interface.d.ts +36 -6
  24. package/dest/key_store/interface.d.ts.map +1 -1
  25. package/dest/key_store/local_key_store.d.ts +10 -5
  26. package/dest/key_store/local_key_store.d.ts.map +1 -1
  27. package/dest/key_store/local_key_store.js +9 -5
  28. package/dest/key_store/node_keystore_adapter.d.ts +18 -5
  29. package/dest/key_store/node_keystore_adapter.d.ts.map +1 -1
  30. package/dest/key_store/node_keystore_adapter.js +18 -4
  31. package/dest/key_store/web3signer_key_store.d.ts +10 -11
  32. package/dest/key_store/web3signer_key_store.d.ts.map +1 -1
  33. package/dest/key_store/web3signer_key_store.js +9 -5
  34. package/dest/metrics.d.ts +16 -3
  35. package/dest/metrics.d.ts.map +1 -1
  36. package/dest/metrics.js +58 -30
  37. package/dest/proposal_handler.d.ts +134 -0
  38. package/dest/proposal_handler.d.ts.map +1 -0
  39. package/dest/proposal_handler.js +1072 -0
  40. package/dest/validator.d.ts +87 -24
  41. package/dest/validator.d.ts.map +1 -1
  42. package/dest/validator.js +520 -90
  43. package/package.json +24 -14
  44. package/src/checkpoint_builder.ts +417 -0
  45. package/src/config.ts +52 -11
  46. package/src/duties/validation_service.ts +170 -46
  47. package/src/factory.ts +37 -11
  48. package/src/index.ts +2 -1
  49. package/src/key_store/ha_key_store.ts +269 -0
  50. package/src/key_store/index.ts +1 -0
  51. package/src/key_store/interface.ts +44 -5
  52. package/src/key_store/local_key_store.ts +14 -5
  53. package/src/key_store/node_keystore_adapter.ts +28 -5
  54. package/src/key_store/web3signer_key_store.ts +18 -5
  55. package/src/metrics.ts +81 -33
  56. package/src/proposal_handler.ts +1161 -0
  57. package/src/validator.ts +739 -134
  58. package/dest/block_proposal_handler.d.ts +0 -52
  59. package/dest/block_proposal_handler.d.ts.map +0 -1
  60. package/dest/block_proposal_handler.js +0 -286
  61. package/src/block_proposal_handler.ts +0 -343
package/README.md ADDED
@@ -0,0 +1,325 @@
1
+ # Validator Client
2
+
3
+ The validator client handles consensus duties for Aztec validators: validating block proposals, attesting to checkpoints, and detecting slashable some offenses. Validators do NOT attest to individual blocks. Attestations are only created for checkpoint proposals that aggregate an entire slot's worth of blocks.
4
+
5
+ ## Key Concepts
6
+
7
+ ### Slots, Blocks, and Checkpoints
8
+
9
+ - **Slot**: A fixed time window (e.g., 72 seconds) during which a designated proposer builds blocks
10
+ - **Block**: A single batch of transactions executed and validated within a slot
11
+ - **Checkpoint**: The collection of all blocks built in a slot, attested by validators and published to L1
12
+ - **Sub-slot**: A fixed-duration window within a slot for building each block (e.g., 8 seconds)
13
+
14
+ A proposer builds several blocks during their slot. These blocks share the same `slotNumber` but have incrementing `blockNumber` and `indexWithinCheckpoint` values.
15
+
16
+ ### Block Proposals
17
+
18
+ A `BlockProposal` is broadcast by the proposer for each block **except the last one** in a slot:
19
+
20
+ ```
21
+ BlockProposal {
22
+ blockHeader // Per-block header with global variables
23
+ indexWithinCheckpoint // 0, 1, 2, ... position within checkpoint
24
+ inHash // L1-to-L2 messages hash (constant across checkpoint)
25
+ archive // Archive root after this block
26
+ txHashes // Transaction hashes in order
27
+ signature // Proposer's signature
28
+ signedTxs? // Optional full transactions for DA
29
+ }
30
+ ```
31
+
32
+ Validators receive block proposals, validate them, and re-execute transactions—but they do **not** create attestations for individual blocks.
33
+
34
+ ### Checkpoint Proposals
35
+
36
+ A `CheckpointProposal` is broadcast at the end of a slot along with the last block:
37
+
38
+ ```
39
+ CheckpointProposal {
40
+ checkpointHeader // Aggregated header for consensus
41
+ archive // Final archive root after all blocks
42
+ signature // Proposer's signature over checkpoint
43
+ lastBlock? { // Last block info (extracted as BlockProposal)
44
+ blockHeader
45
+ indexWithinCheckpoint
46
+ txHashes
47
+ signature
48
+ signedTxs?
49
+ }
50
+ }
51
+ ```
52
+
53
+ The `checkpointHeader` contains aggregated data: `blockHeadersHash` (hash of all block headers), `contentCommitment` (blobsHash, inHash, outHash), and shared global variables.
54
+
55
+ ### Checkpoint Attestations
56
+
57
+ Validators who have validated all blocks in a checkpoint create a `CheckpointAttestation`:
58
+
59
+ ```
60
+ CheckpointAttestation {
61
+ payload { // What's being attested to
62
+ checkpointHeader // The checkpoint header
63
+ archive // The final archive root
64
+ }
65
+ signature // Validator's signature
66
+ proposerSignature // Copy of proposer's signature (for verification)
67
+ }
68
+ ```
69
+
70
+ Attestations are collected by the proposer and submitted to L1 along with the checkpoint.
71
+
72
+ ## Key Invariants
73
+
74
+ These rules must always hold:
75
+
76
+ 1. **Attestations are checkpoint-only**: Validators never attest to individual `BlockProposal`s
77
+ 2. **Global variables match within checkpoint**: All blocks within the same checkpoint must have identical global variables (except `blockNumber`), which includes the slot number
78
+ 3. **inHash is constant**: All blocks in a checkpoint share the same L1-to-L2 messages hash
79
+ 4. **Sequential indexWithinCheckpoint**: Block N must have `indexWithinCheckpoint = parent.indexWithinCheckpoint + 1`
80
+ 5. **One proposer per slot**: Each slot has exactly one designated proposer. Sending multiple proposals for the same position (slot, indexWithinCheckpoint) with different content is equivocation and slashable
81
+ 6. **One attestation per slot**: Validators should only attest to one checkpoint per slot. Attesting to different proposals (different archives) for the same slot is equivocation and slashable
82
+
83
+ ## Validation Flow
84
+
85
+ ### Block Proposal Validation
86
+
87
+ When a `BlockProposal` is received via P2P, the `BlockProposalHandler` performs:
88
+
89
+ ```
90
+ 1. Verify proposer signature
91
+ 2. Check proposal is from current/next slot proposer (via BlockProposalValidator)
92
+ 3. Detect duplicate proposals (same slot + indexWithinCheckpoint, different archive) slashing proposer on equivocation
93
+ 4. Find parent block by archive root (wait/retry if not synced)
94
+ 5. Compute checkpoint number from parent
95
+ 6. If indexWithinCheckpoint > 0, then validate global variables match parent (chainId, version, slotNumber, timestamp, coinbase, feeRecipient, gasFees)
96
+ 7. Verify inHash matches computed from L1-to-L2 messages
97
+ 8. Collect transactions from pool/network/proposal
98
+ 9. Re-execute transactions (if enabled)
99
+ 10. Compare re-execution result with proposal
100
+ ```
101
+
102
+ ### Checkpoint Proposal Validation
103
+
104
+ When a `CheckpointProposal` is received, before creating attestations:
105
+
106
+ ```
107
+ 1. Verify proposer signature
108
+ 2. Wait for last block to sync (by archive root)
109
+ 3. Collect all blocks in this slot
110
+ 4. Recompute blockHeadersHash from collected headers
111
+ 5. Verify blockHeadersHash matches checkpointHeader
112
+ 6. Verify checkpoint header fields match last block's global variables:
113
+ - slotNumber, coinbase, feeRecipient, gasFees
114
+ 7. Verify lastArchiveRoot matches first block's lastArchive
115
+ ```
116
+
117
+ ### Attestation Creation
118
+
119
+ After successful checkpoint validation:
120
+
121
+ ```
122
+ 1. Check if any of our validator addresses are in the committee
123
+ 2. For each address in committee:
124
+ - Sign ConsensusPayload (checkpointHeader + archive)
125
+ - Create CheckpointAttestation with our signature + proposer signature
126
+ 3. Add attestations to attestation pool
127
+ 4. Broadcast attestations to peers
128
+ ```
129
+
130
+ ## Sequence Diagram
131
+
132
+ ```
133
+ Time | Proposer | Validator
134
+ -----|------------------------------|------------------------------------
135
+ 2s | Build Block 0 |
136
+ 10s | Broadcast BlockProposal 0 |
137
+ | Build Block 1 |
138
+ 12s | | Receive BlockProposal 0
139
+ | | Validate + re-execute Block 0
140
+ 18s | Broadcast BlockProposal 1 |
141
+ | Build Block 2 |
142
+ 20s | | Receive BlockProposal 1
143
+ | | Validate + re-execute Block 1
144
+ ... | |
145
+ 42s | Build Block 4 (last) |
146
+ | Assemble CheckpointProposal |
147
+ | Broadcast CheckpointProposal |
148
+ 44s | | Receive CheckpointProposal
149
+ | | Extract + validate Block 4
150
+ | | Validate checkpoint (blockHeadersHash)
151
+ 52s | | Create CheckpointAttestations
152
+ | | Broadcast attestations
153
+ 54s | Receive attestations |
154
+ 55s | Finalize + publish to L1 |
155
+ ```
156
+
157
+ ## Configuration
158
+
159
+ | Flag | Purpose |
160
+ | -------------------------------------------------- | -------------------------------------------------------------------- |
161
+ | `fishermanMode` | Validate proposals but don't broadcast attestations (monitoring only) |
162
+ | `alwaysReexecuteBlockProposals` | Force re-execution even when not in committee |
163
+ | `slashBroadcastedInvalidBlockPenalty` | Penalty amount for invalid proposals (0 = disabled) |
164
+ | `slashBroadcastedInvalidCheckpointProposalPenalty` | Penalty amount for invalid checkpoint proposals (0 = disabled) |
165
+ | `slashDuplicateProposalPenalty` | Penalty amount for duplicate proposals (0 = disabled) |
166
+ | `slashDuplicateAttestationPenalty` | Penalty amount for duplicate attestations (0 = disabled) |
167
+ | `attestationPollingIntervalMs` | How often to poll for attestations when collecting |
168
+ | `disabledValidators` | Validator addresses to exclude from duties |
169
+
170
+ ### High Availability (HA) Keystore
171
+
172
+ When running multiple validator nodes with the same validator keys in a high-availability setup, enable HA signing to prevent double-signing:
173
+
174
+ | Environment Variable | Purpose |
175
+ | -------------------------------------- | ---------------------------------------------------------------------- |
176
+ | `VALIDATOR_HA_SIGNING_ENABLED` | Enable HA signing / slashing protection (default: false) |
177
+ | `VALIDATOR_HA_DATABASE_URL` | PostgreSQL connection string for coordination (required when enabled) |
178
+ | `VALIDATOR_HA_NODE_ID` | Unique identifier for this validator node (required when enabled) |
179
+ | `VALIDATOR_HA_POLLING_INTERVAL_MS` | How often to check duty status (default: 100) |
180
+ | `VALIDATOR_HA_SIGNING_TIMEOUT_MS` | Max wait for in-progress signing (default: 3000) |
181
+ | `VALIDATOR_HA_MAX_STUCK_DUTIES_AGE_MS` | Max age of stuck duties before cleanup (default: 2\*aztecSlotDuration) |
182
+
183
+ When `VALIDATOR_HA_SIGNING_ENABLED=true`, the validator client automatically:
184
+
185
+ - Creates an HA signer using the provided configuration
186
+ - Wraps the base keystore with `HAKeyStore` for HA-protected signing
187
+ - Coordinates signing across nodes via PostgreSQL to prevent double-signing
188
+ - Provides slashing protection to block conflicting signatures
189
+
190
+ See [`@aztec/validator-ha-signer`](../validator-ha-signer/README.md) for more details.
191
+
192
+ ### Fisherman Mode
193
+
194
+ When `fishermanMode: true`, the validator:
195
+
196
+ - Validates all proposals (block and checkpoint)
197
+ - Re-executes transactions
198
+ - Creates attestations internally for validation
199
+ - Does **not** broadcast attestations to the network
200
+ - Does **not** add attestations to the pool
201
+
202
+ This is useful for monitoring network health without participating in consensus.
203
+
204
+ ### Key Methods
205
+
206
+ **ValidatorClient** (`validator.ts`):
207
+
208
+ - `validateBlockProposal(proposal, sender)` → `boolean`: Validates block, optionally re-executes, emits slash events
209
+ - `attestToCheckpointProposal(proposal, sender)` → `CheckpointAttestation[]?`: Validates checkpoint and creates attestations
210
+ - `collectAttestations(proposal, required, deadline)` → `CheckpointAttestation[]`: Waits for attestations from other validators
211
+ - `createBlockProposal(...)` → `BlockProposal`: Creates and signs a block proposal (used by sequencer)
212
+ - `createCheckpointProposal(...)` → `CheckpointProposal`: Creates and signs a checkpoint proposal
213
+
214
+ **BlockProposalHandler** (`block_proposal_handler.ts`):
215
+
216
+ - `handleBlockProposal(proposal, sender, shouldReexecute)` → `ValidationResult`: Full block validation pipeline
217
+ - `reexecuteTransactions(proposal, blockNumber, txs, messages)` → `ReexecutionResult`: Re-runs transactions and compares state
218
+
219
+ **ValidationService** (`duties/validation_service.ts`):
220
+
221
+ - `createBlockProposal(...)` → `BlockProposal`: Signs block proposal with validator key
222
+ - `createCheckpointProposal(...)` → `CheckpointProposal`: Signs checkpoint proposal
223
+ - `attestToCheckpointProposal(proposal, attestors)` → `CheckpointAttestation[]`: Creates attestations for given addresses
224
+
225
+ ## Block Building Limits
226
+
227
+ L1 enforces gas and blob capacity per checkpoint. The node enforces these during block building to avoid L1 rejection. Three dimensions are metered: L2 gas (mana), DA gas, and blob fields. DA gas maps to blob fields today (`daGas = blobFields * 32`) but both are tracked independently.
228
+
229
+ ### Checkpoint limits
230
+
231
+ | Dimension | Source | Budget |
232
+ | --- | --- | --- |
233
+ | L2 gas (mana) | `rollup.getManaLimit()` | Fetched from L1 at startup |
234
+ | DA gas | `MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT` | 786,432 (6 blobs × 4096 fields × 32 gas/field) |
235
+ | Blob fields | `BLOBS_PER_CHECKPOINT × FIELDS_PER_BLOB` | 24,576 minus checkpoint/block-end overhead |
236
+
237
+ ### Per-block budgets
238
+
239
+ Per-block budgets prevent one block from consuming the entire checkpoint budget. The checkpoint builder dynamically computes per-block limits before each block based on the remaining checkpoint budget and the number of remaining blocks.
240
+
241
+ **Proposer**: When building a proposal (`isBuildingProposal: true`), the `CheckpointProposalJob` passes `maxBlocksPerCheckpoint` (from the timetable) and `perBlockAllocationMultiplier` (default 1.2) via opts to `CheckpointBuilder.buildBlock`. The builder computes a fair share as `min(perBlockLimit, ceil(remainingBudget / remainingBlocks * multiplier), remainingBudget)`. The multiplier greater than 1 allows early blocks to use more than their even share, since different blocks hit different limit dimensions (L2 gas, DA gas, blob fields) — a strict even split would waste capacity. As prior blocks consume budget, later blocks see tightened limits. This applies to all four dimensions (L2 gas, DA gas, blob fields, transaction count). Operators can set hard per-block caps via `SEQ_MAX_L2_BLOCK_GAS` / `SEQ_MAX_DA_BLOCK_GAS` / `SEQ_MAX_TX_PER_BLOCK` (capped at checkpoint limits at startup); these act as additional upper bounds alongside the redistribution.
242
+
243
+ **Validator**: When re-executing a proposal (`isBuildingProposal` unset), `capLimitsByCheckpointBudgets` only caps by the per-block limit and the total remaining checkpoint budget — no redistribution or multiplier is applied. This avoids false rejections due to differences between proposer and validator fair-share calculations. Validators can optionally set hard per-block limits via `VALIDATOR_MAX_L2_BLOCK_GAS`, `VALIDATOR_MAX_DA_BLOCK_GAS`, and `VALIDATOR_MAX_TX_PER_BLOCK`. When unset, no per-block limit is enforced (checkpoint-level protocol limits still apply). These are independent of the `SEQ_` vars so operators can tune proposer and validation limits separately.
244
+
245
+ ### Per-transaction enforcement
246
+
247
+ **Mempool entry** (`GasLimitsValidator`): L2 gas must be ≤ `MAX_PROCESSABLE_L2_GAS` (6,540,000) and ≥ fixed minimums.
248
+
249
+ **Block building** (`PublicProcessor.process`): Before processing, txs are skipped if their estimated blob fields or gas limits would exceed the block budget. After processing, actual values are checked and the tx is reverted if limits are exceeded.
250
+
251
+ ### Gas limit configuration
252
+
253
+ | Variable | Default | Description |
254
+ | --- | --- | --- |
255
+ | `SEQ_MAX_L2_BLOCK_GAS` | *none* | Hard per-block L2 gas cap. Capped at `rollupManaLimit` at startup. When unset, redistribution dynamically computes per-block limits. |
256
+ | `SEQ_MAX_DA_BLOCK_GAS` | *none* | Hard per-block DA gas cap. Capped at `MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT` at startup. When unset, redistribution handles it. |
257
+ | `SEQ_MAX_TX_PER_BLOCK` | *none* | Hard per-block tx count cap. Capped at `SEQ_MAX_TX_PER_CHECKPOINT` at startup (if set). |
258
+ | `SEQ_MAX_TX_PER_CHECKPOINT` | *none* | Total txs across all blocks in a checkpoint. When set, checkpoint-level capping and redistribution are enforced for tx count. |
259
+ | `SEQ_PER_BLOCK_ALLOCATION_MULTIPLIER` | 1.2 | Multiplier for per-block budget redistribution. Passed via opts to the checkpoint builder during proposal building. |
260
+ | `SEQ_REDISTRIBUTE_CHECKPOINT_BUDGET` | true | Legacy flag; redistribution is now always active during proposal building and inactive during validation. |
261
+ | `VALIDATOR_MAX_L2_BLOCK_GAS` | *none* | Per-block L2 gas limit for validation. Proposals exceeding this are rejected. |
262
+ | `VALIDATOR_MAX_DA_BLOCK_GAS` | *none* | Per-block DA gas limit for validation. Proposals exceeding this are rejected. |
263
+ | `VALIDATOR_MAX_TX_PER_BLOCK` | *none* | Per-block tx count limit for validation. Proposals exceeding this are rejected. |
264
+ | `VALIDATOR_MAX_TX_PER_CHECKPOINT` | *none* | Per-checkpoint tx count limit for validation. Proposals exceeding this are rejected. |
265
+
266
+ ## Testing Patterns
267
+
268
+ ### Common Mocks
269
+
270
+ Tests typically mock these dependencies:
271
+
272
+ ```typescript
273
+ let epochCache: MockProxy<EpochCache>;
274
+ let blockSource: MockProxy<L2BlockSource>;
275
+ let txProvider: MockProxy<TxProvider>;
276
+ let checkpointsBuilder: MockProxy<FullNodeCheckpointsBuilder>;
277
+ let p2pClient: MockProxy<P2P>;
278
+
279
+ beforeEach(() => {
280
+ epochCache = mock<EpochCache>();
281
+ blockSource = mock<L2BlockSource>();
282
+ // ... etc
283
+ });
284
+ ```
285
+
286
+ ### Creating Test Proposals
287
+
288
+ Use factory functions from `@aztec/stdlib/testing`:
289
+
290
+ ```typescript
291
+ import { makeBlockHeader, makeBlockProposal, makeCheckpointHeader, makeCheckpointProposal } from '@aztec/stdlib/testing';
292
+
293
+ // These are async - always await
294
+ const blockProposal = await makeBlockProposal({
295
+ blockHeader: makeBlockHeader(1, { blockNumber: BlockNumber(100), slotNumber: SlotNumber(100) }),
296
+ indexWithinCheckpoint: 0,
297
+ signer: Secp256k1Signer.random(),
298
+ });
299
+
300
+ const checkpointProposal = await makeCheckpointProposal({
301
+ checkpointHeader: makeCheckpointHeader(1, { slotNumber: SlotNumber(100) }),
302
+ signer: proposer,
303
+ lastBlock: { blockHeader: makeBlockHeader(1), txs },
304
+ });
305
+ ```
306
+
307
+ ### Mocking for Re-execution Tests
308
+
309
+ For tests that exercise re-execution:
310
+
311
+ ```typescript
312
+ // Mock parent block lookup
313
+ blockSource.getBlockHeaderByArchive.mockResolvedValue(parentBlockHeader);
314
+ blockSource.getL2Block.mockResolvedValue({
315
+ checkpointNumber: CheckpointNumber(1),
316
+ indexWithinCheckpoint: 0,
317
+ header: { globalVariables: parentGlobalVariables },
318
+ });
319
+
320
+ // Mock block builder result
321
+ blockBuilder.buildBlock.mockResolvedValue({
322
+ block: expectedBlock,
323
+ failedTxs: [],
324
+ });
325
+ ```
@@ -0,0 +1,79 @@
1
+ import { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
2
+ import { Fr } from '@aztec/foundation/curves/bn254';
3
+ import { type LoggerBindings } from '@aztec/foundation/log';
4
+ import { DateProvider } from '@aztec/foundation/timer';
5
+ import { LightweightCheckpointBuilder } from '@aztec/prover-client/light';
6
+ import { PublicContractsDB, PublicProcessor } from '@aztec/simulator/server';
7
+ import { L2Block } from '@aztec/stdlib/block';
8
+ import { Checkpoint } from '@aztec/stdlib/checkpoint';
9
+ import type { ContractDataSource } from '@aztec/stdlib/contract';
10
+ import type { L1RollupConstants } from '@aztec/stdlib/epoch-helpers';
11
+ import { type BlockBuilderOptions, type BuildBlockInCheckpointResult, type FullNodeBlockBuilderConfig, type ICheckpointBlockBuilder, type ICheckpointsBuilder, type MerkleTreeWriteOperations, type PublicProcessorLimits, type WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
12
+ import { type DebugLogStore } from '@aztec/stdlib/logs';
13
+ import { type CheckpointGlobalVariables, GlobalVariables, StateReference, Tx } from '@aztec/stdlib/tx';
14
+ import { type TelemetryClient } from '@aztec/telemetry-client';
15
+ export type { BuildBlockInCheckpointResult } from '@aztec/stdlib/interfaces/server';
16
+ /**
17
+ * Builder for a single checkpoint. Handles building blocks within the checkpoint
18
+ * and completing it.
19
+ */
20
+ export declare class CheckpointBuilder implements ICheckpointBlockBuilder {
21
+ private checkpointBuilder;
22
+ private fork;
23
+ private config;
24
+ private contractDataSource;
25
+ private dateProvider;
26
+ private telemetryClient;
27
+ private debugLogStore;
28
+ private log;
29
+ /** Persistent contracts DB shared across all blocks in this checkpoint. */
30
+ protected contractsDB: PublicContractsDB;
31
+ constructor(checkpointBuilder: LightweightCheckpointBuilder, fork: MerkleTreeWriteOperations, config: FullNodeBlockBuilderConfig, contractDataSource: ContractDataSource, dateProvider: DateProvider, telemetryClient: TelemetryClient, bindings?: LoggerBindings, debugLogStore?: DebugLogStore);
32
+ getConstantData(): CheckpointGlobalVariables;
33
+ /**
34
+ * Builds a single block within this checkpoint.
35
+ * Automatically caps gas and blob field limits based on checkpoint-level budgets and prior blocks.
36
+ */
37
+ buildBlock(pendingTxs: Iterable<Tx> | AsyncIterable<Tx>, blockNumber: BlockNumber, timestamp: bigint, opts: BlockBuilderOptions & {
38
+ expectedEndState?: StateReference;
39
+ }): Promise<BuildBlockInCheckpointResult>;
40
+ /** Completes the checkpoint and returns it. */
41
+ completeCheckpoint(): Promise<Checkpoint>;
42
+ /** Gets the checkpoint currently in progress. */
43
+ getCheckpoint(): Promise<Checkpoint>;
44
+ /**
45
+ * Caps per-block gas and blob field limits by remaining checkpoint-level budgets.
46
+ * When building a proposal (isBuildingProposal=true), computes a fair share of remaining budget
47
+ * across remaining blocks scaled by the multiplier. When validating, only caps by per-block limit
48
+ * and remaining checkpoint budget (no redistribution or multiplier).
49
+ */
50
+ protected capLimitsByCheckpointBudgets(opts: BlockBuilderOptions): Pick<PublicProcessorLimits, 'maxBlockGas' | 'maxBlobFields' | 'maxTransactions'>;
51
+ protected makeBlockBuilderDeps(globalVariables: GlobalVariables, fork: MerkleTreeWriteOperations): Promise<{
52
+ processor: PublicProcessor;
53
+ validator: import("@aztec/stdlib/interfaces/server").PublicProcessorValidator;
54
+ }>;
55
+ }
56
+ /** Factory for creating checkpoint builders. */
57
+ export declare class FullNodeCheckpointsBuilder implements ICheckpointsBuilder {
58
+ private config;
59
+ private worldState;
60
+ private contractDataSource;
61
+ private dateProvider;
62
+ private telemetryClient;
63
+ private debugLogStore;
64
+ private log;
65
+ constructor(config: FullNodeBlockBuilderConfig & Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration'>, worldState: WorldStateSynchronizer, contractDataSource: ContractDataSource, dateProvider: DateProvider, telemetryClient?: TelemetryClient, debugLogStore?: DebugLogStore);
66
+ getConfig(): FullNodeBlockBuilderConfig;
67
+ updateConfig(config: Partial<FullNodeBlockBuilderConfig>): void;
68
+ /**
69
+ * Starts a new checkpoint and returns a CheckpointBuilder to build blocks within it.
70
+ */
71
+ startCheckpoint(checkpointNumber: CheckpointNumber, constants: CheckpointGlobalVariables, feeAssetPriceModifier: bigint, l1ToL2Messages: Fr[], previousCheckpointOutHashes: Fr[], fork: MerkleTreeWriteOperations, bindings?: LoggerBindings): Promise<CheckpointBuilder>;
72
+ /**
73
+ * Opens a checkpoint, either starting fresh or resuming from existing blocks.
74
+ */
75
+ openCheckpoint(checkpointNumber: CheckpointNumber, constants: CheckpointGlobalVariables, feeAssetPriceModifier: bigint, l1ToL2Messages: Fr[], previousCheckpointOutHashes: Fr[], fork: MerkleTreeWriteOperations, existingBlocks?: L2Block[], bindings?: LoggerBindings): Promise<CheckpointBuilder>;
76
+ /** Returns a fork of the world state at the given block number. */
77
+ getFork(blockNumber: BlockNumber): Promise<MerkleTreeWriteOperations>;
78
+ }
79
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2hlY2twb2ludF9idWlsZGVyLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvY2hlY2twb2ludF9idWlsZGVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUVBLE9BQU8sRUFBRSxXQUFXLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSxpQ0FBaUMsQ0FBQztBQUVoRixPQUFPLEVBQUUsRUFBRSxFQUFFLE1BQU0sZ0NBQWdDLENBQUM7QUFDcEQsT0FBTyxFQUFlLEtBQUssY0FBYyxFQUFnQixNQUFNLHVCQUF1QixDQUFDO0FBRXZGLE9BQU8sRUFBRSxZQUFZLEVBQVcsTUFBTSx5QkFBeUIsQ0FBQztBQUVoRSxPQUFPLEVBQUUsNEJBQTRCLEVBQUUsTUFBTSw0QkFBNEIsQ0FBQztBQUMxRSxPQUFPLEVBRUwsaUJBQWlCLEVBQ2pCLGVBQWUsRUFFaEIsTUFBTSx5QkFBeUIsQ0FBQztBQUNqQyxPQUFPLEVBQUUsT0FBTyxFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFDOUMsT0FBTyxFQUFFLFVBQVUsRUFBRSxNQUFNLDBCQUEwQixDQUFDO0FBQ3RELE9BQU8sS0FBSyxFQUFFLGtCQUFrQixFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFDakUsT0FBTyxLQUFLLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUVyRSxPQUFPLEVBQ0wsS0FBSyxtQkFBbUIsRUFDeEIsS0FBSyw0QkFBNEIsRUFDakMsS0FBSywwQkFBMEIsRUFFL0IsS0FBSyx1QkFBdUIsRUFDNUIsS0FBSyxtQkFBbUIsRUFFeEIsS0FBSyx5QkFBeUIsRUFDOUIsS0FBSyxxQkFBcUIsRUFDMUIsS0FBSyxzQkFBc0IsRUFDNUIsTUFBTSxpQ0FBaUMsQ0FBQztBQUN6QyxPQUFPLEVBQUUsS0FBSyxhQUFhLEVBQXFCLE1BQU0sb0JBQW9CLENBQUM7QUFFM0UsT0FBTyxFQUFFLEtBQUsseUJBQXlCLEVBQUUsZUFBZSxFQUFFLGNBQWMsRUFBRSxFQUFFLEVBQUUsTUFBTSxr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
@@ -0,0 +1 @@
1
+ {"version":3,"file":"checkpoint_builder.d.ts","sourceRoot":"","sources":["../src/checkpoint_builder.ts"],"names":[],"mappings":"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"}