Trait commit_verify::embed_commit::EmbedCommitVerify

pub trait EmbedCommitVerify<Msg, Protocol>where
    Self: Sized,
    Msg: CommitEncode,
    Protocol: CommitmentProtocol,{
    type Proof: EmbedCommitProof<Msg, Self, Protocol>;
    type CommitError: Error;
    type VerifyError: Error + From<Self::CommitError>;

    fn embed_commit(
        &mut self,
        msg: &Msg
    ) -> Result<Self::Proof, Self::CommitError>;

    fn verify(
        &self,
        msg: &Msg,
        proof: Self::Proof
    ) -> Result<bool, Self::VerifyError>
    where
        Self: VerifyEq,
        Self::Proof: VerifyEq,
    { ... }
}

Trait for embed-commit-verify scheme, where some data structure (named container) may commit to existing message (producing commitment data structure and a proof) in such way that the original message can’t be restored from the commitment, however the fact of the commitment may be deterministically verified when the message and the proof are revealed.

To use embed-commit-verify scheme one needs to implement this trait for a data structure acting as a container for a specific commitment under certain protocol, specified as generic parameter. The container type must specify as associated types proof and commitment types.

Operations with embed-commit-verify scheme may be represented in form of EmbedCommit: (Container, Message) -> (Container', Proof) (see Self::embed_commit and Verify: (Container', Message, Proof) -> bool (see Self::verify).

This trait is heavily used in deterministic bitcoin commitments.

Protocol definition

Generic parameter Protocol provides context & configuration for commitment scheme protocol used for this container type.

Introduction of this generic allows to:

• implement trait for foreign data types;
• add multiple implementations under different commitment protocols to the combination of the same message and container type (each of each will have its own Proof type defined as an associated generic).

Usually represents an uninstantiable type, but may be a structure containing commitment protocol configuration or context objects.

// Uninstantiable type
pub enum Lnpbp6 {}

impl CommitmentProtocol for Lnpbp6 {
    const HASH_TAG_MIDSTATE: Option<Midstate> = Some(Midstate(
        [0u8; 32], // replace with the actual midstate constant
    ));
}

// Protocol definition containing context object
pub struct Lnpbp1 {
    pub secp: Secp256k1,
}
// ...

Required Associated Types

type Proof: EmbedCommitProof<Msg, Self, Protocol>

The proof of the commitment produced as a result of Self::embed_commit procedure. This proof is later used for verification.

type CommitError: Error

Error type that may be reported during Self::embed_commit procedure. It may also be returned from Self::verify in case the proof data are invalid and the commitment can’t be re-created.

type VerifyError: Error + From<Self::CommitError>

Error type that may be reported during Self::verify procedure. It must be a subset of Self::CommitError.

Required Methods

fn embed_commit(&mut self, msg: &Msg) -> Result<Self::Proof, Self::CommitError>

Creates a commitment to a message and embeds it into the provided container (self) by mutating it and returning commitment proof.

Implementations must error with a dedicated error type enumerating commitment procedure mistakes.

Provided Methods

fn verify(&self, msg: &Msg, proof: Self::Proof) -> Result<bool, Self::VerifyError>where
    Self: VerifyEq,
    Self::Proof: VerifyEq,

Verifies commitment with commitment proof against the message.

Default implementation reconstructs original container with the EmbedCommitProof::restore_original_container method and repeats Self::embed_commit procedure checking that the resulting proof and commitment matches the provided self and proof.

Errors if the provided commitment can’t be created, i.e. the Self::embed_commit procedure for the original container, restored from the proof and current container, can’t be performed. This means that the verification has failed and the commitment and proof are invalid. The function returns error in this case (ano not simply false) since this usually means the software error in managing container and proof data, or selection of a different commitment protocol parameters comparing to the ones used during commitment creation. In all these cases we’d like to provide devs with more information for debugging.

The proper way of using the function in a well-debugged software should be if commitment.verify(...).expect("proof managing system") { .. }. However if the proofs are provided by some sort of user/network input from an untrusted party, a proper form would be if commitment.verify(...).unwrap_or(false) { .. }.

Implementors