doxygen documentation for checkpoints.{h,cpp}

All functions in src/cryptonote_core/checkpoints.h are now documented in
doxygen style.

checkpoints.cpp has been reviewed, one function has been marked for
discussion on correctness.
This commit is contained in:
Thomas Winget 2015-10-07 22:28:31 -04:00
parent 89c24ac2be
commit 1b0c98e7e9
No known key found for this signature in database
GPG Key ID: 58131A160789E630
2 changed files with 99 additions and 6 deletions

View File

@ -84,10 +84,7 @@ namespace cryptonote
return check_block(height, h, ignored); return check_block(height, h, ignored);
} }
//--------------------------------------------------------------------------- //---------------------------------------------------------------------------
// this basically says if the blockchain is smaller than the first //FIXME: is this the desired behavior?
// checkpoint then alternate blocks are allowed. Alternatively, if the
// last checkpoint *before* the end of the current chain is also before
// the block to be added, then this is fine.
bool checkpoints::is_alternative_block_allowed(uint64_t blockchain_height, uint64_t block_height) const bool checkpoints::is_alternative_block_allowed(uint64_t blockchain_height, uint64_t block_height) const
{ {
if (0 == block_height) if (0 == block_height)

View File

@ -36,19 +36,115 @@
namespace cryptonote namespace cryptonote
{ {
/**
* @brief A container for blockchain checkpoints
*
* A checkpoint is a pre-defined hash for the block at a given height.
* Some of these are compiled-in, while others can be loaded at runtime
* either from a json file or via DNS from a checkpoint-hosting server.
*/
class checkpoints class checkpoints
{ {
public: public:
/**
* @brief default constructor
*/
checkpoints(); checkpoints();
/**
* @brief adds a checkpoint to the container
*
* @param height the height of the block the checkpoint is for
* @param hash_str the hash of the block, as a string
*
* @return false if parsing the hash fails, or if the height is a duplicate
* AND the existing checkpoint hash does not match the new one,
* otherwise returns true
*/
bool add_checkpoint(uint64_t height, const std::string& hash_str); bool add_checkpoint(uint64_t height, const std::string& hash_str);
/**
* @brief checks if there is a checkpoint in the future
*
* This function checks if the height passed is lower than the highest
* checkpoint.
*
* @param height the height to check against
*
* @return false if no checkpoints, otherwise returns whether or not
* the height passed is lower than the highest checkpoint.
*/
bool is_in_checkpoint_zone(uint64_t height) const; bool is_in_checkpoint_zone(uint64_t height) const;
bool check_block(uint64_t height, const crypto::hash& h) const;
/**
* @brief checks if the given height and hash agree with the checkpoints
*
* This function checks if the given height and hash exist in the
* checkpoints container. If so, it returns whether or not the passed
* parameters match the stored values.
*
* @param height the height to be checked
* @param h the hash to be checked
* @param is_a_checkpoint return-by-reference if there is a checkpoint at the given height
*
* @return true if there is no checkpoint at the given height,
* true if the passed parameters match the stored checkpoint,
* false otherwise
*/
bool check_block(uint64_t height, const crypto::hash& h, bool& is_a_checkpoint) const; bool check_block(uint64_t height, const crypto::hash& h, bool& is_a_checkpoint) const;
/**
* @overload
*/
bool check_block(uint64_t height, const crypto::hash& h) const;
/**
* @brief checks if alternate chain blocks should be kept for a given height
*
* this basically says if the blockchain is smaller than the first
* checkpoint then alternate blocks are allowed. Alternatively, if the
* last checkpoint *before* the end of the current chain is also before
* the block to be added, then this is fine.
*
* @param blockchain_height the current blockchain height
* @param block_height the height of the block to be added as alternate
*
* @return true if alternate blocks are allowed given the parameters,
* otherwise false
*/
bool is_alternative_block_allowed(uint64_t blockchain_height, uint64_t block_height) const; bool is_alternative_block_allowed(uint64_t blockchain_height, uint64_t block_height) const;
/**
* @brief gets the highest checkpoint height
*
* @return the height of the highest checkpoint
*/
uint64_t get_max_height() const; uint64_t get_max_height() const;
/**
* @brief gets the checkpoints container
*
* @return a const reference to the checkpoints container
*/
const std::map<uint64_t, crypto::hash>& get_points() const; const std::map<uint64_t, crypto::hash>& get_points() const;
/**
* @brief checks if our checkpoints container conflicts with another
*
* A conflict refers to a case where both checkpoint sets have a checkpoint
* for a specific height but their hashes for that height do not match.
*
* @param other the other checkpoints instance to check against
*
* @return false if any conflict is found, otherwise true
*/
bool check_for_conflicts(const checkpoints& other) const; bool check_for_conflicts(const checkpoints& other) const;
private: private:
std::map<uint64_t, crypto::hash> m_points;
std::map<uint64_t, crypto::hash> m_points; //!< the checkpoints container
}; };
} }