feat(wasm-sdk): seal and scan DashPay private contact requests

packages/js-evo-sdk/src/private-documents/facade.ts

@@ -0,0 +1,61 @@
+import * as wasm from '../wasm.js';
+import type { EvoSDK } from '../sdk.js';
+
+/**
+ * Private document types (protocol version 15) and DashPay's private contact requests.
+ *
+ * A private type's documents are fixed-size encrypted entries of a store, in append order,
+ * readable a page at a time. A DashPay private contact request is one such entry sealed to the
+ * recipient's DashPay key: only the recipient learns it exists, who sent it and what it holds.
+ *
+ * Appending an entry is paid from the shielded pool, which needs an Orchard proof this SDK
+ * cannot make yet (see `ShieldedFacade`): `sealContactRequest` builds the entry, and a wallet
+ * that can prove appends it.
+ */
+export class PrivateDocumentsFacade {
+  private sdk: EvoSDK;
+
+  constructor(sdk: EvoSDK) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * The proved page of a private type's store from `startPosition`, up to the end of the
+   * store's chunk holding it. A reader walks the store by asking again from the position after
+   * the page's last entry, until `totalCount`.
+   */
+  async entries(
+    dataContractId: wasm.IdentifierLike,
+    documentTypeName: string,
+    startPosition: bigint,
+  ): Promise<wasm.PrivateDocumentEntriesPage> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.getPrivateDocumentEntries(dataContractId, documentTypeName, startPosition);
+  }
+
+  /**
+   * Seals a DashPay private contact request from the sender's encryption key to one of the
+   * recipient's DashPay keys, signed by `options.signer` with one of the sender's signing keys,
+   * as its transitions are.
+   *
+   * @returns The entry, of the type's entry size, to append.
+   */
+  async sealContactRequest(options: wasm.SealPrivateContactRequestOptions): Promise<Uint8Array> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.sealPrivateContactRequest(options);
+  }
+
+  /**
+   * Reads one page of DashPay's private contact request store for the wallet's identities: the
+   * requests to them, each checked against its sender's signing keys, and the requests they
+   * sent. It fetches the identities those requests are checked against right after the page, so
+   * a node serving both can tell which identities the wallet looked up. Keep `nextPosition` as the cursor once the page is stored, and scan
+   * again from it until `isComplete`.
+   */
+  async scanContactRequests(
+    options: wasm.ScanPrivateContactRequestsOptions,
+  ): Promise<wasm.PrivateContactRequestScanResult> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.scanPrivateContactRequests(options);
+  }
+}

packages/js-evo-sdk/src/sdk.ts

@@ -17,6 +17,7 @@ import { ShieldedFacade } from './shielded/facade.js';
 import { EncryptedForFacade } from './encrypted-for/facade.js';
 import { ModerationChartersFacade } from './moderation-charters/facade.js';
 import { DecisionProposalsFacade } from './decision-proposals/facade.js';
+import { PrivateDocumentsFacade } from './private-documents/facade.js';
 
 export interface ConnectionOptions {
   version?: number;
@@ -102,6 +103,7 @@ export class EvoSDK {
   public encryptedFor!: EncryptedForFacade;
   public moderationCharters!: ModerationChartersFacade;
   public decisionProposals!: DecisionProposalsFacade;
+  public privateDocuments!: PrivateDocumentsFacade;
   constructor(options: EvoSDKOptions = {}) {
     // Apply defaults while preserving any future connection options
     const {
@@ -179,6 +181,7 @@ export class EvoSDK {
     this.encryptedFor = new EncryptedForFacade(this);
     this.moderationCharters = new ModerationChartersFacade(this);
     this.decisionProposals = new DecisionProposalsFacade(this);
+    this.privateDocuments = new PrivateDocumentsFacade(this);
   }
 
   get wasm(): wasm.WasmSdk {
@@ -457,5 +460,6 @@ export { ShieldedFacade } from './shielded/facade.js';
 export { EncryptedForFacade } from './encrypted-for/facade.js';
 export { ModerationChartersFacade } from './moderation-charters/facade.js';
 export { DecisionProposalsFacade } from './decision-proposals/facade.js';
+export { PrivateDocumentsFacade } from './private-documents/facade.js';
 export { wallet } from './wallet/functions.js';
 export * from './wasm.js';

packages/js-evo-sdk/tests/unit/facades/private-documents.spec.ts

@@ -0,0 +1,60 @@
+import type { SinonStub } from 'sinon';
+import init, * as wasmSDKPackage from '@dashevo/wasm-sdk';
+import { EvoSDK } from '../../../dist/sdk.js';
+
+describe('PrivateDocumentsFacade', () => {
+  let wasmSdk: wasmSDKPackage.WasmSdk;
+  let client: EvoSDK;
+
+  let getPrivateDocumentEntriesStub: SinonStub;
+  let sealPrivateContactRequestStub: SinonStub;
+  let scanPrivateContactRequestsStub: SinonStub;
+
+  beforeEach(async function setup() {
+    await init();
+    const builder = wasmSDKPackage.WasmSdkBuilder.testnet();
+    wasmSdk = await builder.build();
+    client = EvoSDK.fromWasm(wasmSdk);
+
+    getPrivateDocumentEntriesStub = this.sinon
+      .stub(wasmSdk, 'getPrivateDocumentEntries')
+      .resolves({ entries: [], totalCount: 0n });
+    sealPrivateContactRequestStub = this.sinon
+      .stub(wasmSdk, 'sealPrivateContactRequest')
+      .resolves(new Uint8Array(589));
+    scanPrivateContactRequestsStub = this.sinon
+      .stub(wasmSdk, 'scanPrivateContactRequests')
+      .resolves('scan');
+  });
+
+  describe('entries()', () => {
+    it('should forward the contract, type and start position to getPrivateDocumentEntries', async () => {
+      const big = 9_007_199_254_740_993n; // > Number.MAX_SAFE_INTEGER
+      const result = await client.privateDocuments.entries('contract', 'privateContactRequest', big);
+      expect(getPrivateDocumentEntriesStub).to.be.calledOnceWithExactly(
+        'contract',
+        'privateContactRequest',
+        big,
+      );
+      expect(result).to.deep.equal({ entries: [], totalCount: 0n });
+    });
+  });
+
+  describe('sealContactRequest()', () => {
+    it('should forward the options to sealPrivateContactRequest and return the entry', async () => {
+      const options = { recipientKeyId: 2 } as unknown as wasmSDKPackage.SealPrivateContactRequestOptions;
+      const entry = await client.privateDocuments.sealContactRequest(options);
+      expect(sealPrivateContactRequestStub).to.be.calledOnceWithExactly(options);
+      expect(entry).to.have.length(589);
+    });
+  });
+
+  describe('scanContactRequests()', () => {
+    it('should forward the options to scanPrivateContactRequests', async () => {
+      const options = { startPosition: 0n };
+      const result = await client.privateDocuments.scanContactRequests(options);
+      expect(scanPrivateContactRequestsStub).to.be.calledOnceWithExactly(options);
+      expect(result).to.equal('scan');
+    });
+  });
+});

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>);