Documentation

.gitignore

@@ -73,6 +73,7 @@ _deps
 
 
 # iginore bin
-external/*
 compile_flags.txt
 .cache
+html
+latex

src/includes/blocks/base_block.h

@@ -1,42 +1,75 @@
+/**
+* @file base_block.h
+* @author Nathan Faber (nfaber@olin.edu.com)
+* @brief Base Block definitions and print functions
+* @version 0.1
+* @date 2022-03-17
+* 
+*/
+
 #pragma once
 #include "constants.h"
 #include "base_tx.h"
 
+/**
+ * @brief Blockheader for Block in the BlockChain
+ * 
+ */
 typedef struct BlockHeader{
   unsigned long timestamp;
   unsigned char all_tx[ALL_TX_HASH_LEN];
   unsigned char prev_header_hash[BLOCK_HASH_LEN];
   unsigned long nonce;
 } BlockHeader;
 
+/**
+ * @brief Block within the BlockChain
+ * 
+ */
 typedef struct Block{
   unsigned int num_txs;
   BlockHeader header;
   Transaction** txs;
 } Block;
 
-/* Hashes passed block header
- *
- * dest: Buffer to write hash to, expected to be of size BLOCK_HASH_LEN
- * header: Block header to hash
+/**
+ * @brief Hashes passed block header
+ * 
+ * @param dest Buffer to write hash to, expected to be of size BLOCK_HASH_LEN
+ * @param header Block header to hash
  */
 void hash_blockheader(unsigned char *dest, BlockHeader *header);
 
-/*
-Prints a Block Header to stdout so data can be visualized
-
-header: header to be printed
-
-*/
+/**
+ * @brief Print an entire Block Header to stdout so data can be visualized
+ * 
+ * @param header Header to be printed
+ * @param prefix string prefix to print
+ */
 void print_block_header(BlockHeader *header, char *prefix);
-void pretty_print_block_header(BlockHeader *block, char *prefix);
 
-/*
-Prints a block to stdout, (including header) for visualization
+/**
+ * @brief Print a smaller/prettier version of the blockheader
+ * 
+ * @param header Header to be printed
+ * @param prefix string prefix to print
+ */
+void pretty_print_block_header(BlockHeader *block, char *prefix);
 
-block: block to print
-prefix: string to put in front of all print commands used for tabbing structure
-*/
+/**
+ * @brief Print a block to stdout, (including header) for visualization
+ * 
+ * @param block Block to print
+ * @param prefix string to prefix print commands (for tabbing structure)
+ */
 void print_block(Block *block, char *prefix);
+
+/**
+ * @brief Print a smaller/prettier block to stdout, 
+ * (including header) for visualization
+ * 
+ * @param block Block to print
+ * @param prefix string to prefix print commands (for tabbing structure)
+ */
 void pretty_print_block(Block *block, char *prefix);
 

src/includes/blocks/create_block.h

@@ -1,11 +1,10 @@
 /**
 * @file create_block.h
 * @author Nathan Faber (nfaber@olin.edu.com)
-* @brief Functions to handle block creation for mining functionality as 
+* @brief Functions to handle Block creation for mining functionality as 
 well as mining
 * @version 0.1
 * @date 2022-03-17
-* 
 */
 
 #pragma once

src/includes/blocks/handle_block.h

@@ -1,3 +1,11 @@
+/**
+* @file handle_block.h
+* @author Nathan Faber (nfaber@olin.edu.com)
+* @brief Functions to "handle" a Block after it has been validated
+* @version 0.1
+* @date 2022-03-17
+*/
+
 #pragma once
 
 #include "base_block.h"

src/includes/blocks/ser_block.h

@@ -1,3 +1,11 @@
+/**
+* @file ser_block.h
+* @author Eamon Ito-Fisher (efisher@olin.edu.com)
+* @brief Serilaization and Deserializatoin functions for Block and BlockHeader
+* @version 0.1
+* @date 2022-03-17
+*/
+
 #pragma once
 
 #include "base_block.h"

src/includes/blocks/validate_block.h

@@ -1,8 +1,7 @@
 /**
 * @file validate_block.h
 * @author Nathan Faber (nfaber@olin.edu.com)
-* @brief Header for fof functions used to validate a new block that is 
- * broadcast on the blockchain and update the various appropriate structures
+* @brief Header for functions used to validate a new Block 
 * @version 0.1
 * @date 2022-03-18
 * 
@@ -12,22 +11,74 @@
 
 #include "base_tx.h"
 #include "base_block.h"
-
+/**
+ * @brief Validate a transaction both when inocming and in a block
+ * 
+ * @param tx Transaction to validate
+ * @return int 0 if success, otherwise not zero
+ */
 int validate_tx_shared(Transaction *tx);
 
+/**
+ * @brief Validate a coinbase Transaction
+ * 
+ * @param txs set of transactions with the coinbase transaction first
+ * @param num_txs number of transaction in the set
+ * @return int 0 if valid, not zero if invalid
+ */
 int validate_coinbase_tx(Transaction **txs, unsigned int num_txs);
 
+/**
+ * @brief Validate transactions in an incoming block
+ * 
+ * @param txs Transactions within a block
+ * @param num_txs number of transactions in block
+ * @return int 0 if valid, not zero if invalid
+ */
 int validate_incoming_block_txs(Transaction **txs, unsigned int num_txs);
 
-///OPTIONAL
+/**
+ * @brief NOT IMPLEMENTED
+ * 
+ * @param prev_header 
+ */
 void request_prev_block(unsigned char *prev_header);
 
+/**
+ * @brief NOT IMPLEMENTED
+ * 
+ * @param curr_header 
+ */
 void add_to_pending_blocks(unsigned char *curr_header);
 
+/**
+ * @brief Validate if the block's previous header hash is in local blockchain
+ * 
+ * @param block Block to check 
+ * @return int 0 if previous header is found, not zero if not
+ */
 int validate_prev_block_exists(Block *block);
 
+/**
+ * @brief Verify that the all_tx_hash matches the set of transactions in a block
+ * 
+ * @param block Block to check
+ * @return int 0 if all_tx_hash is valid, not zero if invalid
+ */
 int validate_all_tx_hash(Block *block);
 
+/**
+ * @brief Check if a block conatins a double-spend
+ * 
+ * @param block Block to check
+ * @return int 0 if no double spends, not zero if double spend present
+ */
 int validate_block_double_spend(Block *block);
 
+/**
+ * @brief Validate an entire block
+ * 
+ * @param block Block to validate
+ * @return int 0 if block is valid, not zero if invalid
+ */
 int validate_block(Block *block);

src/includes/globals/blockchain.h

@@ -1,3 +1,12 @@
+/**
+ * @file blockchain.h
+ * @author  Eamon Ito-Fisher (efisher@olin.edu.com)
+ * @brief Core BlockChain Datastructure and functions
+ * @version 0.1
+ * @date 2022-05-06
+ * 
+ * @copyright Copyright (c) 2022
+ */
 #pragma once
 
 #include "constants.h"
@@ -6,20 +15,32 @@
 #include "constants.h"
 #include "leveldb/c.h"
 
-typedef struct BlockChain {
-  unsigned char id[BLOCK_HASH_LEN];
-  Block *block;
-  UT_hash_handle hh;
-} BlockChain;
-
-BlockChain *blockchain;
+/**
+ * @brief Top Hash that the node is working on
+ */
 unsigned char top_block_header_hash[BLOCK_HASH_LEN];
+
+/**
+ * @brief Number of blocks in this node's Blockchain
+ */
 unsigned long chain_height;
 
+/**
+ * @brief Path to local blockchain
+ */
 char *blockchain_path;
+
+/**
+ * @brief Database
+ */
 leveldb_t *blockchain_db;  // Level DB Database
 
-/* Initializes the global blockchain variables */
+/**
+ * @brief Create or a blockchain,, populates blockchain_db
+ * 
+ * @param db_env DB environment to use (Test or prod)
+ * @return int 0 if success, not zero otherwise
+ */
 int blockchain_init_leveldb(char *db_env);
 
 /**
@@ -68,7 +89,18 @@ Prints the entire blockchain Hashmap to stdout
 
 prefix: string to put in front of all print commands used for tabbing structure
 */
+
+/**
+ * @brief Print the blockchain hashmap
+ * 
+ * @param prefix String to print in front of hashmap
+ */
 void print_blockchain_hashmap(char *prefix);
+
+/**
+ * @brief Print the blockchain with abbreviated data (prettier)
+ * 
+ */
 void pretty_print_blockchain_hashmap();
 
 /**

src/includes/globals/constants.h

@@ -1,19 +1,95 @@
+/**
+ * @file constants.h
+ * @author nfaber@olin.edu and efisher@olin.edu
+ * @brief Constants used within the project, character buffer sizes etc
+ * @version 0.1
+ * @date 2022-05-06
+ * 
+ * @copyright Copyright (c) 2022
+ * 
+ */
 #pragma once
 
+/**
+ * @brief Buffer length for SHA operations
+ * 
+ */
 #define SHA_HASH_LEN 32
+
+/**
+ * @brief Hashed Transaction length
+ * 
+ */
 #define TX_HASH_LEN SHA_HASH_LEN
+
+/**
+ * @brief All Transactions Hash length
+ * 
+ */
 #define ALL_TX_HASH_LEN SHA_HASH_LEN
+
+/**
+ * @brief Block Hash length
+ * 
+ */
 #define BLOCK_HASH_LEN SHA_HASH_LEN
+
+/**
+ * @brief Public Key Hash length
+ * 
+ */
 #define PUB_KEY_HASH_LEN SHA_HASH_LEN
+
+/**
+ * @brief Length of ECDSA Signature
+ * 
+ */
 #define SIGNATURE_LEN 72
-#define PRINT_TAB "  "
+
+/**
+ * @brief Error Buffer size
+ * 
+ */
 #define ERR_BUF 1024
+
+/**
+ * @brief Block Mining Reward
+ * 
+ */
 #define BLOCK_REWARD 100
+
+/**
+ * @brief Number of Transactions to include in a block
+ * 
+ */
 #define DESIRED_NUM_TX 10
+
+/**
+ * @brief Number of 0's required for the hash of a block
+ * 
+ */
 #define HASH_DIFFICULTY 2
-#define MINING_NODE 1
-#define WALLET_NODE 1
 
+/**
+ * @brief Tab Characters for use in printing
+ * 
+ */
+#define PRINT_TAB "  "
+
+/**
+ * @brief Line Break for printing
+ * 
+ */
 #define LINE_BREAK "================================\n"
+
+/**
+ * @brief Soft Line Break
+ * 
+ */
 #define SOFT_LINE_BREAK "--------------------------------\n"
+
+/**
+ * @brief Local location of database folders
+ * 
+ */
 #define LOCAL_LOCATION "/.Olincoin"