mithril_aggregator/services/certifier/
interface.rs

1use async_trait::async_trait;
2use thiserror::Error;
3
4use mithril_common::entities::{
5    Certificate, Epoch, ProtocolMessage, SignedEntityType, SignedEntityTypeDiscriminants,
6    SingleSignature,
7};
8use mithril_common::{StdError, StdResult};
9
10use crate::entities::OpenMessage;
11
12/// Errors dedicated to the CertifierService.
13#[derive(Debug, Error)]
14pub enum CertifierServiceError {
15    /// OpenMessage not found.
16    #[error("The open message was not found for beacon {0:?}.")]
17    NotFound(SignedEntityType),
18
19    /// The open message is already certified, no more single signatures may be
20    /// attached to it nor be certified again.
21    #[error("Open message for beacon {0:?} already certified.")]
22    AlreadyCertified(SignedEntityType),
23
24    /// The open message is expired, no more single signatures may be
25    /// attached to it nor be certified again.
26    #[error("Open message for beacon {0:?} is expired.")]
27    Expired(SignedEntityType),
28
29    /// An invalid signature was provided.
30    #[error("Invalid single signature for {0:?}.")]
31    InvalidSingleSignature(SignedEntityType, #[source] StdError),
32
33    /// No parent certificate could be found, this certifier cannot create genesis certificates.
34    #[error(
35        "No parent certificate could be found, this certifier cannot create genesis certificates."
36    )]
37    NoParentCertificateFound,
38
39    /// No certificate for this epoch
40    #[error("There is an epoch gap between the last certificate epoch ({certificate_epoch:?}) and current epoch ({current_epoch:?})")]
41    CertificateEpochGap {
42        /// Epoch of the last issued certificate
43        certificate_epoch: Epoch,
44
45        /// Given current epoch
46        current_epoch: Epoch,
47    },
48
49    /// Could not verify certificate chain because could not find last certificate.
50    #[error("No certificate found.")]
51    CouldNotFindLastCertificate,
52}
53
54/// Status of a successful registration of a single signature.
55#[derive(Debug, Copy, Clone, PartialEq)]
56pub enum SignatureRegistrationStatus {
57    /// The signature was registered and will be used for the next certificate.
58    Registered,
59
60    /// The signature was buffered, it will be used later.
61    Buffered,
62}
63
64/// ## CertifierService
65///
66/// This service manages the open message and their beacon transitions. It can
67/// ultimately transform open messages into certificates.
68#[cfg_attr(test, mockall::automock)]
69#[async_trait]
70pub trait CertifierService: Sync + Send {
71    /// Inform the certifier I have detected a new epoch, it may clear its state
72    /// and prepare the new signature round. If the given Epoch is equal or less
73    /// than the previous informed Epoch, nothing is done.
74    async fn inform_epoch(&self, epoch: Epoch) -> StdResult<()>;
75
76    /// Add a new single signature for the open message at the given beacon. If
77    /// the open message does not exist or the open message has been certified
78    /// since then, an error is returned.
79    async fn register_single_signature(
80        &self,
81        signed_entity_type: &SignedEntityType,
82        signature: &SingleSignature,
83    ) -> StdResult<SignatureRegistrationStatus>;
84
85    /// Create an open message at the given beacon. If the open message does not
86    /// exist or exists at an older beacon, the older open messages are cleared
87    /// along with their associated single signatures and the new open message
88    /// is created. If the message already exists, an error is returned.
89    async fn create_open_message(
90        &self,
91        signed_entity_type: &SignedEntityType,
92        protocol_message: &ProtocolMessage,
93    ) -> StdResult<OpenMessage>;
94
95    /// Return the open message at the given Beacon. If the message does not
96    /// exist, None is returned.
97    async fn get_open_message(
98        &self,
99        signed_entity_type: &SignedEntityType,
100    ) -> StdResult<Option<OpenMessage>>;
101
102    /// Mark the open message if it has expired.
103    async fn mark_open_message_if_expired(
104        &self,
105        signed_entity_type: &SignedEntityType,
106    ) -> StdResult<Option<OpenMessage>>;
107
108    /// Create a certificate if possible. If the pointed open message does
109    /// not exist or has been already certified, an error is raised. If a multi
110    /// signature is created then the flag `is_certified` of the open
111    /// message is set to true. The Certificate is created.
112    /// If the stake quorum of the single signatures is
113    /// not reached for the multisignature to be created, the certificate is not
114    /// created and None is returned. If the certificate can be created, the
115    /// list of the registered signers for the given epoch is used.
116    async fn create_certificate(
117        &self,
118        signed_entity_type: &SignedEntityType,
119    ) -> StdResult<Option<Certificate>>;
120
121    /// Returns a certificate from its hash.
122    async fn get_certificate_by_hash(&self, hash: &str) -> StdResult<Option<Certificate>>;
123
124    /// Returns the list of the latest created certificates.
125    async fn get_latest_certificates(&self, last_n: usize) -> StdResult<Vec<Certificate>>;
126
127    /// Verify the certificate chain and epoch gap. This will return an error if
128    /// there is at least an epoch between the given epoch and the most recent
129    /// certificate.
130    async fn verify_certificate_chain(&self, epoch: Epoch) -> StdResult<()>;
131}
132
133/// ## BufferedSingleSignatureStore
134///
135/// Allow to buffer single signatures for later use when an open message isn't available yet.
136#[cfg_attr(test, mockall::automock)]
137#[async_trait]
138pub trait BufferedSingleSignatureStore: Sync + Send {
139    /// Buffer a single signature for later use.
140    async fn buffer_signature(
141        &self,
142        signed_entity_type_discriminant: SignedEntityTypeDiscriminants,
143        signature: &SingleSignature,
144    ) -> StdResult<()>;
145
146    /// Get the buffered single signatures for the given signed entity discriminant.
147    async fn get_buffered_signatures(
148        &self,
149        signed_entity_type_discriminant: SignedEntityTypeDiscriminants,
150    ) -> StdResult<Vec<SingleSignature>>;
151
152    /// Remove the given single signatures from the buffer.
153    async fn remove_buffered_signatures(
154        &self,
155        signed_entity_type_discriminant: SignedEntityTypeDiscriminants,
156        single_signatures: Vec<SingleSignature>,
157    ) -> StdResult<()>;
158}
mithril_aggregator/services/certifier/interface.rs

mithril_aggregator/services/certifier/
interface.rs
