Modules

all_imports.py

This file is a consolidation of the majority of imports needed by the project scripts

Note

Some scripts need to reimport files locally because of their ordering in this file

blockchain_funcs.py

This file contains functions and classes related to the blockchain and transactions This includes the general structure, consensus, validation, manipulation, data types, etc.

class blockchain_funcs.Block(index, timestamp, data, previous_hash)

This class defines the structure of a block

__init__(index, timestamp, data, previous_hash)

This function initializes a block

Parameters

  • index – index of this block

  • timestamp – timestamp of this block

  • data – data to be included in this block (transactions)

  • previous_hash – hash of previous block in the chain

__weakref__

list of weak references to the object (if defined)

hash_block()

This function returns the hash of this block, using the index, timestamp, data, and previous hash

to_dict()

This function returns a dict of this block’s fields

blockchain_funcs.add_trans_to_block()

This function will add a block’s transactions to their blockchain according to the BLOCK_SIZE

blockchain_funcs.add_transaction(timestamp, type, sender, recip, value, listOfTransactions=None, port=8100, my_chain=None)

This function will ‘insort’ a transaction into this nodes transaction list based on the confirmation timestamp

Parameters

  • timestamp – Timestamp of transaction confirmation

  • type – type of transaction being added

  • sender – sender of the transaction

  • recip – recipient of the transaction

  • value – value associated with the transaction

  • listOfTransactions – provided list of transactions to add this transaction to

  • port – port of the node adding the transaction for debugging

  • my_chain – blockchain of the node adding the transaction

Returns

updated list of transactions

blockchain_funcs.consensus(chainList=None, port=8100, cons_array=None, cindex=None, chain_dict=None, trans_dict=None, id_list=None, trans_vote_dict=None)

This function is responsible for enacting consensus on this node’s blockchain. Once all “votes” have been received or the time window has expired, the most popular “vote” is copied to our blockchain if it is agreed upon by >50% of the nodes

Parameters

  • chainList – current or specified blockchain

  • port – port of enacting node

  • cons_array – dictionary/ of votes for consensus

  • cindex – index of last agreed block

  • chain_dict – dictionary of blockchains being voted on

  • trans_dict – dictionary of transactions being voted on

  • id_list – list of nodes that voted

  • trans_vote_dict – dictionary of votes for the transactions

Returns

consensus-agreed chain

blockchain_funcs.consensus_and_reset(threadNum=None)

This function will call consensus and reset its variables

Parameters

threadNum – Thread number if activated via timeout

blockchain_funcs.consensus_reset_and_send(threadNum=None)

This function will call consensus, reset its variables, then send the result to the smart contract node

Parameters

threadNum – Thread number if activated via timeout

blockchain_funcs.create_genesis_block(prev=None)

This function creates the genesis block upon this node’s instantiation. This is only relevant if it is the first node in the system, as all other nodes will seek consensus and throw away their genesis block

Returns

returns the object of a genesis block

blockchain_funcs.get_block_objs(chainDict)

This function will do the opposite of blockchain_funcs.get_dict_list(), it will take a dictionary list and turn it into a list of blockchain_funcs.Block objects, used to copy chains from messages

Parameters

chainDict – the dict list to copy

Returns

list of block objects

blockchain_funcs.get_dict_list(chainList=None)

This function returns a dictionary list of a given list of objects (Blocks or Transactions)

Parameters

chainList – list to get objects from, default None results in global blockchain used

Returns

local blockchain in dictionary form

blockchain_funcs.get_hash(*s)

This function will return a SHA256 hash of the variables(s) provided

Parameters

s – arbitrary number of arguments to be combined into a string then converted to a hash

Returns

hash of arguments provided

blockchain_funcs.get_trans_objs(chainDict)

This function will take a dictionary list and turn it into a list of blockchain_funcs.Transaction objects

Parameters

chainDict – the dict list to convert to blocks

Returns

list of block objects

blockchain_funcs.get_transaction_list_hash(this_list=None)

This function will hash together the list of transactions

Parameters

this_list – can specify a different list to hash

Returns

the resulting hash

blockchain_funcs.in_transactions(t_hash, t_list=None)

This function will tell if a transaction has already been recorded

Parameters

  • t_hash – hash of transaction to search for

  • t_list – list of transactions

Returns

Boolean representing whether the transaction was found

blockchain_funcs.reset_consensus(newIndex)

This function resets global variables used for consensus

Parameters

newIndex – new index of consensus_index used to keep track of the last agreed block

blockchain_funcs.restore_chain(port=8100)

This function will restore a blockchain from local storage or generate a genesis block if there is no chain stored

Parameters

port – port of the node restoring its blockchain

Returns

the restored blockchain

blockchain_funcs.validate(chain, lasthash, index=None, fromport=None)

This function validates a chain against itself and its proposed hash

Returns

boolean value representing validity of the provided chain and hash

communication.py

This file contains classes and functions relative to sockets enabling communication between blockchain nodes Every node will have a server for receiving and reacting to messages, and a client for actively sending messages out

class communication.Receiver(my_host, my_port)

This class is responsible for receiving and reacting to messages from other nodes

__init__(my_host, my_port)

This function will initialize the receiver server variables

Parameters

  • my_host – host of this node

  • my_port – port of this node

listen()

This function is the listener for incoming messages

power_consensus(threadNum)

This function will perform the consensus to fabricate the LC-DMPC grid aggregator power reference (Pseudocode)

Parameters

threadNum – Thread number if activated via timeout

request_power(threadNum)

This function will request power for consensus in the event that it does not receive power from upstream (Pseudocode)

Parameters

threadNum – Thread number if activated via timeout

respond_addblock(msgJson, msgData)

This function will perform consensus on addblock messages received from other nodes then it will send the result to the smartcontract to finalize

Parameters

  • msgJson – Json structure of message

  • msgData – Json structure of message data

respond_confirm(msgJson, msgData)

This function will add the power/sensitivity transaction to the transaction list of this node

Parameters

  • msgJson – Json structure of message

  • msgData – Json structure of message data

respond_intro(msgJson, msgData)

This function is responsible for responding to the introduction message of a new node

Parameters

  • msgJson – Json structure of message

  • msgData – Json structure of message data

respond_pay(msgJson, msgData)

This method will automatically insort payment transactions from the smartcontract

Parameters

  • msgJson – Json structure of message

  • msgData – Json structure of message data

respond_powerDMPC(msgJson, msgData)

This function will respond to instructions from the LC-DMPC program to send power references

Parameters

  • msgJson – Json structure of message

  • msgData – Json structure of message data

respond_powerRequest(msgJson, msgData)

This function responds to a request for power reference (Pseudocode)

Parameters

  • msgJson – Json structure of message

  • msgData – Json structure of message data

respond_powerResponse(msgJson, msgData)

This function will do a form of consensus on the powers of other nodes (Pseudocode)

Parameters

  • msgJson – Json structure of message

  • msgData – Json structure of message data

respond_powerref(msgJson, msgData)

This function is responsible for responding to power reference messages

Parameters

  • msgJson – Json structure of message

  • msgData – Json structure of message data

respond_request(msgJson, msgData)

This function will respond to requests for the blockchain

Parameters

  • msgJson – Json structure of message

  • msgData – Json structure of message data

respond_response(msgJson, msgData)

This function is responsible for responding to introduction responses (performing consensus on all of the returned blockchains)

Parameters

  • msgJson – Json structure of message

  • msgData – Json structure of message data

respond_sensitivity(msgJson, msgData)

This function is responsible for responding to sensitivity messages

Parameters

  • msgJson – Json structure of message

  • msgData – Json structure of message data

respond_validators(msgJson, msgData)

This function is responsible for recording validators broadcasted from the smartcontract

Parameters

  • msgJson – Json structure of message

  • msgData – Json structure of message data

run()

This function is run at the start of the server thread

class communication.Sender(my_host, my_port)

This class is responsible for actively sending data including power references and introduction It is the client in the server-client P2P node structure

__init__(my_host, my_port)

This function will initialize the client

Parameters

  • my_host – host of the client

  • my_port – port of the client

run()

This function is the bulk of the thread and will be run as the thread is started

communication.propose_block(msgJson, msgData)

This function will propose a block update to all of the other blocks

Parameters

  • msgJson – Json structure of message

  • msgData – Json structure of message data

communication.reportNode(node)

This function will report a node to the smart contract for punishment

Parameters

node – hash of the node to report

communication.report_sensitivity(msgJson, threadNum)

This function will execute similarly to communication.respond_sensitivity() but is executed from timeout and thus will omit the missing sensitivity data and will report the node that should’ve sent it

Parameters

  • msgJson – original power message

  • threadNum – Thread number if activated via timeout

communication.sendMessage(message, destPort, pr_key=None, myport=8100)

This function sends a given message to a given port

Parameters

  • pr_key – private key (None defaults to global variable)

  • message – The string message to send

  • destPort – The port of the destination node

  • myport – this node’s port for debugging

communication.sendPowerref(message_power)

This function will send power reference data to any downstream nodes from this node

Parameters

message_power – power value to send (this is a parameter so that LC-DMPC can feed in its own data)

communication.sendToDMPC(message, myport=8100)

This function sends a given message to the lcdmpc program

Parameters

  • message – The string message to send

  • myport – this node’s port (for debugging)

communication.updateDMPCPower(fromport, power)

This function will tell the DMPC program to update the power reference input

communication.updateDMPCSense(fromport)

This function will tell the DMPC program to update the sensitivity input

consensus.py

This file will act as the centralization necessary to implement the Proof of Stake Algorithm It will perform the selection of validators and consensus of blocks

class SmartContracts.consensus.Server(my_host='localhost', my_port=8100)

This class is responsible for receiving and reacting to messages for the “smart contract” server

__init__(my_host='localhost', my_port=8100)

This function initializes the server and its variables :param my_host: host of the server (defaults to BASE) :param my_port: port of the server (defaults to BASE)

broadcast_validators()

This funciton will broadcast the current validators to the rest of the nodes online

check_validators()

This function will check if the validators need to be updated

consensus_response(msgJson, msgData)

This function reacts to consensus messages, collecting consensus results from the validators then performing its own consensus using those messages (Pseudocode)

Parameters

  • msgJson – Json structure of message

  • msgData – Json structure of message data

introduction_response(msgJson, msgData)

This function is responsible for responding to the introduction message of a new node

Parameters

  • msgJson – Json structure of message

  • msgData – Json structure of message data

is_validator(hash)

This function will return the index if the hash provided is in the validator list :param hash: the hash to check :return: index of hash in the validator list

listen()

This function is the listener for the server, it accepts connections and messages then reacts to them

pay(destHash, value)

This function will send an official message of UtilityToken transfer

Parameters

  • destHash – Destination port

  • value – UtilityToken Value (negative for penalty)

read_validators()

This function will read the validators stored in memory

report(msgJson, msgData)

This function will report a node for penalty :param msgJson: Json structure of message :param msgData: Json structure of message data

reset_consensus()

This function will clear consensus server variables

run()

Run the thread

update_wallets()

This function will scan the blockchain to assign current balances for the nodes (Pseudocode)

validator_consensus(threadNum=None)

This function will perform consensus among the assigned validators and issue payment/penalties (Pseudocode)

validator_select()

This function will select random nodes weighted by their UtilityToken Balance to be validator nodes

write_validators()

This function will write the validators to memory

SmartContracts.consensus.main()

This is the main file, it will run if this script is run individually

Data_Recorder.py

This file holds functions that will write data to storage for later analysis

Data_Recorder.clear_balances()

This function will clear the csv that balances are written to

Data_Recorder.clear_latencies()

This function will clear the latency log

Data_Recorder.record_filesize(index, transactions, blocksize)

This function will record the node file size

Parameters

  • index – current block index

  • transactions – current # of non-stored transactions

  • blocksize – set blocksize

Data_Recorder.write_balances(walletList, index)

This function will write the current balances to a csv file to be displayed as a graph

Parameters

  • walletList – list of wallet values for each node

  • index – block index to keep

Data_Recorder.write_msg_time(id, type, index, myport)

This function will write a log of a message’s send/receive time to calculate latency

Parameters

  • id – id of the sending message to be matched with its reception

  • type – type of message if there are different latency patterns

encryption.py

This file will contain functions for encrypting and decrypting messages

encryption.check_signature(signature, message, pub_port)

This function will check whether the signature of a message maches a given public key

Parameters

  • signature – provided signature

  • message – message claimed to be signed with signature

  • pub_key – public key of sender

Returns

boolean value representing validity

encryption.decrypt(package, port=8100, pr_key=None)

This function will decrypt the provided bytes into a usable form (Pseudocode)

Parameters

  • pr_key – private key to decrypt with

  • port – port for debugging

  • package – message bytes to decrypt

Returns

decrypted message string

encryption.encrypt(message, destPort, pr_key=None)

This function will encrypt a given string using hybrid encryption (Pseudocode)

Parameters

  • pr_key – private key of the node trying to encrypt

  • message – The string to encrypt

  • destPort – The port of the destination node

Returns

encoded Json of the encrypted message and key

encryption.gen_signature(message, pr_key)

This function will generate a signature for a given message

Parameters

  • message – message to be signed

  • pr_key – sending node’s private key

Returns

signature

global_vars.py

This file contains and initializes the global variables shared across files

key_editor.py

This file holds functions that manipulate keys used for encryption and digital signatures

key_editor.create_key(port)

This function will create a private and public key pair for a node if it does not already exist Then it will write the keys to a file The public_keys file represents a publicly accessible server/database of public keys, whereas the local_keys file represents local storage accessible only to each node

Parameters

port – port number associated with the node

Returns

private key (generated or read)

key_editor.get_pub_key(port)

This function will read the public key of a port

Parameters

port – The port of which to retrieve the public key

Returns

returns the public key object read from the json file

node_editor.py

This file contains functions that edit the local storage of the nodes

node_editor.get_transactions(port=8100)

This function will return the transactions stored locally

Parameters

port – port of this node

Returns

transaction list

node_editor.new_node(port)

This function will add a node to the local storage with a unique hash if it does not already exist

Parameters

port – port of the node to add

Returns

hash of the node added

node_editor.tryLoad(f, port)

This function will attempt to load a json file 5 times with a small delay to allow for a read-write collision to clear

Parameters

  • f – file to read

  • port – port of this node

Returns

(loaded json file, boolean of success)

node_editor.update_chain(port=8100, chainList=None)

This function will write a blockchain into local storage

Parameters

  • port – port of this node

  • chainList – blockchain to write

node_editor.update_transactions(port=8100, transactions=None)

This function will write the transactions into local storage

Parameters

  • port – port of this node

  • transactions – transactions to write

Timeouts.py

This file will contain functions for timing out any process

class Timeouts.Timeout(timer_type, functionCall, duration=3.0, port=8100, threadNum=None, arg=None)
This class will act as a general thread timer for any process

(Pseudocode)

__init__(timer_type, functionCall, duration=3.0, port=8100, threadNum=None, arg=None)

This function initializes the class object with the type, start time, and thread running condition

Parameters

  • timer_type – type of timer for debugging purposes

  • functionCall – callback function for after timeout expires

  • duration – duration of the timer

  • port – port of node calling this function for debugging

  • threadNum – thread number to pass along if this thread is part of a list of threads

  • arg – argument to pass into the callback function

run()

This is the bulk of the thread, it will repeatedly check if the time has exceeded the duration

stop()

This function will effectively stop the thread by setting the run condition to false