From 09ce87237f54d100ca19038aebf350cbc862c066 Mon Sep 17 00:00:00 2001 From: kchojn Date: Wed, 28 May 2025 16:28:52 +0700 Subject: [PATCH 1/5] feat(finality_based_event_syncing.md): add SIP proposal for transitioning to finality-based event syncing for stronger cryptographic guarantees and reliability in event processing. --- sips/finality_based_event_syncing.md | 198 +++++++++++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 sips/finality_based_event_syncing.md diff --git a/sips/finality_based_event_syncing.md b/sips/finality_based_event_syncing.md new file mode 100644 index 0000000..9f07d19 --- /dev/null +++ b/sips/finality_based_event_syncing.md @@ -0,0 +1,198 @@ +| Author | Title | Category | Status | Date | +|--------|------------------------------|----------|---------------------|------------| +| xxx | Finality-Based Event Syncing | Core | open-for-discussion | 2025-05-27 | + +## Summary + +This SIP proposes transitioning from the current `follow-distance` approach to a `finality-based` approach for syncing +Ethereum events. After a configurable fork epoch, SSV nodes will process events only from blocks confirmed as +`finalized` +by the consensus layer. This transition will provide stronger cryptographic guarantees against most chain +reorganizations, significantly enhancing the reliability of event processing while maintaining a clear path for backward +compatibility during the upgrade. + +## Motivation + +The current event syncing mechanism has critical issues: + +1. **Vulnerability to Reorganizations**: Relying on non-finalized blocks (which are inherently less reliable until + finality) exposes the system to potential state inconsistencies if processed blocks are later reorged out. +2. **False Sync Failures**: The system can incorrectly assume a sync failure and crash when detecting old execution + layer block times, even when this is due to the beacon chain simply not proposing new blocks (e.g., due to network + stalls or low participation). + +These issues compromise SSV's reliability and can cause unnecessary downtime or state divergence between operators. + +## Rationale + +### Current State: Follow Distance + +- Processes blocks N blocks behind head (default: 8) +- Assumes probabilistic finality +- Vulnerable to deep reorganizations + +### Proposed: Finality-Based Syncing + +- Uses Ethereum's finalized blocks (providing cryptographic finality) +- Significantly reduces reorganization risks by relying on cryptographically finalized blocks +- Aligns with Ethereum's security model + +## Specification + +### Fork Mechanism + +Introduce network forks to manage the transition. The node's configuration will include the fork schedule, allowing it +to adapt its behavior based on the current epoch. + +```go +// SSVFork defines a specific network fork and its activation epoch. +type SSVFork struct { + Name string + Epoch phase0.Epoch // Activation epoch for this fork +} + +// Example network configuration including the fork schedule +// (within the existing NetworkConfig or a similar structure) +// Config.Forks: []SSVFork{ +// {Name: "Alan", Epoch: 0}, // Represents the pre-finality logic +// {Name: "FinalityConsensus", Epoch: TBD_PER_NETWORK}, // Activation epoch to be determined per network +// } +``` + +### Behavioral Changes + +**Pre-Fork (Alan)**: + +- Continue using the existing follow-distance mechanism for event syncing. +- Existing behavior remains unchanged. + +**Post-Fork (FinalityConsensus)**: + +- Query finalized blocks directly from the execution layer client using calls `eth_getBlockByNumber("finalized")` +- Process SSV contract events exclusively from these finalized blocks. +- The staleness threshold for determining if the node is lagging behind the chain will need adjustment. For example, + instead of a fixed time (e.g., 5 minutes), it could be based on the number of epochs behind the current finalized + epoch. A proposed value for this, **open for discussion,** is approximately 2-3 epochs. + +### Key Implementation Points + +1. **One-way Transition**: Once the "FinalityConsensus" fork activates for a given epoch, the node will exclusively use + finality-based syncing for events from that epoch onwards. There will be no fallback to the follow-distance mechanism + for post-fork blocks. +2. **Automatic Detection**: Nodes will automatically detect fork activation by comparing the current beacon chain epoch + with the "FinalityConsensus" activation epoch defined in their network configuration. +3. **Health Monitoring**: Health monitoring and sync status metrics will be adapted to reflect the new finality-driven + approach. The acceptable lag behind the finalized head of the chain before considering the node unhealthy or out of + sync will be based on epochs (e.g., the **proposed and discussable** 2-3 epochs) rather than solely on block time. +4. **Client Configuration**: The execution client (`ExecutionClient` and `MultiClient`) will be initialized with a + configuration object that includes details of the fork schedule, specifically the `FinalityConsensusEpoch`, enabling + it to switch its internal logic accordingly. + +## Visual Overview + +The following diagrams illustrate the key concepts of this proposal. + +### 1. Fork State Transition Diagram + +This diagram shows the one-way transition from PreFork (follow-distance) mode to PostFork (finality) mode based on the +beacon chain epoch. + +```mermaid +stateDiagram-v2 + direction LR + FollowDistance --> Finality: Fork Activation + note left of FollowDistance: 96 sec delay
Reorg risk + note right of Finality: 13 min delay
No reorg risk +``` + +### 2. Event Processing Flow Comparison + +This diagram contrasts the event processing flow before and after the fork, highlighting the reorg risk in the current +approach. + +```mermaid +graph TB + subgraph "Proposed" + A2[New Block] --> B2[Check Finality] + B2 --> C2[Wait Finalized] + C2 --> D2[Fetch Events] + D2 --> E2[Safe Process] + end + + subgraph "Current" + A1[New Block] --> B1[Wait 8 Blocks] + B1 --> C1[Fetch Events] + C1 --> D1[Process] + D1 --> E1[RISK: Reorg] + end +``` + +### 3. Event Processing Timeline Comparison + +This Gantt chart visualizes the difference in event processing latency between the pre-fork and post-fork mechanisms. + +```mermaid +gantt + title Event Processing Timeline + dateFormat X + axisFormat %s + + section PreFork + Block Produced: done, pre1, 0, 12 + Follow Distance Wait: active, pre2, 12, 96 + Process Events: crit, pre3, 96, 10 + + section PostFork + Block Produced: done, post1, 0, 12 + Wait for Finality: active, post2, 12, 768 + Process Events: crit, post3, 768, 10 +``` + +## Performance Impact + +- **Event Lag**: The time between an event occurring on-chain and it being processed by the SSV node will likely + increase. Using the current follow distance (e.g., 8 blocks * ~12s/block ≈ 1.6 minutes) versus waiting for finality ( + typically 2 epochs, so ~12.8 minutes) represents a significant change. This is a crucial tradeoff: longer lag for + guaranteed event stability. + +## Backwards Compatibility + +This is a consensus-breaking change that necessitates a coordinated network upgrade: + +- Nodes that are not upgraded before the "FinalityConsensus" fork activation epoch will continue to use the + follow-distance mechanism. +- Such non-upgraded nodes risk processing events from blocks that are subsequently reorganized and not part of the + finalized chain, leading to potential state divergence from upgraded nodes, especially in edge cases involving chain + instability. + +## Security Considerations + +- **Enhanced Security**: Transitioning to cryptographic finality for event processing inherently strengthens the node + against state corruption or inconsistencies caused by execution layer reorganizations. +- **Trust Model**: Reliance shifts more explicitly towards the finality guarantees provided by Ethereum's consensus + layer, which is a core security assumption of the PoS network. +- **Attack Surface**: This change is expected to reduce the attack surface related to manipulating node state through EL + reorgs. + +## Test Scenarios + +1. Verification of smooth fork transition during active syncing and under various network conditions. +2. Node behavior when finalized blocks are temporarily unavailable or significantly delayed from the consensus layer. +3. Performance analysis of event processing lag under normal and stressed network conditions post-fork. +4. Monitoring and alerting functionality for the new finality-based sync status. + +## Migration Guide + +1. **Pre-Fork**: Node operators must update their SSV node software to a version supporting the "FinalityConsensus" fork + well in advance of the announced activation epoch for their respective network. Monitor official announcements for + activation epoch details. +2. **During Fork Activation**: The transition should be automatic once the node's current epoch reaches the " + FinalityConsensus" activation epoch. Operators should monitor node logs for confirmation of the new operational mode. +3. **Post-Fork**: Verify that the node is processing events based on finalized blocks. Adjust any external monitoring or + alerting systems to align with the new finality-based health metrics and expected event lag. + +## Open Questions + +- The exact activation epoch for the "FinalityConsensus" fork needs to be determined. +- What are the optimal and commonly agreed-upon thresholds for health monitoring regarding lag behind the finalized + epoch (currently **proposed for discussion at 2-3 epochs**)? \ No newline at end of file From 66ce8881595e6685788cadd3a46272d86446f8ec Mon Sep 17 00:00:00 2001 From: kchojn Date: Wed, 28 May 2025 16:44:17 +0700 Subject: [PATCH 2/5] docs(finality_based_event_syncing.md): improve clarity and consistency in the document by removing unnecessary details and simplifying descriptions --- sips/finality_based_event_syncing.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/sips/finality_based_event_syncing.md b/sips/finality_based_event_syncing.md index 9f07d19..17d478f 100644 --- a/sips/finality_based_event_syncing.md +++ b/sips/finality_based_event_syncing.md @@ -21,7 +21,7 @@ The current event syncing mechanism has critical issues: layer block times, even when this is due to the beacon chain simply not proposing new blocks (e.g., due to network stalls or low participation). -These issues compromise SSV's reliability and can cause unnecessary downtime or state divergence between operators. +These issues compromise SSV's reliability and can cause state divergence between operators. ## Rationale @@ -33,7 +33,7 @@ These issues compromise SSV's reliability and can cause unnecessary downtime or ### Proposed: Finality-Based Syncing -- Uses Ethereum's finalized blocks (providing cryptographic finality) +- Uses Ethereum's finalized blocks - Significantly reduces reorganization risks by relying on cryptographically finalized blocks - Aligns with Ethereum's security model @@ -94,8 +94,7 @@ The following diagrams illustrate the key concepts of this proposal. ### 1. Fork State Transition Diagram -This diagram shows the one-way transition from PreFork (follow-distance) mode to PostFork (finality) mode based on the -beacon chain epoch. +The one-way transition from PreFork (follow-distance) mode to PostFork (finality) mode based on the beacon chain epoch. ```mermaid stateDiagram-v2 @@ -107,8 +106,7 @@ stateDiagram-v2 ### 2. Event Processing Flow Comparison -This diagram contrasts the event processing flow before and after the fork, highlighting the reorg risk in the current -approach. +The event processing flow before and after the fork. ```mermaid graph TB @@ -129,7 +127,7 @@ graph TB ### 3. Event Processing Timeline Comparison -This Gantt chart visualizes the difference in event processing latency between the pre-fork and post-fork mechanisms. +The difference in event processing latency between the pre-fork and post-fork mechanisms. ```mermaid gantt @@ -157,8 +155,6 @@ gantt ## Backwards Compatibility -This is a consensus-breaking change that necessitates a coordinated network upgrade: - - Nodes that are not upgraded before the "FinalityConsensus" fork activation epoch will continue to use the follow-distance mechanism. - Such non-upgraded nodes risk processing events from blocks that are subsequently reorganized and not part of the @@ -195,4 +191,4 @@ This is a consensus-breaking change that necessitates a coordinated network upgr - The exact activation epoch for the "FinalityConsensus" fork needs to be determined. - What are the optimal and commonly agreed-upon thresholds for health monitoring regarding lag behind the finalized - epoch (currently **proposed for discussion at 2-3 epochs**)? \ No newline at end of file + epoch (currently **proposed for discussion at 2-3 epochs**)? From ce7b79ddde3d0f6528ba6bc3831fd754cbc3be01 Mon Sep 17 00:00:00 2001 From: kchojn Date: Wed, 28 May 2025 20:41:28 +0700 Subject: [PATCH 3/5] docs(finality_based_event_syncing.md): clarify the network-wide fork activation and define specific fork mechanism and activation epochs separately feat(finality_based_event_syncing.md): update behavioral changes to include finality-based syncing and define pre-fork and post-fork behaviors feat(finality_based_event_syncing.md): simplify key implementation points for one-way transition and automatic detection of fork activation --- sips/finality_based_event_syncing.md | 38 ++++++---------------------- 1 file changed, 8 insertions(+), 30 deletions(-) diff --git a/sips/finality_based_event_syncing.md b/sips/finality_based_event_syncing.md index 17d478f..a4af14b 100644 --- a/sips/finality_based_event_syncing.md +++ b/sips/finality_based_event_syncing.md @@ -39,32 +39,16 @@ These issues compromise SSV's reliability and can cause state divergence between ## Specification -### Fork Mechanism - -Introduce network forks to manage the transition. The node's configuration will include the fork schedule, allowing it -to adapt its behavior based on the current epoch. - -```go -// SSVFork defines a specific network fork and its activation epoch. -type SSVFork struct { - Name string - Epoch phase0.Epoch // Activation epoch for this fork -} - -// Example network configuration including the fork schedule -// (within the existing NetworkConfig or a similar structure) -// Config.Forks: []SSVFork{ -// {Name: "Alan", Epoch: 0}, // Represents the pre-finality logic -// {Name: "FinalityConsensus", Epoch: TBD_PER_NETWORK}, // Activation epoch to be determined per network -// } -``` - ### Behavioral Changes +This change will be activated as part of a network-wide fork. The specific fork mechanism and activation epochs will be +defined separately as part of the broader network upgrade. + **Pre-Fork (Alan)**: -- Continue using the existing follow-distance mechanism for event syncing. -- Existing behavior remains unchanged. +- Continue using the existing follow-distance mechanism (N blocks behind head, default N=8) +- Process events from blocks assumed to be probabilistically final +- Existing behavior remains unchanged **Post-Fork (FinalityConsensus)**: @@ -76,17 +60,11 @@ type SSVFork struct { ### Key Implementation Points -1. **One-way Transition**: Once the "FinalityConsensus" fork activates for a given epoch, the node will exclusively use - finality-based syncing for events from that epoch onwards. There will be no fallback to the follow-distance mechanism - for post-fork blocks. -2. **Automatic Detection**: Nodes will automatically detect fork activation by comparing the current beacon chain epoch - with the "FinalityConsensus" activation epoch defined in their network configuration. +1. **One-way Transition**: Once the fork activates, nodes will exclusively use finality-based syncing with no fallback. +2. **Automatic Detection**: Nodes will detect fork activation and transition automatically. 3. **Health Monitoring**: Health monitoring and sync status metrics will be adapted to reflect the new finality-driven approach. The acceptable lag behind the finalized head of the chain before considering the node unhealthy or out of sync will be based on epochs (e.g., the **proposed and discussable** 2-3 epochs) rather than solely on block time. -4. **Client Configuration**: The execution client (`ExecutionClient` and `MultiClient`) will be initialized with a - configuration object that includes details of the fork schedule, specifically the `FinalityConsensusEpoch`, enabling - it to switch its internal logic accordingly. ## Visual Overview From aff56e8a6ad5717e1f3b6503a4ac44db288ae5c0 Mon Sep 17 00:00:00 2001 From: kchojn Date: Wed, 4 Jun 2025 17:45:52 +0700 Subject: [PATCH 4/5] =?UTF-8?q?feat(finality=5Fbased=5Fevent=5Fsyncing.md)?= =?UTF-8?q?:=20update=20staleness=20check=20to=20be=20time-based=20and=20c?= =?UTF-8?q?omputed=20as=20`finalized=5Fblock.timestamp=20-=20processed=5Fb?= =?UTF-8?q?lock.timestamp`=20for=20improved=20accuracy=20feat(finality=5Fb?= =?UTF-8?q?ased=5Fevent=5Fsyncing.md):=20adjust=20event=20processing=20to?= =?UTF-8?q?=20occur=20only=20when=20latency=20is=20less=20than=20or=20equa?= =?UTF-8?q?l=20to=20staleness=20threshold=20feat(finality=5Fbased=5Fevent?= =?UTF-8?q?=5Fsyncing.md):=20redefine=20node=20health=20as=20`finalized=5F?= =?UTF-8?q?timestamp=20-=20processed=5Ftimestamp=20=E2=89=A4=20staleness?= =?UTF-8?q?=5Fthreshold`=20for=20clarity=20and=20consistency?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- sips/finality_based_event_syncing.md | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/sips/finality_based_event_syncing.md b/sips/finality_based_event_syncing.md index a4af14b..b0a231a 100644 --- a/sips/finality_based_event_syncing.md +++ b/sips/finality_based_event_syncing.md @@ -54,17 +54,17 @@ defined separately as part of the broader network upgrade. - Query finalized blocks directly from the execution layer client using calls `eth_getBlockByNumber("finalized")` - Process SSV contract events exclusively from these finalized blocks. -- The staleness threshold for determining if the node is lagging behind the chain will need adjustment. For example, - instead of a fixed time (e.g., 5 minutes), it could be based on the number of epochs behind the current finalized - epoch. A proposed value for this, **open for discussion,** is approximately 2-3 epochs. +- Staleness check stays time-based (default ≈ 5 minutes) but is now computed as + `finalized_block.timestamp − processed_block.timestamp` rather than comparing either timestamp to wall-clock time. +- Events are processed only when this latency (`finalized_block.timestamp − processed_block.timestamp`) is ≤ + `staleness_threshold`. ### Key Implementation Points 1. **One-way Transition**: Once the fork activates, nodes will exclusively use finality-based syncing with no fallback. 2. **Automatic Detection**: Nodes will detect fork activation and transition automatically. -3. **Health Monitoring**: Health monitoring and sync status metrics will be adapted to reflect the new finality-driven - approach. The acceptable lag behind the finalized head of the chain before considering the node unhealthy or out of - sync will be based on epochs (e.g., the **proposed and discussable** 2-3 epochs) rather than solely on block time. +3. **Health Monitoring**: A node is considered healthy when + `finalized_timestamp − processed_timestamp ≤ staleness_threshold`. ## Visual Overview @@ -154,6 +154,10 @@ gantt 2. Node behavior when finalized blocks are temporarily unavailable or significantly delayed from the consensus layer. 3. Performance analysis of event processing lag under normal and stressed network conditions post-fork. 4. Monitoring and alerting functionality for the new finality-based sync status. +5. **Finalization Delay Resilience**: Simulate a beacon-chain stall (no new finalized blocks for several epochs). Verify + the node remains healthy as long as its `processed_block.timestamp` approaches the stagnant + `finalized_block.timestamp`, keeping their difference (latency, i.e., + `finalized_block.timestamp - processed_block.timestamp`) within the configured time-based `staleness_threshold`. ## Migration Guide @@ -164,9 +168,3 @@ gantt FinalityConsensus" activation epoch. Operators should monitor node logs for confirmation of the new operational mode. 3. **Post-Fork**: Verify that the node is processing events based on finalized blocks. Adjust any external monitoring or alerting systems to align with the new finality-based health metrics and expected event lag. - -## Open Questions - -- The exact activation epoch for the "FinalityConsensus" fork needs to be determined. -- What are the optimal and commonly agreed-upon thresholds for health monitoring regarding lag behind the finalized - epoch (currently **proposed for discussion at 2-3 epochs**)? From 0c23bca56dfd93c57fbea564467c510fe2f03527 Mon Sep 17 00:00:00 2001 From: Karol Chojnowski Date: Mon, 14 Jul 2025 12:25:46 +0700 Subject: [PATCH 5/5] docs(finality_based_event_syncing): update documentation to clarify staleness check and health monitoring criteria for finality-based syncing --- sips/finality_based_event_syncing.md | 18 ++++-------------- 1 file changed, 4 insertions(+), 14 deletions(-) diff --git a/sips/finality_based_event_syncing.md b/sips/finality_based_event_syncing.md index b0a231a..b2676a6 100644 --- a/sips/finality_based_event_syncing.md +++ b/sips/finality_based_event_syncing.md @@ -54,17 +54,11 @@ defined separately as part of the broader network upgrade. - Query finalized blocks directly from the execution layer client using calls `eth_getBlockByNumber("finalized")` - Process SSV contract events exclusively from these finalized blocks. -- Staleness check stays time-based (default ≈ 5 minutes) but is now computed as - `finalized_block.timestamp − processed_block.timestamp` rather than comparing either timestamp to wall-clock time. -- Events are processed only when this latency (`finalized_block.timestamp − processed_block.timestamp`) is ≤ - `staleness_threshold`. ### Key Implementation Points 1. **One-way Transition**: Once the fork activates, nodes will exclusively use finality-based syncing with no fallback. 2. **Automatic Detection**: Nodes will detect fork activation and transition automatically. -3. **Health Monitoring**: A node is considered healthy when - `finalized_timestamp − processed_timestamp ≤ staleness_threshold`. ## Visual Overview @@ -154,17 +148,13 @@ gantt 2. Node behavior when finalized blocks are temporarily unavailable or significantly delayed from the consensus layer. 3. Performance analysis of event processing lag under normal and stressed network conditions post-fork. 4. Monitoring and alerting functionality for the new finality-based sync status. -5. **Finalization Delay Resilience**: Simulate a beacon-chain stall (no new finalized blocks for several epochs). Verify - the node remains healthy as long as its `processed_block.timestamp` approaches the stagnant - `finalized_block.timestamp`, keeping their difference (latency, i.e., - `finalized_block.timestamp - processed_block.timestamp`) within the configured time-based `staleness_threshold`. ## Migration Guide 1. **Pre-Fork**: Node operators must update their SSV node software to a version supporting the "FinalityConsensus" fork well in advance of the announced activation epoch for their respective network. Monitor official announcements for activation epoch details. -2. **During Fork Activation**: The transition should be automatic once the node's current epoch reaches the " - FinalityConsensus" activation epoch. Operators should monitor node logs for confirmation of the new operational mode. -3. **Post-Fork**: Verify that the node is processing events based on finalized blocks. Adjust any external monitoring or - alerting systems to align with the new finality-based health metrics and expected event lag. +2. **During Fork Activation**: The transition should be automatic once the node's current epoch reaches the +"FinalityConsensus" activation epoch. Operators should monitor node logs for confirmation of the new operational mode. +3. **Post-Fork**: Verify that the node is processing events based on finalized blocks. Node operators may implement + their own monitoring solutions as needed.