fix: paid/unpaid classification for invalid batch transitions

packages/rs-dpp/src/validation/validation_result/flatten/mod.rs

@@ -0,0 +1,2 @@
+pub(super) mod v0;
+pub(super) mod v1;

packages/rs-dpp/src/validation/validation_result/flatten/v0/mod.rs

@@ -0,0 +1,75 @@
+//! v0 of [`ConsensusValidationResult::flatten`].
+//!
+//! Legacy semantics: always returns `data: Some(Vec<...>)`, including
+//! `Some(empty_vec)` when no input contributed any data.
+//!
+//! Preserved for `PROTOCOL_VERSION_11` and below — the
+//! `Some(empty_vec)`-on-no-data behavior is part of the existing chain
+//! history, and changing it would be a consensus-breaking change for
+//! already-finalized blocks. New code should let the facade dispatch to v1.
+//!
+//! See issue #2867 for context.
+//!
+//! [`ConsensusValidationResult::flatten`]: crate::validation::ConsensusValidationResult::flatten
+
+use crate::validation::ValidationResult;
+use std::fmt::Debug;
+
+pub(in crate::validation::validation_result) fn flatten_v0<TData, E, I>(
+    items: I,
+) -> ValidationResult<Vec<TData>, E>
+where
+    TData: Clone,
+    E: Debug,
+    I: IntoIterator<Item = ValidationResult<Vec<TData>, E>>,
+{
+    let mut aggregate_errors = vec![];
+    let mut aggregate_data = vec![];
+    items.into_iter().for_each(|single_validation_result| {
+        let ValidationResult { mut errors, data } = single_validation_result;
+        aggregate_errors.append(&mut errors);
+        if let Some(mut data) = data {
+            aggregate_data.append(&mut data);
+        }
+    });
+    ValidationResult::new_with_data_and_errors(aggregate_data, aggregate_errors)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn merges_data_and_errors() {
+        let r1: ValidationResult<Vec<i32>, String> = ValidationResult::new_with_data(vec![1, 2]);
+        let r2: ValidationResult<Vec<i32>, String> =
+            ValidationResult::new_with_data_and_errors(vec![3], vec!["e".to_string()]);
+        let r3: ValidationResult<Vec<i32>, String> =
+            ValidationResult::new_with_error("e2".to_string());
+
+        let flat = flatten_v0(vec![r1, r2, r3]);
+        assert_eq!(flat.data, Some(vec![1, 2, 3]));
+        assert_eq!(flat.errors, vec!["e".to_string(), "e2".to_string()]);
+    }
+
+    #[test]
+    fn empty_input_returns_some_empty() {
+        // Legacy v11 behavior: Some(empty_vec), not None.
+        let flat: ValidationResult<Vec<i32>, String> =
+            flatten_v0(std::iter::empty::<ValidationResult<Vec<i32>, String>>());
+        assert_eq!(flat.data, Some(vec![]));
+        assert!(flat.errors.is_empty());
+    }
+
+    #[test]
+    fn all_inputs_no_data_returns_some_empty() {
+        let r1: ValidationResult<Vec<i32>, String> =
+            ValidationResult::new_with_error("e1".to_string());
+        let r2: ValidationResult<Vec<i32>, String> =
+            ValidationResult::new_with_error("e2".to_string());
+
+        let flat = flatten_v0(vec![r1, r2]);
+        assert_eq!(flat.data, Some(vec![]));
+        assert_eq!(flat.errors, vec!["e1".to_string(), "e2".to_string()]);
+    }
+}

packages/rs-dpp/src/validation/validation_result/flatten/v1/mod.rs

@@ -0,0 +1,121 @@
+//! v1 of [`ConsensusValidationResult::flatten`].
+//!
+//! Canonical semantics: returns `data: None` when no input contributed any
+//! data (i.e. every input was either `data: None` or `data: Some(empty_vec)`),
+//! and `data: Some(merged_vec)` when at least one input contributed
+//! non-empty data.
+//!
+//! This honors the invariant `data.is_none() ⇔ no work done`, which
+//! downstream code (e.g. `process_validation_result_v0:241`) relies on to
+//! choose between `PaidConsensusError` and `UnpaidConsensusError`.
+//!
+//! # Caller-intent ambiguity
+//!
+//! `flatten_v1` keys on `aggregate_data.is_empty()` to decide between
+//! `data: None` and `data: Some(_)`. This collapses two distinct
+//! caller-side intents into the same output:
+//!
+//! * **Truly no work**: every input had `data: None`.
+//! * **Validated but produced no output**: every input had
+//!   `data: Some(empty_vec)`.
+//!
+//! v1 cannot distinguish those two cases at the aggregate level — both
+//! end up as `data: None` and are routed to `UnpaidConsensusError`
+//! downstream. For the documents-batch path under PROTOCOL_VERSION_12 this
+//! is safe: every per-transition handler emits at least one action on
+//! success and a bump action on failure, so no caller produces
+//! `Some(empty_vec)`. A future caller that needs "validated, but no
+//! actions to apply" must signal that with at least one non-empty entry,
+//! not with `Some(empty_vec)`.
+//!
+//! See issue #2867 for context.
+//!
+//! [`ConsensusValidationResult::flatten`]: crate::validation::ConsensusValidationResult::flatten
+
+use crate::validation::ValidationResult;
+use std::fmt::Debug;
+
+pub(in crate::validation::validation_result) fn flatten_v1<TData, E, I>(
+    items: I,
+) -> ValidationResult<Vec<TData>, E>
+where
+    TData: Clone,
+    E: Debug,
+    I: IntoIterator<Item = ValidationResult<Vec<TData>, E>>,
+{
+    let mut aggregate_errors = vec![];
+    let mut aggregate_data = vec![];
+    items.into_iter().for_each(|single_validation_result| {
+        let ValidationResult { mut errors, data } = single_validation_result;
+        aggregate_errors.append(&mut errors);
+        if let Some(mut data) = data {
+            aggregate_data.append(&mut data);
+        }
+    });
+    if aggregate_data.is_empty() {
+        ValidationResult::new_with_errors(aggregate_errors)
+    } else {
+        ValidationResult::new_with_data_and_errors(aggregate_data, aggregate_errors)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn merges_non_empty_data() {
+        let r1: ValidationResult<Vec<i32>, String> = ValidationResult::new_with_data(vec![1, 2]);
+        let r2: ValidationResult<Vec<i32>, String> =
+            ValidationResult::new_with_data_and_errors(vec![3], vec!["e".to_string()]);
+        let r3: ValidationResult<Vec<i32>, String> =
+            ValidationResult::new_with_error("e2".to_string());
+
+        let flat = flatten_v1(vec![r1, r2, r3]);
+        assert_eq!(flat.data, Some(vec![1, 2, 3]));
+        assert_eq!(flat.errors, vec!["e".to_string(), "e2".to_string()]);
+    }
+
+    #[test]
+    fn empty_input_returns_none() {
+        let flat: ValidationResult<Vec<i32>, String> =
+            flatten_v1(std::iter::empty::<ValidationResult<Vec<i32>, String>>());
+        assert_eq!(flat.data, None);
+        assert!(flat.errors.is_empty());
+    }
+
+    #[test]
+    fn all_inputs_no_data_returns_none() {
+        // Downstream code (process_validation_result_v0:241) keys on
+        // data.is_none() to route to UnpaidConsensusError.
+        let r1: ValidationResult<Vec<i32>, String> =
+            ValidationResult::new_with_error("e1".to_string());
+        let r2: ValidationResult<Vec<i32>, String> =
+            ValidationResult::new_with_error("e2".to_string());
+
+        let flat = flatten_v1(vec![r1, r2]);
+        assert!(flat.data.is_none());
+        assert_eq!(flat.errors, vec!["e1".to_string(), "e2".to_string()]);
+    }
+
+    #[test]
+    fn some_empty_some_non_empty_returns_some() {
+        let r1: ValidationResult<Vec<i32>, String> = ValidationResult::new_with_data(vec![]);
+        let r2: ValidationResult<Vec<i32>, String> = ValidationResult::new_with_data(vec![42]);
+
+        let flat = flatten_v1(vec![r1, r2]);
+        assert_eq!(flat.data, Some(vec![42]));
+        assert!(flat.errors.is_empty());
+    }
+
+    #[test]
+    fn all_some_empty_returns_none() {
+        // All inputs had data:Some(empty_vec). The aggregate Vec is empty → data:None.
+        let r1: ValidationResult<Vec<i32>, String> = ValidationResult::new_with_data(vec![]);
+        let r2: ValidationResult<Vec<i32>, String> = ValidationResult::new_with_data(vec![]);
+
+        let flat = flatten_v1(vec![r1, r2]);
+        assert!(flat.data.is_none());
+        assert!(flat.errors.is_empty());
+    }
+}

packages/rs-dpp/src/validation/validation_result/merge_many/mod.rs

@@ -0,0 +1,2 @@
+pub(super) mod v0;
+pub(super) mod v1;

packages/rs-dpp/src/validation/validation_result/merge_many/v0/mod.rs

@@ -0,0 +1,71 @@
+//! v0 of [`ValidationResult::merge_many`].
+//!
+//! Legacy semantics: always returns `data: Some(Vec<...>)`, including
+//! `Some(empty_vec)` when no input had `data: Some(_)`.
+//!
+//! Preserved for `PROTOCOL_VERSION_11` and below — the
+//! `Some(empty_vec)`-on-no-data behavior is part of the existing chain
+//! history, and changing it would be a consensus-breaking change for
+//! already-finalized blocks. New code should let the facade dispatch to v1.
+//!
+//! See issue #2867 for context.
+//!
+//! [`ValidationResult::merge_many`]: crate::validation::ValidationResult::merge_many
+
+use crate::validation::ValidationResult;
+use std::fmt::Debug;
+
+pub(in crate::validation::validation_result) fn merge_many_v0<TData, E, I>(
+    items: I,
+) -> ValidationResult<Vec<TData>, E>
+where
+    TData: Clone,
+    E: Debug,
+    I: IntoIterator<Item = ValidationResult<TData, E>>,
+{
+    let mut aggregate_errors = vec![];
+    let mut aggregate_data = vec![];
+    items.into_iter().for_each(|single_validation_result| {
+        let ValidationResult { mut errors, data } = single_validation_result;
+        aggregate_errors.append(&mut errors);
+        if let Some(data) = data {
+            aggregate_data.push(data);
+        }
+    });
+    ValidationResult::new_with_data_and_errors(aggregate_data, aggregate_errors)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn collects_data_into_vec() {
+        let r1: ValidationResult<i32, String> = ValidationResult::new_with_data(1);
+        let r2: ValidationResult<i32, String> = ValidationResult::new_with_data(2);
+        let r3: ValidationResult<i32, String> = ValidationResult::new_with_error("e".to_string());
+
+        let merged = merge_many_v0(vec![r1, r2, r3]);
+        assert_eq!(merged.data, Some(vec![1, 2]));
+        assert_eq!(merged.errors, vec!["e".to_string()]);
+    }
+
+    #[test]
+    fn empty_input_returns_some_empty() {
+        // Legacy v11 behavior: Some(empty_vec), not None.
+        let merged: ValidationResult<Vec<i32>, String> =
+            merge_many_v0(std::iter::empty::<ValidationResult<i32, String>>());
+        assert_eq!(merged.data, Some(vec![]));
+        assert!(merged.errors.is_empty());
+    }
+
+    #[test]
+    fn all_inputs_no_data_returns_some_empty() {
+        let r1: ValidationResult<i32, String> = ValidationResult::new_with_error("e1".to_string());
+        let r2: ValidationResult<i32, String> = ValidationResult::new_with_error("e2".to_string());
+
+        let merged = merge_many_v0(vec![r1, r2]);
+        assert_eq!(merged.data, Some(vec![]));
+        assert_eq!(merged.errors, vec!["e1".to_string(), "e2".to_string()]);
+    }
+}

packages/rs-dpp/src/validation/validation_result/merge_many/v1/mod.rs

@@ -0,0 +1,95 @@
+//! v1 of [`ValidationResult::merge_many`].
+//!
+//! Canonical semantics: returns `data: None` when no input had
+//! `data: Some(_)`, and `data: Some(Vec<TData>)` when at least one input
+//! contributed data.
+//!
+//! This honors the invariant `data.is_none() ⇔ no work done`, which
+//! downstream code (e.g. `process_validation_result_v0:241`) relies on to
+//! choose between `PaidConsensusError` and `UnpaidConsensusError`.
+//!
+//! # Caller-intent ambiguity
+//!
+//! `merge_many_v1` keys on `aggregate_data.is_empty()` to decide between
+//! `data: None` and `data: Some(_)`. Every `Some(_)` input contributes one
+//! element to `aggregate_data`, so the only way to get `data: None` is to
+//! have zero inputs with `data: Some(_)`. There is no `Some(empty_vec)`
+//! input shape at this layer (the per-item `data` is `TData`, not
+//! `Vec<TData>`), so the collapse hazard described for `flatten_v1`
+//! doesn't apply here. The dispatcher facade ([`ValidationResult::merge_many`])
+//! shares the limitation note for symmetry.
+//!
+//! See issue #2867 for context.
+//!
+//! [`ValidationResult::merge_many`]: crate::validation::ValidationResult::merge_many
+
+use crate::validation::ValidationResult;
+use std::fmt::Debug;
+
+pub(in crate::validation::validation_result) fn merge_many_v1<TData, E, I>(
+    items: I,
+) -> ValidationResult<Vec<TData>, E>
+where
+    TData: Clone,
+    E: Debug,
+    I: IntoIterator<Item = ValidationResult<TData, E>>,
+{
+    let mut aggregate_errors = vec![];
+    let mut aggregate_data = vec![];
+    items.into_iter().for_each(|single_validation_result| {
+        let ValidationResult { mut errors, data } = single_validation_result;
+        aggregate_errors.append(&mut errors);
+        if let Some(data) = data {
+            aggregate_data.push(data);
+        }
+    });
+    if aggregate_data.is_empty() {
+        ValidationResult::new_with_errors(aggregate_errors)
+    } else {
+        ValidationResult::new_with_data_and_errors(aggregate_data, aggregate_errors)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn collects_non_empty_data() {
+        let r1: ValidationResult<i32, String> = ValidationResult::new_with_data(1);
+        let r2: ValidationResult<i32, String> = ValidationResult::new_with_data(2);
+        let r3: ValidationResult<i32, String> = ValidationResult::new_with_error("e".to_string());
+
+        let merged = merge_many_v1(vec![r1, r2, r3]);
+        assert_eq!(merged.data, Some(vec![1, 2]));
+        assert_eq!(merged.errors, vec!["e".to_string()]);
+    }
+
+    #[test]
+    fn empty_input_returns_none() {
+        let merged: ValidationResult<Vec<i32>, String> =
+            merge_many_v1(std::iter::empty::<ValidationResult<i32, String>>());
+        assert!(merged.data.is_none());
+        assert!(merged.errors.is_empty());
+    }
+
+    #[test]
+    fn all_inputs_no_data_returns_none() {
+        let r1: ValidationResult<i32, String> = ValidationResult::new_with_error("e1".to_string());
+        let r2: ValidationResult<i32, String> = ValidationResult::new_with_error("e2".to_string());
+
+        let merged = merge_many_v1(vec![r1, r2]);
+        assert!(merged.data.is_none());
+        assert_eq!(merged.errors, vec!["e1".to_string(), "e2".to_string()]);
+    }
+
+    #[test]
+    fn some_data_returns_some() {
+        let r1: ValidationResult<i32, String> = ValidationResult::new_with_error("e1".to_string());
+        let r2: ValidationResult<i32, String> = ValidationResult::new_with_data(7);
+
+        let merged = merge_many_v1(vec![r1, r2]);
+        assert_eq!(merged.data, Some(vec![7]));
+        assert_eq!(merged.errors, vec!["e1".to_string()]);
+    }
+}