@aztec/p2p 0.0.1-commit.b64cb54f6 → 0.0.1-commit.b6e433891

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 (133) hide show
  1. package/README.md +129 -3
  2. package/dest/client/factory.d.ts +1 -1
  3. package/dest/client/factory.d.ts.map +1 -1
  4. package/dest/client/factory.js +19 -12
  5. package/dest/client/p2p_client.d.ts +1 -1
  6. package/dest/client/p2p_client.d.ts.map +1 -1
  7. package/dest/client/p2p_client.js +16 -10
  8. package/dest/client/test/tx_proposal_collector/proposal_tx_collector_worker.js +6 -5
  9. package/dest/config.d.ts +7 -1
  10. package/dest/config.d.ts.map +1 -1
  11. package/dest/config.js +10 -0
  12. package/dest/mem_pools/attestation_pool/attestation_pool.d.ts +3 -3
  13. package/dest/mem_pools/attestation_pool/attestation_pool.js +3 -3
  14. package/dest/mem_pools/attestation_pool/attestation_pool_test_suite.js +6 -6
  15. package/dest/mem_pools/tx_pool/eviction/fee_payer_balance_eviction_rule.d.ts +1 -1
  16. package/dest/mem_pools/tx_pool/eviction/fee_payer_balance_eviction_rule.d.ts.map +1 -1
  17. package/dest/mem_pools/tx_pool/eviction/fee_payer_balance_eviction_rule.js +2 -1
  18. package/dest/mem_pools/tx_pool/priority.d.ts +2 -2
  19. package/dest/mem_pools/tx_pool/priority.d.ts.map +1 -1
  20. package/dest/mem_pools/tx_pool/priority.js +2 -3
  21. package/dest/mem_pools/tx_pool_v2/eviction/fee_payer_balance_eviction_rule.d.ts +1 -1
  22. package/dest/mem_pools/tx_pool_v2/eviction/fee_payer_balance_eviction_rule.d.ts.map +1 -1
  23. package/dest/mem_pools/tx_pool_v2/eviction/fee_payer_balance_eviction_rule.js +2 -1
  24. package/dest/mem_pools/tx_pool_v2/interfaces.d.ts +7 -5
  25. package/dest/mem_pools/tx_pool_v2/interfaces.d.ts.map +1 -1
  26. package/dest/mem_pools/tx_pool_v2/tx_metadata.d.ts +9 -2
  27. package/dest/mem_pools/tx_pool_v2/tx_metadata.d.ts.map +1 -1
  28. package/dest/mem_pools/tx_pool_v2/tx_metadata.js +7 -1
  29. package/dest/mem_pools/tx_pool_v2/tx_pool_v2.d.ts +4 -2
  30. package/dest/mem_pools/tx_pool_v2/tx_pool_v2.d.ts.map +1 -1
  31. package/dest/mem_pools/tx_pool_v2/tx_pool_v2.js +3 -0
  32. package/dest/mem_pools/tx_pool_v2/tx_pool_v2_impl.d.ts +1 -1
  33. package/dest/mem_pools/tx_pool_v2/tx_pool_v2_impl.d.ts.map +1 -1
  34. package/dest/mem_pools/tx_pool_v2/tx_pool_v2_impl.js +11 -4
  35. package/dest/msg_validators/attestation_validator/attestation_validator.d.ts +1 -1
  36. package/dest/msg_validators/attestation_validator/attestation_validator.d.ts.map +1 -1
  37. package/dest/msg_validators/attestation_validator/attestation_validator.js +5 -4
  38. package/dest/msg_validators/clock_tolerance.d.ts +1 -1
  39. package/dest/msg_validators/clock_tolerance.d.ts.map +1 -1
  40. package/dest/msg_validators/clock_tolerance.js +4 -3
  41. package/dest/msg_validators/proposal_validator/proposal_validator.d.ts +1 -1
  42. package/dest/msg_validators/proposal_validator/proposal_validator.d.ts.map +1 -1
  43. package/dest/msg_validators/proposal_validator/proposal_validator.js +5 -5
  44. package/dest/msg_validators/tx_validator/factory.d.ts +9 -1
  45. package/dest/msg_validators/tx_validator/factory.d.ts.map +1 -1
  46. package/dest/msg_validators/tx_validator/factory.js +15 -2
  47. package/dest/msg_validators/tx_validator/phases_validator.d.ts +21 -1
  48. package/dest/msg_validators/tx_validator/phases_validator.d.ts.map +1 -1
  49. package/dest/msg_validators/tx_validator/phases_validator.js +27 -0
  50. package/dest/services/encoding.d.ts +5 -1
  51. package/dest/services/encoding.d.ts.map +1 -1
  52. package/dest/services/encoding.js +7 -1
  53. package/dest/services/libp2p/libp2p_service.d.ts +2 -9
  54. package/dest/services/libp2p/libp2p_service.d.ts.map +1 -1
  55. package/dest/services/libp2p/libp2p_service.js +7 -24
  56. package/dest/services/peer-manager/peer_manager.d.ts +1 -1
  57. package/dest/services/peer-manager/peer_manager.d.ts.map +1 -1
  58. package/dest/services/peer-manager/peer_manager.js +2 -2
  59. package/dest/services/reqresp/batch-tx-requester/batch_tx_requester.d.ts +11 -8
  60. package/dest/services/reqresp/batch-tx-requester/batch_tx_requester.d.ts.map +1 -1
  61. package/dest/services/reqresp/batch-tx-requester/batch_tx_requester.js +66 -65
  62. package/dest/services/reqresp/batch-tx-requester/interface.d.ts +3 -2
  63. package/dest/services/reqresp/batch-tx-requester/interface.d.ts.map +1 -1
  64. package/dest/services/reqresp/batch-tx-requester/missing_txs.d.ts +5 -4
  65. package/dest/services/reqresp/batch-tx-requester/missing_txs.d.ts.map +1 -1
  66. package/dest/services/reqresp/batch-tx-requester/missing_txs.js +13 -7
  67. package/dest/services/reqresp/batch-tx-requester/peer_collection.d.ts +3 -1
  68. package/dest/services/reqresp/batch-tx-requester/peer_collection.d.ts.map +1 -1
  69. package/dest/services/reqresp/batch-tx-requester/peer_collection.js +3 -0
  70. package/dest/services/reqresp/reqresp.d.ts +1 -1
  71. package/dest/services/reqresp/reqresp.d.ts.map +1 -1
  72. package/dest/services/reqresp/reqresp.js +17 -9
  73. package/dest/services/tx_collection/fast_tx_collection.d.ts +1 -4
  74. package/dest/services/tx_collection/fast_tx_collection.d.ts.map +1 -1
  75. package/dest/services/tx_collection/fast_tx_collection.js +57 -73
  76. package/dest/services/tx_collection/proposal_tx_collector.d.ts +6 -7
  77. package/dest/services/tx_collection/proposal_tx_collector.d.ts.map +1 -1
  78. package/dest/services/tx_collection/proposal_tx_collector.js +4 -4
  79. package/dest/services/tx_collection/request_tracker.d.ts +53 -0
  80. package/dest/services/tx_collection/request_tracker.d.ts.map +1 -0
  81. package/dest/services/tx_collection/request_tracker.js +84 -0
  82. package/dest/services/tx_collection/slow_tx_collection.js +1 -1
  83. package/dest/services/tx_collection/tx_collection.d.ts +3 -6
  84. package/dest/services/tx_collection/tx_collection.d.ts.map +1 -1
  85. package/dest/test-helpers/testbench-utils.d.ts +1 -1
  86. package/dest/test-helpers/testbench-utils.d.ts.map +1 -1
  87. package/dest/test-helpers/testbench-utils.js +20 -2
  88. package/dest/testbench/p2p_client_testbench_worker.d.ts +1 -1
  89. package/dest/testbench/p2p_client_testbench_worker.d.ts.map +1 -1
  90. package/dest/testbench/p2p_client_testbench_worker.js +6 -5
  91. package/package.json +14 -14
  92. package/src/client/factory.ts +34 -17
  93. package/src/client/p2p_client.ts +19 -10
  94. package/src/client/test/tx_proposal_collector/proposal_tx_collector_worker.ts +6 -7
  95. package/src/config.ts +17 -0
  96. package/src/mem_pools/attestation_pool/attestation_pool.ts +3 -3
  97. package/src/mem_pools/attestation_pool/attestation_pool_test_suite.ts +6 -6
  98. package/src/mem_pools/tx_pool/eviction/fee_payer_balance_eviction_rule.ts +2 -1
  99. package/src/mem_pools/tx_pool/priority.ts +2 -5
  100. package/src/mem_pools/tx_pool_v2/eviction/fee_payer_balance_eviction_rule.ts +2 -1
  101. package/src/mem_pools/tx_pool_v2/interfaces.ts +6 -4
  102. package/src/mem_pools/tx_pool_v2/tx_metadata.ts +11 -1
  103. package/src/mem_pools/tx_pool_v2/tx_pool_v2.ts +13 -1
  104. package/src/mem_pools/tx_pool_v2/tx_pool_v2_impl.ts +12 -4
  105. package/src/msg_validators/attestation_validator/README.md +49 -0
  106. package/src/msg_validators/attestation_validator/attestation_validator.ts +5 -4
  107. package/src/msg_validators/clock_tolerance.ts +4 -3
  108. package/src/msg_validators/proposal_validator/README.md +123 -0
  109. package/src/msg_validators/proposal_validator/proposal_validator.ts +6 -5
  110. package/src/msg_validators/tx_validator/README.md +5 -1
  111. package/src/msg_validators/tx_validator/factory.ts +21 -1
  112. package/src/msg_validators/tx_validator/phases_validator.ts +30 -0
  113. package/src/services/encoding.ts +9 -1
  114. package/src/services/libp2p/libp2p_service.ts +6 -27
  115. package/src/services/peer-manager/peer_manager.ts +3 -2
  116. package/src/services/reqresp/README.md +229 -0
  117. package/src/services/reqresp/batch-tx-requester/README.md +46 -7
  118. package/src/services/reqresp/batch-tx-requester/batch_tx_requester.ts +61 -69
  119. package/src/services/reqresp/batch-tx-requester/interface.ts +2 -1
  120. package/src/services/reqresp/batch-tx-requester/missing_txs.ts +13 -6
  121. package/src/services/reqresp/batch-tx-requester/peer_collection.ts +5 -0
  122. package/src/services/reqresp/reqresp.ts +19 -11
  123. package/src/services/tx_collection/fast_tx_collection.ts +57 -83
  124. package/src/services/tx_collection/proposal_tx_collector.ts +8 -13
  125. package/src/services/tx_collection/request_tracker.ts +127 -0
  126. package/src/services/tx_collection/slow_tx_collection.ts +1 -1
  127. package/src/services/tx_collection/tx_collection.ts +3 -5
  128. package/src/test-helpers/testbench-utils.ts +28 -3
  129. package/src/testbench/p2p_client_testbench_worker.ts +6 -8
  130. package/dest/services/tx_collection/missing_txs_tracker.d.ts +0 -32
  131. package/dest/services/tx_collection/missing_txs_tracker.d.ts.map +0 -1
  132. package/dest/services/tx_collection/missing_txs_tracker.js +0 -27
  133. package/src/services/tx_collection/missing_txs_tracker.ts +0 -52
@@ -11,7 +11,14 @@ import { type TelemetryClient, getTelemetryClient } from '@aztec/telemetry-clien
11
11
  import EventEmitter from 'node:events';
12
12
 
13
13
  import { PoolInstrumentation, PoolName } from '../instrumentation.js';
14
- import type { AddTxsResult, TxPoolV2, TxPoolV2Config, TxPoolV2Dependencies, TxPoolV2Events } from './interfaces.js';
14
+ import type {
15
+ AddTxsResult,
16
+ PoolReadAccess,
17
+ TxPoolV2,
18
+ TxPoolV2Config,
19
+ TxPoolV2Dependencies,
20
+ TxPoolV2Events,
21
+ } from './interfaces.js';
15
22
  import type { TxState } from './tx_metadata.js';
16
23
  import { TxPoolV2Impl } from './tx_pool_v2_impl.js';
17
24
 
@@ -165,6 +172,11 @@ export class AztecKVTxPoolV2 extends (EventEmitter as new () => TypedEventEmitte
165
172
  return this.#queue.put(() => Promise.resolve(this.#impl.getLowestPriorityPending(limit)));
166
173
  }
167
174
 
175
+ /** Returns read-only access to the pool. Used for testing. */
176
+ getPoolReadAccess(): PoolReadAccess {
177
+ return this.#impl.getPoolReadAccess();
178
+ }
179
+
168
180
  // === Configuration ===
169
181
 
170
182
  updateConfig(config: Partial<TxPoolV2Config>): Promise<void> {
@@ -62,6 +62,7 @@ export class TxPoolV2Impl {
62
62
  #l2BlockSource: L2BlockSource;
63
63
  #worldStateSynchronizer: WorldStateSynchronizer;
64
64
  #createTxValidator: TxPoolV2Dependencies['createTxValidator'];
65
+ #checkAllowedSetupCalls: TxPoolV2Dependencies['checkAllowedSetupCalls'];
65
66
 
66
67
  // === In-Memory Indices ===
67
68
  #indices: TxPoolIndices = new TxPoolIndices();
@@ -93,6 +94,7 @@ export class TxPoolV2Impl {
93
94
  this.#l2BlockSource = deps.l2BlockSource;
94
95
  this.#worldStateSynchronizer = deps.worldStateSynchronizer;
95
96
  this.#createTxValidator = deps.createTxValidator;
97
+ this.#checkAllowedSetupCalls = deps.checkAllowedSetupCalls;
96
98
 
97
99
  this.#config = { ...DEFAULT_TX_POOL_V2_CONFIG, ...config };
98
100
  this.#archive = new TxArchive(archiveStore, this.#config.archivedTxLimit, log);
@@ -375,20 +377,25 @@ export class TxPoolV2Impl {
375
377
  async addProtectedTxs(txs: Tx[], block: BlockHeader, opts: { source?: string }): Promise<void> {
376
378
  const slotNumber = block.globalVariables.slotNumber;
377
379
 
380
+ // Precompute setup-call allow-list flags outside the store transaction
381
+ const allowedFlags = await Promise.all(txs.map(tx => this.#checkAllowedSetupCalls(tx)));
382
+
378
383
  await this.#store.transactionAsync(async () => {
379
- for (const tx of txs) {
384
+ for (let i = 0; i < txs.length; i++) {
385
+ const tx = txs[i];
380
386
  const txHash = tx.getTxHash();
381
387
  const txHashStr = txHash.toString();
382
388
  const isNew = !this.#indices.has(txHashStr);
383
389
  const minedBlockId = await this.#getMinedBlockId(txHash);
384
390
 
385
391
  if (isNew) {
392
+ const meta = await buildTxMetaData(tx, allowedFlags[i]);
386
393
  // New tx - add as mined or protected (callback emitted by #addTx)
387
394
  if (minedBlockId) {
388
- await this.#addTx(tx, { mined: minedBlockId }, opts);
395
+ await this.#addTx(tx, { mined: minedBlockId }, opts, meta);
389
396
  this.#indices.setProtection(txHashStr, slotNumber);
390
397
  } else {
391
- await this.#addTx(tx, { protected: slotNumber }, opts);
398
+ await this.#addTx(tx, { protected: slotNumber }, opts, meta);
392
399
  }
393
400
  } else {
394
401
  // Existing tx - update protection and mined status
@@ -983,7 +990,8 @@ export class TxPoolV2Impl {
983
990
 
984
991
  try {
985
992
  const tx = Tx.fromBuffer(buffer);
986
- const meta = await buildTxMetaData(tx);
993
+ const allowedSetupCalls = await this.#checkAllowedSetupCalls(tx);
994
+ const meta = await buildTxMetaData(tx, allowedSetupCalls);
987
995
  loaded.push({ tx, meta });
988
996
  } catch (err) {
989
997
  this.#log.warn(`Failed to deserialize tx ${txHashStr}, deleting`, { err });
@@ -0,0 +1,49 @@
1
+ # Attestation Validation
2
+
3
+ This module validates `CheckpointAttestation` gossipsub messages. Attestations are signatures from committee members endorsing a checkpoint proposal.
4
+
5
+ **Topic**: `checkpoint_attestation` | **Snappy size limit**: 5 KB
6
+
7
+ ## Stage 1: AttestationValidator (Gossipsub Validation)
8
+
9
+ | # | Rule | Consequence | Severity | File |
10
+ |---|------|-------------|----------|------|
11
+ | 1 | **Slot timeliness**: `currentSlot` or `nextSlot`. Previous slot within 500ms: IGNORE. Older: REJECT. | REJECT or IGNORE | HighToleranceError | `attestation_validator.ts` |
12
+ | 2 | **Attester signature**: `getSender()` must recover valid address | REJECT | LowToleranceError | same |
13
+ | 3 | **Attester in committee**: recovered address in committee for slot | REJECT | HighToleranceError | same |
14
+ | 4 | **Proposer exists**: `getProposerAttesterAddressInSlot` must return defined | REJECT | HighToleranceError | same |
15
+ | 5 | **Proposer signature**: `getProposer()` must recover valid address | REJECT | LowToleranceError | same |
16
+ | 6 | **Proposer matches expected**: recovered proposer = expected for slot | REJECT | HighToleranceError | same |
17
+ | 7 | **NoCommitteeError**: committee unavailable | REJECT | LowToleranceError | same |
18
+
19
+ **Fisherman mode extension** (`FishermanAttestationValidator`): if a checkpoint proposal for the same archive exists in pool, the attestation's `ConsensusPayload` must `.equals()` the stored proposal's payload. On mismatch: REJECT + LowToleranceError.
20
+
21
+ ## Stage 2: Pool Admission
22
+
23
+ | # | Rule | Consequence |
24
+ |---|------|-------------|
25
+ | 8 | Sender recoverable (pool-side) | Silent drop |
26
+ | 9 | Not a duplicate (same slot + proposalId + signer) | IGNORE |
27
+ | 10 | Per-signer cap: `MAX_ATTESTATIONS_PER_SLOT_AND_SIGNER` = 2 | IGNORE |
28
+
29
+ Own attestations added via `addOwnCheckpointAttestations` bypass the per-signer cap.
30
+
31
+ ## Stage 3: Equivocation Detection
32
+
33
+ When a signer's attestation count for a slot reaches exactly 2 (different proposals): `duplicateAttestationCallback` fires -> `WANT_TO_SLASH_EVENT` with `OffenseType.DUPLICATE_ATTESTATION`. Attestation still ACCEPTED and rebroadcast. Callback fires once (not again at count 3+).
34
+
35
+ ## Validation at L1 Checkpoint Submission (Archiver)
36
+
37
+ | Rule | Consequence | File |
38
+ |------|-------------|------|
39
+ | Each attestation must have recoverable signature (or address-only is allowed but does not count toward quorum) | Checkpoint rejected as invalid | `archiver/src/modules/validation.ts` |
40
+ | Attestation at index `i` must correspond to committee member at index `i` | Checkpoint rejected as invalid | same |
41
+ | Valid attestation count >= floor(committee * 2/3) + 1 | Checkpoint rejected as invalid | same |
42
+ | No committee / escape hatch open | Accepted unconditionally | same |
43
+
44
+ Note: `skipValidateCheckpointAttestations` config flag bypasses all archiver attestation validation.
45
+
46
+ ## Gossipsub Topic Scoring
47
+
48
+ P3 enabled with expected messages per slot = `targetCommitteeSize`. Conservative threshold (30% of convergence value). Max P3 penalty = -34 per topic.
49
+
@@ -23,13 +23,14 @@ export class CheckpointAttestationValidator implements P2PValidator<CheckpointAt
23
23
  const slotNumber = message.payload.header.slotNumber;
24
24
 
25
25
  try {
26
- const { currentSlot, nextSlot } = this.epochCache.getCurrentAndNextSlot();
26
+ // Use target slots since proposals target pipeline slots (slot + 1 when pipelining)
27
+ const { targetSlot, nextSlot } = this.epochCache.getTargetAndNextSlot();
27
28
 
28
- if (slotNumber !== currentSlot && slotNumber !== nextSlot) {
29
+ if (slotNumber !== targetSlot && slotNumber !== nextSlot) {
29
30
  // Check if message is for previous slot and within clock tolerance
30
- if (!isWithinClockTolerance(slotNumber, currentSlot, this.epochCache)) {
31
+ if (!isWithinClockTolerance(slotNumber, targetSlot, this.epochCache)) {
31
32
  this.logger.warn(
32
- `Checkpoint attestation slot ${slotNumber} is not current (${currentSlot}) or next (${nextSlot}) slot`,
33
+ `Checkpoint attestation slot ${slotNumber} is not current (${targetSlot}) or next (${nextSlot}) slot`,
33
34
  );
34
35
  return { result: 'reject', severity: PeerErrorSeverity.HighToleranceError };
35
36
  }
@@ -36,10 +36,11 @@ export function isWithinClockTolerance(
36
36
  }
37
37
 
38
38
  // Check how far we are into the current slot (in milliseconds)
39
- const { ts: slotStartTs, nowMs, slot } = epochCache.getEpochAndSlotNow();
39
+ const { ts: slotStartTs, nowMs } = epochCache.getEpochAndSlotNow();
40
+ const targetSlot = epochCache.getTargetSlot();
40
41
 
41
- // Sanity check: ensure the epoch cache's current slot matches the expected current slot
42
- if (slot !== currentSlot) {
42
+ // Sanity check: ensure the epoch cache's target slot matches the expected current slot
43
+ if (targetSlot !== currentSlot) {
43
44
  return false;
44
45
  }
45
46
 
@@ -0,0 +1,123 @@
1
+ # Proposal Validation
2
+
3
+ This module validates `BlockProposal` and `CheckpointProposal` gossipsub messages. Both share the same base `ProposalValidator` (neither subclass overrides `validate()`), with checkpoint-specific logic layered on top in the gossipsub handler.
4
+
5
+ ## BlockProposal
6
+
7
+ **Topic**: `block_proposal` | **Snappy size limit**: 10 MB
8
+
9
+ ### Stage 1: Gossipsub Validation (ProposalValidator)
10
+
11
+ File: `proposal_validator.ts`
12
+
13
+ | # | Rule | Consequence | Severity |
14
+ |---|------|-------------|----------|
15
+ | 1 | **Slot check**: must be `currentSlot` or `nextSlot`. Previous slot within 500ms tolerance: IGNORE. | REJECT | HighToleranceError |
16
+ | 2 | **Signature**: `getSender()` must recover a valid address. If `signedTxs` present, its recovered sender must match. | REJECT | MidToleranceError |
17
+ | 3 | **Txs permitted**: if `disableTransactions`, must have 0 txHashes and 0 embedded txs | REJECT | MidToleranceError |
18
+ | 4 | **Max txs**: `txHashes.length <= maxTxsPerBlock` | REJECT | MidToleranceError |
19
+ | 5 | **Embedded txs in txHashes**: every embedded tx's hash must appear in `txHashes` | REJECT | MidToleranceError |
20
+ | 6 | **Proposer check**: signer must match expected proposer for slot (skipped if committee size = 0) | REJECT | MidToleranceError |
21
+ | 7 | **Tx hash integrity**: each embedded tx's recomputed hash must match declared hash | REJECT | LowToleranceError |
22
+ | 8 | **NoCommitteeError**: epoch cache cannot determine committee | REJECT | LowToleranceError |
23
+
24
+ Deserialization guards: `BlockProposal.fromBuffer` and `SignedTxs.fromBuffer` both enforce `txCount <= MAX_TXS_PER_BLOCK` (65536). Violation -> REJECT + LowToleranceError.
25
+
26
+ ### Stage 2: Mempool (Attestation Pool)
27
+
28
+ | # | Rule | Consequence |
29
+ |---|------|-------------|
30
+ | 9 | **Duplicate**: same archive root already stored | IGNORE (no penalty) |
31
+ | 10 | **Per-position cap**: max 2 proposals per (slot, indexWithinCheckpoint) | REJECT + HighToleranceError |
32
+ | 11 | **Equivocation**: >1 distinct proposal for same (slot, index) | ACCEPT (rebroadcast for detection). At count=2: `duplicateProposalCallback` fires -> slash event (`OffenseType.DUPLICATE_PROPOSAL`, configured via `slashDuplicateProposalPenalty`) |
33
+
34
+ ### Stage 3: Validator-Client Processing (BlockProposalHandler)
35
+
36
+ Only runs on validator nodes. Non-validator nodes use a default handler that triggers tx collection without deep validation.
37
+
38
+ | # | Rule | Failure Reason |
39
+ |---|------|----------------|
40
+ | 12 | Signature re-check | `invalid_proposal` |
41
+ | 13 | ProposalValidator re-run | `invalid_proposal` |
42
+ | 14 | Self-proposal filter | Ignored silently |
43
+ | 15 | Parent block exists (`lastArchive.root` matches known block or genesis) | `parent_block_not_found` |
44
+ | 16 | Parent block slot <= proposal slot | `parent_block_wrong_slot` |
45
+ | 17 | Block number not already in archiver | `block_number_already_exists` |
46
+ | 18 | Checkpoint number consistency (multiple sub-rules for first/non-first blocks) | `invalid_proposal` |
47
+ | 19 | Global variables consistency (non-first block: chainId, version, slot, timestamp, coinbase, feeRecipient, gasFees match parent) | `global_variables_mismatch` |
48
+ | 20 | L1-to-L2 message hash matches `proposal.inHash` | `in_hash_mismatch` |
49
+ | 21 | All txs referenced by `txHashes` obtainable | `txs_not_available` |
50
+ | 22 | **Re-execution**: processed tx count matches `txHashes.length` | `timeout` (ReExTimeoutError) |
51
+ | 23 | **Re-execution**: no failed txs | `failed_txs` (ReExFailedTxsError) -- **SLASHABLE** |
52
+ | 24 | **Re-execution**: archive root and header match proposal | `state_mismatch` (ReExStateMismatchError) -- **SLASHABLE** |
53
+
54
+ **Escape hatch**: during escape hatch periods (`isEscapeHatchOpenAtSlot`), re-execution and slashing are both disabled, and the proposal is rejected locally.
55
+
56
+ **Conditional re-execution**: rules 22-24 only run when at least one condition is true: `fishermanMode` enabled, `slashBroadcastedInvalidBlockPenalty > 0` with `validatorReexecute`, committee membership with `validatorReexecute`, `alwaysReexecuteBlockProposals`, or `blobClient.canUpload()`.
57
+
58
+ **Slashing**: only `state_mismatch` and `failed_txs` trigger on-chain slashing (`OffenseType.BROADCASTED_INVALID_BLOCK_PROPOSAL`, gated by `slashBroadcastedInvalidBlockPenalty > 0`). Unknown errors during re-execution do NOT slash.
59
+
60
+ **Embedded tx validation**: txs in `signedTxs` are validated via `createTxValidatorForBlockProposalReceivedTxs` (well-formedness only) when stored in the tx pool. Invalid embedded txs are rejected from the pool but do not cause the block proposal itself to be rejected at gossipsub level.
61
+
62
+ ### Gossipsub Topic Scoring
63
+
64
+ | Parameter | Effect |
65
+ |-----------|--------|
66
+ | P4 (invalidMessageDeliveries) | weight = -20, decay over 4 slots |
67
+ | P3 (meshMessageDeliveries) | Enabled only when `expectedBlockProposalsPerSlot > 0` (MBPS mode) |
68
+ | P1/P2 | Only active when P3 is enabled |
69
+
70
+ ---
71
+
72
+ ## CheckpointProposal
73
+
74
+ **Topic**: `checkpoint_proposal` | **Snappy size limit**: 10 MB
75
+
76
+ ### Stage 1: Gossipsub Validation (ProposalValidator)
77
+
78
+ Same `ProposalValidator.validate()` as BlockProposal (shared implementation, neither subclass overrides it). See BlockProposal Stage 1 rules 1-8.
79
+
80
+ ### Stage 2: Embedded Block Proposal Validation (if `lastBlock` present)
81
+
82
+ The checkpoint's embedded `lastBlock` is extracted via `getBlockProposal()` and validated through `BlockProposalValidator.validate()` plus block mempool checks.
83
+
84
+ | Rule | Consequence | File |
85
+ |------|-------------|------|
86
+ | Block proposal must pass `BlockProposalValidator.validate()` | If REJECT: entire checkpoint REJECTED | `libp2p_service.ts` |
87
+ | Block proposal must not exceed per-position cap (2) | Checkpoint REJECTED + HighToleranceError | same |
88
+ | Block equivocation detected (>1 proposals for same slot+index) | Checkpoint REJECTED (block itself is ACCEPT for re-broadcast) | same |
89
+
90
+ ### Stage 3: Mempool (Attestation Pool)
91
+
92
+ | Rule | Consequence | File |
93
+ |------|-------------|------|
94
+ | Duplicate (same archive ID) | IGNORE (no penalty). Embedded block still processed if valid. | `attestation_pool.ts` |
95
+ | Per-slot cap: `MAX_CHECKPOINT_PROPOSALS_PER_SLOT` = 2 | REJECT + HighToleranceError. Embedded block still processed. | same |
96
+
97
+ ### Stage 4: Equivocation Detection
98
+
99
+ When >1 checkpoint proposals exist for same slot (count > 1): ACCEPT (re-broadcast). At count == 2 (exactly): `duplicateProposalCallback` fires. Proposal NOT further processed. Callback fires only once per equivocation pair.
100
+
101
+ ### Stage 5: Validator-Client Consensus Validation
102
+
103
+ Determines whether the validator signs an attestation.
104
+
105
+ | Rule | Consequence | File |
106
+ |------|-------------|------|
107
+ | Escape hatch open | No attestation | `validator-client/src/validator.ts` |
108
+ | Signature invalid (re-check) | No attestation | same |
109
+ | Self-proposal | No attestation (ignored) | same |
110
+ | `feeAssetPriceModifier` outside [-100, +100] bps | No attestation | same |
111
+ | Not in committee (unless fisherman mode) | No attestation | same |
112
+ | Checkpoint header mismatch (computed vs proposal) | No attestation | same |
113
+ | Archive root mismatch | No attestation | same |
114
+ | Epoch out hash mismatch | No attestation | same |
115
+ | Last block not found / not matching | No attestation | same |
116
+ | Already attested to this or earlier slot | No attestation (unless `attestToEquivocatedProposals`) | same |
117
+
118
+ **`skipCheckpointProposalValidation` config**: when true, the re-execution checks (header/archive/epoch hash) are all skipped. Signature, fee modifier, committee, escape hatch, and equivocation checks still apply.
119
+
120
+ ### Gossipsub Topic Scoring
121
+
122
+ P3 enabled with expected rate of 1 message per slot. P4 weight = -20, max P3 penalty = -34 per topic.
123
+
@@ -31,13 +31,14 @@ export class ProposalValidator {
31
31
  /** Validates header-level fields: slot, signature, and proposer. */
32
32
  public async validate(proposal: BlockProposal | CheckpointProposalCore): Promise<ValidationResult> {
33
33
  try {
34
- // Slot check
35
- const { currentSlot, nextSlot } = this.epochCache.getCurrentAndNextSlot();
34
+ // Slot check: use target slots since proposals target pipeline slots (slot + 1 when pipelining)
35
+ const { targetSlot, nextSlot } = this.epochCache.getTargetAndNextSlot();
36
+
36
37
  const slotNumber = proposal.slotNumber;
37
- if (slotNumber !== currentSlot && slotNumber !== nextSlot) {
38
+ if (slotNumber !== targetSlot && slotNumber !== nextSlot) {
38
39
  // Check if message is for previous slot and within clock tolerance
39
- if (!isWithinClockTolerance(slotNumber, currentSlot, this.epochCache)) {
40
- this.logger.warn(`Penalizing peer for invalid slot number ${slotNumber}`, { currentSlot, nextSlot });
40
+ if (!isWithinClockTolerance(slotNumber, targetSlot, this.epochCache)) {
41
+ this.logger.warn(`Penalizing peer for invalid slot number ${slotNumber}`, { targetSlot, nextSlot });
41
42
  return { result: 'reject', severity: PeerErrorSeverity.HighToleranceError };
42
43
  }
43
44
  this.logger.verbose(`Ignoring proposal for previous slot ${slotNumber} within clock tolerance`);
@@ -75,10 +75,12 @@ This validator is invoked on **every** transaction potentially entering the pend
75
75
  - Startup hydration — revalidating persisted non-mined txs on node restart
76
76
 
77
77
  Runs:
78
- - DoubleSpend, BlockHeader, GasLimits, Timestamp
78
+ - DoubleSpend, BlockHeader, GasLimits, Timestamp, AllowedSetupCalls
79
79
 
80
80
  Operates on `TxMetaData` (pre-built by the pool) rather than full `Tx` objects.
81
81
 
82
+ The `AllowedSetupCallsMetaValidator` checks a precomputed boolean flag (`TxMetaData.allowedSetupCalls`) rather than re-running the full `PhasesTxValidator`. This flag is computed by `createCheckAllowedSetupCalls` when the tx first enters the pool (via `addProtectedTxs` or startup hydration), so the pool migration validator can reject txs with disallowed setup calls without needing the full `Tx` object or its dependencies.
83
+
82
84
  ## Individual Validators
83
85
 
84
86
  | Validator | What it checks | Benchmarked verification duration |
@@ -92,6 +94,7 @@ Operates on `TxMetaData` (pre-built by the pool) rather than full `Tx` objects.
92
94
  | `GasTxValidator` | Gas limits are within bounds (delegates to `GasLimitsValidator`), max fee per gas meets current block fees, and fee payer has sufficient FeeJuice balance | 1.02 ms |
93
95
  | `GasLimitsValidator` | Gas limits are >= fixed minimums and <= AVM max processable L2 gas. Used standalone in pool migration; also called internally by `GasTxValidator` | 3–10 us |
94
96
  | `PhasesTxValidator` | Public function calls in setup phase are on the allow list | 10.12–13.12 us |
97
+ | `AllowedSetupCallsMetaValidator` | Checks the precomputed `allowedSetupCalls` flag on `TxMetaData`. Used in pool migration instead of the full `PhasesTxValidator` | — |
95
98
  | `BlockHeaderTxValidator` | Transaction's anchor block hash exists in the archive tree | 98.88 us |
96
99
  | `TxProofValidator` | Client proof verifies correctly | ~250ms |
97
100
 
@@ -108,6 +111,7 @@ Operates on `TxMetaData` (pre-built by the pool) rather than full `Tx` objects.
108
111
  | Gas (balance + limits) | Stage 1 | Optional* | — | Yes | — |
109
112
  | GasLimits (standalone) | — | — | — | — | Yes |
110
113
  | Phases | Stage 1 | Yes | — | Yes | — |
114
+ | AllowedSetupCalls | — | — | — | — | Yes |
111
115
  | BlockHeader | Stage 1 | Yes | — | Yes | Yes |
112
116
  | Proof | Stage 2 | Optional** | Yes | — | — |
113
117
 
@@ -58,7 +58,7 @@ import { DoubleSpendTxValidator, type NullifierSource } from './double_spend_val
58
58
  import { GasLimitsValidator, GasTxValidator } from './gas_validator.js';
59
59
  import { MetadataTxValidator } from './metadata_validator.js';
60
60
  import { NullifierCache } from './nullifier_cache.js';
61
- import { PhasesTxValidator } from './phases_validator.js';
61
+ import { AllowedSetupCallsMetaValidator, PhasesTxValidator } from './phases_validator.js';
62
62
  import { SizeTxValidator } from './size_validator.js';
63
63
  import { TimestampTxValidator } from './timestamp_validator.js';
64
64
  import { TxPermittedValidator } from './tx_permitted_validator.js';
@@ -436,5 +436,25 @@ export async function createTxValidatorForTransactionsEnteringPendingTxPool(
436
436
  new TimestampTxValidator<TxMetaData>({ timestamp, blockNumber }, bindings),
437
437
  new DoubleSpendTxValidator<TxMetaData>(nullifierSource, bindings),
438
438
  new BlockHeaderTxValidator<TxMetaData>(archiveSource, bindings),
439
+ new AllowedSetupCallsMetaValidator<TxMetaData>(bindings),
439
440
  );
440
441
  }
442
+
443
+ /**
444
+ * Creates a function that checks whether a tx's setup-phase calls are on the allow list.
445
+ *
446
+ * Uses the `PhasesTxValidator` on the full Tx. The result is stored as a boolean
447
+ * flag in `TxMetaData.allowedSetupCalls` at receipt time, so the pending pool
448
+ * migration validator can check it without needing the full Tx or its dependencies.
449
+ */
450
+ export function createCheckAllowedSetupCalls(
451
+ contractDataSource: ContractDataSource,
452
+ setupAllowList: AllowedElement[],
453
+ getTimestamp: () => UInt64,
454
+ ): (tx: Tx) => Promise<boolean> {
455
+ return async (tx: Tx) => {
456
+ const validator = new PhasesTxValidator(contractDataSource, setupAllowList, getTimestamp());
457
+ const result = await validator.validateTx(tx);
458
+ return result.result === 'valid';
459
+ };
460
+ }
@@ -141,3 +141,33 @@ export class PhasesTxValidator implements TxValidator<Tx> {
141
141
  return TX_ERROR_SETUP_FUNCTION_NOT_ALLOWED;
142
142
  }
143
143
  }
144
+
145
+ /** Structural interface for the allowed-setup-calls flag check. */
146
+ export interface HasAllowedSetupCallsData {
147
+ txHash: { toString(): string };
148
+ allowedSetupCalls: boolean;
149
+ }
150
+
151
+ /**
152
+ * Validates that a transaction's setup-phase calls were allowed at receipt time.
153
+ *
154
+ * Checks the precomputed `allowedSetupCalls` flag on TxMetaData. The flag is
155
+ * computed by running the PhasesTxValidator on the full Tx when it first enters
156
+ * the pool. This lightweight validator is used during pending pool migration to
157
+ * reject txs whose setup calls are not on the allow list.
158
+ */
159
+ export class AllowedSetupCallsMetaValidator<T extends HasAllowedSetupCallsData> implements TxValidator<T> {
160
+ #log: Logger;
161
+
162
+ constructor(bindings?: LoggerBindings) {
163
+ this.#log = createLogger('sequencer:tx_validator:tx_phases_meta', bindings);
164
+ }
165
+
166
+ validateTx(tx: T): Promise<TxValidationResult> {
167
+ if (!tx.allowedSetupCalls) {
168
+ this.#log.verbose(`Rejecting tx ${tx.txHash} because its setup calls are not on the allow list`);
169
+ return Promise.resolve({ result: 'invalid', reason: [TX_ERROR_SETUP_FUNCTION_NOT_ALLOWED] });
170
+ }
171
+ return Promise.resolve({ result: 'valid' });
172
+ }
173
+ }
@@ -9,6 +9,14 @@ import { webcrypto } from 'node:crypto';
9
9
  import { compressSync, uncompressSync } from 'snappy';
10
10
  import xxhashFactory from 'xxhash-wasm';
11
11
 
12
+ /** Thrown when a Snappy-compressed response exceeds the allowed decompressed size. */
13
+ export class OversizedSnappyResponseError extends Error {
14
+ constructor(decompressedSize: number, maxSizeKb: number) {
15
+ super(`Decompressed size ${decompressedSize} exceeds maximum allowed size of ${maxSizeKb}kb`);
16
+ this.name = 'OversizedSnappyResponseError';
17
+ }
18
+ }
19
+
12
20
  // Load WASM
13
21
  const xxhash = await xxhashFactory();
14
22
 
@@ -86,7 +94,7 @@ export class SnappyTransform implements DataTransform {
86
94
  const { decompressedSize } = readSnappyPreamble(data);
87
95
  if (decompressedSize > maxSizeKb * 1024) {
88
96
  this.logger.warn(`Decompressed size ${decompressedSize} exceeds maximum allowed size of ${maxSizeKb}kb`);
89
- throw new Error(`Decompressed size ${decompressedSize} exceeds maximum allowed size of ${maxSizeKb}kb`);
97
+ throw new OversizedSnappyResponseError(decompressedSize, maxSizeKb);
90
98
  }
91
99
 
92
100
  return Buffer.from(uncompressSync(data, { asBuffer: true }));
@@ -18,7 +18,6 @@ import {
18
18
  type CheckpointProposalCore,
19
19
  type Gossipable,
20
20
  P2PMessage,
21
- type ValidationResult as P2PValidationResult,
22
21
  PeerErrorSeverity,
23
22
  PeerErrorSeverityByHarshness,
24
23
  TopicType,
@@ -226,7 +225,7 @@ export class LibP2PService extends WithTracer implements P2PService {
226
225
 
227
226
  const proposalValidatorOpts = {
228
227
  txsPermitted: !config.disableTransactions,
229
- maxTxsPerBlock: config.validateMaxTxsPerBlock,
228
+ maxTxsPerBlock: config.validateMaxTxsPerBlock ?? config.validateMaxTxsPerCheckpoint,
230
229
  };
231
230
  this.blockProposalValidator = new BlockProposalValidator(epochCache, proposalValidatorOpts);
232
231
  this.checkpointProposalValidator = new CheckpointProposalValidator(epochCache, proposalValidatorOpts);
@@ -976,6 +975,11 @@ export class LibP2PService extends WithTracer implements P2PService {
976
975
  } else if (wasIgnored) {
977
976
  return { result: TopicValidatorResult.Ignore, obj: tx };
978
977
  } else {
978
+ this.logger.warn(`Gossiped tx ${txHash.toString()} unexpectedly rejected by pool`, {
979
+ source: source.toString(),
980
+ txHash: txHash.toString(),
981
+ });
982
+ this.peerManager.penalizePeer(source, PeerErrorSeverity.HighToleranceError);
979
983
  return { result: TopicValidatorResult.Reject };
980
984
  }
981
985
  };
@@ -1742,31 +1746,6 @@ export class LibP2PService extends WithTracer implements P2PService {
1742
1746
  return PeerErrorSeverity.HighToleranceError;
1743
1747
  }
1744
1748
 
1745
- /**
1746
- * Validate a checkpoint attestation.
1747
- *
1748
- * @param attestation - The checkpoint attestation to validate.
1749
- * @returns True if the checkpoint attestation is valid, false otherwise.
1750
- */
1751
- @trackSpan('Libp2pService.validateCheckpointAttestation', async (_, attestation) => ({
1752
- [Attributes.SLOT_NUMBER]: attestation.payload.header.slotNumber,
1753
- [Attributes.BLOCK_ARCHIVE]: attestation.archive.toString(),
1754
- [Attributes.P2P_ID]: await attestation.p2pMessageLoggingIdentifier().then(i => i.toString()),
1755
- }))
1756
- public async validateCheckpointAttestation(
1757
- peerId: PeerId,
1758
- attestation: CheckpointAttestation,
1759
- ): Promise<P2PValidationResult> {
1760
- const result = await this.checkpointAttestationValidator.validate(attestation);
1761
-
1762
- if (result.result === 'reject') {
1763
- this.logger.warn(`Penalizing peer ${peerId} for checkpoint attestation validation failure`);
1764
- this.peerManager.penalizePeer(peerId, result.severity);
1765
- }
1766
-
1767
- return result;
1768
- }
1769
-
1770
1749
  public getPeerScore(peerId: PeerId): number {
1771
1750
  return this.node.services.pubsub.score.score(peerId.toString());
1772
1751
  }
@@ -32,7 +32,7 @@ import { PeerScoreState, type PeerScoring } from './peer_scoring.js';
32
32
  const MAX_DIAL_ATTEMPTS = 3;
33
33
  const MAX_CACHED_PEERS = 100;
34
34
  const MAX_CACHED_PEER_AGE_MS = 5 * 60 * 1000; // 5 minutes
35
- const FAILED_PEER_BAN_TIME_MS = 5 * 60 * 1000; // 5 minutes timeout after failing MAX_DIAL_ATTEMPTS
35
+ const DEFAULT_FAILED_PEER_BAN_TIME_MS = 5 * 60 * 1000; // 5 minutes timeout after failing MAX_DIAL_ATTEMPTS
36
36
  const GOODBYE_DIAL_TIMEOUT_MS = 1000;
37
37
  const FAILED_AUTH_HANDSHAKE_EXPIRY_MS = 60 * 60 * 1000; // 1 hour
38
38
 
@@ -776,7 +776,8 @@ export class PeerManager implements PeerManagerInterface {
776
776
  // Add to timed out peers
777
777
  this.timedOutPeers.set(id, {
778
778
  peerId: id,
779
- timeoutUntilMs: this.dateProvider.now() + FAILED_PEER_BAN_TIME_MS,
779
+ timeoutUntilMs:
780
+ this.dateProvider.now() + (this.config.peerFailedBanTimeMs ?? DEFAULT_FAILED_PEER_BAN_TIME_MS),
780
781
  });
781
782
  }
782
783
  }