diff --git a/.gitignore b/.gitignore index 351eedc..9450767 100644 --- a/.gitignore +++ b/.gitignore @@ -73,6 +73,7 @@ _deps # iginore bin -external/* compile_flags.txt .cache +html +latex \ No newline at end of file diff --git a/src/includes/blocks/base_block.h b/src/includes/blocks/base_block.h index 2233563..2df2f43 100644 --- a/src/includes/blocks/base_block.h +++ b/src/includes/blocks/base_block.h @@ -1,7 +1,20 @@ +/** +* @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]; @@ -9,34 +22,54 @@ typedef struct BlockHeader{ 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); diff --git a/src/includes/blocks/create_block.h b/src/includes/blocks/create_block.h index bfeacbf..dca768c 100644 --- a/src/includes/blocks/create_block.h +++ b/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 diff --git a/src/includes/blocks/handle_block.h b/src/includes/blocks/handle_block.h index 9c41f7f..270fb96 100644 --- a/src/includes/blocks/handle_block.h +++ b/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" diff --git a/src/includes/blocks/ser_block.h b/src/includes/blocks/ser_block.h index e5f52c1..6b79a46 100644 --- a/src/includes/blocks/ser_block.h +++ b/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" diff --git a/src/includes/blocks/validate_block.h b/src/includes/blocks/validate_block.h index e8cf89b..5e3cadc 100644 --- a/src/includes/blocks/validate_block.h +++ b/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); diff --git a/src/includes/globals/blockchain.h b/src/includes/globals/blockchain.h index e02c539..2c4c0f4 100644 --- a/src/includes/globals/blockchain.h +++ b/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(); /** diff --git a/src/includes/globals/constants.h b/src/includes/globals/constants.h index 85a8f90..a09bd37 100644 --- a/src/includes/globals/constants.h +++ b/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" diff --git a/src/includes/globals/double_spend_set.h b/src/includes/globals/double_spend_set.h index b4d14ce..fc09275 100644 --- a/src/includes/globals/double_spend_set.h +++ b/src/includes/globals/double_spend_set.h @@ -1,3 +1,14 @@ +/** + * @file double_spend_set.h + * @author nfaber@olin.edu and efisher@olin.edu + * @brief Double Spend implementation for in-memory checkin if there are + * duplicate UTXO inputs to a block or transaction + * @version 0.1 + * @date 2022-05-06 + * + * @copyright Copyright (c) 2022 + * + */ #include "utxo_pool.h" /** diff --git a/src/includes/globals/init_globals.h b/src/includes/globals/init_globals.h index b997c90..564737e 100644 --- a/src/includes/globals/init_globals.h +++ b/src/includes/globals/init_globals.h @@ -1,3 +1,13 @@ +/** + * @file init_globals.h + * @author nfaber@olin.edu and efisher@olin.edu + * @brief Initialize the global datastructures required for a node to run + * @version 0.1 + * @date 2022-05-06 + * + * @copyright Copyright (c) 2022 + * + */ #pragma once /** diff --git a/src/includes/globals/mempool.h b/src/includes/globals/mempool.h index 8fcdc25..4a32731 100644 --- a/src/includes/globals/mempool.h +++ b/src/includes/globals/mempool.h @@ -1,3 +1,13 @@ +/** + * @file mempool.h + * @author nfaber@olin.edu and efisher@olin.edu + * @brief Memory Pool to keep track of transactions that need validated + * @version 0.1 + * @date 2022-05-06 + * + * @copyright Copyright (c) 2022 + * + */ #pragma once #include @@ -5,60 +15,73 @@ #include "uthash.h" #include "base_tx.h" +/** + * @brief UTHASH Memory Pool hashmap + * + */ typedef struct MemPool { unsigned char id[TX_HASH_LEN]; Transaction *tx; UT_hash_handle hh; } MemPool; +/** + * @brief Global MemPool hashmap + * + */ MemPool *mempool; -/* Initializes the global mempool variable */ +/** + * @brief Initializes the global mempool variable + * + */ void mempool_init(); -/* Creates a new entry in the hashmap with the passed transaction - * - * Returns passed transaction pointer if entry created, NULL otherwise - * - * transaction: Transaction pointer that will be stored in entry +/** + * @brief Create a new entry in the hashmap with the passed transaction + * + * @param tx Transaction pointer that will be stored in mempool + * @return Transaction* passed transaction pointer if entry created, NULL otherwise */ Transaction *mempool_add(Transaction *tx); -/* Removes the entry corresponding to tx_hash - * - * Returns the transaction pointer stored in removed entry if succesfully +/** + * @brief Removes the entry corresponding to tx_hash + * + * @param tx_hash Buffer of length TX_HASH_LEN, hash of transaction + * @return Transaction* transaction pointer stored in removed entry if succesfully * removed, NULL otherwise - * - * tx_hash: Buffer of length TX_HASH_LEN, hash of transaction */ Transaction *mempool_remove(unsigned char *tx_hash); -/* Finds transaction corresponding to tx_hash - * - * Returns transaction pointer if found, NULL otherwise - * - * tx_hash: Buffer of length TX_HASH_LEN, hash of transaction + +/** + * @brief Finds transaction corresponding to tx_hash + * + * @param tx_hash Buffer of length TX_HASH_LEN, hash of transaction + * @return Transaction* transaction pointer if found, NULL otherwise */ Transaction *mempool_find(unsigned char *tx_hash); -/* Finds entry corresponding to tx_hash - * - * Returns entry if found, NULL otherwise - * - * tx_hash: Buffer of length TX_HASH_LEN, hash of transaction +/** + * @brief Find entry corresponding to tx_hash + * + * @param tx_hash Buffer of length TX_HASH_LEN, hash of transaction + * @return MemPool* entry if found, NULL otherwise */ MemPool *mempool_find_node(unsigned char *tx_hash); -/* -Prints a mempool item with the associated id/hash from the hasmap - -prefix: string to put in front of all print commands used for tabbing structure -*/ +/** + * @brief Prints a mempool item with the associated id/hash from the hasmap + * + * @param mempool mempool entry to print + * @param prefix tring to put in front of all print commands used for tabbing structure + */ void print_mempool(MemPool *mempool, char *prefix); -/* -Prints all transactions in mempool hashmap to stdout - -prefix: string to put in front of all print commands used for tabbing structure -*/ +/** + * @brief Prints all transactions in mempool hashmap to stdout + * + * @param prefix string to put in front of all print commands used for tabbing structure + */ void print_mempool_hashmap(char *prefix); diff --git a/src/includes/globals/utxo_pool.h b/src/includes/globals/utxo_pool.h index b747c6c..1eefa06 100644 --- a/src/includes/globals/utxo_pool.h +++ b/src/includes/globals/utxo_pool.h @@ -1,23 +1,56 @@ +/** + * @file utxo_pool.h + * @author nfaber@olin.edu and efisher@olin.edu + * @brief Unspent Transaction Pool Hashmap and associated functions, + * concept of currency in this blockchain + * @version 0.1 + * @date 2022-05-06 + * + * @copyright Copyright (c) 2022 + * + */ #pragma once #include "constants.h" #include "uthash.h" #include "base_tx.h" #include "leveldb/c.h" + +/** + * @brief Length of UTXO POOL KEY + * + */ #define UTXO_POOL_KEY_LEN TX_HASH_LEN+sizeof(((Transaction*)0)->inputs->prev_utxo_output) +/** + * @brief Key used in UTHASH UTXOPool hashmap + * + */ typedef struct UTXOPoolKey { unsigned char tx_hash[TX_HASH_LEN]; unsigned int vout; } UTXOPoolKey; +/** + * @brief UTHASH UTXO Pool hashmap + * + */ typedef struct UTXOPool { UTXOPoolKey id; UTXO *utxo; UT_hash_handle hh; } UTXOPool; +/** + * @brief Path to perisitent UTXO Pool + * + */ char *utxo_pool_path; + +/** + * @brief LevelDB UTXO Pool Database object + * + */ leveldb_t *utxo_pool_db; // Level DB Database /** diff --git a/src/includes/globals/utxo_to_tx.h b/src/includes/globals/utxo_to_tx.h index 81433b4..b911747 100644 --- a/src/includes/globals/utxo_to_tx.h +++ b/src/includes/globals/utxo_to_tx.h @@ -1,7 +1,23 @@ +/** + * @file utxo_to_tx.h + * @author nfaber@olin.edu and efisher@olin.edu + * @brief Mapping from UTXO to transactions in the mempool to check for + * conflicts in blocks and the Blockchain + * @version 0.1 + * @date 2022-05-06 + * + * @copyright Copyright (c) 2022 + * + */ + #pragma once #include "utxo_pool.h" +/** + * @brief UTHASH Hashmap of UTXO's to Transactions + * + */ typedef struct { UTXOPoolKey id; unsigned char tx_hash[TX_HASH_LEN];