eth-state-diff 0.2.2

Fork-aware, domain-specific delta encoding for Ethereum consensus-layer state.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

//! Delta encoding for the Eth1 data vote list.
//!
//! Eth1 data votes accumulate during an Eth1 voting period and are reset when
//! the voting period changes. This module represents those transitions using
//! either an append-only update or a complete replacement.
//!
//! The delta operates directly on the serialized SSZ representation and does
//! not deserialize individual Eth1 data values.

use crate::types::{ArchivedEth1DataVotesDiff, Eth1DataVotesDiff};

/// Computes a delta between two serialized Eth1 data vote lists.
///
/// If the target preserves the complete serialized base list, only the bytes
/// appended to the base are stored in [`Eth1DataVotesDiff::Append`].
/// Otherwise, the complete target list is stored in
/// [`Eth1DataVotesDiff::ResetAndAppend`].
///
/// This covers both accumulation of votes during an Eth1 voting period and
/// replacement of the vote list when the voting period changes.
///
/// This function operates directly on serialized SSZ bytes and does not
/// deserialize individual votes.
///
/// # Arguments
///
/// * `base` - Serialized SSZ representation of the current vote list.
/// * `target` - Serialized SSZ representation of the target vote list.
///
/// # Returns
///
/// A delta representing the transition from `base` to `target`.
///
/// # Complexity
///
/// O(n), where *n* is the length of `base`, for the prefix comparison.
/// Additional space is proportional to the selected delta payload.
///
/// # Example
///
/// ```
/// use eth_state_diff::eth1_data_votes::diff_eth1_votes;
/// use eth_state_diff::types::Eth1DataVotesDiff;
///
/// let base = b"AAAA";
/// let target = b"AAAABBBB";
///
/// let delta = diff_eth1_votes(base, target);
///
/// assert_eq!(delta, Eth1DataVotesDiff::Append(b"BBBB".to_vec()));
/// ```
pub fn diff_eth1_votes(base: &[u8], target: &[u8]) -> Eth1DataVotesDiff {
    if let Some(appended_votes) = target
        .get(base.len()..)
        .filter(|_| target.starts_with(base))
    {
        Eth1DataVotesDiff::Append(appended_votes.to_vec())
    } else {
        Eth1DataVotesDiff::ResetAndAppend(target.to_vec())
    }
}

/// Applies an Eth1 data vote delta to a serialized vote list in place.
///
/// [`Eth1DataVotesDiff::Append`] preserves the existing bytes and appends the
/// delta payload.
///
/// [`Eth1DataVotesDiff::ResetAndAppend`] clears the existing vote list before
/// writing the replacement payload.
///
/// The delta is assumed to have been produced for the current base state.
/// This function does not validate that an append delta's base bytes match
/// the state being modified.
///
/// # Arguments
///
/// * `base` - Serialized SSZ vote list to modify.
/// * `delta` - Archived delta to apply.
///
/// # Complexity
///
/// - [`Eth1DataVotesDiff::Append`]: O(k), where *k* is the number of appended
///   bytes.
/// - [`Eth1DataVotesDiff::ResetAndAppend`]: O(k), where *k* is the size of the
///   replacement payload.
///
/// # Example
///
/// ```
/// use eth_state_diff::eth1_data_votes::{apply_eth1_votes, diff_eth1_votes};
/// use eth_state_diff::types::Eth1DataVotesDiff;
///
/// let mut base = b"AAAA".to_vec();
/// let delta = diff_eth1_votes(&base, b"AAAABBBB");
///
/// // The delta is generated locally, so its contents can be applied directly.
/// match delta {
///     Eth1DataVotesDiff::Append(appended_votes) => {
///         base.extend_from_slice(&appended_votes);
///     }
///     Eth1DataVotesDiff::ResetAndAppend(replacement) => {
///         base.clear();
///         base.extend_from_slice(&replacement);
///     }
/// }
///
/// assert_eq!(base, b"AAAABBBB");
/// ```
///
/// [`Eth1DataVotesDiff`]: crate::types::Eth1DataVotesDiff
pub fn apply_eth1_votes(base: &mut Vec<u8>, delta: &ArchivedEth1DataVotesDiff) {
    match delta {
        ArchivedEth1DataVotesDiff::Append(appended_votes) => {
            base.extend_from_slice(appended_votes.as_slice());
        }
        ArchivedEth1DataVotesDiff::ResetAndAppend(replacement) => {
            base.clear();
            base.extend_from_slice(replacement.as_slice());
        }
    }
}