Refactor top-level modules related to cryptography, signed messages, and certificates

[lyulka]

Affected version

v0.4 (branch: dev/v0.4)

Related issues

Definitely related: #49. May be related: #46.

Problem

Cryptography, signed messages, and certificates-related definitions are currently split up into seven modules:

• crate::messages
• crate::types::keypair
• crate::types::validators
• crate::types::collectors
• crate::state::safety
• crate::hotstuff::types
• crate::pacemaker::types.

I feel like the way these types are split up leaves a lot to be desired, for several reasons:

• There isn't a clear delineation between the duties of QuorumCertificate::is_correct and Block::is_correct on the one hand, and safe_qc and safe_block on the other:
  • The initial idea was for the is_correct pair to only check the cryptographic well-formedness of their respective types, and so their signatures should only take in verifying key(s), just like SignedMessage::is_correct. However, as it turns out, both the is_correct and safe_ pairs currently take in BlockTree. The similarity in the signatures of both pairs of functions make the distinction between them unclear.
  • Inspecting the source code, all calls to QuorumCertificate::is_correct are always followed by a call to safe_qc, and all calls to Block::is_correct are always followed by a call to safe_block. The opposite is also true, all calls to safe_qc are always preceded by a call to QuorumCertificate::is_correct, and all calls to safe_block are always preceded by a call to Block::is_correct. This suggests that QuorumCertificate::is_correct should just be called in safe_qc, and Block::is_correct should just be called in safe_block.
• Cryptographic primitives provided by ed25519_dalek are re-exported from two separate modules: crate::types::keypair, crate::types::validators. This does not feel right, because:
  • The bulk of validators define complex types, not primitives like the three Dalek types it currently re-exports (i.e., Signature, SigningKey, and VerifyingKey).
  • crate::types::keypair defines only one type, that is Keypair. This is out of place when compared to its sibling modules, which defines many types.
• The traits SignedMessage, Certificate, and Collectors, are all intimately related, yet SignedMessages is defined at the top-level crate::messages module, while Certificate and Collectors are defined in crate::types.

Proposed solution

Organization

I propose that we reorganize the top-level cryptography, signed messages, and certificates-related definitions into the following six modules:

• mod networking
  • enum Message
  • enum ProgressMessage
  • trait Cacheable
  • ...other existing definitions omitted.
• mod state::safety
  • fn safe_block (calls safe_qc).
  • fn safe_nudge (calls safe_qc).
  • fn safe_qc (calls QuorumCertificate::is_correct).
  • ...other existing definitions omitted.
  • mod types::crypto_primitives
  • struct Keypair
  • ed25519::Signature
  • ed25519::SigningKey
  • ed25519::VerifyingKey
• mod types::signed_messages
  • trait SignedMessage
    • fn message_bytes
    • fn signature_bytes
    • fn is_correct.
    • trait Certificate
      • fn message_bytes(&self) -> &[u8]
      • fn signature_set(&self) -> &SignatureSet
      • fn is_correct(&self, vk: VerifyingKey) -> bool (provided)
      • fn quorum(total_power: TotalPower) -> TotalPower (provided)
    • trait Collector<SignedMessage: SignedMessage, Certificate: Certificate>
      • fn collect(signer: VerifyingKey, message: Self::SignedMessage) -> Self::Certificate
• mod hotstuff::types
  • struct QuorumCertificate
  • impl Certificate for QuorumCertificate
  • struct VoteCollector
  • impl Collector for VoteCollector
  • ...other existing definitions omitted.
• mod pacemaker::types
  • struct TimeoutCertificate
  • impl Certificate for TimeoutCertificate
  • struct TimeoutVoteCollector
  • impl Collector for TimeoutVoteCollector
  • ...other existing definitions omitted.

Changes

The changes that the above organization makes on the current organization are:

• Move all ed25519_dalek re-exports into a single module: types::crypto_primitives, enhancing coherence.
• Define SignedMessage, Certificate, and Collector in a single module: types::signed_messages, enhancing coherence.
• Move definitions currently in crate::messages that are related to networking to crate::networking, enhancing coherence.
• Modify Certificate::is_correct to take in only a ValidatorSet, clarifying the difference in the responsibilities of is_correct and safe_: is_correct checks the cryptographic well-formedness of the type, and safe_ checks everything else, most significantly the properties that can only be checked by reading the block tree.
• Call is_correct from safe_ methods, simplifying calling code and allowing us to remove the preconditions of the safe_ methods.

[lyulka]

Most of the things in this issue has been implemented up to the last commit, the last things have to do with the networking module and the Certificate::is_correct method (may do the latter in the future instead of now).