Trait Domain 

pub trait Domain {
    type EphemeralSecretKey: ConstantTimeEq;
    type EphemeralPublicKey;
    type PreparedEphemeralPublicKey;
    type SharedSecret;
    type SymmetricKey: AsRef<[u8]>;
    type Note;
    type Recipient;
    type DiversifiedTransmissionKey;
    type IncomingViewingKey;
    type OutgoingViewingKey;
    type ValueCommitment;
    type Memo;

    // Required methods
    fn derive_esk(note: &Self::Note) -> Option<Self::EphemeralSecretKey>;
    fn get_pk_d(note: &Self::Note) -> Self::DiversifiedTransmissionKey;
    fn prepare_epk(
        epk: Self::EphemeralPublicKey,
    ) -> Self::PreparedEphemeralPublicKey;
    fn ka_derive_public(
        note: &Self::Note,
        esk: &Self::EphemeralSecretKey,
    ) -> Self::EphemeralPublicKey;
    fn ka_agree_enc(
        esk: &Self::EphemeralSecretKey,
        pk_d: &Self::DiversifiedTransmissionKey,
    ) -> Self::SharedSecret;
    fn ka_agree_dec(
        ivk: &Self::IncomingViewingKey,
        epk: &Self::PreparedEphemeralPublicKey,
    ) -> Self::SharedSecret;
    fn kdf(
        secret: Self::SharedSecret,
        ephemeral_key: &EphemeralKeyBytes,
    ) -> Self::SymmetricKey;
    fn note_plaintext_bytes(
        note: &Self::Note,
        recipient: &Self::Recipient,
        memo: &Self::Memo,
    ) -> NotePlaintextBytes;
    fn derive_ock(
        ovk: &Self::OutgoingViewingKey,
        cv: &Self::ValueCommitment,
        cmstar_bytes: &ExtractedCommitmentBytes,
        ephemeral_key: &EphemeralKeyBytes,
    ) -> OutgoingCipherKey;
    fn outgoing_plaintext_bytes(
        note: &Self::Note,
        esk: &Self::EphemeralSecretKey,
    ) -> OutPlaintextBytes;
    fn epk_bytes(epk: &Self::EphemeralPublicKey) -> EphemeralKeyBytes;
    fn epk(
        ephemeral_key: &EphemeralKeyBytes,
    ) -> Option<Self::EphemeralPublicKey>;
    fn cmstar(note: &Self::Note) -> ExtractedCommitment;
    fn parse_note_plaintext_without_memo_ivk(
        &self,
        ivk: &Self::IncomingViewingKey,
        plaintext: &[u8],
    ) -> Option<(Self::Note, Self::Recipient)>;
    fn parse_note_plaintext_without_memo_ovk(
        &self,
        pk_d: &Self::DiversifiedTransmissionKey,
        esk: &Self::EphemeralSecretKey,
        ephemeral_key: &EphemeralKeyBytes,
        plaintext: &NotePlaintextBytes,
    ) -> Option<(Self::Note, Self::Recipient)>;
    fn extract_memo(&self, plaintext: &NotePlaintextBytes) -> Self::Memo;
    fn extract_pk_d(
        out_plaintext: &OutPlaintextBytes,
    ) -> Option<Self::DiversifiedTransmissionKey>;
    fn extract_esk(
        out_plaintext: &OutPlaintextBytes,
    ) -> Option<Self::EphemeralSecretKey>;
}

Trait that encapsulates protocol-specific note encryption types and logic.

This trait enables most of the note encryption logic to be shared between Sapling and Orchard, as well as between different implementations of those protocols.

Required Associated Types

type EphemeralSecretKey: ConstantTimeEq

type EphemeralPublicKey

type PreparedEphemeralPublicKey

type SharedSecret

type SymmetricKey: AsRef<[u8]>

type Note

type Recipient

type DiversifiedTransmissionKey

type IncomingViewingKey

type OutgoingViewingKey

type ValueCommitment

type Memo

Required Methods

fn derive_esk(note: &Self::Note) -> Option<Self::EphemeralSecretKey>

Derives the EphemeralSecretKey corresponding to this note.

Returns None if the note was created prior to ZIP 212, and doesn’t have a deterministic EphemeralSecretKey.

fn get_pk_d(note: &Self::Note) -> Self::DiversifiedTransmissionKey

Extracts the DiversifiedTransmissionKey from the note.

fn prepare_epk( epk: Self::EphemeralPublicKey, ) -> Self::PreparedEphemeralPublicKey

Prepare an ephemeral public key for more efficient scalar multiplication.

fn ka_derive_public( note: &Self::Note, esk: &Self::EphemeralSecretKey, ) -> Self::EphemeralPublicKey

Derives EphemeralPublicKey from esk and the note’s diversifier.

fn ka_agree_enc( esk: &Self::EphemeralSecretKey, pk_d: &Self::DiversifiedTransmissionKey, ) -> Self::SharedSecret

Derives the SharedSecret from the sender’s information during note encryption.

fn ka_agree_dec( ivk: &Self::IncomingViewingKey, epk: &Self::PreparedEphemeralPublicKey, ) -> Self::SharedSecret

Derives the SharedSecret from the recipient’s information during note trial decryption.

fn kdf( secret: Self::SharedSecret, ephemeral_key: &EphemeralKeyBytes, ) -> Self::SymmetricKey

Derives the SymmetricKey used to encrypt the note plaintext.

secret is the SharedSecret obtained from Self::ka_agree_enc or Self::ka_agree_dec.

ephemeral_key is the byte encoding of the EphemeralPublicKey used to derive secret. During encryption it is derived via Self::epk_bytes; during trial decryption it is obtained from ShieldedOutput::ephemeral_key.

fn note_plaintext_bytes( note: &Self::Note, recipient: &Self::Recipient, memo: &Self::Memo, ) -> NotePlaintextBytes

Encodes the given Note and Memo as a note plaintext.

Future breaking changes

The recipient argument is present as a secondary way to obtain the diversifier; this is due to a historical quirk of how the Sapling Note struct was implemented in the zcash_primitives crate. recipient will be removed from this method in a future crate release, once zcash_primitives has been refactored.

fn derive_ock( ovk: &Self::OutgoingViewingKey, cv: &Self::ValueCommitment, cmstar_bytes: &ExtractedCommitmentBytes, ephemeral_key: &EphemeralKeyBytes, ) -> OutgoingCipherKey

Derives the OutgoingCipherKey for an encrypted note, given the note-specific public data and an OutgoingViewingKey.

fn outgoing_plaintext_bytes( note: &Self::Note, esk: &Self::EphemeralSecretKey, ) -> OutPlaintextBytes

Encodes the outgoing plaintext for the given note.

fn epk_bytes(epk: &Self::EphemeralPublicKey) -> EphemeralKeyBytes

Returns the byte encoding of the given EphemeralPublicKey.

fn epk(ephemeral_key: &EphemeralKeyBytes) -> Option<Self::EphemeralPublicKey>

Attempts to parse ephemeral_key as an EphemeralPublicKey.

Returns None if ephemeral_key is not a valid byte encoding of an EphemeralPublicKey.

fn cmstar(note: &Self::Note) -> ExtractedCommitment

Derives the ExtractedCommitment for this note.

fn parse_note_plaintext_without_memo_ivk( &self, ivk: &Self::IncomingViewingKey, plaintext: &[u8], ) -> Option<(Self::Note, Self::Recipient)>

Parses the given note plaintext from the recipient’s perspective.

The implementation of this method must check that:

• The note plaintext version is valid (for the given decryption domain’s context, which may be passed via self).
• The note plaintext contains valid encodings of its various fields.
• Any domain-specific requirements are satisfied.

&self is passed here to enable the implementation to enforce contextual checks, such as rules like ZIP 212 that become active at a specific block height.

Panics

Panics if plaintext is shorter than COMPACT_NOTE_SIZE.

fn parse_note_plaintext_without_memo_ovk( &self, pk_d: &Self::DiversifiedTransmissionKey, esk: &Self::EphemeralSecretKey, ephemeral_key: &EphemeralKeyBytes, plaintext: &NotePlaintextBytes, ) -> Option<(Self::Note, Self::Recipient)>

Parses the given note plaintext from the sender’s perspective.

The implementation of this method must check that:

• The note plaintext version is valid (for the given decryption domain’s context, which may be passed via self).
• The note plaintext contains valid encodings of its various fields.
• Any domain-specific requirements are satisfied.
• ephemeral_key can be derived from esk and the diversifier within the note plaintext.

&self is passed here to enable the implementation to enforce contextual checks, such as rules like ZIP 212 that become active at a specific block height.

fn extract_memo(&self, plaintext: &NotePlaintextBytes) -> Self::Memo

Extracts the memo field from the given note plaintext.

Compatibility

&self is passed here in anticipation of future changes to memo handling, where the memos may no longer be part of the note plaintext.

fn extract_pk_d( out_plaintext: &OutPlaintextBytes, ) -> Option<Self::DiversifiedTransmissionKey>

Parses the DiversifiedTransmissionKey field of the outgoing plaintext.

Returns None if out_plaintext does not contain a valid byte encoding of a DiversifiedTransmissionKey.

fn extract_esk( out_plaintext: &OutPlaintextBytes, ) -> Option<Self::EphemeralSecretKey>

Parses the EphemeralSecretKey field of the outgoing plaintext.

Returns None if out_plaintext does not contain a valid byte encoding of an EphemeralSecretKey.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors