@aztec/sequencer-client 0.0.1-commit.b655e406 → 0.0.1-commit.b9865e97

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 (153) hide show
  1. package/README.md +281 -21
  2. package/dest/client/index.d.ts +1 -1
  3. package/dest/client/sequencer-client.d.ts +26 -16
  4. package/dest/client/sequencer-client.d.ts.map +1 -1
  5. package/dest/client/sequencer-client.js +78 -37
  6. package/dest/config.d.ts +37 -8
  7. package/dest/config.d.ts.map +1 -1
  8. package/dest/config.js +139 -48
  9. package/dest/global_variable_builder/fee_predictor.d.ts +37 -0
  10. package/dest/global_variable_builder/fee_predictor.d.ts.map +1 -0
  11. package/dest/global_variable_builder/fee_predictor.js +128 -0
  12. package/dest/global_variable_builder/fee_provider.d.ts +21 -0
  13. package/dest/global_variable_builder/fee_provider.d.ts.map +1 -0
  14. package/dest/global_variable_builder/fee_provider.js +58 -0
  15. package/dest/global_variable_builder/global_builder.d.ts +24 -20
  16. package/dest/global_variable_builder/global_builder.d.ts.map +1 -1
  17. package/dest/global_variable_builder/global_builder.js +44 -65
  18. package/dest/global_variable_builder/index.d.ts +4 -2
  19. package/dest/global_variable_builder/index.d.ts.map +1 -1
  20. package/dest/global_variable_builder/index.js +2 -0
  21. package/dest/index.d.ts +2 -3
  22. package/dest/index.d.ts.map +1 -1
  23. package/dest/index.js +1 -2
  24. package/dest/publisher/config.d.ts +55 -20
  25. package/dest/publisher/config.d.ts.map +1 -1
  26. package/dest/publisher/config.js +124 -34
  27. package/dest/publisher/index.d.ts +2 -1
  28. package/dest/publisher/index.d.ts.map +1 -1
  29. package/dest/publisher/l1_tx_failed_store/factory.d.ts +11 -0
  30. package/dest/publisher/l1_tx_failed_store/factory.d.ts.map +1 -0
  31. package/dest/publisher/l1_tx_failed_store/factory.js +22 -0
  32. package/dest/publisher/l1_tx_failed_store/failed_tx_store.d.ts +58 -0
  33. package/dest/publisher/l1_tx_failed_store/failed_tx_store.d.ts.map +1 -0
  34. package/dest/publisher/l1_tx_failed_store/failed_tx_store.js +1 -0
  35. package/dest/publisher/l1_tx_failed_store/file_store_failed_tx_store.d.ts +15 -0
  36. package/dest/publisher/l1_tx_failed_store/file_store_failed_tx_store.d.ts.map +1 -0
  37. package/dest/publisher/l1_tx_failed_store/file_store_failed_tx_store.js +34 -0
  38. package/dest/publisher/l1_tx_failed_store/index.d.ts +4 -0
  39. package/dest/publisher/l1_tx_failed_store/index.d.ts.map +1 -0
  40. package/dest/publisher/l1_tx_failed_store/index.js +2 -0
  41. package/dest/publisher/sequencer-bundle-simulator.d.ts +96 -0
  42. package/dest/publisher/sequencer-bundle-simulator.d.ts.map +1 -0
  43. package/dest/publisher/sequencer-bundle-simulator.js +198 -0
  44. package/dest/publisher/sequencer-publisher-factory.d.ts +15 -8
  45. package/dest/publisher/sequencer-publisher-factory.d.ts.map +1 -1
  46. package/dest/publisher/sequencer-publisher-factory.js +28 -4
  47. package/dest/publisher/sequencer-publisher-metrics.d.ts +3 -3
  48. package/dest/publisher/sequencer-publisher-metrics.d.ts.map +1 -1
  49. package/dest/publisher/sequencer-publisher-metrics.js +23 -86
  50. package/dest/publisher/sequencer-publisher.d.ts +137 -97
  51. package/dest/publisher/sequencer-publisher.d.ts.map +1 -1
  52. package/dest/publisher/sequencer-publisher.js +1004 -416
  53. package/dest/sequencer/automine/automine_factory.d.ts +54 -0
  54. package/dest/sequencer/automine/automine_factory.d.ts.map +1 -0
  55. package/dest/sequencer/automine/automine_factory.js +84 -0
  56. package/dest/sequencer/automine/automine_sequencer.d.ts +151 -0
  57. package/dest/sequencer/automine/automine_sequencer.d.ts.map +1 -0
  58. package/dest/sequencer/automine/automine_sequencer.js +509 -0
  59. package/dest/sequencer/chain_state_overrides.d.ts +61 -0
  60. package/dest/sequencer/chain_state_overrides.d.ts.map +1 -0
  61. package/dest/sequencer/chain_state_overrides.js +98 -0
  62. package/dest/sequencer/checkpoint_proposal_job.d.ts +150 -0
  63. package/dest/sequencer/checkpoint_proposal_job.d.ts.map +1 -0
  64. package/dest/sequencer/checkpoint_proposal_job.js +1793 -0
  65. package/dest/sequencer/checkpoint_proposal_job_metrics.d.ts +34 -0
  66. package/dest/sequencer/checkpoint_proposal_job_metrics.d.ts.map +1 -0
  67. package/dest/sequencer/checkpoint_proposal_job_metrics.js +72 -0
  68. package/dest/sequencer/checkpoint_voter.d.ts +34 -0
  69. package/dest/sequencer/checkpoint_voter.d.ts.map +1 -0
  70. package/dest/sequencer/checkpoint_voter.js +106 -0
  71. package/dest/sequencer/config.d.ts +3 -2
  72. package/dest/sequencer/config.d.ts.map +1 -1
  73. package/dest/sequencer/errors.d.ts +1 -1
  74. package/dest/sequencer/errors.d.ts.map +1 -1
  75. package/dest/sequencer/events.d.ts +92 -0
  76. package/dest/sequencer/events.d.ts.map +1 -0
  77. package/dest/sequencer/events.js +1 -0
  78. package/dest/sequencer/index.d.ts +6 -2
  79. package/dest/sequencer/index.d.ts.map +1 -1
  80. package/dest/sequencer/index.js +5 -1
  81. package/dest/sequencer/metrics.d.ts +48 -4
  82. package/dest/sequencer/metrics.d.ts.map +1 -1
  83. package/dest/sequencer/metrics.js +257 -50
  84. package/dest/sequencer/sequencer.d.ts +175 -144
  85. package/dest/sequencer/sequencer.d.ts.map +1 -1
  86. package/dest/sequencer/sequencer.js +1022 -567
  87. package/dest/sequencer/timetable.d.ts +64 -16
  88. package/dest/sequencer/timetable.d.ts.map +1 -1
  89. package/dest/sequencer/timetable.js +154 -64
  90. package/dest/sequencer/types.d.ts +3 -0
  91. package/dest/sequencer/types.d.ts.map +1 -0
  92. package/dest/sequencer/types.js +1 -0
  93. package/dest/sequencer/utils.d.ts +14 -8
  94. package/dest/sequencer/utils.d.ts.map +1 -1
  95. package/dest/sequencer/utils.js +7 -4
  96. package/dest/test/index.d.ts +6 -7
  97. package/dest/test/index.d.ts.map +1 -1
  98. package/dest/test/mock_checkpoint_builder.d.ts +95 -0
  99. package/dest/test/mock_checkpoint_builder.d.ts.map +1 -0
  100. package/dest/test/mock_checkpoint_builder.js +231 -0
  101. package/dest/test/utils.d.ts +53 -0
  102. package/dest/test/utils.d.ts.map +1 -0
  103. package/dest/test/utils.js +105 -0
  104. package/package.json +32 -30
  105. package/src/client/sequencer-client.ts +105 -60
  106. package/src/config.ts +163 -57
  107. package/src/global_variable_builder/README.md +44 -0
  108. package/src/global_variable_builder/fee_predictor.ts +172 -0
  109. package/src/global_variable_builder/fee_provider.ts +75 -0
  110. package/src/global_variable_builder/global_builder.ts +63 -92
  111. package/src/global_variable_builder/index.ts +3 -1
  112. package/src/index.ts +5 -2
  113. package/src/publisher/config.ts +174 -51
  114. package/src/publisher/index.ts +3 -0
  115. package/src/publisher/l1_tx_failed_store/factory.ts +32 -0
  116. package/src/publisher/l1_tx_failed_store/failed_tx_store.ts +57 -0
  117. package/src/publisher/l1_tx_failed_store/file_store_failed_tx_store.ts +46 -0
  118. package/src/publisher/l1_tx_failed_store/index.ts +3 -0
  119. package/src/publisher/sequencer-bundle-simulator.ts +254 -0
  120. package/src/publisher/sequencer-publisher-factory.ts +45 -14
  121. package/src/publisher/sequencer-publisher-metrics.ts +19 -71
  122. package/src/publisher/sequencer-publisher.ts +798 -538
  123. package/src/sequencer/README.md +243 -0
  124. package/src/sequencer/automine/README.md +46 -0
  125. package/src/sequencer/automine/automine_factory.ts +145 -0
  126. package/src/sequencer/automine/automine_sequencer.ts +595 -0
  127. package/src/sequencer/chain_state_overrides.ts +162 -0
  128. package/src/sequencer/checkpoint_proposal_job.ts +1633 -0
  129. package/src/sequencer/checkpoint_proposal_job_metrics.ts +128 -0
  130. package/src/sequencer/checkpoint_voter.ts +119 -0
  131. package/src/sequencer/config.ts +2 -1
  132. package/src/sequencer/events.ts +76 -0
  133. package/src/sequencer/index.ts +5 -1
  134. package/src/sequencer/metrics.ts +330 -62
  135. package/src/sequencer/sequencer.ts +831 -748
  136. package/src/sequencer/timetable.ts +181 -81
  137. package/src/sequencer/types.ts +6 -0
  138. package/src/sequencer/utils.ts +18 -9
  139. package/src/test/index.ts +5 -6
  140. package/src/test/mock_checkpoint_builder.ts +323 -0
  141. package/src/test/utils.ts +185 -0
  142. package/dest/sequencer/block_builder.d.ts +0 -27
  143. package/dest/sequencer/block_builder.d.ts.map +0 -1
  144. package/dest/sequencer/block_builder.js +0 -130
  145. package/dest/tx_validator/nullifier_cache.d.ts +0 -14
  146. package/dest/tx_validator/nullifier_cache.d.ts.map +0 -1
  147. package/dest/tx_validator/nullifier_cache.js +0 -24
  148. package/dest/tx_validator/tx_validator_factory.d.ts +0 -17
  149. package/dest/tx_validator/tx_validator_factory.d.ts.map +0 -1
  150. package/dest/tx_validator/tx_validator_factory.js +0 -53
  151. package/src/sequencer/block_builder.ts +0 -218
  152. package/src/tx_validator/nullifier_cache.ts +0 -30
  153. package/src/tx_validator/tx_validator_factory.ts +0 -132
@@ -0,0 +1,243 @@
1
+ # Sequencer Timing Model
2
+
3
+ This document covers how the sequencer schedules its work within a slot. See the [package README](../../README.md) for the high-level architecture; this one focuses on the timing math and the state-machine deadlines.
4
+
5
+ The model described here is for **proposer pipelining**, the only mode the production sequencer runs in (the proposer always builds for `slot + 1`). The deterministic single-sequencer `AutomineSequencer` used in some e2e tests publishes synchronously in-slot and does not use this timing model.
6
+
7
+ ## Overview
8
+
9
+ Block production runs on three nested clocks:
10
+
11
+ - A **slot** is a fixed window (e.g. 72 s) during which one elected proposer is allowed to build.
12
+ - A slot contains several equal-length **sub-slots** (e.g. 8 s). Each sub-slot owns the budget for one L2 block and has a deadline fixed relative to the slot start.
13
+ - All blocks built within one slot make up one **checkpoint**, which is what eventually goes on L1.
14
+
15
+ Under pipelining, the proposer for slot `N` does its building inside slot `N - 1` ("build slot"). Slot `N` ("target slot") is only used to mine the L1 transaction. This shifts work like this:
16
+
17
+ | Phase | When |
18
+ | ------------------------------ | -------------- |
19
+ | Initialization | slot `N - 1` |
20
+ | Block building | slot `N - 1` |
21
+ | Checkpoint proposal broadcast | slot `N - 1` |
22
+ | Last-block re-execution | slot `N - 1` |
23
+ | Attestation collection | slot `N - 1` |
24
+ | L1 submission | slot `N` |
25
+
26
+ The wall-clock slot the sequencer is reasoning about ("build slot") and the slot the checkpoint commits to ("target slot") are always `N - 1` and `N` respectively.
27
+
28
+ ## Sub-slots
29
+
30
+ Each sub-slot has a fixed start time and a fixed deadline, both relative to the slot start:
31
+
32
+ ```
33
+ subSlotStart[k] = initializationOffset + (k - 1) * blockDuration
34
+ subSlotDeadline[k] = initializationOffset + k * blockDuration
35
+ ```
36
+
37
+ with `k = 1, 2, ..., maxNumberOfBlocks`. Deadlines do **not** shift based on when the previous block finished. If a block finishes early, the sequencer waits for the next sub-slot to begin (so validators see a regular cadence). If it finishes late, the next block has correspondingly less time.
38
+
39
+ `canStartNextBlock(secondsIntoSlot)` walks the sub-slot list and returns the first one with at least `minExecutionTime` left before its deadline. Sub-slots that no longer have enough headroom are skipped entirely.
40
+
41
+ ### Number of sub-slots
42
+
43
+ The maximum number of buildable blocks per slot is:
44
+
45
+ ```
46
+ timeReservedAtEnd = checkpointAssembleTime
47
+ + 2 * p2pPropagationTime // proposal out + attestations back
48
+ + blockDuration // last-block re-execution
49
+
50
+ timeAvailableForBlocks = aztecSlotDuration
51
+ - checkpointInitializationTime
52
+ - timeReservedAtEnd
53
+
54
+ maxNumberOfBlocks = floor(timeAvailableForBlocks / blockDuration)
55
+ ```
56
+
57
+ The reservation at the end of the slot is sized so that, on the happy path, attestations are in hand by the time the target slot starts. The enforced `COLLECTING_ATTESTATIONS` and `PUBLISHING_CHECKPOINT` deadlines are softer (see the deadline table below) and let a late attestation spill into the target slot. L1 publishing is **not** included in `timeReservedAtEnd` — that is paid for by the target slot.
58
+
59
+ ### Cooldown after the last sub-slot
60
+
61
+ All `maxNumberOfBlocks` sub-slots build a block. The cooldown lives in the `timeReservedAtEnd` window that follows the last sub-slot:
62
+
63
+ - 1 × `checkpointAssembleTime` to assemble and sign the checkpoint,
64
+ - 1 × `p2pPropagationTime` for the `CheckpointProposal` to reach the committee,
65
+ - 1 × `blockDuration` for the committee to re-execute the last block,
66
+ - 1 × `p2pPropagationTime` for attestations to come back.
67
+
68
+ These four windows total `checkpointAssembleTime + blockDuration + 2 * p2pPropagationTime`, exactly the `timeReservedAtEnd` formula above. The block built in the last sub-slot is *not* broadcast as a regular `BlockProposal`; the proposer holds it as `blockPendingBroadcast` so it travels bundled inside the `CheckpointProposal`.
69
+
70
+ ## Timing constants
71
+
72
+ These constants come from `@aztec/stdlib/timetable` (see `stdlib/src/timetable/index.ts`). Some are fixed across the network, some are inputs from configuration.
73
+
74
+ | Constant | Source | Typical value | Purpose |
75
+ | --------------------------------- | --------------------------------------- | ------------- | ---------------------------------------------------- |
76
+ | `aztecSlotDuration` | L1 rollup contract | 72 s | Length of one Aztec slot. |
77
+ | `ethereumSlotDuration` | L1 rollup contract | 12 s | Length of one Ethereum slot. |
78
+ | `blockDuration` | `blockDurationMs` config | 6–8 s | Sub-slot length. |
79
+ | `checkpointInitializationTime` | constant (`CHECKPOINT_INITIALIZATION_TIME`) | 1 s | Estimated sync + proposer check time. |
80
+ | `checkpointAssembleTime` | constant (`CHECKPOINT_ASSEMBLE_TIME`) | 1 s | Time to assemble and sign the checkpoint after the last block. |
81
+ | `p2pPropagationTime` | `attestationPropagationTime` config | 2 s | One-way p2p estimate (proposals, attestations). |
82
+ | `l1PublishingTime` | `l1PublishingTime` config | 12 s | Time reserved for the L1 tx to land. Used by the target slot, not the build slot. |
83
+ | `minExecutionTime` | constant (`MIN_EXECUTION_TIME`) | 2 s | Minimum headroom to start a block. |
84
+ | `initializationOffset` | `=checkpointInitializationTime` | 1 s | Where sub-slot 1 starts. |
85
+
86
+ ## Deadlines
87
+
88
+ `SequencerTimetable.getMaxAllowedTime(state)` returns the latest second-into-slot a given state is allowed to be entered. `assertTimeLeft()` throws `SequencerTooSlowError` if the slot has already advanced past that deadline. Sub-slot scheduling is measured against the build slot (`slotNow`); state assertions, however, are measured against whichever slot `setState` was called with — for the publishing path that is the target slot, which is why the publishing deadline is allowed to exceed `aztecSlotDuration`.
89
+
90
+ | State | Max allowed time (seconds into build slot) |
91
+ | --------------------------- | --------------------------------------------------------------------------- |
92
+ | `PROPOSER_CHECK` | `initializeDeadline = aztecSlotDuration - (checkpointInitializationTime + 2*minExecutionTime)` |
93
+ | `INITIALIZING_CHECKPOINT` | same as `PROPOSER_CHECK` |
94
+ | `WAITING_FOR_TXS` | `initializeDeadline + checkpointInitializationTime` |
95
+ | `CREATING_BLOCK` | same as `WAITING_FOR_TXS` |
96
+ | `WAITING_UNTIL_NEXT_BLOCK` | same as `WAITING_FOR_TXS` |
97
+ | `ASSEMBLING_CHECKPOINT` | `aztecSlotDuration + pipeliningAttestationGracePeriod` |
98
+ | `COLLECTING_ATTESTATIONS` | same as `ASSEMBLING_CHECKPOINT` |
99
+ | `PUBLISHING_CHECKPOINT` | `2 * aztecSlotDuration - ethereumSlotDuration` (extends into the target slot) |
100
+
101
+ In production-like timing, `pipeliningAttestationGracePeriod` is zero, so `ASSEMBLING_CHECKPOINT` and
102
+ `COLLECTING_ATTESTATIONS` must be *entered* before the build-slot boundary. Local networks with
103
+ `l1PublishingTime < ethereumSlotDuration` can use the target-slot attestation window as grace while preserving the
104
+ L1-geometry publishing cutoff. Once entered, attestation collection itself has its own
105
+ `checkpointAttestationDeadline = 2 * aztecSlotDuration - ethereumSlotDuration`, so a late attestation arriving after
106
+ the boundary is still accepted. The publishing deadline extends into the target slot because that is when the L1 tx is
107
+ actually submitted.
108
+
109
+ ## Example: 72 s slot, 8 s sub-slots
110
+
111
+ With typical pipelining values:
112
+
113
+ ```
114
+ checkpointInitializationTime = 1s
115
+ blockDuration = 8s
116
+ checkpointAssembleTime = 1s
117
+ p2pPropagationTime = 2s
118
+ l1PublishingTime = 12s
119
+
120
+ timeReservedAtEnd = 1 + 2*2 + 8 = 13s
121
+ timeAvailableForBlocks = 72 - 1 - 13 = 58s
122
+ maxNumberOfBlocks = floor(58 / 8) = 7
123
+ ```
124
+
125
+ Seven sub-slots, all of which build a block:
126
+
127
+ ```
128
+ Sub-slot 1: starts 1s, deadline 9s (Block 1)
129
+ Sub-slot 2: starts 9s, deadline 17s (Block 2)
130
+ Sub-slot 3: starts 17s, deadline 25s (Block 3)
131
+ Sub-slot 4: starts 25s, deadline 33s (Block 4)
132
+ Sub-slot 5: starts 33s, deadline 41s (Block 5)
133
+ Sub-slot 6: starts 41s, deadline 49s (Block 6)
134
+ Sub-slot 7: starts 49s, deadline 57s (Block 7 — held for the checkpoint proposal)
135
+
136
+ 57s: Block 7 done, ASSEMBLING_CHECKPOINT (1s)
137
+ 58s: CheckpointProposal broadcast
138
+ 60s: Committee receives proposal (+2s p2p)
139
+ 60-68s: Committee re-executes Block 7
140
+ 68s: Committee sends attestations
141
+ 70s: Proposer has the quorum (+2s p2p)
142
+
143
+ 70-72s: Slack
144
+ 72s: Build slot ends → L1 submission starts (target slot begins)
145
+ 84s: L1 tx mined inside the target slot (+12s)
146
+ ```
147
+
148
+ ## Parallel execution: proposer vs committee
149
+
150
+ While the proposer builds block `k+1`, the committee is re-executing block `k`. The pipeline keeps both sides busy except for the cooldown sub-slot.
151
+
152
+ ```
153
+ Time | Proposer | Committee
154
+ -----|------------------------------|--------------------------------------
155
+ 1s | Start Block 1 | (idle)
156
+ 9s | Finish Block 1, broadcast |
157
+ 9s | Start Block 2 |
158
+ 11s | | Receive Block 1 (9s + 2s)
159
+ | | Re-execute Block 1
160
+ 17s | Finish Block 2, broadcast |
161
+ 17s | Start Block 3 |
162
+ 19s | | Finish Block 1 (11s + 8s)
163
+ | | Receive Block 2 (17s + 2s)
164
+ | | Re-execute Block 2
165
+ ...
166
+ 49s | Finish Block 6, broadcast |
167
+ 49s | Start Block 7 (last) |
168
+ 51s | | Receive Block 6 (49s + 2s)
169
+ | | Re-execute Block 6
170
+ 57s | Finish Block 7 (held) |
171
+ | ASSEMBLING_CHECKPOINT (1s) |
172
+ 58s | Broadcast CheckpointProposal |
173
+ 59s | | Finish Block 6 (51s + 8s)
174
+ 60s | | Receive Block 7 + Checkpoint (58s + 2s)
175
+ | | Re-execute Block 7
176
+ 68s | | Send attestations (60s + 8s)
177
+ 70s | Receive attestations |
178
+ 70-72s| Slack |
179
+ 72s | L1 tx submitted |
180
+ 84s | L1 tx mined |
181
+ ```
182
+
183
+ **Observations**:
184
+
185
+ - Validators always lag the proposer by ~2 s (one p2p hop).
186
+ - For the last block there is no `k+1` to build alongside; once the proposer broadcasts the `CheckpointProposal`, it just waits while the committee re-executes.
187
+ - L1 publishing happens entirely inside the next slot and does not steal time from block building.
188
+
189
+ ## Handling timing variations
190
+
191
+ ### Fast initialization (0.5 s instead of 1 s)
192
+
193
+ Sub-slot 1's deadline is still 9 s, so Block 1 gets a 0.5 s bonus before hitting its deadline. No structural change.
194
+
195
+ ### Slow initialization (2 s instead of 1 s)
196
+
197
+ Block 1 has 7 s of build time instead of 8 s. Still well above `minExecutionTime`, so the block still gets built. No sub-slots are skipped.
198
+
199
+ ### Very slow initialization (8 s)
200
+
201
+ Sub-slot 1's deadline (9 s) is closer than `minExecutionTime` (2 s), so it is skipped entirely. The first attempted block runs in sub-slot 2 with the usual budget. The checkpoint will have one fewer block.
202
+
203
+ ### Block takes longer than its budget
204
+
205
+ `CheckpointBuilder` enforces the deadline by stopping public-tx execution; in practice a block can only overrun by the time it takes to finalize the block (typically < 1 s). The next sub-slot starts as scheduled but with proportionally less headroom. If that headroom drops below `minExecutionTime`, the next sub-slot is skipped.
206
+
207
+ ### Block finishes early
208
+
209
+ The sequencer transitions to `WAITING_UNTIL_NEXT_BLOCK` and sleeps until the next sub-slot start. This keeps the cadence regular and gives validators predictable arrival times for re-execution.
210
+
211
+ ### Block proposal returns insufficient txs
212
+
213
+ The current sub-slot is dropped without committing anything. The loop retries on the next sub-slot. If `buildCheckpointIfEmpty` is true, the last sub-slot is forced through with whatever is available, including zero txs.
214
+
215
+ ### Build slot ends before attestations arrive
216
+
217
+ `assertTimeLeft` will reject `PUBLISHING_CHECKPOINT` if the attestation deadline has passed; the slot is abandoned, and
218
+ `checkpoint-publish-failed` is emitted. The `PUBLISHING_CHECKPOINT` deadline allows spillover into the target slot
219
+ (`2 * aztecSlotDuration - ethereumSlotDuration`) precisely to absorb a small overrun.
220
+
221
+ ### Pipelined parent fails on L1
222
+
223
+ Before submitting, the job calls `waitForValidParentCheckpointOnL1`. If the parent we built on top of did not land cleanly (wrong archive, missing attestations, etc.) the job discards its checkpoint, emits `pipelined-checkpoint-discarded`, and enqueues an invalidation for the parent so the next proposer doesn't get stuck on the same bad ancestor.
224
+
225
+ ## Configuration constraints
226
+
227
+ `initializeDeadline` must be positive, so `aztecSlotDuration > checkpointInitializationTime + 2 * minExecutionTime`. With defaults that lower bound is 5 s, far below any realistic slot length.
228
+
229
+ For multi-block production to make sense, `maxNumberOfBlocks ≥ 2`:
230
+
231
+ ```
232
+ aztecSlotDuration ≥ checkpointInitializationTime
233
+ + 2 * blockDuration // two blocks
234
+ + checkpointAssembleTime
235
+ + 2 * p2pPropagationTime
236
+ + blockDuration // last-block re-execution window
237
+ ```
238
+
239
+ Block duration should be ≥ `minExecutionTime` (otherwise no sub-slot ever has enough headroom). `p2pPropagationTime` should be measured against the deployment's actual p2p latency: it directly determines how much of each slot is spent on the cooldown.
240
+
241
+ `l1PublishingTime` should fit inside the Ethereum slot the target slot maps to. The default of 12 s lines up with one
242
+ Ethereum slot; fast local networks may reduce it to use the target-slot attestation window as assembly and attestation
243
+ grace.
@@ -0,0 +1,46 @@
1
+ # AutomineSequencer
2
+
3
+ A minimal, deterministic, queue-driven sequencer for e2e tests that do not exercise block-building or consensus mechanics (e.g. `e2e_token`, `e2e_amm`, `e2e_authwit`).
4
+
5
+ ## When to use it
6
+
7
+ Use `AutomineSequencer` (via `AUTOMINE_E2E_OPTS`) for single-sequencer tests that care about contract logic, not about proposer selection, attestations, pipelining, or multi-validator coordination. It bypasses all of that machinery.
8
+
9
+ Use the production `Sequencer` (via `PIPELINING_SETUP_OPTS` or the default) for tests that explicitly exercise consensus, validator rotation, P2P gossip, slashing, or multi-node behavior.
10
+
11
+ **Requirement**: the deployed rollup must have `aztecTargetCommitteeSize == 0`. This causes `Rollup.verifyProposer` / `verifyAttestations` on L1 to short-circuit and accept an empty `CommitteeAttestationsAndSigners`, which is what `AutomineSequencer` always sends.
12
+
13
+ ## What it omits
14
+
15
+ Compared to the production `Sequencer`:
16
+
17
+ - No proposer-turn check (single sequencer, always proposes).
18
+ - No sync check, no pipelining, no timetable enforcement.
19
+ - No validator orchestration, attestation collection, or P2P proposal gossip.
20
+ - No slashing, no governance votes, no `SequencerEvents`.
21
+
22
+ Consumers (archiver, world-state, `EpochTestSettler`) observe L1 and the archiver tip directly rather than listening for sequencer events.
23
+
24
+ ## Serial-queue invariant
25
+
26
+ Every operation — mempool-driven block builds, explicit empty-block builds, time warps, and reorgs — is serialized through a single `SerialQueue`. They never interleave.
27
+
28
+ Public entry points:
29
+
30
+ | Method | Description |
31
+ | --- | --- |
32
+ | `buildIfPending()` | Enqueues a mempool-driven build. Coalesces bursts into one job. |
33
+ | `buildEmptyBlock()` | Enqueues a forced empty-block build. |
34
+ | `warpTo(ts)` / `warpBy(delta)` | Advances L1 time to a slot boundary. |
35
+ | `revertToCheckpoint(n)` | Rolls L1 back to the block that published checkpoint `n`, then resets archiver, world-state, and P2P pool. |
36
+ | `syncPoint()` | Awaits the queue reaching idle. |
37
+
38
+ ## Entry points
39
+
40
+ **Factory** — `createAutomineSequencer` in `automine_factory.ts` wires up all dependencies (publisher manager, keystore, cheat codes, etc.), starts the `PublisherManager`, and returns an unstarted `AutomineSequencer`. The caller (`AztecNodeService.createAndSync` in `aztec-node/src/aztec-node/server.ts`) invokes `AutomineSequencer.start()` separately. It is called by the full node when `aztecTargetCommitteeSize == 0`.
41
+
42
+ **Test fixture** — `AUTOMINE_E2E_OPTS` in `end-to-end/src/fixtures/fixtures.ts` is the test-side entry point. Pass it to `setup()` to get a node + `AutomineSequencer` instead of the production sequencer stack.
43
+
44
+ ## Epoch proving caveat
45
+
46
+ Epoch proving remains manual under `AUTOMINE_E2E_OPTS`. The e2e `setup()` fixture does NOT wire an `EpochTestSettler` — that observer is only attached in `local-network.ts`. Tests that cross epoch boundaries must therefore advance the proven anchor explicitly via `cheatCodes.rollup.markAsProven(...)`. See `e2e_lending_contract.test.ts` (which calls `progressSlots` in `simulators/lending_simulator.ts`) and `e2e_pruned_blocks.test.ts` for real examples.
@@ -0,0 +1,145 @@
1
+ import type { Archiver } from '@aztec/archiver';
2
+ import type { BlobClientInterface } from '@aztec/blob-client/client';
3
+ import type { EpochCache } from '@aztec/epoch-cache';
4
+ import { GovernanceProposerContract, type RollupContract } from '@aztec/ethereum/contracts';
5
+ import type { L1TxUtils } from '@aztec/ethereum/l1-tx-utils';
6
+ import { PublisherManager } from '@aztec/ethereum/publisher-manager';
7
+ import { EthCheatCodes } from '@aztec/ethereum/test';
8
+ import type { ViemPublicClient } from '@aztec/ethereum/types';
9
+ import type { Logger } from '@aztec/foundation/log';
10
+ import type { DateProvider } from '@aztec/foundation/timer';
11
+ import type { KeystoreManager } from '@aztec/node-keystore';
12
+ import type { P2PClient as ConcreteP2PClient, P2P } from '@aztec/p2p';
13
+ import type { L2BlockSource } from '@aztec/stdlib/block';
14
+ import type { ChainConfig } from '@aztec/stdlib/config';
15
+ import type { WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
16
+ import type { L1ToL2MessageSource } from '@aztec/stdlib/messaging';
17
+ import type { TelemetryClient } from '@aztec/telemetry-client';
18
+ import { type FullNodeCheckpointsBuilder, NodeKeystoreAdapter, type ValidatorClient } from '@aztec/validator-client';
19
+
20
+ import { type SequencerClientConfig, getPublisherConfigFromSequencerConfig } from '../../config.js';
21
+ import type { GlobalVariableBuilder } from '../../global_variable_builder/global_builder.js';
22
+ import { SequencerPublisherFactory } from '../../publisher/sequencer-publisher-factory.js';
23
+ import { AutomineSequencer } from './automine_sequencer.js';
24
+
25
+ /** Arguments for {@link createAutomineSequencer}. */
26
+ export type CreateAutomineSequencerArgs = {
27
+ config: SequencerClientConfig & Pick<ChainConfig, 'l1ChainId' | 'rollupAddress'>;
28
+ l1TxUtils: L1TxUtils[];
29
+ funderL1TxUtils: L1TxUtils | undefined;
30
+ publicClient: ViemPublicClient;
31
+ rollupContract: RollupContract;
32
+ epochCache: EpochCache;
33
+ blobClient: BlobClientInterface | undefined;
34
+ telemetry: TelemetryClient;
35
+ dateProvider: DateProvider;
36
+ keyStoreManager: KeystoreManager;
37
+ validatorClient: ValidatorClient;
38
+ checkpointsBuilder: FullNodeCheckpointsBuilder;
39
+ globalVariableBuilder: GlobalVariableBuilder;
40
+ worldStateSynchronizer: WorldStateSynchronizer;
41
+ archiver: L2BlockSource &
42
+ L1ToL2MessageSource &
43
+ Pick<Archiver, 'rollbackTo' | 'addBlock' | 'addProposedCheckpoint' | 'syncImmediate'>;
44
+ p2pClient: P2P & Pick<ConcreteP2PClient, 'sync'>;
45
+ l1Constants: { l1GenesisTime: bigint; slotDuration: number; ethereumSlotDuration: number; rollupManaLimit: number };
46
+ log: Logger;
47
+ };
48
+
49
+ /**
50
+ * Builds an {@link AutomineSequencer} for use in single-sequencer e2e tests.
51
+ *
52
+ * Constructs the PublisherManager, GovernanceProposerContract, SequencerPublisherFactory,
53
+ * looks up the attestor/coinbase/feeRecipient from the keystore, wires EthCheatCodes,
54
+ * and starts the publisher manager before returning.
55
+ */
56
+ export async function createAutomineSequencer({
57
+ config,
58
+ l1TxUtils,
59
+ funderL1TxUtils,
60
+ publicClient,
61
+ rollupContract,
62
+ epochCache,
63
+ blobClient,
64
+ telemetry,
65
+ dateProvider,
66
+ keyStoreManager,
67
+ validatorClient,
68
+ checkpointsBuilder,
69
+ globalVariableBuilder,
70
+ worldStateSynchronizer,
71
+ archiver,
72
+ p2pClient,
73
+ l1Constants,
74
+ log,
75
+ }: CreateAutomineSequencerArgs): Promise<AutomineSequencer> {
76
+ const publisherManager = new PublisherManager(l1TxUtils, getPublisherConfigFromSequencerConfig(config), {
77
+ bindings: log.getBindings(),
78
+ funder: funderL1TxUtils,
79
+ });
80
+ const governanceProposerContract = new GovernanceProposerContract(
81
+ publicClient,
82
+ config.governanceProposerAddress.toString(),
83
+ );
84
+ const publisherFactory = new SequencerPublisherFactory(config, {
85
+ telemetry,
86
+ blobClient: blobClient!,
87
+ epochCache,
88
+ governanceProposerContract,
89
+ rollupContract,
90
+ dateProvider,
91
+ publisherManager,
92
+ nodeKeyStore: NodeKeystoreAdapter.fromKeyStoreManager(keyStoreManager),
93
+ logger: log,
94
+ });
95
+ const attestorAddresses = NodeKeystoreAdapter.fromKeyStoreManager(keyStoreManager).getAttesterAddresses();
96
+ const attestor = attestorAddresses[0];
97
+ if (!attestor) {
98
+ throw new Error('AutomineSequencer requires at least one attestor address in the keystore');
99
+ }
100
+ const coinbase = validatorClient.getCoinbaseForAttestor(attestor);
101
+ const feeRecipient = validatorClient.getFeeRecipientForAttestor(attestor);
102
+ const ethCheatCodes = new EthCheatCodes(config.l1RpcUrls, dateProvider, log.createChild('eth-cheat-codes'));
103
+
104
+ // Include the funder's L1TxUtils in the reorg reset list so funding-tx nonces don't
105
+ // go stale after L1 rollbacks. Dedupe by sender address in case the funder reuses a
106
+ // publisher's signer.
107
+ const reorgResetL1TxUtils = (() => {
108
+ if (!funderL1TxUtils) {
109
+ return l1TxUtils;
110
+ }
111
+ const funderAddress = funderL1TxUtils.getSenderAddress().toString();
112
+ const alreadyIncluded = l1TxUtils.some(utils => utils.getSenderAddress().toString() === funderAddress);
113
+ return alreadyIncluded ? l1TxUtils : [...l1TxUtils, funderL1TxUtils];
114
+ })();
115
+
116
+ const automineSequencer = new AutomineSequencer({
117
+ publisherFactory,
118
+ checkpointsBuilder,
119
+ globalsBuilder: globalVariableBuilder,
120
+ worldState: worldStateSynchronizer,
121
+ l2BlockSource: archiver,
122
+ l1ToL2MessageSource: archiver,
123
+ p2pClient,
124
+ ethCheatCodes,
125
+ dateProvider: dateProvider as any, // TestDateProvider; verified at construction in fixture
126
+ l1Constants: {
127
+ l1GenesisTime: l1Constants.l1GenesisTime,
128
+ slotDuration: l1Constants.slotDuration,
129
+ ethereumSlotDuration: l1Constants.ethereumSlotDuration,
130
+ rollupManaLimit: l1Constants.rollupManaLimit,
131
+ epochDuration: config.aztecEpochDuration,
132
+ },
133
+ coinbase,
134
+ feeRecipient,
135
+ signatureContext: { chainId: config.l1ChainId, rollupAddress: config.rollupAddress },
136
+ config,
137
+ archiver,
138
+ l1TxUtils: reorgResetL1TxUtils,
139
+ stopExtras: () => publisherManager.stop(),
140
+ log: log.createChild('automine-sequencer'),
141
+ });
142
+
143
+ await publisherManager.start();
144
+ return automineSequencer;
145
+ }