feat(sdk): send, scan and read DashPay private contact requests

packages/rs-context-provider/src/provider.rs

@@ -60,6 +60,12 @@ pub trait ContextProvider: Send + Sync {
     /// Providers that maintain a writable known-contracts cache (e.g. the
     /// mobile `TrustedHttpContextProvider`) override this; the default is a
     /// no-op for providers that fetch on demand or don't cache.
+    ///
+    /// A provider that overrides it keeps a held contract of a higher version
+    /// than `contract`, deciding atomically under its own cache lock: a
+    /// registration that waited on a fetch must not replace a newer contract
+    /// another operation registered meanwhile, which a proof of that newer
+    /// version would then fail to verify against.
     fn register_data_contract(&self, _contract: Arc<DataContract>) {}
 
     /// Fetches the token configuration for a specified token ID.

packages/rs-dpp/src/identity/identity_public_key/contract_bounds/mod.rs

@@ -82,6 +82,21 @@ pub enum BatchedTransitionBoundsCheck {
     },
 }
 
+/// Whether a key carrying contract bounds may be used with the documents of one document type.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DocumentTypeBoundsCheck {
+    /// The document type lies inside the bounds.
+    Allowed,
+    /// The document type lies outside the bounds.
+    Denied,
+    /// The bounds name a contract group. The type lies inside them when its contract holds it,
+    /// or is a whole-contract member, of the group: only state can answer that.
+    RequiresContractGroupMembership {
+        /// The group the bounds name.
+        contract_group_id: Identifier,
+    },
+}
+
 impl ContractBounds {
     /// Creates a new contract bounds for the key
     pub fn new_from_type(
@@ -175,6 +190,33 @@ impl ContractBounds {
         }
     }
 
+    /// Whether a key carrying these bounds may be used with the documents of the type
+    /// `document_type_name` of the contract `contract_id`. Clients scope their ENCRYPTION and
+    /// DECRYPTION keys with this, as the bounds ask. A contract group bound is answered by the
+    /// group's members, which only state holds: a client that does not read them treats the
+    /// type as outside the bounds.
+    pub fn check_document_type(
+        &self,
+        contract_id: &Identifier,
+        document_type_name: &str,
+    ) -> DocumentTypeBoundsCheck {
+        match self {
+            SingleContract { id } if id == contract_id => DocumentTypeBoundsCheck::Allowed,
+            SingleContractDocumentType {
+                id,
+                document_type_name: bound_document_type_name,
+            } if id == contract_id && bound_document_type_name == document_type_name => {
+                DocumentTypeBoundsCheck::Allowed
+            }
+            SingleContract { .. } | SingleContractDocumentType { .. } => {
+                DocumentTypeBoundsCheck::Denied
+            }
+            ContractGroup { id } => DocumentTypeBoundsCheck::RequiresContractGroupMembership {
+                contract_group_id: *id,
+            },
+        }
+    }
+
     /// What authorizing `transition` with a key carrying these bounds needs. Consensus uses this
     /// to authorize a batch signed by a contract-bound AUTHENTICATION key. Token operations are
     /// contract-wide, so a document-type bound never covers them. A contract group bound is
@@ -376,6 +418,85 @@ mod core_tests {
     }
 }
 
+#[cfg(test)]
+mod document_type_tests {
+    use super::{ContractBounds, DocumentTypeBoundsCheck};
+    use crate::identifier::Identifier;
+
+    #[test]
+    fn should_allow_only_the_bound_contract_or_document_type() {
+        let contract_id = Identifier::from([1; 32]);
+        let other_id = Identifier::from([2; 32]);
+        let contract = ContractBounds::SingleContract { id: contract_id };
+        let document_type = ContractBounds::SingleContractDocumentType {
+            id: contract_id,
+            document_type_name: "note".to_string(),
+        };
+        for (case, bounds, checked_contract, checked_type, expected) in [
+            (
+                "a contract bound, a type of it",
+                &contract,
+                contract_id,
+                "note",
+                DocumentTypeBoundsCheck::Allowed,
+            ),
+            (
+                "a contract bound, another type of it",
+                &contract,
+                contract_id,
+                "other",
+                DocumentTypeBoundsCheck::Allowed,
+            ),
+            (
+                "a contract bound, another contract",
+                &contract,
+                other_id,
+                "note",
+                DocumentTypeBoundsCheck::Denied,
+            ),
+            (
+                "a type bound, that type",
+                &document_type,
+                contract_id,
+                "note",
+                DocumentTypeBoundsCheck::Allowed,
+            ),
+            (
+                "a type bound, another type",
+                &document_type,
+                contract_id,
+                "other",
+                DocumentTypeBoundsCheck::Denied,
+            ),
+            (
+                "a type bound, that type's name in another contract",
+                &document_type,
+                other_id,
+                "note",
+                DocumentTypeBoundsCheck::Denied,
+            ),
+        ] {
+            assert_eq!(
+                bounds.check_document_type(&checked_contract, checked_type),
+                expected,
+                "{case}"
+            );
+        }
+    }
+
+    #[test]
+    fn should_leave_a_contract_group_bound_to_its_members() {
+        let contract_group_id = Identifier::from([3; 32]);
+        let bounds = ContractBounds::ContractGroup {
+            id: contract_group_id,
+        };
+        assert_eq!(
+            bounds.check_document_type(&Identifier::from([1; 32]), "note"),
+            DocumentTypeBoundsCheck::RequiresContractGroupMembership { contract_group_id }
+        );
+    }
+}
+
 #[cfg(all(test, feature = "json-conversion"))]
 mod tests {
     use super::*;

packages/rs-dpp/src/identity/identity_public_key/security_level.rs

@@ -105,6 +105,21 @@ impl SecurityLevel {
     pub fn stronger_or_equal_security_than(self: SecurityLevel, rhs: SecurityLevel) -> bool {
         (self as u8) <= (rhs as u8)
     }
+
+    /// The security levels a key may sign a document at when the document's type requires
+    /// `self` (its `security_level_requirement`): `MASTER` alone when the requirement is
+    /// `MASTER`, otherwise every level from `CRITICAL` to the requirement, strongest first. A
+    /// batch takes the levels of the strongest requirement among its documents
+    /// (`DocumentsBatchTransitionMethodsV0::combined_security_level_requirement`).
+    pub fn document_signing_levels(self) -> Vec<SecurityLevel> {
+        if self == Self::MASTER {
+            return vec![Self::MASTER];
+        }
+        Self::full_range()
+            .into_iter()
+            .filter(|level| *level != Self::MASTER && (*level as u8) <= (self as u8))
+            .collect()
+    }
 }
 
 impl std::fmt::Display for SecurityLevel {
@@ -117,6 +132,34 @@ impl std::fmt::Display for SecurityLevel {
 mod tests {
     use super::*;
 
+    /// Each requirement admits `MASTER` alone, or `CRITICAL` to itself, as a document batch
+    /// has always computed it.
+    #[test]
+    fn should_give_the_levels_each_document_requirement_admits() {
+        use SecurityLevel::*;
+        assert_eq!(MASTER.document_signing_levels(), vec![MASTER]);
+        assert_eq!(CRITICAL.document_signing_levels(), vec![CRITICAL]);
+        assert_eq!(HIGH.document_signing_levels(), vec![CRITICAL, HIGH]);
+        assert_eq!(
+            MEDIUM.document_signing_levels(),
+            vec![CRITICAL, HIGH, MEDIUM]
+        );
+        for requirement in SecurityLevel::full_range() {
+            let range: Vec<SecurityLevel> = if requirement == MASTER {
+                vec![MASTER]
+            } else {
+                (CRITICAL as u8..=requirement as u8)
+                    .map(|level| SecurityLevel::try_from(level).expect("a security level"))
+                    .collect()
+            };
+            assert_eq!(
+                requirement.document_signing_levels(),
+                range,
+                "{requirement}"
+            );
+        }
+    }
+
     // -- TryFrom<u8> valid --
     #[test]
     fn test_security_level_try_from_u8_all_valid() {

packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/methods/v0/mod.rs

@@ -19,7 +19,6 @@ use crate::ProtocolError;
 use platform_value::Identifier;
 #[cfg(feature = "state-transition-signing")]
 use platform_version::version::PlatformVersion;
-use std::convert::TryFrom;
 use crate::state_transition::batch_transition::batched_transition::{BatchedTransition, BatchedTransitionRef};
 #[cfg(feature = "state-transition-signing")]
 use crate::state_transition::batch_transition::methods::StateTransitionCreationOptions;
@@ -165,14 +164,12 @@ pub trait DocumentsBatchTransitionMethodsV0: DocumentsBatchTransitionAccessorsV0
             }
         };
 
-        Ok(if highest_security_level == SecurityLevel::MASTER {
-            vec![SecurityLevel::MASTER]
-        } else {
-            // this might seem wrong until you realize that master is 0, critical 1, etc
-            (SecurityLevel::CRITICAL as u8..=highest_security_level as u8)
-                .map(|security_level| SecurityLevel::try_from(security_level).unwrap())
-                .collect()
-        })
+        // Edited in place in a shipped generation: `document_signing_levels` returns what the
+        // code it replaced did for every requirement (MASTER alone for MASTER, otherwise
+        // CRITICAL through the requirement, strongest first), without its `unwrap`. Its tests
+        // and the batch tests pin each output, so no protocol version that signs or checks a
+        // batch through this method can see another result.
+        Ok(highest_security_level.document_signing_levels())
     }
 
     fn set_transitions(&mut self, transitions: Vec<BatchedTransition>);

packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/tests.rs

@@ -858,6 +858,69 @@ mod batch_transition_tests {
         assert_eq!(purposes, vec![Purpose::AUTHENTICATION]);
     }
 
+    // -----------------------------------------------------------------------
+    // combined_security_level_requirement
+    // -----------------------------------------------------------------------
+
+    /// The levels a batch may be signed at, pinned for each document requirement, for the
+    /// strongest of two requirements, for a token transition and for an empty batch: they
+    /// come from `SecurityLevel::document_signing_levels` and must not change.
+    #[test]
+    fn should_keep_the_levels_a_batch_may_be_signed_at() {
+        use SecurityLevel::*;
+        let documents = make_batch_v1(vec![
+            BatchedTransition::Document(make_delete_transition(1)),
+            BatchedTransition::Document(make_delete_transition(2)),
+        ]);
+        for (requirement, expected) in [
+            (MASTER, vec![MASTER]),
+            (CRITICAL, vec![CRITICAL]),
+            (HIGH, vec![CRITICAL, HIGH]),
+            (MEDIUM, vec![CRITICAL, HIGH, MEDIUM]),
+        ] {
+            let levels = documents
+                .combined_security_level_requirement(Some(
+                    move |_: Identifier, _: String| -> Result<SecurityLevel, ProtocolError> {
+                        Ok(requirement)
+                    },
+                ))
+                .expect("the levels");
+            assert_eq!(levels, expected, "{requirement}");
+        }
+
+        // The strongest requirement among the batch's documents wins.
+        let calls = std::cell::Cell::new(0);
+        let mixed = documents
+            .combined_security_level_requirement(Some(
+                |_: Identifier, _: String| -> Result<SecurityLevel, ProtocolError> {
+                    calls.set(calls.get() + 1);
+                    Ok(if calls.get() == 1 { MEDIUM } else { HIGH })
+                },
+            ))
+            .expect("the levels");
+        assert_eq!(mixed, vec![CRITICAL, HIGH]);
+
+        let token = make_batch_v1(vec![BatchedTransition::Token(make_token_burn_transition(
+            1, 10,
+        ))]);
+        assert_eq!(
+            token
+                .combined_security_level_requirement(
+                    None::<fn(Identifier, String) -> Result<SecurityLevel, ProtocolError>>
+                )
+                .expect("the levels"),
+            vec![CRITICAL]
+        );
+        assert_eq!(
+            make_batch_v1(vec![])
+                .combined_security_level_requirement(
+                    None::<fn(Identifier, String) -> Result<SecurityLevel, ProtocolError>>
+                )
+                .expect("the levels"),
+            vec![CRITICAL, HIGH, MEDIUM]
+        );
+    }
+
     // -----------------------------------------------------------------------
     // get_security_level_requirement function
     // -----------------------------------------------------------------------

packages/rs-drive-abci/tests/protocol_gate.rs

@@ -395,9 +395,10 @@ fn should_export_protocol_gate_sdk_fixtures() {
         Provider.get_quorum_public_key(106, [2; 32], 0).unwrap(),
     )
     .unwrap();
-    // The versions on either side of protocol 14, fixed so that re-running on a later
-    // branch rewrites the same files the SDK tests read.
-    for signed in [13, 14] {
+    // The versions on either side of protocol 14, and protocol 15, which the private
+    // document requests need, fixed so that re-running on a later branch rewrites the same
+    // files the SDK tests read.
+    for signed in [13, 14, 15] {
         let answer = Node::new(signed).epoch_probe();
         assert_eq!(verified_epoch_probe(answer.clone(), signed), signed);
         std::fs::write(
@@ -455,11 +456,11 @@ fn should_export_protocol_gate_sdk_fixtures() {
 #[test]
 fn should_keep_the_recorded_protocol_gate_vectors_verifiable() {
     let read = |name: &str| std::fs::read(directory().join(name)).unwrap();
-    for signed in [13, 14] {
+    for signed in [13, 14, 15] {
         let answer =
             GetEpochsInfoResponse::decode(read(&format!("epoch-probe-pv{signed}.bin")).as_slice())
                 .unwrap();
-        for rules_version in [13, 14] {
+        for rules_version in [13, 14, 15] {
             assert_eq!(verified_epoch_probe(answer.clone(), rules_version), signed);
         }
     }

packages/rs-drive-proof-verifier/src/types/private_document_entries.rs

@@ -52,8 +52,10 @@ pub(crate) fn private_document_entries_from_response(
             })
         })
         .collect::<Result<Vec<_>, Error>>()?;
+    // The response carries no chunk power; only a proof binds it.
     Ok(PrivateDocumentEntries {
         entries,
         total_count,
+        chunk_power: None,
     })
 }

packages/rs-drive-proof-verifier/tests/vectors/protocol-gate/README.md

@@ -12,9 +12,9 @@ the network runs a protocol version that serves it. When it does not know that y
 asks for the genesis epoch first. `rs-sdk`'s protocol gate tests replay these answers
 through the normal proof and signature verifier:
 
-- `epoch-probe-pv13.bin`, `epoch-probe-pv14.bin`: the genesis epoch
+- `epoch-probe-pv13.bin`, `epoch-probe-pv14.bin`, `epoch-probe-pv15.bin`: the genesis epoch
   (`GetEpochsInfoRequestV0 { start_epoch: Some(0), count: 1, ascending: true, prove: true }`)
-  proved by a node at genesis state of protocol 13 or 14, signed at that version.
+  proved by a node at genesis state of protocol 13, 14 or 15, signed at that version.
 - `epoch-probe-newer.bin`: the same answer from a protocol 14 state, signed as protocol
   version 1000, far above any real version, so the SDK always reads it with the newest
   rules it knows.

packages/rs-drive/src/drive/document/private_document_store/fetch_private_document_entries/v0/mod.rs

@@ -59,6 +59,7 @@ impl Drive {
         Ok(PrivateDocumentEntries {
             entries,
             total_count: page.total_count,
+            chunk_power: Some(chunk_power),
         })
     }
 }