Merge pull request #749

bfd4a28 Update BlockchainDB documentation (Thomas Winget)
797357e Change Doxyfile, Blockchain not blockchain_storage (Thomas Winget)
c835215 remove defunct code from cryptonote::core (Thomas Winget)
50dba6d cryptonote::core doxygen documentation (Thomas Winget)
8ac329d doxygen documentation for difficulty functions (Thomas Winget)
540a76c Move checkpoint functions into checkpoints class (Thomas Winget)
1b0c98e doxygen documentation for checkpoints.{h,cpp} (Thomas Winget)
89c24ac Remove unnecessary or defunct code (Thomas Winget)
ab0ed14 doxygen include private and static members (Thomas Winget)
3a48449 Updated documentation for blockchain.* (Thomas Winget)

15 files changed, 2909 insertions, 594 deletions

diff --git a/Doxyfile b/Doxyfile
index a70ef812b..93a5c6e76 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -409,13 +409,13 @@ LOOKUP_CACHE_SIZE      = 0
 # normally produced when WARNINGS is set to YES.
 # The default value is: NO.
 
-EXTRACT_ALL            = NO
+EXTRACT_ALL            = YES
 
 # If the EXTRACT_PRIVATE tag is set to YES all private members of a class will
 # be included in the documentation.
 # The default value is: NO.
 
-EXTRACT_PRIVATE        = NO
+EXTRACT_PRIVATE        = YES
 
 # If the EXTRACT_PACKAGE tag is set to YES all members with package or internal
 # scope will be included in the documentation.
@@ -427,7 +427,7 @@ EXTRACT_PACKAGE        = NO
 # included in the documentation.
 # The default value is: NO.
 
-EXTRACT_STATIC         = NO
+EXTRACT_STATIC         = YES
 
 # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) defined
 # locally in source files will be included in the documentation. If set to NO
@@ -452,7 +452,7 @@ EXTRACT_LOCAL_METHODS  = NO
 # are hidden.
 # The default value is: NO.
 
-EXTRACT_ANON_NSPACES   = NO
+EXTRACT_ANON_NSPACES   = YES
 
 # If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all
 # undocumented members inside documented classes or files. If set to NO these
@@ -1902,7 +1902,7 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
@@ -1910,7 +1910,7 @@ MACRO_EXPANSION        = NO
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES the includes files in the
 # INCLUDE_PATH will be searched if a #include is found.
@@ -1942,7 +1942,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             =
+PREDEFINED             = "BLOCKCHAIN_DB=2" \ # DB_LMDB
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
diff --git a/src/blockchain_db/blockchain_db.h b/src/blockchain_db/blockchain_db.h
index 3396b8c20..3e0ca141e 100644
--- a/src/blockchain_db/blockchain_db.h
+++ b/src/blockchain_db/blockchain_db.h
@@ -38,18 +38,20 @@
 #include "cryptonote_core/difficulty.h"
 #include "cryptonote_core/hardfork.h"
 
-/* DB Driver Interface
+/** \file
+ * Cryptonote Blockchain Database Interface
  *
  * The DB interface is a store for the canonical block chain.
  * It serves as a persistent storage for the blockchain.
  *
- * For the sake of efficiency, the reference implementation will also
+ * For the sake of efficiency, a concrete implementation may also
  * store some blockchain data outside of the blocks, such as spent
  * transfer key images, unspent transaction outputs, etc.
  *
+ * Examples are as follows:
+ *
  * Transactions are duplicated so that we don't have to fetch a whole block
- * in order to fetch a transaction from that block.  If this is deemed
- * unnecessary later, this can change.
+ * in order to fetch a transaction from that block.
  *
  * Spent key images are duplicated outside of the blocks so it is quick
  * to verify an output hasn't already been spent
@@ -57,100 +59,34 @@
  * Unspent transaction outputs are duplicated to quickly gather random
  * outputs to use for mixins
  *
- * IMPORTANT:
- * A concrete implementation of this interface should populate these
- * duplicated members!  It is possible to have a partial implementation
- * of this interface call to private members of the interface to be added
- * later that will then populate as needed.
- *
- * General:
- *   open()
- *   is_open()
- *   close()
- *   sync()
- *   reset()
- *
- *   Lock and unlock provided for reorg externally, and for block
- *   additions internally, this way threaded reads are completely fine
- *   unless the blockchain is changing.
- *   bool lock()
- *   unlock()
- *
- * vector<str>   get_filenames()
- *
- * Blocks:
- *   bool        block_exists(hash)
- *   height      add_block(block, block_size, cumulative_difficulty, coins_generated, transactions)
- *   block       get_block(hash)
- *   height      get_block_height(hash)
- *   header      get_block_header(hash)
- *   block       get_block_from_height(height)
- *   size_t      get_block_size(height)
- *   difficulty  get_block_cumulative_difficulty(height)
- *   uint64_t    get_block_already_generated_coins(height)
- *   uint64_t    get_block_timestamp(height)
- *   uint64_t    get_top_block_timestamp()
- *   hash        get_block_hash_from_height(height)
- *   blocks      get_blocks_range(height1, height2)
- *   hashes      get_hashes_range(height1, height2)
- *   hash        top_block_hash()
- *   block       get_top_block()
- *   height      height()
- *   void        pop_block(block&, tx_list&)
- *
- * Transactions:
- *   bool        tx_exists(hash)
- *   uint64_t    get_tx_unlock_time(hash)
- *   tx          get_tx(hash)
- *   uint64_t    get_tx_count()
- *   tx_list     get_tx_list(hash_list)
- *   height      get_tx_block_height(hash)
- *
- * Outputs:
- *   uint64_t    get_num_outputs(amount)
- *   pub_key     get_output_key(amount, index)
- *   hash,index  get_output_tx_and_index_from_global(index)
- *   hash,index  get_output_tx_and_index(amount, index)
- *   vec<uint64> get_tx_output_indices(tx_hash)
- *
- *
- * Spent Output Key Images:
- *   bool        has_key_image(key_image)
- *
- * Exceptions:
- *   DB_ERROR -- generic
- *   DB_OPEN_FAILURE
- *   DB_CREATE_FAILURE
- *   DB_SYNC_FAILURE
- *   BLOCK_DNE
- *   BLOCK_PARENT_DNE
- *   BLOCK_EXISTS
- *   BLOCK_INVALID -- considering making this multiple errors
- *   TX_DNE
- *   TX_EXISTS
- *   OUTPUT_DNE
- *   OUTPUT_EXISTS
- *   KEY_IMAGE_EXISTS
  */
 
 namespace cryptonote
 {
 
-// typedef for convenience
+/** a pair of <transaction hash, output index>, typedef for convenience */
 typedef std::pair<crypto::hash, uint64_t> tx_out_index;
 
 #pragma pack(push, 1)
+
+/**
+ * @brief a struct containing output metadata
+ */
 struct output_data_t
 {
-  crypto::public_key pubkey;
-  uint64_t unlock_time;
-  uint64_t height;
+  crypto::public_key pubkey;       //!< the output's public key (for spend verification)
+  uint64_t           unlock_time;  //!< the output's unlock time (or height)
+  uint64_t           height;       //!< the height of the block which created the output
 };
 #pragma pack(pop)
 
 /***********************************
  * Exception Definitions
  ***********************************/
+
+/**
+ * @brief A base class for BlockchainDB exceptions
+ */
 class DB_EXCEPTION : public std::exception
 {
   private:
@@ -168,6 +104,9 @@ class DB_EXCEPTION : public std::exception
     }
 };
 
+/**
+ * @brief A generic BlockchainDB exception
+ */
 class DB_ERROR : public DB_EXCEPTION
 {
   public:
@@ -175,7 +114,9 @@ class DB_ERROR : public DB_EXCEPTION
     DB_ERROR(const char* s) : DB_EXCEPTION(s) { }
 };
 
-// For distinguishing errors trying to set up a DB txn from other errors
+/**
+ * @brief thrown when there is an error starting a DB transaction
+ */
 class DB_ERROR_TXN_START : public DB_EXCEPTION
 {
   public:
@@ -183,6 +124,9 @@ class DB_ERROR_TXN_START : public DB_EXCEPTION
     DB_ERROR_TXN_START(const char* s) : DB_EXCEPTION(s) { }
 };
 
+/**
+ * @brief thrown when opening the BlockchainDB fails
+ */
 class DB_OPEN_FAILURE : public DB_EXCEPTION
 {
   public:
@@ -190,6 +134,9 @@ class DB_OPEN_FAILURE : public DB_EXCEPTION
     DB_OPEN_FAILURE(const char* s) : DB_EXCEPTION(s) { }
 };
 
+/**
+ * @brief thrown when creating the BlockchainDB fails
+ */
 class DB_CREATE_FAILURE : public DB_EXCEPTION
 {
   public:
@@ -197,6 +144,9 @@ class DB_CREATE_FAILURE : public DB_EXCEPTION
     DB_CREATE_FAILURE(const char* s) : DB_EXCEPTION(s) { }
 };
 
+/**
+ * @brief thrown when synchronizing the BlockchainDB to disk fails
+ */
 class DB_SYNC_FAILURE : public DB_EXCEPTION
 {
   public:
@@ -204,6 +154,9 @@ class DB_SYNC_FAILURE : public DB_EXCEPTION
     DB_SYNC_FAILURE(const char* s) : DB_EXCEPTION(s) { }
 };
 
+/**
+ * @brief thrown when a requested block does not exist
+ */
 class BLOCK_DNE : public DB_EXCEPTION
 {
   public:
@@ -211,6 +164,9 @@ class BLOCK_DNE : public DB_EXCEPTION
     BLOCK_DNE(const char* s) : DB_EXCEPTION(s) { }
 };
 
+/**
+ * @brief thrown when a block's parent does not exist (and it needed to)
+ */
 class BLOCK_PARENT_DNE : public DB_EXCEPTION
 {
   public:
@@ -218,6 +174,9 @@ class BLOCK_PARENT_DNE : public DB_EXCEPTION
     BLOCK_PARENT_DNE(const char* s) : DB_EXCEPTION(s) { }
 };
 
+/**
+ * @brief thrown when a block exists, but shouldn't, namely when adding a block
+ */
 class BLOCK_EXISTS : public DB_EXCEPTION
 {
   public:
@@ -225,6 +184,9 @@ class BLOCK_EXISTS : public DB_EXCEPTION
     BLOCK_EXISTS(const char* s) : DB_EXCEPTION(s) { }
 };
 
+/**
+ * @brief thrown when something is wrong with the block to be added
+ */
 class BLOCK_INVALID : public DB_EXCEPTION
 {
   public:
@@ -232,6 +194,9 @@ class BLOCK_INVALID : public DB_EXCEPTION
     BLOCK_INVALID(const char* s) : DB_EXCEPTION(s) { }
 };
 
+/**
+ * @brief thrown when a requested transaction does not exist
+ */
 class TX_DNE : public DB_EXCEPTION
 {
   public:
@@ -239,6 +204,9 @@ class TX_DNE : public DB_EXCEPTION
     TX_DNE(const char* s) : DB_EXCEPTION(s) { }
 };
 
+/**
+ * @brief thrown when a transaction exists, but shouldn't, namely when adding a block
+ */
 class TX_EXISTS : public DB_EXCEPTION
 {
   public:
@@ -246,6 +214,9 @@ class TX_EXISTS : public DB_EXCEPTION
     TX_EXISTS(const char* s) : DB_EXCEPTION(s) { }
 };
 
+/**
+ * @brief thrown when a requested output does not exist
+ */
 class OUTPUT_DNE : public DB_EXCEPTION
 {
   public:
@@ -253,6 +224,9 @@ class OUTPUT_DNE : public DB_EXCEPTION
     OUTPUT_DNE(const char* s) : DB_EXCEPTION(s) { }
 };
 
+/**
+ * @brief thrown when an output exists, but shouldn't, namely when adding a block
+ */
 class OUTPUT_EXISTS : public DB_EXCEPTION
 {
   public:
@@ -260,6 +234,9 @@ class OUTPUT_EXISTS : public DB_EXCEPTION
     OUTPUT_EXISTS(const char* s) : DB_EXCEPTION(s) { }
 };
 
+/**
+ * @brief thrown when a spent key image exists, but shouldn't, namely when adding a block
+ */
 class KEY_IMAGE_EXISTS : public DB_EXCEPTION
 {
   public:
@@ -272,6 +249,18 @@ class KEY_IMAGE_EXISTS : public DB_EXCEPTION
  ***********************************/
 
 
+/**
+ * @brief The BlockchainDB backing store interface declaration/contract
+ *
+ * This class provides a uniform interface for using BlockchainDB to store
+ * a blockchain.  Any implementation of this class will also implement all
+ * functions exposed here, so one can use this class without knowing what
+ * implementation is being used.  Refer to each pure virtual function's
+ * documentation here when implementing a BlockchainDB subclass.
+ *
+ * A subclass which encounters an issue should report that issue by throwing
+ * a DB_EXCEPTION which adequately conveys the issue.
+ */
 class BlockchainDB
 {
 private:
@@ -279,7 +268,22 @@ private:
    * private virtual members
    *********************************************************************/
 
-  // tells the subclass to add the block and metadata to storage
+  /**
+   * @brief add the block and metadata to the db
+   *
+   * The subclass implementing this will add the specified block and
+   * block metadata to its backing store.  This does not include its
+   * transactions, those are added in a separate step.
+   *
+   * If any of this cannot be done, the subclass should throw the corresponding
+   * subclass of DB_EXCEPTION
+   *
+   * @param blk the block to be added
+   * @param block_size the size of the block (transactions and all)
+   * @param cumulative_difficulty the accumulated difficulty after this block
+   * @param coins_generated the number of coins generated total after this block
+   * @param blk_hash the hash of the block
+   */
   virtual void add_block( const block& blk
                 , const size_t& block_size
                 , const difficulty_type& cumulative_difficulty
@@ -287,84 +291,274 @@ private:
                 , const crypto::hash& blk_hash
                 ) = 0;
 
-  // tells the subclass to remove data about the top block
+  /**
+   * @brief remove data about the top block
+   *
+   * The subclass implementing this will remove the block data from the top
+   * block in the chain.  The data to be removed is that which was added in
+   * BlockchainDB::add_block(const block& blk, const size_t& block_size, const difficulty_type& cumulative_difficulty, const uint64_t& coins_generated, const crypto::hash& blk_hash)
+   *
+   * If any of this cannot be done, the subclass should throw the corresponding
+   * subclass of DB_EXCEPTION
+   */
   virtual void remove_block() = 0;
 
-  // tells the subclass to store the transaction and its metadata
+  /**
+   * @brief store the transaction and its metadata
+   *
+   * The subclass implementing this will add the specified transaction data
+   * to its backing store.  This includes only the transaction blob itself
+   * and the other data passed here, not the separate outputs of the
+   * transaction.
+   *
+   * If any of this cannot be done, the subclass should throw the corresponding
+   * subclass of DB_EXCEPTION
+   *
+   * @param blk_hash the hash of the block containing the transaction
+   * @param tx the transaction to be added
+   * @param tx_hash the hash of the transaction
+   */
   virtual void add_transaction_data(const crypto::hash& blk_hash, const transaction& tx, const crypto::hash& tx_hash) = 0;
 
-  // tells the subclass to remove data about a transaction
+  /**
+   * @brief remove data about a transaction
+   *
+   * The subclass implementing this will remove the transaction data 
+   * for the passed transaction.  The data to be removed was added in
+   * add_transaction_data().  Additionally, current subclasses have behavior
+   * which requires the transaction itself as a parameter here.  Future
+   * implementations should note that this parameter is subject to be removed
+   * at a later time.
+   *
+   * If any of this cannot be done, the subclass should throw the corresponding
+   * subclass of DB_EXCEPTION
+   *
+   * @param tx_hash the hash of the transaction to be removed
+   * @param tx the transaction
+   */
   virtual void remove_transaction_data(const crypto::hash& tx_hash, const transaction& tx) = 0;
 
-  // tells the subclass to store an output
+  /**
+   * @brief store an output
+   *
+   * The subclass implementing this will add the output data passed to its
+   * backing store in a suitable manner.  In addition, the subclass is responsible
+   * for keeping track of the global output count in some manner, so that
+   * outputs may be indexed by the order in which they were created.  In the
+   * future, this tracking (of the number, at least) should be moved to
+   * this class, as it is necessary and the same among all BlockchainDB.
+   *
+   * This data should be stored in such a manner that the only thing needed to
+   * reverse the process is the tx_out.
+   *
+   * If any of this cannot be done, the subclass should throw the corresponding
+   * subclass of DB_EXCEPTION
+   *
+   * @param tx_hash hash of the transaction the output was created by
+   * @param tx_output the output
+   * @param local_index index of the output in its transaction
+   * @param unlock_time unlock time/height of the output
+   */
   virtual void add_output(const crypto::hash& tx_hash, const tx_out& tx_output, const uint64_t& local_index, const uint64_t unlock_time) = 0;
 
-  // tells the subclass to remove an output
+  /**
+   * @brief remove an output
+   *
+   * The subclass implementing this will remove all output data it stored
+   * in add_output().
+   *
+   * In addition, the subclass is responsible for correctly decrementing
+   * its global output counter (this may be automatic for some, such as using
+   * a database backend "count" feature).
+   *
+   * If any of this cannot be done, the subclass should throw the corresponding
+   * subclass of DB_EXCEPTION
+   *
+   * @param tx_output the output to be removed
+   */
   virtual void remove_output(const tx_out& tx_output) = 0;
 
-  // tells the subclass to store a spent key
+  /**
+   * @brief store a spent key
+   *
+   * The subclass implementing this will store the spent key image.
+   *
+   * If any of this cannot be done, the subclass should throw the corresponding
+   * subclass of DB_EXCEPTION
+   *
+   * @param k_image the spent key image to store
+   */
   virtual void add_spent_key(const crypto::key_image& k_image) = 0;
 
-  // tells the subclass to remove a spent key
+  /**
+   * @brief remove a spent key
+   *
+   * The subclass implementing this will remove the key image.
+   *
+   * If any of this cannot be done, the subclass should throw the corresponding
+   * subclass of DB_EXCEPTION
+   *
+   * @param k_image the spent key image to remove
+   */
   virtual void remove_spent_key(const crypto::key_image& k_image) = 0;
 
 
   /*********************************************************************
    * private concrete members
    *********************************************************************/
-  // private version of pop_block, for undoing if an add_block goes tits up
+  /**
+   * @brief private version of pop_block, for undoing if an add_block fails
+   *
+   * This function simply calls pop_block(block& blk, std::vector<transaction>& txs)
+   * with dummy parameters, as the returns-by-reference can be discarded.
+   */
   void pop_block();
 
-  // helper function for add_transactions, to add each individual tx
+  /**
+   * @brief helper function for add_transactions, to add each individual transaction
+   *
+   * This function is called by add_transactions() for each transaction to be
+   * added.
+   *
+   * @param blk_hash hash of the block which has the transaction
+   * @param tx the transaction to add
+   * @param tx_hash_ptr the hash of the transaction, if already calculated
+   */
   void add_transaction(const crypto::hash& blk_hash, const transaction& tx, const crypto::hash* tx_hash_ptr = NULL);
 
   // helper function to remove transaction from blockchain
+  /**
+   * @brief helper function to remove transaction from the blockchain
+   *
+   * This function encapsulates aspects of removing a transaction.
+   *
+   * @param tx_hash the hash of the transaction to be removed
+   */
   void remove_transaction(const crypto::hash& tx_hash);
 
-  uint64_t num_calls = 0;
-  uint64_t time_blk_hash = 0;
-  uint64_t time_add_block1 = 0;
-  uint64_t time_add_transaction = 0;
+  uint64_t num_calls = 0;  //!< a performance metric
+  uint64_t time_blk_hash = 0;  //!< a performance metric
+  uint64_t time_add_block1 = 0;  //!< a performance metric
+  uint64_t time_add_transaction = 0;  //!< a performance metric
 
 
 protected:
 
-  mutable uint64_t time_tx_exists = 0;
-  uint64_t time_commit1 = 0;
-  bool m_auto_remove_logs = true;
+  mutable uint64_t time_tx_exists = 0;  //!< a performance metric
+  uint64_t time_commit1 = 0;  //!< a performance metric
+  bool m_auto_remove_logs = true;  //!< whether or not to automatically remove old logs
 
   HardFork* m_hardfork;
 
 public:
 
-  // virtual dtor
+  /**
+   * @brief An empty destructor.
+   */
   virtual ~BlockchainDB() { };
 
-  // reset profiling stats
+  /**
+   * @brief reset profiling stats
+   */
   void reset_stats();
 
-  // show profiling stats
+  /**
+   * @brief show profiling stats
+   *
+   * This function prints current performance/profiling data to whichever
+   * log file(s) are set up (possibly including stdout or stderr)
+   */
   void show_stats();
 
-  // open the db at location <filename>, or create it if there isn't one.
+  /**
+   * @brief open a db, or create it if necessary.
+   *
+   * This function opens an existing database or creates it if it
+   * does not exist.
+   *
+   * The subclass implementing this will handle all file opening/creation,
+   * and is responsible for maintaining its state.
+   *
+   * The parameter <filename> may not refer to a file name, necessarily, but
+   * could be an IP:PORT for a database which needs it, and so on.  Calling it
+   * <filename> is convenient and should be descriptive enough, however.
+   *
+   * For now, db_flags are
+   * specific to the subclass being instantiated.  This is subject to change,
+   * and the db_flags parameter may be deprecated.
+   *
+   * If any of this cannot be done, the subclass should throw the corresponding
+   * subclass of DB_EXCEPTION
+   *
+   * @param filename a string referring to the BlockchainDB to open
+   * @param db_flags flags relevant to how to open/use the BlockchainDB
+   */
   virtual void open(const std::string& filename, const int db_flags = 0) = 0;
 
-  // returns true of the db is open/ready, else false
+  /**
+   * @brief Gets the current open/ready state of the BlockchainDB
+   *
+   * @return true if open/ready, otherwise false
+   */
   bool is_open() const;
 
-  // close and sync the db
+  /**
+   * @brief close the BlockchainDB
+   *
+   * At minimum, this call ensures that further use of the BlockchainDB
+   * instance will not have effect.  In any case where it is necessary
+   * to do so, a subclass implementing this will sync with disk.
+   *
+   * If any of this cannot be done, the subclass should throw the corresponding
+   * subclass of DB_EXCEPTION
+   */
   virtual void close() = 0;
 
-  // sync the db
+  /**
+   * @brief sync the BlockchainDB with disk
+   *
+   * This function should write any changes to whatever permanent backing
+   * store the subclass uses.  Example: a BlockchainDB instance which
+   * keeps the whole blockchain in RAM won't need to regularly access a
+   * disk, but should write out its state when this is called.
+   *
+   * If any of this cannot be done, the subclass should throw the corresponding
+   * subclass of DB_EXCEPTION
+   */
   virtual void sync() = 0;
 
-  // reset the db -- USE WITH CARE
+  /**
+   * @brief Remove everything from the BlockchainDB
+   *
+   * This function should completely remove all data from a BlockchainDB.
+   *
+   * Use with caution!
+   *
+   * If any of this cannot be done, the subclass should throw the corresponding
+   * subclass of DB_EXCEPTION
+   */
   virtual void reset() = 0;
 
-  // get all files used by this db (if any)
+  /**
+   * @brief get all files used by the BlockchainDB (if any)
+   *
+   * This function is largely for ease of automation, namely for unit tests.
+   *
+   * The subclass implementation should return all filenames it uses.
+   *
+   * @return a list of filenames
+   */
   virtual std::vector<std::string> get_filenames() const = 0;
 
   // return the name of the folder the db's file(s) should reside in
+  /**
+   * @brief gets the name of the folder the BlockchainDB's file(s) should be in
+   *
+   * The subclass implementation should return the name of the folder in which
+   * it stores files, or an empty string if there is none.
+   *
+   * @return the name of the folder with the BlockchainDB's files, if any.
+   */
   virtual std::string get_db_name() const = 0;
 
 
@@ -372,13 +566,86 @@ public:
   // RAII-friendly and multi-read one-write friendly locking mechanism
   //
   // acquire db lock
+  /**
+   * @brief acquires the BlockchainDB lock
+   *
+   * This function is a stub until such a time as locking is implemented at
+   * this level.
+   *
+   * The subclass implementation should return true unless implementing a
+   * locking scheme of some sort, in which case it should return true upon
+   * acquisition of the lock and block until then.
+   *
+   * If any of this cannot be done, the subclass should throw the corresponding
+   * subclass of DB_EXCEPTION
+   *
+   * @return true, unless at a future time false makes sense (timeout, etc)
+   */
   virtual bool lock() = 0;
 
   // release db lock
+  /**
+   * @brief This function releases the BlockchainDB lock
+   *
+   * The subclass, should it have implemented lock(), will release any lock
+   * held by the calling thread.  In the case of recursive locking, it should
+   * release one instance of a lock.
+   *
+   * If any of this cannot be done, the subclass should throw the corresponding
+   * subclass of DB_EXCEPTION
+   */
   virtual void unlock() = 0;
 
+  /**
+   * @brief tells the BlockchainDB to start a new "batch" of blocks
+   *
+   * If the subclass implements a batching method of caching blocks in RAM to
+   * be added to a backing store in groups, it should start a batch which will
+   * end either when <batch_num_blocks> has been added or batch_stop() has
+   * been called.  In either case, it should end the batch and write to its
+   * backing store.
+   *
+   * If a batch is already in-progress, this function should throw a DB_ERROR.
+   * This exception may change in the future if it is deemed necessary to
+   * have a more granular exception type for this scenario.
+   *
+   * If any of this cannot be done, the subclass should throw the corresponding
+   * subclass of DB_EXCEPTION
+   *
+   * @param batch_num_blocks number of blocks to batch together
+   */
   virtual void batch_start(uint64_t batch_num_blocks=0) = 0;
+
+  /**
+   * @brief ends a batch transaction
+   *
+   * If the subclass implements batching, this function should store the
+   * batch it is currently on and mark it finished.
+   *
+   * If no batch is in-progress, this function should throw a DB_ERROR.
+   * This exception may change in the future if it is deemed necessary to
+   * have a more granular exception type for this scenario.
+   *
+   * If any of this cannot be done, the subclass should throw the corresponding
+   * subclass of DB_EXCEPTION
+   */
   virtual void batch_stop() = 0;
+
+  /**
+   * @brief sets whether or not to batch transactions
+   *
+   * If the subclass implements batching, this function tells it to begin
+   * batching automatically.
+   *
+   * If the subclass implements batching and has a batch in-progress, a
+   * parameter of false should disable batching and call batch_stop() to
+   * store the current batch.
+   *
+   * If any of this cannot be done, the subclass should throw the corresponding
+   * subclass of DB_EXCEPTION
+   *
+   * @param bool batch whether or not to use batch transactions.
+   */
   virtual void set_batch_transactions(bool) = 0;
 
   virtual void block_txn_start(bool readonly=false) = 0;
@@ -388,8 +655,26 @@ public:
   virtual void set_hard_fork(HardFork* hf);
 
   // adds a block with the given metadata to the top of the blockchain, returns the new height
-  // NOTE: subclass implementations of this (or the functions it calls) need
-  // to handle undoing any partially-added blocks in the event of a failure.
+  /**
+   * @brief handles the addition of a new block to BlockchainDB
+   *
+   * This function organizes block addition and calls various functions as
+   * necessary.
+   *
+   * NOTE: subclass implementations of this (or the functions it calls) need
+   * to handle undoing any partially-added blocks in the event of a failure.
+   *
+   * If any of this cannot be done, the subclass should throw the corresponding
+   * subclass of DB_EXCEPTION
+   *
+   * @param blk the block to be added
+   * @param block_size the size of the block (transactions and all)
+   * @param cumulative_difficulty the accumulated difficulty after this block
+   * @param coins_generated the number of coins generated total after this block
+   * @param txs the transactions in the block
+   *
+   * @return the height of the chain post-addition
+   */
   virtual uint64_t add_block( const block& blk
                             , const size_t& block_size
                             , const difficulty_type& cumulative_difficulty
@@ -397,142 +682,639 @@ public:
                             , const std::vector<transaction>& txs
                             );
 
-  // return true if a block with hash <h> exists in the blockchain
+  /**
+   * @brief checks if a block exists
+   *
+   * @param h the hash of the requested block
+   *
+   * @return true of the block exists, otherwise false
+   */
   virtual bool block_exists(const crypto::hash& h) const = 0;
 
-  // return block with hash <h>
+  /**
+   * @brief fetches the block with the given hash
+   *
+   * The subclass should return the requested block.
+   *
+   * If the block does not exist, the subclass should throw BLOCK_DNE
+   *
+   * @param h the hash to look for
+   *
+   * @return the block requested
+   */
   virtual block get_block(const crypto::hash& h) const = 0;
 
-  // return the height of the block with hash <h> on the blockchain,
-  // throw if it doesn't exist
+  /**
+   * @brief gets the height of the block with a given hash
+   *
+   * The subclass should return the requested height.
+   *
+   * If the block does not exist, the subclass should throw BLOCK_DNE
+   *
+   * @param h the hash to look for
+   *
+   * @return the height
+   */
   virtual uint64_t get_block_height(const crypto::hash& h) const = 0;
 
-  // return header for block with hash <h>
+  /**
+   * @brief fetch a block header
+   *
+   * The subclass should return the block header from the block with
+   * the given hash.
+   *
+   * If the block does not exist, the subclass should throw BLOCK_DNE
+   *
+   * @param h the hash to look for
+   *
+   * @return the block header
+   */
   virtual block_header get_block_header(const crypto::hash& h) const = 0;
 
-  // return block at height <height>
+  /**
+   * @brief fetch a block by height
+   *
+   * The subclass should return the block at the given height.
+   *
+   * If the block does not exist, that is to say if the blockchain is not
+   * that high, then the subclass should throw BLOCK_DNE
+   *
+   * @param height the height to look for
+   *
+   * @return the block
+   */
   virtual block get_block_from_height(const uint64_t& height) const = 0;
 
-  // return timestamp of block at height <height>
+  /**
+   * @brief fetch a block's timestamp
+   *
+   * The subclass should return the timestamp of the block with the
+   * given height.
+   *
+   * If the block does not exist, the subclass should throw BLOCK_DNE
+   *
+   * @param height the height requested
+   *
+   * @return the timestamp
+   */
   virtual uint64_t get_block_timestamp(const uint64_t& height) const = 0;
 
-  // return timestamp of most recent block
+  /**
+   * @brief fetch the top block's timestamp
+   *
+   * The subclass should return the timestamp of the most recent block.
+   *
+   * @return the top block's timestamp
+   */
   virtual uint64_t get_top_block_timestamp() const = 0;
 
-  // return block size of block at height <height>
+  /**
+   * @brief fetch a block's size
+   *
+   * The subclass should return the size of the block with the
+   * given height.
+   *
+   * If the block does not exist, the subclass should throw BLOCK_DNE
+   *
+   * @param height the height requested
+   *
+   * @return the size
+   */
   virtual size_t get_block_size(const uint64_t& height) const = 0;
 
-  // return cumulative difficulty up to and including block at height <height>
+  /**
+   * @brief fetch a block's cumulative difficulty
+   *
+   * The subclass should return the cumulative difficulty of the block with the
+   * given height.
+   *
+   * If the block does not exist, the subclass should throw BLOCK_DNE
+   *
+   * @param height the height requested
+   *
+   * @return the cumulative difficulty
+   */
   virtual difficulty_type get_block_cumulative_difficulty(const uint64_t& height) const = 0;
 
-  // return difficulty of block at height <height>
+  /**
+   * @brief fetch a block's difficulty
+   *
+   * The subclass should return the difficulty of the block with the
+   * given height.
+   *
+   * If the block does not exist, the subclass should throw BLOCK_DNE
+   *
+   * @param height the height requested
+   *
+   * @return the difficulty
+   */
   virtual difficulty_type get_block_difficulty(const uint64_t& height) const = 0;
 
-  // return number of coins generated up to and including block at height <height>
+  /**
+   * @brief fetch a block's already generated coins
+   *
+   * The subclass should return the total coins generated as of the block
+   * with the given height.
+   *
+   * If the block does not exist, the subclass should throw BLOCK_DNE
+   *
+   * @param height the height requested
+   *
+   * @return the already generated coins
+   */
   virtual uint64_t get_block_already_generated_coins(const uint64_t& height) const = 0;
 
-  // return hash of block at height <height>
+  /**
+   * @brief fetch a block's hash
+   *
+   * The subclass should return hash of the block with the
+   * given height.
+   *
+   * If the block does not exist, the subclass should throw BLOCK_DNE
+   *
+   * @param height the height requested
+   *
+   * @return the hash
+   */
   virtual crypto::hash get_block_hash_from_height(const uint64_t& height) const = 0;
 
-  // return vector of blocks in range <h1,h2> of height (inclusively)
+  /**
+   * @brief fetch a list of blocks
+   *
+   * The subclass should return a vector of blocks with heights starting at
+   * h1 and ending at h2, inclusively.
+   *
+   * If the height range requested goes past the end of the blockchain,
+   * the subclass should throw BLOCK_DNE.  (current implementations simply
+   * don't catch this exception as thrown by methods called within)
+   *
+   * @param h1 the start height
+   * @param h2 the end height
+   *
+   * @return a vector of blocks
+   */
   virtual std::vector<block> get_blocks_range(const uint64_t& h1, const uint64_t& h2) const = 0;
 
-  // return vector of block hashes in range <h1, h2> of height (inclusively)
+  /**
+   * @brief fetch a list of block hashes
+   *
+   * The subclass should return a vector of block hashes from blocks with
+   * heights starting at h1 and ending at h2, inclusively.
+   *
+   * If the height range requested goes past the end of the blockchain,
+   * the subclass should throw BLOCK_DNE.  (current implementations simply
+   * don't catch this exception as thrown by methods called within)
+   *
+   * @param h1 the start height
+   * @param h2 the end height
+   *
+   * @return a vector of block hashes
+   */
   virtual std::vector<crypto::hash> get_hashes_range(const uint64_t& h1, const uint64_t& h2) const = 0;
 
-  // return the hash of the top block on the chain
+  /**
+   * @brief fetch the top block's hash
+   *
+   * The subclass should return the hash of the most recent block
+   *
+   * @return the top block's hash
+   */
   virtual crypto::hash top_block_hash() const = 0;
 
-  // return the block at the top of the blockchain
+  /**
+   * @brief fetch the top block
+   *
+   * The subclass should return most recent block
+   *
+   * @return the top block
+   */
   virtual block get_top_block() const = 0;
 
-  // return the height of the chain
+  /**
+   * @brief fetch the current blockchain height
+   *
+   * The subclass should return the current blockchain height
+   *
+   * @return the current blockchain height
+   */
   virtual uint64_t height() const = 0;
 
-  // pops the top block off the blockchain.
-  // Returns by reference the popped block and its associated transactions
-  //
-  // IMPORTANT:
-  // When a block is popped, the transactions associated with it need to be
-  // removed, as well as outputs and spent key images associated with
-  // those transactions.
+
+  /**
+   * <!--
+   * TODO: Rewrite (if necessary) such that all calls to remove_* are
+   *       done in concrete members of this base class.
+   * -->
+   *
+   * @brief pops the top block off the blockchain
+   *
+   * The subclass should remove the most recent block from the blockchain,
+   * along with all transactions, outputs, and other metadata created as
+   * a result of its addition to the blockchain.  Most of this is handled
+   * by the concrete members of the base class provided the subclass correctly
+   * implements remove_* functions.
+   *
+   * The subclass should return by reference the popped block and
+   * its associated transactions
+   *
+   * @param blk return-by-reference the block which was popped
+   * @param txs return-by-reference the transactions from the popped block
+   */
   virtual void pop_block(block& blk, std::vector<transaction>& txs);
 
 
-  // return true if a transaction with hash <h> exists
+  /**
+   * @brief check if a transaction with a given hash exists
+   *
+   * The subclass should check if a transaction is stored which has the
+   * given hash and return true if so, false otherwise.
+   *
+   * @param h the hash to check against
+   *
+   * @return true if the transaction exists, otherwise false
+   */
   virtual bool tx_exists(const crypto::hash& h) const = 0;
 
   // return unlock time of tx with hash <h>
+  /**
+   * @brief fetch a transaction's unlock time/height
+   *
+   * The subclass should return the stored unlock time for the transaction
+   * with the given hash.
+   *
+   * If no such transaction exists, the subclass should throw TX_DNE.
+   *
+   * @param h the hash of the requested transaction
+   *
+   * @return the unlock time/height
+   */
   virtual uint64_t get_tx_unlock_time(const crypto::hash& h) const = 0;
 
   // return tx with hash <h>
   // throw if no such tx exists
+  /**
+   * @brief fetches the transaction with the given hash
+   *
+   * The subclass should return the transaction stored which has the given
+   * hash.
+   *
+   * If the transaction does not exist, the subclass should throw TX_DNE.
+   *
+   * @param h the hash to look for
+   *
+   * @return the transaction with the given hash
+   */
   virtual transaction get_tx(const crypto::hash& h) const = 0;
 
-  // returns the total number of transactions in all blocks
+  /**
+   * @brief fetches the total number of transactions ever
+   *
+   * The subclass should return a count of all the transactions from
+   * all blocks.
+   *
+   * @return the number of transactions in the blockchain
+   */
   virtual uint64_t get_tx_count() const = 0;
 
-  // return list of tx with hashes <hlist>.
-  // TODO: decide if a missing hash means return empty list
-  // or just skip that hash
+  /**
+   * @brief fetches a list of transactions based on their hashes
+   *
+   * The subclass should attempt to fetch each transaction referred to by
+   * the hashes passed.
+   *
+   * Currently, if any of the transactions is not in BlockchainDB, the call
+   * to get_tx in the implementation will throw TX_DNE.
+   *
+   * <!-- TODO: decide if this behavior is correct for missing transactions -->
+   *
+   * @param hlist a list of hashes
+   *
+   * @return the list of transactions
+   */
   virtual std::vector<transaction> get_tx_list(const std::vector<crypto::hash>& hlist) const = 0;
 
   // returns height of block that contains transaction with hash <h>
+  /**
+   * @brief fetches the height of a transaction's block
+   *
+   * The subclass should attempt to return the height of the block containing
+   * the transaction with the given hash.
+   *
+   * If the transaction cannot be found, the subclass should throw TX_DNE.
+   *
+   * @param h the hash of the transaction
+   *
+   * @return the height of the transaction's block
+   */
   virtual uint64_t get_tx_block_height(const crypto::hash& h) const = 0;
 
   // returns the total number of outputs of amount <amount>
+  /**
+   * @brief fetches the number of outputs of a given amount
+   *
+   * The subclass should return a count of outputs of the given amount,
+   * or zero if there are none.
+   *
+   * <!-- TODO: should outputs spent with a low mixin (especially 0) be
+   * excluded from the count? -->
+   *
+   * @param amount the output amount being looked up
+   *
+   * @return the number of outputs of the given amount
+   */
   virtual uint64_t get_num_outputs(const uint64_t& amount) const = 0;
 
-  // return index of the first element (should be hidden, but isn't)
+  /**
+   * @brief return index of the first element (should be hidden, but isn't)
+   *
+   * @return the index
+   */
   virtual uint64_t get_indexing_base() const { return 0; }
 
-  // return public key for output with global output amount <amount> and index <index>
+  /**
+   * @brief get some of an output's data
+   *
+   * The subclass should return the public key, unlock time, and block height
+   * for the output with the given amount and index, collected in a struct.
+   *
+   * If the output cannot be found, the subclass should throw OUTPUT_DNE.
+   *
+   * If any of these parts cannot be found, but some are, the subclass
+   * should throw DB_ERROR with a message stating as much.
+   *
+   * @param amount the output amount
+   * @param index the output's index (indexed by amount)
+   *
+   * @return the requested output data
+   */
   virtual output_data_t get_output_key(const uint64_t& amount, const uint64_t& index) = 0;
+
+  /**
+   * @brief get some of an output's data
+   *
+   * The subclass should return the public key, unlock time, and block height
+   * for the output with the given global index, collected in a struct.
+   *
+   * If the output cannot be found, the subclass should throw OUTPUT_DNE.
+   *
+   * If any of these parts cannot be found, but some are, the subclass
+   * should throw DB_ERROR with a message stating as much.
+   *
+   * @param global_index the output's index (global)
+   *
+   * @return the requested output data
+   */
   virtual output_data_t get_output_key(const uint64_t& global_index) const = 0;
 
-  // returns the tx hash associated with an output, referenced by global output index
+  /**
+   * @brief gets an output's tx hash and index
+   *
+   * The subclass should return the hash of the transaction which created the
+   * output with the global index given, as well as its index in that transaction.
+   *
+   * @param index an output's global index
+   *
+   * @return the tx hash and output index
+   */
   virtual tx_out_index get_output_tx_and_index_from_global(const uint64_t& index) const = 0;
 
-  // returns the transaction-local reference for the output with <amount> at <index>
-  // return type is pair of tx hash and index
+  /**
+   * @brief gets an output's tx hash and index
+   *
+   * The subclass should return the hash of the transaction which created the
+   * output with the amount and index given, as well as its index in that
+   * transaction.
+   *
+   * @param amount an output amount
+   * @param index an output's amount-specific index
+   *
+   * @return the tx hash and output index
+   */
   virtual tx_out_index get_output_tx_and_index(const uint64_t& amount, const uint64_t& index) = 0;
+
+  /**
+   * @brief gets some outputs' tx hashes and indices
+   *
+   * This function is a mirror of
+   * get_output_tx_and_index(const uint64_t& amount, const uint64_t& index),
+   * but for a list of outputs rather than just one.
+   *
+   * @param amount an output amount
+   * @param offsets a list of amount-specific output indices
+   * @param indices return-by-reference a list of tx hashes and output indices (as pairs)
+   */
   virtual void get_output_tx_and_index(const uint64_t& amount, const std::vector<uint64_t> &offsets, std::vector<tx_out_index> &indices) = 0;
-  virtual void get_output_key(const uint64_t &amount, const std::vector<uint64_t> &offsets, std::vector<output_data_t> &outputs) = 0;
 
+  /**
+   * @brief gets outputs' data
+   *
+   * This function is a mirror of
+   * get_output_data(const uint64_t& amount, const uint64_t& index)
+   * but for a list of outputs rather than just one.
+   *
+   * @param amount an output amount
+   * @param offsets a list of amount-specific output indices
+   * @param outputs return-by-reference a list of outputs' metadata
+   */
+  virtual void get_output_key(const uint64_t &amount, const std::vector<uint64_t> &offsets, std::vector<output_data_t> &outputs) = 0;
+  
+  /*
+   * FIXME: Need to check with git blame and ask what this does to
+   * document it
+   */
   virtual bool can_thread_bulk_indices() const = 0;
 
-  // return a vector of indices corresponding to the global output index for
-  // each output in the transaction with hash <h>
+  /**
+   * @brief gets output indices (global) for a transaction's outputs
+   *
+   * The subclass should fetch the global output indices for each output
+   * in the transaction with the given hash.
+   *
+   * If the transaction does not exist, the subclass should throw TX_DNE.
+   *
+   * If an output cannot be found, the subclass should throw OUTPUT_DNE.
+   *
+   * @param h a transaction hash
+   *
+   * @return a list of global output indices
+   */
   virtual std::vector<uint64_t> get_tx_output_indices(const crypto::hash& h) const = 0;
-  // return a vector of indices corresponding to the amount output index for
-  // each output in the transaction with hash <h>
+
+  /**
+   * @brief gets output indices (amount-specific) for a transaction's outputs
+   *
+   * The subclass should fetch the amount-specific output indices for each
+   * output in the transaction with the given hash.
+   *
+   * If the transaction does not exist, the subclass should throw TX_DNE.
+   *
+   * If an output cannot be found, the subclass should throw OUTPUT_DNE.
+   *
+   * @param h a transaction hash
+   *
+   * @return a list of amount-specific output indices
+   */
   virtual std::vector<uint64_t> get_tx_amount_output_indices(const crypto::hash& h) const = 0;
 
-  // returns true if key image <img> is present in spent key images storage
+  /**
+   * @brief check if a key image is stored as spent
+   *
+   * @param img the key image to check for
+   *
+   * @return true if the image is present, otherwise false
+   */
   virtual bool has_key_image(const crypto::key_image& img) const = 0;
 
+  /**
+   * @brief runs a function over all key images stored
+   *
+   * The subclass should run the passed function for each key image it has
+   * stored, passing the key image as its parameter.
+   *
+   * If any call to the function returns false, the subclass should return
+   * false.  Otherwise, the subclass returns true.
+   *
+   * @param std::function fn the function to run
+   *
+   * @return false if the function returns false for any key image, otherwise true
+   */
   virtual bool for_all_key_images(std::function<bool(const crypto::key_image&)>) const = 0;
+
+  /**
+   * @brief runs a function over all blocks stored
+   *
+   * The subclass should run the passed function for each block it has
+   * stored, passing (block_height, block_hash, block) as its parameters.
+   *
+   * If any call to the function returns false, the subclass should return
+   * false.  Otherwise, the subclass returns true.
+   *
+   * The subclass should throw DB_ERROR if any of the expected values are
+   * not found.  Current implementations simply return false.
+   *
+   * @param std::function fn the function to run
+   *
+   * @return false if the function returns false for any block, otherwise true
+   */
   virtual bool for_all_blocks(std::function<bool(uint64_t, const crypto::hash&, const cryptonote::block&)>) const = 0;
+
+  /**
+   * @brief runs a function over all transactions stored
+   *
+   * The subclass should run the passed function for each transaction it has
+   * stored, passing (transaction_hash, transaction) as its parameters.
+   *
+   * If any call to the function returns false, the subclass should return
+   * false.  Otherwise, the subclass returns true.
+   *
+   * The subclass should throw DB_ERROR if any of the expected values are
+   * not found.  Current implementations simply return false.
+   *
+   * @param std::function fn the function to run
+   *
+   * @return false if the function returns false for any transaction, otherwise true
+   */
   virtual bool for_all_transactions(std::function<bool(const crypto::hash&, const cryptonote::transaction&)>) const = 0;
+
+  /**
+   * @brief runs a function over all outputs stored
+   *
+   * The subclass should run the passed function for each output it has
+   * stored, passing (amount, transaction_hash, tx_local_output_index)
+   * as its parameters.
+   *
+   * If any call to the function returns false, the subclass should return
+   * false.  Otherwise, the subclass returns true.
+   *
+   * The subclass should throw DB_ERROR if any of the expected values are
+   * not found.  Current implementations simply return false.
+   *
+   * @param std::function f the function to run
+   *
+   * @return false if the function returns false for any output, otherwise true
+   */
   virtual bool for_all_outputs(std::function<bool(uint64_t amount, const crypto::hash &tx_hash, size_t tx_idx)> f) const = 0;
 
+
+  //
   // Hard fork related storage
+  //
+
+  // FIXME: verify that this is all correct
+  //      - TW
+  /**
+   * @brief sets the height at which a hard fork has been voted to happen
+   *
+   *
+   * @param version the version voted to fork to
+   * @param height the height of the first block on the new fork
+   */
   virtual void set_hard_fork_starting_height(uint8_t version, uint64_t height) = 0;
+
+  /**
+   * @brief gets the height at which a hard fork has been voted to happen
+   *
+   * @param version the version to check
+   *
+   * @return the height at which the hard fork was accepted, if it has been,
+   * otherwise max(uint64_t)
+   */
   virtual uint64_t get_hard_fork_starting_height(uint8_t version) const = 0;
+
+  /**
+   * @brief sets which hardfork version a height is on
+   *
+   * @param height the height
+   * @param version the version
+   */
   virtual void set_hard_fork_version(uint64_t height, uint8_t version) = 0;
+
+  /**
+   * @brief checks which hardfork version a height is on
+   *
+   * @param height the height
+   *
+   * @return the version
+   */
   virtual uint8_t get_hard_fork_version(uint64_t height) const = 0;
+
+  /**
+   * @brief verify hard fork info in database
+   */
   virtual void check_hard_fork_info() = 0;
+
+  /**
+   * @brief delete hard fork info from database
+   */
   virtual void drop_hard_fork_info() = 0;
 
+  /**
+   * @brief is BlockchainDB in read-only mode?
+   *
+   * @return true if in read-only mode, otherwise false
+   */
   virtual bool is_read_only() const = 0;
 
-  // fix up anything that may be wrong due to past bugs
+  // TODO: this should perhaps be (or call) a series of functions which
+  // progressively update through version updates
+  /**
+   * @brief fix up anything that may be wrong due to past bugs
+   */
   virtual void fixup();
 
+  /**
+   * @brief set whether or not to automatically remove logs
+   *
+   * This function is only relevant for one implementation (BlockchainBDB), but
+   * is here to keep BlockchainDB users implementation-agnostic.
+   *
+   * @param auto_remove whether or not to auto-remove logs
+   */
   void set_auto_remove_logs(bool auto_remove) { m_auto_remove_logs = auto_remove; }
 
-  bool m_open;
-  mutable epee::critical_section m_synchronization_lock;
+  bool m_open;  //!< Whether or not the BlockchainDB is open/ready for use
+  mutable epee::critical_section m_synchronization_lock;  //!< A lock, currently for when BlockchainLMDB needs to resize the backing db file
+
 };  // class BlockchainDB
 
 
diff --git a/src/cryptonote_core/CMakeLists.txt b/src/cryptonote_core/CMakeLists.txt
index 88eea1d7e..205356797 100644
--- a/src/cryptonote_core/CMakeLists.txt
+++ b/src/cryptonote_core/CMakeLists.txt
@@ -31,7 +31,6 @@ set(cryptonote_core_sources
   blockchain_storage.cpp
   blockchain.cpp
   checkpoints.cpp
-  checkpoints_create.cpp
   cryptonote_basic_impl.cpp
   cryptonote_core.cpp
   cryptonote_format_utils.cpp
@@ -49,7 +48,6 @@ set(cryptonote_core_private_headers
   blockchain_storage_boost_serialization.h
   blockchain.h
   checkpoints.h
-  checkpoints_create.h
   connection_context.h
   cryptonote_basic.h
   cryptonote_basic_impl.h
diff --git a/src/cryptonote_core/blockchain.cpp b/src/cryptonote_core/blockchain.cpp
index 131f56a4d..2f42e1db5 100644
--- a/src/cryptonote_core/blockchain.cpp
+++ b/src/cryptonote_core/blockchain.cpp
@@ -49,7 +49,7 @@
 #include "common/boost_serialization_helper.h"
 #include "warnings.h"
 #include "crypto/hash.h"
-#include "cryptonote_core/checkpoints_create.h"
+#include "cryptonote_core/checkpoints.h"
 #include "cryptonote_core/cryptonote_core.h"
 #if defined(PER_BLOCK_CHECKPOINT)
 #include "blocks/blocks.h"
@@ -840,7 +840,7 @@ bool Blockchain::switch_to_alternative_blockchain(std::list<blocks_ext_by_hash::
     }
   }
 
-  //removing alt_chain entries from alternative chain
+  //removing alt_chain entries from alternative chains container
   for (auto ch_ent: alt_chain)
   {
     m_alternative_chains.erase(ch_ent);
@@ -991,8 +991,7 @@ bool Blockchain::validate_miner_transaction(const block& b, size_t cumulative_bl
   return true;
 }
 //------------------------------------------------------------------
-// get the block sizes of the last <count> blocks, starting at <from_height>
-// and return by reference <sz>.
+// get the block sizes of the last <count> blocks, and return by reference <sz>.
 void Blockchain::get_last_n_blocks_sizes(std::vector<size_t>& sz, size_t count) const
 {
   LOG_PRINT_L3("Blockchain::" << __func__);
@@ -1408,6 +1407,10 @@ bool Blockchain::get_blocks(uint64_t start_offset, size_t count, std::list<block
 //TODO: This function *looks* like it won't need to be rewritten
 //      to use BlockchainDB, as it calls other functions that were,
 //      but it warrants some looking into later.
+//
+//FIXME: This function appears to want to return false if any transactions
+//       that belong with blocks are missing, but not if blocks themselves
+//       are missing.
 bool Blockchain::handle_get_objects(NOTIFY_REQUEST_GET_OBJECTS::request& arg, NOTIFY_RESPONSE_GET_OBJECTS::request& rsp)
 {
   LOG_PRINT_L3("Blockchain::" << __func__);
@@ -1421,6 +1424,9 @@ bool Blockchain::handle_get_objects(NOTIFY_REQUEST_GET_OBJECTS::request& arg, NO
   {
     std::list<crypto::hash> missed_tx_ids;
     std::list<transaction> txs;
+
+    // FIXME: s/rsp.missed_ids/missed_tx_id/ ?  Seems like rsp.missed_ids
+    //        is for missed blocks, not missed transactions as well.
     get_transactions(bl.tx_hashes, txs, missed_tx_ids);
 
     if (missed_tx_ids.size() != 0)
@@ -1668,6 +1674,8 @@ uint64_t Blockchain::block_difficulty(uint64_t i) const
   return 0;
 }
 //------------------------------------------------------------------
+//TODO: return type should be void, throw on exception
+//       alternatively, return true only if no blocks missed
 template<class t_ids_container, class t_blocks_container, class t_missed_container>
 bool Blockchain::get_blocks(const t_ids_container& block_ids, t_blocks_container& blocks, t_missed_container& missed_bs) const
 {
@@ -1692,6 +1700,8 @@ bool Blockchain::get_blocks(const t_ids_container& block_ids, t_blocks_container
   return true;
 }
 //------------------------------------------------------------------
+//TODO: return type should be void, throw on exception
+//       alternatively, return true only if no transactions missed
 template<class t_ids_container, class t_tx_container, class t_missed_container>
 bool Blockchain::get_transactions(const t_ids_container& txs_ids, t_tx_container& txs, t_missed_container& missed_txs) const
 {
@@ -1708,7 +1718,6 @@ bool Blockchain::get_transactions(const t_ids_container& txs_ids, t_tx_container
     {
       missed_txs.push_back(tx_hash);
     }
-    //FIXME: is this the correct way to handle this?
     catch (const std::exception& e)
     {
       return false;
@@ -1965,6 +1974,11 @@ bool Blockchain::get_tx_outputs_gindexs(const crypto::hash& tx_id, std::vector<u
   return true;
 }
 //------------------------------------------------------------------
+//FIXME: it seems this function is meant to be merely a wrapper around
+//       another function of the same name, this one adding one bit of
+//       functionality.  Should probably move anything more than that
+//       (getting the hash of the block at height max_used_block_id)
+//       to the other function to keep everything in one place.
 // This function overloads its sister function with
 // an extra value (hash of highest block that holds an output used as input)
 // as a return-by-reference.
@@ -1975,6 +1989,7 @@ bool Blockchain::check_tx_inputs(const transaction& tx, uint64_t& max_used_block
 
 #if defined(PER_BLOCK_CHECKPOINT)
   // check if we're doing per-block checkpointing
+  // FIXME: investigate why this block returns
   if (m_db->height() < m_blocks_hash_check.size() && kept_by_block)
   {
     TIME_MEASURE_START(a);
@@ -2038,6 +2053,10 @@ bool Blockchain::have_tx_keyimges_as_spent(const transaction &tx) const
 }
 //------------------------------------------------------------------
 // This function validates transaction inputs and their keys.
+// FIXME: consider moving functionality specific to one input into
+//        check_tx_input() rather than here, and use this function simply
+//        to iterate the inputs as necessary (splitting the task
+//        using threads, etc.)
 bool Blockchain::check_tx_inputs(const transaction& tx, uint64_t* pmax_used_block_height)
 {
   LOG_PRINT_L3("Blockchain::" << __func__);
@@ -2320,7 +2339,7 @@ bool Blockchain::check_tx_input(const txin_to_key& txin, const crypto::hash& tx_
 
   output_keys.clear();
 
-  //check ring signature
+  // collect output keys
   outputs_visitor vi(output_keys, *this);
   if (!scan_outputkeys_for_indexes(txin, vi, tx_prefix_hash, pmax_related_block_height))
   {
@@ -2617,6 +2636,11 @@ leave:
     txs.push_back(tx);
     TIME_MEASURE_START(dd);
 
+    // FIXME: the storage should not be responsible for validation.
+    //        If it does any, it is merely a sanity check.
+    //        Validation is the purview of the Blockchain class
+    //        - TW
+    //
     // ND: this is not needed, db->add_block() checks for duplicate k_images and fails accordingly.
     // if (!check_for_double_spend(tx, keys))
     // {
@@ -2797,6 +2821,8 @@ bool Blockchain::add_new_block(const block& bl_, block_verification_context& bvc
   return handle_block_to_main_chain(bl, id, bvc);
 }
 //------------------------------------------------------------------
+//TODO: Refactor, consider returning a failure height and letting
+//      caller decide course of action.
 void Blockchain::check_against_checkpoints(const checkpoints& points, bool enforce)
 {
   const auto& pts = points.get_points();
@@ -2834,16 +2860,16 @@ void Blockchain::check_against_checkpoints(const checkpoints& points, bool enfor
 // with an existing checkpoint.
 bool Blockchain::update_checkpoints(const std::string& file_path, bool check_dns)
 {
-  if (!cryptonote::load_checkpoints_from_json(m_checkpoints, file_path))
+  if (!m_checkpoints.load_checkpoints_from_json(file_path))
   {
-    return false;
+      return false;
   }
 
   // if we're checking both dns and json, load checkpoints from dns.
   // if we're not hard-enforcing dns checkpoints, handle accordingly
   if (m_enforce_dns_checkpoints && check_dns)
   {
-    if (!cryptonote::load_checkpoints_from_dns(m_checkpoints))
+    if (!m_checkpoints.load_checkpoints_from_dns())
     {
       return false;
     }
@@ -2851,7 +2877,7 @@ bool Blockchain::update_checkpoints(const std::string& file_path, bool check_dns
   else if (check_dns)
   {
     checkpoints dns_points;
-    cryptonote::load_checkpoints_from_dns(dns_points);
+    dns_points.load_checkpoints_from_dns();
     if (m_checkpoints.check_for_conflicts(dns_points))
     {
       check_against_checkpoints(dns_points, false);
@@ -2878,6 +2904,8 @@ void Blockchain::block_longhash_worker(const uint64_t height, const std::vector<
   TIME_MEASURE_START(t);
   slow_hash_allocate_state();
 
+  //FIXME: height should be changing here, as get_block_longhash expects
+  //       the height of the block passed to it
   for (const auto & block : blocks)
   {
     crypto::hash id = get_block_hash(block);
@@ -2933,6 +2961,7 @@ bool Blockchain::cleanup_handle_incoming_blocks(bool force_sync)
 }
 
 //------------------------------------------------------------------
+//FIXME: unused parameter txs
 void Blockchain::output_scan_worker(const uint64_t amount, const std::vector<uint64_t> &offsets, std::vector<output_data_t> &outputs, std::unordered_map<crypto::hash, cryptonote::transaction> &txs) const
 {
   try
diff --git a/src/cryptonote_core/blockchain.h b/src/cryptonote_core/blockchain.h
index ab2c8f9e8..94def1aa9 100644
--- a/src/cryptonote_core/blockchain.h
+++ b/src/cryptonote_core/blockchain.h
@@ -60,11 +60,14 @@ namespace cryptonote
   class tx_memory_pool;
   struct test_options;
 
+  /** Declares ways in which the BlockchainDB backend should be told to sync
+   *
+   */
   enum blockchain_db_sync_mode
   {
-    db_sync,
-    db_async,
-    db_nosync
+    db_sync,  //!< handle syncing calls instead of the backing db, synchronously
+    db_async, //!< handle syncing calls instead of the backing db, asynchronously
+    db_nosync //!< Leave syncing up to the backing db (safest, but slowest because of disk I/O)
   };
 
   /************************************************************************/
@@ -73,6 +76,9 @@ namespace cryptonote
   class Blockchain
   {
   public:
+    /**
+     * @brief Now-defunct (TODO: remove) struct from in-memory blockchain
+     */
     struct transaction_chain_entry
     {
       transaction tx;
@@ -81,127 +87,697 @@ namespace cryptonote
       std::vector<uint64_t> m_global_output_indexes;
     };
 
+    /**
+     * @brief container for passing a block and metadata about it on the blockchain
+     */
     struct block_extended_info
     {
-      block   bl;
-      uint64_t height;
-      size_t block_cumulative_size;
-      difficulty_type cumulative_difficulty;
-      uint64_t already_generated_coins;
+      block   bl; //!< the block
+      uint64_t height; //!< the height of the block in the blockchain
+      size_t block_cumulative_size; //!< the size (in bytes) of the block
+      difficulty_type cumulative_difficulty; //!< the accumulated difficulty after that block
+      uint64_t already_generated_coins; //!< the total coins minted after that block
     };
 
+    /**
+     * @brief Blockchain constructor
+     *
+     * @param tx_pool a reference to the transaction pool to be kept by the Blockchain
+     */
     Blockchain(tx_memory_pool& tx_pool);
 
+    /**
+     * @brief Initialize the Blockchain state
+     *
+     * @param db a pointer to the backing store to use for the blockchain
+     * @param testnet true if on testnet, else false
+     * @param test_options test parameters
+     *
+     * @return true on success, false if any initialization steps fail
+     */
     bool init(BlockchainDB* db, const bool testnet = false, const cryptonote::test_options *test_options = NULL);
+
+    /**
+     * @brief Initialize the Blockchain state
+     *
+     * @param db a pointer to the backing store to use for the blockchain
+     * @param hf a structure containing hardfork information
+     * @param testnet true if on testnet, else false
+     *
+     * @return true on success, false if any initialization steps fail
+     */
     bool init(BlockchainDB* db, HardFork*& hf, const bool testnet = false);
+
+    /**
+     * @brief Uninitializes the blockchain state
+     *
+     * Saves to disk any state that needs to be maintained
+     *
+     * @return true on success, false if any uninitialization steps fail
+     */
     bool deinit();
 
+    /**
+     * @brief assign a set of blockchain checkpoint hashes
+     *
+     * @param chk_pts the set of checkpoints to assign
+     */
     void set_checkpoints(checkpoints&& chk_pts) { m_checkpoints = chk_pts; }
 
-    //bool push_new_block();
+    /**
+     * @brief get blocks and transactions from blocks based on start height and count
+     *
+     * @param start_offset the height on the blockchain to start at
+     * @param count the number of blocks to get, if there are as many after start_offset
+     * @param blocks return-by-reference container to put result blocks in
+     * @param txs return-by-reference container to put result transactions in
+     *
+     * @return false if start_offset > blockchain height, else true
+     */
     bool get_blocks(uint64_t start_offset, size_t count, std::list<block>& blocks, std::list<transaction>& txs) const;
+
+    /**
+     * @brief get blocks from blocks based on start height and count
+     *
+     * @param start_offset the height on the blockchain to start at
+     * @param count the number of blocks to get, if there are as many after start_offset
+     * @param blocks return-by-reference container to put result blocks in
+     *
+     * @return false if start_offset > blockchain height, else true
+     */
     bool get_blocks(uint64_t start_offset, size_t count, std::list<block>& blocks) const;
+
+    /**
+     * @brief compiles a list of all blocks stored as alternative chains
+     *
+     * @param blocks return-by-reference container to put result blocks in
+     *
+     * @return true
+     */
     bool get_alternative_blocks(std::list<block>& blocks) const;
+
+    /**
+     * @brief returns the number of alternative blocks stored
+     *
+     * @return the number of alternative blocks stored
+     */
     size_t get_alternative_blocks_count() const;
+
+    /**
+     * @brief gets a block's hash given a height
+     *
+     * @param height the height of the block
+     *
+     * @return the hash of the block at the requested height, or a zeroed hash if there is no such block
+     */
     crypto::hash get_block_id_by_height(uint64_t height) const;
+
+    /**
+     * @brief gets the block with a given hash
+     *
+     * @param h the hash to look for
+     * @param blk return-by-reference variable to put result block in
+     *
+     * @return true if the block was found, else false
+     */
     bool get_block_by_hash(const crypto::hash &h, block &blk) const;
+
+    /**
+     * @brief get all block hashes (main chain, alt chains, and invalid blocks)
+     *
+     * @param main return-by-reference container to put result main chain blocks' hashes in
+     * @param alt return-by-reference container to put result alt chain blocks' hashes in
+     * @param invalid return-by-reference container to put result invalid blocks' hashes in
+     */
     void get_all_known_block_ids(std::list<crypto::hash> &main, std::list<crypto::hash> &alt, std::list<crypto::hash> &invalid) const;
+
+    /**
+     * @brief performs some preprocessing on a group of incoming blocks to speed up verification
+     *
+     * @param blocks a list of incoming blocks
+     *
+     * @return false on erroneous blocks, else true
+     */
     bool prepare_handle_incoming_blocks(const std::list<block_complete_entry>  &blocks);
+
+    /**
+     * @brief incoming blocks post-processing, cleanup, and disk sync
+     *
+     * @param force_sync if true, and Blockchain is handling syncing to disk, always sync
+     *
+     * @return true
+     */
     bool cleanup_handle_incoming_blocks(bool force_sync = false);
 
+    /**
+     * @brief search the blockchain for a transaction by hash
+     *
+     * @param id the hash to search for
+     *
+     * @return true if the tx exists, else false
+     */
     bool have_tx(const crypto::hash &id) const;
+
+    /**
+     * @brief check if any key image in a transaction has already been spent
+     *
+     * @param tx the transaction to check
+     *
+     * @return true if any key image is already spent in the blockchain, else false
+     */
     bool have_tx_keyimges_as_spent(const transaction &tx) const;
+
+    /**
+     * @brief check if a key image is already spent on the blockchain
+     *
+     * Whenever a transaction output is used as an input for another transaction
+     * (a true input, not just one of a mixing set), a key image is generated
+     * and stored in the transaction in order to prevent double spending.  If
+     * this key image is seen again, the transaction using it is rejected.
+     *
+     * @param key_im the key image to search for
+     *
+     * @return true if the key image is already spent in the blockchain, else false
+     */
     bool have_tx_keyimg_as_spent(const crypto::key_image &key_im) const;
 
+    /**
+     * @brief get the current height of the blockchain
+     *
+     * @return the height
+     */
     uint64_t get_current_blockchain_height() const;
+
+    /**
+     * @brief get the hash of the most recent block on the blockchain
+     *
+     * @return the hash
+     */
     crypto::hash get_tail_id() const;
+
+    /**
+     * @brief get the height and hash of the most recent block on the blockchain
+     *
+     * @param height return-by-reference variable to store the height in
+     *
+     * @return the hash
+     */
     crypto::hash get_tail_id(uint64_t& height) const;
+
+    /**
+     * @brief returns the difficulty target the next block to be added must meet
+     *
+     * @return the target
+     */
     difficulty_type get_difficulty_for_next_block();
+
+    /**
+     * @brief adds a block to the blockchain
+     *
+     * Adds a new block to the blockchain.  If the block's parent is not the
+     * current top of the blockchain, the block may be added to an alternate
+     * chain.  If the block does not belong, is already in the blockchain
+     * or an alternate chain, or is invalid, return false.
+     *
+     * @param bl_ the block to be added
+     * @param bvc metadata about the block addition's success/failure
+     *
+     * @return true on successful addition to the blockchain, else false
+     */
     bool add_new_block(const block& bl_, block_verification_context& bvc);
+
+    /**
+     * @brief clears the blockchain and starts a new one
+     *
+     * @param b the first block in the new chain (the genesis block)
+     *
+     * @return true on success, else false
+     */
     bool reset_and_set_genesis_block(const block& b);
+
+    /**
+     * @brief creates a new block to mine against
+     *
+     * @param b return-by-reference block to be filled in
+     * @param miner_address address new coins for the block will go to
+     * @param di return-by-reference tells the miner what the difficulty target is
+     * @param height return-by-reference tells the miner what height it's mining against
+     * @param ex_nonce extra data to be added to the miner transaction's extra
+     *
+     * @return true if block template filled in successfully, else false
+     */
     bool create_block_template(block& b, const account_public_address& miner_address, difficulty_type& di, uint64_t& height, const blobdata& ex_nonce);
+
+    /**
+     * @brief checks if a block is known about with a given hash
+     *
+     * This function checks the main chain, alternate chains, and invalid blocks
+     * for a block with the given hash
+     *
+     * @param id the hash to search for
+     *
+     * @return true if the block is known, else false
+     */
     bool have_block(const crypto::hash& id) const;
+
+    /**
+     * @brief gets the total number of transactions on the main chain
+     *
+     * @return the number of transactions on the main chain
+     */
     size_t get_total_transactions() const;
+
+    /**
+     * @brief gets the hashes for a subset of the blockchain
+     *
+     * puts into list <ids> a list of hashes representing certain blocks
+     * from the blockchain in reverse chronological order
+     *
+     * the blocks chosen, at the time of this writing, are:
+     *   the most recent 11
+     *   powers of 2 less recent from there, so 13, 17, 25, etc...
+     *
+     * @param ids return-by-reference list to put the resulting hashes in
+     *
+     * @return true
+     */
     bool get_short_chain_history(std::list<crypto::hash>& ids) const;
+
+    /**
+     * @brief get recent block hashes for a foreign chain
+     *
+     * Find the split point between us and foreign blockchain and return
+     * (by reference) the most recent common block hash along with up to
+     * BLOCKS_IDS_SYNCHRONIZING_DEFAULT_COUNT additional (more recent) hashes.
+     *
+     * @param qblock_ids the foreign chain's "short history" (see get_short_chain_history)
+     * @param resp return-by-reference the split height and subsequent blocks' hashes
+     *
+     * @return true if a block found in common, else false
+     */
     bool find_blockchain_supplement(const std::list<crypto::hash>& qblock_ids, NOTIFY_RESPONSE_CHAIN_ENTRY::request& resp) const;
+
+    /**
+     * @brief find the most recent common point between ours and a foreign chain
+     *
+     * This function takes a list of block hashes from another node
+     * on the network to find where the split point is between us and them.
+     * This is used to see what to send another node that needs to sync.
+     *
+     * @param qblock_ids the foreign chain's "short history" (see get_short_chain_history)
+     * @param starter_offset return-by-reference the most recent common block's height
+     *
+     * @return true if a block found in common, else false
+     */
     bool find_blockchain_supplement(const std::list<crypto::hash>& qblock_ids, uint64_t& starter_offset) const;
+
+    /**
+     * @brief get recent blocks for a foreign chain
+     *
+     * This function gets recent blocks relative to a foreign chain, starting either at
+     * a requested height or whatever height is the most recent ours and the foreign
+     * chain have in common.
+     *
+     * @param req_start_block if non-zero, specifies a start point (otherwise find most recent commonality)
+     * @param qblock_ids the foreign chain's "short history" (see get_short_chain_history)
+     * @param blocks return-by-reference the blocks and their transactions
+     * @param total_height return-by-reference our current blockchain height
+     * @param start_height return-by-reference the height of the first block returned
+     * @param max_count the max number of blocks to get
+     *
+     * @return true if a block found in common or req_start_block specified, else false
+     */
     bool find_blockchain_supplement(const uint64_t req_start_block, const std::list<crypto::hash>& qblock_ids, std::list<std::pair<block, std::list<transaction> > >& blocks, uint64_t& total_height, uint64_t& start_height, size_t max_count) const;
+
+    /**
+     * @brief retrieves a set of blocks and their transactions, and possibly other transactions
+     *
+     * the request object encapsulates a list of block hashes and a (possibly empty) list of
+     * transaction hashes.  for each block hash, the block is fetched along with all of that
+     * block's transactions.  Any transactions requested separately are fetched afterwards.
+     *
+     * @param arg the request
+     * @param rsp return-by-reference the response to fill in
+     *
+     * @return true unless any blocks or transactions are missing
+     */
     bool handle_get_objects(NOTIFY_REQUEST_GET_OBJECTS::request& arg, NOTIFY_RESPONSE_GET_OBJECTS::request& rsp);
-    bool handle_get_objects(const COMMAND_RPC_GET_RANDOM_OUTPUTS_FOR_AMOUNTS::request& req, COMMAND_RPC_GET_RANDOM_OUTPUTS_FOR_AMOUNTS::response& res);
+
+    /**
+     * @brief gets random outputs to mix with
+     *
+     * This function takes an RPC request for outputs to mix with
+     * and creates an RPC response with the resultant output indices.
+     *
+     * Outputs to mix with are randomly selected from the utxo set
+     * for each output amount in the request.
+     *
+     * @param req the output amounts and number of mixins to select
+     * @param res return-by-reference the resultant output indices
+     *
+     * @return true
+     */
     bool get_random_outs_for_amounts(const COMMAND_RPC_GET_RANDOM_OUTPUTS_FOR_AMOUNTS::request& req, COMMAND_RPC_GET_RANDOM_OUTPUTS_FOR_AMOUNTS::response& res) const;
+
+    /**
+     * @brief gets the global indices for outputs from a given transaction
+     *
+     * This function gets the global indices for all outputs belonging
+     * to a specific transaction.
+     *
+     * @param tx_id the hash of the transaction to fetch indices for
+     * @param indexs return-by-reference the global indices for the transaction's outputs
+     *
+     * @return false if the transaction does not exist, or if no indices are found, otherwise true
+     */
     bool get_tx_outputs_gindexs(const crypto::hash& tx_id, std::vector<uint64_t>& indexs) const;
+
+    /**
+     * @brief stores the blockchain
+     *
+     * If Blockchain is handling storing of the blockchain (rather than BlockchainDB),
+     * this initiates a blockchain save.
+     *
+     * @return true unless saving the blockchain fails
+     */
     bool store_blockchain();
 
+    /**
+     * @brief validates a transaction's inputs
+     *
+     * validates a transaction's inputs as correctly used and not previously
+     * spent.  also returns the hash and height of the most recent block
+     * which contains an output that was used as an input to the transaction.
+     *
+     * @param tx the transaction to validate
+     * @param pmax_used_block_height return-by-reference block height of most recent input
+     * @param max_used_block_id return-by-reference block hash of most recent input
+     * @param kept_by_block whether or not the transaction is from a previously-verified block
+     *
+     * @return false if any input is invalid, otherwise true
+     */
     bool check_tx_inputs(const transaction& tx, uint64_t& pmax_used_block_height, crypto::hash& max_used_block_id, bool kept_by_block = false);
+
+    /**
+     * @brief check that a transaction's outputs conform to current standards
+     *
+     * This function checks, for example at the time of this writing, that
+     * each output is of the form a * 10^b (phrased differently, that if
+     * written out would have only one non-zero digit in base 10).
+     *
+     * @param tx the transaction to check the outputs of
+     *
+     * @return false if any outputs do not conform, otherwise true
+     */
     bool check_tx_outputs(const transaction& tx);
+
+    /**
+     * @brief gets the blocksize limit based on recent blocks
+     *
+     * @return the limit
+     */
     uint64_t get_current_cumulative_blocksize_limit() const;
+
+    /**
+     * @brief checks if the blockchain is currently being stored
+     *
+     * Note: this should be meaningless in cases where Blockchain is not
+     * directly managing saving the blockchain to disk.
+     *
+     * @return true if Blockchain is having the chain stored currently, else false
+     */
     bool is_storing_blockchain()const{return m_is_blockchain_storing;}
+
+    /**
+     * @brief gets the difficulty of the block with a given height
+     *
+     * @param i the height
+     *
+     * @return the difficulty
+     */
     uint64_t block_difficulty(uint64_t i) const;
 
+    /**
+     * @brief gets blocks based on a list of block hashes
+     *
+     * @tparam t_ids_container a standard-iterable container
+     * @tparam t_blocks_container a standard-iterable container
+     * @tparam t_missed_container a standard-iterable container
+     * @param block_ids a container of block hashes for which to get the corresponding blocks
+     * @param blocks return-by-reference a container to store result blocks in
+     * @param missed_bs return-by-reference a container to store missed blocks in
+     *
+     * @return false if an unexpected exception occurs, else true
+     */
     template<class t_ids_container, class t_blocks_container, class t_missed_container>
     bool get_blocks(const t_ids_container& block_ids, t_blocks_container& blocks, t_missed_container& missed_bs) const;
 
+    /**
+     * @brief gets transactions based on a list of transaction hashes
+     *
+     * @tparam t_ids_container a standard-iterable container
+     * @tparam t_tx_container a standard-iterable container
+     * @tparam t_missed_container a standard-iterable container
+     * @param txs_ids a container of hashes for which to get the corresponding transactions
+     * @param txs return-by-reference a container to store result transactions in
+     * @param missed_txs return-by-reference a container to store missed transactions in
+     *
+     * @return false if an unexpected exception occurs, else true
+     */
     template<class t_ids_container, class t_tx_container, class t_missed_container>
     bool get_transactions(const t_ids_container& txs_ids, t_tx_container& txs, t_missed_container& missed_txs) const;
 
+
     //debug functions
+
+    /**
+     * @brief prints data about a snippet of the blockchain
+     *
+     * if start_index is greater than the blockchain height, do nothing
+     *
+     * @param start_index height on chain to start at
+     * @param end_index height on chain to end at
+     */
     void print_blockchain(uint64_t start_index, uint64_t end_index) const;
+
+    /**
+     * @brief prints every block's hash
+     *
+     * WARNING: This function will absolutely crush a terminal in prints, so
+     * it is recommended to redirect this output to a log file (or null sink
+     * if a log file is already set up, as should be the default)
+     */
     void print_blockchain_index() const;
+
+    /**
+     * @brief currently does nothing, candidate for removal
+     *
+     * @param file
+     */
     void print_blockchain_outs(const std::string& file) const;
 
+    /**
+     * @brief check the blockchain against a set of checkpoints
+     *
+     * If a block fails a checkpoint and enforce is enabled, the blockchain
+     * will be rolled back to two blocks prior to that block.  If enforce
+     * is disabled, as is currently the default case with DNS-based checkpoints,
+     * an error will be printed to the user but no other action will be taken.
+     *
+     * @param points the checkpoints to check against
+     * @param enforce whether or not to take action on failure
+     */
     void check_against_checkpoints(const checkpoints& points, bool enforce);
+
+    /**
+     * @brief configure whether or not to enforce DNS-based checkpoints
+     *
+     * @param enforce the new enforcement setting
+     */
     void set_enforce_dns_checkpoints(bool enforce);
+
+    /**
+     * @brief loads new checkpoints from a file and optionally from DNS
+     *
+     * @param file_path the path of the file to look for and load checkpoints from
+     * @param check_dns whether or not to check for new DNS-based checkpoints
+     *
+     * @return false if any enforced checkpoint type fails to load, otherwise true
+     */
     bool update_checkpoints(const std::string& file_path, bool check_dns);
 
+
     // user options, must be called before calling init()
+
+    //FIXME: parameter names don't match function definition in .cpp file
+    /**
+     * @brief sets various performance options
+     *
+     * @param block_threads max number of threads when preparing blocks for addition
+     * @param blocks_per_sync number of blocks to cache before syncing to database
+     * @param sync_mode the ::blockchain_db_sync_mode to use
+     * @param fast_sync sync using built-in block hashes as trusted
+     */
     void set_user_options(uint64_t block_threads, uint64_t blocks_per_sync,
         blockchain_db_sync_mode sync_mode, bool fast_sync);
 
+    /**
+     * @brief set whether or not to show/print time statistics
+     *
+     * @param stats the new time stats setting
+     */
     void set_show_time_stats(bool stats) { m_show_time_stats = stats; }
 
+    /**
+     * @brief gets the hardfork voting state object
+     *
+     * @return the HardFork object
+     */
     HardFork::State get_hard_fork_state() const;
+
+    /**
+     * @brief gets the current hardfork version in use/voted for
+     *
+     * @return the version
+     */
     uint8_t get_current_hard_fork_version() const { return m_hardfork->get_current_version(); }
+
+    /**
+     * @brief returns the newest hardfork version known to the blockchain
+     *
+     * @return the version
+     */
     uint8_t get_ideal_hard_fork_version() const { return m_hardfork->get_ideal_version(); }
+
+    /**
+     * @brief returns the newest hardfork version voted to be enabled
+     * as of a certain height
+     *
+     * @param height the height for which to check version info
+     *
+     * @return the version
+     */
     uint8_t get_ideal_hard_fork_version(uint64_t height) const { return m_hardfork->get_ideal_version(height); }
 
+    /**
+     * @brief get information about hardfork voting for a version
+     *
+     * @param version the version in question
+     * @param window the size of the voting window
+     * @param votes the number of votes to enable <version>
+     * @param threshold the number of votes required to enable <version>
+     * @param earliest_height the earliest height at which <version> is allowed
+     * @param voting which version this node is voting for/using
+     *
+     * @return whether the version queried is enabled 
+     */
     bool get_hard_fork_voting_info(uint8_t version, uint32_t &window, uint32_t &votes, uint32_t &threshold, uint64_t &earliest_height, uint8_t &voting) const;
 
+    /**
+     * @brief remove transactions from the transaction pool (if present)
+     *
+     * @param txids a list of hashes of transactions to be removed
+     *
+     * @return false if any removals fail, otherwise true
+     */
     bool flush_txes_from_pool(const std::list<crypto::hash> &txids);
 
+    /**
+     * @brief perform a check on all key images in the blockchain
+     *
+     * @param std::function the check to perform, pass/fail
+     *
+     * @return false if any key image fails the check, otherwise true
+     */
     bool for_all_key_images(std::function<bool(const crypto::key_image&)>) const;
+
+    /**
+     * @brief perform a check on all blocks in the blockchain
+     *
+     * @param std::function the check to perform, pass/fail
+     *
+     * @return false if any block fails the check, otherwise true
+     */
     bool for_all_blocks(std::function<bool(uint64_t, const crypto::hash&, const block&)>) const;
+
+    /**
+     * @brief perform a check on all transactions in the blockchain
+     *
+     * @param std::function the check to perform, pass/fail
+     *
+     * @return false if any transaction fails the check, otherwise true
+     */
     bool for_all_transactions(std::function<bool(const crypto::hash&, const cryptonote::transaction&)>) const;
+
+    /**
+     * @brief perform a check on all outputs in the blockchain
+     *
+     * @param std::function the check to perform, pass/fail
+     *
+     * @return false if any output fails the check, otherwise true
+     */
     bool for_all_outputs(std::function<bool(uint64_t amount, const crypto::hash &tx_hash, size_t tx_idx)>) const;
 
+    /**
+     * @brief get a reference to the BlockchainDB in use by Blockchain
+     *
+     * @return a reference to the BlockchainDB instance
+     */
     BlockchainDB& get_db()
     {
       return *m_db;
     }
 
+    /**
+     * @brief get a number of outputs of a specific amount
+     *
+     * @param amount the amount
+     * @param offsets the indices (indexed to the amount) of the outputs
+     * @param outputs return-by-reference the outputs collected
+     * @param txs unused, candidate for removal
+     */
     void output_scan_worker(const uint64_t amount,const std::vector<uint64_t> &offsets,
         std::vector<output_data_t> &outputs, std::unordered_map<crypto::hash,
         cryptonote::transaction> &txs) const;
 
+    /**
+     * @brief computes the "short" and "long" hashes for a set of blocks
+     *
+     * @param height the height of the first block
+     * @param blocks the blocks to be hashed
+     * @param map return-by-reference the hashes for each block
+     */
     void block_longhash_worker(const uint64_t height, const std::vector<block> &blocks,
         std::unordered_map<crypto::hash, crypto::hash> &map) const;
   private:
+
+    // TODO: evaluate whether or not each of these typedefs are left over from blockchain_storage
     typedef std::unordered_map<crypto::hash, size_t> blocks_by_id_index;
+
     typedef std::unordered_map<crypto::hash, transaction_chain_entry> transactions_container;
+
     typedef std::unordered_set<crypto::key_image> key_images_container;
+
     typedef std::vector<block_extended_info> blocks_container;
+
     typedef std::unordered_map<crypto::hash, block_extended_info> blocks_ext_by_hash;
+
     typedef std::unordered_map<crypto::hash, block> blocks_by_hash;
+
     typedef std::map<uint64_t, std::vector<std::pair<crypto::hash, size_t>>> outputs_container; //crypto::hash - tx hash, size_t - index of out in transaction
 
+
     BlockchainDB* m_db;
 
     tx_memory_pool& m_tx_pool;
+
     mutable epee::critical_section m_blockchain_lock; // TODO: add here reader/writer lock
 
     // main chain
     transactions_container m_transactions;
     size_t m_current_block_cumul_sz_limit;
 
+    // metadata containers
     std::unordered_map<crypto::hash, std::unordered_map<crypto::key_image, std::vector<output_data_t>>> m_scan_table;
     std::unordered_map<crypto::hash, std::pair<bool, uint64_t>> m_check_tx_inputs_table;
     std::unordered_map<crypto::hash, crypto::hash> m_blocks_longhash_table;
@@ -243,39 +819,323 @@ namespace cryptonote
 
     bool m_testnet;
 
+    /**
+     * @brief collects the keys for all outputs being "spent" as an input
+     *
+     * This function makes sure that each "input" in an input (mixins) exists
+     * and collects the public key for each from the transaction it was included in
+     * via the visitor passed to it.
+     *
+     * If pmax_related_block_height is not NULL, its value is set to the height
+     * of the most recent block which contains an output used in the input set
+     *
+     * @tparam visitor_t a class encapsulating tx is unlocked and collect tx key
+     * @param tx_in_to_key a transaction input instance
+     * @param vis an instance of the visitor to use
+     * @param tx_prefix_hash the hash of the associated transaction_prefix
+     * @param pmax_related_block_height return-by-pointer the height of the most recent block in the input set
+     *
+     * @return false if any keys are not found or any inputs are not unlocked, otherwise true
+     */
     template<class visitor_t>
     inline bool scan_outputkeys_for_indexes(const txin_to_key& tx_in_to_key, visitor_t &vis, const crypto::hash &tx_prefix_hash, uint64_t* pmax_related_block_height = NULL) const;
+
+    /**
+     * @brief collect output public keys of a transaction input set
+     *
+     * This function locates all outputs associated with a given input set (mixins)
+     * and validates that they exist and are usable
+     * (unlocked, unspent is checked elsewhere).
+     *
+     * If pmax_related_block_height is not NULL, its value is set to the height
+     * of the most recent block which contains an output used in the input set
+     *
+     * @param txin the transaction input
+     * @param tx_prefix_hash the transaction prefix hash, for caching organization
+     * @param sig the input signature
+     * @param output_keys return-by-reference the public keys of the outputs in the input set
+     * @param pmax_related_block_height return-by-pointer the height of the most recent block in the input set
+     *
+     * @return false if any output is not yet unlocked, or is missing, otherwise true
+     */
     bool check_tx_input(const txin_to_key& txin, const crypto::hash& tx_prefix_hash, const std::vector<crypto::signature>& sig, std::vector<crypto::public_key> &output_keys, uint64_t* pmax_related_block_height);
+
+    /**
+     * @brief validate a transaction's inputs and their keys
+     *
+     * This function validates transaction inputs and their keys.  Previously
+     * it also performed double spend checking, but that has been moved to its
+     * own function.
+     *
+     * If pmax_related_block_height is not NULL, its value is set to the height
+     * of the most recent block which contains an output used in any input set
+     *
+     * Currently this function calls ring signature validation for each
+     * transaction.
+     *
+     * @param tx the transaction to validate
+     * @param pmax_related_block_height return-by-pointer the height of the most recent block in the input set
+     *
+     * @return false if any validation step fails, otherwise true
+     */
     bool check_tx_inputs(const transaction& tx, uint64_t* pmax_used_block_height = NULL);
 
+    /**
+     * @brief performs a blockchain reorganization according to the longest chain rule
+     *
+     * This function aggregates all the actions necessary to switch to a
+     * newly-longer chain.  If any step in the reorganization process fails,
+     * the blockchain is reverted to its previous state.
+     *
+     * @param alt_chain the chain to switch to
+     * @param discard_disconnected_chain whether or not to keep the old chain as an alternate
+     *
+     * @return false if the reorganization fails, otherwise true
+     */
     bool switch_to_alternative_blockchain(std::list<blocks_ext_by_hash::iterator>& alt_chain, bool discard_disconnected_chain);
+
+    /**
+     * @brief removes the most recent block from the blockchain
+     *
+     * @return the block removed
+     */
     block pop_block_from_blockchain();
 
+    /**
+     * @brief validate and add a new block to the end of the blockchain
+     *
+     * This function is merely a convenience wrapper around the other
+     * of the same name.  This one passes the block's hash to the other
+     * as well as the block and verification context.
+     *
+     * @param bl the block to be added
+     * @param bvc metadata concerning the block's validity
+     *
+     * @return true if the block was added successfully, otherwise false
+     */
     bool handle_block_to_main_chain(const block& bl, block_verification_context& bvc);
+
+    /**
+     * @brief validate and add a new block to the end of the blockchain
+     *
+     * When a block is given to Blockchain to be added to the blockchain, it
+     * is passed here if it is determined to belong at the end of the current
+     * chain.
+     *
+     * @param bl the block to be added
+     * @param id the hash of the block
+     * @param bvc metadata concerning the block's validity
+     *
+     * @return true if the block was added successfully, otherwise false
+     */
     bool handle_block_to_main_chain(const block& bl, const crypto::hash& id, block_verification_context& bvc);
+
+    /**
+     * @brief validate and add a new block to an alternate blockchain
+     *
+     * If a block to be added does not belong to the main chain, but there
+     * is an alternate chain to which it should be added, that is handled
+     * here.
+     *
+     * @param b the block to be added
+     * @param id the hash of the block
+     * @param bvc metadata concerning the block's validity
+     *
+     * @return true if the block was added successfully, otherwise false
+     */
     bool handle_alternative_block(const block& b, const crypto::hash& id, block_verification_context& bvc);
+
+    /**
+     * @brief gets the difficulty requirement for a new block on an alternate chain
+     *
+     * @param alt_chain the chain to be added to
+     * @param bei the block being added (and metadata, see ::block_extended_info)
+     *
+     * @return the difficulty requirement
+     */
     difficulty_type get_next_difficulty_for_alternative_chain(const std::list<blocks_ext_by_hash::iterator>& alt_chain, block_extended_info& bei) const;
+
+    /**
+     * @brief sanity checks a miner transaction before validating an entire block
+     *
+     * This function merely checks basic things like the structure of the miner
+     * transaction, the unlock time, and that the amount doesn't overflow.
+     *
+     * @param b the block containing the miner transaction
+     * @param height the height at which the block will be added
+     *
+     * @return false if anything is found wrong with the miner transaction, otherwise true
+     */
     bool prevalidate_miner_transaction(const block& b, uint64_t height);
+
+    /**
+     * @brief validates a miner (coinbase) transaction
+     *
+     * This function makes sure that the miner calculated his reward correctly
+     * and that his miner transaction totals reward + fee.
+     *
+     * @param b the block containing the miner transaction to be validated
+     * @param cumulative_block_size the block's size
+     * @param fee the total fees collected in the block
+     * @param base_reward return-by-reference the new block's generated coins
+     * @param already_generated_coins the amount of currency generated prior to this block
+     * @param partial_block_reward return-by-reference true if miner accepted only partial reward
+     *
+     * @return false if anything is found wrong with the miner transaction, otherwise true
+     */
     bool validate_miner_transaction(const block& b, size_t cumulative_block_size, uint64_t fee, uint64_t& base_reward, uint64_t already_generated_coins, bool &partial_block_reward);
-    bool validate_transaction(const block& b, uint64_t height, const transaction& tx);
+
+    /**
+     * @brief reverts the blockchain to its previous state following a failed switch
+     *
+     * If Blockchain fails to switch to an alternate chain when it means
+     * to do so, this function reverts the blockchain to how it was before
+     * the attempted switch.
+     *
+     * @param original_chain the chain to switch back to
+     * @param rollback_height the height to revert to before appending the original chain
+     *
+     * @return false if something goes wrong with reverting (very bad), otherwise true
+     */
     bool rollback_blockchain_switching(std::list<block>& original_chain, uint64_t rollback_height);
-    bool add_transaction_from_block(const transaction& tx, const crypto::hash& tx_id, const crypto::hash& bl_id, uint64_t bl_height);
-    bool push_transaction_to_global_outs_index(const transaction& tx, const crypto::hash& tx_id, std::vector<uint64_t>& global_indexes);
-    bool pop_transaction_from_global_index(const transaction& tx, const crypto::hash& tx_id);
+
+    /**
+     * @brief gets recent block sizes for median calculation
+     *
+     * get the block sizes of the last <count> blocks, and return by reference <sz>.
+     *
+     * @param sz return-by-reference the list of sizes
+     * @param count the number of blocks to get sizes for
+     */
     void get_last_n_blocks_sizes(std::vector<size_t>& sz, size_t count) const;
+
+    /**
+     * @brief adds the given output to the requested set of random outputs
+     *
+     * @param result_outs return-by-reference the set the output is to be added to
+     * @param amount the output amount
+     * @param i the output index (indexed to amount)
+     */
     void add_out_to_get_random_outs(COMMAND_RPC_GET_RANDOM_OUTPUTS_FOR_AMOUNTS::outs_for_amount& result_outs, uint64_t amount, size_t i) const;
+
+    /**
+     * @brief checks if a transaction is unlocked (its outputs spendable)
+     *
+     * This function checks to see if a transaction is unlocked.
+     * unlock_time is either a block index or a unix time.
+     *
+     * @param unlock_time the unlock parameter (height or time)
+     *
+     * @return true if spendable, otherwise false
+     */
     bool is_tx_spendtime_unlocked(uint64_t unlock_time) const;
+
+    /**
+     * @brief stores an invalid block in a separate container
+     *
+     * Storing invalid blocks allows quick dismissal of the same block
+     * if it is seen again.
+     *
+     * @param bl the invalid block
+     * @param h the block's hash
+     *
+     * @return false if the block cannot be stored for some reason, otherwise true
+     */
     bool add_block_as_invalid(const block& bl, const crypto::hash& h);
+
+    /**
+     * @brief stores an invalid block in a separate container
+     *
+     * Storing invalid blocks allows quick dismissal of the same block
+     * if it is seen again.
+     *
+     * @param bei the invalid block (see ::block_extended_info)
+     * @param h the block's hash
+     *
+     * @return false if the block cannot be stored for some reason, otherwise true
+     */
     bool add_block_as_invalid(const block_extended_info& bei, const crypto::hash& h);
+
+    /**
+     * @brief checks a block's timestamp
+     *
+     * This function grabs the timestamps from the most recent <n> blocks,
+     * where n = BLOCKCHAIN_TIMESTAMP_CHECK_WINDOW.  If there are not those many
+     * blocks in the blockchain, the timestap is assumed to be valid.  If there
+     * are, this function returns:
+     *   true if the block's timestamp is not less than the timestamp of the
+     *       median of the selected blocks
+     *   false otherwise
+     *
+     * @param b the block to be checked
+     *
+     * @return true if the block's timestamp is valid, otherwise false
+     */
     bool check_block_timestamp(const block& b) const;
+
+    /**
+     * @brief checks a block's timestamp
+     *
+     * If the block is not more recent than the median of the recent
+     * timestamps passed here, it is considered invalid.
+     *
+     * @param timestamps a list of the most recent timestamps to check against
+     * @param b the block to be checked
+     *
+     * @return true if the block's timestamp is valid, otherwise false
+     */
     bool check_block_timestamp(std::vector<uint64_t>& timestamps, const block& b) const;
+
+    /**
+     * @brief get the "adjusted time"
+     *
+     * Currently this simply returns the current time according to the
+     * user's machine.
+     *
+     * @return the current time
+     */
     uint64_t get_adjusted_time() const;
+
+    /**
+     * @brief finish an alternate chain's timestamp window from the main chain
+     *
+     * for an alternate chain, get the timestamps from the main chain to complete
+     * the needed number of timestamps for the BLOCKCHAIN_TIMESTAMP_CHECK_WINDOW.
+     *
+     * @param start_height the alternate chain's attachment height to the main chain
+     * @param timestamps return-by-value the timestamps set to be populated
+     *
+     * @return true unless start_height is greater than the current blockchain height
+     */
     bool complete_timestamps_vector(uint64_t start_height, std::vector<uint64_t>& timestamps);
+
+    /**
+     * @brief calculate the block size limit for the next block to be added
+     *
+     * @return true
+     */
     bool update_next_cumulative_size_limit();
     void return_tx_to_pool(const std::vector<transaction> &txs);
 
+    /**
+     * @brief make sure a transaction isn't attempting a double-spend
+     *
+     * @param tx the transaction to check
+     * @param keys_this_block a cumulative list of spent keys for the current block
+     *
+     * @return false if a double spend was detected, otherwise true
+     */
     bool check_for_double_spend(const transaction& tx, key_images_container& keys_this_block) const;
-    void get_timestamp_and_difficulty(uint64_t &timestamp, difficulty_type &difficulty, const int offset) const;
+
+    /**
+     * @brief validates a transaction input's ring signature
+     *
+     * @param tx_prefix_hash the transaction prefix' hash
+     * @param key_image the key image generated from the true input
+     * @param pubkeys the public keys for each input in the ring signature
+     * @param sig the signature generated for each input in the ring signature
+     * @param result false if the ring signature is invalid, otherwise true
+     */
     void check_ring_signature(const crypto::hash &tx_prefix_hash, const crypto::key_image &key_image,
         const std::vector<crypto::public_key> &pubkeys, const std::vector<crypto::signature> &sig, uint64_t &result);
 
diff --git a/src/cryptonote_core/blockchain_storage.cpp b/src/cryptonote_core/blockchain_storage.cpp
index e1b89f887..a829b7cbe 100644
--- a/src/cryptonote_core/blockchain_storage.cpp
+++ b/src/cryptonote_core/blockchain_storage.cpp
@@ -48,7 +48,7 @@
 #include "common/boost_serialization_helper.h"
 #include "warnings.h"
 #include "crypto/hash.h"
-#include "cryptonote_core/checkpoints_create.h"
+#include "cryptonote_core/checkpoints.h"
 //#include "serialization/json_archive.h"
 #include "../../contrib/otshell_utils/utils.hpp"
 #include "../../src/p2p/data_logger.hpp"
@@ -1854,7 +1854,7 @@ void blockchain_storage::check_against_checkpoints(const checkpoints& points, bo
 // with an existing checkpoint.
 bool blockchain_storage::update_checkpoints(const std::string& file_path, bool check_dns)
 {
-  if (!cryptonote::load_checkpoints_from_json(m_checkpoints, file_path))
+  if (!m_checkpoints.load_checkpoints_from_json(file_path))
   {
     return false;
   }
@@ -1863,7 +1863,7 @@ bool blockchain_storage::update_checkpoints(const std::string& file_path, bool c
   // if we're not hard-enforcing dns checkpoints, handle accordingly
   if (m_enforce_dns_checkpoints && check_dns)
   {
-    if (!cryptonote::load_checkpoints_from_dns(m_checkpoints))
+    if (!m_checkpoints.load_checkpoints_from_dns())
     {
       return false;
     }
@@ -1871,7 +1871,7 @@ bool blockchain_storage::update_checkpoints(const std::string& file_path, bool c
   else if (check_dns)
   {
     checkpoints dns_points;
-    cryptonote::load_checkpoints_from_dns(dns_points, m_testnet);
+    dns_points.load_checkpoints_from_dns(m_testnet);
     if (m_checkpoints.check_for_conflicts(dns_points))
     {
       check_against_checkpoints(dns_points, false);
diff --git a/src/cryptonote_core/checkpoints.cpp b/src/cryptonote_core/checkpoints.cpp
index 24d066dae..c038a4802 100644
--- a/src/cryptonote_core/checkpoints.cpp
+++ b/src/cryptonote_core/checkpoints.cpp
@@ -1,21 +1,21 @@
 // Copyright (c) 2014-2016, The Monero Project
-// 
+//
 // All rights reserved.
-// 
+//
 // Redistribution and use in source and binary forms, with or without modification, are
 // permitted provided that the following conditions are met:
-// 
+//
 // 1. Redistributions of source code must retain the above copyright notice, this list of
 //    conditions and the following disclaimer.
-// 
+//
 // 2. Redistributions in binary form must reproduce the above copyright notice, this list
 //    of conditions and the following disclaimer in the documentation and/or other
 //    materials provided with the distribution.
-// 
+//
 // 3. Neither the name of the copyright holder nor the names of its contributors may be
 //    used to endorse or promote products derived from this software without specific
 //    prior written permission.
-// 
+//
 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 // MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
@@ -25,14 +25,44 @@
 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 // STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
 // THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-// 
+//
 // Parts of this file are originally copyright (c) 2012-2013 The Cryptonote developers
 
 #include "include_base_utils.h"
+
 using namespace epee;
 
 #include "checkpoints.h"
 
+#include "common/dns_utils.h"
+#include "include_base_utils.h"
+#include <sstream>
+#include <random>
+
+namespace
+{
+  bool dns_records_match(const std::vector<std::string>& a, const std::vector<std::string>& b)
+  {
+    if (a.size() != b.size()) return false;
+
+    for (const auto& record_in_a : a)
+    {
+      bool ok = false;
+      for (const auto& record_in_b : b)
+      {
+	if (record_in_a == record_in_b)
+	{
+	  ok = true;
+	  break;
+	}
+      }
+      if (!ok) return false;
+    }
+
+    return true;
+  }
+} // anonymous namespace
+
 namespace cryptonote
 {
   //---------------------------------------------------------------------------
@@ -84,10 +114,7 @@ namespace cryptonote
     return check_block(height, h, ignored);
   }
   //---------------------------------------------------------------------------
-  // 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.
+  //FIXME: is this the desired behavior?
   bool checkpoints::is_alternative_block_allowed(uint64_t blockchain_height, uint64_t block_height) const
   {
     if (0 == block_height)
@@ -128,4 +155,206 @@ namespace cryptonote
     }
     return true;
   }
+
+  bool checkpoints::init_default_checkpoints()
+  {
+    ADD_CHECKPOINT(1,     "771fbcd656ec1464d3a02ead5e18644030007a0fc664c0a964d30922821a8148");
+    ADD_CHECKPOINT(10,    "c0e3b387e47042f72d8ccdca88071ff96bff1ac7cde09ae113dbb7ad3fe92381");
+    ADD_CHECKPOINT(100,   "ac3e11ca545e57c49fca2b4e8c48c03c23be047c43e471e1394528b1f9f80b2d");
+    ADD_CHECKPOINT(1000,  "5acfc45acffd2b2e7345caf42fa02308c5793f15ec33946e969e829f40b03876");
+    ADD_CHECKPOINT(10000, "c758b7c81f928be3295d45e230646de8b852ec96a821eac3fea4daf3fcac0ca2");
+    ADD_CHECKPOINT(22231, "7cb10e29d67e1c069e6e11b17d30b809724255fee2f6868dc14cfc6ed44dfb25");
+    ADD_CHECKPOINT(29556, "53c484a8ed91e4da621bb2fa88106dbde426fe90d7ef07b9c1e5127fb6f3a7f6");
+    ADD_CHECKPOINT(50000, "0fe8758ab06a8b9cb35b7328fd4f757af530a5d37759f9d3e421023231f7b31c");
+    ADD_CHECKPOINT(80000, "a62dcd7b536f22e003ebae8726e9e7276f63d594e264b6f0cd7aab27b66e75e3");
+    ADD_CHECKPOINT(202612, "bbd604d2ba11ba27935e006ed39c9bfdd99b76bf4a50654bc1e1e61217962698");
+    ADD_CHECKPOINT(202613, "e2aa337e78df1f98f462b3b1e560c6b914dec47b610698b7b7d1e3e86b6197c2");
+    ADD_CHECKPOINT(202614, "c29e3dc37d8da3e72e506e31a213a58771b24450144305bcba9e70fa4d6ea6fb");
+    ADD_CHECKPOINT(205000, "5d3d7a26e6dc7535e34f03def711daa8c263785f73ec1fadef8a45880fde8063");
+    ADD_CHECKPOINT(220000, "9613f455933c00e3e33ac315cc6b455ee8aa0c567163836858c2d9caff111553");
+    ADD_CHECKPOINT(230300, "bae7a80c46859db355556e3a9204a337ae8f24309926a1312323fdecf1920e61");
+    ADD_CHECKPOINT(230700, "93e631240ceac831da1aebfc5dac8f722c430463024763ebafa888796ceaeedf");
+    ADD_CHECKPOINT(231350, "b5add137199b820e1ea26640e5c3e121fd85faa86a1e39cf7e6cc097bdeb1131");
+    ADD_CHECKPOINT(232150, "955de8e6b6508af2c24f7334f97beeea651d78e9ade3ab18fec3763be3201aa8");
+    ADD_CHECKPOINT(249380, "654fb0a81ce3e5caf7e3264a70f447d4bd07586c08fa50f6638cc54da0a52b2d");
+    ADD_CHECKPOINT(460000, "75037a7aed3e765db96c75bcf908f59d690a5f3390baebb9edeafd336a1c4831");
+    ADD_CHECKPOINT(500000, "2428f0dbe49796be05ed81b347f53e1f7f44aed0abf641446ec2b94cae066b02");
+    ADD_CHECKPOINT(600000, "f5828ebf7d7d1cb61762c4dfe3ccf4ecab2e1aad23e8113668d981713b7a54c5");
+    ADD_CHECKPOINT(700000, "12be9b3d210b93f574d2526abb9c1ab2a881b479131fd0d4f7dac93875f503cd");
+    ADD_CHECKPOINT(825000, "56503f9ad766774b575be3aff73245e9d159be88132c93d1754764f28da2ff60");
+    ADD_CHECKPOINT(900000, "d9958d0e7dcf91a5a7b11de225927bf7efc6eb26240315ce12372be902cc1337");
+    ADD_CHECKPOINT(913193, "5292d5d56f6ba4de33a58d9a34d263e2cb3c6fee0aed2286fd4ac7f36d53c85f");
+
+    return true;
+  }
+
+  bool checkpoints::load_checkpoints_from_json(const std::string json_hashfile_fullpath)
+  {
+    boost::system::error_code errcode;
+    if (! (boost::filesystem::exists(json_hashfile_fullpath, errcode)))
+    {
+      LOG_PRINT_L1("Blockchain checkpoints file not found");
+      return true;
+    }
+
+    LOG_PRINT_L1("Adding checkpoints from blockchain hashfile");
+
+    uint64_t prev_max_height = get_max_height();
+    LOG_PRINT_L1("Hard-coded max checkpoint height is " << prev_max_height);
+    t_hash_json hashes;
+    epee::serialization::load_t_from_json_file(hashes, json_hashfile_fullpath);
+    for (std::vector<t_hashline>::const_iterator it = hashes.hashlines.begin(); it != hashes.hashlines.end(); )
+    {
+      uint64_t height;
+      height = it->height;
+      if (height <= prev_max_height) {
+	LOG_PRINT_L1("ignoring checkpoint height " << height);
+      } else {
+	std::string blockhash = it->hash;
+	LOG_PRINT_L1("Adding checkpoint height " << height << ", hash=" << blockhash);
+	ADD_CHECKPOINT(height, blockhash);
+      }
+      ++it;
+    }
+
+    return true;
+  }
+
+  bool checkpoints::load_checkpoints_from_dns(bool testnet)
+  {
+    // All four MoneroPulse domains have DNSSEC on and valid
+    static const std::vector<std::string> dns_urls = { "checkpoints.moneropulse.se"
+						     , "checkpoints.moneropulse.org"
+						     , "checkpoints.moneropulse.net"
+						     , "checkpoints.moneropulse.co"
+    };
+
+    static const std::vector<std::string> testnet_dns_urls = { "testpoints.moneropulse.se"
+							     , "testpoints.moneropulse.org"
+							     , "testpoints.moneropulse.net"
+							     , "testpoints.moneropulse.co"
+    };
+
+    std::vector<std::vector<std::string> > records;
+    records.resize(dns_urls.size());
+
+    std::random_device rd;
+    std::mt19937 gen(rd());
+    std::uniform_int_distribution<int> dis(0, dns_urls.size() - 1);
+    size_t first_index = dis(gen);
+
+    bool avail, valid;
+    size_t cur_index = first_index;
+    do
+    {
+      std::string url;
+      if (testnet)
+      {
+        url = testnet_dns_urls[cur_index];
+      }
+      else
+      {
+        url = dns_urls[cur_index];
+      }
+
+      records[cur_index] = tools::DNSResolver::instance().get_txt_record(url, avail, valid);
+      if (!avail)
+      {
+        records[cur_index].clear();
+        LOG_PRINT_L2("DNSSEC not available for checkpoint update at URL: " << url << ", skipping.");
+      }
+      if (!valid)
+      {
+        records[cur_index].clear();
+        LOG_PRINT_L2("DNSSEC validation failed for checkpoint update at URL: " << url << ", skipping.");
+      }
+
+      cur_index++;
+      if (cur_index == dns_urls.size())
+      {
+        cur_index = 0;
+      }
+      records[cur_index].clear();
+    } while (cur_index != first_index);
+
+    size_t num_valid_records = 0;
+
+    for( const auto& record_set : records)
+    {
+      if (record_set.size() != 0)
+      {
+        num_valid_records++;
+      }
+    }
+
+    if (num_valid_records < 2)
+    {
+      LOG_PRINT_L0("WARNING: no two valid MoneroPulse DNS checkpoint records were received");
+      return true;
+    }
+
+    int good_records_index = -1;
+    for (size_t i = 0; i < records.size() - 1; ++i)
+    {
+      if (records[i].size() == 0) continue;
+
+      for (size_t j = i + 1; j < records.size(); ++j)
+      {
+        if (dns_records_match(records[i], records[j]))
+        {
+    good_records_index = i;
+    break;
+        }
+      }
+      if (good_records_index >= 0) break;
+    }
+
+    if (good_records_index < 0)
+    {
+      LOG_PRINT_L0("WARNING: no two MoneroPulse DNS checkpoint records matched");
+      return true;
+    }
+
+    for (auto& record : records[good_records_index])
+    {
+      auto pos = record.find(":");
+      if (pos != std::string::npos)
+      {
+        uint64_t height;
+        crypto::hash hash;
+
+        // parse the first part as uint64_t,
+        // if this fails move on to the next record
+        std::stringstream ss(record.substr(0, pos));
+        if (!(ss >> height))
+        {
+    continue;
+        }
+
+        // parse the second part as crypto::hash,
+        // if this fails move on to the next record
+        std::string hashStr = record.substr(pos + 1);
+        if (!epee::string_tools::parse_tpod_from_hex_string(hashStr, hash))
+        {
+    continue;
+        }
+
+        ADD_CHECKPOINT(height, hashStr);
+      }
+    }
+    return true;
+  }
+
+  bool checkpoints::load_new_checkpoints(const std::string json_hashfile_fullpath, bool testnet, bool dns)
+  {
+    bool result;
+
+    result = load_checkpoints_from_json(json_hashfile_fullpath);
+    if (dns)
+    {
+      result &= load_checkpoints_from_dns(testnet);
+    }
+
+    return result;
+  }
 }
diff --git a/src/cryptonote_core/checkpoints.h b/src/cryptonote_core/checkpoints.h
index 00a53ec24..71727753e 100644
--- a/src/cryptonote_core/checkpoints.h
+++ b/src/cryptonote_core/checkpoints.h
@@ -1,21 +1,21 @@
 // Copyright (c) 2014-2016, The Monero Project
-// 
+//
 // All rights reserved.
-// 
+//
 // Redistribution and use in source and binary forms, with or without modification, are
 // permitted provided that the following conditions are met:
-// 
+//
 // 1. Redistributions of source code must retain the above copyright notice, this list of
 //    conditions and the following disclaimer.
-// 
+//
 // 2. Redistributions in binary form must reproduce the above copyright notice, this list
 //    of conditions and the following disclaimer in the documentation and/or other
 //    materials provided with the distribution.
-// 
+//
 // 3. Neither the name of the copyright holder nor the names of its contributors may be
 //    used to endorse or promote products derived from this software without specific
 //    prior written permission.
-// 
+//
 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 // MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
@@ -25,30 +25,193 @@
 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 // STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
 // THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-// 
+//
 // Parts of this file are originally copyright (c) 2012-2013 The Cryptonote developers
 
 #pragma once
 #include <map>
 #include <vector>
 #include "cryptonote_basic_impl.h"
+#include "misc_log_ex.h"
+#include "storages/portable_storage_template_helper.h" // epee json include
+
+#define ADD_CHECKPOINT(h, hash)  CHECK_AND_ASSERT(add_checkpoint(h,  hash), false);
+#define JSON_HASH_FILE_NAME "checkpoints.json"
 
 
 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
   {
   public:
+
+    /**
+     * @brief default constructor
+     */
     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);
+
+    /**
+     * @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 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;
+
+    /**
+     * @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;
+
+    /**
+     * @brief gets the highest checkpoint height
+     *
+     * @return the height of the highest checkpoint
+     */
     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;
+
+    /**
+     * @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;
+
+    /**
+     * @brief loads the default main chain checkpoints
+     *
+     * @return true unless adding a checkpoint fails
+     */
+    bool init_default_checkpoints();
+
+    /**
+     * @brief load new checkpoints
+     *
+     * Loads new checkpoints from the specified json file, as well as
+     * (optionally) from DNS.
+     *
+     * @param json_hashfile_fullpath path to the json checkpoints file
+     * @param testnet whether to load testnet checkpoints or mainnet
+     * @param dns whether or not to load DNS checkpoints
+     *
+     * @return true if loading successful and no conflicts
+     */
+    bool load_new_checkpoints(const std::string json_hashfile_fullpath, bool testnet=false, bool dns=true);
+
+    /**
+     * @brief load new checkpoints from json
+     *
+     * @param json_hashfile_fullpath path to the json checkpoints file
+     *
+     * @return true if loading successful and no conflicts
+     */
+    bool load_checkpoints_from_json(const std::string json_hashfile_fullpath);
+
+    /**
+     * @brief load new checkpoints from DNS
+     *
+     * @param testnet whether to load testnet checkpoints or mainnet
+     *
+     * @return true if loading successful and no conflicts
+     */
+    bool load_checkpoints_from_dns(bool testnet = false);
+
   private:
-    std::map<uint64_t, crypto::hash> m_points;
+
+
+    /**
+     * @brief struct for loading a checkpoint from json
+     */
+  struct t_hashline
+  {
+    uint64_t height; //!< the height of the checkpoint
+    std::string hash; //!< the hash for the checkpoint
+        BEGIN_KV_SERIALIZE_MAP()
+          KV_SERIALIZE(height)
+          KV_SERIALIZE(hash)
+        END_KV_SERIALIZE_MAP()
+  };
+
+  /**
+   * @brief struct for loading many checkpoints from json
+   */
+  struct t_hash_json {
+    std::vector<t_hashline> hashlines; //!< the checkpoint lines from the file
+        BEGIN_KV_SERIALIZE_MAP()
+          KV_SERIALIZE(hashlines)
+        END_KV_SERIALIZE_MAP()
+  };
+
+    std::map<uint64_t, crypto::hash> m_points; //!< the checkpoints container
+
   };
 }
diff --git a/src/cryptonote_core/checkpoints_create.cpp b/src/cryptonote_core/checkpoints_create.cpp
deleted file mode 100644
index 41f2321d5..000000000
--- a/src/cryptonote_core/checkpoints_create.cpp
+++ /dev/null
@@ -1,280 +0,0 @@
-// Copyright (c) 2014-2016, The Monero Project
-//
-// All rights reserved.
-//
-// Redistribution and use in source and binary forms, with or without modification, are
-// permitted provided that the following conditions are met:
-//
-// 1. Redistributions of source code must retain the above copyright notice, this list of
-//    conditions and the following disclaimer.
-//
-// 2. Redistributions in binary form must reproduce the above copyright notice, this list
-//    of conditions and the following disclaimer in the documentation and/or other
-//    materials provided with the distribution.
-//
-// 3. Neither the name of the copyright holder nor the names of its contributors may be
-//    used to endorse or promote products derived from this software without specific
-//    prior written permission.
-//
-// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
-// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-// MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
-// THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
-// STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
-// THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-//
-// Parts of this file are originally copyright (c) 2012-2013 The Cryptonote developers
-
-#include "checkpoints_create.h"
-#include "common/dns_utils.h"
-#include "include_base_utils.h"
-#include <sstream>
-#include <random>
-#include "storages/portable_storage_template_helper.h" // epee json include
-
-namespace
-{
-  bool dns_records_match(const std::vector<std::string>& a, const std::vector<std::string>& b)
-  {
-    if (a.size() != b.size()) return false;
-
-    for (const auto& record_in_a : a)
-    {
-      bool ok = false;
-      for (const auto& record_in_b : b)
-      {
-        if (record_in_a == record_in_b)
-        {
-          ok = true;
-          break;
-        }
-      }
-      if (!ok) return false;
-    }
-
-    return true;
-  }
-} // anonymous namespace
-
-namespace cryptonote
-{
-
-struct t_hashline
-{
-  uint64_t height;
-  std::string hash;
-  BEGIN_KV_SERIALIZE_MAP()
-    KV_SERIALIZE(height)
-    KV_SERIALIZE(hash)
-  END_KV_SERIALIZE_MAP()
-};
-
-struct t_hash_json {
-  std::vector<t_hashline> hashlines;
-  BEGIN_KV_SERIALIZE_MAP()
-    KV_SERIALIZE(hashlines)
-  END_KV_SERIALIZE_MAP()
-};
-
-bool create_checkpoints(cryptonote::checkpoints& checkpoints)
-{
-  ADD_CHECKPOINT(1,     "771fbcd656ec1464d3a02ead5e18644030007a0fc664c0a964d30922821a8148");
-  ADD_CHECKPOINT(10,    "c0e3b387e47042f72d8ccdca88071ff96bff1ac7cde09ae113dbb7ad3fe92381");
-  ADD_CHECKPOINT(100,   "ac3e11ca545e57c49fca2b4e8c48c03c23be047c43e471e1394528b1f9f80b2d");
-  ADD_CHECKPOINT(1000,  "5acfc45acffd2b2e7345caf42fa02308c5793f15ec33946e969e829f40b03876");
-  ADD_CHECKPOINT(10000, "c758b7c81f928be3295d45e230646de8b852ec96a821eac3fea4daf3fcac0ca2");
-  ADD_CHECKPOINT(22231, "7cb10e29d67e1c069e6e11b17d30b809724255fee2f6868dc14cfc6ed44dfb25");
-  ADD_CHECKPOINT(29556, "53c484a8ed91e4da621bb2fa88106dbde426fe90d7ef07b9c1e5127fb6f3a7f6");
-  ADD_CHECKPOINT(50000, "0fe8758ab06a8b9cb35b7328fd4f757af530a5d37759f9d3e421023231f7b31c");
-  ADD_CHECKPOINT(80000, "a62dcd7b536f22e003ebae8726e9e7276f63d594e264b6f0cd7aab27b66e75e3");
-  ADD_CHECKPOINT(202612, "bbd604d2ba11ba27935e006ed39c9bfdd99b76bf4a50654bc1e1e61217962698");
-  ADD_CHECKPOINT(202613, "e2aa337e78df1f98f462b3b1e560c6b914dec47b610698b7b7d1e3e86b6197c2");
-  ADD_CHECKPOINT(202614, "c29e3dc37d8da3e72e506e31a213a58771b24450144305bcba9e70fa4d6ea6fb");
-  ADD_CHECKPOINT(205000, "5d3d7a26e6dc7535e34f03def711daa8c263785f73ec1fadef8a45880fde8063");
-  ADD_CHECKPOINT(220000, "9613f455933c00e3e33ac315cc6b455ee8aa0c567163836858c2d9caff111553");
-  ADD_CHECKPOINT(230300, "bae7a80c46859db355556e3a9204a337ae8f24309926a1312323fdecf1920e61");
-  ADD_CHECKPOINT(230700, "93e631240ceac831da1aebfc5dac8f722c430463024763ebafa888796ceaeedf");
-  ADD_CHECKPOINT(231350, "b5add137199b820e1ea26640e5c3e121fd85faa86a1e39cf7e6cc097bdeb1131");
-  ADD_CHECKPOINT(232150, "955de8e6b6508af2c24f7334f97beeea651d78e9ade3ab18fec3763be3201aa8");
-  ADD_CHECKPOINT(249380, "654fb0a81ce3e5caf7e3264a70f447d4bd07586c08fa50f6638cc54da0a52b2d");
-  ADD_CHECKPOINT(300000, "0c1cd46df6ccff90ec4ab493281f2583c344cd62216c427628990fe9db1bb8b6");
-  ADD_CHECKPOINT(400000, "1b2b0e7a30e59691491529a3d506d1ba3d6052d0f6b52198b7330b28a6f1b6ac");
-  ADD_CHECKPOINT(450000, "4d098b511ca97723e81737c448343cfd4e6dadb3d8a0e757c6e4d595e6e48357");
-  ADD_CHECKPOINT(460000, "75037a7aed3e765db96c75bcf908f59d690a5f3390baebb9edeafd336a1c4831");
-  ADD_CHECKPOINT(500000, "2428f0dbe49796be05ed81b347f53e1f7f44aed0abf641446ec2b94cae066b02");
-  ADD_CHECKPOINT(600000, "f5828ebf7d7d1cb61762c4dfe3ccf4ecab2e1aad23e8113668d981713b7a54c5");
-  ADD_CHECKPOINT(700000, "12be9b3d210b93f574d2526abb9c1ab2a881b479131fd0d4f7dac93875f503cd");
-  ADD_CHECKPOINT(825000, "56503f9ad766774b575be3aff73245e9d159be88132c93d1754764f28da2ff60");
-  ADD_CHECKPOINT(900000, "d9958d0e7dcf91a5a7b11de225927bf7efc6eb26240315ce12372be902cc1337");
-  ADD_CHECKPOINT(913193, "5292d5d56f6ba4de33a58d9a34d263e2cb3c6fee0aed2286fd4ac7f36d53c85f");
-
-  return true;
-}
-
-bool load_checkpoints_from_json(cryptonote::checkpoints& checkpoints, std::string json_hashfile_fullpath)
-{
-  boost::system::error_code errcode;
-  if (! (boost::filesystem::exists(json_hashfile_fullpath, errcode)))
-  {
-    LOG_PRINT_L1("Blockchain checkpoints file not found");
-    return true;
-  }
-
-  LOG_PRINT_L1("Adding checkpoints from blockchain hashfile");
-
-  uint64_t prev_max_height = checkpoints.get_max_height();
-  LOG_PRINT_L1("Hard-coded max checkpoint height is " << prev_max_height);
-  t_hash_json hashes;
-  epee::serialization::load_t_from_json_file(hashes, json_hashfile_fullpath);
-  for (std::vector<t_hashline>::const_iterator it = hashes.hashlines.begin(); it != hashes.hashlines.end(); )
-  {
-      uint64_t height;
-      height = it->height;
-      if (height <= prev_max_height) {
-        LOG_PRINT_L1("ignoring checkpoint height " << height);
-      } else {
-        std::string blockhash = it->hash;
-        LOG_PRINT_L1("Adding checkpoint height " << height << ", hash=" << blockhash);
-        ADD_CHECKPOINT(height, blockhash);
-      }
-      ++it;
-  }
-
-  return true;
-}
-
-bool load_checkpoints_from_dns(cryptonote::checkpoints& checkpoints, bool testnet)
-{
-  // All four MoneroPulse domains have DNSSEC on and valid
-  static const std::vector<std::string> dns_urls = { "checkpoints.moneropulse.se"
-                                                   , "checkpoints.moneropulse.org"
-                                                   , "checkpoints.moneropulse.net"
-                                                   , "checkpoints.moneropulse.co"
-  };
-
-  static const std::vector<std::string> testnet_dns_urls = { "testpoints.moneropulse.se"
-                                                           , "testpoints.moneropulse.org"
-                                                           , "testpoints.moneropulse.net"
-                                                           , "testpoints.moneropulse.co"
-  };
-
-  std::vector<std::vector<std::string> > records;
-  records.resize(dns_urls.size());
-
-  std::random_device rd;
-  std::mt19937 gen(rd());
-  std::uniform_int_distribution<int> dis(0, dns_urls.size() - 1);
-  size_t first_index = dis(gen);
-
-  bool avail, valid;
-  size_t cur_index = first_index;
-  do
-  {
-    std::string url;
-    if (testnet)
-    {
-      url = testnet_dns_urls[cur_index];
-    }
-    else
-    {
-      url = dns_urls[cur_index];
-    }
-
-    records[cur_index] = tools::DNSResolver::instance().get_txt_record(url, avail, valid);
-    if (!avail)
-    {
-      records[cur_index].clear();
-      LOG_PRINT_L2("DNSSEC not available for checkpoint update at URL: " << url << ", skipping.");
-    }
-    if (!valid)
-    {
-      records[cur_index].clear();
-      LOG_PRINT_L2("DNSSEC validation failed for checkpoint update at URL: " << url << ", skipping.");
-    }
-
-    cur_index++;
-    if (cur_index == dns_urls.size())
-    {
-      cur_index = 0;
-    }
-    records[cur_index].clear();
-  } while (cur_index != first_index);
-
-  size_t num_valid_records = 0;
-
-  for( const auto& record_set : records)
-  {
-    if (record_set.size() != 0)
-    {
-      num_valid_records++;
-    }
-  }
-
-  if (num_valid_records < 2)
-  {
-    LOG_PRINT_L0("WARNING: no two valid MoneroPulse DNS checkpoint records were received");
-    return true;
-  }
-
-  int good_records_index = -1;
-  for (size_t i = 0; i < records.size() - 1; ++i)
-  {
-    if (records[i].size() == 0) continue;
-
-    for (size_t j = i + 1; j < records.size(); ++j)
-    {
-      if (dns_records_match(records[i], records[j]))
-      {
-        good_records_index = i;
-        break;
-      }
-    }
-    if (good_records_index >= 0) break;
-  }
-
-  if (good_records_index < 0)
-  {
-    LOG_PRINT_L0("WARNING: no two MoneroPulse DNS checkpoint records matched");
-    return true;
-  }
-
-  for (auto& record : records[good_records_index])
-  {
-    auto pos = record.find(":");
-    if (pos != std::string::npos)
-    {
-      uint64_t height;
-      crypto::hash hash;
-
-      // parse the first part as uint64_t,
-      // if this fails move on to the next record
-      std::stringstream ss(record.substr(0, pos));
-      if (!(ss >> height))
-      {
-        continue;
-      }
-
-      // parse the second part as crypto::hash,
-      // if this fails move on to the next record
-      std::string hashStr = record.substr(pos + 1);
-      if (!epee::string_tools::parse_tpod_from_hex_string(hashStr, hash))
-      {
-        continue;
-      }
-
-      ADD_CHECKPOINT(height, hashStr);
-    }
-  }
-  return true;
-}
-
-bool load_new_checkpoints(cryptonote::checkpoints& checkpoints, std::string json_hashfile_fullpath)
-{
-  // TODO: replace hard-coded url with const string or #define
-  return (load_checkpoints_from_json(checkpoints, json_hashfile_fullpath) && load_checkpoints_from_dns(checkpoints));
-}
-
-}  // namespace cryptonote
diff --git a/src/cryptonote_core/checkpoints_create.h b/src/cryptonote_core/checkpoints_create.h
deleted file mode 100644
index 83830f8a2..000000000
--- a/src/cryptonote_core/checkpoints_create.h
+++ /dev/null
@@ -1,48 +0,0 @@
-// Copyright (c) 2014-2016, The Monero Project
-// 
-// All rights reserved.
-// 
-// Redistribution and use in source and binary forms, with or without modification, are
-// permitted provided that the following conditions are met:
-// 
-// 1. Redistributions of source code must retain the above copyright notice, this list of
-//    conditions and the following disclaimer.
-// 
-// 2. Redistributions in binary form must reproduce the above copyright notice, this list
-//    of conditions and the following disclaimer in the documentation and/or other
-//    materials provided with the distribution.
-// 
-// 3. Neither the name of the copyright holder nor the names of its contributors may be
-//    used to endorse or promote products derived from this software without specific
-//    prior written permission.
-// 
-// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
-// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-// MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
-// THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
-// STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
-// THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-// 
-// Parts of this file are originally copyright (c) 2012-2013 The Cryptonote developers
-
-#pragma once
-
-#include "checkpoints.h"
-#include "misc_log_ex.h"
-
-#define ADD_CHECKPOINT(h, hash)  CHECK_AND_ASSERT(checkpoints.add_checkpoint(h,  hash), false);
-#define JSON_HASH_FILE_NAME "checkpoints.json"
-
-namespace cryptonote
-{
-
-  bool create_checkpoints(cryptonote::checkpoints& checkpoints);
-
-  bool load_checkpoints_from_json(cryptonote::checkpoints& checkpoints, std::string json_hashfile_fullpath);
-  bool load_checkpoints_from_dns(cryptonote::checkpoints& checkpoints, bool testnet = false);
-  bool load_new_checkpoints(cryptonote::checkpoints& checkpoints, std::string json_hashfile_fullpath);
-
-}  // namespace cryptonote
diff --git a/src/cryptonote_core/cryptonote_core.cpp b/src/cryptonote_core/cryptonote_core.cpp
index 6f0fe88a4..c31be5acf 100644
--- a/src/cryptonote_core/cryptonote_core.cpp
+++ b/src/cryptonote_core/cryptonote_core.cpp
@@ -42,7 +42,7 @@ using namespace epee;
 #include "cryptonote_format_utils.h"
 #include "misc_language.h"
 #include <csignal>
-#include "cryptonote_core/checkpoints_create.h"
+#include "cryptonote_core/checkpoints.h"
 #include "blockchain_db/blockchain_db.h"
 #include "blockchain_db/lmdb/db_lmdb.h"
 #if defined(BERKELEY_DB)
@@ -159,7 +159,7 @@ namespace cryptonote
     if (!m_testnet && !m_fakechain)
     {
       cryptonote::checkpoints checkpoints;
-      if (!cryptonote::create_checkpoints(checkpoints))
+      if (!checkpoints.init_default_checkpoints())
       {
         throw std::runtime_error("Failed to initialize checkpoints");
       }
@@ -415,7 +415,7 @@ namespace cryptonote
     CHECK_AND_ASSERT_MES(update_checkpoints(), false, "One or more checkpoints loaded from json or dns conflicted with existing checkpoints.");
 
     r = m_miner.init(vm, m_testnet);
-    CHECK_AND_ASSERT_MES(r, false, "Failed to initialize blockchain storage");
+    CHECK_AND_ASSERT_MES(r, false, "Failed to initialize miner instance");
 
     return load_state_data();
   }
@@ -634,11 +634,6 @@ namespace cryptonote
     return m_blockchain_storage.get_total_transactions();
   }
   //-----------------------------------------------------------------------------------------------
-  //bool core::get_outs(uint64_t amount, std::list<crypto::public_key>& pkeys)
-  //{
-  //  return m_blockchain_storage.get_outs(amount, pkeys);
-  //}
-  //-----------------------------------------------------------------------------------------------
   bool core::add_new_tx(const transaction& tx, const crypto::hash& tx_hash, const crypto::hash& tx_prefix_hash, size_t blob_size, tx_verification_context& tvc, bool keeped_by_block, bool relayed)
   {
     if(m_mempool.have_tx(tx_hash))
@@ -770,10 +765,6 @@ namespace cryptonote
   {
     m_miner.on_synchronized();
   }
-  //bool core::get_backward_blocks_sizes(uint64_t from_height, std::vector<size_t>& sizes, size_t count)
-  //{
-  //  return m_blockchain_storage.get_backward_blocks_sizes(from_height, sizes, count);
-  //}
   //-----------------------------------------------------------------------------------------------
   bool core::add_new_block(const block& b, block_verification_context& bvc)
   {
@@ -894,10 +885,6 @@ namespace cryptonote
     return m_blockchain_storage.get_block_by_hash(h, blk);
   }
   //-----------------------------------------------------------------------------------------------
-  //void core::get_all_known_block_ids(std::list<crypto::hash> &main, std::list<crypto::hash> &alt, std::list<crypto::hash> &invalid) {
-  //  m_blockchain_storage.get_all_known_block_ids(main, alt, invalid);
-  //}
-  //-----------------------------------------------------------------------------------------------
   std::string core::print_pool(bool short_format) const
   {
     return m_mempool.print_pool(short_format);
diff --git a/src/cryptonote_core/cryptonote_core.h b/src/cryptonote_core/cryptonote_core.h
index 32f0b2ad4..30384209f 100644
--- a/src/cryptonote_core/cryptonote_core.h
+++ b/src/cryptonote_core/cryptonote_core.h
@@ -63,157 +63,739 @@ namespace cryptonote
   /************************************************************************/
   /*                                                                      */
   /************************************************************************/
+
+   /**
+    * @brief handles core cryptonote functionality
+    *
+    * This class coordinates cryptonote functionality including, but not
+    * limited to, communication among the Blockchain, the transaction pool,
+    * any miners, and the network.
+    */
    class core: public i_miner_handler
    {
    public:
+
+      /**
+       * @brief constructor
+       *
+       * sets member variables into a usable state
+       *
+       * @param pprotocol pre-constructed protocol object to store and use
+       */
      core(i_cryptonote_protocol* pprotocol);
+
+    /**
+     * @copydoc Blockchain::handle_get_objects
+     *
+     * @note see Blockchain::handle_get_objects()
+     * @param context connection context associated with the request
+     */
      bool handle_get_objects(NOTIFY_REQUEST_GET_OBJECTS::request& arg, NOTIFY_RESPONSE_GET_OBJECTS::request& rsp, cryptonote_connection_context& context);
+
+     /**
+      * @brief calls various idle routines
+      *
+      * @note see miner::on_idle and tx_memory_pool::on_idle
+      *
+      * @return true
+      */
      bool on_idle();
+
+     /**
+      * @brief handles an incoming transaction
+      *
+      * Parses an incoming transaction and, if nothing is obviously wrong,
+      * passes it along to the transaction pool
+      *
+      * @param tx_blob the tx to handle
+      * @param tvc metadata about the transaction's validity
+      * @param keeped_by_block if the transaction has been in a block
+      * @param relayed whether or not the transaction was relayed to us
+      *
+      * @return true if the transaction made it to the transaction pool, otherwise false
+      */
      bool handle_incoming_tx(const blobdata& tx_blob, tx_verification_context& tvc, bool keeped_by_block, bool relayed);
+
+     /**
+      * @brief handles an incoming block
+      *
+      * periodic update to checkpoints is triggered here
+      * Attempts to add the block to the Blockchain and, on success,
+      * optionally updates the miner's block template.
+      *
+      * @param block_blob the block to be added
+      * @param bvc return-by-reference metadata context about the block's validity
+      * @param update_miner_blocktemplate whether or not to update the miner's block template
+      *
+      * @return false if loading new checkpoints fails, or the block is not
+      * added, otherwise true
+      */
      bool handle_incoming_block(const blobdata& block_blob, block_verification_context& bvc, bool update_miner_blocktemplate = true);
+
+     /**
+      * @copydoc Blockchain::prepare_handle_incoming_blocks
+      *
+      * @note see Blockchain::prepare_handle_incoming_blocks
+      */
      bool prepare_handle_incoming_blocks(const std::list<block_complete_entry>  &blocks);
-     bool cleanup_handle_incoming_blocks(bool force_sync = false);
 
+     /**
+      * @copydoc Blockchain::cleanup_handle_incoming_blocks
+      *
+      * @note see Blockchain::cleanup_handle_incoming_blocks
+      */
+     bool cleanup_handle_incoming_blocks(bool force_sync = false);
+     	     	
+     /**
+      * @brief check the size of a block against the current maximum
+      *
+      * @param block_blob the block to check
+      *
+      * @return whether or not the block is too big
+      */
      bool check_incoming_block_size(const blobdata& block_blob) const;
+
+     /**
+      * @brief get the cryptonote protocol instance
+      *
+      * @return the instance
+      */
      i_cryptonote_protocol* get_protocol(){return m_pprotocol;}
 
      //-------------------- i_miner_handler -----------------------
+
+     /**
+      * @brief stores and relays a block found by a miner
+      *
+      * Updates the miner's target block, attempts to store the found
+      * block in Blockchain, and -- on success -- relays that block to
+      * the network.
+      *
+      * @param b the block found
+      *
+      * @return true if the block was added to the main chain, otherwise false
+      */
      virtual bool handle_block_found( block& b);
+
+     /**
+      * @copydoc Blockchain::create_block_template
+      *
+      * @note see Blockchain::create_block_template
+      */
      virtual bool get_block_template(block& b, const account_public_address& adr, difficulty_type& diffic, uint64_t& height, const blobdata& ex_nonce);
 
 
+     /**
+      * @brief gets the miner instance
+      *
+      * @return a reference to the miner instance
+      */
      miner& get_miner(){return m_miner;}
+
+     /**
+      * @brief gets the miner instance (const)
+      *
+      * @return a const reference to the miner instance
+      */
      const miner& get_miner()const{return m_miner;}
+
+     /**
+      * @brief adds command line options to the given options set
+      *
+      * As of now, there are no command line options specific to core,
+      * so this function simply returns.
+      *
+      * @param desc return-by-reference the command line options set to add to
+      */
      static void init_options(boost::program_options::options_description& desc);
+
+     /**
+      * @brief initializes the core as needed
+      *
+      * This function initializes the transaction pool, the Blockchain, and
+      * a miner instance with parameters given on the command line (or defaults)
+      *
+      * @param vm command line parameters
+      * @param test_options configuration options for testing
+      *
+      * @return false if one of the init steps fails, otherwise true
+      */
      bool init(const boost::program_options::variables_map& vm, const test_options *test_options = NULL);
+
+     /**
+      * @copydoc Blockchain::reset_and_set_genesis_block
+      *
+      * @note see Blockchain::reset_and_set_genesis_block
+      */
      bool set_genesis_block(const block& b);
+
+     /**
+      * @brief performs safe shutdown steps for core and core components
+      *
+      * Uninitializes the miner instance, transaction pool, and Blockchain
+      *
+      * if m_fast_exit is set, the call to Blockchain::deinit() is not made.
+      *
+      * @return true
+      */
      bool deinit();
+
+     /**
+      * @brief sets fast exit flag
+      *
+      * @note see deinit()
+      */
      static void set_fast_exit();
+
+     /**
+      * @brief gets the current state of the fast exit flag
+      *
+      * @return the fast exit flag
+      *
+      * @note see deinit()
+      */
      static bool get_fast_exit();
+
+     /**
+      * @brief sets to drop blocks downloaded (for testing)
+      */
      void test_drop_download();
+
+     /**
+      * @brief sets to drop blocks downloaded below a certain height
+      *
+      * @param height height below which to drop blocks
+      */
      void test_drop_download_height(uint64_t height);
+
+     /**
+      * @brief gets whether or not to drop blocks (for testing)
+      *
+      * @return whether or not to drop blocks
+      */
      bool get_test_drop_download() const;
+
+     /**
+      * @brief gets whether or not to drop blocks
+      *
+      * If the current blockchain height <= our block drop threshold
+      * and test drop blocks is set, return true
+      *
+      * @return see above
+      */
      bool get_test_drop_download_height() const;
+
+     /**
+      * @copydoc Blockchain::get_current_blockchain_height
+      *
+      * @note see Blockchain::get_current_blockchain_height()
+      */
      uint64_t get_current_blockchain_height() const;
-     bool get_blockchain_top(uint64_t& heeight, crypto::hash& top_id) const;
+
+     /**
+      * @brief get the hash and height of the most recent block
+      *
+      * @param height return-by-reference height of the block
+      * @param top_id return-by-reference hash of the block
+      *
+      * @return true
+      */
+     bool get_blockchain_top(uint64_t& height, crypto::hash& top_id) const;
+
+     /**
+      * @copydoc Blockchain::get_blocks(uint64_t, size_t, std::list<block>&, std::list<transaction>&) const
+      *
+      * @note see Blockchain::get_blocks(uint64_t, size_t, std::list<block>&, std::list<transaction>&) const
+      */
      bool get_blocks(uint64_t start_offset, size_t count, std::list<block>& blocks, std::list<transaction>& txs) const;
+
+     /**
+      * @copydoc Blockchain::get_blocks(uint64_t, size_t, std::list<block>&) const
+      *
+      * @note see Blockchain::get_blocks(uint64_t, size_t, std::list<block>&) const
+      */
      bool get_blocks(uint64_t start_offset, size_t count, std::list<block>& blocks) const;
+
+     /**
+      * @copydoc Blockchain::get_blocks(const t_ids_container&, t_blocks_container&, t_missed_container&) const
+      *
+      * @note see Blockchain::get_blocks(const t_ids_container&, t_blocks_container&, t_missed_container&) const
+      */
      template<class t_ids_container, class t_blocks_container, class t_missed_container>
      bool get_blocks(const t_ids_container& block_ids, t_blocks_container& blocks, t_missed_container& missed_bs) const
      {
        return m_blockchain_storage.get_blocks(block_ids, blocks, missed_bs);
      }
+
+     /**
+      * @copydoc Blockchain::get_block_id_by_height
+      *
+      * @note see Blockchain::get_block_id_by_height
+      */
      crypto::hash get_block_id_by_height(uint64_t height) const;
+
+     /**
+      * @copydoc Blockchain::get_transactions
+      *
+      * @note see Blockchain::get_transactions
+      */
      bool get_transactions(const std::vector<crypto::hash>& txs_ids, std::list<transaction>& txs, std::list<crypto::hash>& missed_txs) const;
+
+     /**
+      * @copydoc Blockchain::get_block_by_hash
+      *
+      * @note see Blockchain::get_block_by_hash
+      */
      bool get_block_by_hash(const crypto::hash &h, block &blk) const;
-     //void get_all_known_block_ids(std::list<crypto::hash> &main, std::list<crypto::hash> &alt, std::list<crypto::hash> &invalid);
 
+     /**
+      * @copydoc Blockchain::get_alternative_blocks
+      *
+      * @note see Blockchain::get_alternative_blocks(std::list<block>&) const
+      */
      bool get_alternative_blocks(std::list<block>& blocks) const;
+
+     /**
+      * @copydoc Blockchain::get_alternative_blocks_count
+      *
+      * @note see Blockchain::get_alternative_blocks_count() const
+      */
      size_t get_alternative_blocks_count() const;
 
+     /**
+      * @brief set the pointer to the cryptonote protocol object to use
+      *
+      * @param pprotocol the pointer to set ours as
+      */
      void set_cryptonote_protocol(i_cryptonote_protocol* pprotocol);
+
+     /**
+      * @copydoc Blockchain::set_checkpoints
+      *
+      * @note see Blockchain::set_checkpoints()
+      */
      void set_checkpoints(checkpoints&& chk_pts);
+
+     /**
+      * @brief set the file path to read from when loading checkpoints
+      *
+      * @param path the path to set ours as
+      */
      void set_checkpoints_file_path(const std::string& path);
+
+     /**
+      * @brief set whether or not we enforce DNS checkpoints
+      *
+      * @param enforce_dns enforce DNS checkpoints or not
+      */
      void set_enforce_dns_checkpoints(bool enforce_dns);
 
+     /**
+      * @copydoc tx_memory_pool::get_transactions
+      *
+      * @note see tx_memory_pool::get_transactions
+      */
      bool get_pool_transactions(std::list<transaction>& txs) const;
+
+     /**
+      * @copydoc tx_memory_pool::get_pool_transactions_and_spent_keys_info
+      *
+      * @note see tx_memory_pool::get_pool_transactions_and_spent_keys_info
+      */
      bool get_pool_transactions_and_spent_keys_info(std::vector<tx_info>& tx_infos, std::vector<spent_key_image_info>& key_image_infos) const;
+
+     /**
+      * @copydoc tx_memory_pool::get_transactions_count
+      *
+      * @note see tx_memory_pool::get_transactions_count
+      */
      size_t get_pool_transactions_count() const;
+
+     /**
+      * @copydoc Blockchain::get_total_transactions
+      *
+      * @note see Blockchain::get_total_transactions
+      */
      size_t get_blockchain_total_transactions() const;
-     //bool get_outs(uint64_t amount, std::list<crypto::public_key>& pkeys);
+
+     /**
+      * @copydoc Blockchain::have_block
+      *
+      * @note see Blockchain::have_block
+      */
      bool have_block(const crypto::hash& id) const;
+
+     /**
+      * @copydoc Blockchain::get_short_chain_history
+      *
+      * @note see Blockchain::get_short_chain_history
+      */
      bool get_short_chain_history(std::list<crypto::hash>& ids) const;
+
+     /**
+      * @copydoc Blockchain::find_blockchain_supplement(const std::list<crypto::hash>&, NOTIFY_RESPONSE_CHAIN_ENTRY::request&) const
+      *
+      * @note see Blockchain::find_blockchain_supplement(const std::list<crypto::hash>&, NOTIFY_RESPONSE_CHAIN_ENTRY::request&) const
+      */
      bool find_blockchain_supplement(const std::list<crypto::hash>& qblock_ids, NOTIFY_RESPONSE_CHAIN_ENTRY::request& resp) const;
+
+     /**
+      * @copydoc Blockchain::find_blockchain_supplement(const uint64_t, const std::list<crypto::hash>&, std::list<std::pair<block, std::list<transaction> > >&, uint64_t&, uint64_t&, size_t) const
+      *
+      * @note see Blockchain::find_blockchain_supplement(const uint64_t, const std::list<crypto::hash>&, std::list<std::pair<block, std::list<transaction> > >&, uint64_t&, uint64_t&, size_t) const
+      */
      bool find_blockchain_supplement(const uint64_t req_start_block, const std::list<crypto::hash>& qblock_ids, std::list<std::pair<block, std::list<transaction> > >& blocks, uint64_t& total_height, uint64_t& start_height, size_t max_count) const;
+
+     /**
+      * @brief gets some stats about the daemon
+      *
+      * @param st_inf return-by-reference container for the stats requested
+      *
+      * @return true
+      */
      bool get_stat_info(core_stat_info& st_inf) const;
-     //bool get_backward_blocks_sizes(uint64_t from_height, std::vector<size_t>& sizes, size_t count);
+
+     /**
+      * @copydoc Blockchain::get_tx_outputs_gindexs
+      *
+      * @note see Blockchain::get_tx_outputs_gindexs
+      */
      bool get_tx_outputs_gindexs(const crypto::hash& tx_id, std::vector<uint64_t>& indexs) const;
+
+     /**
+      * @copydoc Blockchain::get_tail_id
+      *
+      * @note see Blockchain::get_tail_id
+      */
      crypto::hash get_tail_id() const;
+
+     /**
+      * @copydoc Blockchain::get_random_outs_for_amounts
+      *
+      * @note see Blockchain::get_random_outs_for_amounts
+      */
      bool get_random_outs_for_amounts(const COMMAND_RPC_GET_RANDOM_OUTPUTS_FOR_AMOUNTS::request& req, COMMAND_RPC_GET_RANDOM_OUTPUTS_FOR_AMOUNTS::response& res) const;
+
+
+     /**
+      * @copydoc miner::pause
+      *
+      * @note see miner::pause
+      */
      void pause_mine();
+
+     /**
+      * @copydoc miner::resume
+      *
+      * @note see miner::resume
+      */
      void resume_mine();
+
 #if BLOCKCHAIN_DB == DB_LMDB
+     /**
+      * @brief gets the Blockchain instance
+      *
+      * @return a reference to the Blockchain instance
+      */
      Blockchain& get_blockchain_storage(){return m_blockchain_storage;}
+
+     /**
+      * @brief gets the Blockchain instance (const)
+      *
+      * @return a const reference to the Blockchain instance
+      */
      const Blockchain& get_blockchain_storage()const{return m_blockchain_storage;}
 #else
      blockchain_storage& get_blockchain_storage(){return m_blockchain_storage;}
      const blockchain_storage& get_blockchain_storage()const{return m_blockchain_storage;}
 #endif
-     //debug functions
+
+     /**
+      * @copydoc Blockchain::print_blockchain
+      *
+      * @note see Blockchain::print_blockchain
+      */
      void print_blockchain(uint64_t start_index, uint64_t end_index) const;
+
+     /**
+      * @copydoc Blockchain::print_blockchain_index
+      *
+      * @note see Blockchain::print_blockchain_index
+      */
      void print_blockchain_index() const;
+
+     /**
+      * @copydoc tx_memory_pool::print_pool
+      *
+      * @note see tx_memory_pool::print_pool
+      */
      std::string print_pool(bool short_format) const;
+
+     /**
+      * @copydoc Blockchain::print_blockchain_outs
+      *
+      * @note see Blockchain::print_blockchain_outs
+      */
      void print_blockchain_outs(const std::string& file);
+
+     /**
+      * @copydoc miner::on_synchronized
+      *
+      * @note see miner::on_synchronized
+      */
      void on_synchronized();
 
+     /**
+      * @brief sets the target blockchain height
+      *
+      * @param target_blockchain_height the height to set
+      */
      void set_target_blockchain_height(uint64_t target_blockchain_height);
+
+     /**
+      * @brief gets the target blockchain height
+      *
+      * @param target_blockchain_height the target height
+      */
      uint64_t get_target_blockchain_height() const;
 
+     /**
+      * @brief tells the Blockchain to update its checkpoints
+      *
+      * This function will check if enough time has passed since the last
+      * time checkpoints were updated and tell the Blockchain to update
+      * its checkpoints if it is time.  If updating checkpoints fails,
+      * the daemon is told to shut down.
+      *
+      * @note see Blockchain::update_checkpoints()
+      */
      bool update_checkpoints();
 
+     /**
+      * @brief tells the daemon to wind down operations and stop running
+      *
+      * Currently this function raises SIGTERM, allowing the installed signal
+      * handlers to do the actual stopping.
+      */
+     void graceful_exit();
+
+     /**
+      * @brief stops the daemon running
+      *
+      * @note see graceful_exit()
+      */
      void stop();
 
+     /**
+      * @copydoc Blockchain::have_tx_keyimg_as_spent
+      *
+      * @note see Blockchain::have_tx_keyimg_as_spent
+      */
      bool is_key_image_spent(const crypto::key_image& key_im) const;
+
+     /**
+      * @brief check if multiple key images are spent
+      *
+      * plural version of is_key_image_spent()
+      *
+      * @param key_im list of key images to check
+      * @param spent return-by-reference result for each image checked
+      *
+      * @return true
+      */
      bool are_key_images_spent(const std::vector<crypto::key_image>& key_im, std::vector<bool> &spent) const;
 
    private:
+
+     /**
+      * @copydoc add_new_tx(const transaction&, tx_verification_context&, bool)
+      *
+      * @param tx_hash the transaction's hash
+      * @param tx_prefix_hash the transaction prefix' hash
+      * @param blob_size the size of the transaction
+      * @param relayed whether or not the transaction was relayed to us
+      *
+      */
      bool add_new_tx(const transaction& tx, const crypto::hash& tx_hash, const crypto::hash& tx_prefix_hash, size_t blob_size, tx_verification_context& tvc, bool keeped_by_block, bool relayed);
+
+     /**
+      * @brief add a new transaction to the transaction pool
+      *
+      * Adds a new transaction to the transaction pool.
+      *
+      * @param tx the transaction to add
+      * @param tvc return-by-reference metadata about the transaction's verification process
+      * @param keeped_by_block whether or not the transaction has been in a block
+      * @param relayed whether or not the transaction was relayed to us
+      *
+      * @return true if the transaction is already in the transaction pool,
+      * is already in a block on the Blockchain, or is successfully added
+      * to the transaction pool
+      */
      bool add_new_tx(const transaction& tx, tx_verification_context& tvc, bool keeped_by_block, bool relayed);
+
+     /**
+      * @copydoc Blockchain::add_new_block
+      *
+      * @note see Blockchain::add_new_block
+      */
      bool add_new_block(const block& b, block_verification_context& bvc);
+
+     /**
+      * @brief load any core state stored on disk
+      *
+      * currently does nothing, but may have state to load in the future.
+      *
+      * @return true
+      */
      bool load_state_data();
+
+     /**
+      * @copydoc parse_tx_from_blob(transaction&, crypto::hash&, crypto::hash&, const blobdata&) const
+      *
+      * @note see parse_tx_from_blob(transaction&, crypto::hash&, crypto::hash&, const blobdata&) const
+      */
      bool parse_tx_from_blob(transaction& tx, crypto::hash& tx_hash, crypto::hash& tx_prefix_hash, const blobdata& blob) const;
 
+     /**
+      * @brief check a transaction's syntax
+      *
+      * For now this does nothing, but it may check something about the tx
+      * in the future.
+      *
+      * @param tx the transaction to check
+      *
+      * @return true
+      */
      bool check_tx_syntax(const transaction& tx) const;
-     //check correct values, amounts and all lightweight checks not related with database
+
+     /**
+      * @brief validates some simple properties of a transaction
+      *
+      * Currently checks: tx has inputs,
+      *                   tx inputs all of supported type(s),
+      *                   tx outputs valid (type, key, amount),
+      *                   input and output total amounts don't overflow,
+      *                   output amount <= input amount,
+      *                   tx not too large,
+      *                   each input has a different key image.
+      *
+      * @param tx the transaction to check
+      * @param keeped_by_block if the transaction has been in a block
+      *
+      * @return true if all the checks pass, otherwise false
+      */
      bool check_tx_semantic(const transaction& tx, bool keeped_by_block) const;
-     //check if tx already in memory pool or in main blockchain
 
-     bool check_tx_ring_signature(const txin_to_key& tx, const crypto::hash& tx_prefix_hash, const std::vector<crypto::signature>& sig) const;
-     bool is_tx_spendtime_unlocked(uint64_t unlock_time) const;
+     /**
+      * @copydoc miner::on_block_chain_update
+      *
+      * @note see miner::on_block_chain_update
+      *
+      * @return true
+      */
      bool update_miner_block_template();
+
+     /**
+      * @brief act on a set of command line options given
+      *
+      * @param vm the command line options
+      *
+      * @return true
+      */
      bool handle_command_line(const boost::program_options::variables_map& vm);
-     bool on_update_blocktemplate_interval();
+
+     /**
+      * @brief verify that each input key image in a transaction is unique
+      *
+      * @param tx the transaction to check
+      *
+      * @return false if any key image is repeated, otherwise true
+      */
      bool check_tx_inputs_keyimages_diff(const transaction& tx) const;
-     void graceful_exit();
+
+     /**
+      * @brief checks HardFork status and prints messages about it
+      *
+      * Checks the status of HardFork and logs/prints if an update to
+      * the daemon is necessary.
+      *
+      * @note see Blockchain::get_hard_fork_state and HardFork::State
+      *
+      * @return true
+      */
      bool check_fork_time();
+
+     /**
+      * @brief attempts to relay any transactions in the mempool which need it
+      *
+      * @return true
+      */
      bool relay_txpool_transactions();
+
+     /**
+      * @brief locks a file in the BlockchainDB directory
+      *
+      * @param path the directory in which to place the file
+      *
+      * @return true if lock acquired successfully, otherwise false
+      */
      bool lock_db_directory(const boost::filesystem::path &path);
+
+     /**
+      * @brief unlocks the db directory
+      *
+      * @note see lock_db_directory()
+      *
+      * @return true
+      */
      bool unlock_db_directory();
 
-     static std::atomic<bool> m_fast_exit;
-     bool m_test_drop_download = true;
-     uint64_t m_test_drop_download_height = 0;
+     static std::atomic<bool> m_fast_exit; //!< whether or not to deinit Blockchain on exit
+
+     bool m_test_drop_download = true; //!< whether or not to drop incoming blocks (for testing)
 
-     tx_memory_pool m_mempool;
+     uint64_t m_test_drop_download_height = 0; //!< height under which to drop incoming blocks, if doing so
+
+     tx_memory_pool m_mempool; //!< transaction pool instance
 #if BLOCKCHAIN_DB == DB_LMDB
-     Blockchain m_blockchain_storage;
+     Blockchain m_blockchain_storage; //!< Blockchain instance
 #else
      blockchain_storage m_blockchain_storage;
 #endif
-     i_cryptonote_protocol* m_pprotocol;
-     epee::critical_section m_incoming_tx_lock;
+
+     i_cryptonote_protocol* m_pprotocol; //!< cryptonote protocol instance
+
+     epee::critical_section m_incoming_tx_lock; //!< incoming transaction lock
+
      //m_miner and m_miner_addres are probably temporary here
-     miner m_miner;
-     account_public_address m_miner_address;
-     std::string m_config_folder;
-     cryptonote_protocol_stub m_protocol_stub;
-     epee::math_helper::once_a_time_seconds<60*60*12, false> m_store_blockchain_interval;
-     epee::math_helper::once_a_time_seconds<60*60*2, true> m_fork_moaner;
+     miner m_miner; //!< miner instance
+     account_public_address m_miner_address; //!< address to mine to (for miner instance)
+
+     std::string m_config_folder; //!< folder to look in for configs and other files
+
+     cryptonote_protocol_stub m_protocol_stub; //!< cryptonote protocol stub instance
+
+     epee::math_helper::once_a_time_seconds<60*60*12, false> m_store_blockchain_interval; //!< interval for manual storing of Blockchain, if enabled
+     epee::math_helper::once_a_time_seconds<60*60*2, false> m_fork_moaner; //!< interval for checking HardFork status
      epee::math_helper::once_a_time_seconds<60*2, false> m_txpool_auto_relayer; //!< interval for checking re-relaying txpool transactions
+
      friend class tx_validate_inputs;
-     std::atomic<bool> m_starter_message_showed;
+     std::atomic<bool> m_starter_message_showed; //!< has the "daemon will sync now" message been shown?
+
+     uint64_t m_target_blockchain_height; //!< blockchain height target
+
+     bool m_testnet; //!< are we on testnet?
 
-     uint64_t m_target_blockchain_height;
+     bool m_fakechain; //!< are we using a fake chain (for testing purposes)?
 
-     bool m_testnet;
-     bool m_fakechain;
-     std::string m_checkpoints_path;
-     time_t m_last_dns_checkpoints_update;
-     time_t m_last_json_checkpoints_update;
+     std::string m_checkpoints_path; //!< path to json checkpoints file
+     time_t m_last_dns_checkpoints_update; //!< time when dns checkpoints were last updated
+     time_t m_last_json_checkpoints_update; //!< time when json checkpoints were last updated
 
-     std::atomic_flag m_checkpoints_updating;
+     std::atomic_flag m_checkpoints_updating; //!< set if checkpoints are currently updating to avoid multiple threads attempting to update at once
 
-     boost::interprocess::file_lock db_lock;
+     boost::interprocess::file_lock db_lock; //!< a lock object for a file lock in the db directory
    };
 }
 
diff --git a/src/cryptonote_core/difficulty.cpp b/src/cryptonote_core/difficulty.cpp
index 236e84481..54da77392 100644
--- a/src/cryptonote_core/difficulty.cpp
+++ b/src/cryptonote_core/difficulty.cpp
@@ -116,8 +116,8 @@ namespace cryptonote {
     return !carry;
   }
 
-  difficulty_type next_difficulty(vector<uint64_t> timestamps, vector<difficulty_type> cumulative_difficulties, size_t target_seconds) {
-    //cutoff DIFFICULTY_LAG
+  difficulty_type next_difficulty(std::vector<std::uint64_t> timestamps, std::vector<difficulty_type> cumulative_difficulties, size_t target_seconds) {
+
     if(timestamps.size() > DIFFICULTY_WINDOW)
     {
       timestamps.resize(DIFFICULTY_WINDOW);
@@ -151,6 +151,8 @@ namespace cryptonote {
     assert(total_work > 0);
     uint64_t low, high;
     mul(total_work, target_seconds, low, high);
+    // blockchain errors "difficulty overhead" if this function returns zero.
+    // TODO: consider throwing an exception instead
     if (high != 0 || low + time_span - 1 < low) {
       return 0;
     }
diff --git a/src/cryptonote_core/difficulty.h b/src/cryptonote_core/difficulty.h
index d49c2f3b8..910f97035 100644
--- a/src/cryptonote_core/difficulty.h
+++ b/src/cryptonote_core/difficulty.h
@@ -39,6 +39,18 @@ namespace cryptonote
 {
     typedef std::uint64_t difficulty_type;
 
+    /**
+     * @brief checks if a hash fits the given difficulty
+     *
+     * The hash passes if (hash * difficulty) < 2^192.
+     * Phrased differently, if (hash * difficulty) fits without overflow into
+     * the least significant 192 bits of the 256 bit multiplication result.
+     *
+     * @param hash the hash to check
+     * @param difficulty the difficulty to check against
+     *
+     * @return true if valid, else false
+     */
     bool check_hash(const crypto::hash &hash, difficulty_type difficulty);
     difficulty_type next_difficulty(std::vector<std::uint64_t> timestamps, std::vector<difficulty_type> cumulative_difficulties, size_t target_seconds);
 }
diff --git a/src/daemon/core.h b/src/daemon/core.h
index 2208ef25a..2b7f0d177 100644
--- a/src/daemon/core.h
+++ b/src/daemon/core.h
@@ -28,7 +28,6 @@
 
 #pragma once
 
-#include "cryptonote_core/checkpoints_create.h"
 #include "cryptonote_core/cryptonote_core.h"
 #include "cryptonote_protocol/cryptonote_protocol_handler.h"
 #include "misc_log_ex.h"